13 KiB

Raw Blame History

Module 11: Conceptual Specifications

Time: 60 min | Agent: Freya | Phase: Design | Focus: UX

Every Decision Documented

This is where design becomes specification.

This is the core of WDS.

Specifications are the new code.

In an AI-powered world, well-structured specifications get transformed into working software. The clearer and more complete your specifications, the better the code that gets generated from them.

WDS specifications provide what sketches and mockups cannot:

Unique IDs — Every object traceable from spec to code to test
Real Content — Actual copy with translations ready
Functional Objects — Reusable components identified and specified
The Invisible Layer — SEO, accessibility, performance, analytics
Strategic Context — Every decision connected to user needs
Complete Behavior — All states, all interactions, all edge cases

Sketches show what you see. Specifications define what gets built.

Why Specifications Matter

A sketch can be interpreted 10 different ways.

A specification has one meaning.

When you specify, you decide:

No ambiguity
No guessing
No "I thought you meant..."
No developer questions
No implementation drift

If they need to ask, your spec is incomplete.

The Hierarchy

Specifications work from big to small:

┌─────────────────────────────────────────────────┐
│ PAGE                                            │
│ Purpose, Layout, Accessibility                  │
│                                                 │
│  ┌───────────────────────────────────────────┐  │
│  │ SECTION                                   │  │
│  │ Purpose, Placement, Behavior              │  │
│  │                                           │  │
│  │  ┌─────────────────────────────────────┐  │  │
│  │  │ WIDGET                              │  │  │
│  │  │ Reusable component, States          │  │  │
│  │  │                                     │  │  │
│  │  │  ┌───────────────────────────────┐  │  │  │
│  │  │  │ CARD                          │  │  │  │
│  │  │  │ Content grouping              │  │  │  │
│  │  │  │                               │  │  │  │
│  │  │  │  ┌─────────┐  ┌─────────┐    │  │  │  │
│  │  │  │  │ BUTTON  │  │  FIELD  │    │  │  │  │
│  │  │  │  └─────────┘  └─────────┘    │  │  │  │
│  │  │  │  Individual elements          │  │  │  │
│  │  │  └───────────────────────────────┘  │  │  │
│  │  └─────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

You don't specify a button until you understand the page.

Design System Terminology

Specifications use consistent terminology:

Term	What It Means	Example
Page	Complete view in scenario	Signup page, Dashboard
Section	Major area of page	Header, Hero, Form area, Footer
Widget	Reusable component	Navigation bar, User menu, Search box
Card	Grouped content container	Profile card, Feature card, Stat card
Element	Individual UI piece	Button, Input field, Icon, Label

Use these terms consistently across all specifications.

IDs Are the Key

Every object gets a unique ID:

Page:       P01-signup-page
Section:    P01-S01-hero-section
Widget:     P01-S02-W01-signup-form
Card:       P01-S03-C01-feature-card
Element:    P01-S02-W01-E01-email-field

Why IDs matter:

Traceability — From spec → code → test
Maintenance — Find exactly what needs updating
Translation — Map content to language files
Accessibility — Reference specific elements for ARIA
Analytics — Track interactions precisely
Testing — Target elements for automation

Without IDs, specifications are just documentation. With IDs, they're implementation maps.

Multiple Dimensions

Every specification addresses:

1. Structure & Behavior

What appears, what happens, what changes

2. Content & Copy

Actual text, not placeholders, in all languages

3. Accessibility

Screen reader labels, keyboard navigation, focus management

4. Internationalization

Text expansion, RTL support, locale formats

5. Performance

Loading priorities, lazy loading, skeleton screens

A complete specification covers all dimensions.

Why Start with Page Purpose

Before you specify anything, answer:

What is this page trying to accomplish?

BAD:
"This is the signup page."

GOOD:
"This page lets Felix (persona) create an account with
minimal friction (driving force) by asking only for
essential information (email + password) so he can
start trying the product immediately."

Purpose connects specification to strategy.

Every element on the page must serve this purpose. If it doesn't, it shouldn't be there.

Why Section Structure Matters

Sections organize the page:

Signup Page Sections:
┌─────────────────────────────────────┐
│ S01: Header (Logo, Login link)     │
├─────────────────────────────────────┤
│ S02: Hero (Value prop)             │
├─────────────────────────────────────┤
│ S03: Form Area (Signup widget)     │
├─────────────────────────────────────┤
│ S04: Trust Signals (Testimonials)  │
├─────────────────────────────────────┤
│ S05: Footer (Legal links)          │
└─────────────────────────────────────┘

Each section has:

Purpose (why it exists)
Placement (where it appears)
Behavior (responsive, sticky, collapsible)
Priority (load order, importance)

Sections before widgets. Structure before details.

Why Widgets Are Reusable

A widget is a component that appears in multiple places:

signup-form widget:
- Used on: Signup page, Modal signup, Embedded signup
- Same behavior everywhere
- Same validation everywhere
- Specify once, use many times

Widgets enforce consistency.

