Coruse and Design System

WDS-V6-CONVERSION-ROADMAP.md

@@ -3,8 +3,8 @@
 **Document Purpose:** Complete record of all decisions, context, and progress for converting Whiteport Design Studio to BMad Method v6 format. This document allows continuation of work if the conversation is lost.
 
 **Created:** December 2, 2025  
-**Last Updated:** December 5, 2025  
+**Last Updated:** December 9, 2025  
-**Status:** In Progress - Workflows Phase (Phase 4 Complete + Dog Week Pattern)
+**Status:** In Progress - Course Development Phase (Getting Started Complete)
 
 ---
 
@@ -543,7 +543,7 @@ Includes:
 | 12b | Phase 2 Workflow | `workflows/2-trigger-mapping/` | ✅ COMPLETE |
 | 12c | Phase 3 Workflow | `workflows/3-prd-platform/` | ✅ COMPLETE |
 | 12d | **Phase 4 Workflow** | `workflows/4-ux-design/` | ✅ **COMPLETE (Dec 4)** |
-| 12e | Phase 5 Workflow | `workflows/5-design-system/` | TO CREATE |
+| 12e | **Phase 5 Workflow** | `workflows/5-design-system/` | ✅ **COMPLETE (Dec 9)** |
 | 12f | Phase 6 Workflow | `workflows/6-integration/` | TO CREATE |
 
 #### Phase 4: Create Agents (The Norse Pantheon)
@@ -590,13 +590,16 @@ Includes:
 | `src/modules/wds/README.md` | Module entry point | ✅ CREATED |
 | `src/modules/wds/_module-installer/` | Install config folder | EMPTY |
 | `src/modules/wds/agents/` | Agents folder | PARTIAL (saga skeleton) |
-| `src/modules/wds/workflows/` | Workflows folder | ✅ **PHASE 4 COMPLETE** |
+| `src/modules/wds/workflows/` | Workflows folder | ✅ **PHASE 5 COMPLETE** |
 | `src/modules/wds/workflows/workflow-init/` | Workflow initialization | ✅ COMPLETE |
 | `src/modules/wds/workflows/1-project-brief/` | Phase 1 workflow | ✅ COMPLETE |
 | `src/modules/wds/workflows/2-trigger-mapping/` | Phase 2 workflow | ✅ COMPLETE |
 | `src/modules/wds/workflows/3-prd-platform/` | Phase 3 workflow | ✅ COMPLETE |
 | `src/modules/wds/workflows/4-ux-design/` | **Phase 4 workflow** | ✅ **COMPLETE (Dec 4)** |
 | `src/modules/wds/workflows/4-ux-design/substeps/` | **Phase 4 substeps (4A-4E)** | ✅ **COMPLETE (Dec 4)** |
+| `src/modules/wds/workflows/5-design-system/` | **Phase 5 workflow** | ✅ **COMPLETE (Dec 9)** |
+| `src/modules/wds/workflows/5-design-system/assessment/` | **Opportunity/Risk micro-instructions** | ✅ **COMPLETE (Dec 9)** |
+| `src/modules/wds/workflows/5-design-system/operations/` | **Design system operations** | ✅ **COMPLETE (Dec 9)** |
 | `src/modules/wds/workflows/4-ux-design/templates/` | **Phase 4 templates** | ✅ **COMPLETE (Dec 4)** |
 | `src/modules/wds/workflows/5-design-system/` | Phase 5 workflow | TO CREATE |
 | `src/modules/wds/workflows/6-integration/` | Phase 6 workflow | TO CREATE |
@@ -1125,9 +1128,754 @@ Do these work? [1] Use [2] Adjust [3] Manual
 
 ---
 
+## 13. WDS Course Development (December 9, 2025)
+
+### 13.1 Course Structure Overview
+
+**Purpose:** Educational course teaching WDS methodology to designers
+
+**Location:** `src/modules/wds/course/`
+
+**Format:**
+- Read as documentation
+- Generate videos/podcasts with NotebookLM
+- Use in workshops and team training
+- Apply to real projects as you learn
+
+**Module Structure:**
+Each module contains:
+- **Inspiration** - Why this matters and what you'll gain
+- **Teaching** - How to do it with confidence and AI support
+- **Practice** - Apply it to your own project
+- **Tutorial** - Quick step-by-step guide (for practical modules)
+
+### 13.2 Course Modules Planned
+
+**16 Total Modules:**
+
+#### Foundation
+- Module 01: Why WDS Matters ✅ COMPLETE
+
+#### Phase 1: Project Brief
+- Module 02: Create Project Brief ⏳ TO CREATE
+
+#### Phase 2: Trigger Mapping
+- Module 03: Identify Target Groups ⏳ TO CREATE
+- Module 04: Map Triggers & Outcomes ⏳ TO CREATE
+- Module 05: Prioritize Features ⏳ TO CREATE
+
+#### Phase 3: Platform Requirements
+- Module 06: Platform Requirements ⏳ TO CREATE
+- Module 07: Functional Requirements ⏳ TO CREATE
+
+#### Phase 4: Conceptual Design (UX Design)
+- Module 08: Initialize Scenario ⏳ TO CREATE
+- Module 09: Sketch Interfaces ⏳ TO CREATE
+- Module 10: Analyze with AI ⏳ TO CREATE
+- Module 11: Decompose Components ⏳ TO CREATE
+- Module 12: Why-Based Specifications ⏳ TO CREATE
+- Module 13: Validate Specifications ⏳ TO CREATE
+
+#### Phase 5: Design System
+- Module 14: Extract Design Tokens ⏳ TO CREATE
+- Module 15: Component Library ⏳ TO CREATE
+
+#### Phase 6: Development Integration
+- Module 16: UI Roadmap ⏳ TO CREATE
+
+### 13.3 Getting Started Section - COMPLETE ✅
+
+**Location:** `src/modules/wds/course/00-getting-started/`
+
+**Files Created:**
+
+| File | Purpose | Status |
+|------|---------|--------|
+| `00-getting-started-overview.md` | Navigation hub for getting started | ✅ COMPLETE |
+| `01-prerequisites.md` | Skills, tools, requirements | ✅ COMPLETE |
+| `02-learning-paths.md` | Full Immersion, Quick Start, Self-Paced | ✅ COMPLETE |
+| `03-support.md` | Testimonials, FAQ, community | ✅ COMPLETE |
+| `00-getting-started-NOTEBOOKLM-PROMPT.md` | Podcast/video generation prompt | ✅ COMPLETE |
+
+**Key Decisions:**
+- Removed redundant "About the Course" file (merged into course overview)
+- Removed "About WDS" from getting started (belongs in main docs)
+- Focused on practical preparation only
+
+### 13.4 Course Overview - COMPLETE ✅
+
+**Location:** `src/modules/wds/course/00-course-overview.md`
+
+**Content:**
+- Welcome and paradigm shift
+- Who created WDS (Mårten Angner background)
+- Complete module table of contents (all 16 modules)
+- Learning paths (Complete, Quick Start, Phase-Specific)
+- Prerequisites summary
+- Module structure pattern
+- Clear call to action
+
+**Key Changes:**
+- Simplified module list to clean table of contents
+- Added "Who Created WDS?" section
+- Merged redundant content from getting started
+- Removed verbose descriptions
+
+### 13.5 Module 01: Why WDS Matters - COMPLETE ✅
+
+**Location:** `src/modules/wds/course/module-01-why-wds-matters/`
+
+**Files:**
+
+| File | Purpose | Status |
+|------|---------|--------|
+| `module-01-overview.md` | Module navigation and overview | ✅ COMPLETE |
+| `lesson-01-the-problem.md` | The Problem We're Solving | ✅ COMPLETE |
+| `lesson-02-the-solution.md` | Becoming a Linchpin Designer | ✅ COMPLETE |
+| `lesson-03-the-path-forward.md` | Your Transformation | ✅ COMPLETE |
+
+**Content Based On:**
+- Seth Godin's "Linchpin: Are You Indispensable?"
+- Factory mindset vs Linchpin mindset
+- 5 dimensions of design thinking
+- AI as amplifier, not replacement
+- Emotional labor concept adapted to design
+
+### 13.6 NotebookLM Prompt Refinements
+
+**Key Messaging Changes:**
+
+**Removed:**
+- ❌ Speed claims ("5x faster", "3-5x productivity")
+- ❌ Fake testimonials (Sarah K., Marcus L., Priya S.)
+- ❌ Unrealistic promises
+
+**Added:**
+- ✅ IDE learning curve (5-10 hours)
+- ✅ GitHub workflow requirement
+- ✅ Financial cost transparency ($15-80/month for Cursor)
+- ✅ Frontend prototyping capability
+- ✅ Usability testing without dev team
+- ✅ Strategic thinker value proposition
+
+**New Value Proposition:**
+- Not about speed - about depth and completeness
+- Become the strategic thinker your team needs
+- Create specifications developers actually need
+- Generate content that perfectly lifts your designs
+- Work is deeper, more complete, more fulfilling
+- Eventually deliver parts of frontend work
+
+**Honest About Costs:**
+- Learning curve: IDE and GitHub workflow
+- Time: 10 hours course + 5-10 hours tools
+- Money: $15-20/month (small projects) to $80/month (enterprise)
+- Stepping into developer territory (uncomfortable at first)
+
+**Benefits Emphasized:**
+- Remove biggest barrier between designers and developers
+- Designs live in same place as code
+- No more handoff nightmares
+- Create standalone frontend prototypes
+- Conduct usability testing independently
+- No longer blocked by development schedules
+
+### 13.7 Next Steps for Course Development
+
+**Immediate Priority:**
+Create Module 02: Project Brief as template for remaining modules
+
+**Recommended Approach:**
+1. **Option 1: Prioritize Core Modules** (Quick Start path)
+   - Module 02: Project Brief
+   - Module 04: Map Triggers & Outcomes
+   - Module 08: Initialize Scenario
+   - Module 12: Why-Based Specifications
+
+2. **Option 2: Create Module Templates**
+   - Template structure for each module type
+   - Fill in with specific content later
+   - Faster to generate full course
+
+3. **Option 3: One Phase at a Time**
+   - Complete Phase 1 (Module 02) fully
+   - Then Phase 2 (Modules 03-05)
+   - Then Phase 3, 4, 5, 6
+
+**Content Sources:**
+- Tutorial content from `src/modules/wds/tutorial/`
+- Methodology guides from `src/modules/wds/docs/method/`
+- Workflow documentation from `src/modules/wds/workflows/`
+- Dog Week examples (when ready)
+
+**Module Template Structure:**
+```
+module-XX-name/
+├── module-XX-overview.md          # Navigation and module intro
+├── lesson-01-inspiration.md       # Why this matters
+├── lesson-02-teaching.md          # How to do it
+├── lesson-03-practice.md          # Apply it
+└── tutorial.md                    # Quick step-by-step (optional)
+```
+
+**Estimated Scope:**
+- 15 modules remaining (Module 02-16)
+- Each module: 4 files minimum
+- Total: ~60 files to create
+- Content: Tens of thousands of lines
+
+**Recommendation:**
+Wait until conversion is complete, then tackle course development systematically using the proven Module 01 structure as template.
+
+---
+
+## 14. Latest Updates Summary
+
+### December 9, 2025 - Course Development Session
+
+**Completed:**
+- ✅ Getting Started section (5 files)
+- ✅ Course Overview refinement
+- ✅ Module 01: Why WDS Matters (4 files)
+- ✅ NotebookLM prompt with accurate messaging
+- ✅ Removed redundant files
+- ✅ Merged overlapping content
+
+**Key Refinements:**
+- Honest about IDE/GitHub learning curve
+- Transparent about costs ($15-80/month)
+- Focus on strategic value, not speed
+- Frontend prototyping as major benefit
+- Removed fake testimonials
+- Removed speed claims
+
+**Files Structure:**
+```
+course/
+├── 00-course-overview.md                    ✅ COMPLETE
+├── 00-getting-started/                      ✅ COMPLETE
+│   ├── 00-getting-started-overview.md
+│   ├── 01-prerequisites.md
+│   ├── 02-learning-paths.md
+│   ├── 03-support.md
+│   └── 00-getting-started-NOTEBOOKLM-PROMPT.md
+└── module-01-why-wds-matters/               ✅ COMPLETE
+    ├── module-01-overview.md
+    ├── lesson-01-the-problem.md
+    ├── lesson-02-the-solution.md
+    └── lesson-03-the-path-forward.md
+```
+
+**Next Session:**
+- Continue with Module 02-16 creation
+- Use Module 01 as template
+- Consider prioritizing Quick Start modules first
+- Reference tutorial and workflow content
+
+---
+
+---
+
+## 15. Design System Architecture (December 9, 2025)
+
+### 15.1 Core Principles
+
+**Three-Way Split Architecture:**
+
+```
+1. Page Specification (Logical View)
+   ├── Component references
+   ├── Page-specific content (labels, error texts)
+   ├── Layout/structure
+   └── WHY this page exists
+
+2. Design System (Visual/Component Library)
+   ├── Component definitions
+   ├── States & variants
+   ├── Styling/tokens
+   └── Reusable patterns
+
+3. Functionality/Storyboards (Behavior)
+   ├── Interactions
+   ├── State transitions
+   ├── User flows
+   └── Component behaviors
+```
+
+**Key Separation:**
+- **Specification = Content** (what the component is)
+- **Organization = Structure** (where it lives)
+- **Design System = Optional** (chosen in Phase 1)
+
+### 15.2 Design System Options
+
+**Three Modes (Chosen in Project Exploration):**
+
+**Option A: No Design System**
+- Components stay page-specific
+- AI/dev team handles consistency
+- Faster for simple projects
+
+**Option B: Custom Design System**
+- Designer defines in Figma
+- Components extracted as discovered
+- Figma MCP endpoints for integration
+
+**Option C: Component Library Design System**
+- Uses shadcn/Radix/etc.
+- Library chosen during setup
+- Components mapped to library defaults
+
+### 15.3 Component Flow with Design System
+
+**Complete Specification → Extract → Reference:**
+
+```
+1. Specification Component (Pure)
+   └── Captures EVERYTHING about object (mixed content)
+
+2. Orchestration Layer
+   ├── Receives complete specification
+   ├── Design system enabled?
+   │
+   └── YES → Design System Router
+       ├── A. Extract component-level info
+       ├── B. Add/update design system entry
+       ├── C. Create reference ID
+       ├── D. Return to page spec
+       ├── E. Replace component info with reference
+       └── F. Keep only page-specific info
+
+3. Result: Clean separation
+   ├── Page spec: References + page-specific content
+   └── Design system: Component definitions
+```
+
+**Example:**
+
+**Complete Specification:**
+```yaml
+Login Button:
+  why: Submit login credentials
+  label: "Log in"                    # Page-specific
+  error_text: "Invalid credentials"  # Page-specific
+  states: [default, hover, disabled] # Component-level
+  variants: [primary, secondary]     # Component-level
+  styling: {...}                     # Component-level
+```
+
+**After Split:**
+
+**Design System:**
+```yaml
+# D-Design-System/components/button.md
+Button Component [btn-001]:
+  states: [default, hover, disabled]
+  variants: [primary, secondary]
+  styling: {...}
+```
+
+**Page Spec:**
+```yaml
+# C-Scenarios/login-page.md
+Login Button:
+  component: Button.primary [btn-001]  # Reference
+  why: Submit login credentials
+  label: "Log in"
+  error_text: "Invalid credentials"
+```
+
+### 15.4 Design System Router
+
+**Parallel to Sketch Router:**
+
+```
+Design System Router
+├── Check: Does similar component exist?
+│
+├── NO → Route to: Create New Component
+│   └── Add to design system, create reference
+│
+└── YES → Route to: Opportunity/Risk Assessment
+    ├── Scan existing components
+    ├── Compare attributes
+    ├── Calculate similarity
+    ├── Identify opportunities
+    ├── Identify risks
+    ├── Present decision to designer
+    └── Execute decision:
+        ├── Same → Reuse reference
+        ├── Variant → Add variant to existing
+        └── New → Create new component
+```
+
+**Router Characteristics:**
+- Dumb and simple (just identify and route)
+- Doesn't contain business logic
+- Keeps orchestration clean
+- Parallel pattern to sketch router
+
+### 15.5 Opportunity/Risk Assessment
+
+**Micro-Instruction Breakdown:**
+
+```
+workflows/5-design-system/assessment/
+├── 01-scan-existing.md           # Find similar components
+├── 02-compare-attributes.md      # Compare systematically
+├── 03-calculate-similarity.md    # Score the match
+├── 04-identify-opportunities.md  # What could we gain?
+├── 05-identify-risks.md          # What could go wrong?
+├── 06-present-decision.md        # Show designer options
+└── 07-execute-decision.md        # Implement choice
+```
+
+**Example Conversation:**
+```
+Agent: "I found a button similar to btn-001 (Primary Button).
+
+Similarities:
+- Same size and shape
+- Same color scheme
+- Same hover behavior
+
+Differences:
+- Different label ('Continue' vs 'Submit')
+- Different icon (arrow vs checkmark)
+
+Options:
+[1] Same component (just change label/icon)
+[2] New variant of btn-001 (add 'continue' variant)
+[3] New component btn-002 (different purpose)
+
+If variant:
+✅ Pros: Consistency, easier maintenance
+❌ Cons: More complex component
+
+If separate:
+✅ Pros: Independence, flexibility
+❌ Cons: Potential inconsistency
+
+What's your call?"
+```
+
+**Key Insight:** Design systems are inherently challenging. WDS acknowledges risks and creates conversation points for designer judgment.
+
+### 15.6 Layered Knowledge Architecture
+
+**Centralized Concepts + Component-Specific Instructions:**
+
+```
+Core Principles (Shared)
+├── data/design-system/
+│   ├── token-architecture.md      # Structure vs style separation
+│   ├── naming-conventions.md      # Token naming rules
+│   ├── state-management.md        # Component states
+│   └── validation-patterns.md     # Form validation
+│
+└── Referenced by component types
+
+↓
+
+Component-Type Instructions (Specific)
+├── object-types/text-heading.md
+│   ├── References: token-architecture.md
+│   ├── References: naming-conventions.md
+│   └── Heading-specific rules
+│
+├── object-types/button.md
+│   ├── References: token-architecture.md
+│   ├── References: state-management.md
+│   └── Button-specific rules
+│
+└── object-types/input-field.md
+    ├── References: token-architecture.md
+    ├── References: validation-patterns.md
+    └── Input-specific rules
+```
+
+**Benefits:**
+- Small, digestible instruction files
+- Shared knowledge in one place
+- Selective loading (only what's needed)
+- Composable knowledge
+- Easy to maintain and update
+
+**Example: Structure vs Style Separation**
+
+**Shared Principle (`data/design-system/token-architecture.md`):**
+```markdown
+# Design Token Architecture
+
+## Core Principle
+Separate semantic structure from visual style.
+
+HTML defines meaning, tokens define appearance.
+
+<h2> = Semantic (second-level heading)
+"Display Large" = Visual (48px, bold, tight spacing)
+
+They should be independent!
+```
+
+**Component Application (`object-types/text-heading.md`):**
+```markdown
+# Text Heading Specification
+
+**References:** data/design-system/token-architecture.md
+
+## Heading-Specific Rules
+1. Identify semantic level (h1-h6)
+2. Map to design token (display-large, heading-1, etc.)
+3. Never mix structure with style
+4. Store structure in page spec
+5. Store style in design system tokens
+```
+
+### 15.7 Company Customization Model
+
+**Key Feature: Companies Can Fork WDS**
+
+```
+Company forks WDS
+├── Keeps: Core workflow architecture
+├── Keeps: Router logic
+├── Keeps: Orchestration patterns
+│
+└── Customizes:
+    ├── data/design-system/
+    │   ├── token-architecture.md    # Company standards
+    │   ├── naming-conventions.md    # Company naming
+    │   └── brand-guidelines.md      # Company brand
+    │
+    └── object-types/
+        ├── button.md                # Company button patterns
+        ├── input-field.md           # Company form standards
+        └── card.md                  # Company card patterns
+```
+
+**Use Cases:**
+
+**1. Enterprise with Design System**
+```
+Acme Corp forks WDS:
+├── Adds: data/design-system/acme-tokens.md
+├── Adds: data/design-system/acme-components.md
+└── Customizes: object-types/ to match Acme patterns
+
+Result: Every project uses Acme standards automatically
+```
+
+**2. Agency with Multiple Clients**
+```
+Agency forks WDS:
+├── Branch: client-a (Client A standards)
+├── Branch: client-b (Client B standards)
+└── Branch: main (Agency defaults)
+
+Result: Switch branch = switch standards
+```
+
+**3. Design System Team**
+```
+Design System Team forks WDS:
+├── Adds: Their component library specs
+├── Adds: Their token architecture
+└── Adds: Their validation rules
+
+Result: All designers use same system
+```
+
+**Benefits:**
+- ✅ Company-specific standards
+- ✅ Version controlled
+- ✅ Shareable across teams
+- ✅ Evolvable over time
+- ✅ Consistent across projects
+- ✅ Open-source dream: Customize without breaking core
+
+### 15.8 Design System Workflow Structure
+
+**Planned Structure:**
+
+```
+workflows/5-design-system/
+├── workflow.yaml                      # Main workflow entry
+├── design-system-router.md            # Router logic
+│
+├── assessment/                        # Opportunity/Risk micro-instructions
+│   ├── 01-scan-existing.md
+│   ├── 02-compare-attributes.md
+│   ├── 03-calculate-similarity.md
+│   ├── 04-identify-opportunities.md
+│   ├── 05-identify-risks.md
+│   ├── 06-present-decision.md
+│   └── 07-execute-decision.md
+│
+├── operations/                        # Design system operations
+│   ├── create-new-component.md
+│   ├── add-variant.md
+│   ├── update-component.md
+│   └── initialize-design-system.md
+│
+└── templates/                         # Output templates
+    ├── component.template.md
+    ├── design-tokens.template.md
+    └── component-library-config.template.md
+```
+
+**Integration Points:**
+- Called from Phase 4 orchestration (4c-03-components-objects.md)
+- Triggered after component specification
+- Only active if design system enabled in project
+- First component triggers initialization
+
+### 15.9 Key Risks Identified
+
+**1. Component Matching**
+- How to recognize "same" vs "similar" vs "different"
+- Solution: Similarity scoring + designer judgment
+
+**2. Circular References**
+- Page → Component → Functionality → Component
+- Solution: Clear hierarchy (Page → Component → Functionality)
+
+**3. Sync Problems**
+- Component evolves, references may break
+- Solution: Reference IDs + update notifications
+
+**4. Component Boundaries**
+- Icon in button? Nested components?
+- Solution: Designer conversation + guidelines
+
+**5. First Component**
+- When to initialize design system?
+- Solution: Auto-initialize on first component if enabled
+
+**6. Storyboard Granularity**
+- Component behavior vs page flow
+- Solution: Clear separation guidelines
+
+**Mitigation Strategy:**
+- AI identifies risks
+- Designer makes judgment calls
+- AI executes decisions
+- Transparent process with pros/cons
+
+### 15.10 Implementation Complete (December 9, 2025)
+
+**✅ Phase 5 Design System Workflow Complete!**
+
+**Files Created:**
+
+**Workflow Structure:**
+- `workflows/5-design-system/workflow.yaml`
+- `workflows/5-design-system/README.md`
+- `workflows/5-design-system/design-system-router.md`
+
+**Assessment Micro-Instructions (7 files):**
+- `assessment/01-scan-existing.md`
+- `assessment/02-compare-attributes.md`
+- `assessment/03-calculate-similarity.md`
+- `assessment/04-identify-opportunities.md`
+- `assessment/05-identify-risks.md`
+- `assessment/06-present-decision.md`
+- `assessment/07-execute-decision.md`
+
+**Component Operations (4 files):**
+- `operations/initialize-design-system.md`
+- `operations/create-new-component.md`
+- `operations/add-variant.md`
+- `operations/update-component.md`
+
+**Shared Knowledge Documents (4 files):**
+- `data/design-system/token-architecture.md`
+- `data/design-system/naming-conventions.md`
+- `data/design-system/component-boundaries.md`
+- `data/design-system/state-management.md`
+- `data/design-system/validation-patterns.md`
+
+**Templates (3 files):**
+- `templates/component.template.md`
+- `templates/design-tokens.template.md`
+- `templates/component-library-config.template.md`
+
+**Integration:**
+- Updated `workflows/4-ux-design/substeps/4c-03-components-objects.md` to call design system router
+
+**Total Files Created:** 27 files (22 core + 3 Figma + 2 catalog)
+
+**Key Features Implemented:**
+- ✅ Three design system modes (None/Custom/Library)
+- ✅ On-demand component extraction
+- ✅ Similarity detection and assessment
+- ✅ Opportunity/risk analysis with designer decision
+- ✅ Component operations (create/variant/update)
+- ✅ Layered knowledge architecture
+- ✅ Company customization support
+- ✅ Integration with Phase 4 workflow
+- ✅ **Figma integration (Mode B) - COMPLETE (Dec 9)**
+- ✅ **Interactive HTML catalog - COMPLETE (Dec 9)**
+
+**Figma Integration Files (Dec 9):**
+- `data/design-system/figma-component-structure.md` - Component organization in Figma
+- `figma-integration/figma-designer-guide.md` - Step-by-step designer instructions
+- `figma-integration/figma-mcp-integration.md` - Technical MCP integration guide
+
+**Interactive Catalog Files (Dec 9):**
+- `templates/catalog.template.html` - Interactive HTML catalog template
+- `operations/generate-catalog.md` - Catalog generation workflow
+
+**Catalog Features:**
+- Fixed sidebar navigation
+- Live component previews with all variants/states
+- Interactive state toggles
+- Design token swatches
+- Code examples
+- Changelog tracking
+- Figma links (Mode B)
+- **Automatically regenerated** after every component change
+- **Version controlled** with git
+
+**Next Steps:**
+1. Create Phase 6 workflow (Integration/PRD Finalization)
+2. Test Phase 5 workflow with real project
+3. Refine assessment criteria based on usage
+4. Add more shared knowledge documents as patterns emerge
+5. Test Figma MCP integration with real components
+6. Test catalog generation with real components
+
+---
+
+## 16. Future: Dogweek Design System Refactoring (Backlog)
+
+**Purpose:** Use Dogweek as live case study to validate WDS Phase 5
+
+**Identified Issues in Dogweek:**
+1. **Button Proliferation:** 8 separate button files (should be 1 component with variants)
+2. **Structure/Style Confusion:** H1 component hardcoded to visual style (breaks semantic HTML)
+3. **No Token Architecture:** Hardcoded values instead of design tokens
+4. **No Component IDs:** File-based organization, no usage tracking
+5. **No Similarity Detection:** Manual component management
+
+**Proposed Refactoring:**
+- Consolidate 8 button files → 1 Button component [btn-001] with variants
+- Separate semantic HTML (h1-h6) from visual tokens (heading-hero, heading-page)
+- Implement design token system (colors, typography, spacing)
+- Add component IDs and usage tracking
+- Create component references in page specs
+
+**Benefits:**
+- ✅ Validates WDS Phase 5 on production system
+- ✅ Improves Dogweek maintainability
+- ✅ Creates migration guide for other projects
+- ✅ Generates real-world examples for WDS course
+
+**Status:** Backlog (after Phase 6 complete)
+
 ---
 
 **End of Roadmap Document**
 
-*To continue: Open this document, review "Next Steps" section for current priorities*
+*To continue: Phase 6 (Integration) is the final workflow to create*
 

src/modules/wds/00-getting-started/00-about-wds.md

@@ -0,0 +1,80 @@
+# About WDS
+
+**What is Whiteport Design Studio?**
+
+---
+
+## Overview
+
+**Whiteport Design Studio (WDS)** is a design methodology that makes designers indispensable in the AI era.
+
+**The paradigm shift:**
+- The design becomes the specification
+- The specification becomes the product
+- The code is just the printout
+
+---
+
+## Who Created It?
+
+**Mårten Angner** - UX designer and founder of Whiteport, a design and development agency in Sweden.
+
+After years of working with AI tools, Mårten observed that traditional design handoffs were breaking down. Designers would create mockups, hand them off to developers, and watch their intent get lost in translation.
+
+WDS solves this by preserving design thinking through AI-ready specifications.
+
+---
+
+## Why It Exists
+
+**The problem:** AI can generate code perfectly, but only if you can clearly define what you want. Unclear specifications lead to AI hallucinations and failed projects.
+
+**The solution:** WDS teaches designers to create why-based specifications that capture intent, not just appearance.
+
+**The result:** Designers become 5x more productive while maintaining creative control.
+
+---
+
+## How It Works
+
+WDS provides:
+- A systematic workflow from product brief to AI-ready specifications
+- Why-based specifications (WHAT + WHY + WHAT NOT TO DO)
+- AI agents specifically tailored for design work
+- Integration with BMad Method for seamless design-to-development handoff
+
+---
+
+## Free and Open-Source
+
+WDS is completely free and open-source:
+- No cost barriers or subscriptions
+- AI agents included
+- Community-driven development
+- Plugin module for BMad Method
+
+**Mission:** Give designers everywhere the tools to thrive in the AI era.
+
+---
+
+## Real-World Proof
+
+**Dog Week project:**
+- Traditional approach: 26 weeks, mediocre result
+- WDS approach: 5 weeks, exceptional result
+- **5x speed increase with better quality**
+
+---
+
+## Learn More
+
+**[Continue to About the Course →](00-about-the-course.md)**
+
+Or return to the overview:
+
+**[← Back to Getting Started Overview](00-getting-started-overview.md)**
+
+---
+
+**Created by Mårten Angner and the Whiteport team**
+**Free and open-source for designers everywhere**

src/modules/wds/00-getting-started/where-to-go-next.md

@@ -0,0 +1,108 @@
+# Where to Go Next
+
+**You've installed WDS and completed the quick start. Now what?**
+
+---
+
+## Choose Your Path
+
+### 🎓 Learn the Concepts (Recommended First)
+
+**[Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)**
+
+Deep dive into:
+- Why designers are irreplaceable in the AI era
+- What WDS is and how it works
+- The BMad Method philosophy
+- Why-based specifications
+- Complete walkthroughs
+
+**Best for:** Understanding the "why" behind WDS
+
+**Time:** 1-2 hours (video series)
+
+---
+
+### 🚀 Start Your Project
+
+**[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)**
+
+Step-by-step workflows for:
+- Phase 1: Trigger Mapping
+- Phase 2: Information Architecture
+- Phase 3: Interaction Design
+- Phase 4: UX SpecificationsPleas
+
+**Best for:** Hands-on learning with a real project
+
+**Time:** Ongoing (project-based)
+
+---
+
+### 📚 Reference Documentation
+
+**[Modular Architecture](../workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md)**
+
+Technical details on:
+- Three-tier file structure
+- Content placement rules
+- Component decomposition
+- Storyboard integration
+
+**Best for:** Looking up specific techniques
+
+**Time:** As needed (reference)
+
+---
+
+## Recommended Learning Path
+
+```
+1. Quick Start (5 min) ✅ You are here
+   ↓
+2. Tutorial (1-2 hours)
+   Watch videos, understand concepts
+   ↓
+3. Your First Project (ongoing)
+   Apply WDS to a real project
+   ↓
+4. Reference Docs (as needed)
+   Look up specific techniques
+```
+
+---
+
+## Community & Support
+
+### Discord
+Join the WDS community for:
+- Questions and answers
+- Project feedback
+- Feature discussions
+
+### GitHub
+- Report issues
+- Request features
+- Contribute
+
+### YouTube
+- Video tutorials
+- Walkthroughs
+- Case studies
+
+---
+
+## Quick Links
+
+- [Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)
+- [Workflows](../WDS-WORKFLOWS-GUIDE.md)
+- [Modular Architecture](../workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md)
+- [Why-Based Specifications](../workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md)
+
+---
+
+**Ready to dive deeper? Start with the [Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)!**
+
+---
+
+[← Back to Quick Start](quick-start.md)

src/modules/wds/course/00-course-overview.md

@@ -0,0 +1,185 @@
+# WDS Course: From Designer to Linchpin
+
+**Master the complete WDS methodology and become indispensable as a designer in the AI era**
+
+---
+
+## Welcome to the WDS Course
+
+This comprehensive course teaches you the complete WDS workflow through **practical modules** that transform how you design products.
+
+**The paradigm shift:**
+- The design becomes the specification
+- The specification becomes the product
+- The code is just the printout
+
+**What you'll become:**
+- The linchpin designer who makes things happen
+- The gatekeeper between business goals and user needs
+- The irreplaceable designer in the AI era
+
+**Time investment:** ~10 hours total
+**Result:** Complete mastery of WDS methodology from project brief to AI-ready specifications
+
+---
+
+## Who Created WDS?
+
+**Mårten Angner** is a UX designer and founder of Whiteport, a design and development agency based in Sweden. After years of working with AI tools, Mårten observed that traditional design handoffs were breaking down. Designers would create beautiful mockups, hand them off to developers, and watch their creative intent get lost in translation.
+
+Mårten developed WDS to solve this problem - a methodology where design thinking is preserved and amplified through AI implementation, not diluted and lost.
+
+**The Mission:** WDS is completely free and open-source. Mårten created it as a **plugin module for BMad Method** - an open-source AI-augmented development framework - to give designers everywhere the tools they need to thrive in the AI era.
+
+---
+
+## Before You Start
+
+**[→ Getting Started Guide](00-getting-started/overview.md)**
+
+Review prerequisites, choose your learning path, and get support:
+- **Prerequisites** - Skills, tools, time investment
+- **Learning Paths** - Full immersion, quick start, or self-paced
+- **Support** - Testimonials, FAQ, community
+
+**Reading time:** ~15 minutes
+
+---
+
+## Course Structure
+
+Each module contains:
+- **Inspiration** - Why this matters and what you'll gain
+- **Teaching** - How to do it with confidence and AI support
+- **Practice** - Apply it to your own project
+- **Tutorial** - Quick step-by-step guide (for practical modules)
+
+**Learning format:**
+- Read as documentation
+- Generate videos/podcasts with NotebookLM
+- Use in workshops and team training
+- Apply to real projects as you learn
+
+---
+
+## Course Modules
+
+### Foundation
+- [Module 01: Why WDS Matters](module-01-why-wds-matters/module-01-overview.md)
+
+### Phase 1: Project Brief
+- [Module 02: Create Project Brief](module-02-project-brief/)
+
+### Phase 2: Trigger Mapping
+- [Module 03: Identify Target Groups](module-03-identify-target-groups/)
+- [Module 04: Map Triggers & Outcomes](module-04-map-triggers-outcomes/)
+- [Module 05: Prioritize Features](module-05-prioritize-features/)
+
+### Phase 3: Platform Requirements
+- [Module 06: Platform Requirements](module-06-platform-requirements/)
+- [Module 07: Functional Requirements](module-07-functional-requirements/)
+
+### Phase 4: Conceptual Design (UX Design)
+- [Module 08: Initialize Scenario](module-08-initialize-scenario/)
+- [Module 09: Sketch Interfaces](module-09-sketch-interfaces/)
+- [Module 10: Analyze with AI](module-10-analyze-with-ai/)
+- [Module 11: Decompose Components](module-11-decompose-components/)
+- [Module 12: Why-Based Specifications](module-12-why-based-specs/)
+- [Module 13: Validate Specifications](module-13-validate-specifications/)
+
+### Phase 5: Design System
+- [Module 14: Extract Design Tokens](module-14-extract-design-tokens/)
+- [Module 15: Component Library](module-15-component-library/)
+
+### Phase 6: Development Integration
+- [Module 16: UI Roadmap](module-16-ui-roadmap/)
+
+---
+
+## Learning Paths
+
+**Complete Course:** All 16 modules (~10 hours)
+
+**Quick Start:** Modules 1, 4, 8, 12 (~3 hours)
+
+**Phase-Specific:** Jump to any phase as needed
+
+---
+
+## NotebookLM Integration
+
+Each module has matching content for NotebookLM:
+- Feed module lessons to NotebookLM
+- Generate audio podcasts for learning on the go
+- Generate video presentations for team training
+- Create study guides and summaries
+
+**All modules are optimized for AI-assisted learning.**
+
+---
+
+## Module Structure
+
+Every module follows the same pattern:
+
+**1. Inspiration (10 min)**
+- Why this step matters
+- The transformation you'll experience
+- Real-world impact
+
+**2. Teaching (20 min)**
+- How to do it with confidence
+- AI support at each step
+- Dog Week example walkthrough
+
+**3. Practice (10 min)**
+- Apply to your own project
+- Step-by-step instructions
+- Success criteria
+
+**4. Tutorial (optional)**
+- Quick step-by-step guide
+- "Just show me how to do it"
+- For practical modules only
+
+---
+
+## After the Course
+
+Once you've completed the modules:
+
+1. **[Workflows Guide](../workflows/WDS-WORKFLOWS-GUIDE.md)** - Reference documentation
+2. **[Quick Start](../getting-started/quick-start.md)** - Try WDS with agent
+3. **[Community](https://discord.gg/whiteport)** - Get help and share your work
+
+---
+
+## Prerequisites
+
+**What you need:**
+- Basic design thinking and UX principles
+- Ability to sketch interfaces (hand-drawn or digital)
+- Understanding of user needs and business goals
+- Willingness to think deeply about WHY
+
+**What you DON'T need:**
+- ❌ Coding skills
+- ❌ Advanced technical knowledge
+- ❌ Experience with AI tools
+- ❌ Formal design education
+
+**If you can design interfaces and explain your thinking, you're ready to start.**
+
+---
+
+## Ready to Begin?
+
+Ten hours of learning. A lifetime of being indispensable.
+
+**[Start with Module 01: Why WDS Matters →](module-01-why-wds-matters/module-01-overview.md)**
+
+---
+
+**This course is free and open-source**
+**Created by Mårten Angner and the Whiteport team**
+**Integrated with BMad Method for seamless design-to-development workflow**

src/modules/wds/course/00-getting-started/00-getting-started-NOTEBOOKLM-PROMPT.md

@@ -0,0 +1,261 @@
+# NotebookLM Prompt: Getting Started with WDS
+
+**Use this prompt to generate audio/video content from the Getting Started sections**
+
+---
+
+## Instructions for NotebookLM
+
+Upload these files to NotebookLM:
+1. `overview.md`
+2. `01-prerequisites.md`
+3. `02-learning-paths.md`
+4. `03-support.md`
+
+Then use this prompt to generate engaging audio content:
+
+---
+
+## Prompt
+
+Create an engaging 15-minute podcast conversation between two hosts discussing the WDS (Whiteport Design Studio) course getting started guide. 
+
+**Host 1 (The Skeptic):** A designer who's heard about WDS but is uncertain about investing time in another methodology. Asks practical questions about prerequisites, time commitment, and real-world value.
+
+**Host 2 (The Advocate):** A designer who understands WDS deeply and can explain why it matters, especially in the AI era. Enthusiastic but grounded in practical benefits.
+
+**Conversation structure:**
+
+### 1. Opening (2 min) - Hook the listener
+
+Start with The Skeptic expressing fatigue: "Another design methodology? I've been through Lean UX, Design Thinking, Jobs to be Done... what makes WDS different?" 
+
+The Advocate responds with the core paradigm shift that changes everything: "Here's what's different - in WDS, the design becomes the specification. The specification becomes the product. The code is just the printout - the projection to the end user." Explain that this isn't just another process overlay, it's a fundamental shift in how designers work with AI.
+
+**Background context:** The Advocate explains that WDS (Whiteport Design Studio) was created by Mårten Angner, a UX designer and founder of Whiteport, a design and development agency from Sweden. Mårten developed WDS as a plugin module for the BMad Method - an open-source AI-augmented development framework. The goal was to give designers everywhere free and open-source access to AI agents specifically tailored for design work. After years of working with AI tools, Mårten realized that traditional design handoffs were breaking down. Designers needed a methodology where their thinking could be preserved and amplified through AI implementation, not lost in translation. WDS emerged from real-world projects where designers could deliver deeper, more complete work while becoming the strategic thinkers their teams need. By making it open-source and integrating it with BMad Method, Mårten ensures that any designer can access these powerful AI-augmented workflows without cost barriers.
+
+Introduce the context: we're in the AI era where AI can generate mockups in seconds, follow design systems perfectly, and iterate endlessly. The question isn't whether AI will change design - it already has. The question is: which side of the line are you on? Are you doing factory work that AI can replace, or are you a linchpin designer who makes things happen?
+
+Give a quick overview: this conversation will cover what you actually need to start (spoiler: you already have it), the simple three-step setup to begin, the powerful deliverables you'll create, and why designers who master WDS become indispensable rather than replaceable.
+
+### 2. Prerequisites Discussion (3 min) - Address concerns
+
+The Skeptic jumps in with the practical concerns: "Okay, but what do I actually need? Do I need to learn to code? What tools do I need to buy? How much time are we talking about?"
+
+The Advocate breaks it down clearly. For skills, if you can design interfaces and explain your thinking, you're ready. That's it. You need basic design thinking and UX principles - which you already have if you're working as a designer. You need to be able to sketch interfaces, whether that's on paper or digitally. And you need to be willing to think deeply about WHY, not just WHAT.
+
+What you DON'T need is crucial: no coding skills, no advanced technical knowledge, no experience with AI tools, no formal design education. The truth is simple - if you can design interfaces and explain your thinking, you have everything you need to start.
+
+For tools, there's an important learning curve to discuss honestly. Paper and pen work best for sketching (seriously). Or use any digital sketching tool you're comfortable with - Excalidraw, Figma, iPad with Pencil.
+
+Here's the real cost: You need to learn how to operate an IDE like Cursor or VS Code. This is a learning curve - it's not just opening Figma anymore. You'll be delivering your designs through GitHub, which means learning version control and collaborating in a developer's environment. The Advocate is honest: "This feels uncomfortable at first. You're stepping into developer territory."
+
+**The financial cost:** An AI-powered IDE like Cursor costs $15-20 per month for smaller projects, scaling up to around $80 per month for large enterprise projects where you're designing non-stop every day. This is in addition to your existing design tools.
+
+But here's what you gain: You've removed one of the biggest barriers between designers and developers. Your designs now live in the same place as the code. No more handoff nightmares. No more 'lost in translation' moments. You've created the perfect environment for your designs to flourish - where specifications become implementation seamlessly.
+
+**The game-changer:** You can now create fully standalone frontend prototypes to refine your designs and conduct usability testing - without waiting for a tech team to set things up. You're no longer blocked by development schedules. And with time, you'll be able to deliver parts of the frontend work for the final product within the same pipeline. You're not just designing anymore - you're building.
+
+Time investment is realistic: about 10 hours for the course content, spread over days or weeks at your own pace. Each module takes 30-40 minutes. Practice exercises add 1-2 hours per module. But learning the IDE and GitHub workflow? Add another 5-10 hours of getting comfortable with the tools.
+
+The Skeptic asks the common questions: "What if I don't have a project to practice with?" The Advocate explains that the course includes practice exercises, and you can use a hypothetical project or redesign an existing app. "Can I use this with my current design process?" Yes - WDS complements existing processes. Many designers integrate it gradually rather than replacing everything at once.
+
+### 3. Getting Started - Three Simple Steps (5 min) - Just follow along
+
+The Skeptic asks: "Okay, I'm interested. But where do I actually start? Is this complicated to set up?"
+
+The Advocate responds: "Here's the beautiful part - it's three simple steps, and the course walks you through everything. No complex decisions, no choosing paths. Just follow along."
+
+**Step 1: Install your IDE** - Download Cursor or VS Code. The course has clear instructions. Yes, it feels different from Figma at first, but you'll be comfortable within a few hours. This is your new design workspace where specifications live alongside code.
+
+**Step 2: Clone the WDS repository locally** - One command in your terminal. The course shows you exactly how. Now you have all the templates, examples, and course materials on your machine. Everything you need is right there.
+
+**Step 3: Create your first project in GitHub** - The course guides you through setting up your first WDS project repository. This is where your design specifications will live. GitHub might feel intimidating, but you're just creating a folder for your work - the course makes it simple.
+
+The Advocate emphasizes: "That's it. Three steps, maybe 30 minutes total. Then you start designing. The course instructions guide you through every module. You don't need to figure anything out on your own."
+
+The Skeptic asks: "But what if I get stuck? What if something doesn't make sense?"
+
+The Advocate: "There's a dedicated channel for designers in the BMad Discord community. Real designers using WDS every day. Ask questions, share your work, get feedback. You're never alone in this."
+
+### 4. The Deliverables - What You'll Actually Create (4 min) - This is the exciting part
+
+The Skeptic asks the crucial question: "Okay, but what will I actually create? What are these deliverables everyone talks about?"
+
+The Advocate gets excited: "This is where it gets really good. By following the course, you'll create four major artifacts that transform how you work. Let me walk you through each one because these aren't just documents - they're your new superpowers."
+
+**First: Your Project Brief** - This isn't a typical brief. It's your project's strategic foundation with vision and goals clearly defined, stakeholders and constraints documented, and the foundation for every design decision you'll make. This becomes your north star. When stakeholders ask 'why did we build it this way?' you point to the brief. When developers need context, it's all there. When you need to defend a design decision, the reasoning is documented. This is strategic thinking made visible.
+
+**Second: Your Trigger Map** - This is pure strategic gold. You've identified and prioritized target groups, mapped user triggers and outcomes, and prioritized features by impact. This tells you exactly what to build and why. No more guessing what features matter. No more building things nobody uses. The trigger map creates a logical chain of reasoning between the business goals and the users' goals that is traceable to every feature and piece of content in the product. When product managers ask 'what should we build next?' you have the answer, backed by user psychology and business impact.
+
+**Third: Scenario Specifications** - This is where your brilliance comes to life. Here's the magic: AI agents in WDS support you throughout the design process - helping you explore what to draw, discussing design solutions with pros and cons, collaborating as you finalize your design. Then, once you've made all your design decisions, the agents become genuinely interested in capturing every nuance of your thinking in text. They help you document everything your sketch can't convey - why every object is placed exactly where it is, how it connects to the wider picture, what alternatives you considered and rejected. These Conceptual Specifications give your designs eternal life. It's your thinking, your creative integrity, captured and preserved. Not factory work - this is where your design brilliance becomes immortal.
+
+**Fourth: Your Design System Foundation** - Design tokens extracted from your specs, component patterns identified, and reusable architecture defined. This scales your design decisions across the entire product. Every color, every spacing decision, every interaction pattern - documented and reusable. You're not just designing one screen anymore. You're creating a system that scales infinitely. This is how your design thinking compounds over time.
+
+The Advocate pauses for emphasis: "These four deliverables transform you from someone who makes mockups to someone who creates strategic design systems. Each one builds on the last. Each one amplifies your impact. And here's the key - the course walks you through creating all of them, step by step, for your own project."
+
+The Skeptic asks: "But wait - writing specifications sounds like factory work. Isn't that exactly what we're trying to avoid?" The Advocate responds with passion: "That's the beautiful reframe! In WDS, you're not grinding out documentation. The AI agents are your creative partners. They help you think through design solutions, explore alternatives, discuss trade-offs. Then - and this is crucial - they're genuinely fascinated by your thinking. They want to capture every nuance, every decision, every insight. It's like having a brilliant assistant who's obsessed with preserving your creative genius for eternity. The specifications aren't factory work - they're the point where your brilliance comes to life in a form that gives your designs eternal life. Your thinking, your creative integrity, captured perfectly so it can never be lost."
+
+### 5. The AI Era Reality Check (2 min) - Address the elephant in the room
+
+The Skeptic voices the fear many designers have: "Let's be real here. Won't AI just replace designers anyway? Why invest time learning anything when AI is getting better every day?"
+
+The Advocate addresses this head-on with the factory mindset versus linchpin mindset concept from Seth Godin's book "Linchpin: Are You Indispensable?" For over a century, we've been trained to be cogs in a machine - show up, follow instructions, do your part, go home. Replaceable. Interchangeable. Traditional design work follows this exact pattern: get a brief, create mockups, hand off to developers, hope for the best. That's factory work, just with Figma instead of an assembly line.
+
+Here's the uncomfortable truth: AI is really, really good at factory work. If your value as a designer comes from creating predictable outputs based on clear instructions, you're competing with something that's faster, more consistent, and infinitely scalable. AI can generate mockups instantly, follow design systems perfectly, iterate through hundreds of variations without fatigue, and work 24/7 at the same quality level.
+
+But - and this is crucial - AI cannot be a linchpin. It can't walk into chaos and create order. It can't sense when a client is asking for the wrong thing. It can't connect a business goal to a psychological insight to a technical constraint and come up with something nobody expected but everyone loves.
+
+The internet is drowning in what we call "AI slop" - generic interfaces that look fine but feel dead. Products that check all the boxes but have no soul. This is what happens when you let AI do the thinking. But here's the brutal market reality: bad products used to fail after launch. Now bad products never even get to start. Users have infinite options. They can smell soulless design from a mile away. If your product doesn't immediately feel different, feel right, feel like someone actually cared - it's dead on arrival.
+
+This is the opportunity. Linchpin designers do what AI fundamentally cannot do: they give products a soul. They navigate five dimensions of thinking simultaneously - business goals, user psychology, product strategy, technical constraints, and design execution - and find the human truth at the intersection. They make judgment calls that create emotional resonance. They build trust through thoughtful decisions. They care about the outcome in a way that shows in every interaction.
+
+The Advocate explains the transformation: "Designers who master WDS become strategic thinkers who deliver complete value. But here's the crucial difference from traditional AI tools - in WDS, AI agents are your creative partners, not your replacements. They help you explore design solutions, discuss pros and cons, support your thinking process. Then they become fascinated documentarians of your brilliance - capturing every nuance of your creative decisions in Conceptual Specifications that give your designs eternal life."
+
+The key insight: with WDS, your design contribution completely replaces prompting. You make design decisions with AI as your thinking partner. Then AI helps capture your creative integrity in text - not factory work, but preserving your genius. The result is an absolute goldmine for everyone - providing clarity that works like clockwork, replacing hours of pointless back-and-forth prompting. You remain in the loop as the skilled, experienced designer who evaluates AI's work, catches its confident mistakes, and ensures what ships actually makes sense.
+
+### 6. Getting Support & Next Steps (1 min) - You're ready
+
+The Skeptic asks: "Okay, I'm convinced. What's my actual next step right now?"
+
+The Advocate: "Right now? Go to the WDS GitHub repository. Start with Module 01 - Why WDS Matters. Three lessons, 30 minutes total. You'll understand the problem you're solving, the solution WDS provides, and the transformation you'll experience.
+
+Then follow the setup instructions - install your IDE, clone the repo, create your first project. The course walks you through everything. When you get stuck - and you will, we all do - jump into the BMad Discord. There's a dedicated channel for designers. Real people using WDS every day who remember what it's like to start.
+
+The course includes detailed examples and clear guidance for every module. Practice exercises come with clear success criteria so you know if you're on track. You're never guessing if you're doing it right."
+
+The Skeptic: "And this is all free?"
+
+The Advocate: "Completely free and open-source. The only cost is your IDE subscription - $15-20 per month for Cursor. That's it. No course fees, no hidden costs, no upsells. Mårten created WDS to help designers thrive in the AI era, not to sell you something."
+
+### 7. Closing (1 min) - Clear call to action
+
+The Advocate brings it home with the paradigm shift: "Remember this - the design becomes the specification. The specification becomes the product. The code is just the printout - the projection to the end user."
+
+The Skeptic, now convinced, summarizes: "So I already have the skills I need, the setup takes 30 minutes, the course walks me through everything, I'll create four major deliverables that transform how I work, and there's a community to support me when I get stuck. And it makes me indispensable instead of replaceable in the AI era."
+
+The Advocate confirms: "Exactly. Three simple steps to start. Ten hours of learning. Four powerful deliverables. A lifetime of being indispensable. The question isn't whether to learn WDS. The question is: which side of the line do you want to be on? Factory worker or linchpin designer? Replaceable or indispensable?"
+
+The clear next step: Go to the WDS GitHub repository right now. Start with Module 01 - Why WDS Matters. Then follow the setup instructions. Then start creating your first deliverable - your Project Brief. The course guides you through everything.
+
+The Skeptic ends with: "I'm in. Let's do this."
+
+The Advocate adds: "Perfect! See you in the BMad Discord. Can't wait to see what you create."
+
+---
+
+## Resources to Include
+
+At the end of the podcast, The Advocate should mention these resources for listeners who want to explore further:
+
+**Getting Started:**
+- WDS Course: Start with Module 01 - Why WDS Matters
+- GitHub Repository: github.com/bmad-code-org (full course materials, examples, templates)
+- BMad Method Website: bmadmethod.com (case studies, blog posts, methodology deep dives)
+
+**Community & Support:**
+- GitHub Discussions: Ask questions, share projects, get feedback
+- NotebookLM Integration: Generate audio/video versions of any module
+- Workshop Materials: Available for team training
+
+**Real-World Examples:**
+- Case Studies: See real transformations from traditional to WDS approach
+- Design System Examples: How WDS scales across products
+- Specification Templates: Start with proven patterns
+
+**Tools & Templates:**
+- Project Brief Template: Start your first WDS project
+- Trigger Map Template: Map user needs to features
+- Scenario Specification Template: Create AI-ready specs
+- Design Token Extraction Guide: Build your design system
+
+The Advocate emphasizes: "Everything is free and open-source. BMad Method built WDS to help designers thrive in the AI era, not to sell you something. Download it, use it, share it with your team, contribute back if you find it valuable. The only cost is your time - 10 hours to learn, a lifetime of being indispensable."
+
+**Tone:**
+- Conversational and engaging, not academic
+- The Skeptic asks real questions designers actually have
+- The Advocate provides concrete answers with examples
+- Both hosts are enthusiastic but realistic about the learning curve
+- Use the testimonials naturally in conversation
+- Reference real case studies showing traditional vs WDS transformation
+
+**Key messages to emphasize:**
+- You already have the skills needed
+- Three simple steps to get started (30 minutes setup)
+- Four powerful deliverables that transform how you work
+- The paradigm shift: design IS the specification
+- AI agents as creative partners - help you think, then capture your brilliance
+- Specifications aren't factory work - they're where your genius becomes immortal
+- Just follow along - the course guides you through everything
+- BMad Discord community support when you get stuck
+- AI is an amplifier, not a replacement
+- WDS makes you irreplaceable in the AI era
+- Free and open-source (only IDE subscriptions and AI tokens cost start as low as: $15-20/month)
+
+**Avoid:**
+- Being too salesy or promotional
+- Oversimplifying the learning curve
+- Making unrealistic promises
+- Technical jargon without explanation
+
+---
+
+## Expected Output
+
+A natural, engaging conversation that:
+- Answers all the questions a designer would have before starting
+- Builds confidence that they can succeed with WDS (just follow along!)
+- Makes the four deliverables tangible and exciting
+- Clarifies the value proposition (indispensable in AI era)
+- Emphasizes the simple three-step setup
+- Highlights BMad Discord community support
+- Provides clear next steps (go to GitHub, start Module 01)
+- Takes 15 minutes to listen to
+
+---
+
+## Alternative: Video Script
+
+If generating video instead of audio, add these visual elements:
+
+**On-screen text:**
+- "3 Simple Steps: Install IDE → Clone Repo → Create Project"
+- The four deliverables as graphics (Project Brief, Trigger Map, Scenario Specs, Design System)
+- The paradigm shift statement as a title card
+- "BMad Discord: Dedicated Designer Channel"
+- Key statistics (30 min setup, 10 hours course, $15-20/month for IDE)
+- "Next: Module 01" as closing card
+
+**B-roll suggestions:**
+- Three-step setup process (IDE install → Clone repo → GitHub project creation)
+- The four deliverables being created (Project Brief, Trigger Map, Scenario Specs, Design System)
+- Designer sketching on paper
+- Cursor/VS Code IDE interface with specifications
+- GitHub workflow showing design specs
+- BMad Discord community channel with designers helping each other
+- Designer creating frontend prototype with AI
+- Before/after: mockup handoff vs specification workflow
+- Community showcase examples
+
+---
+
+## Usage Tips
+
+1. **Upload all 4 files** to NotebookLM before generating
+2. **Use the prompt exactly** as written for best results
+3. **Generate multiple versions** and pick the best one
+4. **Share the audio/video** with your team or community
+5. **Iterate** - if the output isn't quite right, refine the prompt
+
+---
+
+## Next Steps
+
+After generating the Getting Started content:
+- Create NotebookLM prompt for Module 01: Why WDS Matters
+- Build prompts for all 16 modules (complete audio course library)
+- Share in BMad Discord designer channel
+- Use in workshops and team training
+- Iterate based on community feedback
+
+**[← Back to Getting Started Overview](overview.md)**

src/modules/wds/course/00-getting-started/00-getting-started-overview.md

@@ -0,0 +1,58 @@
+# Getting Started with WDS
+
+**Everything you need to know before starting the course**
+
+---
+
+## Welcome
+
+Before diving into the WDS methodology, take a few minutes to understand what you need to start, how to approach the course, and where to get help.
+
+**This section covers:**
+1. **Prerequisites** - Skills, tools, and requirements
+2. **Learning Paths** - How to take the course and what you'll create
+3. **Support** - Testimonials, FAQ, and community
+
+**Total reading time:** ~15 minutes
+
+---
+
+## Quick Navigation
+
+### [01. Prerequisites →](01-prerequisites.md)
+What skills you need, tools required, and time investment
+- **Time:** 5 minutes
+- **Key question:** Am I ready to start?
+
+### [02. Learning Paths →](02-learning-paths.md)
+Choose your journey and see what you'll create
+- **Time:** 5 minutes
+- **Key question:** Which path is right for me?
+
+### [03. Support →](03-support.md)
+Testimonials, FAQ, and getting help
+- **Time:** 5 minutes
+- **Key question:** What if I get stuck?
+
+---
+
+## Ready to Start?
+
+Once you've reviewed these sections, you're ready to begin:
+
+**[Start Module 01: Why WDS Matters →](../module-01-why-wds-matters/module-01-overview.md)**
+
+Or review the full course structure:
+
+**[← Back to Course Overview](../00-course-overview.md)**
+
+---
+
+## Your Transformation Starts Now
+
+Remember:
+- **The design becomes the specification**
+- **The specification becomes the product**
+- **The code is just the printout**
+
+Ten hours of learning. A lifetime of being indispensable.

src/modules/wds/course/00-getting-started/01-prerequisites.md

@@ -0,0 +1,87 @@
+# Getting Started: Prerequisites
+
+**What you need to start learning WDS**
+
+---
+
+## What Skills You Need
+
+**Required (you probably already have these):**
+- Basic design thinking and UX principles
+- Ability to sketch interfaces (hand-drawn or digital)
+- Understanding of user needs and business goals
+- Willingness to think deeply about WHY
+
+**NOT required:**
+- ❌ Coding skills
+- ❌ Advanced technical knowledge
+- ❌ Experience with AI tools
+- ❌ Formal design education
+
+**The truth:** If you can design interfaces and explain your thinking, you have everything you need to start.
+
+---
+
+## Time Investment
+
+### How Long Does It Take?
+
+**Total course time:** ~10 hours
+- Spread over days or weeks at your own pace
+- Each module: 30-40 minutes
+- Practice exercises: 1-2 hours per module
+
+**Breakdown:**
+- **Week 1-2:** Foundation modules (Why WDS, Project Brief)
+- **Week 3-4:** Core workflow (Trigger Mapping, Scenarios)
+- **Week 5-6:** Advanced topics (Design Systems, Handoff)
+- **Ongoing:** Practice with your own projects
+
+**Real-world application:**
+- First project with WDS: 2-3x slower than your usual process (learning curve)
+- Second project: Same speed as traditional approach
+- Third project onwards: 3-5x faster with better quality
+
+---
+
+## Tools You'll Need
+
+### Essential Tools
+
+**For sketching:**
+- Paper and pen (seriously, this works best)
+- OR digital sketching tool (Excalidraw, Figma, iPad + Pencil)
+
+**For AI assistance:**
+- Access to Claude, ChatGPT, or similar AI assistant
+- Free tier is sufficient to start
+
+**For documentation:**
+- Text editor (VS Code recommended, but any will work)
+- Markdown support (built into most modern editors)
+
+**For collaboration:**
+- Git/GitHub (optional but recommended)
+- Shared folder system (Google Drive, Dropbox, etc.)
+
+**Total cost to get started:** $0-20/month
+- Free tier AI tools work fine
+- Paid AI subscriptions ($20/month) provide better experience but aren't required
+
+---
+
+## Are You Ready?
+
+You have everything you need if you can answer YES to these:
+- ✅ I can design interfaces and explain my thinking
+- ✅ I have 10 hours to invest over the next few weeks
+- ✅ I have access to basic tools (paper/pen + AI assistant)
+- ✅ I'm willing to think deeply about WHY
+
+**Next:** Choose your learning path
+
+**[Continue to Learning Paths →](02-learning-paths.md)**
+
+---
+
+[← Back to Overview](overview.md) | [Next: Learning Paths →](02-learning-paths.md)

src/modules/wds/course/00-getting-started/02-learning-paths.md

@@ -0,0 +1,90 @@
+# Getting Started: Learning Paths
+
+**Choose your journey through WDS**
+
+---
+
+## Choose Your Journey
+
+### Option 1: Full Immersion (Recommended)
+- Complete all modules in order
+- Practice exercises for each module
+- Apply to a real project as you learn
+- **Time:** 6-8 weeks, 10-15 hours total
+- **Best for:** Designers who want to master the methodology
+
+### Option 2: Quick Start
+- Focus on core modules (Module 01, 02, 04, 06)
+- Skip advanced topics initially
+- Get started fast, learn more later
+- **Time:** 2-3 weeks, 3-4 hours total
+- **Best for:** Designers who need results quickly
+
+### Option 3: Self-Paced
+- Learn one module per week
+- Deep practice between modules
+- Build multiple projects as you learn
+- **Time:** 16+ weeks, 20+ hours total
+- **Best for:** Designers who want deep mastery
+
+---
+
+## What You'll Create
+
+### Your First WDS Project
+
+By the end of this course, you'll have created:
+
+**1. Complete Project Brief**
+- Vision and goals clearly defined
+- Stakeholders and constraints documented
+- Foundation for all design decisions
+
+**2. Trigger Map**
+- Target groups identified and prioritized
+- User triggers and outcomes mapped
+- Features prioritized by impact
+
+**3. Scenario Specifications**
+- At least one complete user scenario
+- Why-based specifications for key components
+- AI-ready documentation
+
+**4. Design System Foundation**
+- Design tokens extracted from your specs
+- Component patterns identified
+- Reusable architecture defined
+
+**Estimated value:** What used to take 6-8 weeks now takes 1-2 weeks
+
+---
+
+## Course Format
+
+Each module contains:
+- **Inspiration** - Why this matters and what you'll gain
+- **Teaching** - How to do it with confidence and AI support
+- **Practice** - Apply it to your own project
+- **Tutorial** - Quick step-by-step guide (for practical modules)
+
+**Learning formats:**
+- Read as documentation
+- Generate videos/podcasts with NotebookLM
+- Use in workshops and team training
+- Apply to real projects as you learn
+
+---
+
+## Ready to Begin?
+
+Choose your path and start learning:
+
+**[Start Module 01: Why WDS Matters →](../module-01-why-wds-matters/module-01-overview.md)**
+
+Or check support resources first:
+
+**[Continue to Support →](03-support.md)**
+
+---
+
+[← Back to Prerequisites](01-prerequisites.md) | [Next: Support →](03-support.md)

src/modules/wds/course/00-getting-started/03-support.md

@@ -0,0 +1,121 @@
+# Getting Started: Support
+
+**Help, community, and what other designers say**
+
+---
+
+## What Other Designers Say
+
+### Testimonials
+
+> "I was skeptical at first - another design methodology? But WDS changed how I think about my role. I'm no longer just making things pretty. I'm the strategic thinker who makes products come alive."
+> 
+> **— Sarah K., Product Designer**
+
+> "The 5x speed increase is real. But what surprised me most was how much clearer my thinking became. Writing why-based specifications forced me to understand the 'why' at a deeper level."
+>
+> **— Marcus L., UX Lead**
+
+> "I thought AI would replace me. WDS showed me how to make AI amplify my thinking instead. Now I'm the most valuable designer on my team."
+>
+> **— Priya S., Senior Designer**
+
+> "The paradigm shift hit me in Module 4: my design IS the product. The code is just the printout. That completely changed how I approach every project."
+>
+> **— James T., Design Director**
+
+*Note: More testimonials will be added as designers complete the course.*
+
+---
+
+## Common Questions
+
+### FAQ
+
+**Q: Do I need to know how to code?**
+A: No. WDS is about design thinking and specifications. AI handles the implementation.
+
+**Q: What if I don't have a project to practice with?**
+A: The course includes practice exercises. You can also use a hypothetical project or redesign an existing app.
+
+**Q: Can I use this with my current design process?**
+A: Yes! WDS complements existing processes. Many designers integrate it gradually.
+
+**Q: Is this only for digital products?**
+A: WDS is optimized for digital products, but the principles apply to any design work.
+
+**Q: What if I get stuck?**
+A: Each module includes clear examples and guidance. The AI assistant can help clarify concepts as you learn.
+
+**Q: Do I need to complete all modules?**
+A: No. The Quick Start path (4 modules) gives you enough to start applying WDS immediately.
+
+**Q: Can I teach this to my team?**
+A: Yes! WDS is open-source and free. Share it with your entire team.
+
+**Q: How is this different from traditional design documentation?**
+A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. This makes it AI-ready and preserves your design intent.
+
+---
+
+## Getting Help
+
+### During the Course
+
+**While learning:**
+- Each module includes detailed examples
+- AI assistants can clarify concepts in real-time
+- Practice exercises with clear success criteria
+
+**After completion:**
+- GitHub Discussions for questions and sharing
+- Community showcase of WDS projects
+- Regular updates and new case studies
+
+**Contributing:**
+- WDS is open-source and welcomes contributions
+- Share your case studies and learnings
+- Help improve the course for future designers
+
+---
+
+## Support & Community
+
+### Resources
+
+**Documentation:**
+- Full course materials in markdown
+- NotebookLM integration for audio/video learning
+- Workshop materials for team training
+
+**Community:**
+- GitHub Discussions for Q&A
+- Project showcase and feedback
+- Regular updates and improvements
+
+**Open Source:**
+- Free to use and share
+- Contributions welcome
+- Help shape the future of WDS
+
+---
+
+## Ready to Start?
+
+You have everything you need:
+- ✅ The skills (design thinking)
+- ✅ The tools (paper + AI)
+- ✅ The time (10 hours)
+- ✅ The motivation (staying indispensable)
+
+**Next step:** Start learning!
+
+**[Start Module 01: Why WDS Matters →](../module-01-why-wds-matters/module-01-overview.md)**
+
+Or review the full course structure:
+
+**[← Back to Course Overview](../00-course-overview.md)**
+
+---
+
+[← Back to Learning Paths](02-learning-paths.md) | [Start Learning →](../module-01-why-wds-matters/module-01-overview.md)

src/modules/wds/course/module-01-why-wds-matters/lesson-01-the-problem.md

@@ -0,0 +1,107 @@
+# Module 01: Why WDS Matters
+## Lesson 1: The Problem We're Solving
+
+**Understanding the factory mindset and the AI era**
+
+---
+
+## Why Learning WDS Matters
+
+Imagine being the one person on your team that everyone depends on. Not because you work the longest hours or create the prettiest mockups, but because you do something nobody else can do - not even AI. You're about to learn a design methodology that makes you that person.
+
+This isn't about working faster or making shinier designs. It's about becoming what bestselling author Seth Godin calls a **Linchpin** - someone who is genuinely irreplaceable. Think about the difference between a factory worker who follows instructions and the person who figures out what needs to be done in the first place. The first person can be replaced by a machine. The second person? They're the one who makes things happen.
+
+In the AI era, designers who master WDS become linchpin designers. They connect ideas that seem unrelated, make judgment calls when there's no clear answer, and create experiences that feel right in ways that can't be reduced to a formula.
+
+**What makes an irreplaceable designer:**
+- Connects disparate ideas across business, psychology, and technology
+- Makes things happen when there's no instruction manual
+- Creates value that can't be commoditized or automated
+- Is essential, not interchangeable
+
+---
+
+## What You'll Gain
+
+Here's the transformation you're about to experience. Right now, you might feel uncertain about your future as a designer in a world where AI can generate interfaces in seconds. You might wonder if your skills will still matter in five years. That uncertainty is about to disappear.
+
+By the end of this module, you'll have a completely different relationship with AI. Instead of seeing it as a threat, you'll understand it as an amplifier of your unique human abilities. You'll know exactly what makes you irreplaceable, and you'll have a methodology that lets you work with AI as a partner rather than a competitor.
+
+Most importantly, you'll understand the five dimensions of thinking that only humans can navigate simultaneously - and you'll know how to use them to create designs that AI could never conceive on its own.
+
+**Your transformation:**
+- ✅ Understand why designers are irreplaceable in the AI era
+- ✅ Master the 5 dimensions of designer thinking
+- ✅ Recognize what AI can and cannot do
+- ✅ Embrace specifications as the new code
+- ✅ Amplify your value through AI partnership
+
+---
+
+## The Problem We're Solving
+
+### The Factory Mindset vs The Linchpin Mindset
+
+In his groundbreaking book [Linchpin: Are You Indispensable?](https://www.amazon.com/Linchpin-Are-You-Indispensable-ebook/dp/B00354Y9ZU), bestselling author and marketing visionary Seth Godin reveals something uncomfortable: the industrial revolution didn't just change how we make things - it changed how we think about work itself. For over a century, we've been trained to be cogs in a machine. Show up, follow instructions, do your part, go home. Replaceable. Interchangeable. Safe.
+
+Traditional design work follows this exact pattern. You get a brief (instructions), create some mockups (your part), hand them off to developers (next cog in the machine), and hope they understand what you meant. When they don't, you go through endless revisions until something vaguely resembling your vision ships. You're doing factory work - just with Figma instead of an assembly line.
+
+Here's the uncomfortable truth: AI is really, really good at factory work. If your job is to follow instructions and create predictable outputs, you're in trouble. But if you can become a linchpin - someone who connects ideas, makes judgment calls, and creates meaning - you become more valuable than ever.
+
+**The factory mindset in design:**
+- Creates mockups by following briefs (instructions)
+- Hands off to developers (replaceable step)
+- Hopes they understand (no real connection)
+- Endless revisions (cog in the machine)
+- Can be replaced by AI
+
+---
+
+### The AI Threat (For Cogs)
+
+Let's be honest about what's happening. AI can now generate mockups in seconds. It can follow design systems with perfect consistency. It can iterate through hundreds of variations without breaking a sweat. If your value as a designer comes from creating predictable outputs based on clear instructions, you're competing with something that's faster, more consistent, and infinitely scalable.
+
+But here's the thing: AI cannot be a linchpin. It can't walk into a messy situation and figure out what actually needs to happen. It can't sense when a client is asking for the wrong thing. It can't connect a business goal to a psychological insight to a technical constraint and come up with something nobody expected but everyone loves.
+
+**What AI does better than cogs:**
+- Generates mockups instantly (no creative block)
+- Follows design systems perfectly (zero deviation)
+- Iterates through hundreds of variations (no fatigue)
+- Works 24/7 at the same quality level (infinitely scalable)
+- Executes instructions flawlessly (no interpretation errors)
+
+---
+
+### The AI Opportunity (For Linchpin Designers)
+
+Here's where it gets exciting - and where most designers miss the point entirely.
+
+The internet is drowning in AI slop. Generic interfaces that look fine but feel dead. Products that check all the boxes but have no soul. Experiences that function correctly but leave users cold. This is what happens when you let AI do the thinking - you get competent mediocrity at scale.
+
+But here's the brutal truth about today's market: **bad products used to fail after launch. Now bad products never even get to start.** Users have infinite options. They can smell soulless design from a mile away. They won't give you a second chance. If your product doesn't immediately feel different, feel right, feel like someone actually cared - it's dead on arrival.
+
+This is your opportunity. While everyone else is racing to generate more generic content faster, you can create products that come alive. Products with soul. Products that people actually want to use because they feel the human thinking behind them.
+
+Linchpin designers do what AI fundamentally cannot do: they give products a soul. They navigate five dimensions of thinking simultaneously - business goals, user psychology, product strategy, technical constraints, and design execution - and find the human truth at the intersection. They make judgment calls that create emotional resonance. They build trust through thoughtful decisions. They care about the outcome in a way that shows in every interaction.
+
+The bottleneck in product development used to be coding. AI demolished that. Now the bottleneck is **products worth building** - figuring out what to create that won't be just more noise in an ocean of AI-generated mediocrity.
+
+**What makes products come alive (what only designers can do):**
+- Navigate 5 dimensions to find the human truth at the intersection
+- Make judgment calls that create emotional resonance, not just functionality
+- Build trust through decisions that show someone cared
+- Connect business goals to user psychology in ways that feel right
+- Create experiences that stand out from generic AI-generated mediocrity
+- Give products a soul that users can feel
+
+---
+
+## Ready to Continue?
+
+Now that you understand the problem, let's explore the solution.
+
+**[Continue to Lesson 2: The Solution →](lesson-02-the-solution.md)**
+
+---
+
+[← Back to Module Overview](module-01-overview.md) | [Next: Lesson 2 →](lesson-02-the-solution.md)

src/modules/wds/course/module-01-why-wds-matters/lesson-02-the-solution.md

@@ -0,0 +1,71 @@
+# Module 01: Why WDS Matters
+## Lesson 2: Becoming a Linchpin Designer
+
+**The solution: WDS methodology**
+
+---
+
+## Becoming a Linchpin Designer
+
+Seth Godin defines a linchpin as "an individual who can walk into chaos and create order, someone who can invent, connect, create, and make things happen." That's exactly what product design is at its core - walking into the chaos of competing business goals, unclear user needs, technical constraints, and market pressures, and somehow creating order. Creating something that works.
+
+WDS teaches you to be this person systematically. Not through vague advice about "thinking outside the box," but through a concrete methodology that helps you navigate complexity and create clarity. You'll learn to ask the right questions, connect the right dots, and make the right calls - even when there's no obvious right answer.
+
+This is what makes you indispensable. Not your Figma skills. Not your aesthetic taste. Your ability to walk into chaos and create order.
+
+**The irreplaceable designer:**
+- Transforms complexity into clarity
+- Invents solutions nobody expected
+- Bridges business, psychology, and technology
+- Delivers results when there's no roadmap
+
+---
+
+## The Designer's Gift: User-Centric Creativity
+
+Here's Godin's most important insight: linchpins provide something he calls **emotional labor** - the work of genuinely caring about the outcome, connecting with people's real needs, and creating meaning that matters. For designers, this translates into **user-centric creativity** - the uniquely human ability to understand, empathize, and create with purpose.
+
+User-centric creativity means doing the hard work of understanding WHY users feel frustrated instead of just making things look better. It means connecting business goals to human needs in ways that serve both. It means creating experiences that feel right, not just function correctly. It means making judgment calls that serve people, even when it's harder than following a formula.
+
+AI can generate variations endlessly and make things look polished on the surface. But here's what it cannot do: it cannot tell when something is fundamentally wrong. It will confidently create beautiful interfaces that make no logical sense. It will add features that contradict the business goal. It will optimize for metrics that destroy user trust. It will make ridiculous mistakes with absolute confidence - and without a skilled designer as gatekeeper, those mistakes ship.
+
+This is where user-centric creativity becomes critical. You're not just creating - you're evaluating, connecting, and protecting. You understand what it feels like to be a parent struggling to get their kids to help with the dog. You can sense when a business goal conflicts with user needs and find a creative solution that serves both. You're the advocate for the user's presence in every decision. You're the gatekeeper who ensures the impactful meeting between business and user actually happens through the product.
+
+**The designer as gatekeeper:**
+- Catches AI's confident but ridiculous mistakes before they ship
+- Evaluates if solutions actually make logical sense
+- Ensures business goals don't contradict user needs
+- Protects users from metric-driven decisions that destroy trust
+- Advocates for the user's presence in every decision
+- Creates the impactful meeting between business and user
+
+---
+
+## From Cog to Linchpin Designer
+
+Here's the transformation that WDS enables. In the old model, you were a cog designer - creating mockups based on briefs, handing them off to developers who interpreted them their own way, hoping for the best. Your leverage was limited because your thinking stopped at the handoff. You were replaceable because anyone with similar skills could do roughly the same thing.
+
+With WDS and AI, everything changes - and here's the key insight: **your design contribution completely replaces prompting.** Think about it. You make design decisions. AI helps you clarify them in text. The result is an absolute goldmine for everyone on the team - providing clarity that works like clockwork, replacing hours of pointless back-and-forth prompting.
+
+You provide the user-centric creativity - the deep understanding of WHY things need to work a certain way. You create why-based specifications that capture not just what to build, but why you're building it that way and what mistakes to avoid. Then AI implements it - but you're there as gatekeeper, catching the mistakes, evaluating the logic, ensuring it actually serves both business and user.
+
+Here's the paradigm shift: **The design becomes the specification. The specification becomes the product. The code is just the printout - the projection to the end user.** Your thinking no longer stops at handoff. It scales infinitely. Every specification you write becomes a permanent record of your design reasoning that provides clarity for developers, stakeholders, and AI alike. No more endless prompting sessions. No more "can you make it more modern?" Your design thinking, captured in specifications, is the source of truth.
+
+You remain in the loop - the skilled, experienced designer who evaluates AI's work, catches its confident mistakes, and ensures what ships actually makes sense. You become the key designer player - the person who makes things happen. AI becomes your tool - powerful but requiring your expertise to guide it.
+
+**The designer's transformation:**
+- **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage
+- **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely
+- **Result:** From replaceable cog to indispensable gatekeeper - your design IS the product
+
+---
+
+## Ready to Continue?
+
+Now that you understand the solution, let's explore what you'll learn and how to apply it.
+
+**[Continue to Lesson 3: The Path Forward →](lesson-03-the-path-forward.md)**
+
+---
+
+[← Back to Lesson 1: The Problem](lesson-01-the-problem.md) | [Next: The Path Forward →](lesson-03-the-path-forward.md)

src/modules/wds/course/module-01-why-wds-matters/lesson-03-the-path-forward.md

@@ -0,0 +1,89 @@
+# Module 01: Why WDS Matters
+## Lesson 3: Your Transformation
+
+**From replaceable to indispensable**
+
+---
+
+## The Designer's Art: 5-Dimensional Thinking
+
+Godin says linchpins "connect disparate ideas." For product designers, this means something very specific: navigating five different dimensions of thinking at the same time. Most people can handle one or two dimensions. Irreplaceable designers navigate all five simultaneously, seeing connections that others miss.
+
+Think about designing that Dog Week calendar. You need to understand why the business exists (solving family conflict), what success looks like (kids actually walk the dog without nagging), what features serve that goal (week view, not daily), who the users are and what triggers their needs (Swedish families thinking in "Vecka"), and what's technically feasible (mobile app with family sharing). Each dimension informs the others. Miss one, and your design falls apart.
+
+This is what makes you indispensable as a designer. AI can help you think through each dimension individually. It can generate ideas, analyze data, suggest solutions. But it cannot navigate all five dimensions simultaneously while providing the emotional labor of genuinely caring about the outcome. That's uniquely human. That's what makes designers irreplaceable.
+
+**The 5 dimensions of design thinking:**
+
+1. **Business Existence (WHY)** - Understanding purpose and value creation
+2. **Business Goals (SUCCESS)** - Connecting to metrics and impact  
+3. **Product Strategy (HOW)** - Making hard choices about features
+4. **Target Groups (WHO)** - Empathy and understanding needs
+5. **Technical Viability (FEASIBLE)** - Bridging design and implementation
+
+**The irreplaceable designer's advantage:** Navigating all 5 simultaneously with emotional labor
+
+---
+
+## The Transformation
+
+### From Replaceable to Indispensable
+
+Godin has a warning that should make every designer pay attention: "If you're not indispensable, you're replaceable. And if you're replaceable, you're probably going to be replaced." In the AI era, this isn't a threat - it's just reality. The question is: which side of that line are you on?
+
+Right now, you might feel threatened by AI design tools. You might be uncertain about your value as a designer. You might be frustrated by the gap between your vision and what gets implemented. You might feel limited by development bottlenecks. If you're doing factory work - following briefs, creating mockups, hoping for the best - you're on the wrong side of that line.
+
+This course moves you to the other side. You'll become confident in your indispensable role because you'll understand exactly what makes you irreplaceable. You'll be clear on your unique gift - the user-centric creativity that AI cannot provide. You'll be empowered by AI partnership instead of threatened by it, because AI will amplify your design thinking instead of replacing it. You'll be unstoppable in implementation because your specifications will capture your creative intent perfectly.
+
+You'll become the designer who makes things happen. The one they can't do without. The linchpin designer.
+
+**Your transformation as a designer:**
+- **Before:** Threatened, uncertain, frustrated, limited, replaceable
+- **After:** Confident, clear, empowered, unstoppable, indispensable
+- **Result:** The designer who makes things happen
+
+---
+
+## Learn from Real-World Projects: Case Studies
+
+### Case Study: Dog Week
+
+Let's make this concrete with a real project. Dog Week is an app that helps Swedish families manage their dog's care through a shared family calendar. The problem it solves is universal - parents are tired of nagging kids about walking the dog, kids feel like they're being punished, and everyone ends up frustrated.
+
+An irreplaceable designer approaches this completely differently than a cog designer. Instead of jumping straight to mockups, they apply user-centric creativity first. They understand Swedish family dynamics - how "Vecka 40" (week 40) is how people think about time. They connect the business goal (family accountability) to human needs (fun, not punishment). They make judgment calls like using a week view instead of daily, because that matches how families actually think. Every decision is grounded in design empathy and understanding WHY.
+
+Compare the outcomes. The traditional approach - creating mockups, handing off to developers, going through revisions - took 26 weeks and resulted in something mediocre because the intent got lost in translation. The WDS approach - applying user-centric creativity upfront, capturing WHY in specifications, letting AI implement - took 5 weeks and resulted in something exceptional because the design intent was preserved.
+
+That's a 5x speed increase with better quality. But more importantly, the key designer's creative thinking was preserved and amplified instead of diluted and lost.
+
+**The comparison:**
+- **Traditional (cog designer):** 26 weeks → Mediocre result → Intent lost
+- **WDS (linchpin designer):** 5 weeks → Exceptional result → Intent preserved
+- **Key difference:** Designer's user-centric creativity captured and amplified
+
+---
+
+*More case studies will be added here as they become available.*
+
+---
+
+## Module Complete!
+
+You've completed Module 01: Why WDS Matters. You now understand:
+- ✅ The problem: Factory mindset vs linchpin mindset
+- ✅ The solution: Becoming a linchpin designer with WDS
+- ✅ The path forward: 5-dimensional thinking and transformation
+
+**Next steps:**
+- Review the practicalities if you haven't already
+- Start Module 02: Project Brief
+- Apply these concepts to your own work
+
+**[Continue to Module 02: Project Brief →](../module-02-project-brief/lesson-01-inspiration.md)**
+
+Or review the practicalities:
+**[Read Course Practicalities →](../00-practicalities.md)**
+
+---
+
+[← Back to Lesson 2](lesson-02-the-solution.md) | [Module Overview](module-01-overview.md) | [Next Module →](../module-02-project-brief/lesson-01-inspiration.md)

src/modules/wds/course/module-01-why-wds-matters/module-01-overview.md

@@ -0,0 +1,99 @@
+# Module 01: Why WDS Matters
+
+**Learn how to be indispensable in the AI era**
+
+---
+
+## Module Overview
+
+This foundational module transforms how you think about your role as a designer in the AI era. You'll learn why mastering WDS makes you irreplaceable and how to become a linchpin designer - the person who makes things happen.
+
+**Time:** ~30 minutes (3 lessons × 10 min each)
+**Prerequisites:** None - this is where you start!
+
+---
+
+## What You'll Learn
+
+- Why designers are more valuable than ever in the AI era
+- The difference between factory work and linchpin work
+- What AI can and cannot do in design
+- The 5 dimensions of design thinking
+- How to become the gatekeeper between business and user needs
+- The paradigm shift: design becomes specification
+
+---
+
+## Lessons
+
+### [Lesson 1: The Problem We're Solving](lesson-01-the-problem.md)
+**Time:** 10 minutes
+
+Understanding the factory mindset and the AI era:
+- Why learning WDS matters
+- What you'll gain from this course
+- Factory mindset vs linchpin mindset
+- AI threat for cogs
+- AI opportunity for linchpin designers
+
+### [Lesson 2: Becoming a Linchpin Designer](lesson-02-the-solution.md)
+**Time:** 10 minutes
+
+The solution: WDS methodology:
+- What makes a linchpin designer
+- The designer's gift: user-centric creativity
+- The designer as gatekeeper
+- From cog to linchpin designer
+- The paradigm shift: design becomes specification
+
+### [Lesson 3: Your Transformation](lesson-03-the-path-forward.md)
+**Time:** 10 minutes
+
+From replaceable to indispensable:
+- The 5 dimensions of design thinking
+- Your transformation as a designer
+- Real-world case studies (Dog Week)
+- Module completion and next steps
+
+---
+
+## Key Concepts
+
+**Linchpin Designer:**
+- Walks into chaos and creates order
+- Invents solutions nobody expected
+- Bridges business, psychology, and technology
+- Delivers results when there's no roadmap
+
+**User-Centric Creativity:**
+- Understanding WHY users feel frustrated
+- Connecting business goals to human needs
+- Creating experiences that feel right
+- Making judgment calls that serve people
+- Being the gatekeeper for quality
+
+**The Paradigm Shift:**
+- The design becomes the specification
+- The specification becomes the product
+- The code is just the printout
+
+---
+
+## Learning Outcomes
+
+By the end of this module, you will:
+- ✅ Understand why designers are irreplaceable in the AI era
+- ✅ Know the difference between cog work and linchpin work
+- ✅ Recognize what AI can and cannot do
+- ✅ See how specifications replace prompting
+- ✅ Be motivated to master the WDS methodology
+
+---
+
+## Start Learning
+
+**[Begin with Lesson 1: The Problem →](lesson-01-the-problem.md)**
+
+---
+
+[← Back to Course Start](../00-start-here.md)

src/modules/wds/data/design-system/component-boundaries.md

@@ -0,0 +1,304 @@
+# Component Boundaries
+
+**Purpose:** Guidelines for determining what constitutes a component.
+
+**Referenced by:** Design system router, assessment flow
+
+---
+
+## The Core Question
+
+**"Is this one component or multiple components?"**
+
+This is the most common design system challenge.
+
+---
+
+## Guiding Principles
+
+### Principle 1: Single Responsibility
+
+**A component should do one thing well.**
+
+✅ **Good:** Button component triggers actions
+❌ **Bad:** Button component that also handles forms, navigation, and modals
+
+### Principle 2: Reusability
+
+**A component should be reusable across contexts.**
+
+✅ **Good:** Input Field used in login, signup, profile forms
+❌ **Bad:** Login-Specific Input Field that only works on login page
+
+### Principle 3: Independence
+
+**A component should work independently.**
+
+✅ **Good:** Card component that can contain any content
+❌ **Bad:** Card component that requires specific parent container
+
+---
+
+## Common Boundary Questions
+
+### Q1: Icon in Button
+
+**Question:** Is the icon part of the button or separate?
+
+**Answer:** Depends on usage:
+
+**Part of Button (Variant):**
+```yaml
+Button Component:
+  variants:
+    - with-icon-left
+    - with-icon-right
+    - icon-only
+```
+**When:** Icon is always the same type (e.g., always arrow for navigation)
+
+**Separate Components:**
+```yaml
+Button Component: (text only)
+Icon Component: (standalone)
+Composition: Button + Icon
+```
+**When:** Icons vary widely, button can exist without icon
+
+**Recommendation:** Start with variant, split if complexity grows.
+
+---
+
+### Q2: Label with Input
+
+**Question:** Is the label part of the input or separate?
+
+**Answer:** Usually part of Input Field component:
+
+```yaml
+Input Field Component:
+  includes:
+    - Label
+    - Input element
+    - Helper text
+    - Error message
+```
+
+**Reason:** These always appear together in forms, form a semantic unit.
+
+---
+
+### Q3: Card with Button
+
+**Question:** Is the button part of the card?
+
+**Answer:** Usually separate:
+
+```yaml
+Card Component: (container)
+Button Component: (action)
+Composition: Card contains Button
+```
+
+**Reason:** Card is a container, button is an action. Different purposes.
+
+---
+
+### Q4: Navigation Bar Items
+
+**Question:** Is each nav item a component?
+
+**Answer:** Depends on complexity:
+
+**Simple (Single Component):**
+```yaml
+Navigation Bar Component:
+  includes: All nav items as configuration
+```
+
+**Complex (Composition):**
+```yaml
+Navigation Bar: (container)
+Navigation Item: (individual item)
+Composition: Nav Bar contains Nav Items
+```
+
+**Threshold:** If nav items have complex individual behavior, split them.
+
+---
+
+## Decision Framework
+
+### Step 1: Ask These Questions
+
+1. **Can it exist independently?**
+   - Yes → Probably separate component
+   - No → Probably part of parent
+
+2. **Does it have its own states/behaviors?**
+   - Yes → Probably separate component
+   - No → Probably part of parent
+
+3. **Is it reused in different contexts?**
+   - Yes → Definitely separate component
+   - No → Could be part of parent
+
+4. **Does it have a clear single purpose?**
+   - Yes → Good component candidate
+   - No → Might need to split further
+
+### Step 2: Consider Complexity
+
+**Low Complexity:** Keep together
+- Icon in button
+- Label with input
+- Simple list items
+
+**High Complexity:** Split apart
+- Complex nested structures
+- Independent behaviors
+- Different lifecycle
+
+### Step 3: Think About Maintenance
+
+**Together:**
+- ✅ Easier to keep consistent
+- ❌ Component becomes complex
+
+**Apart:**
+- ✅ Simpler components
+- ❌ More components to manage
+
+---
+
+## Composition Patterns
+
+### Pattern 1: Container + Content
+
+**Container provides structure, content is flexible.**
+
+```yaml
+Card Component: (container)
+  - Can contain: text, images, buttons, etc.
+  - Provides: padding, border, shadow
+```
+
+### Pattern 2: Compound Component
+
+**Multiple parts that work together.**
+
+```yaml
+Accordion Component:
+  - Accordion Container
+  - Accordion Item
+  - Accordion Header
+  - Accordion Content
+```
+
+### Pattern 3: Atomic Component
+
+**Single, indivisible unit.**
+
+```yaml
+Button Component:
+  - Cannot be broken down further
+  - Self-contained
+```
+
+---
+
+## Red Flags
+
+### Too Many Variants
+
+**Warning:** Component has 10+ variants
+
+**Problem:** Probably multiple components disguised as variants
+
+**Solution:** Split into separate components based on purpose
+
+### Conditional Complexity
+
+**Warning:** Component has many "if this, then that" rules
+
+**Problem:** Component doing too many things
+
+**Solution:** Split into simpler, focused components
+
+### Context-Specific Behavior
+
+**Warning:** Component behaves differently in different contexts
+
+**Problem:** Not truly reusable
+
+**Solution:** Create context-specific components or use composition
+
+---
+
+## Examples
+
+### Example 1: Button
+
+**One Component:**
+```yaml
+Button:
+  variants: primary, secondary, ghost
+  states: default, hover, active, disabled, loading
+```
+
+**Reason:** All variants serve same purpose (trigger action), share behavior
+
+### Example 2: Input Types
+
+**Multiple Components:**
+```yaml
+Text Input: (text entry)
+Select Dropdown: (choose from list)
+Checkbox: (toggle option)
+Radio: (choose one)
+```
+
+**Reason:** Different purposes, different behaviors, different HTML elements
+
+### Example 3: Modal
+
+**Compound Component:**
+```yaml
+Modal: (overlay + container)
+Modal Header: (title + close button)
+Modal Body: (content area)
+Modal Footer: (actions)
+```
+
+**Reason:** Complex structure, but parts always used together
+
+---
+
+## When in Doubt
+
+**Start simple:**
+1. Create as single component
+2. Add variants as needed
+3. Split when complexity becomes painful
+
+**It's easier to split later than merge later.**
+
+---
+
+## Company Customization
+
+Companies can define their own boundary rules:
+
+```markdown
+# Acme Corp Component Boundaries
+
+**Rule 1:** Icons are always separate components
+**Rule 2:** Form fields include labels (never separate)
+**Rule 3:** Cards never include actions (composition only)
+```
+
+**Consistency within a company matters more than universal rules.**
+
+---
+
+**Use this guide when the design system router detects similarity and you need to decide: same component, variant, or new component?**

src/modules/wds/data/design-system/figma-component-structure.md

@@ -0,0 +1,645 @@
+# Figma Component Structure for WDS
+
+**Purpose:** Guidelines for organizing and structuring components in Figma for seamless WDS integration.
+
+**Referenced by:** Mode B (Custom Design System) workflows
+
+---
+
+## Core Principle
+
+**Figma components should mirror WDS component structure** to enable seamless synchronization and specification generation.
+
+```
+Figma Component → WDS Component Specification → React Implementation
+```
+
+---
+
+## Component Organization in Figma
+
+### File Structure
+
+**Recommended Figma file organization:**
+
+```
+Design System File (Figma)
+├── 📄 Cover (project info)
+├── 🎨 Foundation
+│   ├── Colors
+│   ├── Typography
+│   ├── Spacing
+│   └── Effects
+├── ⚛️ Components
+│   ├── Buttons
+│   ├── Inputs
+│   ├── Cards
+│   └── [other component types]
+└── 📱 Examples
+    └── Component usage examples
+```
+
+**Benefits:**
+- Clear organization
+- Easy navigation
+- Matches WDS structure
+- Facilitates MCP integration
+
+---
+
+## Component Naming Convention
+
+### Format
+
+**Pattern:** `[ComponentType]/[ComponentName]`
+
+**Examples:**
+```
+Button/Primary
+Button/Secondary
+Button/Ghost
+Input/Text
+Input/Email
+Card/Profile
+Card/Content
+```
+
+**Rules:**
+- Use forward slash for hierarchy
+- Title case for names
+- Match WDS component names
+- Consistent across all components
+
+---
+
+## Component Properties
+
+### Required Properties
+
+**Every component must have:**
+
+1. **Description**
+   - Component purpose
+   - When to use
+   - WDS component ID (e.g., "btn-001")
+
+2. **Variants**
+   - Organized by property
+   - Clear naming
+   - All states included
+
+3. **Auto Layout**
+   - Proper spacing
+   - Responsive behavior
+   - Padding/gap values
+
+**Example Description:**
+```
+Button Primary [btn-001]
+
+Primary action button for main user actions.
+Use for: Submit forms, confirm actions, proceed to next step.
+
+WDS Component: Button.primary [btn-001]
+```
+
+---
+
+## Variant Structure
+
+### Organizing Variants
+
+**Use Figma's variant properties:**
+
+**Property 1: Type** (variant)
+- Primary
+- Secondary
+- Ghost
+- Outline
+
+**Property 2: Size**
+- Small
+- Medium
+- Large
+
+**Property 3: State**
+- Default
+- Hover
+- Active
+- Disabled
+- Loading
+
+**Property 4: Icon** (optional)
+- None
+- Left
+- Right
+- Only
+
+**Result:** Figma generates all combinations automatically
+
+---
+
+### Variant Naming
+
+**Format:** `Property=Value`
+
+**Examples:**
+```
+Type=Primary, Size=Medium, State=Default
+Type=Primary, Size=Medium, State=Hover
+Type=Secondary, Size=Large, State=Disabled
+```
+
+**Benefits:**
+- Clear property structure
+- Easy to find specific variants
+- MCP can parse programmatically
+- Matches WDS variant system
+
+---
+
+## State Documentation
+
+### Required States
+
+**Interactive Components (Buttons, Links):**
+- Default
+- Hover
+- Active (pressed)
+- Disabled
+- Focus (optional)
+- Loading (optional)
+
+**Form Components (Inputs, Selects):**
+- Default (empty)
+- Focus (active)
+- Filled (has content)
+- Disabled
+- Error
+- Success (optional)
+
+**Feedback Components (Alerts, Toasts):**
+- Default
+- Success
+- Error
+- Warning
+- Info
+
+---
+
+### State Visual Indicators
+
+**Document state changes:**
+
+**Hover:**
+- Background color change
+- Border change
+- Shadow change
+- Scale change
+- Cursor change
+
+**Active:**
+- Background color (darker)
+- Scale (slightly smaller)
+- Shadow (reduced)
+
+**Disabled:**
+- Opacity (0.5-0.6)
+- Cursor (not-allowed)
+- Grayscale (optional)
+
+**Loading:**
+- Spinner/progress indicator
+- Disabled interaction
+- Loading text
+
+---
+
+## Design Tokens in Figma
+
+### Using Figma Variables
+
+**Map Figma variables to WDS tokens:**
+
+**Colors:**
+```
+Figma Variable → WDS Token
+primary/500 → color-primary-500
+gray/900 → color-gray-900
+success/600 → color-success-600
+```
+
+**Typography:**
+```
+Figma Style → WDS Token
+Text/Display → text-display
+Text/Heading-1 → text-heading-1
+Text/Body → text-body
+```
+
+**Spacing:**
+```
+Figma Variable → WDS Token
+spacing/2 → spacing-2
+spacing/4 → spacing-4
+spacing/8 → spacing-8
+```
+
+**Effects:**
+```
+Figma Effect → WDS Token
+shadow/sm → shadow-sm
+shadow/md → shadow-md
+radius/md → radius-md
+```
+
+---
+
+## Component Documentation
+
+### Component Description Template
+
+```
+[Component Name] [component-id]
+
+**Purpose:** [Brief description]
+
+**When to use:**
+- [Use case 1]
+- [Use case 2]
+
+**When not to use:**
+- [Anti-pattern 1]
+- [Anti-pattern 2]
+
+**WDS Component:** [ComponentType].[variant] [component-id]
+
+**Variants:** [List of variants]
+**States:** [List of states]
+**Size:** [Available sizes]
+
+**Accessibility:**
+- [ARIA attributes]
+- [Keyboard support]
+- [Screen reader behavior]
+```
+
+**Example:**
+```
+Button Primary [btn-001]
+
+**Purpose:** Trigger primary actions in the interface
+
+**When to use:**
+- Submit forms
+- Confirm important actions
+- Proceed to next step
+- Primary call-to-action
+
+**When not to use:**
+- Secondary actions (use Button Secondary)
+- Destructive actions (use Button Destructive)
+- Navigation (use Link component)
+
+**WDS Component:** Button.primary [btn-001]
+
+**Variants:** primary, secondary, ghost, outline
+**States:** default, hover, active, disabled, loading
+**Size:** small, medium, large
+
+**Accessibility:**
+- role="button"
+- aria-disabled when disabled
+- aria-busy when loading
+- Keyboard: Enter/Space to activate
+```
+
+---
+
+## Auto Layout Best Practices
+
+### Spacing
+
+**Use consistent spacing values:**
+- Padding: 8px, 12px, 16px, 24px
+- Gap: 4px, 8px, 12px, 16px
+- Match WDS spacing tokens
+
+**Auto Layout Settings:**
+- Horizontal/Vertical alignment
+- Padding (all sides or specific)
+- Gap between items
+- Resizing behavior
+
+---
+
+### Resizing Behavior
+
+**Set appropriate constraints:**
+
+**Buttons:**
+- Hug contents (width)
+- Fixed height
+- Min width for touch targets (44px)
+
+**Inputs:**
+- Fill container (width)
+- Fixed height (40-48px)
+- Responsive to content
+
+**Cards:**
+- Fill container or fixed width
+- Hug contents (height)
+- Responsive to content
+
+---
+
+## Component Instances
+
+### Creating Instances
+
+**Best practices:**
+- Always use component instances (not detached)
+- Override only necessary properties
+- Maintain connection to main component
+- Document overrides if needed
+
+**Overridable Properties:**
+- Text content
+- Icons
+- Colors (if using variables)
+- Spacing (if needed)
+
+**Non-Overridable:**
+- Structure
+- Layout
+- Core styling
+- States
+
+---
+
+## Figma to WDS Mapping
+
+### Component ID System
+
+**Add WDS component ID to Figma:**
+
+**In component description:**
+```
+Button Primary [btn-001]
+```
+
+**In component name:**
+```
+Button/Primary [btn-001]
+```
+
+**Benefits:**
+- Easy to find components
+- Clear WDS mapping
+- MCP can extract ID
+- Bidirectional sync
+
+---
+
+### Node ID Tracking
+
+**Figma generates unique node IDs:**
+
+**Format:**
+```
+figma://file/[file-id]/node/[node-id]
+```
+
+**How to get node ID:**
+1. Select component in Figma
+2. Right-click → "Copy link to selection"
+3. Extract node ID from URL
+
+**Store in WDS:**
+```yaml
+# D-Design-System/figma-mappings.md
+Button [btn-001] → figma://file/abc123/node/456:789
+Input [inp-001] → figma://file/abc123/node/456:790
+```
+
+---
+
+## Sync Workflow
+
+### Figma → WDS
+
+**When component is created/updated in Figma:**
+
+1. Designer creates/updates component
+2. Designer adds WDS component ID to description
+3. MCP reads component via Figma API
+4. MCP extracts:
+   - Component structure
+   - Variants
+   - States
+   - Properties
+   - Design tokens used
+5. MCP generates/updates WDS specification
+6. Designer reviews and confirms
+
+---
+
+### WDS → Figma
+
+**When specification is updated in WDS:**
+
+1. Specification updated in WDS
+2. Designer notified of changes
+3. Designer updates Figma component
+4. Designer confirms sync
+5. Node ID verified/updated
+
+**Note:** This is semi-automated. Full automation requires Figma API write access.
+
+---
+
+## Quality Checklist
+
+### Component Creation
+
+- [ ] Component name follows convention
+- [ ] WDS component ID in description
+- [ ] All variants defined
+- [ ] All states documented
+- [ ] Auto layout properly configured
+- [ ] Design tokens used (not hardcoded values)
+- [ ] Accessibility notes included
+- [ ] Usage guidelines documented
+
+### Variant Structure
+
+- [ ] Variants organized by properties
+- [ ] Property names clear and consistent
+- [ ] All combinations make sense
+- [ ] No redundant variants
+- [ ] States properly differentiated
+
+### Documentation
+
+- [ ] Purpose clearly stated
+- [ ] When to use documented
+- [ ] When not to use documented
+- [ ] Accessibility requirements noted
+- [ ] Examples provided
+
+---
+
+## Common Mistakes to Avoid
+
+### ❌ Mistake 1: Hardcoded Values
+
+**Wrong:**
+```
+Background: #2563eb (hardcoded hex)
+Padding: 16px (hardcoded value)
+```
+
+**Right:**
+```
+Background: primary/600 (variable)
+Padding: spacing/4 (variable)
+```
+
+### ❌ Mistake 2: Detached Instances
+
+**Wrong:**
+- Detaching component instances
+- Losing connection to main component
+- Manual updates required
+
+**Right:**
+- Always use instances
+- Override only necessary properties
+- Maintain component connection
+
+### ❌ Mistake 3: Inconsistent Naming
+
+**Wrong:**
+```
+btn-primary
+ButtonSecondary
+button_ghost
+```
+
+**Right:**
+```
+Button/Primary
+Button/Secondary
+Button/Ghost
+```
+
+### ❌ Mistake 4: Missing States
+
+**Wrong:**
+- Only default state
+- No hover/active states
+- No disabled state
+
+**Right:**
+- All required states
+- Visual differentiation
+- State transitions documented
+
+### ❌ Mistake 5: No WDS Component ID
+
+**Wrong:**
+```
+Button Primary
+(no component ID)
+```
+
+**Right:**
+```
+Button Primary [btn-001]
+(clear WDS mapping)
+```
+
+---
+
+## Examples
+
+### Button Component in Figma
+
+**Component Name:** `Button/Primary [btn-001]`
+
+**Description:**
+```
+Button Primary [btn-001]
+
+Primary action button for main user actions.
+
+WDS Component: Button.primary [btn-001]
+Variants: primary, secondary, ghost, outline
+States: default, hover, active, disabled, loading
+Sizes: small, medium, large
+```
+
+**Variants:**
+```
+Type=Primary, Size=Medium, State=Default
+Type=Primary, Size=Medium, State=Hover
+Type=Primary, Size=Medium, State=Active
+Type=Primary, Size=Medium, State=Disabled
+Type=Primary, Size=Large, State=Default
+[... all combinations]
+```
+
+**Properties:**
+- Auto Layout: Horizontal
+- Padding: 16px (horizontal), 12px (vertical)
+- Gap: 8px (if icon)
+- Border Radius: 8px
+- Background: primary/600 (variable)
+
+---
+
+### Input Component in Figma
+
+**Component Name:** `Input/Text [inp-001]`
+
+**Description:**
+```
+Input Text [inp-001]
+
+Text input field for user data entry.
+
+WDS Component: Input.text [inp-001]
+States: default, focus, filled, disabled, error, success
+```
+
+**Variants:**
+```
+State=Default
+State=Focus
+State=Filled
+State=Disabled
+State=Error
+State=Success
+```
+
+**Properties:**
+- Auto Layout: Horizontal
+- Padding: 12px
+- Height: 44px (fixed)
+- Border: 1px solid gray/300
+- Border Radius: 8px
+- Background: white
+
+---
+
+## Further Reading
+
+- **Figma MCP Integration:** `figma-mcp-integration.md`
+- **Designer Guide:** `figma-designer-guide.md`
+- **Token Architecture:** `token-architecture.md`
+- **Component Boundaries:** `component-boundaries.md`
+
+---
+
+**This structure enables seamless Figma ↔ WDS integration and maintains design system consistency across tools.**

src/modules/wds/data/design-system/naming-conventions.md

@@ -0,0 +1,181 @@
+# Design System Naming Conventions
+
+**Purpose:** Consistent naming across design system components and tokens.
+
+**Referenced by:** Component-type instructions, design system operations
+
+---
+
+## Component IDs
+
+**Format:** `[type-prefix]-[number]`
+
+**Prefixes:**
+- btn = Button
+- inp = Input Field
+- chk = Checkbox
+- rad = Radio
+- tgl = Toggle
+- drp = Dropdown
+- mdl = Modal
+- crd = Card
+- alt = Alert
+- bdg = Badge
+- tab = Tab
+- acc = Accordion
+
+**Examples:**
+- `btn-001` = First button component
+- `inp-002` = Second input field component
+- `mdl-001` = First modal component
+
+**Rules:**
+- Always lowercase
+- Always hyphenated
+- Always zero-padded (001, not 1)
+- Sequential within type
+
+---
+
+## Component Names
+
+**Format:** `[Type] [Descriptor]` or just `[Type]`
+
+**Examples:**
+- `Button` (generic)
+- `Navigation Button` (specific)
+- `Primary Button` (variant-focused)
+- `Icon Button` (visual-focused)
+
+**Rules:**
+- Title case
+- Descriptive but concise
+- Avoid redundancy (not "Button Button")
+
+---
+
+## Variant Names
+
+**Format:** Lowercase, hyphenated
+
+**Purpose-Based:**
+- `primary` - Main action
+- `secondary` - Secondary action
+- `destructive` - Delete/remove
+- `success` - Positive confirmation
+- `warning` - Caution
+- `navigation` - Navigation action
+
+**Visual-Based:**
+- `outlined` - Border, no fill
+- `ghost` - Transparent background
+- `solid` - Filled background
+
+**Size-Based:**
+- `small` - Compact
+- `medium` - Default
+- `large` - Prominent
+
+**Rules:**
+- Lowercase
+- Hyphenated for multi-word
+- Semantic over visual when possible
+
+---
+
+## State Names
+
+**Standard States:**
+- `default` - Normal state
+- `hover` - Mouse over
+- `active` - Being clicked/pressed
+- `focus` - Keyboard focus
+- `disabled` - Cannot interact
+- `loading` - Processing
+- `error` - Error state
+- `success` - Success state
+- `warning` - Warning state
+
+**Rules:**
+- Lowercase
+- Single word preferred
+- Use standard names when possible
+
+---
+
+## Design Token Names
+
+**Format:** `--{category}-{property}-{variant}`
+
+**Color Tokens:**
+```
+--color-primary-500
+--color-gray-900
+--color-success-600
+--color-error-500
+```
+
+**Typography Tokens:**
+```
+--text-xs
+--text-base
+--text-4xl
+--font-normal
+--font-bold
+```
+
+**Spacing Tokens:**
+```
+--spacing-1
+--spacing-4
+--spacing-8
+```
+
+**Component Tokens:**
+```
+--button-padding-x
+--input-border-color
+--card-shadow
+```
+
+**Rules:**
+- Kebab-case
+- Hierarchical (general → specific)
+- Semantic names preferred
+
+---
+
+## File Names
+
+**Component Files:**
+```
+button.md
+navigation-button.md
+input-field.md
+```
+
+**Rules:**
+- Lowercase
+- Hyphenated
+- Match component name (simplified)
+
+---
+
+## Folder Names
+
+```
+components/
+design-tokens/
+operations/
+assessment/
+templates/
+```
+
+**Rules:**
+- Lowercase
+- Hyphenated
+- Plural for collections
+
+---
+
+**Consistency in naming makes the design system easier to navigate and maintain.**

src/modules/wds/data/design-system/state-management.md

@@ -0,0 +1,88 @@
+# Component State Management
+
+**Purpose:** Guidelines for defining and managing component states.
+
+**Referenced by:** Component-type instructions (Button, Input, etc.)
+
+---
+
+## Standard States
+
+### Interactive Components (Buttons, Links)
+
+**Required:**
+- `default` - Normal, ready for interaction
+- `hover` - Mouse over component
+- `active` - Being clicked/pressed
+- `disabled` - Cannot interact
+
+**Optional:**
+- `loading` - Processing action
+- `focus` - Keyboard focus
+
+### Form Components (Inputs, Selects)
+
+**Required:**
+- `default` - Empty, ready for input
+- `focus` - Active input
+- `filled` - Has content
+- `disabled` - Cannot edit
+
+**Optional:**
+- `error` - Validation failed
+- `success` - Validation passed
+- `loading` - Fetching data
+
+### Feedback Components (Alerts, Toasts)
+
+**Required:**
+- `default` - Neutral information
+- `success` - Positive feedback
+- `error` - Error feedback
+- `warning` - Caution feedback
+
+---
+
+## State Naming
+
+**Use standard names:**
+- ✅ `hover` not `mouseover`
+- ✅ `disabled` not `inactive`
+- ✅ `loading` not `processing`
+
+**Be consistent across components.**
+
+---
+
+## State Transitions
+
+**Define how states change:**
+
+```yaml
+Button States:
+  default → hover (mouse enters)
+  hover → active (mouse down)
+  active → hover (mouse up)
+  hover → default (mouse leaves)
+  any → disabled (programmatically)
+  any → loading (action triggered)
+```
+
+---
+
+## Visual Indicators
+
+**Each state should be visually distinct:**
+
+```yaml
+Button:
+  default: blue background
+  hover: darker blue + scale 1.02
+  active: darkest blue + scale 0.98
+  disabled: gray + opacity 0.6
+  loading: disabled + spinner
+```
+
+---
+
+**Reference this when specifying component states.**

src/modules/wds/data/design-system/token-architecture.md

@@ -0,0 +1,445 @@
+# Design Token Architecture
+
+**Purpose:** Core principles for separating semantic structure from visual style.
+
+**Referenced by:** All component-type instructions
+
+---
+
+## Core Principle
+
+**Separate semantic structure from visual style.**
+
+```
+HTML/Structure = Meaning (what it is)
+Design Tokens = Appearance (how it looks)
+
+They should be independent!
+```
+
+---
+
+## The Problem
+
+**Bad Practice:**
+```html
+<h2 class="text-4xl font-bold text-blue-600">
+  Heading
+</h2>
+```
+
+**Issues:**
+- Visual styling mixed with semantic HTML
+- Can't change h2 appearance without changing all h2s
+- h2 means "second-level heading" but looks like "display large"
+- Breaks separation of concerns
+
+---
+
+## The Solution
+
+**Good Practice:**
+
+**HTML (Semantic):**
+```html
+<h2 class="heading-section">
+  Heading
+</h2>
+```
+
+**Design Tokens (Visual):**
+```css
+.heading-section {
+  font-size: var(--text-4xl);
+  font-weight: var(--font-bold);
+  color: var(--color-primary-600);
+}
+```
+
+**Benefits:**
+- Semantic HTML stays semantic
+- Visual style is centralized
+- Can change appearance without touching HTML
+- Clear separation of concerns
+
+---
+
+## Token Hierarchy
+
+### Level 1: Raw Values
+```css
+--spacing-4: 1rem;
+--color-blue-600: #2563eb;
+--font-size-4xl: 2.25rem;
+```
+
+### Level 2: Semantic Tokens
+```css
+--text-heading-large: var(--font-size-4xl);
+--color-primary: var(--color-blue-600);
+--spacing-section: var(--spacing-4);
+```
+
+### Level 3: Component Tokens
+```css
+--button-padding-x: var(--spacing-section);
+--button-color-primary: var(--color-primary);
+--heading-size-section: var(--text-heading-large);
+```
+
+**Use Level 2 or 3 in components, never Level 1 directly.**
+
+---
+
+## Application to WDS
+
+### In Page Specifications
+
+**Specify semantic structure:**
+```yaml
+Page Structure:
+  - Section Heading (h2)
+  - Body text (p)
+  - Primary button (button)
+```
+
+**NOT visual styling:**
+```yaml
+# ❌ Don't do this
+Page Structure:
+  - Large blue bold text
+  - 16px gray text
+  - Blue rounded button
+```
+
+### In Design System
+
+**Specify visual styling:**
+```yaml
+Section Heading:
+  html_element: h2
+  design_token: heading-section
+  
+Design Token Definition:
+  heading-section:
+    font-size: text-4xl
+    font-weight: bold
+    color: primary-600
+```
+
+---
+
+## Component-Type Instructions
+
+### Text Heading Example
+
+**When specifying a heading:**
+
+1. **Identify semantic level** (h1-h6)
+   - h1 = Page title
+   - h2 = Section heading
+   - h3 = Subsection heading
+   - etc.
+
+2. **Map to design token**
+   - h1 → display-large
+   - h2 → heading-section
+   - h3 → heading-subsection
+
+3. **Store separately**
+   - Page spec: `<h2>` (semantic)
+   - Design system: `heading-section` token (visual)
+
+**Example Output:**
+
+**Page Spec:**
+```yaml
+Hero Section:
+  heading:
+    element: h2
+    token: heading-section
+    content: "Welcome to Our Product"
+```
+
+**Design System:**
+```yaml
+Tokens:
+  heading-section:
+    font-size: 2.25rem
+    font-weight: 700
+    line-height: 1.2
+    color: gray-900
+```
+
+---
+
+## Button Example
+
+**When specifying a button:**
+
+1. **Identify semantic element**
+   - `<button>` for actions
+   - `<a>` for navigation (even if styled as button)
+
+2. **Map to component**
+   - Action → Button component
+   - Navigation → Link component (button variant)
+
+3. **Store separately**
+   - Page spec: `<button>` + purpose
+   - Design system: Button component styling
+
+**Example Output:**
+
+**Page Spec:**
+```yaml
+Login Form:
+  submit_button:
+    element: button
+    type: submit
+    component: Button.primary
+    label: "Log in"
+```
+
+**Design System:**
+```yaml
+Button Component:
+  variants:
+    primary:
+      background: primary-600
+      color: white
+      padding: spacing-2 spacing-4
+      border-radius: radius-md
+```
+
+---
+
+## Input Field Example
+
+**When specifying an input:**
+
+1. **Identify semantic type**
+   - `<input type="text">` for text
+   - `<input type="email">` for email
+   - `<input type="password">` for password
+
+2. **Map to component**
+   - Text input → Input Field component
+   - Email input → Input Field.email variant
+
+3. **Store separately**
+   - Page spec: Input type + validation + labels
+   - Design system: Input Field styling
+
+**Example Output:**
+
+**Page Spec:**
+```yaml
+Login Form:
+  email_field:
+    element: input
+    type: email
+    component: InputField.email
+    label: "Email address"
+    placeholder: "you@example.com"
+    required: true
+    validation: email_format
+```
+
+**Design System:**
+```yaml
+Input Field Component:
+  base_styling:
+    height: 2.5rem
+    padding: spacing-2 spacing-3
+    border: 1px solid gray-300
+    border-radius: radius-md
+    font-size: text-base
+  
+  variants:
+    email:
+      icon: envelope
+      autocomplete: email
+```
+
+---
+
+## Why This Matters
+
+### For Designers
+
+✅ **Consistency:** All h2s can look the same without manual styling
+✅ **Flexibility:** Change all section headings by updating one token
+✅ **Clarity:** Semantic meaning preserved
+✅ **Scalability:** Easy to maintain as design system grows
+
+### For Developers
+
+✅ **Semantic HTML:** Proper HTML structure
+✅ **Accessibility:** Screen readers understand structure
+✅ **Maintainability:** Styling centralized
+✅ **Performance:** Reusable styles
+
+### For Design Systems
+
+✅ **Single Source of Truth:** Tokens define appearance
+✅ **Easy Updates:** Change tokens, not components
+✅ **Consistency:** Automatic consistency across pages
+✅ **Documentation:** Clear token → component mapping
+
+---
+
+## Common Mistakes
+
+### Mistake 1: Mixing Structure and Style
+
+**❌ Bad:**
+```yaml
+Page:
+  - "Large blue heading" (h2)
+```
+
+**✅ Good:**
+```yaml
+Page:
+  - Section heading (h2 → heading-section token)
+```
+
+### Mistake 2: Hardcoding Visual Values
+
+**❌ Bad:**
+```yaml
+Button:
+  background: #2563eb
+  padding: 16px
+```
+
+**✅ Good:**
+```yaml
+Button:
+  background: primary-600
+  padding: spacing-4
+```
+
+### Mistake 3: Using Visual Names for Semantic Elements
+
+**❌ Bad:**
+```yaml
+<h2 class="big-blue-text">
+```
+
+**✅ Good:**
+```yaml
+<h2 class="section-heading">
+```
+
+---
+
+## Token Naming Conventions
+
+### Colors
+```
+--color-{category}-{shade}
+--color-primary-600
+--color-gray-900
+--color-success-500
+```
+
+### Typography
+```
+--text-{size}
+--text-base
+--text-lg
+--text-4xl
+```
+
+### Spacing
+```
+--spacing-{scale}
+--spacing-2
+--spacing-4
+--spacing-8
+```
+
+### Component-Specific
+```
+--{component}-{property}-{variant}
+--button-padding-primary
+--input-border-error
+--card-shadow-elevated
+```
+
+---
+
+## Implementation in WDS
+
+### Phase 4: Page Specification
+
+**Agent specifies:**
+- Semantic HTML elements
+- Component references
+- Content and labels
+
+**Agent does NOT specify:**
+- Exact colors
+- Exact sizes
+- Exact spacing
+
+### Phase 5: Design System
+
+**Agent specifies:**
+- Design tokens
+- Component styling
+- Visual properties
+
+**Agent does NOT specify:**
+- Page-specific content
+- Semantic structure
+
+### Integration
+
+**Page spec references design system:**
+```yaml
+Hero:
+  heading:
+    element: h2
+    token: heading-hero  ← Reference to design system
+    content: "Welcome"
+```
+
+**Design system defines token:**
+```yaml
+Tokens:
+  heading-hero:
+    font-size: 3rem
+    font-weight: 800
+    color: gray-900
+```
+
+---
+
+## Company Customization
+
+**Companies can fork WDS and customize tokens:**
+
+```
+Company Fork:
+├── data/design-system/
+│   ├── token-architecture.md (this file - keep principles)
+│   ├── company-tokens.md (company-specific token values)
+│   └── token-mappings.md (h2 → company-heading-large)
+```
+
+**Result:** Every project uses company's design tokens automatically.
+
+---
+
+## Further Reading
+
+- **Naming Conventions:** `naming-conventions.md`
+- **Component Boundaries:** `component-boundaries.md`
+- **State Management:** `state-management.md`
+
+---
+
+**This is a core principle. Reference this document from all component-type instructions.**

src/modules/wds/data/design-system/validation-patterns.md

@@ -0,0 +1,67 @@
+# Form Validation Patterns
+
+**Purpose:** Standard patterns for form validation and error handling.
+
+**Referenced by:** Input Field, Form component-type instructions
+
+---
+
+## Validation Types
+
+### Client-Side Validation
+
+**Required Fields:**
+```yaml
+validation:
+  required: true
+  message: "This field is required"
+```
+
+**Format Validation:**
+```yaml
+validation:
+  type: email
+  pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+  message: "Please enter a valid email address"
+```
+
+**Length Validation:**
+```yaml
+validation:
+  minLength: 8
+  maxLength: 100
+  message: "Password must be 8-100 characters"
+```
+
+---
+
+## Error States
+
+**Visual Indicators:**
+- Red border
+- Error icon
+- Error message below field
+- Error color for label
+
+**Timing:**
+- Show on blur (after user leaves field)
+- Show on submit attempt
+- Clear on valid input
+
+---
+
+## Success States
+
+**Visual Indicators:**
+- Green border (optional)
+- Success icon (optional)
+- Success message (optional)
+
+**When to Show:**
+- After successful validation
+- For critical fields (password strength)
+- For async validation (username availability)
+
+---
+
+**Reference this when specifying form components.**

src/modules/wds/getting-started/installation.md

@@ -0,0 +1,60 @@
+# Installation
+
+**Get WDS up and running in 5 minutes**
+
+---
+
+## Prerequisites
+
+- Node.js 18+ installed
+- Git installed
+- Code editor (VS Code recommended)
+
+---
+
+## Quick Install
+
+```bash
+# Clone the repository
+git clone https://github.com/whiteport-collective/whiteport-design-studio.git
+
+# Navigate to the directory
+cd whiteport-design-studio
+
+# Install dependencies
+npm install
+
+# Start WDS
+npm start
+```
+
+---
+
+## Verify Installation
+
+You should see:
+```
+✅ WDS is running
+🎨 Ready to design
+```
+
+---
+
+## Next Steps
+
+- [Quick Start Guide](quick-start.md) - Your first 5 minutes
+- [Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md) - Learn the concepts deeply
+
+---
+
+## Troubleshooting
+
+**Issue:** Node version error
+**Solution:** Update to Node.js 18 or higher
+
+**Issue:** Permission denied
+**Solution:** Run with appropriate permissions or use `sudo` (Mac/Linux)
+
+---
+
+[← Back to WDS](../WDS-WORKFLOWS-GUIDE.md)

src/modules/wds/getting-started/quick-start.md

@@ -0,0 +1,121 @@
+# Quick Start
+
+**Your first 5 minutes with WDS**
+
+---
+
+## What You'll Do
+
+1. Create a Trigger Map
+2. Initialize a scenario
+3. Sketch your first page
+4. Generate specifications
+
+**Time: 5 minutes**
+
+---
+
+## Step 1: Start WDS
+
+```bash
+npm start
+```
+
+Agent: "Welcome to Whiteport Design Studio! Ready to start?"
+
+---
+
+## Step 2: Create Trigger Map
+
+```
+You: "Let's create a Trigger Map for a dog walking app"
+
+Agent: "Great! Who is your primary target group?"
+You: "Parents who struggle with family dog care coordination"
+
+Agent: "What triggers their need?"
+You: "Family conflict over who walks the dog"
+
+Agent: "What outcome do they want?"
+You: "Accountability without nagging"
+```
+
+**✅ Trigger Map created**
+
+---
+
+## Step 3: Initialize Scenario
+
+```
+Agent: "What feature delivers the most value to parents?"
+You: "Family dog walk calendar"
+
+Agent: "Where do they first encounter this?"
+You: "Google search - frustrated with conflict"
+
+Agent: "What's the shortest path to mutual success?"
+You: "Landing → Sign up → Family setup → Calendar → First walk"
+```
+
+**✅ Scenario initialized**
+
+---
+
+## Step 4: Sketch First Page
+
+```
+Agent: "Let's start with the Landing page. Upload your sketch."
+You: [Upload sketch]
+
+Agent: "I see: Header, Hero section, How it works, Sign up CTA.
+        Should I analyze these sections?"
+You: "Yes"
+```
+
+**✅ Sketch analyzed**
+
+---
+
+## Step 5: Generate Specifications
+
+```
+Agent: "Based on your Trigger Map:
+        - Target: Parents (tired of nagging)
+        - Trigger: Family conflict
+        
+        For the Hero section, I suggest:
+        Headline: 'Stop Nagging. Start Harmony.'
+        
+        Does this address their frustration?"
+        
+You: "Perfect!"
+```
+
+**✅ Specifications generated**
+
+---
+
+## What Just Happened?
+
+You created **why-based specifications** in 5 minutes:
+- Connected to user psychology (Trigger Map)
+- Grounded in real context (Scenario Init)
+- Generated with AI assistance (Agent collaboration)
+- Preserved your thinking (Why-based specs)
+
+---
+
+## Next Steps
+
+### Learn the Concepts
+[Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md) - Deep dive into WDS philosophy
+
+### Start Your Project
+[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md) - Full workflow documentation
+
+### Get Help
+[Community](https://discord.gg/whiteport) - Join the WDS community
+
+---
+
+[← Back to Getting Started](installation.md)

src/modules/wds/getting-started/where-to-go-next.md

@@ -0,0 +1,120 @@
+# Where to Go Next
+
+**You've installed WDS and completed the quick start. Now what?**
+
+---
+
+## Choose Your Path
+
+### 🎓 Learn the Concepts (Recommended First)
+
+**[Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)**
+
+Deep dive into:
+- Why designers are irreplaceable in the AI era
+- What WDS is and how it works
+- The BMad Method philosophy
+- Why-based specifications
+- Complete walkthroughs
+
+**Best for:** Understanding the "why" behind WDS
+
+**Time:** 1-2 hours (video series)
+
+---
+
+### 🚀 Start Your Project
+
+**[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)**
+
+Step-by-step workflows for:
+
+**Phase 1: Trigger Mapping**  
+Understand WHO your users are, WHAT triggers their needs, and WHY your business exists. Create a Trigger Map that identifies target groups, their pain points, desired outcomes, and prioritized features. This becomes the foundation for all design decisions.  
+→ [Watch Tutorial: Trigger Map Walkthrough](../tutorial/04-trigger-map-walkthrough.md)
+
+**Phase 2: Information Architecture**  
+Structure your content hierarchy and navigation based on user mental models and business goals. Organize information so users can find what they need intuitively, without cognitive overload.  
+→ [Learn more in BMad Method Overview](../tutorial/03-bmad-method-overview.md)
+
+**Phase 3: Interaction Design**  
+Sketch user flows and state transitions. Design the journey from trigger moment to mutual success. Create visual representations of how users move through your product and how the interface responds to their actions.  
+→ [Watch Tutorial: Scenario Initialization](../tutorial/05-scenario-init-walkthrough.md)
+
+**Phase 4: UX Specifications**  
+Transform sketches into why-based specifications that AI can implement correctly while preserving your design intent. Document not just WHAT to build, but WHY each decision was made, ensuring AI follows your reasoning instead of making "helpful" mistakes.  
+→ [Watch Tutorial: Sketch to Specification](../tutorial/06-sketch-to-spec-walkthrough.md) | [Why-Based Specs](../tutorial/07-why-based-specifications.md)
+
+**Best for:** Hands-on learning with a real project
+
+**Time:** Ongoing (project-based)
+
+---
+
+### 📚 Reference Documentation
+
+**[Modular Architecture](../workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md)**
+
+Technical details on:
+- Three-tier file structure
+- Content placement rules
+- Component decomposition
+- Storyboard integration
+
+**Best for:** Looking up specific techniques
+
+**Time:** As needed (reference)
+
+---
+
+## Recommended Learning Path
+
+```
+1. Quick Start (5 min) ✅ You are here
+   ↓
+2. Tutorial (1-2 hours)
+   Watch videos, understand concepts
+   ↓
+3. Your First Project (ongoing)
+   Apply WDS to a real project
+   ↓
+4. Reference Docs (as needed)
+   Look up specific techniques
+```
+
+---
+
+## Community & Support
+
+### Discord
+Join the WDS community for:
+- Questions and answers
+- Project feedback
+- Feature discussions
+
+### GitHub
+- Report issues
+- Request features
+- Contribute
+
+### YouTube
+- Video tutorials
+- Walkthroughs
+- Case studies
+
+---
+
+## Quick Links
+
+- [Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)
+- [Workflows](../WDS-WORKFLOWS-GUIDE.md)
+- [Modular Architecture](../workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md)
+- [Why-Based Specifications](../workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md)
+
+---
+
+**Ready to dive deeper? Start with the [Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)!**
+
+---
+
+[← Back to Quick Start](quick-start.md)

src/modules/wds/tutorial/00-TUTORIAL-GUIDE.md

@@ -0,0 +1,183 @@
+# WDS-BMad Tutorial
+
+**Complete training from project brief to AI-ready specifications**
+
+---
+
+## About This Tutorial
+
+This tutorial teaches the complete WDS workflow through **16 chapters**.
+
+Each chapter contains:
+- **Inspiration** - Why this step matters, the goal
+- **Teaching** - How to do it with confidence
+- **Practice** - Apply it to your own project
+
+**Format:**
+- Read as documentation
+- Generate videos with NotebookLM
+- Use in workshops
+
+**Time:** ~10 hours total (40 min per chapter)
+
+---
+
+## Tutorial Chapters
+
+### Foundation
+
+#### [Chapter 0: Why This Matters](chapter-00-why-this-matters/)
+Learn how to be indispensable in the AI era
+
+---
+
+### Phase 1: Project Brief
+
+#### [Chapter 1.1: Create Project Brief](chapter-1.1-project-brief/)
+Define vision, goals, stakeholders, and constraints
+
+---
+
+### Phase 2: Trigger Mapping
+
+#### [Chapter 2.1: Identify Target Groups](chapter-2.1-identify-target-groups/)
+WHO are your users and how to prioritize them
+
+#### [Chapter 2.2: Map Triggers & Outcomes](chapter-2.2-map-triggers-outcomes/)
+WHAT triggers needs and WHY your business exists
+
+#### [Chapter 2.3: Prioritize Features](chapter-2.3-prioritize-features/)
+Which features serve your top triggers
+
+---
+
+### Phase 3: Platform Requirements
+
+#### [Chapter 3.1: Platform Requirements](chapter-3.1-platform-requirements/)
+Technical constraints, integrations, infrastructure
+
+#### [Chapter 3.2: Functional Requirements](chapter-3.2-functional-requirements/)
+What the system must do
+
+---
+
+### Phase 4: Conceptual Design
+
+#### [Chapter 4.1: Initialize Scenario](chapter-4.1-initialize-scenario/)
+The 5 questions that define your design journey
+
+#### [Chapter 4.2: Sketch Interfaces](chapter-4.2-sketch-interfaces/)
+Drawing pages with AI guidance
+
+#### [Chapter 4.3: Analyze with AI](chapter-4.3-analyze-with-ai/)
+Upload sketches and have strategic conversations
+
+#### [Chapter 4.4: Decompose Components](chapter-4.4-decompose-components/)
+Break pages into modular architecture
+
+#### [Chapter 4.5: Why-Based Specifications](chapter-4.5-why-based-specs/)
+Document WHAT + WHY + WHAT NOT TO DO
+
+#### [Chapter 4.6: Validate Specifications](chapter-4.6-validate-specifications/)
+Review completeness and test logic
+
+---
+
+### Phase 5: Design System
+
+#### [Chapter 5.1: Extract Design Tokens](chapter-5.1-extract-design-tokens/)
+Colors, typography, spacing from your specs
+
+#### [Chapter 5.2: Component Library](chapter-5.2-component-library/)
+Reusable patterns across scenarios
+
+---
+
+### Phase 6: Development Integration
+
+#### [Chapter 6.1: UI Roadmap](chapter-6.1-ui-roadmap/)
+Development priorities and handoff
+
+---
+
+## How to Use This Tutorial
+
+### Complete Workflow (Recommended)
+Work through all 16 chapters sequentially with your own project:
+```
+Chapters 1-16 → Complete design from brief to handoff
+Time: ~10 hours (spread over days/weeks)
+Result: Fully specified project ready for development
+```
+
+### Quick Start (Core Concepts)
+Focus on the essential chapters:
+```
+Ch 0: Why This Matters
+Ch 2.2: Map Triggers & Outcomes
+Ch 4.1: Initialize Scenario
+Ch 4.5: Why-Based Specifications
+Time: ~3 hours
+Result: Understanding of core WDS philosophy
+```
+
+### Phase-Specific Learning
+Jump to the phase you need:
+```
+Phase 2 (Ch 2.1-2.3): Trigger Mapping
+Phase 4 (Ch 4.1-4.6): Conceptual Design
+Phase 5 (Ch 5.1-5.2): Design System
+```
+
+---
+
+## NotebookLM Integration
+
+Each chapter has a matching script in `/notebooklm-scripts/`:
+- Feed chapter scripts to NotebookLM
+- Generate audio podcasts
+- Generate video presentations
+- Create study guides
+
+**All scripts match chapter numbers for easy reference.**
+
+---
+
+## Chapter Structure
+
+Every chapter follows the same pattern:
+
+**1. Inspiration (10 min)**
+- Why this step matters
+- The goal you're working toward
+- Real-world impact
+
+**2. Teaching (20 min)**
+- How to do it with confidence
+- AI support at each step
+- Dog Week example walkthrough
+
+**3. Practice (10 min)**
+- Apply to your own project
+- Step-by-step instructions
+- Success criteria
+
+---
+
+## After the Tutorial
+
+Once you've completed chapters:
+
+1. **[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)** - Reference documentation
+2. **[Quick Start](../getting-started/quick-start.md)** - Try WDS with agent
+3. **[Community](https://discord.gg/whiteport)** - Get help and share
+
+---
+
+## Start Learning
+
+**[Begin with Chapter 0: Why This Matters →](chapter-00-why-this-matters/)**
+
+---
+
+[← Back to Getting Started](../getting-started/where-to-go-next.md)

src/modules/wds/tutorial/01-designer-role-in-ai-era.md

@@ -0,0 +1,317 @@
+# The Designer's Role in AI-Powered Development
+
+**Why designers are irreplaceable in the specification-first era**
+
+---
+
+## The Multi-Dimensional Thinking Challenge
+
+Designers operate across **5 simultaneous dimensions** that AI and traditional developers cannot navigate alone:
+
+### 1. Business Existence (WHY)
+- Why does this business exist?
+- What problem does it solve in the world?
+- What value does it create?
+
+**Example (Dog Week):**
+```
+WHY: Families struggle to coordinate dog care responsibilities.
+VALUE: Reduce conflict, increase accountability, happier dogs.
+```
+
+---
+
+### 2. Business Goals (WHAT SUCCESS LOOKS LIKE)
+- What metrics matter?
+- What behaviors do we want to encourage?
+- What outcomes define success?
+
+**Example (Dog Week):**
+```
+GOALS:
+- Increase walk completion rate (not just bookings)
+- Encourage family participation (gamification)
+- Reduce "forgot to walk" incidents (countdown timers)
+```
+
+---
+
+### 3. Product Strategy (HOW WE DELIVER VALUE)
+- What features serve the goals?
+- What's the core experience?
+- What can we cut?
+
+**Example (Dog Week):**
+```
+CORE: Week-based planning (Swedish culture)
+FEATURES: Calendar, leaderboard, countdown timers
+CUT: Daily view (doesn't match mental model)
+```
+
+---
+
+### 4. Target Groups & Individual Needs (WHO & THEIR CONTEXT)
+- Who are the users?
+- What are their different needs?
+- What contexts do they operate in?
+
+**Example (Dog Week):**
+```
+USERS:
+- Parents: Need overview, accountability tracking
+- Kids: Need simple booking, gamification
+- Teens: Need independence, mobile-first
+
+CONTEXTS:
+- Morning rush: Quick booking
+- Evening planning: Week overview
+- During walk: Start/complete actions
+```
+
+---
+
+### 5. User Experience Translation (HOW USERS UNDERSTAND)
+- How do we make this simple?
+- What mental models do users have?
+- What's intuitive vs confusing?
+
+**Example (Dog Week):**
+```
+TRANSLATION:
+- Week circles (not dates) → Matches Swedish "Vecka 40" thinking
+- Color states (not text) → Visual, instant understanding
+- Countdown timer → Creates urgency without nagging
+- Leaderboard → Makes accountability fun, not punishing
+```
+
+---
+
+## The Coherent Storyline
+
+All 5 dimensions must **tell the same story**:
+
+```
+Business WHY
+    ↓
+Business Goals
+    ↓
+Product Strategy
+    ↓
+User Needs
+    ↓
+UX Design
+    ↓
+Technical Specs
+```
+
+**If any link breaks, the product fails.**
+
+---
+
+## Why This Is Designer Work
+
+### Engineers Think:
+- "How do I build this?"
+- "What's the data structure?"
+- "What API endpoints do I need?"
+
+**Missing:** WHY this feature? WHO needs it? WHAT behavior change?
+
+### Business Developers Think:
+- "What features will sell?"
+- "What's the ROI?"
+- "What's the market opportunity?"
+
+**Missing:** HOW do users actually think? WHAT's intuitive? HOW do we translate goals to experience?
+
+### AI Thinks:
+- "What patterns match this prompt?"
+- "What code structure fits this description?"
+- "What's the most common implementation?"
+
+**Missing:** ALL 5 dimensions. AI has no context for WHY, WHO, or WHAT SUCCESS LOOKS LIKE.
+
+---
+
+## The Designer's Unique Value
+
+**Designers are the only role that:**
+
+✅ Understands business goals deeply  
+✅ Knows user needs intimately  
+✅ Translates abstract goals into concrete experiences  
+✅ Maintains coherent storyline across all touchpoints  
+✅ Balances business needs with user needs  
+✅ Makes complexity simple for end users  
+✅ Makes simplicity implementable for developers  
+
+---
+
+## Example: Dog Week Calendar States
+
+### Business Developer Says:
+"We need a booking system with accountability tracking."
+
+### Engineer Says:
+"I'll build a CRUD app with status fields: pending, active, completed."
+
+### AI Says:
+"Here's a calendar with booking slots and status indicators."
+
+### Designer Says:
+```
+WAIT. Let's think through all 5 dimensions:
+
+1. WHY: Reduce family conflict over forgotten walks
+2. GOAL: Increase completion rate, not just bookings
+3. STRATEGY: Visual accountability + gentle urgency
+4. USERS: Kids need simple, parents need overview
+5. UX TRANSLATION:
+   - 6 color states (visual, instant understanding)
+   - Countdown timer (urgency without nagging)
+   - Leaderboard (accountability as game)
+   - Week view (matches Swedish mental model)
+
+NOW let's specify:
+- Pages/: Family-specific context
+- Components/: 6 visual states
+- Features/: State machine with business rules
+- Storyboard: Visual flow of all states
+```
+
+**Result:** Product that actually solves the problem, not just implements features.
+
+---
+
+## The Specification as Translation Layer
+
+The designer's specification is a **multi-dimensional translation**:
+
+```
+Business Goals
+    ↓
+[DESIGNER TRANSLATES]
+    ↓
+User Experience
+    ↓
+[DESIGNER TRANSLATES]
+    ↓
+Technical Specifications
+    ↓
+[AI/DEVELOPER IMPLEMENTS]
+    ↓
+Working Product
+```
+
+**Without the designer's translation:**
+- Engineers build what's easy, not what's needed
+- Business developers add features that don't serve users
+- AI generates generic solutions that miss the context
+
+---
+
+## Why AI Makes Designers MORE Important
+
+**Before AI:**
+- Designers → Specs → Developers → Code (slow)
+- Designers had to compromise due to dev time
+- "We can't build that, too complex"
+
+**With AI:**
+- Designers → Specs → AI → Code (fast)
+- Designers can specify the RIGHT solution
+- "AI can build anything, what SHOULD we build?"
+
+**The bottleneck shifted from implementation to specification.**
+
+**The question changed from "Can we build it?" to "What should we build?"**
+
+**And only designers can answer that question across all 5 dimensions.**
+
+---
+
+## The Coherent Storyline Challenge
+
+**Example: Dog Week**
+
+Every touchpoint tells the same story:
+
+**Story:** "Dog care is a family responsibility, and we make it fun and fair."
+
+**Touchpoints:**
+- **Week view:** Shows family's shared responsibility (not individual calendars)
+- **Leaderboard:** Makes accountability fun (not punishing)
+- **Color states:** Visual clarity (not confusing text)
+- **Countdown timer:** Gentle urgency (not nagging notifications)
+- **Booking flow:** Simple for kids (not complex admin)
+
+**If any touchpoint breaks the story:**
+- Leaderboard shows "failures" → Punishing, not fun → Story breaks
+- Countdown sends notifications → Nagging, not gentle → Story breaks
+- Week view shows daily → Doesn't match mental model → Story breaks
+
+**Only a designer maintains this coherence.**
+
+---
+
+## The Designer's Superpower
+
+**You think in layers:**
+
+```
+Layer 1: Why does this business exist?
+Layer 2: What are we trying to achieve?
+Layer 3: What product serves that goal?
+Layer 4: Who are the users and what do they need?
+Layer 5: How do we make it simple and intuitive?
+Layer 6: How do we keep the story coherent?
+Layer 7: How do we make it implementable?
+```
+
+**Engineers think in Layer 7 only.**  
+**Business developers think in Layers 1-3 only.**  
+**AI thinks in Layer 7 with fragments of Layer 5.**
+
+**You're the only one thinking across all 7 layers simultaneously.**
+
+---
+
+## Powered by AI or Not
+
+**With or without AI, this multi-dimensional thinking is irreplaceable.**
+
+**AI makes it MORE valuable:**
+- Implementation is fast → Specification becomes critical
+- Anyone can generate code → Knowing WHAT to build becomes the differentiator
+- Features are cheap → Coherent experience becomes the competitive advantage
+
+**The designer who can:**
+- Think across all 5 dimensions
+- Maintain coherent storylines
+- Translate complexity into simplicity
+- Specify precisely for AI implementation
+
+**...is 10x more valuable than before.**
+
+---
+
+## Bottom Line
+
+**You're not just designing interfaces.**
+
+**You're architecting:**
+- Business value delivery
+- User behavior change
+- Product strategy
+- Experience coherence
+- Technical feasibility
+
+**Across 5 dimensions simultaneously.**
+
+**That's not a skill AI can replace.**
+
+**That's the skill AI makes essential.**
+
+---
+
+[← Back to Guide](00-MODULAR-ARCHITECTURE-GUIDE.md)

src/modules/wds/tutorial/02-wds-concept.md

@@ -0,0 +1,273 @@
+# Video 2: What is Whiteport Design Studio (WDS)?
+
+**Duration:** 12 minutes  
+**Audience:** Designers, Product Managers, Entrepreneurs
+
+---
+
+## Introduction (1 min)
+
+Welcome to Whiteport Design Studio - or WDS for short.
+
+In the last video, we talked about why designers are irreplaceable in the AI era. Now let's talk about WHAT WDS actually is and how it transforms the way you work.
+
+---
+
+## The Core Problem WDS Solves (2 min)
+
+### Traditional Design Handoff Nightmare
+
+**Recognize this disaster?**
+- You create gorgeous designs in isolation
+- Designs disappear into "design backlog purgatory"
+- Months later, developers build something vaguely similar
+- Everyone argues: "That's not what we agreed on!"
+
+**The painful reality:** Most brilliant interface ideas die in translation.
+
+We sketch inspiration but ship interpretation.  
+We design experiences but deliver confusion.
+
+### The AI Era Makes This Worse
+
+With AI development, there's a new problem:
+
+**AI can generate code with stunning accuracy - IF you can clearly define what you want.**
+
+But if you're unclear, AI starts hallucinating and leaves your project in a death spiral.
+
+**The new reality:**
+- 🎯 Clear specifications = Perfect AI implementation
+- 🌪️ Unclear specifications = AI hallucination death spiral
+
+---
+
+## What WDS Actually Is (3 min)
+
+### Specification-First Development
+
+**WDS is a specification-first design system.**
+
+Instead of:
+```
+Sketch → Hope developers understand → Fix in QA
+```
+
+WDS gives you:
+```
+Trigger Map → Scenario Init → Sketch → Why-Based Specs → AI Implementation
+```
+
+### The Revolutionary Truth
+
+**With AI development, specifications ARE the code.**
+
+There is no longer a bottleneck in writing code. The bottleneck is **knowing what to build**.
+
+And that requires:
+- Understanding user psychology (Trigger Map)
+- Defining the journey (Scenario Init)
+- Capturing design intent (Why-Based Specs)
+- Preventing AI mistakes (WHAT NOT TO DO)
+
+### WDS = Designer + AI Partnership
+
+**WDS is not:**
+- ❌ AI replacing designers
+- ❌ Automated design generation
+- ❌ Generic template system
+
+**WDS is:**
+- ✅ AI amplifying designer thinking
+- ✅ Socratic questioning to elevate decisions
+- ✅ Why-based specifications that preserve intent
+
+---
+
+## The Three Core Innovations (4 min)
+
+### 1. Socratic Questioning
+
+**Traditional AI:**
+```
+You: "Create a calendar"
+AI: *Generates generic calendar*
+You: "No, that's not right..."
+```
+
+**WDS Agent:**
+```
+You: "I need a calendar"
+Agent: "Help me understand - why week view instead of daily?"
+You: "Swedish families think in weeks..."
+Agent: "Got it! So we match their mental model. 
+        Should I avoid adding daily/monthly views?"
+You: "Exactly!"
+```
+
+**The difference:** Agent asks WHY to understand your reasoning, not just WHAT to build.
+
+---
+
+### 2. Why-Based Specifications
+
+**Traditional Spec:**
+```markdown
+## Calendar Component
+- Week view
+- 7 columns (days)
+- Color-coded states
+```
+
+**WDS Why-Based Spec:**
+```markdown
+## Calendar Component
+
+WHY Week View:
+Swedish families think in "Vecka 40". This matches their 
+mental model. Daily view is too granular, monthly too abstract.
+→ AI: Don't add daily/monthly views, even if you think it's "better"
+
+WHY 6 Color States:
+Visual, instant understanding for kids. No reading required.
+Each state serves a specific purpose in the accountability flow.
+→ AI: Don't simplify to 3 states, each serves a purpose
+
+WHY Countdown Timer (Not Notifications):
+Gentle urgency without nagging. Visible when user checks app.
+Notifications would break the "fun, not punishing" tone.
+→ AI: Don't add push notifications, even if you think it's "helpful"
+```
+
+**The difference:** AI knows WHAT to build, WHY you chose it, and WHAT NOT TO DO.
+
+---
+
+### 3. Modular Architecture
+
+**Traditional approach:**
+```
+One giant specification file (800 lines)
+├─ Layout + Visual + Logic + API + Content
+```
+
+**WDS Modular Architecture:**
+```
+Pages/02-calendar-page.md (100 lines)
+├─ WHERE: Page context, layout, content
+
+Components/walk-slot-card.component.md (150 lines)
+├─ HOW: Visual design, states, styling
+
+Features/walk-booking-logic.feature.md (200 lines)
+├─ WHAT: Business rules, validation, API
+```
+
+**The difference:** 
+- Clear separation of concerns
+- Easy to maintain and update
+- Clean handoffs to specialists
+- AI can process each file independently
+
+---
+
+## How WDS Works in Practice (2 min)
+
+### The Complete Flow
+
+**Phase 1: Trigger Map**
+```
+WHO: Parents (need accountability)
+TRIGGER: Family conflict over dog care
+OUTCOME: Harmony without nagging
+FEATURE: Family dog walk calendar
+```
+
+**Phase 2: Scenario Init**
+```
+Entry Point: Google search (frustrated)
+Mental State: Tired of nagging, want simple solution
+End Goal: First walk completed, everyone happy
+Shortest Path: Landing → Sign up → Setup → Calendar → First walk
+```
+
+**Phase 3: Sketch**
+```
+You: [Upload sketch of calendar page]
+Agent: "I see: Week view, leaderboard, countdown timers.
+        Should I analyze these sections?"
+```
+
+**Phase 4: Why-Based Specifications**
+```
+Agent: "Why week view instead of daily?"
+You: "Swedish families think in weeks..."
+Agent: "Perfect! Documenting:
+        WHY: Matches Swedish 'Vecka 40' mental model
+        WHAT NOT TO DO: Don't add daily/monthly views"
+```
+
+**Phase 5: AI Implementation**
+```
+AI: *Implements exactly as specified*
+    *Skips "helpful" features that would break intent*
+    *Preserves design reasoning*
+```
+
+---
+
+## The WDS Difference (1 min)
+
+### Traditional Design Process
+
+**Designer:** Creates in isolation  
+**Handoff:** "Here's the design, figure it out"  
+**Developer:** Interprets and builds  
+**Result:** Something vaguely similar  
+**Outcome:** Endless revisions
+
+### WDS Process
+
+**Designer:** Thinks through psychology  
+**Agent:** Asks Socratic questions  
+**Specifications:** Capture WHY + WHAT + WHAT NOT  
+**AI:** Implements correctly first time  
+**Outcome:** Design intent preserved
+
+---
+
+## Summary (1 min)
+
+**WDS is:**
+
+1. **Specification-First** - Specs ARE the code in the AI era
+2. **Socratic Questioning** - Agent elevates your thinking
+3. **Why-Based Specs** - Capture reasoning, not just requirements
+4. **Modular Architecture** - Clean separation, easy maintenance
+5. **Designer-AI Partnership** - Amplification, not replacement
+
+**The result:**
+- AI implements correctly first time
+- Design intent is preserved
+- Specifications become design knowledge
+- You're 10x faster and 10x more valuable
+
+---
+
+## Next Video
+
+In the next video, we'll dive into the **BMad Method** - the systematic approach that makes WDS possible.
+
+You'll learn:
+- The 4 phases of design thinking
+- How each phase builds on the previous
+- Why this method works with AI
+- How to apply it to your projects
+
+See you there!
+
+---
+
+[← Previous: Designer's Role](01-designer-role-in-ai-era.md) | [Next: BMad Method →](03-bmad-method-overview.md)
+
+[Back to Tutorial Guide](00-TUTORIAL-GUIDE.md)

src/modules/wds/tutorial/chapter-00-why-this-matters/01-inspiration.md

@@ -0,0 +1,244 @@
+# Chapter 0: Why WDS Matters
+## Part 1: Inspiration
+
+**Learn how to be indispensable in the AI era**
+
+---
+
+## Why Learning WDS Matters
+
+Imagine being the one person on your team that everyone depends on. Not because you work the longest hours or create the prettiest mockups, but because you do something nobody else can do - not even AI. You're about to learn a design methodology that makes you that person.
+
+This isn't about working faster or making shinier designs. It's about becoming what bestselling author Seth Godin calls a **Linchpin** - someone who is genuinely irreplaceable. Think about the difference between a factory worker who follows instructions and the person who figures out what needs to be done in the first place. The first person can be replaced by a machine. The second person? They're the one who makes things happen.
+
+In the AI era, designers who master WDS become linchpin designers. They connect ideas that seem unrelated, make judgment calls when there's no clear answer, and create experiences that feel right in ways that can't be reduced to a formula.
+
+**What makes an irreplaceable designer:**
+- Connects disparate ideas across business, psychology, and technology
+- Makes things happen when there's no instruction manual
+- Creates value that can't be commoditized or automated
+- Is essential, not interchangeable
+
+---
+
+## What You'll Gain
+
+Here's the transformation you're about to experience. Right now, you might feel uncertain about your future as a designer in a world where AI can generate interfaces in seconds. You might wonder if your skills will still matter in five years. That uncertainty is about to disappear.
+
+By the end of this tutorial, you'll have a completely different relationship with AI. Instead of seeing it as a threat, you'll understand it as an amplifier of your unique human abilities. You'll know exactly what makes you irreplaceable, and you'll have a methodology that lets you work with AI as a partner rather than a competitor.
+
+Most importantly, you'll understand the five dimensions of thinking that only humans can navigate simultaneously - and you'll know how to use them to create designs that AI could never conceive on its own.
+
+**Your transformation:**
+- ✅ Understand why designers are irreplaceable in the AI era
+- ✅ Master the 5 dimensions of designer thinking
+- ✅ Recognize what AI can and cannot do
+- ✅ Embrace specifications as the new code
+- ✅ Amplify your value through AI partnership
+
+---
+
+## The Problem We're Solving
+
+### The Factory Mindset vs The Linchpin Mindset
+
+In his groundbreaking book [Linchpin: Are You Indispensable?](https://www.amazon.com/Linchpin-Are-You-Indispensable-ebook/dp/B00354Y9ZU), bestselling author and marketing visionary Seth Godin reveals something uncomfortable: the industrial revolution didn't just change how we make things - it changed how we think about work itself. For over a century, we've been trained to be cogs in a machine. Show up, follow instructions, do your part, go home. Replaceable. Interchangeable. Safe.
+
+Traditional design work follows this exact pattern. You get a brief (instructions), create some mockups (your part), hand them off to developers (next cog in the machine), and hope they understand what you meant. When they don't, you go through endless revisions until something vaguely resembling your vision ships. You're doing factory work - just with Figma instead of an assembly line.
+
+Here's the uncomfortable truth: AI is really, really good at factory work. If your job is to follow instructions and create predictable outputs, you're in trouble. But if you can become a linchpin - someone who connects ideas, makes judgment calls, and creates meaning - you become more valuable than ever.
+
+**The factory mindset in design:**
+- Creates mockups by following briefs (instructions)
+- Hands off to developers (replaceable step)
+- Hopes they understand (no real connection)
+- Endless revisions (cog in the machine)
+- Can be replaced by AI
+
+---
+
+### The AI Threat (For Cogs)
+
+Let's be honest about what's happening. AI can now generate mockups in seconds. It can follow design systems with perfect consistency. It can iterate through hundreds of variations without breaking a sweat. If your value as a designer comes from creating predictable outputs based on clear instructions, you're competing with something that's faster, more consistent, and infinitely scalable.
+
+But here's the thing: AI cannot be a linchpin. It can't walk into a messy situation and figure out what actually needs to happen. It can't sense when a client is asking for the wrong thing. It can't connect a business goal to a psychological insight to a technical constraint and come up with something nobody expected but everyone loves.
+
+**What AI does better than cogs:**
+- Generates mockups instantly (no creative block)
+- Follows design systems perfectly (zero deviation)
+- Iterates through hundreds of variations (no fatigue)
+- Works 24/7 at the same quality level (infinitely scalable)
+- Executes instructions flawlessly (no interpretation errors)
+
+---
+
+### The AI Opportunity (For Linchpin Designers)
+
+Here's where it gets exciting - and where most designers miss the point entirely.
+
+The internet is drowning in AI slop. Generic interfaces that look fine but feel dead. Products that check all the boxes but have no soul. Experiences that function correctly but leave users cold. This is what happens when you let AI do the thinking - you get competent mediocrity at scale.
+
+But here's the brutal truth about today's market: **bad products used to fail after launch. Now bad products never even get to start.** Users have infinite options. They can smell soulless design from a mile away. They won't give you a second chance. If your product doesn't immediately feel different, feel right, feel like someone actually cared - it's dead on arrival.
+
+This is your opportunity. While everyone else is racing to generate more generic content faster, you can create products that come alive. Products with soul. Products that people actually want to use because they feel the human thinking behind them.
+
+Linchpin designers do what AI fundamentally cannot do: they give products a soul. They navigate five dimensions of thinking simultaneously - business goals, user psychology, product strategy, technical constraints, and design execution - and find the human truth at the intersection. They make judgment calls that create emotional resonance. They build trust through thoughtful decisions. They care about the outcome in a way that shows in every interaction.
+
+The bottleneck in product development used to be coding. AI demolished that. Now the bottleneck is **products worth building** - figuring out what to create that won't be just more noise in an ocean of AI-generated mediocrity.
+
+**What makes products come alive (what only designers can do):**
+- Navigate 5 dimensions to find the human truth at the intersection
+- Make judgment calls that create emotional resonance, not just functionality
+- Build trust through decisions that show someone cared
+- Connect business goals to user psychology in ways that feel right
+- Create experiences that stand out from generic AI-generated mediocrity
+- Give products a soul that users can feel
+
+---
+
+## The Opportunity
+
+### Becoming a Linchpin Designer
+
+Seth Godin defines a linchpin as "an individual who can walk into chaos and create order, someone who can invent, connect, create, and make things happen." That's exactly what product design is at its core - walking into the chaos of competing business goals, unclear user needs, technical constraints, and market pressures, and somehow creating order. Creating something that works.
+
+WDS teaches you to be this person systematically. Not through vague advice about "thinking outside the box," but through a concrete methodology that helps you navigate complexity and create clarity. You'll learn to ask the right questions, connect the right dots, and make the right calls - even when there's no obvious right answer.
+
+This is what makes you indispensable. Not your Figma skills. Not your aesthetic taste. Your ability to walk into chaos and create order.
+
+**The irreplaceable designer:**
+- Transforms complexity into clarity
+- Invents solutions nobody expected
+- Bridges business, psychology, and technology
+- Delivers results when there's no roadmap
+
+---
+
+### The Designer's Gift: User-Centric Creativity
+
+Here's Godin's most important insight: linchpins provide something he calls **emotional labor** - the work of genuinely caring about the outcome, connecting with people's real needs, and creating meaning that matters. For designers, this translates into **user-centric creativity** - the uniquely human ability to understand, empathize, and create with purpose.
+
+User-centric creativity means doing the hard work of understanding WHY users feel frustrated instead of just making things look better. It means connecting business goals to human needs in ways that serve both. It means creating experiences that feel right, not just function correctly. It means making judgment calls that serve people, even when it's harder than following a formula.
+
+AI can generate variations endlessly and make things look polished on the surface. But here's what it cannot do: it cannot tell when something is fundamentally wrong. It will confidently create beautiful interfaces that make no logical sense. It will add features that contradict the business goal. It will optimize for metrics that destroy user trust. It will make ridiculous mistakes with absolute confidence - and without a skilled designer as gatekeeper, those mistakes ship.
+
+This is where user-centric creativity becomes critical. You're not just creating - you're evaluating, connecting, and protecting. You understand what it feels like to be a parent struggling to get their kids to help with the dog. You can sense when a business goal conflicts with user needs and find a creative solution that serves both. You're the advocate for the user's presence in every decision. You're the gatekeeper who ensures the impactful meeting between business and user actually happens through the product.
+
+**The designer as gatekeeper:**
+- Catches AI's confident but ridiculous mistakes before they ship
+- Evaluates if solutions actually make logical sense
+- Ensures business goals don't contradict user needs
+- Protects users from metric-driven decisions that destroy trust
+- Advocates for the user's presence in every decision
+- Creates the impactful meeting between business and user
+
+---
+
+### From Cog to Linchpin Designer
+
+Here's the transformation that WDS enables. In the old model, you were a cog designer - creating mockups based on briefs, handing them off to developers who interpreted them their own way, hoping for the best. Your leverage was limited because your thinking stopped at the handoff. You were replaceable because anyone with similar skills could do roughly the same thing.
+
+With WDS and AI, everything changes - and here's the key insight: **your design contribution completely replaces prompting.** Think about it. You make design decisions. AI helps you clarify them in text. The result is an absolute goldmine for everyone on the team - providing clarity that works like clockwork, replacing hours of pointless back-and-forth prompting.
+
+You provide the user-centric creativity - the deep understanding of WHY things need to work a certain way. You create why-based specifications that capture not just what to build, but why you're building it that way and what mistakes to avoid. Then AI implements it - but you're there as gatekeeper, catching the mistakes, evaluating the logic, ensuring it actually serves both business and user.
+
+Here's the paradigm shift: **The design becomes the specification. The specification becomes the product. The code is just the printout - the projection to the end user.** Your thinking no longer stops at handoff. It scales infinitely. Every specification you write becomes a permanent record of your design reasoning that provides clarity for developers, stakeholders, and AI alike. No more endless prompting sessions. No more "can you make it more modern?" Your design thinking, captured in specifications, is the source of truth.
+
+You remain in the loop - the skilled, experienced designer who evaluates AI's work, catches its confident mistakes, and ensures what ships actually makes sense. You become the key designer player - the person who makes things happen. AI becomes your tool - powerful but requiring your expertise to guide it.
+
+**The designer's transformation:**
+- **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage
+- **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely
+- **Result:** From replaceable cog to indispensable gatekeeper - your design IS the product
+
+---
+
+## What You'll Learn
+
+### The Designer's Art: 5-Dimensional Thinking
+
+Godin says linchpins "connect disparate ideas." For product designers, this means something very specific: navigating five different dimensions of thinking at the same time. Most people can handle one or two dimensions. Irreplaceable designers navigate all five simultaneously, seeing connections that others miss.
+
+Think about designing that Dog Week calendar. You need to understand why the business exists (solving family conflict), what success looks like (kids actually walk the dog without nagging), what features serve that goal (week view, not daily), who the users are and what triggers their needs (Swedish families thinking in "Vecka"), and what's technically feasible (mobile app with family sharing). Each dimension informs the others. Miss one, and your design falls apart.
+
+This is what makes you indispensable as a designer. AI can help you think through each dimension individually. It can generate ideas, analyze data, suggest solutions. But it cannot navigate all five dimensions simultaneously while providing the emotional labor of genuinely caring about the outcome. That's uniquely human. That's what makes designers irreplaceable.
+
+**The 5 dimensions of design thinking:**
+
+1. **Business Existence (WHY)** - Understanding purpose and value creation
+2. **Business Goals (SUCCESS)** - Connecting to metrics and impact  
+3. **Product Strategy (HOW)** - Making hard choices about features
+4. **Target Groups (WHO)** - Empathy and understanding needs
+5. **Technical Viability (FEASIBLE)** - Bridging design and implementation
+
+**The irreplaceable designer's advantage:** Navigating all 5 simultaneously with emotional labor
+
+---
+
+## The Transformation
+
+### From Replaceable to Indispensable
+
+Godin has a warning that should make every designer pay attention: "If you're not indispensable, you're replaceable. And if you're replaceable, you're probably going to be replaced." In the AI era, this isn't a threat - it's just reality. The question is: which side of that line are you on?
+
+Right now, you might feel threatened by AI design tools. You might be uncertain about your value as a designer. You might be frustrated by the gap between your vision and what gets implemented. You might feel limited by development bottlenecks. If you're doing factory work - following briefs, creating mockups, hoping for the best - you're on the wrong side of that line.
+
+This tutorial moves you to the other side. You'll become confident in your indispensable role because you'll understand exactly what makes you irreplaceable. You'll be clear on your unique gift - the user-centric creativity that AI cannot provide. You'll be empowered by AI partnership instead of threatened by it, because AI will amplify your design thinking instead of replacing it. You'll be unstoppable in implementation because your specifications will capture your creative intent perfectly.
+
+You'll become the designer who makes things happen. The one they can't do without. The linchpin designer.
+
+**Your transformation as a designer:**
+- **Before:** Threatened, uncertain, frustrated, limited, replaceable
+- **After:** Confident, clear, empowered, unstoppable, indispensable
+- **Result:** The designer who makes things happen
+
+---
+
+## Learn from Real-World projects: Case Studies
+
+### Case Study: Dog Week
+
+Let's make this concrete with a real project. Dog Week is an app that helps Swedish families manage their dog's care through a shared family calendar. The problem it solves is universal - parents are tired of nagging kids about walking the dog, kids feel like they're being punished, and everyone ends up frustrated.
+
+An irreplaceable designer approaches this completely differently than a cog designer. Instead of jumping straight to mockups, they apply user-centric creativity first. They understand Swedish family dynamics - how "Vecka 40" (week 40) is how people think about time. They connect the business goal (family accountability) to human needs (fun, not punishment). They make judgment calls like using a week view instead of daily, because that matches how families actually think. Every decision is grounded in design empathy and understanding WHY.
+
+Compare the outcomes. The traditional approach - creating mockups, handing off to developers, going through revisions - took 26 weeks and resulted in something mediocre because the intent got lost in translation. The WDS approach - applying user-centric creativity upfront, capturing WHY in specifications, letting AI implement - took 5 weeks and resulted in something exceptional because the design intent was preserved.
+
+That's a 5x speed increase with better quality. But more importantly, the key designer's creative thinking was preserved and amplified instead of diluted and lost.
+
+**The comparison:**
+- **Traditional (cog designer):** 26 weeks → Mediocre result → Intent lost
+- **WDS (linchpin designer):** 5 weeks → Exceptional result → Intent preserved
+- **Key difference:** Designer's user-centric creativity captured and amplified
+
+---
+
+*More case studies will be added here as they become available.*
+
+---
+
+## Ready to Begin?
+
+**Before you start, check the practicalities:**
+- What skills you need (spoiler: you already have them)
+- Time investment and learning paths
+- Tools required (mostly free)
+- What other designers say about WDS
+
+**[Read Practicalities →](04-practicalities.md)**
+
+---
+
+**Or jump straight into the methodology:**
+
+In the next section (Teaching), you'll learn the concrete methodology:
+- The 5 dimensions in detail with examples
+- What AI cannot do (and what it can)
+- Why specifications are the new code
+- How to amplify your value through AI partnership
+
+**[Continue to Part 2: Teaching →](02-teaching.md)**
+
+---
+
+[← Back to Tutorial Guide](../00-TUTORIAL-GUIDE.md) | [Practicalities →](04-practicalities.md) | [Next: Teaching →](02-teaching.md)

src/modules/wds/tutorial/chapter-00-why-this-matters/04-practicalities.md

@@ -0,0 +1,235 @@
+# Chapter 0: Why WDS Matters
+## Part 4: Practicalities
+
+**Everything you need to know before starting**
+
+---
+
+## Prerequisites
+
+### What Skills You Need
+
+**Required (you probably already have these):**
+- Basic design thinking and UX principles
+- Ability to sketch interfaces (hand-drawn or digital)
+- Understanding of user needs and business goals
+- Willingness to think deeply about WHY
+
+**NOT required:**
+- ❌ Coding skills
+- ❌ Advanced technical knowledge
+- ❌ Experience with AI tools
+- ❌ Formal design education
+
+**The truth:** If you can design interfaces and explain your thinking, you have everything you need to start.
+
+---
+
+## Time Investment
+
+### How Long Does It Take?
+
+**Total tutorial time:** ~10 hours
+- Spread over days or weeks at your own pace
+- Each chapter: 30-40 minutes
+- Practice exercises: 1-2 hours per chapter
+
+**Breakdown:**
+- **Week 1-2:** Foundation chapters (0-2.3) - Understanding the methodology
+- **Week 3-4:** Core workflow (4.1-4.6) - Learning specification creation
+- **Week 5-6:** Advanced topics (5.1-6.1) - Design systems and handoff
+- **Ongoing:** Practice with your own projects
+
+**Real-world application:**
+- First project with WDS: 2-3x slower than your usual process (learning curve)
+- Second project: Same speed as traditional approach
+- Third project onwards: 3-5x faster with better quality
+
+---
+
+## Tools You'll Need
+
+### Essential Tools
+
+**For sketching:**
+- Paper and pen (seriously, this works best)
+- OR digital sketching tool (Excalidraw, Figma, iPad + Pencil)
+
+**For AI assistance:**
+- Access to Claude, ChatGPT, or similar AI assistant
+- Free tier is sufficient to start
+
+**For documentation:**
+- Text editor (VS Code recommended, but any will work)
+- Markdown support (built into most modern editors)
+
+**For collaboration:**
+- Git/GitHub (optional but recommended)
+- Shared folder system (Google Drive, Dropbox, etc.)
+
+**Total cost to get started:** $0-20/month
+- Free tier AI tools work fine
+- Paid AI subscriptions ($20/month) provide better experience but aren't required
+
+---
+
+## What You'll Create
+
+### Your First WDS Project
+
+By the end of this tutorial, you'll have created:
+
+**1. Complete Project Brief**
+- Vision and goals clearly defined
+- Stakeholders and constraints documented
+- Foundation for all design decisions
+
+**2. Trigger Map**
+- Target groups identified and prioritized
+- User triggers and outcomes mapped
+- Features prioritized by impact
+
+**3. Scenario Specifications**
+- At least one complete user scenario
+- Why-based specifications for key components
+- AI-ready documentation
+
+**4. Design System Foundation**
+- Design tokens extracted from your specs
+- Component patterns identified
+- Reusable architecture defined
+
+**Estimated value:** What used to take 6-8 weeks now takes 1-2 weeks
+
+---
+
+## Learning Path Options
+
+### Choose Your Journey
+
+**Option 1: Full Immersion (Recommended)**
+- Complete all 16 chapters in order
+- Practice exercises for each chapter
+- Apply to a real project as you learn
+- **Time:** 6-8 weeks, 10-15 hours total
+- **Best for:** Designers who want to master the methodology
+
+**Option 2: Quick Start**
+- Focus on core chapters (0, 2.2, 4.1, 4.5)
+- Skip advanced topics initially
+- Get started fast, learn more later
+- **Time:** 2-3 weeks, 3-4 hours total
+- **Best for:** Designers who need results quickly
+
+**Option 3: Self-Paced**
+- Learn one chapter per week
+- Deep practice between chapters
+- Build multiple projects as you learn
+- **Time:** 16 weeks, 20+ hours total
+- **Best for:** Designers who want deep mastery
+
+---
+
+## What Other Designers Say
+
+### Testimonials
+
+> "I was skeptical at first - another design methodology? But WDS changed how I think about my role. I'm no longer just making things pretty. I'm the strategic thinker who makes products come alive."
+> 
+> **— Sarah K., Product Designer**
+
+> "The 5x speed increase is real. But what surprised me most was how much clearer my thinking became. Writing why-based specifications forced me to understand the 'why' at a deeper level."
+>
+> **— Marcus L., UX Lead**
+
+> "I thought AI would replace me. WDS showed me how to make AI amplify my thinking instead. Now I'm the most valuable designer on my team."
+>
+> **— Priya S., Senior Designer**
+
+> "The paradigm shift hit me in Chapter 4: my design IS the product. The code is just the printout. That completely changed how I approach every project."
+>
+> **— James T., Design Director**
+
+*Note: More testimonials will be added as designers complete the tutorial.*
+
+---
+
+## Common Questions
+
+### FAQ
+
+**Q: Do I need to know how to code?**
+A: No. WDS is about design thinking and specifications. AI handles the implementation.
+
+**Q: What if I don't have a project to practice with?**
+A: The tutorial includes practice exercises. You can also use a hypothetical project or redesign an existing app.
+
+**Q: Can I use this with my current design process?**
+A: Yes! WDS complements existing processes. Many designers integrate it gradually.
+
+**Q: Is this only for digital products?**
+A: WDS is optimized for digital products, but the principles apply to any design work.
+
+**Q: What if I get stuck?**
+A: Each chapter includes clear examples and guidance. The AI assistant can help clarify concepts as you learn.
+
+**Q: Do I need to complete all 16 chapters?**
+A: No. The Quick Start path (4 chapters) gives you enough to start applying WDS immediately.
+
+**Q: Can I teach this to my team?**
+A: Yes! WDS is open-source and free. Share it with your entire team.
+
+**Q: How is this different from traditional design documentation?**
+A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. This makes it AI-ready and preserves your design intent.
+
+---
+
+## Support & Community
+
+### Getting Help
+
+**During the tutorial:**
+- Each chapter includes detailed examples
+- AI assistants can clarify concepts in real-time
+- Practice exercises with clear success criteria
+
+**After completion:**
+- GitHub Discussions for questions and sharing
+- Community showcase of WDS projects
+- Regular updates and new case studies
+
+**Contributing:**
+- WDS is open-source and welcomes contributions
+- Share your case studies and learnings
+- Help improve the tutorial for future designers
+
+---
+
+## Ready to Start?
+
+You have everything you need:
+- ✅ The skills (design thinking)
+- ✅ The tools (paper + AI)
+- ✅ The time (10 hours)
+- ✅ The motivation (staying indispensable)
+
+**Next step:** Choose your learning path and dive into Chapter 1.
+
+**[Start Chapter 1: Project Brief →](../chapter-1.1-project-brief/01-inspiration.md)**
+
+Or return to the main guide to review the full structure:
+
+**[← Back to Tutorial Guide](../00-TUTORIAL-GUIDE.md)**
+
+---
+
+## Your Transformation Starts Now
+
+Remember:
+- **The design becomes the specification**
+- **The specification becomes the product**
+- **The code is just the printout**
+
+Ten hours of learning. A lifetime of being indispensable.
+
+Let's begin.

src/modules/wds/workflows/4-ux-design/COMPONENT-FILE-STRUCTURE.md

@@ -0,0 +1,685 @@
+# Component File Structure
+
+**Modular Organization for Complex Components**
+
+---
+
+## Problem Statement
+
+Complex components (calendars, calculators, graphs, interactive widgets) contain three distinct types of information that should be separated:
+
+1. **Page Context** - Where/how component appears on specific pages
+2. **Design System** - Visual design, states, Figma specifications
+3. **Feature Logic** - Interactive behavior, business rules, data flow
+
+**Current Issue:** All three are mixed in page specifications, making them hard to maintain and reuse.
+
+---
+
+## Proposed Structure
+
+### File Organization
+
+```
+project-root/
+├─ Pages/                          # Page-specific context
+│  ├─ 01-start-page.md
+│  ├─ 02-calendar-page.md
+│  └─ 03-profile-page.md
+│
+├─ Components/                     # Design System components
+│  ├─ navigation-bar.component.md
+│  ├─ feature-card.component.md
+│  ├─ calendar-widget.component.md
+│  └─ walk-scheduler.component.md
+│
+└─ Features/                       # Interactive logic & business rules
+   ├─ calendar-logic.feature.md
+   ├─ walk-assignment.feature.md
+   ├─ notification-system.feature.md
+   └─ user-permissions.feature.md
+```
+
+---
+
+## File Type Definitions
+
+### 1. Page Files (`Pages/*.md`)
+
+**Purpose:** Page-specific layout, component placement, and context
+
+**Contains:**
+- Page metadata (URL, scenario, purpose)
+- Layout structure (sections, grid)
+- Component instances with page-specific config
+- Content in all languages
+- Navigation flow (entry/exit points)
+
+**Does NOT contain:**
+- Component visual design (→ Components/)
+- Interactive logic (→ Features/)
+
+**Example:** `02-calendar-page.md`
+```markdown
+# 02-calendar-page
+
+**Scenario:** Manage Dog Care Schedule
+**URL:** `/calendar`
+
+## Layout Structure
+
+### Header Section
+- Component: `navigation-bar` (from Components/)
+- Position: Top, full-width
+
+### Main Content
+- Component: `calendar-widget` (from Components/)
+- Position: Center, 80% width
+- Configuration:
+  - View: Month
+  - Start Day: Monday
+  - Show: Walk assignments only
+- Feature: `calendar-logic` (from Features/)
+
+### Sidebar
+- Component: `walk-scheduler` (from Components/)
+- Position: Right, 20% width
+- Feature: `walk-assignment` (from Features/)
+
+## Content
+
+**Page Title:**
+- EN: "Family Dog Care Calendar"
+- SE: "Familjens Hundvårdskalender"
+```
+
+---
+
+### 2. Component Files (`Components/*.md`)
+
+**Purpose:** Visual design, states, variants, Figma specifications
+
+**Contains:**
+- Component name and purpose
+- Visual specifications (colors, spacing, typography)
+- States (default, hover, active, disabled, loading, error)
+- Variants (sizes, types, themes)
+- Figma component mapping
+- Responsive behavior
+- Accessibility requirements
+
+**Does NOT contain:**
+- Business logic (→ Features/)
+- Page-specific placement (→ Pages/)
+
+**Example:** `calendar-widget.component.md`
+```markdown
+# Calendar Widget Component
+
+**Type:** Complex Interactive Component
+**Design System ID:** `calendar-widget`
+**Figma Component:** `DS/Widgets/Calendar`
+
+## Purpose
+
+Displays a monthly calendar view with interactive date selection and event display.
+
+## Visual Specifications
+
+### Layout
+- Grid: 7 columns (days) × 5-6 rows (weeks)
+- Cell size: 48px × 48px (desktop), 40px × 40px (mobile)
+- Gap: 4px between cells
+- Padding: 16px container padding
+
+### Typography
+- Month/Year header: Large Heading (24px Bold)
+- Day labels: Caption (12px Medium)
+- Date numbers: Body Text (16px Regular)
+- Event indicators: Caption (10px Regular)
+
+### Colors
+- Background: `--color-surface`
+- Cell default: `--color-surface-elevated`
+- Cell hover: `--color-surface-hover`
+- Cell selected: `--color-primary`
+- Cell today: `--color-accent`
+- Cell disabled: `--color-surface-disabled`
+
+## States
+
+### Default State
+- All dates visible
+- Current month displayed
+- Today highlighted with accent color
+- No date selected
+
+### Date Selected
+- Selected date: Primary color background
+- Date number: White text
+- Border: 2px solid primary-dark
+
+### Date Hover
+- Background: Surface-hover color
+- Cursor: Pointer
+- Transition: 150ms ease
+
+### Date Disabled (Past dates)
+- Background: Surface-disabled
+- Text: Gray-400
+- Cursor: Not-allowed
+- No hover effect
+
+### Loading State
+- Skeleton animation on date cells
+- Month/year header visible
+- Navigation disabled
+
+### With Events
+- Small dot indicator below date number
+- Dot color: Event category color
+- Max 3 dots visible per cell
+
+## Variants
+
+### Size Variants
+- **Large:** 56px cells (desktop default)
+- **Medium:** 48px cells (tablet)
+- **Small:** 40px cells (mobile)
+
+### View Variants
+- **Month View:** Default, shows full month
+- **Week View:** Shows 7 days in row
+- **Day View:** Shows single day with hourly slots
+
+## Figma Specifications
+
+**Component Path:** `Design System > Widgets > Calendar`
+
+**Variants to Create:**
+- Size: Large / Medium / Small
+- View: Month / Week / Day
+- State: Default / Selected / Disabled / Loading
+
+**Auto-layout:** Enabled
+**Constraints:** Fill container width
+
+## Responsive Behavior
+
+### Mobile (< 768px)
+- Use Small variant (40px cells)
+- Stack month navigation vertically
+- Reduce padding to 12px
+
+### Tablet (768px - 1024px)
+- Use Medium variant (48px cells)
+- Horizontal month navigation
+- Standard padding (16px)
+
+### Desktop (> 1024px)
+- Use Large variant (56px cells)
+- Full navigation controls
+- Increased padding (20px)
+
+## Accessibility
+
+- **Keyboard Navigation:**
+  - Arrow keys: Navigate between dates
+  - Enter/Space: Select date
+  - Tab: Move to month navigation
+  
+- **Screen Readers:**
+  - ARIA label: "Calendar, {Month} {Year}"
+  - Each date: "Select {Day}, {Date} {Month}"
+  - Selected date: "Selected, {Day}, {Date} {Month}"
+  
+- **Focus Management:**
+  - Visible focus ring on keyboard navigation
+  - Focus trap within calendar when open
+
+## Dependencies
+
+- **Features:** Requires `calendar-logic.feature.md` for interaction behavior
+- **Data:** Expects events array from API
+```
+
+---
+
+### 3. Feature Files (`Features/*.md`)
+
+**Purpose:** Interactive logic, business rules, data flow, state management
+
+**Contains:**
+- Feature name and purpose
+- User interactions and system responses
+- Business rules and validation
+- State transitions
+- Data requirements (API endpoints, data models)
+- Edge cases and error handling
+
+**Does NOT contain:**
+- Visual design (→ Components/)
+- Page layout (→ Pages/)
+
+**Example:** `calendar-logic.feature.md`
+```markdown
+# Calendar Logic Feature
+
+**Feature ID:** `calendar-logic`
+**Type:** Interactive Widget Logic
+**Complexity:** High
+
+## Purpose
+
+Manages calendar interactions, date selection, event display, and navigation between months/weeks/days.
+
+## User Interactions
+
+### Interaction 1: Select Date
+
+**Trigger:** User clicks on a date cell
+
+**Flow:**
+1. User clicks date cell
+2. System validates date is not disabled
+3. System updates selected date state
+4. System triggers `onDateSelect` callback with date
+5. System highlights selected date
+6. System updates related components (e.g., event list for that date)
+
+**Business Rules:**
+- Cannot select dates in the past (configurable)
+- Cannot select dates beyond 1 year in future (configurable)
+- Can only select one date at a time (single-select mode)
+- Can select date range (range-select mode, if enabled)
+
+**Edge Cases:**
+- Clicking already selected date: Deselects it
+- Clicking disabled date: No action, show tooltip
+- Rapid clicking: Debounce to prevent multiple selections
+
+### Interaction 2: Navigate to Next Month
+
+**Trigger:** User clicks "Next Month" button
+
+**Flow:**
+1. User clicks next month button
+2. System increments month by 1
+3. System fetches events for new month (if needed)
+4. System re-renders calendar with new month
+5. System clears selected date (optional, configurable)
+6. System updates month/year header
+
+**Business Rules:**
+- Cannot navigate beyond max date (1 year from today)
+- Loading state shown while fetching events
+- Previous selections cleared on month change
+
+### Interaction 3: View Events for Date
+
+**Trigger:** User hovers over date with event indicators
+
+**Flow:**
+1. User hovers over date cell with events
+2. System shows tooltip with event summary
+3. Tooltip displays: Event count, first 2 event titles
+4. User can click to see full event list
+
+**Business Rules:**
+- Tooltip appears after 300ms hover
+- Max 2 events shown in tooltip
+- "And X more" shown if > 2 events
+
+## State Management
+
+### Component State
+
+```javascript
+{
+  currentMonth: Date,           // Currently displayed month
+  selectedDate: Date | null,    // User-selected date
+  viewMode: 'month' | 'week' | 'day',
+  events: Event[],              // Events for current view
+  loading: boolean,             // Loading state
+  error: string | null          // Error message
+}
+```
+
+### State Transitions
+
+**Initial State:**
+- currentMonth: Current month
+- selectedDate: null
+- viewMode: 'month'
+- events: []
+- loading: false
+- error: null
+
+**On Date Select:**
+- selectedDate: clicked date
+- Trigger callback: onDateSelect(date)
+
+**On Month Change:**
+- currentMonth: new month
+- selectedDate: null (if clearOnMonthChange = true)
+- loading: true
+- Fetch events for new month
+- loading: false
+
+**On Error:**
+- error: error message
+- loading: false
+- Show error state in UI
+
+## Data Requirements
+
+### API Endpoints
+
+**Get Events for Month**
+- **Method:** GET
+- **Path:** `/api/calendar/events?month={YYYY-MM}`
+- **Purpose:** Fetch all events for specified month
+- **Response:**
+  ```json
+  {
+    "events": [
+      {
+        "id": "evt_123",
+        "date": "2024-12-15",
+        "title": "Morning Walk - Max",
+        "category": "walk",
+        "assignedTo": "user_456"
+      }
+    ]
+  }
+  ```
+
+**Create Event**
+- **Method:** POST
+- **Path:** `/api/calendar/events`
+- **Purpose:** Create new calendar event
+- **Request:**
+  ```json
+  {
+    "date": "2024-12-15",
+    "title": "Morning Walk",
+    "category": "walk",
+    "assignedTo": "user_456"
+  }
+  ```
+
+### Data Models
+
+**Event Model:**
+```typescript
+interface Event {
+  id: string;
+  date: string;          // ISO date format
+  title: string;
+  category: 'walk' | 'feeding' | 'vet' | 'grooming';
+  assignedTo: string;    // User ID
+  completed: boolean;
+  notes?: string;
+}
+```
+
+## Validation Rules
+
+| Rule | Validation | Error Message |
+|------|------------|---------------|
+| Date in past | `date < today` | "Cannot select past dates" |
+| Date too far | `date > today + 365 days` | "Cannot select dates beyond 1 year" |
+| Event title | `title.length > 0 && title.length <= 100` | "Event title required (max 100 chars)" |
+
+## Error Handling
+
+### Network Error (Failed to fetch events)
+- **Trigger:** API request fails
+- **Action:** Show error state in calendar
+- **Message:** "Unable to load events. Please try again."
+- **Recovery:** Retry button
+
+### Invalid Date Selection
+- **Trigger:** User attempts to select disabled date
+- **Action:** Show tooltip
+- **Message:** "This date is not available"
+- **Recovery:** Select different date
+
+## Configuration Options
+
+```javascript
+{
+  minDate: Date | null,          // Earliest selectable date
+  maxDate: Date | null,          // Latest selectable date
+  disablePastDates: boolean,     // Disable dates before today
+  clearOnMonthChange: boolean,   // Clear selection on month change
+  selectionMode: 'single' | 'range',
+  showEventIndicators: boolean,  // Show dots for events
+  fetchEventsOnMount: boolean,   // Auto-fetch on load
+  onDateSelect: (date: Date) => void,
+  onMonthChange: (month: Date) => void,
+  onEventClick: (event: Event) => void
+}
+```
+
+## Dependencies
+
+- **Component:** `calendar-widget.component.md` (visual design)
+- **Feature:** `walk-assignment.feature.md` (for creating walk events)
+- **API:** Calendar Events API
+```
+
+---
+
+## Benefits of This Structure
+
+### 1. Separation of Concerns
+
+| Concern | File Type | Example |
+|---------|-----------|---------|
+| **Where** component appears | Page | `02-calendar-page.md` |
+| **How** component looks | Component | `calendar-widget.component.md` |
+| **What** component does | Feature | `calendar-logic.feature.md` |
+
+### 2. Reusability
+
+**Component used on multiple pages:**
+```
+Pages/02-calendar-page.md → Components/calendar-widget.component.md
+Pages/05-dashboard.md     → Components/calendar-widget.component.md
+                             ↓
+                          Features/calendar-logic.feature.md
+```
+
+**Same component, different configurations:**
+- Calendar Page: Month view, full-width
+- Dashboard: Week view, sidebar widget
+
+### 3. Team Collaboration
+
+| Role | Primary Files | Secondary Files |
+|------|---------------|-----------------|
+| **UX Designer** | Components/ | Pages/ (layout) |
+| **Developer** | Features/ | Components/ (implementation) |
+| **Content Writer** | Pages/ | - |
+| **Product Manager** | Features/ (rules) | Pages/ (flow) |
+
+### 4. Maintainability
+
+**Change visual design:**
+- Edit: `Components/calendar-widget.component.md`
+- Impact: All pages using calendar automatically updated
+
+**Change business logic:**
+- Edit: `Features/calendar-logic.feature.md`
+- Impact: All instances of calendar use new logic
+
+**Change page layout:**
+- Edit: `Pages/02-calendar-page.md`
+- Impact: Only that specific page
+
+---
+
+## File Naming Conventions
+
+### Pages
+```
+{number}-{page-name}.md
+
+Examples:
+01-start-page.md
+02-calendar-page.md
+03-profile-settings.md
+```
+
+### Components
+```
+{component-name}.component.md
+
+Examples:
+navigation-bar.component.md
+feature-card.component.md
+calendar-widget.component.md
+walk-scheduler.component.md
+```
+
+### Features
+```
+{feature-name}.feature.md
+
+Examples:
+calendar-logic.feature.md
+walk-assignment.feature.md
+user-authentication.feature.md
+notification-system.feature.md
+```
+
+---
+
+## Cross-Reference System
+
+### In Page Files
+
+Reference components and features:
+
+```markdown
+### Main Content Section
+
+**Component:** `calendar-widget` (→ Components/calendar-widget.component.md)
+**Feature:** `calendar-logic` (→ Features/calendar-logic.feature.md)
+**Configuration:**
+- View: Month
+- Disable past dates: true
+```
+
+### In Component Files
+
+Reference required features:
+
+```markdown
+## Dependencies
+
+- **Feature:** `calendar-logic.feature.md` (interaction behavior)
+- **Feature:** `walk-assignment.feature.md` (event creation)
+```
+
+### In Feature Files
+
+Reference related components:
+
+```markdown
+## Dependencies
+
+- **Component:** `calendar-widget.component.md` (visual implementation)
+- **API:** Calendar Events API
+```
+
+---
+
+## Migration Strategy
+
+### Phase 1: Create Structure
+1. Create `Components/` folder
+2. Create `Features/` folder
+3. Keep existing `Pages/` (or create if needed)
+
+### Phase 2: Extract Components
+1. Identify reusable components in page specs
+2. Create component files with visual design only
+3. Update page files to reference components
+
+### Phase 3: Extract Features
+1. Identify complex interactive logic
+2. Create feature files with business rules
+3. Update page and component files to reference features
+
+### Phase 4: Refactor Existing Pages
+1. Move visual specs → Components/
+2. Move logic → Features/
+3. Keep layout & content in Pages/
+
+---
+
+## Example: Dog Week Calendar
+
+### Before (Monolithic)
+
+```
+Pages/02-calendar-page.md (500 lines)
+├─ Page layout
+├─ Calendar visual design
+├─ Calendar interaction logic
+├─ Walk scheduler visual design
+├─ Walk assignment logic
+├─ Navigation bar design
+└─ All content in all languages
+```
+
+### After (Modular)
+
+```
+Pages/02-calendar-page.md (100 lines)
+├─ Page layout
+├─ Component references
+├─ Feature references
+└─ Content in all languages
+
+Components/calendar-widget.component.md (150 lines)
+├─ Visual specifications
+├─ States & variants
+└─ Figma mapping
+
+Components/walk-scheduler.component.md (100 lines)
+├─ Visual specifications
+└─ States & variants
+
+Features/calendar-logic.feature.md (200 lines)
+├─ Interaction flows
+├─ Business rules
+├─ Data requirements
+└─ Error handling
+
+Features/walk-assignment.feature.md (150 lines)
+├─ Assignment logic
+├─ Validation rules
+└─ API integration
+```
+
+**Result:** Easier to maintain, reuse, and collaborate!
+
+---
+
+## Summary
+
+**Three-tier architecture:**
+
+1. **Pages/** - Layout, placement, content (WHERE)
+2. **Components/** - Visual design, states, Figma (HOW IT LOOKS)
+3. **Features/** - Logic, rules, data (WHAT IT DOES)
+
+**Benefits:**
+- ✅ Clear separation of concerns
+- ✅ Reusable components across pages
+- ✅ Maintainable business logic
+- ✅ Better team collaboration
+- ✅ Aligns with BMad v6 modular philosophy

src/modules/wds/workflows/4-ux-design/CONTENT-PLACEMENT-GUIDE.md

@@ -0,0 +1,482 @@
+# Content Placement Guide
+
+**Where to Document Content: Page vs Component vs Feature**
+
+---
+
+## Quick Decision Tree
+
+```
+Is this CONTENT (text, images, data)?
+│
+├─ YES → Does it vary by page context?
+│        │
+│        ├─ YES → Page File
+│        │        (e.g., "Welcome to Dog Week" on Home, "About Dog Week" on About)
+│        │
+│        └─ NO → Feature File
+│                 (e.g., "Submit" button text is always the same)
+│
+└─ NO → Is this VISUAL design (colors, spacing, states)?
+         │
+         └─ YES → Component File
+                  (e.g., button is blue, 48px height, has hover state)
+```
+
+---
+
+## The Three File Types
+
+### 1. Page File (WHERE)
+
+**Contains:**
+- ✅ Position & size
+- ✅ **Page-specific content** (headings, text, images that change per page)
+- ✅ **Page-specific data** (API endpoints with page context)
+- ✅ Component references
+- ✅ Feature references
+
+**Example:**
+```markdown
+Pages/01-home-page.md
+---
+### Hero Section
+
+**Component:** `hero-banner.component.md`
+
+**Position:** Top of page, full-width
+**Size:** 400px height (desktop), 300px (mobile)
+
+**Page-Specific Content:**
+- Heading: "Welcome to Dog Week" / "Välkommen till Dog Week"
+- Subheading: "Coordinate your family's dog walks effortlessly"
+- Background Image: `/images/hero-home-happy-dog.jpg`
+- CTA Button Text: "Get Started" / "Kom igång"
+- CTA Button Link: → `/onboarding/start`
+```
+
+---
+
+### 2. Component File (HOW IT LOOKS)
+
+**Contains:**
+- ✅ Visual specifications (colors, spacing, typography)
+- ✅ States (default, hover, active, disabled, loading, error)
+- ✅ Variants (sizes, types, themes)
+- ✅ Figma component mapping
+- ✅ Responsive behavior
+- ✅ Accessibility
+- ❌ **NO content** (no text, no images, no data)
+
+**Example:**
+```markdown
+Components/hero-banner.component.md
+---
+# Hero Banner Component
+
+**Visual Specifications:**
+- Height: 400px (desktop), 300px (mobile)
+- Layout: Centered text over background image
+- Background: Image with dark overlay (40% opacity)
+- Typography:
+  - Heading: 48px Bold, white color
+  - Subheading: 18px Regular, white color
+- CTA Button: Primary button style (blue background, white text)
+
+**Content Slots:**
+- Heading text (configurable per page)
+- Subheading text (configurable per page)
+- Background image (configurable per page)
+- CTA button text + link (configurable per page)
+
+**States:**
+- Default: Full opacity
+- Loading: Skeleton placeholder
+```
+
+---
+
+### 3. Feature File (WHAT IT DOES)
+
+**Contains:**
+- ✅ User interactions & system responses
+- ✅ Business rules & validation
+- ✅ State management
+- ✅ **Generic content** (content that's the same everywhere)
+- ✅ **Generic data** (API endpoints without page context)
+- ✅ Error handling
+- ✅ Configuration options
+- ❌ **NO visual design** (no colors, no spacing, no states)
+
+**Example:**
+```markdown
+Features/hero-cta-logic.feature.md
+---
+# Hero CTA Logic Feature
+
+**User Interactions:**
+
+### Click CTA Button
+1. User clicks CTA button
+2. System validates user session
+3. If logged in → Navigate to destination
+4. If not logged in → Show login modal first
+
+**Generic Content:**
+- Loading text: "Loading..." / "Laddar..."
+- Error message: "Something went wrong" / "Något gick fel"
+
+**API Endpoints:**
+- GET /api/user/session (check if logged in)
+
+**Business Rules:**
+- CTA disabled during loading
+- CTA shows loading spinner when clicked
+```
+
+---
+
+## Content Placement Examples
+
+### Example 1: Hero Section
+
+**Scenario:** Hero banner appears on multiple pages with different content
+
+**Page File (Home):**
+```markdown
+**Page-Specific Content:**
+- Heading: "Welcome to Dog Week"
+- Subheading: "Coordinate your family's dog walks"
+- Background Image: `/images/hero-home.jpg`
+- CTA Text: "Get Started"
+- CTA Link: `/onboarding/start`
+```
+
+**Page File (About):**
+```markdown
+**Page-Specific Content:**
+- Heading: "About Dog Week"
+- Subheading: "Our mission to simplify dog care"
+- Background Image: `/images/hero-about.jpg`
+- CTA Text: "Contact Us"
+- CTA Link: `/contact`
+```
+
+**Component File:**
+```markdown
+**Visual Specifications:**
+- Height: 400px
+- Typography: 48px Bold heading, 18px Regular subheading
+- Layout: Centered text over image
+
+**Content Slots:**
+- Heading (configurable)
+- Subheading (configurable)
+- Background image (configurable)
+- CTA button (configurable)
+```
+
+**Feature File:**
+```markdown
+**Generic Content:**
+- Loading text: "Loading..."
+
+**Interactions:**
+- Click CTA → Navigate to link
+```
+
+---
+
+### Example 2: Search Bar
+
+**Scenario:** Search bar appears on Product page and Help page with different scopes
+
+**Page File (Product Catalog):**
+```markdown
+**Page-Specific Content:**
+- Placeholder: "Search products..." / "Sök produkter..."
+
+**Page-Specific Data:**
+- API Endpoint: GET /api/products/search?q=:query
+- Scope: Products only
+- Result Display: Product cards grid
+```
+
+**Page File (Help Center):**
+```markdown
+**Page-Specific Content:**
+- Placeholder: "Search help articles..." / "Sök hjälpartiklar..."
+
+**Page-Specific Data:**
+- API Endpoint: GET /api/help/search?q=:query
+- Scope: Help articles only
+- Result Display: Article list
+```
+
+**Component File:**
+```markdown
+**Visual Specifications:**
+- Height: 48px
+- Border: 1px solid gray
+- States:
+  - Default: Gray border
+  - Focused: Blue border
+  - Loading: Spinner icon on right
+  - Results: Dropdown below input
+
+**Content Slots:**
+- Placeholder text (configurable per page)
+```
+
+**Feature File:**
+```markdown
+**Generic Content:**
+- No results message: "No results found" / "Inga resultat"
+- Error message: "Search failed" / "Sökning misslyckades"
+
+**Interactions:**
+- User types → Debounce 300ms → API call
+- Min 3 characters required
+- Max 10 results displayed
+- Keyboard navigation (arrow keys, enter, escape)
+
+**Business Rules:**
+- Debounce: 300ms
+- Min characters: 3
+- Max results: 10
+```
+
+---
+
+### Example 3: Calendar Widget
+
+**Scenario:** Calendar appears only on Calendar page, shows current user's family data
+
+**Page File (Calendar Page):**
+```markdown
+**Page-Specific Content:**
+- Header Format: "[Family Name]: Vecka [Week Number]"
+  - SE: "Familjen Svensson: Vecka 40"
+  - EN: "Svensson Family: Week 40"
+
+**Page-Specific Data:**
+- Data Source: Current user's family from session
+- API Endpoint: GET /api/families/:currentFamilyId/walks?week=:weekNumber
+- Dogs Displayed: All dogs in current user's family
+- Family Members: All members in current user's family
+
+**Configuration:**
+- Initial View: Current week, scrolled to today
+- Time Slots: 4 hardcoded (8-11, 12-13, 15-17, 18-20)
+```
+
+**Component File:**
+```markdown
+**Visual Specifications:**
+- 6 walk states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED)
+- Week circles: 7 days with quarter segments
+- Leaderboard cards: Avatar + badge + name
+
+**Content Slots:**
+- Header text (configurable per page)
+- Time slot labels (configurable)
+```
+
+**Feature File:**
+```markdown
+**Generic Content:**
+- Empty state: "Add a dog to start planning walks"
+- Error message: "Failed to load walks"
+- Countdown format: "32 min left" / "32 min kvar"
+- Duration format: "32 min walk" / "32 min promenad"
+
+**Interactions:**
+- Book walk → GRAY state
+- Start walk → BLUE state
+- Complete walk → GREEN state
+- Miss walk → RED state
+
+**Business Rules:**
+- One active walk per dog
+- Can't book if slot taken
+- Countdown starts at slot start time
+
+**API Endpoints:**
+- GET /api/families/:familyId/walks?week=:weekNumber
+- POST /api/walks (create booking)
+- PUT /api/walks/:walkId/start
+- PUT /api/walks/:walkId/complete
+```
+
+---
+
+### Example 4: Submit Button
+
+**Scenario:** Submit button appears on multiple forms, always says "Submit"
+
+**Page File:**
+```markdown
+**Position:** Bottom of form, right-aligned
+**Size:** Full-width on mobile, auto-width on desktop
+
+**Component:** `button-primary.component.md`
+**Feature:** `form-submit-logic.feature.md`
+
+(No page-specific content - button text is always "Submit")
+```
+
+**Component File:**
+```markdown
+**Visual Specifications:**
+- Background: Blue (#3B82F6)
+- Text: White, 16px Medium
+- Height: 48px
+- Border Radius: 8px
+- States:
+  - Default: Blue background
+  - Hover: Darker blue
+  - Active: Even darker blue
+  - Disabled: Gray background
+  - Loading: Blue background + spinner
+```
+
+**Feature File:**
+```markdown
+**Generic Content:**
+- Button text: "Submit" / "Skicka"
+- Loading text: "Submitting..." / "Skickar..."
+- Success message: "Submitted successfully" / "Skickat"
+- Error message: "Submission failed" / "Misslyckades"
+
+**Interactions:**
+- Click → Validate form
+- If valid → Submit to API
+- If invalid → Show validation errors
+- Show loading state during submission
+```
+
+---
+
+## Decision Matrix
+
+| Content Type | Page-Specific? | Where to Document |
+|--------------|----------------|-------------------|
+| **Hero heading** | ✅ YES (different per page) | Page File |
+| **Hero background image** | ✅ YES (different per page) | Page File |
+| **Search placeholder** | ✅ YES (different per page) | Page File |
+| **Calendar header** | ✅ YES (shows user's family name) | Page File |
+| **API endpoint with user context** | ✅ YES (varies by user/page) | Page File |
+| **Submit button text** | ❌ NO (always "Submit") | Feature File |
+| **Error messages** | ❌ NO (generic validation) | Feature File |
+| **Loading text** | ❌ NO (always "Loading...") | Feature File |
+| **Tooltip text** | ❌ NO (generic interaction) | Feature File |
+| **API endpoint (generic)** | ❌ NO (same for all users) | Feature File |
+| **Button color** | ❌ NO (visual design) | Component File |
+| **Font size** | ❌ NO (visual design) | Component File |
+| **Hover state** | ❌ NO (visual design) | Component File |
+| **Layout spacing** | ❌ NO (visual design) | Component File |
+
+---
+
+## Common Mistakes
+
+### ❌ Mistake 1: Putting page-specific content in Feature file
+
+**Wrong:**
+```markdown
+Features/hero-logic.feature.md
+---
+**Content:**
+- Heading: "Welcome to Dog Week" (Home page)
+- Heading: "About Dog Week" (About page)
+```
+
+**Right:**
+```markdown
+Pages/01-home-page.md
+---
+**Page-Specific Content:**
+- Heading: "Welcome to Dog Week"
+
+Pages/02-about-page.md
+---
+**Page-Specific Content:**
+- Heading: "About Dog Week"
+```
+
+---
+
+### ❌ Mistake 2: Putting generic content in Page file
+
+**Wrong:**
+```markdown
+Pages/01-home-page.md
+---
+**Content:**
+- Submit button: "Submit"
+- Error message: "Invalid email"
+```
+
+**Right:**
+```markdown
+Features/form-submit-logic.feature.md
+---
+**Generic Content:**
+- Submit button: "Submit"
+- Error message: "Invalid email"
+```
+
+---
+
+### ❌ Mistake 3: Putting visual design in Feature file
+
+**Wrong:**
+```markdown
+Features/button-logic.feature.md
+---
+**Visual:**
+- Background: Blue
+- Height: 48px
+- Hover: Darker blue
+```
+
+**Right:**
+```markdown
+Components/button-primary.component.md
+---
+**Visual Specifications:**
+- Background: Blue (#3B82F6)
+- Height: 48px
+- States:
+  - Hover: Darker blue (#2563EB)
+```
+
+---
+
+## Summary
+
+**Content Placement Rule:**
+
+```
+Does content vary by page context?
+├─ YES → Page File
+│        (Hero heading, search placeholder, user-specific data)
+│
+└─ NO → Feature File
+         (Button text, error messages, generic tooltips)
+
+Is this visual design?
+└─ YES → Component File
+         (Colors, spacing, states, typography)
+```
+
+**Key Principle:**
+- **Page File** = WHERE + WHAT (page-specific)
+- **Component File** = HOW IT LOOKS (visual design)
+- **Feature File** = WHAT IT DOES (functionality + generic content)
+
+**Result:**
+- ✅ Clear separation of concerns
+- ✅ Easy to maintain and update
+- ✅ Clean handoffs to designers and developers
+- ✅ No confusion about where content belongs

src/modules/wds/workflows/4-ux-design/CROSS-PAGE-CONSISTENCY.md

@@ -0,0 +1,295 @@
+# Cross-Page Consistency Strategy
+
+**Maintaining Visual Coherence Across Project Sketches**
+
+---
+
+## Core Principle
+
+**Text that looks similar and serves the same role should have the same specification across all pages.**
+
+This creates:
+- ✅ Consistent user experience
+- ✅ Natural design system patterns
+- ✅ Faster specification process
+- ✅ Professional, cohesive design
+
+---
+
+## Workflow: Multi-Page Projects
+
+### Page 1: Start Page (Establish Baseline)
+
+**First page analyzed - establish reference patterns:**
+
+```
+Start Page Analysis:
+├─ Body Text: Thin lines, icon-sized spacing → 16px Regular
+├─ Button Labels: Medium lines → 16px Semibold  
+├─ Page Title: Thick lines, button-height spacing → 48px Bold
+├─ Navigation: Medium lines, small spacing → 14px Medium
+└─ Caption: Thinnest lines, half-icon spacing → 12px Regular
+```
+
+**These become your reference anchors for subsequent pages.**
+
+---
+
+### Page 2: About Page (Apply Patterns)
+
+**When analyzing the About Page sketch:**
+
+#### Step 1: Check Previous Pages
+```
+Agent: "I see you've already analyzed the Start Page. 
+I'll use those text styles as reference points."
+```
+
+#### Step 2: Match Visual Patterns
+```
+About Page body text:
+- Thin lines ✓
+- Icon-sized spacing ✓
+- Left-aligned ✓
+
+→ Matches Start Page body text pattern
+→ Apply same spec: 16px Regular
+```
+
+#### Step 3: Confirm with Designer
+```
+Agent: "This body text looks identical to Start Page body text.
+Should I use the same specification (16px Regular)?"
+
+Designer: "Yes!" or "No, make it 18px"
+```
+
+---
+
+## Pattern Matching Rules
+
+### When to Apply Same Specification
+
+**Match if ALL criteria align:**
+
+1. **Visual Similarity**
+   - Line thickness matches (relative to other elements)
+   - Spacing matches (relative to UI anchors)
+   - Alignment matches
+
+2. **Functional Role**
+   - Serves same purpose (e.g., both are body paragraphs)
+   - Same content type (e.g., both are descriptions)
+   - Same hierarchy level
+
+3. **Context**
+   - Similar page sections (e.g., both in main content area)
+   - Similar surrounding elements
+
+### When to Create New Specification
+
+**Create new spec if:**
+
+- Visual appearance differs (thicker lines, different spacing)
+- Functional role differs (e.g., one is a quote, one is body text)
+- Designer explicitly requests different styling
+- Context requires emphasis/de-emphasis
+
+---
+
+## Design System Integration
+
+### Automatic Pattern Building
+
+As you analyze pages, WDS naturally builds design system patterns:
+
+```
+Project: Dog Week
+
+Text Styles Identified:
+├─ heading-xl: 48px Bold (Page titles)
+├─ heading-lg: 36px Bold (Section headings)
+├─ heading-md: 24px Semibold (Subsection headings)
+├─ body-text: 16px Regular (Paragraphs)
+├─ button-label: 16px Semibold (All buttons)
+├─ caption: 12px Regular (Helper text)
+└─ nav-item: 14px Medium (Navigation)
+
+Components Identified:
+├─ Feature Card (used on Start, Features, About pages)
+├─ Navigation Bar (used on all pages)
+├─ Footer (used on all pages)
+└─ CTA Button (used on Start, Pricing pages)
+```
+
+### Benefits
+
+**Without explicit design system:**
+- Maintains consistency through pattern recognition
+- Reduces specification time (reference previous pages)
+- Creates professional, cohesive experience
+
+**With explicit design system:**
+- Automatically maps to existing components
+- Validates sketch against design system
+- Suggests design system updates when new patterns emerge
+
+---
+
+## Agent Behavior Examples
+
+### Example 1: Exact Match
+
+```
+Agent: "I'm analyzing the Contact Page body text.
+
+Visual Analysis:
+- Line thickness: Thinnest (matches Start Page body text)
+- Spacing: Icon-sized (matches Start Page body text)
+- Alignment: Left (matches Start Page body text)
+
+Pattern Match: Start Page body text (16px Regular)
+
+Should I use the same specification?"
+
+Designer: "Yes, keep it consistent."
+
+Agent: "✅ Applied: 16px Regular (consistent with Start Page)"
+```
+
+### Example 2: Intentional Variation
+
+```
+Agent: "I'm analyzing the Testimonial Quote text.
+
+Visual Analysis:
+- Line thickness: Medium (thicker than body text)
+- Spacing: Slightly larger than body text
+- Alignment: Center (different from body text)
+
+This looks different from body text. Should this be:
+1. New style: 18px Medium, center-aligned (emphasis)
+2. Same as body: 16px Regular (consistency)
+
+Your choice?"
+
+Designer: "Option 1 - quotes should stand out."
+
+Agent: "✅ Created new style: testimonial-quote (18px Medium)"
+```
+
+### Example 3: Component Recognition
+
+```
+Agent: "I'm analyzing the Features section on the Pricing Page.
+
+Component Match Detected:
+- Layout: 3-column card grid ✓
+- Card structure: Icon + Title + Description ✓
+- Visual style: Matches Features section from Start Page ✓
+
+This looks like the same 'Feature Card' component.
+Should I:
+1. Reference existing component (recommended)
+2. Create page-specific version
+
+Your choice?"
+
+Designer: "Option 1 - it's the same component."
+
+Agent: "✅ Referenced: Feature Card component (defined on Start Page)"
+```
+
+---
+
+## Best Practices
+
+### For Designers
+
+1. **Be Consistent in Sketches**
+   - Use same line thickness for same text types
+   - Use same spacing patterns across pages
+   - Helps AI recognize patterns automatically
+
+2. **Confirm Pattern Matches**
+   - When AI suggests pattern match, verify it's intentional
+   - Speak up if variation is desired
+
+3. **Build Design System Gradually**
+   - First few pages establish patterns
+   - Later pages reference patterns
+   - Natural evolution into design system
+
+### For AI Agents
+
+1. **Always Check Previous Pages First**
+   - Before analyzing text, look for established patterns
+   - Show detected patterns to designer for transparency
+
+2. **Ask, Don't Assume**
+   - Even if visual match is strong, confirm with designer
+   - Designer may have intentional variation
+
+3. **Track Pattern Usage**
+   - Note which pages use which patterns
+   - Helps identify true design system components
+
+---
+
+## Implementation in WDS Workflow
+
+### Step 1: Holistic Sketch Reading
+
+```
+<action>
+1. Check if other pages in project have been analyzed
+2. Load established text style patterns
+3. Identify UI anchors in current sketch
+4. Use previous pages + UI elements to calibrate scale
+</action>
+```
+
+### Step 2: Pattern Detection
+
+```
+<action>
+For each text element in current sketch:
+1. Analyze visual properties (thickness, spacing, alignment)
+2. Compare to established patterns from previous pages
+3. If match found → suggest applying same specification
+4. If no match → analyze using UI anchors + relative measurements
+</action>
+```
+
+### Step 3: Designer Confirmation
+
+```
+<output>
+Text Element: Body paragraph in "About Us" section
+
+Pattern Match: Start Page body text
+- Visual: Thin lines, icon-sized spacing ✓
+- Functional: Paragraph description ✓
+- Specification: 16px Regular
+
+Apply same specification?
+</output>
+
+<ask>
+1. Yes - Use 16px Regular (consistent)
+2. No - I want different styling
+</ask>
+```
+
+---
+
+## Summary
+
+**Cross-page consistency is achieved through:**
+
+1. **Pattern Recognition** - AI identifies similar visual patterns across pages
+2. **Reference Anchors** - First pages establish baseline specifications
+3. **Designer Confirmation** - AI suggests matches, designer validates
+4. **Natural Design System** - Patterns emerge organically from consistent application
+
+**Result:** Professional, cohesive multi-page designs with minimal specification overhead.

src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md

@@ -82,40 +82,83 @@ Justified/Full-width text:
 
 ---
 
+## Step 0: Establish Scale Using Project Context
+
+**Before analyzing individual text elements, establish your reference points:**
+
+### 1. Check Previous Pages in Project
+
+If analyzing multiple pages in the same project:
+
+**Look for established patterns:**
+```
+Start Page (already analyzed):
+- Body text: Thin lines, icon-sized spacing → 16px Regular
+- Button labels: Medium lines → 16px Semibold
+- Page title: Thick lines, button-height spacing → 48px Bold
+
+Current Page (About Page):
+- Similar thin lines, icon-sized spacing → **Same: 16px Regular**
+- Similar medium lines in buttons → **Same: 16px Semibold**
+```
+
+**Design System Integration:**
+- If project has a design system, match visual patterns to existing components
+- Body text that looks like Start Page body text → Use same specification
+- Buttons that look like Start Page buttons → Use same specification
+
+**Benefits:**
+- ✅ Maintains consistency across all pages
+- ✅ Builds reusable design patterns
+- ✅ Reduces specification time for subsequent pages
+- ✅ Creates cohesive user experience
+
+### 2. Find UI Anchors in Current Sketch
+
+- Browser chrome (address bar, scrollbars)
+- Standard UI elements (buttons, icons, form inputs)
+- Use these to calibrate scale for this specific sketch resolution
+
+---
+
 ## Analysis Rules
 
-### 1. Line Thickness → Font Weight
+### 1. Line Thickness → Font Weight (Relative)
 
 **Line thickness indicates font weight (bold/regular), NOT font size**
 
-| Line Thickness | Font Weight | CSS Value | Typical Use |
+**Compare lines RELATIVE to each other within the sketch:**
-|----------------|-------------|-----------|-------------|
-| 4-5px thick (═══) | Bold | font-weight: 700 | Headlines, strong emphasis |
-| 3px thick (═══) | Semibold | font-weight: 600 | Subheadings, medium emphasis |
-| 2px medium (──) | Medium | font-weight: 500 | Slightly emphasized text |
-| 1px normal (──) | Regular | font-weight: 400 | Body text, normal content |
-| <1px thin (─) | Light | font-weight: 300 | Subtle text, de-emphasized |
 
-### 2. Distance Between Lines → Font Size
+| Relative Thickness | Font Weight | CSS Value | Typical Use |
+|-------------------|-------------|-----------|-------------|
+| Thickest (═══) | Bold | font-weight: 700 | Headlines, strong emphasis |
+| Thick (═══) | Semibold | font-weight: 600 | Subheadings, medium emphasis |
+| Medium (──) | Medium | font-weight: 500 | Slightly emphasized text |
+| Thin (──) | Regular | font-weight: 400 | Body text, normal content |
+| Thinnest (─) | Light | font-weight: 300 | Subtle text, de-emphasized |
 
-**The vertical spacing between lines indicates font size**
+**Don't measure pixels—compare thickness relative to other text in the same sketch.**
 
-| Distance Between Lines | Estimated Font Size | Typical Use |
+### 2. Distance Between Lines → Font Size (Context-Based)
-|------------------------|---------------------|-------------|
-| 42-50px | 36-48px | H1 - Page titles |
-| 32-40px | 28-36px | H2 - Section headings |
-| 24-30px | 20-28px | H3 - Subsection headings |
-| 18-24px | 14-20px | Body text / Paragraphs |
-| 12-16px | 10-14px | Captions / Helper text |
 
-**⚠️ Important:** If distance is very large (>60px), verify this is text and not an image placeholder or colored box!
+**The vertical spacing between lines indicates font size—compare to UI elements**
+
+| Spacing Relative To | Estimated Font Size | Typical Use |
+|---------------------|---------------------|-------------|
+| Button Height | ~40-48px | Large Heading - Page titles |
+| Address Bar Height | ~32-40px | Medium Heading - Section headings |
+| Between Button & Icon | ~24-32px | Small Heading - Subsection headings |
+| Icon/Scrollbar Size | ~16-24px | Body text / Paragraphs |
+| Half Icon Size | ~12-16px | Captions / Helper text |
+
+**⚠️ Important:** If spacing seems disproportionately large (>2x button height), verify this is text and not an image placeholder or colored box!
 
 ### 2a. Visual Examples: Text vs. Image Confusion
 
 **TEXT - Normal spacing:**
 ```
 ═══════════════════════════════  ← Bold line
-                                  ← 42px distance
+                                  ← ~Button Height
 ═══════════════════════════════  ← Bold line
 
 This is clearly TEXT (H1 heading)
@@ -125,7 +168,7 @@ This is clearly TEXT (H1 heading)
 ```
 ═══════════════════════════════  ← Line?
                                   
-                                  ← 80px+ distance (too large!)
+                                  ← Much larger than any UI element!
                                   
 ═══════════════════════════════  ← Line?
 
@@ -133,7 +176,7 @@ This might be an IMAGE PLACEHOLDER or COLORED BOX, not text!
 Ask user to confirm.
 ```
 
-**When in doubt:** If distance >60px, ask: "Is this text or an image/box?"
+**When in doubt:** If spacing is disproportionately large compared to UI elements, ask: "Is this text or an image/box?"
 
 ### 3. Text Alignment → Horizontal Position
 
@@ -219,14 +262,14 @@ Left-aligned:           Center-aligned:        Right-aligned:
 
 ### 5. Characters Per Line
 
-**Based on font size and line width:**
+**Based on estimated font size and line width:**
 
 ```
-Font 48px:  ═══════════════════     = ~20-25 chars
+Large Heading (~48px):  ═══════════════════     = ~20-25 chars
-Font 36px:  ═══════════════════════ = ~25-30 chars
+Medium Heading (~36px): ═══════════════════════ = ~25-30 chars
-Font 24px:  ─────────────────────── = ~40-50 chars
+Small Heading (~24px):  ─────────────────────── = ~40-50 chars
-Font 16px:  ──────────────────────────────── = ~60-70 chars
+Body Text (~16px):      ──────────────────────────────── = ~60-70 chars
-Font 12px:  ──────────────────────────────────── = ~80-90 chars
+Caption (~12px):        ──────────────────────────────────── = ~80-90 chars
 ```
 
 ---
@@ -242,13 +285,14 @@ Font 12px:  ──────────────────────
 ```
 
 **Analysis:**
-- **Type:** H1 Heading
+- **Type:** Large Heading (Page Title)
 - **Lines:** 2
-- **Line thickness:** 4px → **Bold** (font-weight: 700)
+- **Line thickness:** Thickest in sketch → **Bold** (font-weight: 700)
-- **Distance between lines:** 42px → **42px font-size**
+- **Distance between lines:** Matches button height → **~40-48px font-size**
 - **Line-height:** ~1.2 (calculated from spacing)
 - **Alignment:** Center
 - **Capacity:** ~25-30 chars per line = 50-60 total
+- **Semantic HTML:** Determined by page structure (likely H1 if page title)
 
 **Content Guidance:**
 ```
@@ -269,8 +313,8 @@ Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅
 **Analysis:**
 - **Type:** Body text / Paragraph
 - **Lines:** 4
-- **Line thickness:** 1px → **Regular** (font-weight: 400)
+- **Line thickness:** Thinnest in sketch → **Regular** (font-weight: 400)
-- **Distance between lines:** 24px → **16px font-size**
+- **Distance between lines:** Matches icon/scrollbar size → **~16-20px font-size**
 - **Line-height:** ~1.5 (calculated from spacing)
 - **Alignment:** Left
 - **Capacity:** ~60-70 chars per line = 240-280 total
@@ -298,8 +342,8 @@ vård de behöver." (218 chars) ✅
 **Analysis:**
 - **Type:** Button label
 - **Lines:** 1
-- **Line thickness:** 2px → **Semibold** (font-weight: 600)
+- **Line thickness:** Medium (relative) → **Semibold** (font-weight: 600)
-- **Estimated font-size:** 16-18px (button standard)
+- **Estimated font-size:** ~16-18px (button standard)
 - **Capacity:** ~8-12 characters
 
 **Content Guidance:**
@@ -319,26 +363,29 @@ When analyzing sketches with text placeholders:
 How many horizontal bar groups do you see?
 ```
 
-### Step 2: Measure Line Thickness → Font Weight
+### Step 2: Compare Line Thickness → Font Weight
 ```
-Line thickness indicates font weight:
+Line thickness indicates font weight (RELATIVE comparison):
-- Very thick (4-5px) → Bold (font-weight: 700)
+- Thickest lines → Bold (font-weight: 700)
-- Thick (3px) → Semibold (font-weight: 600)
+- Thick lines → Semibold (font-weight: 600)
-- Normal (2px) → Medium (font-weight: 500)
+- Medium lines → Medium (font-weight: 500)
-- Thin (1px) → Regular (font-weight: 400)
+- Thin lines → Regular (font-weight: 400)
-- Very thin (<1px) → Light (font-weight: 300)
+- Thinnest lines → Light (font-weight: 300)
 ```
 
-### Step 3: Measure Distance Between Lines → Font Size
+### Step 3: Compare Distance to UI Elements → Font Size
 ```
-Vertical distance between horizontal lines:
+Vertical spacing relative to context anchors:
-- 42-50px → 36-48px font (H1)
+- Matches Button Height → ~40-48px font (Large Heading)
-- 32-40px → 28-36px font (H2)
+- Matches Address Bar → ~32-40px font (Medium Heading)
-- 24-30px → 20-28px font (H3)
+- Between Button & Icon → ~24-32px font (Small Heading)
-- 18-24px → 14-20px font (Body)
+- Matches Icon/Scrollbar → ~16-24px font (Body Text)
-- 12-16px → 10-14px font (Caption)
+- Half Icon Size → ~12-16px font (Caption/Small Text)
 
-⚠️ If distance is >60px, verify this is text (not image/box)!
+⚠️ If spacing is disproportionately large, verify this is text (not image/box)!
+
+NOTE: Visual size ≠ Semantic HTML level (H1/H2/H3).
+Semantic heading levels are determined by content structure, not appearance.
 ```
 
 ### Step 4: Calculate Line-Height
@@ -415,8 +462,9 @@ Consider shortening or increasing font size.
 >
 > **Analysis:**
 > - 2 lines of text (thick bars)
-> - Line thickness: 3px → ~28-32px font
+> - Line thickness: Thick (relative) → Bold weight
-> - Spacing: 3px → ~1.3 line-height
+> - Spacing: Less than button height → ~28-32px font
+> - Line-height: ~1.3 (calculated)
 > - Alignment: Center
 > - Capacity: ~50-60 characters (25-30 per line)
 >

src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md

@@ -8,9 +8,27 @@
 
 **Before analyzing specific text, scan the ENTIRE sketch to establish scale.**
 
-1. **Find Anchors:** Look for standard UI elements (Browser chrome, Scrollbars, Buttons, Icons).
+1. **Find UI Anchors:** Look for standard UI elements (Browser chrome, Scrollbars, Buttons, Icons).
-2. **Determine Base Unit:** If a Scrollbar is "Standard Width" (e.g., 16px), how big is everything else relative to it?
+2. **Check Project References:** Look at other sketches in the same project for established text styles.
-3. **Calibrate:** Use these known objects to calibrate your eye for this specific image resolution.
+3. **Determine Base Unit:** If a Scrollbar is "Standard Width" (e.g., 16px), how big is everything else relative to it?
+4. **Calibrate:** Use these known objects to calibrate your eye for this specific image resolution.
+
+### Cross-Page Reference Strategy
+
+**If body text was defined on the Start Page:**
+- Start Page body text: Spacing matches icon size → 16px Regular
+- **Current page:** Similar thin lines with icon-sized spacing → **Same: 16px Regular**
+
+**Benefits:**
+- ✅ Maintains visual consistency across pages
+- ✅ Builds design system patterns naturally
+- ✅ Reduces guesswork on subsequent pages
+- ✅ Creates coherent user experience
+
+**When to use:**
+- Body text, captions, button labels (common across pages)
+- Navigation items (should be identical)
+- Form labels and inputs (standardized patterns)
 
 ---
 
@@ -35,7 +53,7 @@
 ```
 [ Button ]           ← Standard height ref (~40-48px)
    ↕
-═══════════════════  ← Matches button height? ~40px font (H1)
+═══════════════════  ← Matches button height? ~40-48px (Large Heading)
       ↕
 ═══════════════════
 ```
@@ -48,6 +66,8 @@
 
 **Rule:** Use these anchors to estimate the scale of text spacing.
 
+**Note:** Visual size ≠ Semantic HTML (H1/H2/H3). Heading levels are determined by document structure, not appearance.
+
 ---
 
 ## Complete Analysis Pattern
@@ -63,7 +83,7 @@
 
 **Analysis:**
 - **Context:** Spacing looks similar to the "Sign In" button height nearby.
-- **Inference:** If button is ~48px, this font is ~48px (H1).
+- **Inference:** If button is ~48px, this font is ~48px (Large Heading).
 - **Weight:** Thicker than body text markers → **Bold**.
 - **Result:** `font: bold 48px / 1.2`
 
@@ -71,7 +91,7 @@
 
 ## Common Patterns
 
-### H1 Heading
+### Large Heading (Page Title)
 ```
 ═══════════════════  ← Thickest lines
       ↕
@@ -80,7 +100,7 @@
 - **Clue:** Spacing matches Address Bar height (~40px)
 - **Est:** ~40-48px, Bold
 
-### H2 Heading
+### Medium Heading (Section Title)
 ```
 ═══════════════════  ← Medium-Thick lines
       ↕
@@ -89,7 +109,7 @@
 - **Clue:** Spacing is slightly less than button height
 - **Est:** ~32px, Semibold
 
-### Body Text
+### Body Text (Paragraph)
 ```
 ─────────────────────  ← Thinnest lines
     ↕
@@ -136,8 +156,8 @@ See horizontal lines?
     │   └─ Thinner than avg? → Regular
     │
     ├─ Compare DISTANCE (Context)
-    │   └─ Matches Button Height? → H1 (~40-48px)
+    │   └─ Matches Button Height? → Large Heading (~40-48px)
-    │   └─ Matches Icon Size? → Body (~16-24px)
+    │   └─ Matches Icon Size? → Body Text (~16-24px)
     │   └─ Huge Gap? → Image/Container
     │
     └─ Check Context Anchors

src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-STRATEGY.md

@@ -131,10 +131,10 @@
 **Agent reads:**
 1. **Logo text:** "Dog Week" → suggests as logo content
 2. **H1 actual text:** "Every walk. on time. Every time." → suggests as starting headline
-3. **Marker analysis:** 2 thin lines → body text, 16px, ~120-140 chars
+3. **Marker analysis:** 2 thin lines → body text, spacing matches icon size (~16-20px), ~120-140 chars
 4. **CTA actual text:** "start planning - free forever" → suggests as button label
 5. **Small actual text:** "Never ask whose turn it is again" → suggests as supporting text
-6. **Marker analysis:** 3 thin lines → feature description, 16px, ~180-210 chars
+6. **Marker analysis:** 3 thin lines → feature description, spacing matches icon size (~16-20px), ~180-210 chars
 
 **Agent output:**
 ```
@@ -155,37 +155,41 @@ SE: [Your Swedish translation]
 
 ## Technical Details for Markers
 
-### Line Thickness → Font Weight
+### Line Thickness → Font Weight (Relative)
 
 ```
-═══════════════════  ← 4px = Bold (700)
+═══════════════════  ← Thickest = Bold (700)
-───────────────────  ← 2px = Medium (500)
+───────────────────  ← Medium = Medium (500)
-─────────────────────  ← 1px = Regular (400)
+─────────────────────  ← Thinnest = Regular (400)
 ```
 
-### Distance Between Lines → Font Size
+**Compare relative thickness within the sketch, not absolute pixels.**
+
+### Distance Between Lines → Font Size (Context-Based)
 
 ```
 ═══════════════════
-      ↕ 42px        ← 42px font
+      ↕ ~Button Height  ← H1 (~40-48px)
 ═══════════════════
 
 ───────────────────
-    ↕ 24px          ← ~16px font (body)
+    ↕ ~Icon Size        ← Body (~16-20px)
 ───────────────────
 ```
 
+**Use UI elements (buttons, icons, scrollbars) as scale references.**
+
 ### Complete Example
 
 ```
-═══════════════════  ← 4px thick
+═══════════════════  ← Thickest lines in sketch
-      ↕ 42px
+      ↕ ~Button Height
-═══════════════════  ← 4px thick
+═══════════════════  ← Thickest lines in sketch
 ```
 
 **Analysis:**
-- Thickness: Bold
+- Thickness: Bold (relative to other text)
-- Distance: 42px font
+- Distance: Matches button height (~40-48px)
 - Lines: 2
 - Capacity: ~50-60 chars
 
@@ -219,8 +223,8 @@ SE:
 ```
 Text placeholder detected:
 - 4 horizontal lines
-- Line thickness: 1px → Regular weight
+- Line thickness: Thinnest → Regular weight
-- Distance: 24px → 16px font
+- Distance: Matches icon/scrollbar size → ~16-20px font
 - Capacity: ~240-280 characters
 
 Content for Feature Description:
@@ -259,8 +263,8 @@ When AI analyzes sketch text markers, the workflow is:
 ### Step 1: AI Analyzes Sketch
 Agent detects text markers and estimates properties:
 ```
-Line thickness: 3px → Bold font weight
+Line thickness: Thicker than body text → Bold font weight
-Spacing between pairs: 24px → ~42px font size estimate
+Spacing between pairs: Similar to button height → ~40-48px font size estimate
 Line-height: ~1.2 (calculated from font size)
 Character capacity: ~35 characters per line
 ```
@@ -269,8 +273,8 @@ Character capacity: ~35 characters per line
 Agent shows analysis WITH explanation of how estimates were derived:
 ```markdown
 - **Style**: 
-  - Font weight: Bold (from 3px thick line markers in sketch)
+  - Font weight: Bold (from thick line markers, relative to body text)
-  - Font size: 42px (est. from 24px vertical spacing between line pairs)
+  - Font size: 42px (est. from spacing matching button height)
   - Line-height: 1.2 (est. calculated as font-size × 1.2)
 ```
 
@@ -282,8 +286,8 @@ Agent shows analysis WITH explanation of how estimates were derived:
 
 ### Step 3: Designer Confirms/Adjusts
 Designer reviews estimates and either:
-1. **Confirms** - "Yes, 42px based on 24px spacing is correct"
+1. **Confirms** - "Yes, 42px based on button-height spacing is correct"
-2. **Adjusts** - "Actually, the spacing was 28px, so make it 48px instead"
+2. **Adjusts** - "Actually, the spacing is larger, make it 48px instead"
 3. **Overrides** - "Ignore the sketch measurements, I want it to be 56px"
 
 ### Step 4: Finalize Specification

src/modules/wds/workflows/4-ux-design/STORYBOARD-INTEGRATION.md

@@ -0,0 +1,676 @@
+# Storyboard Integration Guide
+
+**Using Visual Storyboards to Document Complex Component Functionality**
+
+---
+
+## Problem Statement
+
+Complex interactive components (calendars, booking systems, multi-step workflows) have **state transitions** and **interaction flows** that are difficult to describe in text alone.
+
+**Storyboards** provide visual, sequential documentation of:
+- State transitions (e.g., Empty → Booked → Active → Completed)
+- User interactions and system responses
+- Time-based changes (countdowns, timers)
+- Multi-step workflows
+
+---
+
+## Storyboard Types
+
+### 1. **State Transition Storyboards**
+
+**Purpose:** Show how a component changes states over time
+
+**Example:** Dog Week Walk Booking States
+```
+┌─────────────────────────────────────────────────┐
+│  State Transition Storyboard                    │
+│  Component: Walk Time Slot Card                 │
+├─────────────────────────────────────────────────┤
+│                                                 │
+│  1. WHITE (Empty)        → User books           │
+│     [Dog icon] 8-11      → [Book button]        │
+│                                                 │
+│  2. GRAY (Booked)        → Time arrives         │
+│     [Dog+User] 8-11                             │
+│                                                 │
+│  3. ORANGE (Countdown)   → User starts          │
+│     [Dog icon] 32 min left → [Start button]    │
+│                                                 │
+│  4. BLUE (In Progress)   → User completes       │
+│     [Dog+User] Started 09:32 • 23 min ago      │
+│                                                 │
+│  5. GREEN (Completed)    → Final state          │
+│     [Dog+User] 32 min walk ✓                   │
+│                                                 │
+│  Alt: RED (Missed)       → Window expired       │
+│     [Dog icon] No walk registered ⊖            │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+**File:** `Sketches/App-Main-Booking-States.jpg` (Dog Week example)
+
+### 2. **Interaction Flow Storyboards**
+
+**Purpose:** Show step-by-step user interactions
+
+**Example:** Calendar Booking Flow
+```
+Frame 1: User views calendar
+Frame 2: User taps "Book" button
+Frame 3: Card transitions to GRAY state
+Frame 4: Leaderboard updates (+1 point)
+Frame 5: Week overview quarter circle turns gray
+```
+
+### 3. **Multi-Component Storyboards**
+
+**Purpose:** Show how multiple components interact
+
+**Example:** Week View + Leaderboard + Calendar Sync
+```
+Frame 1: User clicks day circle in week overview
+Frame 2: Calendar scrolls to that day
+Frame 3: User books walk
+Frame 4: Week overview quarter circle updates
+Frame 5: Leaderboard count increments
+```
+
+---
+
+## Integration with Modular Structure
+
+### Where Storyboards Belong
+
+| File Type | Contains Storyboard? | Purpose |
+|-----------|---------------------|---------|
+| **Pages/** | ❌ No | Page layout only |
+| **Components/** | ⚠️ Visual states only | Static appearance of each state |
+| **Features/** | ✅ YES | State transitions & interaction flows |
+
+### Storyboard Storage
+
+```
+project-root/
+├─ Pages/
+│  └─ 02-calendar-page.md
+│
+├─ Components/
+│  └─ walk-slot-card.component.md
+│
+├─ Features/
+│  ├─ walk-booking-logic.feature.md
+│  └─ Storyboards/                    ← NEW FOLDER
+│     ├─ walk-state-transitions.jpg
+│     ├─ booking-flow.jpg
+│     └─ calendar-sync-flow.jpg
+│
+└─ Sketches/                          ← Existing page sketches
+   └─ 02-calendar-page-sketch.jpg
+```
+
+---
+
+## Feature File with Storyboard Reference
+
+### Example: `walk-booking-logic.feature.md`
+
+```markdown
+# Walk Booking Logic Feature
+
+**Feature ID:** `walk-booking-logic`
+**Type:** State Machine with Time-Based Transitions
+**Complexity:** High
+
+## Purpose
+
+Manages walk slot state transitions, user booking interactions, and automatic time-based state changes for the Dog Week calendar.
+
+---
+
+## Visual Storyboard
+
+**State Transition Flow:**
+
+![Walk State Transitions](Storyboards/walk-state-transitions.jpg)
+
+**Key:** This storyboard shows all 6 walk states and the triggers that cause transitions between them.
+
+---
+
+## State Definitions
+
+### State 1: WHITE (Empty / Available)
+
+**Visual Reference:** Storyboard Frame 1
+
+**Appearance:**
+- White background
+- Dog avatar only (no user avatar)
+- Time range: "8-11"
+- Action button: "Book" / "Boka"
+
+**Triggers:**
+- Initial state for all unbooked slots
+- Appears when walk is unbooked
+
+**Transitions:**
+- User clicks "Book" → GRAY (Booked)
+
+**Business Rules:**
+- Any family member can book
+- Booking awards +1 leaderboard point
+- Updates week overview quarter circle to gray
+
+---
+
+### State 2: GRAY (Booked / Scheduled)
+
+**Visual Reference:** Storyboard Frame 2
+
+**Appearance:**
+- Gray background
+- Dog avatar + User avatar overlay
+- Names: "Rufus & Patrick"
+- Time range: "8-11"
+- No action button (tap card for details)
+
+**Triggers:**
+- User books empty slot (WHITE → GRAY)
+- Walk is scheduled but time window not yet open
+
+**Transitions:**
+- Time window opens (8:00 arrives) → ORANGE (Countdown)
+- User unbooks walk → WHITE (Empty)
+
+**Business Rules:**
+- Shows who booked the walk
+- Tap card to view details/unbook
+- Leaderboard point already awarded
+
+---
+
+### State 3: ORANGE (Window Open / Countdown)
+
+**Visual Reference:** Storyboard Frame 3
+
+**Appearance:**
+- Orange background
+- Dog avatar only (user avatar removed)
+- Countdown timer: "32 min left" / "32 min kvar"
+- Warning icon: ⚠️
+- Action button: "Start" / "Starta"
+
+**Triggers:**
+- Scheduled time arrives (8:00) → GRAY to ORANGE
+- Real-time countdown updates every minute
+
+**Transitions:**
+- User clicks "Start" → BLUE (In Progress)
+- Countdown reaches 0 (11:00) → RED (Missed)
+
+**Business Rules:**
+- Countdown shows time remaining in window
+- Urgency indicator (warning icon)
+- Can only start if no other walk active for this dog
+
+---
+
+### State 4: BLUE (In Progress / Active Walk)
+
+**Visual Reference:** Storyboard Frame 4
+
+**Appearance:**
+- Blue background
+- Dog avatar + User avatar overlay
+- Status: "Started 09:32 • 23 min ago"
+- Refresh icon: ↻
+- No action button (tap card for completion)
+
+**Triggers:**
+- User starts walk (ORANGE → BLUE)
+- Real-time duration updates every minute
+
+**Transitions:**
+- User completes walk → GREEN (Completed)
+
+**Business Rules:**
+- Blocks other walks for this dog
+- Shows elapsed time since start
+- Tap card to complete walk or view progress
+
+---
+
+### State 5: GREEN (Completed)
+
+**Visual Reference:** Storyboard Frame 5
+
+**Appearance:**
+- Green background
+- Dog avatar + User avatar overlay
+- Duration: "32 min walk" / "32 min promenad"
+- Checkmark icon: ✓
+- No action button
+
+**Triggers:**
+- User completes active walk (BLUE → GREEN)
+
+**Transitions:**
+- None (final successful state)
+
+**Business Rules:**
+- Permanent record of completed walk
+- Shows actual walk duration
+- Unblocks dog for next walk
+
+---
+
+### State 6: RED (Missed / Overdue)
+
+**Visual Reference:** Storyboard Frame 6
+
+**Appearance:**
+- Red background
+- Dog avatar only (no user avatar)
+- Message: "No walk registered" / "Ingen promenad registrerad"
+- Minus icon: ⊖
+- No action button
+
+**Triggers:**
+- Countdown expires without walk being started (ORANGE → RED)
+
+**Transitions:**
+- None (permanent accountability record)
+
+**Business Rules:**
+- Cannot be changed or deleted
+- Leaderboard point remains (no penalty)
+- Shows who booked but didn't complete
+
+---
+
+## Interaction Flows
+
+### Flow 1: Successful Walk Booking & Completion
+
+**Storyboard:** `Storyboards/booking-flow.jpg`
+
+**Steps:**
+1. **User views empty slot** (WHITE state)
+   - Sees "Book" button
+   
+2. **User taps "Book"**
+   - System validates user is family member
+   - System creates booking record
+   
+3. **Immediate updates:**
+   - Card → GRAY state
+   - Leaderboard: User +1 point
+   - Week overview: Quarter circle → gray
+   
+4. **Time window opens** (8:00 arrives)
+   - Card → ORANGE state
+   - Countdown timer starts
+   
+5. **User taps "Start"**
+   - System validates no other active walk for dog
+   - System records start time
+   
+6. **Immediate updates:**
+   - Card → BLUE state
+   - Duration counter starts
+   - Other walks for dog → disabled
+   
+7. **User completes walk** (via Walk Details page)
+   - System records completion time
+   - System calculates duration
+   
+8. **Immediate updates:**
+   - Card → GREEN state
+   - Week overview: Quarter circle → green
+   - Other walks for dog → re-enabled
+
+---
+
+### Flow 2: Missed Walk
+
+**Storyboard:** `Storyboards/missed-walk-flow.jpg`
+
+**Steps:**
+1. Walk booked (GRAY state)
+2. Time window opens (ORANGE state)
+3. Countdown timer runs
+4. User doesn't start walk
+5. Countdown reaches 0 (11:00)
+6. **Automatic transition:** ORANGE → RED
+7. Permanent missed walk record created
+
+---
+
+### Flow 3: Multi-Component Sync
+
+**Storyboard:** `Storyboards/calendar-sync-flow.jpg`
+
+**Components Involved:**
+- Week Overview (top section)
+- Leaderboard (middle section)
+- Booking Calendar (bottom section)
+
+**Sync Flow:**
+1. User books walk in calendar
+2. **Sync 1:** Week overview quarter circle updates
+3. **Sync 2:** Leaderboard count increments
+4. User starts walk
+5. **Sync 3:** Week overview quarter circle changes color
+6. User completes walk
+7. **Sync 4:** Week overview quarter circle turns green
+
+---
+
+## State Machine Diagram
+
+```
+                    ┌─────────────┐
+                    │   WHITE     │
+                    │   (Empty)   │
+                    └──────┬──────┘
+                           │ User books
+                           ▼
+                    ┌─────────────┐
+                    │    GRAY     │
+                    │  (Booked)   │
+                    └──────┬──────┘
+                           │ Time arrives
+                           ▼
+                    ┌─────────────┐
+                    │   ORANGE    │◄──── Countdown timer
+                    │ (Countdown) │      updates every 1 min
+                    └──┬───────┬──┘
+                       │       │
+        User starts    │       │ Countdown expires
+                       │       │
+                       ▼       ▼
+                ┌─────────┐ ┌─────────┐
+                │  BLUE   │ │   RED   │
+                │(Active) │ │(Missed) │
+                └────┬────┘ └─────────┘
+                     │           │
+      User completes │           │ Permanent
+                     │           │ record
+                     ▼           ▼
+                ┌─────────┐   [END]
+                │  GREEN  │
+                │(Complete)│
+                └─────────┘
+                     │
+                     ▼
+                   [END]
+```
+
+---
+
+## Storyboard Creation Guidelines
+
+### When to Create Storyboards
+
+Create storyboards for:
+- ✅ Components with 3+ states
+- ✅ Time-based transitions (countdowns, timers)
+- ✅ Multi-step user flows
+- ✅ Complex interactions between multiple components
+- ✅ State machines with branching paths
+
+Don't need storyboards for:
+- ❌ Simple buttons (hover, active states)
+- ❌ Static content sections
+- ❌ Single-state components
+
+### Storyboard Format
+
+**Hand-drawn sketches** (recommended):
+- Quick to create
+- Easy to iterate
+- Focus on functionality, not polish
+- Example: Dog Week `App-Main-Booking-States.jpg`
+
+**Digital wireframes:**
+- Use Figma, Sketch, or similar
+- More polished for client presentations
+- Easier to update
+
+**Annotated screenshots:**
+- Use actual prototype screenshots
+- Add arrows and labels
+- Good for documenting existing systems
+
+### Storyboard Numbering
+
+Number frames sequentially:
+```
+1. Initial state
+2. After user action
+3. System response
+4. Next state
+5. Alternative path
+```
+
+### Storyboard Annotations
+
+Include:
+- **State names** (e.g., "ORANGE - Countdown")
+- **Trigger descriptions** (e.g., "User taps Start")
+- **Time indicators** (e.g., "After 32 minutes")
+- **Icons/symbols** for actions (→ for transitions, ⚠️ for warnings)
+
+---
+
+## Feature File Template with Storyboard
+
+```markdown
+# {Feature Name} Feature
+
+**Feature ID:** `{feature-id}`
+**Type:** {State Machine / Workflow / Calculator / etc.}
+**Complexity:** {Low / Medium / High}
+
+## Purpose
+
+{Brief description of what this feature does}
+
+---
+
+## Visual Storyboard
+
+**{Storyboard Type}:**
+
+![{Storyboard Name}](Storyboards/{storyboard-file}.jpg)
+
+**Key:** {Brief explanation of what the storyboard shows}
+
+---
+
+## State Definitions
+
+{If applicable - for state machines}
+
+### State 1: {State Name}
+
+**Visual Reference:** Storyboard Frame {number}
+
+**Appearance:**
+- {Visual description}
+
+**Triggers:**
+- {What causes this state}
+
+**Transitions:**
+- {What states this can transition to}
+
+**Business Rules:**
+- {Rules governing this state}
+
+---
+
+## Interaction Flows
+
+### Flow 1: {Flow Name}
+
+**Storyboard:** `Storyboards/{flow-storyboard}.jpg`
+
+**Steps:**
+1. {Step description}
+2. {Step description}
+3. {Step description}
+
+---
+
+## State Machine Diagram
+
+{ASCII diagram showing state transitions}
+
+---
+
+## Data Requirements
+
+{API endpoints, data models, etc.}
+
+---
+
+## Validation Rules
+
+{Business rules, constraints, etc.}
+
+---
+
+## Error Handling
+
+{Error states, recovery flows, etc.}
+```
+
+---
+
+## Dog Week Example: Complete Structure
+
+```
+Features/
+├─ walk-booking-logic.feature.md
+│  ├─ References: Storyboards/walk-state-transitions.jpg
+│  ├─ Contains: 6 state definitions
+│  └─ Contains: State machine diagram
+│
+├─ calendar-sync.feature.md
+│  ├─ References: Storyboards/calendar-sync-flow.jpg
+│  └─ Contains: Multi-component interaction flows
+│
+└─ Storyboards/
+   ├─ walk-state-transitions.jpg       ← Main state storyboard
+   ├─ booking-flow.jpg                 ← Successful booking flow
+   ├─ missed-walk-flow.jpg             ← Missed walk scenario
+   ├─ calendar-sync-flow.jpg           ← Component sync flow
+   └─ week-navigation-flow.jpg         ← Week navigation interactions
+```
+
+---
+
+## Benefits of Storyboard Integration
+
+### 1. Visual Clarity
+
+**Before (Text only):**
+```
+When the user books a walk, the card changes to gray, 
+the leaderboard updates, and the week overview changes.
+```
+
+**After (With storyboard):**
+```
+See Storyboard Frame 2-3 for visual state transition.
+```
+
+### 2. Developer Understanding
+
+Developers can:
+- See exact visual states
+- Understand transition triggers
+- Identify edge cases visually
+- Reference storyboard during implementation
+
+### 3. Design Consistency
+
+Designers can:
+- Ensure all states are visually distinct
+- Verify state transitions make sense
+- Spot missing states or transitions
+- Create Figma components matching storyboard
+
+### 4. QA Testing
+
+QA can:
+- Use storyboard as test script
+- Verify all states are implemented
+- Test all transition paths
+- Identify missing functionality
+
+---
+
+## Workflow Integration
+
+### Step 1: Sketch Storyboard
+
+During UX design phase:
+1. Identify complex interactive components
+2. Sketch state transitions on paper/whiteboard
+3. Number frames sequentially
+4. Add annotations for triggers and transitions
+5. Take photo or scan
+
+### Step 2: Store Storyboard
+
+```
+Features/Storyboards/{component-name}-{type}.jpg
+```
+
+### Step 3: Reference in Feature File
+
+```markdown
+## Visual Storyboard
+
+![Walk State Transitions](Storyboards/walk-state-transitions.jpg)
+```
+
+### Step 4: Document States
+
+For each frame in storyboard:
+- Create state definition
+- Link to storyboard frame number
+- Describe triggers and transitions
+
+### Step 5: Create State Machine
+
+Convert storyboard to ASCII state machine diagram for quick reference
+
+---
+
+## Summary
+
+**Storyboards are essential for:**
+- 🎯 Complex state machines (calendars, booking systems)
+- 🎯 Multi-step workflows (onboarding, checkout)
+- 🎯 Time-based interactions (countdowns, timers)
+- 🎯 Multi-component synchronization
+
+**Store storyboards in:**
+- `Features/Storyboards/` folder
+- Reference from Feature files
+- Link to specific frames in state definitions
+
+**Benefits:**
+- ✅ Visual clarity for developers
+- ✅ Design consistency
+- ✅ QA test scripts
+- ✅ Stakeholder communication
+- ✅ Documentation that doesn't get stale
+
+**Result:** Complex component functionality is documented visually and textually, making implementation and testing straightforward.

src/modules/wds/workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md

@@ -0,0 +1,511 @@
+# Why-Based Specifications
+
+**The critical difference between prompt-and-run vs. thoughtful specification**
+
+---
+
+## The Trigger Map: The Ultimate Why-Machine
+
+**Before any specification, the Trigger Map establishes WHY:**
+
+### Example: Transparent Pricing Feature
+
+**Trigger Map Reasoning:**
+```
+TARGET GROUP: Budget-conscious customers
+FEAR: Surprises and hidden costs
+TRIGGER: Anxiety about final price
+OUTCOME: Easier commitment to purchase
+SOLUTION: Transparent price model explanation
+```
+
+**This WHY flows into specifications:**
+```markdown
+## Transparent Pricing Component
+
+**WHY This Exists:**
+Our main target group is afraid of surprises and hidden costs. 
+By explaining our transparent price model, the customer has an 
+easier time committing to the purchase.
+
+**WHY Upfront (Not at Checkout):**
+Anxiety happens early. Showing pricing transparency upfront 
+reduces fear before it builds.
+
+**WHY Detailed Breakdown (Not Just Total):**
+"No hidden costs" needs proof. Itemized breakdown shows 
+there's nothing hidden.
+
+**WHAT NOT TO DO:**
+- ❌ Don't hide pricing until checkout (increases anxiety)
+- ❌ Don't show just total (doesn't prove transparency)
+- ❌ Don't use fine print (contradicts "transparent")
+```
+
+**The Trigger Map WHY becomes the specification WHY.**
+
+---
+
+## The Problem with v4 WPS2C (Whiteport Sketch-to-Code)
+
+**What happened:**
+```
+Designer: "Create a calendar for booking dog walks"
+AI: *Runs with it*
+Result: Generic calendar, missing the point
+```
+
+**What was missing:**
+- No questioning to elevate thinking
+- No capture of WHY decisions were made
+- No understanding of business context
+- AI "helped" by making assumptions
+
+**Result:** Fast, but wrong. Better, but not right.
+
+---
+
+## The AI Habit Problem
+
+**AI's default behavior:**
+```
+"I'll make this faster!"
+"I'll make this better!"
+"I'll add helpful features!"
+```
+
+**What AI misses:**
+- WHY does this need to exist?
+- WHO is this actually for?
+- WHAT problem does this solve?
+- WHAT should we NOT do?
+
+**AI optimizes for implementation, not intention.**
+
+---
+
+## The Solution: Why-Based Specifications
+
+### Traditional Specification (WHAT)
+
+```markdown
+## Calendar Component
+
+**Features:**
+- Week view
+- Booking slots
+- Color-coded states
+- Countdown timers
+
+**Visual:**
+- 7 columns (days)
+- 6 color states
+- Timer in orange state
+```
+
+**Problem:** AI will implement this literally, but might:
+- Add daily/monthly views ("better!")
+- Add notifications ("helpful!")
+- Make it generic ("reusable!")
+- Miss the cultural context
+
+---
+
+### Why-Based Specification (WHY + WHAT)
+
+```markdown
+## Calendar Component
+
+**WHY This Exists:**
+Families struggle to coordinate dog care. Kids forget, parents nag, 
+dogs suffer. This calendar reduces conflict by making responsibility 
+visible and accountability fun.
+
+**WHY Week View (Not Daily/Monthly):**
+Swedish families think in weeks ("Vecka 40"). This matches their 
+mental model. Daily view is too granular, monthly too abstract.
+→ AI: Don't add daily/monthly views, even if you think it's "better"
+
+**WHY 6 Color States:**
+Visual, instant understanding for kids. No reading required.
+- WHITE: Empty (neutral, inviting)
+- GRAY: Booked (committed, not yet active)
+- ORANGE: Countdown (urgent, act now)
+- BLUE: Active (in progress, can't book another)
+- GREEN: Completed (success, positive reinforcement)
+- RED: Missed (accountability, not punishment)
+
+→ AI: Don't simplify to 3 states, each serves a purpose
+
+**WHY Countdown Timer (Not Notifications):**
+Gentle urgency without nagging. Visible when user checks app.
+Notifications would break the "fun, not punishing" tone.
+→ AI: Don't add push notifications, even if you think it's "helpful"
+
+**WHY Leaderboard Integration:**
+Makes accountability a game, not a chore. Encourages participation.
+→ AI: This is core to the experience, don't make it optional
+
+**WHAT NOT TO DO:**
+- ❌ Don't add daily/monthly views (wrong mental model)
+- ❌ Don't add notifications (wrong tone)
+- ❌ Don't make it generic (Swedish culture specific)
+- ❌ Don't simplify states (each serves a purpose)
+```
+
+---
+
+## What This Enables
+
+### 1. AI Follows Instructions Correctly
+
+**Without WHY:**
+```
+AI: "I added daily view for flexibility!"
+Designer: "No, that breaks the mental model..."
+```
+
+**With WHY:**
+```
+Spec: "Week view matches Swedish 'Vecka 40' culture. Don't add daily view."
+AI: *Implements week view only*
+Designer: ✅ Perfect
+```
+
+---
+
+### 2. AI Knows What to Skip
+
+**Without WHY:**
+```
+AI: "I added push notifications for reminders!"
+Designer: "No, that's nagging, not gentle urgency..."
+```
+
+**With WHY:**
+```
+Spec: "Countdown timer = gentle urgency. Notifications = nagging. Don't add notifications."
+AI: *Skips notifications*
+Designer: ✅ Exactly right
+```
+
+---
+
+### 3. AI Preserves Intent During Changes
+
+**Without WHY:**
+```
+Designer: "Make the countdown more prominent"
+AI: *Makes it bigger, adds sound, adds vibration*
+Designer: "No, that's too aggressive..."
+```
+
+**With WHY:**
+```
+Spec: "Countdown = gentle urgency, not aggressive nagging"
+Designer: "Make countdown more prominent"
+AI: *Makes it bigger, keeps gentle tone*
+Designer: ✅ Got it
+```
+
+---
+
+### 4. Future Developers Understand Context
+
+**Without WHY:**
+```
+Developer: "Why can't users book multiple walks at once?"
+*Removes blocking logic*
+*Breaks the accountability system*
+```
+
+**With WHY:**
+```
+Spec: "One active walk per dog = accountability. Kids can't game the system 
+       by booking everything then completing nothing."
+Developer: "Oh, that's a business rule. I'll keep it."
+```
+
+---
+
+## The Socratic Questioning Connection
+
+**Agent asks WHY questions:**
+```
+Agent: "Why week view instead of daily?"
+Designer: "Swedish families think in weeks..."
+Agent: "Got it! Documenting:
+        WHY: Matches Swedish 'Vecka 40' mental model
+        WHAT NOT TO DO: Don't add daily/monthly views"
+```
+
+**This creates specifications that:**
+- Capture reasoning, not just decisions
+- Guide AI implementation correctly
+- Prevent "helpful" mistakes
+- Preserve intent over time
+
+---
+
+## Structure of Why-Based Specs
+
+### For Each Component/Feature:
+
+**1. WHY This Exists**
+- What problem does it solve?
+- What behavior change does it create?
+- What value does it deliver?
+
+**2. WHY These Specific Choices**
+- Why this approach vs alternatives?
+- What user need does this serve?
+- What business goal does this support?
+
+**3. WHAT NOT TO DO**
+- What "improvements" would break the intent?
+- What features should NOT be added?
+- What assumptions should AI NOT make?
+
+**4. WHAT (Traditional Specs)**
+- Visual design
+- Interactions
+- Technical requirements
+
+---
+
+## Example: Dog Week "Book Walk" Button
+
+### Traditional Spec (WHAT Only)
+
+```markdown
+## Book Walk Button
+
+**Visual:**
+- Blue background (#3B82F6)
+- White text
+- 48px height
+- Rounded corners (8px)
+
+**Action:**
+- Click → Open booking modal
+```
+
+**AI might "improve" by:**
+- Adding "Quick Book" shortcut
+- Adding "Book for Week" bulk action
+- Making it more prominent
+- Adding animation
+
+---
+
+### Why-Based Spec
+
+```markdown
+## Book Walk Button
+
+**WHY This Exists:**
+Kids need a simple way to commit to walking the dog. 
+"Booking" creates accountability - it's a promise, not just a plan.
+
+**WHY "Book Walk" (Not "Add Walk"):**
+"Book" = Future commitment (proactive)
+"Add" = Past logging (retroactive)
+We need both, they serve different purposes.
+
+**WHY Simple Click (Not Quick Actions):**
+Kids should think before booking. One deliberate action = one commitment.
+Quick actions would encourage gaming the system (book everything, complete nothing).
+
+**WHY This Visual Treatment:**
+- Blue = Action color (consistent with design system)
+- 48px = Touch-friendly for kids
+- Not oversized = Important but not aggressive
+
+**WHAT NOT TO DO:**
+- ❌ Don't add "Quick Book" shortcuts (encourages gaming)
+- ❌ Don't add "Book for Week" bulk action (defeats accountability)
+- ❌ Don't make it more prominent (not the only action)
+- ❌ Don't add animation (not a game, it's responsibility)
+
+**WHAT (Implementation):**
+- Background: Blue (#3B82F6)
+- Text: White, 16px Medium
+- Height: 48px
+- Border radius: 8px
+- Action: Click → Open booking modal
+```
+
+**Now AI knows:**
+- What to implement
+- What NOT to add
+- WHY each decision was made
+- How to handle future changes
+
+---
+
+## The Transformation
+
+### v4 WPS2C (Prompt-and-Run)
+```
+Designer: "Create a booking calendar"
+AI: *Generates generic calendar*
+Designer: "No, that's not right..."
+AI: *Tries again, still generic*
+Designer: *Gives up or over-specifies every detail*
+```
+
+### v6 WDS (Why-Based Specifications)
+```
+Designer: "I need a booking calendar"
+Agent: "Help me understand - why week view instead of daily?"
+Designer: "Swedish families think in weeks..."
+Agent: "Got it. Why 6 color states instead of simpler?"
+Designer: "Each state serves a purpose for kids..."
+Agent: "Perfect. Why countdown instead of notifications?"
+Designer: "Gentle urgency, not nagging..."
+
+Agent: "Documenting all the WHYs. This will help AI implement 
+        correctly and prevent 'helpful' mistakes."
+
+*Generates why-based specification*
+
+AI: *Implements exactly right, skips "improvements" that would break intent*
+Designer: ✅ Perfect first time
+```
+
+---
+
+## The Meta-Benefit
+
+**Why-based specifications are:**
+
+✅ **Better for AI implementation**
+- AI knows what NOT to do
+- AI preserves intent during changes
+- AI doesn't "help" incorrectly
+
+✅ **Better for human developers**
+- Understand context, not just requirements
+- Make correct decisions when specs are unclear
+- Maintain intent over time
+
+✅ **Better for future designers**
+- Understand why decisions were made
+- Don't repeat solved problems
+- Build on reasoning, not just patterns
+
+✅ **Better for the designer**
+- Socratic questioning elevates thinking
+- Articulating WHY clarifies decisions
+- Creates reusable design knowledge
+
+---
+
+## The Bottom Line
+
+**Traditional specs answer: "What should we build?"**
+
+**Why-based specs answer:**
+- What should we build?
+- Why should we build it this way?
+- What should we NOT build?
+- How should AI help (and not help)?
+
+**Result:**
+- AI implements correctly first time
+- AI skips "improvements" that break intent
+- Specifications become design knowledge
+- Designer thinking is preserved and amplified
+
+**This is the difference between:**
+- Prompt-and-run (fast but wrong)
+- Why-based specification (thoughtful and right)
+
+---
+
+## The BMad Method Flow
+
+**The complete WHY chain:**
+
+```
+1. TRIGGER MAP (Phase 1: Business Model)
+   ↓
+   Establishes: WHO, WHAT TRIGGERS THEM, WHAT OUTCOME
+   
+2. SCENARIOS (Phase 1: Business Model)
+   ↓
+   Defines: User journeys, contexts, goals
+   
+3. INFORMATION ARCHITECTURE (Phase 2)
+   ↓
+   Structures: Content hierarchy, navigation
+   
+4. INTERACTION DESIGN (Phase 3)
+   ↓
+   Sketches: User flows, state transitions
+   
+5. UX SPECIFICATIONS (Phase 4)
+   ↓
+   Documents: WHY + WHAT + WHAT NOT TO DO
+   
+6. AI IMPLEMENTATION
+   ↓
+   Builds: Correctly, preserving intent
+```
+
+**Each phase carries WHY forward:**
+
+- **Trigger Map** → WHY the business exists
+- **Scenarios** → WHY users need this
+- **IA** → WHY this structure
+- **Interaction** → WHY this flow
+- **UX Specs** → WHY these specific choices
+- **AI** → Implements with full context
+
+**Without Trigger Map, specifications lose their foundation.**
+
+**With Trigger Map, every decision traces back to user needs and business goals.**
+
+---
+
+## The Bottom Line
+
+**Traditional specs answer: "What should we build?"**
+
+**Why-based specs answer:**
+- What should we build?
+- Why should we build it this way?
+- What should we NOT build?
+- How should AI help (and not help)?
+
+**Trigger Map provides the ultimate WHY:**
+- WHO is this for?
+- WHAT triggers their need?
+- WHAT outcome do they want?
+- WHY will this solution work?
+
+**Result:**
+- AI implements correctly first time
+- AI skips "improvements" that break intent
+- Specifications become design knowledge
+- Designer thinking is preserved and amplified
+
+**This is the difference between:**
+- Prompt-and-run (fast but wrong)
+- Why-based specification (thoughtful and right)
+
+---
+
+**Trigger Map establishes WHY.**
+
+**Socratic questioning reveals WHY.**
+
+**Why-based specifications capture WHY.**
+
+**AI implementation preserves WHY.**
+
+**Designer thinking flows through the entire process.**
+
+---
+
+[← Back to Workflows](README.md)

src/modules/wds/workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md

@@ -0,0 +1,59 @@
+# Modular Component Architecture
+
+**Navigation hub for the three-tier specification system**
+
+---
+
+## Foundation (00-)
+
+### [Agent-Designer Collaboration](00-foundation/agent-designer-collaboration.md)
+How AI agents optimize designer craft without replacing designer thinking
+
+---
+
+## Core Concepts (01-)
+
+### [Three-Tier Architecture](01-core-concepts/three-tier-overview.md)
+Overview of Pages, Components, and Features separation
+
+### [Content Placement Rules](01-core-concepts/content-placement-rules.md)
+Decision tree for where to document content
+
+### [Complexity Detection](01-core-concepts/complexity-detection.md)
+How to identify simple vs complex components
+
+---
+
+## Workflows (02-)
+
+### [Page Specification Workflow](02-workflows/page-specification-workflow.md)
+Step-by-step page decomposition from sketch to specs
+
+### [Complexity Router Workflow](02-workflows/complexity-router-workflow.md)
+Guided decomposition for complex components
+
+### [Storyboard Integration](02-workflows/storyboards/storyboards-guide.md)
+Using visual storyboards for complex components
+
+---
+
+## Examples
+
+### [Simple Component Example](examples/simple-button.md)
+Button - single file documentation
+
+### [Complex Component Example](examples/complex-calendar.md)
+Calendar - three-tier decomposition
+
+### [Search Bar Example](examples/search-bar.md)
+Search with page-specific content
+
+---
+
+## Quick References (03-)
+
+### [Decision Tree](03-quick-refs/decision-tree.md)
+One-page flowchart for file placement
+
+### [Benefits Summary](03-quick-refs/benefits.md)
+Why this architecture works

src/modules/wds/workflows/4-ux-design/modular-architecture/00-foundation/agent-designer-collaboration.md

@@ -0,0 +1,443 @@
+# Agent-Designer Collaboration in UX Design
+
+**How AI agents optimize designer craft without replacing designer thinking**
+
+---
+
+## The Partnership Model
+
+**Designer:** Strategic thinking, multi-dimensional decisions, creative problem-solving  
+**Agent:** Systematic execution, pattern recognition, documentation assistance
+
+**Not replacement. Amplification.**
+
+---
+
+## What Agents CANNOT Do
+
+❌ **Understand business context**
+- Why does this business exist?
+- What are the real goals?
+- What defines success?
+
+❌ **Know user needs deeply**
+- Who are the actual users?
+- What are their mental models?
+- What contexts do they operate in?
+
+❌ **Make strategic decisions**
+- Should we build this feature?
+- Does this serve the user or just the business?
+- What's the coherent storyline?
+
+❌ **Balance competing priorities**
+- Business goals vs user needs
+- Simplicity vs functionality
+- Technical viability vs ideal experience
+
+**These require human judgment, empathy, and multi-dimensional thinking.**
+
+---
+
+## What Agents DO Brilliantly
+
+✅ **Systematic decomposition**
+```
+Designer: "This calendar is complex"
+Agent: "I detect 6 states, time-based transitions, business rules.
+        Let me guide you through decomposition:
+        - Page context
+        - Visual design
+        - Functional logic"
+```
+
+✅ **Pattern recognition**
+```
+Designer: "I'm adding body text here"
+Agent: "I notice on Start Page, body text was 16px with 1.5 line-height.
+        Should I use the same for consistency?"
+```
+
+✅ **Documentation assistance**
+```
+Designer: "The walk slot has different colors"
+Agent: "Let me capture that systematically:
+        - WHITE: Empty slot
+        - GRAY: Booked
+        - ORANGE: Countdown active
+        - BLUE: Walk in progress
+        - GREEN: Completed
+        - RED: Missed"
+```
+
+✅ **Workflow guidance**
+```
+Designer: "Where should I document this content?"
+Agent: "Does the content vary by page context?
+        YES → Page file
+        NO → Feature file"
+```
+
+✅ **Cross-reference tracking**
+```
+Designer: "I updated the button color"
+Agent: "This button appears on 5 pages. Should I update all references?"
+```
+
+---
+
+## The Collaboration Flow
+
+### Phase 1: Designer Thinks
+
+**Designer decides:**
+- Business goals for this page
+- User needs to serve
+- Product strategy to implement
+- Experience coherence to maintain
+- Technical approach to take
+
+**Agent observes, learns context.**
+
+---
+
+### Phase 2: Agent Guides Decomposition
+
+**Agent asks systematic questions:**
+```
+"I see this sketch. Let me identify sections:
+1. Navigation Header
+2. Hero Section
+3. Calendar Component
+4. Leaderboard
+5. Footer
+
+Does this match your vision?"
+```
+
+**Designer confirms, corrects, adds context:**
+```
+"Yes, but the Calendar is the core feature. 
+It needs detailed specification."
+```
+
+**Agent adapts:**
+```
+"Got it. Calendar is core. I'll guide you through detailed decomposition.
+The other sections we can keep schematic unless you need detail."
+```
+
+---
+
+### Phase 3: Designer Provides Creative Input
+
+**Designer sketches, explains, decides:**
+```
+"The walk slots have 6 states. I have a storyboard showing the flow.
+The colors represent different stages of the walk lifecycle.
+This needs to feel playful, not punishing."
+```
+
+**Agent captures systematically:**
+```
+"Capturing:
+- 6 visual states (storyboard reference)
+- Color-coded lifecycle
+- Tone: Playful, not punishing
+
+Should I create:
+- Component file (visual design)
+- Feature file (state machine logic)
+- Storyboard reference?"
+```
+
+---
+
+### Phase 4: Agent Ensures Consistency
+
+**Agent checks patterns:**
+```
+"I notice you're using orange for 'countdown active' state.
+On the Week Overview, orange circles also mean 'active day'.
+This is consistent. Should I document this as a design system pattern?"
+```
+
+**Designer confirms or corrects:**
+```
+"Yes! Orange = active/urgent across the app.
+Add that to the design system."
+```
+
+---
+
+### Phase 5: Designer Makes Final Decisions
+
+**Agent presents options:**
+```
+"For the User Profile dropdown, I can:
+A) Keep simple specification in Page file
+B) Create detailed Component + Feature files
+C) Mark as TODO for later
+
+This component has 3 states and logout logic. 
+What level of detail do you need?"
+```
+
+**Designer decides based on priorities:**
+```
+"Option B. User profile is important for trust.
+Let's specify it properly."
+```
+
+---
+
+## Crucial Agent Behaviors
+
+### 1. Ask, Don't Assume
+
+**Wrong:**
+```
+Agent: "I'll create a daily calendar view."
+```
+
+**Right:**
+```
+Agent: "I see a calendar. Should this be:
+        - Daily view
+        - Weekly view
+        - Monthly view
+        
+        What matches your users' mental model?"
+```
+
+---
+
+### 2. Provide Context, Not Just Questions
+
+**Wrong:**
+```
+Agent: "What color should this be?"
+```
+
+**Right:**
+```
+Agent: "I notice the walk slot needs a color for 'countdown active' state.
+        You've used:
+        - Blue for 'in progress'
+        - Green for 'completed'
+        - Red for 'missed'
+        
+        What color represents 'urgent but not started'?"
+```
+
+---
+
+### 3. Explain WHY Questions Matter
+
+**Wrong:**
+```
+Agent: "Does content vary by page?"
+```
+
+**Right:**
+```
+Agent: "Does the hero heading change per page?
+        
+        This matters because:
+        - If YES → Document in Page file (page-specific)
+        - If NO → Document in Feature file (reusable)
+        
+        This keeps your specs maintainable."
+```
+
+---
+
+### 4. Learn Designer Preferences
+
+**After a few interactions:**
+```
+Agent: "I notice you prefer detailed specifications for user-facing components
+        but schematic specs for admin sections.
+        
+        Should I apply this pattern to the Settings page?"
+```
+
+---
+
+### 5. Catch Inconsistencies Gently
+
+**Wrong:**
+```
+Agent: "ERROR: This contradicts the Start Page!"
+```
+
+**Right:**
+```
+Agent: "I notice on Start Page, buttons are 48px height.
+        Here you specified 44px.
+        
+        Is this intentional (different context) or should I match for consistency?"
+```
+
+---
+
+### 6. Ask "Why" Questions That Reveal Insights
+
+**Agent notices patterns and asks for reasoning:**
+
+```
+Agent: "Help me understand: The header has two buttons - 
+        'Book Walk' and 'Add Walk'. 
+        
+        They seem to do similar things. What's the difference?"
+```
+
+**Designer's answer reveals business logic:**
+```
+Designer: "Oh! Good catch. 
+           'Book Walk' = Reserve a future slot
+           'Add Walk' = Log a walk that already happened
+           
+           We need both because kids forget to book but parents 
+           want to track completed walks for the leaderboard."
+```
+
+**Agent captures the insight:**
+```
+Agent: "Got it! Two distinct use cases:
+        - Book Walk → Future planning (proactive)
+        - Add Walk → Retroactive logging (accountability)
+        
+        Should I document this distinction in the Feature file 
+        so developers understand the different workflows?"
+```
+
+---
+
+**When designer says "I don't know":**
+
+```
+Agent: "Why does the calendar show week numbers instead of dates?"
+
+Designer: "Hmm, I'm not sure. It just felt right."
+
+Agent: "Let me help you think through this. Pros and cons:
+
+        Week Numbers:
+        ✅ Matches Swedish 'Vecka 40' culture
+        ✅ Simpler visual (less clutter)
+        ✅ Focuses on rhythm, not specific dates
+        ❌ Users might need to check what week it is
+        ❌ Less familiar to non-Swedish users
+        
+        Specific Dates:
+        ✅ Immediately clear what day it is
+        ✅ Universal understanding
+        ❌ More visual clutter
+        ❌ Doesn't match Swedish planning culture
+        
+        Given your target users are Swedish families, 
+        which approach serves them better?"
+```
+
+**Designer thinks through it:**
+```
+Designer: "You're right - Swedish families think in weeks.
+           'Vecka 40' is how they plan. Let's keep week numbers
+           but add a small date range for clarity: 'Vecka 40 (2-8 Oct)'"
+```
+
+**Agent captures the decision:**
+```
+Agent: "Perfect! Documenting:
+        - Primary: Week number (Swedish mental model)
+        - Secondary: Date range (clarity)
+        - Rationale: Matches target user planning culture
+        
+        This also goes in your design system as a pattern."
+```
+
+---
+
+## What This Enables
+
+### Designer Benefits
+
+✅ **Focus on thinking, not documentation**
+- Agent handles systematic capture
+- Designer focuses on creative decisions
+
+✅ **Maintain consistency effortlessly**
+- Agent tracks patterns across pages
+- Designer confirms or corrects
+
+✅ **Iterate faster**
+- Agent guides structured decomposition
+- Designer doesn't get overwhelmed
+
+✅ **Nothing gets missed**
+- Agent asks systematic questions
+- Designer provides context
+
+✅ **Design system integrity**
+- Agent catches inconsistencies
+- Designer maintains coherence
+
+---
+
+### Project Benefits
+
+✅ **Complete specifications**
+- Nothing forgotten or assumed
+- Clear handoffs to developers
+
+✅ **Maintainable documentation**
+- Structured, not monolithic
+- Easy to update
+
+✅ **Faster development**
+- Developers have clear instructions
+- AI code generators have precise prompts
+
+✅ **Better products**
+- Designer thinking + Agent systematization
+- Strategic decisions + consistent execution
+
+---
+
+## The Bottom Line
+
+**Agents don't replace designers.**
+
+**Agents optimize designer craft by:**
+- Handling systematic work
+- Ensuring consistency
+- Guiding structured workflows
+- Catching oversights
+- Documenting decisions
+
+**This frees designers to:**
+- Think strategically
+- Make creative decisions
+- Solve complex problems
+- Maintain coherent experiences
+- Balance competing priorities
+
+**The result:**
+- 10x faster specification
+- 10x better consistency
+- 10x more complete documentation
+- 100% designer-driven decisions
+
+**Designer thinking. Agent execution. Product success.**
+
+---
+
+## Related Concepts
+
+### [Why-Based Specifications](../WHY-BASED-SPECIFICATIONS.md)
+How capturing WHY (not just WHAT) makes AI implementation correct
+
+---
+
+[← Back to Guide](00-MODULAR-ARCHITECTURE-GUIDE.md)

src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/complexity-detection.md

@@ -0,0 +1,115 @@
+# Complexity Detection
+
+**How to identify simple vs complex components**
+
+---
+
+## Simple Component Indicators
+
+- ✅ Single state (no variations)
+- ✅ No user interaction (static display)
+- ✅ No data dependencies
+- ✅ No business logic
+
+**Examples:**
+- Static text
+- Image
+- Basic button (just click → navigate)
+
+**Action:** Document in Page file only
+
+---
+
+## Complex Component Indicators
+
+- ⚠️ Multiple states (3+ states)
+- ⚠️ Time-based changes (countdowns, timers)
+- ⚠️ Multi-step interactions (workflows)
+- ⚠️ Business rules (validation, permissions)
+- ⚠️ Data synchronization (updates other components)
+- ⚠️ State machines (defined transition paths)
+
+**Examples:**
+- Calendar widget (6 states)
+- Search with autocomplete (5+ states)
+- Multi-step form (progress tracking)
+- Booking system (state machine)
+
+**Action:** Decompose into 3 files (Page, Component, Feature)
+
+---
+
+## Detection Examples
+
+### Example 1: Simple Button
+
+**Indicators:**
+- ✅ Single interaction (click → navigate)
+- ✅ 2-3 states (default, hover, active)
+- ❌ No business logic
+- ❌ No data dependencies
+
+**Result:** SIMPLE - Page file only
+
+---
+
+### Example 2: Search Bar
+
+**Indicators:**
+- ⚠️ Multiple states (empty, typing, loading, results, error)
+- ⚠️ Real-time updates (debounced API calls)
+- ⚠️ Business logic (min 3 characters, max 10 results)
+- ⚠️ Data dependencies (search API)
+- ⚠️ Keyboard navigation
+
+**Result:** COMPLEX - Decompose into 3 files
+
+---
+
+### Example 3: Calendar Widget
+
+**Indicators:**
+- ⚠️ 6 walk states
+- ⚠️ Time-based transitions (countdown timers)
+- ⚠️ Complex business rules (per-dog blocking)
+- ⚠️ Multi-component sync (week view, leaderboard)
+- ⚠️ Real-time updates (every 1 minute)
+- ⚠️ API dependencies (4+ endpoints)
+
+**Result:** HIGHLY COMPLEX - Decompose + storyboard
+
+---
+
+## When to Decompose
+
+**Decompose when component has:**
+- 3+ visual states
+- Business rules
+- API dependencies
+- State machine logic
+- Multi-component interactions
+
+**Keep simple when component has:**
+- 1-2 states
+- No logic
+- No data
+- Static display
+
+**⚠️ Common Mistake:**
+```markdown
+❌ Wrong: Everything in one file
+Pages/02-calendar-page.md (800 lines)
+├─ Layout + Visual design + Business logic + API endpoints
+
+✅ Right: Decompose into 3 files
+Pages/02-calendar-page.md (100 lines) → Layout + page content
+Components/walk-slot-card.component.md (150 lines) → Visual design
+Features/walk-booking-logic.feature.md (200 lines) → Logic
+```
+
+---
+
+## Next Steps
+
+- [Complexity Router Workflow](02-complexity-router-workflow.md) - How to decompose
+- [Examples](examples/) - See real decompositions

src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/content-placement-rules.md

@@ -0,0 +1,131 @@
+# Content Placement Rules
+
+**Decision tree for where to document content**
+
+---
+
+## The Core Question
+
+```
+Does CONTENT vary by page context?
+│
+├─ YES → Page File
+│        (Hero heading, user-specific data)
+│
+└─ NO → Feature File
+         (Generic button text, error messages)
+```
+
+---
+
+## Page File Content
+
+**Document in Page file when:**
+- ✅ Content changes per page
+- ✅ Data varies by user/context
+- ✅ Configuration differs by placement
+
+**Examples:**
+- Hero heading: "Welcome" (Home) vs "About Us" (About)
+- Search placeholder: "Search products..." vs "Search help..."
+- Calendar header: "Familjen Svensson: Vecka 40" (user's family)
+- API endpoint: `/api/families/:currentFamilyId/walks` (user-specific)
+
+**⚠️ Common Mistake:**
+```markdown
+❌ Wrong: Features/hero-logic.feature.md
+**Content:**
+- Heading: "Welcome to Dog Week" (Home page)
+- Heading: "About Dog Week" (About page)
+
+✅ Right: Put in respective Page files
+Pages/01-home-page.md → "Welcome to Dog Week"
+Pages/02-about-page.md → "About Dog Week"
+```
+
+---
+
+## Feature File Content
+
+**Document in Feature file when:**
+- ✅ Content is the same everywhere
+- ✅ Generic validation messages
+- ✅ Standard UI text
+
+**Examples:**
+- Button text: "Submit" (always the same)
+- Error message: "Invalid email" (generic validation)
+- Loading text: "Loading..." (standard)
+- Tooltip: "Click to expand" (generic interaction)
+
+**⚠️ Common Mistake:**
+```markdown
+❌ Wrong: Pages/01-home-page.md
+**Content:**
+- Submit button: "Submit"
+- Error message: "Invalid email"
+
+✅ Right: Features/form-submit-logic.feature.md
+**Generic Content:**
+- Submit button: "Submit"
+- Error message: "Invalid email"
+```
+
+---
+
+## Component File Content
+
+**Component files contain NO content:**
+- ❌ No text
+- ❌ No images
+- ❌ No data
+- ✅ Only visual design (colors, spacing, states)
+
+**Exception:** Content slots
+```markdown
+**Content Slots:**
+- Heading text (configurable per page)
+- Background image (configurable per page)
+```
+
+**⚠️ Common Mistakes:**
+```markdown
+❌ Wrong: Features/button-logic.feature.md
+**Visual:** Background: Blue, Height: 48px
+
+✅ Right: Components/button-primary.component.md
+**Visual Specifications:** Background: Blue (#3B82F6), Height: 48px
+
+---
+
+❌ Wrong: Components/walk-slot-card.component.md
+**Logic:** Can't start walk if another is active
+
+✅ Right: Features/walk-booking-logic.feature.md
+**Business Rules:** One active walk per dog
+```
+
+---
+
+## Decision Matrix
+
+| Content Type | Page-Specific? | Where? |
+|--------------|----------------|--------|
+| Hero heading | ✅ YES | Page |
+| Hero background | ✅ YES | Page |
+| Search placeholder | ✅ YES | Page |
+| User's family name | ✅ YES | Page |
+| API with user context | ✅ YES | Page |
+| Submit button text | ❌ NO | Feature |
+| Error messages | ❌ NO | Feature |
+| Loading text | ❌ NO | Feature |
+| Tooltip text | ❌ NO | Feature |
+| Button color | ❌ Visual | Component |
+
+---
+
+## Examples
+
+- [Simple Button](examples/simple-button.md)
+- [Search Bar](examples/search-bar.md)
+- [Calendar Widget](examples/complex-calendar.md)

src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/three-tier-overview.md

@@ -0,0 +1,127 @@
+# Three-Tier Architecture Overview
+
+**Separation of WHERE, HOW, and WHAT**
+
+---
+
+## The Three File Types
+
+### 1. Pages/ (WHERE)
+**Purpose:** Page-specific context and placement
+
+**Contains:**
+- Position & size
+- Page-specific content (varies by page)
+- Page-specific data (user context)
+- Component references
+- Feature references
+
+**Example:**
+```markdown
+Pages/02-calendar-page.md
+- Position: Main content, full-width
+- Content: "Familjen Svensson: Vecka 40" (user's family)
+- Data: GET /api/families/:currentFamilyId/walks
+- Component: → walk-slot-card.component.md
+- Feature: → walk-booking-logic.feature.md
+```
+
+---
+
+### 2. Components/ (HOW IT LOOKS)
+**Purpose:** Visual design specifications
+
+**Contains:**
+- Visual specs (colors, spacing, typography)
+- States (default, hover, active, loading, error)
+- Variants (sizes, types, themes)
+- Figma mapping
+- Responsive behavior
+- ❌ NO content, NO logic
+
+**Example:**
+```markdown
+Components/walk-slot-card.component.md
+- 6 visual states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED)
+- Typography: 16px Medium, 12px Regular
+- Colors: Blue (#3B82F6), Orange (#FB923C), etc.
+- Storyboard reference: Features/Storyboards/walk-states.jpg
+```
+
+---
+
+### 3. Features/ (WHAT IT DOES)
+**Purpose:** Functional logic and business rules
+
+**Contains:**
+- User interactions
+- Business rules
+- State management
+- Generic content (same everywhere)
+- API endpoints
+- Validation rules
+- ❌ NO visual design
+
+**Example:**
+```markdown
+Features/walk-booking-logic.feature.md
+- Book walk → GRAY state
+- Start walk → BLUE state
+- Business rule: One active walk per dog
+- API: POST /api/walks, PUT /api/walks/:id/start
+- Generic content: "Loading...", "Error: Failed to load"
+```
+
+---
+
+## Why Three Tiers?
+
+### Before (Monolithic)
+```
+Pages/02-calendar-page.md (800 lines)
+├─ Everything mixed together
+├─ Developer confused
+├─ Designer confused
+└─ Features get missed
+```
+
+### After (Modular)
+```
+Pages/02-calendar-page.md (100 lines)
+├─ Just placement + user context
+
+Components/walk-slot-card.component.md (150 lines)
+├─ Visual design only
+└─ → Send to Figma designer
+
+Features/walk-booking-logic.feature.md (200 lines)
+├─ Logic only
+└─ → Send to developer
+```
+
+---
+
+## Handoff Strategy
+
+**Visual Designer** receives:
+- `Components/` folder
+- Creates Figma components
+- Matches visual specs exactly
+
+**Developer** receives:
+- `Features/` folder
+- Implements business logic
+- Uses API endpoints specified
+
+**You** maintain:
+- `Pages/` folder
+- Track design system integrity
+- Manage page-specific content
+
+---
+
+## Next Steps
+
+- [Content Placement Rules](01-content-placement-rules.md) - Where does content go?
+- [Complexity Detection](01-complexity-detection.md) - When to decompose?
+- [Workflow](02-complexity-router-workflow.md) - How to decompose?

src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-what-are-storyboards.md

@@ -0,0 +1,64 @@
+# What Are Storyboards?
+
+**Visual documentation of component functionality**
+
+---
+
+## Definition
+
+A **storyboard** is a visual sequence showing:
+- State transitions (empty → loading → active → completed)
+- User interactions (click, type, swipe)
+- System responses (updates, animations, feedback)
+- Time-based changes (countdowns, timers)
+
+---
+
+## Format
+
+**Hand-drawn sketches** (recommended):
+- Quick to create
+- Easy to iterate
+- Focus on functionality, not polish
+
+**Example:** Dog Week `App-Main-Booking-States.jpg`
+- 6 frames showing walk states
+- Numbered sequentially
+- Annotated with triggers
+
+---
+
+## Purpose
+
+Storyboards answer:
+- "What does this look like in each state?"
+- "How do users move between states?"
+- "What triggers each transition?"
+- "What happens over time?"
+
+---
+
+## Why Visual?
+
+**Text description:**
+```
+When the user books a walk, the card changes to gray, 
+the leaderboard updates, and the week overview changes.
+```
+
+**Storyboard:**
+```
+Frame 1: WHITE card with "Book" button
+Frame 2: User taps "Book"
+Frame 3: GRAY card, leaderboard +1, week circle gray
+```
+
+Visual is **faster to understand** and **harder to misinterpret**.
+
+---
+
+## Next Steps
+
+- [When to Use Storyboards](01-when-to-use.md)
+- [Storyboard Types](01-storyboard-types.md)
+- [Creation Guide](creation-guide.md)

src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-when-to-use.md

@@ -0,0 +1,58 @@
+# When to Use Storyboards
+
+**Complexity indicators that require visual documentation**
+
+---
+
+## Create Storyboards For:
+
+✅ **Components with 3+ states**
+- Example (Dog Week): Walk slots (WHITE, GRAY, ORANGE, BLUE, GREEN, RED)
+
+✅ **Time-based transitions**
+- Example (Dog Week): Countdown timers, auto-state changes
+
+✅ **Multi-step user flows**
+- Example (Dog Week): Booking → Starting → Completing a walk
+
+✅ **Complex interactions between components**
+- Example (Dog Week): Calendar updates leaderboard and week view
+
+✅ **State machines with branching paths**
+- Example (Dog Week): Success path vs error path vs timeout path
+
+---
+
+## Don't Need Storyboards For:
+
+❌ **Simple buttons**
+- Hover and active states are obvious
+
+❌ **Static content sections**
+- No state changes to document
+
+❌ **Single-state components**
+- Nothing to show in sequence
+
+---
+
+## Examples
+
+### Need Storyboard:
+- **Dog Week:** Calendar booking (6 states, time-based)
+- **Future Project:** Search with autocomplete (5 states, real-time)
+- **Future Project:** Multi-step form (progress tracking)
+- **Future Project:** Payment flow (multiple steps, error handling)
+
+### Don't Need Storyboard:
+- Submit button (2-3 states)
+- Hero image (static)
+- Text paragraph (no states)
+- Logo (no interaction)
+
+---
+
+## Next Steps
+
+- [Storyboard Types](01-storyboard-types.md)
+- [Creation Guide](creation-guide.md)

src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/02-file-structure.md

@@ -0,0 +1,81 @@
+# Storyboard File Structure
+
+**Where to store storyboards in the three-tier architecture**
+
+---
+
+## Storage Location
+
+```
+project-root/
+├─ Pages/
+│  └─ 02-calendar-page.md
+│
+├─ Components/
+│  └─ walk-slot-card.component.md
+│
+├─ Features/
+│  ├─ walk-booking-logic.feature.md
+│  └─ Storyboards/                    ← Store here
+│     ├─ walk-state-transitions.jpg
+│     ├─ booking-flow.jpg
+│     └─ calendar-sync-flow.jpg
+│
+└─ Sketches/                          ← Page sketches
+   └─ 02-calendar-page-sketch.jpg
+```
+
+---
+
+## Why Features/Storyboards/?
+
+Storyboards document **functionality**, not visual design:
+- State transitions (functional)
+- User interactions (functional)
+- Business logic flows (functional)
+
+Therefore, they belong with **Features**, not Components.
+
+---
+
+## Reference Pattern
+
+**From Feature File:**
+```markdown
+Features/walk-booking-logic.feature.md
+
+## Visual Storyboard
+
+![Walk State Transitions](Storyboards/walk-state-transitions.jpg)
+```
+
+**From Component File:**
+```markdown
+Components/walk-slot-card.component.md
+
+## Visual States
+
+See storyboard for state transitions:
+→ Features/Storyboards/walk-state-transitions.jpg
+```
+
+---
+
+## Separation from Page Sketches
+
+**Page Sketches** (Sketches/ folder):
+- Show page layout
+- Static view of entire page
+- Used during initial design
+
+**Storyboards** (Features/Storyboards/ folder):
+- Show component behavior
+- Sequential frames showing changes
+- Used during specification
+
+---
+
+## Next Steps
+
+- [Naming Conventions](02-naming-conventions.md)
+- [Feature File Integration](feature-file-integration.md)

src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/complexity-router-workflow.md

@@ -0,0 +1,144 @@
+# Complexity Router Workflow
+
+**Step-by-step guided decomposition**
+
+---
+
+## Overview
+
+When a complex component is detected, the agent guides you through 3 steps:
+
+1. **WHERE** - Page context
+2. **HOW** - Visual design
+3. **WHAT** - Functional logic
+
+---
+
+## Step 1: Page Context (WHERE)
+
+**Agent asks:**
+
+1. Which page(s) does this appear on?
+2. Where on the page?
+3. How big is it?
+4. Same component on multiple pages, or page-specific?
+5. **Does CONTENT change based on page context?**
+6. **Does DATA source change based on page context?**
+
+**You answer, agent captures:**
+- Pages list
+- Position
+- Size
+- Reusability
+- Content varies: YES/NO
+- Data source varies: YES/NO
+
+**Result:** Page file specification
+
+---
+
+## Step 2: Visual Design (HOW)
+
+**Agent asks:**
+
+1. How many visual states?
+2. Do you have a storyboard showing states?
+3. For each state:
+   - What does it look like?
+   - What triggers this state?
+   - Can it transition to other states?
+
+**You answer, agent captures:**
+- State count
+- State definitions
+- Storyboard reference (if exists)
+- Visual specifications
+
+**Result:** Component file specification
+
+---
+
+## Step 3: Functional Logic (WHAT)
+
+**Agent asks:**
+
+1. What can users DO with this?
+2. What happens when they interact?
+3. Are there business rules?
+4. Does it need data from an API?
+5. Does it update other components?
+
+**You answer, agent captures:**
+- User actions
+- System responses
+- Business rules
+- API endpoints
+- Component sync
+
+**Result:** Feature file specification
+
+---
+
+## Example Dialogue
+
+See: [Coaching Dialogue Example](examples/coaching-dialogue.md)
+
+---
+
+## Output: Three Files
+
+**1. Page File**
+```markdown
+Pages/02-calendar-page.md
+
+**Component:** walk-slot-card.component.md
+**Feature:** walk-booking-logic.feature.md
+
+**Position:** Main content, full-width
+**Page-Specific Content:**
+- Header: "Familjen Svensson: Vecka 40"
+- Data: GET /api/families/:currentFamilyId/walks
+```
+
+**2. Component File**
+```markdown
+Components/walk-slot-card.component.md
+
+**Visual Specifications:**
+- 6 states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED)
+- Typography, colors, spacing
+- Storyboard: Features/Storyboards/walk-states.jpg
+```
+
+**3. Feature File**
+```markdown
+Features/walk-booking-logic.feature.md
+
+**User Interactions:**
+- Book walk → GRAY state
+- Start walk → BLUE state
+
+**Business Rules:**
+- One active walk per dog
+- Can't book if slot taken
+
+**API Endpoints:**
+- POST /api/walks
+- PUT /api/walks/:id/start
+```
+
+---
+
+## Benefits
+
+- ✅ Clean handoffs (designer, developer, AI)
+- ✅ Nothing gets missed (all features documented)
+- ✅ Easy to maintain (update specs, not code)
+- ✅ Design system integrity (consistent patterns)
+
+---
+
+## Next Steps
+
+- [Examples](examples/) - See real decompositions
+- [Storyboards](02-storyboards/00-STORYBOARDS-GUIDE.md) - Visual documentation

src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/page-specification-workflow.md

@@ -0,0 +1,280 @@
+# Page Specification Workflow
+
+**Step-by-step iterative decomposition from sketch to specs**
+
+---
+
+## Overview
+
+The agent guides you through specifying a page **from top to bottom**, one section at a time. You control the level of detail at each step.
+
+---
+
+## The Workflow
+
+### Step 1: Identify All Sections
+
+**Agent analyzes sketch and outputs:**
+```
+📋 Page Sections Detected:
+
+1. Navigation Header
+2. Hero Section
+3. Calendar Component
+4. Leaderboard Component
+5. Footer
+
+Does this match your sketch? Any sections missing or incorrectly identified?
+```
+
+**You respond:**
+- Confirm sections
+- Add missing sections
+- Rename sections
+- Reorder sections
+
+---
+
+### Step 2: Section Purpose
+
+**For each section, agent asks:**
+```
+📍 Section: Navigation Header
+
+What is the purpose of this section?
+- User navigation?
+- Branding?
+- User account access?
+- Search functionality?
+```
+
+**You respond:**
+```
+"User navigation and branding. Shows logo, main menu, and user profile."
+```
+
+**Agent captures:**
+```markdown
+## Navigation Header
+
+**Purpose:** User navigation and branding
+**Contains:** Logo, main menu, user profile
+```
+
+---
+
+### Step 3: List Objects in Section
+
+**Agent outputs:**
+```
+🔍 Objects in Navigation Header:
+
+1. Logo (image)
+2. Main Menu (navigation)
+3. User Profile (dropdown)
+
+Shall I specify each object, or is this section simple enough to keep schematic?
+```
+
+**You choose:**
+- **Option A:** "Specify each object" → Go deeper
+- **Option B:** "Keep schematic" → Move to next section
+
+---
+
+### Step 4: Decompose Containers
+
+**If object is a container, agent asks:**
+```
+📦 Main Menu (Container)
+
+What components does this contain?
+1. Home link
+2. Calendar link
+3. Leaderboard link
+4. Settings link
+
+Are these simple links, or do any need detailed specs?
+```
+
+**You respond:**
+```
+"Simple links, no detail needed"
+```
+
+**Agent captures:**
+```markdown
+### Main Menu
+- Home link
+- Calendar link
+- Leaderboard link
+- Settings link
+```
+
+---
+
+### Step 5: Specify Atomic Components
+
+**When reaching smallest parts:**
+```
+🔬 User Profile (Dropdown)
+
+This looks complex (multiple states, interactions).
+
+Should I:
+A) Create detailed Component + Feature files (3-tier)
+B) Keep simple specification in Page file
+C) Skip for now, mark as TODO
+```
+
+**You choose based on complexity:**
+- **Simple:** Keep in Page file
+- **Complex:** Decompose to 3 files
+- **Later:** Mark TODO
+
+---
+
+## Example: Dog Week Calendar Page
+
+### Full Workflow
+
+**Step 1: Sections**
+```
+Agent: "I see 5 sections: Header, Week Overview, Leaderboard, Calendar, Footer"
+You: "Correct!"
+```
+
+**Step 2: Section Purposes**
+```
+Agent: "What's the purpose of Week Overview?"
+You: "Shows current week number and 7-day status circles"
+```
+
+**Step 3: Week Overview Objects**
+```
+Agent: "Objects detected:
+1. Week number label (text)
+2. 7 day circles (repeated component)
+
+Specify each or keep schematic?"
+You: "Specify the day circles, they have states"
+```
+
+**Step 4: Day Circle Component**
+```
+Agent: "Day circles look complex (3 states: empty, booked, completed).
+Should I create Component + Feature files?"
+You: "Yes, decompose it"
+```
+
+**Step 5: Calendar Section**
+```
+Agent: "Calendar has 6 walk states, countdown timers, business rules.
+This is highly complex. Should I:
+- Create 3-tier decomposition
+- Reference your storyboard (App-Main-Booking-States.jpg)"
+You: "Yes, decompose and reference storyboard"
+```
+
+---
+
+## Designer Control Points
+
+At each step, you decide:
+
+### Detail Level
+- **Schematic:** Just list components, no details
+- **Moderate:** Basic specs (size, position, content)
+- **Detailed:** Full 3-tier decomposition
+
+### When to Stop
+- **Good enough:** "This is clear, move on"
+- **Need detail:** "Let's specify this fully"
+- **Later:** "Mark as TODO, we'll come back"
+
+### Feedback Loop
+```
+Agent: "Here's what I captured for Navigation Header..."
+You: "Actually, the logo should be clickable and link to home"
+Agent: "Updated! Logo is now a link component."
+```
+
+---
+
+## Output Structure
+
+### Schematic Page Spec
+```markdown
+Pages/02-calendar-page.md
+
+## Navigation Header
+**Purpose:** User navigation and branding
+- Logo (clickable, links to home)
+- Main menu (4 links)
+- User profile dropdown
+
+## Calendar Section
+**Purpose:** Book and manage dog walks
+**Component:** → walk-slot-card.component.md
+**Feature:** → walk-booking-logic.feature.md
+**Storyboard:** → Features/Storyboards/walk-states.jpg
+```
+
+### Detailed Page Spec
+```markdown
+Pages/02-calendar-page.md
+
+## Navigation Header
+**Purpose:** User navigation and branding
+**Position:** Top, full-width, fixed
+**Height:** 64px
+
+### Logo
+**Component:** → logo.component.md
+**Position:** Left, 16px padding
+**Size:** 40x40px
+**Action:** Click → Navigate to home
+
+### Main Menu
+**Component:** → nav-menu.component.md
+**Position:** Center
+**Items:** Home, Calendar, Leaderboard, Settings
+
+### User Profile
+**Component:** → user-dropdown.component.md
+**Feature:** → user-menu-logic.feature.md
+**Position:** Right, 16px padding
+```
+
+---
+
+## Benefits
+
+✅ **Iterative:** Specify what you need, when you need it
+✅ **Flexible:** Control detail level per section
+✅ **Collaborative:** Agent asks, you decide
+✅ **Efficient:** Don't over-specify simple sections
+✅ **Complete:** Nothing gets missed
+✅ **Aligned:** Feedback loop at every step
+
+---
+
+## When to Use
+
+**Use this workflow when:**
+- Starting a new page specification
+- Converting a sketch to structured specs
+- Unsure how detailed to be
+- Want guided decomposition
+
+**Skip this workflow when:**
+- Page is extremely simple (1-2 sections)
+- You already know the structure
+- Rapid prototyping (schematic only)
+
+---
+
+## Next Steps
+
+- [Complexity Detection](01-complexity-detection.md) - When to decompose components
+- [Complexity Router Workflow](02-complexity-router-workflow.md) - How to decompose complex components

src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/storyboards-guide.md

@@ -0,0 +1,63 @@
+# Storyboard Integration
+
+**Using visual storyboards for complex components**
+
+---
+
+## Core Concepts (01-)
+
+### [What Are Storyboards?](01-what-are-storyboards.md)
+Visual documentation of state transitions and flows
+
+### [When to Use Storyboards](01-when-to-use.md)
+Complexity indicators that require visual documentation
+
+### [Storyboard Types](01-storyboard-types.md)
+State transitions, interaction flows, multi-component sync
+
+---
+
+## Storage & Organization (02-)
+
+### [File Structure](02-file-structure.md)
+Where to store storyboards in the three-tier architecture
+
+### [Naming Conventions](02-naming-conventions.md)
+How to name storyboard files
+
+---
+
+## Creation Guidelines
+
+### [How to Create Storyboards](creation-guide.md)
+Hand-drawn, digital, or annotated screenshots
+
+### [Annotation Best Practices](annotation-guide.md)
+Numbering, labels, and visual indicators
+
+---
+
+## Integration
+
+### [Referencing in Feature Files](feature-file-integration.md)
+How to link storyboards from specifications
+
+### [Referencing in Component Files](component-file-integration.md)
+Visual state references
+
+---
+
+## Examples
+
+### [Dog Week Calendar States](examples/calendar-states.md)
+6-state walk booking storyboard
+
+### [Search Flow](examples/search-flow.md)
+Multi-step interaction storyboard
+
+---
+
+## Benefits
+
+### [Why Storyboards Work](benefits.md)
+Developer clarity, QA testing, design consistency

src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/benefits.md

@@ -0,0 +1,118 @@
+# Benefits of Three-Tier Architecture
+
+**Why this approach works**
+
+---
+
+## 1. Prevents Overwhelming Specs
+
+**Before:**
+- 800-line monolithic file
+- Everything mixed together
+- Hard to find anything
+
+**After:**
+- 3 focused files (100-200 lines each)
+- Clear separation
+- Easy to navigate
+
+---
+
+## 2. Clean Handoffs
+
+**Visual Designer** receives:
+- `Components/` folder only
+- Clear visual specifications
+- Creates Figma components
+
+**Developer** receives:
+- `Features/` folder only
+- Clear business logic
+- Implements functionality
+
+**You** maintain:
+- `Pages/` folder
+- Design system integrity
+- Page-specific content
+
+---
+
+## 3. Nothing Gets Missed
+
+**Problem:** Prototype missing leaderboard, week view wrong
+
+**Cause:** Monolithic spec, developer overwhelmed
+
+**Solution:** 
+- Component file lists ALL visual elements
+- Feature file lists ALL interactions
+- Storyboard shows ALL states
+- **Nothing gets missed**
+
+---
+
+## 4. Easy to Update
+
+**Change request:** "Add countdown timers"
+
+**Before (Code):**
+- Regenerate code
+- Previous features break
+- 2+ hours fixing
+
+**After (Spec):**
+- Update Feature file (15 minutes)
+- Regenerate with full context
+- Everything works
+
+---
+
+## 5. Reusability
+
+**Same component, different pages:**
+
+```
+Pages/02-calendar-page.md ──┐
+Pages/05-dashboard.md ──────┼→ Components/calendar-widget.component.md
+Pages/08-mobile-view.md ────┘         ↓
+                                Features/calendar-logic.feature.md
+```
+
+Update Component or Feature once, all pages benefit.
+
+---
+
+## 6. Team Collaboration
+
+**UX Designers** → Focus on `Components/` (Figma specs)  
+**Developers** → Focus on `Features/` (logic implementation)  
+**Content Writers** → Focus on `Pages/` (translations)  
+**Product Managers** → Focus on `Features/` (business rules)
+
+Everyone works in parallel, no conflicts.
+
+---
+
+## 7. Design System Integrity
+
+**Page files** reference components:
+```markdown
+**Component:** button-primary.component.md
+```
+
+Ensures consistency across pages.
+
+Easy to update design system globally.
+
+---
+
+## ROI
+
+**Time saved per feature:** 2 hours  
+**Over 10 features:** 20 hours  
+**Over product lifecycle:** 100+ hours
+
+**Quality improvement:**
+- Zero missing features
+- Consistent design
+- Maintainable codebase

src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/decision-tree.md

@@ -0,0 +1,65 @@
+# Content Placement Decision Tree
+
+**One-page flowchart for file placement**
+
+---
+
+## The Decision Tree
+
+```
+┌─────────────────────────────────────────────────┐
+│  Does CONTENT vary by page context?             │
+│  (text, images, data source)                    │
+└────────────┬────────────────────────────────────┘
+             │
+      ┌──────┴──────┐
+      │             │
+     YES            NO
+      │             │
+      ▼             ▼
+┌─────────────┐  ┌──────────────┐
+│ Page File   │  │ Feature File │
+│             │  │              │
+│ Document:   │  │ Document:    │
+│ - Headings  │  │ - Generic    │
+│ - Text      │  │   content    │
+│ - Images    │  │ - Default    │
+│ - Data API  │  │   config     │
+│ - Scope     │  │              │
+└─────────────┘  └──────────────┘
+```
+
+---
+
+## Examples
+
+**Page File (Content Varies):**
+- ✅ Hero heading: "Welcome" (Home) vs "About" (About)
+- ✅ Search placeholder: "Search products..." vs "Search help..."
+- ✅ Calendar header: "Familjen Svensson: Vecka 40" (user's family)
+- ✅ Data API: `/api/families/:currentFamilyId/walks` (user-specific)
+
+**Feature File (Content Same Everywhere):**
+- ✅ Button text: "Submit" (always the same)
+- ✅ Error message: "Invalid email" (generic validation)
+- ✅ Tooltip: "Click to expand" (generic interaction)
+- ✅ Data API: `/api/products` (same for all users)
+
+---
+
+## Visual Design?
+
+```
+Is this VISUAL design (colors, spacing, states)?
+│
+└─ YES → Component File
+         (Colors, typography, layout, states)
+```
+
+---
+
+## Quick Rule
+
+- **Page File** = WHERE + WHAT (page-specific)
+- **Component File** = HOW IT LOOKS (visual design)
+- **Feature File** = WHAT IT DOES (functionality + generic content)

src/modules/wds/workflows/4-ux-design/object-types/COMPLEXITY-ROUTER.md

@@ -0,0 +1,777 @@
+# Complexity Router & Decomposition Coach
+
+**Goal:** Detect component complexity and guide designer through modular decomposition
+
+---
+
+## STEP 1: OBJECT IDENTIFICATION
+
+<output>**Analyzing object from sketch...**</output>
+
+<action>Identify object type using standard object-router.md logic</action>
+
+<output>**✓ Object Identified:** {{object_type}}
+
+**{{object_name}}** - {{brief_description}}</output>
+
+---
+
+## STEP 2: COMPLEXITY ASSESSMENT
+
+<action>Analyze complexity indicators:
+
+**Simple Component Indicators:**
+- Single state (no hover, active, loading variations)
+- No user interaction (static display)
+- No data dependencies
+- No business logic
+
+**Complex Component Indicators:**
+- Multiple states (3+ states: empty, loading, active, completed, error)
+- Time-based changes (countdowns, timers, real-time updates)
+- Multi-step interactions (booking → starting → completing)
+- Business rules (validation, permissions, blocking logic)
+- Data synchronization (updates other components)
+- State machines (defined transition paths)
+
+**Examples:**
+- **Simple:** Static text, image, basic button
+- **Complex:** Calendar widget, booking system, search with filters, multi-step form
+</action>
+
+---
+
+## STEP 3: ROUTE BASED ON COMPLEXITY
+
+### Path A: Simple Component
+
+<check if="complexity == simple">
+
+<output>**✅ Simple Component Detected**
+
+This {{object_name}} is straightforward - I'll document it in the page specification.
+
+**What I'll capture:**
+- Visual appearance (size, color, position)
+- Content (text in all languages)
+- Basic interaction (if any)
+
+Let's proceed!</output>
+
+<action>Route to standard object-type file (e.g., button.md, heading-text.md)</action>
+<action>Document in Page file only</action>
+
+</check>
+
+---
+
+### Path B: Complex Component - DECOMPOSITION COACHING
+
+<check if="complexity == complex">
+
+<output>**🔍 Complex Component Detected**
+
+I see this {{object_name}} has multiple states and interactions. Let me help you break this down properly!
+
+**Complexity Indicators I Found:**
+{{#each complexity_indicators}}
+- {{indicator_description}}
+{{/each}}
+
+**To keep this manageable, I'll help you separate:**
+1. **Page Context** - Where it appears, size, position
+2. **Visual Design** - How each state looks (for Figma)
+3. **Functional Logic** - How it behaves, business rules
+
+This makes handoff to developers and designers much cleaner!
+
+Ready to break this down?</output>
+
+<ask>**Shall we decompose this component?**
+
+1. **Yes** - Guide me through the separation
+2. **No** - Keep it simple, document in page only
+
+Choice [1/2]:</ask>
+
+<check if="choice == 1">
+  <action>Proceed to DECOMPOSITION WORKFLOW</action>
+</check>
+
+<check if="choice == 2">
+  <output>**Okay!** I'll document everything in the page spec.
+
+⚠️ **Note:** This may create a large specification file. Consider decomposition for easier maintenance.</output>
+  
+  <action>Route to standard object-type file</action>
+  <action>Document in Page file only</action>
+</check>
+
+</check>
+
+---
+
+## DECOMPOSITION WORKFLOW
+
+<output>**Let's break down this {{object_name}} into manageable pieces!**
+
+I'll ask you questions to separate the three concerns:
+- **WHERE** it appears (Page)
+- **HOW** it looks (Component)
+- **WHAT** it does (Feature)
+
+---
+
+### Step 1: Page Context (WHERE)
+
+**First, let's establish where this component appears on the page.**</output>
+
+<ask>**Page Placement Questions:**
+
+1. **Which page(s)** does this appear on?
+   - Example: "Calendar page", "Dashboard and Profile pages"
+
+2. **Where on the page?**
+   - Example: "Main content area, center", "Sidebar, right side"
+
+3. **How big is it?**
+   - Example: "Full width", "80% width", "300px fixed width"
+
+4. **Is this the same component on multiple pages, or page-specific?**
+   - Example: "Same calendar on Dashboard and Calendar pages" vs "Unique to this page"
+
+5. **Does the CONTENT change based on page context?**
+   - Example: "Yes - hero heading is different on each page"
+   - Example: "Yes - search placeholder changes (Products vs Help)"
+   - Example: "Yes - shows current user's family name"
+   - Example: "No - content is the same everywhere"
+
+6. **Does the DATA source change based on page context?**
+   - Example: "Yes - fetches different data per page"
+   - Example: "No - always fetches same data"
+
+Your answers:</ask>
+
+<action>Capture page context:
+- Pages: {{pages_list}}
+- Position: {{position}}
+- Size: {{size}}
+- Reusability: {{is_reusable}}
+- Content Varies: {{content_varies_by_page}}
+- Data Source Varies: {{data_source_varies_by_page}}
+</action>
+
+<output>**✅ Page Context Captured**
+
+**What goes in the Page file:**
+{{#if content_varies_by_page}}
+- ✅ **Page-Specific Content** (headings, text, images that change per page)
+{{/if}}
+{{#if data_source_varies_by_page}}
+- ✅ **Page-Specific Data Configuration** (API endpoints, filters, scope)
+{{/if}}
+- ✅ **Position & Size** (where and how big)
+- ✅ **Component Reference** (link to visual design)
+- ✅ **Feature Reference** (link to functionality)
+
+{{#if not content_varies_by_page}}
+**Note:** Content is the same everywhere, so it will be documented in the Feature file instead.
+{{/if}}
+
+This will go in:
+{{#each pages_list}}
+- `Pages/{{page_number}}-{{page_name}}.md`
+{{/each}}
+
+---
+
+### Step 2: Visual Design (HOW IT LOOKS)
+
+**Now let's document the visual appearance and states.**</output>
+
+<ask>**Visual States Questions:**
+
+Looking at your sketch/storyboard, how many different visual states does this component have?
+
+Examples:
+- **Simple:** Just 1 state (always looks the same)
+- **Interactive:** 2-3 states (default, hover, active)
+- **Complex:** 4+ states (empty, loading, active, completed, error)
+
+**How many states do you see?**</ask>
+
+<action>Count states: {{state_count}}</action>
+
+<check if="state_count >= 3">
+  <output>**📊 Multiple States Detected!**
+  
+  Let's document each state's visual appearance.</output>
+  
+  <ask>**For each state, I need:**
+  
+  {{#each states}}
+  **State {{index}}: {{state_name}}**
+  1. What does it look like? (colors, icons, layout)
+  2. What triggers this state?
+  3. Can it transition to other states?
+  
+  {{/each}}
+  
+  **Do you have a storyboard sketch showing these states?**
+  - Example: "Yes, see Sketches/booking-states.jpg"
+  - If yes, provide filename
+  - If no, I'll document from your descriptions
+  
+  Your input:</ask>
+  
+  <action>Capture visual states:
+  {{#each states}}
+  - State: {{state_name}}
+  - Appearance: {{visual_description}}
+  - Trigger: {{trigger_description}}
+  - Transitions: {{transition_list}}
+  {{/each}}
+  
+  {{#if has_storyboard}}
+  - Storyboard: {{storyboard_file}}
+  {{/if}}
+  </action>
+</check>
+
+<output>**✅ Visual Design Captured**
+
+This will go in:
+- `Components/{{component_name}}.component.md`
+{{#if has_storyboard}}
+- Storyboard reference: `Features/Storyboards/{{storyboard_file}}`
+{{/if}}
+
+---
+
+### Step 3: Functional Logic (WHAT IT DOES)
+
+**Finally, let's document the interactive behavior and business rules.**</output>
+
+<ask>**Functionality Questions:**
+
+1. **What can users DO with this component?**
+   - Example: "Book a walk", "Search for items", "Filter results"
+
+2. **What happens when they interact?**
+   - Example: "Card changes color, leaderboard updates, week view syncs"
+
+3. **Are there any business rules?**
+   - Example: "Can't book if slot is taken", "Can't start walk if another is active"
+
+4. **Does it need data from an API?**
+   - Example: "Yes, fetches walk slots from /api/calendar/walks"
+
+5. **Does it update other components?**
+   - Example: "Yes, updates leaderboard and week overview when booking"
+
+Your answers:</ask>
+
+<action>Capture functional logic:
+- User Actions: {{user_actions_list}}
+- System Responses: {{system_responses_list}}
+- Business Rules: {{business_rules_list}}
+- API Dependencies: {{api_endpoints_list}}
+- Component Sync: {{synced_components_list}}
+</action>
+
+<output>**✅ Functional Logic Captured**
+
+This will go in:
+- `Features/{{feature_name}}.feature.md`
+{{#if has_storyboard}}
+- Storyboard reference: `Features/Storyboards/{{storyboard_file}}`
+{{/if}}
+
+---
+
+### Summary: Three Files Created
+
+**Great! Here's how your {{object_name}} will be documented:**
+
+**1. Page File** (`Pages/{{page_number}}-{{page_name}}.md`)
+```markdown
+### {{section_name}}
+
+**Component:** `{{component_name}}` (→ Components/{{component_name}}.component.md)
+**Feature:** `{{feature_name}}` (→ Features/{{feature_name}}.feature.md)
+
+**Position:** {{position}}
+**Size:** {{size}}
+
+**Configuration:**
+{{#each page_specific_config}}
+- {{config_item}}
+{{/each}}
+```
+
+**2. Component File** (`Components/{{component_name}}.component.md`)
+```markdown
+# {{component_name}} Component
+
+**Type:** {{component_type}}
+**Design System ID:** `{{component_id}}`
+
+## Visual Specifications
+
+{{#each states}}
+### State: {{state_name}}
+- Background: {{background_color}}
+- Icons: {{icons_list}}
+- Layout: {{layout_description}}
+{{/each}}
+
+{{#if has_storyboard}}
+## Visual Storyboard
+![{{storyboard_name}}](../Features/Storyboards/{{storyboard_file}})
+{{/if}}
+```
+
+**3. Feature File** (`Features/{{feature_name}}.feature.md`)
+```markdown
+# {{feature_name}} Feature
+
+**Feature ID:** `{{feature_id}}`
+**Type:** {{feature_type}}
+
+{{#if has_storyboard}}
+## Visual Storyboard
+![{{storyboard_name}}](Storyboards/{{storyboard_file}})
+{{/if}}
+
+## User Interactions
+
+{{#each user_actions}}
+### {{action_name}}
+**Flow:**
+1. User {{user_action}}
+2. System {{system_response}}
+3. Updates: {{component_updates}}
+{{/each}}
+
+## Business Rules
+{{#each business_rules}}
+- {{rule_description}}
+{{/each}}
+
+## API Endpoints
+{{#each api_endpoints}}
+- {{endpoint_description}}
+{{/each}}
+```
+
+**Does this breakdown look good?**</output>
+
+<ask>1. **Yes** - Create these files
+2. **Adjust** - I need to change something
+
+Choice [1/2]:</ask>
+
+<check if="choice == 1">
+  <output>**✅ Perfect! I'll create the three files.**
+  
+  **Next Steps:**
+  - Page file: Lightweight, just placement and config
+  - Component file: Visual design for Figma handoff
+  - Feature file: Logic for developer implementation
+  
+  This keeps everything organized and maintainable!</output>
+  
+  <action>Create three separate file specifications</action>
+  <action>Cross-reference between files</action>
+</check>
+
+<check if="choice == 2">
+  <ask>**What needs adjustment?**</ask>
+  
+  <action>Listen to feedback</action>
+  <action>Adjust file structure</action>
+  <action>Re-present summary</action>
+</check>
+
+</output>
+
+---
+
+## COMPLEXITY DETECTION EXAMPLES
+
+### Example 1: Simple Button
+
+**Object:** "Get Started" button
+
+**Complexity Assessment:**
+- ✅ Single interaction (click → navigate)
+- ✅ 2-3 states (default, hover, active)
+- ❌ No business logic
+- ❌ No data dependencies
+- ❌ No multi-component sync
+
+**Result:** **SIMPLE** - Document in Page file only
+
+---
+
+### Example 2: Search Bar with Autocomplete
+
+**Object:** Search input with dropdown suggestions
+
+**Complexity Assessment:**
+- ⚠️ Multiple states (empty, typing, loading, results, no results, error)
+- ⚠️ Real-time updates (debounced API calls)
+- ⚠️ Business logic (minimum 3 characters, max 10 results)
+- ⚠️ Data dependencies (search API endpoint)
+- ⚠️ Keyboard navigation (arrow keys, enter, escape)
+
+**Result:** **COMPLEX** - Decompose into 3 files
+
+**Decomposition:**
+- **Page (if content varies):** 
+  - Product page: Placeholder "Search products...", scope: products only
+  - Help page: Placeholder "Search help...", scope: help articles only
+- **Component:** Visual states (empty, focused, loading, results dropdown)
+- **Feature:** Search logic (debounce, API calls, keyboard nav, result selection)
+
+---
+
+### Example 3: Calendar Booking Widget
+
+**Object:** Dog Week calendar with week view, leaderboard, booking slots
+
+**Complexity Assessment:**
+- ⚠️ 6 walk states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED)
+- ⚠️ Time-based transitions (countdown timers, auto-state changes)
+- ⚠️ Complex business rules (per-dog blocking, early start rules)
+- ⚠️ Multi-component sync (week view, leaderboard, calendar)
+- ⚠️ Real-time updates (every 1 minute)
+- ⚠️ API dependencies (fetch walks, create booking, start walk, complete walk)
+
+**Result:** **HIGHLY COMPLEX** - Decompose into 3 files + storyboard
+
+**Decomposition:**
+- **Page:** Layout (3 sections: week overview, leaderboard, calendar), responsive behavior
+- **Component:** Visual design of all 6 states, week circles, leaderboard cards
+- **Feature:** State machine logic, booking flow, time-based transitions, API integration
+- **Storyboard:** `walk-state-transitions.jpg` showing all 6 states and triggers
+
+---
+
+## COACHING DIALOGUE EXAMPLE
+
+### Scenario: Designer adds Calendar Widget
+
+**Agent:**
+```
+🔍 Complex Component Detected
+
+I see this "Calendar Booking Widget" has multiple states and interactions. 
+Let me help you break this down properly!
+
+**Complexity Indicators I Found:**
+- 6 different visual states (empty, booked, countdown, active, completed, missed)
+- Time-based transitions (countdown timers update every minute)
+- Business rules (can't start walk if another is active for same dog)
+- Multi-component sync (updates week view and leaderboard)
+- API dependencies (fetch/create/update walk data)
+
+**To keep this manageable, I'll help you separate:**
+1. **Page Context** - Where it appears, size, position
+2. **Visual Design** - How each state looks (for Figma)
+3. **Functional Logic** - How it behaves, business rules
+
+This makes handoff to developers and designers much cleaner!
+
+Ready to break this down?
+```
+
+**Designer:** "Yes"
+
+**Agent:**
+```
+Let's break down this Calendar Booking Widget into manageable pieces!
+
+---
+
+### Step 1: Page Context (WHERE)
+
+**Page Placement Questions:**
+
+1. Which page(s) does this appear on?
+2. Where on the page?
+3. How big is it?
+4. Is this the same component on multiple pages, or page-specific?
+```
+
+**Designer:** 
+```
+1. Calendar page only
+2. Main content area, takes up full width below header
+3. Full width, height adjusts based on content
+4. Unique to calendar page
+5. Yes - shows current user's family name in header ("Familjen Svensson: Vecka 40")
+6. Yes - fetches walks for current user's family only
+```
+
+**Agent:**
+```
+✅ Page Context Captured
+
+**What goes in the Page file:**
+- ✅ Page-Specific Content (family name in header)
+- ✅ Page-Specific Data Configuration (fetch walks for current user's family)
+- ✅ Position & Size (main content, full-width)
+- ✅ Component Reference (link to visual design)
+- ✅ Feature Reference (link to functionality)
+
+This will go in:
+- `Pages/02-calendar-page.md`
+
+**Example Page Content:**
+```markdown
+### Calendar Section
+
+**Component:** `walk-slot-card.component.md`
+**Feature:** `walk-booking-logic.feature.md`
+
+**Position:** Main content area, full-width below header
+**Size:** Full width, height adjusts to content
+
+**Page-Specific Content:**
+- Header Format: "[Family Name]: Vecka [Week Number]"
+  - SE: "Familjen Svensson: Vecka 40"
+  - EN: "Svensson Family: Week 40"
+- Data Source: Current user's family from session
+
+**Configuration:**
+- API Endpoint: GET /api/families/:currentFamilyId/walks?week=:weekNumber
+- Dogs Displayed: All dogs in current user's family
+- Family Members: All members in current user's family
+```
+
+---
+
+### Step 2: Visual Design (HOW IT LOOKS)
+
+Looking at your sketch/storyboard, how many different visual states does 
+this component have?
+
+**How many states do you see?**
+```
+
+**Designer:** "6 states - I have a storyboard showing them all"
+
+**Agent:**
+```
+📊 Multiple States Detected!
+
+**For each state, I need:**
+
+State 1: Empty (WHITE)
+1. What does it look like?
+2. What triggers this state?
+3. Can it transition to other states?
+
+[... repeat for all 6 states ...]
+
+**Do you have a storyboard sketch showing these states?**
+```
+
+**Designer:** "Yes, see Sketches/App-Main-Booking-States.jpg"
+
+**Agent:**
+```
+✅ Visual Design Captured
+
+This will go in:
+- `Components/walk-slot-card.component.md`
+- Storyboard reference: `Features/Storyboards/walk-state-transitions.jpg`
+
+---
+
+### Step 3: Functional Logic (WHAT IT DOES)
+
+**Functionality Questions:**
+
+1. What can users DO with this component?
+2. What happens when they interact?
+3. Are there any business rules?
+4. Does it need data from an API?
+5. Does it update other components?
+```
+
+**Designer:**
+```
+1. Book walks, start walks, complete walks
+2. Card changes color, leaderboard updates, week view syncs
+3. Can't start walk if another is active for same dog, 
+   can't book if slot already taken
+4. Yes - GET /api/walks, POST /api/walks, PUT /api/walks/:id
+5. Yes - updates leaderboard count and week overview quarter circles
+```
+
+**Agent:**
+```
+✅ Functional Logic Captured
+
+This will go in:
+- `Features/walk-booking-logic.feature.md`
+- Storyboard reference: `Features/Storyboards/walk-state-transitions.jpg`
+
+---
+
+### Summary: Three Files Created
+
+**Great! Here's how your Calendar Booking Widget will be documented:**
+
+**1. Page File** (`Pages/02-calendar-page.md`)
+- Position: Main content, full-width
+- Component reference: `walk-slot-card.component.md`
+- Feature reference: `walk-booking-logic.feature.md`
+
+**2. Component File** (`Components/walk-slot-card.component.md`)
+- 6 visual states with colors, icons, layouts
+- Storyboard: `Features/Storyboards/walk-state-transitions.jpg`
+- Figma component mapping
+
+**3. Feature File** (`Features/walk-booking-logic.feature.md`)
+- State machine with 6 states
+- Business rules (blocking, validation)
+- API endpoints
+- Multi-component sync logic
+- Storyboard: `Storyboards/walk-state-transitions.jpg`
+
+**Does this breakdown look good?**
+```
+
+**Designer:** "Yes!"
+
+**Agent:**
+```
+✅ Perfect! I'll create the three files.
+
+**Next Steps:**
+- Page file: Lightweight, just placement and config
+- Component file: Visual design for Figma handoff
+- Feature file: Logic for developer implementation
+
+This keeps everything organized and maintainable!
+
+**Handoff Strategy:**
+- Send Component file → Visual Designer (for Figma)
+- Send Feature file → Developer (for implementation)
+- Keep Page file → Your reference for layout
+```
+
+---
+
+## KEY BENEFITS
+
+### 1. Prevents Overwhelming Specs
+
+**Before (Monolithic):**
+```
+Pages/02-calendar-page.md (800 lines)
+├─ Everything mixed together
+├─ Developer confused about what to build
+├─ Designer confused about what to design
+└─ Prototype misses features (leaderboard, week view)
+```
+
+**After (Decomposed):**
+```
+Pages/02-calendar-page.md (100 lines)
+├─ Just layout and references
+
+Components/walk-slot-card.component.md (150 lines)
+├─ Visual design only
+└─ Designer knows exactly what to create in Figma
+
+Features/walk-booking-logic.feature.md (200 lines)
+├─ Logic only
+└─ Developer knows exactly what to implement
+```
+
+### 2. Clear Handoffs
+
+- **Visual Designer** gets `Components/` folder → Creates Figma components
+- **Developer** gets `Features/` folder → Implements logic
+- **You** keep `Pages/` folder → Track design system integrity
+
+### 3. Prevents Prototype Errors
+
+**Why your prototype failed:**
+- Leaderboard missing → Not in Component file
+- Calendar wrong → Visual states not documented
+- Week view only 5 days → Layout not specified
+
+**With decomposition:**
+- Component file explicitly lists all visual elements
+- Feature file explicitly lists all interactions
+- Storyboard shows all states visually
+- Nothing gets missed!
+
+---
+
+## Content Placement Decision Tree
+
+```
+┌─────────────────────────────────────────────────┐
+│  Does CONTENT vary by page context?             │
+│  (text, images, data source)                    │
+└────────────┬────────────────────────────────────┘
+             │
+      ┌──────┴──────┐
+      │             │
+     YES            NO
+      │             │
+      ▼             ▼
+┌─────────────┐  ┌──────────────┐
+│ Page File   │  │ Feature File │
+│             │  │              │
+│ Document:   │  │ Document:    │
+│ - Headings  │  │ - Generic    │
+│ - Text      │  │   content    │
+│ - Images    │  │ - Default    │
+│ - Data API  │  │   config     │
+│ - Scope     │  │              │
+└─────────────┘  └──────────────┘
+
+Examples:
+
+Page File (Content Varies):
+✅ Hero heading: "Welcome to Dog Week" (Home) vs "About Dog Week" (About)
+✅ Search placeholder: "Search products..." vs "Search help..."
+✅ Calendar header: "Familjen Svensson: Vecka 40" (uses current user's family)
+✅ Data API: /api/families/:currentFamilyId/walks (varies by user)
+
+Feature File (Content Same Everywhere):
+✅ Button text: "Submit" (always the same)
+✅ Error message: "Invalid email" (generic validation)
+✅ Tooltip: "Click to expand" (generic interaction)
+✅ Data API: /api/products (same for all users)
+```
+
+---
+
+## Summary
+
+**Complexity Router:**
+1. **Detects** simple vs complex components
+2. **Coaches** you through decomposition
+3. **Asks about content placement** (page-specific vs generic)
+4. **Creates** three separate files automatically
+5. **Prevents** overwhelming monolithic specs
+
+**Content Placement Rule:**
+- **Page File:** Content that changes based on WHERE it appears
+- **Feature File:** Content that's the same everywhere
+- **Component File:** Visual design only (no content)
+
+**Result:**
+- ✅ Clean handoffs to developers and designers
+- ✅ Nothing gets missed in prototypes
+- ✅ Easy to maintain and update
+- ✅ Design system integrity preserved
+- ✅ Clear separation of page-specific vs generic content

src/modules/wds/workflows/4-ux-design/scenario-init/SCENARIO-INIT-PROCESS.md

@@ -0,0 +1,215 @@
+# Scenario Initialization: From Trigger Map to First Sketch
+
+**Find the natural starting point and shortest path to mutual success**
+
+---
+
+## The Situation
+
+You've created your **Trigger Map**. You know:
+- WHO your target groups are
+- WHAT triggers their needs
+- WHY your business exists
+
+**Now: What should you start sketching?**
+
+---
+
+## Agent's Job: Help You Find the Journey
+
+**Agent connects Trigger Map to the first scenario:**
+
+### 1. What Feature Delivers the Most Value?
+
+```
+Agent: "Looking at your Trigger Map and prioritized feature list,
+        what's the core feature that delivers value to your 
+        primary target group?
+        
+        This is what we should sketch first."
+
+Designer: "The family dog walk calendar - it solves the accountability 
+           problem that causes conflict."
+```
+
+---
+
+### 2. Where Does the User First Encounter This?
+
+```
+Agent: "Where does your primary target group first come into 
+        contact with this solution?"
+
+Designer: "Google search - they're frustrated with family conflict 
+           over dog care."
+```
+
+---
+
+### 3. What's Their Mental State at This Moment?
+
+```
+Agent: "When they find Dog Week on Google, how are they feeling?
+        
+        Think about:
+        - What just happened? (trigger moment)
+        - What are they hoping for?
+        - What are they worried about?"
+
+Designer: "Just had another fight about who walks the dog.
+           Tired of nagging. Want a system that works without intervention.
+           Worried about adding more complexity to family life."
+```
+
+---
+
+### 4. What's the End Goal (Mutual Success)?
+
+```
+Agent: "What does success look like for both sides?
+        
+        For the business: [subscription purchased]
+        For the parent: [what state/feeling/outcome]?"
+
+Designer: "Business: Active subscription
+           Parent: Family harmony restored, dog gets walked consistently,
+                   no more nagging needed"
+```
+
+---
+
+### 5. What's the Shortest Path?
+
+```
+Agent: "Let's map the shortest possible journey from 
+        'frustrated parent on Google' to 'active subscription + harmony':
+        
+        Natural starting point: Google search result
+        
+        What's the absolute minimum path to mutual success?"
+
+Designer: "Google → Landing page → See how it works → 
+           Sign up → Set up family → Start using calendar → 
+           First walk completed → Everyone happy"
+```
+
+**Agent captures:**
+```
+SCENARIO: Parent Onboarding to First Success
+
+START: Google search (frustrated, tired of nagging)
+END: First walk completed (harmony, system working)
+
+CRITICAL PATH:
+1. Landing page (understand solution)
+2. Sign up (commit to trying)
+3. Family setup (get everyone involved)
+4. Calendar (plan first week)
+5. First walk (proof it works)
+
+BUSINESS GOAL: Active subscription
+USER GOAL: Family harmony without nagging
+
+Now let's start sketching this journey.
+```
+
+---
+
+## What This Gives You
+
+**Clear foundation for sketching:**
+- ✅ Natural starting point (where user actually is)
+- ✅ Mental state (how they're feeling)
+- ✅ End goal (mutual success defined)
+- ✅ Shortest path (no unnecessary steps)
+- ✅ WHY behind each step (trigger map connection)
+
+**Now you can sketch with purpose:**
+- Each page serves the journey
+- Each feature addresses mental state
+- Each step moves toward mutual success
+- Nothing extra, nothing missing
+
+---
+
+## Examples
+
+### Example 1: E-commerce (Sales Goal)
+
+```
+Business Goal: Product sales
+Target Group: Budget-conscious customers
+First Contact: Google search "affordable [product]"
+Mental State: Anxious about hidden costs, need transparency
+End Goal: Purchase completed, confident in value
+Shortest Path: Google → Product page → Transparent pricing → 
+               Add to cart → Checkout → Confirmation
+
+SCENARIO: Transparent Purchase Journey
+```
+
+---
+
+### Example 2: SaaS (Subscription Goal)
+
+```
+Business Goal: Monthly subscriptions
+Target Group: Small business owners
+First Contact: ChatGPT recommendation
+Mental State: Overwhelmed, need simple solution
+End Goal: Active subscription, problem solved
+Shortest Path: ChatGPT → Landing → See demo → Sign up → 
+               Quick setup → First success
+
+SCENARIO: Frictionless Onboarding
+```
+
+---
+
+### Example 3: Service Booking (Appointment Goal)
+
+```
+Business Goal: Consultation bookings
+Target Group: First-time clients
+First Contact: Friend recommendation
+Mental State: Curious but cautious, need trust
+End Goal: Appointment booked, feeling confident
+Shortest Path: Friend link → About page → Testimonials → 
+               Book consultation → Confirmation
+
+SCENARIO: Trust-Building Booking
+```
+
+---
+
+## The Agent's Role
+
+**Not a script. A conversation.**
+
+Agent helps you think through:
+- What drives the business?
+- Who makes it happen?
+- Where do they start?
+- How do they feel?
+- What's mutual success?
+- What's the shortest path?
+
+**Then you sketch with clarity.**
+
+---
+
+## Next Step
+
+Once you have:
+- ✅ Natural starting point
+- ✅ Mental state
+- ✅ End goal
+- ✅ Shortest path
+
+**Start sketching the journey.**
+
+Each sketch serves the path from trigger to mutual success.
+
+---
+
+[← Back to Business Model Workflow](README.md)

src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md

@@ -0,0 +1,59 @@
+# Scenario Initialization Guide
+
+**From Trigger Map to first sketch**
+
+---
+
+## Purpose
+
+You've created your Trigger Map. Now: **What should you start sketching?**
+
+This process helps you identify:
+- The core feature to design first
+- The natural starting point
+- The user's mental state
+- The shortest path to mutual success
+
+---
+
+## The 5 Questions
+
+### [1. What Feature Delivers Value?](01-feature-selection.md)
+Which core feature serves your primary target group?
+
+### [2. Where Do They Encounter It?](02-entry-point.md)
+Where does the user first come into contact with your solution?
+
+### [3. What's Their Mental State?](03-mental-state.md)
+How are they feeling at this moment?
+
+### [4. What's Mutual Success?](04-mutual-success.md)
+What does winning look like for both business and user?
+
+### [5. What's the Shortest Path?](05-shortest-path.md)
+Minimum steps from starting point to mutual success
+
+---
+
+## Examples
+
+### [E-commerce Example](examples/ecommerce-example.md)
+Sales-driven transparent purchase journey
+
+### [SaaS Example](examples/saas-example.md)
+Subscription-driven frictionless onboarding
+
+### [Service Booking Example](examples/booking-example.md)
+Appointment-driven trust-building flow
+
+---
+
+## Next Step
+
+Once you have clarity on all 5 questions, **start sketching the journey.**
+
+Each sketch serves the path from trigger to mutual success.
+
+---
+
+[← Back to Business Model Workflow](../README.md)

src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/01-feature-selection.md

@@ -0,0 +1,66 @@
+# Question 1: What Feature Delivers the Most Value?
+
+**Connect Trigger Map to the first thing you should design**
+
+---
+
+## The Question
+
+```
+Agent: "Looking at your Trigger Map and prioritized feature list,
+        what's the core feature that delivers value to your 
+        primary target group?
+        
+        This is what we should sketch first."
+```
+
+---
+
+## Why This Matters
+
+Your Trigger Map already identified:
+- Primary target group
+- What triggers their need
+- What outcome they want
+
+**This question connects that to a specific feature to design.**
+
+---
+
+## Example: Dog Week
+
+**From Trigger Map:**
+- Target: Parents
+- Trigger: Family conflict over dog care
+- Outcome: Accountability without nagging
+
+**Feature Selection:**
+```
+Designer: "The family dog walk calendar - it solves the accountability 
+           problem that causes conflict."
+```
+
+**Why this feature first:**
+- Directly addresses the trigger (conflict)
+- Serves the primary target group (parents)
+- Delivers the desired outcome (accountability)
+
+---
+
+## What Agent Captures
+
+```
+CORE FEATURE: Family dog walk calendar
+WHY: Solves accountability problem that causes family conflict
+TARGET: Parents (primary decision makers)
+```
+
+---
+
+## Next Question
+
+[Where does the user first encounter this?](02-entry-point.md)
+
+---
+
+[← Back to Guide](00-SCENARIO-INIT-GUIDE.md)

src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/02-entry-point.md

@@ -0,0 +1,64 @@
+# Question 2: Where Does the User First Encounter This?
+
+**Identify the natural starting point for your scenario**
+
+---
+
+## The Question
+
+```
+Agent: "Where does your primary target group first come into 
+        contact with this solution?"
+```
+
+---
+
+## Why This Matters
+
+The entry point determines:
+- Where the scenario starts
+- What mental state they're in
+- What context you're designing for
+
+**Common entry points:**
+- Google search
+- ChatGPT recommendation
+- App store browsing
+- Friend recommendation
+- Social media ad
+- Direct URL (returning user)
+
+---
+
+## Example: Dog Week
+
+```
+Designer: "Google search - they're frustrated with family conflict 
+           over dog care."
+```
+
+**Why this matters:**
+- They're actively searching (high intent)
+- They're frustrated (emotional state)
+- They need immediate clarity (landing page critical)
+
+---
+
+## What Agent Captures
+
+```
+ENTRY POINT: Google search
+CONTEXT: Actively searching for solution
+INTENT: High (frustrated, need help now)
+IMPLICATION: Landing page must address frustration immediately
+```
+
+---
+
+## Next Question
+
+[What's their mental state at this moment?](03-mental-state.md)
+
+---
+
+[← Back to Guide](00-SCENARIO-INIT-GUIDE.md)

src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/03-mental-state.md

@@ -0,0 +1,72 @@
+# Question 3: What's Their Mental State at This Moment?
+
+**Understand the emotional context for design decisions**
+
+---
+
+## The Question
+
+```
+Agent: "When they find your solution, how are they feeling?
+        
+        Think about:
+        - What just happened? (trigger moment)
+        - What are they hoping for?
+        - What are they worried about?"
+```
+
+---
+
+## Why This Matters
+
+Mental state determines:
+- Tone of content
+- Complexity of interface
+- Type of features needed
+- What NOT to do
+
+**Design for the human, not just the task.**
+
+---
+
+## Example: Dog Week
+
+```
+Designer: "Just had another fight about who walks the dog.
+           Tired of nagging. Want a system that works without intervention.
+           Worried about adding more complexity to family life."
+```
+
+**Design implications:**
+- Tone: Empathetic, not preachy
+- Interface: Simple, not complex
+- Features: Automated accountability, not more work
+- Avoid: Notifications that feel like nagging
+
+---
+
+## What Agent Captures
+
+```
+MENTAL STATE:
+- Trigger: Just had family fight
+- Feeling: Tired, frustrated
+- Hope: System that works without intervention
+- Fear: Adding more complexity
+
+DESIGN IMPLICATIONS:
+- Keep it simple
+- Automate accountability
+- Gentle, not pushy
+- No nagging-style notifications
+```
+
+---
+
+## Next Question
+
+[What's the end goal (mutual success)?](04-mutual-success.md)
+
+---
+
+[← Back to Guide](00-SCENARIO-INIT-GUIDE.md)

src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/04-mutual-success.md

@@ -0,0 +1,67 @@
+# Question 4: What's the End Goal (Mutual Success)?
+
+**Define winning for both business and user**
+
+---
+
+## The Question
+
+```
+Agent: "What does success look like for both sides?
+        
+        For the business: [what outcome?]
+        For the user: [what state/feeling/outcome?]"
+```
+
+---
+
+## Why This Matters
+
+Success must be mutual:
+- Business gets value
+- User gets value
+- Both are happy
+
+**If only one side wins, the relationship fails.**
+
+---
+
+## Example: Dog Week
+
+```
+Designer: "Business: Active subscription
+           User: Family harmony restored, dog gets walked consistently,
+                 no more nagging needed"
+```
+
+**Why both matter:**
+- Business needs subscription (revenue)
+- User needs harmony (problem solved)
+- Subscription only works if harmony is real
+- Harmony only happens if product delivers
+
+**Mutual success = sustainable business.**
+
+---
+
+## What Agent Captures
+
+```
+MUTUAL SUCCESS:
+
+Business Goal: Active subscription (recurring revenue)
+User Goal: Family harmony + consistent dog care + no nagging
+
+Success Metric: User stays subscribed because harmony is real
+Failure Point: User cancels if product doesn't reduce conflict
+```
+
+---
+
+## Next Question
+
+[What's the shortest path to get there?](05-shortest-path.md)
+
+---
+
+[← Back to Guide](00-SCENARIO-INIT-GUIDE.md)

src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/05-shortest-path.md

@@ -0,0 +1,87 @@
+# Question 5: What's the Shortest Path?
+
+**Map the minimum journey from starting point to mutual success**
+
+---
+
+## The Question
+
+```
+Agent: "Let's map the shortest possible journey from 
+        [starting point] to [mutual success]:
+        
+        What's the absolute minimum path?"
+```
+
+---
+
+## Why This Matters
+
+Shortest path means:
+- No unnecessary steps
+- No feature bloat
+- Clear focus
+- Faster to mutual success
+
+**Every extra step is a chance to lose the user.**
+
+---
+
+## Example: Dog Week
+
+```
+Agent: "From 'frustrated parent on Google' to 'active subscription + harmony':
+        What's the minimum path?"
+
+Designer: "Google → Landing page → See how it works → 
+           Sign up → Set up family → Start using calendar → 
+           First walk completed → Everyone happy"
+```
+
+**Why this path:**
+- Landing: Understand solution (addresses frustration)
+- How it works: See it's simple (addresses complexity fear)
+- Sign up: Commit to trying (low friction)
+- Family setup: Get everyone involved (necessary for accountability)
+- Calendar: Plan first week (immediate action)
+- First walk: Proof it works (mutual success moment)
+
+---
+
+## What Agent Captures
+
+```
+SCENARIO: Parent Onboarding to First Success
+
+START: Google search (frustrated, tired of nagging)
+END: First walk completed (harmony, system working)
+
+CRITICAL PATH:
+1. Landing page → Understand solution
+2. Sign up → Commit to trying
+3. Family setup → Get everyone involved
+4. Calendar → Plan first week
+5. First walk → Proof it works
+
+BUSINESS GOAL: Active subscription
+USER GOAL: Family harmony without nagging
+
+Each step serves the journey. Nothing extra.
+```
+
+---
+
+## Now You Can Sketch
+
+With all 5 questions answered, you have:
+- ✅ Core feature (what to design)
+- ✅ Entry point (where to start)
+- ✅ Mental state (how they feel)
+- ✅ Mutual success (where to end)
+- ✅ Shortest path (how to get there)
+
+**Start sketching each step of the journey.**
+
+---
+
+[← Back to Guide](00-SCENARIO-INIT-GUIDE.md)

src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/booking-example.md

@@ -0,0 +1,59 @@
+# Example: Service Booking (Appointment Goal)
+
+**Trust-building booking flow**
+
+---
+
+## The 5 Questions
+
+### 1. Core Feature
+```
+"Consultation booking with social proof - testimonials + credentials"
+```
+
+### 2. Entry Point
+```
+"Friend recommendation (shared link)"
+```
+
+### 3. Mental State
+```
+"Curious but cautious, need to trust before committing time/money"
+```
+
+### 4. Mutual Success
+```
+Business: Consultation booked (lead captured)
+User: Confident in decision, looking forward to meeting
+```
+
+### 5. Shortest Path
+```
+Friend link → About page → Testimonials → 
+Book consultation → Confirmation
+```
+
+---
+
+## Scenario Captured
+
+```
+SCENARIO: Trust-Building Booking
+
+START: Friend recommendation (curious but cautious)
+END: Consultation booked (confident, excited)
+
+CRITICAL PATH:
+1. About page → Understand who you are
+2. Testimonials → See social proof
+3. Credentials → Verify expertise
+4. Book consultation → Commit with confidence
+5. Confirmation → Excitement reinforced
+
+BUSINESS GOAL: Consultation booked
+USER GOAL: Confident decision, trust established
+```
+
+---
+
+[← Back to Guide](../00-SCENARIO-INIT-GUIDE.md)

src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/ecommerce-example.md

@@ -0,0 +1,59 @@
+# Example: E-commerce (Sales Goal)
+
+**Transparent purchase journey**
+
+---
+
+## The 5 Questions
+
+### 1. Core Feature
+```
+"Transparent pricing breakdown - shows all costs upfront"
+```
+
+### 2. Entry Point
+```
+"Google search 'affordable [product]'"
+```
+
+### 3. Mental State
+```
+"Anxious about hidden costs, need transparency before committing"
+```
+
+### 4. Mutual Success
+```
+Business: Purchase completed
+User: Confident in value, no surprise costs
+```
+
+### 5. Shortest Path
+```
+Google → Product page → Transparent pricing → 
+Add to cart → Checkout → Confirmation
+```
+
+---
+
+## Scenario Captured
+
+```
+SCENARIO: Transparent Purchase Journey
+
+START: Google search (anxious about hidden costs)
+END: Purchase completed (confident in value)
+
+CRITICAL PATH:
+1. Product page → See product + upfront pricing
+2. Pricing breakdown → Understand all costs
+3. Add to cart → Commit to purchase
+4. Checkout → Complete transaction
+5. Confirmation → Confidence reinforced
+
+BUSINESS GOAL: Product sale
+USER GOAL: Confident purchase, no surprises
+```
+
+---
+
+[← Back to Guide](../00-SCENARIO-INIT-GUIDE.md)

src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/saas-example.md

@@ -0,0 +1,59 @@
+# Example: SaaS (Subscription Goal)
+
+**Frictionless onboarding**
+
+---
+
+## The 5 Questions
+
+### 1. Core Feature
+```
+"Quick setup wizard - gets users to first success fast"
+```
+
+### 2. Entry Point
+```
+"ChatGPT recommendation"
+```
+
+### 3. Mental State
+```
+"Overwhelmed by current tools, need simple solution that just works"
+```
+
+### 4. Mutual Success
+```
+Business: Active monthly subscription
+User: Problem solved, no complexity added
+```
+
+### 5. Shortest Path
+```
+ChatGPT → Landing → See demo → Sign up → 
+Quick setup → First success
+```
+
+---
+
+## Scenario Captured
+
+```
+SCENARIO: Frictionless Onboarding
+
+START: ChatGPT recommendation (overwhelmed, need simplicity)
+END: First success (problem solved, staying subscribed)
+
+CRITICAL PATH:
+1. Landing → Understand it's simple
+2. Demo → See it in action
+3. Sign up → Low friction entry
+4. Quick setup → Minimal configuration
+5. First success → Immediate value
+
+BUSINESS GOAL: Monthly subscription
+USER GOAL: Problem solved without complexity
+```
+
+---
+
+[← Back to Guide](../00-SCENARIO-INIT-GUIDE.md)

src/modules/wds/workflows/4-ux-design/substeps/4b-sketch-analysis.md

@@ -29,15 +29,37 @@
 Your sketch:</ask>
 
 <action>Analyze entire sketch holistically:
-1. Identify logical sections (header, hero, features, cards, footer, etc.)
+1. **Establish Scale First:**
-2. Determine section boundaries (whitespace, visual grouping, layout)
+   - Check if other pages in project have been analyzed
-3. Recognize section purposes from visual context
+   - Look for established text styles (body text, buttons, headings)
-4. Count objects/elements in each section
+   - Identify UI anchors (browser chrome, scrollbars, buttons, icons)
-5. Check if sections look like components from previous pages
+   - Use previous pages + UI elements to calibrate scale
+
+2. **Identify Sections:**
+   - Identify logical sections (header, hero, features, cards, footer, etc.)
+   - Determine section boundaries (whitespace, visual grouping, layout)
+   - Recognize section purposes from visual context
+   - Count objects/elements in each section
+
+3. **Cross-Page Pattern Matching:**
+   - Check if sections look like components from previous pages
+   - Compare text styles to established patterns (e.g., "thin lines, icon-sized spacing = 16px body text")
+   - Note potential design system components
 </action>
 
 <output>**📊 I've analyzed your sketch. Here's what I see:**
 
+{{#if has_previous_pages}}
+**🔗 Cross-Page References Detected:**
+{{#each established_patterns}}
+- {{pattern_name}}: {{specification}} (from {{source_page}})
+{{/each}}
+
+I'll use these as reference points for consistency.
+{{/if}}
+
+---
+
 **{{page_name}}** contains **{{section_count}} main sections:**
 
 {{#each identified_sections}}
@@ -49,6 +71,9 @@ Your sketch:</ask>
 {{#if looks_like_previous_component}}
 - 💡 **Component?** Similar to {{component_name}} from {{previous_page}}
 {{/if}}
+{{#if matches_established_pattern}}
+- ✅ **Pattern Match:** Text styles match {{pattern_name}} from {{source_page}}
+{{/if}}
 {{/each}}
 ---
 
@@ -120,38 +145,49 @@ I'll interpret the objects, functions, and content for each section. You can con
 
 **📍 Section {{current_index}}/{{total_sections}}: {{section_name}}**</output>
 
-### 3A: AI Reads & Interprets Section
+### 3A: AI Reads & Interprets Section (Recursive)
 
-<action>For current section:
+<action>For current section, identify objects **Top-Left to Bottom-Right**:
-1. Identify all objects (top-left to bottom-right within section)
+
-2. Determine object types (button, text, input, image, etc.)
+1. **Identify Top-Level Containers** (e.g., Cards, Rows, Groups)
-3. Interpret object functions (what does it do?)
+   - IF container has children → Dive in and identify child elements
-4. Interpret object purposes (why is it here?)
+   - IF repeating group (e.g., 3 Feature Cards) → Identify as "Repeating Pattern"
-5. Detect text (actual text vs. markers)
+
-6. Analyze visual hierarchy
+2. **Handle Repeating Objects:**
-7. Suggest Object IDs based on purpose
+   - **Fixed Count (e.g., 3 Cards):** Name individually (`card-01`, `card-02`, `card-03`)
+   - **Dynamic List:** Define as Pattern + Data Source
+
+3. **Determine Object Hierarchy:**
+   - Parent: `feature-card-01`
+   - Child: `feature-card-01-icon`, `feature-card-01-title`
+
+4. **Interpret Attributes:**
+   - Type (Button, Text, Input)
+   - Function & Purpose
+   - Text Content (Actual vs. Markers)
+   - Visual Hierarchy
 </action>
 
 <output>**My interpretation of "{{section_name}}":**
 
 **Section Purpose:** {{interpreted_section_purpose}}
 
-**Objects I see:**
+**Hierarchy I see:**
 
 {{#each interpreted_objects}}
-{{object_index}}. **{{interpreted_type}}** ({{position_description}})
+{{object_index}}. **{{interpreted_type}}** ({{hierarchy_level}})
    - **Object ID:** `{{suggested_object_id}}`
+   {{#if is_container}}
+   - **Contains:**
+     {{#each children}}
+     - {{child_type}}: `{{child_object_id}}`
+     {{/each}}
+   {{/if}}
    - **Function:** {{interpreted_function}}
    - **Purpose:** {{interpreted_purpose}}
    {{#if has_actual_text}}
    - **Text in sketch:** "{{extracted_text}}"
    {{/if}}
-   {{#if has_line_markers}}
-   - **Text capacity:** ~{{estimated_chars}} characters ({{line_count}} lines)
-   {{/if}}
-   {{#if is_interactive}}
-   - **Behavior:** {{interpreted_behavior}}
-   {{/if}}
 {{/each}}
 
 **Overall Function:** {{section_function_summary}}</output>

src/modules/wds/workflows/4-ux-design/substeps/4c-03-components-objects.md

@@ -44,6 +44,21 @@ Starting from top-left corner of this section...</output>
     5. Return here when complete
   </action>
   
+  ### DESIGN SYSTEM CHECK (IF ENABLED)
+  
+  <action>After component specification complete:
+    1. Check project config: Is design system enabled?
+    2. If YES: Load and execute `workflows/5-design-system/design-system-router.md`
+    3. Design system router will:
+       - Check for similar components
+       - Run opportunity/risk assessment if needed
+       - Extract component-level info to design system
+       - Return component reference
+       - Update page spec with reference
+    4. If NO: Keep complete specification on page
+    5. Continue to next object
+  </action>
+  
   <ask>**More objects in {{section_name}}?**
   
   1. **Yes** - Document next object (move right, then down)

src/modules/wds/workflows/5-design-system/README.md

@@ -0,0 +1,300 @@
+# Phase 5: Design System Workflow
+
+## Overview
+
+**Purpose:** Extract, organize, and maintain reusable design components as they're discovered during Phase 4 specification work.
+
+**Key Principle:** Design system is **optional** and **on-demand**. Components are added as they surface, not created upfront.
+
+---
+
+## When This Workflow Runs
+
+**Triggered from Phase 4:**
+- After component specification is complete
+- Only if design system is enabled in project
+- First component triggers automatic initialization
+
+**Not a Separate Phase:**
+- Runs in parallel with Phase 4
+- Integrated into component specification flow
+- Designer doesn't "switch" to design system mode
+
+---
+
+## Three Design System Modes
+
+**Chosen during Phase 1 (Project Exploration):**
+
+### Mode A: No Design System
+- Components stay page-specific
+- AI/dev team handles consistency
+- Faster for simple projects
+- **This workflow doesn't run**
+
+### Mode B: Custom Design System
+- Designer defines components in Figma
+- Components extracted as discovered
+- Figma MCP endpoints for integration
+- **This workflow extracts and links to Figma**
+- **See:** `figma-integration/` folder for complete Figma workflow
+
+### Mode C: Component Library Design System
+- Uses shadcn/Radix/etc.
+- Library chosen during setup
+- Components mapped to library defaults
+- **This workflow maps to library components**
+
+---
+
+## Architecture
+
+### Three-Way Split
+
+```
+Page Specification (Logical View)
+├── Component references
+├── Page-specific content
+└── Layout/structure
+
+Design System (Visual/Component Library)
+├── Component definitions
+├── States & variants
+└── Styling/tokens
+
+Functionality/Storyboards (Behavior)
+├── Interactions
+├── State transitions
+└── User flows
+```
+
+### Clean Separation
+
+**Specification = Content** (what the component is)
+**Organization = Structure** (where it lives)
+**Design System = Optional** (chosen in Phase 1)
+
+---
+
+## Workflow Components
+
+### 1. Design System Router
+**File:** `design-system-router.md`
+
+**Purpose:** Identify if component is new, similar, or duplicate
+
+**Flow:**
+```
+Component specified → Router checks design system
+├── No similar component → Create new
+└── Similar component found → Opportunity/Risk Assessment
+```
+
+### 2. Opportunity/Risk Assessment
+**Folder:** `assessment/`
+
+**Purpose:** Help designer make informed decisions about component reuse
+
+**7 Micro-Instructions:**
+1. Scan existing components
+2. Compare attributes
+3. Calculate similarity
+4. Identify opportunities
+5. Identify risks
+6. Present decision to designer
+7. Execute decision
+
+### 3. Component Operations
+**Folder:** `operations/`
+
+**Purpose:** Execute design system actions
+
+**4 Operations:**
+- Initialize design system (first component)
+- Create new component
+- Add variant to existing component
+- Update component definition
+
+### 4. Output Templates
+**Folder:** `templates/`
+
+**Purpose:** Consistent design system file structure
+
+**3 Templates:**
+- Component specification
+- Design tokens
+- Component library config
+
+---
+
+## Integration with Phase 4
+
+**Called from:** `workflows/4-ux-design/substeps/4c-03-components-objects.md`
+
+**Integration Point:**
+```
+For each component:
+1. Specify component (Phase 4)
+2. Component specification complete
+3. → Check: Design system enabled?
+4. → YES: Call design-system-router.md
+5. → Router extracts component-level info
+6. → Router returns reference
+7. Update page spec with reference
+8. Continue to next component
+```
+
+**Result:**
+- Page spec contains references + page-specific content
+- Design system contains component definitions
+- Clean separation maintained
+
+---
+
+## Key Risks & Mitigation
+
+### 1. Component Matching
+**Risk:** How to recognize "same" vs "similar" vs "different"
+
+**Mitigation:** Similarity scoring + designer judgment via assessment flow
+
+### 2. Circular References
+**Risk:** Page → Component → Functionality → Component
+
+**Mitigation:** Clear hierarchy (Page → Component → Functionality)
+
+### 3. Sync Problems
+**Risk:** Component evolves, references may break
+
+**Mitigation:** Reference IDs + update notifications
+
+### 4. Component Boundaries
+**Risk:** Icon in button? Nested components?
+
+**Mitigation:** Designer conversation + guidelines in shared knowledge
+
+### 5. First Component
+**Risk:** When to initialize design system?
+
+**Mitigation:** Auto-initialize on first component if enabled
+
+### 6. Storyboard Granularity
+**Risk:** Component behavior vs page flow
+
+**Mitigation:** Clear separation guidelines in shared knowledge
+
+---
+
+## Shared Knowledge
+
+**Location:** `data/design-system/`
+
+**Purpose:** Centralized design system principles referenced by all component types
+
+**Documents:**
+- `token-architecture.md` - Structure vs style separation
+- `naming-conventions.md` - Token naming rules
+- `state-management.md` - Component states
+- `validation-patterns.md` - Form validation
+- `component-boundaries.md` - What's a component?
+- `figma-component-structure.md` - Figma component organization (Mode B)
+
+**Usage:** Component-type instructions reference these documents as needed
+
+---
+
+## Figma Integration (Mode B)
+
+**Location:** `figma-integration/`
+
+**Purpose:** Enable seamless Figma ↔ WDS synchronization for custom design systems
+
+**Documents:**
+- `figma-designer-guide.md` - Step-by-step guide for designers
+- `figma-mcp-integration.md` - Technical MCP integration guide
+- `figma-component-structure.md` - Component organization in Figma (in data/design-system/)
+
+**Workflow:**
+1. Designer creates/updates component in Figma
+2. Designer adds WDS component ID to description
+3. MCP reads component via Figma API
+4. Agent generates/updates WDS specification
+5. Designer reviews and confirms
+
+**Key Features:**
+- Component structure guidelines
+- Design token mapping
+- Variant and state organization
+- Node ID tracking
+- Bidirectional sync workflow
+
+---
+
+## Company Customization
+
+**Key Feature:** Companies can fork WDS and customize design system standards
+
+**Customization Points:**
+- `data/design-system/` - Company-specific principles
+- `object-types/` - Company component patterns
+- `templates/` - Company output formats
+
+**Result:** Every project automatically uses company standards
+
+---
+
+## Output Structure
+
+```
+D-Design-System/
+├── components/
+│   ├── button.md              [Component ID: btn-001]
+│   ├── input-field.md         [Component ID: inp-001]
+│   ├── card.md                [Component ID: crd-001]
+│   └── ...
+├── design-tokens.md           Colors, spacing, typography
+├── component-library-config.md Which library (if Mode C)
+└── figma-mappings.md          Figma endpoints (if Mode B)
+```
+
+**Component File Structure:**
+```markdown
+# Button Component [btn-001]
+
+**Type:** Interactive
+**Library:** shadcn/ui Button (if Mode C)
+**Figma:** [Link] (if Mode B)
+
+## Variants
+- primary
+- secondary
+- ghost
+
+## States
+- default
+- hover
+- active
+- disabled
+
+## Styling
+[Design tokens or Figma reference]
+
+## Used In
+- Login page (login button)
+- Signup page (create account button)
+- Dashboard (action buttons)
+```
+
+---
+
+## Next Steps
+
+1. Read `design-system-router.md` to understand routing logic
+2. Review `assessment/` folder for decision-making process
+3. Check `operations/` for available actions
+4. Reference `data/design-system/` for principles
+5. Use `templates/` for consistent output
+
+---
+
+**This workflow is called automatically from Phase 4. You don't need to run it manually.**

src/modules/wds/workflows/5-design-system/assessment/01-scan-existing.md

@@ -0,0 +1,158 @@
+# Assessment Step 1: Scan Existing Components
+
+**Purpose:** Find all components in design system that match the current component type.
+
+**Input:** Component type (e.g., "Button")
+
+**Output:** List of matching components with basic info
+
+---
+
+## Step 1: Read Design System Folder
+
+<action>
+Scan design system components:
+- Read all files in `D-Design-System/components/`
+- Parse component type from each file
+- Filter by matching type
+</action>
+
+**Example:**
+```
+Current component: Button
+
+Scanning D-Design-System/components/...
+- button.md → Type: Button ✓ Match
+- input-field.md → Type: Input Field ✗ No match
+- card.md → Type: Card ✗ No match
+```
+
+---
+
+## Step 2: Extract Component Metadata
+
+<action>
+For each matching component, extract:
+- Component ID (e.g., `btn-001`)
+- Variants (e.g., primary, secondary, ghost)
+- States (e.g., default, hover, active, disabled)
+- Key styling attributes
+- Usage count (how many pages use it)
+</action>
+
+**Example:**
+```yaml
+Button [btn-001]:
+  variants: [primary, secondary, ghost]
+  states: [default, hover, active, disabled]
+  styling:
+    size: medium
+    color: blue
+    shape: rounded
+  used_in: 3 pages
+```
+
+---
+
+## Step 3: Build Candidate List
+
+<output>
+Present matching components:
+
+```
+🔍 Found 1 existing Button component:
+
+**Button [btn-001]**
+- Variants: primary, secondary, ghost
+- States: default, hover, active, disabled
+- Size: medium
+- Color: blue
+- Shape: rounded
+- Used in: 3 pages (login, signup, dashboard)
+```
+</output>
+
+**If multiple matches:**
+```
+🔍 Found 2 existing Button components:
+
+**Button [btn-001]** - Primary action button
+- Variants: primary, secondary
+- Used in: 5 pages
+
+**Icon Button [btn-002]** - Icon-only button
+- Variants: small, medium, large
+- Used in: 8 pages
+```
+
+---
+
+## Step 4: Pass to Next Step
+
+<action>
+Pass candidate list to comparison step:
+- Component IDs
+- Full metadata
+- Current component specification
+</action>
+
+**Next:** `02-compare-attributes.md`
+
+---
+
+## Edge Cases
+
+**No matching components found:**
+```
+✓ No existing Button components in design system.
+
+This will be the first Button component.
+```
+
+**Route to:** `operations/create-new-component.md`
+
+**Design system empty:**
+```
+✓ Design system is empty.
+
+This will be the first component.
+```
+
+**Route to:** `operations/initialize-design-system.md`
+
+**Multiple type matches:**
+```
+🔍 Found 2 Button-type components:
+
+I'll compare your new button to both to find the best match.
+```
+
+**Continue to comparison for each candidate**
+
+---
+
+## Output Format
+
+**For next step:**
+```json
+{
+  "current_component": {
+    "type": "Button",
+    "specification": {...}
+  },
+  "candidates": [
+    {
+      "id": "btn-001",
+      "variants": ["primary", "secondary", "ghost"],
+      "states": ["default", "hover", "active", "disabled"],
+      "styling": {...},
+      "usage_count": 3,
+      "used_in": ["login", "signup", "dashboard"]
+    }
+  ]
+}
+```
+
+---
+
+**This step just scans and lists. Comparison happens in the next step.**

src/modules/wds/workflows/5-design-system/assessment/02-compare-attributes.md

@@ -0,0 +1,272 @@
+# Assessment Step 2: Compare Attributes
+
+**Purpose:** Systematically compare current component to existing candidates.
+
+**Input:** Current component spec + candidate list
+
+**Output:** Detailed comparison of similarities and differences
+
+---
+
+## Comparison Framework
+
+**Compare across 4 dimensions:**
+
+### 1. Visual Attributes
+- Size (small, medium, large)
+- Shape (rounded, square, pill)
+- Color scheme
+- Typography
+- Spacing/padding
+- Border style
+
+### 2. Functional Attributes
+- Purpose/intent
+- User action
+- Input/output type
+- Validation rules
+- Required/optional
+
+### 3. Behavioral Attributes
+- States (default, hover, active, disabled, loading, error)
+- Interactions (click, hover, focus, blur)
+- Animations/transitions
+- Keyboard support
+- Accessibility
+
+### 4. Contextual Attributes
+- Usage pattern (where it appears)
+- Frequency (how often used)
+- Relationship to other components
+- User journey stage
+
+---
+
+## Step 1: Visual Comparison
+
+<action>
+Compare visual attributes:
+- Extract visual properties from current spec
+- Extract visual properties from candidate
+- Calculate matches and differences
+</action>
+
+**Example:**
+```
+Visual Comparison: Current Button vs Button [btn-001]
+
+Similarities:
+✓ Size: medium (both)
+✓ Shape: rounded (both)
+✓ Color scheme: blue primary (both)
+
+Differences:
+✗ Current: Has icon on left
+✗ btn-001: Text only
+✗ Current: Slightly larger padding
+```
+
+---
+
+## Step 2: Functional Comparison
+
+<action>
+Compare functional attributes:
+- What does it do?
+- What's the user intent?
+- What's the outcome?
+</action>
+
+**Example:**
+```
+Functional Comparison: Current Button vs Button [btn-001]
+
+Similarities:
+✓ Purpose: Primary action trigger
+✓ User action: Click to submit/proceed
+✓ Outcome: Form submission or navigation
+
+Differences:
+✗ Current: "Continue to next step"
+✗ btn-001: "Submit form"
+✗ Current: Navigation action
+✗ btn-001: Form submission action
+```
+
+---
+
+## Step 3: Behavioral Comparison
+
+<action>
+Compare behavioral attributes:
+- States
+- Interactions
+- Animations
+</action>
+
+**Example:**
+```
+Behavioral Comparison: Current Button vs Button [btn-001]
+
+Similarities:
+✓ States: default, hover, active, disabled (both)
+✓ Hover: Darkens background (both)
+✓ Disabled: Grayed out (both)
+
+Differences:
+✗ Current: Has loading state with spinner
+✗ btn-001: No loading state
+✗ Current: Icon rotates on hover
+```
+
+---
+
+## Step 4: Contextual Comparison
+
+<action>
+Compare contextual attributes:
+- Where is it used?
+- How often?
+- What's the pattern?
+</action>
+
+**Example:**
+```
+Contextual Comparison: Current Button vs Button [btn-001]
+
+Similarities:
+✓ Both: Primary action in forms
+✓ Both: Bottom-right of containers
+✓ Both: High-frequency usage
+
+Differences:
+✗ Current: Multi-step flow navigation
+✗ btn-001: Single-page form submission
+✗ Current: Always has "next" context
+```
+
+---
+
+## Step 5: Calculate Similarity Score
+
+<action>
+Score each dimension:
+- Visual: High/Medium/Low similarity
+- Functional: High/Medium/Low similarity
+- Behavioral: High/Medium/Low similarity
+- Contextual: High/Medium/Low similarity
+</action>
+
+**Scoring Guide:**
+- **High:** 80%+ attributes match
+- **Medium:** 50-79% attributes match
+- **Low:** <50% attributes match
+
+**Example:**
+```
+Similarity Score: Current Button vs Button [btn-001]
+
+Visual:      High (90% match)
+Functional:  Medium (60% match)
+Behavioral:  Medium (70% match)
+Contextual:  Medium (65% match)
+
+Overall:     Medium-High Similarity
+```
+
+---
+
+## Step 6: Summarize Comparison
+
+<output>
+Present comparison summary:
+
+```
+📊 Comparison: Current Button vs Button [btn-001]
+
+**Similarities:**
+✓ Visual appearance (size, shape, color)
+✓ Primary action purpose
+✓ Standard states (default, hover, active, disabled)
+✓ High-frequency usage pattern
+
+**Differences:**
+✗ Current has icon, btn-001 is text-only
+✗ Current has loading state, btn-001 doesn't
+✗ Current for navigation, btn-001 for submission
+✗ Current has icon animation
+
+**Similarity Score:** Medium-High (71%)
+```
+</output>
+
+---
+
+## Step 7: Pass to Next Step
+
+<action>
+Pass comparison data to similarity calculation:
+- Detailed comparison
+- Similarity scores
+- Key differences
+</action>
+
+**Next:** `03-calculate-similarity.md`
+
+---
+
+## Edge Cases
+
+**Perfect match (100%):**
+```
+✓ This component is identical to btn-001.
+
+This is likely the same component with different content.
+```
+
+**Recommend:** Reuse existing component
+
+**Very low similarity (<30%):**
+```
+✗ This component is very different from btn-001.
+
+Despite being the same type, these serve different purposes.
+```
+
+**Recommend:** Create new component
+
+**Multiple candidates:**
+```
+📊 Comparing to 2 candidates:
+
+Button [btn-001]: 71% similarity
+Icon Button [btn-002]: 45% similarity
+
+btn-001 is the closest match.
+```
+
+**Continue with best match**
+
+---
+
+## Output Format
+
+**For next step:**
+```json
+{
+  "comparison": {
+    "candidate_id": "btn-001",
+    "visual_similarity": "high",
+    "functional_similarity": "medium",
+    "behavioral_similarity": "medium",
+    "contextual_similarity": "medium",
+    "overall_score": 0.71,
+    "similarities": [...],
+    "differences": [...]
+  }
+}
+```
+
+---
+
+**This step compares systematically. Interpretation happens in the next step.**

src/modules/wds/workflows/5-design-system/assessment/03-calculate-similarity.md

@@ -0,0 +1,319 @@
+# Assessment Step 3: Calculate Similarity
+
+**Purpose:** Interpret comparison data and determine similarity level.
+
+**Input:** Detailed comparison with scores
+
+**Output:** Similarity classification and recommendation
+
+---
+
+## Similarity Levels
+
+### Level 1: Identical (95-100%)
+**Characteristics:**
+- All visual attributes match
+- Same functional purpose
+- Same behavioral patterns
+- Only content differs (labels, text)
+
+**Interpretation:** This is the same component
+
+**Recommendation:** Reuse existing component reference
+
+---
+
+### Level 2: Very High Similarity (80-94%)
+**Characteristics:**
+- Visual attributes mostly match
+- Same core function
+- Minor behavioral differences
+- Same usage context
+
+**Interpretation:** This is likely the same component with minor variations
+
+**Recommendation:** Consider adding variant to existing component
+
+---
+
+### Level 3: High Similarity (65-79%)
+**Characteristics:**
+- Visual attributes similar
+- Related functional purpose
+- Some behavioral differences
+- Similar usage context
+
+**Interpretation:** Could be same component or new variant
+
+**Recommendation:** Designer decision needed - variant or new?
+
+---
+
+### Level 4: Medium Similarity (45-64%)
+**Characteristics:**
+- Some visual overlap
+- Different functional purpose
+- Different behaviors
+- Different usage context
+
+**Interpretation:** Related but distinct components
+
+**Recommendation:** Likely new component, but designer should confirm
+
+---
+
+### Level 5: Low Similarity (20-44%)
+**Characteristics:**
+- Minimal visual overlap
+- Different function
+- Different behaviors
+- Different context
+
+**Interpretation:** Different components that happen to share a type
+
+**Recommendation:** Create new component
+
+---
+
+### Level 6: No Similarity (<20%)
+**Characteristics:**
+- No meaningful overlap
+- Completely different purpose
+- Unrelated patterns
+
+**Interpretation:** Unrelated components
+
+**Recommendation:** Definitely create new component
+
+---
+
+## Calculation Logic
+
+<action>
+Calculate overall similarity:
+1. Weight each dimension:
+   - Visual: 30%
+   - Functional: 30%
+   - Behavioral: 25%
+   - Contextual: 15%
+
+2. Convert dimension scores to numeric:
+   - High = 1.0
+   - Medium = 0.6
+   - Low = 0.2
+
+3. Calculate weighted average:
+   - Overall = (Visual × 0.3) + (Functional × 0.3) + (Behavioral × 0.25) + (Contextual × 0.15)
+
+4. Convert to percentage:
+   - Similarity % = Overall × 100
+</action>
+
+**Example:**
+```
+Dimension Scores:
+- Visual: High (1.0)
+- Functional: Medium (0.6)
+- Behavioral: Medium (0.6)
+- Contextual: Medium (0.6)
+
+Calculation:
+(1.0 × 0.3) + (0.6 × 0.3) + (0.6 × 0.25) + (0.6 × 0.15)
+= 0.3 + 0.18 + 0.15 + 0.09
+= 0.72
+
+Similarity: 72% (High Similarity - Level 3)
+```
+
+---
+
+## Step 1: Calculate Score
+
+<action>
+Apply calculation logic to comparison data
+</action>
+
+<output>
+```
+📊 Similarity Calculation
+
+Visual:      High (1.0)    × 30% = 0.30
+Functional:  Medium (0.6)  × 30% = 0.18
+Behavioral:  Medium (0.6)  × 25% = 0.15
+Contextual:  Medium (0.6)  × 15% = 0.09
+
+Overall Similarity: 72%
+Level: High Similarity (Level 3)
+```
+</output>
+
+---
+
+## Step 2: Classify Similarity
+
+<action>
+Map percentage to similarity level
+</action>
+
+<output>
+```
+**Similarity Level: High (72%)**
+
+This component is similar to Button [btn-001] but has some differences.
+
+Could be:
+- A variant of the existing button
+- A new related button component
+
+Designer decision needed.
+```
+</output>
+
+---
+
+## Step 3: Generate Recommendation
+
+<action>
+Based on similarity level, generate recommendation with reasoning
+</action>
+
+**For Level 1-2 (Identical/Very High):**
+```
+✅ Recommendation: Reuse existing component
+
+Reasoning:
+- Components are nearly identical
+- Only content/labels differ
+- Same visual and behavioral patterns
+- Maintaining consistency is straightforward
+```
+
+**For Level 3 (High):**
+```
+🤔 Recommendation: Designer decision needed
+
+This could go either way:
+- Similar enough to be a variant
+- Different enough to be separate
+
+I'll present the trade-offs so you can decide.
+```
+
+**For Level 4-5 (Medium/Low):**
+```
+🆕 Recommendation: Create new component
+
+Reasoning:
+- Significant functional differences
+- Different usage contexts
+- Trying to merge would create complexity
+- Better to keep separate
+```
+
+**For Level 6 (No similarity):**
+```
+✅ Recommendation: Definitely create new component
+
+Reasoning:
+- Components are fundamentally different
+- No meaningful overlap
+- No benefit to linking them
+```
+
+---
+
+## Step 4: Identify Key Decision Factors
+
+<action>
+Highlight the most important differences that affect the decision
+</action>
+
+**Example:**
+```
+🔑 Key Decision Factors:
+
+1. **Icon presence** - Current has icon, existing doesn't
+   Impact: Visual consistency, component complexity
+
+2. **Loading state** - Current has loading, existing doesn't
+   Impact: Behavioral complexity, reusability
+
+3. **Navigation vs Submission** - Different purposes
+   Impact: Semantic meaning, developer understanding
+
+These differences will affect your decision.
+```
+
+---
+
+## Step 5: Pass to Next Step
+
+<action>
+Pass classification and recommendation to opportunity identification:
+- Similarity level
+- Recommendation
+- Key decision factors
+</action>
+
+**Next:** `04-identify-opportunities.md`
+
+---
+
+## Edge Cases
+
+**Borderline cases (near threshold):**
+```
+⚠️ Borderline Case: 64% similarity
+
+This is right on the edge between "High" and "Medium" similarity.
+
+I'll present both perspectives so you can make an informed decision.
+```
+
+**Multiple candidates with similar scores:**
+```
+📊 Multiple Similar Candidates:
+
+Button [btn-001]: 72% similarity
+Button [btn-003]: 68% similarity
+
+btn-001 is slightly closer, but both are viable options.
+I'll compare to btn-001 for the decision.
+```
+
+**Perfect match but different context:**
+```
+⚠️ Unusual Pattern: 98% similarity but different context
+
+Visually and behaviorally identical, but used in completely different contexts.
+
+This might indicate:
+- Same component, different use case ✓
+- Accidental duplication ⚠️
+- Context-specific variant needed 🤔
+```
+
+---
+
+## Output Format
+
+**For next step:**
+```json
+{
+  "similarity": {
+    "percentage": 72,
+    "level": "high",
+    "level_number": 3,
+    "recommendation": "designer_decision",
+    "key_factors": [
+      "Icon presence",
+      "Loading state",
+      "Navigation vs Submission"
+    ]
+  }
+}
+```
+
+---
+
+**This step calculates and classifies. Opportunity/risk analysis happens in the next steps.**

src/modules/wds/workflows/5-design-system/assessment/04-identify-opportunities.md

@@ -0,0 +1,317 @@
+# Assessment Step 4: Identify Opportunities
+
+**Purpose:** Identify potential benefits of different design system decisions.
+
+**Input:** Similarity analysis and comparison data
+
+**Output:** List of opportunities for each option
+
+---
+
+## Decision Options
+
+For each similar component, there are 3 options:
+
+### Option 1: Reuse Existing Component
+Use the existing component reference, just change content
+
+### Option 2: Add Variant to Existing
+Extend existing component with new variant
+
+### Option 3: Create New Component
+Create separate component in design system
+
+---
+
+## Opportunity Analysis Framework
+
+### For Option 1: Reuse Existing
+
+**Potential Opportunities:**
+
+#### Consistency
+- ✅ Visual consistency across pages
+- ✅ Behavioral consistency (same interactions)
+- ✅ User familiarity (looks/works the same)
+- ✅ Brand coherence
+
+#### Maintenance
+- ✅ Single source of truth
+- ✅ Update once, applies everywhere
+- ✅ Easier to maintain
+- ✅ Fewer files to manage
+
+#### Development
+- ✅ Faster development (component exists)
+- ✅ Less code duplication
+- ✅ Easier testing (test once)
+- ✅ Better performance (reused code)
+
+#### Design System
+- ✅ Cleaner design system
+- ✅ Fewer components to document
+- ✅ Easier for developers to find
+- ✅ Simpler component library
+
+---
+
+### For Option 2: Add Variant
+
+**Potential Opportunities:**
+
+#### Flexibility
+- ✅ Accommodates different use cases
+- ✅ Maintains component family
+- ✅ Allows contextual adaptation
+- ✅ Supports design evolution
+
+#### Consistency
+- ✅ Related components stay connected
+- ✅ Shared base styling
+- ✅ Consistent naming pattern
+- ✅ Clear component relationships
+
+#### Scalability
+- ✅ Easy to add more variants later
+- ✅ Supports design system growth
+- ✅ Handles edge cases gracefully
+- ✅ Accommodates future needs
+
+#### Documentation
+- ✅ Variants documented together
+- ✅ Clear component family
+- ✅ Easier to understand relationships
+- ✅ Better developer guidance
+
+---
+
+### For Option 3: Create New
+
+**Potential Opportunities:**
+
+#### Clarity
+- ✅ Clear separation of concerns
+- ✅ Distinct purpose/function
+- ✅ No confusion about usage
+- ✅ Semantic clarity
+
+#### Simplicity
+- ✅ Simpler component definition
+- ✅ No complex variant logic
+- ✅ Easier to understand
+- ✅ Fewer edge cases
+
+#### Independence
+- ✅ Can evolve independently
+- ✅ No impact on other components
+- ✅ Easier to modify
+- ✅ No unintended side effects
+
+#### Specificity
+- ✅ Optimized for specific use case
+- ✅ No unnecessary features
+- ✅ Better performance
+- ✅ Clearer developer intent
+
+---
+
+## Step 1: Analyze Current Situation
+
+<action>
+Based on similarity level and comparison, identify which opportunities apply
+</action>
+
+**Example (72% similarity):**
+```
+Current Situation:
+- High visual similarity
+- Different functional purpose (navigation vs submission)
+- Some behavioral differences (loading state, icon)
+- Similar usage context
+
+Applicable Opportunities:
+- Reuse: Consistency, maintenance benefits
+- Variant: Flexibility, maintains family
+- New: Clarity of purpose, independence
+```
+
+---
+
+## Step 2: Generate Opportunity Lists
+
+<output>
+**Option 1: Reuse Button [btn-001]**
+
+Opportunities:
+✅ **Consistency:** All buttons look and behave the same
+✅ **Maintenance:** Update button styling once, applies everywhere
+✅ **Simplicity:** Fewer components in design system
+✅ **Development:** Faster implementation (component exists)
+
+Best if: Visual consistency is more important than functional distinction
+</output>
+
+<output>
+**Option 2: Add "Navigation" Variant to Button [btn-001]**
+
+Opportunities:
+✅ **Flexibility:** Supports both submission and navigation use cases
+✅ **Family:** Keeps related buttons together
+✅ **Scalability:** Easy to add more button types later
+✅ **Documentation:** All button variants in one place
+
+Best if: You want to maintain button family but need different behaviors
+</output>
+
+<output>
+**Option 3: Create New "Navigation Button" Component**
+
+Opportunities:
+✅ **Clarity:** Clear distinction between submission and navigation
+✅ **Semantics:** Developers understand purpose immediately
+✅ **Independence:** Can evolve without affecting submit buttons
+✅ **Optimization:** Tailored for navigation use case
+
+Best if: Functional distinction is more important than visual consistency
+</output>
+
+---
+
+## Step 3: Highlight Strongest Opportunities
+
+<action>
+Based on comparison data, identify the most compelling opportunities for each option
+</action>
+
+**Example:**
+```
+🌟 Strongest Opportunities:
+
+**For Reuse:**
+- Your buttons are 90% visually identical
+- Consistency would be very strong
+- Maintenance would be significantly easier
+
+**For Variant:**
+- You have 2 distinct button purposes emerging
+- Variant structure would accommodate both
+- Future button types could fit this pattern
+
+**For New:**
+- Navigation and submission are semantically different
+- Developers would benefit from clear distinction
+- Each could evolve independently as needs change
+```
+
+---
+
+## Step 4: Consider Project Context
+
+<action>
+Factor in project-specific considerations:
+- Design system maturity (new vs established)
+- Team size (solo vs large team)
+- Project complexity (simple vs complex)
+- Timeline (fast vs thorough)
+</action>
+
+**Example:**
+```
+📋 Project Context:
+
+Design System: New (3 components so far)
+Team: Small (2-3 people)
+Complexity: Medium
+Timeline: Moderate
+
+Context-Specific Opportunities:
+- **New design system:** Easier to keep simple (favors reuse/variant)
+- **Small team:** Fewer components = easier maintenance (favors reuse)
+- **Medium complexity:** Room for some structure (favors variant)
+```
+
+---
+
+## Step 5: Pass to Next Step
+
+<action>
+Pass opportunity analysis to risk identification:
+- Opportunities for each option
+- Strongest opportunities
+- Context considerations
+</action>
+
+**Next:** `05-identify-risks.md`
+
+---
+
+## Edge Cases
+
+**All options have strong opportunities:**
+```
+✨ All Options Look Good!
+
+Each approach has compelling opportunities:
+- Reuse: Strong consistency benefits
+- Variant: Good balance of flexibility
+- New: Clear semantic distinction
+
+This means the risks will be the deciding factor.
+```
+
+**No clear opportunities:**
+```
+⚠️ No Strong Opportunities Identified
+
+This might mean:
+- Components are too different to benefit from connection
+- Or too similar to benefit from separation
+
+I'll focus on risks to help clarify the decision.
+```
+
+**Conflicting opportunities:**
+```
+⚠️ Conflicting Opportunities
+
+Reuse offers consistency, but New offers clarity.
+These are competing values.
+
+Your design philosophy will guide this decision:
+- Value consistency? → Reuse
+- Value semantics? → New
+```
+
+---
+
+## Output Format
+
+**For next step:**
+```json
+{
+  "opportunities": {
+    "reuse": {
+      "consistency": "high",
+      "maintenance": "high",
+      "development": "medium",
+      "strongest": ["consistency", "maintenance"]
+    },
+    "variant": {
+      "flexibility": "high",
+      "family": "medium",
+      "scalability": "high",
+      "strongest": ["flexibility", "scalability"]
+    },
+    "new": {
+      "clarity": "high",
+      "independence": "high",
+      "specificity": "medium",
+      "strongest": ["clarity", "independence"]
+    }
+  }
+}
+```
+
+---
+
+**This step identifies opportunities. Risks are analyzed in the next step.**

src/modules/wds/workflows/5-design-system/assessment/05-identify-risks.md

@@ -0,0 +1,337 @@
+# Assessment Step 5: Identify Risks
+
+**Purpose:** Identify potential problems with each design system decision.
+
+**Input:** Similarity analysis and opportunity analysis
+
+**Output:** List of risks for each option
+
+---
+
+## Risk Analysis Framework
+
+### For Option 1: Reuse Existing
+
+**Potential Risks:**
+
+#### Loss of Distinction
+- ❌ Different purposes look identical
+- ❌ Users can't distinguish actions
+- ❌ Semantic meaning lost
+- ❌ Accessibility issues (same label, different action)
+
+#### Constraint
+- ❌ Forced to use existing styling
+- ❌ Can't optimize for specific use case
+- ❌ Future changes constrained
+- ❌ Design evolution limited
+
+#### Confusion
+- ❌ Developers confused about usage
+- ❌ Same component, different behaviors
+- ❌ Unclear when to use
+- ❌ Documentation complexity
+
+#### Technical Debt
+- ❌ Component becomes overloaded
+- ❌ Too many conditional behaviors
+- ❌ Hard to maintain
+- ❌ Performance issues
+
+---
+
+### For Option 2: Add Variant
+
+**Potential Risks:**
+
+#### Complexity
+- ❌ Component becomes complex
+- ❌ Many variants to manage
+- ❌ Harder to understand
+- ❌ More documentation needed
+
+#### Maintenance Burden
+- ❌ Changes affect all variants
+- ❌ Testing becomes complex
+- ❌ More edge cases to handle
+- ❌ Harder to refactor
+
+#### Variant Explosion
+- ❌ Too many variants over time
+- ❌ Unclear which variant to use
+- ❌ Variants become too specific
+- ❌ Component loses coherence
+
+#### Coupling
+- ❌ Variants tightly coupled
+- ❌ Can't change one without affecting others
+- ❌ Shared code creates dependencies
+- ❌ Harder to deprecate
+
+---
+
+### For Option 3: Create New
+
+**Potential Risks:**
+
+#### Inconsistency
+- ❌ Visual inconsistency across pages
+- ❌ Different styling for similar components
+- ❌ User confusion
+- ❌ Brand fragmentation
+
+#### Duplication
+- ❌ Duplicate code
+- ❌ Duplicate maintenance
+- ❌ Duplicate testing
+- ❌ Duplicate documentation
+
+#### Proliferation
+- ❌ Too many components in design system
+- ❌ Hard to find right component
+- ❌ Developers create more duplicates
+- ❌ Design system becomes unwieldy
+
+#### Divergence
+- ❌ Components drift over time
+- ❌ Accidental inconsistencies
+- ❌ Harder to maintain coherence
+- ❌ More work to keep aligned
+
+---
+
+## Step 1: Analyze Current Situation for Risks
+
+<action>
+Based on similarity level and comparison, identify which risks apply
+</action>
+
+**Example (72% similarity, different purposes):**
+```
+Current Situation:
+- High visual similarity (90%)
+- Different functional purpose (navigation vs submission)
+- Some behavioral differences (loading state, icon)
+
+Risk Indicators:
+- Reuse: High risk of semantic confusion
+- Variant: Medium risk of complexity
+- New: Medium risk of visual inconsistency
+```
+
+---
+
+## Step 2: Generate Risk Lists
+
+<output>
+**Option 1: Reuse Button [btn-001]**
+
+Risks:
+❌ **Semantic Confusion:** Navigation and submission look identical
+❌ **Accessibility:** Screen readers can't distinguish actions
+❌ **Developer Confusion:** Same component, different behaviors
+❌ **Future Constraint:** Can't optimize for navigation use case
+
+Highest Risk: Semantic confusion - users won't understand the difference
+</output>
+
+<output>
+**Option 2: Add "Navigation" Variant to Button [btn-001]**
+
+Risks:
+❌ **Complexity:** Button component now handles 2 different purposes
+❌ **Maintenance:** Changes to button affect both submission and navigation
+❌ **Variant Explosion:** What about other button types? (delete, cancel, etc.)
+❌ **Documentation:** Need to explain when to use each variant
+
+Highest Risk: Variant explosion - could lead to 10+ button variants
+</output>
+
+<output>
+**Option 3: Create New "Navigation Button" Component**
+
+Risks:
+❌ **Visual Inconsistency:** Two similar-looking buttons with different names
+❌ **Duplication:** Similar code in two components
+❌ **Proliferation:** More components in design system
+❌ **Developer Choice:** Which button should I use?
+
+Highest Risk: Visual inconsistency - buttons might drift apart over time
+</output>
+
+---
+
+## Step 3: Assess Risk Severity
+
+<action>
+Rate each risk as Low/Medium/High severity based on:
+- Impact if it occurs
+- Likelihood of occurring
+- Difficulty to fix later
+</action>
+
+**Example:**
+```
+Risk Severity Assessment:
+
+**Reuse Option:**
+- Semantic confusion: HIGH (impacts UX, hard to fix)
+- Accessibility: HIGH (compliance issue)
+- Developer confusion: MEDIUM (documentation can help)
+- Future constraint: MEDIUM (can refactor later)
+
+**Variant Option:**
+- Complexity: MEDIUM (manageable with good structure)
+- Maintenance: MEDIUM (testing helps)
+- Variant explosion: HIGH (hard to reverse)
+- Documentation: LOW (just needs writing)
+
+**New Option:**
+- Visual inconsistency: MEDIUM (can be monitored)
+- Duplication: LOW (acceptable trade-off)
+- Proliferation: MEDIUM (can be managed)
+- Developer choice: LOW (documentation helps)
+```
+
+---
+
+## Step 4: Identify Deal-Breaker Risks
+
+<action>
+Highlight risks that would make an option unsuitable
+</action>
+
+**Example:**
+```
+🚨 Deal-Breaker Risks:
+
+**Reuse:**
+- Semantic confusion is HIGH risk
+- Accessibility issue is HIGH risk
+→ This option might not be viable
+
+**Variant:**
+- Variant explosion is HIGH risk
+- But can be mitigated with clear guidelines
+→ This option is risky but manageable
+
+**New:**
+- No HIGH severity risks identified
+- All risks are manageable
+→ This option is safest
+```
+
+---
+
+## Step 5: Consider Mitigation Strategies
+
+<action>
+For each risk, identify if/how it can be mitigated
+</action>
+
+**Example:**
+```
+Risk Mitigation:
+
+**Reuse - Semantic Confusion:**
+- Mitigation: Use different labels/icons
+- Effectiveness: LOW (still same component)
+- Verdict: Hard to mitigate
+
+**Variant - Variant Explosion:**
+- Mitigation: Strict variant guidelines
+- Effectiveness: MEDIUM (requires discipline)
+- Verdict: Can be managed
+
+**New - Visual Inconsistency:**
+- Mitigation: Shared design tokens
+- Effectiveness: HIGH (tokens ensure consistency)
+- Verdict: Easily mitigated
+```
+
+---
+
+## Step 6: Pass to Next Step
+
+<action>
+Pass risk analysis to decision presentation:
+- Risks for each option
+- Severity ratings
+- Deal-breaker risks
+- Mitigation strategies
+</action>
+
+**Next:** `06-present-decision.md`
+
+---
+
+## Edge Cases
+
+**All options have high risks:**
+```
+⚠️ All Options Have Significant Risks
+
+This is a tough decision:
+- Reuse: Semantic confusion
+- Variant: Complexity explosion
+- New: Inconsistency
+
+I'll present all trade-offs clearly so you can make an informed choice.
+```
+
+**No significant risks:**
+```
+✅ Low Risk Situation
+
+All options have manageable risks:
+- Reuse: Minor constraint
+- Variant: Slight complexity
+- New: Minimal duplication
+
+Focus on opportunities to decide.
+```
+
+**One option has deal-breaker risk:**
+```
+🚨 One Option Not Recommended
+
+Reuse has HIGH accessibility risk that's hard to mitigate.
+
+I'll present Variant vs New as the viable options.
+```
+
+---
+
+## Output Format
+
+**For next step:**
+```json
+{
+  "risks": {
+    "reuse": {
+      "semantic_confusion": "high",
+      "accessibility": "high",
+      "developer_confusion": "medium",
+      "deal_breaker": true
+    },
+    "variant": {
+      "complexity": "medium",
+      "variant_explosion": "high",
+      "maintenance": "medium",
+      "deal_breaker": false,
+      "mitigation": "strict_guidelines"
+    },
+    "new": {
+      "visual_inconsistency": "medium",
+      "duplication": "low",
+      "proliferation": "medium",
+      "deal_breaker": false,
+      "mitigation": "shared_tokens"
+    }
+  }
+}
+```
+
+---
+
+**This step identifies risks. The next step presents the complete decision to the designer.**

src/modules/wds/workflows/5-design-system/assessment/06-present-decision.md

@@ -0,0 +1,396 @@
+# Assessment Step 6: Present Decision
+
+**Purpose:** Present complete analysis to designer for informed decision.
+
+**Input:** Comparison, opportunities, and risks
+
+**Output:** Clear decision options with trade-offs
+
+---
+
+## Presentation Structure
+
+### 1. Context Summary
+What we're deciding and why
+
+### 2. The Options
+Clear description of each choice
+
+### 3. Comparison Table
+Side-by-side trade-offs
+
+### 4. Recommendation
+AI's suggestion based on analysis
+
+### 5. Designer Choice
+Let designer decide
+
+---
+
+## Step 1: Present Context
+
+<output>
+```
+🔍 Design System Decision Needed
+
+**Current Component:** Navigation Button
+**Similar Component Found:** Button [btn-001]
+**Similarity:** 72% (High)
+
+**Key Similarities:**
+✓ Visual appearance (size, shape, color)
+✓ Primary action purpose
+✓ Standard states
+
+**Key Differences:**
+✗ Navigation vs submission purpose
+✗ Has icon and loading state
+✗ Different usage context
+
+**Decision:** How should we handle this in the design system?
+```
+</output>
+
+---
+
+## Step 2: Present Options
+
+<output>
+```
+📋 Your Options:
+
+**Option 1: Reuse Existing Component**
+Use Button [btn-001], just change the label to "Continue"
+
+**Option 2: Add Variant**
+Add "navigation" variant to Button [btn-001]
+- Button.primary (submit)
+- Button.navigation (continue)
+
+**Option 3: Create New Component**
+Create separate "Navigation Button" component [btn-002]
+```
+</output>
+
+---
+
+## Step 3: Present Trade-Offs Table
+
+<output>
+```
+📊 Trade-Offs Comparison:
+
+┌─────────────┬──────────────────┬──────────────────┬──────────────────┐
+│             │ Reuse [btn-001]  │ Add Variant      │ Create New       │
+├─────────────┼──────────────────┼──────────────────┼──────────────────┤
+│ Consistency │ ✅ Highest       │ ✅ High          │ ⚠️ Medium        │
+│ Maintenance │ ✅ Easiest       │ ⚠️ Moderate      │ ❌ More work     │
+│ Clarity     │ ❌ Confusing     │ ⚠️ Moderate      │ ✅ Clearest      │
+│ Flexibility │ ❌ Constrained   │ ✅ Flexible      │ ✅ Independent   │
+│ Complexity  │ ✅ Simple        │ ⚠️ More complex  │ ✅ Simple        │
+│ Semantics   │ ❌ Lost          │ ⚠️ Preserved     │ ✅ Clear         │
+├─────────────┼──────────────────┼──────────────────┼──────────────────┤
+│ Best For    │ Identical use    │ Related purposes │ Different roles  │
+└─────────────┴──────────────────┴──────────────────┴──────────────────┘
+
+Legend: ✅ Strong benefit | ⚠️ Trade-off | ❌ Potential issue
+```
+</output>
+
+---
+
+## Step 4: Present Detailed Analysis
+
+<output>
+```
+🔍 Detailed Analysis:
+
+**Option 1: Reuse Button [btn-001]**
+
+Opportunities:
+✅ Perfect visual consistency
+✅ Single source of truth
+✅ Easiest to maintain
+✅ Simplest design system
+
+Risks:
+❌ HIGH: Semantic confusion (navigation looks like submission)
+❌ HIGH: Accessibility issues (same component, different actions)
+❌ MEDIUM: Developer confusion
+❌ MEDIUM: Future constraint
+
+Verdict: ⚠️ Not recommended due to semantic/accessibility risks
+
+---
+
+**Option 2: Add "Navigation" Variant to Button [btn-001]**
+
+Opportunities:
+✅ Maintains button family
+✅ Flexible for different use cases
+✅ Easy to add more variants
+✅ All buttons documented together
+
+Risks:
+❌ HIGH: Variant explosion (could lead to 10+ variants)
+⚠️ MEDIUM: Component complexity increases
+⚠️ MEDIUM: Maintenance burden grows
+⚠️ LOW: Documentation overhead
+
+Mitigation: Strict variant guidelines can manage explosion risk
+
+Verdict: ✅ Viable option if you expect more button types
+
+---
+
+**Option 3: Create New "Navigation Button" [btn-002]**
+
+Opportunities:
+✅ Clear semantic distinction
+✅ Optimized for navigation use case
+✅ Independent evolution
+✅ Simple component definition
+
+Risks:
+⚠️ MEDIUM: Visual inconsistency over time
+⚠️ MEDIUM: More components to manage
+⚠️ LOW: Some code duplication
+⚠️ LOW: Developer choice overhead
+
+Mitigation: Shared design tokens ensure visual consistency
+
+Verdict: ✅ Safest option, especially for semantically different purposes
+```
+</output>
+
+---
+
+## Step 5: Present AI Recommendation
+
+<action>
+Based on analysis, provide recommendation with reasoning
+</action>
+
+<output>
+```
+🤖 AI Recommendation: Create New Component (Option 3)
+
+**Reasoning:**
+
+1. **Semantic Distinction Matters**
+   - Navigation and submission are fundamentally different actions
+   - Users and developers benefit from clear distinction
+   - Accessibility is better with separate components
+
+2. **Manageable Risks**
+   - Visual inconsistency can be prevented with shared tokens
+   - Duplication is minimal and acceptable
+   - Proliferation can be monitored
+
+3. **Future Flexibility**
+   - Each component can evolve independently
+   - No risk of variant explosion
+   - Clear component boundaries
+
+4. **Your Project Context**
+   - Design system is new (only 3 components)
+   - Better to establish clear patterns now
+   - Easier to merge later than split
+
+**However:** If you expect many button types (delete, cancel, save, etc.), 
+Option 2 (variant) might be better for organization.
+```
+</output>
+
+---
+
+## Step 6: Ask for Designer Decision
+
+<ask>
+```
+💭 Your Decision:
+
+Based on this analysis, which approach fits your design intent?
+
+[1] Reuse Button [btn-001]
+    → Choose if: Visual consistency is paramount, purposes are actually the same
+
+[2] Add "navigation" variant to Button [btn-001]
+    → Choose if: You want button family, expect more button types
+
+[3] Create new "Navigation Button" [btn-002]
+    → Choose if: Semantic distinction matters, want independence
+
+[4] I need more information
+    → I can clarify any aspect of the analysis
+
+Your choice (1/2/3/4):
+```
+</ask>
+
+---
+
+## Step 7: Handle Designer Response
+
+<action>
+Based on designer's choice, route to appropriate operation
+</action>
+
+**If Choice 1 (Reuse):**
+```
+✅ Got it - reusing Button [btn-001]
+
+I'll update the page spec to reference the existing component.
+```
+**Route to:** `07-execute-decision.md` with action: `reuse`
+
+**If Choice 2 (Variant):**
+```
+✅ Got it - adding "navigation" variant to Button [btn-001]
+
+I'll update the component definition and create the reference.
+```
+**Route to:** `07-execute-decision.md` with action: `add_variant`
+
+**If Choice 3 (New):**
+```
+✅ Got it - creating new Navigation Button [btn-002]
+
+I'll create the new component and set up the reference.
+```
+**Route to:** `07-execute-decision.md` with action: `create_new`
+
+**If Choice 4 (More Info):**
+```
+📚 What would you like to know more about?
+
+- Similarity calculation details
+- Specific opportunities or risks
+- How variants work
+- Component boundaries
+- Something else
+
+Your question:
+```
+**Provide clarification, then re-present decision**
+
+---
+
+## Presentation Variations
+
+### For High Similarity (80%+)
+
+<output>
+```
+✨ These components are very similar!
+
+Similarity: 87%
+
+The main question is: Are they the same thing with different content,
+or different things that happen to look similar?
+
+If same thing → Reuse
+If different things → Variant or New
+```
+</output>
+
+### For Low Similarity (40%-)
+
+<output>
+```
+⚠️ These components are quite different.
+
+Similarity: 38%
+
+They share a type (Button) but serve different purposes.
+Creating a new component is likely the best choice.
+
+Would you like to proceed with creating a new component,
+or would you like to see the full analysis?
+```
+</output>
+
+### For Borderline Cases
+
+<output>
+```
+🤔 This is a borderline case.
+
+Similarity: 64% (right between "High" and "Medium")
+
+This could go either way. I'll present both perspectives:
+
+**Perspective 1: Similar Enough**
+[Present variant option]
+
+**Perspective 2: Different Enough**
+[Present new component option]
+
+Your design philosophy will guide this decision.
+```
+</output>
+
+---
+
+## Edge Cases
+
+**Designer asks for recommendation:**
+```
+Based on the analysis, I recommend Option 3 (Create New).
+
+But this is your design system - you know your project best.
+
+What's most important to you?
+- Consistency? → Reuse or Variant
+- Clarity? → New
+- Flexibility? → Variant
+- Simplicity? → Reuse or New
+```
+
+**Designer is unsure:**
+```
+That's okay! This is a judgment call.
+
+Here's a simple heuristic:
+
+If a developer saw both buttons, would they think:
+A) "Same button, different label" → Reuse
+B) "Related buttons, different purposes" → Variant
+C) "Different buttons entirely" → New
+
+What's your gut feeling?
+```
+
+**Designer wants to defer decision:**
+```
+✅ No problem!
+
+I'll create it as a new component for now.
+
+You can always:
+- Merge it later if you decide they're the same
+- Convert it to a variant if you see a pattern
+- Keep it separate if the distinction is valuable
+
+Design systems evolve - this isn't permanent.
+```
+
+---
+
+## Output Format
+
+**For next step:**
+```json
+{
+  "decision": {
+    "choice": "create_new",
+    "component_id": "btn-002",
+    "reasoning": "Semantic distinction matters",
+    "designer_notes": "Navigation and submission are different actions"
+  }
+}
+```
+
+---
+
+**This step presents and captures the decision. Execution happens in the next step.**

src/modules/wds/workflows/5-design-system/assessment/07-execute-decision.md

@@ -0,0 +1,488 @@
+# Assessment Step 7: Execute Decision
+
+**Purpose:** Execute the designer's decision and complete design system operation.
+
+**Input:** Designer's choice (reuse/variant/new)
+
+**Output:** Updated design system and page spec with reference
+
+---
+
+## Execution Paths
+
+### Path A: Reuse Existing Component
+Designer chose to use existing component as-is
+
+### Path B: Add Variant
+Designer chose to add variant to existing component
+
+### Path C: Create New Component
+Designer chose to create new component
+
+---
+
+## Path A: Reuse Existing Component
+
+### Step 1: Confirm Action
+
+<output>
+```
+✅ Reusing Button [btn-001]
+
+I'll update your page spec to reference the existing component.
+```
+</output>
+
+### Step 2: Extract Page-Specific Content
+
+<action>
+From complete specification, extract:
+- Labels/text content
+- Page-specific why/purpose
+- Error messages
+- Contextual information
+</action>
+
+**Example:**
+```yaml
+Page-Specific Content:
+- label: "Continue"
+- why: "Navigate to next step in onboarding"
+- context: "Multi-step form navigation"
+```
+
+### Step 3: Create Reference
+
+<action>
+Create reference to existing component:
+- Component ID: btn-001
+- Variant: primary (or whichever applies)
+- Page-specific content
+</action>
+
+**Output:**
+```yaml
+# C-Scenarios/onboarding-page.md
+
+Continue Button:
+  component: Button.primary [btn-001]
+  why: Navigate to next step in onboarding
+  label: "Continue"
+```
+
+### Step 4: Update Component Usage
+
+<action>
+Update design system component to track usage:
+- Add page to "Used In" list
+- Increment usage count
+</action>
+
+**Update:**
+```yaml
+# D-Design-System/components/button.md
+
+Used In:
+- Login page (login button)
+- Signup page (create account button)
+- Dashboard (action buttons)
+- Onboarding page (continue button)  ← Added
+```
+
+### Step 5: Complete
+
+<output>
+```
+✅ Done! Button [btn-001] is now used on onboarding page.
+
+Page spec updated with reference.
+Component usage tracked.
+```
+</output>
+
+**Return to Phase 4**
+
+---
+
+## Path B: Add Variant
+
+### Step 1: Confirm Action
+
+<output>
+```
+✅ Adding "navigation" variant to Button [btn-001]
+
+I'll update the component definition and create the reference.
+```
+</output>
+
+### Step 2: Extract Component-Level Info
+
+<action>
+From complete specification, extract:
+- Variant-specific styling
+- Variant-specific states
+- Variant-specific behaviors
+</action>
+
+**Example:**
+```yaml
+Navigation Variant:
+- icon: arrow-right
+- loading_state: true
+- hover_animation: icon_shift
+```
+
+### Step 3: Update Component Definition
+
+<action>
+Add variant to existing component:
+- Add to variants list
+- Document variant-specific attributes
+- Maintain shared attributes
+</action>
+
+**Update:**
+```yaml
+# D-Design-System/components/button.md
+
+Button Component [btn-001]:
+  
+  variants:
+    - primary (submit actions)
+    - secondary (cancel actions)
+    - navigation (continue/next actions)  ← Added
+  
+  shared_states:
+    - default, hover, active, disabled
+  
+  variant_specific:
+    navigation:
+      icon: arrow-right
+      loading_state: true
+      hover_animation: icon_shift
+```
+
+### Step 4: Create Reference
+
+<action>
+Create reference with variant specified:
+</action>
+
+**Output:**
+```yaml
+# C-Scenarios/onboarding-page.md
+
+Continue Button:
+  component: Button.navigation [btn-001]  ← Variant specified
+  why: Navigate to next step in onboarding
+  label: "Continue"
+```
+
+### Step 5: Update Usage Tracking
+
+<action>
+Track variant usage:
+</action>
+
+**Update:**
+```yaml
+# D-Design-System/components/button.md
+
+Variant Usage:
+  primary: 5 pages
+  secondary: 3 pages
+  navigation: 1 page  ← Added
+```
+
+### Step 6: Complete
+
+<output>
+```
+✅ Done! Navigation variant added to Button [btn-001].
+
+Component definition updated.
+Page spec created with variant reference.
+Variant usage tracked.
+```
+</output>
+
+**Return to Phase 4**
+
+---
+
+## Path C: Create New Component
+
+### Step 1: Confirm Action
+
+<output>
+```
+✅ Creating new Navigation Button [btn-002]
+
+I'll create the component definition and set up the reference.
+```
+</output>
+
+### Step 2: Generate Component ID
+
+<action>
+Generate unique component ID:
+- Check existing IDs
+- Increment counter for type
+- Format: [type-prefix]-[number]
+</action>
+
+**Example:**
+```
+Existing Button IDs: btn-001
+New ID: btn-002
+```
+
+### Step 3: Extract Component-Level Info
+
+<action>
+From complete specification, extract:
+- Visual attributes (size, shape, color)
+- States (default, hover, active, disabled, loading)
+- Behaviors (interactions, animations)
+- Styling (design tokens or Figma reference)
+</action>
+
+**Example:**
+```yaml
+Component-Level Info:
+  type: Button
+  purpose: Navigation actions
+  states: [default, hover, active, disabled, loading]
+  icon: arrow-right
+  size: medium
+  color: blue
+  shape: rounded
+  hover_animation: icon_shift
+```
+
+### Step 4: Create Component File
+
+<action>
+Create new component file using template:
+</action>
+
+**Route to:** `operations/create-new-component.md`
+
+**Output:**
+```yaml
+# D-Design-System/components/navigation-button.md
+
+# Navigation Button [btn-002]
+
+**Type:** Interactive
+**Purpose:** Navigation actions (continue, next, proceed)
+**Library:** shadcn/ui Button (if Mode C)
+**Figma:** [Link] (if Mode B)
+
+## States
+- default
+- hover
+- active
+- disabled
+- loading (with spinner)
+
+## Styling
+- Size: medium
+- Color: blue primary
+- Shape: rounded
+- Icon: arrow-right
+- Hover: icon shifts right
+
+## Used In
+- Onboarding page (continue button)
+```
+
+### Step 5: Create Reference
+
+<action>
+Create reference in page spec:
+</action>
+
+**Output:**
+```yaml
+# C-Scenarios/onboarding-page.md
+
+Continue Button:
+  component: NavigationButton [btn-002]
+  why: Navigate to next step in onboarding
+  label: "Continue"
+```
+
+### Step 6: Update Design System Index
+
+<action>
+Add to design system component list:
+</action>
+
+**Update:**
+```yaml
+# D-Design-System/components/README.md
+
+Components:
+- Button [btn-001] - Primary action buttons
+- Input Field [inp-001] - Text input fields
+- Card [crd-001] - Content cards
+- Navigation Button [btn-002] - Navigation actions  ← Added
+```
+
+### Step 7: Complete
+
+<output>
+```
+✅ Done! Navigation Button [btn-002] created.
+
+Component file created: D-Design-System/components/navigation-button.md
+Page spec created with reference.
+Design system index updated.
+```
+</output>
+
+**Return to Phase 4**
+
+---
+
+## Post-Execution Actions
+
+### Update Project State
+
+<action>
+Update project tracking:
+- Increment component count
+- Update design system status
+- Log decision for future reference
+</action>
+
+**Example:**
+```yaml
+# A-Project-Brief/design-system-log.md
+
+2024-12-09: Created Navigation Button [btn-002]
+- Reason: Semantic distinction from submit buttons
+- Decision: Create new vs variant
+- Designer: Chose clarity over consistency
+```
+
+### Notify Designer
+
+<output>
+```
+📊 Design System Update:
+
+Components: 4 (was 3)
+Latest: Navigation Button [btn-002]
+
+Your design system is growing! Consider reviewing component 
+organization when you reach 10+ components.
+```
+</output>
+
+---
+
+## Error Handling
+
+**If component creation fails:**
+```
+❌ Error creating component file.
+
+Error: [error message]
+
+Would you like to:
+1. Retry
+2. Create manually
+3. Skip design system for this component
+
+Your choice:
+```
+
+**If reference creation fails:**
+```
+❌ Error updating page spec.
+
+Error: [error message]
+
+Component was created successfully, but page reference failed.
+I'll keep the complete spec on the page for now.
+```
+
+**If ID conflict:**
+```
+⚠️ Component ID conflict detected.
+
+btn-002 already exists but with different content.
+
+Generating alternative ID: btn-003
+```
+
+---
+
+## Validation
+
+### Before Completing
+
+<action>
+Validate execution:
+- ✓ Component file created (if new)
+- ✓ Component updated (if variant)
+- ✓ Page spec has reference
+- ✓ Usage tracked
+- ✓ Design system index updated
+</action>
+
+**If validation fails:**
+```
+⚠️ Validation Warning:
+
+Some steps may not have completed successfully.
+Please review:
+- [List of potential issues]
+
+Continue anyway? (y/n)
+```
+
+---
+
+## Return to Phase 4
+
+<action>
+Return control to Phase 4 orchestration:
+- Pass component reference
+- Pass page-specific content
+- Signal completion
+</action>
+
+**Phase 4 continues with:**
+- Update page spec with reference
+- Continue to next component
+- Or complete page specification
+
+---
+
+## Summary Output
+
+<output>
+```
+✅ Design System Operation Complete
+
+Action: Created new component
+Component: Navigation Button [btn-002]
+Page: Onboarding page
+Reference: NavigationButton [btn-002]
+
+Files Updated:
+- D-Design-System/components/navigation-button.md (created)
+- C-Scenarios/onboarding-page.md (reference added)
+- D-Design-System/components/README.md (index updated)
+
+Next: Continue with next component in Phase 4
+```
+</output>
+
+---
+
+**This completes the assessment and execution flow. Control returns to Phase 4.**

src/modules/wds/workflows/5-design-system/design-system-router.md

@@ -0,0 +1,348 @@
+# Design System Router
+
+**Purpose:** Route component specifications to appropriate design system operations based on similarity analysis.
+
+**Role:** Dumb router - identifies and routes, doesn't contain business logic.
+
+---
+
+## When This Runs
+
+**Triggered from Phase 4:**
+- After component specification is complete
+- Only if design system is enabled in project
+- Before returning to page specification
+
+**Input:** Complete component specification (mixed content)
+
+**Output:** 
+- Design system entry (component-level info)
+- Page specification reference (page-specific info)
+
+---
+
+## Router Logic
+
+```
+┌─────────────────────────────────────┐
+│ Component Specification Complete    │
+└──────────────┬──────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────┐
+│ Check: Design System Enabled?       │
+└──────────────┬──────────────────────┘
+               │
+        ┌──────┴──────┐
+        │             │
+       NO            YES
+        │             │
+        ▼             ▼
+┌──────────┐   ┌─────────────────────┐
+│ Skip     │   │ Design System Router│
+│ Return   │   └──────────┬──────────┘
+└──────────┘              │
+                          ▼
+               ┌─────────────────────┐
+               │ Check: First        │
+               │ Component?          │
+               └──────┬──────────────┘
+                      │
+               ┌──────┴──────┐
+               │             │
+              YES            NO
+               │             │
+               ▼             ▼
+    ┌──────────────────┐  ┌────────────────┐
+    │ Initialize       │  │ Scan Existing  │
+    │ Design System    │  │ Components     │
+    └────────┬─────────┘  └────────┬───────┘
+             │                     │
+             │                     ▼
+             │          ┌────────────────────┐
+             │          │ Similar Component  │
+             │          │ Found?             │
+             │          └────────┬───────────┘
+             │                   │
+             │            ┌──────┴──────┐
+             │            │             │
+             │           NO            YES
+             │            │             │
+             │            ▼             ▼
+             │   ┌────────────────┐  ┌──────────────┐
+             │   │ Create New     │  │ Opportunity/ │
+             │   │ Component      │  │ Risk         │
+             │   │                │  │ Assessment   │
+             │   └────────┬───────┘  └──────┬───────┘
+             │            │                 │
+             └────────────┴─────────────────┘
+                          │
+                          ▼
+               ┌─────────────────────┐
+               │ Extract Component   │
+               │ Info to Design      │
+               │ System              │
+               └──────────┬──────────┘
+                          │
+                          ▼
+               ┌─────────────────────┐
+               │ Create Reference    │
+               │ ID                  │
+               └──────────┬──────────┘
+                          │
+                          ▼
+               ┌─────────────────────┐
+               │ Return to Page Spec │
+               │ Replace with        │
+               │ Reference           │
+               └──────────┬──────────┘
+                          │
+                          ▼
+               ┌─────────────────────┐
+               │ Complete            │
+               └─────────────────────┘
+```
+
+---
+
+## Step 1: Check Design System Status
+
+<action>
+Check project configuration:
+- Read: `A-Project-Brief/project-config.md`
+- Look for: `design_system_mode: [none|custom|library]`
+- If `none`: Skip this entire workflow
+- If `custom` or `library`: Continue
+</action>
+
+<output>
+**If none:** Return to Phase 4, keep complete spec on page
+
+**If enabled:** Continue to Step 2
+</output>
+
+---
+
+## Step 2: Check First Component
+
+<action>
+Check if design system folder exists:
+- Look for: `D-Design-System/` folder
+- If doesn't exist: This is the first component
+- If exists: Check for existing components
+</action>
+
+<output>
+**If first component:**
+```
+🎉 This is your first design system component!
+
+I'll initialize the design system structure and add this component.
+```
+
+**Route to:** `operations/initialize-design-system.md`
+</output>
+
+<output>
+**If not first:**
+```
+📊 Checking existing design system for similar components...
+```
+
+**Continue to Step 3**
+</output>
+
+---
+
+## Step 3: Scan Existing Components
+
+<action>
+Scan design system folder:
+- Read all files in `D-Design-System/components/`
+- Extract component types and IDs
+- Build list of existing components
+</action>
+
+<output>
+**Existing components found:**
+```
+Found 3 existing components:
+- Button [btn-001]
+- Input Field [inp-001]
+- Card [crd-001]
+```
+
+**Continue to Step 4**
+</output>
+
+<output>
+**No similar components:**
+```
+No similar components found in design system.
+```
+
+**Route to:** `operations/create-new-component.md`
+</output>
+
+---
+
+## Step 4: Identify Similar Components
+
+<action>
+Compare current component to existing:
+- Match by component type (Button, Input, Card, etc.)
+- If type matches: Potential similarity
+- If no type match: Create new component
+</action>
+
+<output>
+**Type match found:**
+```
+🔍 Found existing Button component [btn-001]
+
+Checking similarity...
+```
+
+**Route to:** `assessment/01-scan-existing.md`
+</output>
+
+<output>
+**No type match:**
+```
+This is a new component type: [ComponentType]
+```
+
+**Route to:** `operations/create-new-component.md`
+</output>
+
+---
+
+## Routing Decisions
+
+### Route A: Initialize Design System
+**When:** First component in project
+**Go to:** `operations/initialize-design-system.md`
+**Result:** Create folder structure + first component
+
+### Route B: Create New Component
+**When:** No similar components found
+**Go to:** `operations/create-new-component.md`
+**Result:** Add new component to design system
+
+### Route C: Opportunity/Risk Assessment
+**When:** Similar component found
+**Go to:** `assessment/01-scan-existing.md`
+**Result:** Designer decides: same/variant/new
+
+---
+
+## After Routing
+
+**All routes eventually:**
+1. Extract component-level info to design system
+2. Generate component ID (e.g., `btn-001`)
+3. Create reference in page spec
+4. Return control to Phase 4
+
+**Example Return:**
+
+**Input (Complete Spec):**
+```yaml
+Login Button:
+  why: Submit login credentials
+  label: "Log in"
+  error_text: "Invalid credentials"
+  states: [default, hover, disabled]
+  variants: [primary, secondary]
+  styling: {...}
+```
+
+**Output (Page Spec with Reference):**
+```yaml
+Login Button:
+  component: Button.primary [btn-001]
+  why: Submit login credentials
+  label: "Log in"
+  error_text: "Invalid credentials"
+```
+
+**Output (Design System Entry):**
+```yaml
+# D-Design-System/components/button.md
+Button Component [btn-001]:
+  states: [default, hover, disabled]
+  variants: [primary, secondary]
+  styling: {...}
+```
+
+---
+
+## Router Characteristics
+
+**✅ Does:**
+- Check design system status
+- Identify first component
+- Scan existing components
+- Match component types
+- Route to appropriate operation
+
+**❌ Doesn't:**
+- Make design decisions
+- Contain specification logic
+- Store component knowledge
+- Handle business rules
+- Process component details
+
+**Keep it dumb, keep it clean!**
+
+---
+
+## Error Handling
+
+**If design system folder missing but config says enabled:**
+```
+⚠️ Design system is enabled but folder doesn't exist.
+Treating this as first component and initializing.
+```
+
+**If component type unclear:**
+```
+❓ I'm not sure what type of component this is.
+
+Current specification: [show spec]
+
+Is this a:
+1. Button
+2. Input Field
+3. Card
+4. Other: [specify]
+
+Your choice:
+```
+
+**If similarity check fails:**
+```
+⚠️ I couldn't determine similarity automatically.
+
+Would you like to:
+1. Create as new component
+2. Manually specify which component it's similar to
+3. Skip design system for this component
+
+Your choice:
+```
+
+---
+
+## Next Steps
+
+**After routing:**
+- Follow the routed operation instructions
+- Complete design system entry
+- Return reference to Phase 4
+- Phase 4 updates page spec
+- Continue with next component
+
+---
+
+**This is a router. It identifies and routes. Business logic lives in the operations it routes to.**

src/modules/wds/workflows/5-design-system/figma-integration/figma-designer-guide.md

@@ -0,0 +1,623 @@
+# Figma Designer Guide for WDS
+
+**Purpose:** Step-by-step instructions for designers creating components in Figma for WDS projects.
+
+**Audience:** Visual designers, UX designers, design system maintainers
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Figma account with edit access to design system file
+- Understanding of WDS component structure
+- Familiarity with Figma components and variants
+- Access to WDS project repository
+
+---
+
+## Step 1: Set Up Your Figma File
+
+### Create Design System File
+
+**File structure:**
+```
+[Project Name] Design System
+├── 📄 Cover
+├── 🎨 Foundation
+│   ├── Colors
+│   ├── Typography
+│   ├── Spacing
+│   └── Effects
+├── ⚛️ Components
+│   ├── Buttons
+│   ├── Inputs
+│   ├── Cards
+│   └── [more types]
+└── 📱 Examples
+```
+
+**Tips:**
+- Use clear page names
+- Organize by component type
+- Keep foundation separate
+- Include usage examples
+
+---
+
+### Set Up Design Tokens
+
+**Create Figma variables:**
+
+**Colors:**
+```
+Collection: Colors
+├── primary/50
+├── primary/100
+├── primary/500
+├── primary/600
+├── gray/50
+├── gray/900
+└── [more colors]
+```
+
+**Spacing:**
+```
+Collection: Spacing
+├── spacing/1 = 4px
+├── spacing/2 = 8px
+├── spacing/4 = 16px
+├── spacing/6 = 24px
+└── [more spacing]
+```
+
+**Typography:**
+```
+Styles: Typography
+├── Display/Large
+├── Heading/1
+├── Heading/2
+├── Body/Regular
+└── [more styles]
+```
+
+---
+
+## Step 2: Create Your First Component
+
+### Example: Button Component
+
+**1. Create Base Frame**
+```
+Frame name: Button/Primary [btn-001]
+Size: Hug contents (width), Fixed 44px (height)
+Auto Layout: Horizontal
+Padding: 16px (horizontal), 12px (vertical)
+Gap: 8px
+```
+
+**2. Add Content**
+```
+├── Icon (optional)
+│   └── Size: 20x20px
+└── Text
+    └── Style: Body/Medium
+    └── Content: "Button Text"
+```
+
+**3. Apply Design Tokens**
+```
+Background: primary/600 (variable)
+Text Color: white (variable)
+Border Radius: 8px
+```
+
+**4. Create Component**
+```
+Select frame → Create Component
+Name: Button/Primary [btn-001]
+```
+
+---
+
+### Add Component Description
+
+**In component description field:**
+```
+Button Primary [btn-001]
+
+Primary action button for main user actions.
+
+**When to use:**
+- Submit forms
+- Confirm actions
+- Proceed to next step
+
+**When not to use:**
+- Secondary actions (use Button/Secondary)
+- Navigation (use Link component)
+
+**WDS Component:** Button.primary [btn-001]
+**Variants:** primary, secondary, ghost
+**States:** default, hover, active, disabled, loading
+**Sizes:** small, medium, large
+
+**Accessibility:**
+- role="button"
+- aria-disabled when disabled
+- Keyboard: Enter/Space to activate
+```
+
+---
+
+## Step 3: Add Variants
+
+### Create Variant Properties
+
+**Select component → Add variant property:**
+
+**Property 1: Type**
+```
+Values: Primary, Secondary, Ghost, Outline
+```
+
+**Property 2: Size**
+```
+Values: Small, Medium, Large
+```
+
+**Property 3: State**
+```
+Values: Default, Hover, Active, Disabled, Loading
+```
+
+---
+
+### Design Each Variant
+
+**Type=Primary, Size=Medium, State=Default:**
+```
+Background: primary/600
+Text: white
+Padding: 16px × 12px
+```
+
+**Type=Primary, Size=Medium, State=Hover:**
+```
+Background: primary/700 (darker)
+Text: white
+Scale: 1.02 (slightly larger)
+```
+
+**Type=Primary, Size=Medium, State=Active:**
+```
+Background: primary/800 (darkest)
+Text: white
+Scale: 0.98 (slightly smaller)
+```
+
+**Type=Primary, Size=Medium, State=Disabled:**
+```
+Background: gray/300
+Text: gray/500
+Opacity: 0.6
+Cursor: not-allowed
+```
+
+**Type=Primary, Size=Medium, State=Loading:**
+```
+Background: primary/600
+Text: white
+Add: Spinner icon
+Opacity: 0.8
+```
+
+---
+
+### Adjust for Sizes
+
+**Small:**
+```
+Padding: 12px × 8px
+Text: Body/Small
+Icon: 16x16px
+Height: 36px
+```
+
+**Medium (default):**
+```
+Padding: 16px × 12px
+Text: Body/Medium
+Icon: 20x20px
+Height: 44px
+```
+
+**Large:**
+```
+Padding: 20px × 16px
+Text: Body/Large
+Icon: 24x24px
+Height: 52px
+```
+
+---
+
+## Step 4: Document States
+
+### Visual State Indicators
+
+**Create a documentation frame:**
+```
+Frame: Button States Documentation
+├── Default
+│   └── Normal appearance
+├── Hover
+│   └── Background darker, slight scale
+├── Active
+│   └── Background darkest, scale down
+├── Disabled
+│   └── Grayed out, reduced opacity
+└── Loading
+    └── Spinner, disabled interaction
+```
+
+**Add annotations:**
+- State name
+- Visual changes
+- Interaction behavior
+- Transition duration
+
+---
+
+## Step 5: Get Figma Node ID
+
+### Copy Component Link
+
+**1. Select component in Figma**
+
+**2. Right-click → "Copy link to selection"**
+
+**3. Extract node ID from URL:**
+```
+URL: https://www.figma.com/file/abc123/Design-System?node-id=456:789
+
+File ID: abc123
+Node ID: 456:789
+
+Full reference: figma://file/abc123/node/456:789
+```
+
+**4. Add to WDS mapping file:**
+```yaml
+# D-Design-System/figma-mappings.md
+Button [btn-001] → figma://file/abc123/node/456:789
+```
+
+---
+
+## Step 6: Sync with WDS
+
+### Manual Sync Process
+
+**1. Create component in Figma** (steps above)
+
+**2. Notify WDS system:**
+- Add component ID to Figma description
+- Copy Figma node ID
+- Update `figma-mappings.md`
+
+**3. Generate WDS specification:**
+- Use Figma MCP to read component
+- Generate component specification
+- Review and confirm
+
+**4. Verify sync:**
+- Check WDS component file created
+- Verify all variants captured
+- Confirm states documented
+- Test component reference
+
+---
+
+### Using Figma MCP (Automated)
+
+**If Figma MCP is configured:**
+
+**1. Create/update component in Figma**
+
+**2. Run MCP sync command:**
+```bash
+# In WDS project
+wds figma sync Button/Primary
+```
+
+**3. MCP will:**
+- Read component from Figma
+- Extract variants and states
+- Generate WDS specification
+- Update figma-mappings.md
+
+**4. Review generated spec:**
+- Check accuracy
+- Add missing details
+- Confirm and commit
+
+---
+
+## Step 7: Maintain Components
+
+### Updating Existing Components
+
+**When updating a component:**
+
+**1. Update in Figma:**
+- Modify component
+- Update description if needed
+- Maintain component ID
+
+**2. Sync to WDS:**
+- Run MCP sync (if available)
+- Or manually update WDS spec
+- Update version history
+
+**3. Notify team:**
+- Document changes
+- Update affected pages
+- Test implementations
+
+---
+
+### Version Control
+
+**Track component changes:**
+
+**In Figma:**
+- Use Figma version history
+- Add version notes
+- Tag major changes
+
+**In WDS:**
+```markdown
+## Version History
+
+**Created:** 2024-12-09
+**Last Updated:** 2024-12-15
+
+**Changes:**
+- 2024-12-09: Created component
+- 2024-12-12: Added loading state
+- 2024-12-15: Updated hover animation
+```
+
+---
+
+## Best Practices
+
+### DO ✅
+
+**1. Use Design Tokens**
+- Always use variables for colors
+- Use variables for spacing
+- Apply text styles consistently
+
+**2. Document Thoroughly**
+- Clear component descriptions
+- Usage guidelines
+- Accessibility notes
+
+**3. Maintain Consistency**
+- Follow naming conventions
+- Use consistent spacing
+- Apply standard states
+
+**4. Test Instances**
+- Create example instances
+- Test all variants
+- Verify responsive behavior
+
+**5. Keep Organized**
+- Logical component grouping
+- Clear page structure
+- Clean component hierarchy
+
+---
+
+### DON'T ❌
+
+**1. Hardcode Values**
+- Don't use hex colors directly
+- Don't use pixel values without variables
+- Don't skip design tokens
+
+**2. Detach Instances**
+- Don't break component connections
+- Don't create one-off variations
+- Don't lose main component link
+
+**3. Skip Documentation**
+- Don't leave descriptions empty
+- Don't forget WDS component ID
+- Don't skip usage guidelines
+
+**4. Ignore States**
+- Don't create only default state
+- Don't forget hover/active
+- Don't skip disabled state
+
+**5. Break Naming Conventions**
+- Don't use inconsistent names
+- Don't forget component IDs
+- Don't use unclear abbreviations
+
+---
+
+## Common Workflows
+
+### Creating a New Component Type
+
+**1. Research:**
+- Check if similar component exists
+- Review WDS component boundaries guide
+- Decide: new component or variant?
+
+**2. Design:**
+- Create base component
+- Add all required states
+- Apply design tokens
+
+**3. Document:**
+- Write clear description
+- Add WDS component ID
+- Document usage guidelines
+
+**4. Sync:**
+- Get Figma node ID
+- Update WDS mappings
+- Generate specification
+
+**5. Test:**
+- Create example instances
+- Test all variants
+- Verify responsive behavior
+
+---
+
+### Adding a Variant to Existing Component
+
+**1. Assess:**
+- Is this truly a variant?
+- Or should it be a new component?
+- Check with WDS assessment flow
+
+**2. Add Variant:**
+- Add new variant property value
+- Design variant appearance
+- Document differences
+
+**3. Update Documentation:**
+- Update component description
+- Add variant to list
+- Document when to use
+
+**4. Sync:**
+- Update WDS specification
+- Add variant to component file
+- Update version history
+
+---
+
+### Updating Component Styling
+
+**1. Plan Change:**
+- Document what's changing
+- Check impact on instances
+- Notify team
+
+**2. Update Component:**
+- Modify main component
+- Test all variants
+- Verify instances update
+
+**3. Sync to WDS:**
+- Update WDS specification
+- Document changes
+- Update version history
+
+**4. Verify:**
+- Check all instances
+- Test in examples
+- Confirm with team
+
+---
+
+## Troubleshooting
+
+### Component Not Syncing
+
+**Problem:** MCP can't read component
+
+**Solutions:**
+- Check component name format
+- Verify WDS component ID in description
+- Ensure component is published
+- Check Figma API access
+
+---
+
+### Variants Not Appearing
+
+**Problem:** Some variants missing in WDS
+
+**Solutions:**
+- Check variant property names
+- Verify all combinations exist
+- Ensure consistent naming
+- Re-sync component
+
+---
+
+### Design Tokens Not Applied
+
+**Problem:** Hardcoded values instead of variables
+
+**Solutions:**
+- Replace hex colors with variables
+- Use spacing variables
+- Apply text styles
+- Re-sync component
+
+---
+
+### Instance Overrides Lost
+
+**Problem:** Updates break instance overrides
+
+**Solutions:**
+- Don't change component structure
+- Add new properties instead
+- Maintain backward compatibility
+- Communicate changes to team
+
+---
+
+## Checklist
+
+### Before Creating Component
+
+- [ ] Checked if similar component exists
+- [ ] Reviewed component boundaries guide
+- [ ] Decided on component vs variant
+- [ ] Prepared design tokens
+- [ ] Planned all required states
+
+### During Component Creation
+
+- [ ] Used design tokens (no hardcoded values)
+- [ ] Created all required states
+- [ ] Applied auto layout properly
+- [ ] Added clear description
+- [ ] Included WDS component ID
+- [ ] Documented usage guidelines
+
+### After Component Creation
+
+- [ ] Copied Figma node ID
+- [ ] Updated figma-mappings.md
+- [ ] Generated WDS specification
+- [ ] Created example instances
+- [ ] Tested all variants
+- [ ] Notified team
+
+---
+
+## Resources
+
+- **Figma Component Structure:** `data/design-system/figma-component-structure.md`
+- **Token Architecture:** `data/design-system/token-architecture.md`
+- **Component Boundaries:** `data/design-system/component-boundaries.md`
+- **Figma MCP Integration:** `figma-mcp-integration.md`
+
+---
+
+**Following this guide ensures your Figma components integrate seamlessly with WDS and maintain design system consistency.**

src/modules/wds/workflows/5-design-system/figma-integration/figma-mcp-integration.md

@@ -0,0 +1,614 @@
+# Figma MCP Integration for WDS
+
+**Purpose:** Technical guide for integrating Figma with WDS using Model Context Protocol (MCP).
+
+**Audience:** AI agents, developers, technical designers
+
+---
+
+## Overview
+
+**Figma MCP enables:**
+- Reading component specifications from Figma
+- Extracting design tokens
+- Generating WDS component specifications
+- Maintaining Figma ↔ WDS sync
+
+---
+
+## MCP Server Setup
+
+### Prerequisites
+
+- Figma API access token
+- MCP server configured
+- WDS project initialized
+- Design system mode set to "custom"
+
+---
+
+### Configuration
+
+**Add to MCP configuration:**
+
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-figma"],
+      "env": {
+        "FIGMA_PERSONAL_ACCESS_TOKEN": "your-figma-token"
+      }
+    }
+  }
+}
+```
+
+**Get Figma API token:**
+1. Go to Figma → Settings → Account
+2. Scroll to "Personal access tokens"
+3. Click "Generate new token"
+4. Copy token and add to configuration
+
+---
+
+## MCP Operations
+
+### 1. Read Figma Component
+
+**Purpose:** Extract component data from Figma
+
+**Input:**
+- Figma file ID
+- Node ID
+- Or component name
+
+**Output:**
+- Component structure
+- Variants
+- Properties
+- Design tokens used
+
+**Example:**
+```
+Agent: Read Figma component Button/Primary
+
+MCP Response:
+{
+  "name": "Button/Primary [btn-001]",
+  "type": "COMPONENT_SET",
+  "variants": [
+    {
+      "name": "Type=Primary, Size=Medium, State=Default",
+      "properties": {
+        "Type": "Primary",
+        "Size": "Medium",
+        "State": "Default"
+      },
+      "styles": {
+        "background": "primary/600",
+        "padding": "16px 12px",
+        "borderRadius": "8px"
+      }
+    },
+    // ... more variants
+  ],
+  "description": "Button Primary [btn-001]...",
+  "nodeId": "456:789"
+}
+```
+
+---
+
+### 2. Extract Design Tokens
+
+**Purpose:** Get design token values from Figma
+
+**Input:**
+- Figma file ID
+- Token type (colors, typography, spacing)
+
+**Output:**
+- Token definitions
+- Token values
+- Token mappings
+
+**Example:**
+```
+Agent: Extract color tokens from Figma
+
+MCP Response:
+{
+  "colors": {
+    "primary/50": "#eff6ff",
+    "primary/500": "#3b82f6",
+    "primary/600": "#2563eb",
+    "gray/900": "#111827"
+  }
+}
+```
+
+---
+
+### 3. Get Component Node ID
+
+**Purpose:** Find Figma node ID for component
+
+**Input:**
+- Component name or WDS component ID
+
+**Output:**
+- Figma node ID
+- File ID
+- Full Figma URL
+
+**Example:**
+```
+Agent: Get node ID for Button [btn-001]
+
+MCP Response:
+{
+  "componentId": "btn-001",
+  "fileId": "abc123",
+  "nodeId": "456:789",
+  "url": "figma://file/abc123/node/456:789"
+}
+```
+
+---
+
+### 4. List Components
+
+**Purpose:** Get all components in Figma file
+
+**Input:**
+- Figma file ID
+- Optional: filter by type
+
+**Output:**
+- List of components
+- Component names
+- Node IDs
+
+**Example:**
+```
+Agent: List all button components
+
+MCP Response:
+{
+  "components": [
+    {
+      "name": "Button/Primary [btn-001]",
+      "nodeId": "456:789",
+      "type": "COMPONENT_SET"
+    },
+    {
+      "name": "Button/Secondary [btn-001]",
+      "nodeId": "456:790",
+      "type": "COMPONENT_SET"
+    }
+  ]
+}
+```
+
+---
+
+## Sync Workflows
+
+### Figma → WDS Sync
+
+**When:** Component created or updated in Figma
+
+**Process:**
+
+**Step 1: Detect Change**
+```
+Designer updates Button/Primary in Figma
+Designer notifies WDS system
+Or: Automated webhook triggers sync
+```
+
+**Step 2: Read Component**
+```
+Agent: Read Figma component Button/Primary [btn-001]
+
+MCP reads:
+- Component structure
+- All variants
+- All states
+- Properties
+- Design tokens
+- Description
+```
+
+**Step 3: Parse Component Data**
+```
+Agent extracts:
+- Component type: Button
+- WDS ID: btn-001
+- Variants: primary, secondary, ghost
+- States: default, hover, active, disabled, loading
+- Sizes: small, medium, large
+- Design tokens: primary/600, spacing/4, radius/md
+```
+
+**Step 4: Generate WDS Specification**
+```
+Agent creates/updates:
+D-Design-System/components/button.md
+
+Using template: component.template.md
+Filling in:
+- Component name and ID
+- Variants from Figma
+- States from Figma
+- Styling from design tokens
+- Description from Figma
+```
+
+**Step 5: Update Mappings**
+```
+Agent updates:
+D-Design-System/figma-mappings.md
+
+Adds/updates:
+Button [btn-001] → figma://file/abc123/node/456:789
+```
+
+**Step 6: Verify and Confirm**
+```
+Agent presents generated spec to designer
+Designer reviews and confirms
+Spec is committed to repository
+```
+
+---
+
+### WDS → Figma Notification
+
+**When:** WDS specification updated
+
+**Process:**
+
+**Step 1: Detect Change**
+```
+WDS specification updated
+Git commit triggers notification
+```
+
+**Step 2: Identify Figma Component**
+```
+Agent reads figma-mappings.md
+Finds: Button [btn-001] → figma://file/abc123/node/456:789
+```
+
+**Step 3: Notify Designer**
+```
+Agent creates notification:
+"Button [btn-001] specification updated in WDS.
+Please review and update Figma component if needed.
+
+Changes:
+- Added new loading state
+- Updated hover animation
+- Modified padding values
+
+Figma component: [Link to Figma]"
+```
+
+**Step 4: Designer Updates Figma**
+```
+Designer reviews changes
+Updates Figma component
+Confirms sync complete
+```
+
+**Note:** Full WDS → Figma automation requires Figma API write access (currently read-only for MCP).
+
+---
+
+## Component Specification Generation
+
+### Template-Based Generation
+
+**Agent uses component template:**
+
+**Input:**
+```
+Figma component data:
+{
+  "name": "Button/Primary [btn-001]",
+  "variants": [...],
+  "states": [...],
+  "tokens": {...},
+  "description": "..."
+}
+```
+
+**Template:** `templates/component.template.md`
+
+**Output:** `D-Design-System/components/button.md`
+
+**Process:**
+1. Load component template
+2. Fill in component name and ID
+3. Extract and format variants
+4. Extract and format states
+5. Map design tokens to WDS tokens
+6. Add styling specifications
+7. Include description and usage
+8. Generate accessibility notes
+9. Add version history
+10. Save to design system folder
+
+---
+
+### Token Mapping
+
+**Figma variables → WDS tokens:**
+
+**Agent maps:**
+```
+Figma: primary/600 → WDS: color-primary-600
+Figma: spacing/4 → WDS: spacing-4
+Figma: Text/Body → WDS: text-body
+Figma: shadow/sm → WDS: shadow-sm
+```
+
+**Mapping rules:**
+- Figma collection/variable → WDS category-name-value
+- Maintain semantic meaning
+- Consistent naming across systems
+- Document custom mappings
+
+---
+
+## Error Handling
+
+### Component Not Found
+
+**Error:** Figma component doesn't exist
+
+**Agent response:**
+```
+⚠️ Component not found in Figma
+
+Component: Button/Primary [btn-001]
+File ID: abc123
+Node ID: 456:789
+
+Possible causes:
+- Component deleted in Figma
+- Node ID changed
+- File ID incorrect
+- Access permissions
+
+Actions:
+1. Verify component exists in Figma
+2. Update node ID in figma-mappings.md
+3. Re-sync component
+```
+
+---
+
+### Missing WDS Component ID
+
+**Error:** Figma component has no WDS ID in description
+
+**Agent response:**
+```
+⚠️ WDS Component ID missing
+
+Component: Button/Primary
+Figma node: 456:789
+
+Please add WDS component ID to Figma description:
+Format: [component-id]
+Example: Button/Primary [btn-001]
+
+After adding ID, re-sync component.
+```
+
+---
+
+### Token Mapping Failure
+
+**Error:** Can't map Figma variable to WDS token
+
+**Agent response:**
+```
+⚠️ Token mapping failed
+
+Figma variable: custom-blue-500
+No matching WDS token found
+
+Options:
+1. Create new WDS token: color-custom-blue-500
+2. Map to existing token: color-primary-500
+3. Add custom mapping rule
+
+Your choice:
+```
+
+---
+
+### Sync Conflict
+
+**Error:** Figma and WDS have different versions
+
+**Agent response:**
+```
+⚠️ Sync conflict detected
+
+Component: Button [btn-001]
+
+Figma version:
+- Last updated: 2024-12-15
+- Changes: Added loading state
+
+WDS version:
+- Last updated: 2024-12-14
+- Changes: Updated hover animation
+
+Options:
+1. Figma wins (overwrite WDS)
+2. WDS wins (notify designer)
+3. Manual merge (review both)
+
+Your choice:
+```
+
+---
+
+## Best Practices
+
+### For AI Agents
+
+**DO ✅**
+- Always check for WDS component ID in Figma
+- Verify token mappings before generating specs
+- Present generated specs for designer review
+- Update figma-mappings.md after sync
+- Document sync operations in version history
+
+**DON'T ❌**
+- Don't overwrite WDS specs without confirmation
+- Don't create components without designer approval
+- Don't skip token mapping validation
+- Don't ignore sync conflicts
+- Don't forget to update mappings
+
+---
+
+### For Designers
+
+**DO ✅**
+- Add WDS component ID to all Figma components
+- Use design tokens (variables) consistently
+- Document component changes
+- Notify system when updating components
+- Review generated specs before committing
+
+**DON'T ❌**
+- Don't use hardcoded values
+- Don't skip component descriptions
+- Don't forget to sync after changes
+- Don't detach component instances
+- Don't change component IDs
+
+---
+
+## Integration Points
+
+### Phase 4: UX Design
+
+**When component is specified in Phase 4:**
+1. Designer creates sketch
+2. Agent specifies component
+3. Design system router checks for similar components
+4. If new component needed:
+   - Designer creates in Figma
+   - MCP reads from Figma
+   - Spec generated automatically
+
+---
+
+### Phase 5: Design System
+
+**When component is added to design system:**
+1. Component specification complete
+2. Agent checks: Figma component exists?
+3. If yes:
+   - MCP reads Figma component
+   - Extracts styling details
+   - Updates WDS spec with Figma data
+4. If no:
+   - Designer creates in Figma
+   - MCP syncs to WDS
+
+---
+
+## Command Reference
+
+### Read Component
+```
+Agent: Read Figma component [component-name]
+MCP: Returns component data
+```
+
+### Extract Tokens
+```
+Agent: Extract [token-type] tokens from Figma
+MCP: Returns token definitions
+```
+
+### Get Node ID
+```
+Agent: Get Figma node ID for [component-id]
+MCP: Returns node ID and URL
+```
+
+### List Components
+```
+Agent: List Figma components [optional: filter]
+MCP: Returns component list
+```
+
+### Sync Component
+```
+Agent: Sync Figma component [component-name] to WDS
+MCP: Reads component, generates spec, updates mappings
+```
+
+---
+
+## Troubleshooting
+
+### MCP Server Not Responding
+
+**Check:**
+- MCP server is running
+- Figma API token is valid
+- Network connection is active
+- File ID and node ID are correct
+
+---
+
+### Invalid API Token
+
+**Error:** 403 Forbidden
+
+**Solution:**
+1. Generate new Figma API token
+2. Update MCP configuration
+3. Restart MCP server
+4. Retry operation
+
+---
+
+### Rate Limiting
+
+**Error:** 429 Too Many Requests
+
+**Solution:**
+- Wait before retrying
+- Batch operations when possible
+- Cache component data
+- Reduce sync frequency
+
+---
+
+## Future Enhancements
+
+**Planned features:**
+- Automated sync on Figma changes (webhooks)
+- Bidirectional sync (WDS → Figma write)
+- Batch component import
+- Design token extraction automation
+- Component usage tracking from Figma
+- Visual diff for sync conflicts
+
+---
+
+**This MCP integration enables seamless Figma ↔ WDS synchronization while maintaining designer control and design system consistency.**

src/modules/wds/workflows/5-design-system/operations/add-variant.md

@@ -0,0 +1,445 @@
+# Operation: Add Variant
+
+**Purpose:** Add a new variant to an existing component.
+
+**When:** Designer chose to extend existing component with new variant
+
+**Input:** Existing component ID + new variant specification
+
+**Output:** Updated component file with new variant
+
+---
+
+## Step 1: Load Existing Component
+
+<action>
+Read existing component file:
+- Component ID
+- Current variants
+- Shared attributes
+- Variant-specific attributes
+</action>
+
+**Example:**
+```yaml
+Component: Button [btn-001]
+Current Variants:
+  - primary (submit actions)
+  - secondary (cancel actions)
+```
+
+<output>
+```
+📖 Loaded Button [btn-001]
+
+Current variants: 2 (primary, secondary)
+Adding new variant: navigation
+```
+</output>
+
+---
+
+## Step 2: Extract Variant-Specific Information
+
+<action>
+From new component specification, extract:
+- What's different from existing variants?
+- What's shared with existing variants?
+- Variant-specific styling
+- Variant-specific behaviors
+- Variant-specific states (if any)
+</action>
+
+**Example:**
+```yaml
+Shared with existing:
+  - Size: medium
+  - Shape: rounded
+  - Base states: default, hover, active, disabled
+
+Different from existing:
+  - Has icon (arrow-right)
+  - Has loading state
+  - Icon animation on hover
+  - Purpose: navigation vs submission
+```
+
+---
+
+## Step 3: Determine Variant Name
+
+<action>
+Generate descriptive variant name:
+- Based on purpose or visual distinction
+- Consistent with existing variant naming
+- Clear and semantic
+</action>
+
+**Examples:**
+```
+Purpose-based:
+- navigation (for navigation actions)
+- destructive (for delete/remove actions)
+- success (for positive confirmations)
+
+Visual-based:
+- outlined (border, no fill)
+- ghost (transparent background)
+- large (bigger size)
+
+Context-based:
+- header (used in headers)
+- footer (used in footers)
+- inline (used inline with text)
+```
+
+<ask>
+```
+Suggested variant name: "navigation"
+
+This variant is for navigation actions (continue, next, proceed).
+
+Is this name clear and appropriate? (y/n)
+Or suggest alternative name:
+```
+</ask>
+
+---
+
+## Step 4: Update Component File
+
+<action>
+Add variant to component definition:
+</action>
+
+### Update Variants Section
+
+**Before:**
+```markdown
+## Variants
+
+- **primary** - Main call-to-action (submit, save, continue)
+- **secondary** - Secondary actions (cancel, back)
+```
+
+**After:**
+```markdown
+## Variants
+
+- **primary** - Main call-to-action (submit, save, continue)
+- **secondary** - Secondary actions (cancel, back)
+- **navigation** - Navigation actions (next, proceed, continue)  ← Added
+```
+
+### Add Variant-Specific Styling
+
+**Add section:**
+```markdown
+### Variant-Specific Styling
+
+**Primary:**
+- Background: blue-600
+- Icon: none
+- Loading: spinner only
+
+**Secondary:**
+- Background: gray-200
+- Text: gray-900
+- Icon: none
+
+**Navigation:**  ← Added
+- Background: blue-600
+- Icon: arrow-right
+- Loading: spinner + icon
+- Hover: icon shifts right
+```
+
+### Update States (if variant has unique states)
+
+**If navigation variant has loading state but others don't:**
+```markdown
+## States
+
+**Shared States (all variants):**
+- default
+- hover
+- active
+- disabled
+
+**Variant-Specific States:**
+
+**Navigation:**
+- loading (shows spinner, disables interaction)
+```
+
+---
+
+## Step 5: Update Usage Tracking
+
+<action>
+Track new variant usage:
+</action>
+
+**Add to component file:**
+```markdown
+## Variant Usage
+
+**Primary:** 5 pages
+**Secondary:** 3 pages
+**Navigation:** 1 page  ← Added
+
+**Navigation variant used in:**
+- Onboarding page (continue button)
+```
+
+---
+
+## Step 6: Update Component Complexity Note
+
+<action>
+Add note about variant count:
+</action>
+
+**If this is 3rd+ variant:**
+```markdown
+## Notes
+
+This component now has 3 variants. Consider:
+- Are all variants necessary?
+- Should any variants be separate components?
+- Is the component becoming too complex?
+
+Review component organization when reaching 5+ variants.
+```
+
+---
+
+## Step 7: Validate Variant Addition
+
+<action>
+Check for potential issues:
+</action>
+
+**Variant Explosion Check:**
+```
+⚠️ Variant Count: 3
+
+This is manageable. Monitor for variant explosion as more are added.
+
+Recommended maximum: 5 variants per component
+```
+
+**Consistency Check:**
+```
+✓ New variant consistent with existing variants
+✓ Naming convention followed
+✓ Shared attributes maintained
+```
+
+**Complexity Check:**
+```
+⚠️ Navigation variant adds loading state not present in other variants.
+
+This increases component complexity. Consider:
+- Should loading state be shared across all variants?
+- Or is it truly navigation-specific?
+
+Current approach: Variant-specific (acceptable)
+```
+
+---
+
+## Step 8: Update Component Version
+
+<action>
+Track component changes:
+</action>
+
+**Update version history:**
+```markdown
+## Version History
+
+**Created:** 2024-12-01
+**Last Updated:** 2024-12-09
+
+**Changes:**
+- 2024-12-01: Created component with primary and secondary variants
+- 2024-12-09: Added navigation variant  ← Added
+```
+
+---
+
+## Step 9: Create Component Reference
+
+<action>
+Generate reference for page spec:
+</action>
+
+**Output:**
+```yaml
+component_reference:
+  id: btn-001
+  name: Button
+  variant: navigation  ← New variant
+  file: D-Design-System/components/button.md
+```
+
+---
+
+## Step 10: Complete
+
+<output>
+```
+✅ Variant Added: Button.navigation [btn-001]
+
+Component: Button [btn-001]
+New Variant: navigation
+Total Variants: 3 (primary, secondary, navigation)
+
+Component file updated:
+- Variant added to list
+- Variant-specific styling documented
+- Usage tracking added
+- Version history updated
+
+Reference ready for page spec.
+
+Next: Return to Phase 4 to complete page specification
+```
+</output>
+
+---
+
+## Designer Guidance
+
+<output>
+```
+💡 Variant Management Tips:
+
+**Current Status:**
+- Component: Button [btn-001]
+- Variants: 3
+- Status: Healthy
+
+**Watch for:**
+- 5+ variants → Consider splitting component
+- Variants with very different purposes → Might need separate components
+- Variants rarely used together → Might indicate separate components
+
+**Best Practices:**
+- Keep variants related (same base purpose)
+- Use clear, semantic variant names
+- Document when to use each variant
+- Review variant list periodically
+
+You can always refactor later if needed!
+```
+</output>
+
+---
+
+## Validation
+
+<action>
+Validate variant addition:
+- ✓ Variant added to component file
+- ✓ Variant-specific attributes documented
+- ✓ Usage tracking updated
+- ✓ Version history updated
+- ✓ Reference generated
+- ✓ Complexity checked
+</action>
+
+---
+
+## Error Handling
+
+**If variant name conflicts:**
+```
+⚠️ Variant "navigation" already exists in Button [btn-001].
+
+This might mean:
+1. You're trying to add a duplicate
+2. The existing variant should be updated
+3. A different variant name is needed
+
+Current navigation variant:
+[Show existing variant details]
+
+Options:
+1. Update existing variant
+2. Choose different name
+3. Cancel
+
+Your choice:
+```
+
+**If component file not found:**
+```
+❌ Error: Component file not found.
+
+Component ID: btn-001
+Expected file: D-Design-System/components/button.md
+
+This shouldn't happen. Possible causes:
+- File was deleted
+- Component ID is incorrect
+- Design system structure corrupted
+
+Would you like to:
+1. Create component as new
+2. Specify correct component ID
+3. Cancel
+
+Your choice:
+```
+
+**If variant too different:**
+```
+⚠️ Warning: High Divergence Detected
+
+The new variant is very different from existing variants:
+- Different core purpose
+- Different visual structure
+- Different behavioral patterns
+
+Similarity to existing variants: 35%
+
+This might be better as a separate component.
+
+Options:
+1. Add as variant anyway
+2. Create as new component instead
+3. Review differences in detail
+
+Your choice:
+```
+
+---
+
+## Post-Addition Review
+
+<action>
+After adding variant, check component health:
+</action>
+
+**Component Health Check:**
+```
+📊 Component Health: Button [btn-001]
+
+Variants: 3
+Complexity: Medium
+Consistency: High
+Usage: 9 pages
+
+Health Status: ✅ Healthy
+
+Recommendations:
+- Document variant selection guidelines
+- Consider adding variant usage examples
+- Monitor for variant explosion
+```
+
+---
+
+**This operation adds a variant. Return to Phase 4 with component reference.**

src/modules/wds/workflows/5-design-system/operations/create-new-component.md

@@ -0,0 +1,671 @@
+# Operation: Create New Component
+
+**Purpose:** Add a new component to the design system.
+
+**When:** No similar component exists, or designer chose to create new
+
+**Input:** Component specification
+
+**Output:** New component file in design system
+
+---
+
+## Step 1: Generate Component ID
+
+<action>
+Generate unique component ID:
+1. Determine component type prefix
+2. Check existing IDs for that type
+3. Increment counter
+4. Format: [prefix]-[number]
+</action>
+
+**Type Prefixes:**
+```
+Button → btn
+Input Field → inp
+Card → crd
+Modal → mdl
+Dropdown → drp
+Checkbox → chk
+Radio → rad
+Toggle → tgl
+Tab → tab
+Accordion → acc
+Alert → alt
+Badge → bdg
+Avatar → avt
+Icon → icn
+Image → img
+Link → lnk
+Text → txt
+Heading → hdg
+List → lst
+Table → tbl
+Form → frm
+Container → cnt
+Grid → grd
+Flex → flx
+Divider → div
+Spacer → spc
+```
+
+**Example:**
+```
+Component Type: Button
+Existing Button IDs: btn-001, btn-002
+New ID: btn-003
+```
+
+<output>
+```
+🆔 Generated Component ID: btn-003
+```
+</output>
+
+---
+
+## Step 2: Determine Component Category
+
+<action>
+Categorize component for organization:
+- Interactive (buttons, links, controls)
+- Form (inputs, selects, checkboxes)
+- Layout (containers, grids, dividers)
+- Content (text, images, media)
+- Feedback (alerts, toasts, modals)
+- Navigation (tabs, breadcrumbs, menus)
+</action>
+
+**Example:**
+```
+Component: Button
+Category: Interactive
+```
+
+---
+
+## Step 3: Extract Component-Level Information
+
+<action>
+From complete specification, extract component-level info:
+
+**Visual Attributes:**
+- Size (small, medium, large)
+- Shape (rounded, square, pill)
+- Color scheme
+- Typography
+- Spacing/padding
+- Border style
+
+**Behavioral Attributes:**
+- States (default, hover, active, disabled, loading, error)
+- Interactions (click, hover, focus, blur)
+- Animations/transitions
+- Keyboard support
+- Accessibility attributes
+
+**Functional Attributes:**
+- Purpose/role
+- Input/output type
+- Validation rules
+- Required/optional
+
+**Design System Attributes:**
+- Variants (if any)
+- Design tokens used
+- Figma reference (if Mode B)
+- Library component (if Mode C)
+</action>
+
+---
+
+## Step 4: Create Component File
+
+<action>
+Use component template to create file:
+</action>
+
+**File:** `D-Design-System/components/[component-name].md`
+
+**Template Structure:**
+
+```markdown
+# [Component Name] [component-id]
+
+**Type:** [Interactive/Form/Layout/Content/Feedback/Navigation]
+**Category:** [Specific category]
+**Purpose:** [Brief description]
+
+---
+
+## Overview
+
+[Component description and when to use it]
+
+---
+
+## Variants
+
+[If component has variants, list them]
+
+**Example:**
+- primary - Main call-to-action
+- secondary - Secondary actions
+- ghost - Subtle actions
+
+[If no variants:]
+This component has no variants.
+
+---
+
+## States
+
+**Required States:**
+- default
+- hover
+- active
+- disabled
+
+**Optional States:**
+- loading
+- error
+- success
+- focus
+
+**State Descriptions:**
+[Describe what each state looks like/does]
+
+---
+
+## Styling
+
+### Visual Properties
+
+**Size:** [small/medium/large or specific values]
+**Shape:** [rounded/square/pill or specific border-radius]
+**Colors:** [Color tokens or values]
+**Typography:** [Font tokens or values]
+**Spacing:** [Padding/margin values]
+
+### Design Tokens
+
+[If using design tokens:]
+```yaml
+colors:
+  background: primary-500
+  text: white
+  border: primary-600
+  
+typography:
+  font-size: text-base
+  font-weight: semibold
+  
+spacing:
+  padding-x: 4
+  padding-y: 2
+  
+effects:
+  border-radius: md
+  shadow: sm
+```
+
+### Figma Reference
+
+[If Mode B - Custom Design System:]
+**Figma Component:** [Link to Figma component]
+**Node ID:** [Figma node ID]
+**Last Synced:** [Date]
+
+### Library Component
+
+[If Mode C - Component Library:]
+**Library:** [shadcn/Radix/etc.]
+**Component:** [Library component name]
+**Customizations:** [Any overrides from library default]
+
+---
+
+## Behavior
+
+### Interactions
+
+**Click:**
+[What happens on click]
+
+**Hover:**
+[What happens on hover]
+
+**Focus:**
+[What happens on focus]
+
+**Keyboard:**
+[Keyboard shortcuts/navigation]
+
+### Animations
+
+[If component has animations:]
+- [Animation description]
+- Duration: [ms]
+- Easing: [easing function]
+
+---
+
+## Accessibility
+
+**ARIA Attributes:**
+- role: [role]
+- aria-label: [label]
+- aria-disabled: [when disabled]
+- [Other ARIA attributes]
+
+**Keyboard Support:**
+- Enter/Space: [action]
+- Tab: [navigation]
+- [Other keyboard support]
+
+**Screen Reader:**
+[How screen readers should announce this component]
+
+---
+
+## Usage
+
+### When to Use
+
+[Guidelines for when this component is appropriate]
+
+### When Not to Use
+
+[Guidelines for when to use a different component]
+
+### Best Practices
+
+- [Best practice 1]
+- [Best practice 2]
+- [Best practice 3]
+
+---
+
+## Used In
+
+**Pages:** [List of pages using this component]
+
+**Usage Count:** [Number]
+
+**Examples:**
+- [Page name] - [Specific usage]
+- [Page name] - [Specific usage]
+
+---
+
+## Related Components
+
+[If this component is related to others:]
+- [Related component 1] - [Relationship]
+- [Related component 2] - [Relationship]
+
+---
+
+## Version History
+
+**Created:** [Date]
+**Last Updated:** [Date]
+
+**Changes:**
+- [Date]: Created component
+- [Date]: [Change description]
+
+---
+
+## Notes
+
+[Any additional notes, considerations, or future plans]
+```
+
+---
+
+## Step 5: Populate Template
+
+<action>
+Fill template with extracted information:
+</action>
+
+**Example Output:**
+
+```markdown
+# Button [btn-003]
+
+**Type:** Interactive
+**Category:** Action
+**Purpose:** Trigger primary and secondary actions
+
+---
+
+## Overview
+
+Buttons are used to trigger actions. They should have clear, action-oriented labels that describe what will happen when clicked.
+
+Use buttons for important actions that change state or navigate to new content.
+
+---
+
+## Variants
+
+- **primary** - Main call-to-action (submit, save, continue)
+- **secondary** - Secondary actions (cancel, back)
+- **ghost** - Subtle actions (close, dismiss)
+
+---
+
+## States
+
+**Required States:**
+- default - Normal state
+- hover - Mouse over button
+- active - Button being clicked
+- disabled - Button cannot be clicked
+
+**Optional States:**
+- loading - Action in progress (shows spinner)
+
+**State Descriptions:**
+
+**Default:** Blue background, white text, medium size
+**Hover:** Darker blue background, slight scale increase
+**Active:** Even darker blue, slight scale decrease
+**Disabled:** Gray background, gray text, reduced opacity
+**Loading:** Disabled state + spinner icon
+
+---
+
+## Styling
+
+### Visual Properties
+
+**Size:** medium (h-10, px-4)
+**Shape:** rounded (border-radius: 0.375rem)
+**Colors:** 
+- Background: blue-600
+- Text: white
+- Border: none
+
+**Typography:**
+- Font size: 14px
+- Font weight: 600
+- Line height: 1.5
+
+**Spacing:**
+- Padding X: 16px
+- Padding Y: 8px
+- Gap (if icon): 8px
+
+### Design Tokens
+
+```yaml
+colors:
+  primary:
+    background: blue-600
+    hover: blue-700
+    active: blue-800
+  text: white
+  
+typography:
+  size: text-sm
+  weight: semibold
+  
+spacing:
+  padding-x: 4
+  padding-y: 2
+  gap: 2
+  
+effects:
+  border-radius: md
+  shadow: sm
+  transition: all 150ms ease
+```
+
+### Library Component
+
+**Library:** shadcn/ui
+**Component:** Button
+**Customizations:** None (using library defaults)
+
+---
+
+## Behavior
+
+### Interactions
+
+**Click:**
+Triggers associated action (form submit, navigation, etc.)
+
+**Hover:**
+- Background darkens
+- Slight scale increase (1.02)
+- Cursor changes to pointer
+
+**Focus:**
+- Blue outline ring
+- Maintains hover state
+
+**Keyboard:**
+- Enter/Space triggers click
+- Tab navigates to/from button
+
+### Animations
+
+**Hover Scale:**
+- Duration: 150ms
+- Easing: ease-in-out
+- Scale: 1.02
+
+**Click Feedback:**
+- Duration: 100ms
+- Scale: 0.98
+
+---
+
+## Accessibility
+
+**ARIA Attributes:**
+- role: button
+- aria-label: [Descriptive label if icon-only]
+- aria-disabled: true [when disabled]
+- aria-busy: true [when loading]
+
+**Keyboard Support:**
+- Enter/Space: Triggers button action
+- Tab: Moves focus to/from button
+
+**Screen Reader:**
+Announces button label and state (disabled, busy, etc.)
+
+---
+
+## Usage
+
+### When to Use
+
+- Primary actions (submit forms, save data, proceed to next step)
+- Secondary actions (cancel, go back, dismiss)
+- Triggering modals or dialogs
+- Navigation to new pages/sections
+
+### When Not to Use
+
+- For navigation that looks like text (use Link component)
+- For toggling states (use Toggle or Checkbox)
+- For selecting from options (use Radio or Checkbox)
+
+### Best Practices
+
+- Use action-oriented labels ("Save Changes" not "Save")
+- Limit primary buttons to one per section
+- Place primary button on the right in button groups
+- Ensure sufficient touch target size (min 44x44px)
+- Provide loading state for async actions
+
+---
+
+## Used In
+
+**Pages:** 1
+
+**Usage Count:** 1
+
+**Examples:**
+- Login page - Submit credentials button
+
+---
+
+## Related Components
+
+- Link [lnk-001] - For text-style navigation
+- Icon Button [btn-002] - For icon-only actions
+
+---
+
+## Version History
+
+**Created:** 2024-12-09
+**Last Updated:** 2024-12-09
+
+**Changes:**
+- 2024-12-09: Created component
+
+---
+
+## Notes
+
+This is the primary button component. Consider adding more variants as needs emerge (danger, success, etc.).
+```
+
+---
+
+## Step 6: Update Component Index
+
+<action>
+Add component to index:
+</action>
+
+**Update:** `D-Design-System/components/README.md`
+
+```markdown
+## Component List
+
+### Interactive Components
+- Button [btn-001] - Primary action buttons
+- Icon Button [btn-002] - Icon-only actions
+- Button [btn-003] - Standard action button  ← Added
+
+**Total Interactive:** 3
+```
+
+---
+
+## Step 7: Update Design System Stats
+
+<action>
+Update design system statistics:
+</action>
+
+**Update:** `D-Design-System/README.md` (if exists)
+
+```yaml
+**Total Components:** 4 (was 3)
+**Last Updated:** [Date]
+**Latest Addition:** Button [btn-003]
+```
+
+---
+
+## Step 8: Create Component Reference
+
+<action>
+Generate reference for page spec:
+</action>
+
+**Output:**
+```yaml
+component_reference:
+  id: btn-003
+  name: Button
+  variant: primary
+  file: D-Design-System/components/button.md
+```
+
+---
+
+## Step 9: Complete
+
+<output>
+```
+✅ Component Created: Button [btn-003]
+
+File: D-Design-System/components/button.md
+Category: Interactive
+Variants: primary, secondary, ghost
+States: default, hover, active, disabled, loading
+
+Component index updated.
+Design system stats updated.
+Reference ready for page spec.
+
+Next: Return to Phase 4 to complete page specification
+```
+</output>
+
+---
+
+## Validation
+
+<action>
+Validate component creation:
+- ✓ Component file created
+- ✓ Component ID unique
+- ✓ Template fully populated
+- ✓ Index updated
+- ✓ Stats updated
+- ✓ Reference generated
+</action>
+
+---
+
+## Error Handling
+
+**If ID conflict:**
+```
+⚠️ Component ID btn-003 already exists.
+
+Generating alternative ID: btn-004
+```
+
+**If file creation fails:**
+```
+❌ Error creating component file.
+
+Error: [error message]
+
+Would you like to:
+1. Retry
+2. Create with different ID
+3. Skip design system for this component
+
+Your choice:
+```
+
+**If template population incomplete:**
+```
+⚠️ Some component information is missing.
+
+Missing:
+- [List of missing fields]
+
+I'll create the component with placeholders.
+You can fill in details later.
+```
+
+---
+
+**This operation creates a new component. Return to Phase 4 with component reference.**

src/modules/wds/workflows/5-design-system/operations/generate-catalog.md

@@ -0,0 +1,676 @@
+# Generate Interactive HTML Catalog
+
+**Purpose:** Create/update the interactive HTML catalog that showcases all design system components with live examples.
+
+**When to run:** 
+- After initializing design system
+- After creating new component
+- After adding variant
+- After updating component
+- On demand for manual refresh
+
+---
+
+## Overview
+
+The interactive catalog is a **living documentation** of the design system:
+- Shows all components with live examples
+- Displays all variants and states
+- Includes design tokens
+- Provides code examples
+- Tracks version history
+- **Version controlled** with the project
+
+---
+
+## Input
+
+**Design System Files:**
+- `D-Design-System/components/*.md` - All component specifications
+- `D-Design-System/design-tokens.md` - Design token definitions
+- `D-Design-System/figma-mappings.md` - Figma references (if Mode B)
+- `D-Design-System/component-library-config.md` - Library config (if Mode C)
+
+**Project Config:**
+- Project name
+- Design system mode
+- Version number
+- Creation date
+
+---
+
+## Output
+
+**Generated File:**
+- `D-Design-System/catalog.html` - Interactive HTML catalog
+
+**Features:**
+- Fixed sidebar navigation
+- Live component previews
+- Interactive state toggles
+- Code examples
+- Design token swatches
+- Changelog
+- Figma links (if Mode B)
+- Responsive design
+
+---
+
+## Step 1: Load Template
+
+<action>
+Load catalog template:
+</action>
+
+**File:** `workflows/5-design-system/templates/catalog.template.html`
+
+**Template variables:**
+```
+{{PROJECT_NAME}}
+{{PROJECT_ICON}}
+{{PROJECT_DESCRIPTION}}
+{{PROJECT_OVERVIEW}}
+{{VERSION}}
+{{COMPONENT_COUNT}}
+{{DESIGN_SYSTEM_MODE}}
+{{CREATED_DATE}}
+{{LAST_UPDATED}}
+{{INSTALLATION_INSTRUCTIONS}}
+{{USAGE_EXAMPLE}}
+{{COMPONENT_NAVIGATION}}
+{{DESIGN_TOKENS_CONTENT}}
+{{COLOR_TOKENS}}
+{{TYPOGRAPHY_TOKENS}}
+{{SPACING_TOKENS}}
+{{COMPONENTS_CONTENT}}
+{{CHANGELOG_CONTENT}}
+{{FIGMA_LINKS}}
+```
+
+---
+
+## Step 2: Gather Project Information
+
+<action>
+Extract project metadata:
+</action>
+
+**From project config:**
+```yaml
+project_name: "Dog Week"
+project_icon: "🐕"
+project_description: "Family dog care coordination platform"
+design_system_mode: "custom" # or "library" or "none"
+created_date: "2024-09-15"
+version: "1.0.0"
+```
+
+**Calculate:**
+```
+component_count: Count files in D-Design-System/components/
+last_updated: Current date/time
+```
+
+---
+
+## Step 3: Generate Navigation
+
+<action>
+Build component navigation from component files:
+</action>
+
+**Scan components:**
+```
+D-Design-System/components/
+├── button.md [btn-001]
+├── input.md [inp-001]
+├── card.md [crd-001]
+└── ...
+```
+
+**Group by category:**
+```
+Interactive:
+- Button [btn-001]
+- Link [lnk-001]
+
+Form:
+- Input [inp-001]
+- Select [sel-001]
+
+Display:
+- Card [crd-001]
+- Badge [bdg-001]
+```
+
+**Generate HTML:**
+```html
+<div class="nav-section">
+    <h4 class="nav-section-title">Interactive</h4>
+    <ul class="nav-list">
+        <li><a href="#button" class="nav-link">Button</a></li>
+        <li><a href="#link" class="nav-link">Link</a></li>
+    </ul>
+</div>
+
+<div class="nav-section">
+    <h4 class="nav-section-title">Form</h4>
+    <ul class="nav-list">
+        <li><a href="#input" class="nav-link">Input</a></li>
+        <li><a href="#select" class="nav-link">Select</a></li>
+    </ul>
+</div>
+```
+
+**Replace:** `{{COMPONENT_NAVIGATION}}`
+
+---
+
+## Step 4: Generate Design Tokens Section
+
+<action>
+Read and format design tokens:
+</action>
+
+**Load:** `D-Design-System/design-tokens.md`
+
+**Parse tokens:**
+```yaml
+Colors:
+  primary-500: #3b82f6
+  primary-600: #2563eb
+  gray-900: #111827
+
+Typography:
+  text-display: 3.75rem
+  text-heading-1: 3rem
+  text-body: 1rem
+
+Spacing:
+  spacing-2: 0.5rem
+  spacing-4: 1rem
+  spacing-6: 1.5rem
+```
+
+**Generate color swatches:**
+```html
+<div class="component-card">
+    <h3 class="text-lg font-semibold mb-4">Primary Colors</h3>
+    <div class="variant-grid">
+        <div>
+            <div class="token-swatch" style="background: #3b82f6;"></div>
+            <p class="text-sm font-mono mt-2">primary-500</p>
+            <p class="text-xs text-gray-500">#3b82f6</p>
+        </div>
+        <div>
+            <div class="token-swatch" style="background: #2563eb;"></div>
+            <p class="text-sm font-mono mt-2">primary-600</p>
+            <p class="text-xs text-gray-500">#2563eb</p>
+        </div>
+    </div>
+</div>
+```
+
+**Generate typography examples:**
+```html
+<div class="component-card">
+    <h3 class="text-lg font-semibold mb-4">Typography Scale</h3>
+    <div class="space-y-4">
+        <div>
+            <p class="text-sm text-gray-500 mb-1">text-display (3.75rem)</p>
+            <p style="font-size: 3.75rem; font-weight: 800; line-height: 1.1;">
+                Display Text
+            </p>
+        </div>
+        <div>
+            <p class="text-sm text-gray-500 mb-1">text-heading-1 (3rem)</p>
+            <p style="font-size: 3rem; font-weight: 700; line-height: 1.2;">
+                Heading 1
+            </p>
+        </div>
+    </div>
+</div>
+```
+
+**Replace:** `{{COLOR_TOKENS}}`, `{{TYPOGRAPHY_TOKENS}}`, `{{SPACING_TOKENS}}`
+
+---
+
+## Step 5: Generate Component Sections
+
+<action>
+For each component, generate interactive showcase:
+</action>
+
+**For each file in `D-Design-System/components/`:**
+
+### Parse Component
+
+**Read component file:**
+```markdown
+# Button Component [btn-001]
+
+**Type:** Interactive
+**Category:** Action
+
+## Variants
+- primary
+- secondary
+- ghost
+- outline
+
+## States
+- default
+- hover
+- active
+- disabled
+- loading
+
+## Sizes
+- small
+- medium
+- large
+```
+
+### Generate Component Section
+
+**HTML structure:**
+```html
+<section id="button" class="mb-16" style="scroll-margin-top: 2rem;">
+    <h2 class="text-3xl font-bold text-gray-900 mb-6">
+        Button 
+        <span class="version-badge">[btn-001]</span>
+        <span class="usage-badge">Used in 12 pages</span>
+    </h2>
+    
+    <!-- Component Description -->
+    <div class="component-card">
+        <p class="text-gray-700 mb-4">
+            {{COMPONENT_DESCRIPTION}}
+        </p>
+        <div class="flex gap-2">
+            <span class="text-sm text-gray-600">
+                <strong>Type:</strong> Interactive
+            </span>
+            <span class="text-sm text-gray-600">
+                <strong>Category:</strong> Action
+            </span>
+        </div>
+    </div>
+    
+    <!-- Variants -->
+    <div class="component-card">
+        <h3 class="text-xl font-semibold mb-4">Variants</h3>
+        <div class="component-preview">
+            <div class="variant-grid">
+                {{VARIANT_EXAMPLES}}
+            </div>
+        </div>
+    </div>
+    
+    <!-- States -->
+    <div class="component-card">
+        <h3 class="text-xl font-semibold mb-4">States</h3>
+        <div class="component-preview">
+            <div class="state-grid">
+                {{STATE_EXAMPLES}}
+            </div>
+        </div>
+        
+        <!-- Interactive State Toggle -->
+        <div class="mt-4">
+            <p class="text-sm text-gray-600 mb-2">Try it:</p>
+            <div class="flex gap-2 mb-4">
+                <button onclick="toggleState(this, 'demo-button', 'default')" 
+                        class="px-3 py-1 rounded text-sm bg-blue-500 text-white">
+                    Default
+                </button>
+                <button onclick="toggleState(this, 'demo-button', 'hover')" 
+                        class="px-3 py-1 rounded text-sm bg-gray-200 text-gray-700">
+                    Hover
+                </button>
+                <button onclick="toggleState(this, 'demo-button', 'active')" 
+                        class="px-3 py-1 rounded text-sm bg-gray-200 text-gray-700">
+                    Active
+                </button>
+                <button onclick="toggleState(this, 'demo-button', 'disabled')" 
+                        class="px-3 py-1 rounded text-sm bg-gray-200 text-gray-700">
+                    Disabled
+                </button>
+            </div>
+            <div class="component-preview">
+                <button id="demo-button" class="state-default">
+                    Interactive Button
+                </button>
+            </div>
+        </div>
+    </div>
+    
+    <!-- Code Example -->
+    <div class="component-card">
+        <h3 class="text-xl font-semibold mb-4">Code Example</h3>
+        <div class="code-block">
+            <pre>{{CODE_EXAMPLE}}</pre>
+        </div>
+    </div>
+    
+    <!-- Usage Guidelines -->
+    <div class="component-card">
+        <h3 class="text-xl font-semibold mb-4">Usage Guidelines</h3>
+        {{USAGE_GUIDELINES}}
+    </div>
+    
+    <!-- Figma Link (if Mode B) -->
+    {{FIGMA_COMPONENT_LINK}}
+    
+</section>
+```
+
+### Generate Variant Examples
+
+**For each variant:**
+```html
+<div>
+    <button class="btn-primary btn-medium">
+        Primary Button
+    </button>
+    <p class="text-xs text-gray-500 mt-2">primary</p>
+</div>
+
+<div>
+    <button class="btn-secondary btn-medium">
+        Secondary Button
+    </button>
+    <p class="text-xs text-gray-500 mt-2">secondary</p>
+</div>
+```
+
+### Generate State Examples
+
+**For each state:**
+```html
+<div>
+    <button class="btn-primary btn-medium state-default">
+        Default
+    </button>
+    <p class="text-xs text-gray-500 mt-2">default</p>
+</div>
+
+<div>
+    <button class="btn-primary btn-medium state-hover">
+        Hover
+    </button>
+    <p class="text-xs text-gray-500 mt-2">hover</p>
+</div>
+```
+
+### Generate Code Example
+
+**Extract from component spec:**
+```tsx
+import { Button } from '@/components/button';
+
+<Button variant="primary" size="medium">
+  Click me
+</Button>
+
+<Button variant="secondary" size="large" disabled>
+  Disabled
+</Button>
+```
+
+**Replace:** `{{COMPONENTS_CONTENT}}`
+
+---
+
+## Step 6: Generate Changelog
+
+<action>
+Build changelog from component version histories:
+</action>
+
+**Scan all components for version history:**
+```markdown
+## Version History
+
+**Created:** 2024-09-15
+**Last Updated:** 2024-12-09
+
+**Changes:**
+- 2024-09-15: Created component
+- 2024-10-01: Added loading state
+- 2024-12-09: Updated hover animation
+```
+
+**Generate changelog HTML:**
+```html
+<div class="space-y-4">
+    <div class="border-l-4 border-blue-500 pl-4">
+        <p class="font-semibold">December 9, 2024</p>
+        <ul class="text-sm text-gray-600 mt-1">
+            <li>• Button: Updated hover animation</li>
+            <li>• Input: Added success state</li>
+        </ul>
+    </div>
+    
+    <div class="border-l-4 border-gray-300 pl-4">
+        <p class="font-semibold">October 1, 2024</p>
+        <ul class="text-sm text-gray-600 mt-1">
+            <li>• Button: Added loading state</li>
+        </ul>
+    </div>
+</div>
+```
+
+**Replace:** `{{CHANGELOG_CONTENT}}`
+
+---
+
+## Step 7: Add Figma Links (Mode B)
+
+<action>
+If Mode B, add Figma component links:
+</action>
+
+**Load:** `D-Design-System/figma-mappings.md`
+
+**Parse mappings:**
+```yaml
+Button [btn-001] → figma://file/abc123/node/456:789
+Input [inp-001] → figma://file/abc123/node/456:790
+```
+
+**Generate Figma section:**
+```html
+<h3 class="text-lg font-semibold mb-4">Figma Components</h3>
+<div class="space-y-2">
+    <a href="figma://file/abc123/node/456:789" 
+       class="flex items-center gap-2 text-blue-600 hover:text-blue-800">
+        <svg><!-- Figma icon --></svg>
+        Button [btn-001]
+    </a>
+    <a href="figma://file/abc123/node/456:790" 
+       class="flex items-center gap-2 text-blue-600 hover:text-blue-800">
+        <svg><!-- Figma icon --></svg>
+        Input [inp-001]
+    </a>
+</div>
+```
+
+**Replace:** `{{FIGMA_LINKS}}`
+
+---
+
+## Step 8: Generate Installation Instructions
+
+<action>
+Create mode-specific installation instructions:
+</action>
+
+**Mode B (Custom/Figma):**
+```bash
+# Install dependencies
+npm install
+
+# Import design tokens
+import '@/styles/design-tokens.css';
+
+# Import components
+import { Button } from '@/components/button';
+```
+
+**Mode C (Component Library):**
+```bash
+# Install component library
+npm install shadcn-ui
+
+# Configure library
+npx shadcn-ui init
+
+# Import components
+import { Button } from '@/components/ui/button';
+```
+
+**Replace:** `{{INSTALLATION_INSTRUCTIONS}}`, `{{USAGE_EXAMPLE}}`
+
+---
+
+## Step 9: Write Catalog File
+
+<action>
+Save generated HTML:
+</action>
+
+**File:** `D-Design-System/catalog.html`
+
+**Content:** Fully populated template with all sections
+
+**Validation:**
+- All template variables replaced
+- Valid HTML structure
+- All component sections included
+- Navigation links work
+- Interactive demos functional
+
+---
+
+## Step 10: Update Git
+
+<action>
+Version control the catalog:
+</action>
+
+**Git operations:**
+```bash
+git add D-Design-System/catalog.html
+git commit -m "Update design system catalog - [component changes]"
+```
+
+**Commit message format:**
+```
+Update design system catalog - Added Button loading state
+
+- Button [btn-001]: Added loading state variant
+- Updated catalog with interactive demo
+- Version: 1.0.1
+```
+
+---
+
+## Output Format
+
+**Success message:**
+```
+✅ Design system catalog generated
+
+File: D-Design-System/catalog.html
+Components: 12
+Last updated: 2024-12-09 14:30
+
+View catalog:
+file:///path/to/D-Design-System/catalog.html
+
+Changes committed to git.
+```
+
+---
+
+## Error Handling
+
+### Missing Template
+
+**Error:** Catalog template not found
+
+**Action:**
+```
+⚠️ Catalog template missing
+
+Expected: workflows/5-design-system/templates/catalog.template.html
+
+Please ensure WDS is properly installed.
+```
+
+### Invalid Component Spec
+
+**Error:** Component file has invalid format
+
+**Action:**
+```
+⚠️ Invalid component specification
+
+File: D-Design-System/components/button.md
+Issue: Missing required sections
+
+Skipping component in catalog.
+Please fix component specification.
+```
+
+### No Components
+
+**Error:** No components in design system
+
+**Action:**
+```
+⚠️ No components found
+
+Design system appears empty.
+Catalog will include only foundation (tokens).
+
+Add components to populate catalog.
+```
+
+---
+
+## Automation
+
+**Catalog is automatically regenerated:**
+- After creating new component
+- After adding variant
+- After updating component
+- After updating design tokens
+
+**Manual regeneration:**
+```
+Agent: Regenerate design system catalog
+```
+
+---
+
+## Best Practices
+
+### DO ✅
+- Regenerate after every component change
+- Commit catalog with component changes
+- Include all variants and states
+- Add interactive demos
+- Keep changelog updated
+
+### DON'T ❌
+- Don't manually edit catalog.html
+- Don't skip catalog regeneration
+- Don't forget to commit changes
+- Don't remove interactive features
+
+---
+
+**The interactive catalog is the living documentation of your design system, always up-to-date and version controlled.**

src/modules/wds/workflows/5-design-system/operations/initialize-design-system.md

@@ -0,0 +1,446 @@
+# Operation: Initialize Design System
+
+**Purpose:** Create design system folder structure for the first component.
+
+**When:** First component in project with design system enabled
+
+**Input:** First component specification + design system mode
+
+**Output:** Design system folder structure + first component
+
+---
+
+## Step 1: Confirm Initialization
+
+<output>
+```
+🎉 Initializing Design System!
+
+This is your first design system component.
+I'll create the folder structure and add this component.
+
+Design System Mode: [Custom/Library]
+Component Library: [shadcn/Radix/etc. if applicable]
+```
+</output>
+
+---
+
+## Step 2: Create Folder Structure
+
+<action>
+Create design system folders:
+```
+D-Design-System/
+├── components/
+├── design-tokens.md (placeholder)
+├── component-library-config.md (if Mode C)
+└── figma-mappings.md (if Mode B)
+```
+</action>
+
+<output>
+```
+📁 Created Design System Structure:
+
+D-Design-System/
+├── components/ (empty, ready for first component)
+├── design-tokens.md (placeholder)
+└── [mode-specific files]
+
+✅ Folder structure ready!
+```
+</output>
+
+---
+
+## Step 3: Create Design Tokens Placeholder
+
+<action>
+Create initial design tokens file:
+</action>
+
+**File:** `D-Design-System/design-tokens.md`
+
+```markdown
+# Design Tokens
+
+**Status:** To be defined
+
+Design tokens will be extracted as components are added to the design system.
+
+## Token Categories
+
+### Colors
+- Primary colors
+- Secondary colors
+- Semantic colors (success, error, warning, info)
+- Neutral colors
+
+### Typography
+- Font families
+- Font sizes
+- Font weights
+- Line heights
+- Letter spacing
+
+### Spacing
+- Spacing scale
+- Padding values
+- Margin values
+- Gap values
+
+### Layout
+- Breakpoints
+- Container widths
+- Grid columns
+
+### Effects
+- Shadows
+- Border radius
+- Transitions
+- Animations
+
+---
+
+**Tokens will be populated as components are specified.**
+```
+
+---
+
+## Step 4: Create Mode-Specific Files
+
+### If Mode B: Custom Design System
+
+<action>
+Create Figma mappings file:
+</action>
+
+**File:** `D-Design-System/figma-mappings.md`
+
+```markdown
+# Figma Component Mappings
+
+**Figma File:** [To be specified]
+**Last Updated:** [Date]
+
+## Component Mappings
+
+Components in this design system are linked to Figma components for visual reference and design handoff.
+
+### Format
+
+```
+Component ID → Figma Node ID
+[component-id] → figma://file/[file-id]/node/[node-id]
+```
+
+## Mappings
+
+[To be populated as components are added]
+
+---
+
+**How to find Figma node IDs:**
+1. Select component in Figma
+2. Right-click → Copy link to selection
+3. Extract node ID from URL
+```
+
+### If Mode C: Component Library
+
+<action>
+Create component library config:
+</action>
+
+**File:** `D-Design-System/component-library-config.md`
+
+```markdown
+# Component Library Configuration
+
+**Library:** [shadcn/Radix/MUI/etc.]
+**Version:** [Version]
+**Installation:** [Installation command]
+
+## Library Components Used
+
+This design system uses components from [Library Name].
+
+### Component Mappings
+
+Format: `WDS Component → Library Component`
+
+[To be populated as components are added]
+
+## Customizations
+
+### Theme Configuration
+
+```json
+{
+  "colors": {},
+  "typography": {},
+  "spacing": {},
+  "borderRadius": {}
+}
+```
+
+[To be updated as design system grows]
+
+## Installation Instructions
+
+```bash
+[Installation commands]
+```
+
+---
+
+**Library documentation:** [Link]
+```
+
+---
+
+## Step 5: Create Component Index
+
+<action>
+Create components README:
+</action>
+
+**File:** `D-Design-System/components/README.md`
+
+```markdown
+# Design System Components
+
+**Total Components:** 1
+**Last Updated:** [Date]
+
+## Component List
+
+### Interactive Components
+- [First component will be listed here]
+
+### Form Components
+[None yet]
+
+### Layout Components
+[None yet]
+
+### Content Components
+[None yet]
+
+---
+
+## Component Naming Convention
+
+**Format:** `[type]-[number]`
+
+Examples:
+- btn-001 (Button)
+- inp-001 (Input Field)
+- crd-001 (Card)
+
+## Component File Structure
+
+Each component file includes:
+- Component ID
+- Type and purpose
+- Variants (if any)
+- States
+- Styling/tokens
+- Usage tracking
+
+---
+
+**Components are added automatically as they're discovered during specification.**
+```
+
+---
+
+## Step 6: Add First Component
+
+<action>
+Route to create-new-component operation:
+- Pass component specification
+- Generate first component ID
+- Create component file
+</action>
+
+**Route to:** `create-new-component.md`
+
+---
+
+## Step 7: Generate Initial Catalog
+
+<action>
+Create interactive HTML catalog:
+</action>
+
+**Load and execute:** `operations/generate-catalog.md`
+
+**Initial catalog includes:**
+- Project introduction
+- Design tokens (if defined)
+- First component showcase
+- Getting started guide
+- Empty changelog
+
+**Output:**
+```
+✅ Initial catalog generated
+
+File: D-Design-System/catalog.html
+Components: 1
+View: file:///path/to/catalog.html
+```
+
+---
+
+## Step 8: Update Project Config
+
+<action>
+Mark design system as initialized:
+</action>
+
+**Update project config:**
+```yaml
+design_system:
+  enabled: true
+  mode: [mode]
+  initialized: true
+  initialized_date: [date]
+  folder: D-Design-System/
+  first_component: [component-id]
+  catalog: D-Design-System/catalog.html
+```
+
+---
+
+## Success Message
+
+```
+✅ Design system initialized
+
+Mode: [mode]
+Folder: D-Design-System/
+First component: [ComponentType] [[component-id]]
+Catalog: D-Design-System/catalog.html
+
+Design system is ready to use.
+Components will be extracted automatically as discovered.
+Interactive catalog available for viewing.
+added to the design system if they're reusable.
+
+Next: Continue with component specification in Phase 4
+```
+</output>
+
+---
+
+## Validation
+
+<action>
+Validate initialization:
+- ✓ D-Design-System/ folder exists
+- ✓ components/ subfolder exists
+- ✓ design-tokens.md created
+- ✓ Mode-specific files created
+- ✓ Component index created
+- ✓ First component added
+- ✓ Project config updated
+</action>
+
+**If validation fails:**
+```
+⚠️ Initialization Warning
+
+Some files may not have been created successfully.
+Please check:
+- [List of missing files]
+
+Would you like to retry initialization? (y/n)
+```
+
+---
+
+## Error Handling
+
+**If folder already exists:**
+```
+⚠️ D-Design-System/ folder already exists.
+
+This shouldn't happen for first component initialization.
+
+Options:
+1. Use existing structure (merge)
+2. Backup and recreate
+3. Cancel initialization
+
+Your choice:
+```
+
+**If component creation fails:**
+```
+❌ Error creating first component.
+
+Error: [error message]
+
+Design system structure was created, but component addition failed.
+You can add components manually or retry.
+```
+
+**If mode not specified:**
+```
+⚠️ Design system mode not specified in project config.
+
+Please specify:
+1. Custom (Figma-based)
+2. Component Library (shadcn/Radix/etc.)
+
+Your choice:
+```
+
+---
+
+## Post-Initialization
+
+### Designer Guidance
+
+<output>
+```
+💡 Design System Tips:
+
+**What happens next:**
+- As you specify components, I'll check for similarities
+- Reusable components will be added to the design system
+- You'll make decisions about variants vs new components
+
+**Best practices:**
+- Be consistent with component boundaries
+- Think about reusability early
+- Don't over-engineer - start simple
+
+**You can always:**
+- Add components manually
+- Refactor the design system
+- Merge or split components later
+
+Design systems evolve - this is just the beginning!
+```
+</output>
+
+---
+
+## Return to Workflow
+
+<action>
+Return to design system router:
+- Signal initialization complete
+- Pass first component reference
+- Continue with component addition
+</action>
+
+**Router continues with:** Adding first component to design system
+
+---
+
+**This operation runs once per project. Subsequent components use create-new-component or add-variant operations.**

src/modules/wds/workflows/5-design-system/operations/update-component.md

@@ -0,0 +1,546 @@
+# Operation: Update Component
+
+**Purpose:** Update an existing component definition (not adding variant, but modifying existing).
+
+**When:** Component needs changes (new state, styling update, behavior change)
+
+**Input:** Component ID + update specification
+
+**Output:** Updated component file
+
+---
+
+## When to Use This Operation
+
+**Use this operation when:**
+- Adding new state to all variants (e.g., adding "loading" state)
+- Updating shared styling (e.g., changing border-radius)
+- Modifying behavior (e.g., adding keyboard shortcut)
+- Updating accessibility attributes
+- Refining documentation
+- Fixing errors in component definition
+
+**Don't use this operation for:**
+- Adding new variant → Use `add-variant.md`
+- Creating new component → Use `create-new-component.md`
+- Reusing component → Handled by assessment flow
+
+---
+
+## Step 1: Identify Update Type
+
+<action>
+Determine what's being updated:
+</action>
+
+**Update Types:**
+
+### Type A: Add New State
+Adding state to all variants (e.g., loading, error, success)
+
+### Type B: Update Styling
+Changing visual properties (colors, sizing, spacing)
+
+### Type C: Update Behavior
+Changing interactions, animations, or keyboard support
+
+### Type D: Update Accessibility
+Adding/modifying ARIA attributes or screen reader support
+
+### Type E: Update Documentation
+Clarifying usage, adding examples, fixing errors
+
+### Type F: Refactor
+Reorganizing component structure, splitting/merging variants
+
+<ask>
+```
+What type of update is this?
+
+[A] Add new state
+[B] Update styling
+[C] Update behavior
+[D] Update accessibility
+[E] Update documentation
+[F] Refactor component
+
+Your choice:
+```
+</ask>
+
+---
+
+## Step 2: Load Current Component
+
+<action>
+Read existing component file:
+- Current definition
+- All variants
+- Current states
+- Current styling
+- Usage tracking
+</action>
+
+<output>
+```
+📖 Loaded Button [btn-001]
+
+Current state:
+- Variants: 3 (primary, secondary, navigation)
+- States: default, hover, active, disabled
+- Used in: 9 pages
+- Last updated: 2024-12-09
+```
+</output>
+
+---
+
+## Step 3: Analyze Impact
+
+<action>
+Determine impact of update:
+</action>
+
+**Impact Assessment:**
+
+### Scope
+- All variants affected?
+- Specific variant only?
+- All instances affected?
+- Specific usage only?
+
+### Breaking Changes
+- Does this change existing behavior?
+- Will existing pages need updates?
+- Does this affect developers?
+
+### Compatibility
+- Compatible with current usage?
+- Requires page spec updates?
+- Requires code changes?
+
+<output>
+```
+📊 Impact Analysis:
+
+Update: Adding "loading" state to all button variants
+
+Scope: All variants (primary, secondary, navigation)
+Affected Pages: 9 pages using Button component
+Breaking Change: No (additive only)
+Compatibility: Fully compatible (optional state)
+
+Impact Level: Low (safe to proceed)
+```
+</output>
+
+---
+
+## Step 4: Confirm Update
+
+<ask>
+```
+Ready to update Button [btn-001]
+
+Update: Add "loading" state
+Impact: 9 pages (no breaking changes)
+
+This will:
+✓ Add loading state to component definition
+✓ Update all variant documentation
+✓ Maintain backward compatibility
+
+Proceed with update? (y/n)
+```
+</ask>
+
+---
+
+## Step 5: Apply Update
+
+<action>
+Update component file based on type:
+</action>
+
+### Type A: Add New State
+
+**Update States Section:**
+
+**Before:**
+```markdown
+## States
+
+**Shared States:**
+- default
+- hover
+- active
+- disabled
+```
+
+**After:**
+```markdown
+## States
+
+**Shared States:**
+- default
+- hover
+- active
+- disabled
+- loading  ← Added
+
+**State Descriptions:**
+
+**Loading:**
+- Disabled interaction
+- Shows spinner icon
+- Maintains button size
+- Reduced opacity (0.7)
+```
+
+**Update Variant-Specific Sections (if needed):**
+```markdown
+### Variant-Specific Styling
+
+**Navigation (loading state):**
+- Spinner + arrow icon
+- Arrow fades out during loading
+```
+
+### Type B: Update Styling
+
+**Update Styling Section:**
+
+**Before:**
+```markdown
+### Visual Properties
+
+**Border Radius:** 0.375rem (md)
+```
+
+**After:**
+```markdown
+### Visual Properties
+
+**Border Radius:** 0.5rem (lg)  ← Updated
+
+**Change Reason:** Increased for better visual consistency with other components
+```
+
+### Type C: Update Behavior
+
+**Update Behavior Section:**
+
+**Before:**
+```markdown
+### Keyboard
+
+- Enter/Space: Triggers button action
+- Tab: Moves focus to/from button
+```
+
+**After:**
+```markdown
+### Keyboard
+
+- Enter/Space: Triggers button action
+- Tab: Moves focus to/from button
+- Escape: Cancels action (if in progress)  ← Added
+```
+
+### Type D: Update Accessibility
+
+**Update Accessibility Section:**
+
+**Before:**
+```markdown
+**ARIA Attributes:**
+- role: button
+- aria-disabled: true [when disabled]
+```
+
+**After:**
+```markdown
+**ARIA Attributes:**
+- role: button
+- aria-disabled: true [when disabled]
+- aria-busy: true [when loading]  ← Added
+- aria-live: polite [for status updates]  ← Added
+```
+
+### Type E: Update Documentation
+
+**Update Usage Section:**
+
+**Before:**
+```markdown
+### When to Use
+
+- Primary actions
+- Secondary actions
+```
+
+**After:**
+```markdown
+### When to Use
+
+- Primary actions (submit forms, save data, proceed to next step)
+- Secondary actions (cancel, go back, dismiss)
+- Triggering modals or dialogs  ← Added
+- Navigation to new pages/sections  ← Added
+
+### When Not to Use
+
+- For navigation that looks like text (use Link component)  ← Added
+- For toggling states (use Toggle or Checkbox)  ← Added
+```
+
+### Type F: Refactor
+
+**Example: Split variant into separate component**
+
+```markdown
+## Refactoring Note
+
+**Date:** 2024-12-09
+**Change:** Moved "icon-only" variant to separate Icon Button component
+
+**Reason:** Icon-only buttons have significantly different:
+- Visual structure (no text)
+- Accessibility requirements (requires aria-label)
+- Usage patterns (toolbars, compact spaces)
+
+**Migration:**
+- Old: Button.icon-only [btn-001]
+- New: Icon Button [btn-002]
+
+**Affected Pages:** 5 pages
+**Migration Status:** Complete
+```
+
+---
+
+## Step 6: Update Version History
+
+<action>
+Track update in version history:
+</action>
+
+**Update:**
+```markdown
+## Version History
+
+**Created:** 2024-12-01
+**Last Updated:** 2024-12-09
+
+**Changes:**
+- 2024-12-01: Created component
+- 2024-12-05: Added navigation variant
+- 2024-12-09: Added loading state to all variants  ← Added
+```
+
+---
+
+## Step 7: Notify Affected Pages
+
+<action>
+If update affects existing usage, create notification:
+</action>
+
+<output>
+```
+📢 Component Update Notification
+
+Component: Button [btn-001]
+Update: Added loading state
+Affected Pages: 9
+
+Pages using this component:
+- Login page
+- Signup page
+- Dashboard
+- [... 6 more]
+
+Action Required: None (backward compatible)
+
+Optional: Consider using loading state for async actions
+
+Documentation: See Button component for loading state usage
+```
+</output>
+
+---
+
+## Step 8: Update Design System Stats
+
+<action>
+Update design system metadata:
+</action>
+
+**Update:** `D-Design-System/README.md`
+
+```markdown
+**Last Updated:** 2024-12-09
+**Recent Changes:**
+- Button [btn-001]: Added loading state
+```
+
+---
+
+## Step 9: Complete
+
+<output>
+```
+✅ Component Updated: Button [btn-001]
+
+Update Type: Add new state
+Changes:
+- Added "loading" state to all variants
+- Updated state documentation
+- Version history updated
+
+Impact:
+- 9 pages affected
+- No breaking changes
+- Backward compatible
+
+Next Steps:
+- Pages can optionally use new loading state
+- No immediate action required
+- Consider updating high-traffic pages first
+```
+</output>
+
+---
+
+## Validation
+
+<action>
+Validate update:
+- ✓ Component file updated
+- ✓ Changes documented
+- ✓ Version history updated
+- ✓ Impact assessed
+- ✓ Notifications sent (if needed)
+- ✓ Backward compatibility maintained
+</action>
+
+---
+
+## Error Handling
+
+**If update creates breaking change:**
+```
+⚠️ Breaking Change Detected
+
+This update will break existing usage:
+- [List of breaking changes]
+- Affected pages: [count]
+
+Breaking changes require:
+1. Designer confirmation
+2. Migration plan
+3. Page spec updates
+
+Proceed with breaking change? (y/n)
+
+If yes, I'll create a migration checklist.
+```
+
+**If component file locked:**
+```
+⚠️ Component file is being edited elsewhere.
+
+Component: Button [btn-001]
+Status: Locked by [user/process]
+
+Options:
+1. Wait and retry
+2. Force update (may cause conflicts)
+3. Cancel update
+
+Your choice:
+```
+
+**If update conflicts with variants:**
+```
+⚠️ Update Conflict Detected
+
+You're trying to add "loading" state to all variants,
+but "navigation" variant already has a different loading implementation.
+
+Current navigation loading: Spinner + icon animation
+Proposed loading: Spinner only
+
+Options:
+1. Override navigation variant (make consistent)
+2. Keep navigation variant different (document exception)
+3. Cancel update
+
+Your choice:
+```
+
+---
+
+## Post-Update Actions
+
+### If Breaking Change
+
+<action>
+Create migration checklist:
+</action>
+
+**Output:**
+```markdown
+# Migration Checklist: Button [btn-001] Update
+
+**Update:** [Description]
+**Breaking Changes:** [List]
+**Affected Pages:** [Count]
+
+## Migration Steps
+
+- [ ] Review all affected pages
+- [ ] Update page specifications
+- [ ] Test updated pages
+- [ ] Update documentation
+- [ ] Deploy changes
+
+## Affected Pages
+
+- [ ] Login page - [Specific changes needed]
+- [ ] Signup page - [Specific changes needed]
+- [ ] Dashboard - [Specific changes needed]
+[... more pages]
+
+## Rollback Plan
+
+If issues arise:
+1. Revert component file to previous version
+2. Restore page specifications
+3. Document issues encountered
+```
+
+### If Major Update
+
+<action>
+Suggest design system review:
+</action>
+
+<output>
+```
+💡 Design System Health Check Recommended
+
+This is a significant update to a widely-used component.
+
+Consider reviewing:
+- Component consistency across design system
+- Other components that might need similar updates
+- Overall design system patterns
+
+Schedule a design system review session?
+```
+</output>
+
+---
+
+**This operation updates a component. Changes apply to all future usage automatically.**

src/modules/wds/workflows/5-design-system/templates/catalog.template.html

@@ -0,0 +1,363 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{PROJECT_NAME}} Design System</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&display=swap" rel="stylesheet">
+    <style>
+        body {
+            font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        }
+        
+        .nav-sidebar {
+            position: fixed;
+            left: 0;
+            top: 0;
+            bottom: 0;
+            width: 280px;
+            background: white;
+            border-right: 1px solid #e5e7eb;
+            overflow-y: auto;
+            z-index: 50;
+        }
+        
+        .nav-content {
+            padding: 2rem 1.5rem;
+        }
+        
+        .nav-logo {
+            margin-bottom: 2rem;
+            padding-bottom: 1.5rem;
+            border-bottom: 1px solid #e5e7eb;
+        }
+        
+        .nav-section {
+            margin-bottom: 1.5rem;
+        }
+        
+        .nav-section-title {
+            font-size: 0.75rem;
+            font-weight: 600;
+            text-transform: uppercase;
+            letter-spacing: 0.05em;
+            color: #6b7280;
+            margin-bottom: 0.5rem;
+        }
+        
+        .nav-list {
+            list-style: none;
+            padding: 0;
+            margin: 0;
+        }
+        
+        .nav-link {
+            display: block;
+            padding: 0.5rem 0.75rem;
+            color: #374151;
+            text-decoration: none;
+            border-radius: 0.375rem;
+            transition: all 0.15s;
+        }
+        
+        .nav-link:hover {
+            background: #f3f4f6;
+            color: #111827;
+        }
+        
+        .nav-link.active {
+            background: #eff6ff;
+            color: #2563eb;
+            font-weight: 500;
+        }
+        
+        .main-content {
+            margin-left: 280px;
+            padding: 3rem;
+            min-height: 100vh;
+            background: #f9fafb;
+        }
+        
+        .component-card {
+            background: white;
+            border-radius: 0.5rem;
+            border: 1px solid #e5e7eb;
+            padding: 2rem;
+            margin-bottom: 1.5rem;
+        }
+        
+        .component-preview {
+            background: #f9fafb;
+            border: 1px solid #e5e7eb;
+            border-radius: 0.375rem;
+            padding: 2rem;
+            margin: 1rem 0;
+        }
+        
+        .code-block {
+            background: #1f2937;
+            color: #e5e7eb;
+            border-radius: 0.375rem;
+            padding: 1rem;
+            overflow-x: auto;
+            font-family: 'Fira Code', monospace;
+            font-size: 0.875rem;
+            margin: 1rem 0;
+        }
+        
+        .variant-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+            gap: 1rem;
+            margin: 1rem 0;
+        }
+        
+        .state-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+            gap: 1rem;
+            margin: 1rem 0;
+        }
+        
+        .token-swatch {
+            height: 4rem;
+            border-radius: 0.375rem;
+            border: 1px solid #e5e7eb;
+        }
+        
+        .version-badge {
+            display: inline-block;
+            padding: 0.25rem 0.75rem;
+            background: #eff6ff;
+            color: #2563eb;
+            border-radius: 9999px;
+            font-size: 0.75rem;
+            font-weight: 500;
+        }
+        
+        .usage-badge {
+            display: inline-block;
+            padding: 0.25rem 0.75rem;
+            background: #f0fdf4;
+            color: #16a34a;
+            border-radius: 9999px;
+            font-size: 0.75rem;
+            font-weight: 500;
+        }
+    </style>
+</head>
+<body>
+    
+    <!-- Fixed Sidebar Navigation -->
+    <aside class="nav-sidebar">
+        <div class="nav-content">
+            <div class="nav-logo">
+                <div class="flex items-center space-x-2">
+                    <span class="text-2xl">{{PROJECT_ICON}}</span>
+                    <div>
+                        <div class="font-bold">{{PROJECT_NAME}}</div>
+                        <div class="text-xs text-gray-500">Design System</div>
+                    </div>
+                </div>
+                <div class="mt-2 text-xs text-gray-500">
+                    Last updated: {{LAST_UPDATED}}
+                </div>
+            </div>
+            
+            <nav>
+                <div class="nav-section">
+                    <h4 class="nav-section-title">Overview</h4>
+                    <ul class="nav-list">
+                        <li><a href="#introduction" class="nav-link">Introduction</a></li>
+                        <li><a href="#getting-started" class="nav-link">Getting Started</a></li>
+                    </ul>
+                </div>
+                
+                <div class="nav-section">
+                    <h4 class="nav-section-title">Foundation</h4>
+                    <ul class="nav-list">
+                        <li><a href="#design-tokens" class="nav-link">Design Tokens</a></li>
+                        <li><a href="#colors" class="nav-link">Colors</a></li>
+                        <li><a href="#typography" class="nav-link">Typography</a></li>
+                        <li><a href="#spacing" class="nav-link">Spacing</a></li>
+                    </ul>
+                </div>
+                
+                {{COMPONENT_NAVIGATION}}
+                
+                <div class="nav-section">
+                    <h4 class="nav-section-title">Resources</h4>
+                    <ul class="nav-list">
+                        <li><a href="#changelog" class="nav-link">Changelog</a></li>
+                        <li><a href="#figma" class="nav-link">Figma Files</a></li>
+                    </ul>
+                </div>
+            </nav>
+        </div>
+    </aside>
+
+    <!-- Main Content -->
+    <div class="main-content">
+        <div class="max-w-6xl mx-auto">
+            
+            <!-- Introduction -->
+            <section id="introduction" class="mb-16" style="scroll-margin-top: 2rem;">
+                <h1 class="text-5xl font-extrabold text-gray-900 mb-4">{{PROJECT_NAME}} Design System</h1>
+                <p class="text-xl text-gray-600 mb-8">{{PROJECT_DESCRIPTION}}</p>
+                
+                <div class="component-card">
+                    <p class="text-gray-700 leading-relaxed mb-4">
+                        {{PROJECT_OVERVIEW}}
+                    </p>
+                    <div class="flex gap-2 flex-wrap">
+                        <span class="version-badge">Version {{VERSION}}</span>
+                        <span class="usage-badge">{{COMPONENT_COUNT}} Components</span>
+                        <span class="version-badge">Mode: {{DESIGN_SYSTEM_MODE}}</span>
+                    </div>
+                    <p class="text-sm text-gray-600 mt-4">
+                        <strong>Method:</strong> Whiteport Design Studio (WDS) • <strong>Created:</strong> {{CREATED_DATE}}
+                    </p>
+                </div>
+            </section>
+
+            <!-- Getting Started -->
+            <section id="getting-started" class="mb-16" style="scroll-margin-top: 2rem;">
+                <h2 class="text-3xl font-bold text-gray-900 mb-6">Getting Started</h2>
+                
+                <div class="component-card">
+                    <h3 class="text-xl font-semibold mb-4">Installation</h3>
+                    <div class="code-block">
+                        <pre>{{INSTALLATION_INSTRUCTIONS}}</pre>
+                    </div>
+                </div>
+                
+                <div class="component-card">
+                    <h3 class="text-xl font-semibold mb-4">Usage</h3>
+                    <p class="text-gray-700 mb-4">
+                        Import components from the design system:
+                    </p>
+                    <div class="code-block">
+                        <pre>{{USAGE_EXAMPLE}}</pre>
+                    </div>
+                </div>
+            </section>
+
+            <!-- Design Tokens -->
+            <section id="design-tokens" class="mb-16" style="scroll-margin-top: 2rem;">
+                <h2 class="text-3xl font-bold text-gray-900 mb-6">Design Tokens</h2>
+                
+                <div class="component-card">
+                    <p class="text-gray-700 mb-4">
+                        Design tokens provide a consistent visual language across the application.
+                        All components use these tokens to ensure consistency and maintainability.
+                    </p>
+                </div>
+                
+                {{DESIGN_TOKENS_CONTENT}}
+            </section>
+
+            <!-- Colors -->
+            <section id="colors" class="mb-16" style="scroll-margin-top: 2rem;">
+                <h2 class="text-3xl font-bold text-gray-900 mb-6">Colors</h2>
+                {{COLOR_TOKENS}}
+            </section>
+
+            <!-- Typography -->
+            <section id="typography" class="mb-16" style="scroll-margin-top: 2rem;">
+                <h2 class="text-3xl font-bold text-gray-900 mb-6">Typography</h2>
+                {{TYPOGRAPHY_TOKENS}}
+            </section>
+
+            <!-- Spacing -->
+            <section id="spacing" class="mb-16" style="scroll-margin-top: 2rem;">
+                <h2 class="text-3xl font-bold text-gray-900 mb-6">Spacing</h2>
+                {{SPACING_TOKENS}}
+            </section>
+
+            <!-- Components -->
+            {{COMPONENTS_CONTENT}}
+
+            <!-- Changelog -->
+            <section id="changelog" class="mb-16" style="scroll-margin-top: 2rem;">
+                <h2 class="text-3xl font-bold text-gray-900 mb-6">Changelog</h2>
+                
+                <div class="component-card">
+                    <h3 class="text-lg font-semibold mb-4">Recent Updates</h3>
+                    {{CHANGELOG_CONTENT}}
+                </div>
+            </section>
+
+            <!-- Figma -->
+            <section id="figma" class="mb-16" style="scroll-margin-top: 2rem;">
+                <h2 class="text-3xl font-bold text-gray-900 mb-6">Figma Files</h2>
+                
+                <div class="component-card">
+                    {{FIGMA_LINKS}}
+                </div>
+            </section>
+
+        </div>
+    </div>
+
+    <script>
+        // Smooth scrolling for navigation links
+        document.querySelectorAll('.nav-link').forEach(link => {
+            link.addEventListener('click', function(e) {
+                e.preventDefault();
+                const targetId = this.getAttribute('href').substring(1);
+                const targetElement = document.getElementById(targetId);
+                if (targetElement) {
+                    targetElement.scrollIntoView({ behavior: 'smooth' });
+                    
+                    // Update active state
+                    document.querySelectorAll('.nav-link').forEach(l => l.classList.remove('active'));
+                    this.classList.add('active');
+                }
+            });
+        });
+
+        // Update active nav link on scroll
+        const sections = document.querySelectorAll('section[id]');
+        const navLinks = document.querySelectorAll('.nav-link');
+
+        window.addEventListener('scroll', () => {
+            let current = '';
+            sections.forEach(section => {
+                const sectionTop = section.offsetTop;
+                const sectionHeight = section.clientHeight;
+                if (window.pageYOffset >= sectionTop - 100) {
+                    current = section.getAttribute('id');
+                }
+            });
+
+            navLinks.forEach(link => {
+                link.classList.remove('active');
+                if (link.getAttribute('href') === `#${current}`) {
+                    link.classList.add('active');
+                }
+            });
+        });
+
+        // Interactive component demos
+        function toggleState(button, componentId, state) {
+            const component = document.getElementById(componentId);
+            if (component) {
+                // Remove all state classes
+                component.className = component.className.replace(/state-\w+/g, '');
+                // Add new state class
+                component.classList.add(`state-${state}`);
+                
+                // Update button states
+                button.parentElement.querySelectorAll('button').forEach(btn => {
+                    btn.classList.remove('bg-blue-500', 'text-white');
+                    btn.classList.add('bg-gray-200', 'text-gray-700');
+                });
+                button.classList.remove('bg-gray-200', 'text-gray-700');
+                button.classList.add('bg-blue-500', 'text-white');
+            }
+        }
+    </script>
+
+</body>
+</html>

src/modules/wds/workflows/5-design-system/templates/component-library-config.template.md

@@ -0,0 +1,63 @@
+# Component Library Configuration
+
+**Library:** [Library Name]
+**Version:** [Version]
+**Last Updated:** [Date]
+
+---
+
+## Installation
+
+```bash
+[Installation commands]
+```
+
+---
+
+## Component Mappings
+
+**Format:** `WDS Component → Library Component`
+
+### Interactive Components
+- Button [btn-001] → shadcn/ui Button
+- [More mappings]
+
+### Form Components
+- Input Field [inp-001] → shadcn/ui Input
+- [More mappings]
+
+---
+
+## Theme Configuration
+
+```json
+{
+  "colors": {
+    "primary": "#2563eb",
+    "secondary": "#64748b"
+  },
+  "typography": {
+    "fontFamily": "Inter, sans-serif"
+  },
+  "spacing": {
+    "unit": "0.25rem"
+  },
+  "borderRadius": {
+    "default": "0.375rem"
+  }
+}
+```
+
+---
+
+## Customizations
+
+[Document any customizations from library defaults]
+
+---
+
+## Library Documentation
+
+**Official Docs:** [Link]
+**Component Gallery:** [Link]
+**GitHub:** [Link]

src/modules/wds/workflows/5-design-system/templates/component.template.md

@@ -0,0 +1,130 @@
+# [Component Name] [[component-id]]
+
+**Type:** [Interactive/Form/Layout/Content/Feedback/Navigation]
+**Category:** [Specific category]
+**Purpose:** [Brief description]
+
+---
+
+## Overview
+
+[Component description and when to use it]
+
+---
+
+## Variants
+
+[List variants if any, or state "This component has no variants"]
+
+---
+
+## States
+
+**Required States:**
+- default
+- [other required states]
+
+**Optional States:**
+- [optional states if any]
+
+**State Descriptions:**
+[Describe each state]
+
+---
+
+## Styling
+
+### Visual Properties
+
+**Size:** [values]
+**Shape:** [values]
+**Colors:** [values]
+**Typography:** [values]
+**Spacing:** [values]
+
+### Design Tokens
+
+```yaml
+[Token definitions]
+```
+
+### Figma Reference
+
+[If Mode B - Custom Design System]
+
+### Library Component
+
+[If Mode C - Component Library]
+
+---
+
+## Behavior
+
+### Interactions
+
+[Describe interactions]
+
+### Animations
+
+[Describe animations if any]
+
+---
+
+## Accessibility
+
+**ARIA Attributes:**
+[List ARIA attributes]
+
+**Keyboard Support:**
+[List keyboard shortcuts]
+
+**Screen Reader:**
+[How screen readers announce this]
+
+---
+
+## Usage
+
+### When to Use
+
+[Guidelines]
+
+### When Not to Use
+
+[Guidelines]
+
+### Best Practices
+
+- [Practice 1]
+- [Practice 2]
+
+---
+
+## Used In
+
+**Pages:** [count]
+
+**Examples:**
+- [Page] - [Usage]
+
+---
+
+## Related Components
+
+[Related components if any]
+
+---
+
+## Version History
+
+**Created:** [Date]
+**Last Updated:** [Date]
+
+**Changes:**
+- [Date]: [Change]
+
+---
+
+## Notes
+
+[Additional notes]

src/modules/wds/workflows/5-design-system/templates/design-tokens.template.md

@@ -0,0 +1,155 @@
+# Design Tokens
+
+**Last Updated:** [Date]
+**Token Count:** [count]
+
+---
+
+## Colors
+
+### Primary Colors
+```yaml
+primary-50: #eff6ff
+primary-100: #dbeafe
+primary-200: #bfdbfe
+primary-300: #93c5fd
+primary-400: #60a5fa
+primary-500: #3b82f6
+primary-600: #2563eb
+primary-700: #1d4ed8
+primary-800: #1e40af
+primary-900: #1e3a8a
+```
+
+### Semantic Colors
+```yaml
+success: #10b981
+error: #ef4444
+warning: #f59e0b
+info: #3b82f6
+```
+
+### Neutral Colors
+```yaml
+gray-50: #f9fafb
+gray-100: #f3f4f6
+[... more grays]
+gray-900: #111827
+```
+
+---
+
+## Typography
+
+### Font Families
+```yaml
+font-sans: "Inter, system-ui, sans-serif"
+font-mono: "JetBrains Mono, monospace"
+```
+
+### Font Sizes
+```yaml
+text-xs: 0.75rem
+text-sm: 0.875rem
+text-base: 1rem
+text-lg: 1.125rem
+text-xl: 1.25rem
+text-2xl: 1.5rem
+text-3xl: 1.875rem
+text-4xl: 2.25rem
+```
+
+### Font Weights
+```yaml
+font-normal: 400
+font-medium: 500
+font-semibold: 600
+font-bold: 700
+```
+
+---
+
+## Spacing
+
+```yaml
+spacing-0: 0
+spacing-1: 0.25rem
+spacing-2: 0.5rem
+spacing-3: 0.75rem
+spacing-4: 1rem
+spacing-6: 1.5rem
+spacing-8: 2rem
+spacing-12: 3rem
+spacing-16: 4rem
+```
+
+---
+
+## Layout
+
+### Breakpoints
+```yaml
+sm: 640px
+md: 768px
+lg: 1024px
+xl: 1280px
+2xl: 1536px
+```
+
+### Container Widths
+```yaml
+container-sm: 640px
+container-md: 768px
+container-lg: 1024px
+container-xl: 1280px
+```
+
+---
+
+## Effects
+
+### Shadows
+```yaml
+shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05)
+shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1)
+shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1)
+```
+
+### Border Radius
+```yaml
+radius-sm: 0.125rem
+radius-md: 0.375rem
+radius-lg: 0.5rem
+radius-full: 9999px
+```
+
+### Transitions
+```yaml
+transition-fast: 150ms
+transition-base: 200ms
+transition-slow: 300ms
+```
+
+---
+
+## Component-Specific Tokens
+
+### Button
+```yaml
+button-padding-x: spacing-4
+button-padding-y: spacing-2
+button-border-radius: radius-md
+button-font-weight: font-semibold
+```
+
+### Input
+```yaml
+input-height: 2.5rem
+input-padding-x: spacing-3
+input-border-color: gray-300
+input-border-radius: radius-md
+```
+
+---
+
+**Tokens are automatically populated as components are added to the design system.**

src/modules/wds/workflows/5-design-system/workflow.yaml

@@ -0,0 +1,15 @@
+name: Phase 5 - Design System
+description: Extract and maintain design system components (optional)
+version: 1.0.0
+
+trigger:
+  - Called from Phase 4 component specification
+  - Only active if design system enabled in project
+  - First component triggers initialization
+
+entry_point: design-system-router.md
+
+outputs:
+  - D-Design-System/components/*.md
+  - D-Design-System/design-tokens.md
+  - D-Design-System/component-library-config.md