461 lines
13 KiB
Markdown
461 lines
13 KiB
Markdown
# 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](#ids-are-the-key)** — Every object traceable from spec to code to test
|
|
- **[Real Content](#why-content-isnt-lorem-ipsum)** — Actual copy with translations ready
|
|
- **[Functional Objects](#design-system-terminology)** — Reusable components identified and specified
|
|
- **[The Invisible Layer](#multiple-dimensions)** — SEO, accessibility, performance, analytics
|
|
- **[Strategic Context](#why-start-with-page-purpose)** — Every decision connected to user needs
|
|
- **[Complete Behavior](#why-elements-need-states)** — 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:**
|
|
|
|
1. **Traceability** — From spec → code → test
|
|
2. **Maintenance** — Find exactly what needs updating
|
|
3. **Translation** — Map content to language files
|
|
4. **Accessibility** — Reference specific elements for ARIA
|
|
5. **Analytics** — Track interactions precisely
|
|
6. **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](lesson-01-design-is-specification.md)
|
|
Start with the big picture, then work down
|
|
|
|
### [Lesson 2: Section & Widget Specifications](lesson-02-section-widget-specifications.md)
|
|
Deep dive on Layers 2 & 3 of the hierarchy
|
|
|
|
### [Lesson 3: Element & State Specifications](lesson-03-element-state-specifications.md)
|
|
Deep dive on Layers 4 & 5 — Complete implementation details
|
|
|
|
---
|
|
|
|
## Tutorial
|
|
|
|
### [Tutorial 11: Write Your Specifications](tutorial-11.md)
|
|
Hands-on guide to creating complete page specifications with Freya
|
|
|
|
---
|
|
|
|
## Next Module
|
|
|
|
**[Module 12: Functional Components →](../module-12-functional-components/module-12-functional-components-overview.md)**
|
|
|
|
Time to identify reusable patterns across your specifications.
|
|
|
|
---
|
|
|
|
*Part of the WDS Course: From Designer to Linchpin*
|