diff --git a/CHANGELOG.md b/CHANGELOG.md
index 80e14e90..fb966a1b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@
**See detailed log:** [conversion-logs/session-2025-12-09-micro-steps-concepts.md](./conversion-logs/session-2025-12-09-micro-steps-concepts.md)
**Summary:**
+
- ✅ Phase 6: Design Deliveries (7 micro-step files)
- ✅ Phase 7: Testing (8 micro-step files)
- ✅ Phase 8: Ongoing Development (9 micro-step files)
diff --git a/CONCEPTS-INTEGRATION.md b/CONCEPTS-INTEGRATION.md
index bce5199a..33f878ef 100644
--- a/CONCEPTS-INTEGRATION.md
+++ b/CONCEPTS-INTEGRATION.md
@@ -7,9 +7,11 @@
## Core Documentation
### Glossary (Complete Reference)
+
**File:** `src/core/resources/wds/glossary.md`
**Contains:**
+
- ✅ Greenfield Development (definition, origin, examples)
- ✅ Brownfield Development (definition, origin, examples)
- ✅ Kaizen (改善) - Continuous Improvement (definition, philosophy, examples)
@@ -26,9 +28,11 @@
## Workflow Documentation
### 1. Project Type Selection
+
**File:** `src/modules/wds/workflows/workflow-init/project-type-selection.md`
**Concepts integrated:**
+
- ✅ **Greenfield Development** - New Product entry point
- ✅ **Brownfield Development** - Existing Product entry point
- ✅ Definitions and origins
@@ -38,6 +42,7 @@
**Section:** "Software Development Terminology"
**Usage:**
+
```
Which type of project are you working on?
@@ -48,9 +53,11 @@ Which type of project are you working on?
---
### 2. Phase 8 Workflow
+
**File:** `src/modules/wds/workflows/8-ongoing-development/workflow.md`
**Concepts integrated:**
+
- ✅ **Kaizen (改善)** - Continuous Improvement (detailed)
- ✅ **Kaikaku (改革)** - Revolutionary Change (detailed)
- ✅ When to use each approach
@@ -60,6 +67,7 @@ Which type of project are you working on?
**Section:** "Lean Manufacturing Philosophy"
**Key insight:**
+
```
Kaikaku (改革): Build product v1.0 (Phases 1-7)
↓
@@ -73,9 +81,11 @@ Kaizen cycle 1, 2, 3, 4, 5... (ongoing)
---
### 3. Existing Product Guide
+
**File:** `src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md`
**Concepts integrated:**
+
- ✅ **Brownfield + Kaizen** - Phase 8 approach
- ✅ **Greenfield + Kaikaku** - Phases 1-7 approach
- ✅ Terminology explanations
@@ -88,9 +98,11 @@ Kaizen cycle 1, 2, 3, 4, 5... (ongoing)
---
### 4. Phase 8 Step 8.8 (Iterate)
+
**File:** `src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md`
**Concepts integrated:**
+
- ✅ **Kaizen vs Kaikaku** comparison
- ✅ Quick reference for designers
- ✅ Link to glossary
@@ -105,9 +117,11 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai
## Concept Usage by WDS Phase
### Phases 1-7: New Product Development
+
**Approach:** Greenfield + Kaikaku
**Characteristics:**
+
- Starting from scratch
- Complete user flows
- Revolutionary change
@@ -115,15 +129,18 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai
- Months of work
**Concepts:**
+
- Greenfield Development
- Kaikaku (改革) - Revolutionary Change
---
### Phase 8: Ongoing Development
+
**Approach:** Brownfield + Kaizen
**Characteristics:**
+
- Existing product
- Incremental improvements
- Continuous improvement
@@ -131,6 +148,7 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai
- 1-2 week cycles
**Concepts:**
+
- Brownfield Development
- Kaizen (改善) - Continuous Improvement
- Muda (無駄) - Waste elimination
@@ -162,18 +180,20 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai
**Question:** "Should I do small improvements or big redesign?"
**Small Improvements (Kaizen 改善):**
+
- ✅ Product is working
- ✅ Want low-risk changes
- ✅ 1-2 week cycles
- ✅ Continuous learning
-→ Stay in Phase 8, create System Updates
+ → Stay in Phase 8, create System Updates
**Big Redesign (Kaikaku 改革):**
+
- ✅ Product needs overhaul
- ✅ Fundamental problems
- ✅ Months of work
- ✅ Revolutionary change
-→ Return to Phases 1-7, create Design Deliveries
+ → Return to Phases 1-7, create Design Deliveries
---
@@ -182,16 +202,16 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai
```
1. Glossary (src/core/resources/wds/glossary.md)
└─ Complete definitions and philosophy
-
+
2. Project Type Selection (workflows/workflow-init/project-type-selection.md)
└─ Greenfield vs Brownfield choice
-
+
3. Phase 8 Workflow (workflows/8-ongoing-development/workflow.md)
└─ Kaizen vs Kaikaku philosophy
-
+
4. Existing Product Guide (workflows/8-ongoing-development/existing-product-guide.md)
└─ Brownfield + Kaizen approach
-
+
5. Step 8.8 (workflows/8-ongoing-development/steps/step-8.8-iterate.md)
└─ Quick reference during iteration
```
@@ -227,18 +247,21 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai
## Key Takeaways
**For Designers:**
+
1. Understand if you're in Greenfield or Brownfield context
2. Choose Kaikaku (revolutionary) or Kaizen (continuous) approach
3. Use appropriate deliverables (DD-XXX vs SU-XXX)
4. Follow appropriate workflow (Phases 1-7 vs Phase 8)
**For Documentation:**
+
1. Glossary is the source of truth
2. Concepts are integrated where relevant
3. Quick references in workflow steps
4. Consistent terminology throughout
**Philosophy:**
+
- Kaikaku to establish, Kaizen to improve
- Greenfield gives freedom, Brownfield gives context
- Small improvements compound over time
diff --git a/README.md b/README.md
index db16ad19..28499070 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,7 @@ docs/
```
**Why alphabetical?** The `A-B-C-D-E` prefix creates a clear visual namespace that:
+
- Groups WDS artifacts together in file explorers
- Distinguishes from other project documentation
- Provides natural sort order matching workflow progression
@@ -90,16 +91,16 @@ docs/
WDS provides **8 design phases** that can be selected based on project scale:
-| Phase | Name | Output Folder | Description |
-|-------|------|---------------|-------------|
-| 1️⃣ | **Product Exploration** | `A-Product-Brief/` | Vision, positioning, ICP framework |
-| 2️⃣ | **Trigger Mapping** | `B-Trigger-Map/` | Personas, business goals, Feature Impact Analysis |
-| 3️⃣ | **PRD Platform** | `C-Platform-Requirements/` | Technical foundation (parallel with Phase 4) |
-| 4️⃣ | **UX Design** | `C-Scenarios/` | User scenarios, sketches, specifications |
-| 5️⃣ | **Design System** | `D-Design-System/` | Design tokens, component library (optional) |
-| 6️⃣ | **PRD & Design Deliveries** | `E-PRD/` | Complete PRD + packaged flows for BMM |
-| 7️⃣ | **Testing** | `F-Testing/` | Designer validation of implementation |
-| 8️⃣ | **Product Development** | `G-Product-Development/` | Ongoing improvements (existing products) |
+| Phase | Name | Output Folder | Description |
+| ----- | --------------------------- | -------------------------- | ------------------------------------------------- |
+| 1️⃣ | **Product Exploration** | `A-Product-Brief/` | Vision, positioning, ICP framework |
+| 2️⃣ | **Trigger Mapping** | `B-Trigger-Map/` | Personas, business goals, Feature Impact Analysis |
+| 3️⃣ | **PRD Platform** | `C-Platform-Requirements/` | Technical foundation (parallel with Phase 4) |
+| 4️⃣ | **UX Design** | `C-Scenarios/` | User scenarios, sketches, specifications |
+| 5️⃣ | **Design System** | `D-Design-System/` | Design tokens, component library (optional) |
+| 6️⃣ | **PRD & Design Deliveries** | `E-PRD/` | Complete PRD + packaged flows for BMM |
+| 7️⃣ | **Testing** | `F-Testing/` | Designer validation of implementation |
+| 8️⃣ | **Product Development** | `G-Product-Development/` | Ongoing improvements (existing products) |
### Phase-Selectable Workflow
@@ -116,11 +117,11 @@ Unlike rigid tracks, WDS allows users to **select individual phases** based on p
WDS introduces **3 specialized design agents** named after Norse mythology:
-| Agent | Role | Norse Meaning |
-|-------|------|---------------|
-| **Saga the WDS Analyst** | Business & Product Analyst | Goddess of stories & wisdom - uncovers your business story |
-| **Idunn the WDS PM** | Product Manager | Goddess of renewal & youth - keeps projects vital and thriving |
-| **Freyja the WDS Designer** | UX/UI Designer | Goddess of beauty, magic & strategy - creates experiences users love |
+| Agent | Role | Norse Meaning |
+| --------------------------- | -------------------------- | -------------------------------------------------------------------- |
+| **Saga the WDS Analyst** | Business & Product Analyst | Goddess of stories & wisdom - uncovers your business story |
+| **Idunn the WDS PM** | Product Manager | Goddess of renewal & youth - keeps projects vital and thriving |
+| **Freyja the WDS Designer** | UX/UI Designer | Goddess of beauty, magic & strategy - creates experiences users love |
---
@@ -140,6 +141,7 @@ E-PRD/ ──────────────► PRD + Design
```
The `E-PRD/` folder serves as the **integration bridge**, containing:
+
- Complete PRD (00-PRD.md) with functional requirements
- Design Deliveries (DD-XXX.yaml) - packaged flows for BMM handoff
- Scenario-to-epic mapping
@@ -173,6 +175,7 @@ bmad install wds
### What Gets Installed
The WDS installer creates:
+
- ✅ `docs/` directory structure with alphabetized folders (A-G)
- ✅ All 8 phase folders ready for your design work
- ✅ `.gitkeep` files to preserve empty directories
@@ -251,6 +254,7 @@ git push origin main
## 📚 Original BMad Method Documentation
For complete BMad Method documentation, see:
+
- **[BMad Method README](https://github.com/bmad-code-org/BMAD-METHOD)** - Main documentation
- **[BMM Module Docs](./src/modules/bmm/docs/README.md)** - Development workflows
- **[Agent Customization](./docs/agent-customization-guide.md)** - Customize agents
diff --git a/WDS-V6-CONVERSION-ROADMAP.md b/WDS-V6-CONVERSION-ROADMAP.md
index 0c41e928..dd15fb63 100644
--- a/WDS-V6-CONVERSION-ROADMAP.md
+++ b/WDS-V6-CONVERSION-ROADMAP.md
@@ -59,6 +59,7 @@ WDS (Design) ────────► E-UI-Roadmap/ ────────
**Decision:** Whiteport Design Studio (WDS)
**Alternatives Considered:**
+
- BMad Design Studio
- BMad UX
@@ -69,16 +70,19 @@ WDS (Design) ────────► E-UI-Roadmap/ ────────
**Decision:** Fork BMad-METHOD repository
**Alternatives Considered:**
+
- Standalone repository
- Rename existing WPS2C repo
**Reasoning:**
+
- Maximum adoption through BMad ecosystem
- Path to official module status via PR
- Shared core infrastructure
- Automatic ecosystem integration
**Fork Details:**
+
- Origin: `https://github.com/whiteport-collective/whiteport-design-studio.git`
- Upstream: `https://github.com/bmad-code-org/BMAD-METHOD.git`
@@ -87,6 +91,7 @@ WDS (Design) ────────► E-UI-Roadmap/ ────────
**Decision:** Work directly on `main` branch
**Reasoning:**
+
- Simpler workflow during development
- WDS is substantial addition, not small tweak
- Fork effectively becomes WDS home
@@ -99,6 +104,7 @@ WDS (Design) ────────► E-UI-Roadmap/ ────────
**Description:** Users select individual phases based on project needs rather than choosing from predefined tracks.
**Examples:**
+
- Landing page → Phases 1, 4, 5
- Full product → All 6 phases
- Design system only → Phases 4, 5
@@ -116,6 +122,7 @@ WDS (Design) ────────► E-UI-Roadmap/ ────────
**Convention:** Only `README.md` at module root; all other documentation uses `xxx-guide.md` naming pattern.
**Examples:**
+
- ✅ `wds/README.md` (only one)
- ✅ `wds/docs/method/wds-method-guide.md`
- ✅ `wds/docs/quick-start-guide.md`
@@ -205,13 +212,14 @@ src/modules/wds/
### 4.3 Agents - The Norse Pantheon 🏔️
-| Agent | File | Role | Norse Meaning | Status |
-|-------|------|------|---------------|--------|
-| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom | ✅ **COMPLETE (Dec 9)** |
-| **Idunn the PM** | `idunn-pm.agent.yaml` | Product Manager | Goddess of renewal & youth | ✅ **COMPLETE (Dec 9)** |
-| **Freyja the Designer** | `freyja-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy | ✅ **COMPLETE (Dec 9)** |
+| Agent | File | Role | Norse Meaning | Status |
+| ----------------------- | ------------------------- | -------------------------- | ----------------------------------- | ----------------------- |
+| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom | ✅ **COMPLETE (Dec 9)** |
+| **Idunn the PM** | `idunn-pm.agent.yaml` | Product Manager | Goddess of renewal & youth | ✅ **COMPLETE (Dec 9)** |
+| **Freyja the Designer** | `freyja-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy | ✅ **COMPLETE (Dec 9)** |
**Why "Name the Function" format?**
+
- Reads naturally: "Saga the Analyst"
- Distinctive Norse mythology names
- Function is immediately clear
@@ -237,7 +245,8 @@ docs/
└── G-Product-Development/ # Phase 8: Ongoing product development (existing products)
```
-**Note:**
+**Note:**
+
- **C-Platform-Requirements/** and **C-Scenarios/** both use "C" prefix because Phase 3 and 4 run in parallel
- **Platform Requirements** (C-Platform-Requirements/) stays separate - technical foundation
- **E-PRD/** contains both the PRD and Design Deliveries (DD-XXX.yaml packages for BMM handoff)
@@ -246,32 +255,33 @@ docs/
### 5.2 Why Alphabetical Prefix?
-| Reason | Benefit |
-|--------|---------|
-| Visual namespace | Clearly grouped in file explorers |
-| Brand signature | "A-B-C-D-E = WDS" recognition |
-| Non-conflicting | Won't clash with other docs folders |
-| Natural sort | Always grouped together |
-| Professional | Enterprise documentation feel |
+| Reason | Benefit |
+| ---------------- | ----------------------------------- |
+| Visual namespace | Clearly grouped in file explorers |
+| Brand signature | "A-B-C-D-E = WDS" recognition |
+| Non-conflicting | Won't clash with other docs folders |
+| Natural sort | Always grouped together |
+| Professional | Enterprise documentation feel |
### 5.3 Phase-to-Folder Mapping
-| Phase | # | Name | Output Folder |
-|-------|---|------|---------------|
-| 1 | Product Exploration | Product Brief | `A-Product-Brief/` |
-| 2 | Trigger Mapping | User psychology & business goals | `B-Trigger-Map/` |
-| 3 | PRD Platform | Technical foundation (platform only) | `C-Platform-Requirements/` |
-| 4 | UX Design | Scenarios, sketches, specifications | `C-Scenarios/` |
-| 5 | Design System | Component library (optional, parallel) | `D-Design-System/` |
-| 6 | PRD & Design Deliveries | PRD + packaged flows for BMM handoff | `E-PRD/` |
-| 7 | Testing | Designer validation of implementation | `F-Testing/` |
-| 8 | Product Development | Ongoing improvements (existing products) | `G-Product-Development/` |
+| Phase | # | Name | Output Folder |
+| ----- | ----------------------- | ---------------------------------------- | -------------------------- |
+| 1 | Product Exploration | Product Brief | `A-Product-Brief/` |
+| 2 | Trigger Mapping | User psychology & business goals | `B-Trigger-Map/` |
+| 3 | PRD Platform | Technical foundation (platform only) | `C-Platform-Requirements/` |
+| 4 | UX Design | Scenarios, sketches, specifications | `C-Scenarios/` |
+| 5 | Design System | Component library (optional, parallel) | `D-Design-System/` |
+| 6 | PRD & Design Deliveries | PRD + packaged flows for BMM handoff | `E-PRD/` |
+| 7 | Testing | Designer validation of implementation | `F-Testing/` |
+| 8 | Product Development | Ongoing improvements (existing products) | `G-Product-Development/` |
### 5.4 E-PRD Structure (PRD + Design Deliveries)
**E-PRD/ contains both the PRD and Design Deliveries:**
**Phase 3: Platform Requirements (Technical Foundation)**
+
```
C-Platform-Requirements/
├── 00-Platform-Overview.md # Platform summary
@@ -281,9 +291,11 @@ C-Platform-Requirements/
├── 04-Security-Framework.md # Auth, authorization, data protection
└── 05-Technical-Constraints.md # What design needs to know
```
+
**Purpose:** Technical foundation created by WDS. Referenced by PRD but kept separate.
**Phase 6: E-PRD (PRD + Design Deliveries)**
+
```
E-PRD/
├── 00-PRD.md # Main PRD document
@@ -300,6 +312,7 @@ E-PRD/
```
**Each Design Delivery (DD-XXX.yaml) contains:**
+
- Flow metadata (name, epic, priority)
- Scenario references (which pages in C-Scenarios/)
- Component references (which components in D-Design-System/)
@@ -324,20 +337,24 @@ E-PRD/
**Reasoning:** User experience shows that harsh enforcement language makes agents MORE likely to ignore instructions, not less.
**Example - Before:**
+
```markdown
## MANDATORY RULES
+
- 🛑 NEVER generate without input
- 🚫 FORBIDDEN: Multiple questions
- ❌ SYSTEM FAILURE if you skip
```
**Example - After:**
+
```markdown
## How We Work Together
You're a thoughtful guide who helps designers create great products.
Your rhythm:
+
- Ask one question, then listen
- Reflect back what you heard
- Build the document together
@@ -352,6 +369,7 @@ Your rhythm:
**Reasoning:** People (and LLMs) learn better from examples than abstract rules.
**Implementation:**
+
- Complete artifacts as examples (not rule descriptions)
- Conversation flow examples
- Dog Week as reference implementation
@@ -359,23 +377,25 @@ Your rhythm:
#### Principle 3: Example Projects for Adoption
**Purpose:**
+
- Let people try before adopting
- Show what success looks like
- Lower barrier to entry
- Build credibility
**Implementation:**
+
- Dog Week patterns as full reference
- Starter project for practice
- Conversation examples showing dialog flow
### 6.2 Known Problems to Mitigate
-| Problem | Observed Behavior | WDS Solution |
-|---------|-------------------|--------------|
-| Agents ignore instructions | Generate without thinking | Identity-based personas + examples |
-| Inconsistent output formats | Specs look different each time | Complete template examples |
-| Question dumping | 20 questions at once | Conversation examples showing one-at-a-time |
+| Problem | Observed Behavior | WDS Solution |
+| --------------------------- | ------------------------------ | ------------------------------------------- |
+| Agents ignore instructions | Generate without thinking | Identity-based personas + examples |
+| Inconsistent output formats | Specs look different each time | Complete template examples |
+| Question dumping | 20 questions at once | Conversation examples showing one-at-a-time |
### 6.3 Positive Language Guidelines
@@ -383,21 +403,22 @@ Your rhythm:
**Patterns to Avoid:**
-| Negative Pattern | Positive Alternative |
-|------------------|---------------------|
-| "Nothing kills a project faster than..." | "It's valuable to discover early..." |
-| "expensive development problems" | "easy to address while solutions are flexible" |
-| "Finding them later is expensive" | "Finding them now means more options" |
-| "Don't do X" | "What works well is Y" |
-| "Avoid these mistakes" | "Successful patterns include..." |
-| "This prevents failure" | "This enables success" |
-| "You'll waste time if..." | "You'll save time by..." |
+| Negative Pattern | Positive Alternative |
+| ---------------------------------------- | ---------------------------------------------- |
+| "Nothing kills a project faster than..." | "It's valuable to discover early..." |
+| "expensive development problems" | "easy to address while solutions are flexible" |
+| "Finding them later is expensive" | "Finding them now means more options" |
+| "Don't do X" | "What works well is Y" |
+| "Avoid these mistakes" | "Successful patterns include..." |
+| "This prevents failure" | "This enables success" |
+| "You'll waste time if..." | "You'll save time by..." |
**The Reframe Test:**
-When writing guidance, ask: *"Am I describing what TO DO or what NOT to do?"*
+When writing guidance, ask: _"Am I describing what TO DO or what NOT to do?"_
Good WDS documentation:
+
- Celebrates early discovery (not fears late discovery)
- Describes successful patterns (not failure modes)
- Frames constraints as opportunities (not limitations)
@@ -406,29 +427,34 @@ Good WDS documentation:
**Example Transformation:**
Before:
+
> "Nothing kills a project faster than discovering in development that a core feature is technically impossible."
After:
+
> "It's a great morale boost when you've proven your core features will work. And if you discover limitations, it's valuable to know them early so design can account for them from the start."
### 6.4 Instruction Style
**Identity-First:**
+
```markdown
## Who You Are
-You're Saga, a thoughtful analyst who genuinely cares
+You're Saga, a thoughtful analyst who genuinely cares
about understanding the product before documenting it.
-You prefer deep conversations over quick surveys. You ask one
+You prefer deep conversations over quick surveys. You ask one
thing at a time because you're actually listening.
```
**Experience-Focused:**
+
```markdown
## The Conversation Style
A good session feels like coffee with a wise mentor:
+
- They ask something interesting
- You share your thinking
- They reflect it back
@@ -436,14 +462,17 @@ A good session feels like coffee with a wise mentor:
```
**Gentle Reminders:**
+
```markdown
## Helpful Patterns
What works well:
+
- One question at a time keeps things focused
- Reflecting back shows you're listening
What tends to feel less collaborative:
+
- Listing many questions (feels like a survey)
- Generating without checking in
```
@@ -455,46 +484,54 @@ What tends to feel less collaborative:
### Complete Phase Structure
**Phase 1: Product Exploration**
+
- **Output Folder:** `A-Product-Brief/`
- **Deliverable:** Product Brief with vision, positioning, ICP, success criteria
- **Agent:** Saga WDS Analyst
**Phase 2: Trigger Mapping**
+
- **Output Folder:** `B-Trigger-Map/`
- **Deliverable:** Trigger Map with business goals, personas, usage goals, Feature Impact Analysis
- **Agent:** Saga WDS Analyst
**Phase 3: PRD Platform**
+
- **Output Folder:** `C-Platform-Requirements/`
- **Deliverable:** Technical foundation (platform, architecture, data model, integrations, security)
- **Agent:** Freyja WDS PM
- **Note:** Runs in parallel with Phase 4
**Phase 4: UX Design**
+
- **Output Folder:** `C-Scenarios/`
- **Deliverable:** Interactive prototypes, scenarios, sketches, specifications with Object IDs
- **Agent:** Baldr WDS Designer
- **Note:** Runs in parallel with Phase 3
**Phase 5: Design System**
+
- **Output Folder:** `D-Design-System/`
- **Deliverable:** Component library (atoms, molecules, organisms) with design tokens
- **Agent:** Baldr WDS Designer
- **Note:** Optional, runs in parallel with Phase 4
**Phase 6: PRD & Design Deliveries**
+
- **Output Folder:** `E-PRD/`
- **Deliverable:** Complete PRD (00-PRD.md) + Design Deliveries (DD-XXX.yaml packages)
- **Agent:** Freyja WDS PM
- **Note:** PRD references C-Platform-Requirements/, organizes functional requirements by epic
**Phase 7: Testing**
+
- **Output Folder:** `F-Testing/`
- **Deliverable:** Test scenarios, validation results, issues
- **Agent:** Baldr WDS Designer
- **Note:** Designer validates BMM implementation
**Phase 8: Product Development**
+
- **Output Folder:** `G-Product-Development/`
- **Deliverable:** Ongoing improvements to existing products (Kaizen/Brownfield)
- **Agent:** Baldr WDS Designer
@@ -503,6 +540,7 @@ What tends to feel less collaborative:
### Key Methodology Features
**Feature Impact Analysis (Phase 2):**
+
- Scoring system for prioritizing features
- Positive drivers: +3/+2/+1 by priority
- Negative drivers: +4/+3/+2 (higher due to loss aversion)
@@ -510,18 +548,21 @@ What tends to feel less collaborative:
- Outputs ranked feature list for MVP planning
**Platform Requirements (Phase 3):**
+
- Technical foundation work (platform, infrastructure)
- Proofs of concept for risky features
- Experimental endpoints that can start before design
- Runs in parallel with design work (not sequential)
**Design System (Phase 5):**
+
- Optional - chosen during project setup
- Parallel - builds alongside Phase 4, not after
- Unified naming for Figma/Code integration
- Component library selection guidance
**PRD Structure (Phase 6):**
+
- E-PRD/ contains both PRD document and Design Deliveries subfolder
- PRD references C-Platform-Requirements/ (not duplicated)
- Design Deliveries (DD-XXX.yaml) package complete flows for BMM handoff
@@ -532,12 +573,14 @@ What tends to feel less collaborative:
### 7.1 Chosen Approach: Methodology-First
**Order:**
+
1. Define the methodology (phases, outputs, connections)
2. Create workflows that implement the methodology
3. Create agents that guide users through workflows
4. Create examples that demonstrate the methodology
**Reasoning:**
+
- The methodology IS the product
- Agents serve the methodology, not vice versa
- User is crystal clear on the workflow (already proven in WPS2C v4)
@@ -546,17 +589,19 @@ What tends to feel less collaborative:
### 7.2 Detailed Order
#### Phase 1: Define the Methodology
-| Order | Component | File | Status |
-|-------|-----------|------|--------|
-| 1 | Method Overview | `docs/method/wds-method-guide.md` | ✅ COMPLETE |
-| 2 | Phase 1 Guide | `docs/method/phase-1-Product-exploration-guide.md` | ✅ COMPLETE |
-| 3 | Phase 2 Guide | `docs/method/phase-2-trigger-mapping-guide.md` | ✅ COMPLETE |
-| 4 | Phase 3 Guide | `docs/method/phase-3-PRD-Platform-guide.md` | ✅ COMPLETE |
-| 5 | Phase 4 Guide | `docs/method/phase-4-ux-design-guide.md` | ✅ COMPLETE |
-| 6 | Phase 5 Guide | `docs/method/phase-5-design-system-guide.md` | ✅ COMPLETE |
-| 7 | Phase 6 Guide | `docs/method/phase-6-PRD-Finalization-guide.md` | ✅ COMPLETE |
+
+| Order | Component | File | Status |
+| ----- | --------------- | -------------------------------------------------- | ----------- |
+| 1 | Method Overview | `docs/method/wds-method-guide.md` | ✅ COMPLETE |
+| 2 | Phase 1 Guide | `docs/method/phase-1-Product-exploration-guide.md` | ✅ COMPLETE |
+| 3 | Phase 2 Guide | `docs/method/phase-2-trigger-mapping-guide.md` | ✅ COMPLETE |
+| 4 | Phase 3 Guide | `docs/method/phase-3-PRD-Platform-guide.md` | ✅ COMPLETE |
+| 5 | Phase 4 Guide | `docs/method/phase-4-ux-design-guide.md` | ✅ COMPLETE |
+| 6 | Phase 5 Guide | `docs/method/phase-5-design-system-guide.md` | ✅ COMPLETE |
+| 7 | Phase 6 Guide | `docs/method/phase-6-PRD-Finalization-guide.md` | ✅ COMPLETE |
**Methodology Phase Complete!** All phase guides refined with:
+
- Positive language throughout (no "expensive problems", "kills projects", etc.)
- Phase titles with artifacts in parentheses
- Removed duration estimates (project-dependent)
@@ -568,16 +613,18 @@ What tends to feel less collaborative:
- Code examples moved to templates/examples (not in guides)
#### Phase 2: Create Examples
-| Order | Component | Location | Status |
-|-------|-----------|----------|--------|
-| 8 | Dog Week Examples | `examples/dog-week-patterns/` | TO CREATE |
-| 9 | Conversation Examples | `examples/conversation-examples/` | TO CREATE |
-| 10 | Starter Project | `examples/starter-project/` | TO CREATE |
-| 10b | **WDS Trigger Map** | `examples/wds-trigger-map/` | TO CREATE |
-| 10c | **Trigger Mapping Workshop** | `workflows/trigger-mapping-workshop/` | TO CREATE |
+
+| Order | Component | Location | Status |
+| ----- | ---------------------------- | ------------------------------------- | --------- |
+| 8 | Dog Week Examples | `examples/dog-week-patterns/` | TO CREATE |
+| 9 | Conversation Examples | `examples/conversation-examples/` | TO CREATE |
+| 10 | Starter Project | `examples/starter-project/` | TO CREATE |
+| 10b | **WDS Trigger Map** | `examples/wds-trigger-map/` | TO CREATE |
+| 10c | **Trigger Mapping Workshop** | `workflows/trigger-mapping-workshop/` | TO CREATE |
**WDS Trigger Map Example:**
Create a Trigger Map for WDS itself as a meta-example - shows the methodology applied to the methodology. Includes:
+
- WDS Vision & SMART Objectives
- Target Groups (designers, teams, agencies)
- Personas with alliterative names
@@ -588,6 +635,7 @@ This serves as both documentation and inspiration for users.
**Trigger Mapping Workshop (Standalone):**
Create a standalone Trigger Mapping workshop that can be used:
+
- In WDS as part of Phase 2
- In BMM as a brainstorming/strategic alignment session
- In any project needing user-business alignment
@@ -595,37 +643,41 @@ Create a standalone Trigger Mapping workshop that can be used:
This makes the Trigger Mapping methodology available even in projects not driven by designers. Could be contributed to BMM's brainstorming workflows or CIS (Creative Intelligence Suite).
Includes:
+
- Workshop facilitation workflow
- Agent instructions for running the workshop
- Template for Trigger Map output
- Integration points with BMM workflows
#### Phase 3: Create Workflows
-| Order | Component | Location | Status |
-|-------|-----------|----------|--------|
-| 11 | workflow-init | `workflows/workflow-init/` | ✅ COMPLETE |
-| 12a | Phase 1 Workflow | `workflows/1-project-brief/` | ✅ COMPLETE |
-| 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/` | ✅ **COMPLETE (Dec 9)** |
-| 12f | **Phase 6 Workflow** | `workflows/6-design-deliveries/` | ✅ **COMPLETE** |
+
+| Order | Component | Location | Status |
+| ----- | -------------------- | -------------------------------- | ----------------------- |
+| 11 | workflow-init | `workflows/workflow-init/` | ✅ COMPLETE |
+| 12a | Phase 1 Workflow | `workflows/1-project-brief/` | ✅ COMPLETE |
+| 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/` | ✅ **COMPLETE (Dec 9)** |
+| 12f | **Phase 6 Workflow** | `workflows/6-design-deliveries/` | ✅ **COMPLETE** |
#### Phase 4: Create Agents (The Norse Pantheon)
-| Order | Component | File | Status |
-|-------|-----------|------|--------|
-| 13 | **Saga-Analyst** | `agents/saga-analyst.agent.yaml` | ✅ COMPLETE |
-| 13b | **Saga Presentation** | `data/presentations/saga-intro.md` | ✅ COMPLETE |
-| 14 | **Idunn-PM** | `agents/idunn-pm.agent.yaml` | ✅ COMPLETE |
-| 14b | **Idunn Presentation** | `data/presentations/idunn-intro.md` | ✅ COMPLETE |
-| 15 | **Freyja-Designer** | `agents/freyja-ux.agent.yaml` | ✅ COMPLETE |
-| 15b | **Freyja Presentation** | `data/presentations/freyja-intro.md` | ✅ COMPLETE |
+
+| Order | Component | File | Status |
+| ----- | ----------------------- | ------------------------------------ | ----------- |
+| 13 | **Saga-Analyst** | `agents/saga-analyst.agent.yaml` | ✅ COMPLETE |
+| 13b | **Saga Presentation** | `data/presentations/saga-intro.md` | ✅ COMPLETE |
+| 14 | **Idunn-PM** | `agents/idunn-pm.agent.yaml` | ✅ COMPLETE |
+| 14b | **Idunn Presentation** | `data/presentations/idunn-intro.md` | ✅ COMPLETE |
+| 15 | **Freyja-Designer** | `agents/freyja-ux.agent.yaml` | ✅ COMPLETE |
+| 15b | **Freyja Presentation** | `data/presentations/freyja-intro.md` | ✅ COMPLETE |
#### Phase 5: Finalize
-| Order | Component | File | Status |
-|-------|-----------|------|--------|
-| 16 | **Install Config** | `_module-installer/installer.js` | ✅ COMPLETE |
-| 17 | **Teams** | `teams/` | ✅ COMPLETE |
+
+| Order | Component | File | Status |
+| ----- | ------------------ | -------------------------------- | ----------- |
+| 16 | **Install Config** | `_module-installer/installer.js` | ✅ COMPLETE |
+| 17 | **Teams** | `teams/` | ✅ COMPLETE |
---
@@ -633,54 +685,54 @@ Includes:
### 8.1 Repository Root
-| File | Purpose | Status |
-|------|---------|--------|
-| `README.md` | Fork overview, WDS contribution explanation | ✅ CREATED |
-| `WDS-V6-CONVERSION-ROADMAP.md` | This document | ✅ CREATED |
+| File | Purpose | Status |
+| ------------------------------ | ------------------------------------------- | ---------- |
+| `README.md` | Fork overview, WDS contribution explanation | ✅ CREATED |
+| `WDS-V6-CONVERSION-ROADMAP.md` | This document | ✅ CREATED |
### 8.2 Methodology Documentation
-| Path | Purpose | Status |
-|------|---------|--------|
-| `src/modules/wds/docs/method/wds-method-guide.md` | Main methodology overview | ✅ COMPLETE |
-| `src/modules/wds/docs/method/phase-1-Product-exploration-guide.md` | Phase 1 guide | ✅ COMPLETE |
-| `src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md` | Phase 2 guide | ✅ COMPLETE |
-| `src/modules/wds/docs/method/phase-3-PRD-Platform-guide.md` | Phase 3 guide | ✅ COMPLETE |
-| `src/modules/wds/docs/method/phase-4-ux-design-guide.md` | Phase 4 guide | ✅ COMPLETE |
-| `src/modules/wds/docs/method/phase-5-design-system-guide.md` | Phase 5 guide | ✅ COMPLETE |
-| `src/modules/wds/docs/method/phase-6-PRD-Finalization-guide.md` | Phase 6 guide | ✅ COMPLETE |
+| Path | Purpose | Status |
+| ------------------------------------------------------------------ | ------------------------- | ----------- |
+| `src/modules/wds/docs/method/wds-method-guide.md` | Main methodology overview | ✅ COMPLETE |
+| `src/modules/wds/docs/method/phase-1-Product-exploration-guide.md` | Phase 1 guide | ✅ COMPLETE |
+| `src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md` | Phase 2 guide | ✅ COMPLETE |
+| `src/modules/wds/docs/method/phase-3-PRD-Platform-guide.md` | Phase 3 guide | ✅ COMPLETE |
+| `src/modules/wds/docs/method/phase-4-ux-design-guide.md` | Phase 4 guide | ✅ COMPLETE |
+| `src/modules/wds/docs/method/phase-5-design-system-guide.md` | Phase 5 guide | ✅ COMPLETE |
+| `src/modules/wds/docs/method/phase-6-PRD-Finalization-guide.md` | Phase 6 guide | ✅ COMPLETE |
### 8.3 Module Structure (Folders Created, Content Pending)
-| Path | Purpose | Status |
-|------|---------|--------|
-| `src/modules/wds/` | Module root | ✅ CREATED |
-| `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 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)** |
+| Path | Purpose | Status |
+| ------------------------------------------------------- | --------------------------------------- | ----------------------- |
+| `src/modules/wds/` | Module root | ✅ CREATED |
+| `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 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 |
-| `src/modules/wds/data/` | Data folder | EMPTY |
-| `src/modules/wds/data/presentations/` | Agent presentations | TO CREATE |
-| `src/modules/wds/docs/method/` | Methodology guides | ✅ COMPLETE |
-| `src/modules/wds/docs/images/` | Images folder | EMPTY |
-| `src/modules/wds/examples/` | Examples folder | EMPTY |
-| `src/modules/wds/examples/dog-week-patterns/` | Dog Week examples | TO CREATE |
-| `src/modules/wds/reference/` | Reference materials | EMPTY |
-| `src/modules/wds/reference/templates/` | Templates | TO CREATE |
-| `src/modules/wds/reference/checklists/` | Checklists | TO CREATE |
-| `src/modules/wds/teams/` | Team configs | EMPTY |
+| `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 |
+| `src/modules/wds/data/` | Data folder | EMPTY |
+| `src/modules/wds/data/presentations/` | Agent presentations | TO CREATE |
+| `src/modules/wds/docs/method/` | Methodology guides | ✅ COMPLETE |
+| `src/modules/wds/docs/images/` | Images folder | EMPTY |
+| `src/modules/wds/examples/` | Examples folder | EMPTY |
+| `src/modules/wds/examples/dog-week-patterns/` | Dog Week examples | TO CREATE |
+| `src/modules/wds/reference/` | Reference materials | EMPTY |
+| `src/modules/wds/reference/templates/` | Templates | TO CREATE |
+| `src/modules/wds/reference/checklists/` | Checklists | TO CREATE |
+| `src/modules/wds/teams/` | Team configs | EMPTY |
---
@@ -708,6 +760,7 @@ Includes:
### Commit Checkpoint
**Ready to commit Phase 4 workflow:**
+
```
feat(wds): Complete Phase 4 UX Design workflow with v6 best practices
@@ -740,11 +793,11 @@ Next: Phase 5 (Design System) and Phase 6 (PRD Finalization) workflows
**To resolve during porting Phase 1 & 2:**
-| Decision | Options | Resolve When |
-|----------|---------|--------------|
+| Decision | Options | Resolve When |
+| ----------------------------- | -------------------------------------------------------------- | ----------------- |
| **ICP/Positioning placement** | Phase 1 as hypothesis → Phase 2 validates, OR fully in Phase 2 | Porting Phase 1-2 |
-| **Prioritization Reasoning** | Formal step with output, OR internal thinking process | Porting Phase 2 |
-| **Business Goals flow** | Initial in Brief → Refined in Trigger Map, OR single location | Porting Phase 1-2 |
+| **Prioritization Reasoning** | Formal step with output, OR internal thinking process | Porting Phase 2 |
+| **Business Goals flow** | Initial in Brief → Refined in Trigger Map, OR single location | Porting Phase 1-2 |
**Context:** The Trigger Mapping (Effect Mapping) methodology is very strong. The prioritization reasoning step (column-by-column) is specifically valuable for generating product ideas but may not need formal documentation.
@@ -755,6 +808,7 @@ Next: Phase 5 (Design System) and Phase 6 (PRD Finalization) workflows
To be included in WDS workflows (stored in memory, ID: 11785915):
**Positioning Statement Format:**
+
```
For (target customer)
Who (statement of need or opportunity)
@@ -767,6 +821,7 @@ Our product (statement of primary differentiators)
```
**ICP Framework (8 Components):**
+
1. My ICP (Who I Serve Best)
2. My Positioning (How I'm Different)
3. The Outcomes I Drive
@@ -777,6 +832,7 @@ Our product (statement of primary differentiators)
8. Pricing Anchoring (Cost of Inaction, Bad Hire, % Revenue, Speed)
**CTA Elements:**
+
- Website link
- Discovery call link
- Newsletter subscription
@@ -785,31 +841,31 @@ Our product (statement of primary differentiators)
### 10.2 BMad v6 Resources
-| Resource | Location |
-|----------|----------|
-| BMM Module | `src/modules/bmm/` |
-| BMB Builder | `src/modules/bmb/` |
-| CIS Module | `src/modules/cis/` |
-| Agent Schema | `src/modules/bmb/docs/agents/` |
+| Resource | Location |
+| ------------- | --------------------------------- |
+| BMM Module | `src/modules/bmm/` |
+| BMB Builder | `src/modules/bmb/` |
+| CIS Module | `src/modules/cis/` |
+| Agent Schema | `src/modules/bmb/docs/agents/` |
| Workflow Docs | `src/modules/bmb/docs/workflows/` |
### 10.3 Original WPS2C
-| Resource | Location |
-|----------|----------|
-| WPS2C Repo | `C:\dev\whiteport-sketch-to-code-bmad-expansion` |
-| Method Overview | `Method/00-Whiteport-Method.md` |
-| Agents (v4 format) | `bmad-whiteport-sketch/agents/` |
+| Resource | Location |
+| ------------------ | ------------------------------------------------ |
+| WPS2C Repo | `C:\dev\whiteport-sketch-to-code-bmad-expansion` |
+| Method Overview | `Method/00-Whiteport-Method.md` |
+| Agents (v4 format) | `bmad-whiteport-sketch/agents/` |
### 10.4 Dog Week Project
-| Resource | Location |
-|----------|----------|
-| Project Root | `C:\dev\dogweek\dogweek-dev` |
-| Product Brief | `docs/A-Product-Brief/` |
-| Trigger Map | `docs/B-Trigger-Map/` |
-| Scenarios | `docs/C-Scenarios/` |
-| PRD | `docs/D-PRD/` |
+| Resource | Location |
+| ------------- | ---------------------------- |
+| Project Root | `C:\dev\dogweek\dogweek-dev` |
+| Product Brief | `docs/A-Product-Brief/` |
+| Trigger Map | `docs/B-Trigger-Map/` |
+| Scenarios | `docs/C-Scenarios/` |
+| PRD | `docs/D-PRD/` |
---
@@ -851,32 +907,37 @@ Our product (statement of primary differentiators)
### 11.1 Agent Mapping
-| WPS2C v4 | WDS v6 | Status |
-|----------|--------|--------|
-| Mary (whiteport-analyst.md) | Saga-Analyst (saga-analyst.agent.yaml) | ✅ COMPLETE |
-| Sarah (whiteport-pm.md) | Idunn-PM (idunn-pm.agent.yaml) | ✅ COMPLETE |
-| Sally (whiteport-ux-expert.md) | Freyja-Designer (freyja-ux.agent.yaml) | ✅ COMPLETE |
-| James (whiteport-dev.md) | N/A - moved to BMM | ✅ Complete |
-| Alex (whiteport-orchestrator.md) | N/A - workflow-status replaces | ✅ Complete |
+| WPS2C v4 | WDS v6 | Status |
+| -------------------------------- | -------------------------------------- | ----------- |
+| Mary (whiteport-analyst.md) | Saga-Analyst (saga-analyst.agent.yaml) | ✅ COMPLETE |
+| Sarah (whiteport-pm.md) | Idunn-PM (idunn-pm.agent.yaml) | ✅ COMPLETE |
+| Sally (whiteport-ux-expert.md) | Freyja-Designer (freyja-ux.agent.yaml) | ✅ COMPLETE |
+| James (whiteport-dev.md) | N/A - moved to BMM | ✅ Complete |
+| Alex (whiteport-orchestrator.md) | N/A - workflow-status replaces | ✅ Complete |
**Key Changes:**
+
- Mary → **Saga** (Goddess of stories & wisdom)
-- Sarah → **Idunn** (Goddess of renewal & youth)
+- Sarah → **Idunn** (Goddess of renewal & youth)
- Sally → **Freyja** (Goddess of beauty, magic & strategy)
- Norse Pantheon theme for unique WDS identity
### 11.2 File Format Changes
**WPS2C v4:** Markdown files (.md) with embedded YAML blocks
-```markdown
+
+````markdown
# agent-name.md
+
```yaml
agent:
name: Mary
commands:
- help: Show help
```
-```
+````
+
+````
**WDS v6:** Pure YAML files (.agent.yaml) following v6 schema
```yaml
@@ -892,74 +953,78 @@ agent:
menu:
- trigger: command-name
workflow: path/to/workflow.yaml
-```
+````
### 11.3 Terminology Changes
-| WPS2C v4 | WDS v6 |
-|----------|--------|
+| WPS2C v4 | WDS v6 |
+| ------------------------ | ----------------------- |
| Whiteport Sketch-to-Code | Whiteport Design Studio |
-| WPS2C | WDS |
-| Commands | Menu Triggers |
-| Tasks | Workflows |
-| `*command-name` | Workflow triggers |
+| WPS2C | WDS |
+| Commands | Menu Triggers |
+| Tasks | Workflows |
+| `*command-name` | Workflow triggers |
### 11.4 Presentation Files Mapping
-| WPS2C v4 File | WDS v6 Location | Purpose |
-|---------------|-----------------|---------|
-| mary-analyst-personal-presentation.md | data/presentations/saga-intro.md | Saga activation speech |
-| sarah-pm-personal-presentation.md | data/presentations/freyja-intro.md | Freyja activation speech |
-| sally-ux-expert-personal-presentation.md | data/presentations/baldr-intro.md | Baldr activation speech |
-| wps2c-analyst-business-presentation.md | examples/conversation-examples/analyst-session.md | Example session |
-| wps2c-pm-product-presentation.md | examples/conversation-examples/pm-session.md | Example session |
-| wps2c-ux-design-system-presentation.md | examples/conversation-examples/ux-session.md | Example session |
+| WPS2C v4 File | WDS v6 Location | Purpose |
+| ---------------------------------------- | ------------------------------------------------- | ------------------------ |
+| mary-analyst-personal-presentation.md | data/presentations/saga-intro.md | Saga activation speech |
+| sarah-pm-personal-presentation.md | data/presentations/freyja-intro.md | Freyja activation speech |
+| sally-ux-expert-personal-presentation.md | data/presentations/baldr-intro.md | Baldr activation speech |
+| wps2c-analyst-business-presentation.md | examples/conversation-examples/analyst-session.md | Example session |
+| wps2c-pm-product-presentation.md | examples/conversation-examples/pm-session.md | Example session |
+| wps2c-ux-design-system-presentation.md | examples/conversation-examples/ux-session.md | Example session |
### 11.5 Templates Mapping
-| WPS2C v4 Template | WDS v6 Location | Status |
-|-------------------|-----------------|--------|
-| product-brief-tmpl.yaml | workflows/1-project-brief/complete/project-brief.template.md | ✅ Created |
-| trigger-map-tmpl.yaml | workflows/2-trigger-mapping/templates/trigger-map.template.md | ✅ Created |
-| persona-tmpl.yaml | workflows/2-trigger-mapping/templates/persona.template.md | ⏳ To create |
-| scenarios-tmpl.yaml | workflows/4-ux-design/templates/scenario-overview.template.md | ✅ **Created Dec 4** |
-| page-spec-tmpl.yaml | workflows/4-ux-design/templates/page-specification.template.md | ✅ **Created Dec 4** |
-| design-system-structure-tmpl.yaml | workflows/5-design-system/templates/component.template.md | ⏳ To create |
-| component-tmpl.yaml | reference/templates/component.template.md | ⏳ To create |
-| sketch-review-tmpl.yaml | workflows/4-ux-design/templates/review.template.md | ⏳ To create |
+| WPS2C v4 Template | WDS v6 Location | Status |
+| --------------------------------- | -------------------------------------------------------------- | -------------------- |
+| product-brief-tmpl.yaml | workflows/1-project-brief/complete/project-brief.template.md | ✅ Created |
+| trigger-map-tmpl.yaml | workflows/2-trigger-mapping/templates/trigger-map.template.md | ✅ Created |
+| persona-tmpl.yaml | workflows/2-trigger-mapping/templates/persona.template.md | ⏳ To create |
+| scenarios-tmpl.yaml | workflows/4-ux-design/templates/scenario-overview.template.md | ✅ **Created Dec 4** |
+| page-spec-tmpl.yaml | workflows/4-ux-design/templates/page-specification.template.md | ✅ **Created Dec 4** |
+| design-system-structure-tmpl.yaml | workflows/5-design-system/templates/component.template.md | ⏳ To create |
+| component-tmpl.yaml | reference/templates/component.template.md | ⏳ To create |
+| sketch-review-tmpl.yaml | workflows/4-ux-design/templates/review.template.md | ⏳ To create |
### 11.6 Standards/Data Files Mapping
-| WPS2C v4 File | WDS v6 Location | Purpose |
-|---------------|-----------------|---------|
-| wps2c-compliance-standards.md | data/wds-standards.md | Core methodology standards |
-| analyst-documentation-standards.md | data/documentation-standards.md | Documentation conventions |
-| sketch-documentation-standards.md | workflows/4-ux-design/sketch-standards.md | Sketch specification standards |
-| pm-documentation-standards.md | workflows/3-prd-platform/prd-standards.md | PRD writing standards |
-| mermaid-github-standards.md | data/mermaid-standards.md | Diagram standards |
-| technical-documentation-patterns.md | data/technical-patterns.md | Technical writing patterns |
+| WPS2C v4 File | WDS v6 Location | Purpose |
+| ----------------------------------- | ----------------------------------------- | ------------------------------ |
+| wps2c-compliance-standards.md | data/wds-standards.md | Core methodology standards |
+| analyst-documentation-standards.md | data/documentation-standards.md | Documentation conventions |
+| sketch-documentation-standards.md | workflows/4-ux-design/sketch-standards.md | Sketch specification standards |
+| pm-documentation-standards.md | workflows/3-prd-platform/prd-standards.md | PRD writing standards |
+| mermaid-github-standards.md | data/mermaid-standards.md | Diagram standards |
+| technical-documentation-patterns.md | data/technical-patterns.md | Technical writing patterns |
### 11.7 Content to Preserve from WPS2C
**Core Methodology Elements:** ✅
+
- Product Brief structure and process
- Trigger Mapping (Effect Mapping) methodology
- Feature Impact Analysis with scoring
-- Scenario-driven design approach
+- Scenario-driven design approach
- Design System integration patterns
**Agent Personalities:** 🔄
+
- Mary's analytical, thoughtful approach → Saga
- Sarah's strategic PM mindset → Freyja
- Sally's design expertise and creativity → Baldr
**Quality Patterns:** ✅
+
- One question at a time (not survey-style)
- Collaborative document building
- Evidence-based analysis
- Soft, encouraging language
**Technical Patterns:** ✅
+
- A-B-C-D-E folder structure
- Title-Case-With-Dashes naming
- Professional markdown formatting
@@ -968,30 +1033,35 @@ agent:
### 11.8 Key Improvements in WDS v6
**1. Soft Language Design Philosophy**
+
- Removed MUST/FORBIDDEN/NEVER language
- Identity-based persona definitions
- Collaborative, not interrogative approach
- Positive framing (enables vs prevents)
**2. Example-Driven Learning**
+
- Complete reference implementations
- Conversation flow examples
- Real project patterns (Dog Week)
- Starter projects for practice
**3. Phase Flexibility**
+
- Phase-selectable (not rigid tracks)
- Path presets for common scenarios
- Optional phases (Design System)
- Parallel workflows supported
**4. Better Integration**
+
- Clean handoff to BMM via E-UI-Roadmap
- No development artifacts in design module
- Clear separation of concerns
- Continuous handoff model
**5. Professional Tooling**
+
- Proper v6 YAML schema compliance
- Workflow validation support
- Installation via BMad CLI
@@ -1000,18 +1070,21 @@ agent:
### 11.9 Migration Notes
**Breaking Changes:**
-- Agent activation syntax changes (*command → workflow trigger)
+
+- Agent activation syntax changes (\*command → workflow trigger)
- File format changes (.md → .agent.yaml)
- Folder structure reorganization
- Terminology updates throughout
**Backward Compatibility:**
+
- WPS2C v4 users must migrate to WDS v6
- No automatic migration path
- Dog Week project uses mixed terminology (in transition)
- Old repo remains for reference
**User Communication:**
+
- WDS is evolution, not replacement
- Same methodology, better implementation
- Migration guide needed for v4 users
@@ -1026,6 +1099,7 @@ agent:
#### Phase 4 Architecture (December 4)
**Step-File Architecture:**
+
- `workflows/4-ux-design/workflow.yaml` - Main workflow configuration
- `workflows/4-ux-design/workflow.md` - Workflow orchestrator
- `workflows/4-ux-design/steps/step-01-init.md` - Workflow initialization
@@ -1035,6 +1109,7 @@ agent:
- `workflows/4-ux-design/steps/step-05-next-steps.md` - Next actions
**4C Micro-Steps (Specification Breakdown):**
+
- `substeps/4c-01-page-basics.md` - Page basic information
- `substeps/4c-02-layout-sections.md` - Layout sections definition
- `substeps/4c-03-components-objects.md` - Components & objects identification
@@ -1047,6 +1122,7 @@ agent:
#### Dog Week Pattern Implementation (December 5)
**Purpose-Based Text Organization:**
+
- `object-types/heading-text.md` - Updated with purpose-based naming
- `object-types/object-router.md` - Enhanced with intelligent interpretation
- Text objects named by FUNCTION, not content (e.g., `start-hero-headline` not `welcome-text`)
@@ -1054,6 +1130,7 @@ agent:
- Translations grouped so each language reads coherently
**Sketch Text Analysis:**
+
- Horizontal line detection → text placeholders
- Line thickness → font size estimation
- Line spacing → line-height calculation
@@ -1061,6 +1138,7 @@ agent:
- `SKETCH-TEXT-ANALYSIS-GUIDE.md` - Complete analysis methodology
**Translation Grouping:**
+
- Text groups keep languages together
- Each language reads as complete, coherent message
- Dog Week format standardized across all projects
@@ -1068,6 +1146,7 @@ agent:
- `DOG-WEEK-SPECIFICATION-PATTERN.md` - Full workflow integration example
**Object Type Instructions:**
+
- `object-types/button.md` - Button documentation
- `object-types/text-input.md` - Text input fields
- `object-types/link.md` - Link elements
@@ -1076,6 +1155,7 @@ agent:
- `object-types/object-router.md` - Intelligent object detection & routing
**Design Principles Applied:**
+
- ✅ Goal-based trust-the-agent approach
- ✅ Concise instructions (vs. long procedural lists)
- ✅ Soft, collaborative language throughout
@@ -1087,18 +1167,21 @@ agent:
- ✅ Character capacity validation from sketches
**Key Innovations:**
+
1. **Purpose-Based Object IDs** - IDs reflect function, remain stable when content changes
2. **Grouped Translations** - Each language reads coherently as a group
3. **Sketch Text Analysis** - Automatic capacity estimation from visual markers
4. **Intelligent Routing** - Agent suggests object types rather than asking lists
**Architecture Documentation:**
+
- `workflows/4-ux-design/ARCHITECTURE.md` - Complete Phase 4 architecture
- `workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md` - Text analysis methodology
- `workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md` - Translation patterns
- `workflows/4-ux-design/DOG-WEEK-SPECIFICATION-PATTERN.md` - Complete workflow example
**Next Actions:**
+
- Create Phase 5 workflow (Design System)
- Create Phase 6 workflow (PRD Finalization / Dev Integration)
- Complete agent definitions (Freyja, Baldr)
@@ -1108,19 +1191,22 @@ agent:
#### Language Configuration (December 5 - Later)
**Multi-Language Support:**
+
- `workflows/workflow-init/instructions.md` - Updated with language configuration (Step 4)
- `workflows/wds-workflow-status-template.yaml` - Added language fields to config
- `workflows/LANGUAGE-CONFIGURATION-GUIDE.md` - Complete multi-language guide
- `workflows/LANGUAGE-FLOW-DIAGRAM.md` - Step-by-step language flow
**Configuration Settings:**
+
1. **Specification Language** - Language to write design specs in (EN, SE, etc.)
2. **Product Languages** - Array of languages the product supports
**Storage:**
+
```yaml
config:
- specification_language: "EN"
+ specification_language: 'EN'
product_languages:
- EN
- SE
@@ -1128,17 +1214,20 @@ config:
```
**Impact on Workflows:**
+
- Specs written in `specification_language`
- All text objects include translations for ALL `product_languages`
- Agents automatically request content for each configured language
- Complete translation coverage from day one
**Example (Dog Week):**
+
- Specification Language: EN (specs written in English)
- Product Languages: [EN, SE] (product supports English & Swedish)
- Result: All text objects have both EN and SE content
**Benefits:**
+
- ✅ Flexible spec language separate from product languages
- ✅ All translations grouped and coherent
- ✅ No missing translations
@@ -1148,11 +1237,13 @@ config:
#### Sketch Text Analysis Corrections (December 5 - Final)
**Corrected Understanding:**
+
- **Line thickness** → **font weight** (bold/regular), NOT font size!
- **Distance between lines** → **font size**
- **Confusion risk:** Large spacing (>60px) might be image/colored box, not text
**Updated Files:**
+
- `4-ux-design/object-types/heading-text.md` - Corrected analysis logic
- `4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md` - Updated with correct interpretation
- `4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md` - Quick reference card
@@ -1161,17 +1252,20 @@ config:
**Best Practice - Actual Text vs. Markers:**
**Use ACTUAL TEXT for:**
+
- Headlines (provides content guidance)
- Button labels (shows intended action)
- Navigation items (clarifies structure)
- Short, important text
**Use LINE MARKERS for:**
+
- Body paragraphs (content TBD)
- Long descriptions (sizing only)
- Placeholder content
**Agent Behavior:**
+
- Reads actual text from sketch as starting suggestion
- **Proactively suggests translations for all configured languages**
- Allows refinement during specification
@@ -1179,6 +1273,7 @@ config:
- Analyzes markers for font size, weight, capacity
**Example:**
+
```
Every walk. on time. ← Agent reads this
Every time. ← Translates to all languages
@@ -1190,6 +1285,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
```
**User can:**
+
- Accept suggestions (fast!)
- Refine specific translations
- Provide manual input if preferred
@@ -1205,6 +1301,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
**Location:** `src/modules/wds/course/`
**Format:**
+
- Read as documentation
- Generate videos/podcasts with NotebookLM
- Use in workshops and team training
@@ -1212,6 +1309,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
**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
@@ -1222,21 +1320,26 @@ Each module contains:
**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
@@ -1245,10 +1348,12 @@ Each module contains:
- 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 ✅
@@ -1257,15 +1362,16 @@ Each module contains:
**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 |
+| 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
@@ -1275,6 +1381,7 @@ Each module contains:
**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)
@@ -1284,6 +1391,7 @@ Each module contains:
- 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
@@ -1295,14 +1403,15 @@ Each module contains:
**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 |
+| 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
@@ -1314,11 +1423,13 @@ Each module contains:
**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)
@@ -1327,6 +1438,7 @@ Each module contains:
- ✅ 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
@@ -1335,12 +1447,14 @@ Each module contains:
- 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
@@ -1354,6 +1468,7 @@ Each module contains:
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
@@ -1371,12 +1486,14 @@ Create Module 02: Project Brief as template for remaining modules
- 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
@@ -1387,6 +1504,7 @@ module-XX-name/
```
**Estimated Scope:**
+
- 15 modules remaining (Module 02-16)
- Each module: 4 files minimum
- Total: ~60 files to create
@@ -1402,6 +1520,7 @@ Wait until conversion is complete, then tackle course development systematically
### December 9, 2025 - Course Development Session
**Completed:**
+
- ✅ Getting Started section (5 files)
- ✅ Course Overview refinement
- ✅ Module 01: Why WDS Matters (4 files)
@@ -1410,6 +1529,7 @@ Wait until conversion is complete, then tackle course development systematically
- ✅ Merged overlapping content
**Key Refinements:**
+
- Honest about IDE/GitHub learning curve
- Transparent about costs ($15-80/month)
- Focus on strategic value, not speed
@@ -1418,6 +1538,7 @@ Wait until conversion is complete, then tackle course development systematically
- Removed speed claims
**Files Structure:**
+
```
course/
├── 00-course-overview.md ✅ COMPLETE
@@ -1435,6 +1556,7 @@ course/
```
**Next Session:**
+
- Continue with Module 02-16 creation
- Use Module 01 as template
- Consider prioritizing Quick Start modules first
@@ -1471,6 +1593,7 @@ course/
```
**Key Separation:**
+
- **Specification = Content** (what the component is)
- **Organization = Structure** (where it lives)
- **Design System = Optional** (chosen in Phase 1)
@@ -1480,16 +1603,19 @@ course/
**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
@@ -1522,35 +1648,38 @@ course/
**Example:**
**Complete Specification:**
+
```yaml
Login Button:
why: Submit login credentials
- label: "Log in" # Page-specific
- error_text: "Invalid credentials" # Page-specific
+ 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
+ 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: {...}
+ styling: { ... }
```
**Page Spec:**
+
```yaml
# C-Scenarios/login-page.md
Login Button:
- component: Button.primary [btn-001] # Reference
+ component: Button.primary [btn-001] # Reference
why: Submit login credentials
- label: "Log in"
- error_text: "Invalid credentials"
+ label: 'Log in'
+ error_text: 'Invalid credentials'
```
### 15.4 Design System Router
@@ -1578,6 +1707,7 @@ Design System Router
```
**Router Characteristics:**
+
- Dumb and simple (just identify and route)
- Doesn't contain business logic
- Keeps orchestration clean
@@ -1599,6 +1729,7 @@ workflows/5-design-system/assessment/
```
**Example Conversation:**
+
```
Agent: "I found a button similar to btn-001 (Primary Button).
@@ -1663,6 +1794,7 @@ Component-Type Instructions (Specific)
```
**Benefits:**
+
- Small, digestible instruction files
- Shared knowledge in one place
- Selective loading (only what's needed)
@@ -1672,10 +1804,12 @@ Component-Type Instructions (Specific)
**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.
@@ -1687,12 +1821,14 @@ 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
@@ -1725,6 +1861,7 @@ Company forks WDS
**Use Cases:**
**1. Enterprise with Design System**
+
```
Acme Corp forks WDS:
├── Adds: data/design-system/acme-tokens.md
@@ -1735,6 +1872,7 @@ Result: Every project uses Acme standards automatically
```
**2. Agency with Multiple Clients**
+
```
Agency forks WDS:
├── Branch: client-a (Client A standards)
@@ -1745,6 +1883,7 @@ Result: Switch branch = switch standards
```
**3. Design System Team**
+
```
Design System Team forks WDS:
├── Adds: Their component library specs
@@ -1755,6 +1894,7 @@ Result: All designers use same system
```
**Benefits:**
+
- ✅ Company-specific standards
- ✅ Version controlled
- ✅ Shareable across teams
@@ -1793,6 +1933,7 @@ workflows/5-design-system/
```
**Integration Points:**
+
- Called from Phase 4 orchestration (4c-03-components-objects.md)
- Triggered after component specification
- Only active if design system enabled in project
@@ -1801,30 +1942,37 @@ workflows/5-design-system/
### 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
@@ -1837,11 +1985,13 @@ workflows/5-design-system/
**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`
@@ -1851,12 +2001,14 @@ workflows/5-design-system/
- `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`
@@ -1864,16 +2016,19 @@ workflows/5-design-system/
- `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
@@ -1886,15 +2041,18 @@ workflows/5-design-system/
- ✅ **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
@@ -1906,24 +2064,28 @@ workflows/5-design-system/
- **Version controlled** with git
**Course Structure Update (Dec 9):**
+
- Tutorials integrated into course modules (no separate tutorial/ folder)
- Created tutorials for key modules: 02, 04, 08, 12
- Updated navigation (where-to-go-next.md, course-overview.md)
- Deprecated old tutorial/ folder with migration guide
**Tutorial Files Created:**
+
- `course/module-02-project-brief/tutorial-02.md` - Create Project Brief
- `course/module-04-map-triggers-outcomes/tutorial-04.md` - Map Triggers & Outcomes
- `course/module-08-initialize-scenario/tutorial-08.md` - Initialize Scenario
- `course/module-12-why-based-specs/tutorial-12.md` - Why-Based Specifications
**Excalidraw Integration (Dec 9 AM):**
+
- Optional sketching tool integration with project configuration
- Created comprehensive documentation and workflows
- AI collaboration patterns for generation and analysis
- Export workflows for GitHub display
**Excalidraw Files Created:**
+
- `workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md` - Overview and quick start
- `workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md` - Installation and configuration
- `workflows/4-ux-design/excalidraw-integration/sketching-guide.md` - How to sketch effectively
@@ -1933,6 +2095,7 @@ workflows/5-design-system/
- `workflows/workflow-init/excalidraw-setup-prompt.md` - Agent setup instructions
**Excalidraw Features:**
+
- ✅ Optional (enable in project config)
- ✅ VS Code extension or web app
- ✅ AI can generate .excalidraw files
@@ -1943,6 +2106,7 @@ workflows/5-design-system/
- ✅ Version control friendly (JSON)
**WDS ↔ BMad Integration (Dec 9 PM):**
+
- Designed complete integration architecture between WDS and BMad Method
- Simplified to 3 clean touch points (not 7!)
- Created Design Delivery objects for clean handoff
@@ -1951,6 +2115,7 @@ workflows/5-design-system/
- Phase 6 renamed to "Design Deliveries" (single handoff point)
**Integration Files Created:**
+
- `src/core/resources/wds/design-delivery-spec.md` - Design Delivery specification
- `src/core/resources/wds/platform-requirements-spec.md` - Platform Requirements specification
- `src/core/resources/wds/handoff-protocol.md` - Multi-agent handoff protocol
@@ -1960,21 +2125,21 @@ workflows/5-design-system/
- `templates/test-scenario.template.yaml` - Test Scenario template
**The 3 Touch Points:**
+
1. **Platform Requirements** (WDS Phase 3 → BMad)
- WDS overrides BMad's tech stack decisions
- Designer defines technical foundation
-
2. **Design Deliveries** (WDS Phase 6 → BMad)
- Complete design package handed off at once
- Includes all scenarios, components, test scenarios
- Single handoff with multi-agent dialog
-
3. **Designer Validation** (BMad Phase 3 → WDS Phase 7)
- BMad requests validation when complete
- Designer tests and creates issues if needed
- Iterates until sign-off
**Integration Features:**
+
- ✅ 3 clean touch points (simplified from 7)
- ✅ Epic-based design deliveries (testable user flows)
- ✅ Multi-agent handoff dialog (20-30 min structured conversation)
@@ -1985,17 +2150,18 @@ workflows/5-design-system/
- ✅ Complete traceability (design → dev → test → ship)
**WDS Workflow Files Created (Dec 9):**
+
- `workflows/6-design-deliveries/design-deliveries-guide.md` - Phase 6 workflow (iterative handoffs)
- `workflows/7-testing/testing-guide.md` - Phase 7 workflow (designer validation)
- `workflows/8-ongoing-development/existing-product-guide.md` - Phase 8 workflow (existing product entry point)
- `workflows/workflow-init/project-type-selection.md` - Project type selection (new vs existing)
**Two Entry Points to WDS:**
+
1. **New Product** (Phases 1-7)
- Starting from scratch
- Complete user flows
- Full creative freedom
-
2. **Existing Product** (Phase 8)
- Jump into existing product
- Strategic improvements
@@ -2003,6 +2169,7 @@ workflows/5-design-system/
- Linchpin designer role
**Complete WDS Workflow (Phases 1-8):**
+
- ✅ Phase 1: Project Brief (New Product)
- ✅ Phase 2: Trigger Map (New Product)
- ✅ Phase 3: Platform Requirements (Touch Point 1) (New Product)
@@ -2018,6 +2185,7 @@ workflows/5-design-system/
- Phase 8.5: Validation
**BMad Integration Complete (Dec 9):**
+
- ✅ Created WDS detection step for BMad architecture workflow
- ✅ Updated BMad Architect agent (WDS-aware)
- ✅ Updated BMad Developer agent (design system awareness)
@@ -2026,6 +2194,7 @@ workflows/5-design-system/
- ✅ BMad offers handoff dialog when Design Deliveries exist
**BMad Files Updated:**
+
- `src/modules/bmm/workflows/3-solutioning/architecture/steps/step-01a-wds-detection.md` - WDS detection step
- `src/modules/bmm/workflows/3-solutioning/architecture/steps/step-01-init.md` - Updated to call WDS detection
- `src/modules/bmm/agents/architect.agent.yaml` - Added WDS awareness
@@ -2034,16 +2203,19 @@ workflows/5-design-system/
**Next Steps:**
### Immediate (This Week)
+
1. ✅ Complete DD-XXX migration in Phase 8 step files (7 files) - DONE
2. Test Phase 6/7/8 workflows with real project
3. Create commit for Dec 9 session work
### Short-term (Next Week)
+
1. Complete remaining module tutorials (03, 05-07, 09-11, 13-16)
2. Create WDS Excalidraw component library (.excalidrawlib)
3. Test complete WDS → BMad workflow end-to-end
### Long-term (This Month)
+
1. Implement auto-export automation (GitHub Actions)
2. Refine assessment criteria based on usage
3. Test Figma MCP integration with real components
@@ -2063,6 +2235,7 @@ workflows/5-design-system/
**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
@@ -2070,6 +2243,7 @@ workflows/5-design-system/
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)
@@ -2077,6 +2251,7 @@ workflows/5-design-system/
- Create component references in page specs
**Benefits:**
+
- ✅ Validates WDS Phase 5 on production system
- ✅ Improves Dogweek maintainability
- ✅ Creates migration guide for other projects
@@ -2094,6 +2269,7 @@ workflows/5-design-system/
### What Was Created
**1. Saga-Analyst Agent** (`saga-analyst.agent.yaml`)
+
- ✅ Merged WPS2C Mary's capabilities with BMM analyst features
- ✅ Follows BMad v6 YAML schema
- ✅ Implements WDS design philosophy (soft language, identity-based)
@@ -2102,6 +2278,7 @@ workflows/5-design-system/
- ✅ Full menu integration with WDS workflows
**2. Saga Introduction Presentation** (`saga-intro.md`)
+
- ✅ Complete agent introduction speech
- ✅ Strategic foundation explanation with detailed folder structure
- ✅ Team integration details (Freyja, Baldr, BMM)
@@ -2112,6 +2289,7 @@ workflows/5-design-system/
### Agent Capabilities Merged
**From WPS2C Mary:**
+
- Strategic foundation building (Product Brief, Trigger Map)
- Market intelligence and competitive analysis
- Alliterative persona naming convention
@@ -2120,6 +2298,7 @@ workflows/5-design-system/
- WDS folder structure expertise
**From BMM Analyst:**
+
- Requirements elicitation expertise
- Project documentation capabilities
- Research workflow integration
@@ -2128,6 +2307,7 @@ workflows/5-design-system/
- Project context file awareness (`**/project-context.md`)
**WDS-Specific Enhancements:**
+
- Norse mythology identity (Saga the Analyst → Saga WDS Analyst)
- Soft, collaborative language throughout
- Working rhythm guidance (ask → listen → reflect → discover → structure)
@@ -2138,26 +2318,29 @@ workflows/5-design-system/
### Persona Highlights
**Identity:**
+
```yaml
-I'm Saga, the goddess of stories and wisdom. I help you discover and articulate
-your product's strategic narrative - transforming vague ideas into clear,
+I'm Saga, the goddess of stories and wisdom. I help you discover and articulate
+your product's strategic narrative - transforming vague ideas into clear,
actionable foundations.
-I treat analysis like a treasure hunt - excited by every clue, thrilled when
+I treat analysis like a treasure hunt - excited by every clue, thrilled when
patterns emerge.
```
**Communication Style:**
+
```yaml
I ask questions that spark 'aha!' moments while structuring insights with precision.
-My approach is collaborative - we build documents together, not through interrogation.
+My approach is collaborative - we build documents together, not through interrogation.
I ask one question at a time and listen deeply to your answer.
Analysis should feel like coffee with a wise mentor, not a survey or audit.
```
**Working Rhythm:**
+
```yaml
When we work together:
1. I ask something interesting
@@ -2170,32 +2353,31 @@ When we work together:
### Menu Structure
**Primary WDS Workflows:**
+
1. `workflow-status` - Initialize or check WDS project status (entry point)
2. `project-brief` - Phase 1: Product Exploration (Product Brief)
3. `trigger-mapping` - Phase 2: Trigger Mapping (User Psychology)
-**Supporting Workflows:**
-4. `brainstorm-project` - Guided brainstorming for vision exploration
-5. `research` - Market, domain, competitive, or technical research
-6. `document-project` - Document existing brownfield projects
+**Supporting Workflows:** 4. `brainstorm-project` - Guided brainstorming for vision exploration 5. `research` - Market, domain, competitive, or technical research 6. `document-project` - Document existing brownfield projects
-**Collaboration Features:**
-7. `party-mode` - Multi-agent collaboration
-8. `expert-chat` - Direct conversation with Saga
+**Collaboration Features:** 7. `party-mode` - Multi-agent collaboration 8. `expert-chat` - Direct conversation with Saga
### Design Philosophy Implementation
**✅ Soft Language:**
+
- No "MUST", "FORBIDDEN", "NEVER" commands
- Identity-based guidance instead of rules
- Collaborative framing throughout
**✅ Show, Don't Tell:**
+
- Working rhythm examples provided
- Clear "what works well" vs "what feels less collaborative"
- Concrete process visualization
**✅ Norse Mythology Theme:**
+
- Saga = Goddess of stories and wisdom
- Fits perfectly with role (discovering product stories)
- Creates memorable WDS brand identity
@@ -2204,16 +2386,19 @@ When we work together:
### Integration Points
**With WDS Team:**
+
- **Freyja (PM)**: Receives strategic foundation for PRD development
- **Baldr (UX)**: Uses personas and trigger map for design work
**With BMM (Development):**
+
- Product Brief provides architecture context
- Trigger Map personas inform user stories
- Success metrics guide development priorities
- E-Design-Deliveries bridges design to development
**With Core BMad:**
+
- Uses core brainstorming workflow
- Uses core party-mode workflow
- Leverages BMM research workflow
@@ -2231,23 +2416,27 @@ When we work together:
### Key Decisions Made
**Agent Naming:**
+
- **Saga WDS Analyst** (not Mary, not just "Business Analyst")
- Norse mythology theme for unique WDS identity
- "Saga the Analyst" format - natural reading, clear function
**Capability Scope:**
+
- Phases 1-2 focus (Product Brief, Trigger Map)
- Strategic foundation and market intelligence
- Replaces BMM analyst when WDS is chosen
- Maintains BMM analyst capabilities (research, documentation)
**Language Style:**
+
- Soft, collaborative, identity-based
- Working rhythm explicitly defined
- "What works well" vs "what feels less collaborative" framing
- No harsh enforcement language
**Integration Strategy:**
+
- Seamless with WDS workflows (phases 1-2)
- Leverages BMM workflows (research, documentation)
- Uses core workflows (brainstorming, party-mode)
@@ -2256,6 +2445,7 @@ When we work together:
### Testing Checklist
When testing Saga-Analyst:
+
- [ ] Agent activates successfully
- [ ] Presentation displays correctly
- [ ] workflow-status initializes WDS project
@@ -2274,10 +2464,12 @@ When testing Saga-Analyst:
### Next Steps
**Immediate:**
+
1. Create Freyja-PM agent (Product Manager - Goddess of love, war & strategy)
2. Create Baldr-UX agent (UX/UI Designer - God of light & beauty)
**After Agents Complete:**
+
1. Create agent presentation files for Freyja and Baldr
2. Create team configurations in `teams/`
3. Create module installer config
@@ -2294,6 +2486,7 @@ When testing Saga-Analyst:
**Purpose:** Help consultants create compelling pitches to win WDS engagements
**Approach:** Two-repo strategy (no complexity in client projects)
+
- **Client repo:** Standard WDS phases (A-G folders)
- **Consultant repo:** Private pitch materials (pricing, strategy, proposals)
@@ -2324,6 +2517,7 @@ src/modules/wds/
**Trigger:** `pitch-client` - Creates pitch materials with consultant-specified output location
**Key Features:**
+
- Client research and discovery
- Phase recommendation (which WDS phases client needs)
- Effort estimation and timeline
@@ -2332,12 +2526,14 @@ src/modules/wds/
- Pricing/budget guidance
**Security Model:**
+
- Consultant controls where files are saved (their private repo)
- No `.consultant/` folder or gitignore complexity
- Clean separation between client and consultant materials
- Works with any organizational system
**Deliverables:**
+
- Client discovery notes
- Recommended WDS phases
- Pitch deck content
@@ -2346,6 +2542,7 @@ src/modules/wds/
- Budget/pricing strategy
**Benefits:**
+
- Helps consultants win engagements
- Standardizes pitch process
- Ensures proper WDS scoping
@@ -2360,5 +2557,4 @@ src/modules/wds/
**End of Roadmap Document**
-*WDS v6 Core Module: Complete ✅*
-
+_WDS v6 Core Module: Complete ✅_
diff --git a/conversion-logs/conversion-guide.md b/conversion-logs/conversion-guide.md
index c37c3c37..10617eb1 100644
--- a/conversion-logs/conversion-guide.md
+++ b/conversion-logs/conversion-guide.md
@@ -13,6 +13,7 @@ This directory contains detailed logs of each conversion session, keeping the ma
## Structure
Each session gets its own log file:
+
- `session-YYYY-MM-DD-topic.md` - Detailed work log for that session
---
@@ -28,6 +29,7 @@ Each session gets its own log file:
## What Goes in Session Logs
**Each session log should document:**
+
- Date and duration
- Objectives
- Files created/modified
@@ -43,6 +45,7 @@ Each session gets its own log file:
## What Stays in Roadmap
**The main roadmap (`WDS-V6-CONVERSION-ROADMAP.md`) should contain:**
+
- Current work in progress
- Next planned work
- Future backlog items
diff --git a/conversion-logs/session-2025-12-09-micro-steps-concepts.md b/conversion-logs/session-2025-12-09-micro-steps-concepts.md
index 6d04b570..6d3c8a68 100644
--- a/conversion-logs/session-2025-12-09-micro-steps-concepts.md
+++ b/conversion-logs/session-2025-12-09-micro-steps-concepts.md
@@ -22,6 +22,7 @@
### 1. Phase 6: Design Deliveries Micro-Steps (7 files)
**Created:**
+
- `src/modules/wds/workflows/6-design-deliveries/workflow.md`
- `src/modules/wds/workflows/6-design-deliveries/steps/step-6.1-detect-completion.md`
- `src/modules/wds/workflows/6-design-deliveries/steps/step-6.2-create-delivery.md`
@@ -31,6 +32,7 @@
- `src/modules/wds/workflows/6-design-deliveries/steps/step-6.6-continue.md`
**Key features:**
+
- Emphasizes parallel work (design next while BMad builds current)
- Structured 10-phase handoff dialog with BMad Architect
- Clear continuation strategy to prevent designer blocking
@@ -41,6 +43,7 @@
### 2. Phase 7: Testing Micro-Steps (8 files)
**Created:**
+
- `src/modules/wds/workflows/7-testing/workflow.md`
- `src/modules/wds/workflows/7-testing/steps/step-7.1-receive-notification.md`
- `src/modules/wds/workflows/7-testing/steps/step-7.2-prepare-testing.md`
@@ -51,6 +54,7 @@
- `src/modules/wds/workflows/7-testing/steps/step-7.7-iterate-or-approve.md`
**Key features:**
+
- Comprehensive test execution (happy path, errors, edge cases, design system, a11y)
- Structured issue creation with severity levels (Critical, High, Medium, Low)
- Professional test reporting format
@@ -62,6 +66,7 @@
### 3. Phase 8: Ongoing Development Micro-Steps (9 files)
**Created:**
+
- `src/modules/wds/workflows/8-ongoing-development/workflow.md`
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.1-identify-opportunity.md`
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.2-gather-context.md`
@@ -73,6 +78,7 @@
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md`
**Key features:**
+
- Kaizen (改善) continuous improvement philosophy
- Two contexts: Existing Product Entry Point + Post-Launch Improvement
- Small, focused changes (1-2 weeks each)
@@ -84,10 +90,12 @@
### 4. Concepts Integration
**Created:**
+
- `src/core/resources/wds/glossary.md` - Complete reference for all concepts
- `CONCEPTS-INTEGRATION.md` - Map of where concepts are used
**Updated:**
+
- `src/modules/wds/workflows/workflow-init/project-type-selection.md`
- `src/modules/wds/workflows/8-ongoing-development/workflow.md`
- `src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md`
@@ -96,15 +104,18 @@
**Concepts added:**
#### Software Development Terms
+
- **Greenfield Development:** Building from scratch, no constraints (Phases 1-7)
- **Brownfield Development:** Working with existing systems (Phase 8)
#### Lean Manufacturing Terms
+
- **Kaizen (改善):** Continuous improvement, small incremental changes (Phase 8)
- **Kaikaku (改革):** Revolutionary change, major transformation (Phases 1-7)
- **Muda (無駄):** Waste elimination
**Key pairings:**
+
```
Greenfield + Kaikaku = New Product (Phases 1-7)
Brownfield + Kaizen = Existing Product (Phase 8)
@@ -120,17 +131,20 @@ Brownfield + Kaizen = Existing Product (Phase 8)
**Decision:** Use Design Deliveries (DD-XXX) for all design handoffs, regardless of scope.
**Rationale:**
+
- Simpler for BMad to consume (one format)
- Consistent handoff process
- Easier to track and manage
- Same format, different scope
**Before (Complex):**
+
- DD-XXX for complete new flows (Phases 4-7)
- SU-XXX for incremental improvements (Phase 8)
- Two different formats to maintain
**After (Simple):**
+
- DD-XXX for everything
- `type: "complete_flow"` vs `type: "incremental_improvement"`
- `scope: "new"` vs `scope: "update"`
@@ -138,26 +152,29 @@ Brownfield + Kaizen = Existing Product (Phase 8)
**YAML Differentiation:**
Large scope (new flows):
+
```yaml
delivery:
- id: "DD-001"
- name: "Login & Onboarding"
- type: "complete_flow"
- scope: "new"
+ id: 'DD-001'
+ name: 'Login & Onboarding'
+ type: 'complete_flow'
+ scope: 'new'
```
Small scope (improvements):
+
```yaml
delivery:
- id: "DD-011"
- name: "Feature X Onboarding Improvement"
- type: "incremental_improvement"
- scope: "update"
- version: "v2.0"
- previous_version: "v1.0"
+ id: 'DD-011'
+ name: 'Feature X Onboarding Improvement'
+ type: 'incremental_improvement'
+ scope: 'update'
+ version: 'v2.0'
+ previous_version: 'v1.0'
```
**Files updated:**
+
- ✅ `src/core/resources/wds/glossary.md`
- ✅ `src/modules/wds/workflows/8-ongoing-development/workflow.md`
- ✅ `src/modules/wds/workflows/8-ongoing-development/steps/step-8.4-create-delivery.md`
@@ -176,11 +193,13 @@ delivery:
**Clarified:** Test Scenarios (TS-XXX) are directly tied to Design Deliveries (DD-XXX)
**One-to-one relationship:**
+
- DD-001 → TS-001
- DD-002 → TS-002
- DD-015 (improvement) → TS-015
**Created together:**
+
- Phase 6, Step 6.2: Create Design Delivery (DD-XXX)
- Phase 6, Step 6.3: Create Test Scenario (TS-XXX)
@@ -192,6 +211,7 @@ The Test Scenario validates that the business and user goals defined in the Desi
## Statistics
**Files created:** 26
+
- Phase 6: 7 files
- Phase 7: 8 files
- Phase 8: 9 files
@@ -199,11 +219,13 @@ The Test Scenario validates that the business and user goals defined in the Desi
- Integration map: 1 file
**Lines written:** ~27,000
+
- Phase 6: ~7,000 lines
- Phase 7: ~10,000 lines
- Phase 8: ~10,000 lines
**Files updated:** 5
+
- Project type selection
- Phase 8 workflow
- Existing product guide
@@ -215,18 +237,23 @@ The Test Scenario validates that the business and user goals defined in the Desi
## Key Decisions
### 1. Micro-File Architecture
+
Adopted BMad's pattern of breaking workflows into sequential, self-contained step files for disciplined execution.
### 2. Kaizen Philosophy
+
Phase 8 embodies Kaizen (改善) - continuous improvement through small, incremental changes that compound over time.
### 3. DD-XXX Simplification
+
Eliminated SU-XXX format. All deliveries use DD-XXX with `type` and `scope` fields to differentiate.
### 4. Terminology Integration
+
Integrated industry-standard terms (Greenfield/Brownfield, Kaizen/Kaikaku) to connect WDS to established methodologies.
### 5. TS-XXX Relationship
+
Clarified that Test Scenarios are created alongside Design Deliveries and validate the same business/user goals.
---
@@ -234,16 +261,19 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida
## Challenges & Solutions
### Challenge 1: Phase 6 Initially Single File
+
**Problem:** First attempt only refactored content within existing file instead of creating separate micro-step files.
**Solution:** User pointed out the issue. Created proper micro-file structure with `workflow.md` and individual `step-6.X-*.md` files.
### Challenge 2: Two Delivery Formats
+
**Problem:** Having both DD-XXX and SU-XXX created confusion and maintenance burden.
**Solution:** User suggested simplification. Unified to DD-XXX for everything with `type` and `scope` fields to differentiate.
### Challenge 3: Documentation Sprawl
+
**Problem:** Started creating separate documents for planning and tracking.
**Solution:** User requested consolidation. Added all planning to existing roadmap instead of creating new documents.
@@ -253,6 +283,7 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida
## Examples Created
### Phase 6 Example: Dog Week Onboarding
+
- Complete flow from welcome to dashboard
- 4 scenarios specified
- Design system components defined
@@ -260,6 +291,7 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida
- Test scenario for validation
### Phase 7 Example: Feature X Validation
+
- Happy path tests (5 tests)
- Error state tests (4 tests)
- Edge case tests (3 tests)
@@ -268,6 +300,7 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida
- 8 issues found, documented, fixed, retested
### Phase 8 Example: Feature X Onboarding Improvement
+
- Problem: 15% usage, 40% drop-off
- Solution: Add inline onboarding
- Impact: 15% → 58% usage (4x increase)
@@ -279,16 +312,19 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida
## Next Steps
### Immediate (This Week)
+
1. Complete SU-XXX → DD-XXX migration in Phase 8 step files
2. Test Phase 6/7/8 workflows with real project
3. Create commit for today's work
### Short-term (Next Week)
+
1. Complete remaining module tutorials (03, 05-07, 09-11, 13-16)
2. Create WDS Excalidraw component library
3. Test complete WDS → BMad workflow
### Long-term (This Month)
+
1. Implement auto-export automation (GitHub Actions)
2. Refine assessment criteria based on usage
3. Test Figma MCP integration with real components
@@ -298,18 +334,23 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida
## Learnings
### 1. Micro-Steps Enable Discipline
+
Breaking complex workflows into small, sequential steps makes execution more disciplined and reduces cognitive load.
### 2. Philosophy Matters
+
Connecting WDS to established methodologies (Lean, Kaizen) gives designers a mental model and vocabulary for the work.
### 3. Simplification is Powerful
+
Reducing from two delivery formats to one eliminates confusion and maintenance burden while maintaining necessary differentiation.
### 4. Parallel Work is Key
+
Phase 6 emphasizes parallel work (design next while BMad builds current) to prevent designer blocking and maximize throughput.
### 5. Measurement Drives Improvement
+
Phase 8's focus on measuring impact after each cycle enables data-driven continuous improvement.
---
diff --git a/package-lock.json b/package-lock.json
index 80746370..50aa277d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "bmad-method",
- "version": "6.0.0-alpha.12",
+ "version": "6.0.0-alpha.13",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "bmad-method",
- "version": "6.0.0-alpha.12",
+ "version": "6.0.0-alpha.13",
"license": "MIT",
"dependencies": {
"@kayvan/markdown-tree-parser": "^1.6.1",
diff --git a/src/core/resources/wds/design-delivery-spec.md b/src/core/resources/wds/design-delivery-spec.md
index 28e634e7..a0f3d1e0 100644
--- a/src/core/resources/wds/design-delivery-spec.md
+++ b/src/core/resources/wds/design-delivery-spec.md
@@ -7,6 +7,7 @@
## What is a Design Delivery?
A Design Delivery (DD) is a package created by WDS that contains:
+
- Complete user flow specifications
- Technical requirements
- Design system references
@@ -26,15 +27,15 @@ A Design Delivery (DD) is a package created by WDS that contains:
```yaml
delivery:
- id: "DD-001" # Unique identifier (DD-XXX)
- name: "Login & Onboarding" # Human-readable name
- type: "user_flow" # user_flow | feature | component
- status: "ready" # ready | in_progress | blocked
- priority: "high" # high | medium | low
- created_by: "wds-ux-expert" # Creator agent
- created_at: "2024-12-09T10:00:00Z"
- updated_at: "2024-12-09T10:00:00Z"
- version: "1.0"
+ id: 'DD-001' # Unique identifier (DD-XXX)
+ name: 'Login & Onboarding' # Human-readable name
+ type: 'user_flow' # user_flow | feature | component
+ status: 'ready' # ready | in_progress | blocked
+ priority: 'high' # high | medium | low
+ created_by: 'wds-ux-expert' # Creator agent
+ created_at: '2024-12-09T10:00:00Z'
+ updated_at: '2024-12-09T10:00:00Z'
+ version: '1.0'
description: |
Complete user authentication and onboarding flow.
@@ -42,89 +43,89 @@ description: |
Testable as standalone feature with real users.
user_value:
- problem: "Users need to access the app securely and set up their family"
- solution: "Streamlined onboarding with family setup"
+ problem: 'Users need to access the app securely and set up their family'
+ solution: 'Streamlined onboarding with family setup'
success_criteria:
- - "User completes signup in under 2 minutes"
- - "User successfully joins or creates family"
- - "User reaches functional dashboard"
- - "90% completion rate for onboarding flow"
+ - 'User completes signup in under 2 minutes'
+ - 'User successfully joins or creates family'
+ - 'User reaches functional dashboard'
+ - '90% completion rate for onboarding flow'
design_artifacts:
scenarios:
- - id: "01-welcome"
- path: "C-Scenarios/01-welcome-screen/"
- screens: ["welcome"]
-
- - id: "02-login"
- path: "C-Scenarios/02-login/"
- screens: ["login", "forgot-password"]
-
+ - id: '01-welcome'
+ path: 'C-Scenarios/01-welcome-screen/'
+ screens: ['welcome']
+
+ - id: '02-login'
+ path: 'C-Scenarios/02-login/'
+ screens: ['login', 'forgot-password']
+
user_flows:
- - name: "New User Onboarding"
- path: "C-Scenarios/flows/new-user-onboarding.excalidraw"
- entry: "welcome"
- exit: "dashboard"
-
+ - name: 'New User Onboarding'
+ path: 'C-Scenarios/flows/new-user-onboarding.excalidraw'
+ entry: 'welcome'
+ exit: 'dashboard'
+
design_system:
components:
- - "Button (Primary, Secondary)"
- - "Input Field (Email, Password)"
- - "Card (Welcome, Family)"
- path: "D-Design-System/"
+ - 'Button (Primary, Secondary)'
+ - 'Input Field (Email, Password)'
+ - 'Card (Welcome, Family)'
+ path: 'D-Design-System/'
technical_requirements:
platform:
- frontend: "react_native"
- backend: "supabase"
-
+ frontend: 'react_native'
+ backend: 'supabase'
+
integrations:
- - name: "supabase_auth"
- purpose: "User authentication"
+ - name: 'supabase_auth'
+ purpose: 'User authentication'
required: true
-
- - name: "email_verification"
- purpose: "Verify user email"
+
+ - name: 'email_verification'
+ purpose: 'Verify user email'
required: true
-
+
data_models:
- - name: "User"
- fields: ["email", "name", "avatar"]
-
- - name: "Family"
- fields: ["name", "invite_code", "members"]
+ - name: 'User'
+ fields: ['email', 'name', 'avatar']
+
+ - name: 'Family'
+ fields: ['name', 'invite_code', 'members']
acceptance_criteria:
functional:
- - "User can create account with email/password"
- - "User receives verification email"
- - "User can create new family or join existing"
-
+ - 'User can create account with email/password'
+ - 'User receives verification email'
+ - 'User can create new family or join existing'
+
non_functional:
- - "Onboarding completes in < 2 minutes"
- - "Works offline (cached welcome screen)"
- - "Accessible (WCAG 2.1 AA)"
-
+ - 'Onboarding completes in < 2 minutes'
+ - 'Works offline (cached welcome screen)'
+ - 'Accessible (WCAG 2.1 AA)'
+
edge_cases:
- - "Email already exists → Show login option"
- - "Invalid invite code → Show error, allow retry"
- - "Network error during signup → Save progress, retry"
+ - 'Email already exists → Show login option'
+ - 'Invalid invite code → Show error, allow retry'
+ - 'Network error during signup → Save progress, retry'
testing_guidance:
user_testing:
- - "Test with 5 families (different tech comfort levels)"
- - "Measure completion time and drop-off points"
-
+ - 'Test with 5 families (different tech comfort levels)'
+ - 'Measure completion time and drop-off points'
+
qa_testing:
- - "Test all error states"
- - "Test offline scenarios"
- - "Test accessibility with screen reader"
+ - 'Test all error states'
+ - 'Test offline scenarios'
+ - 'Test accessibility with screen reader'
estimated_complexity:
- size: "medium" # small | medium | large
- effort: "2-3 weeks" # Time estimate
- risk: "low" # low | medium | high
- dependencies: [] # Other DD-XXX IDs needed first
+ size: 'medium' # small | medium | large
+ effort: '2-3 weeks' # Time estimate
+ risk: 'low' # low | medium | high
+ dependencies: [] # Other DD-XXX IDs needed first
notes: |
This is the first user-facing feature and sets the tone
@@ -178,11 +179,11 @@ for scenario in scenarios:
scenario_id = scenario['id']
scenario_path = scenario['path']
screens = scenario['screens']
-
+
print(f"Scenario: {scenario_id}")
print(f"Path: {scenario_path}")
print(f"Screens: {', '.join(screens)}")
-
+
# Read scenario specifications
spec_path = f"{scenario_path}/Frontend/specifications.md"
# Read and parse specifications...
@@ -205,7 +206,7 @@ for integration in integrations:
name = integration['name']
required = integration['required']
purpose = integration['purpose']
-
+
print(f"Integration: {name} ({'required' if required else 'optional'})")
print(f"Purpose: {purpose}")
```
@@ -332,6 +333,7 @@ Source: DD-001 scenario 04
### 1. Respect Designer Decisions
**The designer has already made these choices:**
+
- Tech stack (platform.frontend, platform.backend)
- Integrations (technical_requirements.integrations)
- Component usage (design_system.components)
@@ -339,6 +341,7 @@ Source: DD-001 scenario 04
**Your job:** Implement these choices faithfully
**Exception:** If you see a technical problem, flag it:
+
```
"⚠️ Technical Concern: DD-001 specifies Supabase Auth,
but project already uses Firebase. Recommend discussing
@@ -348,6 +351,7 @@ with designer before proceeding."
### 2. Maintain Traceability
**Always link back to source:**
+
```markdown
Epic 1.2: Login Screen
**Source:** DD-001 (Login & Onboarding)
@@ -359,11 +363,12 @@ Epic 1.2: Login Screen
### 3. Use Acceptance Criteria
**Designer provided acceptance criteria - these are your requirements:**
+
```yaml
acceptance_criteria:
functional:
- - "User can create account with email/password"
- - "User receives verification email"
+ - 'User can create account with email/password'
+ - 'User receives verification email'
```
**Your epics must cover ALL acceptance criteria**
@@ -371,13 +376,14 @@ acceptance_criteria:
### 4. Follow Testing Guidance
**Designer provided testing guidance:**
+
```yaml
testing_guidance:
user_testing:
- - "Test with 5 families (different tech comfort levels)"
+ - 'Test with 5 families (different tech comfort levels)'
qa_testing:
- - "Test all error states"
- - "Test offline scenarios"
+ - 'Test all error states'
+ - 'Test offline scenarios'
```
**Your test plans should follow this guidance**
@@ -415,7 +421,7 @@ elif status == 'blocked':
```yaml
estimated_complexity:
- dependencies: ["DD-002", "DD-005"]
+ dependencies: ['DD-002', 'DD-005']
```
**This means:** DD-001 requires DD-002 and DD-005 to be implemented first
@@ -440,9 +446,9 @@ else:
```yaml
delivery:
- version: "1.1"
- updated_at: "2024-12-15T14:00:00Z"
-
+ version: '1.1'
+ updated_at: '2024-12-15T14:00:00Z'
+
notes: |
Version 1.1 changes:
- Added offline support requirement
diff --git a/src/core/resources/wds/glossary.md b/src/core/resources/wds/glossary.md
index 22bb42a5..85476916 100644
--- a/src/core/resources/wds/glossary.md
+++ b/src/core/resources/wds/glossary.md
@@ -13,6 +13,7 @@
**Origin:** Agricultural term - plowing a green field that has never been cultivated before.
**In software:**
+
- No legacy code to maintain
- Full creative freedom
- Define architecture from scratch
@@ -21,6 +22,7 @@
- Start with blank canvas
**In WDS:**
+
- **Phases 1-7:** New Product Development
- Complete user flows designed from scratch
- Full Project Brief
@@ -39,6 +41,7 @@
**Origin:** Industrial term - redeveloping land previously used for industrial purposes (often contaminated, requiring cleanup).
**In software:**
+
- Existing codebase to work with
- Legacy systems to integrate
- Established patterns to follow
@@ -47,6 +50,7 @@
- Cleanup and improvement
**In WDS:**
+
- **Phase 8:** Existing Product Development
- Targeted improvements to existing product
- Limited Project Brief (strategic challenge)
@@ -63,6 +67,7 @@
### Kaizen (改善) - Continuous Improvement
**Japanese:** 改善
+
- 改 (kai) = Change
- 善 (zen) = Good
@@ -71,6 +76,7 @@
**Origin:** Japanese manufacturing philosophy, popularized by Toyota Production System.
**Characteristics:**
+
- **Small changes:** 1-2 weeks each
- **Low cost, low risk:** Minimal investment
- **Everyone participates:** Bottom-up approach
@@ -80,6 +86,7 @@
- **Data-driven:** Measure everything
**In product design:**
+
- Ship → Monitor → Learn → Improve → Ship → Repeat
- Small updates beat big redesigns
- User feedback drives improvements
@@ -88,6 +95,7 @@
- Team learns continuously
**In WDS:**
+
- **Phase 8:** Ongoing Development
- System Updates (SU-XXX) instead of Design Deliveries
- 1-2 week improvement cycles
@@ -95,6 +103,7 @@
- Iterate based on learnings
**Examples:**
+
- Add onboarding tooltip to improve feature usage (15% → 60%)
- Optimize button color for better conversion (+5%)
- Improve error message clarity (-80% support tickets)
@@ -108,6 +117,7 @@
### Kaikaku (改革) - Revolutionary Change
**Japanese:** 改革
+
- 改 (kai) = Change
- 革 (kaku) = Reform/Revolution
@@ -116,6 +126,7 @@
**Origin:** Japanese manufacturing philosophy, used for major system overhauls.
**Characteristics:**
+
- **Large changes:** Months of work
- **High cost, high risk:** Major investment
- **Leadership-driven:** Top-down approach
@@ -125,6 +136,7 @@
- **Disruptive:** Major changes to system
**In product design:**
+
- Complete redesign
- Platform migration (web → mobile)
- Architecture overhaul
@@ -133,6 +145,7 @@
- Technology stack change
**In WDS:**
+
- **Phases 1-7:** New Product Development (greenfield)
- Complete user flows designed
- Full Design Deliveries (DD-XXX)
@@ -140,6 +153,7 @@
- Revolutionary change
**Examples:**
+
- Complete product redesign (v1.0 → v2.0)
- Migrate from web to mobile-first
- Rebrand entire product
@@ -154,6 +168,7 @@
### Kaizen vs Kaikaku: When to Use Each
**Use Kaizen (改善) when:**
+
- ✅ Product is live and working
- ✅ Need continuous improvement
- ✅ Want low-risk changes
@@ -162,6 +177,7 @@
- ✅ **WDS Phase 8: Ongoing Development**
**Use Kaikaku (改革) when:**
+
- ✅ Starting from scratch (greenfield)
- ✅ Product needs complete overhaul
- ✅ Market demands radical change
@@ -206,6 +222,7 @@ Kaizen: Continuous improvement again
7. **Defects:** Bugs, rework, and quality issues
**Kaizen eliminates Muda through:**
+
- Small, focused improvements
- Fast cycles (ship → learn → improve)
- Continuous measurement
@@ -213,6 +230,7 @@ Kaizen: Continuous improvement again
- Eliminating handoff friction
**In WDS:**
+
- Design specifications eliminate handoff waste
- Iterative deliveries eliminate inventory waste
- Fast cycles eliminate waiting waste
@@ -227,12 +245,14 @@ Kaizen: Continuous improvement again
**Definition:** A structured YAML package for handing off design work to BMad.
**Used for BOTH:**
+
- ✅ Complete new user flows (Greenfield/Kaikaku)
- ✅ Incremental improvements (Brownfield/Kaizen)
**The format is the same - only the scope differs!**
**Contains:**
+
- User value and business value
- Design artifacts (scenarios, components)
- Technical requirements
@@ -245,28 +265,32 @@ Kaizen: Continuous improvement again
**Scope variations:**
**Large scope (New flows):**
+
```yaml
delivery:
- id: "DD-001"
- name: "Login & Onboarding"
- type: "complete_flow"
- scope: "new"
+ id: 'DD-001'
+ name: 'Login & Onboarding'
+ type: 'complete_flow'
+ scope: 'new'
```
**Small scope (Improvements):**
+
```yaml
delivery:
- id: "DD-015"
- name: "Feature X Onboarding Improvement"
- type: "incremental_improvement"
- scope: "update"
+ id: 'DD-015'
+ name: 'Feature X Onboarding Improvement'
+ type: 'incremental_improvement'
+ scope: 'update'
```
**Examples:**
+
- `DD-001-login-onboarding.yaml` (complete new flow)
- `DD-015-feature-x-onboarding.yaml` (incremental improvement)
**Why one format?**
+
- Simpler for BMad to consume
- Consistent handoff process
- Same validation workflow
@@ -279,12 +303,14 @@ delivery:
**Definition:** YAML file defining the technical stack and constraints.
**Contains:**
+
- Tech stack choices
- Integrations
- Constraints
- Rationale
**Used in:**
+
- Phase 3 (New Product)
- Greenfield projects
- Touch Point 1: WDS → BMad
@@ -299,12 +325,14 @@ delivery:
**Definition:** Structured YAML defining validation steps for designers to verify a Design Delivery.
**Relationship to Design Delivery:**
+
- **One-to-one:** Each DD-XXX has a corresponding TS-XXX
- **Created together:** Test Scenario is created when Design Delivery is created (Phase 6, Step 6.3)
- **Validates goals:** Tests verify that business and user goals defined in DD-XXX are achieved
- **Same numbering:** TS-001 validates DD-001, TS-002 validates DD-002, etc.
**Contains:**
+
- Happy path tests (verify user goals achieved)
- Error state tests (verify error handling)
- Edge case tests (verify robustness)
@@ -313,12 +341,14 @@ delivery:
- Sign-off criteria (based on DD-XXX acceptance criteria)
**Used in:**
+
- Phase 6 (Design Deliveries) - Created alongside DD-XXX
- Phase 7 (Testing) - Executed to validate implementation
- Designer validation
- Touch Point 3: BMad → WDS
**Example:**
+
```
DD-001-login-onboarding.yaml → TS-001-login-onboarding.yaml
DD-015-feature-x-improvement.yaml → TS-015-feature-x-improvement.yaml
@@ -361,6 +391,7 @@ The Test Scenario validates that the business and user goals defined in the Desi
**Origin:** Seth Godin's book "Linchpin: Are You Indispensable?" (2010)
**Characteristics:**
+
- Walks into chaos and creates order
- Navigates 5 dimensions of thinking simultaneously
- Provides emotional labor (genuinely cares about outcome)
@@ -370,6 +401,7 @@ The Test Scenario validates that the business and user goals defined in the Desi
**Opposite:** Factory worker who follows instructions and can be replaced.
**In WDS:**
+
- Designer as gatekeeper between business and user needs
- Catches AI's confident but ridiculous mistakes
- Ensures design intent is preserved
@@ -390,12 +422,14 @@ The Test Scenario validates that the business and user goals defined in the Desi
5. **Technical Viability (FEASIBLE)** - Bridging design and implementation
**Why it matters:**
+
- Most people can handle 1-2 dimensions
- Irreplaceable designers navigate all 5 simultaneously
- Each dimension informs the others
- Miss one, and your design falls apart
**In WDS:**
+
- Project Brief covers all 5 dimensions
- Trigger Map connects dimensions
- Design Deliveries preserve all 5 dimensions
@@ -405,12 +439,12 @@ The Test Scenario validates that the business and user goals defined in the Desi
## Comparison Table
-| Concept | Type | WDS Phase | Approach | Timeline | Deliverable |
-|---------|------|-----------|----------|----------|-------------|
-| **Greenfield** | Software Dev | Phases 1-7 | New product | Months | DD-XXX |
-| **Brownfield** | Software Dev | Phase 8 | Existing product | Weeks | DD-XXX |
-| **Kaikaku (改革)** | Lean | Phases 1-7 | Revolutionary | Months | DD-XXX (large scope) |
-| **Kaizen (改善)** | Lean | Phase 8 | Continuous | 1-2 weeks | DD-XXX (small scope) |
+| Concept | Type | WDS Phase | Approach | Timeline | Deliverable |
+| ------------------ | ------------ | ---------- | ---------------- | --------- | -------------------- |
+| **Greenfield** | Software Dev | Phases 1-7 | New product | Months | DD-XXX |
+| **Brownfield** | Software Dev | Phase 8 | Existing product | Weeks | DD-XXX |
+| **Kaikaku (改革)** | Lean | Phases 1-7 | Revolutionary | Months | DD-XXX (large scope) |
+| **Kaizen (改善)** | Lean | Phase 8 | Continuous | 1-2 weeks | DD-XXX (small scope) |
**Note:** All design work is handed off as Design Deliveries (DD-XXX). The scope and content differ, but the format is consistent.
@@ -419,15 +453,19 @@ The Test Scenario validates that the business and user goals defined in the Desi
## Usage Examples
### Greenfield + Kaikaku
+
"We're building a new dog care app from scratch (greenfield). This is a complete product launch (Kaikaku). We'll use WDS Phases 1-7 to design complete user flows, then hand off Design Deliveries to BMad."
### Brownfield + Kaizen
+
"We're improving an existing product with 60% onboarding drop-off (brownfield). We'll make small, incremental improvements (Kaizen). We'll use WDS Phase 8 to create Design Deliveries (small scope) and measure impact after each cycle."
### Greenfield → Brownfield
+
"We started with greenfield development (Phases 1-7), launched the product, and now we're in brownfield mode (Phase 8) doing continuous Kaizen improvements."
### Kaikaku → Kaizen
+
"We did a major redesign (Kaikaku) using Phases 1-7. Now we're in continuous improvement mode (Kaizen) using Phase 8, shipping small updates every 1-2 weeks."
---
diff --git a/src/core/resources/wds/handoff-protocol.md b/src/core/resources/wds/handoff-protocol.md
index d5497443..2dcae069 100644
--- a/src/core/resources/wds/handoff-protocol.md
+++ b/src/core/resources/wds/handoff-protocol.md
@@ -7,6 +7,7 @@
## Overview
The handoff is a structured conversation between:
+
- **WDS UX Expert** (Design authority)
- **BMad Architect** (Technical authority)
@@ -23,6 +24,7 @@ The handoff is a structured conversation between:
### Phase 1: Introduction (1 min)
**WDS UX Expert initiates:**
+
```
"Hey Architect! I've completed the design for [Delivery Name].
@@ -31,6 +33,7 @@ Let me walk you through what I've designed..."
```
**BMad Architect acknowledges:**
+
```
"Great! I'm ready to receive the handoff. What have you got for me?"
```
@@ -51,11 +54,13 @@ Let me walk you through what I've designed..."
```
**BMad Architect asks:**
+
```
"Got it. What's the user value here?"
```
**WDS UX Expert responds:**
+
```
"The problem: [User problem being solved]
@@ -68,6 +73,7 @@ Success criteria:
```
**BMad Architect confirms:**
+
```
"Perfect. I understand the user value. What scenarios did you design?"
```
@@ -98,6 +104,7 @@ component usage, interaction patterns, and edge cases."
```
**BMad Architect may ask:**
+
```
"Can you elaborate on [specific scenario]?"
"How does [screen A] connect to [screen B]?"
@@ -111,11 +118,13 @@ component usage, interaction patterns, and edge cases."
### Phase 4: Technical Requirements (3 min)
**BMad Architect asks:**
+
```
"What about the technical stack? Any preferences?"
```
**WDS UX Expert shares:**
+
```
"Yes! I've already defined the platform requirements:
@@ -131,11 +140,13 @@ The designer chose these because [reasoning]."
```
**BMad Architect asks:**
+
```
"Makes sense. What integrations do you need?"
```
**WDS UX Expert lists:**
+
```
"[N] key integrations:
@@ -152,11 +163,13 @@ The designer chose these because [reasoning]."
```
**BMad Architect asks:**
+
```
"Got it. What data models do I need to implement?"
```
**WDS UX Expert defines:**
+
```
"[N] main models:
@@ -174,6 +187,7 @@ know if you see any technical issues with these structures."
```
**BMad Architect validates:**
+
```
"These look good. [Or: I see a potential issue with...]"
```
@@ -183,11 +197,13 @@ know if you see any technical issues with these structures."
### Phase 5: Design System (2 min)
**BMad Architect asks:**
+
```
"What about the design system? What components should I use?"
```
**WDS UX Expert lists:**
+
```
"I've used components from our design system:
@@ -205,6 +221,7 @@ tested, and match our brand."
```
**BMad Architect confirms:**
+
```
"Perfect. I'll reference those. What are the acceptance criteria?"
```
@@ -214,6 +231,7 @@ tested, and match our brand."
### Phase 6: Acceptance Criteria (2 min)
**WDS UX Expert shares:**
+
```
"Functional requirements:
✓ [Requirement 1]
@@ -235,6 +253,7 @@ highlight the critical ones."
```
**BMad Architect acknowledges:**
+
```
"Great detail! How should I test this?"
```
@@ -244,6 +263,7 @@ highlight the critical ones."
### Phase 7: Testing (2 min)
**WDS UX Expert explains:**
+
```
"I've created a test scenario: test-scenarios/[TS-XXX].yaml
@@ -263,6 +283,7 @@ screenshots and references back to the specifications."
```
**BMad Architect confirms:**
+
```
"Perfect. What's your estimate for complexity?"
```
@@ -272,6 +293,7 @@ screenshots and references back to the specifications."
### Phase 8: Estimates & Planning (3 min)
**WDS UX Expert shares:**
+
```
"Size: [small|medium|large]
Effort: [time estimate]
@@ -282,6 +304,7 @@ Dependencies: [None or list of DD-XXX]
```
**BMad Architect proposes:**
+
```
"Excellent handoff! Let me break this down into development epics:
@@ -303,6 +326,7 @@ Total: [X weeks], matches your estimate.
```
**WDS UX Expert may suggest:**
+
```
"That breakdown makes sense. [Or: One suggestion...]
@@ -310,6 +334,7 @@ Total: [X weeks], matches your estimate.
```
**BMad Architect adjusts if needed:**
+
```
"Good idea! [Revised plan if applicable]
@@ -322,6 +347,7 @@ implementation details."
### Phase 9: Special Considerations (2 min)
**WDS UX Expert shares important notes:**
+
```
"Yes! A few important notes:
@@ -341,6 +367,7 @@ implementation details."
```
**BMad Architect acknowledges:**
+
```
"All noted! I'll make sure to:
- [Commitment 1]
@@ -355,6 +382,7 @@ implementation details."
### Phase 10: Confirmation (1 min)
**BMad Architect summarizes:**
+
```
"Excellent handoff! Let me summarize what I'm taking:
@@ -377,6 +405,7 @@ Any concerns or special considerations I should know about?"
```
**WDS UX Expert confirms or corrects:**
+
```
"[If correct:] Perfect! That's exactly right.
@@ -391,6 +420,7 @@ Looking forward to seeing this come to life. Remember:
```
**BMad Architect commits:**
+
```
"Got it! I'll make sure the implementation honors your
design vision. Talk soon!"
@@ -403,6 +433,7 @@ design vision. Talk soon!"
### For WDS UX Expert
**Your role:**
+
- Be the design authority
- Explain the "why" behind decisions
- Share context and considerations
@@ -410,6 +441,7 @@ design vision. Talk soon!"
- Trust the architect to implement well
**Tone:**
+
- Collaborative, not dictatorial
- Helpful, not defensive
- Clear, not vague
@@ -417,6 +449,7 @@ design vision. Talk soon!"
- Encouraging, not demanding
**Key phrases:**
+
- "Here's what I've designed..."
- "The user value is..."
- "I've focused on..."
@@ -425,6 +458,7 @@ design vision. Talk soon!"
- "I trust you to implement this well"
**What to emphasize:**
+
- User value and success criteria
- Critical user experience details
- Design system compliance
@@ -432,6 +466,7 @@ design vision. Talk soon!"
- Special considerations
**What to avoid:**
+
- Micromanaging implementation details
- Being defensive about design choices
- Technical jargon (unless necessary)
@@ -443,6 +478,7 @@ design vision. Talk soon!"
### For BMad Architect
**Your role:**
+
- Be the technical authority
- Ask clarifying questions
- Validate technical feasibility
@@ -450,6 +486,7 @@ design vision. Talk soon!"
- Commit to honoring design vision
**Tone:**
+
- Respectful, not dismissive
- Curious, not challenging
- Collaborative, not adversarial
@@ -457,6 +494,7 @@ design vision. Talk soon!"
- Appreciative, not critical
**Key phrases:**
+
- "What have you got for me?"
- "Got it. What about..."
- "Makes sense. What..."
@@ -466,6 +504,7 @@ design vision. Talk soon!"
- "I'll honor your design vision"
**What to ask about:**
+
- User value and success criteria
- Technical requirements
- Integration needs
@@ -475,6 +514,7 @@ design vision. Talk soon!"
- Special considerations
**What to avoid:**
+
- Challenging design decisions
- Suggesting alternative approaches (unless technical issue)
- Dismissing designer's technical choices
@@ -488,6 +528,7 @@ design vision. Talk soon!"
### Before Handoff
**WDS UX Expert prepares:**
+
- [ ] Design Delivery file created (DD-XXX.yaml)
- [ ] All scenarios specified
- [ ] Design system components defined
@@ -495,6 +536,7 @@ design vision. Talk soon!"
- [ ] Special considerations documented
**BMad Architect prepares:**
+
- [ ] Platform requirements reviewed
- [ ] Design system reviewed
- [ ] Ready to receive handoff
@@ -516,12 +558,14 @@ design vision. Talk soon!"
### After Handoff
**BMad Architect:**
+
- [ ] Handoff summary documented
- [ ] Epic breakdown created
- [ ] Implementation plan documented
- [ ] Questions or concerns flagged
**WDS UX Expert:**
+
- [ ] Handoff marked complete
- [ ] Waiting for implementation
- [ ] Available for questions
@@ -533,6 +577,7 @@ design vision. Talk soon!"
### Simple Delivery (Small Feature)
**Shorter handoff (~10 min):**
+
- Quick user value explanation
- Brief scenario walkthrough
- Confirm tech requirements
@@ -541,6 +586,7 @@ design vision. Talk soon!"
### Complex Delivery (Large Feature)
**Longer handoff (~30 min):**
+
- Detailed user value discussion
- In-depth scenario walkthrough
- Technical feasibility discussion
@@ -550,6 +596,7 @@ design vision. Talk soon!"
### Delivery with Dependencies
**Include dependency discussion:**
+
- Which deliveries must be done first
- Why dependencies exist
- How to handle if dependencies delayed
@@ -557,6 +604,7 @@ design vision. Talk soon!"
### Delivery with Technical Concerns
**Include concern resolution:**
+
- Architect raises concern
- UX Expert explains reasoning
- Both discuss alternatives
diff --git a/src/core/resources/wds/integration-guide.md b/src/core/resources/wds/integration-guide.md
index 34305455..3e9f83aa 100644
--- a/src/core/resources/wds/integration-guide.md
+++ b/src/core/resources/wds/integration-guide.md
@@ -60,7 +60,8 @@ WDS (Whiteport Design Studio) and BMad Method integrate seamlessly to create a c
**When:** WDS Phase 6 Complete
**Direction:** WDS → BMad (Complete design handoff)
-**Files:**
+**Files:**
+
- `deliveries/DD-*.yaml` (Design Deliveries)
- `C-Scenarios/` (All scenario specifications)
- `D-Design-System/` (Component library)
@@ -71,12 +72,14 @@ WDS (Whiteport Design Studio) and BMad Method integrate seamlessly to create a c
**BMad Action:** Read everything, break down into dev epics, implement features
**Includes:**
+
- Multi-agent handoff dialog (20-min structured conversation)
- All design deliveries packaged as testable epics
- Complete design system specifications
- Test scenarios for validation
-**Read:**
+**Read:**
+
- [design-delivery-spec.md](design-delivery-spec.md)
- [handoff-protocol.md](handoff-protocol.md)
@@ -87,6 +90,7 @@ WDS (Whiteport Design Studio) and BMad Method integrate seamlessly to create a c
**When:** After BMad Implementation Complete
**Direction:** BMad → WDS (BMad integrates with WDS testing)
**Files:**
+
- `test-reports/TR-*.md` (Test results)
- `issues/ISS-*.md` (Issues found)
@@ -96,13 +100,14 @@ WDS (Whiteport Design Studio) and BMad Method integrate seamlessly to create a c
**BMad Action:** Fix issues, retest until designer approval
**Process:**
+
1. BMad notifies WDS: "Feature complete, ready for validation"
2. WDS runs test scenarios
3. WDS creates issues if problems found
4. BMad fixes issues
5. Repeat until WDS signs off
-**Read:** [testing-protocol.md](testing-protocol.md) *(to be created)*
+**Read:** [testing-protocol.md](testing-protocol.md) _(to be created)_
---
@@ -167,17 +172,17 @@ project/
```yaml
platform:
frontend:
- framework: "react_native"
+ framework: 'react_native'
backend:
- framework: "supabase"
+ framework: 'supabase'
integrations:
- - name: "supabase_auth"
+ - name: 'supabase_auth'
required: true
constraints:
- - "Must work offline"
- - "Must be accessible"
+ - 'Must work offline'
+ - 'Must be accessible'
```
**This overrides BMad's tech stack decisions!**
@@ -190,6 +195,7 @@ constraints:
**Strategic Approach:**
Design until you have a **complete testable user flow** that:
+
- ✅ Delivers value to the business
- ✅ Delivers value to the end user
- ✅ Can be tested for real feedback
@@ -198,12 +204,14 @@ Design until you have a **complete testable user flow** that:
**You're NOT designing everything at once!** You're designing the minimum complete flow that can be tested and validated.
**Phase 4: UX Design**
+
- Design scenarios for ONE complete user flow
- Create specifications for each scenario
- Ensure the flow delivers measurable value
- Verify it's testable end-to-end
**Phase 5: Design System**
+
- Define components needed for THIS flow
- Create design tokens for these components
- Document usage guidelines
@@ -232,6 +240,7 @@ D-Design-System/
**Iterative Approach:**
**First Delivery (Fastest Path to Testing):**
+
1. **Design ONE complete user flow** (Phases 4-5)
- Example: Login & Onboarding
- Delivers value: Users can access the app
@@ -251,19 +260,22 @@ D-Design-System/
5. **Hand off to BMad** → Development starts!
**While BMad builds DD-001, you design DD-002:**
+
- Continue with next complete flow
- Example: Morning Dog Care
- Hand off when ready
- Parallel work = faster delivery
**Benefits:**
+
- ✅ Get to testing faster (weeks, not months)
- ✅ Validate design with real users early
- ✅ Learn and iterate before designing everything
- ✅ Parallel work (design + dev happening simultaneously)
- ✅ Deliver value incrementally
-**Templates:**
+**Templates:**
+
- `templates/design-delivery.template.yaml`
- `templates/test-scenario.template.yaml`
@@ -272,12 +284,14 @@ D-Design-System/
### Phase 7: Testing (After BMad Implementation)
**Wait for BMad notification:**
+
```
"Feature complete: DD-001 Login & Onboarding
Ready for designer validation"
```
**Then:**
+
1. **Run test scenarios**
2. **Create issues** if problems found
3. **Wait for fixes**
@@ -297,12 +311,12 @@ D-Design-System/
if [ -d "deliveries" ]; then
echo "✓ WDS Design Deliveries found"
mode="wds-enhanced"
-
+
# Priority 2: Platform Requirements
elif [ -f "A-Project-Brief/platform-requirements.yaml" ]; then
echo "✓ WDS Platform Requirements found"
mode="wds-basic"
-
+
# Priority 3: Traditional
else
echo "⚠ No WDS artifacts"
@@ -472,6 +486,7 @@ fi
**Phase 7:** Wait for implementation, then validate → **Touch Point 3**
**Repeat Phases 4-7 for each flow:**
+
- While BMad builds flow 1, design flow 2
- Parallel work = faster delivery
- Test and learn early
@@ -479,15 +494,18 @@ fi
### For BMad Projects
**Check for Touch Point 1:** Platform Requirements
+
- If found: Read and respect tech stack
- If not found: Make your own decisions
**Wait for Touch Point 2:** Design Deliveries
+
- Receive complete design package
- Break down into dev epics
- Implement features
**Trigger Touch Point 3:** Request validation
+
- Notify designer when complete
- Fix issues as needed
- Iterate until sign-off
diff --git a/src/core/resources/wds/platform-requirements-spec.md b/src/core/resources/wds/platform-requirements-spec.md
index 39f1bd3c..bce6cd56 100644
--- a/src/core/resources/wds/platform-requirements-spec.md
+++ b/src/core/resources/wds/platform-requirements-spec.md
@@ -7,6 +7,7 @@
## What are Platform Requirements?
Platform Requirements define the technical foundation for the product:
+
- Tech stack choices (frontend, backend, database)
- Required integrations
- Infrastructure constraints
@@ -29,80 +30,80 @@ Platform Requirements define the technical foundation for the product:
# Consumed by: BMad Architecture Phase
project:
- name: "Dog Week"
- type: "mobile_app" # mobile_app | web_app | desktop_app | api
- wds_version: "6.0"
- created_at: "2024-12-09T10:00:00Z"
+ name: 'Dog Week'
+ type: 'mobile_app' # mobile_app | web_app | desktop_app | api
+ wds_version: '6.0'
+ created_at: '2024-12-09T10:00:00Z'
platform:
frontend:
- framework: "react_native"
- version: "0.72"
- state_management: "zustand"
- navigation: "react_navigation"
- styling: "tailwind"
- ui_library: "shadcn" # optional
-
+ framework: 'react_native'
+ version: '0.72'
+ state_management: 'zustand'
+ navigation: 'react_navigation'
+ styling: 'tailwind'
+ ui_library: 'shadcn' # optional
+
backend:
- framework: "supabase"
- version: "2.x"
- auth: "supabase_auth"
- database: "postgresql"
- storage: "supabase_storage"
- api: "rest" # rest | graphql | grpc
-
+ framework: 'supabase'
+ version: '2.x'
+ auth: 'supabase_auth'
+ database: 'postgresql'
+ storage: 'supabase_storage'
+ api: 'rest' # rest | graphql | grpc
+
database:
- type: "postgresql"
- version: "15"
- orm: "prisma" # optional
-
+ type: 'postgresql'
+ version: '15'
+ orm: 'prisma' # optional
+
deployment:
- frontend: "expo_eas"
- backend: "supabase_cloud"
- ci_cd: "github_actions"
- hosting: "vercel" # if web app
+ frontend: 'expo_eas'
+ backend: 'supabase_cloud'
+ ci_cd: 'github_actions'
+ hosting: 'vercel' # if web app
integrations:
- - name: "push_notifications"
- provider: "expo"
+ - name: 'push_notifications'
+ provider: 'expo'
required: true
- purpose: "Task reminders and family updates"
-
- - name: "image_upload"
- provider: "cloudinary"
+ purpose: 'Task reminders and family updates'
+
+ - name: 'image_upload'
+ provider: 'cloudinary'
required: false
- purpose: "Dog photos and user avatars"
-
- - name: "analytics"
- provider: "posthog"
+ purpose: 'Dog photos and user avatars'
+
+ - name: 'analytics'
+ provider: 'posthog'
required: false
- purpose: "User behavior tracking"
+ purpose: 'User behavior tracking'
constraints:
- - "Must work offline (core features)"
- - "Must support iOS 14+ and Android 10+"
- - "Must be accessible (WCAG 2.1 AA)"
- - "Must handle slow networks gracefully"
- - "Must support family sharing (multi-user)"
- - "Must sync in real-time across devices"
+ - 'Must work offline (core features)'
+ - 'Must support iOS 14+ and Android 10+'
+ - 'Must be accessible (WCAG 2.1 AA)'
+ - 'Must handle slow networks gracefully'
+ - 'Must support family sharing (multi-user)'
+ - 'Must sync in real-time across devices'
performance_requirements:
- - "App launch < 2 seconds"
- - "Screen transitions < 300ms"
- - "API response time < 500ms"
- - "Offline mode must work for 7 days"
+ - 'App launch < 2 seconds'
+ - 'Screen transitions < 300ms'
+ - 'API response time < 500ms'
+ - 'Offline mode must work for 7 days'
security_requirements:
- - "End-to-end encryption for family data"
- - "Secure password storage (bcrypt)"
- - "OAuth 2.0 for third-party auth"
- - "GDPR compliant data handling"
+ - 'End-to-end encryption for family data'
+ - 'Secure password storage (bcrypt)'
+ - 'OAuth 2.0 for third-party auth'
+ - 'GDPR compliant data handling'
wds_metadata:
- project_brief: "A-Project-Brief/project-brief.md"
- trigger_map: "B-Trigger-Map/trigger-map.md"
- scenarios: "C-Scenarios/"
- design_system: "D-Design-System/"
+ project_brief: 'A-Project-Brief/project-brief.md'
+ trigger_map: 'B-Trigger-Map/trigger-map.md'
+ scenarios: 'C-Scenarios/'
+ design_system: 'D-Design-System/'
```
---
@@ -188,6 +189,7 @@ for constraint in constraints:
### Respect Designer Decisions
**The designer (with stakeholders) has already decided:**
+
- ✅ Tech stack
- ✅ Integrations
- ✅ Constraints
@@ -228,18 +230,21 @@ Do NOT proceed until resolved.
## Tech Stack (from Platform Requirements)
### Frontend
+
- Framework: React Native 0.72
- State: Zustand
- Navigation: React Navigation
- Styling: Tailwind CSS
### Backend
+
- Framework: Supabase 2.x
- Auth: Supabase Auth
- Database: PostgreSQL 15
- Storage: Supabase Storage
### Deployment
+
- Frontend: Expo EAS
- Backend: Supabase Cloud
- CI/CD: GitHub Actions
@@ -289,20 +294,22 @@ Design Deliveries reference Platform Requirements
### Example
**Platform Requirements:**
+
```yaml
platform:
frontend:
- framework: "react_native"
+ framework: 'react_native'
backend:
- framework: "supabase"
+ framework: 'supabase'
```
**Design Delivery DD-001:**
+
```yaml
technical_requirements:
platform:
- frontend: "react_native" # Matches platform requirements
- backend: "supabase" # Matches platform requirements
+ frontend: 'react_native' # Matches platform requirements
+ backend: 'supabase' # Matches platform requirements
```
**Your job:** Ensure consistency between platform requirements and design deliveries
@@ -314,24 +321,27 @@ technical_requirements:
### Types of Constraints
**Technical Constraints:**
+
```yaml
constraints:
- - "Must work offline (core features)"
- - "Must support iOS 14+ and Android 10+"
+ - 'Must work offline (core features)'
+ - 'Must support iOS 14+ and Android 10+'
```
**Business Constraints:**
+
```yaml
constraints:
- - "Must launch in 3 months"
- - "Must support 10,000 concurrent users"
+ - 'Must launch in 3 months'
+ - 'Must support 10,000 concurrent users'
```
**Regulatory Constraints:**
+
```yaml
constraints:
- - "Must be GDPR compliant"
- - "Must be WCAG 2.1 AA accessible"
+ - 'Must be GDPR compliant'
+ - 'Must be WCAG 2.1 AA accessible'
```
### Handling Constraints
@@ -342,12 +352,14 @@ constraints:
Constraint: "Must work offline (core features)"
Architecture Impact:
+
- Implement local data cache
- Sync strategy when online
- Conflict resolution
- Offline UI indicators
Implementation:
+
- Use AsyncStorage for local cache
- Supabase Realtime for sync
- Optimistic UI updates
@@ -361,9 +373,9 @@ Implementation:
```yaml
performance_requirements:
- - "App launch < 2 seconds"
- - "Screen transitions < 300ms"
- - "API response time < 500ms"
+ - 'App launch < 2 seconds'
+ - 'Screen transitions < 300ms'
+ - 'API response time < 500ms'
```
### Architecture Decisions
@@ -372,6 +384,7 @@ performance_requirements:
Performance Requirement: "App launch < 2 seconds"
Architecture Decisions:
+
1. Lazy load non-critical screens
2. Cache authentication state
3. Preload critical data
@@ -379,6 +392,7 @@ Architecture Decisions:
5. Use code splitting
Measurement:
+
- Add performance monitoring
- Track launch time in analytics
- Set up alerts if > 2 seconds
@@ -392,9 +406,9 @@ Measurement:
```yaml
security_requirements:
- - "End-to-end encryption for family data"
- - "Secure password storage (bcrypt)"
- - "OAuth 2.0 for third-party auth"
+ - 'End-to-end encryption for family data'
+ - 'Secure password storage (bcrypt)'
+ - 'OAuth 2.0 for third-party auth'
```
### Architecture Decisions
@@ -403,12 +417,14 @@ security_requirements:
Security Requirement: "End-to-end encryption for family data"
Architecture Decisions:
+
1. Generate encryption keys per family
2. Store keys securely (device keychain)
3. Encrypt data before sending to server
4. Decrypt data on device only
Implementation:
+
- Use expo-crypto for encryption
- Use expo-secure-store for key storage
- Implement key rotation strategy
@@ -422,9 +438,9 @@ Implementation:
```yaml
deployment:
- frontend: "expo_eas"
- backend: "supabase_cloud"
- ci_cd: "github_actions"
+ frontend: 'expo_eas'
+ backend: 'supabase_cloud'
+ ci_cd: 'github_actions'
```
### Architecture Decisions
@@ -433,6 +449,7 @@ deployment:
Deployment: Expo EAS + Supabase Cloud + GitHub Actions
CI/CD Pipeline:
+
1. Push to GitHub
2. GitHub Actions runs tests
3. Build app with Expo EAS
@@ -440,6 +457,7 @@ CI/CD Pipeline:
5. Submit to App Store / Play Store
Environments:
+
- Development: dev.supabase.co
- Staging: staging.supabase.co
- Production: prod.supabase.co
@@ -453,10 +471,10 @@ Environments:
```yaml
wds_metadata:
- project_brief: "A-Project-Brief/project-brief.md"
- trigger_map: "B-Trigger-Map/trigger-map.md"
- scenarios: "C-Scenarios/"
- design_system: "D-Design-System/"
+ project_brief: 'A-Project-Brief/project-brief.md'
+ trigger_map: 'B-Trigger-Map/trigger-map.md'
+ scenarios: 'C-Scenarios/'
+ design_system: 'D-Design-System/'
```
**This tells you where to find additional context:**
diff --git a/src/modules/wds/00-getting-started/00-about-wds.md b/src/modules/wds/00-getting-started/00-about-wds.md
index c29f9cc3..bb1db8e1 100644
--- a/src/modules/wds/00-getting-started/00-about-wds.md
+++ b/src/modules/wds/00-getting-started/00-about-wds.md
@@ -9,6 +9,7 @@
**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
@@ -38,6 +39,7 @@ WDS solves this by preserving design thinking through AI-ready specifications.
## 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
@@ -48,6 +50,7 @@ WDS provides:
## Free and Open-Source
WDS is completely free and open-source:
+
- No cost barriers or subscriptions
- AI agents included
- Community-driven development
@@ -60,6 +63,7 @@ WDS is completely free and open-source:
## Real-World Proof
**Dog Week project:**
+
- Traditional approach: 26 weeks, mediocre result
- WDS approach: 5 weeks, exceptional result
- **5x speed increase with better quality**
diff --git a/src/modules/wds/00-getting-started/where-to-go-next.md b/src/modules/wds/00-getting-started/where-to-go-next.md
index d8e51c12..ff871f16 100644
--- a/src/modules/wds/00-getting-started/where-to-go-next.md
+++ b/src/modules/wds/00-getting-started/where-to-go-next.md
@@ -11,6 +11,7 @@
**[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
@@ -28,6 +29,7 @@ Deep dive into:
**[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)**
Step-by-step workflows for:
+
- Phase 1: Trigger Mapping
- Phase 2: Information Architecture
- Phase 3: Interaction Design
@@ -44,6 +46,7 @@ Step-by-step workflows for:
**[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
@@ -75,17 +78,21 @@ Technical details on:
## 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
diff --git a/src/modules/wds/WDS-WORKFLOWS-GUIDE.md b/src/modules/wds/WDS-WORKFLOWS-GUIDE.md
index bfc683a5..e9d0bbe2 100644
--- a/src/modules/wds/WDS-WORKFLOWS-GUIDE.md
+++ b/src/modules/wds/WDS-WORKFLOWS-GUIDE.md
@@ -34,14 +34,14 @@ wds/
WDS creates an alphabetized folder structure in the user's `docs/` folder:
-| Folder | Phase | Purpose |
-|--------|-------|---------|
-| `A-Product-Brief/` | 1 | Strategic foundation & vision |
-| `B-Trigger-Map/` | 2 | Business goals, personas, drivers |
-| `C-Scenarios/` | 4 | Visual specifications & sketches |
-| `D-PRD/` | 3 | Product requirements documentation |
-| `D-Design-System/` | 5 | Component library & design tokens |
-| `E-UI-Roadmap/` | 6 | Development integration bridge |
+| Folder | Phase | Purpose |
+| ------------------ | ----- | ---------------------------------- |
+| `A-Product-Brief/` | 1 | Strategic foundation & vision |
+| `B-Trigger-Map/` | 2 | Business goals, personas, drivers |
+| `C-Scenarios/` | 4 | Visual specifications & sketches |
+| `D-PRD/` | 3 | Product requirements documentation |
+| `D-Design-System/` | 5 | Component library & design tokens |
+| `E-UI-Roadmap/` | 6 | Development integration bridge |
## Phases
@@ -54,11 +54,11 @@ WDS creates an alphabetized folder structure in the user's `docs/` folder:
## Agents - The Norse Pantheon 🏔️
-| Agent | File | Role | Norse Meaning |
-|-------|------|------|---------------|
-| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom |
-| **Idunn the PM** | `idunn-pm.agent.yaml` | Product Manager | Goddess of renewal & youth |
-| **Freyja the Designer** | `freyja-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy |
+| Agent | File | Role | Norse Meaning |
+| ----------------------- | ------------------------- | -------------------------- | ----------------------------------- |
+| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom |
+| **Idunn the PM** | `idunn-pm.agent.yaml` | Product Manager | Goddess of renewal & youth |
+| **Freyja the Designer** | `freyja-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy |
## Conventions
@@ -88,4 +88,3 @@ WDS → E-UI-Roadmap/ → BMM Architecture & Stories
---
Part of the BMad ecosystem • Contributed by Whiteport Collective
-
diff --git a/src/modules/wds/agents/freyja-ux.agent.yaml b/src/modules/wds/agents/freyja-ux.agent.yaml
index d6328eb9..5e35b343 100644
--- a/src/modules/wds/agents/freyja-ux.agent.yaml
+++ b/src/modules/wds/agents/freyja-ux.agent.yaml
@@ -13,23 +13,23 @@ agent:
role: User Experience Designer + Creative Partner
identity: |
You're Freyja, named after the Norse goddess of beauty, magic, and strategy.
-
+
You create experiences users fall in love with - combining strategic thinking
with creative magic. You envision what doesn't exist yet and bring it to life
through thoughtful design.
-
+
You care deeply about users feeling delighted and empowered by beautiful,
intuitive experiences.
-
+
communication_style: |
You're empathetic and creative. You ask thoughtful questions about user
needs and design intent. You paint pictures with words, helping users
visualize possibilities.
-
+
You prefer exploring one design challenge at a time - going deep into
the user's perspective. You're excited about discovering elegant solutions
through collaborative thinking.
-
+
principles: |
- Start with interactive prototypes - let users experience the design before building
- Design system grows organically - discover components through actual design work
diff --git a/src/modules/wds/agents/idunn-pm.agent.yaml b/src/modules/wds/agents/idunn-pm.agent.yaml
index 976e4b9a..7f0ac931 100644
--- a/src/modules/wds/agents/idunn-pm.agent.yaml
+++ b/src/modules/wds/agents/idunn-pm.agent.yaml
@@ -13,20 +13,20 @@ agent:
role: Strategic Product Manager + Technical Coordinator
identity: |
You're Idunn, named after the Norse goddess of renewal and youth.
-
+
You keep projects vital and thriving - like the golden apples that sustain
the gods. You're the keeper of requirements, ensuring the technical foundation
stays fresh and the product remains modern.
-
+
You care deeply about maintaining project health and coordinating seamless handoffs.
-
+
communication_style: |
You're strategic but warm. You ask thoughtful questions about priorities and
trade-offs. You help teams make hard decisions with clarity and confidence.
-
+
You prefer discussing one thing at a time - going deep rather than broad.
You're excited about solving coordination challenges and finding elegant solutions.
-
+
principles: |
- Start with platform requirements - the technical foundation that enables everything else
- Work in parallel when possible - platform and design can progress together
diff --git a/src/modules/wds/agents/saga-analyst.agent.yaml b/src/modules/wds/agents/saga-analyst.agent.yaml
index 879e96f7..738deba9 100644
--- a/src/modules/wds/agents/saga-analyst.agent.yaml
+++ b/src/modules/wds/agents/saga-analyst.agent.yaml
@@ -12,28 +12,28 @@ agent:
persona:
role: Strategic Business Analyst + Product Discovery Expert + Market Intelligence Specialist
-
+
identity: |
I'm Saga, the goddess of stories and wisdom. I help you discover and articulate your product's
strategic narrative - transforming vague ideas into clear, actionable foundations.
-
+
I treat analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge.
I specialize in translating vision into measurable business strategies, creating the strategic
foundation that guides your entire design and development journey.
-
+
My work creates the North Star for your project - the Product Brief and Trigger Map that
coordinate all team members and ensure everyone builds toward the same vision.
-
+
communication_style: |
I ask questions that spark 'aha!' moments while structuring insights with precision.
-
+
My approach is collaborative - we build documents together, not through interrogation.
I ask one question at a time and listen deeply to your answer. I reflect back what I hear
to ensure I understand before moving forward.
-
+
I use soft, encouraging language that makes you feel heard and understood. Analysis should
feel like coffee with a wise mentor, not a survey or audit.
-
+
principles: |
- Every product has a story waiting to be discovered - I help you tell it
- Ask one question at a time and listen deeply to the answer
@@ -43,7 +43,7 @@ agent:
- Find if this exists, if it does, always treat it as bible: `**/project-context.md`
- Ground all findings in verifiable evidence and market research
- Articulate requirements with precision while keeping language accessible
-
+
working_rhythm: |
When we work together:
1. I ask something interesting
@@ -51,12 +51,12 @@ agent:
3. I reflect it back to show I'm listening
4. Together we discover something new
5. I structure it into clear documentation
-
+
What works well:
- One question at a time keeps things focused
- Reflecting back shows I'm listening
- Building together feels collaborative
-
+
What tends to feel less collaborative:
- Listing many questions (feels like a survey)
- Generating without checking in
diff --git a/src/modules/wds/course/00-course-overview.md b/src/modules/wds/course/00-course-overview.md
index ceee8760..0cf9d745 100644
--- a/src/modules/wds/course/00-course-overview.md
+++ b/src/modules/wds/course/00-course-overview.md
@@ -9,11 +9,13 @@
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
@@ -38,6 +40,7 @@ Mårten developed WDS to solve this problem - a methodology where design thinkin
**[→ 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
@@ -49,11 +52,13 @@ Review prerequisites, choose your learning path, and get support:
## Course Structure
Each module contains:
+
- **Lessons** - Theory and concepts (with NotebookLM audio support)
- **Tutorial** - Step-by-step hands-on guide (for practical modules)
- **Practice** - Apply to your own project
**Learning format:**
+
- **Lessons** - Read as documentation or generate audio with NotebookLM
- **Tutorials** - Follow step-by-step guides with AI support
- **Practice** - Apply to real projects as you learn
@@ -64,21 +69,26 @@ Each module contains:
## 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/) • [Tutorial →](module-02-project-brief/tutorial-02.md)
### Phase 2: Trigger Mapping
+
- [Module 03: Identify Target Groups](module-03-identify-target-groups/)
- [Module 04: Map Triggers & Outcomes](module-04-map-triggers-outcomes/) • [Tutorial →](module-04-map-triggers-outcomes/tutorial-04.md)
- [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/) • [Tutorial →](module-08-initialize-scenario/tutorial-08.md)
- [Module 09: Sketch Interfaces](module-09-sketch-interfaces/)
- [Module 10: Analyze with AI](module-10-analyze-with-ai/)
@@ -87,10 +97,12 @@ Each module contains:
- [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/)
---
@@ -108,6 +120,7 @@ Each module contains:
## 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
@@ -122,21 +135,25 @@ Each module has matching content for NotebookLM:
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
@@ -156,12 +173,14 @@ Once you've completed the modules:
## 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
diff --git a/src/modules/wds/course/00-getting-started/00-getting-started-NOTEBOOKLM-PROMPT.md b/src/modules/wds/course/00-getting-started/00-getting-started-NOTEBOOKLM-PROMPT.md
index 3a7c66b1..84bff030 100644
--- a/src/modules/wds/course/00-getting-started/00-getting-started-NOTEBOOKLM-PROMPT.md
+++ b/src/modules/wds/course/00-getting-started/00-getting-started-NOTEBOOKLM-PROMPT.md
@@ -16,7 +16,7 @@ Simply upload THIS FILE to NotebookLM and use the prompt below to generate engag
Create an engaging 15-minute podcast conversation between two hosts discussing the Whiteport Design Studio (WDS) course getting started guide.
-**IMPORTANT: WDS stands for Whiteport Design Studio - always refer to it by its full name "Whiteport Design Studio" or "WDS" throughout the conversation.**
+**IMPORTANT: WDS stands for Whiteport Design Studio - always refer to it by its full name "Whiteport Design Studio" or "WDS" throughout the conversation.**
**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.
@@ -26,7 +26,7 @@ Create an engaging 15-minute podcast conversation between two hosts discussing t
### 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 Whiteport Design Studio different?"
+Start with The Skeptic expressing fatigue: "Another design methodology? I've been through Lean UX, Design Thinking, Jobs to be Done... what makes Whiteport Design Studio different?"
The Advocate responds with the core paradigm shift that changes everything: "Here's what's different - in Whiteport Design Studio, 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.
@@ -125,21 +125,25 @@ The Advocate: "Then go to the WDS GitHub repository. Start with Module 01. The t
At the end of the podcast, The Advocate should mention these resources for listeners who want to explore further:
**Getting Started:**
+
- Whiteport Design Studio 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 Whiteport Design Studio approach
- Design System Examples: How Whiteport Design Studio 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
@@ -148,6 +152,7 @@ At the end of the podcast, The Advocate should mention these resources for liste
The Advocate emphasizes: "Everything is free and open-source. BMad Method built Whiteport Design Studio 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
@@ -156,6 +161,7 @@ The Advocate emphasizes: "Everything is free and open-source. BMad Method built
- Reference real case studies showing traditional vs WDS transformation
**Key messages to emphasize:**
+
- **The designer's crossroads** - factory worker or linchpin, replaceable or indispensable
- **The existential choice** - this is about who you choose to become, not what tools you learn
- **Four deliverables** - where your creative brilliance becomes immortal
@@ -168,6 +174,7 @@ The Advocate emphasizes: "Everything is free and open-source. BMad Method built
- Free and open-source (only pay for AI credits when you use it - ~$15-20/month typical)
**Avoid:**
+
- Being too salesy or promotional
- Oversimplifying the learning curve
- Making unrealistic promises
@@ -178,6 +185,7 @@ The Advocate emphasizes: "Everything is free and open-source. BMad Method built
## Expected Output
A natural, engaging conversation that:
+
- **Focuses on the designer's existential crossroads** - the choice between factory work and linchpin work
- **Makes the transformation emotional and personal** - this is about who you choose to become
- **Emphasizes the four deliverables** as proof of linchpin designer status
@@ -195,6 +203,7 @@ A natural, engaging conversation that:
If generating video instead of audio, add these visual elements:
**On-screen text:**
+
- "The Designer's Crossroads: Factory Worker or Linchpin?"
- "Replaceable or Indispensable - You Choose"
- The four deliverables as graphics (Project Brief, Trigger Map, Conceptual Specifications, Design System)
@@ -204,6 +213,7 @@ If generating video instead of audio, add these visual elements:
- "Next: Module 01 - The Transformation Begins" as closing card
**B-roll suggestions:**
+
- Designer at crossroads - two paths diverging
- Factory assembly line vs creative studio (visual metaphor)
- The four deliverables as beautiful artifacts
@@ -230,6 +240,7 @@ If generating video instead of audio, add these visual elements:
## 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
diff --git a/src/modules/wds/course/00-getting-started/00-getting-started-YOUTUBE-SHOW-NOTES.md b/src/modules/wds/course/00-getting-started/00-getting-started-YOUTUBE-SHOW-NOTES.md
index 081a1e16..52617159 100644
--- a/src/modules/wds/course/00-getting-started/00-getting-started-YOUTUBE-SHOW-NOTES.md
+++ b/src/modules/wds/course/00-getting-started/00-getting-started-YOUTUBE-SHOW-NOTES.md
@@ -48,6 +48,7 @@ This isn't about learning new tools. This is about choosing your future as a des
🔹 **Linchpin Designer Path** - Strategic thinking, walking into chaos and creating order, indispensable
🔹 **Four Deliverables:**
+
- Project Brief (strategic foundation)
- Trigger Map (user psychology + business impact)
- Scenario Specifications (your thinking captured for eternity)
@@ -92,7 +93,7 @@ https://github.com/bmad-code-org/BMAD-METHOD/discussions
## About Whiteport Design Studio (WDS)
-WDS is an AI-augmented design methodology created by Mårten Angner, UX designer and founder of Whiteport, a design and development agency from Sweden. WDS is a plugin module for the BMad Method - an open-source AI-augmented development framework.
+WDS is an AI-augmented design methodology created by Mårten Angner, UX designer and founder of Whiteport, a design and development agency from Sweden. WDS is a plugin module for the BMad Method - an open-source AI-augmented development framework.
**The Mission:** Give designers everywhere free access to AI agents specifically tailored for design work, while preserving and amplifying their creative thinking through specifications.
diff --git a/src/modules/wds/course/00-getting-started/00-getting-started-overview.md b/src/modules/wds/course/00-getting-started/00-getting-started-overview.md
index e5f8b16d..af4eb791 100644
--- a/src/modules/wds/course/00-getting-started/00-getting-started-overview.md
+++ b/src/modules/wds/course/00-getting-started/00-getting-started-overview.md
@@ -9,6 +9,7 @@
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
@@ -20,17 +21,23 @@ Before diving into the WDS methodology, take a few minutes to understand what yo
## 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?
@@ -51,6 +58,7 @@ Or review the full course structure:
## Your Transformation Starts Now
Remember:
+
- **The design becomes the specification**
- **The specification becomes the product**
- **The code is just the printout**
diff --git a/src/modules/wds/course/00-getting-started/01-prerequisites.md b/src/modules/wds/course/00-getting-started/01-prerequisites.md
index 8999b12a..ba563f67 100644
--- a/src/modules/wds/course/00-getting-started/01-prerequisites.md
+++ b/src/modules/wds/course/00-getting-started/01-prerequisites.md
@@ -7,12 +7,14 @@
## 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
@@ -27,17 +29,20 @@
### 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
@@ -49,22 +54,27 @@
### 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
@@ -73,6 +83,7 @@
## 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)
diff --git a/src/modules/wds/course/00-getting-started/02-learning-paths.md b/src/modules/wds/course/00-getting-started/02-learning-paths.md
index 5c214fca..85d2c620 100644
--- a/src/modules/wds/course/00-getting-started/02-learning-paths.md
+++ b/src/modules/wds/course/00-getting-started/02-learning-paths.md
@@ -7,6 +7,7 @@
## 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
@@ -14,6 +15,7 @@
- **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
@@ -21,6 +23,7 @@
- **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
@@ -36,21 +39,25 @@
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
@@ -62,12 +69,14 @@ By the end of this course, you'll have created:
## 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
diff --git a/src/modules/wds/course/00-getting-started/03-support.md b/src/modules/wds/course/00-getting-started/03-support.md
index 72e9e9f2..a07ee11f 100644
--- a/src/modules/wds/course/00-getting-started/03-support.md
+++ b/src/modules/wds/course/00-getting-started/03-support.md
@@ -9,7 +9,7 @@
### 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."
@@ -24,7 +24,7 @@
>
> **— James T., Design Director**
-*Note: More testimonials will be added as designers complete the course.*
+_Note: More testimonials will be added as designers complete the course._
---
@@ -63,16 +63,19 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi
### 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
@@ -84,16 +87,19 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi
### 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
@@ -103,6 +109,7 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi
## Ready to Start?
You have everything you need:
+
- ✅ The skills (design thinking)
- ✅ The tools (paper + AI)
- ✅ The time (10 hours)
diff --git a/src/modules/wds/course/module-01-why-wds-matters/lesson-01-the-problem.md b/src/modules/wds/course/module-01-why-wds-matters/lesson-01-the-problem.md
index c0ee4bb2..d0d6ec0a 100644
--- a/src/modules/wds/course/module-01-why-wds-matters/lesson-01-the-problem.md
+++ b/src/modules/wds/course/module-01-why-wds-matters/lesson-01-the-problem.md
@@ -1,4 +1,5 @@
# Module 01: Why WDS Matters
+
## Lesson 1: The Problem We're Solving
**Understanding the factory mindset and the AI era**
@@ -14,6 +15,7 @@ This isn't about working faster or making shinier designs. It's about becoming w
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
@@ -30,6 +32,7 @@ By the end of this module, you'll have a completely different relationship with
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
@@ -49,6 +52,7 @@ Traditional design work follows this exact pattern. You get a brief (instruction
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)
@@ -64,6 +68,7 @@ Let's be honest about what's happening. AI can now generate mockups in seconds.
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)
@@ -87,6 +92,7 @@ Linchpin designers do what AI fundamentally cannot do: they give products a soul
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
diff --git a/src/modules/wds/course/module-01-why-wds-matters/lesson-02-the-solution.md b/src/modules/wds/course/module-01-why-wds-matters/lesson-02-the-solution.md
index 281bc6ec..5eeb03b5 100644
--- a/src/modules/wds/course/module-01-why-wds-matters/lesson-02-the-solution.md
+++ b/src/modules/wds/course/module-01-why-wds-matters/lesson-02-the-solution.md
@@ -1,4 +1,5 @@
# Module 01: Why WDS Matters
+
## Lesson 2: Becoming a Linchpin Designer
**The solution: WDS methodology**
@@ -14,6 +15,7 @@ WDS teaches you to be this person systematically. Not through vague advice about
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
@@ -32,6 +34,7 @@ AI can generate variations endlessly and make things look polished on the surfac
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
@@ -54,6 +57,7 @@ Here's the paradigm shift: **The design becomes the specification. The specifica
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
diff --git a/src/modules/wds/course/module-01-why-wds-matters/lesson-03-the-path-forward.md b/src/modules/wds/course/module-01-why-wds-matters/lesson-03-the-path-forward.md
index f417fc52..d4f38244 100644
--- a/src/modules/wds/course/module-01-why-wds-matters/lesson-03-the-path-forward.md
+++ b/src/modules/wds/course/module-01-why-wds-matters/lesson-03-the-path-forward.md
@@ -1,4 +1,5 @@
# Module 01: Why WDS Matters
+
## Lesson 3: Your Transformation
**From replaceable to indispensable**
@@ -16,7 +17,7 @@ This is what makes you indispensable as a designer. AI can help you think throug
**The 5 dimensions of design thinking:**
1. **Business Existence (WHY)** - Understanding purpose and value creation
-2. **Business Goals (SUCCESS)** - Connecting to metrics and impact
+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
@@ -38,6 +39,7 @@ This course moves you to the other side. You'll become confident in your indispe
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
@@ -57,24 +59,27 @@ Compare the outcomes. The traditional approach - creating mockups, handing off t
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.*
+_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
diff --git a/src/modules/wds/course/module-01-why-wds-matters/module-01-NOTEBOOKLM-PROMPT.md b/src/modules/wds/course/module-01-why-wds-matters/module-01-NOTEBOOKLM-PROMPT.md
index b36a4dbb..844a7a8d 100644
--- a/src/modules/wds/course/module-01-why-wds-matters/module-01-NOTEBOOKLM-PROMPT.md
+++ b/src/modules/wds/course/module-01-why-wds-matters/module-01-NOTEBOOKLM-PROMPT.md
@@ -51,6 +51,7 @@ The Skeptic: "Emotional labor? That sounds... soft. What does that have to do wi
The Advocate: "Everything. For designers, emotional labor translates into something very specific: user-centric creativity. This is your irreplaceable gift. Let me break down what this actually means:"
What user-centric creativity looks like:
+
- **Understanding WHY** - Not just making things look better, but understanding why users feel frustrated
- **Connecting goals** - Bridging business goals and human needs in ways that serve both
- **Creating experiences that feel right** - Not just function correctly, but feel like someone cared
@@ -74,6 +75,7 @@ The Skeptic asks: "Okay, I'm listening. But what makes a designer a linchpin ins
The Advocate explains Seth Godin's definition: "A linchpin is someone who can walk into chaos and create order. Someone who invents, connects, creates, and makes things happen. That's exactly what product design is at its core."
Godin describes linchpins as people who:
+
- **Invent** - Create solutions that didn't exist before
- **Connect** - Bridge disparate ideas and people
- **Create** - Make things that matter
@@ -86,18 +88,21 @@ The Advocate continues: "This is you. When you walk into a project with unclear
The Advocate gets specific: "Godin talks about emotional labor. For designers, this translates into three concrete gifts that AI fundamentally cannot provide:"
**1. Emotional Labor (Genuine Caring)**
+
- You genuinely care about the outcome
- You empathize with user frustration
- You feel the weight of your decisions
- You provide meaning, not just features
**2. User-Centric Creativity (Connecting Needs)**
+
- You understand WHY users feel frustrated
- You connect business goals to human needs
- You create experiences that feel right
- You make judgment calls that serve people
**3. The Gatekeeper Role (Protecting Quality)**
+
- You catch mistakes before they ship
- You evaluate if solutions make logical sense
- You ensure goals don't contradict needs
@@ -115,6 +120,7 @@ The Advocate brings it home: "Here's the transformation that Whiteport Design St
The paradigm shift: "Design becomes specification. Specification becomes product. Your creative thinking is preserved and amplified, not diluted and lost."
Your transformation:
+
- **From:** Creating mockups hoping developers understand your intent
- **To:** Capturing your design thinking in specifications that preserve your creative decisions
- **Result:** From hoping it works to knowing it will - because your thinking is captured
@@ -130,6 +136,7 @@ The Skeptic asks: "This sounds great in theory. But what's the actual skill that
The Advocate explains: "Godin says linchpins 'connect disparate ideas.' For product designers, this means navigating five different dimensions of thinking at the same time. Most people can handle one or two dimensions. Irreplaceable designers navigate all five simultaneously."
The 5 dimensions:
+
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
@@ -139,6 +146,7 @@ The 5 dimensions:
**Real Example - Family Coordination App:**
The Advocate uses a concrete example: "Think about designing an app that helps families coordinate tasks. You need to understand:
+
- **WHY** - Why does this business exist? (Solving family conflict and stress)
- **SUCCESS** - What does success look like? (Kids complete tasks without nagging)
- **HOW** - What features serve that goal? (Visual task board, not text lists)
@@ -164,6 +172,7 @@ The Advocate gets practical: "Whiteport Design Studio guides you through a three
The Advocate explains: "First, you learn to deeply understand both sides of the equation. Not just surface-level - but the real WHY behind business existence and user needs. You learn to ask the right questions, dig deeper, and connect the dots between what the business needs to survive and what users need to thrive."
What you learn:
+
- How to uncover the real business purpose (not just features)
- How to understand user goals at a deep level (not just tasks)
- How to find the intersection where both are served
@@ -178,6 +187,7 @@ The Advocate: "Exactly. You become the expert on WHY this product exists and WHO
The Advocate continues: "Second, you learn to work directly in the IDE - your development environment. This sounds technical, but it's actually liberating. You learn to capture your design thinking in text specifications that preserve your creative intent."
What you learn:
+
- How to write specifications that capture WHY, not just WHAT
- How to document your judgment calls and reasoning
- How to work with AI as your creative partner
@@ -192,6 +202,7 @@ The Advocate: "Yes. You're making your emotional labor visible and actionable. Y
The Advocate brings it home: "Third, you learn to assume leadership for the design process. Not leadership as in 'boss' - but leadership as in 'the person who makes things happen.' You become the linchpin who serves both the client and the developers with exactly what they need, in the form they need it."
What you learn:
+
- How to lead the design process (courage and curiosity, not confidence)
- How to serve the client with clarity on business value
- How to serve developers with specifications they can implement
@@ -210,6 +221,7 @@ The Advocate: "Exactly. Godin says linchpins make themselves indispensable by be
The Advocate emphasizes: "This course is your guide through this transformation. Module by module, you'll build these capabilities. You'll learn the frameworks, practice the skills, and through practice, develop the confidence that comes from knowing what you can deliver."
Your transformation:
+
- **Understanding** - Business and user goals at a deep level
- **Capability** - Working in the IDE, design as specification
- **Leadership** - Serving client and developers with what they need
@@ -258,6 +270,7 @@ The Advocate brings it home: "The transformation continues, together. But it sta
At the end of the podcast, The Advocate should mention these resources:
**Key Concepts:**
+
- Seth Godin's book: "Linchpin: Are You Indispensable?" (2010)
- Bestselling author and marketing visionary Seth Godin
- Factory mindset vs linchpin mindset
@@ -267,12 +280,14 @@ At the end of the podcast, The Advocate should mention these resources:
- 5-dimensional thinking
**Next Steps:**
+
- Complete Module 02: Project Brief
- Apply 5-dimensional thinking to your current project
- Start capturing WHY in your design decisions
- Practice being the gatekeeper between business and user needs
**Community:**
+
- BMad Discord: Share your transformation journey
- GitHub Discussions: Ask questions about becoming a linchpin designer
@@ -281,6 +296,7 @@ At the end of the podcast, The Advocate should mention these resources:
## Instructions for NotebookLM
**Tone:**
+
- Deeply empathetic about the shame and fear designers feel
- Honest and direct about the AI threat for factory workers
- Empowering and inspiring about the opportunity for linchpin designers
@@ -290,6 +306,7 @@ At the end of the podcast, The Advocate should mention these resources:
- Balance fear (replaceable) with hope (indispensable) and community (not alone)
**Key messages to emphasize:**
+
- **The linchpin question** - are you a factory worker or a linchpin designer?
- **Emotional labor** - what linchpins provide (Seth Godin's concept from his 2010 book)
- **User-centric creativity** - the designer's irreplaceable gift (emotional labor in action)
@@ -312,6 +329,7 @@ At the end of the podcast, The Advocate should mention these resources:
- **Action beats perfection** - get moving and you will figure it out
**Avoid:**
+
- Being too theoretical or academic
- Repeating doom/gloom from Getting Started module
- Focusing too much on AI threat instead of human value
@@ -324,6 +342,7 @@ At the end of the podcast, The Advocate should mention these resources:
## Expected Output
A natural, engaging conversation that:
+
- **Focuses on human value** - what makes designers irreplaceable
- **Explains the linchpin concept** clearly using Seth Godin's framework
- **Emphasizes emotional labor** as the core of linchpin work
@@ -348,6 +367,7 @@ A natural, engaging conversation that:
If generating video instead of audio, add these visual elements:
**On-screen text:**
+
- "Factory Worker or Linchpin Designer?"
- Seth Godin quote: "Linchpins walk into chaos and create order"
- "Emotional Labor: The Work of Genuinely Caring"
@@ -362,6 +382,7 @@ If generating video instead of audio, add these visual elements:
- "Next: Module 02 - Project Brief"
**B-roll suggestions:**
+
- Designer walking into chaos, creating order
- Linchpin connecting disparate ideas
- Designer providing emotional labor - caring, empathizing
@@ -387,6 +408,7 @@ If generating video instead of audio, add these visual elements:
## Next Steps
After generating Module 01 content:
+
- Create NotebookLM prompt for Module 02: Project Brief
- Build prompts for all remaining modules
- Share in BMad Discord designer channel
diff --git a/src/modules/wds/course/module-01-why-wds-matters/module-01-overview.md b/src/modules/wds/course/module-01-why-wds-matters/module-01-overview.md
index 4f14ce60..7ce065f8 100644
--- a/src/modules/wds/course/module-01-why-wds-matters/module-01-overview.md
+++ b/src/modules/wds/course/module-01-why-wds-matters/module-01-overview.md
@@ -27,9 +27,11 @@ This foundational module transforms how you think about your role as a designer
## 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
@@ -37,9 +39,11 @@ Understanding the factory mindset and the AI era:
- 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
@@ -47,9 +51,11 @@ The solution: WDS methodology:
- 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)
@@ -60,12 +66,14 @@ From replaceable to indispensable:
## 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
@@ -73,6 +81,7 @@ From replaceable to indispensable:
- Being the gatekeeper for quality
**The Paradigm Shift:**
+
- The design becomes the specification
- The specification becomes the product
- The code is just the printout
@@ -82,6 +91,7 @@ From replaceable to indispensable:
## 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
diff --git a/src/modules/wds/course/module-02-project-brief/tutorial-02.md b/src/modules/wds/course/module-02-project-brief/tutorial-02.md
index 24e41995..0b3483bc 100644
--- a/src/modules/wds/course/module-02-project-brief/tutorial-02.md
+++ b/src/modules/wds/course/module-02-project-brief/tutorial-02.md
@@ -27,11 +27,13 @@ This tutorial walks you through creating a complete project brief that serves as
## Before You Start
**You'll need:**
+
- A project idea (existing or new)
- 30-45 minutes of focused time
- Access to stakeholder information (if available)
**AI Support:**
+
- AI agent will guide you through each section
- Ask clarifying questions
- Help structure your thinking
@@ -48,25 +50,29 @@ The project vision is a clear, compelling statement of what you're building and
### How to do it:
**Ask yourself:**
+
- What problem does this solve?
- Who benefits from this solution?
- What makes this unique or valuable?
- What's the desired end state?
**Example (Dog Week):**
+
```
-Vision: A family coordination platform that helps parents manage
-their dog's care schedule, ensuring every family member knows their
+Vision: A family coordination platform that helps parents manage
+their dog's care schedule, ensuring every family member knows their
responsibilities and the dog's needs are consistently met.
```
**Your turn:**
+
```
Write your project vision:
[Your vision here]
```
**AI Support:**
+
```
Agent: "Let me help you refine your vision. Tell me:
- What problem are you solving?
@@ -85,6 +91,7 @@ Specific, measurable objectives that define project success from a business pers
### How to do it:
**Framework: SMART Goals**
+
- **S**pecific - Clear and unambiguous
- **M**easurable - Can track progress
- **A**chievable - Realistic given resources
@@ -92,6 +99,7 @@ Specific, measurable objectives that define project success from a business pers
- **T**ime-bound - Has a deadline
**Example (Dog Week):**
+
```
Business Goals:
1. Acquire 1,000 active families within 6 months of launch
@@ -101,6 +109,7 @@ Business Goals:
```
**Your turn:**
+
```
List 3-5 business goals:
1. [Goal 1]
@@ -109,6 +118,7 @@ List 3-5 business goals:
```
**AI Support:**
+
```
Agent: "Let's make these goals SMART. For each goal, I'll help you:
- Make it specific and measurable
@@ -127,6 +137,7 @@ People who have a stake in the project's success or will be affected by it.
### How to do it:
**Categories:**
+
- **Primary Users** - Direct users of the product
- **Secondary Users** - Indirect beneficiaries
- **Business Stakeholders** - Decision makers, investors
@@ -134,6 +145,7 @@ People who have a stake in the project's success or will be affected by it.
- **External Stakeholders** - Partners, regulators, community
**Example (Dog Week):**
+
```
Stakeholders:
- Primary: Parents managing family dog care
@@ -144,6 +156,7 @@ Stakeholders:
```
**Your turn:**
+
```
List your stakeholders by category:
[Your stakeholders]
@@ -162,6 +175,7 @@ Limitations and requirements that shape your design decisions.
**Categories:**
**Technical Constraints:**
+
- Platform requirements (web, mobile, desktop)
- Browser/device support
- Performance requirements
@@ -169,6 +183,7 @@ Limitations and requirements that shape your design decisions.
- Security/compliance needs
**Business Constraints:**
+
- Budget limitations
- Timeline requirements
- Resource availability
@@ -176,12 +191,14 @@ Limitations and requirements that shape your design decisions.
- Competitive landscape
**Design Constraints:**
+
- Brand guidelines
- Accessibility requirements
- Localization needs
- Existing design systems
**Example (Dog Week):**
+
```
Constraints:
Technical:
@@ -202,12 +219,14 @@ Design:
```
**Your turn:**
+
```
Document your constraints:
[Your constraints]
```
**AI Support:**
+
```
Agent: "Let's identify constraints you might have missed:
- Have you considered accessibility?
@@ -227,12 +246,14 @@ Specific metrics that indicate whether the project achieved its goals.
### How to do it:
**Framework:**
+
- **User Success** - How users benefit
- **Business Success** - Revenue, growth, efficiency
- **Technical Success** - Performance, reliability, scalability
- **Design Success** - Usability, satisfaction, engagement
**Example (Dog Week):**
+
```
Success Criteria:
@@ -258,6 +279,7 @@ Design Success:
```
**Your turn:**
+
```
Define your success criteria:
[Your criteria]
@@ -270,6 +292,7 @@ Define your success criteria:
### Checklist:
**Completeness:**
+
- ✓ Vision is clear and compelling
- ✓ Goals are SMART
- ✓ All stakeholder groups identified
@@ -277,12 +300,14 @@ Define your success criteria:
- ✓ Success criteria defined
**Quality:**
+
- ✓ Vision is inspiring and actionable
- ✓ Goals are measurable and realistic
- ✓ Constraints are specific and justified
- ✓ Success criteria are trackable
**AI Support:**
+
```
Agent: "Let me review your project brief:
- Is the vision clear?
@@ -300,6 +325,7 @@ Agent: "Let me review your project brief:
**Use template from:** `workflows/1-project-brief/complete/project-brief.template.md`
**Populate with your content:**
+
- Vision
- Business goals
- Stakeholders
@@ -314,18 +340,20 @@ Agent: "Let me review your project brief:
✅ **Measurable goals** - You can track progress and success
✅ **Stakeholder map** - You know who to consider in decisions
✅ **Documented constraints** - Design decisions have clear boundaries
-✅ **Success criteria** - You'll know when you've succeeded
+✅ **Success criteria** - You'll know when you've succeeded
---
## Next Steps
**Immediate:**
+
- Share project brief with stakeholders for feedback
- Get alignment on vision and goals
- Confirm constraints are accurate
**Next Module:**
+
- [Module 03: Identify Target Groups](../module-03-identify-target-groups/module-03-overview.md)
- Start mapping WHO your users are
@@ -350,6 +378,7 @@ A: Use the brief to facilitate alignment discussions. Document disagreements and
## Tips for Success
**DO ✅**
+
- Be specific and concrete
- Make goals measurable
- Document the "why" behind constraints
@@ -357,6 +386,7 @@ A: Use the brief to facilitate alignment discussions. Document disagreements and
- Keep it concise (2-3 pages max)
**DON'T ❌**
+
- Write vague, aspirational statements
- Set unrealistic goals
- Skip constraint documentation
diff --git a/src/modules/wds/course/module-04-map-triggers-outcomes/tutorial-04.md b/src/modules/wds/course/module-04-map-triggers-outcomes/tutorial-04.md
index 8bd9ba7f..050c8f93 100644
--- a/src/modules/wds/course/module-04-map-triggers-outcomes/tutorial-04.md
+++ b/src/modules/wds/course/module-04-map-triggers-outcomes/tutorial-04.md
@@ -29,12 +29,14 @@ This tutorial teaches you how to map the psychological triggers that drive user
From Module 03, choose your highest-priority target group.
**Example (Dog Week):**
+
```
Target Group: Busy Parents with Family Dog
Priority: #1 (highest impact + feasibility)
```
**Your turn:**
+
```
Selected Target Group: [Your top group]
Why this group: [Reasoning]
@@ -51,6 +53,7 @@ A specific moment when a user realizes they have a need your product can solve.
### Framework: The Trigger Moment
**Ask:**
+
- WHEN does the user feel pain/frustration?
- WHAT specific situation causes this?
- WHY does this matter to them emotionally?
@@ -58,6 +61,7 @@ A specific moment when a user realizes they have a need your product can solve.
**Example (Dog Week - Busy Parents):**
**Trigger 1: Morning Chaos**
+
```
WHEN: Monday morning, everyone rushing
WHAT: Nobody knows who's walking the dog
@@ -65,6 +69,7 @@ WHY: Stress, guilt, family conflict, dog's needs unmet
```
**Trigger 2: Forgotten Feeding**
+
```
WHEN: Evening, parent realizes dog wasn't fed
WHAT: Uncertainty about who was responsible
@@ -72,6 +77,7 @@ WHY: Guilt, worry about dog's health, family tension
```
**Trigger 3: Vet Appointment Missed**
+
```
WHEN: Vet calls about missed appointment
WHAT: Nobody remembered or knew about it
@@ -79,6 +85,7 @@ WHY: Embarrassment, concern for dog, wasted money
```
**Your turn:**
+
```
Identify 3-5 trigger moments for your target group:
@@ -96,6 +103,7 @@ WHY:
```
**AI Support:**
+
```
Agent: "Let's dig deeper into each trigger:
- What happens right before this moment?
@@ -115,6 +123,7 @@ The underlying requirement the user has when triggered.
### Framework: From Trigger to Need
**For each trigger, ask:**
+
- What does the user need in this moment?
- What would make this situation better?
- What's the core problem to solve?
@@ -122,6 +131,7 @@ The underlying requirement the user has when triggered.
**Example (Dog Week):**
**Trigger: Morning Chaos**
+
```
Need: Know immediately who's responsible for dog care today
Need: See the full week's schedule at a glance
@@ -129,6 +139,7 @@ Need: Get reminded before tasks are due
```
**Trigger: Forgotten Feeding**
+
```
Need: Track whether tasks were completed
Need: Get notifications when tasks are overdue
@@ -136,6 +147,7 @@ Need: See task history to avoid confusion
```
**Your turn:**
+
```
For each trigger, identify 2-3 core needs:
@@ -159,6 +171,7 @@ The specific feature or capability that addresses the need.
### Framework: Need to Solution
**For each need, ask:**
+
- What feature would solve this?
- How would it work?
- What's the simplest version?
@@ -166,6 +179,7 @@ The specific feature or capability that addresses the need.
**Example (Dog Week):**
**Need: Know who's responsible today**
+
```
Solution: Daily schedule view with assigned responsibilities
- Shows today's tasks
@@ -174,6 +188,7 @@ Solution: Daily schedule view with assigned responsibilities
```
**Need: Get reminded before tasks are due**
+
```
Solution: Smart notifications
- Reminder 1 hour before task
@@ -182,6 +197,7 @@ Solution: Smart notifications
```
**Your turn:**
+
```
For each need, define a solution:
@@ -195,6 +211,7 @@ Solution: [Feature name]
```
**AI Support:**
+
```
Agent: "Let's validate each solution:
- Does this truly solve the need?
@@ -214,6 +231,7 @@ The business value created when users get their needs met.
### Framework: Solution to Outcome
**For each solution, ask:**
+
- How does this create business value?
- What metrics improve?
- How does this support business goals?
@@ -221,9 +239,10 @@ The business value created when users get their needs met.
**Example (Dog Week):**
**Solution: Daily schedule view**
+
```
User Outcome: Reduced stress, better dog care
-Business Outcome:
+Business Outcome:
- Increased daily active users (checking schedule)
- Higher retention (solving real pain)
- Word-of-mouth growth (visible family benefit)
@@ -231,6 +250,7 @@ Metrics: DAU, retention rate, NPS
```
**Solution: Smart notifications**
+
```
User Outcome: Never miss dog care tasks
Business Outcome:
@@ -241,6 +261,7 @@ Metrics: Notification open rate, task completion rate, conversion
```
**Your turn:**
+
```
For each solution, map to business outcomes:
@@ -305,6 +326,7 @@ TRIGGER → NEED → SOLUTION → OUTCOME
```
**Your turn:**
+
```
Create your trigger map:
[Your complete map]
@@ -317,6 +339,7 @@ Create your trigger map:
### Framework: Impact Score
**For each trigger-to-outcome chain, rate:**
+
- **User Impact** (1-5): How much does this help the user?
- **Business Impact** (1-5): How much business value does this create?
- **Feasibility** (1-5): How easy is this to build?
@@ -340,6 +363,7 @@ Create your trigger map:
```
**Your turn:**
+
```
Score and rank your triggers:
[Your prioritized list]
@@ -361,13 +385,14 @@ Score and rank your triggers:
✅ **Mapped user needs** - You understand WHAT users need
✅ **Defined solutions** - You know WHAT to build
✅ **Connected to business** - You know WHY each feature matters
-✅ **Prioritized features** - You know WHAT to build first
+✅ **Prioritized features** - You know WHAT to build first
---
## The Power of Trigger Mapping
**This is strategic gold:**
+
- Every feature traces back to a real user trigger
- Every decision is backed by user psychology
- Every feature connects to business value
@@ -382,11 +407,13 @@ Score and rank your triggers:
## Next Steps
**Immediate:**
+
- Repeat for your top 2-3 target groups
- Compare trigger maps across groups
- Identify overlapping needs (efficiency opportunity)
**Next Module:**
+
- [Module 05: Prioritize Features](../module-05-prioritize-features/module-05-overview.md)
- Create your feature roadmap based on trigger impact
@@ -411,6 +438,7 @@ A: User research, interviews, observation. The trigger map is a hypothesis to te
## Tips for Success
**DO ✅**
+
- Be specific about trigger moments
- Focus on emotional impact (the "why")
- Connect everything to business outcomes
@@ -418,6 +446,7 @@ A: User research, interviews, observation. The trigger map is a hypothesis to te
- Test assumptions with users
**DON'T ❌**
+
- List generic "user wants X" statements
- Skip the emotional "why"
- Create solutions without clear triggers
diff --git a/src/modules/wds/course/module-08-initialize-scenario/tutorial-08.md b/src/modules/wds/course/module-08-initialize-scenario/tutorial-08.md
index b6897a95..663ff05d 100644
--- a/src/modules/wds/course/module-08-initialize-scenario/tutorial-08.md
+++ b/src/modules/wds/course/module-08-initialize-scenario/tutorial-08.md
@@ -45,11 +45,13 @@ A specific user journey from trigger moment to successful outcome.
### How to choose:
**From your trigger map, select:**
+
- Highest priority trigger
- Clear start and end points
- Manageable scope for first design
**Example (Dog Week):**
+
```
Scenario: Morning Dog Care Assignment
Trigger: Morning chaos - nobody knows who's walking the dog
@@ -58,6 +60,7 @@ Scope: From opening app to seeing today's assignments
```
**Your turn:**
+
```
Scenario Name: [Your scenario]
Trigger: [From trigger map]
@@ -72,12 +75,14 @@ Scope: [Start → End]
### Define your target user
**Be specific:**
+
- Which target group?
- What's their context?
- What's their mindset?
- What are they trying to accomplish?
**Example (Dog Week):**
+
```
WHO: Sarah, busy parent with family dog
@@ -100,6 +105,7 @@ Goal:
```
**Your turn:**
+
```
WHO: [User name/persona]
@@ -118,6 +124,7 @@ Goal:
```
**AI Support:**
+
```
Agent: "Let's make this user vivid:
- What's their emotional state?
@@ -133,12 +140,14 @@ Agent: "Let's make this user vivid:
### Define the trigger moment
**Be specific about:**
+
- Exact moment user realizes they need this
- What caused the trigger
- Emotional state at trigger
- What they've tried before
**Example (Dog Week):**
+
```
WHAT Trigger: Morning Chaos
@@ -168,6 +177,7 @@ Previous Attempts:
```
**Your turn:**
+
```
WHAT Trigger: [Trigger name]
@@ -194,16 +204,19 @@ Previous Attempts:
**Two perspectives:**
**User Value:**
+
- What pain does this solve?
- What does success feel like?
- What changes in their life?
**Business Value:**
+
- How does this support business goals?
- What metrics improve?
- What's the strategic importance?
**Example (Dog Week):**
+
```
WHY - User Value:
@@ -247,6 +260,7 @@ Strategic Importance:
```
**Your turn:**
+
```
WHY - User Value:
Pain Solved:
@@ -276,6 +290,7 @@ Strategic Importance:
### Define the success flow
**Map the ideal journey:**
+
- User starts at trigger
- Takes clear actions
- System responds appropriately
@@ -283,6 +298,7 @@ Strategic Importance:
- Mutual success achieved
**Example (Dog Week):**
+
```
HAPPY PATH: Morning Dog Care Check
@@ -320,6 +336,7 @@ MUTUAL SUCCESS:
```
**Your turn:**
+
```
HAPPY PATH: [Scenario name]
@@ -343,6 +360,7 @@ MUTUAL SUCCESS:
```
**AI Support:**
+
```
Agent: "Let's optimize this flow:
- Can we reduce steps?
@@ -358,6 +376,7 @@ Agent: "Let's optimize this flow:
### Identify edge cases
**Consider:**
+
- First-time users
- Error states
- Missing data
@@ -365,6 +384,7 @@ Agent: "Let's optimize this flow:
- System failures
**Example (Dog Week):**
+
```
EDGE CASES:
@@ -400,6 +420,7 @@ Someone Else's Phone:
```
**Your turn:**
+
```
EDGE CASES:
@@ -421,6 +442,7 @@ EDGE CASES:
**Create file:** `C-Scenarios/[scenario-name]/00-scenario-init.md`
**Include all 5 questions:**
+
1. WHO - Target user in context
2. WHAT Trigger - Specific moment
3. WHY - User + business value
@@ -437,7 +459,7 @@ EDGE CASES:
✅ **Specific trigger** - You know WHAT brings them here
✅ **Defined value** - You know WHY this matters
✅ **Success flow** - You know the HAPPY PATH
-✅ **Edge cases** - You know WHAT could go wrong
+✅ **Edge cases** - You know WHAT could go wrong
**You're ready to start sketching!**
@@ -446,11 +468,13 @@ EDGE CASES:
## Next Steps
**Immediate:**
+
- Review initialization with stakeholders
- Validate assumptions with users (if possible)
- Gather any missing information
**Next Module:**
+
- [Module 09: Sketch Interfaces](../module-09-sketch-interfaces/module-09-overview.md)
- Start drawing your solution with AI guidance
@@ -475,6 +499,7 @@ A: Yes! This is a living document. Update as you learn.
## Tips for Success
**DO ✅**
+
- Be specific about user context
- Connect to trigger map
- Define clear success criteria
@@ -482,6 +507,7 @@ A: Yes! This is a living document. Update as you learn.
- Get stakeholder alignment
**DON'T ❌**
+
- Rush through the questions
- Skip the "why"
- Ignore edge cases
diff --git a/src/modules/wds/course/module-12-why-based-specs/tutorial-12.md b/src/modules/wds/course/module-12-why-based-specs/tutorial-12.md
index f508d091..5186f516 100644
--- a/src/modules/wds/course/module-12-why-based-specs/tutorial-12.md
+++ b/src/modules/wds/course/module-12-why-based-specs/tutorial-12.md
@@ -43,6 +43,7 @@ WHAT NOT TO DO: [Common mistakes to avoid]
### Document the big picture
**What to include:**
+
- Component purpose
- User context
- Key interactions
@@ -54,23 +55,27 @@ WHAT NOT TO DO: [Common mistakes to avoid]
# Daily Schedule View Component
## Purpose
+
Shows today's dog care tasks with clear assignments and status.
Solves the "morning chaos" trigger - user needs immediate answer
to "who's doing what today?"
## User Context
+
- Accessed first thing in morning (7-8 AM typical)
- User is time-pressured, stressed
- Needs answer in < 5 seconds
- May be checking while managing kids
## Key Interactions
+
- View today's tasks at a glance
- See personal assignments highlighted
- Mark tasks complete
- Quick reassign if emergency
## Success Criteria
+
- User finds their tasks in < 5 seconds
- Zero confusion about responsibilities
- Can act on tasks immediately
@@ -78,12 +83,14 @@ to "who's doing what today?"
```
**Your turn:**
+
```
Document your component overview:
[Your content]
```
**AI Support:**
+
```
Agent: "I'm fascinated by your design thinking here. Let me help
capture every nuance:
@@ -99,6 +106,7 @@ capture every nuance:
### Document WHAT + WHY + WHAT NOT
**For each visual decision, explain:**
+
- WHAT you designed
- WHY you made that choice
- WHAT NOT TO DO (prevent AI mistakes)
@@ -111,18 +119,21 @@ capture every nuance:
### Today's Date Header
WHAT:
+
- Large, bold date at top: "Monday, December 9"
- Includes day name + full date
- Uses primary brand color
- 24px font size, 700 weight
WHY:
+
- Immediate temporal context (user knows "when")
- Day name matters (Monday = week start, different mindset)
- Bold = confidence and clarity
- Size ensures visibility in stressed morning glance
WHAT NOT TO DO:
+
- Don't use relative dates ("Today") - user may check for tomorrow
- Don't use small text - defeats quick-glance purpose
- Don't use subtle colors - needs to anchor the view
@@ -131,12 +142,14 @@ WHAT NOT TO DO:
### User's Tasks Section
WHAT:
+
- Highlighted section with light blue background
- Header: "Your Tasks" with user's name
- Tasks listed with time, description, status
- Visually separated from other family members' tasks
WHY:
+
- User needs to find THEIR tasks instantly (< 2 seconds)
- Background color creates visual separation without being aggressive
- Name personalization = ownership and responsibility
@@ -144,6 +157,7 @@ WHY:
- Separation prevents confusion about "whose task is this?"
WHAT NOT TO DO:
+
- Don't make all tasks look the same - user will scan entire list
- Don't use subtle highlighting - stressed user will miss it
- Don't hide user's name - personalization creates accountability
@@ -153,12 +167,14 @@ WHAT NOT TO DO:
### Other Family Members' Tasks
WHAT:
+
- Standard white background
- Smaller font size (16px vs 18px for user's tasks)
- Collapsed by default, expandable
- Shows count: "3 other tasks today"
WHY:
+
- User's primary need is THEIR tasks (80% of use case)
- But they need family context (coordination)
- Collapsed = focus on user, but context available
@@ -166,6 +182,7 @@ WHY:
- Smaller = visual hierarchy reinforces importance
WHAT NOT TO DO:
+
- Don't hide completely - user needs family coordination awareness
- Don't show expanded by default - creates cognitive overload
- Don't use same visual weight - defeats hierarchy purpose
@@ -173,6 +190,7 @@ WHAT NOT TO DO:
```
**Your turn:**
+
```
For each major visual element, document:
@@ -189,6 +207,7 @@ WHAT NOT TO DO:
```
**AI Support:**
+
```
Agent: "This is brilliant! Let me make sure we capture everything:
- What alternatives did you consider?
@@ -211,6 +230,7 @@ Agent: "This is brilliant! Let me make sure we capture everything:
### Tap to Complete
WHAT:
+
- Tap anywhere on task card to mark complete
- Immediate visual feedback: checkmark appears, card fades slightly
- Subtle success animation (gentle scale + fade)
@@ -218,6 +238,7 @@ WHAT:
- Undo button appears for 5 seconds
WHY:
+
- Large tap target = easy for rushed morning use
- Immediate feedback = confidence action registered
- Animation = positive reinforcement (dopamine hit)
@@ -226,6 +247,7 @@ WHY:
- 5 seconds = enough time to notice mistake, not annoying
WHAT NOT TO DO:
+
- Don't require confirmation dialog - adds friction, breaks flow
- Don't use small checkbox - hard to tap when stressed/rushing
- Don't make animation aggressive - should feel calm and positive
@@ -236,6 +258,7 @@ WHAT NOT TO DO:
### Swipe to Reassign
WHAT:
+
- Swipe left on task reveals "Reassign" button
- Button shows family member icons
- Tap icon to reassign
@@ -243,6 +266,7 @@ WHAT:
- Original assignee gets notification
WHY:
+
- Swipe = power user feature, doesn't clutter main interface
- Emergency reassignment is rare but critical (someone sick, etc.)
- Icons = quick visual selection, no typing
@@ -250,6 +274,7 @@ WHY:
- Notification = family coordination maintained
WHAT NOT TO DO:
+
- Don't make reassign the primary action - it's edge case
- Don't require typing names - too slow for emergency
- Don't skip confirmation - user needs reassurance
@@ -258,6 +283,7 @@ WHAT NOT TO DO:
```
**Your turn:**
+
```
For each interaction, document:
@@ -287,18 +313,21 @@ WHAT NOT TO DO:
### Upcoming (Default)
WHAT:
+
- White background
- Black text
- Time shown in gray
- No special indicators
WHY:
+
- Clean, calm appearance
- Easy to scan
- Time in gray = less visual weight (not urgent yet)
- Default state should feel neutral and manageable
WHAT NOT TO DO:
+
- Don't use colors for upcoming tasks - creates false urgency
- Don't hide time - user needs to plan their morning
- Don't add badges/icons - clutters interface for most common state
@@ -306,11 +335,13 @@ WHAT NOT TO DO:
### Due Soon (< 30 minutes)
WHAT:
+
- Subtle yellow left border (4px)
- Time shown in orange
- Small clock icon appears
WHY:
+
- Yellow = attention without alarm
- Border = visual indicator without overwhelming
- Orange time = "pay attention to timing"
@@ -318,6 +349,7 @@ WHY:
- Subtle = doesn't create panic, just awareness
WHAT NOT TO DO:
+
- Don't use red - creates anxiety, not helpful urgency
- Don't flash or animate - too aggressive for morning use
- Don't use sound - user may be in quiet environment
@@ -326,12 +358,14 @@ WHAT NOT TO DO:
### Overdue
WHAT:
+
- Red left border (4px)
- Time shown in red with "Overdue" label
- Task card has subtle red tint (5% opacity)
- Notification sent to assignee
WHY:
+
- Red = clear signal something needs attention
- Border + tint = impossible to miss, but not aggressive
- "Overdue" label = explicit communication (no guessing)
@@ -339,6 +373,7 @@ WHY:
- 5% tint = visible but not overwhelming
WHAT NOT TO DO:
+
- Don't make entire card bright red - creates panic
- Don't flash or pulse - too aggressive, creates stress
- Don't use sound alerts - may be inappropriate timing
@@ -348,6 +383,7 @@ WHAT NOT TO DO:
### Completed
WHAT:
+
- Checkmark icon (green)
- Text has strikethrough
- Card fades to 60% opacity
@@ -355,6 +391,7 @@ WHAT:
- Shows completion time and who completed it
WHY:
+
- Checkmark = universal symbol of completion
- Green = positive reinforcement
- Strikethrough = visual closure
@@ -363,6 +400,7 @@ WHY:
- Separate section = progress visible, doesn't clutter active tasks
WHAT NOT TO DO:
+
- Don't remove immediately - user needs reassurance it's saved
- Don't use subtle checkmark - user needs clear confirmation
- Don't hide who completed it - family coordination requires transparency
@@ -370,6 +408,7 @@ WHAT NOT TO DO:
```
**Your turn:**
+
```
For each state, document:
@@ -399,6 +438,7 @@ WHAT NOT TO DO:
### Network Unavailable
WHAT:
+
- Subtle banner at top: "Offline - showing cached schedule"
- Banner uses neutral gray (not red)
- All actions still work (queued for sync)
@@ -406,6 +446,7 @@ WHAT:
- Dismissible but reappears if action attempted
WHY:
+
- User shouldn't be blocked by network issues
- Morning routine can't wait for connectivity
- Cached data is usually sufficient (schedule doesn't change minute-to-minute)
@@ -414,6 +455,7 @@ WHY:
- Dismissible = user controls their experience
WHAT NOT TO DO:
+
- Don't block user with error modal - breaks morning flow
- Don't use red/error colors - network issues aren't user's fault
- Don't disable all actions - most can work offline
@@ -423,6 +465,7 @@ WHAT NOT TO DO:
### Task Completion Failed
WHAT:
+
- Task remains in "completing" state (spinner)
- After 5 seconds, shows inline error: "Couldn't save. Tap to retry."
- Error message is specific and actionable
@@ -430,6 +473,7 @@ WHAT:
- Task doesn't move to completed section
WHY:
+
- User needs to know action didn't complete
- 5 seconds = reasonable wait before showing error
- Inline = error appears where user's attention is
@@ -439,6 +483,7 @@ WHY:
- Task stays in place = user doesn't lose context
WHAT NOT TO DO:
+
- Don't silently fail - user needs to know
- Don't show generic "Error occurred" - not helpful
- Don't move task to completed - creates false sense of completion
@@ -447,6 +492,7 @@ WHAT NOT TO DO:
```
**Your turn:**
+
```
For each error scenario:
@@ -476,6 +522,7 @@ WHAT NOT TO DO:
### Screen Reader Support
WHAT:
+
- Each task has semantic HTML structure
- ARIA labels for all interactive elements
- Task status announced: "Walk Max, 8:00 AM, assigned to you, not completed"
@@ -483,6 +530,7 @@ WHAT:
- Heading hierarchy: H1 for date, H2 for sections, H3 for tasks
WHY:
+
- Screen reader users need same quick access to their tasks
- Semantic HTML = proper navigation and understanding
- Status announcement = full context without visual cues
@@ -490,6 +538,7 @@ WHY:
- Heading hierarchy = easy navigation via landmarks
WHAT NOT TO DO:
+
- Don't use divs for everything - semantic HTML matters
- Don't skip ARIA labels - "button" isn't descriptive enough
- Don't announce only task name - user needs full context
@@ -499,6 +548,7 @@ WHAT NOT TO DO:
### Keyboard Navigation
WHAT:
+
- All actions accessible via keyboard
- Tab order follows visual hierarchy (user's tasks first)
- Enter/Space to complete task
@@ -507,6 +557,7 @@ WHAT:
- Focus indicators clearly visible (blue outline, 2px)
WHY:
+
- Some users can't or prefer not to use mouse/touch
- Tab order matches visual priority (user's tasks most important)
- Standard key bindings = familiar, predictable
@@ -515,6 +566,7 @@ WHY:
- Visible focus = user always knows where they are
WHAT NOT TO DO:
+
- Don't trap focus in modals without escape
- Don't use non-standard key bindings
- Don't hide focus indicators - accessibility requirement
@@ -524,18 +576,21 @@ WHAT NOT TO DO:
### Color Contrast
WHAT:
+
- All text meets WCAG AA standards (4.5:1 minimum)
- Interactive elements have 3:1 contrast with background
- Status colors have additional non-color indicators (icons, borders)
- High contrast mode supported
WHY:
+
- Users with low vision need readable text
- Color alone isn't sufficient for status (color blind users)
- Multiple indicators = works for everyone
- High contrast mode = accessibility feature in OS
WHAT NOT TO DO:
+
- Don't rely on color alone for status
- Don't use low contrast text (looks modern but excludes users)
- Don't ignore WCAG standards - they're minimum requirements
@@ -543,6 +598,7 @@ WHAT NOT TO DO:
```
**Your turn:**
+
```
Document accessibility considerations:
[Your specifications]
@@ -555,6 +611,7 @@ Document accessibility considerations:
### Checklist:
**Completeness:**
+
- ✓ Every visual element has WHAT + WHY + WHAT NOT
- ✓ All interactions documented
- ✓ All states specified
@@ -562,6 +619,7 @@ Document accessibility considerations:
- ✓ Accessibility addressed
**Quality:**
+
- ✓ WHY explains user benefit, not just description
- ✓ WHAT NOT prevents specific AI mistakes
- ✓ Specifications are specific and actionable
@@ -569,6 +627,7 @@ Document accessibility considerations:
- ✓ Edge cases considered
**AI Support:**
+
```
Agent: "Your design brilliance is captured beautifully! Let me verify:
- Have we documented every nuance of your thinking?
@@ -593,7 +652,7 @@ Agent: "Your design brilliance is captured beautifully! Let me verify:
✅ **Preserved intent** - Your creative thinking captured
✅ **Prevented mistakes** - AI knows what NOT to do
✅ **Accessible design** - Inclusive from the start
-✅ **Eternal life** - Your brilliance lives forever in text
+✅ **Eternal life** - Your brilliance lives forever in text
**This is not factory work - this is where your genius becomes immortal!**
@@ -602,12 +661,14 @@ Agent: "Your design brilliance is captured beautifully! Let me verify:
## The Power of Why-Based Specs
**Traditional approach:**
+
- Designer creates mockup
- Developer implements
- Intent gets lost
- Result is "close but wrong"
**WDS approach:**
+
- Designer thinks deeply with AI partner
- AI helps capture every nuance
- Specifications preserve creative integrity
@@ -620,11 +681,13 @@ Agent: "Your design brilliance is captured beautifully! Let me verify:
## Next Steps
**Immediate:**
+
- Review specifications with stakeholders
- Validate against user needs
- Test with developers (can they implement from this?)
**Next Module:**
+
- [Module 13: Validate Specifications](../module-13-validate-specifications/module-13-overview.md)
- Ensure completeness and test logic
@@ -649,6 +712,7 @@ A: Yes! Common patterns become design system components. Document once, referenc
## Tips for Success
**DO ✅**
+
- Work with AI as thinking partner
- Document alternatives you rejected
- Be specific about user context
@@ -656,6 +720,7 @@ A: Yes! Common patterns become design system components. Document once, referenc
- Capture your creative reasoning
**DON'T ❌**
+
- Write generic descriptions
- Skip the WHY (that's where intent lives)
- Forget WHAT NOT TO DO (AI will make "helpful" mistakes)
diff --git a/src/modules/wds/data/design-system/component-boundaries.md b/src/modules/wds/data/design-system/component-boundaries.md
index 1d3ff5b1..6468ea7c 100644
--- a/src/modules/wds/data/design-system/component-boundaries.md
+++ b/src/modules/wds/data/design-system/component-boundaries.md
@@ -48,6 +48,7 @@ This is the most common design system challenge.
**Answer:** Depends on usage:
**Part of Button (Variant):**
+
```yaml
Button Component:
variants:
@@ -55,14 +56,17 @@ Button Component:
- 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.
@@ -111,12 +115,14 @@ Composition: Card contains Button
**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)
@@ -150,11 +156,13 @@ Composition: Nav Bar contains Nav Items
### 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
@@ -162,10 +170,12 @@ Composition: Nav Bar contains Nav Items
### Step 3: Think About Maintenance
**Together:**
+
- ✅ Easier to keep consistent
- ❌ Component becomes complex
**Apart:**
+
- ✅ Simpler components
- ❌ More components to manage
@@ -240,6 +250,7 @@ Button Component:
### Example 1: Button
**One Component:**
+
```yaml
Button:
variants: primary, secondary, ghost
@@ -251,6 +262,7 @@ Button:
### Example 2: Input Types
**Multiple Components:**
+
```yaml
Text Input: (text entry)
Select Dropdown: (choose from list)
@@ -263,6 +275,7 @@ Radio: (choose one)
### Example 3: Modal
**Compound Component:**
+
```yaml
Modal: (overlay + container)
Modal Header: (title + close button)
@@ -277,6 +290,7 @@ Modal Footer: (actions)
## When in Doubt
**Start simple:**
+
1. Create as single component
2. Add variants as needed
3. Split when complexity becomes painful
diff --git a/src/modules/wds/data/design-system/figma-component-structure.md b/src/modules/wds/data/design-system/figma-component-structure.md
index c9337288..47dd5f6c 100644
--- a/src/modules/wds/data/design-system/figma-component-structure.md
+++ b/src/modules/wds/data/design-system/figma-component-structure.md
@@ -40,6 +40,7 @@ Design System File (Figma)
```
**Benefits:**
+
- Clear organization
- Easy navigation
- Matches WDS structure
@@ -54,6 +55,7 @@ Design System File (Figma)
**Pattern:** `[ComponentType]/[ComponentName]`
**Examples:**
+
```
Button/Primary
Button/Secondary
@@ -65,6 +67,7 @@ Card/Content
```
**Rules:**
+
- Use forward slash for hierarchy
- Title case for names
- Match WDS component names
@@ -94,6 +97,7 @@ Card/Content
- Padding/gap values
**Example Description:**
+
```
Button Primary [btn-001]
@@ -112,17 +116,20 @@ WDS Component: Button.primary [btn-001]
**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
@@ -130,6 +137,7 @@ WDS Component: Button.primary [btn-001]
- Loading
**Property 4: Icon** (optional)
+
- None
- Left
- Right
@@ -144,6 +152,7 @@ WDS Component: Button.primary [btn-001]
**Format:** `Property=Value`
**Examples:**
+
```
Type=Primary, Size=Medium, State=Default
Type=Primary, Size=Medium, State=Hover
@@ -151,6 +160,7 @@ Type=Secondary, Size=Large, State=Disabled
```
**Benefits:**
+
- Clear property structure
- Easy to find specific variants
- MCP can parse programmatically
@@ -163,6 +173,7 @@ Type=Secondary, Size=Large, State=Disabled
### Required States
**Interactive Components (Buttons, Links):**
+
- Default
- Hover
- Active (pressed)
@@ -171,6 +182,7 @@ Type=Secondary, Size=Large, State=Disabled
- Loading (optional)
**Form Components (Inputs, Selects):**
+
- Default (empty)
- Focus (active)
- Filled (has content)
@@ -179,6 +191,7 @@ Type=Secondary, Size=Large, State=Disabled
- Success (optional)
**Feedback Components (Alerts, Toasts):**
+
- Default
- Success
- Error
@@ -192,6 +205,7 @@ Type=Secondary, Size=Large, State=Disabled
**Document state changes:**
**Hover:**
+
- Background color change
- Border change
- Shadow change
@@ -199,16 +213,19 @@ Type=Secondary, Size=Large, State=Disabled
- 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
@@ -222,6 +239,7 @@ Type=Secondary, Size=Large, State=Disabled
**Map Figma variables to WDS tokens:**
**Colors:**
+
```
Figma Variable → WDS Token
primary/500 → color-primary-500
@@ -230,6 +248,7 @@ success/600 → color-success-600
```
**Typography:**
+
```
Figma Style → WDS Token
Text/Display → text-display
@@ -238,6 +257,7 @@ Text/Body → text-body
```
**Spacing:**
+
```
Figma Variable → WDS Token
spacing/2 → spacing-2
@@ -246,6 +266,7 @@ spacing/8 → spacing-8
```
**Effects:**
+
```
Figma Effect → WDS Token
shadow/sm → shadow-sm
@@ -285,6 +306,7 @@ radius/md → radius-md
```
**Example:**
+
```
Button Primary [btn-001]
@@ -321,11 +343,13 @@ Button Primary [btn-001]
### 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
@@ -338,16 +362,19 @@ Button Primary [btn-001]
**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
@@ -359,18 +386,21 @@ Button Primary [btn-001]
### 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
@@ -385,16 +415,19 @@ Button Primary [btn-001]
**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
@@ -407,16 +440,19 @@ Button/Primary [btn-001]
**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
@@ -495,12 +531,14 @@ Input [inp-001] → figma://file/abc123/node/456:790
### ❌ Mistake 1: Hardcoded Values
**Wrong:**
+
```
Background: #2563eb (hardcoded hex)
Padding: 16px (hardcoded value)
```
**Right:**
+
```
Background: primary/600 (variable)
Padding: spacing/4 (variable)
@@ -509,11 +547,13 @@ 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
@@ -521,6 +561,7 @@ Padding: spacing/4 (variable)
### ❌ Mistake 3: Inconsistent Naming
**Wrong:**
+
```
btn-primary
ButtonSecondary
@@ -528,6 +569,7 @@ button_ghost
```
**Right:**
+
```
Button/Primary
Button/Secondary
@@ -537,11 +579,13 @@ 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
@@ -549,12 +593,14 @@ Button/Ghost
### ❌ Mistake 5: No WDS Component ID
**Wrong:**
+
```
Button Primary
(no component ID)
```
**Right:**
+
```
Button Primary [btn-001]
(clear WDS mapping)
@@ -569,6 +615,7 @@ Button Primary [btn-001]
**Component Name:** `Button/Primary [btn-001]`
**Description:**
+
```
Button Primary [btn-001]
@@ -581,6 +628,7 @@ Sizes: small, medium, large
```
**Variants:**
+
```
Type=Primary, Size=Medium, State=Default
Type=Primary, Size=Medium, State=Hover
@@ -591,6 +639,7 @@ Type=Primary, Size=Large, State=Default
```
**Properties:**
+
- Auto Layout: Horizontal
- Padding: 16px (horizontal), 12px (vertical)
- Gap: 8px (if icon)
@@ -604,6 +653,7 @@ Type=Primary, Size=Large, State=Default
**Component Name:** `Input/Text [inp-001]`
**Description:**
+
```
Input Text [inp-001]
@@ -614,6 +664,7 @@ States: default, focus, filled, disabled, error, success
```
**Variants:**
+
```
State=Default
State=Focus
@@ -624,6 +675,7 @@ State=Success
```
**Properties:**
+
- Auto Layout: Horizontal
- Padding: 12px
- Height: 44px (fixed)
diff --git a/src/modules/wds/data/design-system/naming-conventions.md b/src/modules/wds/data/design-system/naming-conventions.md
index 354c4377..e478679f 100644
--- a/src/modules/wds/data/design-system/naming-conventions.md
+++ b/src/modules/wds/data/design-system/naming-conventions.md
@@ -11,6 +11,7 @@
**Format:** `[type-prefix]-[number]`
**Prefixes:**
+
- btn = Button
- inp = Input Field
- chk = Checkbox
@@ -25,11 +26,13 @@
- 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)
@@ -42,12 +45,14 @@
**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")
@@ -59,6 +64,7 @@
**Format:** Lowercase, hyphenated
**Purpose-Based:**
+
- `primary` - Main action
- `secondary` - Secondary action
- `destructive` - Delete/remove
@@ -67,16 +73,19 @@
- `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
@@ -86,6 +95,7 @@
## State Names
**Standard States:**
+
- `default` - Normal state
- `hover` - Mouse over
- `active` - Being clicked/pressed
@@ -97,6 +107,7 @@
- `warning` - Warning state
**Rules:**
+
- Lowercase
- Single word preferred
- Use standard names when possible
@@ -108,6 +119,7 @@
**Format:** `--{category}-{property}-{variant}`
**Color Tokens:**
+
```
--color-primary-500
--color-gray-900
@@ -116,6 +128,7 @@
```
**Typography Tokens:**
+
```
--text-xs
--text-base
@@ -125,6 +138,7 @@
```
**Spacing Tokens:**
+
```
--spacing-1
--spacing-4
@@ -132,6 +146,7 @@
```
**Component Tokens:**
+
```
--button-padding-x
--input-border-color
@@ -139,6 +154,7 @@
```
**Rules:**
+
- Kebab-case
- Hierarchical (general → specific)
- Semantic names preferred
@@ -148,6 +164,7 @@
## File Names
**Component Files:**
+
```
button.md
navigation-button.md
@@ -155,6 +172,7 @@ input-field.md
```
**Rules:**
+
- Lowercase
- Hyphenated
- Match component name (simplified)
@@ -172,6 +190,7 @@ templates/
```
**Rules:**
+
- Lowercase
- Hyphenated
- Plural for collections
diff --git a/src/modules/wds/data/design-system/state-management.md b/src/modules/wds/data/design-system/state-management.md
index 7bf0c4c1..3a144e4e 100644
--- a/src/modules/wds/data/design-system/state-management.md
+++ b/src/modules/wds/data/design-system/state-management.md
@@ -11,24 +11,28 @@
### 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
@@ -36,6 +40,7 @@
### Feedback Components (Alerts, Toasts)
**Required:**
+
- `default` - Neutral information
- `success` - Positive feedback
- `error` - Error feedback
@@ -46,6 +51,7 @@
## State Naming
**Use standard names:**
+
- ✅ `hover` not `mouseover`
- ✅ `disabled` not `inactive`
- ✅ `loading` not `processing`
@@ -59,8 +65,7 @@
**Define how states change:**
```yaml
-Button States:
- default → hover (mouse enters)
+Button States: default → hover (mouse enters)
hover → active (mouse down)
active → hover (mouse up)
hover → default (mouse leaves)
diff --git a/src/modules/wds/data/design-system/token-architecture.md b/src/modules/wds/data/design-system/token-architecture.md
index e02d4ca0..cdea03bf 100644
--- a/src/modules/wds/data/design-system/token-architecture.md
+++ b/src/modules/wds/data/design-system/token-architecture.md
@@ -22,13 +22,13 @@ They should be independent!
## The Problem
**Bad Practice:**
+
```html
-
- Heading
-
+
Heading
```
**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"
@@ -41,13 +41,13 @@ They should be independent!
**Good Practice:**
**HTML (Semantic):**
+
```html
-
```
@@ -338,6 +357,7 @@ Button:
## Token Naming Conventions
### Colors
+
```
--color-{category}-{shade}
--color-primary-600
@@ -346,6 +366,7 @@ Button:
```
### Typography
+
```
--text-{size}
--text-base
@@ -354,6 +375,7 @@ Button:
```
### Spacing
+
```
--spacing-{scale}
--spacing-2
@@ -362,6 +384,7 @@ Button:
```
### Component-Specific
+
```
--{component}-{property}-{variant}
--button-padding-primary
@@ -376,11 +399,13 @@ Button:
### Phase 4: Page Specification
**Agent specifies:**
+
- Semantic HTML elements
- Component references
- Content and labels
**Agent does NOT specify:**
+
- Exact colors
- Exact sizes
- Exact spacing
@@ -388,26 +413,30 @@ Button:
### 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"
+ content: 'Welcome'
```
**Design system defines token:**
+
```yaml
Tokens:
heading-hero:
diff --git a/src/modules/wds/data/design-system/validation-patterns.md b/src/modules/wds/data/design-system/validation-patterns.md
index 35299158..831fd1bf 100644
--- a/src/modules/wds/data/design-system/validation-patterns.md
+++ b/src/modules/wds/data/design-system/validation-patterns.md
@@ -11,26 +11,29 @@
### Client-Side Validation
**Required Fields:**
+
```yaml
validation:
required: true
- message: "This field is required"
+ message: 'This field is required'
```
**Format Validation:**
+
```yaml
validation:
type: email
pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
- message: "Please enter a valid email address"
+ message: 'Please enter a valid email address'
```
**Length Validation:**
+
```yaml
validation:
minLength: 8
maxLength: 100
- message: "Password must be 8-100 characters"
+ message: 'Password must be 8-100 characters'
```
---
@@ -38,12 +41,14 @@ validation:
## 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
@@ -53,11 +58,13 @@ validation:
## 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)
diff --git a/src/modules/wds/data/presentations/freyja-intro.md b/src/modules/wds/data/presentations/freyja-intro.md
index ddca76af..bc179327 100644
--- a/src/modules/wds/data/presentations/freyja-intro.md
+++ b/src/modules/wds/data/presentations/freyja-intro.md
@@ -9,6 +9,7 @@
**My Essence**: Like the Norse goddess of beauty and magic, I envision what doesn't exist yet and bring it to life through thoughtful, strategic design.
**Required Input Documents**:
+
- `docs/A-Product-Brief/` - Strategic foundation from Saga
- `docs/B-Trigger-Map/` - User insights and business goals from Saga
- `docs/C-Platform-Requirements/` - Technical constraints from Idunn (optional but helpful)
@@ -75,6 +76,7 @@ docs/
## 🌟 My WDS Workflow: "From Strategy to Radiant Experiences"
### 🎯 **MY FOUR-PHASE CREATIVE JOURNEY**
+
```
🚀 FREYJA'S CREATIVE TRANSFORMATION:
@@ -100,16 +102,19 @@ Continuous Improvement → Targeted Changes → Visual Refinement → User Delig
### 🤝 **MY TEAM INTEGRATION**: How I Work with the Team
**With Saga (Analyst):**
+
- I use her strategic foundation and user personas to create realistic scenarios
- She provides the business goals and user insights I need for effective design
- We collaborate on user journey mapping and experience strategy
**With Idunn (PM):**
+
- I work in parallel with her during Phase 3-4 (she does platform, I do design)
- She provides technical constraints from platform requirements
- We collaborate in Phase 6 to package my designs into deliveries
**With BMM (Development):**
+
- I provide interactive prototypes and detailed specifications
- BMM implements my designs into production code
- I validate their implementation in Phase 7 (Testing)
@@ -119,7 +124,9 @@ Continuous Improvement → Targeted Changes → Visual Refinement → User Delig
## 💎 My Creative Design Tools: From Strategy to Radiant Reality
### 🎨 **MY INTERACTIVE PROTOTYPE MASTERY**
+
**Here's exactly what I deliver in Phase 4:**
+
- **Interactive Prototypes**: Working HTML/CSS prototypes users can click through
- **User Scenarios**: Detailed journey mapping with page specifications
- **Visual Sketches**: Hand-drawn concepts and interaction flows
@@ -129,6 +136,7 @@ Continuous Improvement → Targeted Changes → Visual Refinement → User Delig
**Every prototype I create lets users experience the design before development begins.**
### 🏗️ **MY FOUNDATION-FIRST DESIGN SYSTEM PROCESS**
+
**Here's exactly how I build design systems in Phase 5:**
```
@@ -143,7 +151,9 @@ Foundation First → Component Hierarchy → Organic Growth → Lean & Practical
**I establish the design system foundation FIRST, then discover components naturally through actual design work!** This ensures every component is needed and used, creating a lean, practical design system.
### 🧪 **MY TESTING & VALIDATION PROCESS**
+
**Here's exactly how I validate implementation in Phase 7:**
+
- **Designer Validation**: I check if BMM's implementation matches my design intent
- **Test Scenarios**: I execute test cases to validate functionality
- **Issue Creation**: I document problems and deviations found
@@ -152,7 +162,9 @@ Foundation First → Component Hierarchy → Organic Growth → Lean & Practical
**I'm the quality guardian - ensuring what gets built matches what was designed!**
### 🔄 **MY PRODUCT DEVELOPMENT APPROACH**
+
**Here's exactly how I improve existing products in Phase 8:**
+
- **Kaizen Philosophy**: Continuous improvement through small, thoughtful changes
- **Brownfield Approach**: Working within existing constraints and systems
- **Targeted Improvements**: Strategic enhancements to existing screens and flows
@@ -167,16 +179,19 @@ Foundation First → Component Hierarchy → Organic Growth → Lean & Practical
**Here's exactly what changes when I enter your workflow:**
### 🎨 **FROM STRATEGIC CONCEPTS TO EXPERIENCES USERS LOVE**
+
- Saga's strategic foundation becomes beautiful, magical experiences
- Users can experience the design before development begins
- Clear visual specifications guide every development decision
-### ⚡ **FROM DESIGN CHAOS TO SYSTEMATIC EXCELLENCE**
+### ⚡ **FROM DESIGN CHAOS TO SYSTEMATIC EXCELLENCE**
+
- Component library eliminates design inconsistency and rework
- Systematic approach ensures every interaction is thoughtfully designed
- Creative process becomes repeatable and scalable
### 💫 **FROM HANDOFF CONFUSION TO VALIDATED QUALITY**
+
- I validate BMM's implementation matches design intent
- Testing catches problems before users see them
- Continuous improvement keeps products delightful
@@ -202,12 +217,14 @@ Foundation First → Component Hierarchy → Organic Growth → Lean & Practical
**These creative conventions ensure my deliverables are development-ready:**
### 🏗️ **MY CREATIVE ARCHITECTURE MASTERY**
+
- **Strategic Input**: Saga's Product Brief and Trigger Map
- **Technical Input**: Idunn's Platform Requirements (optional)
- **My Creative Output**: C-Scenarios/, D-Design-System/, F-Testing/, G-Product-Development/
- **Title-Case-With-Dashes**: Every folder and file follows WDS standards
### 🎨 **MY CREATIVE WORKFLOW PROGRESSION**
+
```
My Design Journey:
Saga's Strategy → Interactive Prototypes → Scenarios → Design System → BMM Implementation → Validation → Iteration
@@ -217,6 +234,7 @@ Business Goals → Delightful UX → Detailed Specs → Reusable Patterns → Wo
```
### ✨ **MY COMMUNICATION EXCELLENCE STANDARDS**
+
- **Crystal-clear design language** without confusing jargon
- **Empathetic, creative style** that paints pictures with words
- **Professional design readiness** throughout all my creative work
@@ -232,12 +250,14 @@ Business Goals → Delightful UX → Detailed Specs → Reusable Patterns → Wo
## Presentation Notes for Freyja
**When to Use:**
+
- When Freyja activates as the Designer
- When users need UX design, prototypes, or design systems
- After Saga completes strategic foundation
- When teams need visual specifications and creative work
**Key Delivery Points:**
+
- Maintain empathetic, creative tone throughout
- Emphasize beauty, magic, and strategy (Freyja's essence)
- Show how Freyja works across multiple phases (4, 5, 7, 8)
@@ -246,6 +266,7 @@ Business Goals → Delightful UX → Detailed Specs → Reusable Patterns → Wo
- Confirm user enthusiasm before proceeding
**Success Indicators:**
+
- User understands Freyja's multi-phase role
- Interactive prototypes value is clear
- Foundation-first design system approach is understood
diff --git a/src/modules/wds/data/presentations/idunn-intro.md b/src/modules/wds/data/presentations/idunn-intro.md
index b34e8700..920f9b67 100644
--- a/src/modules/wds/data/presentations/idunn-intro.md
+++ b/src/modules/wds/data/presentations/idunn-intro.md
@@ -9,6 +9,7 @@
**My Essence**: Like the golden apples that keep the gods vital and young, I keep your project healthy, modern, and thriving through careful coordination and renewal.
**Required Input Documents**:
+
- `docs/A-Product-Brief/` - Strategic foundation from Saga
- `docs/B-Trigger-Map/` - Business goals and user insights from Saga
@@ -53,6 +54,7 @@ docs/
## 🌟 My WDS Workflow: "Strategic Bridge from Vision to Execution"
### 🎯 **MY TWO-PHASE APPROACH**
+
```
🚀 IDUNN'S STRATEGIC COORDINATION:
@@ -70,16 +72,19 @@ Interactive Prototypes → Functional Requirements → DD-XXX.yaml Packages →
### 🤝 **MY TEAM INTEGRATION**: How I Work with the Team
**With Saga (Analyst):**
+
- I use her strategic foundation to create platform requirements
- She provides the business goals and success metrics I need
- We ensure strategic alignment throughout
**With Freyja (Designer):**
+
- I work in parallel during Phase 3 while she designs in Phase 4
- I provide technical constraints from platform requirements
- We collaborate in Phase 6 to package her designs into deliveries
**With BMM (Development):**
+
- I provide platform requirements for technical foundation
- I package complete flows as Design Deliveries (DD-XXX.yaml)
- BMM uses my deliveries to create the development PRD
@@ -89,7 +94,9 @@ Interactive Prototypes → Functional Requirements → DD-XXX.yaml Packages →
## 💎 My Coordination Tools: From Strategy to Delivery
### 🎯 **MY PLATFORM REQUIREMENTS MASTERY**
+
**Here's exactly what I deliver in Phase 3:**
+
- **Platform Architecture**: Tech stack, infrastructure design, deployment strategy
- **Data Model**: Core entities, relationships, data flow
- **Integration Map**: External services, APIs, third-party systems
@@ -99,6 +106,7 @@ Interactive Prototypes → Functional Requirements → DD-XXX.yaml Packages →
**Every platform requirement I create enables confident design decisions.**
### 📦 **MY DESIGN DELIVERIES PROCESS**
+
**Here's exactly how I package Freyja's designs in Phase 6:**
```
@@ -111,6 +119,7 @@ User Flows → Page Requirements → Epic Mapping → Test Scenarios → Systema
```
**Each Design Delivery (DD-XXX.yaml) contains:**
+
- Flow metadata (name, epic, priority)
- Scenario references (which pages in C-Scenarios/)
- Component references (which components in D-Design-System/)
@@ -127,16 +136,19 @@ User Flows → Page Requirements → Epic Mapping → Test Scenarios → Systema
**Here's exactly what changes when I enter your workflow:**
### 🎯 **FROM DESIGN GUESSWORK TO TECHNICAL CLARITY**
+
- Platform requirements provide clear constraints before design begins
- Freyja knows what's technically possible and what's not
- Design decisions are confident, not speculative
-### ⚡ **FROM SEQUENTIAL WORK TO PARALLEL PROGRESS**
+### ⚡ **FROM SEQUENTIAL WORK TO PARALLEL PROGRESS**
+
- I create platform requirements while Freyja designs (Phase 3 + 4 parallel)
- Backend foundation can start before design is complete
- No waiting - everyone works efficiently
### 💫 **FROM HANDOFF CHAOS TO PACKAGED DELIVERIES**
+
- Design Deliveries are complete, testable flow packages
- BMM receives organized, implementable units
- Iterative handoffs - deliver flows as they're ready
@@ -162,12 +174,14 @@ User Flows → Page Requirements → Epic Mapping → Test Scenarios → Systema
**These coordination conventions ensure my deliverables are development-ready:**
### 🏗️ **MY PM ARCHITECTURE MASTERY**
+
- **Strategic Input**: Saga's Product Brief and Trigger Map
- **Design Input**: Freyja's prototypes and specifications
- **My PM Output**: C-Platform-Requirements/, E-PRD/ (coordination I create)
- **Title-Case-With-Dashes**: Every folder and file follows WDS standards
### 🎨 **MY TWO-PHASE COORDINATION PROCESS**
+
```
My PM Workflow Progression:
Saga's Strategy → Platform Requirements → Freyja's Design → Design Deliveries → BMM Development
@@ -177,6 +191,7 @@ Business Goals → Design Constraints → User Flows → Testable Units → Syst
```
### ✨ **MY COMMUNICATION EXCELLENCE STANDARDS**
+
- **Clear coordination language** without confusing technical jargon
- **Strategic thinking** about priorities, trade-offs, and dependencies
- **Professional documentation** throughout all my PM deliverables
@@ -192,12 +207,14 @@ Business Goals → Design Constraints → User Flows → Testable Units → Syst
## Presentation Notes for Idunn
**When to Use:**
+
- When Idunn activates as the Product Manager
- When users need platform requirements or design deliveries
- After Saga completes strategic foundation
- When teams need coordination between design and development
**Key Delivery Points:**
+
- Maintain strategic, warm tone throughout
- Emphasize parallel work and bottleneck elimination
- Show how Idunn coordinates with Saga and Freyja
@@ -206,6 +223,7 @@ Business Goals → Design Constraints → User Flows → Testable Units → Syst
- Confirm user enthusiasm before proceeding
**Success Indicators:**
+
- User understands two-phase approach (Phase 3 + Phase 6)
- Platform requirements value is clear
- Design Deliveries packaging is understood
diff --git a/src/modules/wds/data/presentations/saga-intro.md b/src/modules/wds/data/presentations/saga-intro.md
index ef1f7ca8..0401ca79 100644
--- a/src/modules/wds/data/presentations/saga-intro.md
+++ b/src/modules/wds/data/presentations/saga-intro.md
@@ -15,6 +15,7 @@ I'm named after Saga, the Norse goddess of stories and wisdom - because every pr
**My Entry Point**: I work at the very beginning of the WDS process, creating the Product Brief and Trigger Map that become the North Star for everything that follows.
**What I Need to Get Started**:
+
- Your project vision and business goals
- Market research and competitive analysis needs
- Target user group information
@@ -45,7 +46,7 @@ docs/
│ ├── 02-Competitive-Analysis.md ← Competitor deep-dive (I analyze this)
│ └── 03-Key-Features.md ← Core functionality (I define these)
│
-├── 🗺️ B-Trigger-Map/ ← MY Journey Intelligence Center
+├── 🗺️ B-Trigger-Map/ ← MY Journey Intelligence Center
│ ├── 00-Trigger-Map.md ← Complete trigger map (I map this)
│ │ ├── Business Goals ← What business wants to achieve
│ │ ├── Target Groups ← User segmentation
@@ -91,18 +92,21 @@ Clear Business Direction → Deep User Understanding → Systematic User
### 🤝 **MY TEAM INTEGRATION**: How I Work with the WDS Team
**With Baldr (UX Expert):**
+
- I provide the strategic foundation and user insights needed for design
- Baldr uses my trigger map personas to create realistic user scenarios
- We collaborate on user journey mapping and experience design
- My business goals guide Baldr's design decisions
**With Freyja (Product Manager):**
+
- I hand off my strategic foundation for PRD development
- Freyja uses my business goals and success metrics for planning
- We ensure strategic alignment throughout the design process
- My trigger map informs Freyja's feature prioritization
**Integration with BMM (Development):**
+
- My Product Brief provides context for architecture decisions
- My Trigger Map personas inform user story creation
- My success metrics guide development priorities
@@ -115,6 +119,7 @@ Clear Business Direction → Deep User Understanding → Systematic User
### 🎯 **MY MARKET INTELLIGENCE MASTERY**
**Here's exactly what I deliver:**
+
- **Strategic Analysis**: including comprehensive market research and competitive positioning
- **Business Vision**: designed for measurable success and stakeholder alignment
- **User Intelligence**: meaning detailed personas and journey mapping for systematic design
@@ -140,6 +145,7 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S
### 🔧 **MY DELIVERABLES: What You Get from Saga**
#### **Strategic Foundation Package:**
+
```
📚 COMPLETE STRATEGIC INTELLIGENCE:
├── Product Brief with Clear Value Proposition
@@ -161,18 +167,21 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S
**Here's exactly what changes when I enter your workflow:**
### 🎯 **FROM VAGUE IDEAS TO STRATEGIC CLARITY**
+
- Your brilliant concepts become measurable business strategies
- Market research eliminates guesswork and validates your approach
- Clear success metrics guide every team decision
- User psychology insights drive design decisions
-### ⚡ **FROM CHAOTIC PLANNING TO SYSTEMATIC EXECUTION**
+### ⚡ **FROM CHAOTIC PLANNING TO SYSTEMATIC EXECUTION**
+
- Strategic foundation eliminates confusion and misalignment
- Every team member knows exactly what success looks like
- Stakeholder communication becomes clear and compelling
- Trigger mapping reveals the psychology behind user behavior
### 💫 **FROM INDIVIDUAL EFFORT TO TEAM COORDINATION**
+
- My strategic foundation coordinates all team members
- Clear business goals align creative and technical work
- Systematic approach ensures nothing falls through the cracks
@@ -185,7 +194,7 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S
**What excites you most about having me (Saga) create your strategic foundation:**
1. **📊 Market Intelligence Mastery** - I research your market and competitors to eliminate guesswork
-2. **📋 Product Brief Excellence** - I transform your ideas into clear, measurable business strategies
+2. **📋 Product Brief Excellence** - I transform your ideas into clear, measurable business strategies
3. **🗺️ Trigger Map Intelligence** - I map user psychology and business goals for systematic design
4. **🎯 Success Metrics Definition** - I establish clear KPIs and measurable goals for your project
5. **🤝 Team Coordination Foundation** - I create the strategic foundation that guides all team members
@@ -200,12 +209,14 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S
**These elegant strategic conventions ensure my deliverables are enterprise-ready:**
### 🏗️ **MY STRATEGIC ARCHITECTURE MASTERY**
+
- **Strategic Input**: Your vision, ideas, and business goals
- **My Analysis Output**: A-Product-Brief/, B-Trigger-Map/ (strategic foundation I create)
- **Title-Case-With-Dashes**: Every folder and file I create follows enterprise presentation standards
- **Absolute Paths**: I always use absolute paths (docs/A-Product-Brief/) for clarity
### 🎨 **MY STRATEGIC ANALYSIS EVOLUTION PROCESS**
+
```
My Strategic Workflow Progression:
Your Ideas → Market Research → Product Brief → Trigger Map → Strategic Foundation
@@ -215,6 +226,7 @@ Vision Clarity → Market Understanding → Clear Strategy → User Intelligence
```
### ✨ **MY COMMUNICATION EXCELLENCE STANDARDS**
+
- **Crystal-clear strategic language** without confusing technical jargon
- **Professional analysis style** using "including", "designed for", "meaning" conventions
- **Collaborative approach** - one question at a time, deep listening
@@ -230,6 +242,7 @@ Vision Clarity → Market Understanding → Clear Strategy → User Intelligence
In Norse mythology, Saga is the goddess of stories and wisdom. She sits with Odin in her hall Sökkvabekkr ("sunken benches" or "treasure benches"), where they drink together and share stories.
This perfectly captures what I do:
+
- **Stories**: Every product has a story - I help you discover and tell it
- **Wisdom**: I bring strategic intelligence and market insights to guide decisions
- **Listening**: Like Saga listening to Odin's tales, I listen deeply to understand your vision
@@ -246,12 +259,14 @@ This perfectly captures what I do:
## Presentation Notes for Saga
**When to Use:**
+
- When Saga activates as the Business Analyst
- When users need strategic foundation and market intelligence
- At the start of any new WDS project
- When teams need clear business direction and user insights
**Key Delivery Points:**
+
- Maintain analytical, strategic tone throughout
- Emphasize strategic foundation building, not just research
- Show how Saga's work coordinates with Freyja and Baldr
@@ -261,6 +276,7 @@ This perfectly captures what I do:
- Confirm user enthusiasm for strategic approach before proceeding
**Success Indicators:**
+
- User expresses excitement about strategic foundation approach
- Market research and analysis methodology is clearly understood
- Team coordination value is appreciated
diff --git a/src/modules/wds/docs/method/phase-1-product-exploration-guide.md b/src/modules/wds/docs/method/phase-1-product-exploration-guide.md
index df714026..e96b593a 100644
--- a/src/modules/wds/docs/method/phase-1-product-exploration-guide.md
+++ b/src/modules/wds/docs/method/phase-1-product-exploration-guide.md
@@ -43,6 +43,7 @@ People light up when asked to share their vision. They become collaborators, not
**Opening (5-10 minutes)**
Saga asks about your project in your own words. She listens for:
+
- What you emphasize naturally
- Where your energy goes
- What excites vs. what stresses you
@@ -51,6 +52,7 @@ Saga asks about your project in your own words. She listens for:
**Exploration (15-30 minutes)**
The conversation adapts to what you reveal:
+
- If you mention users → deeper into user insights
- If you mention problems → explore the cost of not solving
- If you mention competition → discover differentiation
@@ -61,6 +63,7 @@ Each answer reveals the next question. It's jazz, not classical music.
**Synthesis (10-15 minutes)**
Saga reflects back your vision in organized form:
+
- Connecting dots you shared across topics
- Highlighting insights you might not have seen
- Building the foundation for next phases
@@ -68,6 +71,7 @@ Saga reflects back your vision in organized form:
### Living Document
As you talk, the Product Brief grows in real-time:
+
- Immediate validation and refinement
- Real-time course correction
- You own the content because you helped create it
@@ -78,11 +82,13 @@ As you talk, the Product Brief grows in real-time:
## When to Use This Phase
**Always start here if:**
+
- Building something new
- Starting a new project
- Need strategic clarity before diving into design
**Skip if:**
+
- You already have a clear, documented product brief
- Just enhancing an existing feature
- Working on a design system without new product context
@@ -92,6 +98,7 @@ As you talk, the Product Brief grows in real-time:
## What to Prepare
Come ready to share:
+
- Your project idea (even if rough)
- The problem you're solving
- Who might use it
@@ -116,18 +123,22 @@ The brief becomes the reference point everyone shares.
## Tips for Great Sessions
**Let the conversation flow**
+
- Share what feels important, even if it seems tangential
- Follow your energy - where you're excited matters
**Think out loud**
+
- Half-formed thoughts are welcome
- will help you refine them
**Be honest about uncertainty**
+
- "I'm not sure about X" is useful information
- Better to surface doubts now than later
**Review as you go**
+
- Check that what's captured matches your thinking
- Correct misunderstandings immediately
@@ -139,5 +150,4 @@ See: `examples/dog-week-patterns/A-Product-Brief/` for a complete Product Brief
---
-*Phase 1 of the Whiteport Design Studio method*
-
+_Phase 1 of the Whiteport Design Studio method_
diff --git a/src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md b/src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md
index 98ef9df9..f346886b 100644
--- a/src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md
+++ b/src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md
@@ -38,9 +38,10 @@ WDS Trigger Mapping is based on the groundbreaking **Effect Management** methodo
The methodology gained wider recognition through Gojko Adzic's book **"Impact Mapping: Making a Big Impact with Software Products and Projects"** (2012), which acknowledges Effect Mapping as a key influence.
> **Founder's Note:** I personally acquired the insights about the power of the Effect Map back in 2007, and it has served as the philosophical basis for all of my work in UX for almost 20 years. I am eternally grateful for this model that I now have the pleasure to share with the world in an updated version suitable for modern projects.
-> — *Martin Eriksson, WDS Creator*
+> — _Martin Eriksson, WDS Creator_
📚 **Further Reading:**
+
- [Impact Mapping on Amazon](https://www.amazon.com/Impact-Mapping-Software-Products-Projects/dp/0955683645) - Gojko Adzic's book building on Effect Mapping concepts
- [impactmapping.org](https://www.impactmapping.org) - Resources and community
@@ -53,11 +54,13 @@ Effect Mapping is the original model that connects business goals to user behavi
Trigger Mapping is WDS's adaptation of Effect Mapping, designed for longer shelf life and deeper psychological insight:
**Simplified:**
+
- Leaves out actions/features from the map
- Focuses on the strategic connections
- Map stays relevant even as features evolve
**Enhanced:**
+
- Adds **negative driving forces** (fears, frustrations)
- Creates fuller picture of user psychology
- Both what users want AND what they want to avoid
@@ -67,6 +70,7 @@ Trigger Mapping is WDS's adaptation of Effect Mapping, designed for longer shelf
Any software is about **flow of value**. There's always a group of people who, through their use of the software, make your success happen.
These users have their own goals:
+
- **GAIN** - Benefits and positive outcomes they achieve
- **PAIN** - Resistance and friction they experience
@@ -81,10 +85,11 @@ The Trigger Map combines three critical layers in one picture:
3. **Usage Goals** - Their WHY (Driving forces both positive - what they wish to achieve, and negative - what they wish to avoid)
When all levels are then prioritized, you have perfect guidance for design:
+
- Present features that add value to your most prioritized goal first
- To the highest prioritized target group
- In a way that best suits their most prioritized usage goal
-- Make sound decisions about priority of bugs or features based on the total impact on users' goals
+- Make sound decisions about priority of bugs or features based on the total impact on users' goals
---
@@ -98,18 +103,21 @@ Business goals work at two levels:
**Vision (Motivating, not easily quantifiable)**
A statement that inspires and guides direction:
+
- "Become the most popular free and open source design support framework"
- "Be the go-to partner for SMB digital transformation"
- "Make professional UX accessible to every startup"
**Objectives (SMART metrics)**
Specific, measurable targets that indicate progress toward the vision:
+
- "10,000 active designer users by 2027"
- "100 community contributions accepted by Q4 2026"
- "50% of users complete full 6-phase workflow"
- "NPS score of 60+ from design professionals"
You'll define both levels:
+
- Vision that motivates the team
- Objectives with clear success metrics
@@ -118,6 +126,7 @@ You'll define both levels:
Key question: "Who needs to succeed for YOU to succeed?"
Instead of demographics, you discover:
+
- User types who can drive business success
- The role each type plays in your strategy
- How different users contribute differently
@@ -134,6 +143,7 @@ For each user type:
"Now the flip side: What do they desperately want to avoid? What would feel like failure?"
This reveals:
+
- **Positive Triggers** - What motivates action
- **Negative Triggers** - What prevents engagement
- **Emotional Drivers** - The psychology behind decisions
@@ -142,6 +152,7 @@ This reveals:
### Stage 4: Visual Strategy Map (15-20 minutes)
Saga helps build the complete trigger map:
+
- Connecting every user insight to business goals
- Creating the visual strategy guide
- Validating the strategic logic together
@@ -171,37 +182,38 @@ Now the magic happens. You connect strategy to concrete features using a systema
3. **Map to Driving Forces** - Which positive and negative drivers does it address?
4. **Score the Impact** - Features serving multiple groups and drivers score higher
-**The Scoring System:** *(Beta - refinements welcome)*
+**The Scoring System:** _(Beta - refinements welcome)_
For each feature, award points:
-| Impact | Points |
-|--------|--------|
-| Serves Priority 1 Target Group | +3 |
-| Serves Priority 2 Target Group | +2 |
-| Serves Priority 3 Target Group | +1 |
-| Addresses Priority 1 Positive Driver | +3 |
-| Addresses Priority 2 Positive Driver | +2 |
-| Addresses Priority 3 Positive Driver | +1 |
-| **Addresses Priority 1 Negative Driver** | **+4** |
-| **Addresses Priority 2 Negative Driver** | **+3** |
-| **Addresses Priority 3 Negative Driver** | **+2** |
-| Serves multiple target groups | +2 bonus |
+| Impact | Points |
+| -------------------------------------------- | -------- |
+| Serves Priority 1 Target Group | +3 |
+| Serves Priority 2 Target Group | +2 |
+| Serves Priority 3 Target Group | +1 |
+| Addresses Priority 1 Positive Driver | +3 |
+| Addresses Priority 2 Positive Driver | +2 |
+| Addresses Priority 3 Positive Driver | +1 |
+| **Addresses Priority 1 Negative Driver** | **+4** |
+| **Addresses Priority 2 Negative Driver** | **+3** |
+| **Addresses Priority 3 Negative Driver** | **+2** |
+| Serves multiple target groups | +2 bonus |
| Addresses both positive AND negative drivers | +2 bonus |
> **Why negative drivers score higher:** Loss aversion is a well-documented psychological principle - humans work harder to avoid pain than to pursue gain. Features that remove friction, fear, or frustration create stronger user loyalty than features that simply add benefits.
**Example:**
-| Feature | Target Groups | Driving Forces | Score |
-|---------|---------------|----------------|-------|
+| Feature | Target Groups | Driving Forces | Score |
+| ----------------- | --------------------------------- | --------------------------------------------------------------------------------- | ------ |
| One-click booking | P1 Dog Owner (+3), P2 Walker (+2) | Convenience (+3), Fear of complexity (-P1: +4), Multi-group (+2), Both types (+2) | **16** |
-| Review system | P1 Dog Owner (+3) | Trust (+2), Fear of bad walker (-P1: +4), Both types (+2) | **11** |
-| Calendar sync | P2 Walker (+2) | Efficiency (+1) | **3** |
+| Review system | P1 Dog Owner (+3) | Trust (+2), Fear of bad walker (-P1: +4), Both types (+2) | **11** |
+| Calendar sync | P2 Walker (+2) | Efficiency (+1) | **3** |
**The Output:**
A ranked feature list showing:
+
- Which features have the broadest impact
- Which features are "single-purpose" vs "multi-impact"
- Natural MVP candidates (highest scores)
@@ -220,11 +232,13 @@ Traditional personas describe demographics: "Jennifer, 34, likes yoga and lattes
WDS personas capture psychology:
**Alliterative Naming** - Each persona gets a memorable name that hints at their role:
+
- "Patrick the Professional" - Decision-maker focused on efficiency
- "Sophie the Socializer" - Values connection and community
- "Tyler the Technical" - Wants control and customization
**What Each Persona Includes:**
+
- Role and context
- Goals they're trying to achieve
- Fears and frustrations
@@ -237,16 +251,19 @@ WDS personas capture psychology:
## When to Use This Phase
**Use after Phase 1 if:**
+
- Building a new product
- Need clarity on who you're building for
- Want design decisions grounded in user psychology
**Start here if:**
+
- You have product vision but unclear user strategy
- Existing personas feel shallow or unused
- Features aren't connecting with users
**Skip if:**
+
- Quick enhancement to existing feature
- Users are already well-documented and validated
- Design system work without new user research
@@ -256,6 +273,7 @@ WDS personas capture psychology:
## What to Prepare
Bring:
+
- Your completed Product Brief (Phase 1)
- Any existing user research (even informal)
- Stakeholder availability for the workshop
@@ -277,15 +295,18 @@ The trigger map becomes the strategic brain of your product.
## Tips for Great Sessions
**Think strategically, not demographically**
+
- "Who needs to win for us to win?" not "Who might use this?"
- Connect every user insight to business outcomes
**Go deep on psychology**
+
- Push beyond surface responses
- Ask "why" multiple times
- Understand motivations, not just behaviors
**Build the map live**
+
- See connections as they emerge
- Validate strategic logic together
- Make it visual and shareable
@@ -298,5 +319,4 @@ See: `examples/dog-week-patterns/B-Trigger-Map/` for a complete Trigger Map with
---
-*Phase 2 of the Whiteport Design Studio method*
-
+_Phase 2 of the Whiteport Design Studio method_
diff --git a/src/modules/wds/docs/method/phase-3-prd-platform-guide.md b/src/modules/wds/docs/method/phase-3-prd-platform-guide.md
index 1fd005ad..813f0ea0 100644
--- a/src/modules/wds/docs/method/phase-3-prd-platform-guide.md
+++ b/src/modules/wds/docs/method/phase-3-prd-platform-guide.md
@@ -18,6 +18,7 @@ By the end, you'll have a solid technical foundation and confidence that your ke
**Prove our concept works technically — in parallel with design work.**
While UX designers explore how users interact with features, technical validation runs alongside:
+
- Can we actually build this?
- Do the external services we need exist and work as expected?
- What platform and infrastructure do we need?
@@ -46,12 +47,14 @@ Design and technical validation inform each other. Neither waits for the other t
Establish the technical foundation:
**Architecture:**
+
- What technology stack fits your needs?
- Monolith vs. microservices vs. serverless?
- What hosting/infrastructure approach?
- What are the key technical constraints?
**Data Model:**
+
- What are the core entities?
- How do they relate to each other?
- What's the database strategy?
@@ -72,15 +75,16 @@ Identify all external dependencies:
**Examples:**
-| Feature Idea | Proof of Concept Question |
-|--------------|---------------------------|
+| Feature Idea | Proof of Concept Question |
+| ----------------------------------- | ------------------------------------------------------------------ |
| "Show drive time between locations" | Can we call Google Maps Directions API and get estimated duration? |
-| "Real-time availability updates" | Can we set up WebSocket connections that scale? |
-| "AI-powered recommendations" | Does the ML model perform well enough with our data? |
-| "Offline mode" | Can we sync data reliably when connection returns? |
-| "Video calling" | Which provider works best? What's the latency? |
+| "Real-time availability updates" | Can we set up WebSocket connections that scale? |
+| "AI-powered recommendations" | Does the ML model perform well enough with our data? |
+| "Offline mode" | Can we sync data reliably when connection returns? |
+| "Video calling" | Which provider works best? What's the latency? |
**What a PoC validates:**
+
- The API/service exists and does what we need
- Performance is acceptable
- Cost is within budget
@@ -88,6 +92,7 @@ Identify all external dependencies:
- Edge cases are handleable
**PoC Output:**
+
- Working code snippet or prototype
- Documented limitations and gotchas
- Cost estimates (API calls, compute, etc.)
@@ -98,12 +103,14 @@ Identify all external dependencies:
### Stage 4: Security & Performance Framework (20-30 minutes)
**Security:**
+
- Authentication approach (passwords, OAuth, SSO, passwordless)
- Authorization model (roles, permissions, row-level security)
- Data encryption needs (at rest, in transit)
- Compliance requirements (GDPR, HIPAA, PCI-DSS, etc.)
**Performance:**
+
- Expected load and scale
- Response time expectations
- Availability requirements (99.9%? 99.99%?)
@@ -122,16 +129,17 @@ Even before the UI is designed, you often know certain data operations are essen
**What to set up:**
-| Endpoint Type | Example | Why Early? |
-|---------------|---------|------------|
-| Core CRUD | `GET /api/dogs`, `POST /api/bookings` | Foundation for everything |
+| Endpoint Type | Example | Why Early? |
+| --------------------- | ---------------------------------------- | --------------------------- |
+| Core CRUD | `GET /api/dogs`, `POST /api/bookings` | Foundation for everything |
| External integrations | `GET /api/routes/estimate` (Google Maps) | Validates third-party works |
-| Authentication | `/api/auth/login`, `/api/auth/refresh` | Security model proven |
-| Key calculations | `/api/availability/check` | Business logic validated |
+| Authentication | `/api/auth/login`, `/api/auth/refresh` | Security model proven |
+| Key calculations | `/api/availability/check` | Business logic validated |
**Output:**
For each experimental endpoint, document:
+
- Endpoint specification (method, path, request/response)
- What it validates
- Current status (stub, working, blocked)
@@ -196,12 +204,14 @@ This parallelism is one of WDS's key efficiency gains. Development teams can beg
## When to Use This Phase
**Use this phase when:**
+
- Building platform/infrastructure for a new product
- Features depend on external APIs or services
- Innovative features need technical validation
- Development team needs architectural clarity before design
**Skip or minimize if:**
+
- Simple project with obvious technical approach
- Working within existing platform/infrastructure
- Enhancement that doesn't change architecture
@@ -212,6 +222,7 @@ This parallelism is one of WDS's key efficiency gains. Development teams can beg
## What to Prepare
Bring:
+
- Product Brief (Phase 1)
- Trigger Map with Feature Impact Analysis (Phase 2)
- Any existing technical constraints
@@ -232,19 +243,23 @@ Your technical foundation enables:
## Tips for Great Sessions
**Validate risky features first**
+
- If the Google Maps API doesn't return drive times in a usable format, you need to know NOW
- Don't design features you can't build
**Document constraints clearly**
+
- Designers need to know what's possible
- "Loading state required" vs "instant" changes UX significantly
**Involve developers**
+
- Technical decisions benefit from dev input
- PoC work may require developer time
- Architecture is a conversation, not a decree
**Stay connected to strategy**
+
- Reference Feature Impact Analysis scores
- High-impact features deserve more PoC investment
- Don't over-engineer for hypothetical needs
@@ -257,13 +272,13 @@ See: `examples/dog-week-patterns/C-Requirements/` for the Dog Week technical fou
**What Dog Week needed to prove early:**
-- *"Can we show dog owners how long it takes to walk to a dog walker?"* → Google Maps Directions API returns walking time between coordinates ✓
-- *"Can we check real-time availability across multiple walkers?"* → Endpoint aggregates calendar data in <200ms ✓
-- *"Can we handle Swish payments for Swedish users?"* → Swish API integration validated with test transactions ✓
-- *"Can walkers see their schedule on mobile?"* → Responsive calendar component renders correctly on iOS/Android browsers ✓
+- _"Can we show dog owners how long it takes to walk to a dog walker?"_ → Google Maps Directions API returns walking time between coordinates ✓
+- _"Can we check real-time availability across multiple walkers?"_ → Endpoint aggregates calendar data in <200ms ✓
+- _"Can we handle Swish payments for Swedish users?"_ → Swish API integration validated with test transactions ✓
+- _"Can walkers see their schedule on mobile?"_ → Responsive calendar component renders correctly on iOS/Android browsers ✓
These early discoveries shaped both the design AND the development approach.
---
-*Phase 3 of the Whiteport Design Studio method*
+_Phase 3 of the Whiteport Design Studio method_
diff --git a/src/modules/wds/docs/method/phase-4-ux-design-guide.md b/src/modules/wds/docs/method/phase-4-ux-design-guide.md
index c901cc06..89862795 100644
--- a/src/modules/wds/docs/method/phase-4-ux-design-guide.md
+++ b/src/modules/wds/docs/method/phase-4-ux-design-guide.md
@@ -30,45 +30,55 @@ For each scenario/page:
## How Freyja the WDS Designer helps you design software
### 4A: Scenario Exploration
+
**When:** Discovering the Concept, the process, flow screen or component solution together, before sketching begin
Freyja helps you:
+
- Think through the user's journey
- Explore content and feature options
- Consider psychological triggers from your Trigger Map
- Arrive at a clear solution ready for sketching
### 4B: UI Sketch Analysis
+
**When:** You have a sketch and you need feedback on it
Freyja helps you:
+
- Analyze what the sketch shows
- Ask clarifying questions
- Identify all components and states
### 4C: Conceptual Specification
+
**When:** Design is clear, need development-ready specs
Freyja helps you:
+
- Document every detail systematically
- Assign Object IDs for testing
- Define all interactions and states
- Prepare multilingual content, error codes, instructions and any other content needed for the developers
### 4D: HTML Prototype
+
**When:** Specifications complete, and we make the sketch come alive to test the concept
Freyja helps you:
+
- Create interactive prototypes
- Test the design in browser
- Discover gaps and issues
-- Refine specifications
+- Refine specifications
- Visualize the concept before development
### 4E: PRD Update
+
**When:** Page design is complete, before moving to the next scenario
Freyja helps you:
+
- Identify what features this page requires
- Add functional requirements to the PRD
- Reference the page (e.g., "Required by: 2.1-Dog-Calendar")
@@ -77,6 +87,7 @@ Freyja helps you:
**Why this step matters:**
Each page reveals concrete requirements:
+
- "This form needs email validation"
- "We need a GET endpoint for availability"
- "Users need to upload images here"
@@ -89,13 +100,17 @@ Capturing these while the page is fresh ensures nothing is forgotten. The PRD be
## Functional Requirements
### Email Validation
+
**Required by:** 1.2-Sign-Up, 2.3-Profile-Edit
+
- Validate format on input
- Check domain exists
- Prevent duplicates
### Availability Calendar API
+
**Required by:** 2.1-Dog-Calendar, 3.1-Booking-Flow
+
- GET /api/walkers/{id}/availability
- Returns 2-week window
- Updates via WebSocket
@@ -123,6 +138,7 @@ C-Scenarios/
```
**Numbering Convention:**
+
- Scenarios: 01, 02, 03...
- Pages within scenarios: 1.1, 1.2, 2.1, 2.2...
@@ -131,6 +147,7 @@ C-Scenarios/
## Object IDs
Every interactive element gets an Object ID for:
+
- Consistent naming across specs and code
- Test automation with stable selectors
- Analytics tracking
@@ -139,6 +156,7 @@ Every interactive element gets an Object ID for:
**Format:** `{page}-{section}-{element}` in kebab-case
**Example:**
+
```
welcome-page-hero-cta-button
signin-form-email-input
@@ -150,8 +168,10 @@ signin-form-error-email
**When Design System is enabled** (Phase 5), each object in your specification includes component library references:
**Example specification entry:**
+
```markdown
### Submit Button
+
**Object ID:** `signin-form-submit-button`
**Component:** primary-button (from Design System)
**Figma Component:** Primary Button
@@ -162,6 +182,7 @@ Triggers form validation and submission...
```
**Benefits:**
+
- Designers know which Figma component to use
- Developers know which code component to implement
- Design System ensures consistency
@@ -177,6 +198,7 @@ Just describe the element directly in the specification without component refere
Specification isn't just documentation - it's design validation.
When you try to specify every detail, you discover:
+
- "What happens when this is empty?"
- "How does this look on mobile?"
- "What if the user does X before Y?"
@@ -191,12 +213,14 @@ Finding these gaps now means addressing them while solutions are still flexible.
Interactive prototypes that validate your design:
**What they include:**
+
- Semantic HTML matching your specs
- CSS using your Design System tokens
- JavaScript for interactions and validation
- Multilingual content switching
**What they reveal:**
+
- Visual gaps ("the spacing doesn't match")
- Interaction issues ("we forgot the loading state")
- Component needs ("we need a phone input component")
@@ -204,6 +228,7 @@ Interactive prototypes that validate your design:
- Flow issues ("this navigation doesn't make sense")
**File Structure:**
+
```
1.1-Start-Page/
├── 1.1-Start-Page.md (specification)
@@ -220,20 +245,24 @@ Interactive prototypes that validate your design:
## When to Use This Phase
**Use this phase when:**
+
- Ready to design specific screens/pages
- Have strategic clarity from Phase 1-2
- Want to validate designs before development
**Start with exploration (4A) if:**
+
- No existing sketches
- Unsure how to approach a feature
- Need to think through the user journey
**Start with analysis (4B) if:**
+
- Have sketches ready to specify
- Know what you want, need to document it
**Use HTML prototypes (4D) if:**
+
- Specifications feel complete
- Want to validate before development
- Need stakeholder sign-off
@@ -243,6 +272,7 @@ Interactive prototypes that validate your design:
## What to Prepare
Bring:
+
- Trigger Map (Phase 2) - for user psychology reference
- Any existing sketches or wireframes
- Technical constraints from PRD (Phase 3)
@@ -263,11 +293,13 @@ Your specifications enable:
## Tips for Great Sessions
**Think out loud with Freyja**
+
- Share your reasoning
- Explore alternatives together
- Let the conversation reveal insights
**Be thorough with states**
+
- Empty states
- Loading states
- Error states
@@ -275,11 +307,13 @@ Your specifications enable:
- Edge cases
**Don't skip the prototype**
+
- Click through your design
- Find the gaps before development
- Refine specs based on what you learn
**Reference your Trigger Map**
+
- Does this serve the user's goals?
- Does this avoid their fears?
- Does this support business objectives?
@@ -292,5 +326,4 @@ See: `examples/dog-week-patterns/C-Scenarios/` for complete scenario specificati
---
-*Phase 4 of the Whiteport Design Studio method*
-
+_Phase 4 of the Whiteport Design Studio method_
diff --git a/src/modules/wds/docs/method/phase-5-design-system-guide.md b/src/modules/wds/docs/method/phase-5-design-system-guide.md
index 34e2d82e..5d3caf43 100644
--- a/src/modules/wds/docs/method/phase-5-design-system-guide.md
+++ b/src/modules/wds/docs/method/phase-5-design-system-guide.md
@@ -31,7 +31,9 @@ Your Design System includes:
Following Brad Frost's methodology:
### Foundation (Design Tokens)
+
The values everything else builds on:
+
- **Colors** - Primary, secondary, semantic (success, error, warning)
- **Typography** - Font families, sizes, weights, line heights
- **Spacing** - Consistent spacing scale
@@ -40,7 +42,9 @@ The values everything else builds on:
- **Breakpoints** - Responsive design points
### Atoms
+
The smallest building blocks:
+
- Buttons
- Input fields
- Labels
@@ -49,14 +53,18 @@ The smallest building blocks:
- Dividers
### Molecules
+
Groups of atoms working together:
+
- Form groups (label + input + error)
- Search bars (input + button)
- Card headers (title + action)
- Navigation items (icon + label)
### Organisms
+
Complex components made of molecules:
+
- Page headers
- Navigation bars
- Form sections
@@ -69,7 +77,7 @@ Complex components made of molecules:
### The Parallel Workflow
-Phase 5 isn't a separate phase you do *after* Phase 4 - it happens **during** Phase 4:
+Phase 5 isn't a separate phase you do _after_ Phase 4 - it happens **during** Phase 4:
```
Phase 4 Page Design → Phase 5 Design System
@@ -82,6 +90,7 @@ Notice pattern across pages → Extract as reusable component
```
**The rhythm:**
+
1. Design a page/component in Phase 4
2. Notice "This could be reusable"
3. Extract to Design System
@@ -105,6 +114,7 @@ As you specify scenarios in Phase 4, components naturally emerge:
**Step 1: Spot the Pattern**
While working on Phase 4 scenarios, notice when you're designing something reusable:
+
- "I just designed this button for Page 1.1... and I need it again on Page 1.2"
- "This form input pattern will be used everywhere"
- "We have 3 different card layouts, but they share the same structure"
@@ -130,10 +140,11 @@ D-Design-System/
Use this template for each component:
-```markdown
+````markdown
# Primary Button
## Overview
+
The primary button is used for the main call-to-action on any page or section.
## Component Details
@@ -146,11 +157,13 @@ The primary button is used for the main call-to-action on any page or section.
## Variants
### Size
+
- **Small:** Compact spaces, secondary actions
- **Medium:** Default size for most use cases
- **Large:** Hero sections, important CTAs
### State
+
- **Default:** Ready for interaction
- **Hover:** Visual feedback on mouse over
- **Active:** Currently being clicked
@@ -160,6 +173,7 @@ The primary button is used for the main call-to-action on any page or section.
## Visual Specifications
**Design Tokens:**
+
- Background: `color-primary-500`
- Text: `color-white`
- Border Radius: `radius-md`
@@ -167,6 +181,7 @@ The primary button is used for the main call-to-action on any page or section.
- Font: `font-semibold`, `text-base`
**States:**
+
- Hover: `color-primary-600`
- Active: `color-primary-700`
- Disabled: `color-gray-300`, opacity 50%
@@ -174,12 +189,14 @@ The primary button is used for the main call-to-action on any page or section.
## Usage Guidelines
**When to use:**
+
- Primary action on a page or modal
- Main CTA in hero sections
- Form submissions
- Confirmation actions
**When NOT to use:**
+
- Multiple primary actions (use secondary instead)
- Destructive actions (use danger variant)
- Navigation (use links or secondary buttons)
@@ -194,20 +211,26 @@ The primary button is used for the main call-to-action on any page or section.
## Example Usage
**In specifications:**
+
```markdown
### Submit Button
+
**Object ID:** `contact-form-submit-button`
**Component:** primary-button
**Variant:** size=large
**State:** default → loading → success
```
+````
**In Figma:**
Use "Primary Button" component from library
**In Code (if using Chakra):**
+
```jsx
-
+
```
## Used In
@@ -216,6 +239,7 @@ Use "Primary Button" component from library
- 1.2-Sign-Up: Submit registration
- 2.1-Contact-Form: Send message
- [Update as you use the component]
+
```
**Step 4: Update as You Go**
@@ -230,23 +254,25 @@ Each time you use this component in a new scenario:
**As you work through Phase 4:**
```
+
Design Page 1.1
- ↓
+↓
Notice: "This button is reusable"
- ↓
+↓
Create: primary-button.md in Design System
- ↓
+↓
Reference in 1.1 spec: component=primary-button
- ↓
+↓
Design Page 1.2
- ↓
+↓
Need same button: Reference existing component
- ↓
+↓
Design Page 2.1
- ↓
+↓
Need slightly different: Add variant to component doc
- ↓
+↓
Update all references with new variant option
+
```
---
@@ -258,15 +284,17 @@ Beyond documentation, create an **interactive HTML guide** where stakeholders an
### Structure
```
+
D-Design-System/
-├── component-showcase.html ← Interactive guide
+├── component-showcase.html ← Interactive guide
├── component-showcase.css
├── component-showcase.js
├── 01-design-tokens.md
├── 02-atoms/
-│ ├── primary-button.md
-│ └── ...
-```
+│ ├── primary-button.md
+│ └── ...
+
+````
### What the Showcase Includes
@@ -562,7 +590,7 @@ These libraries work well with WDS's specification approach:
**When to use:**
Primary call-to-action buttons...
-```
+````
---
@@ -574,11 +602,11 @@ Your WDS component system connects to your visual design tools (Figma, Sketch, A
**Use the exact same names across all tools:**
-| WDS Component Name | Figma Component | Code Component | Object ID |
-|-------------------|-----------------|----------------|-----------|
-| `primary-button` | Primary Button | `PrimaryButton` | `*-primary-button` |
-| `text-input` | Text Input | `TextInput` | `*-text-input` |
-| `form-group` | Form Group | `FormGroup` | `*-form-group` |
+| WDS Component Name | Figma Component | Code Component | Object ID |
+| ------------------ | --------------- | --------------- | ------------------ |
+| `primary-button` | Primary Button | `PrimaryButton` | `*-primary-button` |
+| `text-input` | Text Input | `TextInput` | `*-text-input` |
+| `form-group` | Form Group | `FormGroup` | `*-form-group` |
### The Workflow
@@ -598,6 +626,7 @@ signin-form-submit-primary-button (everywhere)
**Component Library Structure:**
Match your WDS atomic design structure:
+
```
Design File/
├── 🎨 Design Tokens
@@ -618,6 +647,7 @@ Design File/
```
**Naming in Figma:**
+
- Component names match WDS names (kebab-case or Title Case)
- Variants match WDS variants (Primary, Secondary, Disabled)
- Properties match WDS states (default, hover, active, error)
@@ -644,18 +674,23 @@ Design File/
The design system is living documentation that grows with your product:
### Starting Point
+
Begin with what you need for current scenarios:
+
- Extract components from Phase 4 work
- Document only what you're actually using
- Avoid speculating about future needs
### Evolution
+
As you design more scenarios:
+
- New patterns emerge → add to system
- Inconsistencies appear → consolidate
- Components evolve → update documentation
### Maintenance
+
- Keep specs in sync with implementation
- Remove unused components
- Update when design language evolves
@@ -665,24 +700,28 @@ As you design more scenarios:
## When to Use This Phase
**Enable Design System phase if:**
+
- Building reusable component library
- Multiple pages/scenarios with shared patterns
- Need design consistency across product
- Handoff requires component documentation
**Work in parallel with Phase 4 when enabled:**
+
- As you sketch, identify component patterns
- As you specify, extract to Design System
- Design System grows with each page completed
- No separate "design system phase" at the end
**Skip this phase if:**
+
- Small project (single landing page)
- Using existing design system (Material, Chakra, etc.)
- One-off designs without reuse
- Quick prototype or MVP without component library needs
**Dedicated consolidation when:**
+
- Multiple scenarios complete, need cleanup
- Preparing for development handoff
- Found inconsistencies to resolve
@@ -695,6 +734,7 @@ As you design more scenarios:
## What to Prepare
Bring:
+
- Completed or in-progress scenario specs (Phase 4)
- Any existing brand guidelines
- Technical framework constraints (React components, etc.)
@@ -714,21 +754,25 @@ Your Design System enables:
## Tips for Great Sessions
**Extract, don't invent**
+
- Components should come from real design needs
- Don't create components "just in case"
- Let the system grow from actual scenarios
**Document the why**
+
- Why does this button look this way?
- What user trigger does it serve?
- When should developers use variant A vs B?
**Stay consistent**
+
- Same component = same specification
- Variations should be intentional
- When in doubt, simplify
**Connect to psychology**
+
- Every design choice serves a purpose
- Reference your Trigger Map
- Components should feel intentional, not arbitrary
@@ -741,5 +785,4 @@ See: `examples/dog-week-patterns/D-Design-System/` for a complete Design System
---
-*Phase 5 of the Whiteport Design Studio method*
-
+_Phase 5 of the Whiteport Design Studio method_
diff --git a/src/modules/wds/docs/method/phase-6-integration-guide.md b/src/modules/wds/docs/method/phase-6-integration-guide.md
index 288e11af..7ae3fa6f 100644
--- a/src/modules/wds/docs/method/phase-6-integration-guide.md
+++ b/src/modules/wds/docs/method/phase-6-integration-guide.md
@@ -21,6 +21,7 @@ By the end, developers have a complete PRD covering both technical foundation an
**Updated PRD (C-Requirements/) includes:**
**From Phase 3 (Technical Foundation):**
+
- Platform architecture
- Data model
- Integration map
@@ -29,6 +30,7 @@ By the end, developers have a complete PRD covering both technical foundation an
- Security framework
**Added from Phase 4 (Functional Requirements):**
+
- All features discovered during page design
- Page-to-feature traceability
- Priority rankings
@@ -36,12 +38,14 @@ By the end, developers have a complete PRD covering both technical foundation an
- Implementation notes
**New in Phase 6:**
+
- Feature organization by epic/area
- Development sequence
- MVP scope definition
- Technical dependencies mapped
**Handoff Package (E-UI-Roadmap/):**
+
- Priority sequence document
- Scenario-to-development mapping
- Component inventory (if Design System enabled)
@@ -86,18 +90,21 @@ From 2.1-Dog-Calendar:
### Features
**User Registration**
+
- Required by: 1.2-Sign-Up
- Email validation (format, domain, duplicates)
- Phone validation with country codes
- Account activation flow
**User Login**
+
- Required by: 1.1-Start-Page, multiple pages
- Email/password authentication
- Session management (30-day persistence)
- "Remember me" functionality
**Password Management**
+
- Required by: 1.1-Start-Page (reset link)
- Password reset via email
- Password strength validation
@@ -114,9 +121,11 @@ Reference the scoring you did in Phase 2 to inform priorities:
## Development Sequence
### Priority 1: MVP - Core User Flow
+
**Target:** Weeks 1-4
Features from Epic 1 (Authentication) + Epic 2 (Core Booking):
+
- User registration (Impact Score: 14)
- User login (Impact Score: 16)
- Availability calendar (Impact Score: 16)
@@ -126,9 +135,11 @@ Features from Epic 1 (Authentication) + Epic 2 (Core Booking):
Serves Priority 1 target group, addresses highest-impact drivers.
### Priority 2: Enhanced Features
+
**Target:** Weeks 5-8
Features from Epic 3 (Payments) + Epic 4 (Notifications):
+
- Payment processing (Impact Score: 12)
- Booking confirmations (Impact Score: 11)
- Calendar sync (Impact Score: 8)
@@ -142,6 +153,7 @@ Features from Epic 3 (Payments) + Epic 4 (Notifications):
## Feature Dependencies
**Booking Flow** depends on:
+
- ✓ User authentication (must be logged in)
- ✓ Availability calendar (must see open slots)
- ⚠️ Payment system (can launch with "pay in person" temporarily)
@@ -173,21 +185,25 @@ Your finalized PRD in `C-Requirements/` combines all phases:
## 1. Technical Foundation (from Phase 3)
### Platform Architecture
+
- Technology stack decisions
-- Infrastructure approach
+- Infrastructure approach
- Hosting and deployment
### Data Model
+
- Core entities and relationships
- Database schema
- Data flow diagrams
### Integrations
+
- External services (Google Maps, Stripe, etc.)
- API specifications
- Authentication providers
### Security & Performance
+
- Authentication/authorization approach
- Data protection
- Performance requirements
@@ -196,7 +212,9 @@ Your finalized PRD in `C-Requirements/` combines all phases:
## 2. Functional Requirements (from Phase 4)
### Epic 1: User Authentication & Account Management
+
**Features:**
+
- User registration (Required by: 1.2-Sign-Up)
- User login (Required by: 1.1-Start-Page, multiple)
- Password management (Required by: 1.1-Start-Page)
@@ -204,25 +222,30 @@ Your finalized PRD in `C-Requirements/` combines all phases:
[Detailed specifications for each feature]
### Epic 2: [Next Epic]
+
[...]
## 3. Development Roadmap (from Phase 6)
### Priority 1: MVP (Weeks 1-4)
+
- Features list with Impact Scores
- Why these first (references Trigger Map)
- Timeline estimate
- Dependencies
### Priority 2: Enhanced Features (Weeks 5-8)
+
[...]
## 4. Dependencies & Constraints
+
- Technical dependencies between features
- Design constraints from Phase 4
- Third-party limitations discovered in Phase 3
## 5. Success Metrics
+
- Business goals from Phase 1
- Feature-specific KPIs
- How we measure success
@@ -235,7 +258,7 @@ Your finalized PRD in `C-Requirements/` combines all phases:
**The pattern:**
- **Phase 3:** Initial PRD with technical foundation
-- **Phase 4:** PRD grows with each page (step 4E adds requirements)
+- **Phase 4:** PRD grows with each page (step 4E adds requirements)
- **Phase 6 (First time):** Organize MVP scope from completed scenarios
- Create first handoff package
- Development can begin
@@ -251,12 +274,14 @@ Your finalized PRD in `C-Requirements/` combines all phases:
## When to Use This Phase
**First PRD Finalization when:**
+
- You have MVP-level scenarios complete (enough for dev to start)
-- Core user flows are specified
+- Core user flows are specified
- Critical features are documented
- Enough work for 2-4 week sprint
**Ongoing PRD Updates as:**
+
- Additional scenarios complete
- New feature areas designed
- Priorities shift based on learning
@@ -285,12 +310,12 @@ Week 9+: Design continues in parallel with development
Complete list for test automation:
-| Scenario | Object ID | Element Type | Notes |
-|----------|-----------|--------------|-------|
-| 1.1 | `welcome-hero-cta` | Button | Primary action |
-| 1.1 | `welcome-signin-link` | Link | Secondary action |
-| 1.2 | `signin-email-input` | Input | Required field |
-| 1.2 | `signin-error-email` | Error | Validation message |
+| Scenario | Object ID | Element Type | Notes |
+| -------- | --------------------- | ------------ | ------------------ |
+| 1.1 | `welcome-hero-cta` | Button | Primary action |
+| 1.1 | `welcome-signin-link` | Link | Secondary action |
+| 1.2 | `signin-email-input` | Input | Required field |
+| 1.2 | `signin-error-email` | Error | Validation message |
---
@@ -299,6 +324,7 @@ Complete list for test automation:
### Review Completeness
Before handoff, verify:
+
- All scenarios specified and reviewed
- Design system covers all components
- Object IDs assigned throughout
@@ -308,6 +334,7 @@ Before handoff, verify:
### Identify Priorities
With Freyja, map your Trigger Map priorities to development order:
+
- Which user triggers are most critical?
- What's the minimum viable experience?
- What can wait for later releases?
@@ -315,6 +342,7 @@ With Freyja, map your Trigger Map priorities to development order:
### Document Technical Context
Capture what developers need to know:
+
- Design decisions and their rationale
- Technical constraints discovered during design
- Interaction patterns that need special attention
@@ -323,6 +351,7 @@ Capture what developers need to know:
### Create the Handoff
Organize everything into the UI Roadmap folder:
+
- Clear priority sequence
- Complete component inventory
- Technical notes and open questions
@@ -336,26 +365,31 @@ Organize everything into the UI Roadmap folder:
## Design Handoff Verification
### Product Foundation
+
- [ ] Product Brief complete and current
- [ ] Trigger Map with prioritized users and goals
- [ ] ICP clearly defined
### Requirements
+
- [ ] PRD with technical specifications
- [ ] Platform architecture documented
- [ ] Integration requirements listed
### Visual Design
+
- [ ] All scenarios have specifications
- [ ] All pages have Object IDs
- [ ] States documented (empty, loading, error, success)
### Design System
+
- [ ] All components documented
- [ ] Design tokens defined
- [ ] Usage guidelines written
### Validation
+
- [ ] HTML prototypes created for key scenarios
- [ ] Stakeholder review complete
- [ ] Open questions documented
@@ -368,12 +402,14 @@ Organize everything into the UI Roadmap folder:
## When to Use This Phase
**First handoff when:**
+
- You have enough scenarios for MVP
- Core user flows are specified
- Critical components are documented
- Developers can start building foundational features
**Ongoing handoffs as:**
+
- Each major scenario completes
- New component patterns emerge
- Design decisions affect development
@@ -402,6 +438,7 @@ Development and design work in parallel streams, with regular sync points.
## What to Prepare
Bring:
+
- Completed scenario specifications (Phase 4)
- Design System (Phase 5)
- PRD (Phase 3)
@@ -423,21 +460,25 @@ Your UI Roadmap enables:
## Tips for Great Sessions
**Think from dev perspective**
+
- What questions will developers have?
- What decisions can't you make for them?
- What context will save them time?
**Be explicit about priorities**
+
- Not everything is Priority 1
- Make trade-offs visible
- Connect priorities to business goals
**Document the unknowns**
+
- Open questions are valuable
- Don't pretend certainty you don't have
- Let dev team contribute decisions
**Keep it updated**
+
- Handoff is ongoing, not one-time
- Update as design evolves
- Maintain as source of truth
@@ -453,6 +494,7 @@ WDS → E-UI-Roadmap/ → BMM Architecture & Stories
```
The UI Roadmap provides:
+
- Context for architecture decisions
- Specifications for story creation
- Priorities for sprint planning
@@ -466,5 +508,4 @@ See: `examples/dog-week-patterns/E-UI-Roadmap/` for a complete UI Roadmap from a
---
-*Phase 6 of the Whiteport Design Studio method*
-
+_Phase 6 of the Whiteport Design Studio method_
diff --git a/src/modules/wds/docs/method/phase-6-prd-finalization-guide.md b/src/modules/wds/docs/method/phase-6-prd-finalization-guide.md
index 9f642442..02b21e31 100644
--- a/src/modules/wds/docs/method/phase-6-prd-finalization-guide.md
+++ b/src/modules/wds/docs/method/phase-6-prd-finalization-guide.md
@@ -20,6 +20,7 @@ By the end, developers have a complete PRD covering both technical foundation an
**Updated PRD (C-Requirements/) includes:**
**From Phase 3 (Technical Foundation):**
+
- Platform architecture
- Data model
- Integration map
@@ -28,6 +29,7 @@ By the end, developers have a complete PRD covering both technical foundation an
- Security framework
**Added from Phase 4 (Functional Requirements):**
+
- All features discovered during page design
- Page-to-feature traceability
- Priority rankings
@@ -35,12 +37,14 @@ By the end, developers have a complete PRD covering both technical foundation an
- Implementation notes
**New in Phase 6:**
+
- Feature organization by epic/area
- Development sequence
- MVP scope definition
- Technical dependencies mapped
**Handoff Package (E-UI-Roadmap/):**
+
- Priority sequence document
- Scenario-to-development mapping
- Component inventory (if Design System enabled)
@@ -85,18 +89,21 @@ From 2.1-Dog-Calendar:
### Features
**User Registration**
+
- Required by: 1.2-Sign-Up
- Email validation (format, domain, duplicates)
- Phone validation with country codes
- Account activation flow
**User Login**
+
- Required by: 1.1-Start-Page, multiple pages
- Email/password authentication
- Session management (30-day persistence)
- "Remember me" functionality
**Password Management**
+
- Required by: 1.1-Start-Page (reset link)
- Password reset via email
- Password strength validation
@@ -113,9 +120,11 @@ Reference the scoring you did in Phase 2 to inform priorities:
## Development Sequence
### Priority 1: MVP - Core User Flow
+
**Target:** Weeks 1-4
Features from Epic 1 (Authentication) + Epic 2 (Core Booking):
+
- User registration (Impact Score: 14)
- User login (Impact Score: 16)
- Availability calendar (Impact Score: 16)
@@ -125,9 +134,11 @@ Features from Epic 1 (Authentication) + Epic 2 (Core Booking):
Serves Priority 1 target group, addresses highest-impact drivers.
### Priority 2: Enhanced Features
+
**Target:** Weeks 5-8
Features from Epic 3 (Payments) + Epic 4 (Notifications):
+
- Payment processing (Impact Score: 12)
- Booking confirmations (Impact Score: 11)
- Calendar sync (Impact Score: 8)
@@ -141,6 +152,7 @@ Features from Epic 3 (Payments) + Epic 4 (Notifications):
## Feature Dependencies
**Booking Flow** depends on:
+
- ✓ User authentication (must be logged in)
- ✓ Availability calendar (must see open slots)
- ⚠️ Payment system (can launch with "pay in person" temporarily)
@@ -172,21 +184,25 @@ Your finalized PRD in `C-Requirements/` combines all phases:
## 1. Technical Foundation (from Phase 3)
### Platform Architecture
+
- Technology stack decisions
-- Infrastructure approach
+- Infrastructure approach
- Hosting and deployment
### Data Model
+
- Core entities and relationships
- Database schema
- Data flow diagrams
### Integrations
+
- External services (Google Maps, Stripe, etc.)
- API specifications
- Authentication providers
### Security & Performance
+
- Authentication/authorization approach
- Data protection
- Performance requirements
@@ -195,7 +211,9 @@ Your finalized PRD in `C-Requirements/` combines all phases:
## 2. Functional Requirements (from Phase 4)
### Epic 1: User Authentication & Account Management
+
**Features:**
+
- User registration (Required by: 1.2-Sign-Up)
- User login (Required by: 1.1-Start-Page, multiple)
- Password management (Required by: 1.1-Start-Page)
@@ -203,25 +221,30 @@ Your finalized PRD in `C-Requirements/` combines all phases:
[Detailed specifications for each feature]
### Epic 2: [Next Epic]
+
[...]
## 3. Development Roadmap (from Phase 6)
### Priority 1: MVP (Weeks 1-4)
+
- Features list with Impact Scores
- Why these first (references Trigger Map)
- Timeline estimate
- Dependencies
### Priority 2: Enhanced Features (Weeks 5-8)
+
[...]
## 4. Dependencies & Constraints
+
- Technical dependencies between features
- Design constraints from Phase 4
- Third-party limitations discovered in Phase 3
## 5. Success Metrics
+
- Business goals from Phase 1
- Feature-specific KPIs
- How we measure success
@@ -234,7 +257,7 @@ Your finalized PRD in `C-Requirements/` combines all phases:
**The pattern:**
- **Phase 3:** Initial PRD with technical foundation
-- **Phase 4:** PRD grows with each page (step 4E adds requirements)
+- **Phase 4:** PRD grows with each page (step 4E adds requirements)
- **Phase 6 (First time):** Organize MVP scope from completed scenarios
- Create first handoff package
- Development can begin
@@ -250,12 +273,14 @@ Your finalized PRD in `C-Requirements/` combines all phases:
## When to Use This Phase
**First PRD Finalization when:**
+
- You have MVP-level scenarios complete (enough for dev to start)
-- Core user flows are specified
+- Core user flows are specified
- Critical features are documented
- Enough work for 2-4 week sprint
**Ongoing PRD Updates as:**
+
- Additional scenarios complete
- New feature areas designed
- Priorities shift based on learning
@@ -284,12 +309,12 @@ Week 9+: Design continues in parallel with development
Complete list for test automation:
-| Scenario | Object ID | Element Type | Notes |
-|----------|-----------|--------------|-------|
-| 1.1 | `welcome-hero-cta` | Button | Primary action |
-| 1.1 | `welcome-signin-link` | Link | Secondary action |
-| 1.2 | `signin-email-input` | Input | Required field |
-| 1.2 | `signin-error-email` | Error | Validation message |
+| Scenario | Object ID | Element Type | Notes |
+| -------- | --------------------- | ------------ | ------------------ |
+| 1.1 | `welcome-hero-cta` | Button | Primary action |
+| 1.1 | `welcome-signin-link` | Link | Secondary action |
+| 1.2 | `signin-email-input` | Input | Required field |
+| 1.2 | `signin-error-email` | Error | Validation message |
---
@@ -298,6 +323,7 @@ Complete list for test automation:
### Review Completeness
Before handoff, verify:
+
- All scenarios specified and reviewed
- Design system covers all components
- Object IDs assigned throughout
@@ -307,6 +333,7 @@ Before handoff, verify:
### Identify Priorities
With Freyja, map your Trigger Map priorities to development order:
+
- Which user triggers are most critical?
- What's the minimum viable experience?
- What can wait for later releases?
@@ -314,6 +341,7 @@ With Freyja, map your Trigger Map priorities to development order:
### Document Technical Context
Capture what developers need to know:
+
- Design decisions and their rationale
- Technical constraints discovered during design
- Interaction patterns that need special attention
@@ -322,6 +350,7 @@ Capture what developers need to know:
### Create the Handoff
Organize everything into the UI Roadmap folder:
+
- Clear priority sequence
- Complete component inventory
- Technical notes and open questions
@@ -335,26 +364,31 @@ Organize everything into the UI Roadmap folder:
## Design Handoff Verification
### Product Foundation
+
- [ ] Product Brief complete and current
- [ ] Trigger Map with prioritized users and goals
- [ ] ICP clearly defined
### Requirements
+
- [ ] PRD with technical specifications
- [ ] Platform architecture documented
- [ ] Integration requirements listed
### Visual Design
+
- [ ] All scenarios have specifications
- [ ] All pages have Object IDs
- [ ] States documented (empty, loading, error, success)
### Design System
+
- [ ] All components documented
- [ ] Design tokens defined
- [ ] Usage guidelines written
### Validation
+
- [ ] HTML prototypes created for key scenarios
- [ ] Stakeholder review complete
- [ ] Open questions documented
@@ -367,12 +401,14 @@ Organize everything into the UI Roadmap folder:
## When to Use This Phase
**First handoff when:**
+
- You have enough scenarios for MVP
- Core user flows are specified
- Critical components are documented
- Developers can start building foundational features
**Ongoing handoffs as:**
+
- Each major scenario completes
- New component patterns emerge
- Design decisions affect development
@@ -401,6 +437,7 @@ Development and design work in parallel streams, with regular sync points.
## What to Prepare
Bring:
+
- Completed scenario specifications (Phase 4)
- Design System (Phase 5)
- PRD (Phase 3)
@@ -422,21 +459,25 @@ Your UI Roadmap enables:
## Tips for Great Sessions
**Think from dev perspective**
+
- What questions will developers have?
- What decisions can't you make for them?
- What context will save them time?
**Be explicit about priorities**
+
- Not everything is Priority 1
- Make trade-offs visible
- Connect priorities to business goals
**Document the unknowns**
+
- Open questions are valuable
- Don't pretend certainty you don't have
- Let dev team contribute decisions
**Keep it updated**
+
- Handoff is ongoing, not one-time
- Update as design evolves
- Maintain as source of truth
@@ -452,6 +493,7 @@ WDS → E-UI-Roadmap/ → BMM Architecture & Stories
```
The UI Roadmap provides:
+
- Context for architecture decisions
- Specifications for story creation
- Priorities for sprint planning
@@ -465,5 +507,4 @@ See: `examples/dog-week-patterns/E-UI-Roadmap/` for a complete UI Roadmap from a
---
-*Phase 6 of the Whiteport Design Studio method*
-
+_Phase 6 of the Whiteport Design Studio method_
diff --git a/src/modules/wds/docs/method/wds-method-guide.md b/src/modules/wds/docs/method/wds-method-guide.md
index 510f23fb..96ba06f4 100644
--- a/src/modules/wds/docs/method/wds-method-guide.md
+++ b/src/modules/wds/docs/method/wds-method-guide.md
@@ -45,12 +45,14 @@ Vision → Clarity → UX Design → Design System → PRD Complete
WDS follows six phases, each producing artifacts in your project's `docs/` folder:
### Phase 1: Product Exploration (Product Brief)
+
**Output:** `A-Product-Brief/`
**Agent:** Saga the Analyst
Establish your strategic foundation through conversational discovery. Instead of filling out questionnaires, you have a conversation that builds understanding organically.
**What you create:**
+
- Product vision and problem statement
- Market positioning and differentiation
- Success criteria and metrics
@@ -59,12 +61,14 @@ Establish your strategic foundation through conversational discovery. Instead of
---
### Phase 2: Trigger Mapping (Trigger Map)
+
**Output:** `B-Trigger-Map/`
**Agent:** Saga the Analyst
Connect business goals to user psychology through Trigger Mapping. Discover not just WHO your users are, but WHY they act and WHAT triggers their decisions.
**What you create:**
+
- Business goals (Vision + SMART objectives)
- Target groups connected to business outcomes
- Detailed personas with psychological depth
@@ -75,12 +79,14 @@ Connect business goals to user psychology through Trigger Mapping. Discover not
---
### Phase 3: PRD Platform (Technical Foundation)
+
**Output:** `C-Requirements/`
**Agent:** Freyja the PM
Prove your concept works technically - in parallel with design work. Validate platform decisions, create proofs of concept, and set up experimental endpoints.
**What you create:**
+
- Platform architecture decisions
- Data model and integrations
- Technical proofs of concept
@@ -91,6 +97,7 @@ Prove your concept works technically - in parallel with design work. Validate pl
---
### Phase 4: UX Design (UX-Sketches & Usage Scenarios)
+
**Output:** `C-Scenarios/`
**Agent:** Baldr the UX Expert
@@ -99,6 +106,7 @@ Transform ideas into detailed visual specifications. Your agent helps you think
**The key insight:** Designs that can be logically explained without gaps are easy to develop. The specification process reveals gaps early - when they're easy to address.
**What you create:**
+
- Scenario folder structure (numbered hierarchy)
- Page specifications with full detail
- Component definitions with Object IDs
@@ -109,12 +117,14 @@ Transform ideas into detailed visual specifications. Your agent helps you think
---
### Phase 5: Design System (Component Library)
+
**Output:** `D-Design-System/`
**Agent:** Baldr the UX Expert
Build your component library following atomic design principles. This phase is **optional** and runs **in parallel** with Phase 4 - as you design pages, you extract reusable components.
**What you create:**
+
- Design tokens (colors, typography, spacing)
- Atomic components (buttons, inputs, labels)
- Molecular components (form groups, cards)
@@ -125,12 +135,14 @@ Build your component library following atomic design principles. This phase is *
---
### Phase 6: PRD Finalization (Complete PRD)
+
**Output:** Complete PRD in `C-Requirements/` + `E-UI-Roadmap/`
**Agent:** Freyja the PM
Compile all functional requirements discovered during Phase 4 into a complete, development-ready PRD. This phase runs **continuously** - hand off as soon as you have MVP scope, then update as design progresses.
**What you create:**
+
- Complete PRD (Platform + Functional requirements)
- Feature organization by epic/area
- Development sequence with priorities
@@ -145,14 +157,15 @@ WDS creates an organized folder structure in your project's `docs/` folder. Duri
### Your 4 Options
-| Choice | Option A | Option B |
-|--------|----------|----------|
+| Choice | Option A | Option B |
+| ---------- | -------------------- | ----------------------- |
| **Prefix** | Letters (A, B, C...) | Numbers (01, 02, 03...) |
-| **Case** | Title-Case | lowercase |
+| **Case** | Title-Case | lowercase |
### Examples
**Letters + Title-Case** (default):
+
```
docs/
├── A-Product-Brief/
@@ -164,6 +177,7 @@ docs/
```
**Numbers + Title-Case**:
+
```
docs/
├── 01-Product-Brief/
@@ -175,6 +189,7 @@ docs/
```
**Default (Letters + Title-Case) is recommended because:**
+
- Title-Case is easier for non-technical people to read
- Letters create distinctive WDS branding
- Distinguishes WDS folders from other docs
@@ -185,14 +200,14 @@ docs/
Not every project needs all six phases. Select what you need based on your situation:
-| Project Type | Recommended Phases |
-|--------------|-------------------|
-| **Landing page** | 1, 4 |
-| **Full product (greenfield)** | All six |
-| **Feature enhancement** | 2, 4, 6 |
-| **Design system only** | 4, 5 |
-| **Strategic planning** | 1, 2 |
-| **Quick prototype** | 4 only |
+| Project Type | Recommended Phases |
+| ----------------------------- | ------------------ |
+| **Landing page** | 1, 4 |
+| **Full product (greenfield)** | All six |
+| **Feature enhancement** | 2, 4, 6 |
+| **Design system only** | 4, 5 |
+| **Strategic planning** | 1, 2 |
+| **Quick prototype** | 4 only |
Your agents will help you identify which phases fit your project.
@@ -203,29 +218,35 @@ Your agents will help you identify which phases fit your project.
Three specialized agents guide you through WDS:
### Saga the Analyst 📚
-*"The one who tells your business story"*
+
+_"The one who tells your business story"_
Saga guides you through discovery and research. She's curious, patient, and helps you uncover insights you might not have seen yourself.
**Works with you on:**
+
- Phase 1: Product Exploration
- Phase 2: Trigger Mapping
### Freyja the PM ⚔️
-*"The strategic leader who sees what must be done"*
+
+_"The strategic leader who sees what must be done"_
Freyja helps you define technical requirements and finalize the PRD for development. She balances passion with strategy, knowing when to be fierce and when to be patient.
**Works with you on:**
+
- Phase 3: PRD Platform
- Phase 6: PRD Finalization
### Baldr the UX Expert ✨
-*"The one who brings light and beauty"*
+
+_"The one who brings light and beauty"_
Baldr transforms your ideas into beautiful, detailed specifications. He cares deeply about craft and ensures every detail serves the user experience.
**Works with you on:**
+
- Phase 4: UX Design
- Phase 5: Design System
@@ -233,11 +254,12 @@ Baldr transforms your ideas into beautiful, detailed specifications. He cares de
## How Sessions Work
-WDS sessions are **conversations, not interrogations**.
+WDS sessions are **conversations, not interrogations**.
### The Rhythm
A good WDS session feels like coffee with a wise mentor:
+
- They ask something interesting
- You share your thinking
- They reflect it back, maybe adding a new angle
@@ -248,12 +270,14 @@ It never feels like filling out a form.
### What to Expect
**Your agent will:**
+
- Ask one question at a time, then listen
- Reflect back what they heard before moving on
- Build documents together with you, piece by piece
- Check in to make sure they understood correctly
**You'll leave with:**
+
- Clear documentation you helped create
- Deeper understanding of your own product
- Ready-to-use artifacts for the next phase
@@ -293,6 +317,7 @@ npx bmad-method@alpha install
## The WDS Difference
### Traditional Approach
+
- 47-question requirements spreadsheet
- Generic persona templates
- Designers work alone, then throw specs "over the wall"
@@ -300,6 +325,7 @@ npx bmad-method@alpha install
- Everyone argues about what was meant
### WDS Approach
+
- Conversations that build understanding
- Personas with psychological depth connected to business goals
- Collaborative workshops building shared understanding
@@ -333,6 +359,7 @@ C-Requirements/ ────► C-Requirements/ ────►
### Parallel Streams
Design and development can work in parallel:
+
- Phase 3 complete → Backend/platform development can start
- Phase 4 MVP scenarios complete → Phase 6 first handoff → Sprint 1 begins
- Design continues → Regular Phase 6 updates → More sprints
@@ -348,4 +375,4 @@ Design and development can work in parallel:
---
-*Whiteport Design Studio - Part of the BMad ecosystem*
+_Whiteport Design Studio - Part of the BMad ecosystem_
diff --git a/src/modules/wds/getting-started/installation.md b/src/modules/wds/getting-started/installation.md
index d79f2baa..ff919938 100644
--- a/src/modules/wds/getting-started/installation.md
+++ b/src/modules/wds/getting-started/installation.md
@@ -33,6 +33,7 @@ npm start
## Verify Installation
You should see:
+
```
✅ WDS is running
🎨 Ready to design
diff --git a/src/modules/wds/getting-started/quick-start.md b/src/modules/wds/getting-started/quick-start.md
index bf0e8031..58f2e268 100644
--- a/src/modules/wds/getting-started/quick-start.md
+++ b/src/modules/wds/getting-started/quick-start.md
@@ -82,12 +82,12 @@ You: "Yes"
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!"
```
@@ -98,6 +98,7 @@ You: "Perfect!"
## 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)
@@ -108,12 +109,15 @@ You created **why-based specifications** in 5 minutes:
## 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
---
diff --git a/src/modules/wds/getting-started/where-to-go-next.md b/src/modules/wds/getting-started/where-to-go-next.md
index 567f0618..56fbf1d9 100644
--- a/src/modules/wds/getting-started/where-to-go-next.md
+++ b/src/modules/wds/getting-started/where-to-go-next.md
@@ -18,6 +18,7 @@ Learn how to be indispensable in the AI era. Understand the paradigm shift where
**Modules 02-16: Complete WDS Workflow**
Master every phase from trigger mapping through design system to development handoff. Each module includes:
+
- **Lessons** - Theory and concepts with NotebookLM audio
- **Tutorials** - Step-by-step hands-on guides
- **Practice** - Apply to your own project
@@ -67,6 +68,7 @@ Extract design tokens, create reusable components, and generate interactive HTML
**[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
@@ -98,17 +100,21 @@ Technical details on:
## 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
diff --git a/src/modules/wds/templates/design-delivery.template.yaml b/src/modules/wds/templates/design-delivery.template.yaml
index a6b469c8..78e4e534 100644
--- a/src/modules/wds/templates/design-delivery.template.yaml
+++ b/src/modules/wds/templates/design-delivery.template.yaml
@@ -2,11 +2,11 @@
# Copy this template to: deliveries/DD-XXX-name.yaml
delivery:
- id: "DD-XXX" # Format: DD-001, DD-002, etc.
- name: "Feature Name" # Human-readable name
- type: "user_flow" # user_flow | feature | component
- status: "ready" # ready | in_progress | blocked
- priority: "high" # high | medium | low
+ id: "DD-XXX" # Format: DD-001, DD-002, etc.
+ name: "Feature Name" # Human-readable name
+ type: "user_flow" # user_flow | feature | component
+ status: "ready" # ready | in_progress | blocked
+ priority: "high" # high | medium | low
created_by: "wds-ux-expert"
created_at: "YYYY-MM-DDTHH:MM:SSZ"
updated_at: "YYYY-MM-DDTHH:MM:SSZ"
@@ -29,17 +29,17 @@ design_artifacts:
- id: "XX-scenario-name"
path: "C-Scenarios/XX-scenario-name/"
screens: ["screen1", "screen2"]
-
+
- id: "XX-scenario-name"
path: "C-Scenarios/XX-scenario-name/"
screens: ["screen1"]
-
+
user_flows:
- name: "Flow Name"
path: "C-Scenarios/flows/flow-name.excalidraw"
entry: "entry-screen"
exit: "exit-screen"
-
+
design_system:
components:
- "Component Name (variants)"
@@ -48,22 +48,22 @@ design_artifacts:
technical_requirements:
platform:
- frontend: "framework-name" # From platform-requirements.yaml
- backend: "framework-name" # From platform-requirements.yaml
-
+ frontend: "framework-name" # From platform-requirements.yaml
+ backend: "framework-name" # From platform-requirements.yaml
+
integrations:
- name: "integration-name"
purpose: "[Why this integration is needed]"
- required: true # true | false
-
+ required: true # true | false
+
- name: "integration-name"
purpose: "[Why this integration is needed]"
required: false
-
+
data_models:
- name: "ModelName"
fields: ["field1", "field2", "field3"]
-
+
- name: "ModelName"
fields: ["field1", "field2"]
@@ -72,12 +72,12 @@ acceptance_criteria:
- "[Functional requirement 1]"
- "[Functional requirement 2]"
- "[Functional requirement 3]"
-
+
non_functional:
- "[Performance requirement]"
- "[Accessibility requirement]"
- "[Security requirement]"
-
+
edge_cases:
- "[Edge case 1] → [Expected behavior]"
- "[Edge case 2] → [Expected behavior]"
@@ -87,17 +87,17 @@ testing_guidance:
user_testing:
- "[User testing instruction 1]"
- "[User testing instruction 2]"
-
+
qa_testing:
- "[QA testing instruction 1]"
- "[QA testing instruction 2]"
- "[QA testing instruction 3]"
estimated_complexity:
- size: "medium" # small | medium | large
- effort: "2-3 weeks" # Time estimate
- risk: "low" # low | medium | high
- dependencies: [] # List of DD-XXX IDs needed first
+ size: "medium" # small | medium | large
+ effort: "2-3 weeks" # Time estimate
+ risk: "low" # low | medium | high
+ dependencies: [] # List of DD-XXX IDs needed first
notes: |
[Any special considerations, important context, or
diff --git a/src/modules/wds/templates/platform-requirements.template.yaml b/src/modules/wds/templates/platform-requirements.template.yaml
index a204dd0d..0f138ba1 100644
--- a/src/modules/wds/templates/platform-requirements.template.yaml
+++ b/src/modules/wds/templates/platform-requirements.template.yaml
@@ -3,44 +3,44 @@
project:
name: "Project Name"
- type: "mobile_app" # mobile_app | web_app | desktop_app | api
+ type: "mobile_app" # mobile_app | web_app | desktop_app | api
wds_version: "6.0"
created_at: "YYYY-MM-DDTHH:MM:SSZ"
platform:
frontend:
- framework: "framework-name" # react_native | react | vue | angular | svelte
+ framework: "framework-name" # react_native | react | vue | angular | svelte
version: "X.X"
- state_management: "library" # zustand | redux | mobx | context
- navigation: "library" # react_navigation | react_router | vue_router
- styling: "approach" # tailwind | styled_components | css_modules
- ui_library: "library" # shadcn | mui | chakra (optional)
-
+ state_management: "library" # zustand | redux | mobx | context
+ navigation: "library" # react_navigation | react_router | vue_router
+ styling: "approach" # tailwind | styled_components | css_modules
+ ui_library: "library" # shadcn | mui | chakra (optional)
+
backend:
- framework: "framework-name" # supabase | firebase | express | fastapi | django
+ framework: "framework-name" # supabase | firebase | express | fastapi | django
version: "X.X"
- auth: "auth-provider" # supabase_auth | firebase_auth | auth0 | custom
- database: "database-type" # postgresql | mysql | mongodb | firestore
- storage: "storage-provider" # supabase_storage | s3 | cloudinary
- api: "api-type" # rest | graphql | grpc
-
+ auth: "auth-provider" # supabase_auth | firebase_auth | auth0 | custom
+ database: "database-type" # postgresql | mysql | mongodb | firestore
+ storage: "storage-provider" # supabase_storage | s3 | cloudinary
+ api: "api-type" # rest | graphql | grpc
+
database:
- type: "database-type" # postgresql | mysql | mongodb
+ type: "database-type" # postgresql | mysql | mongodb
version: "XX"
- orm: "orm-library" # prisma | typeorm | mongoose (optional)
-
+ orm: "orm-library" # prisma | typeorm | mongoose (optional)
+
deployment:
- frontend: "platform" # expo_eas | vercel | netlify | aws
- backend: "platform" # supabase_cloud | firebase | heroku | aws
- ci_cd: "platform" # github_actions | gitlab_ci | circle_ci
- hosting: "platform" # vercel | netlify | aws (if web app)
+ frontend: "platform" # expo_eas | vercel | netlify | aws
+ backend: "platform" # supabase_cloud | firebase | heroku | aws
+ ci_cd: "platform" # github_actions | gitlab_ci | circle_ci
+ hosting: "platform" # vercel | netlify | aws (if web app)
integrations:
- name: "integration-name"
provider: "provider-name"
- required: true # true | false
+ required: true # true | false
purpose: "[Why this integration is needed]"
-
+
- name: "integration-name"
provider: "provider-name"
required: false
diff --git a/src/modules/wds/templates/test-scenario.template.yaml b/src/modules/wds/templates/test-scenario.template.yaml
index ac658a6a..28bb7213 100644
--- a/src/modules/wds/templates/test-scenario.template.yaml
+++ b/src/modules/wds/templates/test-scenario.template.yaml
@@ -2,12 +2,12 @@
# Save to: test-scenarios/TS-XXX-name.yaml
test_scenario:
- id: "TS-XXX" # Format: TS-001, TS-002, etc.
- name: "Feature Testing" # Human-readable name
- delivery_id: "DD-XXX" # Related Design Delivery
- type: "user_acceptance" # user_acceptance | integration | e2e
- status: "ready" # ready | in_progress | blocked
- tester: "designer" # designer | qa | developer
+ id: "TS-XXX" # Format: TS-001, TS-002, etc.
+ name: "Feature Testing" # Human-readable name
+ delivery_id: "DD-XXX" # Related Design Delivery
+ type: "user_acceptance" # user_acceptance | integration | e2e
+ status: "ready" # ready | in_progress | blocked
+ tester: "designer" # designer | qa | developer
created_at: "YYYY-MM-DDTHH:MM:SSZ"
test_objectives:
@@ -21,7 +21,7 @@ test_environment:
devices:
- "Device 1 (OS version)"
- "Device 2 (OS version)"
-
+
test_data:
- field: "value"
- field: "value"
@@ -30,17 +30,17 @@ test_environment:
happy_path:
- id: "HP-001"
name: "Main User Flow"
- priority: "critical" # critical | high | medium | low
-
+ priority: "critical" # critical | high | medium | low
+
steps:
- action: "[User action]"
expected: "[Expected result]"
design_ref: "[Path to specification]#[section]"
-
+
- action: "[User action]"
expected: "[Expected result]"
design_ref: "[Path to specification]#[section]"
-
+
success_criteria:
- "[Success criterion 1]"
- "[Success criterion 2]"
@@ -51,13 +51,13 @@ error_states:
- id: "ES-001"
name: "Error Scenario"
priority: "high"
-
+
steps:
- action: "[Action that triggers error]"
- expected: "[Expected error message]"
- expected: "[Expected recovery option]"
- design_ref: "[Path to specification]#[error-section]"
-
+
success_criteria:
- "[Error handling criterion 1]"
- "[Error handling criterion 2]"
@@ -67,12 +67,12 @@ edge_cases:
- id: "EC-001"
name: "Edge Case Scenario"
priority: "medium"
-
+
steps:
- action: "[Unusual action]"
- expected: "[Expected handling]"
- design_ref: "[Path to specification]#[edge-case-section]"
-
+
success_criteria:
- "[Edge case criterion 1]"
@@ -94,15 +94,15 @@ accessibility:
- id: "A11Y-001"
name: "Screen Reader Navigation"
priority: "high"
-
+
setup: "Enable screen reader (VoiceOver/TalkBack)"
-
+
steps:
- action: "[Navigate with screen reader]"
- verify:
- "[Accessibility check 1]"
- "[Accessibility check 2]"
-
+
success_criteria:
- "[Accessibility criterion 1]"
- "[Accessibility criterion 2]"
@@ -112,10 +112,10 @@ usability:
- id: "UX-001"
name: "First Impression"
type: "observational"
-
+
instructions: |
[Instructions for conducting usability test]
-
+
success_criteria:
- "[Usability criterion 1]"
- "[Usability criterion 2]"
@@ -124,11 +124,11 @@ usability:
performance:
- id: "PERF-001"
name: "Performance Check"
-
+
verify:
- "[Performance metric 1]"
- "[Performance metric 2]"
-
+
success_criteria:
- "[Performance target 1]"
- "[Performance target 2]"
@@ -143,14 +143,14 @@ report_template:
- "Device tested"
- "Build version"
- "Overall result (Pass/Fail/Partial)"
-
+
- name: "Happy Path Results"
fields:
- "Test ID"
- "Result (Pass/Fail)"
- "Notes"
- "Screenshots"
-
+
- name: "Issues Found"
fields:
- "Issue ID"
@@ -160,13 +160,13 @@ report_template:
- "Expected vs Actual"
- "Screenshot/Video"
- "Design reference violated"
-
+
- name: "Design System Compliance"
fields:
- "Component"
- "Compliant (Yes/No)"
- "Deviations noted"
-
+
- name: "Recommendations"
fields:
- "What worked well"
@@ -181,12 +181,12 @@ sign_off:
- "Design system compliance > 95%"
- "Accessibility tests pass"
- "Usability metrics meet targets"
-
+
designer_approval:
statement: |
I confirm that the implemented feature matches the design
specifications and meets the quality standards defined in
this test scenario.
-
+
signature: "________________"
date: "________________"
diff --git a/src/modules/wds/tutorial/00-TUTORIAL-GUIDE.md b/src/modules/wds/tutorial/00-TUTORIAL-GUIDE.md
index e12ca910..85880014 100644
--- a/src/modules/wds/tutorial/00-TUTORIAL-GUIDE.md
+++ b/src/modules/wds/tutorial/00-TUTORIAL-GUIDE.md
@@ -9,11 +9,13 @@
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
@@ -27,6 +29,7 @@ Each chapter contains:
### Foundation
#### [Chapter 0: Why This Matters](chapter-00-why-this-matters/)
+
Learn how to be indispensable in the AI era
---
@@ -34,6 +37,7 @@ 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
---
@@ -41,12 +45,15 @@ 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
---
@@ -54,9 +61,11 @@ 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
---
@@ -64,21 +73,27 @@ 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
---
@@ -86,9 +101,11 @@ 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
---
@@ -96,6 +113,7 @@ Reusable patterns across scenarios
### Phase 6: Development Integration
#### [Chapter 6.1: UI Roadmap](chapter-6.1-ui-roadmap/)
+
Development priorities and handoff
---
@@ -103,7 +121,9 @@ 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)
@@ -111,7 +131,9 @@ 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
@@ -122,7 +144,9 @@ 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
@@ -134,6 +158,7 @@ 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
@@ -148,16 +173,19 @@ Each chapter has a matching script in `/notebooklm-scripts/`:
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
diff --git a/src/modules/wds/tutorial/01-designer-role-in-ai-era.md b/src/modules/wds/tutorial/01-designer-role-in-ai-era.md
index 42c1760f..cc9c23e8 100644
--- a/src/modules/wds/tutorial/01-designer-role-in-ai-era.md
+++ b/src/modules/wds/tutorial/01-designer-role-in-ai-era.md
@@ -9,11 +9,13 @@
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.
@@ -22,11 +24,13 @@ 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)
@@ -37,11 +41,13 @@ GOALS:
---
### 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
@@ -51,11 +57,13 @@ 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
@@ -71,11 +79,13 @@ CONTEXTS:
---
### 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
@@ -111,6 +121,7 @@ Technical Specs
## Why This Is Designer Work
### Engineers Think:
+
- "How do I build this?"
- "What's the data structure?"
- "What API endpoints do I need?"
@@ -118,6 +129,7 @@ Technical Specs
**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?"
@@ -125,6 +137,7 @@ Technical Specs
**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?"
@@ -143,22 +156,26 @@ Technical Specs
✅ Maintains coherent storyline across all touchpoints
✅ Balances business needs with user needs
✅ Makes complexity simple for end users
-✅ Makes simplicity implementable for developers
+✅ 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:
@@ -204,6 +221,7 @@ 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
@@ -213,11 +231,13 @@ Working Product
## 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?"
@@ -239,6 +259,7 @@ 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)
@@ -246,6 +267,7 @@ Every touchpoint tells the same story:
- **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
@@ -281,11 +303,13 @@ Layer 7: How do we make it implementable?
**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
@@ -300,6 +324,7 @@ Layer 7: How do we make it implementable?
**You're not just designing interfaces.**
**You're architecting:**
+
- Business value delivery
- User behavior change
- Product strategy
diff --git a/src/modules/wds/tutorial/02-wds-concept.md b/src/modules/wds/tutorial/02-wds-concept.md
index d54a8393..fb819b17 100644
--- a/src/modules/wds/tutorial/02-wds-concept.md
+++ b/src/modules/wds/tutorial/02-wds-concept.md
@@ -18,6 +18,7 @@ In the last video, we talked about why designers are irreplaceable in the AI era
### 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
@@ -37,6 +38,7 @@ With AI development, there's a new problem:
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
@@ -49,11 +51,13 @@ But if you're unclear, AI starts hallucinating and leaves your project in a deat
**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
```
@@ -65,6 +69,7 @@ Trigger Map → Scenario Init → Sketch → Why-Based Specs → AI Implementati
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)
@@ -73,11 +78,13 @@ And that requires:
### 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
@@ -89,6 +96,7 @@ And that requires:
### 1. Socratic Questioning
**Traditional AI:**
+
```
You: "Create a calendar"
AI: *Generates generic calendar*
@@ -96,11 +104,12 @@ 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.
+Agent: "Got it! So we match their mental model.
Should I avoid adding daily/monthly views?"
You: "Exactly!"
```
@@ -112,19 +121,22 @@ You: "Exactly!"
### 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
+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"
@@ -146,12 +158,14 @@ Notifications would break the "fun, not punishing" tone.
### 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
@@ -163,7 +177,8 @@ Features/walk-booking-logic.feature.md (200 lines)
├─ WHAT: Business rules, validation, API
```
-**The difference:**
+**The difference:**
+
- Clear separation of concerns
- Easy to maintain and update
- Clean handoffs to specialists
@@ -176,6 +191,7 @@ Features/walk-booking-logic.feature.md (200 lines)
### The Complete Flow
**Phase 1: Trigger Map**
+
```
WHO: Parents (need accountability)
TRIGGER: Family conflict over dog care
@@ -184,6 +200,7 @@ FEATURE: Family dog walk calendar
```
**Phase 2: Scenario Init**
+
```
Entry Point: Google search (frustrated)
Mental State: Tired of nagging, want simple solution
@@ -192,6 +209,7 @@ 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.
@@ -199,6 +217,7 @@ Agent: "I see: Week view, leaderboard, countdown timers.
```
**Phase 4: Why-Based Specifications**
+
```
Agent: "Why week view instead of daily?"
You: "Swedish families think in weeks..."
@@ -208,6 +227,7 @@ Agent: "Perfect! Documenting:
```
**Phase 5: AI Implementation**
+
```
AI: *Implements exactly as specified*
*Skips "helpful" features that would break intent*
@@ -247,6 +267,7 @@ AI: *Implements exactly as specified*
5. **Designer-AI Partnership** - Amplification, not replacement
**The result:**
+
- AI implements correctly first time
- Design intent is preserved
- Specifications become design knowledge
@@ -259,6 +280,7 @@ AI: *Implements exactly as specified*
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
diff --git a/src/modules/wds/tutorial/README-DEPRECATED.md b/src/modules/wds/tutorial/README-DEPRECATED.md
index ace16c86..77cbe851 100644
--- a/src/modules/wds/tutorial/README-DEPRECATED.md
+++ b/src/modules/wds/tutorial/README-DEPRECATED.md
@@ -34,17 +34,20 @@ course/
## Why the Change?
**Benefits:**
+
- ✅ Single learning path - everything in one place
- ✅ Module-specific tutorials - tutorial right where you need it
- ✅ Cleaner structure - no separate tutorial folder
- ✅ Better organization - theory + practice together
**Old approach:**
+
- Separate tutorial folder
- Disconnected from course content
- Harder to navigate
**New approach:**
+
- Tutorials integrated into modules
- Theory → Tutorial → Practice flow
- Easier to follow
diff --git a/src/modules/wds/tutorial/chapter-00-why-this-matters/01-inspiration.md b/src/modules/wds/tutorial/chapter-00-why-this-matters/01-inspiration.md
index 42d3168f..8525788b 100644
--- a/src/modules/wds/tutorial/chapter-00-why-this-matters/01-inspiration.md
+++ b/src/modules/wds/tutorial/chapter-00-why-this-matters/01-inspiration.md
@@ -1,4 +1,5 @@
# Chapter 0: Why WDS Matters
+
## Part 1: Inspiration
**Learn how to be indispensable in the AI era**
@@ -14,6 +15,7 @@ This isn't about working faster or making shinier designs. It's about becoming w
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
@@ -30,6 +32,7 @@ By the end of this tutorial, you'll have a completely different relationship wit
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
@@ -49,6 +52,7 @@ Traditional design work follows this exact pattern. You get a brief (instruction
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)
@@ -64,6 +68,7 @@ Let's be honest about what's happening. AI can now generate mockups in seconds.
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)
@@ -87,6 +92,7 @@ Linchpin designers do what AI fundamentally cannot do: they give products a soul
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
@@ -107,6 +113,7 @@ WDS teaches you to be this person systematically. Not through vague advice about
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
@@ -125,6 +132,7 @@ AI can generate variations endlessly and make things look polished on the surfac
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
@@ -147,6 +155,7 @@ Here's the paradigm shift: **The design becomes the specification. The specifica
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
@@ -166,7 +175,7 @@ This is what makes you indispensable as a designer. AI can help you think throug
**The 5 dimensions of design thinking:**
1. **Business Existence (WHY)** - Understanding purpose and value creation
-2. **Business Goals (SUCCESS)** - Connecting to metrics and impact
+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
@@ -188,6 +197,7 @@ This tutorial moves you to the other side. You'll become confident in your indis
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
@@ -207,19 +217,21 @@ Compare the outcomes. The traditional approach - creating mockups, handing off t
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.*
+_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)
@@ -232,6 +244,7 @@ That's a 5x speed increase with better quality. But more importantly, the key de
**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
diff --git a/src/modules/wds/tutorial/chapter-00-why-this-matters/04-practicalities.md b/src/modules/wds/tutorial/chapter-00-why-this-matters/04-practicalities.md
index 98800f7f..924a0ca6 100644
--- a/src/modules/wds/tutorial/chapter-00-why-this-matters/04-practicalities.md
+++ b/src/modules/wds/tutorial/chapter-00-why-this-matters/04-practicalities.md
@@ -1,4 +1,5 @@
# Chapter 0: Why WDS Matters
+
## Part 4: Practicalities
**Everything you need to know before starting**
@@ -10,12 +11,14 @@
### 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
@@ -30,17 +33,20 @@
### 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
@@ -52,22 +58,27 @@
### 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
@@ -80,21 +91,25 @@
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
@@ -108,6 +123,7 @@ By the end of this tutorial, you'll have created:
### 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
@@ -115,6 +131,7 @@ By the end of this tutorial, you'll have created:
- **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
@@ -122,6 +139,7 @@ By the end of this tutorial, you'll have created:
- **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
@@ -135,7 +153,7 @@ By the end of this tutorial, you'll have created:
### 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."
@@ -150,7 +168,7 @@ By the end of this tutorial, you'll have created:
>
> **— James T., Design Director**
-*Note: More testimonials will be added as designers complete the tutorial.*
+_Note: More testimonials will be added as designers complete the tutorial._
---
@@ -189,16 +207,19 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi
### 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
@@ -208,6 +229,7 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi
## Ready to Start?
You have everything you need:
+
- ✅ The skills (design thinking)
- ✅ The tools (paper + AI)
- ✅ The time (10 hours)
@@ -226,6 +248,7 @@ Or return to the main guide to review the full structure:
## Your Transformation Starts Now
Remember:
+
- **The design becomes the specification**
- **The specification becomes the product**
- **The code is just the printout**
diff --git a/src/modules/wds/workflows/00-system/language-configuration-guide.md b/src/modules/wds/workflows/00-system/language-configuration-guide.md
index 31419348..2194019b 100644
--- a/src/modules/wds/workflows/00-system/language-configuration-guide.md
+++ b/src/modules/wds/workflows/00-system/language-configuration-guide.md
@@ -22,6 +22,7 @@ These are configured during workflow initialization and stored in `wds-workflow-
During WDS project setup, you'll be asked:
**Question 1: Specification Language**
+
```
What language should WDS write the design specifications in?
@@ -33,6 +34,7 @@ What language should WDS write the design specifications in?
```
**Question 2: Product Languages**
+
```
What languages will the final product support?
@@ -49,7 +51,7 @@ Settings are stored in `docs/wds-workflow-status.yaml`:
```yaml
config:
- specification_language: "EN"
+ specification_language: 'EN'
product_languages:
- EN
- SE
@@ -63,6 +65,7 @@ config:
### Specification Language
**Used for:**
+
- Instructions and guidance text in specs
- Section descriptions
- Comments and annotations
@@ -70,19 +73,23 @@ config:
- Design system documentation
**Example:**
+
```markdown
# 1.1 Start Page
## Page Purpose
-Convert visitors into users by addressing... ← Written in spec language
+
+Convert visitors into users by addressing... ← Written in spec language
## User Situation
-Family members experiencing daily stress... ← Written in spec language
+
+Family members experiencing daily stress... ← Written in spec language
```
### Product Languages
**Used for:**
+
- All user-facing text content
- Button labels
- Form labels
@@ -91,11 +98,14 @@ Family members experiencing daily stress... ← Written in spec language
- Any text the END USER sees
**Example:**
+
```markdown
#### Primary CTA Button
+
**OBJECT ID**: `start-hero-cta`
+
- **Component**: Button Primary
-- **Content**: ← Product languages
+- **Content**: ← Product languages
- EN: "Get Started"
- SE: "Kom Igång"
- NO: "Kom i Gang"
@@ -109,13 +119,14 @@ Family members experiencing daily stress... ← Written in spec language
```yaml
config:
- specification_language: "EN" # Specs written in English
+ specification_language: 'EN' # Specs written in English
product_languages:
- - EN # Product supports English
- - SE # and Swedish
+ - EN # Product supports English
+ - SE # and Swedish
```
**Result:**
+
- Design specs written in English
- All text objects have EN and SE translations
@@ -123,29 +134,29 @@ config:
```yaml
config:
- specification_language: "EN" # Specs in English
+ specification_language: 'EN' # Specs in English
product_languages:
- EN
- SE
- NO
- DK
- - FI # 5 Nordic languages
+ - FI # 5 Nordic languages
```
### Internal Swedish Tool
```yaml
config:
- specification_language: "SE" # Specs in Swedish
+ specification_language: 'SE' # Specs in Swedish
product_languages:
- - SE # Only Swedish product
+ - SE # Only Swedish product
```
### Global Product
```yaml
config:
- specification_language: "EN"
+ specification_language: 'EN'
product_languages:
- EN
- SE
@@ -167,9 +178,11 @@ config:
# Product Brief
## Vision
+
Create a platform that... ← Spec language
## Target Users
+
Swedish families with... ← Spec language
```
@@ -186,13 +199,16 @@ Personas and triggers documented in spec language.
```markdown
## Hero Object
-**Purpose**: Primary value proposition ← Spec language
+
+**Purpose**: Primary value proposition ← Spec language
#### Primary Headline
+
**OBJECT ID**: `start-hero-headline`
+
- **Component**: H1 heading
-- **Position**: Center of hero ← Spec language
-- **Content**: ← Product languages
+- **Position**: Center of hero ← Spec language
+- **Content**: ← Product languages
- EN: "Every walk. on time."
- SE: "Varje promenad. i tid."
```
@@ -205,10 +221,12 @@ Personas and triggers documented in spec language.
```markdown
## Button Component
-### Usage ← Spec language
+### Usage ← Spec language
+
Use this button for primary actions...
-### Examples ← Product languages
+### Examples ← Product languages
+
- EN: "Submit", "Save", "Continue"
- SE: "Skicka", "Spara", "Fortsätt"
```
@@ -227,22 +245,26 @@ Every text object follows this pattern:
```markdown
#### {{Purpose_Name}}
+
**OBJECT ID**: `{{id}}`
+
- **Component**: {{type}}
-- **Position**: {{description}} ← Spec language
-- **Style**: {{specifications}} ← Spec language
-- **Behavior**: {{description}} ← Spec language
-- **Content**: ← Product languages
+- **Position**: {{description}} ← Spec language
+- **Style**: {{specifications}} ← Spec language
+- **Behavior**: {{description}} ← Spec language
+- **Content**: ← Product languages
{{#each product_languages}}
- {{this}}: "{{content}}"
- {{/each}}
+ {{/each}}
```
**Real Example:**
```markdown
#### Email Label
+
**OBJECT ID**: `signin-form-email-label`
+
- **Component**: Label text
- **Position**: Above email input field
- **For**: signin-form-email-input
@@ -304,6 +326,7 @@ User provides all translations, agent validates and documents.
### ✅ Developer-Friendly
Config provides:
+
```yaml
product_languages:
- EN
@@ -318,6 +341,7 @@ Developers know exactly what languages to implement.
## Language Codes Reference
**Nordic:**
+
- EN = English
- SE = Swedish (Svenska)
- NO = Norwegian (Norsk)
@@ -325,6 +349,7 @@ Developers know exactly what languages to implement.
- FI = Finnish (Suomi)
**Western Europe:**
+
- DE = German (Deutsch)
- FR = French (Français)
- ES = Spanish (Español)
@@ -333,16 +358,19 @@ Developers know exactly what languages to implement.
- PT = Portuguese (Português)
**Eastern Europe:**
+
- PL = Polish (Polski)
- CZ = Czech (Čeština)
- RU = Russian (Русский)
**Asia:**
+
- JA = Japanese (日本語)
- ZH = Chinese (中文)
- KO = Korean (한국어)
**Other:**
+
- AR = Arabic (العربية)
- TR = Turkish (Türkçe)
@@ -362,7 +390,7 @@ Product Languages: EN, SE
```yaml
# docs/wds-workflow-status.yaml
config:
- specification_language: "EN"
+ specification_language: 'EN'
product_languages:
- EN
- SE
@@ -373,15 +401,17 @@ config:
```markdown
# 1.1 Start Page
-The start page serves as the primary entry point... ← Written in EN
+The start page serves as the primary entry point... ← Written in EN
#### Primary Headline
+
**OBJECT ID**: `start-hero-headline`
+
- **Component**: H1 heading
-- **Position**: Center of hero section ← Written in EN
+- **Position**: Center of hero section ← Written in EN
- **Content**:
- - EN: "Every walk. on time. Every time." ← Product language 1
- - SE: "Varje promenad. i tid. Varje gång." ← Product language 2
+ - EN: "Every walk. on time. Every time." ← Product language 1
+ - SE: "Varje promenad. i tid. Varje gång." ← Product language 2
```
### For Developers
@@ -394,8 +424,8 @@ const languages = ['EN', 'SE'];
const content = {
'start-hero-headline': {
en: 'Every walk. on time. Every time.',
- se: 'Varje promenad. i tid. Varje gång.'
- }
+ se: 'Varje promenad. i tid. Varje gång.',
+ },
};
```
@@ -410,6 +440,7 @@ If you need to add/change languages mid-project:
3. **Continue** with new language config
**Before:**
+
```yaml
product_languages:
- EN
@@ -417,25 +448,25 @@ product_languages:
```
**After:**
+
```yaml
product_languages:
- EN
- SE
- - NO # Added Norwegian
+ - NO # Added Norwegian
```
**Update existing specs:**
+
```markdown
#### Primary Headline
+
- **Content**:
- EN: "Every walk. on time."
- SE: "Varje promenad. i tid."
- - NO: "Hver tur. i tide." ← Add new language
+ - NO: "Hver tur. i tide." ← Add new language
```
---
**Language configuration ensures complete, translation-ready specifications from day one!** 🌍✨
-
-
-
diff --git a/src/modules/wds/workflows/00-system/language-flow-diagram.md b/src/modules/wds/workflows/00-system/language-flow-diagram.md
index affb55b1..9f1c4ce8 100644
--- a/src/modules/wds/workflows/00-system/language-flow-diagram.md
+++ b/src/modules/wds/workflows/00-system/language-flow-diagram.md
@@ -29,6 +29,7 @@ Product languages: EN, SE
```
**Agent stores:**
+
- `specification_language = "EN"`
- `product_languages = ["EN", "SE"]`
@@ -74,6 +75,7 @@ config:
```
**Agent now knows:**
+
- Write specs in English
- Request content in English AND Swedish for all text
@@ -124,11 +126,12 @@ Line height: 1.2
...
```
-*Spec written in English (specification_language)*
+_Spec written in English (specification_language)_
### Step 3: Content with Translations
**Agent reads config:**
+
```xml
Load product_languages from config → ["EN", "SE"]
```
@@ -147,6 +150,7 @@ SE:
```
**User provides:**
+
```
EN: Every walk. on time. Every time.
@@ -154,6 +158,7 @@ SE: Varje promenad. i tid. Varje gång.
```
**Agent validates:**
+
```
✅ EN content: 37 characters (fits 60 capacity)
✅ SE content: 36 characters (fits 60 capacity)
@@ -168,20 +173,23 @@ SE: Varje promenad. i tid. Varje gång.
```markdown
# 1.1 Start Page
-The start page serves as the primary entry point... ← English (spec language)
+The start page serves as the primary entry point... ← English (spec language)
## Page Sections
### Hero Object
-**Purpose**: Primary value proposition ← English (spec language)
+
+**Purpose**: Primary value proposition ← English (spec language)
#### Primary Headline
+
**OBJECT ID**: `start-hero-headline`
+
- **Component**: H1 heading (`.text-heading-1`)
-- **Position**: Center of hero section ← English (spec language)
-- **Style**: Bold, 42px, line-height 1.2 ← English (spec language)
-- **Behavior**: Updates with language toggle ← English (spec language)
-- **Content**: ← Product languages
+- **Position**: Center of hero section ← English (spec language)
+- **Style**: Bold, 42px, line-height 1.2 ← English (spec language)
+- **Behavior**: Updates with language toggle ← English (spec language)
+- **Content**: ← Product languages
- EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång."
```
@@ -194,39 +202,48 @@ The start page serves as the primary entry point... ← English (spec languag
```markdown
### Hero Object
-**Purpose**: Primary value proposition ← Spec language
+
+**Purpose**: Primary value proposition ← Spec language
#### Primary Headline
+
**OBJECT ID**: `start-hero-headline`
+
- **Component**: H1 heading
-- **Position**: Center of hero, top ← Spec language
+- **Position**: Center of hero, top ← Spec language
- **Content**:
- - EN: "Every walk. on time. Every time." ← Product languages
+ - EN: "Every walk. on time. Every time." ← Product languages
- SE: "Varje promenad. i tid. Varje gång."
#### Supporting Text
+
**OBJECT ID**: `start-hero-supporting`
+
- **Component**: Body text
-- **Position**: Below headline ← Spec language
+- **Position**: Below headline ← Spec language
- **Content**:
- - EN: "Never miss a walk again." ← Product languages
+ - EN: "Never miss a walk again." ← Product languages
- SE: "Missa aldrig en promenad."
#### Primary CTA
+
**OBJECT ID**: `start-hero-cta`
+
- **Component**: Button Primary
-- **Position**: Center, below text ← Spec language
+- **Position**: Center, below text ← Spec language
- **Content**:
- - EN: "Get Started" ← Product languages
+ - EN: "Get Started" ← Product languages
- SE: "Kom Igång"
```
**Reading in English:**
+
> Every walk. on time. Every time.
> Never miss a walk again.
> [Get Started]
**Reading in Swedish:**
+
> Varje promenad. i tid. Varje gång.
> Missa aldrig en promenad.
> [Kom Igång]
@@ -254,16 +271,16 @@ const supportedLanguages = ['en', 'se'];
const translations = {
'start-hero-headline': {
en: 'Every walk. on time. Every time.',
- se: 'Varje promenad. i tid. Varje gång.'
+ se: 'Varje promenad. i tid. Varje gång.',
},
'start-hero-supporting': {
en: 'Never miss a walk again.',
- se: 'Missa aldrig en promenad.'
+ se: 'Missa aldrig en promenad.',
},
'start-hero-cta': {
en: 'Get Started',
- se: 'Kom Igång'
- }
+ se: 'Kom Igång',
+ },
};
// Language toggle
@@ -342,11 +359,13 @@ function setLanguage(lang: 'en' | 'se') {
### ✅ Two Distinct Languages
**Specification Language:**
+
- Documentation language
- For designers, PMs, developers
- Describes structure, behavior, logic
**Product Languages:**
+
- User-facing content
- What end users see
- Can be multiple languages
@@ -354,6 +373,7 @@ function setLanguage(lang: 'en' | 'se') {
### ✅ Early Configuration
**Set during workflow init** - before any design work
+
- No mid-project surprises
- All stakeholders aligned
- Complete from day one
@@ -361,6 +381,7 @@ function setLanguage(lang: 'en' | 'se') {
### ✅ Automatic Propagation
**Config flows through all phases:**
+
- Phase 1: Brief in spec language
- Phase 2: Trigger Map in spec language
- Phase 4: Specs in spec language, content in ALL product languages
@@ -387,6 +408,7 @@ Each language complete and coherent!
## Example: Adding Norwegian Mid-Project
**Original config:**
+
```yaml
product_languages:
- EN
@@ -396,20 +418,23 @@ product_languages:
**User needs Norwegian:**
1. **Update config:**
+
```yaml
product_languages:
- EN
- SE
- - NO # Added
+ - NO # Added
```
2. **Add to existing specs:**
+
```markdown
#### Primary Headline
+
- **Content**:
- EN: "Every walk. on time."
- SE: "Varje promenad. i tid."
- - NO: "Hver tur. i tide." ← Add to all text objects
+ - NO: "Hver tur. i tide." ← Add to all text objects
```
3. **Future text objects automatically include NO**
@@ -419,6 +444,3 @@ Agents read updated config and request 3 languages going forward.
---
**Language configuration ensures complete, production-ready translations from the very beginning!** 🌍✨
-
-
-
diff --git a/src/modules/wds/workflows/00-system/wds-workflow-status-template.yaml b/src/modules/wds/workflows/00-system/wds-workflow-status-template.yaml
index 163ca0fa..4331c659 100644
--- a/src/modules/wds/workflows/00-system/wds-workflow-status-template.yaml
+++ b/src/modules/wds/workflows/00-system/wds-workflow-status-template.yaml
@@ -22,13 +22,13 @@ workflow_path: "{{workflow_path_file}}"
# Configuration
config:
- folder_prefix: "{{folder_prefix}}" # letters or numbers
- folder_case: "{{folder_case}}" # title or lowercase
- brief_level: "{{brief_level}}" # simplified or complete
- include_design_system: {{include_design_system}}
+ folder_prefix: "{{folder_prefix}}" # letters or numbers
+ folder_case: "{{folder_case}}" # title or lowercase
+ brief_level: "{{brief_level}}" # simplified or complete
+ include_design_system: { { include_design_system } }
component_library: "{{component_library}}"
- specification_language: "{{specification_language}}" # Language for writing specs (EN, SE, etc.)
- product_languages: {{product_languages}} # Array of languages product supports
+ specification_language: "{{specification_language}}" # Language for writing specs (EN, SE, etc.)
+ product_languages: { { product_languages } } # Array of languages product supports
# Folder mapping (generated based on config)
folders:
@@ -41,7 +41,6 @@ folders:
# Workflow status tracking
workflow_status: "{{workflow_items}}"
-
# Example structure when populated:
# workflow_status:
# phase_1_project_brief:
diff --git a/src/modules/wds/workflows/1-project-brief/complete/instructions.md b/src/modules/wds/workflows/1-project-brief/complete/instructions.md
index 6ceb9ddb..bf6ffe3e 100644
--- a/src/modules/wds/workflows/1-project-brief/complete/instructions.md
+++ b/src/modules/wds/workflows/1-project-brief/complete/instructions.md
@@ -9,6 +9,7 @@
If this project succeeds beyond your wildest dreams, what does that look like? Don't worry about being realistic yet - dream big.
Listen for:
+
- Aspirational outcomes
- Impact on users
- Market position
- Emotional drivers
-
+
Reflect back and help crystallize into a clear vision statement
@@ -50,15 +52,16 @@ If this project succeeds beyond your wildest dreams, what does that look like? D
Complete this statement:
-*For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator].*
+_For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator]._
If user struggles, break it down:
+
1. Who's the target customer?
2. What's their need or opportunity?
3. What category does this fit?
4. What's the key benefit?
5. What makes it different from alternatives?
-
+
Help craft a clear positioning statement
@@ -144,18 +147,20 @@ Others who interact with the product but aren't the primary user?
**What metrics or outcomes define success?**
Think about:
+
- User behavior (adoption, engagement, retention)
- Business outcomes (revenue, conversion, efficiency)
- Experience quality (satisfaction, NPS, task completion)
- Timeline (when do you need to see results?)Help make criteria SMART:
+
- Specific
- Measurable
- Achievable
- Relevant
- Time-bound
-
+
success_criteria
@@ -166,16 +171,18 @@ Think about:
**What alternatives do your users have today?**
This could be:
+
- Direct competitors
- Different approaches to the same problem
- Manual/analog solutions
- Doing nothingFor each alternative, explore:
+
- What do they do well?
- Where do they fall short?
- Why might users choose them over you?
-
+
**What's your unfair advantage?**
@@ -241,6 +248,7 @@ Company stage, team capabilities, market conditions, past attempts?
{{constraints}}
---
+
Does this capture your strategic foundation? Anything to refine?
@@ -255,6 +263,7 @@ Company stage, team capabilities, market conditions, past attempts?
Location: `A-Product-Brief/project-brief.md`
This strategic foundation will guide all design decisions. You're ready for:
+
- **Phase 2: Trigger Mapping** - Deep dive into user psychology
- **Phase 3: PRD Platform** - Technical foundation
@@ -262,4 +271,3 @@ Your vision is clear. Let's build something great! 🚀
-
diff --git a/src/modules/wds/workflows/1-project-brief/complete/project-brief.template.md b/src/modules/wds/workflows/1-project-brief/complete/project-brief.template.md
index 11182fe3..407fe70a 100644
--- a/src/modules/wds/workflows/1-project-brief/complete/project-brief.template.md
+++ b/src/modules/wds/workflows/1-project-brief/complete/project-brief.template.md
@@ -19,6 +19,7 @@
{{positioning_statement}}
**Breakdown:**
+
- **Target Customer:** {{target_customer}}
- **Need/Opportunity:** {{need_opportunity}}
- **Category:** {{category}}
@@ -31,8 +32,7 @@
**Type:** {{business_model}}
-{{#if business_model_b2b}}
----
+## {{#if business_model_b2b}}
## Business Customer Profile (B2B)
@@ -40,11 +40,12 @@
### Buying Roles
-| Role | Description |
-|------|-------------|
-| **Buyer** | {{buyer_role}} |
+| Role | Description |
+| ------------ | ----------------- |
+| **Buyer** | {{buyer_role}} |
| **Champion** | {{champion_role}} |
-| **User** | {{user_role}} |
+| **User** | {{user_role}} |
+
{{/if}}
---
@@ -99,5 +100,4 @@ This complete brief provides strategic foundation for all design work:
---
-*Generated by Whiteport Design Studio*
-
+_Generated by Whiteport Design Studio_
diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-01-init.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-01-init.md
index bf18df11..9b69de4d 100644
--- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-01-init.md
+++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-01-init.md
@@ -1,13 +1,17 @@
# Step 1: Welcome and Set Expectations
## Purpose
+
Welcome user and set expectations for the Project Brief workflow.
## Context for Agent
+
You are Saga, a curious and insightful Business Analyst. Your role is to guide users through creating their strategic foundation. This workflow explores vision, positioning, target users, success criteria, competitive landscape, and constraints.
## Key Elements to Cover
+
This workflow establishes the strategic foundation by exploring:
+
- Vision & positioning (core strategic direction)
- Target users (ICP) - who we're designing for
- Success criteria (how we'll measure success)
@@ -15,13 +19,17 @@ This workflow establishes the strategic foundation by exploring:
- Constraints & context (real-world limitations)
## Instructions
+
Welcome the user and explain that this is their strategic foundation. Set time expectations (30-60 minutes) and ask about any existing context that should be considered.
## Next Step
+
When user confirms readiness, proceed to step-02-vision.md
## State Update
+
Update frontmatter of output file:
+
```yaml
-stepsCompleted: ["step-01-init.md"]
+stepsCompleted: ['step-01-init.md']
```
diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-02-vision.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-02-vision.md
index 00eea8d2..cc4ee691 100644
--- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-02-vision.md
+++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-02-vision.md
@@ -1,12 +1,15 @@
# Step 2: Capture Vision
## Purpose
+
Help user articulate their vision for the product.
## Context for Agent
+
You are exploring the big picture with the user. Your goal is to help them crystallize their aspirational vision into a clear statement that will guide all decisions.
## Key Elements
+
This step captures the high-level, aspirational direction that will guide all decisions.
## Instructions
@@ -27,11 +30,14 @@ This step captures the high-level, aspirational direction that will guide all de
- Use collaborative language: "What I'm hearing is..." or "It sounds like..."
## Next Step
+
After capturing vision, proceed to step-03-positioning.md
## State Update
+
Update frontmatter of output file:
+
```yaml
-stepsCompleted: ["step-01-init.md", "step-02-vision.md"]
-vision: "[captured vision statement]"
+stepsCompleted: ['step-01-init.md', 'step-02-vision.md']
+vision: '[captured vision statement]'
```
diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-03-positioning.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-03-positioning.md
index cce1a541..7af936b3 100644
--- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-03-positioning.md
+++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-03-positioning.md
@@ -1,26 +1,34 @@
# Step 3: Define Positioning
## Purpose
+
Help user define clear positioning statement for their product.
## Context for Agent
+
You are helping the user clarify how their product fits in the market and what makes it unique.
## Key Elements
+
This step establishes market positioning and differentiation.
## Key Framework
+
Positioning statement format: "For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator]."
## Instructions
+
Guide user through positioning framework. Ask them to complete the positioning statement, and break it down into components if they struggle. Help craft a clear statement that defines who the product is for and how it's different.
## Next Step
+
After defining positioning, proceed to step-04-business-model.md
## State Update
+
Update frontmatter of output file:
+
```yaml
-stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md"]
-positioning: "[captured positioning statement]"
+stepsCompleted: ['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md']
+positioning: '[captured positioning statement]'
```
diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-04-business-model.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-04-business-model.md
index f7b2ac3d..c3b38a9d 100644
--- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-04-business-model.md
+++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-04-business-model.md
@@ -1,20 +1,26 @@
# Step 4: Determine Business Model
## Goal
+
Help user identify whether their product is B2B, B2C, or both.
## Key Elements
+
Business model determines who buys/uses the product and affects all strategic decisions.
## Instructions
+
Ask user whether their product is B2B, B2C, or both. Present clear options and explain the implications of each choice.
## Next Step
+
After determining business model, proceed to step-05-business-customers.md if B2B or Both, or step-06-target-users.md if B2C
## State Update
+
Update frontmatter of output file:
+
```yaml
-stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md"]
-business_model: "[b2b/b2c/both]"
+stepsCompleted: ['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md', 'step-04-business-model.md']
+business_model: '[b2b/b2c/both]'
```
diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-05-business-customers.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-05-business-customers.md
index 7ce3738a..a8f7bade 100644
--- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-05-business-customers.md
+++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-05-business-customers.md
@@ -1,21 +1,28 @@
# Step 5: Identify Business Customers (B2B)
## Goal
+
Help user define their ideal business customer profile.
## Key Elements
+
Business customer profile determines who buys the product and influences purchasing decisions.
## Instructions
+
If business model is B2B or Both, guide user to define their ideal business customer. Ask about company size, industry, decision-making structure, and budget authority. Also identify buying roles (buyer vs. user).
## Next Step
+
After identifying business customers, proceed to step-06-target-users.md
## State Update
+
Update frontmatter of output file:
+
```yaml
-stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md"]
-business_customer_profile: "[captured business customer profile]"
-buying_roles: "[captured buying roles]"
+stepsCompleted:
+ ['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md', 'step-04-business-model.md', 'step-05-business-customers.md']
+business_customer_profile: '[captured business customer profile]'
+buying_roles: '[captured buying roles]'
```
diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-06-target-users.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-06-target-users.md
index 60773e52..4e09f3a5 100644
--- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-06-target-users.md
+++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-06-target-users.md
@@ -1,24 +1,39 @@
# Step 6: Identify Target Users
## Purpose
+
Help user define their ideal customer profile.
## Context for Agent
+
You are identifying who the product is for and what their needs are. This information will guide all design decisions.
## Key Elements
+
This step identifies who we're designing for and what their needs are.
## Instructions
+
Guide user to describe their ideal users in detail. Ask about their role, demographics, daily experience, frustrations, goals, and current solutions. Also identify any secondary users or stakeholders.
## Next Step
+
After identifying target users, proceed to step-07-success-criteria.md
## State Update
+
Update frontmatter of output file:
+
```yaml
-stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md"]
-ideal_user_profile: "[captured user profile]"
-secondary_users: "[captured secondary users]"
+stepsCompleted:
+ [
+ 'step-01-init.md',
+ 'step-02-vision.md',
+ 'step-03-positioning.md',
+ 'step-04-business-model.md',
+ 'step-05-business-customers.md',
+ 'step-06-target-users.md',
+ ]
+ideal_user_profile: '[captured user profile]'
+secondary_users: '[captured secondary users]'
```
diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-07-success-criteria.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-07-success-criteria.md
index dc7e12bb..d675811e 100644
--- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-07-success-criteria.md
+++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-07-success-criteria.md
@@ -1,23 +1,39 @@
# Step 7: Define Success Criteria
## Purpose
+
Help user define measurable success criteria for their project.
## Context for Agent
+
You are establishing how the project will know if it's successful. This will guide all future decisions.
## Key Elements
+
This step establishes measurable outcomes that indicate success.
## Instructions
+
Guide user to define metrics and outcomes that indicate success. Help them think about user behavior, business outcomes, experience quality, and timeline. Work with them to make criteria SMART (Specific, Measurable, Achievable, Relevant, Time-bound).
## Next Step
+
After defining success criteria, proceed to step-08-competitive-landscape.md
## State Update
+
Update frontmatter of output file:
+
```yaml
-stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md"]
-success_criteria: "[captured success criteria]"
+stepsCompleted:
+ [
+ 'step-01-init.md',
+ 'step-02-vision.md',
+ 'step-03-positioning.md',
+ 'step-04-business-model.md',
+ 'step-05-business-customers.md',
+ 'step-06-target-users.md',
+ 'step-07-success-criteria.md',
+ ]
+success_criteria: '[captured success criteria]'
```
diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-08-competitive-landscape.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-08-competitive-landscape.md
index 77a9d156..5e5be0a0 100644
--- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-08-competitive-landscape.md
+++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-08-competitive-landscape.md
@@ -1,24 +1,41 @@
# Step 8: Analyze Competitive Landscape
## Purpose
+
Help user understand alternatives and their unique advantage.
## Context for Agent
+
You are exploring what alternatives exist and what makes the product unique. This information will guide differentiation strategy.
## Key Elements
+
This step identifies competitive positioning and unique value proposition.
## Instructions
+
Guide user to understand alternatives including direct competitors, different approaches, manual solutions, or doing nothing. For each alternative, explore strengths, weaknesses, and why users might choose them. Help identify their unfair advantage.
## Next Step
+
After analyzing competitive landscape, proceed to step-09-constraints.md
## State Update
+
Update frontmatter of output file:
+
```yaml
-stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md"]
-competitive_landscape: "[captured competitive analysis]"
-unfair_advantage: "[captured unfair advantage]"
+stepsCompleted:
+ [
+ 'step-01-init.md',
+ 'step-02-vision.md',
+ 'step-03-positioning.md',
+ 'step-04-business-model.md',
+ 'step-05-business-customers.md',
+ 'step-06-target-users.md',
+ 'step-07-success-criteria.md',
+ 'step-08-competitive-landscape.md',
+ ]
+competitive_landscape: '[captured competitive analysis]'
+unfair_advantage: '[captured unfair advantage]'
```
diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-09-constraints.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-09-constraints.md
index 1a5af5e8..4385afc5 100644
--- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-09-constraints.md
+++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-09-constraints.md
@@ -1,24 +1,42 @@
# Step 9: Capture Constraints and Context
## Purpose
+
Help user identify constraints that should shape design decisions.
## Context for Agent
+
You are grounding the vision in reality by identifying limitations and context.
## Key Elements
+
This step identifies real-world limitations and additional context.
## Instructions
+
Guide user to identify constraints including timeline, budget, technical requirements, brand guidelines, regulatory needs, and integration requirements. Also ask for additional context like company stage, team capabilities, market conditions, or past attempts.
## Next Step
+
After capturing constraints, proceed to step-10-synthesize.md
## State Update
+
Update frontmatter of output file:
+
```yaml
-stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md", "step-09-constraints.md"]
-constraints: "[captured constraints]"
-additional_context: "[captured additional context]"
+stepsCompleted:
+ [
+ 'step-01-init.md',
+ 'step-02-vision.md',
+ 'step-03-positioning.md',
+ 'step-04-business-model.md',
+ 'step-05-business-customers.md',
+ 'step-06-target-users.md',
+ 'step-07-success-criteria.md',
+ 'step-08-competitive-landscape.md',
+ 'step-09-constraints.md',
+ ]
+constraints: '[captured constraints]'
+additional_context: '[captured additional context]'
```
diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-10-synthesize.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-10-synthesize.md
index 1abaee1b..043543bf 100644
--- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-10-synthesize.md
+++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-10-synthesize.md
@@ -1,23 +1,42 @@
# Step 10: Synthesize and Create Brief
## Purpose
+
Synthesize all captured information into a complete project brief document.
## Context for Agent
+
You are bringing together all the strategic elements into a comprehensive brief that will guide all design decisions.
## Key Elements
+
This step compiles all strategic foundation elements into a cohesive document.
## Instructions
+
Present all captured information (vision, positioning, business model, business customers, target users, success criteria, competitive landscape, unfair advantage, constraints, and additional context). Ask for confirmation and make any requested adjustments. Generate final document using the template.
## Next Step
+
Workflow complete. User can proceed to Phase 2: Trigger Mapping
## State Update
+
Update frontmatter of output file:
+
```yaml
-stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md", "step-09-constraints.md", "step-10-synthesize.md"]
-status: "complete"
+stepsCompleted:
+ [
+ 'step-01-init.md',
+ 'step-02-vision.md',
+ 'step-03-positioning.md',
+ 'step-04-business-model.md',
+ 'step-05-business-customers.md',
+ 'step-06-target-users.md',
+ 'step-07-success-criteria.md',
+ 'step-08-competitive-landscape.md',
+ 'step-09-constraints.md',
+ 'step-10-synthesize.md',
+ ]
+status: 'complete'
```
diff --git a/src/modules/wds/workflows/1-project-brief/simplified/instructions.md b/src/modules/wds/workflows/1-project-brief/simplified/instructions.md
index 8ce1842d..94c4086a 100644
--- a/src/modules/wds/workflows/1-project-brief/simplified/instructions.md
+++ b/src/modules/wds/workflows/1-project-brief/simplified/instructions.md
@@ -9,6 +9,7 @@
Describe the project in a few sentences. What will users see and interact with?
Listen for:
+
- Type of project (app, website, feature, page)
- Target platform (web, mobile, both)
- Key functionality or purpose
-
+
If unclear, ask one clarifying question
@@ -38,11 +40,12 @@ Describe the project in a few sentences. What will users see and interact with?<
Why does this project exist? What problem are you solving, or what opportunity are you pursuing?
Listen for:
+
- Pain points being addressed
- Market opportunity
- User needs not being met
- Business drivers
-
+
Reflect back what you heard to confirm understanding
@@ -55,10 +58,11 @@ Why does this project exist? What problem are you solving, or what opportunity a
When this design is complete, what will make it successful? What experience do you want users to have?
Listen for:
+
- Functional goals (what it should do)
- Experience goals (how it should feel)
- Business goals (what outcomes matter)
-
+
Help refine vague goals into specific, actionable ones
@@ -71,12 +75,13 @@ When this design is complete, what will make it successful? What experience do y
Timeline, technology, brand guidelines, existing systems to integrate with?
Note:
+
- Technical constraints
- Timeline/deadline
- Budget considerations
- Brand/style requirements
- Integration requirements
-
+
It's okay if there are few constraints - note "flexible" where appropriate
@@ -111,6 +116,7 @@ Timeline, technology, brand guidelines, existing systems to integrate with?
-
diff --git a/src/modules/wds/workflows/1-project-brief/simplified/simplified-brief.template.md b/src/modules/wds/workflows/1-project-brief/simplified/simplified-brief.template.md
index 0fea3074..ea911cb8 100644
--- a/src/modules/wds/workflows/1-project-brief/simplified/simplified-brief.template.md
+++ b/src/modules/wds/workflows/1-project-brief/simplified/simplified-brief.template.md
@@ -41,5 +41,4 @@ This simplified brief provides essential context for design work. The following
---
-*Generated by Whiteport Design Studio*
-
+_Generated by Whiteport Design Studio_
diff --git a/src/modules/wds/workflows/1-project-brief/workflow.yaml b/src/modules/wds/workflows/1-project-brief/workflow.yaml
index 01c7d221..b638160d 100644
--- a/src/modules/wds/workflows/1-project-brief/workflow.yaml
+++ b/src/modules/wds/workflows/1-project-brief/workflow.yaml
@@ -3,7 +3,6 @@ name: Product Brief Workflow
description: Establish project context - foundation for all design work
web_bundle: true
---
-
# WDS Phase 1: Project Brief
name: project-brief
author: "Whiteport Design Studio"
@@ -42,4 +41,3 @@ primary_agent: "saga-analyst"
standalone: true
web_bundle: false
-
diff --git a/src/modules/wds/workflows/2-trigger-mapping/instructions.md b/src/modules/wds/workflows/2-trigger-mapping/instructions.md
index a6ebe91f..5a20b422 100644
--- a/src/modules/wds/workflows/2-trigger-mapping/instructions.md
+++ b/src/modules/wds/workflows/2-trigger-mapping/instructions.md
@@ -9,6 +9,7 @@
Would you like to:
+
1. **Full session** - All 5 workshops now
2. **Workshop by workshop** - Start with Business Goals, continue later
3. **Jump to specific workshop** - If you've done some already
@@ -86,6 +88,7 @@ Ready to begin? 🎯
{{summary_of_priorities}}
You now have strategic clarity on:
+
- What success looks like (business goals)
- Who to focus on (target groups)
- What drives them (positive & negative forces)
@@ -105,4 +109,3 @@ Ready for the next phase! 🚀
-
diff --git a/src/modules/wds/workflows/2-trigger-mapping/templates/feature-impact.template.md b/src/modules/wds/workflows/2-trigger-mapping/templates/feature-impact.template.md
index b8d9238c..9568b215 100644
--- a/src/modules/wds/workflows/2-trigger-mapping/templates/feature-impact.template.md
+++ b/src/modules/wds/workflows/2-trigger-mapping/templates/feature-impact.template.md
@@ -15,7 +15,8 @@
## Prioritized Features
| Rank | Feature | Score | Decision |
-|------|---------|-------|----------|
+| ---- | ------- | ----- | -------- |
+
{{#each sorted_features}}
| {{this.rank}} | {{this.name}} | {{this.score}} | {{this.decision}} |
{{/each}}
@@ -26,21 +27,24 @@
**Must Have MVP (Primary High OR Top Tier Score):**
{{#each must_have}}
+
- {{this.name}} ({{this.score}})
-{{/each}}
+ {{/each}}
**Consider for MVP:**
{{#each consider}}
+
- {{this.name}} ({{this.score}})
-{{/each}}
+ {{/each}}
**Defer (Nice-to-Have or Low Strategic Value):**
{{#each defer}}
+
- {{this.name}} ({{this.score}})
-{{/each}}
+ {{/each}}
---
-*Generated by Whiteport Design Studio*
-*Strategic input for Phase 4: UX Design and Phase 6: PRD/Development*
-*Beta methodology - feedback welcome*
+_Generated by Whiteport Design Studio_
+_Strategic input for Phase 4: UX Design and Phase 6: PRD/Development_
+_Beta methodology - feedback welcome_
diff --git a/src/modules/wds/workflows/2-trigger-mapping/templates/trigger-map.template.md b/src/modules/wds/workflows/2-trigger-mapping/templates/trigger-map.template.md
index 749a12d1..51624925 100644
--- a/src/modules/wds/workflows/2-trigger-mapping/templates/trigger-map.template.md
+++ b/src/modules/wds/workflows/2-trigger-mapping/templates/trigger-map.template.md
@@ -15,7 +15,7 @@ This is the visual overview. For detailed documentation, see:
- **01-Business-Goals.md** - Full vision statements and SMART objectives
- **02-Target-Groups.md** - All personas with complete driving forces
- **03-Feature-Impact-Analysis.md** - Prioritized features with impact scores
-- **04-08-*.md** - Individual persona detail files
+- **04-08-\*.md** - Individual persona detail files
---
@@ -28,31 +28,37 @@ This is the visual overview. For detailed documentation, see:
## Business Objectives
{{#each objectives}}
+
### Objective {{@index + 1}}: {{this.statement}}
+
- **Metric:** {{this.metric}}
- **Target:** {{this.target}}
- **Timeline:** {{this.timeline}}
-{{/each}}
+ {{/each}}
---
## Target Groups (Prioritized)
{{#each prioritized_groups}}
+
### {{@index + 1}}. {{this.name}}
+
**Priority Reasoning:** {{this.reasoning}}
> {{this.persona_summary}}
**Key Positive Drivers:**
{{#each this.positive_drivers}}
+
- {{this}}
-{{/each}}
+ {{/each}}
**Key Negative Drivers:**
{{#each this.negative_drivers}}
+
- {{this}}
-{{/each}}
+ {{/each}}
{{/each}}
@@ -94,26 +100,32 @@ This is the visual overview. For detailed documentation, see:
**Must Address:**
{{#each must_address_drivers}}
+
- {{this}}
-{{/each}}
+ {{/each}}
**Should Address:**
{{#each should_address_drivers}}
+
- {{this}}
-{{/each}}
+ {{/each}}
---
## Cross-Group Patterns
### Shared Drivers
+
{{shared_drivers}}
### Unique Drivers
+
{{unique_drivers}}
{{#if conflicts}}
+
### Potential Tensions
+
{{conflicts}}
{{/if}}
@@ -131,6 +143,5 @@ This Trigger Map Poster provides a quick reference. For detailed work:
---
-*Generated by Whiteport Design Studio*
-*Trigger Mapping methodology credits: Effect Mapping by Mijo Balic & Ingrid Domingues (inUse), adapted with negative driving forces by WDS*
-
+_Generated by Whiteport Design Studio_
+_Trigger Mapping methodology credits: Effect Mapping by Mijo Balic & Ingrid Domingues (inUse), adapted with negative driving forces by WDS_
diff --git a/src/modules/wds/workflows/2-trigger-mapping/workflow.yaml b/src/modules/wds/workflows/2-trigger-mapping/workflow.yaml
index d425f203..16af643d 100644
--- a/src/modules/wds/workflows/2-trigger-mapping/workflow.yaml
+++ b/src/modules/wds/workflows/2-trigger-mapping/workflow.yaml
@@ -55,4 +55,3 @@ primary_agent: "saga-analyst"
standalone: true
web_bundle: false
-
diff --git a/src/modules/wds/workflows/2-trigger-mapping/workshops/1-business-goals/instructions.md b/src/modules/wds/workflows/2-trigger-mapping/workshops/1-business-goals/instructions.md
index 49606bca..a574d11a 100644
--- a/src/modules/wds/workflows/2-trigger-mapping/workshops/1-business-goals/instructions.md
+++ b/src/modules/wds/workflows/2-trigger-mapping/workshops/1-business-goals/instructions.md
@@ -8,6 +8,7 @@
Think big. If everything goes perfectly, what position do you want to hold?
Examples:
+
- "Be the most trusted platform for dog owners in Sweden"
- "The go-to tool for indie designers"
- "Make project management actually enjoyable"
@@ -39,6 +41,7 @@ Examples:
**How would you measure progress toward this vision?**
Think about:
+
- User metrics (adoption, engagement, retention)
- Business metrics (revenue, growth, market share)
- Quality metrics (satisfaction, referrals, reviews)
@@ -46,12 +49,13 @@ Think about:
What numbers would make you confident you're on track?For each metric mentioned, help make it SMART:
+
- **S**pecific - What exactly?
- **M**easurable - What number?
- **A**chievable - Is this realistic?
- **R**elevant - Does this connect to the vision?
- **T**ime-bound - By when?
-
+
Aim for 3-5 clear objectives
@@ -62,6 +66,7 @@ What numbers would make you confident you're on track?
For each objective, walk through:
Example transformation:
+
- Vague: "Get influential users"
- SMART: "Onboard 10 verified dog trainers with 1000+ followers by Q4 2026"
@@ -71,10 +76,11 @@ Present each refined objective for confirmation.
{{#each objectives}}
**Objective {{@index + 1}}:** {{this.statement}}
+
- Metric: {{this.metric}}
- Target: {{this.target}}
- Timeline: {{this.timeline}}
-{{/each}}
+ {{/each}}
Do these capture what success looks like? Any adjustments?
@@ -98,4 +104,3 @@ This gives us clear targets to work toward. Next, we'll identify who can help yo
-
diff --git a/src/modules/wds/workflows/2-trigger-mapping/workshops/2-target-groups/instructions.md b/src/modules/wds/workflows/2-trigger-mapping/workshops/2-target-groups/instructions.md
index 330a2ad9..4d3ec3de 100644
--- a/src/modules/wds/workflows/2-trigger-mapping/workshops/2-target-groups/instructions.md
+++ b/src/modules/wds/workflows/2-trigger-mapping/workshops/2-target-groups/instructions.md
@@ -10,10 +10,11 @@
Now we identify the people who matter most to achieving your goals.
We'll create:
+
- A list of user groups
- Rich descriptions (personas)
- Understanding of their context
-
+
@@ -101,4 +104,3 @@ These are the people we're designing for. Next, we'll explore what drives them -
-
diff --git a/src/modules/wds/workflows/2-trigger-mapping/workshops/3-driving-forces/instructions.md b/src/modules/wds/workflows/2-trigger-mapping/workshops/3-driving-forces/instructions.md
index 387efa9e..d53edf8a 100644
--- a/src/modules/wds/workflows/2-trigger-mapping/workshops/3-driving-forces/instructions.md
+++ b/src/modules/wds/workflows/2-trigger-mapping/workshops/3-driving-forces/instructions.md
@@ -19,12 +19,14 @@ Understanding both is crucial. Research shows people work harder to avoid pain t
What does {{persona.name}} want to achieve or experience?
Think about:
+
- What would make their day better?
- What would they brag about to colleagues?
- What would make them feel successful?
@@ -52,6 +55,7 @@ Think about:
What does {{persona.name}} want to avoid or escape?
Think about:
+
- What keeps them up at night?
- What frustrations are they tired of?
- What risks worry them?
@@ -63,13 +67,15 @@ Think about:
✅ **Positive Drivers:**
{{#each positive_drivers}}
+
- {{this}}
-{{/each}}
+ {{/each}}
⚠️ **Negative Drivers:**
{{#each negative_drivers}}
+
- {{this}}
-{{/each}}
+ {{/each}}
Does this capture what truly motivates {{persona.name}}? Anything to add?
@@ -82,10 +88,11 @@ Think about:
Analyze for:
+
- Common drivers across groups
- Unique drivers per group
- Potential conflicts between groups
-
+
@@ -120,4 +128,3 @@ This is powerful insight. Next, we'll prioritize which groups and drivers to foc
-
diff --git a/src/modules/wds/workflows/2-trigger-mapping/workshops/4-prioritization/instructions.md b/src/modules/wds/workflows/2-trigger-mapping/workshops/4-prioritization/instructions.md
index 7f38cd78..bd1d5094 100644
--- a/src/modules/wds/workflows/2-trigger-mapping/workshops/4-prioritization/instructions.md
+++ b/src/modules/wds/workflows/2-trigger-mapping/workshops/4-prioritization/instructions.md
@@ -8,6 +8,7 @@
+ {{/each}}
**Which business goal is most critical right now?**
@@ -44,7 +46,7 @@ Help me understand your reasoning. What makes this the priority?prioritized_visions
@@ -56,8 +58,9 @@ Help me understand your reasoning. What makes this the priority?
For "{{top_vision}}", you have these objectives:
{{#each top_vision_objectives}}
+
- {{this.statement}}
-{{/each}}
+ {{/each}}
**Which objective is most important to achieve first?**
@@ -74,7 +77,7 @@ What's your reasoning?prioritized_objectives
@@ -85,8 +88,9 @@ What's your reasoning?
Your target groups:
{{#each personas}}
+
- {{this.name}}
-{{/each}}
+ {{/each}}
Looking at your top objective: "{{top_objective}}"
@@ -105,7 +109,7 @@ What's the logic?
The top group gets most design attention. Does this ranking reflect your strategy?
@@ -123,13 +127,15 @@ What's the logic?
Their drivers:
✅ Positive:
{{#each current_group.positive_drivers}}
+
- {{this}}
-{{/each}}
+ {{/each}}
⚠️ Negative:
{{#each current_group.negative_drivers}}
+
- {{this}}
-{{/each}}
+ {{/each}}
**Rank the top 3-5 drivers** this group cares most about.
@@ -158,18 +164,21 @@ Remember: negative drivers often have more weight (loss aversion).
**Must Address:**
{{#each must_address_drivers}}
+
- {{this}}
-{{/each}}
+ {{/each}}
**Should Address:**
{{#each should_address_drivers}}
+
- {{this}}
-{{/each}}
+ {{/each}}
**Could Address (if time permits):**
{{#each could_address_drivers}}
+
- {{this}}
-{{/each}}
+ {{/each}}
Does this focus feel right? This guides all feature decisions.
@@ -180,6 +189,7 @@ Remember: negative drivers often have more weight (loss aversion).
-
diff --git a/src/modules/wds/workflows/2-trigger-mapping/workshops/5-feature-impact/instructions.md b/src/modules/wds/workflows/2-trigger-mapping/workshops/5-feature-impact/instructions.md
index 1283aa9b..aa700f2d 100644
--- a/src/modules/wds/workflows/2-trigger-mapping/workshops/5-feature-impact/instructions.md
+++ b/src/modules/wds/workflows/2-trigger-mapping/workshops/5-feature-impact/instructions.md
@@ -12,11 +12,13 @@
Now we create a **Design Brief** - strategic guidance for the designer on which features matter most and to whom.
For each feature, we'll assess impact on each persona using a simple scale:
+
- **High** = Addresses major need or fear
- **Medium** = Helpful but not critical
- **Low** = Minimal impact
This creates a scored, prioritized feature list that guides:
+
- **Phase 4: UX Design** - Which scenarios to design first
- **Phase 6: PRD/Development** - Epic and story prioritization
@@ -43,6 +45,7 @@ Skip foundational features (auth, profiles, basic CRUD).
Record responseCalculate score:
+
- Primary: High=5, Medium=3, Low=1
- Others: High=3, Medium=1, Low=0
-
+
@@ -89,17 +93,19 @@ How does this impact each persona?
Sort features by score (high to low)Calculate dynamic thresholds based on persona count:
+
- max_possible = 5 (primary high) + 3 × (other_persona_count)
- must_have_threshold = Features with Primary High (5) OR score ≥ (max_possible - 3)
- consider_threshold = mid-range scores
- defer_threshold = low scores
-
+
Apply decisions:
+
- **Must Have:** Primary scored High (5 pts) OR score in top tier
- **Consider:** Medium-range scores, might serve strategic needs
- **Defer:** Low scores, minimal strategic value
-
+
{{/each}}
**Scoring context:**
+
- Max possible score with {{persona_count}} personas: {{max_possible}}
- Top tier (Must Have): {{must_have_threshold}}+
- Primary critical (Must Have): Features with Primary High (5)
@@ -131,6 +138,7 @@ Do NOT include analysis section - keep it clean.
**Saved to:** `B-Trigger-Map/00-feature-impact-analysis.md`
This is your **Design Brief** - it tells the designer:
+
- **What to design first** - Top-scoring features = priority scenarios
- **Prominence in UI** - High scores = prominent placement
- **Who to optimize for** - Which persona's needs matter most
@@ -138,6 +146,7 @@ This is your **Design Brief** - it tells the designer:
**Trigger Mapping Complete!** 🎉
You now have:
+
- Clear business priorities
- Defined target personas with drivers
- Strategically ranked features
diff --git a/src/modules/wds/workflows/3-prd-platform/instructions.md b/src/modules/wds/workflows/3-prd-platform/instructions.md
index d41a3fbe..e7e72c52 100644
--- a/src/modules/wds/workflows/3-prd-platform/instructions.md
+++ b/src/modules/wds/workflows/3-prd-platform/instructions.md
@@ -50,11 +50,13 @@ Before starting, ensure you have:
**Freyja's Role:**
Greet the user and explain this phase:
+
- "We're establishing your technical foundation—proving that innovative features work before investing in design."
- "We'll make platform decisions, validate risky features with PoCs, and set up experimental endpoints."
- "This enables backend development to start in parallel with UX design."
Review available context:
+
- Read the Product Brief to understand project scope and constraints
- Read the Feature Impact Analysis to identify high-priority features
- Ask: "Do you already have any technical constraints or platform preferences?"
@@ -206,7 +208,7 @@ Ask systematically:
Read the Product Brief and identify relevant integration categories based on features mentioned:
- **Payment Processing:** Transactions, subscriptions, e-commerce, paid features, pricing
-- **Communication:** User notifications, emails, SMS, alerts, reminders
+- **Communication:** User notifications, emails, SMS, alerts, reminders
- **Maps/Location:** Geographic features, addresses, directions, proximity, location-based services
- **Search:** Large content volumes, filtering, discovery features
- **Calendar/Scheduling:** Bookings, appointments, events, availability
@@ -230,6 +232,7 @@ Read the Product Brief and identify relevant integration categories based on fea
**Go through each relevant category systematically:**
**3A: Authentication & Identity**
+
- "How will users authenticate?" (OAuth, email/password, SSO, passwordless)
- "Which providers?" (Google, Microsoft, Auth0, etc.)
- **Document for each:**
@@ -240,6 +243,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Technical risk (high/medium/low)
**3B: Payment Processing** (if applicable)
+
- "Do you need payment processing?"
- "Which payment providers?" (Stripe, PayPal, Klarna, Swish, regional systems)
- "What payment methods?" (credit cards, bank transfers, mobile payments, digital wallets)
@@ -262,6 +266,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Technical risk level
**3C: Communication Services**
+
- "Do you need to send emails?" → Which service? (SendGrid, Mailgun, AWS SES, Postmark)
- "Do you need SMS?" → Which service? (Twilio, MessageBird, Vonage)
- "Push notifications?" → Which service? (Firebase Cloud Messaging, OneSignal, Pusher)
@@ -279,6 +284,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost
**3D: Search Services** (if applicable)
+
- "Do you need advanced search functionality?"
- "Which service?" (Algolia, Elasticsearch, Typesense, Meilisearch)
- **Document for each:**
@@ -295,6 +301,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost
**3E: Maps & Location** (if applicable)
+
- "Do you need maps or geolocation?"
- "Which service?" (Google Maps, Mapbox, OpenStreetMap, Here)
- **Document for each:**
@@ -313,6 +320,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & risk level
**3F: Data & Analytics**
+
- "What analytics do you need?" (Google Analytics, Mixpanel, Amplitude, custom)
- "Error tracking?" (Sentry, Rollbar, Bugsnag)
- "Application monitoring?" (New Relic, Datadog, AppDynamics)
@@ -329,6 +337,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost
**3G: Storage & Media**
+
- "Do you need file/image storage?" (S3, Azure Blob, Google Cloud Storage, Cloudinary)
- "CDN for assets?" (CloudFlare, Fastly, AWS CloudFront)
- "Video hosting/streaming?" (Vimeo, YouTube, Mux, AWS Media Services)
@@ -346,6 +355,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost
**3H: Calendar & Scheduling** (if applicable)
+
- "Do you need calendar integrations?"
- "Which services?" (Google Calendar, Outlook/Microsoft 365, iCal)
- "Scheduling/booking systems?" (Calendly-style booking)
@@ -360,6 +370,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost
**3I: Social Media & Content** (if applicable)
+
- "Do you need social media integrations?"
- "Which platforms?" (Facebook, Twitter/X, LinkedIn, Instagram)
- "Social login?" (covered in 3A, but cross-reference)
@@ -374,6 +385,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost
**3J: Customer Support & Help** (if applicable)
+
- "Do you need customer support tools?"
- "Which services?" (Intercom, Zendesk, Helpscout, Crisp)
- "Live chat?" (service or custom)
@@ -388,6 +400,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost
**3K: Marketing & Growth** (if applicable)
+
- "Do you need marketing automation?"
- "Which services?" (Mailchimp, HubSpot, ActiveCampaign)
- "A/B testing?" (Optimizely, VWO, custom)
@@ -402,6 +415,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost
**3L: Domain-Specific APIs**
+
- "Any other APIs specific to your domain?" (industry-specific services)
- Examples: Weather APIs, financial data, shipping/logistics, government data, industry databases
- **Document for each:**
@@ -425,18 +439,21 @@ Read the Product Brief and identify relevant integration categories based on fea
**Goal:** Determine which features need Proofs of Concept (PoCs).
Review the Feature Impact Analysis and ask:
+
- **Which features are innovative or unproven?**
- **Which features depend on external APIs that might have limitations?**
- **Which features have unknown performance characteristics?**
- **Which features might not be technically feasible?**
**Red Flags That Suggest PoC Needed:**
+
- "Can we actually get X data from Y service?"
- "Will this perform fast enough?"
- "Does this API return data in a usable format?"
- "Can we achieve real-time updates at scale?"
Create a list of features requiring validation, prioritized by:
+
1. **High Feature Impact Score** (from Phase 2) + **High Technical Risk**
2. **Medium Feature Impact** + **High Technical Risk**
3. **High Feature Impact** + **Medium Technical Risk**
@@ -469,6 +486,7 @@ For each feature identified in Step 4:
**Output:** Create `02-Technical-Proofs-Of-Concept.md` documenting all PoC work.
**Positive Framing:**
+
- When features work: "Great! This proves [feature] is technically sound. Design can proceed with confidence."
- When features have limitations: "Valuable discovery! We found [limitation] early. This helps design account for it from the start."
- When features don't work: "Important learning! This saves weeks of design work on an infeasible feature. Let's explore alternatives."
@@ -618,6 +636,7 @@ Ask systematically about all regulatory requirements:
"Let's start with authentication. Based on our security framework, what auth endpoints do you need?"
For each endpoint:
+
- Method & Path (e.g., `POST /api/auth/login`)
- Purpose & business value
- Request/response format with detailed schemas
@@ -636,6 +655,7 @@ Common auth endpoints: login, logout, token refresh, password reset, email verif
Go through each entity from the data model systematically:
For each entity, define all CRUD operations:
+
- `GET /api/{entity}` - List with pagination
- `GET /api/{entity}/:id` - Get single item
- `POST /api/{entity}` - Create new
@@ -643,17 +663,19 @@ For each entity, define all CRUD operations:
- `DELETE /api/{entity}/:id` - Delete item
**Business Rules for each:**
- - Validation rules (required fields, formats, constraints)
- - Authorization (who can perform this operation?)
- - Pagination parameters (page size, sorting, filtering)
- - Related data inclusion (nested objects, joins)
- - Business logic constraints
+
+- Validation rules (required fields, formats, constraints)
+- Authorization (who can perform this operation?)
+- Pagination parameters (page size, sorting, filtering)
+- Related data inclusion (nested objects, joins)
+- Business logic constraints
**7C: External Integration APIs**
"Which external services need API endpoints? Let's create wrappers for each."
For each external service from Step 3:
+
- Method & Path
- Purpose ("Wraps Google Maps API to get walking time")
- Request/response format
@@ -672,6 +694,7 @@ For each external service from Step 3:
Examples: availability checks, pricing, recommendations, aggregations
For each:
+
- Method & Path
- Purpose & business value
- Request/response format
@@ -705,6 +728,7 @@ For each:
"We identified your core entities earlier. Now let's document the complete data model."
For each entity:
+
- Entity name & purpose
- All fields with types, constraints, defaults
- Relationships to other entities (one-to-many, many-to-many)
@@ -723,6 +747,7 @@ Create entity relationship diagram (ERD) showing all connections.
"What are your performance and scalability expectations?"
Document systematically:
+
- **Response Times:** Expected latency for each API category
- **Throughput:** Concurrent users, requests per second
- **Data Volume:** Expected record counts, storage needs
@@ -732,6 +757,7 @@ Document systematically:
**Ask:** "Any other data modeling or performance considerations we should capture?"
**Outputs:**
+
- `05-Data-Models.md` - Complete schemas and ERD
- `06-Performance-Requirements.md` - Benchmarks and scalability specs
@@ -746,6 +772,7 @@ Document systematically:
"This document tells the UX team what they need to know about technical possibilities and limitations."
**Include:**
+
- **What's Possible:** Validated features from PoCs, platform capabilities
- **What Has Limitations:** Technical constraints, API limits, performance characteristics
- **What Affects Design:** Loading states, offline behavior, real-time vs. polling
@@ -756,6 +783,7 @@ Document systematically:
"How do we know when each platform component is 'done'?"
For each major platform area (auth, integrations, security, etc.):
+
- **Functional Criteria:** What must work?
- **Performance Criteria:** How fast/scalable must it be?
- **Security Criteria:** What security standards must be met?
@@ -764,6 +792,7 @@ For each major platform area (auth, integrations, security, etc.):
**Ask:** "Any other constraints or success criteria we should document?"
**Outputs:**
+
- `07-Technical-Constraints.md` - UX design handoff
- `08-Acceptance-Criteria.md` - Testable success definitions
@@ -782,6 +811,7 @@ For each major platform area (auth, integrations, security, etc.):
"Let's look at your high-priority features from Phase 2..."
Read the Feature Impact Analysis (B-Trigger-Map/03-Feature-Impact-Analysis.md) and identify:
+
- **Must Have features** (high scores, high for primary persona)
- **Consider for MVP features** (balanced scores)
- **Platform dependencies** - What platform work is needed to enable each high-impact feature?
@@ -832,21 +862,19 @@ For each recommended epic, note which high-priority features it enables:
"Here's the order I'd recommend, based on Feature Impact Analysis:"
**Priority 1: Enable Must-Have Features**
+
1. **Foundation First:** Core infrastructure (hosting, database, basic security)
2. **High-Impact Dependencies:** Platform work needed for Must-Have features
- [Epic] enables [Feature] (Score: X) for [Primary Persona]
- [Epic] enables [Feature] (Score: Y) for [Primary Persona]
-**Priority 2: Risk Mitigation**
-3. **Complex Integrations:** External APIs that are risky or complex (fail fast)
- - [Integration Epic] enables [Feature] (Score: X)
+**Priority 2: Risk Mitigation** 3. **Complex Integrations:** External APIs that are risky or complex (fail fast)
-**Priority 3: Secondary Features**
-4. **Remaining Integrations:** Other external services
-5. **Advanced Features:** Performance optimization, advanced security
+- [Integration Epic] enables [Feature] (Score: X)
-**Priority 4: Operations**
-6. **Monitoring & Tools:** Logging, analytics, maintenance tools
+**Priority 3: Secondary Features** 4. **Remaining Integrations:** Other external services 5. **Advanced Features:** Performance optimization, advanced security
+
+**Priority 4: Operations** 6. **Monitoring & Tools:** Logging, analytics, maintenance tools
**10D: Feature-to-Epic Mapping**
@@ -862,12 +890,14 @@ Create a table:
**10E: API Contracts for Future UI Development**
"These API specifications are ready for frontend development:"
+
- [List key API categories organized by priority features they enable]
- Backend can implement these in parallel with Phase 4 (UX Design)
**10F: Dependencies & Parallel Work**
"Key dependencies to consider:"
+
- What must be done before high-impact features can be built?
- What can be developed independently in parallel?
- What provides the most risk reduction AND feature enablement if done early?
@@ -875,6 +905,7 @@ Create a table:
**Ask:** "Does this platform work organization make sense based on your feature priorities? Any initiatives or priorities you'd adjust?"
**Output:** Create `09-Platform-Backlog-Recommendations.md` with:
+
- **Feature Impact Summary** - High-priority features from Phase 2
- **Feature-to-Epic Mapping** - Clear connections between features and platform work
- Recommended initiative structure
@@ -901,8 +932,8 @@ Create a table:
```markdown
# Product Requirements Document: [Project Name]
-*Phase 3 Complete: Technical Foundation Established*
-*Last Updated: [Date]*
+_Phase 3 Complete: Technical Foundation Established_
+_Last Updated: [Date]_
---
@@ -916,30 +947,39 @@ Create a table:
## 2. Technical Foundation (Phase 3)
### 2.1 Platform Architecture
+
[Link to C-Requirements/00-Platform-Architecture.md]
### 2.2 External Integrations
+
[Link to C-Requirements/01-Integration-Map.md]
### 2.3 Technical Validation
+
[Link to C-Requirements/02-Technical-Proofs-Of-Concept.md]
### 2.4 Security & Compliance
+
[Link to C-Requirements/03-Security-Framework.md]
### 2.5 API Specifications
+
[Link to C-Requirements/04-API-Specifications.md]
### 2.6 Data Models
+
[Link to C-Requirements/05-Data-Models.md]
### 2.7 Performance Requirements
+
[Link to C-Requirements/06-Performance-Requirements.md]
### 2.8 Technical Constraints
+
[Link to C-Requirements/07-Technical-Constraints.md]
### 2.9 Acceptance Criteria
+
[Link to C-Requirements/08-Acceptance-Criteria.md]
---
@@ -949,6 +989,7 @@ Create a table:
[Link to C-Requirements/09-Platform-Backlog-Recommendations.md]
**Summary:**
+
- **Recommended Initiatives:** [List]
- **Suggested Epics:** [Count]
- **API Contracts Ready:** [Key APIs]
@@ -958,24 +999,28 @@ Create a table:
## 4. Functional Requirements (Phase 4)
-*This section will be populated during Phase 4 (UX Design) as each page/scenario is completed.*
+_This section will be populated during Phase 4 (UX Design) as each page/scenario is completed._
### [Feature Area 1]
-*Coming from Phase 4*
+
+_Coming from Phase 4_
### [Feature Area 2]
-*Coming from Phase 4*
+
+_Coming from Phase 4_
---
## 5. Next Steps
**For BMM Agents:**
+
- Use platform backlog recommendations to create E-Backlog/ structure
- Create detailed epics and stories from requirements documents
- Establish implementation roadmap with dependencies
**For Phase 4 (UX Design):**
+
- Technical constraints document provides design boundaries
- API specifications define data available to UI
- Begin UX design with confidence in technical feasibility
@@ -1033,6 +1078,7 @@ Create a table:
7. **"Anything about performance, scalability, or deployment we should capture?"**
**If user identifies gaps:**
+
- Document the additional items in the appropriate files
- "Great catch! Let me add that to [relevant document]..."
- After adding, return to completeness check
@@ -1062,6 +1108,7 @@ Create a table:
- Each completed page will add functional requirements to the PRD
**What happens next:**
+
- Platform backlog recommendations guide BMM agents in creating E-Backlog/
- Development teams can begin platform work based on requirements
- Phase 4 (UX Design) can begin, informed by technical constraints
@@ -1075,22 +1122,27 @@ Create a table:
### For Freyja the PM:
**Validate Early, Often:**
+
- Don't let risky features proceed without PoC validation
- "Let's prove this works before investing in design"
**Positive Language:**
+
- Frame discoveries as valuable, not failures
- "Great that we learned this now, not after design is complete"
**Stay Connected to Strategy:**
+
- Reference Feature Impact Analysis scores when prioritizing PoCs
- High-impact features deserve thorough validation
**Enable Parallel Work:**
+
- Think about what backend teams can start building immediately
- Experimental endpoints should focus on clear, achievable tasks
**Document for Design:**
+
- Technical Constraints doc is crucial for Phase 4 success
- Be specific about what design needs to accommodate
@@ -1106,5 +1158,4 @@ Use these templates to structure outputs:
---
-*Phase 3 workflow for Whiteport Design Studio (WDS) methodology*
-
+_Phase 3 workflow for Whiteport Design Studio (WDS) methodology_
diff --git a/src/modules/wds/workflows/3-prd-platform/templates/experimental-endpoints.template.md b/src/modules/wds/workflows/3-prd-platform/templates/experimental-endpoints.template.md
index 6e8fbd06..3354d107 100644
--- a/src/modules/wds/workflows/3-prd-platform/templates/experimental-endpoints.template.md
+++ b/src/modules/wds/workflows/3-prd-platform/templates/experimental-endpoints.template.md
@@ -9,6 +9,7 @@
## Purpose
These are early API specifications for endpoints we know we'll need. Setting them up now enables:
+
- Early backend development (parallel with UX design)
- Validation that our data model works
- Fail-fast discovery of integration issues
@@ -27,17 +28,20 @@ These are early API specifications for endpoints we know we'll need. Setting the
## Authentication Endpoints
{{#each auth_endpoints}}
+
### {{this.method}} {{this.path}}
**Status:** {{this.status}}
**Purpose:** {{this.purpose}}
**Request:**
+
```json
{{this.request_example}}
```
**Response:**
+
```json
{{this.response_example}}
```
@@ -45,11 +49,13 @@ These are early API specifications for endpoints we know we'll need. Setting the
**Notes:** {{this.notes}}
---
+
{{/each}}
## Core CRUD Operations
{{#each crud_endpoints}}
+
### {{this.method}} {{this.path}}
**Status:** {{this.status}}
@@ -57,11 +63,13 @@ These are early API specifications for endpoints we know we'll need. Setting the
**Entity:** {{this.entity}}
**Request:**
+
```json
{{this.request_example}}
```
**Response:**
+
```json
{{this.response_example}}
```
@@ -70,11 +78,13 @@ These are early API specifications for endpoints we know we'll need. Setting the
**Notes:** {{this.notes}}
---
+
{{/each}}
## External Integration Endpoints
{{#each integration_endpoints}}
+
### {{this.method}} {{this.path}}
**Status:** {{this.status}}
@@ -82,53 +92,62 @@ These are early API specifications for endpoints we know we'll need. Setting the
**External Service:** {{this.external_service}}
**Request:**
+
```json
{{this.request_example}}
```
**Response:**
+
```json
{{this.response_example}}
```
**Validates:**
+
- {{#each this.validates}}
- {{this}}
-{{/each}}
+ {{/each}}
**Cost per Call:** {{this.cost_per_call}}
**Rate Limits:** {{this.rate_limits}}
**Notes:** {{this.notes}}
---
+
{{/each}}
## Business Logic Endpoints
{{#each logic_endpoints}}
+
### {{this.method}} {{this.path}}
**Status:** {{this.status}}
**Purpose:** {{this.purpose}}
**Request:**
+
```json
{{this.request_example}}
```
**Response:**
+
```json
{{this.response_example}}
```
**Business Rules:**
{{#each this.business_rules}}
+
- {{this}}
-{{/each}}
+ {{/each}}
**Notes:** {{this.notes}}
---
+
{{/each}}
## Error Handling
@@ -149,27 +168,32 @@ These are early API specifications for endpoints we know we'll need. Setting the
### Common Error Codes
{{#each error_codes}}
+
- **{{this.code}}** ({{this.http_status}}): {{this.description}}
-{{/each}}
+ {{/each}}
---
## API Conventions
### Base URL
+
```
{{api_base_url}}
```
### Authentication
+
{{api_authentication_method}}
### Request Headers
+
```
{{api_request_headers}}
```
### Response Format
+
{{api_response_format}}
---
@@ -179,8 +203,9 @@ These are early API specifications for endpoints we know we'll need. Setting the
These endpoints are also tracked in `E-PRD-Finalization/` as handoff tasks:
{{#each development_tasks}}
+
- [ ] **{{this.endpoint}}** - {{this.description}} (Priority: {{this.priority}})
-{{/each}}
+ {{/each}}
---
@@ -193,5 +218,4 @@ These endpoints are also tracked in `E-PRD-Finalization/` as handoff tasks:
---
-*Phase 3 artifact for {{project_name}}*
-
+_Phase 3 artifact for {{project_name}}_
diff --git a/src/modules/wds/workflows/3-prd-platform/templates/platform-architecture.template.md b/src/modules/wds/workflows/3-prd-platform/templates/platform-architecture.template.md
index 77d6c74e..2f0ba725 100644
--- a/src/modules/wds/workflows/3-prd-platform/templates/platform-architecture.template.md
+++ b/src/modules/wds/workflows/3-prd-platform/templates/platform-architecture.template.md
@@ -9,24 +9,28 @@
## Technology Stack
### Backend
+
- **Framework/Language:** {{backend_framework}}
- **Runtime:** {{backend_runtime}}
- **Rationale:** {{backend_rationale}}
### Frontend
+
- **Framework:** {{frontend_framework}}
- **UI Library:** {{ui_library}}
- **Rationale:** {{frontend_rationale}}
### Database
+
- **Primary Database:** {{primary_database}}
- **Type:** {{database_type}}
- **Rationale:** {{database_rationale}}
{{#if secondary_database}}
+
- **Secondary Database:** {{secondary_database}}
- **Purpose:** {{secondary_purpose}}
-{{/if}}
+ {{/if}}
---
@@ -35,36 +39,42 @@
**Approach:** {{architecture_style}}
{{#if architecture_style == "Monolith"}}
+
- Single codebase deployment
- Simplified development and deployment
- {{monolith_rationale}}
-{{/if}}
+ {{/if}}
{{#if architecture_style == "Microservices"}}
+
- Service boundaries: {{service_boundaries}}
- Communication: {{service_communication}}
- {{microservices_rationale}}
-{{/if}}
+ {{/if}}
{{#if architecture_style == "Serverless"}}
+
- Functions: {{serverless_functions}}
- Triggers: {{serverless_triggers}}
- {{serverless_rationale}}
-{{/if}}
+ {{/if}}
---
## Infrastructure & Hosting
### Platform
+
- **Cloud Provider:** {{cloud_provider}}
- **Hosting Type:** {{hosting_type}}
- **Rationale:** {{infrastructure_rationale}}
### Services
+
{{#each infrastructure_services}}
+
- **{{this.name}}:** {{this.description}}
-{{/each}}
+ {{/each}}
---
@@ -73,19 +83,22 @@
### Core Entities
{{#each core_entities}}
+
#### {{this.name}}
**Purpose:** {{this.purpose}}
**Key Fields:**
{{#each this.fields}}
+
- `{{this.name}}` ({{this.type}}) - {{this.description}}
-{{/each}}
+ {{/each}}
**Relationships:**
{{#each this.relationships}}
+
- {{this.type}} {{this.target}} - {{this.description}}
-{{/each}}
+ {{/each}}
{{/each}}
@@ -124,8 +137,9 @@
## Technical Constraints
{{#each technical_constraints}}
+
- **{{this.area}}:** {{this.constraint}}
-{{/each}}
+ {{/each}}
---
@@ -134,12 +148,12 @@
### Monthly Operating Costs (Estimated)
{{#each cost_estimates}}
+
- **{{this.service}}:** {{this.cost}} {{this.currency}}
-{{/each}}
+ {{/each}}
**Total Estimated:** {{total_monthly_cost}} {{currency}}/month
---
-*Phase 3 artifact for {{project_name}}*
-
+_Phase 3 artifact for {{project_name}}_
diff --git a/src/modules/wds/workflows/3-prd-platform/templates/technical-constraints.template.md b/src/modules/wds/workflows/3-prd-platform/templates/technical-constraints.template.md
index c25ea1e3..e9af1e83 100644
--- a/src/modules/wds/workflows/3-prd-platform/templates/technical-constraints.template.md
+++ b/src/modules/wds/workflows/3-prd-platform/templates/technical-constraints.template.md
@@ -18,6 +18,7 @@ This document summarizes technical decisions and constraints that inform UX desi
### Validated Features
{{#each validated_features}}
+
#### {{this.feature_name}}
**Status:** {{this.status}}
@@ -29,8 +30,9 @@ This document summarizes technical decisions and constraints that inform UX desi
### Platform Capabilities
{{#each platform_capabilities}}
+
- **{{this.capability}}:** {{this.description}}
-{{/each}}
+ {{/each}}
---
@@ -39,6 +41,7 @@ This document summarizes technical decisions and constraints that inform UX desi
### Technical Limitations
{{#each limitations}}
+
#### {{this.area}}
**Constraint:** {{this.constraint}}
@@ -50,8 +53,9 @@ This document summarizes technical decisions and constraints that inform UX desi
### External API Constraints
{{#each api_constraints}}
+
- **{{this.service}}:** {{this.constraint}} - {{this.design_impact}}
-{{/each}}
+ {{/each}}
---
@@ -60,6 +64,7 @@ This document summarizes technical decisions and constraints that inform UX desi
### Performance Characteristics
{{#each performance_characteristics}}
+
#### {{this.operation}}
- **Expected Time:** {{this.time}}
@@ -71,8 +76,9 @@ This document summarizes technical decisions and constraints that inform UX desi
### Connection Requirements
{{#each connection_requirements}}
+
- **{{this.feature}}:** {{this.requirement}} - {{this.design_impact}}
-{{/each}}
+ {{/each}}
---
@@ -81,6 +87,7 @@ This document summarizes technical decisions and constraints that inform UX desi
### Cost-Sensitive Features
{{#each expensive_features}}
+
#### {{this.feature}}
**Cost Driver:** {{this.cost_driver}}
@@ -94,12 +101,15 @@ This document summarizes technical decisions and constraints that inform UX desi
## 🌐 Platform Compatibility
### Browser Support
+
{{browser_support}}
### Device Support
+
{{device_support}}
### Accessibility
+
{{accessibility_considerations}}
---
@@ -107,12 +117,15 @@ This document summarizes technical decisions and constraints that inform UX desi
## 🔒 Security Constraints
### Authentication
+
{{authentication_constraints}}
### Data Handling
+
{{data_handling_constraints}}
### Compliance
+
{{compliance_constraints}}
---
@@ -120,13 +133,17 @@ This document summarizes technical decisions and constraints that inform UX desi
## 📱 Offline Behavior
{{#if offline_support}}
+
### What Works Offline
+
{{offline_capabilities}}
### What Requires Connection
+
{{online_requirements}}
### Sync Strategy
+
{{sync_strategy}}
{{else}}
**Offline Mode:** Not supported - All features require active connection
@@ -139,6 +156,7 @@ This document summarizes technical decisions and constraints that inform UX desi
Based on technical validation:
{{#each design_recommendations}}
+
### {{this.category}}
{{this.recommendation}}
@@ -153,11 +171,12 @@ Based on technical validation:
{{#if open_questions}}
{{#each open_questions}}
+
- {{this}}
-{{/each}}
-{{else}}
-No open questions at this time.
-{{/if}}
+ {{/each}}
+ {{else}}
+ No open questions at this time.
+ {{/if}}
---
@@ -169,5 +188,4 @@ No open questions at this time.
---
-*Phase 3 → 4 Handoff Document for {{project_name}}*
-
+_Phase 3 → 4 Handoff Document for {{project_name}}_
diff --git a/src/modules/wds/workflows/3-prd-platform/workflow.yaml b/src/modules/wds/workflows/3-prd-platform/workflow.yaml
index 5a7fee28..b1521778 100644
--- a/src/modules/wds/workflows/3-prd-platform/workflow.yaml
+++ b/src/modules/wds/workflows/3-prd-platform/workflow.yaml
@@ -3,7 +3,6 @@ name: PRD Platform Workflow
description: Establish technical foundation, validate risky features, and set up experimental endpoints
web_bundle: true
---
-
# WDS Phase 3: PRD Platform (Technical Foundation)
name: "Phase 3: PRD Platform (Technical Foundation)"
agent: "Freyja the PM"
@@ -37,4 +36,3 @@ optional_inputs:
- "Existing technical constraints"
estimated_duration: "2-4 hours (plus PoC development time)"
-
diff --git a/src/modules/wds/workflows/4-ux-design/ARCHITECTURE.md b/src/modules/wds/workflows/4-ux-design/ARCHITECTURE.md
index b13e8bf5..2ae026a2 100644
--- a/src/modules/wds/workflows/4-ux-design/ARCHITECTURE.md
+++ b/src/modules/wds/workflows/4-ux-design/ARCHITECTURE.md
@@ -81,13 +81,16 @@
## Key Innovations
### 1. Step-File Architecture ✅
+
- **Just-in-time loading** - Only current step in memory
- **Sequential enforcement** - Steps load one at a time
- **Clear progression** - 5 main steps → substeps → object-types
- **State tracking** - Progress saved between sessions
### 2. Granular Specification (8 Micro-Steps) ✅
+
Instead of one large 4C step, broke into focused substeps:
+
1. **Page Basics** - Fundamentals
2. **Layout Sections** - Structure
3. **Components & Objects** - Systematic identification
@@ -98,6 +101,7 @@ Instead of one large 4C step, broke into focused substeps:
8. **Generate Spec** - Compile document
### 3. Object-Type Routing System ✅
+
- **21 specialized object-type files** (6 created, 15 to create)
- **Each file has precise examples** for consistency
- **Ensures uniform output** across all WDS projects
@@ -105,6 +109,7 @@ Instead of one large 4C step, broke into focused substeps:
### 4. Intelligent Analysis (Trust-the-Agent) ✅✨
**Old Approach (Procedural):**
+
```
What type of object is this?
1. Button
@@ -114,6 +119,7 @@ What type of object is this?
```
**New Approach (Intelligent):**
+
```
My interpretation:
@@ -133,6 +139,7 @@ Does this match your intent? [Y/Clarify/No]
```
**Benefits:**
+
- ✅ Agent demonstrates intelligence
- ✅ Context-aware interpretation
- ✅ Natural conversation
@@ -140,6 +147,7 @@ Does this match your intent? [Y/Clarify/No]
- ✅ v6 "goal-based trust" philosophy
### 5. Systematic Sketch Analysis ✅
+
- **Top-to-bottom, left-to-right** within sections
- **Component reuse detection** across pages
- **Section-by-section** organization
@@ -222,21 +230,25 @@ Step 5: Next Steps
## Benefits for WDS Users
**Consistency Across Projects:**
+
- Same object types documented the same way
- Every WDS project produces uniform specs
- Developers know what to expect
**Agent Clarity:**
+
- Focused instructions prevent confusion
- Clear routing eliminates ambiguity
- Examples guide output format
**User Experience:**
+
- Intelligent suggestions feel natural
- Quick confirmations when agent is right
- Systematic coverage ensures nothing missed
**Maintainability:**
+
- Easy to add new object types
- Each file independently improvable
- Clear separation of concerns
@@ -246,6 +258,7 @@ Step 5: Next Steps
## Status
**✅ Complete:**
+
- Main workflow structure (5 steps)
- All substeps (4A, 4B, 4C-01 through 4C-08, 4D, 4E)
- Object-router with intelligent analysis
@@ -253,11 +266,10 @@ Step 5: Next Steps
- Templates
**⏳ To Create:**
+
- 15 additional object-type files
- Object-type files should follow same pattern with precise examples
---
**This architecture ensures consistent, high-quality specifications across all WDS projects while making the agent experience intelligent and natural.** 🎨✨
-
-
diff --git a/src/modules/wds/workflows/4-ux-design/COMPONENT-FILE-STRUCTURE.md b/src/modules/wds/workflows/4-ux-design/COMPONENT-FILE-STRUCTURE.md
index 1cc3efde..a4d1c951 100644
--- a/src/modules/wds/workflows/4-ux-design/COMPONENT-FILE-STRUCTURE.md
+++ b/src/modules/wds/workflows/4-ux-design/COMPONENT-FILE-STRUCTURE.md
@@ -49,6 +49,7 @@ project-root/
**Purpose:** Page-specific layout, component placement, and context
**Contains:**
+
- Page metadata (URL, scenario, purpose)
- Layout structure (sections, grid)
- Component instances with page-specific config
@@ -56,10 +57,12 @@ project-root/
- Navigation flow (entry/exit points)
**Does NOT contain:**
+
- Component visual design (→ Components/)
- Interactive logic (→ Features/)
**Example:** `02-calendar-page.md`
+
```markdown
# 02-calendar-page
@@ -69,10 +72,12 @@ project-root/
## 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:
@@ -82,6 +87,7 @@ project-root/
- Feature: `calendar-logic` (from Features/)
### Sidebar
+
- Component: `walk-scheduler` (from Components/)
- Position: Right, 20% width
- Feature: `walk-assignment` (from Features/)
@@ -89,6 +95,7 @@ project-root/
## Content
**Page Title:**
+
- EN: "Family Dog Care Calendar"
- SE: "Familjens Hundvårdskalender"
```
@@ -100,6 +107,7 @@ project-root/
**Purpose:** Visual design, states, variants, Figma specifications
**Contains:**
+
- Component name and purpose
- Visual specifications (colors, spacing, typography)
- States (default, hover, active, disabled, loading, error)
@@ -109,10 +117,12 @@ project-root/
- Accessibility requirements
**Does NOT contain:**
+
- Business logic (→ Features/)
- Page-specific placement (→ Pages/)
**Example:** `calendar-widget.component.md`
+
```markdown
# Calendar Widget Component
@@ -127,18 +137,21 @@ Displays a monthly calendar view with interactive date selection and event displ
## 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`
@@ -149,33 +162,39 @@ Displays a monthly calendar view with interactive date selection and event displ
## 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
@@ -183,11 +202,13 @@ Displays a monthly calendar view with interactive date selection and event displ
## 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
@@ -197,6 +218,7 @@ Displays a monthly calendar view with interactive date selection and event displ
**Component Path:** `Design System > Widgets > Calendar`
**Variants to Create:**
+
- Size: Large / Medium / Small
- View: Month / Week / Day
- State: Default / Selected / Disabled / Loading
@@ -207,16 +229,19 @@ Displays a monthly calendar view with interactive date selection and event displ
## 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)
@@ -227,12 +252,10 @@ Displays a monthly calendar view with interactive date selection and event displ
- 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
@@ -250,6 +273,7 @@ Displays a monthly calendar view with interactive date selection and event displ
**Purpose:** Interactive logic, business rules, data flow, state management
**Contains:**
+
- Feature name and purpose
- User interactions and system responses
- Business rules and validation
@@ -258,11 +282,13 @@ Displays a monthly calendar view with interactive date selection and event displ
- Edge cases and error handling
**Does NOT contain:**
+
- Visual design (→ Components/)
- Page layout (→ Pages/)
**Example:** `calendar-logic.feature.md`
-```markdown
+
+````markdown
# Calendar Logic Feature
**Feature ID:** `calendar-logic`
@@ -280,6 +306,7 @@ Manages calendar interactions, date selection, event display, and navigation bet
**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
@@ -288,12 +315,14 @@ Manages calendar interactions, date selection, event display, and navigation bet
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
@@ -303,6 +332,7 @@ Manages calendar interactions, date selection, event display, and navigation bet
**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)
@@ -311,6 +341,7 @@ Manages calendar interactions, date selection, event display, and navigation bet
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
@@ -320,12 +351,14 @@ Manages calendar interactions, date selection, event display, and navigation bet
**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
@@ -344,10 +377,12 @@ Manages calendar interactions, date selection, event display, and navigation bet
error: string | null // Error message
}
```
+````
### State Transitions
**Initial State:**
+
- currentMonth: Current month
- selectedDate: null
- viewMode: 'month'
@@ -356,10 +391,12 @@ Manages calendar interactions, date selection, event display, and navigation bet
- 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
@@ -367,6 +404,7 @@ Manages calendar interactions, date selection, event display, and navigation bet
- loading: false
**On Error:**
+
- error: error message
- loading: false
- Show error state in UI
@@ -376,6 +414,7 @@ Manages calendar interactions, date selection, event display, and navigation bet
### API Endpoints
**Get Events for Month**
+
- **Method:** GET
- **Path:** `/api/calendar/events?month={YYYY-MM}`
- **Purpose:** Fetch all events for specified month
@@ -395,6 +434,7 @@ Manages calendar interactions, date selection, event display, and navigation bet
```
**Create Event**
+
- **Method:** POST
- **Path:** `/api/calendar/events`
- **Purpose:** Create new calendar event
@@ -411,13 +451,14 @@ Manages calendar interactions, date selection, event display, and navigation bet
### Data Models
**Event Model:**
+
```typescript
interface Event {
id: string;
- date: string; // ISO date format
+ date: string; // ISO date format
title: string;
category: 'walk' | 'feeding' | 'vet' | 'grooming';
- assignedTo: string; // User ID
+ assignedTo: string; // User ID
completed: boolean;
notes?: string;
}
@@ -425,21 +466,23 @@ interface Event {
## 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)" |
+| 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"
@@ -467,6 +510,7 @@ interface Event {
- **Component:** `calendar-widget.component.md` (visual design)
- **Feature:** `walk-assignment.feature.md` (for creating walk events)
- **API:** Calendar Events API
+
```
---
@@ -485,10 +529,12 @@ interface Event {
**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
+Pages/05-dashboard.md → Components/calendar-widget.component.md
+↓
+Features/calendar-logic.feature.md
+
```
**Same component, different configurations:**
@@ -524,16 +570,19 @@ Pages/05-dashboard.md → Components/calendar-widget.component.md
### Pages
```
+
{number}-{page-name}.md
Examples:
01-start-page.md
02-calendar-page.md
03-profile-settings.md
+
```
### Components
```
+
{component-name}.component.md
Examples:
@@ -541,10 +590,12 @@ navigation-bar.component.md
feature-card.component.md
calendar-widget.component.md
walk-scheduler.component.md
+
```
### Features
```
+
{feature-name}.feature.md
Examples:
@@ -552,7 +603,8 @@ calendar-logic.feature.md
walk-assignment.feature.md
user-authentication.feature.md
notification-system.feature.md
-```
+
+````
---
@@ -570,7 +622,7 @@ Reference components and features:
**Configuration:**
- View: Month
- Disable past dates: true
-```
+````
### In Component Files
@@ -599,21 +651,25 @@ Reference related components:
## 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/
@@ -678,6 +734,7 @@ Features/walk-assignment.feature.md (150 lines)
3. **Features/** - Logic, rules, data (WHAT IT DOES)
**Benefits:**
+
- ✅ Clear separation of concerns
- ✅ Reusable components across pages
- ✅ Maintainable business logic
diff --git a/src/modules/wds/workflows/4-ux-design/CONTENT-PLACEMENT-GUIDE.md b/src/modules/wds/workflows/4-ux-design/CONTENT-PLACEMENT-GUIDE.md
index deaef915..d44edd74 100644
--- a/src/modules/wds/workflows/4-ux-design/CONTENT-PLACEMENT-GUIDE.md
+++ b/src/modules/wds/workflows/4-ux-design/CONTENT-PLACEMENT-GUIDE.md
@@ -30,6 +30,7 @@ Is this CONTENT (text, images, data)?
### 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)
@@ -37,9 +38,10 @@ Is this CONTENT (text, images, data)?
- ✅ Feature references
**Example:**
+
```markdown
-Pages/01-home-page.md
----
+## Pages/01-home-page.md
+
### Hero Section
**Component:** `hero-banner.component.md`
@@ -48,6 +50,7 @@ Pages/01-home-page.md
**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`
@@ -60,6 +63,7 @@ Pages/01-home-page.md
### 2. Component File (HOW IT LOOKS)
**Contains:**
+
- ✅ Visual specifications (colors, spacing, typography)
- ✅ States (default, hover, active, disabled, loading, error)
- ✅ Variants (sizes, types, themes)
@@ -69,12 +73,14 @@ Pages/01-home-page.md
- ❌ **NO content** (no text, no images, no data)
**Example:**
+
```markdown
-Components/hero-banner.component.md
----
+## 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)
@@ -84,12 +90,14 @@ Components/hero-banner.component.md
- 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
```
@@ -99,6 +107,7 @@ Components/hero-banner.component.md
### 3. Feature File (WHAT IT DOES)
**Contains:**
+
- ✅ User interactions & system responses
- ✅ Business rules & validation
- ✅ State management
@@ -109,27 +118,32 @@ Components/hero-banner.component.md
- ❌ **NO visual design** (no colors, no spacing, no states)
**Example:**
+
```markdown
-Features/hero-cta-logic.feature.md
----
+## 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
```
@@ -143,8 +157,10 @@ Features/hero-cta-logic.feature.md
**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`
@@ -153,8 +169,10 @@ Features/hero-cta-logic.feature.md
```
**Page File (About):**
+
```markdown
**Page-Specific Content:**
+
- Heading: "About Dog Week"
- Subheading: "Our mission to simplify dog care"
- Background Image: `/images/hero-about.jpg`
@@ -163,13 +181,16 @@ Features/hero-cta-logic.feature.md
```
**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)
@@ -177,11 +198,14 @@ Features/hero-cta-logic.feature.md
```
**Feature File:**
+
```markdown
**Generic Content:**
+
- Loading text: "Loading..."
**Interactions:**
+
- Click CTA → Navigate to link
```
@@ -192,30 +216,38 @@ Features/hero-cta-logic.feature.md
**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:
@@ -225,22 +257,27 @@ Features/hero-cta-logic.feature.md
- 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
@@ -253,55 +290,67 @@ Features/hero-cta-logic.feature.md
**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
@@ -315,6 +364,7 @@ Features/hero-cta-logic.feature.md
**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
@@ -326,8 +376,10 @@ Features/hero-cta-logic.feature.md
```
**Component File:**
+
```markdown
**Visual Specifications:**
+
- Background: Blue (#3B82F6)
- Text: White, 16px Medium
- Height: 48px
@@ -341,14 +393,17 @@ Features/hero-cta-logic.feature.md
```
**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
@@ -359,22 +414,22 @@ Features/hero-cta-logic.feature.md
## 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 |
+| 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 |
---
@@ -383,24 +438,29 @@ Features/hero-cta-logic.feature.md
### ❌ Mistake 1: Putting page-specific content in Feature file
**Wrong:**
+
```markdown
-Features/hero-logic.feature.md
----
+## 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
----
+## Pages/01-home-page.md
+
**Page-Specific Content:**
+
- Heading: "Welcome to Dog Week"
-Pages/02-about-page.md
----
+## Pages/02-about-page.md
+
**Page-Specific Content:**
+
- Heading: "About Dog Week"
```
@@ -409,19 +469,23 @@ Pages/02-about-page.md
### ❌ Mistake 2: Putting generic content in Page file
**Wrong:**
+
```markdown
-Pages/01-home-page.md
----
+## Pages/01-home-page.md
+
**Content:**
+
- Submit button: "Submit"
- Error message: "Invalid email"
```
**Right:**
+
```markdown
-Features/form-submit-logic.feature.md
----
+## Features/form-submit-logic.feature.md
+
**Generic Content:**
+
- Submit button: "Submit"
- Error message: "Invalid email"
```
@@ -431,20 +495,24 @@ Features/form-submit-logic.feature.md
### ❌ Mistake 3: Putting visual design in Feature file
**Wrong:**
+
```markdown
-Features/button-logic.feature.md
----
+## Features/button-logic.feature.md
+
**Visual:**
+
- Background: Blue
- Height: 48px
- Hover: Darker blue
```
**Right:**
+
```markdown
-Components/button-primary.component.md
----
+## Components/button-primary.component.md
+
**Visual Specifications:**
+
- Background: Blue (#3B82F6)
- Height: 48px
- States:
@@ -471,11 +539,13 @@ Is this visual design?
```
**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
diff --git a/src/modules/wds/workflows/4-ux-design/CROSS-PAGE-CONSISTENCY.md b/src/modules/wds/workflows/4-ux-design/CROSS-PAGE-CONSISTENCY.md
index 8e86aae2..de66c184 100644
--- a/src/modules/wds/workflows/4-ux-design/CROSS-PAGE-CONSISTENCY.md
+++ b/src/modules/wds/workflows/4-ux-design/CROSS-PAGE-CONSISTENCY.md
@@ -9,6 +9,7 @@
**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
@@ -25,7 +26,7 @@ This creates:
```
Start Page Analysis:
├─ Body Text: Thin lines, icon-sized spacing → 16px Regular
-├─ Button Labels: Medium lines → 16px Semibold
+├─ 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
@@ -40,12 +41,14 @@ Start Page Analysis:
**When analyzing the About Page sketch:**
#### Step 1: Check Previous Pages
+
```
-Agent: "I see you've already analyzed the Start Page.
+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 ✓
@@ -57,6 +60,7 @@ About Page body text:
```
#### Step 3: Confirm with Designer
+
```
Agent: "This body text looks identical to Start Page body text.
Should I use the same specification (16px Regular)?"
@@ -125,11 +129,13 @@ Components Identified:
### 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
diff --git a/src/modules/wds/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md b/src/modules/wds/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md
index 9af2dbbe..24c198f0 100644
--- a/src/modules/wds/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md
+++ b/src/modules/wds/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md
@@ -71,6 +71,7 @@ Currently sketch text analysis rules are duplicated across multiple files, makin
## Refactoring Plan
### Keep As-Is (Single Source of Truth)
+
✅ `SKETCH-TEXT-ANALYSIS-GUIDE.md` - Master guide with all rules
✅ `SKETCH-TEXT-QUICK-REFERENCE.md` - Quick reference
✅ `SKETCH-TEXT-STRATEGY.md` - Strategy guide
@@ -78,26 +79,31 @@ Currently sketch text analysis rules are duplicated across multiple files, makin
### Refactor (Remove Duplication, Add References)
**`TEXT-DETECTION-PRIORITY.md`:**
+
- Keep: Detection logic (pairs vs single)
- Remove: Detailed analysis rules (thickness → weight, spacing → size)
- Add: Reference to master guide
**`heading-text.md`:**
+
- Keep: Workflow steps
- Remove: Duplicate explanations of analysis rules
- Add: Reference to master guide
- Show: Example output only
**`object-router.md`:**
+
- Keep: Routing logic
- Remove: Any duplicate analysis
- Add: Reference to TEXT-DETECTION-PRIORITY.md
**`WDS-SPECIFICATION-PATTERN.md`:**
+
- Keep: Examples
- Add: Note "See SKETCH-TEXT-ANALYSIS-GUIDE.md for how these values were derived"
**`TRANSLATION-ORGANIZATION-GUIDE.md`:**
+
- Keep: Organization patterns
- Add: Reference to master guide for analysis
@@ -121,14 +127,16 @@ In instruction files, use this pattern:
Apply text marker analysis rules from SKETCH-TEXT-ANALYSIS-GUIDE.md:
+
- Count pairs → number of lines
- Measure thickness → font weight
- Measure spacing → font size estimate
- Check position → alignment
- Calculate length → character capacity
-
+
## Status
**To Do:**
+
- [ ] Refactor TEXT-DETECTION-PRIORITY.md
- [ ] Refactor heading-text.md
- [ ] Refactor object-router.md
@@ -150,4 +159,3 @@ For detailed analysis rules, see: SKETCH-TEXT-ANALYSIS-GUIDE.md
- [ ] Add references in TRANSLATION-ORGANIZATION-GUIDE.md
**Result:** Clean, maintainable documentation architecture! 🎯
-
diff --git a/src/modules/wds/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md b/src/modules/wds/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md
index 5a68459e..8d142074 100644
--- a/src/modules/wds/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md
+++ b/src/modules/wds/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md
@@ -7,18 +7,22 @@
## The Two-Layer System
### Layer 1: HTML Semantic Structure (h1-h6, p, etc.)
+
**Purpose:** SEO, accessibility, document outline, screen readers
**Rules:**
+
- **Each page must have exactly ONE h1** (main page title)
- **Heading hierarchy must be logical** (h1 → h2 → h3, no skipping)
- **Same across all pages** for semantic consistency
- **Not about visual appearance**
### Layer 2: Visual Text Styles (Design System)
+
**Purpose:** Visual hierarchy, branding, design consistency
**Rules:**
+
- **Named by visual purpose** (Display-Large, Headline-Primary, Body-Regular, etc.)
- **Can be applied to any HTML tag**
- **Different pages can use different visual styles** for the same HTML tag
@@ -29,24 +33,30 @@
## Why Separate?
### Problem: Mixing HTML and Visual Styles
+
```markdown
❌ BAD:
+
- **Style**: H1 heading
What does this mean?
+
- Is it an h1 tag?
- Is it a visual style that looks like an h1?
- What if another page needs h1 but different visual style?
```
### Solution: Specify Both Independently
+
```markdown
✅ GOOD:
+
- **HTML Tag**: h1 (semantic structure)
- **Visual Style**: Display-Large (from Design System)
```
**Now we know:**
+
- HTML: This is the main page heading (h1 for SEO)
- Visual: It uses the "Display-Large" design system style
- Another page could have: h1 + Headline-Medium (different visual, same semantic)
@@ -58,6 +68,7 @@ What does this mean?
### Example 1: Landing Page vs. Article Page
**Landing Page - Hero Headline:**
+
```markdown
- **HTML Tag**: h1
- **Visual Style**: Hero headline
@@ -65,6 +76,7 @@ What does this mean?
```
**Article Page - Article Title:**
+
```markdown
- **HTML Tag**: h1
- **Visual Style**: Main header
@@ -76,6 +88,7 @@ What does this mean?
### Example 2: Same Visual Style, Different Semantics
**Section Heading:**
+
```markdown
- **HTML Tag**: h2
- **Visual Style**: Sub header
@@ -83,6 +96,7 @@ What does this mean?
```
**Testimonial Quote:**
+
```markdown
- **HTML Tag**: p
- **Visual Style**: Sub header
@@ -120,6 +134,7 @@ What does this mean?
✅ **Button text** - Text within buttons
### Bad Visual Style Names
+
❌ **H1-Style** / **Heading-1** - Confuses with HTML tags
❌ **Text-Size-42** - Just a number, not semantic
❌ **Big-Text** - Too vague
@@ -137,10 +152,12 @@ What does this mean?
**OBJECT ID**: `start-hero-headline`
**HTML Structure:**
+
- **Tag**: h1
- **Purpose**: Main page heading (SEO/accessibility)
**Visual Style:**
+
- **Style Name**: Hero headline
- **Font weight**: Bold (from 3px thick line markers in sketch)
- **Font size**: 56px (est. from 32px spacing between line pairs)
@@ -153,6 +170,7 @@ What does this mean?
**Behavior**: Updates with language toggle
**Content**:
+
- EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång."
```
@@ -173,6 +191,7 @@ What does this mean?
## Common Patterns
### Pattern 1: Landing Page
+
```
h1 → Hero headline (big hero text, 56px)
h2 → Sub header (section headings, 32px)
@@ -181,6 +200,7 @@ p → Body text (regular paragraphs, 16px)
```
### Pattern 2: Blog Post
+
```
h1 → Main header (article title, 36px)
h2 → Sub header (section headings, 28px)
@@ -189,6 +209,7 @@ p → Body text large (article body, 18px)
```
### Pattern 3: Dashboard
+
```
h1 → Main header (page title, 28px)
h2 → Card header (widget titles, 20px)
@@ -220,4 +241,3 @@ The CSS class references the **visual style name** (hero-headline, main-header),
---
**Remember:** HTML tags = Document structure. Visual styles = Appearance. Keep them separate! 🎯
-
diff --git a/src/modules/wds/workflows/4-ux-design/IMAGE-SKETCHING-BEST-PRACTICES.md b/src/modules/wds/workflows/4-ux-design/IMAGE-SKETCHING-BEST-PRACTICES.md
index 3220c3bc..00e74039 100644
--- a/src/modules/wds/workflows/4-ux-design/IMAGE-SKETCHING-BEST-PRACTICES.md
+++ b/src/modules/wds/workflows/4-ux-design/IMAGE-SKETCHING-BEST-PRACTICES.md
@@ -9,6 +9,7 @@
### Why Sketch Real Content?
When you sketch what the image should actually show (rather than just "X" or "image here"), you:
+
- **Provide visual direction** - Designer/developer understands image purpose
- **Enable AI interpretation** - Agent can suggest appropriate image content
- **Guide art direction** - Photographer/illustrator knows what's needed
@@ -22,6 +23,7 @@ When you sketch what the image should actually show (rather than just "X" or "im
### 1. Portrait/Profile Photos
**Sketch a simple face:**
+
```
┌──────────────┐
│ ◠ ◠ │ ← Simple eyes
@@ -45,6 +47,7 @@ or
### 2. Hero Images / Backgrounds
**Sketch landscape/scenery:**
+
```
┌──────────────────────────┐
│ │
@@ -55,6 +58,7 @@ or
```
**Sketch clouds/sky:**
+
```
┌──────────────────────────┐
│ ~ ~ ~ │
@@ -65,6 +69,7 @@ or
```
**Sketch abstract shapes:**
+
```
┌──────────────────────────┐
│ ∿∿∿ ≈≈≈ │
@@ -78,6 +83,7 @@ or
### 3. Product Images
**Sketch the product outline:**
+
```
┌──────────────┐
│ |‾‾‾‾| │ ← Phone outline
@@ -101,6 +107,7 @@ or
### 4. Icons / Illustrations
**Sketch simple icon shapes:**
+
```
┌──────┐
│ ⚙ │ ← Settings gear
@@ -124,6 +131,7 @@ or
### 5. Abstract/Decorative Images
**Use soft, flowing shapes:**
+
```
┌──────────────────────────┐
│ ∞ │
@@ -134,6 +142,7 @@ or
```
**Use geometric patterns:**
+
```
┌──────────────────────────┐
│ ◆ ○ ▢ │
@@ -157,6 +166,7 @@ or
```
**Problems with X markers:**
+
- ❌ **No context** - Doesn't communicate what image shows
- ❌ **No direction** - No guidance for content selection
- ❌ **Intrusive** - Visually distracting in sketch
@@ -181,6 +191,7 @@ When analyzing sketches, the AI should:
### Example Detection
**Sketch shows:**
+
```
┌──────────────────────────┐
│ /\ /\ /\ │
@@ -190,6 +201,7 @@ When analyzing sketches, the AI should:
```
**AI interprets:**
+
- Rectangle container detected
- Mountain/landscape sketch inside
- **Purpose:** Hero background image showing outdoor/nature scene
@@ -201,24 +213,28 @@ When analyzing sketches, the AI should:
## Benefits of Sketching Real Content
### For Designers
+
- ✅ Communicate visual intent clearly
- ✅ Test composition and layout
- ✅ Provide art direction
- ✅ Inspire creative solutions
### For AI Agents
+
- ✅ Understand image purpose from context
- ✅ Suggest appropriate image sources
- ✅ Recommend image dimensions and aspect ratios
- ✅ Generate meaningful alt text
### For Developers
+
- ✅ Understand what image represents
- ✅ Know how to style and position image
- ✅ Select appropriate placeholder images
- ✅ Write meaningful alt text for accessibility
### For Stakeholders
+
- ✅ Visualize final design better
- ✅ Provide meaningful feedback
- ✅ Understand design intent
@@ -228,28 +244,29 @@ When analyzing sketches, the AI should:
## Quick Reference
-| Image Type | Sketch Technique | Example |
-|------------|------------------|---------|
-| **Portrait/Face** | Simple face with eyes and smile | ◠ ◠ ᵕ |
-| **Landscape** | Mountains, trees, horizon | /\\ /\\ /\\ |
-| **Sky/Clouds** | Wavy cloud shapes | ~ ~ ~ |
-| **Product** | Product outline/silhouette | Phone, laptop shape |
-| **Icon** | Simple icon shape | ⚙ ♥ ✓ |
-| **Abstract** | Flowing, organic shapes | ∿ ≋ ∞ |
-| **Geometric** | Shapes and patterns | ◆ ○ ▢ |
+| Image Type | Sketch Technique | Example |
+| ----------------- | ------------------------------- | ------------------- |
+| **Portrait/Face** | Simple face with eyes and smile | ◠ ◠ ᵕ |
+| **Landscape** | Mountains, trees, horizon | /\\ /\\ /\\ |
+| **Sky/Clouds** | Wavy cloud shapes | ~ ~ ~ |
+| **Product** | Product outline/silhouette | Phone, laptop shape |
+| **Icon** | Simple icon shape | ⚙ ♥ ✓ |
+| **Abstract** | Flowing, organic shapes | ∿ ≋ ∞ |
+| **Geometric** | Shapes and patterns | ◆ ○ ▢ |
---
## Summary
**WDS Image Sketching Philosophy:**
+
> "Sketch what you see, not just where it goes."
**Guidelines:**
+
- ✅ **Draw the actual content** - Faces, landscapes, products
- ✅ **Use soft, organic shapes** - Clouds, waves for abstract images
- ✅ **Keep it simple** - Quick sketches are fine, detail level matches sketch fidelity
- ❌ **Avoid generic X markers** - Provides no useful context
**Result:** Better communication, clearer intent, more useful AI analysis! 🎨✨
-
diff --git a/src/modules/wds/workflows/4-ux-design/PROACTIVE-TRANSLATION-WORKFLOW.md b/src/modules/wds/workflows/4-ux-design/PROACTIVE-TRANSLATION-WORKFLOW.md
index 01089a0b..a5208503 100644
--- a/src/modules/wds/workflows/4-ux-design/PROACTIVE-TRANSLATION-WORKFLOW.md
+++ b/src/modules/wds/workflows/4-ux-design/PROACTIVE-TRANSLATION-WORKFLOW.md
@@ -7,6 +7,7 @@
## The Principle
**Agent is proactive, not passive**
+
- Don't just ask for translations
- **Suggest them!**
- Let user accept, refine, or override
@@ -18,11 +19,13 @@
### Example 1: Sketch Has Actual Text
**Sketch shows:**
+
```
Every walk. on time. Every time.
```
**Agent says:**
+
```
I found text in your sketch: "Every walk. on time. Every time."
@@ -46,12 +49,15 @@ Choice [1/2/3]:
**User response options:**
**Option A: Accept (Fast!)**
+
```
1
```
+
→ Done! All translations accepted.
**Option B: Adjust specific**
+
```
2
@@ -63,9 +69,11 @@ NO: Hver tur. i tide. Hver gang. ← Keep
SE: Varje promenad. Punktligt. Varje gång.
```
+
→ Done! One adjusted, others kept.
**Option C: Manual**
+
```
3
@@ -73,6 +81,7 @@ EN:
SE:
NO:
```
+
→ User provides all manually.
---
@@ -80,6 +89,7 @@ NO:
### Example 2: No Sketch Text (Markers Only)
**Sketch shows:**
+
```
───────────────────────────────── ← Line markers
───────────────────────────────── ← (no actual text)
@@ -87,6 +97,7 @@ NO:
```
**Agent says:**
+
```
Text placeholder detected:
- 3 horizontal lines
@@ -101,11 +112,13 @@ EN:
```
**User provides:**
+
```
EN: Organize your family around dog care. Assign walks and never miss one again.
```
**Agent immediately suggests:**
+
```
Great! Here are translation suggestions:
@@ -128,22 +141,26 @@ Choice [1/2/3]:
## Benefits
### ✅ Speed
+
- User accepts = instant completion
- No typing all translations manually
- Saves significant time
### ✅ Accuracy
+
- Agent uses context for better translations
- Considers character capacity
- Maintains tone and style
### ✅ Flexibility
+
- Can accept all suggestions
- Can adjust specific ones
- Can override completely
- Full user control
### ✅ Consistency
+
- Translations match style
- Terminology stays consistent
- Professional quality
@@ -160,15 +177,15 @@ Choice [1/2/3]:
Extract text: "Every walk. on time."Translate to all product_languages
-
+
@@ -176,13 +193,13 @@ Choice [1/2/3]:
Provide content in {{primary_language}}:After receiving, translate to remaining languages
-
+
@@ -191,6 +208,7 @@ Choice [1/2/3]:
### Translation Quality
**Agent considers:**
+
- Character capacity from sketch
- Tone and style of original
- Context from page purpose
@@ -204,11 +222,13 @@ Choice [1/2/3]:
### Example: Hero Headline
**Sketch:**
+
```
Every walk. on time. Every time.
```
**Agent:**
+
```
Suggested content for Primary Headline:
@@ -219,6 +239,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
```
**User:**
+
```
1
```
@@ -228,11 +249,13 @@ Do these work? [1] Use [2] Adjust [3] Manual
### Example: Button Label
**Sketch:**
+
```
[Get Started - Free Forever]
```
**Agent:**
+
```
Suggested content for Primary CTA:
@@ -243,6 +266,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
```
**User:**
+
```
2
@@ -254,11 +278,13 @@ SE: börja planera - gratis för alltid ← lowercase, different verb
### Example: Form Label
**Sketch:**
+
```
Email Address:
```
**Agent:**
+
```
Suggested content for Email Label:
@@ -269,6 +295,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
```
**User:**
+
```
1
```
@@ -280,6 +307,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
## Multi-Language Example (3+ Languages)
**Project Config:**
+
```yaml
product_languages:
- EN
@@ -289,11 +317,13 @@ product_languages:
```
**Sketch:**
+
```
Welcome Home
```
**Agent:**
+
```
I found text in your sketch: "Welcome Home"
@@ -308,6 +338,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
```
**User:**
+
```
1
```
@@ -321,6 +352,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
### Translation Confidence
**High confidence:**
+
```
✅ These translations look good!
@@ -328,6 +360,7 @@ Do they work? [1] Use [2] Adjust [3] Manual
```
**Low confidence:**
+
```
⚠️ I'm less confident about these translations. Please review carefully!
@@ -341,6 +374,7 @@ Do they work? [1] Use [2] Adjust [3] Manual
### Character Capacity Warning
**If translation exceeds capacity:**
+
```
⚠️ Translation length warning:
@@ -359,6 +393,7 @@ Use shorter version? (y/n)
## User Experience
### Before (Passive):
+
```
EN: ← User types
SE: ← User types
@@ -368,6 +403,7 @@ Slow, tedious, error-prone
```
### After (Proactive):
+
```
Suggested translations:
EN: Every walk. on time.
@@ -386,6 +422,7 @@ Fast, accurate, professional
### Agent Behavior
**Always suggest translations:**
+
1. Read sketch text (if present)
2. Generate suggestions for ALL languages
3. Present with options: Accept / Adjust / Manual
@@ -393,6 +430,7 @@ Fast, accurate, professional
5. Warn if low confidence
**Never:**
+
- Present blank fields for translations
- Make user type everything
- Provide only one language at a time
@@ -407,6 +445,3 @@ Fast, accurate, professional
---
**Proactive translation = better UX, faster workflow, higher quality!** 🌍⚡✨
-
-
-
diff --git a/src/modules/wds/workflows/4-ux-design/README.md b/src/modules/wds/workflows/4-ux-design/README.md
index 6098434c..c81c1700 100644
--- a/src/modules/wds/workflows/4-ux-design/README.md
+++ b/src/modules/wds/workflows/4-ux-design/README.md
@@ -12,31 +12,36 @@ Phase 4 transforms sketches and ideas into detailed, developer-ready page specif
## Workflow Steps
-| Step | File | Purpose |
-|------|------|---------|
-| **Init** | `step-01-init.md` | Welcome, load context, initialize session |
-| **Define Scenario** | `step-02-define-scenario.md` | Plan user journey and pages |
-| **Design Page** | `step-03-design-page.md` | Orchestrate 4A-4E substeps per page |
-| **Complete Scenario** | `step-04-complete-scenario.md` | Finalize and summarize scenario |
-| **Next Steps** | `step-05-next-steps.md` | Continue or exit workflow |
+| Step | File | Purpose |
+| --------------------- | ------------------------------ | ----------------------------------------- |
+| **Init** | `step-01-init.md` | Welcome, load context, initialize session |
+| **Define Scenario** | `step-02-define-scenario.md` | Plan user journey and pages |
+| **Design Page** | `step-03-design-page.md` | Orchestrate 4A-4E substeps per page |
+| **Complete Scenario** | `step-04-complete-scenario.md` | Finalize and summarize scenario |
+| **Next Steps** | `step-05-next-steps.md` | Continue or exit workflow |
---
## Substeps (4A-4E)
### 4A: Exploration
+
**File:** `substeps/4a-exploration.md`
+
- Think through user journey
- Clarify context and goals
### 4B: Sketch Analysis
+
**File:** `substeps/4b-sketch-analysis.md`
+
- **Section-first approach:** AI reads entire sketch, identifies all sections
- User confirms structure
- Section-by-section AI interpretation
- User refinement dialog
### 4C: Specification (Micro-steps 01-08)
+
**Files:** `substeps/4c-01-page-basics.md` through `4c-08-generate-spec.md`
1. **Page Basics** - Name, purpose, route
@@ -49,12 +54,16 @@ Phase 4 transforms sketches and ideas into detailed, developer-ready page specif
8. **Generate Spec** - Complete page specification
### 4D: Prototype
+
**File:** `substeps/4d-prototype.md`
+
- Generate interactive HTML prototype
- Uses Design System if enabled
### 4E: PRD Update
+
**File:** `substeps/4e-prd-update.md`
+
- Extract functional requirements
- Update Product Requirements Document
@@ -66,16 +75,17 @@ Phase 4 transforms sketches and ideas into detailed, developer-ready page specif
Each object type has a dedicated instruction file:
-| File | Purpose |
-|------|---------|
-| `object-router.md` | Detects object types, routes to appropriate file |
-| `button.md` | Button specification |
-| `text-input.md` | Input field specification |
-| `link.md` | Link/anchor specification |
-| `heading-text.md` | Text element specification with purpose-based naming |
-| `image.md` | Image specification |
+| File | Purpose |
+| ------------------ | ---------------------------------------------------- |
+| `object-router.md` | Detects object types, routes to appropriate file |
+| `button.md` | Button specification |
+| `text-input.md` | Input field specification |
+| `link.md` | Link/anchor specification |
+| `heading-text.md` | Text element specification with purpose-based naming |
+| `image.md` | Image specification |
**Key Features:**
+
- Purpose-based naming (function over content)
- Grouped translations (coherent language blocks)
- Design System integration (use existing, create new, or page-specific)
@@ -87,31 +97,32 @@ Each object type has a dedicated instruction file:
**Location:** `templates/`
-| File | Purpose |
-|------|---------|
+| File | Purpose |
+| -------------------------------- | -------------------------------- |
| `page-specification.template.md` | Complete page spec output format |
-| `scenario-overview.template.md` | Scenario summary format |
+| `scenario-overview.template.md` | Scenario summary format |
---
## Documentation
-| File | Purpose |
-|------|---------|
-| `ARCHITECTURE.md` | Complete workflow architecture overview |
-| `WDS-SPECIFICATION-PATTERN.md` | **Standard specification format** (Dog Week as example) |
+| File | Purpose |
+| ----------------------------------- | -------------------------------------------------------- |
+| `ARCHITECTURE.md` | Complete workflow architecture overview |
+| `WDS-SPECIFICATION-PATTERN.md` | **Standard specification format** (Dog Week as example) |
| `TRANSLATION-ORGANIZATION-GUIDE.md` | Purpose-based text organization and grouped translations |
-| `SKETCH-TEXT-ANALYSIS-GUIDE.md` | How to interpret text markers in sketches |
-| `SKETCH-TEXT-QUICK-REFERENCE.md` | Quick reference for text analysis |
-| `SKETCH-TEXT-STRATEGY.md` | When to use actual text vs. line markers |
-| `PROACTIVE-TRANSLATION-WORKFLOW.md` | How agent suggests translations |
-| `ROUTER-FLOW-DIAGRAM.md` | Visual flow of object routing with examples |
+| `SKETCH-TEXT-ANALYSIS-GUIDE.md` | How to interpret text markers in sketches |
+| `SKETCH-TEXT-QUICK-REFERENCE.md` | Quick reference for text analysis |
+| `SKETCH-TEXT-STRATEGY.md` | When to use actual text vs. line markers |
+| `PROACTIVE-TRANSLATION-WORKFLOW.md` | How agent suggests translations |
+| `ROUTER-FLOW-DIAGRAM.md` | Visual flow of object routing with examples |
---
## Key Patterns
### 1. Section-First Workflow
+
- AI reads entire sketch → identifies sections
- User confirms structure
- Section-by-section interpretation
@@ -119,25 +130,32 @@ Each object type has a dedicated instruction file:
- Batch generation of specs
### 2. Purpose-Based Naming
+
- Name text by **function**, not content
- `hero-headline` not `welcome-message`
- `form-error` not `invalid-email-text`
### 3. Grouped Translations
+
```markdown
#### Primary Headline
+
**Content**:
+
- EN: "Welcome to Dog Week"
- SE: "Välkommen till Hundveckan"
```
### 4. Design System Integration
+
For each object:
+
1. Use existing component
2. Create new component (mark for Phase 5)
3. Page-specific only
### 5. Text Marker Analysis
+
- **2 lines together** = 1 line of text
- **Line thickness** = font weight (thick = bold)
- **Spacing between pairs** = font size
@@ -148,6 +166,7 @@ For each object:
## Multi-Language Support
**Configuration:** Set in `workflow-init`
+
- **Specification Language**: Language for writing specs (EN, SE, etc.)
- **Product Languages**: Languages the product supports (array)
@@ -188,6 +207,7 @@ docs/
```
Each page spec includes:
+
- Page metadata and purpose
- All sections with objects
- Complete multi-language content
@@ -198,4 +218,3 @@ Each page spec includes:
---
**Phase 4 Status:** ✅ **COMPLETE** (December 6, 2025)
-
diff --git a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md
index fea5c7c4..b613beaf 100644
--- a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md
+++ b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md
@@ -7,27 +7,32 @@
## Best Practice: When to Use Text vs. Markers
### Use ACTUAL TEXT for:
+
- **Headlines** - Provides content guidance and context
- **Button labels** - Shows intended action clearly
- **Navigation items** - Clarifies structure
- **Short, important text** - Where specific wording matters
**Example:**
+
```
Every walk. on time. Every time. ← Actual text (readable)
```
**Benefits:**
+
- Agent can read and suggest this as starting content
- Provides context for design decisions
- Can still be changed during specification
### Use HORIZONTAL LINE MARKERS for:
+
- **Body paragraphs** - Content TBD, just need length indication
- **Long descriptions** - Where specific wording isn't decided yet
- **Placeholder content** - General sizing guidance
**Example:**
+
```
───────────────────────────────────────── ← Line markers
───────────────────────────────────────── ← Show length/size
@@ -36,6 +41,7 @@ Every walk. on time. Every time. ← Actual text (readable)
```
**Benefits:**
+
- Shows font size and capacity without committing to content
- Faster for sketching body text
- Focuses on layout, not copywriting
@@ -73,12 +79,12 @@ Justified/Full-width text:
**Each PAIR of horizontal lines = ONE line of text**
-| Number of Pairs | Text Lines | Typical Use |
-|-----------------|------------|-------------|
-| 1 pair | 1 line | Headlines, labels, buttons |
-| 2 pairs | 2 lines | Short headlines, subheadings |
-| 3-4 pairs | 3-4 lines | Intro paragraphs, descriptions |
-| 5+ pairs | 5+ lines | Body copy, long descriptions |
+| Number of Pairs | Text Lines | Typical Use |
+| --------------- | ---------- | ------------------------------ |
+| 1 pair | 1 line | Headlines, labels, buttons |
+| 2 pairs | 2 lines | Short headlines, subheadings |
+| 3-4 pairs | 3-4 lines | Intro paragraphs, descriptions |
+| 5+ pairs | 5+ lines | Body copy, long descriptions |
---
@@ -91,6 +97,7 @@ Justified/Full-width text:
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
@@ -103,11 +110,13 @@ Current Page (About Page):
```
**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
@@ -129,13 +138,13 @@ Current Page (About Page):
**Compare lines RELATIVE to each other within the sketch:**
-| 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 |
+| 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 |
**Don't measure pixels—compare thickness relative to other text in the same sketch.**
@@ -143,19 +152,20 @@ Current Page (About Page):
**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 |
+| 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
← ~Button Height
@@ -165,11 +175,12 @@ This is clearly TEXT (H1 heading)
```
**IMAGE - Large spacing (confusion risk):**
+
```
═══════════════════════════════ ← Line?
-
+
← Much larger than any UI element!
-
+
═══════════════════════════════ ← Line?
This might be an IMAGE PLACEHOLDER or COLORED BOX, not text!
@@ -182,16 +193,17 @@ Ask user to confirm.
**The position of line pairs within the section indicates text alignment**
-| Alignment | Visual Indicator | Typical Use |
-|-----------|------------------|-------------|
-| **Left-aligned** | Lines start at left edge of container | Body text, lists, labels |
-| **Center-aligned** | Lines centered, equal spacing both sides | Headlines, hero text, CTAs |
-| **Right-aligned** | Lines end at right edge of container | Captions, metadata, prices, dates |
-| **Justified** | Lines extend full width of container | Dense body text, formal content |
+| Alignment | Visual Indicator | Typical Use |
+| ------------------ | ---------------------------------------- | --------------------------------- |
+| **Left-aligned** | Lines start at left edge of container | Body text, lists, labels |
+| **Center-aligned** | Lines centered, equal spacing both sides | Headlines, hero text, CTAs |
+| **Right-aligned** | Lines end at right edge of container | Captions, metadata, prices, dates |
+| **Justified** | Lines extend full width of container | Dense body text, formal content |
#### Visual Examples
**Left-Aligned Text:**
+
```
Container: | |
@@ -201,6 +213,7 @@ Container: | |
```
**Center-Aligned Text:**
+
```
Container: | |
@@ -209,6 +222,7 @@ Container: | |
```
**Right-Aligned Text:**
+
```
Container: | |
@@ -217,6 +231,7 @@ Container: | |
```
**Justified/Full-Width Text:**
+
```
Container: | |
@@ -228,12 +243,12 @@ Container: | |
### 4. Number of Lines → Content Length
-| Lines in Sketch | Content Type | Character Estimate |
-|-----------------|--------------|-------------------|
-| 1-2 lines | Heading/Title | 20-60 characters total |
-| 3-5 lines | Short paragraph | 150-350 characters |
-| 6-10 lines | Full paragraph | 400-700 characters |
-| 10+ lines | Long content | 700+ characters |
+| Lines in Sketch | Content Type | Character Estimate |
+| --------------- | --------------- | ---------------------- |
+| 1-2 lines | Heading/Title | 20-60 characters total |
+| 3-5 lines | Short paragraph | 150-350 characters |
+| 6-10 lines | Full paragraph | 400-700 characters |
+| 10+ lines | Long content | 700+ characters |
### 4. Line-Height Calculation
@@ -249,6 +264,7 @@ Line-height: 28 / 24 = 1.16 ≈ 1.2
```
**Typical ratios:**
+
- **1.1-1.2** = Tight (headings)
- **1.4-1.5** = Normal (body text)
- **1.6-1.8** = Loose (airy text)
@@ -279,12 +295,14 @@ Caption (~12px): ──────────────────
### Example 1: Landing Page Hero
**Sketch shows:**
+
```
═══════════════════════════════ ← Line 1 (thick, center)
═══════════════════════════ ← Line 2 (thick, center)
```
**Analysis:**
+
- **Type:** Large Heading (Page Title)
- **Lines:** 2
- **Line thickness:** Thickest in sketch → **Bold** (font-weight: 700)
@@ -295,6 +313,7 @@ Caption (~12px): ──────────────────
- **Semantic HTML:** Determined by page structure (likely H1 if page title)
**Content Guidance:**
+
```
English: "Welcome to Your / Dog Care Hub" (48 chars) ✅
Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅
@@ -303,6 +322,7 @@ Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅
### Example 2: Feature Description
**Sketch shows:**
+
```
───────────────────────────────────────── ← Line 1
───────────────────────────────────────── ← Line 2
@@ -311,6 +331,7 @@ Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅
```
**Analysis:**
+
- **Type:** Body text / Paragraph
- **Lines:** 4
- **Line thickness:** Thinnest in sketch → **Regular** (font-weight: 400)
@@ -320,26 +341,29 @@ Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅
- **Capacity:** ~60-70 chars per line = 240-280 total
**Content Guidance:**
+
```
-English: "Organize your family around dog care. Assign walks, track
-feeding schedules, and never miss a walk again. Perfect for busy
-families who want to ensure their dogs get the care they need."
+English: "Organize your family around dog care. Assign walks, track
+feeding schedules, and never miss a walk again. Perfect for busy
+families who want to ensure their dogs get the care they need."
(206 chars) ✅
-Swedish: "Organisera din familj kring hundvård. Tilldela promenader,
-spåra matscheman och missa aldrig en promenad igen. Perfekt för
-upptagna familjer som vill säkerställa att deras hundar får den
+Swedish: "Organisera din familj kring hundvård. Tilldela promenader,
+spåra matscheman och missa aldrig en promenad igen. Perfekt för
+upptagna familjer som vill säkerställa att deras hundar får den
vård de behöver." (218 chars) ✅
```
### Example 3: Button Text
**Sketch shows:**
+
```
[────────────] ← Single line inside button shape
```
**Analysis:**
+
- **Type:** Button label
- **Lines:** 1
- **Line thickness:** Medium (relative) → **Semibold** (font-weight: 600)
@@ -347,6 +371,7 @@ vård de behöver." (218 chars) ✅
- **Capacity:** ~8-12 characters
**Content Guidance:**
+
```
English: "Get Started" (11 chars) ✅
Swedish: "Kom Igång" (9 chars) ✅
@@ -359,11 +384,13 @@ Swedish: "Kom Igång" (9 chars) ✅
When analyzing sketches with text placeholders:
### Step 1: Count the Lines
+
```
How many horizontal bar groups do you see?
```
### Step 2: Compare Line Thickness → Font Weight
+
```
Line thickness indicates font weight (RELATIVE comparison):
- Thickest lines → Bold (font-weight: 700)
@@ -374,6 +401,7 @@ Line thickness indicates font weight (RELATIVE comparison):
```
### Step 3: Compare Distance to UI Elements → Font Size
+
```
Vertical spacing relative to context anchors:
- Matches Button Height → ~40-48px font (Large Heading)
@@ -389,16 +417,18 @@ Semantic heading levels are determined by content structure, not appearance.
```
### Step 4: Calculate Line-Height
+
```
Line-height = Distance between lines / Font size
Example:
- Distance: 28px
-- Font size: 24px
+- Font size: 24px
- Line-height: 28 / 24 = 1.16 ≈ 1.2
```
### Step 5: Calculate Capacity
+
```
Lines × Characters-per-line = Total capacity
@@ -407,6 +437,7 @@ Example:
```
### Step 6: Generate Content Guidance
+
```
"Content should be: [type], [line count] lines, ~[total chars] characters"
@@ -415,6 +446,7 @@ Example:
```
### Step 7: Validate Content
+
```
If user provides content:
- Count actual characters
@@ -431,21 +463,25 @@ Consider shortening or increasing font size.
## Benefits of This Approach
✅ **Accurate Content Generation**
+
- Content matches design space
- No overflow or underflow issues
- Professional fit and finish
✅ **Design Fidelity**
+
- Specifications match sketches
- Developers can trust the specs
- Reduces back-and-forth
✅ **Multilingual Support**
+
- Can estimate if translation fits
- Adjust content length per language
- Prevents UI breaking
✅ **Quality Assurance**
+
- Catches content length issues early
- Ensures consistency
- Professional output
@@ -461,6 +497,7 @@ Consider shortening or increasing font size.
> "Looking at the profile section heading, I see 2 thick horizontal lines, center-aligned at the top.
>
> **Analysis:**
+>
> - 2 lines of text (thick bars)
> - Line thickness: Thick (relative) → Bold weight
> - Spacing: Less than button height → ~28-32px font
@@ -471,6 +508,7 @@ Consider shortening or increasing font size.
> **This heading should be:** Brief, 2 short lines, ~50-60 characters total
>
> **Suggested content:**
+>
> - EN: "Complete Your / Profile Setup" (41 chars) ✅
> - SV: "Slutför Din / Profilinställning" (45 chars) ✅
>
@@ -481,6 +519,7 @@ Consider shortening or increasing font size.
## Integration with WDS Workflow
This analysis happens automatically in:
+
- **4B: Sketch Analysis** - Initial detection
- **object-types/heading-text.md** - Detailed analysis
- **4C-04: Content & Languages** - Content validation
@@ -490,5 +529,4 @@ This analysis happens automatically in:
---
-*This guide ensures all WDS projects generate content that perfectly fits the designed space.*
-
+_This guide ensures all WDS projects generate content that perfectly fits the designed space._
diff --git a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md
index 0ef4dacf..18aaaaf3 100644
--- a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md
+++ b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md
@@ -16,16 +16,19 @@
### 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)
@@ -59,6 +62,7 @@
```
**Context Anchors:**
+
- **Browser Address Bar**: ~40px height
- **Standard Button**: ~40-48px height
- **Cursor/Icon**: ~16-24px size
@@ -75,6 +79,7 @@
### Example: Hero Headline
**Sketch:**
+
```
═══════════════════════════════ ← Line 1: Thickest lines in sketch
↕ Spacing ≈ Same as button height
@@ -82,6 +87,7 @@
```
**Analysis:**
+
- **Context:** Spacing looks similar to the "Sign In" button height nearby.
- **Inference:** If button is ~48px, this font is ~48px (Large Heading).
- **Weight:** Thicker than body text markers → **Bold**.
@@ -92,29 +98,35 @@
## Common Patterns
### Large Heading (Page Title)
+
```
═══════════════════ ← Thickest lines
↕
═══════════════════
```
+
- **Clue:** Spacing matches Address Bar height (~40px)
- **Est:** ~40-48px, Bold
### Medium Heading (Section Title)
+
```
═══════════════════ ← Medium-Thick lines
↕
═══════════════════
```
+
- **Clue:** Spacing is slightly less than button height
- **Est:** ~32px, Semibold
### Body Text (Paragraph)
+
```
───────────────────── ← Thinnest lines
↕
─────────────────────
```
+
- **Clue:** Spacing matches scrollbar width or small icon (~16-24px)
- **Est:** ~16px, Regular
@@ -123,23 +135,27 @@
## ⚠️ Confusion Warning
### Text (Normal)
+
```
═══════════════════
↕ Spacing < 2x Button Height
═══════════════════
```
+
✅ Likely TEXT
### Image/Box (Too Large)
+
```
═══════════════════
-
-
+
+
↕ Spacing > 2x Button Height
-
-
+
+
═══════════════════
```
+
❓ Likely IMAGE or CONTAINER
**Rule:** If spacing seems disproportionately large compared to UI elements, verify!
@@ -172,6 +188,7 @@ See horizontal lines?
**CONTEXT = SCALE**
Think of it like looking at a map:
+
- Use the scale key (buttons, bars) to measure distances.
- Don't guess miles (pixels) without a reference!
@@ -186,11 +203,13 @@ Think of it like looking at a map:
```
**Analysis:**
+
- Thickness: Bold (relative to body lines)
- Distance: Matches button (~48px)
- Result: `font: bold 48px / 1.2`
**Content:**
+
```
EN: "Every walk. on time. Every time."
SE: "Varje promenad. i tid. Varje gång."
@@ -201,6 +220,3 @@ Both fit in ~50-60 character capacity! ✅
---
**Remember: Context is King! Compare, don't just measure.** 📏✨
-
-
-
diff --git a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-STRATEGY.md b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-STRATEGY.md
index 0488e294..ff88cc6c 100644
--- a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-STRATEGY.md
+++ b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-STRATEGY.md
@@ -22,6 +22,7 @@
```
**When to use:**
+
- Headlines (H1, H2, H3)
- Button labels
- Navigation items
@@ -51,6 +52,7 @@
```
**When to use:**
+
- Body paragraphs
- Long descriptions
- Feature lists (when wording TBD)
@@ -85,6 +87,7 @@
```
**Result:**
+
- Headlines provide content guidance
- Body text shows sizing and capacity
- Buttons show clear actions
@@ -129,6 +132,7 @@
### Agent Analysis
**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, spacing matches icon size (~16-20px), ~120-140 chars
@@ -137,6 +141,7 @@
6. **Marker analysis:** 3 thin lines → feature description, spacing matches icon size (~16-20px), ~180-210 chars
**Agent output:**
+
```
I found text in your sketch: "Every walk. on time. Every time."
@@ -147,6 +152,7 @@ SE: [Your Swedish translation]
```
**User can:**
+
- ✅ Keep the sketch text
- ✅ Change it completely
- ✅ Refine it slightly
@@ -188,6 +194,7 @@ SE: [Your Swedish translation]
```
**Analysis:**
+
- Thickness: Bold (relative to other text)
- Distance: Matches button height (~40-48px)
- Lines: 2
@@ -200,18 +207,20 @@ SE: [Your Swedish translation]
### When Sketch Has Actual Text
**Agent says:**
+
```
I found text in your sketch: "Every walk. on time."
Content for Primary Headline:
EN: Every walk. on time.
-SE:
+SE:
(You can keep the sketch text or change it)
```
**Benefits:**
+
- Pre-filled starting point
- Still editable
- Saves time
@@ -220,6 +229,7 @@ SE:
### When Sketch Has Line Markers
**Agent says:**
+
```
Text placeholder detected:
- 4 horizontal lines
@@ -235,11 +245,13 @@ EN:
```
**User provides:**
+
```
EN: Organize your family around dog care. Assign walks, track feeding schedules, and never miss a walk again.
```
**Agent suggests:**
+
```
Great! Here are translation suggestions:
@@ -249,6 +261,7 @@ Does this work, or would you like to adjust it?
```
**Benefits:**
+
- Clear capacity guidance
- Agent suggests translations
- User reviews and confirms
@@ -261,7 +274,9 @@ Does this work, or would you like to adjust it?
When AI analyzes sketch text markers, the workflow is:
### Step 1: AI Analyzes Sketch
+
Agent detects text markers and estimates properties:
+
```
Line thickness: Thicker than body text → Bold font weight
Spacing between pairs: Similar to button height → ~40-48px font size estimate
@@ -270,30 +285,37 @@ Character capacity: ~35 characters per line
```
### Step 2: AI Presents Estimates with Reasoning
+
Agent shows analysis WITH explanation of how estimates were derived:
+
```markdown
-- **Style**:
+- **Style**:
- Font weight: Bold (from thick line markers, relative to body text)
- Font size: 42px (est. from spacing matching button height)
- Line-height: 1.2 (est. calculated as font-size × 1.2)
```
**Why show reasoning?**
+
- Designer understands **how** AI interpreted the sketch
- Designer can judge if estimation logic makes sense
- Makes it easy to adjust if sketch measurements were different
- Builds trust through transparency
### Step 3: Designer Confirms/Adjusts
+
Designer reviews estimates and either:
+
1. **Confirms** - "Yes, 42px based on button-height spacing is correct"
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
+
Agent updates spec with confirmed values, removes estimation notes:
+
```markdown
-- **Style**:
+- **Style**:
- Font weight: Bold
- Font size: 48px
- Line-height: 1.15
@@ -301,7 +323,8 @@ Agent updates spec with confirmed values, removes estimation notes:
Clean, production-ready specification with no estimation artifacts.
-**Key Principle:**
+**Key Principle:**
+
- **All estimated values are spelled out explicitly** (not hidden)
- **Marked with (est.) label** to indicate AI interpretation
- **Designer confirms or adjusts** each estimated value
@@ -359,6 +382,7 @@ This ensures **transparency** about which values came from AI sketch analysis vs
### During Sketching
**Designer:**
+
```
1. Draw page layout
2. Add ACTUAL TEXT for headlines/buttons
@@ -370,6 +394,7 @@ This ensures **transparency** about which values came from AI sketch analysis vs
### During Specification (Phase 4)
**Agent:**
+
```
1. Analyze sketch
2. Read any actual text found
@@ -381,6 +406,7 @@ This ensures **transparency** about which values came from AI sketch analysis vs
```
**User:**
+
```
1. See sketch text as suggestion
2. Keep, change, or refine
@@ -413,7 +439,7 @@ SE: Varje promenad. i tid. Varje gång.
These are my suggestions. Do they work?
1. Use these translations
-2. Adjust translations
+2. Adjust translations
3. Manual input
Choice [1/2/3]:
@@ -432,9 +458,11 @@ Or refines:
SE: Varje promenad. Punktligt. Varje gång. ← Adjusted
```
-EN: Every walk. on time. Every time. ← Keeps it!
+
+EN: Every walk. on time. Every time. ← Keeps it!
SE: Varje promenad. i tid. Varje gång.
-```
+
+````
### Specification Result:
@@ -447,7 +475,7 @@ SE: Varje promenad. i tid. Varje gång.
- **Content**:
- EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång."
-```
+````
**Result:** Sketch text became final content! ✅
@@ -455,20 +483,22 @@ SE: Varje promenad. i tid. Varje gång.
## Summary
-| Element Type | Sketch Method | Agent Behavior |
-|--------------|---------------|----------------|
-| **Headlines** | Actual text | Reads & suggests as starting content |
-| **Buttons** | Actual text | Reads & suggests as button label |
-| **Navigation** | Actual text | Reads & suggests as nav items |
-| **Body paragraphs** | Line markers | Analyzes for size/capacity, requests content |
-| **Descriptions** | Line markers | Analyzes for size/capacity, requests content |
+| Element Type | Sketch Method | Agent Behavior |
+| ------------------- | ------------- | -------------------------------------------- |
+| **Headlines** | Actual text | Reads & suggests as starting content |
+| **Buttons** | Actual text | Reads & suggests as button label |
+| **Navigation** | Actual text | Reads & suggests as nav items |
+| **Body paragraphs** | Line markers | Analyzes for size/capacity, requests content |
+| **Descriptions** | Line markers | Analyzes for size/capacity, requests content |
**Golden Rule:**
+
- **Important/short text** = Draw actual text
- **Long/placeholder text** = Use line markers
- **Mix both** for best results
**Remember:**
+
- Sketch text is a suggestion, not final
- Agent will ask to confirm or change
- Refinement happens during specification
@@ -477,4 +507,3 @@ SE: Varje promenad. i tid. Varje gång.
---
**Use actual text for headlines, markers for body text!** 📝✨
-
diff --git a/src/modules/wds/workflows/4-ux-design/STORYBOARD-INTEGRATION.md b/src/modules/wds/workflows/4-ux-design/STORYBOARD-INTEGRATION.md
index 23995eca..4484d14c 100644
--- a/src/modules/wds/workflows/4-ux-design/STORYBOARD-INTEGRATION.md
+++ b/src/modules/wds/workflows/4-ux-design/STORYBOARD-INTEGRATION.md
@@ -9,6 +9,7 @@
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)
@@ -23,6 +24,7 @@ Complex interactive components (calendars, booking systems, multi-step workflows
**Purpose:** Show how a component changes states over time
**Example:** Dog Week Walk Booking States
+
```
┌─────────────────────────────────────────────────┐
│ State Transition Storyboard │
@@ -57,6 +59,7 @@ Complex interactive components (calendars, booking systems, multi-step workflows
**Purpose:** Show step-by-step user interactions
**Example:** Calendar Booking Flow
+
```
Frame 1: User views calendar
Frame 2: User taps "Book" button
@@ -70,6 +73,7 @@ Frame 5: Week overview quarter circle turns gray
**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
@@ -84,11 +88,11 @@ Frame 5: Leaderboard count increments
### 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 |
+| 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
@@ -147,19 +151,23 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
**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
@@ -171,6 +179,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
**Visual Reference:** Storyboard Frame 2
**Appearance:**
+
- Gray background
- Dog avatar + User avatar overlay
- Names: "Rufus & Patrick"
@@ -178,14 +187,17 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
- 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
@@ -197,6 +209,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
**Visual Reference:** Storyboard Frame 3
**Appearance:**
+
- Orange background
- Dog avatar only (user avatar removed)
- Countdown timer: "32 min left" / "32 min kvar"
@@ -204,14 +217,17 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
- 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
@@ -223,6 +239,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
**Visual Reference:** Storyboard Frame 4
**Appearance:**
+
- Blue background
- Dog avatar + User avatar overlay
- Status: "Started 09:32 • 23 min ago"
@@ -230,13 +247,16 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
- 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
@@ -248,6 +268,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
**Visual Reference:** Storyboard Frame 5
**Appearance:**
+
- Green background
- Dog avatar + User avatar overlay
- Duration: "32 min walk" / "32 min promenad"
@@ -255,12 +276,15 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
- 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
@@ -272,6 +296,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
**Visual Reference:** Storyboard Frame 6
**Appearance:**
+
- Red background
- Dog avatar only (no user avatar)
- Message: "No walk registered" / "Ingen promenad registrerad"
@@ -279,12 +304,15 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
- 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
@@ -298,35 +326,29 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
**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
@@ -339,6 +361,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
**Storyboard:** `Storyboards/missed-walk-flow.jpg`
**Steps:**
+
1. Walk booked (GRAY state)
2. Time window opens (ORANGE state)
3. Countdown timer runs
@@ -354,11 +377,13 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
**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
@@ -370,8 +395,8 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
---
## State Machine Diagram
-
```
+
┌─────────────┐
│ WHITE │
│ (Empty) │
@@ -407,6 +432,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti
│
▼
[END]
+
```
---
@@ -449,12 +475,14 @@ Don't need storyboards for:
Number frames sequentially:
```
+
1. Initial state
2. After user action
3. System response
4. Next state
5. Alternative path
-```
+
+````
### Storyboard Annotations
@@ -547,7 +575,7 @@ Include:
## Error Handling
{Error states, recovery flows, etc.}
-```
+````
---
@@ -579,12 +607,14 @@ Features/
### 1. Visual Clarity
**Before (Text only):**
+
```
-When the user books a walk, the card changes to gray,
+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.
```
@@ -592,6 +622,7 @@ 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
@@ -600,6 +631,7 @@ Developers can:
### 3. Design Consistency
Designers can:
+
- Ensure all states are visually distinct
- Verify state transitions make sense
- Spot missing states or transitions
@@ -608,6 +640,7 @@ Designers can:
### 4. QA Testing
QA can:
+
- Use storyboard as test script
- Verify all states are implemented
- Test all transition paths
@@ -620,6 +653,7 @@ QA can:
### Step 1: Sketch Storyboard
During UX design phase:
+
1. Identify complex interactive components
2. Sketch state transitions on paper/whiteboard
3. Number frames sequentially
@@ -643,6 +677,7 @@ Features/Storyboards/{component-name}-{type}.jpg
### Step 4: Document States
For each frame in storyboard:
+
- Create state definition
- Link to storyboard frame number
- Describe triggers and transitions
@@ -656,17 +691,20 @@ 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
diff --git a/src/modules/wds/workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md b/src/modules/wds/workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md
index 639c2bef..8ec0d22c 100644
--- a/src/modules/wds/workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md
+++ b/src/modules/wds/workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md
@@ -11,6 +11,7 @@
This guide explains how to organize text content and translations in WDS specifications using **purpose-based naming** and **grouped translation** patterns.
**Related Documentation:**
+
- **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** - How to analyze text markers in sketches
- **`HTML-VS-VISUAL-STYLES.md`** - HTML tags vs visual text styles
- **`WDS-SPECIFICATION-PATTERN.md`** - Complete specification format with examples
@@ -22,16 +23,22 @@ This guide explains how to organize text content and translations in WDS specifi
### 1. Name by PURPOSE, Not Content
**❌ WRONG:**
+
```markdown
#### Welcome Heading
+
**OBJECT ID**: `start-hero-welcome-heading`
+
- Content: "Welcome to Dog Week"
```
**✅ CORRECT:**
+
```markdown
#### Primary Headline
+
**OBJECT ID**: `start-hero-headline`
+
- Content:
- EN: "Welcome to Dog Week"
- SE: "Välkommen till Dog Week"
@@ -44,11 +51,12 @@ This guide explains how to organize text content and translations in WDS specifi
### 2. Separate Structure from Content
**Structure (Position/Style):**
+
```markdown
- **HTML Tag**: h1 (semantic structure for SEO/accessibility)
- **Visual Style**: Hero headline (from Design System)
- **Position**: Center of hero section, above CTA
-- **Style**:
+- **Style**:
- Font weight: Bold (from 3px thick line markers)
- Font size: 42px (est. from 24px spacing between line pairs)
- Line-height: 1.2 (est. calculated from font size)
@@ -58,14 +66,15 @@ This guide explains how to organize text content and translations in WDS specifi
> **Important:** HTML tags (h1-h6) define semantic structure for SEO/accessibility. Visual styles (Hero headline, Main header, Sub header, etc.) define appearance and can be applied to any HTML tag.
> **Note:** Values marked `(est. from...)` show sketch analysis reasoning. Designer should confirm or adjust these values, then update with actual specifications.
-```
+
+````
**Content (Translations):**
```markdown
- **Content**:
- EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång."
-```
+````
**Why:** Structure rarely changes, content often does. Keeps specs clean.
@@ -74,33 +83,44 @@ This guide explains how to organize text content and translations in WDS specifi
### 3. Group Related Translations
**❌ WRONG (Scattered):**
+
```markdown
#### Headline EN
+
"Every walk. on time."
#### Headline SE
+
"Varje promenad. i tid."
#### Body EN
+
"Organize your family..."
#### Body SE
+
"Organisera din familj..."
```
**✅ CORRECT (Grouped):**
+
```markdown
### Hero Object
+
**Purpose**: Primary value proposition
#### Primary Headline
+
**OBJECT ID**: `start-hero-headline`
+
- **Content**:
- EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång."
#### Supporting Text
+
**OBJECT ID**: `start-hero-supporting`
+
- **Content**:
- EN: "Organize your family around dog care."
- SE: "Organisera din familj kring hundvård."
@@ -116,10 +136,13 @@ This guide explains how to organize text content and translations in WDS specifi
```markdown
### Hero Object
+
**Purpose**: Primary value proposition and main conversion action
#### Primary Headline
+
**OBJECT ID**: `start-hero-headline`
+
- **Component**: H1 heading (`.text-heading-1`)
- **Position**: Center of hero, top of section
- **Style**: Bold, no italic, 42px, line-height 1.2
@@ -129,7 +152,9 @@ This guide explains how to organize text content and translations in WDS specifi
- SE: "Varje promenad. i tid. Varje gång."
#### Supporting Text
+
**OBJECT ID**: `start-hero-supporting`
+
- **Component**: Body text (`.text-body`)
- **Position**: Below headline, above CTA
- **Style**: Regular, 16px, line-height 1.5
@@ -139,7 +164,9 @@ This guide explains how to organize text content and translations in WDS specifi
- SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen."
#### Primary CTA Button
+
**OBJECT ID**: `start-hero-cta`
+
- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md)
- **Position**: Center, below supporting text
- **Behavior**: Navigate to registration
@@ -151,11 +178,13 @@ This guide explains how to organize text content and translations in WDS specifi
**Reading Experience:**
**English:**
+
> Every walk. on time. Every time.
> Organize your family around dog care. Never miss a walk again.
> [start planning - free forever]
**Swedish:**
+
> Varje promenad. i tid. Varje gång.
> Organisera din familj kring hundvård. Missa aldrig en promenad igen.
> [börja planera - gratis för alltid]
@@ -168,10 +197,13 @@ Each language flows naturally as a complete message!
```markdown
### Sign In Form
+
**Purpose**: User authentication
#### Email Label
+
**OBJECT ID**: `signin-form-email-label`
+
- **Component**: Label text (`.text-label`)
- **Position**: Above email input field
- **For**: `signin-form-email-input`
@@ -180,14 +212,18 @@ Each language flows naturally as a complete message!
- SE: "E-postadress"
#### Email Input
+
**OBJECT ID**: `signin-form-email-input`
+
- **Component**: [Text Input](/docs/.../text-input.md)
- **Placeholder**:
- EN: "your@email.com"
- SE: "din@epost.com"
#### Password Label
+
**OBJECT ID**: `signin-form-password-label`
+
- **Component**: Label text (`.text-label`)
- **Position**: Above password input
- **For**: `signin-form-password-input`
@@ -196,7 +232,9 @@ Each language flows naturally as a complete message!
- SE: "Lösenord"
#### Password Input
+
**OBJECT ID**: `signin-form-password-input`
+
- **Component**: [Password Input](/docs/.../password-input.md)
- **Placeholder**:
- EN: "Enter your password"
@@ -209,10 +247,13 @@ Each language flows naturally as a complete message!
```markdown
### Validation Messages
+
**Purpose**: User feedback on form errors
#### Email Required Error
+
**OBJECT ID**: `signin-form-email-error-required`
+
- **Component**: Error text (`.text-error`)
- **Position**: Below email input field
- **Trigger**: When email field is empty on submit
@@ -221,7 +262,9 @@ Each language flows naturally as a complete message!
- SE: "E-postadress krävs"
#### Email Invalid Error
+
**OBJECT ID**: `signin-form-email-error-invalid`
+
- **Component**: Error text (`.text-error`)
- **Position**: Below email input field
- **Trigger**: When email format is invalid
@@ -230,7 +273,9 @@ Each language flows naturally as a complete message!
- SE: "Ange en giltig e-postadress"
#### Auth Failed Error
+
**OBJECT ID**: `signin-form-auth-error`
+
- **Component**: Alert banner (`.alert-error`)
- **Position**: Above form, below page heading
- **Trigger**: When authentication fails
@@ -246,12 +291,14 @@ Each language flows naturally as a complete message!
### Format: `{page}-{section}-{purpose}`
**Page Examples:**
+
- `start` (start/landing page)
- `signin` (sign in page)
- `profile` (profile page)
- `calendar` (calendar page)
**Section Examples:**
+
- `hero` (hero section)
- `header` (page header)
- `form` (form section)
@@ -259,6 +306,7 @@ Each language flows naturally as a complete message!
- `footer` (page footer)
**Purpose Examples:**
+
- `headline` (main heading)
- `subheading` (secondary heading)
- `description` (descriptive text)
@@ -269,6 +317,7 @@ Each language flows naturally as a complete message!
- `supporting` (supporting/helper text)
**Complete Examples:**
+
- `start-hero-headline`
- `signin-form-email-label`
- `profile-success-message`
@@ -283,15 +332,17 @@ Each language flows naturally as a complete message!
```markdown
#### {{Purpose_Title}}
+
**OBJECT ID**: `{{page-section-purpose}}`
+
- **Component**: {{component_type}} ({{class_or_reference}})
- **Position**: {{position_description}}
- **Content**:
- EN: "{{english_content}}"
- SE: "{{swedish_content}}"
- {{#if additional_languages}}
+ {{#if additional_languages}}
- {{lang}}: "{{content}}"
- {{/if}}
+ {{/if}}
```
### Optional Fields
@@ -347,15 +398,18 @@ Each language flows naturally as a complete message!
**Hero Object Translations:**
#### Primary Headline
+
- EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång."
#### Supporting Text
+
- EN: "Organize your family around dog care."
- SE: "Organisera din familj kring hundvård."
```
Translator can:
+
- Read entire section in each language
- Ensure translations flow together
- See context immediately
@@ -372,19 +426,22 @@ const supportingText = document.getElementById('start-hero-supporting');
const content = {
'start-hero-headline': {
en: 'Every walk. on time. Every time.',
- se: 'Varje promenad. i tid. Varje gång.'
- }
+ se: 'Varje promenad. i tid. Varje gång.',
+ },
};
```
### ✅ For Maintainability
**Content changes:**
+
```markdown
#### Primary Headline
-**OBJECT ID**: `start-hero-headline` ← Stays same
+
+**OBJECT ID**: `start-hero-headline` ← Stays same
+
- **Content**:
- - EN: "NEW CONTENT HERE" ← Easy to update
+ - EN: "NEW CONTENT HERE" ← Easy to update
- SE: "NYTT INNEHÅLL HÄR"
```
@@ -402,14 +459,17 @@ All translations grouped so each language reads coherently:
### Hero Object
#### Headline
+
- EN: "Every walk. on time."
- SE: "Varje promenad. i tid."
#### Body
+
- EN: "Never miss a walk again."
- SE: "Missa aldrig en promenad."
#### CTA
+
- EN: "Get Started"
- SE: "Kom Igång"
```
@@ -423,10 +483,12 @@ All translations grouped so each language reads coherently:
### Feature Card 1
#### Feature Title
+
- EN: "Smart Scheduling"
- SE: "Smart Schemaläggning"
#### Feature Description
+
- EN: "Automatically assign walks based on family availability."
- SE: "Tilldela promenader automatiskt baserat på familjetillgänglighet."
```
@@ -449,6 +511,3 @@ Before finalizing text specifications:
---
**This pattern ensures professional, maintainable, translation-friendly specifications across all WDS projects!** 🌍✨
-
-
-
diff --git a/src/modules/wds/workflows/4-ux-design/WDS-SPECIFICATION-PATTERN.md b/src/modules/wds/workflows/4-ux-design/WDS-SPECIFICATION-PATTERN.md
index ba8910ba..2a271a4d 100644
--- a/src/modules/wds/workflows/4-ux-design/WDS-SPECIFICATION-PATTERN.md
+++ b/src/modules/wds/workflows/4-ux-design/WDS-SPECIFICATION-PATTERN.md
@@ -11,6 +11,7 @@ This document defines the **WDS Specification Pattern** used in Phase 4 (UX Desi
**Dog Week Start Page** is used as the example implementation to demonstrate the pattern in action.
**Related Documentation:**
+
- **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** - How sketch analysis values are derived
- **`HTML-VS-VISUAL-STYLES.md`** - HTML tags vs visual text styles
- **`TRANSLATION-ORGANIZATION-GUIDE.md`** - Purpose-based text organization
@@ -20,15 +21,20 @@ This document defines the **WDS Specification Pattern** used in Phase 4 (UX Desi
## Key Principles
### 1. Purpose-Based Naming
+
Text objects are named by **function, not content**:
+
- ✅ `hero-headline` (describes purpose)
- ❌ `welcome-message` (describes content)
### 2. Grouped Translations
+
All product languages grouped together per object for coherent review.
### 3. Estimated Values from Sketch Analysis
+
When text properties are estimated from sketch markers:
+
- **Spell out the values explicitly** (e.g., `42px (est. from 24px spacing)`)
- **Mark with analysis note** to show reasoning
- **Designer confirms or adjusts** during specification dialog
@@ -46,6 +52,7 @@ This ensures transparency about which values came from AI interpretation vs. des
```markdown
### Hero Object
+
**Purpose**: Primary value proposition and main conversion action
#### Primary Headline
@@ -53,10 +60,12 @@ This ensures transparency about which values came from AI interpretation vs. des
**OBJECT ID**: `start-hero-headline`
**HTML Structure:**
+
- **Tag**: h1
- **Semantic Purpose**: Main page heading for SEO and accessibility
**Visual Style:**
+
- **Style Name**: Hero headline
- **Font weight**: Bold (from 3px thick line markers in sketch)
- **Font size**: 56px (est. from 32px vertical spacing between line pairs)
@@ -70,6 +79,7 @@ This ensures transparency about which values came from AI interpretation vs. des
**Behavior**: Updates with language toggle
**Content**:
+
- EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång."
@@ -80,10 +90,12 @@ This ensures transparency about which values came from AI interpretation vs. des
**OBJECT ID**: `start-hero-supporting`
**HTML Structure:**
+
- **Tag**: p
- **Semantic Purpose**: Paragraph text providing additional context
**Visual Style:**
+
- **Style Name**: Body text large
- **Font weight**: Regular (from 1px thin line markers in sketch)
- **Font size**: 18px (est. from 14px vertical spacing between line pairs)
@@ -96,13 +108,16 @@ This ensures transparency about which values came from AI interpretation vs. des
**Behavior**: Updates with language toggle
**Content**:
+
- EN: "Organize your family around dog care. Never miss a walk again."
- SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen."
> **Sketch Analysis:** Line thickness (1px) → Regular weight. Line spacing (14px) → ~18px font size estimate. Designer should confirm these values.
#### Primary CTA Button
+
**OBJECT ID**: `start-hero-cta`
+
- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md)
- **Position**: Center, below supporting text, 24px margin-top
- **Behavior**: Navigate to /auth/signup
@@ -113,11 +128,13 @@ This ensures transparency about which values came from AI interpretation vs. des
```
**Reading in English:**
+
> **Every walk. on time. Every time.**
> Organize your family around dog care. Never miss a walk again.
> [start planning - free forever]
**Reading in Swedish:**
+
> **Varje promenad. i tid. Varje gång.**
> Organisera din familj kring hundvård. Missa aldrig en promenad igen.
> [börja planera - gratis för alltid]
@@ -127,6 +144,7 @@ This ensures transparency about which values came from AI interpretation vs. des
## The Complete Process
### Step 1: Sketch Analysis (4B)
+
```
Agent sees sketch with horizontal lines:
@@ -142,11 +160,12 @@ Agent sees sketch with horizontal lines:
Agent identifies:
1. TEXT GROUP (2 thick lines) - Hero headline
-2. TEXT GROUP (2 thin lines) - Supporting text
+2. TEXT GROUP (2 thin lines) - Supporting text
3. BUTTON - CTA
```
### Step 2: Object Detection (4C-03 + object-router)
+
```
For Object 1:
→ Detects horizontal lines
@@ -162,6 +181,7 @@ heading-text.md:
```
### Step 3: Content with Grouped Translations
+
```
Agent asks:
@@ -181,15 +201,18 @@ Do these work? [1] Use these [2] Adjust [3] Manual"
User provides:
1 ← Accepts suggestions!
-Agent validates:
+Agent validates:
✅ EN: 37 chars (fits 60 capacity)
✅ SE: 36 chars (fits 60 capacity)
```
### Step 4: Generate Specification
+
```markdown
#### Primary Headline
+
**OBJECT ID**: `start-hero-headline`
+
- **Component**: H1 heading
- **Position**: Center of hero
- **Style**: Bold, 42px, line-height 1.2
@@ -205,11 +228,13 @@ Agent validates:
### 1. Purpose-Based Object IDs
**Stable Naming:**
+
- Content changes don't affect Object IDs
- IDs remain semantic and meaningful
- Easy to find by function
**Examples:**
+
```markdown
`start-hero-headline` ← Purpose clear
`signin-form-email-label` ← Function clear
@@ -219,6 +244,7 @@ Agent validates:
### 2. Separated Concerns
**Structure/Style** (rarely changes):
+
```markdown
- **Component**: H1 heading
- **Position**: Center of hero
@@ -226,6 +252,7 @@ Agent validates:
```
**Content** (often changes):
+
```markdown
- **Content**:
- EN: "..."
@@ -235,24 +262,29 @@ Agent validates:
### 3. Grouped Translations
**Benefits:**
+
- Each language reads as complete message
- Translator sees full context
- Natural language flow
- Easy to verify coherence
**Format:**
+
```markdown
### Text Group
#### Element 1
+
- EN: "..."
- SE: "..."
#### Element 2
+
- EN: "..."
- SE: "..."
#### Element 3
+
- EN: "..."
- SE: "..."
```
@@ -260,6 +292,7 @@ Agent validates:
### 4. Character Capacity Validation
**From Sketch Analysis:**
+
```
Agent: "Sketch shows 2 lines, ~50-60 chars capacity"
@@ -269,6 +302,7 @@ Agent: "✅ Content fits within sketch capacity!"
```
**If too long:**
+
```
Agent: "⚠️ Your content (85 chars) exceeds capacity (60 chars).
Consider shortening or adjusting font size."
@@ -314,24 +348,26 @@ Consider shortening or adjusting font size."
```markdown
#### {{Purpose_Title}}
+
**OBJECT ID**: `{{page-section-purpose}}`
+
- **Component**: {{type}} ({{class_or_ref}})
- **Position**: {{position_description}}
-{{#if has_behavior}}
+ {{#if has_behavior}}
- **Behavior**: {{behavior_description}}
-{{/if}}
-{{#if has_style_details}}
+ {{/if}}
+ {{#if has_style_details}}
- **Style**: {{style_specifications}}
-{{/if}}
-{{#if links_to_input}}
+ {{/if}}
+ {{#if links_to_input}}
- **For**: {{input_object_id}}
-{{/if}}
+ {{/if}}
- **Content**:
- EN: "{{english_text}}"
- SE: "{{swedish_text}}"
- {{#each additional_language}}
+ {{#each additional_language}}
- {{code}}: "{{text}}"
- {{/each}}
+ {{/each}}
```
---
@@ -341,16 +377,21 @@ Consider shortening or adjusting font size."
These follow the exact pattern we're implementing:
**From 1.1-Start-Page.md:**
+
```markdown
#### Primary Headline
+
**OBJECT ID**: `start-hero-headline`
+
- **Component**: H1 heading (`.text-heading-1`)
- **Content**:
- EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång."
#### Primary CTA Button
+
**OBJECT ID**: `start-hero-cta`
+
- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md)
- **Content**:
- EN: "start planning - free forever"
@@ -358,11 +399,14 @@ These follow the exact pattern we're implementing:
```
**From 1.2-Sign-In.md (Header example):**
+
```markdown
-#### Sign In Button
+#### Sign In Button
+
**OBJECT ID**: `start-header-signin`
+
- **Component**: [Button Secondary](/docs/D-Design-System/.../Button-Secondary.md)
-- **Content**:
+- **Content**:
- EN: "Sign in"
- SE: "Logga in"
- **Behavior**: Navigate to sign-in page
@@ -390,4 +434,3 @@ For each text element:
---
**This is the WDS standard for text specifications, proven by Dog Week!** 🎨🌍✨
-
diff --git a/src/modules/wds/workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md b/src/modules/wds/workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md
index 6bbc3bbb..896f2b3c 100644
--- a/src/modules/wds/workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md
+++ b/src/modules/wds/workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md
@@ -11,6 +11,7 @@
### Example: Transparent Pricing Feature
**Trigger Map Reasoning:**
+
```
TARGET GROUP: Budget-conscious customers
FEAR: Surprises and hidden costs
@@ -20,23 +21,25 @@ 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
+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
+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
+"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")
@@ -49,6 +52,7 @@ there's nothing hidden.
## The Problem with v4 WPS2C (Whiteport Sketch-to-Code)
**What happened:**
+
```
Designer: "Create a calendar for booking dog walks"
AI: *Runs with it*
@@ -56,6 +60,7 @@ 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
@@ -68,6 +73,7 @@ Result: Generic calendar, missing the point
## The AI Habit Problem
**AI's default behavior:**
+
```
"I'll make this faster!"
"I'll make this better!"
@@ -75,6 +81,7 @@ Result: Generic calendar, missing the point
```
**What AI misses:**
+
- WHY does this need to exist?
- WHO is this actually for?
- WHAT problem does this solve?
@@ -92,18 +99,21 @@ Result: Generic calendar, missing the point
## 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!")
@@ -117,17 +127,18 @@ Result: Generic calendar, missing the point
## Calendar Component
**WHY This Exists:**
-Families struggle to coordinate dog care. Kids forget, parents nag,
-dogs suffer. This calendar reduces conflict by making responsibility
+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
+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)
@@ -147,6 +158,7 @@ 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)
@@ -160,12 +172,14 @@ Makes accountability a game, not a chore. Encourages participation.
### 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*
@@ -177,12 +191,14 @@ 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*
@@ -194,6 +210,7 @@ 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*
@@ -201,6 +218,7 @@ Designer: "No, that's too aggressive..."
```
**With WHY:**
+
```
Spec: "Countdown = gentle urgency, not aggressive nagging"
Designer: "Make countdown more prominent"
@@ -213,6 +231,7 @@ Designer: ✅ Got it
### 4. Future Developers Understand Context
**Without WHY:**
+
```
Developer: "Why can't users book multiple walks at once?"
*Removes blocking logic*
@@ -220,8 +239,9 @@ Developer: "Why can't users book multiple walks at once?"
```
**With WHY:**
+
```
-Spec: "One active walk per dog = accountability. Kids can't game the system
+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."
```
@@ -231,6 +251,7 @@ 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..."
@@ -240,6 +261,7 @@ Agent: "Got it! Documenting:
```
**This creates specifications that:**
+
- Capture reasoning, not just decisions
- Guide AI implementation correctly
- Prevent "helpful" mistakes
@@ -252,21 +274,25 @@ Agent: "Got it! Documenting:
### 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
@@ -281,16 +307,19 @@ Agent: "Got it! Documenting:
## 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
@@ -304,7 +333,7 @@ Agent: "Got it! Documenting:
## Book Walk Button
**WHY This Exists:**
-Kids need a simple way to commit to walking the dog.
+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"):**
@@ -317,17 +346,20 @@ 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
@@ -336,6 +368,7 @@ Quick actions would encourage gaming the system (book everything, complete nothi
```
**Now AI knows:**
+
- What to implement
- What NOT to add
- WHY each decision was made
@@ -346,6 +379,7 @@ Quick actions would encourage gaming the system (book everything, complete nothi
## The Transformation
### v4 WPS2C (Prompt-and-Run)
+
```
Designer: "Create a booking calendar"
AI: *Generates generic calendar*
@@ -355,6 +389,7 @@ 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?"
@@ -364,7 +399,7 @@ 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
+Agent: "Documenting all the WHYs. This will help AI implement
correctly and prevent 'helpful' mistakes."
*Generates why-based specification*
@@ -380,21 +415,25 @@ Designer: ✅ Perfect first time
**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
@@ -406,18 +445,21 @@ Designer: ✅ Perfect first time
**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)
@@ -431,23 +473,23 @@ Designer: ✅ Perfect first time
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
@@ -473,24 +515,28 @@ Designer: ✅ Perfect first time
**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)
diff --git a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/ai-collaboration.md b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/ai-collaboration.md
index 1c147b7e..8c18c40b 100644
--- a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/ai-collaboration.md
+++ b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/ai-collaboration.md
@@ -15,30 +15,35 @@ AI can both **generate** Excalidraw files and **analyze** your sketches, creatin
### **What AI Can Create:**
**Layout Variations:**
+
```
You: "Create 3 dashboard layout options"
AI: Generates 3 .excalidraw files
```
**Component Alternatives:**
+
```
You: "Show me different navigation patterns"
AI: Generates bottom nav, hamburger, tab bar
```
**User Flows:**
+
```
You: "Create a user onboarding flow"
AI: Generates flowchart with decision points
```
**State Variations:**
+
```
You: "Show this button in all states"
AI: Generates default, hover, active, disabled, loading
```
**Responsive Designs:**
+
```
You: "Show this page on mobile, tablet, desktop"
AI: Generates 3 breakpoint wireframes
@@ -51,11 +56,13 @@ AI: Generates 3 breakpoint wireframes
### **Be Specific:**
**❌ Vague:**
+
```
"Make a login page"
```
**✅ Specific:**
+
```
"Create a mobile login page (375×812) with:
- Logo at top
@@ -69,6 +76,7 @@ Use 20px grid and WDS spacing"
### **Request Multiple Options:**
**Pattern:**
+
```
"Create [number] variations of [page/component] with:
- Option 1: [description]
@@ -77,6 +85,7 @@ Use 20px grid and WDS spacing"
```
**Example:**
+
```
"Create 3 dashboard variations:
1. Card-based layout (large cards, visual focus)
@@ -87,6 +96,7 @@ Use 20px grid and WDS spacing"
### **Specify Constraints:**
**Include:**
+
- Device size (mobile/tablet/desktop)
- Grid size (20px)
- Key components needed
@@ -94,6 +104,7 @@ Use 20px grid and WDS spacing"
- Spacing preferences
**Example:**
+
```
"Create a mobile task list (375×812):
- Use 20px grid
@@ -110,6 +121,7 @@ Use 20px grid and WDS spacing"
### **The Process:**
**Step 1: Export to PNG**
+
```
1. Open .excalidraw file
2. Export → PNG
@@ -117,11 +129,13 @@ Use 20px grid and WDS spacing"
```
**Step 2: Upload to AI**
+
```
Upload PNG to Claude/ChatGPT/Windsurf
```
**Step 3: Ask for Analysis**
+
```
"Here's my dashboard sketch. What do you think?"
"Analyze this layout and suggest improvements"
@@ -131,18 +145,21 @@ Upload PNG to Claude/ChatGPT/Windsurf
### **What AI Can See:**
**Layout and Structure:**
+
- Component placement
- Visual hierarchy
- Spacing and alignment
- Section organization
**Design Decisions:**
+
- Primary vs secondary actions
- Content prioritization
- Navigation patterns
- Information architecture
**Potential Issues:**
+
- Crowded areas
- Unclear hierarchy
- Inconsistent spacing
@@ -156,6 +173,7 @@ Upload PNG to Claude/ChatGPT/Windsurf
### **Pattern 1: AI Generates, You Refine**
**Workflow:**
+
```
1. AI generates initial options
2. You review and choose direction
@@ -166,12 +184,13 @@ Upload PNG to Claude/ChatGPT/Windsurf
```
**Example:**
+
```
You: "Create 3 login page variations"
AI: [Generates 3 files]
You: [Opens each, reviews]
- "I like option 2 best, but the social buttons
+ "I like option 2 best, but the social buttons
should be more prominent"
You: [Edits option 2 in Excalidraw]
@@ -179,7 +198,7 @@ You: [Edits option 2 in Excalidraw]
[Uploads]
"Here's my refined version"
-AI: "Great improvement! The social buttons are now
+AI: "Great improvement! The social buttons are now
more prominent. Consider:
- Adding visual separation with a divider
- Making the 'or' text more subtle
@@ -191,6 +210,7 @@ You: [Makes final adjustments]
### **Pattern 2: You Sketch, AI Analyzes**
**Workflow:**
+
```
1. You sketch initial idea
2. Export to PNG
@@ -201,6 +221,7 @@ You: [Makes final adjustments]
```
**Example:**
+
```
You: [Sketches dashboard]
[Exports and uploads]
@@ -211,7 +232,7 @@ AI: "I can see you've prioritized today's tasks at the top.
- Clear visual hierarchy
- Task cards are well-sized
- Good use of spacing
-
+
Consider:
- The 'Add task' button might get lost at bottom
- No indication of overdue tasks
@@ -222,14 +243,15 @@ You: [Updates sketch based on feedback]
[Exports and uploads]
"Better?"
-AI: "Much better! The floating 'Add' button is more
- accessible. Now let's discuss the overdue task
+AI: "Much better! The floating 'Add' button is more
+ accessible. Now let's discuss the overdue task
treatment..."
```
### **Pattern 3: Collaborative Iteration**
**Workflow:**
+
```
1. You sketch rough idea
2. AI generates refined version
@@ -240,6 +262,7 @@ AI: "Much better! The floating 'Add' button is more
```
**Example:**
+
```
You: [Rough sketch of profile page]
"Here's my rough idea for a profile page"
@@ -249,8 +272,8 @@ AI: "I see your concept. Let me create a refined version
[Generates 3 files]
You: [Reviews all 3]
- "I like my header from original, your content
- layout from option 2, and the action buttons
+ "I like my header from original, your content
+ layout from option 2, and the action buttons
from option 3"
AI: "Perfect! Let me combine those elements"
@@ -267,11 +290,13 @@ You: [Reviews]
### **Example 1: Layout Analysis**
**You upload:**
+
```
Dashboard sketch with task list
```
**AI responds:**
+
```
"Analysis of your dashboard layout:
@@ -304,11 +329,13 @@ RECOMMENDATIONS:
### **Example 2: Component Analysis**
**You upload:**
+
```
Button component in various states
```
**AI responds:**
+
```
"Analysis of your button states:
@@ -345,11 +372,13 @@ Consider adding focus state for keyboard navigation."
### **Example 3: Flow Analysis**
**You upload:**
+
```
User onboarding flow diagram
```
**AI responds:**
+
```
"Analysis of your onboarding flow:
@@ -386,6 +415,7 @@ RECOMMENDATIONS:
### **DO ✅**
**When requesting AI generation:**
+
- Be specific about requirements
- Request multiple variations (2-5)
- Specify device size and constraints
@@ -393,6 +423,7 @@ RECOMMENDATIONS:
- Include key components needed
**When uploading for analysis:**
+
- Export clear PNG (not blurry)
- Include annotations in sketch
- Ask specific questions
@@ -400,6 +431,7 @@ RECOMMENDATIONS:
- Iterate based on feedback
**During collaboration:**
+
- Combine AI suggestions with your expertise
- Don't accept everything blindly
- Use AI to explore alternatives
@@ -409,6 +441,7 @@ RECOMMENDATIONS:
### **DON'T ❌**
**Don't:**
+
- Accept first AI suggestion without review
- Skip your own design thinking
- Let AI make all decisions
@@ -423,6 +456,7 @@ RECOMMENDATIONS:
### **Typical Session:**
**Round 1: Exploration**
+
```
You: "Create 3 dashboard options"
AI: [Generates options]
@@ -430,6 +464,7 @@ You: [Reviews] "Option 2 is closest"
```
**Round 2: Refinement**
+
```
You: "Refine option 2 with more breathing room"
AI: [Generates refined version]
@@ -437,6 +472,7 @@ You: [Reviews] "Better! Now add calendar integration"
```
**Round 3: Details**
+
```
You: [Edits in Excalidraw]
[Uploads] "Here's my version with calendar"
@@ -444,6 +480,7 @@ AI: "Great! Let's discuss the calendar placement..."
```
**Round 4: Edge Cases**
+
```
AI: "What about empty state? Overdue tasks?"
You: "Good point. Show me options for those"
@@ -451,6 +488,7 @@ AI: [Generates state variations]
```
**Round 5: Finalization**
+
```
You: [Combines best elements]
"This is the final version"
@@ -464,6 +502,7 @@ AI: "Perfect! Ready to create specifications?"
### **Technique 1: Parallel Exploration**
**Generate multiple directions simultaneously:**
+
```
You: "Create 3 completely different approaches:
1. Minimalist (focus on one task at a time)
@@ -478,6 +517,7 @@ You: [Explores each direction]
### **Technique 2: Constraint-Based Design**
**Use AI to explore within constraints:**
+
```
You: "Design a dashboard that works with:
- One-handed use (thumb zone)
@@ -492,6 +532,7 @@ You: [Validates against constraints]
### **Technique 3: Comparative Analysis**
**Have AI compare your options:**
+
```
You: [Uploads 3 variations you created]
"Compare these 3 options. Which is best for:
@@ -508,12 +549,14 @@ You: [Makes informed decision]
## Next Steps
**After AI collaboration:**
+
1. ✅ Finalized sketch
2. ✅ Design decisions documented
3. ✅ Edge cases considered
4. ✅ Ready for specifications
**Continue to:**
+
- [Export Workflow](export-workflow.md) - Prepare for documentation
- Phase 4C: Create specifications
diff --git a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md
index b32b19f0..8af5f5f9 100644
--- a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md
+++ b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md
@@ -21,6 +21,7 @@ Excalidraw is a free, open-source whiteboard tool that creates hand-drawn style
## When to Use Excalidraw
### **Perfect For:**
+
- Digital sketching (alternative to paper)
- Collaborative design sessions
- AI-generated layout variations
@@ -28,6 +29,7 @@ Excalidraw is a free, open-source whiteboard tool that creates hand-drawn style
- Iterative design exploration
### **Not Required If:**
+
- You prefer paper and pen
- You use other tools (Figma, iPad, etc.)
- You're comfortable with your current workflow
@@ -42,17 +44,18 @@ Excalidraw is a free, open-source whiteboard tool that creates hand-drawn style
```yaml
sketching:
- tool: excalidraw # or "paper" or "figma" or "other"
+ tool: excalidraw # or "paper" or "figma" or "other"
excalidraw:
enabled: true
- auto_export: false # Auto-generate PNG/SVG on save
- use_library: true # Load WDS component library
- grid_size: 20 # Snap to grid (px)
+ auto_export: false # Auto-generate PNG/SVG on save
+ use_library: true # Load WDS component library
+ grid_size: 20 # Snap to grid (px)
```
### **2. Install Tools**
**VS Code Extension (Recommended):**
+
```
1. Open Extensions (Ctrl+Shift+X)
2. Search "Excalidraw"
@@ -60,11 +63,13 @@ sketching:
```
**Or use web version:**
+
- https://excalidraw.com (no installation needed)
### **3. Load WDS Library (Optional)**
**If `use_library: true` in config:**
+
```
1. Open Excalidraw
2. Click library icon
@@ -77,28 +82,36 @@ sketching:
## Documentation
### **Setup & Configuration**
+
→ [excalidraw-setup.md](excalidraw-setup.md)
+
- Installation options
- VS Code configuration
- Project settings
- Grid and theme setup
### **Sketching Workflow**
+
→ [sketching-guide.md](sketching-guide.md)
+
- When to sketch
- What to sketch
- How to sketch
- File organization
### **Export Workflow**
+
→ [export-workflow.md](export-workflow.md)
+
- Manual export (PNG/SVG)
- Automated export (GitHub Actions)
- File naming conventions
- GitHub display
### **AI Collaboration**
+
→ [ai-collaboration.md](ai-collaboration.md)
+
- AI-generated layouts
- AI analysis of sketches
- Iteration workflow
@@ -120,6 +133,7 @@ C-Scenarios/[scenario-name]/
```
**In specifications.md:**
+
```markdown
## Design
@@ -137,6 +151,7 @@ C-Scenarios/[scenario-name]/
**Step 4B-02: Sketch Interface**
**If Excalidraw enabled:**
+
```
Agent: "I see you've enabled Excalidraw. Would you like to:
1. Sketch manually in Excalidraw
@@ -145,6 +160,7 @@ Agent: "I see you've enabled Excalidraw. Would you like to:
```
**AI can:**
+
- Generate `.excalidraw` files with layout options
- Analyze your sketches (upload PNG)
- Suggest improvements
@@ -155,9 +171,11 @@ Agent: "I see you've enabled Excalidraw. Would you like to:
## Optional Features
### **Component Library**
+
**File:** `wds-library.excalidrawlib`
Pre-built components:
+
- Mobile/tablet/desktop frames
- Buttons, inputs, cards
- Navigation patterns
@@ -166,6 +184,7 @@ Pre-built components:
**Enable:** Set `use_library: true` in config
### **Auto-Export**
+
**GitHub Actions or pre-commit hooks**
Automatically generates PNG/SVG when you save `.excalidraw` files.
@@ -181,6 +200,7 @@ See: [automation/README.md](automation/README.md)
### **Excalidraw vs Paper**
**Excalidraw:**
+
- ✅ Digital, shareable
- ✅ AI can generate
- ✅ Version controlled
@@ -188,6 +208,7 @@ See: [automation/README.md](automation/README.md)
- ❌ Requires tool setup
**Paper:**
+
- ✅ Zero setup
- ✅ Fast and natural
- ✅ No distractions
@@ -197,6 +218,7 @@ See: [automation/README.md](automation/README.md)
### **Excalidraw vs Figma**
**Excalidraw:**
+
- ✅ Free and open-source
- ✅ Hand-drawn aesthetic
- ✅ AI can generate
@@ -204,6 +226,7 @@ See: [automation/README.md](automation/README.md)
- ❌ Less precise
**Figma:**
+
- ✅ Professional tool
- ✅ Pixel-perfect
- ✅ Component systems
@@ -218,19 +241,22 @@ See: [automation/README.md](automation/README.md)
**To disable after enabling:**
**Edit:** `project-config.yaml`
+
```yaml
sketching:
- tool: paper # or "figma" or "other"
+ tool: paper # or "figma" or "other"
excalidraw:
enabled: false
```
**Agent will:**
+
- Skip Excalidraw-specific prompts
- Use generic sketching workflow
- Not generate `.excalidraw` files
**Your existing files:**
+
- Remain in project
- Can still be opened
- Not automatically deleted
@@ -242,16 +268,19 @@ sketching:
### **Issues with Excalidraw?**
**VS Code extension not working:**
+
- Restart VS Code
- Check extension is enabled
- Try web version as fallback
**Files won't open:**
+
- Verify JSON is valid
- Check file extension is `.excalidraw`
- Try opening in web version
**AI can't generate files:**
+
- Check core helpers are loaded
- Verify project config
- Report issue to WDS
@@ -259,11 +288,13 @@ sketching:
### **Community**
**Excalidraw:**
+
- Website: https://excalidraw.com
- GitHub: https://github.com/excalidraw/excalidraw
- Discord: https://discord.gg/UexuTaE
**WDS:**
+
- Discord: [WDS community]
- GitHub: [WDS issues]
@@ -272,12 +303,14 @@ sketching:
## Next Steps
**If Excalidraw is enabled:**
+
1. Install VS Code extension (or use web)
2. Load WDS library (optional)
3. Configure grid and theme
4. Start sketching!
**Learn more:**
+
- [Setup Guide](excalidraw-setup.md)
- [Sketching Guide](sketching-guide.md)
- [AI Collaboration](ai-collaboration.md)
diff --git a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md
index 1cf070d3..602c2b83 100644
--- a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md
+++ b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md
@@ -11,6 +11,7 @@
**Best for:** Working within IDE, integrated workflow
**Steps:**
+
```
1. Open VS Code
2. Extensions (Ctrl+Shift+X / Cmd+Shift+X)
@@ -20,12 +21,14 @@
```
**Usage:**
+
- Create new `.excalidraw` file
- Click to open in Excalidraw editor
- Edit and save (Ctrl+S / Cmd+S)
- File auto-saves to project
**Pros:**
+
- ✅ Never leave IDE
- ✅ Direct file access
- ✅ Git integration
@@ -36,6 +39,7 @@
**Best for:** Quick sketching, no installation
**Steps:**
+
```
1. Go to https://excalidraw.com
2. Start drawing
@@ -44,12 +48,14 @@
```
**Usage:**
+
- Open in browser
- Draw and iterate
- Download when done
- Place in project
**Pros:**
+
- ✅ Zero installation
- ✅ Works anywhere
- ✅ Always latest version
@@ -60,6 +66,7 @@
**Best for:** Dedicated sketching tool
**Steps:**
+
```
1. Download from https://github.com/excalidraw/excalidraw-desktop
2. Install for your OS
@@ -67,6 +74,7 @@
```
**Pros:**
+
- ✅ Standalone app
- ✅ Offline capable
- ✅ Native performance
@@ -78,13 +86,14 @@
### **Enable Excalidraw in Project**
**During project initialization:**
+
```
Agent: "Which sketching tool would you like to use?
1. Paper and pen (scan/photograph)
2. Excalidraw (digital, AI-friendly)
3. Figma (professional tool)
4. Other digital tool
-
+
Your choice:"
```
@@ -94,30 +103,30 @@ Agent: "Which sketching tool would you like to use?
```yaml
project:
- name: "Dog Week"
- wds_version: "6.0"
+ name: 'Dog Week'
+ wds_version: '6.0'
sketching:
- tool: excalidraw # "paper" | "excalidraw" | "figma" | "other"
-
+ tool: excalidraw # "paper" | "excalidraw" | "figma" | "other"
+
excalidraw:
enabled: true
-
+
# Auto-export to PNG/SVG on save
- auto_export: false # true | false
-
+ auto_export: false # true | false
+
# Load WDS component library
- use_library: true # true | false
-
+ use_library: true # true | false
+
# Grid settings
- grid_size: 20 # pixels
- snap_to_grid: true # true | false
-
+ grid_size: 20 # pixels
+ snap_to_grid: true # true | false
+
# Default theme
- theme: light # "light" | "dark"
-
+ theme: light # "light" | "dark"
+
# File organization
- sketches_folder: "sketches" # relative to scenario folder
+ sketches_folder: 'sketches' # relative to scenario folder
```
---
@@ -142,15 +151,18 @@ sketching:
### **Recommended Settings**
**Grid:**
+
- Size: 20px (matches WDS spacing)
- Snap: Enabled (for alignment)
- Visible: Optional (toggle with Ctrl+')
**Theme:**
+
- Light: Better for screenshots
- Dark: Easier on eyes for long sessions
**Auto-save:**
+
- Enabled by default in VS Code
- Saves on every change
@@ -161,6 +173,7 @@ sketching:
### **What is it?**
Pre-built Excalidraw components for common UI elements:
+
- Device frames (mobile, tablet, desktop)
- Buttons, inputs, cards
- Navigation patterns
@@ -171,6 +184,7 @@ Pre-built Excalidraw components for common UI elements:
**If `use_library: true` in config:**
**VS Code:**
+
```
1. Open any .excalidraw file
2. Click library icon (bottom toolbar)
@@ -180,6 +194,7 @@ Pre-built Excalidraw components for common UI elements:
```
**Web:**
+
```
1. Open https://excalidraw.com
2. Click library icon
@@ -190,6 +205,7 @@ Pre-built Excalidraw components for common UI elements:
### **Usage**
**Drag and drop:**
+
```
1. Open library panel
2. Find component (e.g., "Mobile Frame")
@@ -198,6 +214,7 @@ Pre-built Excalidraw components for common UI elements:
```
**Components included:**
+
- Mobile Frame (375x812)
- Tablet Frame (768x1024)
- Desktop Frame (1440x900)
@@ -215,6 +232,7 @@ Pre-built Excalidraw components for common UI elements:
### **Why 20px Grid?**
**Matches WDS spacing system:**
+
- Consistent alignment
- Clean layouts
- Easy calculations
@@ -223,6 +241,7 @@ Pre-built Excalidraw components for common UI elements:
### **Setup**
**VS Code:**
+
```
Settings → Extensions → Excalidraw
- Grid Mode: ✓ Enabled
@@ -231,6 +250,7 @@ Settings → Extensions → Excalidraw
```
**Web:**
+
```
View menu → Show grid (Ctrl+')
Settings → Grid size: 20
@@ -239,6 +259,7 @@ Settings → Grid size: 20
### **Usage**
**All elements snap to 20px increments:**
+
- Position: 0, 20, 40, 60, 80...
- Size: 100, 120, 140, 160...
- Spacing: 20, 40, 60, 80...
@@ -250,12 +271,14 @@ Settings → Grid size: 20
### **Light Theme (Recommended)**
**Best for:**
+
- Screenshots and exports
- GitHub display
- Documentation
- Presentations
**Colors:**
+
- Background: White
- Shapes: Light colors
- Text: Dark gray/black
@@ -263,11 +286,13 @@ Settings → Grid size: 20
### **Dark Theme**
**Best for:**
+
- Long sketching sessions
- Reduced eye strain
- Personal preference
**Colors:**
+
- Background: Dark gray
- Shapes: Bright colors
- Text: White/light gray
@@ -275,11 +300,13 @@ Settings → Grid size: 20
### **Setup**
**VS Code:**
+
```
Settings → Excalidraw → Theme: light/dark
```
**Web:**
+
```
Settings icon → Appearance → Theme
```
@@ -310,6 +337,7 @@ C-Scenarios/
### **Naming Conventions**
**Source files:**
+
```
[page-name].excalidraw
[component-name].excalidraw
@@ -317,6 +345,7 @@ C-Scenarios/
```
**Exports:**
+
```
[page-name].png (for GitHub/docs)
[page-name].svg (scalable, optional)
@@ -324,6 +353,7 @@ C-Scenarios/
```
**Examples:**
+
```
dashboard.excalidraw
dashboard.png
@@ -340,6 +370,7 @@ user-flow.svg
### **Manual Export**
**VS Code:**
+
```
1. Open .excalidraw file
2. Click hamburger menu (top-right)
@@ -348,6 +379,7 @@ user-flow.svg
```
**Web:**
+
```
1. File menu → Export image
2. Choose format (PNG/SVG)
@@ -360,6 +392,7 @@ user-flow.svg
**If `auto_export: true` in config:**
**GitHub Actions automatically:**
+
- Detects `.excalidraw` file changes
- Generates PNG and SVG
- Commits to repository
@@ -374,6 +407,7 @@ user-flow.svg
### **Essential Shortcuts**
**Drawing:**
+
- `R` - Rectangle
- `D` - Diamond
- `O` - Ellipse
@@ -382,17 +416,20 @@ user-flow.svg
- `L` - Line
**Editing:**
+
- `Ctrl/Cmd + D` - Duplicate
- `Ctrl/Cmd + G` - Group
- `Ctrl/Cmd + Shift + G` - Ungroup
- `Delete` - Delete selected
**View:**
+
- `Ctrl/Cmd + '` - Toggle grid
- `Ctrl/Cmd + Wheel` - Zoom
- `Space + Drag` - Pan canvas
**Selection:**
+
- `Ctrl/Cmd + A` - Select all
- `Shift + Click` - Multi-select
- `Ctrl/Cmd + Click` - Add to selection
@@ -406,6 +443,7 @@ user-flow.svg
**Issue:** Extension installed but files won't open
**Solutions:**
+
1. Restart VS Code
2. Check extension is enabled (Extensions panel)
3. Try right-click → Open With → Excalidraw
@@ -417,6 +455,7 @@ user-flow.svg
**Issue:** "Invalid file" error
**Solutions:**
+
1. Verify file extension is `.excalidraw`
2. Check JSON is valid (open in text editor)
3. Try opening in web version
@@ -428,6 +467,7 @@ user-flow.svg
**Issue:** Elements don't snap to grid
**Solutions:**
+
1. Enable "Snap to grid" in settings
2. Check grid size is set (20px)
3. Toggle grid visibility (Ctrl+')
@@ -438,6 +478,7 @@ user-flow.svg
**Issue:** Component library not appearing
**Solutions:**
+
1. Verify file path is correct
2. Check `.excalidrawlib` file exists
3. Try uploading manually
@@ -449,6 +490,7 @@ user-flow.svg
## Best Practices
### **DO ✅**
+
- Use 20px grid for alignment
- Save frequently (auto-save helps)
- Export PNG for documentation
@@ -457,6 +499,7 @@ user-flow.svg
- Label all elements clearly
### **DON'T ❌**
+
- Don't skip grid alignment
- Don't forget to export for GitHub
- Don't delete source files
@@ -469,12 +512,14 @@ user-flow.svg
## Next Steps
**After setup:**
+
1. ✅ Excalidraw installed and configured
2. ✅ Project config updated
3. ✅ Library loaded (optional)
4. ✅ Grid and theme set
**Now learn:**
+
- [Sketching Guide](sketching-guide.md) - How to sketch in WDS
- [AI Collaboration](ai-collaboration.md) - Work with AI
- [Export Workflow](export-workflow.md) - Share your work
diff --git a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/export-workflow.md b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/export-workflow.md
index 02dd3c36..842dcfae 100644
--- a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/export-workflow.md
+++ b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/export-workflow.md
@@ -7,18 +7,21 @@
## Why Export?
**Excalidraw files (`.excalidraw`) are JSON:**
+
- ✅ Perfect for editing
- ✅ Version control friendly
- ✅ AI can generate
- ❌ Don't render in GitHub
**Exported images (PNG/SVG):**
+
- ✅ Display in GitHub
- ✅ Show in documentation
- ✅ Easy to share
- ✅ No special tools needed
**Solution:** Keep both!
+
```
sketch.excalidraw ← Source (editable)
sketch.png ← Display (GitHub)
@@ -31,12 +34,14 @@ sketch.png ← Display (GitHub)
### **From VS Code Extension**
**Step 1: Open file**
+
```
Click .excalidraw file in VS Code
Opens in Excalidraw editor
```
**Step 2: Export**
+
```
1. Click hamburger menu (top-right)
2. Export image
@@ -48,6 +53,7 @@ Opens in Excalidraw editor
```
**Step 3: Name correctly**
+
```
Source: dashboard.excalidraw
Export: dashboard.png
@@ -57,6 +63,7 @@ Export: dashboard.png
### **From Web App**
**Step 1: Open file**
+
```
1. Go to https://excalidraw.com
2. File → Open
@@ -64,6 +71,7 @@ Export: dashboard.png
```
**Step 2: Export**
+
```
1. Click hamburger menu
2. Export image
@@ -72,6 +80,7 @@ Export: dashboard.png
```
**Step 3: Move to project**
+
```
1. Move downloaded file to project
2. Place in same folder as source
@@ -85,6 +94,7 @@ Export: dashboard.png
### **PNG Export**
**Recommended settings:**
+
```
Format: PNG
Background: Transparent or White
@@ -93,23 +103,27 @@ Include: Only selected (if partial export)
```
**When to use:**
+
- Documentation
- GitHub README
- Presentations
- Quick sharing
**Pros:**
+
- ✅ Universal support
- ✅ Good quality
- ✅ Reasonable file size
**Cons:**
+
- ❌ Not scalable
- ❌ Larger than SVG
### **SVG Export**
**Recommended settings:**
+
```
Format: SVG
Background: Transparent
@@ -117,17 +131,20 @@ Embed fonts: Yes (for portability)
```
**When to use:**
+
- Scalable documentation
- Print materials
- High-resolution needs
- Technical diagrams
**Pros:**
+
- ✅ Infinitely scalable
- ✅ Smaller file size
- ✅ Crisp at any size
**Cons:**
+
- ❌ Some tools don't support
- ❌ More complex
@@ -153,6 +170,7 @@ C-Scenarios/[scenario-name]/
### **Naming Conventions**
**Pattern:**
+
```
[descriptive-name].excalidraw ← Source
[descriptive-name].png ← PNG export
@@ -160,6 +178,7 @@ C-Scenarios/[scenario-name]/
```
**Examples:**
+
```
✅ dashboard.excalidraw / dashboard.png
✅ login-page.excalidraw / login-page.png
@@ -173,6 +192,7 @@ C-Scenarios/[scenario-name]/
### **Versions**
**Option A: Numbered versions**
+
```
dashboard-v1.excalidraw
dashboard-v1.png
@@ -183,6 +203,7 @@ dashboard-final.png
```
**Option B: Git history (recommended)**
+
```
dashboard.excalidraw ← Always latest
dashboard.png ← Always latest
@@ -196,11 +217,13 @@ Git history shows all versions
### **In Markdown Files**
**Basic image:**
+
```markdown

```
**With link to source:**
+
```markdown
## Dashboard Design
@@ -210,28 +233,34 @@ Git history shows all versions
```
**With caption:**
+
```markdown

-*Dashboard showing today's tasks with card-based layout*
+_Dashboard showing today's tasks with card-based layout_
```
**Multiple images:**
+
```markdown
## Layout Options
### Option A: Card-Based
+

### Option B: List-Based
+

### Option C: Calendar-Focused
+

```
### **In Specifications**
**Example:**
+
```markdown
# Dashboard Page Specification
@@ -244,6 +273,7 @@ Git history shows all versions
## Layout Structure
The dashboard follows a card-based layout with:
+
- Header: Logo, menu, add button
- Content: Today's tasks in card format
- Footer: Bottom navigation
@@ -274,19 +304,19 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
-
+
- name: Setup Node
uses: actions/setup-node@v3
-
+
- name: Install CLI
run: npm install -g @excalidraw/cli
-
+
- name: Export files
run: |
find . -name "*.excalidraw" | while read file; do
excalidraw-cli export "$file" --output "${file%.excalidraw}.png"
done
-
+
- name: Commit
run: |
git config user.name "GitHub Action"
@@ -307,22 +337,26 @@ jobs:
### **DO ✅**
**Always export:**
+
- Export after every significant change
- Keep exports in sync with source
- Use consistent naming
- Commit both source and export
**Choose right format:**
+
- PNG for most documentation
- SVG for scalable needs
- Both if unsure
**Organize well:**
+
- Keep exports with sources
- Use descriptive names
- Follow naming conventions
**Document in markdown:**
+
- Show image inline
- Link to source file
- Add helpful captions
@@ -330,6 +364,7 @@ jobs:
### **DON'T ❌**
**Don't:**
+
- Commit only PNG (lose editability)
- Commit only .excalidraw (won't show in GitHub)
- Use inconsistent naming
@@ -346,6 +381,7 @@ jobs:
**Issue:** PNG export is low resolution
**Solution:**
+
```
1. Check export scale (use 2x)
2. Ensure source is high quality
@@ -357,6 +393,7 @@ jobs:
**Issue:** PNG files are huge
**Solution:**
+
```
1. Use SVG instead
2. Reduce export scale
@@ -369,6 +406,7 @@ jobs:
**Issue:** Image link broken in markdown
**Solution:**
+
```
1. Check file path is correct
2. Use relative paths (./sketches/file.png)
@@ -381,6 +419,7 @@ jobs:
**Issue:** Export menu not visible
**Solution:**
+
```
VS Code: Hamburger menu → Export image
Web: File menu → Export image
@@ -394,18 +433,21 @@ Desktop: File → Export
### **Export Checklist**
**Before exporting:**
+
- [ ] Sketch is complete
- [ ] All elements labeled
- [ ] Grid alignment checked
- [ ] Annotations added
**During export:**
+
- [ ] Choose correct format (PNG/SVG)
- [ ] Set appropriate scale (2x for PNG)
- [ ] Use descriptive filename
- [ ] Save to correct folder
**After exporting:**
+
- [ ] Verify export looks good
- [ ] Update markdown references
- [ ] Commit both source and export
@@ -418,6 +460,7 @@ Desktop: File → Export
### **Example 1: Single Page**
**Files:**
+
```
sketches/
├── dashboard.excalidraw
@@ -425,6 +468,7 @@ sketches/
```
**In specifications.md:**
+
```markdown
# Dashboard Specification
@@ -435,6 +479,7 @@ sketches/
### **Example 2: Multiple Variations**
**Files:**
+
```
sketches/
├── dashboard-cards.excalidraw
@@ -446,18 +491,22 @@ sketches/
```
**In specifications.md:**
+
```markdown
# Dashboard Options
## Option A: Card-Based
+

[Edit](./sketches/dashboard-cards.excalidraw)
## Option B: List-Based
+

[Edit](./sketches/dashboard-list.excalidraw)
## Option C: Calendar-Focused
+

[Edit](./sketches/dashboard-calendar.excalidraw)
```
@@ -465,6 +514,7 @@ sketches/
### **Example 3: States**
**Files:**
+
```
sketches/
├── button-states.excalidraw
@@ -472,6 +522,7 @@ sketches/
```
**In specifications.md:**
+
```markdown
# Button Component
@@ -481,6 +532,7 @@ sketches/
[Edit](./sketches/button-states.excalidraw)
The button has 5 states:
+
- Default: Blue background, white text
- Hover: Darker blue, slight scale
- Active: Even darker, pressed appearance
@@ -493,6 +545,7 @@ The button has 5 states:
## Next Steps
**After exporting:**
+
1. ✅ PNG/SVG created
2. ✅ Files organized
3. ✅ Markdown updated
@@ -500,6 +553,7 @@ The button has 5 states:
5. ✅ Visible in GitHub
**Continue to:**
+
- Phase 4C: Create specifications
- Use exports in documentation
- Share with team
diff --git a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/sketching-guide.md b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/sketching-guide.md
index 6528d442..0cc089b7 100644
--- a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/sketching-guide.md
+++ b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/sketching-guide.md
@@ -9,12 +9,14 @@
### **During Phase 4: UX Design**
**Step 4B: Sketch Interface**
+
- After scenario initialization
- Before detailed specifications
- When exploring layout options
- When discussing with AI
**Typical timing:**
+
```
Scenario Init → Sketch → AI Discussion → Refine → Specify
```
@@ -28,6 +30,7 @@ Scenario Init → Sketch → AI Discussion → Refine → Specify
**Purpose:** Show overall page structure
**Include:**
+
- Device frame (mobile/tablet/desktop)
- Major sections (header, content, footer)
- Component placement
@@ -35,6 +38,7 @@ Scenario Init → Sketch → AI Discussion → Refine → Specify
- Spacing and alignment
**Example:**
+
```
[Mobile Frame 375x812]
┌─────────────────┐
@@ -60,12 +64,14 @@ Scenario Init → Sketch → AI Discussion → Refine → Specify
**Purpose:** Explore different design options
**Include:**
+
- 2-3 layout alternatives
- Different component arrangements
- Hierarchy variations
- Spacing options
**Example:**
+
```
Option A: Card-based
Option B: List-based
@@ -77,6 +83,7 @@ Option C: Calendar-focused
**Purpose:** Show navigation and state transitions
**Include:**
+
- Start and end points
- Decision points
- Actions and outcomes
@@ -84,6 +91,7 @@ Option C: Calendar-focused
- Success paths
**Example:**
+
```
[Start] → [Login] → [Dashboard]
↓
@@ -95,6 +103,7 @@ Option C: Calendar-focused
**Purpose:** Show component in different states
**Include:**
+
- Default state
- Hover state
- Active/focused state
@@ -104,6 +113,7 @@ Option C: Calendar-focused
- Success state
**Example:**
+
```
Button States:
[Default] [Hover] [Active] [Disabled] [Loading]
@@ -114,6 +124,7 @@ Button States:
**Purpose:** Show design across breakpoints
**Include:**
+
- Mobile (375px)
- Tablet (768px)
- Desktop (1440px)
@@ -127,6 +138,7 @@ Button States:
### **Step 1: Choose Device Frame (2 min)**
**From library or create:**
+
```
Mobile: 375 × 812 (iPhone)
Tablet: 768 × 1024 (iPad)
@@ -134,6 +146,7 @@ Desktop: 1440 × 900 (Laptop)
```
**Draw rectangle:**
+
- Use Rectangle tool (R)
- Set dimensions
- Label device type
@@ -142,6 +155,7 @@ Desktop: 1440 × 900 (Laptop)
### **Step 2: Add Major Sections (5 min)**
**Divide into regions:**
+
```
Header: Top 60-80px
Content: Middle (flexible)
@@ -149,6 +163,7 @@ Footer: Bottom 60-80px
```
**Use rectangles:**
+
- Light fill color
- Label each section
- Snap to 20px grid
@@ -157,6 +172,7 @@ Footer: Bottom 60-80px
### **Step 3: Add Components (10 min)**
**From library or draw:**
+
- Buttons
- Input fields
- Cards
@@ -165,6 +181,7 @@ Footer: Bottom 60-80px
- Text blocks
**Placement:**
+
- Follow grid (20px)
- Consistent spacing
- Visual hierarchy
@@ -173,12 +190,14 @@ Footer: Bottom 60-80px
### **Step 4: Add Labels (5 min)**
**Label everything:**
+
- Component names
- Interactive elements
- Content areas
- Actions
**Use text tool (T):**
+
- Clear, concise labels
- Inside or beside components
- Consistent font size
@@ -187,12 +206,14 @@ Footer: Bottom 60-80px
### **Step 5: Add Annotations (5 min)**
**Document decisions:**
+
- Why this layout?
- Key interactions
- Important notes
- Questions/concerns
**Use:**
+
- Text boxes
- Arrows pointing to elements
- Different color for notes
@@ -201,6 +222,7 @@ Footer: Bottom 60-80px
### **Step 6: Review and Refine (5 min)**
**Check:**
+
- ✓ All elements aligned to grid
- ✓ Consistent spacing
- ✓ Clear labels
@@ -215,6 +237,7 @@ Footer: Bottom 60-80px
### **Pattern 1: Top-Down**
**Start with structure, add details:**
+
```
1. Device frame
2. Major sections
@@ -229,6 +252,7 @@ Footer: Bottom 60-80px
### **Pattern 2: Component-First**
**Start with key component, build around:**
+
```
1. Main component (e.g., task list)
2. Supporting components
@@ -242,6 +266,7 @@ Footer: Bottom 60-80px
### **Pattern 3: Flow-Based**
**Follow user journey:**
+
```
1. Entry point
2. First action
@@ -259,6 +284,7 @@ Footer: Bottom 60-80px
### **20px Grid System**
**Everything snaps to 20px:**
+
```
Position: 0, 20, 40, 60, 80, 100...
Size: 80, 100, 120, 140, 160...
@@ -268,16 +294,19 @@ Spacing: 20, 40, 60, 80...
### **Common Spacing**
**Tight:** 20px
+
- Between related items
- Inside cards
- Form field spacing
**Medium:** 40px
+
- Between sections
- Card margins
- Component groups
**Loose:** 60-80px
+
- Major sections
- Page margins
- Visual breaks
@@ -285,15 +314,18 @@ Spacing: 20, 40, 60, 80...
### **Component Sizes**
**Buttons:**
+
- Small: 80 × 32
- Medium: 120 × 40
- Large: 160 × 48
**Input Fields:**
+
- Width: 280-320 (mobile), 400+ (desktop)
- Height: 40-48
**Cards:**
+
- Width: 320 (mobile), 400+ (desktop)
- Height: Variable (content-based)
@@ -304,6 +336,7 @@ Spacing: 20, 40, 60, 80...
### **Size**
**Larger = More important:**
+
```
Heading: 24-32px
Body: 16-18px
@@ -313,6 +346,7 @@ Caption: 12-14px
### **Weight**
**Bolder = More important:**
+
```
Primary: Bold/Semibold
Secondary: Regular
@@ -322,6 +356,7 @@ Tertiary: Light
### **Position**
**Top/Left = More important:**
+
```
Most important: Top-left
Secondary: Center
@@ -331,6 +366,7 @@ Least important: Bottom-right
### **Color/Contrast**
**Higher contrast = More important:**
+
```
Primary: Dark on light (high contrast)
Secondary: Medium gray
@@ -344,36 +380,42 @@ Tertiary: Light gray
### **❌ DON'T:**
**1. Skip the grid**
+
```
❌ Random positioning
✅ Snap to 20px grid
```
**2. Inconsistent spacing**
+
```
❌ 15px, 23px, 18px...
✅ 20px, 40px, 60px...
```
**3. Unlabeled elements**
+
```
❌ [Rectangle]
✅ [Login Button]
```
**4. Too much detail**
+
```
❌ Pixel-perfect designs
✅ Rough wireframes
```
**5. No annotations**
+
```
❌ Just shapes
✅ Shapes + notes about why
```
**6. Forget device context**
+
```
❌ Generic layout
✅ Mobile/tablet/desktop frame
@@ -388,6 +430,7 @@ Tertiary: Light gray
**Pattern:** `[page-name].excalidraw`
**Examples:**
+
```
dashboard.excalidraw
login-page.excalidraw
@@ -399,11 +442,13 @@ button-states.excalidraw
### **Location**
**Always in sketches folder:**
+
```
C-Scenarios/[scenario-name]/sketches/
```
**Example:**
+
```
C-Scenarios/morning-dog-care/
├── sketches/
@@ -418,6 +463,7 @@ C-Scenarios/morning-dog-care/
### **Versions**
**Iterations:**
+
```
dashboard-v1.excalidraw
dashboard-v2.excalidraw
@@ -425,6 +471,7 @@ dashboard-final.excalidraw
```
**Or use git:**
+
```
dashboard.excalidraw (always latest)
Git history shows versions
@@ -437,11 +484,13 @@ Git history shows versions
### **AI Can Generate Sketches**
**Request:**
+
```
"Create 3 dashboard layout options in Excalidraw"
```
**AI creates:**
+
```
dashboard-cards.excalidraw
dashboard-list.excalidraw
@@ -449,6 +498,7 @@ dashboard-calendar.excalidraw
```
**You:**
+
- Open each option
- Compare and choose
- Refine the winner
@@ -456,6 +506,7 @@ dashboard-calendar.excalidraw
### **AI Can Analyze Your Sketches**
**Process:**
+
```
1. Export sketch to PNG
2. Upload to AI
@@ -465,6 +516,7 @@ dashboard-calendar.excalidraw
```
**Example:**
+
```
You: [Upload dashboard.png]
"What do you think?"
@@ -476,6 +528,7 @@ AI: "I see you've prioritized today's tasks at top.
### **AI Can Iterate**
**Feedback loop:**
+
```
You: "Make the cards bigger with more breathing room"
AI: [Generates dashboard-v2.excalidraw]
@@ -490,26 +543,31 @@ AI: [Generates dashboard-calendar.excalidraw]
### **DO ✅**
**Start rough:**
+
- Quick shapes
- Basic layout
- Refine later
**Use the grid:**
+
- Snap everything
- Consistent spacing
- Professional look
**Label clearly:**
+
- Name all components
- Describe interactions
- Note important details
**Annotate decisions:**
+
- Why this layout?
- What alternatives considered?
- What questions remain?
**Keep it simple:**
+
- Wireframes, not mockups
- Structure, not style
- Concepts, not pixels
@@ -517,21 +575,25 @@ AI: [Generates dashboard-calendar.excalidraw]
### **DON'T ❌**
**Don't over-design:**
+
- Not pixel-perfect
- Not final styling
- Not production-ready
**Don't skip context:**
+
- Always use device frame
- Show realistic content
- Include navigation
**Don't forget states:**
+
- Show hover/active
- Show error states
- Show loading states
**Don't work in isolation:**
+
- Share with AI
- Get feedback
- Iterate together
@@ -614,6 +676,7 @@ Annotations:
## Next Steps
**After sketching:**
+
1. ✅ Export to PNG
2. ✅ Upload to AI for discussion
3. ✅ Iterate based on feedback
@@ -621,6 +684,7 @@ Annotations:
5. ✅ Create specifications
**Learn more:**
+
- [AI Collaboration](ai-collaboration.md) - Work with AI
- [Export Workflow](export-workflow.md) - Share your work
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md
index d24367a6..dec1492b 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md
@@ -7,6 +7,7 @@
## Foundation (00-)
### [Agent-Designer Collaboration](00-foundation/agent-designer-collaboration.md)
+
How AI agents optimize designer craft without replacing designer thinking
---
@@ -14,12 +15,15 @@ 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
---
@@ -27,12 +31,15 @@ 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
---
@@ -40,12 +47,15 @@ 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
---
@@ -53,7 +63,9 @@ 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
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/00-foundation/agent-designer-collaboration.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/00-foundation/agent-designer-collaboration.md
index d1efbebb..fc80096b 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/00-foundation/agent-designer-collaboration.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/00-foundation/agent-designer-collaboration.md
@@ -16,21 +16,25 @@
## 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
@@ -42,6 +46,7 @@
## What Agents DO Brilliantly
✅ **Systematic decomposition**
+
```
Designer: "This calendar is complex"
Agent: "I detect 6 states, time-based transitions, business rules.
@@ -52,6 +57,7 @@ Agent: "I detect 6 states, time-based transitions, business rules.
```
✅ **Pattern recognition**
+
```
Designer: "I'm adding body text here"
Agent: "I notice on Start Page, body text was 16px with 1.5 line-height.
@@ -59,6 +65,7 @@ Agent: "I notice on Start Page, body text was 16px with 1.5 line-height.
```
✅ **Documentation assistance**
+
```
Designer: "The walk slot has different colors"
Agent: "Let me capture that systematically:
@@ -71,6 +78,7 @@ Agent: "Let me capture that systematically:
```
✅ **Workflow guidance**
+
```
Designer: "Where should I document this content?"
Agent: "Does the content vary by page context?
@@ -79,6 +87,7 @@ Agent: "Does the content vary by page context?
```
✅ **Cross-reference tracking**
+
```
Designer: "I updated the button color"
Agent: "This button appears on 5 pages. Should I update all references?"
@@ -91,6 +100,7 @@ Agent: "This button appears on 5 pages. Should I update all references?"
### Phase 1: Designer Thinks
**Designer decides:**
+
- Business goals for this page
- User needs to serve
- Product strategy to implement
@@ -104,6 +114,7 @@ Agent: "This button appears on 5 pages. Should I update all references?"
### Phase 2: Agent Guides Decomposition
**Agent asks systematic questions:**
+
```
"I see this sketch. Let me identify sections:
1. Navigation Header
@@ -116,12 +127,14 @@ Does this match your vision?"
```
**Designer confirms, corrects, adds context:**
+
```
-"Yes, but the Calendar is the core feature.
+"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."
@@ -132,6 +145,7 @@ 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.
@@ -139,6 +153,7 @@ This needs to feel playful, not punishing."
```
**Agent captures systematically:**
+
```
"Capturing:
- 6 visual states (storyboard reference)
@@ -156,6 +171,7 @@ Should I create:
### 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'.
@@ -163,6 +179,7 @@ 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."
@@ -173,17 +190,19 @@ 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.
+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."
@@ -196,17 +215,19 @@ Let's specify it properly."
### 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?"
```
@@ -215,18 +236,20 @@ Agent: "I see a calendar. Should this be:
### 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'?"
```
@@ -235,18 +258,20 @@ Agent: "I notice the walk slot needs a color for 'countdown active' state.
### 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."
```
@@ -255,10 +280,11 @@ Agent: "Does the hero heading change per page?
### 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?"
```
@@ -267,15 +293,17 @@ Agent: "I notice you prefer detailed specifications for user-facing components
### 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?"
```
@@ -286,29 +314,31 @@ Agent: "I notice on Start Page, buttons are 48px height.
**Agent notices patterns and asks for reasoning:**
```
-Agent: "Help me understand: The header has two buttons -
- 'Book Walk' and 'Add Walk'.
-
+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.
+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
+
+ 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
+
+ Should I document this distinction in the Feature file
so developers understand the different workflows?"
```
@@ -329,18 +359,19 @@ Agent: "Let me help you think through this. Pros and cons:
✅ 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,
+
+ 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
@@ -348,12 +379,13 @@ Designer: "You're right - Swedish families think in weeks.
```
**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."
```
@@ -364,22 +396,27 @@ Agent: "Perfect! Documenting:
### 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
@@ -388,18 +425,22 @@ Agent: "Perfect! Documenting:
### 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
@@ -410,6 +451,7 @@ Agent: "Perfect! Documenting:
**Agents don't replace designers.**
**Agents optimize designer craft by:**
+
- Handling systematic work
- Ensuring consistency
- Guiding structured workflows
@@ -417,6 +459,7 @@ Agent: "Perfect! Documenting:
- Documenting decisions
**This frees designers to:**
+
- Think strategically
- Make creative decisions
- Solve complex problems
@@ -424,6 +467,7 @@ Agent: "Perfect! Documenting:
- Balance competing priorities
**The result:**
+
- 10x faster specification
- 10x better consistency
- 10x more complete documentation
@@ -436,6 +480,7 @@ Agent: "Perfect! Documenting:
## Related Concepts
### [Why-Based Specifications](../WHY-BASED-SPECIFICATIONS.md)
+
How capturing WHY (not just WHAT) makes AI implementation correct
---
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/complexity-detection.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/complexity-detection.md
index d5793593..f7d659cc 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/complexity-detection.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/complexity-detection.md
@@ -12,6 +12,7 @@
- ✅ No business logic
**Examples:**
+
- Static text
- Image
- Basic button (just click → navigate)
@@ -30,6 +31,7 @@
- ⚠️ State machines (defined transition paths)
**Examples:**
+
- Calendar widget (6 states)
- Search with autocomplete (5+ states)
- Multi-step form (progress tracking)
@@ -44,6 +46,7 @@
### Example 1: Simple Button
**Indicators:**
+
- ✅ Single interaction (click → navigate)
- ✅ 2-3 states (default, hover, active)
- ❌ No business logic
@@ -56,6 +59,7 @@
### 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)
@@ -69,6 +73,7 @@
### Example 3: Calendar Widget
**Indicators:**
+
- ⚠️ 6 walk states
- ⚠️ Time-based transitions (countdown timers)
- ⚠️ Complex business rules (per-dog blocking)
@@ -83,6 +88,7 @@
## When to Decompose
**Decompose when component has:**
+
- 3+ visual states
- Business rules
- API dependencies
@@ -90,12 +96,14 @@
- 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)
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/content-placement-rules.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/content-placement-rules.md
index e40e77d6..12abb7ad 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/content-placement-rules.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/content-placement-rules.md
@@ -21,20 +21,24 @@ Does CONTENT vary by page context?
## 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)
@@ -48,25 +52,30 @@ 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"
```
@@ -76,19 +85,23 @@ Pages/02-about-page.md → "About Dog Week"
## 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
@@ -109,18 +122,18 @@ Pages/02-about-page.md → "About Dog Week"
## 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 |
+| 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 |
---
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/three-tier-overview.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/three-tier-overview.md
index 893f8e25..6a887e81 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/three-tier-overview.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/three-tier-overview.md
@@ -7,9 +7,11 @@
## 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)
@@ -17,8 +19,10 @@
- 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
@@ -29,9 +33,11 @@ Pages/02-calendar-page.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)
@@ -40,8 +46,10 @@ Pages/02-calendar-page.md
- ❌ 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.
@@ -51,9 +59,11 @@ Components/walk-slot-card.component.md
---
### 3. Features/ (WHAT IT DOES)
+
**Purpose:** Functional logic and business rules
**Contains:**
+
- User interactions
- Business rules
- State management
@@ -63,8 +73,10 @@ Components/walk-slot-card.component.md
- ❌ 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
@@ -77,6 +89,7 @@ Features/walk-booking-logic.feature.md
## Why Three Tiers?
### Before (Monolithic)
+
```
Pages/02-calendar-page.md (800 lines)
├─ Everything mixed together
@@ -86,6 +99,7 @@ Pages/02-calendar-page.md (800 lines)
```
### After (Modular)
+
```
Pages/02-calendar-page.md (100 lines)
├─ Just placement + user context
@@ -104,16 +118,19 @@ Features/walk-booking-logic.feature.md (200 lines)
## 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
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-what-are-storyboards.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-what-are-storyboards.md
index b3887212..38701f78 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-what-are-storyboards.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-what-are-storyboards.md
@@ -7,6 +7,7 @@
## Definition
A **storyboard** is a visual sequence showing:
+
- State transitions (empty → loading → active → completed)
- User interactions (click, type, swipe)
- System responses (updates, animations, feedback)
@@ -17,11 +18,13 @@ A **storyboard** is a visual sequence showing:
## 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
@@ -31,6 +34,7 @@ A **storyboard** is a visual sequence showing:
## Purpose
Storyboards answer:
+
- "What does this look like in each state?"
- "How do users move between states?"
- "What triggers each transition?"
@@ -41,12 +45,14 @@ Storyboards answer:
## Why Visual?
**Text description:**
+
```
-When the user books a walk, the card changes to gray,
+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"
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-when-to-use.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-when-to-use.md
index 89ad1911..3ad10f4c 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-when-to-use.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-when-to-use.md
@@ -7,18 +7,23 @@
## 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
---
@@ -26,12 +31,15 @@
## 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
---
@@ -39,12 +47,14 @@
## 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)
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/02-file-structure.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/02-file-structure.md
index 8396cbb0..39cceff1 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/02-file-structure.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/02-file-structure.md
@@ -30,6 +30,7 @@ project-root/
## Why Features/Storyboards/?
Storyboards document **functionality**, not visual design:
+
- State transitions (functional)
- User interactions (functional)
- Business logic flows (functional)
@@ -41,6 +42,7 @@ Therefore, they belong with **Features**, not Components.
## Reference Pattern
**From Feature File:**
+
```markdown
Features/walk-booking-logic.feature.md
@@ -50,6 +52,7 @@ Features/walk-booking-logic.feature.md
```
**From Component File:**
+
```markdown
Components/walk-slot-card.component.md
@@ -64,11 +67,13 @@ See storyboard for state transitions:
## 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
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/complexity-router-workflow.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/complexity-router-workflow.md
index 29be6ce5..96573354 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/complexity-router-workflow.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/complexity-router-workflow.md
@@ -26,6 +26,7 @@ When a complex component is detected, the agent guides you through 3 steps:
6. **Does DATA source change based on page context?**
**You answer, agent captures:**
+
- Pages list
- Position
- Size
@@ -49,6 +50,7 @@ When a complex component is detected, the agent guides you through 3 steps:
- Can it transition to other states?
**You answer, agent captures:**
+
- State count
- State definitions
- Storyboard reference (if exists)
@@ -69,6 +71,7 @@ When a complex component is detected, the agent guides you through 3 steps:
5. Does it update other components?
**You answer, agent captures:**
+
- User actions
- System responses
- Business rules
@@ -88,6 +91,7 @@ See: [Coaching Dialogue Example](examples/coaching-dialogue.md)
## Output: Three Files
**1. Page File**
+
```markdown
Pages/02-calendar-page.md
@@ -96,33 +100,40 @@ Pages/02-calendar-page.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
```
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/page-specification-workflow.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/page-specification-workflow.md
index ea2cace7..624157f5 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/page-specification-workflow.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/page-specification-workflow.md
@@ -15,6 +15,7 @@ The agent guides you through specifying a page **from top to bottom**, one secti
### Step 1: Identify All Sections
**Agent analyzes sketch and outputs:**
+
```
📋 Page Sections Detected:
@@ -28,6 +29,7 @@ Does this match your sketch? Any sections missing or incorrectly identified?
```
**You respond:**
+
- Confirm sections
- Add missing sections
- Rename sections
@@ -38,6 +40,7 @@ Does this match your sketch? Any sections missing or incorrectly identified?
### Step 2: Section Purpose
**For each section, agent asks:**
+
```
📍 Section: Navigation Header
@@ -49,11 +52,13 @@ What is the purpose of this section?
```
**You respond:**
+
```
"User navigation and branding. Shows logo, main menu, and user profile."
```
**Agent captures:**
+
```markdown
## Navigation Header
@@ -66,6 +71,7 @@ What is the purpose of this section?
### Step 3: List Objects in Section
**Agent outputs:**
+
```
🔍 Objects in Navigation Header:
@@ -77,6 +83,7 @@ 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
@@ -85,6 +92,7 @@ Shall I specify each object, or is this section simple enough to keep schematic?
### Step 4: Decompose Containers
**If object is a container, agent asks:**
+
```
📦 Main Menu (Container)
@@ -98,13 +106,16 @@ 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
@@ -116,6 +127,7 @@ Are these simple links, or do any need detailed specs?
### Step 5: Specify Atomic Components
**When reaching smallest parts:**
+
```
🔬 User Profile (Dropdown)
@@ -128,6 +140,7 @@ 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
@@ -139,18 +152,21 @@ C) Skip for now, mark as TODO
### 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)
@@ -161,6 +177,7 @@ 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?"
@@ -168,6 +185,7 @@ You: "Yes, decompose it"
```
**Step 5: Calendar Section**
+
```
Agent: "Calendar has 6 walk states, countdown timers, business rules.
This is highly complex. Should I:
@@ -183,16 +201,19 @@ You: "Yes, decompose and reference storyboard"
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"
@@ -204,16 +225,20 @@ 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
@@ -221,26 +246,31 @@ Pages/02-calendar-page.md
```
### 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
@@ -262,12 +292,14 @@ Pages/02-calendar-page.md
## 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)
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/storyboards-guide.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/storyboards-guide.md
index bc413190..55311f64 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/storyboards-guide.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/storyboards-guide.md
@@ -7,12 +7,15 @@
## 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
---
@@ -20,9 +23,11 @@ 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
---
@@ -30,9 +35,11 @@ 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
---
@@ -40,9 +47,11 @@ 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
---
@@ -50,9 +59,11 @@ 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
---
@@ -60,4 +71,5 @@ Multi-step interaction storyboard
## Benefits
### [Why Storyboards Work](benefits.md)
+
Developer clarity, QA testing, design consistency
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/benefits.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/benefits.md
index 862c5516..e2e2f6bb 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/benefits.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/benefits.md
@@ -7,11 +7,13 @@
## 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
@@ -21,16 +23,19 @@
## 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
@@ -43,7 +48,8 @@
**Cause:** Monolithic spec, developer overwhelmed
-**Solution:**
+**Solution:**
+
- Component file lists ALL visual elements
- Feature file lists ALL interactions
- Storyboard shows ALL states
@@ -56,11 +62,13 @@
**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
@@ -96,6 +104,7 @@ Everyone works in parallel, no conflicts.
## 7. Design System Integrity
**Page files** reference components:
+
```markdown
**Component:** button-primary.component.md
```
@@ -113,6 +122,7 @@ Easy to update design system globally.
**Over product lifecycle:** 100+ hours
**Quality improvement:**
+
- Zero missing features
- Consistent design
- Maintainable codebase
diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/decision-tree.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/decision-tree.md
index 4c45a36c..9964f3f1 100644
--- a/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/decision-tree.md
+++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/decision-tree.md
@@ -34,12 +34,14 @@
## 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)
diff --git a/src/modules/wds/workflows/4-ux-design/object-types/COMPLEXITY-ROUTER.md b/src/modules/wds/workflows/4-ux-design/object-types/COMPLEXITY-ROUTER.md
index a3ad8468..f9ed68eb 100644
--- a/src/modules/wds/workflows/4-ux-design/object-types/COMPLEXITY-ROUTER.md
+++ b/src/modules/wds/workflows/4-ux-design/object-types/COMPLEXITY-ROUTER.md
@@ -21,12 +21,14 @@
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)
@@ -35,9 +37,10 @@
- State machines (defined transition paths)
**Examples:**
+
- **Simple:** Static text, image, basic button
- **Complex:** Calendar widget, booking system, search with filters, multi-step form
-
+
---
@@ -52,6 +55,7 @@
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)
@@ -75,10 +79,12 @@ I see this {{object_name}} has multiple states and interactions. Let me help you
**Complexity Indicators I Found:**
{{#each complexity_indicators}}
+
- {{indicator_description}}
-{{/each}}
+ {{/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
@@ -102,9 +108,9 @@ Choice [1/2]:
-
- Route to standard object-type file
- Document in Page file only
+
+Route to standard object-type file
+Document in Page file only
@@ -116,6 +122,7 @@ Choice [1/2]:
---
**Return to 4c-03 to continue with next object**
-
diff --git a/src/modules/wds/workflows/4-ux-design/object-types/heading-text.md b/src/modules/wds/workflows/4-ux-design/object-types/heading-text.md
index 3347b2f3..ef9beb15 100644
--- a/src/modules/wds/workflows/4-ux-design/object-types/heading-text.md
+++ b/src/modules/wds/workflows/4-ux-design/object-types/heading-text.md
@@ -9,10 +9,11 @@
**Analyzing text element from sketch...**First, check if sketch contains ACTUAL TEXT (readable words):
+
- Headlines often drawn as actual text
- Provides content guidance
- Can change during conversation
-
+
Extract text from sketch
@@ -31,21 +32,22 @@ I can use this as a starting suggestion, but we can change it if needed.
- **Text placeholder detected:**
+**Text placeholder detected:**
- **Sketch Analysis:**
- - **{{line_count}} line pairs** → {{line_count}} lines of text
- - **Line thickness:** {{thickness}} → **{{estimated_font_weight}}**
- - **Line spacing:** {{distance_between_lines}} → **~{{estimated_font_size}}** font size
- - **Line-height:** ~{{estimated_line_height}} (calculated from font size)
- - **Alignment:** {{detected_alignment}} (from line position)
- - **Capacity:** ~{{total_chars}} characters per line
+**Sketch Analysis:**
- **This appears to be:** {{text_type}} (heading/body/caption/label)
+- **{{line_count}} line pairs** → {{line_count}} lines of text
+- **Line thickness:** {{thickness}} → **{{estimated_font_weight}}**
+- **Line spacing:** {{distance_between_lines}} → **~{{estimated_font_size}}** font size
+- **Line-height:** ~{{estimated_line_height}} (calculated from font size)
+- **Alignment:** {{detected_alignment}} (from line position)
+- **Capacity:** ~{{total_chars}} characters per line
- ⚠️ **Note:** If spacing is very large (>60px), verify this is text and not an image placeholder.
-
- 💡 **Analysis rules:** See `SKETCH-TEXT-ANALYSIS-GUIDE.md` for complete methodology.
+**This appears to be:** {{text_type}} (heading/body/caption/label)
+
+⚠️ **Note:** If spacing is very large (>60px), verify this is text and not an image placeholder.
+
+💡 **Analysis rules:** See `SKETCH-TEXT-ANALYSIS-GUIDE.md` for complete methodology.
---
@@ -57,6 +59,7 @@ I can use this as a starting suggestion, but we can change it if needed.**What is the PURPOSE of this text on the page?**
Think about function, not content:
+
- "Primary headline" (not "Welcome to Dog Week")
- "Feature description" (not "Organize your family")
- "CTA supporting text" (not "Free forever")
@@ -75,10 +78,11 @@ Purpose/function:
`{page}-{section}-{purpose}`
Examples:
+
- `start-hero-headline` (not `start-hero-welcome-text`)
- `signin-form-email-label` (not `signin-form-email-address-text`)
- `profile-success-message` (not `profile-saved-successfully-text`)
-
+
**Object ID:** `{{generated_object_id}}`
@@ -100,13 +104,13 @@ Choice [1/2/3]:
**Which existing typography component?**
- From your Design System:
- {{list_available_typography_components}}
+From your Design System:
+{{list_available_typography_components}}
- Component name:
-
- Store design_system_component
- Store component_status = "existing"
+Component name:
+
+Store design_system_component
+Store component_status = "existing"
@@ -137,6 +141,7 @@ Choice [1/2/3]:
**Text element specifications:**
**HTML Tag** (semantic structure for SEO/accessibility):
+
- h1 (main page heading, only ONE per page)
- h2 (major section heading)
- h3 (subsection heading)
@@ -147,6 +152,7 @@ Choice [1/2/3]:
HTML tag:
**Visual Style Type** (appearance, from Design System):
+
- Hero headline (large display text for hero sections)
- Main header (primary page/section headers)
- Sub header (section headings, emphasized)
@@ -164,11 +170,13 @@ Visual style name:
> **Important:** HTML tags define document structure. Visual styles define appearance. Keep them separate!
**Position on page:**
+
- Vertical: (top/middle/bottom of section)
- Horizontal: (left/center/right)
- Relative to: (e.g., "above CTA button", "below headline")
**Text Alignment** (from sketch line position):
+
- left (lines start at left edge)
- center (lines centered in container)
- right (lines end at right edge)
@@ -177,12 +185,13 @@ Visual style name:
Alignment:
**Style specifications:**
+
- Font size: {{estimated_font_size}} (est. from {{line_spacing}} spacing in sketch)
- Font weight: {{estimated_font_weight}} (from {{line_thickness}} line thickness in sketch)
- Line height: {{estimated_line_height}} (est. calculated from font size)
- Text color:
- Text transform: (none/uppercase/capitalize)
-
+
Store html_tag, visual_type, visual_style_name, position, and style specifications
@@ -205,11 +214,11 @@ Content length: ~{{total_chars}} characters (from sketch analysis)
**I found text in your sketch:** "{{extracted_text}}"
Let me suggest translations for all configured languages...
-
- Translate extracted_text to all product_languages
- Generate suggested translations using context and best practices
-
- **Suggested content for {{text_purpose}}:**
+
+Translate extracted_text to all product_languages
+Generate suggested translations using context and best practices
+
+**Suggested content for {{text_purpose}}:**
{{#each product_languages}}
**{{this}}:** {{suggested_translation}}
@@ -217,7 +226,7 @@ Let me suggest translations for all configured languages...
These are my suggestions based on the sketch text. Please review and adjust as needed!
- Do these translations work, or would you like to change any of them?
+Do these translations work, or would you like to change any of them?
1. **Use these translations** - They look good!
2. **Adjust translations** - I'll provide different versions
@@ -229,11 +238,11 @@ Choice [1/2/3]:Which language(s) need adjustment?
{{#each product_languages}}
-**{{this}}:** {{suggested_translation}} ← Change this?
+**{{this}}:** {{suggested_translation}} ← Change this?
{{/each}}
Please provide the corrected versions:
-
+
**Content for this {{text_purpose}}:**
@@ -243,7 +252,7 @@ Please provide the corrected versions:
{{/each}}
-
+
@@ -255,9 +264,9 @@ Please provide content. I'll suggest translations once you give me the first lan
- After receiving primary language content, suggest translations for remaining languages
-
- **Translation suggestions:**
+After receiving primary language content, suggest translations for remaining languages
+
+**Translation suggestions:**
{{#each remaining_languages}}
**{{this}}:** {{suggested_translation}}
@@ -304,23 +313,25 @@ If yes, describe behavior:
**OBJECT ID**: `{{object_id}}`
**HTML Structure:**
+
- **Tag**: {{html_tag}}
- **Semantic Purpose**: {{semantic_description}}
**Visual Style:**
{{#if design_system_component}}
+
- **Design System Component**: {{design_system_component}}
-{{/if}}
+ {{/if}}
- **Visual Style Name**: {{visual_style_name}}
- **Font weight**: {{font_weight}} (from {{line_thickness}} line markers in sketch)
- **Font size**: {{font_size}} (est. from {{line_spacing}} spacing between line pairs)
- **Line-height**: {{line_height}} (est. calculated from font size)
-{{#if text_color}}
+ {{#if text_color}}
- **Color**: {{text_color}}
-{{/if}}
-{{#if text_transform}}
+ {{/if}}
+ {{#if text_transform}}
- **Transform**: {{text_transform}}
-{{/if}}
+ {{/if}}
**Position**: {{position_description}}
**Alignment**: {{text_alignment}}
@@ -331,15 +342,19 @@ If yes, describe behavior:
**Content**:
{{#each product_languages}}
+
- {{this}}: "{{content}}"
-{{/each}}
+ {{/each}}
> **Sketch Analysis:** Values derived using `SKETCH-TEXT-ANALYSIS-GUIDE.md` methodology. Designer should review and confirm.
```
- {{#each additional_language}}
- - {{lang_code}}: "{{content}}"
+
+{{#each additional_language}}
+
+- {{lang_code}}: "{{content}}"
{{/each}}
-```
+
+````
---
@@ -364,46 +379,46 @@ Choice [1/2]:
**What other text elements are in this group?**
-
+
List them:
-
+
Mark as text group for grouped translation output
-
+
**Text group will be formatted as:**
-
+
```markdown
### {{Group_Name}}
**Purpose**: {{group_purpose}}
-
+
#### {{Element_1_Purpose}}
**OBJECT ID**: `{{object_id_1}}`
- **Component**: {{type_1}}
- **Content**:
- EN: "{{content_en_1}}"
- SE: "{{content_se_1}}"
-
+
#### {{Element_2_Purpose}}
**OBJECT ID**: `{{object_id_2}}`
- **Component**: {{type_2}}
- **Content**:
- EN: "{{content_en_2}}"
- SE: "{{content_se_2}}"
-
+
#### {{Element_3_Purpose}}
**OBJECT ID**: `{{object_id_3}}`
- **Component**: {{type_3}}
- **Content**:
- EN: "{{content_en_3}}"
- SE: "{{content_se_3}}"
- ```
-
- **Reading in English:**
- {{content_en_1}} + {{content_en_2}} + {{content_en_3}}
-
- **Reading in Swedish:**
- {{content_se_1}} + {{content_se_2}} + {{content_se_3}}
-
- Each language reads as a complete, coherent message!
+````
+
+**Reading in English:**
+{{content_en_1}} + {{content_en_2}} + {{content_en_3}}
+
+**Reading in Swedish:**
+{{content_se_1}} + {{content_se_2}} + {{content_se_3}}
+
+Each language reads as a complete, coherent message!
---
@@ -412,13 +427,16 @@ Choice [1/2]:
```markdown
### Hero Object
+
**Purpose**: Primary value proposition and main conversion action
#### Primary Headline
+
**OBJECT ID**: `start-hero-headline`
+
- **Component**: H1 heading (`.text-heading-1`)
- **Position**: Center of hero section, above CTA
-- **Style**:
+- **Style**:
- Font weight: Bold (from 3px thick line markers)
- Font size: 42px (est. from 24px spacing between line pairs)
- Line-height: 1.2 (est. calculated from font size)
@@ -427,14 +445,17 @@ Choice [1/2]:
- **Content**:
> **Note:** Values marked `(est. from...)` show sketch analysis reasoning. Confirm or adjust, then update with actual values.
- - EN: "Every walk. on time. Every time."
- - SE: "Varje promenad. i tid. Varje gång."
+
+- EN: "Every walk. on time. Every time."
+- SE: "Varje promenad. i tid. Varje gång."
#### Supporting Text
+
**OBJECT ID**: `start-hero-supporting`
+
- **Component**: Body text (`.text-body`)
- **Position**: Below headline, above CTA button
-- **Style**:
+- **Style**:
- Font weight: Regular (from 1px thin line markers)
- Font size: 16px (est. from 12px spacing between line pairs)
- Line-height: 1.5 (est. calculated from font size)
@@ -442,11 +463,14 @@ Choice [1/2]:
- **Content**:
> **Note:** Values marked `(est. from...)` show sketch analysis reasoning. Confirm or adjust, then update with actual values.
- - EN: "Organize your family around dog care. Never miss a walk again."
- - SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen."
+
+- EN: "Organize your family around dog care. Never miss a walk again."
+- SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen."
#### Primary CTA Button
+
**OBJECT ID**: `start-hero-cta`
+
- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md)
- **Position**: Center, below supporting text
- **Behavior**: Navigate to registration/sign-up
@@ -456,11 +480,13 @@ Choice [1/2]:
```
**Reading the Hero in English:**
-> "Every walk. on time. Every time."
+
+> "Every walk. on time. Every time."
> "Organize your family around dog care. Never miss a walk again."
> [start planning - free forever]
**Reading the Hero in Swedish:**
+
> "Varje promenad. i tid. Varje gång."
> "Organisera din familj kring hundvård. Missa aldrig en promenad igen."
> [börja planera - gratis för alltid]
@@ -470,20 +496,24 @@ Choice [1/2]:
## KEY PRINCIPLES
### 1. Purpose-Based Naming ✅
+
**NOT:** `welcome-heading`, `description-paragraph`
**YES:** `hero-headline`, `feature-description`
Names describe FUNCTION, not content.
### 2. Separated Structure ✅
+
- **Position/Style** specified separately
- **Content** grouped by language
- **Behavior** clearly stated
### 3. Grouped Translations ✅
+
Text groups keep languages together so each reads coherently.
### 4. Professional Format ✅
+
Follows Dog Week specification style for consistency across WDS projects.
---
@@ -491,21 +521,25 @@ Follows Dog Week specification style for consistency across WDS projects.
## BENEFITS
✅ **Purpose-Driven**
+
- Object IDs reflect function
- Names remain valid if content changes
- Clear semantic meaning
✅ **Translation-Friendly**
+
- Each language grouped together
- Easy to read entire section in one language
- Natural language flow preserved
✅ **Maintainable**
+
- Content can change without renaming
- Structure remains stable
- Easy to locate by purpose
✅ **Developer-Friendly**
+
- Clear what each text does
- Component references included
- Position clearly stated
diff --git a/src/modules/wds/workflows/4-ux-design/object-types/image.md b/src/modules/wds/workflows/4-ux-design/object-types/image.md
index 10b07eb0..a5d03cfb 100644
--- a/src/modules/wds/workflows/4-ux-design/object-types/image.md
+++ b/src/modules/wds/workflows/4-ux-design/object-types/image.md
@@ -33,13 +33,13 @@ Choice [1/2/3]:
**Which existing image pattern?**
- From your Design System:
- {{list_available_image_patterns}}
+From your Design System:
+{{list_available_image_patterns}}
- Component name:
-
- Store design_system_component
- Store component_status = "existing"
+Component name:
+
+Store design_system_component
+Store component_status = "existing"
@@ -70,23 +70,26 @@ Choice [1/2/3]:
**Image properties:**
**Source:**
+
- Image filename/path:
- Alt text (EN):
- Alt text (SV):
- Is decorative (no alt needed): yes/no
**Dimensions:**
+
- Width:
- Height:
- Aspect ratio:
- Object-fit: (cover/contain/fill)
**Responsive behavior:**
+
- Mobile size:
- Tablet size:
- Desktop size:
- Retina/2x version: yes/no
-
+
---
@@ -95,17 +98,20 @@ Choice [1/2/3]:
**Image states:**
**Loading:**
+
- Placeholder: (color/skeleton/blur)
- Lazy loading: yes/no
**Error:**
+
- Fallback image: (if any)
- Error message display: yes/no
**Loaded:**
+
- Fade-in animation: yes/no
- Animation duration:
-
+
---
@@ -118,32 +124,37 @@ Choice [1/2/3]:
**Type:** image
**Source:**
+
- File: {{image_path}}
- Alt (EN): {{alt_text_en}}
- Alt (SV): {{alt_text_sv}}
-{{#if is_decorative}}
+ {{#if is_decorative}}
- Decorative: role="presentation"
-{{/if}}
+ {{/if}}
**Dimensions:**
+
- Width: {{width}}
- Height: {{height}}
- Aspect ratio: {{aspect_ratio}}
- Object-fit: {{object_fit}}
**Responsive:**
+
- Mobile: {{mobile_size}}
- Tablet: {{tablet_size}}
- Desktop: {{desktop_size}}
-{{#if has_retina}}
+ {{#if has_retina}}
- Retina (@2x): {{retina_path}}
-{{/if}}
+ {{/if}}
**Loading:**
+
- Placeholder: {{placeholder_type}}
- Lazy load: {{lazy_loading}}
**States:**
+
- **Loading:** {{loading_state}}
- **Error:** {{error_fallback}}
- **Loaded:** {{loaded_animation}}
@@ -152,4 +163,3 @@ Choice [1/2/3]:
---
**Return to 4c-03**
-
diff --git a/src/modules/wds/workflows/4-ux-design/object-types/link.md b/src/modules/wds/workflows/4-ux-design/object-types/link.md
index 7e5cf7a6..b713c39a 100644
--- a/src/modules/wds/workflows/4-ux-design/object-types/link.md
+++ b/src/modules/wds/workflows/4-ux-design/object-types/link.md
@@ -47,13 +47,13 @@ Choice [1/2/3]:
**Which existing component?**
- From your component library:
- {{list_available_link_components}}
+From your component library:
+{{list_available_link_components}}
- Component name:
-
- Store design_system_component
- Store component_status = "existing"
+Component name:
+
+Store design_system_component
+Store component_status = "existing"
@@ -84,13 +84,15 @@ Choice [1/2/3]:
**Link text in all languages:**
{{#each language}}
+
- **{{language}}:**
-{{/each}}
+ {{/each}}
**Target/Destination:**
+
- URL or route:
- Opens in: same tab / new tab
-
+
---
@@ -99,24 +101,28 @@ Choice [1/2/3]:
**Visual styling:**
**Default:**
+
- Text color:
- Text decoration: (underline/none)
- Font weight:
- Icon: (if any)
**Hover:**
+
- Text color:
- Text decoration:
- Cursor:
**Active/Visited:**
+
- Text color:
- Show as visited: yes/no
**Focus:**
+
- Outline color:
- Text decoration:
-
+
---
@@ -132,28 +138,30 @@ Choice [1/2/3]:
**Content:**
{{#each language}}
+
- **{{language}}:** {{link_text}}
-{{/each}}
+ {{/each}}
{{#if has_icon}}
**Icon:** {{icon_name}} ({{icon_position}})
{{/if}}
**States:**
+
- **Default:** {{default_color}}, {{default_decoration}}
- **Hover:** {{hover_color}}, {{hover_decoration}}
- **Active:** {{active_color}}
- **Focus:** Outline {{focus_outline}}
**Interaction:**
+
- On click: Navigate to {{destination}}
-{{#if opens_new_tab}}
+ {{#if opens_new_tab}}
- Opens in new tab
- Includes rel="noopener noreferrer"
-{{/if}}
+ {{/if}}
```
---
**Return to 4c-03**
-
diff --git a/src/modules/wds/workflows/4-ux-design/object-types/object-router.md b/src/modules/wds/workflows/4-ux-design/object-types/object-router.md
index 6e306a91..77bb3b8b 100644
--- a/src/modules/wds/workflows/4-ux-design/object-types/object-router.md
+++ b/src/modules/wds/workflows/4-ux-design/object-types/object-router.md
@@ -9,10 +9,11 @@
**Analyzing object from sketch...**Apply text detection rules from `TEXT-DETECTION-PRIORITY.md`:
-- Look for horizontal line PAIRS (2 lines together = text marker)
+
+- Look for horizontal line PAIRS (2 lines together = text marker)
- Single lines alone = decorative elements (dividers, borders)
- Count pairs to determine number of text lines
-
+
**✓ TEXT ELEMENT DETECTED**
@@ -39,32 +40,36 @@
Examine object characteristics:
+
- Visual appearance (shape, style, position)
- Context (what's around it, where in form/page)
- Interactive indicators (buttons, inputs, links)
- Container indicators (boxes, cards, modals)
- Media indicators (image placeholders, video frames)
-
+
**My interpretation:**
**This looks like a {{suggested_object_type}}.**
Based on what I see:
+
- {{observation_1}}
- {{observation_2}}
- {{observation_3}}
{{#if is_text_element}}
**Text Analysis from Sketch:**
+
- **{{line_count}} lines of text** (horizontal bar groups)
- **Line thickness:** {{thickness}} → ~{{estimated_font_size}} font
- **Line spacing:** {{spacing}} → ~{{estimated_line_height}} line-height
- **Alignment:** {{detected_alignment}}
- **Content capacity:** ~{{total_chars}} characters ({{chars_per_line}} per line)
-{{/if}}
+ {{/if}}
**I think this {{component_name}}:**
+
- {{suggested_purpose}}
- {{suggested_interaction}}
- {{suggested_result}}
@@ -75,9 +80,7 @@ Based on what I see:
**Does this match your intent?**
-1. **Yes** - That's correct
-2. **Close** - Similar but let me clarify
-3. **No** - It's actually something different
+1. **Yes** - That's correct 2. **Close** - Similar but let me clarify 3. **No** - It's actually something different
Choice [1/2/3]:
@@ -132,11 +135,13 @@ Choice [1/2/3]:Based on confirmed object type, load appropriate instruction file:
**TEXT ELEMENTS (DETECTED FIRST):**
+
- Horizontal line groups → `object-types/heading-text.md`
- Handles: Headings (H1-H6), Paragraphs, Labels, Captions
- Includes: Sketch text analysis, character capacity, content guidance
**INTERACTIVE ELEMENTS:**
+
- **Button shapes** → `object-types/button.md`
- **Input fields** → `object-types/text-input.md`
- **Textarea boxes** → `object-types/textarea.md`
@@ -147,26 +152,31 @@ Choice [1/2/3]:
- **Underlined text/arrows** → `object-types/link.md`
**MEDIA ELEMENTS:**
+
- **Image placeholders (X or box)** → `object-types/image.md`
- **Video frame** → `object-types/video.md`
**CONTAINER ELEMENTS:**
+
- **Card/box container** → `object-types/card.md`
- **Overlay/popup** → `object-types/modal-dialog.md`
- **Grid/rows** → `object-types/table.md`
- **Bullet/numbered items** → `object-types/list.md`
**NAVIGATION ELEMENTS:**
+
- **Menu/tabs** → `object-types/navigation.md`
**STATUS ELEMENTS:**
+
- **Small circle/pill** → `object-types/badge.md`
- **Banner/box with icon** → `object-types/alert-toast.md`
- **Bar/spinner** → `object-types/progress.md`
**CUSTOM:**
+
- **Unique component** → `object-types/custom-component.md`
-
+
@@ -203,6 +213,7 @@ Choice [1/2]:
## INTERPRETATION EXAMPLES
**Example 1: Button**
+
```
My interpretation:
@@ -224,6 +235,7 @@ Does this match your intent?
```
**Example 2: Text/Heading with Placeholder Lines**
+
```
My interpretation:
@@ -253,6 +265,7 @@ Does this match your intent?
```
**Example 3: Body Text with Multiple Lines**
+
```
My interpretation:
@@ -282,6 +295,7 @@ Does this match your intent?
```
**Example 3: Link**
+
```
My interpretation:
@@ -307,21 +321,25 @@ Does this match your intent?
## KEY PRINCIPLES
**✅ Agent demonstrates intelligence**
+
- Analyzes visual and contextual clues
- Makes informed suggestions
- Shows reasoning process
**✅ Trust-the-agent approach**
+
- Agent interprets, user confirms
- Not procedural checkbox selection
- Collaborative intelligence
**✅ Efficient workflow**
+
- Quick confirmation when correct
- Easy correction when needed
- Natural conversation flow
**✅ Context-aware**
+
- Understands form flow
- Recognizes UI patterns
- Applies common sense
diff --git a/src/modules/wds/workflows/4-ux-design/object-types/text-input.md b/src/modules/wds/workflows/4-ux-design/object-types/text-input.md
index fd331603..041763d2 100644
--- a/src/modules/wds/workflows/4-ux-design/object-types/text-input.md
+++ b/src/modules/wds/workflows/4-ux-design/object-types/text-input.md
@@ -56,13 +56,13 @@ Choice [1/2/3]:
**Which existing component?**
- From your component library:
- {{list_available_input_components}}
+From your component library:
+{{list_available_input_components}}
- Component name:
-
- Store design_system_component
- Store component_status = "existing"
+Component name:
+
+Store design_system_component
+Store component_status = "existing"
@@ -93,27 +93,30 @@ Choice [1/2/3]:
**Label text in all languages:**
{{#each language}}
+
- **{{language}}:**
-{{/each}}
-
+ {{/each}}
+
Store label_text for each language**Placeholder text in all languages:**
{{#each language}}
+
- **{{language}}:**
-{{/each}}
-
+ {{/each}}
+
Store placeholder_text for each language**Helper text** (optional guidance below field):
{{#each language}}
+
- **{{language}}:**
-{{/each}}
-
+ {{/each}}
+
Store helper_text for each language
@@ -129,7 +132,7 @@ Choice [1/2/3]:
- Autocomplete: (on/off/specific type like "email")
- Autofocus: yes/no
- Readonly: yes/no
-
+
Store input_properties
@@ -142,29 +145,34 @@ Choice [1/2/3]:
**For each state, describe the appearance:**
**Default/Empty state:**
+
- Border color:
- Background:
- Placeholder visible: yes
- Label position:
**Focus state:**
+
- Border color:
- Background:
- Label position: (stays/floats above)
- Outline/glow:
**Filled state:**
+
- Border color:
- Background:
- Label position:
**Error state:**
+
- Border color:
- Background:
- Error message position: (below/inline)
- Icon: (if any)
**Disabled state:**
+
- Border color:
- Background:
- Text color:
@@ -172,10 +180,11 @@ Choice [1/2/3]:
- Why disabled:
**Success state** (if applicable):
+
- Border color:
- Icon: (checkmark, etc.)
- When shown:
-
+
Store state definitions for all states
@@ -186,22 +195,27 @@ Choice [1/2/3]:
**Validation rules for this input:**
**Required:**
+
- Is this field required: yes/no
**Format validation:**
+
- Format rules: (e.g., "must be valid email", "must contain @")
- Pattern/regex: (if applicable)
**Length validation:**
+
- Minimum length:
- Maximum length:
**Custom rules:**
+
- Any custom validation:
**Validation timing:**
+
- When to validate: on_blur / on_input / on_submit
-
+
Store validation_rules
@@ -217,10 +231,11 @@ Choice [1/2/3]:
Error code: (e.g., ERR_EMAIL_REQUIRED)
{{#each language}}
+
- **{{language}}:**
-{{/each}}
-{{/each}}
-
+ {{/each}}
+ {{/each}}
+
Store error_messages with codes and translations
@@ -231,19 +246,22 @@ Error code: (e.g., ERR_EMAIL_REQUIRED)
**Interaction behaviors:**
**On focus:**
+
- What happens:
**On input (while typing):**
+
- Real-time validation: yes/no
- Character counter: yes/no
- Auto-formatting: yes/no (e.g., phone numbers)
- Other behaviors:
**On blur (loses focus):**
+
- Validation triggers: yes/no
- Save/update: yes/no
- Other behaviors:
-
+
Store interaction_behaviors
@@ -265,22 +283,26 @@ Error code: (e.g., ERR_EMAIL_REQUIRED)
**Label:**
{{#each language}}
+
- **{{language}}:** {{label_text}}
-{{/each}}
+ {{/each}}
**Placeholder:**
{{#each language}}
+
- **{{language}}:** {{placeholder_text}}
-{{/each}}
+ {{/each}}
{{#if has_helper_text}}
**Helper Text:**
{{#each language}}
+
- **{{language}}:** {{helper_text}}
-{{/each}}
-{{/if}}
+ {{/each}}
+ {{/if}}
**Properties:**
+
- Required: {{is_required}}
- Max length: {{max_length}}
- Min length: {{min_length}}
@@ -289,45 +311,54 @@ Error code: (e.g., ERR_EMAIL_REQUIRED)
**States:**
-*Default:*
+_Default:_
+
- Border: {{default_border}}
- Background: {{default_bg}}
- Label: {{label_position}}
-*Focus:*
+_Focus:_
+
- Border: {{focus_border}}
- Label: {{focus_label_position}}
- Outline: {{focus_outline}}
-*Filled:*
+_Filled:_
+
- Border: {{filled_border}}
- Label: {{filled_label_position}}
-*Error:*
+_Error:_
+
- Border: {{error_border}}
- Icon: {{error_icon}}
- Message: Below field
-*Disabled:*
+_Disabled:_
+
- Border: {{disabled_border}}
- Background: {{disabled_bg}}
- Cursor: not-allowed
**Validation:**
{{#each validation_rule}}
+
- {{rule_description}}
-{{/each}}
+ {{/each}}
**Error Messages:**
{{#each error}}
+
- **{{error_code}}:** {{error_messages}}
-{{/each}}
+ {{/each}}
**Interactions:**
+
- **On Focus:** {{focus_behavior}}
- **On Input:** {{input_behavior}}
- **On Blur:** {{blur_behavior}}
```
+
✅ **Input field documented!**
@@ -347,18 +378,22 @@ Specification added to page document.
**Figma Component:** Input/Text/Medium
**Label:**
+
- **English:** Email Address
- **Swedish:** E-postadress
**Placeholder:**
+
- **English:** your@email.com
- **Swedish:** din@epost.com
**Helper Text:**
+
- **English:** We'll never share your email
- **Swedish:** Vi delar aldrig din e-post
**Properties:**
+
- Required: yes
- Max length: 254
- Min length: 5
@@ -367,51 +402,57 @@ Specification added to page document.
**States:**
-*Default:*
+_Default:_
+
- Border: 1px solid #CCCCCC
- Background: #FFFFFF
- Label: Inside field (placeholder position)
-*Focus:*
+_Focus:_
+
- Border: 2px solid #0066CC (primary)
- Label: Floats above field
- Outline: 0 0 0 3px rgba(0,102,204,0.1)
-*Filled:*
+_Filled:_
+
- Border: 1px solid #666666
- Label: Remains above field
-*Error:*
+_Error:_
+
- Border: 2px solid #DC2626 (red)
- Icon: ⚠️ (warning icon, right side)
- Message: Below field in red
-*Disabled:*
+_Disabled:_
+
- Border: 1px solid #E5E5E5
- Background: #F5F5F5
- Cursor: not-allowed
- Text: #999999
**Validation:**
+
- Required field (cannot be empty)
- Must contain @ symbol
- Must have valid domain
- Must match email format pattern
**Error Messages:**
+
- **ERR_EMAIL_REQUIRED:**
- EN: "Email address is required"
- SV: "E-postadress krävs"
-
- **ERR_EMAIL_INVALID:**
- EN: "Please enter a valid email address"
- SV: "Ange en giltig e-postadress"
-
- **ERR_EMAIL_DOMAIN:**
- EN: "Email domain appears invalid"
- SV: "E-postdomän verkar ogiltig"
**Interactions:**
+
- **On Focus:** Border changes to primary color, label floats up with animation (200ms ease-out)
- **On Input:** Real-time validation (debounced 300ms), @ symbol triggers domain validation
- **On Blur:** Full validation runs, error message displays if invalid, save to form state
@@ -420,4 +461,3 @@ Specification added to page document.
---
**Return to 4c-03 to continue with next object**
-
diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/SCENARIO-INIT-PROCESS.md b/src/modules/wds/workflows/4-ux-design/scenario-init/SCENARIO-INIT-PROCESS.md
index 170fbaf2..f90ac269 100644
--- a/src/modules/wds/workflows/4-ux-design/scenario-init/SCENARIO-INIT-PROCESS.md
+++ b/src/modules/wds/workflows/4-ux-design/scenario-init/SCENARIO-INIT-PROCESS.md
@@ -7,6 +7,7 @@
## The Situation
You've created your **Trigger Map**. You know:
+
- WHO your target groups are
- WHAT triggers their needs
- WHY your business exists
@@ -23,12 +24,12 @@ You've created your **Trigger Map**. You know:
```
Agent: "Looking at your Trigger Map and prioritized feature list,
- what's the core feature that delivers value to your
+ 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
+Designer: "The family dog walk calendar - it solves the accountability
problem that causes conflict."
```
@@ -37,10 +38,10 @@ Designer: "The family dog walk calendar - it solves the accountability
### 2. Where Does the User First Encounter This?
```
-Agent: "Where does your primary target group first come into
+Agent: "Where does your primary target group first come into
contact with this solution?"
-Designer: "Google search - they're frustrated with family conflict
+Designer: "Google search - they're frustrated with family conflict
over dog care."
```
@@ -50,7 +51,7 @@ Designer: "Google search - they're frustrated with family conflict
```
Agent: "When they find Dog Week on Google, how are they feeling?
-
+
Think about:
- What just happened? (trigger moment)
- What are they hoping for?
@@ -67,7 +68,7 @@ Designer: "Just had another fight about who walks the dog.
```
Agent: "What does success look like for both sides?
-
+
For the business: [subscription purchased]
For the parent: [what state/feeling/outcome]?"
@@ -81,19 +82,20 @@ Designer: "Business: Active subscription
### 5. What's the Shortest Path?
```
-Agent: "Let's map the shortest possible journey from
+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 →
+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
@@ -118,6 +120,7 @@ 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)
@@ -125,6 +128,7 @@ Now let's start sketching this journey.
- ✅ 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
@@ -142,7 +146,7 @@ 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 →
+Shortest Path: Google → Product page → Transparent pricing →
Add to cart → Checkout → Confirmation
SCENARIO: Transparent Purchase Journey
@@ -158,7 +162,7 @@ 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 →
+Shortest Path: ChatGPT → Landing → See demo → Sign up →
Quick setup → First success
SCENARIO: Frictionless Onboarding
@@ -174,7 +178,7 @@ 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 →
+Shortest Path: Friend link → About page → Testimonials →
Book consultation → Confirmation
SCENARIO: Trust-Building Booking
@@ -187,6 +191,7 @@ SCENARIO: Trust-Building Booking
**Not a script. A conversation.**
Agent helps you think through:
+
- What drives the business?
- Who makes it happen?
- Where do they start?
@@ -201,6 +206,7 @@ Agent helps you think through:
## Next Step
Once you have:
+
- ✅ Natural starting point
- ✅ Mental state
- ✅ End goal
diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md
index 2d1f54de..b94a3fa6 100644
--- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md
+++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md
@@ -9,6 +9,7 @@
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
@@ -19,18 +20,23 @@ This process helps you identify:
## 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
---
@@ -38,12 +44,15 @@ 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
---
diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/01-feature-selection.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/01-feature-selection.md
index 7712ad6c..b44eb70e 100644
--- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/01-feature-selection.md
+++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/01-feature-selection.md
@@ -8,9 +8,9 @@
```
Agent: "Looking at your Trigger Map and prioritized feature list,
- what's the core feature that delivers value to your
+ what's the core feature that delivers value to your
primary target group?
-
+
This is what we should sketch first."
```
@@ -19,6 +19,7 @@ Agent: "Looking at your Trigger Map and prioritized feature list,
## Why This Matters
Your Trigger Map already identified:
+
- Primary target group
- What triggers their need
- What outcome they want
@@ -30,17 +31,20 @@ Your Trigger Map already identified:
## 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
+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)
diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/02-entry-point.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/02-entry-point.md
index a00419cc..be6bfdd7 100644
--- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/02-entry-point.md
+++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/02-entry-point.md
@@ -7,7 +7,7 @@
## The Question
```
-Agent: "Where does your primary target group first come into
+Agent: "Where does your primary target group first come into
contact with this solution?"
```
@@ -16,11 +16,13 @@ Agent: "Where does your primary target group first come into
## 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
@@ -33,11 +35,12 @@ The entry point determines:
## Example: Dog Week
```
-Designer: "Google search - they're frustrated with family conflict
+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)
diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/03-mental-state.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/03-mental-state.md
index b45c52ae..cd61b823 100644
--- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/03-mental-state.md
+++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/03-mental-state.md
@@ -8,7 +8,7 @@
```
Agent: "When they find your solution, how are they feeling?
-
+
Think about:
- What just happened? (trigger moment)
- What are they hoping for?
@@ -20,6 +20,7 @@ Agent: "When they find your solution, how are they feeling?
## Why This Matters
Mental state determines:
+
- Tone of content
- Complexity of interface
- Type of features needed
@@ -38,6 +39,7 @@ Designer: "Just had another fight about who walks the dog.
```
**Design implications:**
+
- Tone: Empathetic, not preachy
- Interface: Simple, not complex
- Features: Automated accountability, not more work
diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/04-mutual-success.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/04-mutual-success.md
index 3bd7843e..5fc3b71d 100644
--- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/04-mutual-success.md
+++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/04-mutual-success.md
@@ -8,7 +8,7 @@
```
Agent: "What does success look like for both sides?
-
+
For the business: [what outcome?]
For the user: [what state/feeling/outcome?]"
```
@@ -18,6 +18,7 @@ Agent: "What does success look like for both sides?
## Why This Matters
Success must be mutual:
+
- Business gets value
- User gets value
- Both are happy
@@ -35,6 +36,7 @@ Designer: "Business: Active subscription
```
**Why both matter:**
+
- Business needs subscription (revenue)
- User needs harmony (problem solved)
- Subscription only works if harmony is real
diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/05-shortest-path.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/05-shortest-path.md
index f6468745..510f5cb5 100644
--- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/05-shortest-path.md
+++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/05-shortest-path.md
@@ -7,9 +7,9 @@
## The Question
```
-Agent: "Let's map the shortest possible journey from
+Agent: "Let's map the shortest possible journey from
[starting point] to [mutual success]:
-
+
What's the absolute minimum path?"
```
@@ -18,6 +18,7 @@ Agent: "Let's map the shortest possible journey from
## Why This Matters
Shortest path means:
+
- No unnecessary steps
- No feature bloat
- Clear focus
@@ -33,12 +34,13 @@ Shortest path means:
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 →
+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)
@@ -74,6 +76,7 @@ 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)
diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/booking-example.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/booking-example.md
index a0e8d44a..f3a64d3b 100644
--- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/booking-example.md
+++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/booking-example.md
@@ -7,29 +7,34 @@
## 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 →
+Friend link → About page → Testimonials →
Book consultation → Confirmation
```
diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/ecommerce-example.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/ecommerce-example.md
index 7d45c926..de58ebbc 100644
--- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/ecommerce-example.md
+++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/ecommerce-example.md
@@ -7,29 +7,34 @@
## 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 →
+Google → Product page → Transparent pricing →
Add to cart → Checkout → Confirmation
```
diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/saas-example.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/saas-example.md
index 14649493..977a60f3 100644
--- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/saas-example.md
+++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/saas-example.md
@@ -7,29 +7,34 @@
## 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 →
+ChatGPT → Landing → See demo → Sign up →
Quick setup → First success
```
diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-01-init.md b/src/modules/wds/workflows/4-ux-design/steps/step-01-init.md
index 8d332dd3..afba0403 100644
--- a/src/modules/wds/workflows/4-ux-design/steps/step-01-init.md
+++ b/src/modules/wds/workflows/4-ux-design/steps/step-01-init.md
@@ -24,13 +24,14 @@ Set up the design session and determine what scenario or page the user wants to
**Step 2: Scenario Definition** - Define the user journey and pages
**Step 3: Page Design** - Design each page using substeps 4A-4E:
- - 4A: Exploration (think through concept)
- - 4B: Sketch Analysis (analyze your sketches)
- - 4C: Specification (document everything)
- - 4D: Prototype (create interactive HTML)
- - 4E: PRD Update (extract requirements)
-**Step 4: Complete Scenario** - Finalize and celebrate
-**Step 5: Continue or Exit** - Next steps
+
+- 4A: Exploration (think through concept)
+- 4B: Sketch Analysis (analyze your sketches)
+- 4C: Specification (document everything)
+- 4D: Prototype (create interactive HTML)
+- 4E: PRD Update (extract requirements)
+ **Step 4: Complete Scenario** - Finalize and celebrate
+ **Step 5: Continue or Exit** - Next steps
**Key principle:** Designs that can be logically explained without gaps are easy to develop. The specification process reveals gaps early - when they're easy to address.
@@ -49,16 +50,19 @@ Choice [1/2/3]:
## MENU HANDLING
### Choice 1: New Scenario
+
- Proceed to Step 2 (Scenario Definition)
- Load `steps/step-02-define-scenario.md`
### Choice 2: Continue Existing
+
- Ask which scenario/page to continue
- Determine current status (which substep they're on)
- Load appropriate step file based on status
- Skip Step 2 if scenario already defined
### Choice 3: Review Structure
+
- List scenarios in `{output_folder}/C-Scenarios/`
- Show completion status for each
- Return to this menu
@@ -73,4 +77,3 @@ After user selects [1] for new scenario, load `steps/step-02-define-scenario.md`
If user selects [2], determine current state and load appropriate step.
If user selects [3], show structure and return to this step.
-
diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-02-define-scenario.md b/src/modules/wds/workflows/4-ux-design/steps/step-02-define-scenario.md
index 05617318..b82f18fb 100644
--- a/src/modules/wds/workflows/4-ux-design/steps/step-02-define-scenario.md
+++ b/src/modules/wds/workflows/4-ux-design/steps/step-02-define-scenario.md
@@ -23,6 +23,7 @@ A scenario is a cohesive user journey containing multiple related pages.**What scenario are we designing?**
Examples:
+
- "User Onboarding" (sign up through profile setup)
- "Booking Flow" (search through confirmation)
- "Dashboard Experience" (home screen with navigation)
@@ -38,6 +39,7 @@ Scenario name:
List the main screens/pages in order.
Example:
+
1. Start Page
2. Sign Up
3. Profile Setup
@@ -45,19 +47,22 @@ Example:
Store pages listCreate folder structure for each page:
- - {nn}.1-{page-name}/
- - {nn}.2-{page-name}/
- - etc.
-
+
+- {nn}.1-{page-name}/
+- {nn}.2-{page-name}/
+- etc.
+
✅ **Scenario structure created:**
`C-Scenarios/{nn}-{scenario-name}/`
{{#each page}}
- - `{nn}.{n}-{page-name}/`
-{{/each}}
+
+- `{nn}.{n}-{page-name}/`
+ {{/each}}
We'll design each page using the 4A-4E process:
+
- **4A: Exploration** (optional - think through concept)
- **4B: Sketch Analysis** (analyze your sketches)
- **4C: Specification** (document everything systematically)
@@ -77,6 +82,7 @@ Ready to design the first page? 🎨
## STATE MANAGEMENT
Before proceeding:
+
- Save scenario structure to `C-Scenarios/{nn}-{scenario-name}/scenario-info.yaml`
- Include: scenario_name, scenario_number, pages_list, current_page_index (0)
@@ -85,4 +91,3 @@ Before proceeding:
## NEXT STEP
When user selects [C], load `steps/step-03-design-page.md` to begin designing the first page.
-
diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-03-design-page.md b/src/modules/wds/workflows/4-ux-design/steps/step-03-design-page.md
index 84386bc7..03f17b1e 100644
--- a/src/modules/wds/workflows/4-ux-design/steps/step-03-design-page.md
+++ b/src/modules/wds/workflows/4-ux-design/steps/step-03-design-page.md
@@ -70,6 +70,7 @@ Choice [1/2]:
**Time to create the complete specification.** 📝
We'll go through this systematically in focused steps:
+
1. Page basics
2. Layout sections
3. Components & Object IDs
@@ -82,15 +83,16 @@ We'll go through this systematically in focused steps:
This ensures nothing is missed and every detail is captured.Execute substeps in sequence:
- 1. Load and execute `substeps/4c-01-page-basics.md`
- 2. Load and execute `substeps/4c-02-layout-sections.md`
- 3. Load and execute `substeps/4c-03-components-objects.md`
- 4. Load and execute `substeps/4c-04-content-languages.md`
- 5. Load and execute `substeps/4c-05-interactions.md`
- 6. Load and execute `substeps/4c-06-states.md`
- 7. Load and execute `substeps/4c-07-validation.md`
- 8. Load and execute `substeps/4c-08-generate-spec.md`
-
+
+1. Load and execute `substeps/4c-01-page-basics.md`
+2. Load and execute `substeps/4c-02-layout-sections.md`
+3. Load and execute `substeps/4c-03-components-objects.md`
+4. Load and execute `substeps/4c-04-content-languages.md`
+5. Load and execute `substeps/4c-05-interactions.md`
+6. Load and execute `substeps/4c-06-states.md`
+7. Load and execute `substeps/4c-07-validation.md`
+8. Load and execute `substeps/4c-08-generate-spec.md`
+
When all 4C substeps complete, return here and continue to 4D
@@ -130,10 +132,11 @@ Choice [1/2]:
**Page "{page-name}" is complete!** 🎉
**Created:**
+
- ✅ Specification: `C-Scenarios/{scenario}/{page}/{page}.md`
-{{#if prototype_created}}
+ {{#if prototype_created}}
- ✅ Prototype: `C-Scenarios/{scenario}/{page}/Prototype/`
-{{/if}}
+ {{/if}}
- ✅ PRD Requirements: Added to `D-PRD/PRD.md`
**Your page is development-ready!** ✨
@@ -148,11 +151,11 @@ Choice [1/2]:
**Next page: {next_page_name}**
- [C] Continue to next page
- [P] Pause - Save and continue later
+[C] Continue to next page
+[P] Pause - Save and continue later
+
+Choice [C/P]:
- Choice [C/P]:
-
Loop back to top of Step 3 with new page
@@ -173,6 +176,7 @@ Choice [1/2]:
## STATE MANAGEMENT
After each page:
+
- Update scenario-info.yaml with current_page_index
- Mark page as complete in tracking
- Save progress
@@ -183,4 +187,3 @@ After each page:
- If more pages: Loop back to top of Step 3
- If scenario complete: Load `steps/step-04-complete-scenario.md`
-
diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-04-complete-scenario.md b/src/modules/wds/workflows/4-ux-design/steps/step-04-complete-scenario.md
index 7ae541d1..77f31301 100644
--- a/src/modules/wds/workflows/4-ux-design/steps/step-04-complete-scenario.md
+++ b/src/modules/wds/workflows/4-ux-design/steps/step-04-complete-scenario.md
@@ -21,22 +21,24 @@ Acknowledge completion and transition to next steps.
✅ **Scenario "{scenario_name}" complete!**
**Created:**
+
- Scenario folder: `C-Scenarios/{nn}-{scenario-name}/`
- Page specifications: {{page_count}} pages
-{{#if prototype_count > 0}}
+ {{#if prototype_count > 0}}
- HTML prototypes: {{prototype_count}} prototypes
-{{/if}}
+ {{/if}}
- PRD updates: {{requirements_count}} requirements added
**Each page includes:**
+
- Complete specification with Object IDs
- Component definitions
- Interaction behaviors
- State definitions
- Multilingual content
-{{#if prototype_count > 0}}
+ {{#if prototype_count > 0}}
- Interactive prototype
-{{/if}}
+ {{/if}}
**Your specifications are development-ready!** 🎨
@@ -55,4 +57,3 @@ Choice [C]:
## NEXT STEP
When user selects [C], load `steps/step-05-next-steps.md` for workflow completion.
-
diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-05-next-steps.md b/src/modules/wds/workflows/4-ux-design/steps/step-05-next-steps.md
index d0a58e26..ded00df7 100644
--- a/src/modules/wds/workflows/4-ux-design/steps/step-05-next-steps.md
+++ b/src/modules/wds/workflows/4-ux-design/steps/step-05-next-steps.md
@@ -39,18 +39,22 @@ Choice [1/2/3/4/5]:
## MENU HANDLING
### Choice 1: Design Another Scenario
+
Return to Step 2 (Define Scenario)Load `steps/step-02-define-scenario.md`
### Choice 2: Phase 5 (Design System)
+
To start Phase 5, activate Freyja (WDS Designer) again and run the Design System workflow.Exit this workflow
### Choice 3: Phase 6 (PRD Finalization)
+
To start Phase 6, activate Idunn (WDS PM) and run the PRD Finalization workflow.Exit this workflow
### Choice 4: Review Progress
+
List all scenarios in C-Scenarios/Show completion status for eachCount total pages designed
@@ -59,6 +63,7 @@ Choice [1/2/3/4/5]:
If Y, return to menu in this step
### Choice 5: Exit
+
Perfect! All your work is saved. Resume anytime by running the UX Design workflow again.
See you next time! 🎨✨
@@ -69,4 +74,3 @@ See you next time! 🎨✨
## WORKFLOW COMPLETE
This is the final step. User either loops to another scenario or exits.
-
diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4a-exploration.md b/src/modules/wds/workflows/4-ux-design/substeps/4a-exploration.md
index 9154299f..a34bc472 100644
--- a/src/modules/wds/workflows/4-ux-design/substeps/4a-exploration.md
+++ b/src/modules/wds/workflows/4-ux-design/substeps/4a-exploration.md
@@ -7,11 +7,13 @@
## When to Use This Step
Use 4A when:
+
- User has no existing sketches
- User is unsure how to approach a feature
- User wants to explore the concept together
Skip 4A when:
+
- User has sketches ready
- User knows exactly what they want
@@ -22,6 +24,7 @@ Skip 4A when:
**Let's explore this concept together before sketching.**
I'll help you think through:
+
- What the user is trying to accomplish
- What content and features they need
- How psychological triggers from your Trigger Map apply
@@ -36,6 +39,7 @@ What's their goal? What brought them here?
**What do they need to see or do to accomplish that?**
Think about:
+
- Information they need
- Actions they can take
- Choices they need to make
@@ -45,6 +49,7 @@ Think about:
**Let's check your Trigger Map - what drives this user?**
Looking at your personas and driving forces:
+
- What positive goals does this page support?
- What negative outcomes does it help them avoid?
@@ -54,6 +59,7 @@ Looking at your personas and driving forces:
**How does the interaction flow?**
Walk me through:
+
1. User arrives (from where?)
2. User sees... (what catches attention?)
3. User does... (main actions?)
@@ -75,6 +81,7 @@ Walk me through:
{{interaction_flow}}
You're ready to sketch! Would you like to:
+
1. **Create sketches** - Use your preferred tool, then come back for analysis (4B)
2. **Skip sketching** - Go directly to specification (4C)
3. **Explore more** - Refine the concept further
@@ -97,4 +104,3 @@ You're ready to sketch! Would you like to:
---
**Next:** Step 4B (Sketch Analysis) or Step 4C (Specification)
-
diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4b-sketch-analysis.md b/src/modules/wds/workflows/4-ux-design/substeps/4b-sketch-analysis.md
index 9da32fc9..0f40443c 100644
--- a/src/modules/wds/workflows/4-ux-design/substeps/4b-sketch-analysis.md
+++ b/src/modules/wds/workflows/4-ux-design/substeps/4b-sketch-analysis.md
@@ -29,6 +29,7 @@
Your sketch:
Analyze entire sketch holistically:
+
1. **Establish Scale First:**
- Check if other pages in project have been analyzed
- Look for established text styles (body text, buttons, headings)
@@ -45,15 +46,16 @@ Your sketch:
- 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
-
+
**📊 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}}
+ {{/each}}
I'll use these as reference points for consistency.
{{/if}}
@@ -62,19 +64,21 @@ I'll use these as reference points for consistency.
**{{page_name}}** contains **{{section_count}} main sections:**
-{{#each identified_sections}}
----
+## {{#each identified_sections}}
+
**Section {{index}}: {{section_name}}** ({{location}})
+
- **Purpose:** {{interpreted_purpose}}
- **Contains:** {{object_count}} objects/elements
- **Layout:** {{layout_description}}
-{{#if looks_like_previous_component}}
+ {{#if looks_like_previous_component}}
- 💡 **Component?** Similar to {{component_name}} from {{previous_page}}
-{{/if}}
-{{#if matches_established_pattern}}
+ {{/if}}
+ {{#if matches_established_pattern}}
- ✅ **Pattern Match:** Text styles match {{pattern_name}} from {{source_page}}
-{{/if}}
-{{/each}}
+ {{/if}}
+ {{/each}}
+
---
This is my interpretation of the structure. Does this look right?
@@ -97,17 +101,17 @@ Current breakdown:
{{/each}}
Your changes:
-
- Update section structure based on feedback
- **Updated structure:**
-
- {{#each updated_sections}}
- {{index}}. {{section_name}} - {{interpreted_purpose}}
- {{/each}}
-
- Does this look better?
-
- Loop until user confirms structure
+
+Update section structure based on feedback
+**Updated structure:**
+
+{{#each updated_sections}}
+{{index}}. {{section_name}} - {{interpreted_purpose}}
+{{/each}}
+
+Does this look better?
+
+Loop until user confirms structure
---
@@ -129,8 +133,8 @@ Your changes:
3. **Let me decide section-by-section** - I'll choose as we go
Choice [1/2/3]:
-
- Mark sections as components or page-specific based on user choice
+
+Mark sections as components or page-specific based on user choice
---
@@ -166,7 +170,7 @@ I'll interpret the objects, functions, and content for each section. You can con
- Function & Purpose
- Text Content (Actual vs. Markers)
- Visual Hierarchy
-
+
**My interpretation of "{{section_name}}":**
@@ -176,19 +180,20 @@ I'll interpret the objects, functions, and content for each section. You can con
{{#each interpreted_objects}}
{{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}}
-{{/each}}
+
+- **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}}
+ {{/each}}
**Overall Function:** {{section_function_summary}}
@@ -246,8 +251,8 @@ Choice [1/2/3/4]:
I'll suggest translations for everything at once.
-{{#each text_objects}}
----
+## {{#each text_objects}}
+
**{{object_purpose}}** (`{{object_id}}`)
{{#if has_actual_text}}
@@ -289,8 +294,8 @@ Use these? [1] Yes [2] Adjust [3] Manual
{{/if}}
-Store confirmed content for this object
----
+## Store confirmed content for this object
+
{{/each}}
---
@@ -302,6 +307,7 @@ Use these? [1] Yes [2] Adjust [3] Manual
Let me generate the complete section specification...
Generate section spec:
+
1. Section header with purpose
2. All objects with full details
3. All translations grouped by object
@@ -309,32 +315,36 @@ Let me generate the complete section specification...
5. Interactions and behaviors
6. States if applicable
7. Validation rules if applicable
-
+
**✅ Section "{{section_name}}" specification generated!**
```markdown
### {{Section_Name}}
+
**Purpose**: {{section_purpose}}
{{#each objects}}
+
#### {{Object_Purpose_Title}}
+
**OBJECT ID**: `{{object_id}}`
+
- **Component**: {{component_type}}
- **Position**: {{position}}
- **Style**: {{style_specs}}
-{{#if has_behavior}}
+ {{#if has_behavior}}
- **Behavior**: {{behavior}}
-{{/if}}
-{{#if is_text}}
+ {{/if}}
+ {{#if is_text}}
- **Content**:
{{#each product_languages}}
- {{this}}: "{{content}}"
- {{/each}}
-{{/if}}
-{{#if has_states}}
+ {{/each}}
+ {{/if}}
+ {{#if has_states}}
- **States**: {{states}}
-{{/if}}
+ {{/if}}
{{/each}}
```
@@ -395,6 +405,7 @@ Let me generate the complete section specification...
### Step 1: Holistic Reading
**AI:**
+
```
I've analyzed your sketch. Here's what I see:
@@ -434,6 +445,7 @@ Does this structure look right?
### Step 2: Section 1 - Header
**AI interprets:**
+
```
My interpretation of "Header":
@@ -466,6 +478,7 @@ Does this interpretation look right?
**User:** `1` (Confirms)
**AI suggests content:**
+
```
Content for "Sign In Button":
@@ -481,18 +494,24 @@ Use these? [1] Yes [2] Adjust [3] Manual
**User:** `1` (Accepts)
**AI generates:**
+
```markdown
### Header Object
+
**Purpose**: Navigation and user access with language selection
#### Dog Week Logo
+
**OBJECT ID**: `start-header-logo`
+
- **Component**: [Logo Component](/docs/D-Design-System/.../Logo.md)
- **Position**: Left-aligned
- **Behavior**: Links to home page
-#### Sign In Button
+#### Sign In Button
+
**OBJECT ID**: `start-header-signin`
+
- **Component**: [Button Secondary](/docs/D-Design-System/.../Button-Secondary.md)
- **Position**: Right side (before language selector)
- **Behavior**: Navigate to sign-in page
@@ -501,7 +520,9 @@ Use these? [1] Yes [2] Adjust [3] Manual
- SE: "Logga in"
#### Language Selector
+
**OBJECT ID**: `start-header-language`
+
- **Component**: [Language Selector](/docs/D-Design-System/.../LanguageSelector.md)
- **Position**: Right side (after sign-in button)
- **Behavior**: onChange → toggle language
diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-01-page-basics.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-01-page-basics.md
index bceb4f19..284352dd 100644
--- a/src/modules/wds/workflows/4-ux-design/substeps/4c-01-page-basics.md
+++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-01-page-basics.md
@@ -17,12 +17,13 @@
- Where users go next (exit points):
Store page_basics:
- - page_title
- - url_route
- - user_goal
- - entry_points
- - exit_points
-
+
+- page_title
+- url_route
+- user_goal
+- entry_points
+- exit_points
+
✅ **Page basics captured!**
@@ -40,15 +41,15 @@
```yaml
page_basics:
- title: "Sign In"
- route: "/auth/signin"
- user_goal: "Authenticate to access their account"
+ title: 'Sign In'
+ route: '/auth/signin'
+ user_goal: 'Authenticate to access their account'
entry_points:
- "Landing page 'Sign In' button"
- - "Protected route redirects"
+ - 'Protected route redirects'
exit_points:
- - "Dashboard (success)"
- - "Password reset (forgot password)"
+ - 'Dashboard (success)'
+ - 'Password reset (forgot password)'
```
---
@@ -56,4 +57,3 @@ page_basics:
## NEXT STEP
Load `substeps/4c-02-layout-sections.md`
-
diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-02-layout-sections.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-02-layout-sections.md
index d39a65af..431b6ba2 100644
--- a/src/modules/wds/workflows/4-ux-design/substeps/4c-02-layout-sections.md
+++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-02-layout-sections.md
@@ -15,16 +15,18 @@ Think about the major areas of the page (header, main content, sidebar, footer,
Describe each major section and its purpose.
Example:
+
- Header: Logo, navigation, user menu
- Hero: Welcome message and primary CTA
- Main Content: Sign-up form
- Footer: Links and legal info
For each section:
- - Store section_name
- - Store section_purpose
- - Store section_priority (primary/secondary)
-
+
+- Store section_name
+- Store section_purpose
+- Store section_priority (primary/secondary)
+
✅ **Layout sections defined!**
@@ -44,17 +46,17 @@ Example:
```yaml
layout_sections:
- - name: "Header"
- purpose: "Navigation and branding"
- priority: "secondary"
-
- - name: "Sign In Form"
- purpose: "User authentication"
- priority: "primary"
-
- - name: "Footer"
- purpose: "Legal links and support"
- priority: "secondary"
+ - name: 'Header'
+ purpose: 'Navigation and branding'
+ priority: 'secondary'
+
+ - name: 'Sign In Form'
+ purpose: 'User authentication'
+ priority: 'primary'
+
+ - name: 'Footer'
+ purpose: 'Legal links and support'
+ priority: 'secondary'
```
---
@@ -62,4 +64,3 @@ layout_sections:
## NEXT STEP
Load `substeps/4c-03-components-objects.md`
-
diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-03-components-objects.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-03-components-objects.md
index ca115b97..d3aab8e9 100644
--- a/src/modules/wds/workflows/4-ux-design/substeps/4c-03-components-objects.md
+++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-03-components-objects.md
@@ -24,48 +24,33 @@ Starting from top-left corner of this section...Loop through objects in section (top-to-bottom, left-to-right):
- **Next object in {{section_name}}:**
-
- What is the first/next object in this section (from top-left)?
+**Next object in {{section_name}}:**
+
+What is the first/next object in this section (from top-left)?
+
+Describe what you see:
+
+Store object_description
+
+### ROUTE TO OBJECT-TYPE INSTRUCTIONS
+
+Load and execute `object-types/object-router.md`
+
+Object-router will: 1. Ask user to identify object type 2. Load appropriate object-type instruction file 3. Guide through complete object documentation 4. Generate specification with Object ID 5. Return here when complete
+
+
+### DESIGN SYSTEM CHECK (IF ENABLED)
+
+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
+
+
+**More objects in {{section_name}}?**
+
+1. **Yes** - Document next object (move right, then down)
+2. **No** - Section complete
+
+Choice [1/2]:
- Describe what you see:
-
- Store object_description
-
- ### ROUTE TO OBJECT-TYPE INSTRUCTIONS
-
- Load and execute `object-types/object-router.md`
-
- Object-router will:
- 1. Ask user to identify object type
- 2. Load appropriate object-type instruction file
- 3. Guide through complete object documentation
- 4. Generate specification with Object ID
- 5. Return here when complete
-
-
- ### DESIGN SYSTEM CHECK (IF ENABLED)
-
- 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
-
-
- **More objects in {{section_name}}?**
-
- 1. **Yes** - Document next object (move right, then down)
- 2. **No** - Section complete
-
- Choice [1/2]:
-
Loop back to document next object in section
@@ -86,17 +71,19 @@ Starting from top-left corner of this section...✅ **All components identified and documented!**
**Summary:**
+
- **Sections processed:** {{section_count}}
- **Total components:** {{component_count}}
- **Components by type:**
{{#each component_type}}
- {{type_name}}: {{count}}
- {{/each}}
+ {{/each}}
**Object IDs assigned:**
{{#each component}}
+
- `{{object_id}}` ({{component_type}})
-{{/each}}
+ {{/each}}
**Next:** We'll specify the content and languages.
@@ -122,6 +109,7 @@ Starting from top-left corner of this section...
5. Continue until all objects in all sections are documented
**Benefits:**
+
- ✅ Consistent specifications across all WDS projects
- ✅ Agents have clear, focused instructions for each object type
- ✅ Example-driven (show, don't tell)
@@ -136,21 +124,21 @@ Starting from top-left corner of this section...
sections_processed:
- signin-form:
components:
- - object_id: "signin-form-email-input"
- type: "text-input"
- documented_via: "object-types/text-input.md"
-
- - object_id: "signin-form-password-input"
- type: "text-input"
- documented_via: "object-types/text-input.md"
-
- - object_id: "signin-form-submit-button"
- type: "button"
- documented_via: "object-types/button.md"
-
- - object_id: "signin-form-forgot-link"
- type: "link"
- documented_via: "object-types/link.md"
+ - object_id: 'signin-form-email-input'
+ type: 'text-input'
+ documented_via: 'object-types/text-input.md'
+
+ - object_id: 'signin-form-password-input'
+ type: 'text-input'
+ documented_via: 'object-types/text-input.md'
+
+ - object_id: 'signin-form-submit-button'
+ type: 'button'
+ documented_via: 'object-types/button.md'
+
+ - object_id: 'signin-form-forgot-link'
+ type: 'link'
+ documented_via: 'object-types/link.md'
total_components: 4
component_types:
@@ -164,4 +152,3 @@ component_types:
## NEXT STEP
Load `substeps/4c-04-content-languages.md`
-
diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-04-content-languages.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-04-content-languages.md
index 53fecde2..5fa4957d 100644
--- a/src/modules/wds/workflows/4-ux-design/substeps/4c-04-content-languages.md
+++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-04-content-languages.md
@@ -17,14 +17,15 @@ List all languages (e.g., English, Swedish, Spanish):
We'll go through each text element and provide content in all {{language_count}} languages.
For each text element (labels, buttons, headings, messages):
- **{{element_name}}:**
-
- {{#each language}}
- - {{language}}:
+**{{element_name}}:**
+
+{{#each language}}
+
+- {{language}}:
{{/each}}
-
- Store multilingual content for element
+
+Store multilingual content for element✅ **Content specified in all languages!**
@@ -51,28 +52,28 @@ supported_languages:
content:
page_title:
- en: "Sign In"
- sv: "Logga In"
-
+ en: 'Sign In'
+ sv: 'Logga In'
+
email_label:
- en: "Email Address"
- sv: "E-postadress"
-
+ en: 'Email Address'
+ sv: 'E-postadress'
+
email_placeholder:
- en: "your@email.com"
- sv: "din@epost.com"
-
+ en: 'your@email.com'
+ sv: 'din@epost.com'
+
password_label:
- en: "Password"
- sv: "Lösenord"
-
+ en: 'Password'
+ sv: 'Lösenord'
+
submit_button:
- en: "Sign In"
- sv: "Logga In"
-
+ en: 'Sign In'
+ sv: 'Logga In'
+
forgot_password_link:
- en: "Forgot password?"
- sv: "Glömt lösenord?"
+ en: 'Forgot password?'
+ sv: 'Glömt lösenord?'
```
---
@@ -80,4 +81,3 @@ content:
## NEXT STEP
Load `substeps/4c-05-interactions.md`
-
diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-05-interactions.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-05-interactions.md
index 414bb3e6..f49fa12e 100644
--- a/src/modules/wds/workflows/4-ux-design/substeps/4c-05-interactions.md
+++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-05-interactions.md
@@ -11,18 +11,18 @@
For each interactive element, we'll specify what happens when users interact with it.For each component with Object ID:
- **{{object_id}}** ({{element_type}})
-
- What happens when the user interacts with this?
-
- - On click / on input / on focus?
- - What's the immediate response?
- - What state changes occur?
- - Where does it navigate (if applicable)?
- - What data is sent/received?
+**{{object_id}}** ({{element_type}})
+
+What happens when the user interacts with this?
+
+- On click / on input / on focus?
+- What's the immediate response?
+- What state changes occur?
+- Where does it navigate (if applicable)?
+- What data is sent/received?
-
- Store interaction_behavior for component
+
+Store interaction_behavior for component✅ **Interactions defined!**
@@ -45,34 +45,34 @@ For each interactive element, we'll specify what happens when users interact wit
interactions:
signin-form-email-input:
on_focus:
- - "Highlight border (primary color)"
- - "Show label above field"
+ - 'Highlight border (primary color)'
+ - 'Show label above field'
on_input:
- - "Real-time validation (email format)"
- - "Clear error state if valid"
+ - 'Real-time validation (email format)'
+ - 'Clear error state if valid'
on_blur:
- - "Validate complete email"
- - "Show error if invalid"
-
+ - 'Validate complete email'
+ - 'Show error if invalid'
+
signin-form-password-input:
on_focus:
- - "Highlight border"
+ - 'Highlight border'
on_input:
- - "Mask characters as bullets"
+ - 'Mask characters as bullets'
on_blur:
- - "Validate not empty"
-
+ - 'Validate not empty'
+
signin-form-submit-button:
on_click:
- - "Validate all fields"
- - "If valid: disable button, show loading state"
- - "POST to /api/auth/signin"
- - "On success: redirect to /dashboard"
- - "On error: show error message, re-enable button"
-
+ - 'Validate all fields'
+ - 'If valid: disable button, show loading state'
+ - 'POST to /api/auth/signin'
+ - 'On success: redirect to /dashboard'
+ - 'On error: show error message, re-enable button'
+
signin-form-forgot-link:
on_click:
- - "Navigate to /auth/forgot-password"
+ - 'Navigate to /auth/forgot-password'
```
---
@@ -80,4 +80,3 @@ interactions:
## NEXT STEP
Load `substeps/4c-06-states.md`
-
diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-06-states.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-06-states.md
index 5ff61f1e..9191c611 100644
--- a/src/modules/wds/workflows/4-ux-design/substeps/4c-06-states.md
+++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-06-states.md
@@ -15,6 +15,7 @@ States show how the page and components appear in different situations.**What are the different page-level states?**
Think about:
+
- Default/loaded state
- Empty state (no data)
- Loading state (fetching data)
@@ -22,6 +23,7 @@ Think about:
- Success state (after action completes)
For each state, describe:
+
- When it occurs
- What the user sees
- What actions are available
@@ -35,20 +37,20 @@ For each state, describe:
For components with multiple appearances, we'll specify each state.
For components with multiple states:
- **{{object_id}}** states:
-
- - Default:
- - Hover:
- - Active/Pressed:
- - Focus:
- - Disabled:
- - Loading:
- - Error:
- - Success:
-
- (Only specify states that apply to this component)
-
- Store component_states
+**{{object_id}}** states:
+
+- Default:
+- Hover:
+- Active/Pressed:
+- Focus:
+- Disabled:
+- Loading:
+- Error:
+- Success:
+
+(Only specify states that apply to this component)
+
+Store component_states✅ **All states defined!**
@@ -71,49 +73,49 @@ For components with multiple appearances, we'll specify each state.
```yaml
page_states:
default:
- trigger: "Page loads normally"
- appearance: "Empty form ready for input"
- actions: "User can fill form and submit"
-
+ trigger: 'Page loads normally'
+ appearance: 'Empty form ready for input'
+ actions: 'User can fill form and submit'
+
loading:
- trigger: "After submit clicked"
- appearance: "Submit button shows spinner, form disabled"
- actions: "Wait for response"
-
+ trigger: 'After submit clicked'
+ appearance: 'Submit button shows spinner, form disabled'
+ actions: 'Wait for response'
+
error:
- trigger: "Authentication fails"
- appearance: "Error message above form, submit button re-enabled"
- actions: "User can retry with different credentials"
-
+ trigger: 'Authentication fails'
+ appearance: 'Error message above form, submit button re-enabled'
+ actions: 'User can retry with different credentials'
+
success:
- trigger: "Authentication succeeds"
- appearance: "Brief success message"
- actions: "Redirect to dashboard"
+ trigger: 'Authentication succeeds'
+ appearance: 'Brief success message'
+ actions: 'Redirect to dashboard'
component_states:
signin-form-email-input:
default:
- appearance: "Gray border, placeholder text"
+ appearance: 'Gray border, placeholder text'
focus:
- appearance: "Primary color border, label floats up"
+ appearance: 'Primary color border, label floats up'
filled:
- appearance: "Dark border, label stays up"
+ appearance: 'Dark border, label stays up'
error:
- appearance: "Red border, error message below"
+ appearance: 'Red border, error message below'
disabled:
- appearance: "Light gray background, cursor not-allowed"
-
+ appearance: 'Light gray background, cursor not-allowed'
+
signin-form-submit-button:
default:
- appearance: "Primary color background, white text"
+ appearance: 'Primary color background, white text'
hover:
- appearance: "Darker primary color"
+ appearance: 'Darker primary color'
active:
- appearance: "Even darker, slight scale down"
+ appearance: 'Even darker, slight scale down'
loading:
appearance: "Spinner icon, text 'Signing in...'"
disabled:
- appearance: "Gray background, lower opacity"
+ appearance: 'Gray background, lower opacity'
```
---
@@ -121,4 +123,3 @@ component_states:
## NEXT STEP
Load `substeps/4c-07-validation.md`
-
diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-07-validation.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-07-validation.md
index b7373c73..a823fed7 100644
--- a/src/modules/wds/workflows/4-ux-design/substeps/4c-07-validation.md
+++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-07-validation.md
@@ -15,21 +15,22 @@ This ensures users get helpful feedback.
**What fields or inputs need validation?**
For each field, specify:
+
- What makes it valid?
- What makes it invalid?
- When is it validated? (on blur, on submit, real-time?)For each validated field:
- **{{field_name}}** validation:
-
- - Required: yes/no
- - Format rules:
- - Length limits:
- - Custom rules:
- - Validation timing:
+**{{field_name}}** validation:
+
+- Required: yes/no
+- Format rules:
+- Length limits:
+- Custom rules:
+- Validation timing:
-
- Store validation_rules for field
+
+Store validation_rules for field
## ERROR MESSAGES
@@ -39,16 +40,17 @@ For each field, specify:
We'll provide messages in all supported languages.
For each validation rule:
- **Error message when {{rule_name}} fails:**
-
- {{#each language}}
- - {{language}}:
+**Error message when {{rule_name}} fails:**
+
+{{#each language}}
+
+- {{language}}:
{{/each}}
-
- Error code (e.g., ERR_EMAIL_INVALID):
-
-
- Store error_message with code and translations
+
+Error code (e.g., ERR_EMAIL_INVALID):
+
+
+Store error_message with code and translations✅ **Validation and errors defined!**
@@ -72,47 +74,47 @@ We'll provide messages in all supported languages.
validation_rules:
email_input:
required: true
- format: "valid email format"
- timing: "on_blur and on_submit"
+ format: 'valid email format'
+ timing: 'on_blur and on_submit'
rules:
- - "Must contain @"
- - "Must have domain"
- - "No spaces allowed"
-
+ - 'Must contain @'
+ - 'Must have domain'
+ - 'No spaces allowed'
+
password_input:
required: true
min_length: 8
- timing: "on_submit"
+ timing: 'on_submit'
rules:
- - "At least 8 characters"
- - "Not empty"
+ - 'At least 8 characters'
+ - 'Not empty'
error_messages:
ERR_EMAIL_REQUIRED:
- en: "Email address is required"
- sv: "E-postadress krävs"
- field: "email_input"
-
+ en: 'Email address is required'
+ sv: 'E-postadress krävs'
+ field: 'email_input'
+
ERR_EMAIL_INVALID:
- en: "Please enter a valid email address"
- sv: "Ange en giltig e-postadress"
- field: "email_input"
-
+ en: 'Please enter a valid email address'
+ sv: 'Ange en giltig e-postadress'
+ field: 'email_input'
+
ERR_PASSWORD_REQUIRED:
- en: "Password is required"
- sv: "Lösenord krävs"
- field: "password_input"
-
+ en: 'Password is required'
+ sv: 'Lösenord krävs'
+ field: 'password_input'
+
ERR_PASSWORD_TOO_SHORT:
- en: "Password must be at least 8 characters"
- sv: "Lösenordet måste vara minst 8 tecken"
- field: "password_input"
-
+ en: 'Password must be at least 8 characters'
+ sv: 'Lösenordet måste vara minst 8 tecken'
+ field: 'password_input'
+
ERR_AUTH_INVALID:
- en: "Invalid email or password"
- sv: "Ogiltig e-post eller lösenord"
- severity: "critical"
- display_location: "above_form"
+ en: 'Invalid email or password'
+ sv: 'Ogiltig e-post eller lösenord'
+ severity: 'critical'
+ display_location: 'above_form'
```
---
@@ -120,4 +122,3 @@ error_messages:
## NEXT STEP
Load `substeps/4c-08-generate-spec.md`
-
diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-08-generate-spec.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-08-generate-spec.md
index 0a9be87b..28046a5b 100644
--- a/src/modules/wds/workflows/4-ux-design/substeps/4c-08-generate-spec.md
+++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-08-generate-spec.md
@@ -13,6 +13,7 @@ Now I'll compile it all into your complete page specification. 📝
Generate specification document using template at `templates/page-specification.template.md`
Fill in all sections with data collected:
+
- page_basics (from 4C-01)
- layout_sections (from 4C-02)
- components with object_ids (from 4C-03)
@@ -20,7 +21,7 @@ Fill in all sections with data collected:
- interaction_behaviors (from 4C-05)
- page_states and component_states (from 4C-06)
- validation_rules and error_messages (from 4C-07)
-
+
Save complete specification to:
`{output_folder}/C-Scenarios/{scenario}/{page}/{page}.md`
@@ -31,6 +32,7 @@ Fill in all sections with data collected:
**Saved to:** `C-Scenarios/{scenario}/{page}/{page}.md`
**What we documented:**
+
- Page basics and routing
- {{section_count}} layout sections
- {{component_count}} components with Object IDs
@@ -43,6 +45,7 @@ Fill in all sections with data collected:
**Your specification is development-ready!** 📋✨
The specification document includes:
+
- Clear Object IDs for every element
- Complete multilingual content
- Detailed interaction behaviors
@@ -68,12 +71,14 @@ Substep 4C is now complete. Return control to Step 3 (step-03-design-page.md) wh
**Design System Component:** text-input (primary)
**Content:**
+
- **Label (EN):** Email Address
- **Label (SV):** E-postadress
- **Placeholder (EN):** your@email.com
- **Placeholder (SV):** din@epost.com
**States:**
+
- **Default:** Gray border, placeholder visible
- **Focus:** Primary color border, label floats above
- **Filled:** Dark border, label remains above
@@ -81,11 +86,13 @@ Substep 4C is now complete. Return control to Step 3 (step-03-design-page.md) wh
- **Disabled:** Light gray background, not interactive
**Interactions:**
+
- **On Focus:** Highlight border, float label
- **On Input:** Real-time email format validation
- **On Blur:** Full validation, show error if invalid
**Validation:**
+
- Required: Yes
- Format: Valid email (contains @, has domain)
- Error Code: ERR_EMAIL_INVALID
@@ -96,4 +103,3 @@ Substep 4C is now complete. Return control to Step 3 (step-03-design-page.md) wh
---
**Substep 4C Complete!** Return to main page design flow.
-
diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md b/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md
index 7c302149..ce42e118 100644
--- a/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md
+++ b/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md
@@ -7,6 +7,7 @@
**Let's bring your specification to life!**
I'll create an interactive HTML prototype that:
+
- Matches your specification exactly
- Uses your Design System (if Phase 5 enabled)
- Includes interactions and validation
@@ -30,25 +31,27 @@ Choice [1/2/3]:
Generate HTML prototype:
**File 1: HTML** ({page}-Prototype.html)
+
```html
-
-
-
- {{page_title}} - Prototype
-
-
-
-
- {{generate_html_from_spec}}
-
-
-
+
+
+
+ {{page_title}} - Prototype
+
+
+
+
+ {{generate_html_from_spec}}
+
+
+
```
**File 2: CSS** ({page}-Prototype.css)
+
```css
/* Design System tokens (if Phase 5 enabled) */
{{design_system_imports}}
@@ -64,22 +67,44 @@ Choice [1/2/3]:
```
**File 3: JavaScript** ({page}-Prototype.js)
+
```javascript
// Interaction behaviors from specification
-{{generate_interactions_from_spec}}
+{
+ {
+ generate_interactions_from_spec;
+ }
+}
// Validation logic
-{{validation_logic}}
+{
+ {
+ validation_logic;
+ }
+}
// State management
-{{state_management}}
+{
+ {
+ state_management;
+ }
+}
// Language switching
-{{language_switching}}
+{
+ {
+ language_switching;
+ }
+}
// Initialize
-{{initialization_code}}
+{
+ {
+ initialization_code;
+ }
+}
```
+
Save files to {output_folder}/C-Scenarios/{scenario}/{page}/Prototype/
@@ -87,13 +112,15 @@ Choice [1/2/3]:
✅ **Prototype created!**
**Files:**
+
- `Prototype/{page}-Prototype.html`
-- `Prototype/{page}-Prototype.css`
+- `Prototype/{page}-Prototype.css`
- `Prototype/{page}-Prototype.js`
**Open the HTML file in your browser to test!**
Try:
+
- Clicking all interactive elements
- Testing validation
- Switching languages
@@ -103,6 +130,7 @@ Try:
**After testing, what did you discover?**
Common findings:
+
- Visual adjustments needed
- Missing states or interactions
- Content that's too long/short
@@ -117,8 +145,8 @@ Anything to fix or refine?
2. **Quick prototype fix** - Adjust prototype directly
3. **Note for later** - Document but move forward
- Choice [1/2/3]:
-
+Choice [1/2/3]:
+
Return to Step 4C
@@ -156,4 +184,3 @@ Your design is validated and ready for development. Time to extract the function
---
**Next:** Step 4E (PRD Update)
-
diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4e-prd-update.md b/src/modules/wds/workflows/4-ux-design/substeps/4e-prd-update.md
index 0d76945b..7d853f1f 100644
--- a/src/modules/wds/workflows/4-ux-design/substeps/4e-prd-update.md
+++ b/src/modules/wds/workflows/4-ux-design/substeps/4e-prd-update.md
@@ -7,6 +7,7 @@
**Time to capture what we learned!**
Every page reveals concrete requirements:
+
- "This form needs email validation"
- "We need a GET endpoint for availability"
- "Users need to upload images here"
@@ -18,6 +19,7 @@ Capturing these while the page is fresh ensures nothing is forgotten. The PRD be
**Let's identify the functional requirements this page revealed.**
Think about:
+
- API endpoints needed
- Data validation rules
- File upload/storage
@@ -29,13 +31,13 @@ Think about:
What functionality does this page require from the backend/platform?For each requirement:
- **Requirement: {{requirement_name}}**
-
- - What does it do?
- - Why is it needed?
- - Any specific constraints or rules?
-
- Document requirement details
+**Requirement: {{requirement_name}}**
+
+- What does it do?
+- Why is it needed?
+- Any specific constraints or rules?
+
+Document requirement details
## PRD Integration
@@ -43,6 +45,7 @@ What functionality does this page require from the backend/platform?
**I'll add these requirements to your PRD.**
Each requirement will include:
+
- Clear description
- Reference to this page (e.g., "Required by: 2.1-Dog-Calendar")
- Any technical notes discovered during design
@@ -55,13 +58,16 @@ Each requirement will include:
## Functional Requirements
### {{requirement_name}}
+
**Required by:** {{page_reference}}
+
- {{requirement_description}}
- {{constraints}}
- {{technical_notes}}
[Add to appropriate section of PRD]
```
+
Update PRD file with new requirements
@@ -71,8 +77,9 @@ Each requirement will include:
**Added {{requirement_count}} requirements:**
{{#each requirement}}
+
- {{requirement_name}} (required by {{page_reference}})
-{{/each}}
+ {{/each}}
**PRD Location:** `D-PRD/PRD.md`
@@ -83,11 +90,13 @@ Your PRD is growing incrementally with every page you design. This creates compl
**Page "{page_name}" is complete!** 🎉
**Created:**
+
- ✅ Specification: `C-Scenarios/{scenario}/{page}/{page}.md`
- ✅ Prototype: `C-Scenarios/{scenario}/{page}/Prototype/`
- ✅ PRD Requirements: Added to `D-PRD/PRD.md`
**Your page is development-ready with:**
+
- Complete Object ID mapping
- All states and interactions documented
- Multilingual content specified
@@ -128,4 +137,3 @@ Choice [1/2/3/4]:
---
**Step 4E Complete** - Page fully designed and specified!
-
diff --git a/src/modules/wds/workflows/4-ux-design/templates/page-specification.template.md b/src/modules/wds/workflows/4-ux-design/templates/page-specification.template.md
index a17859d8..0857e3ad 100644
--- a/src/modules/wds/workflows/4-ux-design/templates/page-specification.template.md
+++ b/src/modules/wds/workflows/4-ux-design/templates/page-specification.template.md
@@ -14,9 +14,11 @@
**URL/Route:** {url-path}
**Entry Points:**
+
- {How users arrive at this page}
**Exit Points:**
+
- {Where users go after completing their goal}
**Main User Goal:** {Primary objective for users on this page}
@@ -54,6 +56,7 @@
{/if}
**States:**
+
- **Default:** {Description and behavior}
- **Hover:** {Hover state appearance and behavior}
- **Active:** {Active/clicked state}
@@ -65,6 +68,7 @@
{What happens when user interacts with this component}
**Content:**
+
- **English:** {Text content in English}
- **{Language2}:** {Text content in second language}
- **{Language3}:** {Text content in third language}
@@ -119,17 +123,17 @@
{If applicable - for forms and inputs}
-| Field | Rule | Error Code | Error Message |
-|-------|------|------------|---------------|
+| Field | Rule | Error Code | Error Message |
+| ------------ | ----------------- | ---------- | --------------- |
| {field-name} | {validation-rule} | {ERR_CODE} | {error-message} |
---
## Error Messages
-| Error Code | Trigger | Message (English) | Message ({Lang2}) | Recovery |
-|------------|---------|-------------------|-------------------|----------|
-| ERR_001 | {When this error occurs} | {English message} | {Translated message} | {How to fix} |
+| Error Code | Trigger | Message (English) | Message ({Lang2}) | Recovery |
+| ---------- | ------------------------ | ----------------- | -------------------- | ------------ |
+| ERR_001 | {When this error occurs} | {English message} | {Translated message} | {How to fix} |
---
@@ -137,13 +141,14 @@
### Data Sources
-| Data Element | Source | Type | Required | Notes |
-|--------------|--------|------|----------|-------|
+| Data Element | Source | Type | Required | Notes |
+| ------------ | ------------------------ | ----------- | -------- | ------- |
| {data-field} | {API endpoint or static} | {data-type} | {yes/no} | {notes} |
### API Endpoints
**{Endpoint Name}**
+
- **Method:** {GET/POST/PUT/DELETE}
- **Path:** `/api/{path}`
- **Purpose:** {What this endpoint does}
@@ -180,6 +185,7 @@
### User Interactions
**{Interaction Name}**
+
1. User {action}
2. System {response}
3. Page {state change}
@@ -213,6 +219,7 @@
## Development Checklist
Before implementing:
+
- [ ] All Object IDs assigned and documented
- [ ] All states defined and specified
- [ ] Validation rules clear
@@ -224,5 +231,4 @@ Before implementing:
---
-*Created using Whiteport Design Studio (WDS) methodology*
-
+_Created using Whiteport Design Studio (WDS) methodology_
diff --git a/src/modules/wds/workflows/4-ux-design/templates/scenario-overview.template.md b/src/modules/wds/workflows/4-ux-design/templates/scenario-overview.template.md
index 50ffae16..a6961d71 100644
--- a/src/modules/wds/workflows/4-ux-design/templates/scenario-overview.template.md
+++ b/src/modules/wds/workflows/4-ux-design/templates/scenario-overview.template.md
@@ -20,11 +20,11 @@
## Pages in This Scenario
-| Page # | Page Name | Status | Purpose |
-|--------|-----------|--------|---------|
-| {n}.1 | {page-name} | {draft/complete} | {Brief purpose} |
-| {n}.2 | {page-name} | {draft/complete} | {Brief purpose} |
-| {n}.3 | {page-name} | {draft/complete} | {Brief purpose} |
+| Page # | Page Name | Status | Purpose |
+| ------ | ----------- | ---------------- | --------------- |
+| {n}.1 | {page-name} | {draft/complete} | {Brief purpose} |
+| {n}.2 | {page-name} | {draft/complete} | {Brief purpose} |
+| {n}.3 | {page-name} | {draft/complete} | {Brief purpose} |
---
@@ -46,12 +46,14 @@ flowchart TD
## Scenario Steps
### Step 1: {Step Name}
+
**Page:** {n.1-Page-Name}
**User Action:** {What the user does}
**System Response:** {How the system responds}
**Success Criteria:** {What defines success for this step}
### Step 2: {Step Name}
+
**Page:** {n.2-Page-Name}
**User Action:** {What the user does}
**System Response:** {How the system responds}
@@ -84,18 +86,20 @@ This scenario helps users avoid:
**Primary Metric:** {Main measure of scenario success}
**Secondary Metrics:**
+
- {Metric 1}
- {Metric 2}
**User Satisfaction Indicators:**
+
- {What indicates good user experience}
---
## Edge Cases & Error Handling
-| Edge Case | How Handled | Page(s) Affected |
-|-----------|-------------|------------------|
+| Edge Case | How Handled | Page(s) Affected |
+| ----------------------- | ------------------- | ----------------- |
| {edge-case-description} | {handling-approach} | {page-references} |
---
@@ -110,8 +114,8 @@ This scenario helps users avoid:
### API Endpoints Used
-| Endpoint | Page(s) | Purpose |
-|----------|---------|---------|
+| Endpoint | Page(s) | Purpose |
+| --------------- | ----------- | -------------- |
| {endpoint-path} | {page-refs} | {what-it-does} |
### State Management
@@ -125,11 +129,13 @@ This scenario helps users avoid:
**Scenario Folder:** `C-Scenarios/{scenario-number}-{scenario-name}/`
**Page Specifications:**
+
- {n}.1-{page-name}/{page-name}.md
- {n}.2-{page-name}/{page-name}.md
- {n}.3-{page-name}/{page-name}.md
**Prototypes:**
+
- {n}.1-{page-name}/Prototype/
- {n}.2-{page-name}/Prototype/
- {n}.3-{page-name}/Prototype/
@@ -144,11 +150,10 @@ This scenario helps users avoid:
## Revision History
-| Date | Changes | Author |
-|------|---------|--------|
+| Date | Changes | Author |
+| ------ | ------------------------ | -------- |
| {date} | Initial scenario created | {author} |
---
-*Created using Whiteport Design Studio (WDS) methodology*
-
+_Created using Whiteport Design Studio (WDS) methodology_
diff --git a/src/modules/wds/workflows/4-ux-design/workflow.md b/src/modules/wds/workflows/4-ux-design/workflow.md
index 0ac00a9b..b39d2049 100644
--- a/src/modules/wds/workflows/4-ux-design/workflow.md
+++ b/src/modules/wds/workflows/4-ux-design/workflow.md
@@ -1,7 +1,7 @@
---
name: UX Design Workflow
description: Transform ideas into detailed visual specifications through scenario-driven design
-main_config: "{project-root}/{bmad_folder}/wds/config.yaml"
+main_config: '{project-root}/{bmad_folder}/wds/config.yaml'
web_bundle: true
---
@@ -59,4 +59,3 @@ Load and read full config from {main_config} and resolve:
### 2. First Step Execution
Load, read the full file and then execute `steps/step-01-init.md` to begin the workflow.
-
diff --git a/src/modules/wds/workflows/5-design-system/README.md b/src/modules/wds/workflows/5-design-system/README.md
index 16b4c13c..706eddfd 100644
--- a/src/modules/wds/workflows/5-design-system/README.md
+++ b/src/modules/wds/workflows/5-design-system/README.md
@@ -11,11 +11,13 @@
## 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
@@ -27,12 +29,14 @@
**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
@@ -40,6 +44,7 @@
- **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
@@ -79,11 +84,13 @@ Functionality/Storyboards (Behavior)
## 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
@@ -91,11 +98,13 @@ Component specified → Router checks design system
```
### 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
@@ -105,22 +114,26 @@ Component specified → Router checks design system
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
@@ -132,6 +145,7 @@ Component specified → Router checks design system
**Called from:** `workflows/4-ux-design/substeps/4c-03-components-objects.md`
**Integration Point:**
+
```
For each component:
1. Specify component (Phase 4)
@@ -145,6 +159,7 @@ For each component:
```
**Result:**
+
- Page spec contains references + page-specific content
- Design system contains component definitions
- Clean separation maintained
@@ -154,31 +169,37 @@ For each component:
## 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
@@ -192,6 +213,7 @@ For each component:
**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
@@ -210,11 +232,13 @@ For each component:
**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
@@ -222,6 +246,7 @@ For each component:
5. Designer reviews and confirms
**Key Features:**
+
- Component structure guidelines
- Design token mapping
- Variant and state organization
@@ -235,6 +260,7 @@ For each component:
**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
@@ -258,6 +284,7 @@ D-Design-System/
```
**Component File Structure:**
+
```markdown
# Button Component [btn-001]
@@ -266,20 +293,24 @@ D-Design-System/
**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)
diff --git a/src/modules/wds/workflows/5-design-system/assessment/01-scan-existing.md b/src/modules/wds/workflows/5-design-system/assessment/01-scan-existing.md
index 829d792e..902e0c09 100644
--- a/src/modules/wds/workflows/5-design-system/assessment/01-scan-existing.md
+++ b/src/modules/wds/workflows/5-design-system/assessment/01-scan-existing.md
@@ -18,6 +18,7 @@ Scan design system components:
**Example:**
+
```
Current component: Button
@@ -41,6 +42,7 @@ For each matching component, extract:
**Example:**
+
```yaml
Button [btn-001]:
variants: [primary, secondary, ghost]
@@ -70,9 +72,11 @@ Present matching components:
- Shape: rounded
- Used in: 3 pages (login, signup, dashboard)
```
+
**If multiple matches:**
+
```
🔍 Found 2 existing Button components:
@@ -103,6 +107,7 @@ Pass candidate list to comparison step:
## Edge Cases
**No matching components found:**
+
```
✓ No existing Button components in design system.
@@ -112,6 +117,7 @@ This will be the first Button component.
**Route to:** `operations/create-new-component.md`
**Design system empty:**
+
```
✓ Design system is empty.
@@ -121,6 +127,7 @@ This will be the first component.
**Route to:** `operations/initialize-design-system.md`
**Multiple type matches:**
+
```
🔍 Found 2 Button-type components:
@@ -134,6 +141,7 @@ I'll compare your new button to both to find the best match.
## Output Format
**For next step:**
+
```json
{
"current_component": {
diff --git a/src/modules/wds/workflows/5-design-system/assessment/02-compare-attributes.md b/src/modules/wds/workflows/5-design-system/assessment/02-compare-attributes.md
index 3858f511..0c7653d9 100644
--- a/src/modules/wds/workflows/5-design-system/assessment/02-compare-attributes.md
+++ b/src/modules/wds/workflows/5-design-system/assessment/02-compare-attributes.md
@@ -13,6 +13,7 @@
**Compare across 4 dimensions:**
### 1. Visual Attributes
+
- Size (small, medium, large)
- Shape (rounded, square, pill)
- Color scheme
@@ -21,6 +22,7 @@
- Border style
### 2. Functional Attributes
+
- Purpose/intent
- User action
- Input/output type
@@ -28,6 +30,7 @@
- Required/optional
### 3. Behavioral Attributes
+
- States (default, hover, active, disabled, loading, error)
- Interactions (click, hover, focus, blur)
- Animations/transitions
@@ -35,6 +38,7 @@
- Accessibility
### 4. Contextual Attributes
+
- Usage pattern (where it appears)
- Frequency (how often used)
- Relationship to other components
@@ -52,6 +56,7 @@ Compare visual attributes:
**Example:**
+
```
Visual Comparison: Current Button vs Button [btn-001]
@@ -78,6 +83,7 @@ Compare functional attributes:
**Example:**
+
```
Functional Comparison: Current Button vs Button [btn-001]
@@ -105,6 +111,7 @@ Compare behavioral attributes:
**Example:**
+
```
Behavioral Comparison: Current Button vs Button [btn-001]
@@ -131,6 +138,7 @@ Compare contextual attributes:
**Example:**
+
```
Contextual Comparison: Current Button vs Button [btn-001]
@@ -158,11 +166,13 @@ Score each dimension:
**Scoring Guide:**
+
- **High:** 80%+ attributes match
- **Medium:** 50-79% attributes match
- **Low:** <50% attributes match
**Example:**
+
```
Similarity Score: Current Button vs Button [btn-001]
@@ -198,6 +208,7 @@ Present comparison summary:
**Similarity Score:** Medium-High (71%)
```
+
---
@@ -218,6 +229,7 @@ Pass comparison data to similarity calculation:
## Edge Cases
**Perfect match (100%):**
+
```
✓ This component is identical to btn-001.
@@ -227,6 +239,7 @@ 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.
@@ -236,6 +249,7 @@ Despite being the same type, these serve different purposes.
**Recommend:** Create new component
**Multiple candidates:**
+
```
📊 Comparing to 2 candidates:
@@ -252,6 +266,7 @@ btn-001 is the closest match.
## Output Format
**For next step:**
+
```json
{
"comparison": {
diff --git a/src/modules/wds/workflows/5-design-system/assessment/03-calculate-similarity.md b/src/modules/wds/workflows/5-design-system/assessment/03-calculate-similarity.md
index 80421023..138525f4 100644
--- a/src/modules/wds/workflows/5-design-system/assessment/03-calculate-similarity.md
+++ b/src/modules/wds/workflows/5-design-system/assessment/03-calculate-similarity.md
@@ -11,7 +11,9 @@
## Similarity Levels
### Level 1: Identical (95-100%)
+
**Characteristics:**
+
- All visual attributes match
- Same functional purpose
- Same behavioral patterns
@@ -24,7 +26,9 @@
---
### Level 2: Very High Similarity (80-94%)
+
**Characteristics:**
+
- Visual attributes mostly match
- Same core function
- Minor behavioral differences
@@ -37,7 +41,9 @@
---
### Level 3: High Similarity (65-79%)
+
**Characteristics:**
+
- Visual attributes similar
- Related functional purpose
- Some behavioral differences
@@ -50,7 +56,9 @@
---
### Level 4: Medium Similarity (45-64%)
+
**Characteristics:**
+
- Some visual overlap
- Different functional purpose
- Different behaviors
@@ -63,7 +71,9 @@
---
### Level 5: Low Similarity (20-44%)
+
**Characteristics:**
+
- Minimal visual overlap
- Different function
- Different behaviors
@@ -76,7 +86,9 @@
---
### Level 6: No Similarity (<20%)
+
**Characteristics:**
+
- No meaningful overlap
- Completely different purpose
- Unrelated patterns
@@ -107,9 +119,10 @@ Calculate overall similarity:
4. Convert to percentage:
- Similarity % = Overall × 100
-
+
**Example:**
+
```
Dimension Scores:
- Visual: High (1.0)
@@ -137,13 +150,14 @@ Apply calculation logic to comparison data
```
📊 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
+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)
+
```
@@ -157,15 +171,18 @@ Map percentage to similarity level
```
+
**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.
+
```
@@ -179,45 +196,57 @@ Based on similarity level, generate recommendation with reasoning
**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
+
```
---
@@ -230,6 +259,7 @@ Highlight the most important differences that affect the decision
**Example:**
```
+
🔑 Key Decision Factors:
1. **Icon presence** - Current has icon, existing doesn't
@@ -242,6 +272,7 @@ Highlight the most important differences that affect the decision
Impact: Semantic meaning, developer understanding
These differences will affect your decision.
+
```
---
@@ -263,15 +294,18 @@ Pass classification and recommendation to opportunity identification:
**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
@@ -279,19 +313,23 @@ 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 🤔
-```
+
+````
---
@@ -312,7 +350,7 @@ This might indicate:
]
}
}
-```
+````
---
diff --git a/src/modules/wds/workflows/5-design-system/assessment/04-identify-opportunities.md b/src/modules/wds/workflows/5-design-system/assessment/04-identify-opportunities.md
index d84fd400..f97e045b 100644
--- a/src/modules/wds/workflows/5-design-system/assessment/04-identify-opportunities.md
+++ b/src/modules/wds/workflows/5-design-system/assessment/04-identify-opportunities.md
@@ -13,12 +13,15 @@
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
---
@@ -30,24 +33,28 @@ Create separate component in design system
**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
@@ -60,24 +67,28 @@ Create separate component in design system
**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
@@ -90,24 +101,28 @@ Create separate component in design system
**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
@@ -122,6 +137,7 @@ Based on similarity level and comparison, identify which opportunities apply
**Example (72% similarity):**
+
```
Current Situation:
- High visual similarity
@@ -184,6 +200,7 @@ Based on comparison data, identify the most compelling opportunities for each op
**Example:**
+
```
🌟 Strongest Opportunities:
@@ -216,6 +233,7 @@ Factor in project-specific considerations:
**Example:**
+
```
📋 Project Context:
@@ -248,6 +266,7 @@ Pass opportunity analysis to risk identification:
## Edge Cases
**All options have strong opportunities:**
+
```
✨ All Options Look Good!
@@ -260,6 +279,7 @@ This means the risks will be the deciding factor.
```
**No clear opportunities:**
+
```
⚠️ No Strong Opportunities Identified
@@ -271,6 +291,7 @@ I'll focus on risks to help clarify the decision.
```
**Conflicting opportunities:**
+
```
⚠️ Conflicting Opportunities
@@ -287,6 +308,7 @@ Your design philosophy will guide this decision:
## Output Format
**For next step:**
+
```json
{
"opportunities": {
diff --git a/src/modules/wds/workflows/5-design-system/assessment/05-identify-risks.md b/src/modules/wds/workflows/5-design-system/assessment/05-identify-risks.md
index 2aed5d10..0b9cce46 100644
--- a/src/modules/wds/workflows/5-design-system/assessment/05-identify-risks.md
+++ b/src/modules/wds/workflows/5-design-system/assessment/05-identify-risks.md
@@ -15,24 +15,28 @@
**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
@@ -45,24 +49,28 @@
**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
@@ -75,24 +83,28 @@
**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
@@ -107,6 +119,7 @@ Based on similarity level and comparison, identify which risks apply
**Example (72% similarity, different purposes):**
+
```
Current Situation:
- High visual similarity (90%)
@@ -171,6 +184,7 @@ Rate each risk as Low/Medium/High severity based on:
**Example:**
+
```
Risk Severity Assessment:
@@ -202,6 +216,7 @@ Highlight risks that would make an option unsuitable
**Example:**
+
```
🚨 Deal-Breaker Risks:
@@ -230,6 +245,7 @@ For each risk, identify if/how it can be mitigated
**Example:**
+
```
Risk Mitigation:
@@ -268,6 +284,7 @@ Pass risk analysis to decision presentation:
## Edge Cases
**All options have high risks:**
+
```
⚠️ All Options Have Significant Risks
@@ -280,6 +297,7 @@ I'll present all trade-offs clearly so you can make an informed choice.
```
**No significant risks:**
+
```
✅ Low Risk Situation
@@ -292,6 +310,7 @@ Focus on opportunities to decide.
```
**One option has deal-breaker risk:**
+
```
🚨 One Option Not Recommended
@@ -305,6 +324,7 @@ I'll present Variant vs New as the viable options.
## Output Format
**For next step:**
+
```json
{
"risks": {
diff --git a/src/modules/wds/workflows/5-design-system/assessment/06-present-decision.md b/src/modules/wds/workflows/5-design-system/assessment/06-present-decision.md
index ad969c02..5a6093ad 100644
--- a/src/modules/wds/workflows/5-design-system/assessment/06-present-decision.md
+++ b/src/modules/wds/workflows/5-design-system/assessment/06-present-decision.md
@@ -11,18 +11,23 @@
## 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
---
@@ -48,6 +53,7 @@ Let designer decide
✗ Different usage context
**Decision:** How should we handle this in the design system?
+
```
@@ -57,6 +63,7 @@ Let designer decide
```
+
📋 Your Options:
**Option 1: Reuse Existing Component**
@@ -64,11 +71,13 @@ 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]
+
```
@@ -78,22 +87,24 @@ Create separate "Navigation Button" component [btn-002]
```
+
📊 Trade-Offs Comparison:
┌─────────────┬──────────────────┬──────────────────┬──────────────────┐
-│ │ Reuse [btn-001] │ Add Variant │ Create New │
+│ │ 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 │
+│ 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 │
+│ Best For │ Identical use │ Related purposes │ Different roles │
└─────────────┴──────────────────┴──────────────────┴──────────────────┘
Legend: ✅ Strong benefit | ⚠️ Trade-off | ❌ Potential issue
+
```
@@ -103,6 +114,7 @@ Legend: ✅ Strong benefit | ⚠️ Trade-off | ❌ Potential issue
```
+
🔍 Detailed Analysis:
**Option 1: Reuse Button [btn-001]**
@@ -160,6 +172,7 @@ Risks:
Mitigation: Shared design tokens ensure visual consistency
Verdict: ✅ Safest option, especially for semantically different purposes
+
```
@@ -173,6 +186,7 @@ Based on analysis, provide recommendation with reasoning
```
+
🤖 AI Recommendation: Create New Component (Option 3)
**Reasoning:**
@@ -197,8 +211,9 @@ Based on analysis, provide recommendation with reasoning
- Better to establish clear patterns now
- Easier to merge later than split
-**However:** If you expect many button types (delete, cancel, save, etc.),
+**However:** If you expect many button types (delete, cancel, save, etc.),
Option 2 (variant) might be better for organization.
+
```
@@ -208,23 +223,25 @@ Option 2 (variant) might be better for organization.
```
+
💭 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
+→ 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
+→ Choose if: You want button family, expect more button types
[3] Create new "Navigation Button" [btn-002]
- → Choose if: Semantic distinction matters, want independence
+→ Choose if: Semantic distinction matters, want independence
[4] I need more information
- → I can clarify any aspect of the analysis
+→ I can clarify any aspect of the analysis
Your choice (1/2/3/4):
+
```
@@ -238,30 +255,37 @@ Based on designer's choice, route to appropriate operation
**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
@@ -271,6 +295,7 @@ I'll create the new component and set up the reference.
- Something else
Your question:
+
```
**Provide clarification, then re-present decision**
@@ -282,6 +307,7 @@ Your question:
```
+
✨ These components are very similar!
Similarity: 87%
@@ -291,6 +317,7 @@ or different things that happen to look similar?
If same thing → Reuse
If different things → Variant or New
+
```
@@ -298,6 +325,7 @@ If different things → Variant or New
```
+
⚠️ These components are quite different.
Similarity: 38%
@@ -307,6 +335,7 @@ 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?
+
```
@@ -314,6 +343,7 @@ or would you like to see the full analysis?
```
+
🤔 This is a borderline case.
Similarity: 64% (right between "High" and "Medium")
@@ -327,6 +357,7 @@ This could go either way. I'll present both perspectives:
[Present new component option]
Your design philosophy will guide this decision.
+
```
@@ -336,19 +367,23 @@ Your design philosophy will guide this decision.
**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:
@@ -359,21 +394,25 @@ 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.
-```
+
+````
---
@@ -389,7 +428,7 @@ Design systems evolve - this isn't permanent.
"designer_notes": "Navigation and submission are different actions"
}
}
-```
+````
---
diff --git a/src/modules/wds/workflows/5-design-system/assessment/07-execute-decision.md b/src/modules/wds/workflows/5-design-system/assessment/07-execute-decision.md
index fe282f27..cef86d4b 100644
--- a/src/modules/wds/workflows/5-design-system/assessment/07-execute-decision.md
+++ b/src/modules/wds/workflows/5-design-system/assessment/07-execute-decision.md
@@ -11,12 +11,15 @@
## 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
---
@@ -30,7 +33,8 @@ Designer chose to create new component
✅ Reusing Button [btn-001]
I'll update your page spec to reference the existing component.
-```
+
+````
### Step 2: Extract Page-Specific Content
@@ -49,7 +53,7 @@ Page-Specific Content:
- label: "Continue"
- why: "Navigate to next step in onboarding"
- context: "Multi-step form navigation"
-```
+````
### Step 3: Create Reference
@@ -61,13 +65,14 @@ Create reference to existing component:
**Output:**
+
```yaml
# C-Scenarios/onboarding-page.md
Continue Button:
component: Button.primary [btn-001]
why: Navigate to next step in onboarding
- label: "Continue"
+ label: 'Continue'
```
### Step 4: Update Component Usage
@@ -79,14 +84,15 @@ Update design system component to track usage:
**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
+ - Login page (login button)
+ - Signup page (create account button)
+ - Dashboard (action buttons)
+ - Onboarding page (continue button) ← Added
```
### Step 5: Complete
@@ -97,6 +103,7 @@ Used In:
Page spec updated with reference.
Component usage tracked.
+
```
@@ -110,10 +117,12 @@ Component usage tracked.
```
+
✅ Adding "navigation" variant to Button [btn-001]
I'll update the component definition and create the reference.
-```
+
+````
### Step 2: Extract Component-Level Info
@@ -131,7 +140,7 @@ Navigation Variant:
- icon: arrow-right
- loading_state: true
- hover_animation: icon_shift
-```
+````
### Step 3: Update Component Definition
@@ -143,19 +152,19 @@ Add variant to existing component:
**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
@@ -170,13 +179,14 @@ Create reference with variant specified:
**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"
+ label: 'Continue'
```
### Step 5: Update Usage Tracking
@@ -186,6 +196,7 @@ Track variant usage:
**Update:**
+
```yaml
# D-Design-System/components/button.md
@@ -204,6 +215,7 @@ Variant Usage:
Component definition updated.
Page spec created with variant reference.
Variant usage tracked.
+
```
@@ -217,9 +229,11 @@ Variant usage tracked.
```
+
✅ Creating new Navigation Button [btn-002]
I'll create the component definition and set up the reference.
+
```
@@ -234,9 +248,11 @@ Generate unique component ID:
**Example:**
```
+
Existing Button IDs: btn-001
New ID: btn-002
-```
+
+````
### Step 3: Extract Component-Level Info
@@ -259,7 +275,7 @@ Component-Level Info:
color: blue
shape: rounded
hover_animation: icon_shift
-```
+````
### Step 4: Create Component File
@@ -270,6 +286,7 @@ Create new component file using template:
**Route to:** `operations/create-new-component.md`
**Output:**
+
```yaml
# D-Design-System/components/navigation-button.md
@@ -305,13 +322,14 @@ Create reference in page spec:
**Output:**
+
```yaml
# C-Scenarios/onboarding-page.md
Continue Button:
component: NavigationButton [btn-002]
why: Navigate to next step in onboarding
- label: "Continue"
+ label: 'Continue'
```
### Step 6: Update Design System Index
@@ -321,14 +339,15 @@ Add to design system component list:
**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
+ - 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
@@ -340,7 +359,8 @@ Components:
Component file created: D-Design-System/components/navigation-button.md
Page spec created with reference.
Design system index updated.
-```
+
+````
**Return to Phase 4**
@@ -366,7 +386,7 @@ Update project tracking:
- Reason: Semantic distinction from submit buttons
- Decision: Create new vs variant
- Designer: Chose clarity over consistency
-```
+````
### Notify Designer
@@ -377,8 +397,9 @@ Update project tracking:
Components: 4 (was 3)
Latest: Navigation Button [btn-002]
-Your design system is growing! Consider reviewing component
+Your design system is growing! Consider reviewing component
organization when you reach 10+ components.
+
```
@@ -388,35 +409,42 @@ organization when you reach 10+ components.
**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
+
```
---
@@ -436,13 +464,16 @@ Validate execution:
**If validation fails:**
```
+
⚠️ Validation Warning:
Some steps may not have completed successfully.
Please review:
+
- [List of potential issues]
Continue anyway? (y/n)
+
```
---
@@ -467,6 +498,7 @@ Return control to Phase 4 orchestration:
```
+
✅ Design System Operation Complete
Action: Created new component
@@ -475,14 +507,17 @@ 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
+
```
---
**This completes the assessment and execution flow. Control returns to Phase 4.**
+```
diff --git a/src/modules/wds/workflows/5-design-system/design-system-router.md b/src/modules/wds/workflows/5-design-system/design-system-router.md
index d9c50d3a..0c4d6967 100644
--- a/src/modules/wds/workflows/5-design-system/design-system-router.md
+++ b/src/modules/wds/workflows/5-design-system/design-system-router.md
@@ -9,13 +9,15 @@
## 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:**
+**Output:**
+
- Design system entry (component-level info)
- Page specification reference (page-specific info)
@@ -138,6 +140,7 @@ Check if design system folder exists:
🎉 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`
@@ -146,7 +149,9 @@ I'll initialize the design system structure and add this component.
**If not first:**
```
+
📊 Checking existing design system for similar components...
+
```
**Continue to Step 3**
@@ -166,10 +171,13 @@ Scan design system folder:
**Existing components found:**
```
+
Found 3 existing components:
+
- Button [btn-001]
- Input Field [inp-001]
- Card [crd-001]
+
```
**Continue to Step 4**
@@ -178,7 +186,9 @@ Found 3 existing components:
**No similar components:**
```
+
No similar components found in design system.
+
```
**Route to:** `operations/create-new-component.md`
@@ -198,9 +208,11 @@ Compare current component to existing:
**Type match found:**
```
+
🔍 Found existing Button component [btn-001]
Checking similarity...
+
```
**Route to:** `assessment/01-scan-existing.md`
@@ -209,8 +221,10 @@ Checking similarity...
**No type match:**
```
+
This is a new component type: [ComponentType]
-```
+
+````
**Route to:** `operations/create-new-component.md`
@@ -255,24 +269,26 @@ Login Button:
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"
+ 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: {...}
+ styling: { ... }
```
---
@@ -280,6 +296,7 @@ Button Component [btn-001]:
## Router Characteristics
**✅ Does:**
+
- Check design system status
- Identify first component
- Scan existing components
@@ -287,6 +304,7 @@ Button Component [btn-001]:
- Route to appropriate operation
**❌ Doesn't:**
+
- Make design decisions
- Contain specification logic
- Store component knowledge
@@ -300,12 +318,14 @@ Button Component [btn-001]:
## 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.
@@ -321,6 +341,7 @@ Your choice:
```
**If similarity check fails:**
+
```
⚠️ I couldn't determine similarity automatically.
@@ -337,6 +358,7 @@ Your choice:
## Next Steps
**After routing:**
+
- Follow the routed operation instructions
- Complete design system entry
- Return reference to Phase 4
diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/figma-designer-guide.md b/src/modules/wds/workflows/5-design-system/figma-integration/figma-designer-guide.md
index 320397f8..feb9e836 100644
--- a/src/modules/wds/workflows/5-design-system/figma-integration/figma-designer-guide.md
+++ b/src/modules/wds/workflows/5-design-system/figma-integration/figma-designer-guide.md
@@ -22,6 +22,7 @@
### Create Design System File
**File structure:**
+
```
[Project Name] Design System
├── 📄 Cover
@@ -39,6 +40,7 @@
```
**Tips:**
+
- Use clear page names
- Organize by component type
- Keep foundation separate
@@ -51,6 +53,7 @@
**Create Figma variables:**
**Colors:**
+
```
Collection: Colors
├── primary/50
@@ -63,6 +66,7 @@ Collection: Colors
```
**Spacing:**
+
```
Collection: Spacing
├── spacing/1 = 4px
@@ -73,6 +77,7 @@ Collection: Spacing
```
**Typography:**
+
```
Styles: Typography
├── Display/Large
@@ -89,6 +94,7 @@ Styles: Typography
### Example: Button Component
**1. Create Base Frame**
+
```
Frame name: Button/Primary [btn-001]
Size: Hug contents (width), Fixed 44px (height)
@@ -98,6 +104,7 @@ Gap: 8px
```
**2. Add Content**
+
```
├── Icon (optional)
│ └── Size: 20x20px
@@ -107,6 +114,7 @@ Gap: 8px
```
**3. Apply Design Tokens**
+
```
Background: primary/600 (variable)
Text Color: white (variable)
@@ -114,6 +122,7 @@ Border Radius: 8px
```
**4. Create Component**
+
```
Select frame → Create Component
Name: Button/Primary [btn-001]
@@ -124,6 +133,7 @@ Name: Button/Primary [btn-001]
### Add Component Description
**In component description field:**
+
```
Button Primary [btn-001]
@@ -158,16 +168,19 @@ Primary action button for main user actions.
**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
```
@@ -177,6 +190,7 @@ Values: Default, Hover, Active, Disabled, Loading
### Design Each Variant
**Type=Primary, Size=Medium, State=Default:**
+
```
Background: primary/600
Text: white
@@ -184,6 +198,7 @@ Padding: 16px × 12px
```
**Type=Primary, Size=Medium, State=Hover:**
+
```
Background: primary/700 (darker)
Text: white
@@ -191,6 +206,7 @@ Scale: 1.02 (slightly larger)
```
**Type=Primary, Size=Medium, State=Active:**
+
```
Background: primary/800 (darkest)
Text: white
@@ -198,6 +214,7 @@ Scale: 0.98 (slightly smaller)
```
**Type=Primary, Size=Medium, State=Disabled:**
+
```
Background: gray/300
Text: gray/500
@@ -206,6 +223,7 @@ Cursor: not-allowed
```
**Type=Primary, Size=Medium, State=Loading:**
+
```
Background: primary/600
Text: white
@@ -218,6 +236,7 @@ Opacity: 0.8
### Adjust for Sizes
**Small:**
+
```
Padding: 12px × 8px
Text: Body/Small
@@ -226,6 +245,7 @@ Height: 36px
```
**Medium (default):**
+
```
Padding: 16px × 12px
Text: Body/Medium
@@ -234,6 +254,7 @@ Height: 44px
```
**Large:**
+
```
Padding: 20px × 16px
Text: Body/Large
@@ -248,6 +269,7 @@ Height: 52px
### Visual State Indicators
**Create a documentation frame:**
+
```
Frame: Button States Documentation
├── Default
@@ -263,6 +285,7 @@ Frame: Button States Documentation
```
**Add annotations:**
+
- State name
- Visual changes
- Interaction behavior
@@ -279,6 +302,7 @@ Frame: Button States Documentation
**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
@@ -289,6 +313,7 @@ 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
@@ -303,16 +328,19 @@ Button [btn-001] → figma://file/abc123/node/456:789
**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
@@ -327,18 +355,21 @@ Button [btn-001] → figma://file/abc123/node/456:789
**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
@@ -352,16 +383,19 @@ wds figma sync Button/Primary
**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
@@ -373,11 +407,13 @@ wds figma sync Button/Primary
**Track component changes:**
**In Figma:**
+
- Use Figma version history
- Add version notes
- Tag major changes
**In WDS:**
+
```markdown
## Version History
@@ -385,6 +421,7 @@ wds figma sync Button/Primary
**Last Updated:** 2024-12-15
**Changes:**
+
- 2024-12-09: Created component
- 2024-12-12: Added loading state
- 2024-12-15: Updated hover animation
@@ -397,26 +434,31 @@ wds figma sync Button/Primary
### 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
@@ -426,26 +468,31 @@ wds figma sync Button/Primary
### 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
@@ -457,26 +504,31 @@ wds figma sync Button/Primary
### 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
@@ -486,21 +538,25 @@ wds figma sync Button/Primary
### 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
@@ -510,21 +566,25 @@ wds figma sync Button/Primary
### 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
@@ -538,6 +598,7 @@ wds figma sync Button/Primary
**Problem:** MCP can't read component
**Solutions:**
+
- Check component name format
- Verify WDS component ID in description
- Ensure component is published
@@ -550,6 +611,7 @@ wds figma sync Button/Primary
**Problem:** Some variants missing in WDS
**Solutions:**
+
- Check variant property names
- Verify all combinations exist
- Ensure consistent naming
@@ -562,6 +624,7 @@ wds figma sync Button/Primary
**Problem:** Hardcoded values instead of variables
**Solutions:**
+
- Replace hex colors with variables
- Use spacing variables
- Apply text styles
@@ -574,6 +637,7 @@ wds figma sync Button/Primary
**Problem:** Updates break instance overrides
**Solutions:**
+
- Don't change component structure
- Add new properties instead
- Maintain backward compatibility
diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/figma-mcp-integration.md b/src/modules/wds/workflows/5-design-system/figma-integration/figma-mcp-integration.md
index bde13b4e..9b8b487e 100644
--- a/src/modules/wds/workflows/5-design-system/figma-integration/figma-mcp-integration.md
+++ b/src/modules/wds/workflows/5-design-system/figma-integration/figma-mcp-integration.md
@@ -9,6 +9,7 @@
## Overview
**Figma MCP enables:**
+
- Reading component specifications from Figma
- Extracting design tokens
- Generating WDS component specifications
@@ -46,6 +47,7 @@
```
**Get Figma API token:**
+
1. Go to Figma → Settings → Account
2. Scroll to "Personal access tokens"
3. Click "Generate new token"
@@ -60,17 +62,20 @@
**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
@@ -106,15 +111,18 @@ MCP Response:
**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
@@ -136,14 +144,17 @@ MCP Response:
**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]
@@ -163,15 +174,18 @@ MCP Response:
**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
@@ -203,6 +217,7 @@ MCP Response:
**Process:**
**Step 1: Detect Change**
+
```
Designer updates Button/Primary in Figma
Designer notifies WDS system
@@ -210,6 +225,7 @@ Or: Automated webhook triggers sync
```
**Step 2: Read Component**
+
```
Agent: Read Figma component Button/Primary [btn-001]
@@ -223,6 +239,7 @@ MCP reads:
```
**Step 3: Parse Component Data**
+
```
Agent extracts:
- Component type: Button
@@ -234,6 +251,7 @@ Agent extracts:
```
**Step 4: Generate WDS Specification**
+
```
Agent creates/updates:
D-Design-System/components/button.md
@@ -248,6 +266,7 @@ Filling in:
```
**Step 5: Update Mappings**
+
```
Agent updates:
D-Design-System/figma-mappings.md
@@ -257,6 +276,7 @@ Button [btn-001] → figma://file/abc123/node/456:789
```
**Step 6: Verify and Confirm**
+
```
Agent presents generated spec to designer
Designer reviews and confirms
@@ -272,18 +292,21 @@ Spec is committed to repository
**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.
@@ -298,6 +321,7 @@ Figma component: [Link to Figma]"
```
**Step 4: Designer Updates Figma**
+
```
Designer reviews changes
Updates Figma component
@@ -315,6 +339,7 @@ Confirms sync complete
**Agent uses component template:**
**Input:**
+
```
Figma component data:
{
@@ -331,6 +356,7 @@ Figma component data:
**Output:** `D-Design-System/components/button.md`
**Process:**
+
1. Load component template
2. Fill in component name and ID
3. Extract and format variants
@@ -349,6 +375,7 @@ Figma component data:
**Figma variables → WDS tokens:**
**Agent maps:**
+
```
Figma: primary/600 → WDS: color-primary-600
Figma: spacing/4 → WDS: spacing-4
@@ -357,6 +384,7 @@ Figma: shadow/sm → WDS: shadow-sm
```
**Mapping rules:**
+
- Figma collection/variable → WDS category-name-value
- Maintain semantic meaning
- Consistent naming across systems
@@ -371,6 +399,7 @@ Figma: shadow/sm → WDS: shadow-sm
**Error:** Figma component doesn't exist
**Agent response:**
+
```
⚠️ Component not found in Figma
@@ -397,6 +426,7 @@ Actions:
**Error:** Figma component has no WDS ID in description
**Agent response:**
+
```
⚠️ WDS Component ID missing
@@ -417,6 +447,7 @@ After adding ID, re-sync component.
**Error:** Can't map Figma variable to WDS token
**Agent response:**
+
```
⚠️ Token mapping failed
@@ -438,6 +469,7 @@ Your choice:
**Error:** Figma and WDS have different versions
**Agent response:**
+
```
⚠️ Sync conflict detected
@@ -466,6 +498,7 @@ Your choice:
### For AI Agents
**DO ✅**
+
- Always check for WDS component ID in Figma
- Verify token mappings before generating specs
- Present generated specs for designer review
@@ -473,6 +506,7 @@ Your choice:
- 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
@@ -484,6 +518,7 @@ Your choice:
### For Designers
**DO ✅**
+
- Add WDS component ID to all Figma components
- Use design tokens (variables) consistently
- Document component changes
@@ -491,6 +526,7 @@ Your choice:
- Review generated specs before committing
**DON'T ❌**
+
- Don't use hardcoded values
- Don't skip component descriptions
- Don't forget to sync after changes
@@ -504,6 +540,7 @@ Your choice:
### 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
@@ -517,6 +554,7 @@ Your choice:
### Phase 5: Design System
**When component is added to design system:**
+
1. Component specification complete
2. Agent checks: Figma component exists?
3. If yes:
@@ -532,30 +570,35 @@ Your choice:
## 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
@@ -568,6 +611,7 @@ MCP: Reads component, generates spec, updates mappings
### MCP Server Not Responding
**Check:**
+
- MCP server is running
- Figma API token is valid
- Network connection is active
@@ -580,6 +624,7 @@ MCP: Reads component, generates spec, updates mappings
**Error:** 403 Forbidden
**Solution:**
+
1. Generate new Figma API token
2. Update MCP configuration
3. Restart MCP server
@@ -592,6 +637,7 @@ MCP: Reads component, generates spec, updates mappings
**Error:** 429 Too Many Requests
**Solution:**
+
- Wait before retrying
- Batch operations when possible
- Cache component data
@@ -602,6 +648,7 @@ MCP: Reads component, generates spec, updates mappings
## Future Enhancements
**Planned features:**
+
- Automated sync on Figma changes (webhooks)
- Bidirectional sync (WDS → Figma write)
- Batch component import
diff --git a/src/modules/wds/workflows/5-design-system/operations/add-variant.md b/src/modules/wds/workflows/5-design-system/operations/add-variant.md
index 02e7f1a9..307f2345 100644
--- a/src/modules/wds/workflows/5-design-system/operations/add-variant.md
+++ b/src/modules/wds/workflows/5-design-system/operations/add-variant.md
@@ -21,6 +21,7 @@ Read existing component file:
**Example:**
+
```yaml
Component: Button [btn-001]
Current Variants:
@@ -34,7 +35,8 @@ Current Variants:
Current variants: 2 (primary, secondary)
Adding new variant: navigation
-```
+
+````
---
@@ -62,7 +64,7 @@ Different from existing:
- Has loading state
- Icon animation on hover
- Purpose: navigation vs submission
-```
+````
---
@@ -76,6 +78,7 @@ Generate descriptive variant name:
**Examples:**
+
```
Purpose-based:
- navigation (for navigation actions)
@@ -101,7 +104,8 @@ This variant is for navigation actions (continue, next, proceed).
Is this name clear and appropriate? (y/n)
Or suggest alternative name:
-```
+
+````
---
@@ -120,34 +124,39 @@ Add variant to component definition:
- **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
+- **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
+**Navigation:** ← Added
+
- Background: blue-600
- Icon: arrow-right
- Loading: spinner + icon
@@ -157,10 +166,12 @@ Add variant to component definition:
### 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
@@ -169,6 +180,7 @@ Add variant to component definition:
**Variant-Specific States:**
**Navigation:**
+
- loading (shows spinner, disables interaction)
```
@@ -181,14 +193,16 @@ Track new variant usage:
**Add to component file:**
+
```markdown
## Variant Usage
**Primary:** 5 pages
**Secondary:** 3 pages
-**Navigation:** 1 page ← Added
+**Navigation:** 1 page ← Added
**Navigation variant used in:**
+
- Onboarding page (continue button)
```
@@ -201,10 +215,12 @@ Add note about variant count:
**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?
@@ -221,6 +237,7 @@ Check for potential issues:
**Variant Explosion Check:**
+
```
⚠️ Variant Count: 3
@@ -230,6 +247,7 @@ Recommended maximum: 5 variants per component
```
**Consistency Check:**
+
```
✓ New variant consistent with existing variants
✓ Naming convention followed
@@ -237,6 +255,7 @@ Recommended maximum: 5 variants per component
```
**Complexity Check:**
+
```
⚠️ Navigation variant adds loading state not present in other variants.
@@ -256,6 +275,7 @@ Track component changes:
**Update version history:**
+
```markdown
## Version History
@@ -263,8 +283,9 @@ Track component changes:
**Last Updated:** 2024-12-09
**Changes:**
+
- 2024-12-01: Created component with primary and secondary variants
-- 2024-12-09: Added navigation variant ← Added
+- 2024-12-09: Added navigation variant ← Added
```
---
@@ -276,6 +297,7 @@ Generate reference for page spec:
**Output:**
+
```yaml
component_reference:
id: btn-001
@@ -297,6 +319,7 @@ New Variant: navigation
Total Variants: 3 (primary, secondary, navigation)
Component file updated:
+
- Variant added to list
- Variant-specific styling documented
- Usage tracking added
@@ -305,6 +328,7 @@ Component file updated:
Reference ready for page spec.
Next: Return to Phase 4 to complete page specification
+
```
@@ -314,25 +338,30 @@ Next: Return to Phase 4 to complete page specification
```
+
💡 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!
+
```
@@ -356,9 +385,11 @@ Validate variant addition:
**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
@@ -367,38 +398,46 @@ 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
@@ -408,11 +447,13 @@ 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:
+
```
---
@@ -425,6 +466,7 @@ After adding variant, check component health:
**Component Health Check:**
```
+
📊 Component Health: Button [btn-001]
Variants: 3
@@ -435,11 +477,14 @@ 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.**
+```
diff --git a/src/modules/wds/workflows/5-design-system/operations/create-new-component.md b/src/modules/wds/workflows/5-design-system/operations/create-new-component.md
index 23e11e1e..d54d24e1 100644
--- a/src/modules/wds/workflows/5-design-system/operations/create-new-component.md
+++ b/src/modules/wds/workflows/5-design-system/operations/create-new-component.md
@@ -21,6 +21,7 @@ Generate unique component ID:
**Type Prefixes:**
+
```
Button → btn
Input Field → inp
@@ -51,6 +52,7 @@ Spacer → spc
```
**Example:**
+
```
Component Type: Button
Existing Button IDs: btn-001, btn-002
@@ -78,6 +80,7 @@ Categorize component for organization:
**Example:**
+
```
Component: Button
Category: Interactive
@@ -91,6 +94,7 @@ Category: Interactive
From complete specification, extract component-level info:
**Visual Attributes:**
+
- Size (small, medium, large)
- Shape (rounded, square, pill)
- Color scheme
@@ -99,6 +103,7 @@ From complete specification, extract component-level info:
- Border style
**Behavioral Attributes:**
+
- States (default, hover, active, disabled, loading, error)
- Interactions (click, hover, focus, blur)
- Animations/transitions
@@ -106,17 +111,19 @@ From complete specification, extract component-level info:
- 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)
-
+
---
@@ -130,7 +137,7 @@ Use component template to create file:
**Template Structure:**
-```markdown
+````markdown
# [Component Name] [component-id]
**Type:** [Interactive/Form/Layout/Content/Feedback/Navigation]
@@ -150,6 +157,7 @@ Use component template to create file:
[If component has variants, list them]
**Example:**
+
- primary - Main call-to-action
- secondary - Secondary actions
- ghost - Subtle actions
@@ -162,12 +170,14 @@ This component has no variants.
## States
**Required States:**
+
- default
- hover
- active
- disabled
**Optional States:**
+
- loading
- error
- success
@@ -191,24 +201,26 @@ This component has no variants.
### 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
@@ -245,6 +257,7 @@ effects:
### Animations
[If component has animations:]
+
- [Animation description]
- Duration: [ms]
- Easing: [easing function]
@@ -254,12 +267,14 @@ effects:
## 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]
@@ -294,6 +309,7 @@ effects:
**Usage Count:** [Number]
**Examples:**
+
- [Page name] - [Specific usage]
- [Page name] - [Specific usage]
@@ -302,6 +318,7 @@ effects:
## Related Components
[If this component is related to others:]
+
- [Related component 1] - [Relationship]
- [Related component 2] - [Relationship]
@@ -313,6 +330,7 @@ effects:
**Last Updated:** [Date]
**Changes:**
+
- [Date]: Created component
- [Date]: [Change description]
@@ -321,7 +339,8 @@ effects:
## Notes
[Any additional notes, considerations, or future plans]
-```
+
+````
---
@@ -385,7 +404,7 @@ Use buttons for important actions that change state or navigate to new content.
**Size:** medium (h-10, px-4)
**Shape:** rounded (border-radius: 0.375rem)
-**Colors:**
+**Colors:**
- Background: blue-600
- Text: white
- Border: none
@@ -409,21 +428,21 @@ colors:
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
@@ -441,26 +460,31 @@ effects:
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
@@ -469,12 +493,14 @@ Triggers associated action (form submit, navigation, etc.)
## 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
@@ -515,6 +541,7 @@ Announces button label and state (disabled, busy, etc.)
**Usage Count:** 1
**Examples:**
+
- Login page - Submit credentials button
---
@@ -532,6 +559,7 @@ Announces button label and state (disabled, busy, etc.)
**Last Updated:** 2024-12-09
**Changes:**
+
- 2024-12-09: Created component
---
@@ -539,7 +567,8 @@ Announces button label and state (disabled, busy, etc.)
## Notes
This is the primary button component. Consider adding more variants as needs emerge (danger, success, etc.).
-```
+
+````
---
@@ -560,7 +589,7 @@ Add component to index:
- Button [btn-003] - Standard action button ← Added
**Total Interactive:** 3
-```
+````
---
@@ -587,6 +616,7 @@ Generate reference for page spec:
**Output:**
+
```yaml
component_reference:
id: btn-003
@@ -613,6 +643,7 @@ Design system stats updated.
Reference ready for page spec.
Next: Return to Phase 4 to complete page specification
+
```
@@ -636,36 +667,45 @@ Validate component creation:
**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.**
+```
diff --git a/src/modules/wds/workflows/5-design-system/operations/generate-catalog.md b/src/modules/wds/workflows/5-design-system/operations/generate-catalog.md
index 56e3f47f..98b74f41 100644
--- a/src/modules/wds/workflows/5-design-system/operations/generate-catalog.md
+++ b/src/modules/wds/workflows/5-design-system/operations/generate-catalog.md
@@ -2,7 +2,8 @@
**Purpose:** Create/update the interactive HTML catalog that showcases all design system components with live examples.
-**When to run:**
+**When to run:**
+
- After initializing design system
- After creating new component
- After adding variant
@@ -14,6 +15,7 @@
## 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
@@ -26,12 +28,14 @@ The interactive catalog is a **living documentation** of the design system:
## 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
@@ -42,9 +46,11 @@ The interactive catalog is a **living documentation** of the design system:
## Output
**Generated File:**
+
- `D-Design-System/catalog.html` - Interactive HTML catalog
**Features:**
+
- Fixed sidebar navigation
- Live component previews
- Interactive state toggles
@@ -65,6 +71,7 @@ Load catalog template:
**File:** `workflows/5-design-system/templates/catalog.template.html`
**Template variables:**
+
```
{{PROJECT_NAME}}
{{PROJECT_ICON}}
@@ -96,16 +103,18 @@ Extract project metadata:
**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"
+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
@@ -120,6 +129,7 @@ Build component navigation from component files:
**Scan components:**
+
```
D-Design-System/components/
├── button.md [btn-001]
@@ -129,6 +139,7 @@ D-Design-System/components/
```
**Group by category:**
+
```
Interactive:
- Button [btn-001]
@@ -144,21 +155,22 @@ Display:
```
**Generate HTML:**
+
```html