Why Cards Group Content

Cards contain related information:

feature-card:
┌───────────────────┐
│ [Icon]            │
│ Feature Title     │
│ Description here  │
│ [Learn More →]    │
└───────────────────┘

Cards make content scannable and repeatable.

Why Elements Need States

An element isn't just one thing. It transforms:

Button States:
Default  → Hover → Active → Loading → Success → Error
                                    → Disabled

Each state needs:
- Visual appearance
- Behavior
- Accessibility label
- Content (if changes)

Incomplete state specifications = bugs.

Why Content Isn't Lorem Ipsum

Actual copy affects design:

BAD:
Button: "Lorem ipsum"

GOOD:
Button: "Create Free Account"
Translation (ES): "Crear Cuenta Gratuita"
Translation (DE): "Kostenloses Konto erstellen"

Real content reveals:

Length constraints
Wrapping issues
Translation expansion
Tone and voice

Write real copy in specifications.

Why Accessibility Isn't Optional

Every element needs:

email-field:
- Label: "Email" (visible)
- aria-label: "Email address for your account"
- aria-required: "true"
- aria-invalid: "false" (default) → "true" (on error)
- aria-describedby: "email-error" (when error shown)

Accessibility is part of the specification, not added later.

Why Translations Matter Early

Content expands in translation:

English:  "Sign up" (7 chars)
German:   "Registrieren" (13 chars)
Finnish:  "Rekisteröidy" (13 chars)

English:  "Delete account" (14 chars)
German:   "Konto löschen" (13 chars)
Russian:  "Удалить аккаунт" (15 chars)

Design for expansion. Specify content constraints.

The Specification Layers

Layer 1: PAGE LEVEL
- Purpose
- Personas served
- Trigger Map connections
- Layout approach (mobile-first, responsive)
- Accessibility requirements
- Performance priorities

Layer 2: SECTION LEVEL
- Purpose of each section
- Placement and hierarchy
- Responsive behavior
- Load priority

Layer 3: WIDGET LEVEL
- Reusable components
- States and interactions
- Validation rules
- Accessibility patterns

Layer 4: CARD LEVEL
- Content grouping
- Repeatable patterns
- Data structure

Layer 5: ELEMENT LEVEL
- Individual buttons, fields, icons
- States, content, behavior
- Specific ARIA attributes

Start at Layer 1. Work down to Layer 5.

The lessons teach HOW to specify each layer.

The Completeness Test

Your specification is complete when:

✅ A developer can build it without asking questions ✅ A translator can extract all content ✅ A tester can verify every state ✅ An accessibility auditor can validate ARIA ✅ A designer can maintain it 6 months later

If any role needs to guess, the spec is incomplete.

Common Mistakes

Mistake	Why It Fails	Fix
Starting with buttons	No context for decisions	Start with page purpose
Lorem ipsum content	Can't plan for translations	Write real copy
Missing states	Bugs in edge cases	Document all states
No IDs	Can't trace implementation	ID everything
Vague descriptions	Multiple interpretations	Be specific
Skipping accessibility	Fails audits	Specify ARIA from start

Output Structure

C-UX-Scenarios/
└── S01-User-Registration/
    ├── scenario-overview.md
    ├── pages/
    │   ├── P01-signup-page.md       ← Complete page spec
    │   └── P02-welcome-screen.md
    ├── widgets/
    │   ├── W01-signup-form.md       ← Reusable component
    │   └── W02-header-nav.md
    └── content/
        ├── copy-en.md               ← English content
        ├── copy-es.md               ← Spanish content
        └── copy-de.md               ← German content

Organized by hierarchy, not by feature.

What You'll Learn

Lesson 1: Hierarchical Specification Learn the 5-layer pattern (Page → Section → Widget → Card → Element) and how to work from large to small

Lesson 2: Section & Widget Specifications Deep dive on specifying sections (placement, responsive behavior) and widgets (reusability, states, validation)

Lesson 3: Element & State Specifications Complete element specifications with all states, exact content, ARIA attributes, edge cases, and translations

Tutorial: Specify Your Pages Hands-on practice with Freya creating complete specifications

The Freya Method

Freya ensures completeness:

"You specified the page purpose, but which persona is this for?" "This section appears on mobile — what's the responsive behavior?" "Your button has a default state but no disabled state. When is it disabled?" "This error message is in English. What about Spanish users?" "Where's the ID for this widget? How will developers reference it?"

She won't let you ship incomplete specs.

Lessons

Lesson 1: Page-Level Specifications

Start with the big picture, then work down

Deep dive on Layers 2 & 3 of the hierarchy

Lesson 3: Element & State Specifications

Deep dive on Layers 4 & 5 — Complete implementation details

Tutorial

Tutorial 11: Write Your Specifications

Hands-on guide to creating complete page specifications with Freya

Next Module

Module 12: Functional Components →

Time to identify reusable patterns across your specifications.

Part of the WDS Course: From Designer to Linchpin

13 KiB Raw Blame History