ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

chore: apply formatting updates across BMAD v6

This commit is contained in:
Mårten Angner 2025-12-10 17:27:28 +01:00
parent 2e72ed0be6
commit b970527ab2
226 changed files with 6978 additions and 3008 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG.md
View File

@ -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) **See detailed log:** [conversion-logs/session-2025-12-09-micro-steps-concepts.md](./conversion-logs/session-2025-12-09-micro-steps-concepts.md)
**Summary:** **Summary:**
- ✅ Phase 6: Design Deliveries (7 micro-step files) - ✅ Phase 6: Design Deliveries (7 micro-step files)
- ✅ Phase 7: Testing (8 micro-step files) - ✅ Phase 7: Testing (8 micro-step files)
- ✅ Phase 8: Ongoing Development (9 micro-step files) - ✅ Phase 8: Ongoing Development (9 micro-step files)

27
CONCEPTS-INTEGRATION.md
View File

@ -7,9 +7,11 @@
## Core Documentation ## Core Documentation
### Glossary (Complete Reference) ### Glossary (Complete Reference)
**File:** `src/core/resources/wds/glossary.md` **File:** `src/core/resources/wds/glossary.md`
**Contains:** **Contains:**
- ✅ Greenfield Development (definition, origin, examples) - ✅ Greenfield Development (definition, origin, examples)
- ✅ Brownfield Development (definition, origin, examples) - ✅ Brownfield Development (definition, origin, examples)
- ✅ Kaizen (改善) - Continuous Improvement (definition, philosophy, examples) - ✅ Kaizen (改善) - Continuous Improvement (definition, philosophy, examples)
@ -26,9 +28,11 @@
## Workflow Documentation ## Workflow Documentation
### 1. Project Type Selection ### 1. Project Type Selection
**File:** `src/modules/wds/workflows/workflow-init/project-type-selection.md` **File:** `src/modules/wds/workflows/workflow-init/project-type-selection.md`
**Concepts integrated:** **Concepts integrated:**
- ✅ **Greenfield Development** - New Product entry point - ✅ **Greenfield Development** - New Product entry point
- ✅ **Brownfield Development** - Existing Product entry point - ✅ **Brownfield Development** - Existing Product entry point
- ✅ Definitions and origins - ✅ Definitions and origins
@ -38,6 +42,7 @@
**Section:** "Software Development Terminology" **Section:** "Software Development Terminology"
**Usage:** **Usage:**
``` ```
Which type of project are you working on? Which type of project are you working on?
@ -48,9 +53,11 @@ Which type of project are you working on?
--- ---
### 2. Phase 8 Workflow ### 2. Phase 8 Workflow
**File:** `src/modules/wds/workflows/8-ongoing-development/workflow.md` **File:** `src/modules/wds/workflows/8-ongoing-development/workflow.md`
**Concepts integrated:** **Concepts integrated:**
- ✅ **Kaizen (改善)** - Continuous Improvement (detailed) - ✅ **Kaizen (改善)** - Continuous Improvement (detailed)
- ✅ **Kaikaku (改革)** - Revolutionary Change (detailed) - ✅ **Kaikaku (改革)** - Revolutionary Change (detailed)
- ✅ When to use each approach - ✅ When to use each approach
@ -60,6 +67,7 @@ Which type of project are you working on?
**Section:** "Lean Manufacturing Philosophy" **Section:** "Lean Manufacturing Philosophy"
**Key insight:** **Key insight:**
``` ```
Kaikaku (改革): Build product v1.0 (Phases 1-7) Kaikaku (改革): Build product v1.0 (Phases 1-7)
↓ ↓
@ -73,9 +81,11 @@ Kaizen cycle 1, 2, 3, 4, 5... (ongoing)
--- ---
### 3. Existing Product Guide ### 3. Existing Product Guide
**File:** `src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md` **File:** `src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md`
**Concepts integrated:** **Concepts integrated:**
- ✅ **Brownfield + Kaizen** - Phase 8 approach - ✅ **Brownfield + Kaizen** - Phase 8 approach
- ✅ **Greenfield + Kaikaku** - Phases 1-7 approach - ✅ **Greenfield + Kaikaku** - Phases 1-7 approach
- ✅ Terminology explanations - ✅ Terminology explanations
@ -88,9 +98,11 @@ Kaizen cycle 1, 2, 3, 4, 5... (ongoing)
--- ---
### 4. Phase 8 Step 8.8 (Iterate) ### 4. Phase 8 Step 8.8 (Iterate)
**File:** `src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md` **File:** `src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md`
**Concepts integrated:** **Concepts integrated:**
- ✅ **Kaizen vs Kaikaku** comparison - ✅ **Kaizen vs Kaikaku** comparison
- ✅ Quick reference for designers - ✅ Quick reference for designers
- ✅ Link to glossary - ✅ Link to glossary
@ -105,9 +117,11 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai
## Concept Usage by WDS Phase ## Concept Usage by WDS Phase
### Phases 1-7: New Product Development ### Phases 1-7: New Product Development
**Approach:** Greenfield + Kaikaku **Approach:** Greenfield + Kaikaku
**Characteristics:** **Characteristics:**
- Starting from scratch - Starting from scratch
- Complete user flows - Complete user flows
- Revolutionary change - Revolutionary change
@ -115,15 +129,18 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai
- Months of work - Months of work
**Concepts:** **Concepts:**
- Greenfield Development - Greenfield Development
- Kaikaku (改革) - Revolutionary Change - Kaikaku (改革) - Revolutionary Change
--- ---
### Phase 8: Ongoing Development ### Phase 8: Ongoing Development
**Approach:** Brownfield + Kaizen **Approach:** Brownfield + Kaizen
**Characteristics:** **Characteristics:**
- Existing product - Existing product
- Incremental improvements - Incremental improvements
- Continuous improvement - Continuous improvement
@ -131,6 +148,7 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai
- 1-2 week cycles - 1-2 week cycles
**Concepts:** **Concepts:**
- Brownfield Development - Brownfield Development
- Kaizen (改善) - Continuous Improvement - Kaizen (改善) - Continuous Improvement
- Muda (無駄) - Waste elimination - 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?" **Question:** "Should I do small improvements or big redesign?"
**Small Improvements (Kaizen 改善):** **Small Improvements (Kaizen 改善):**
- ✅ Product is working - ✅ Product is working
- ✅ Want low-risk changes - ✅ Want low-risk changes
- ✅ 1-2 week cycles - ✅ 1-2 week cycles
- ✅ Continuous learning - ✅ Continuous learning
→ Stay in Phase 8, create System Updates → Stay in Phase 8, create System Updates
**Big Redesign (Kaikaku 改革):** **Big Redesign (Kaikaku 改革):**
- ✅ Product needs overhaul - ✅ Product needs overhaul
- ✅ Fundamental problems - ✅ Fundamental problems
- ✅ Months of work - ✅ Months of work
- ✅ Revolutionary change - ✅ Revolutionary change
→ Return to Phases 1-7, create Design Deliveries → Return to Phases 1-7, create Design Deliveries
--- ---
@ -227,18 +247,21 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai
## Key Takeaways ## Key Takeaways
**For Designers:** **For Designers:**
1. Understand if you're in Greenfield or Brownfield context 1. Understand if you're in Greenfield or Brownfield context
2. Choose Kaikaku (revolutionary) or Kaizen (continuous) approach 2. Choose Kaikaku (revolutionary) or Kaizen (continuous) approach
3. Use appropriate deliverables (DD-XXX vs SU-XXX) 3. Use appropriate deliverables (DD-XXX vs SU-XXX)
4. Follow appropriate workflow (Phases 1-7 vs Phase 8) 4. Follow appropriate workflow (Phases 1-7 vs Phase 8)
**For Documentation:** **For Documentation:**
1. Glossary is the source of truth 1. Glossary is the source of truth
2. Concepts are integrated where relevant 2. Concepts are integrated where relevant
3. Quick references in workflow steps 3. Quick references in workflow steps
4. Consistent terminology throughout 4. Consistent terminology throughout
**Philosophy:** **Philosophy:**
- Kaikaku to establish, Kaizen to improve - Kaikaku to establish, Kaizen to improve
- Greenfield gives freedom, Brownfield gives context - Greenfield gives freedom, Brownfield gives context
- Small improvements compound over time - Small improvements compound over time

34
README.md
View File

@ -79,6 +79,7 @@ docs/
``` ```
**Why alphabetical?** The `A-B-C-D-E` prefix creates a clear visual namespace that: **Why alphabetical?** The `A-B-C-D-E` prefix creates a clear visual namespace that:
- Groups WDS artifacts together in file explorers - Groups WDS artifacts together in file explorers
- Distinguishes from other project documentation - Distinguishes from other project documentation
- Provides natural sort order matching workflow progression - 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: WDS provides **8 design phases** that can be selected based on project scale:
| Phase | Name | Output Folder | Description | | Phase | Name | Output Folder | Description |
|-------|------|---------------|-------------| | ----- | --------------------------- | -------------------------- | ------------------------------------------------- |
| 1️⃣ | **Product Exploration** | `A-Product-Brief/` | Vision, positioning, ICP framework | | 1️⃣ | **Product Exploration** | `A-Product-Brief/` | Vision, positioning, ICP framework |
| 2️⃣ | **Trigger Mapping** | `B-Trigger-Map/` | Personas, business goals, Feature Impact Analysis | | 2️⃣ | **Trigger Mapping** | `B-Trigger-Map/` | Personas, business goals, Feature Impact Analysis |
| 3️⃣ | **PRD Platform** | `C-Platform-Requirements/` | Technical foundation (parallel with Phase 4) | | 3️⃣ | **PRD Platform** | `C-Platform-Requirements/` | Technical foundation (parallel with Phase 4) |
| 4️⃣ | **UX Design** | `C-Scenarios/` | User scenarios, sketches, specifications | | 4️⃣ | **UX Design** | `C-Scenarios/` | User scenarios, sketches, specifications |
| 5️⃣ | **Design System** | `D-Design-System/` | Design tokens, component library (optional) | | 5️⃣ | **Design System** | `D-Design-System/` | Design tokens, component library (optional) |
| 6️⃣ | **PRD & Design Deliveries** | `E-PRD/` | Complete PRD + packaged flows for BMM | | 6️⃣ | **PRD & Design Deliveries** | `E-PRD/` | Complete PRD + packaged flows for BMM |
| 7️⃣ | **Testing** | `F-Testing/` | Designer validation of implementation | | 7️⃣ | **Testing** | `F-Testing/` | Designer validation of implementation |
| 8️⃣ | **Product Development** | `G-Product-Development/` | Ongoing improvements (existing products) | | 8️⃣ | **Product Development** | `G-Product-Development/` | Ongoing improvements (existing products) |
### Phase-Selectable Workflow ### 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: WDS introduces **3 specialized design agents** named after Norse mythology:
| Agent | Role | Norse Meaning | | Agent | Role | Norse Meaning |
|-------|------|---------------| | --------------------------- | -------------------------- | -------------------------------------------------------------------- |
| **Saga the WDS Analyst** | Business & Product Analyst | Goddess of stories & wisdom - uncovers your business story | | **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 | | **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 | | **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: The `E-PRD/` folder serves as the **integration bridge**, containing:
- Complete PRD (00-PRD.md) with functional requirements - Complete PRD (00-PRD.md) with functional requirements
- Design Deliveries (DD-XXX.yaml) - packaged flows for BMM handoff - Design Deliveries (DD-XXX.yaml) - packaged flows for BMM handoff
- Scenario-to-epic mapping - Scenario-to-epic mapping
@ -173,6 +175,7 @@ bmad install wds
### What Gets Installed ### What Gets Installed
The WDS installer creates: The WDS installer creates:
- ✅ `docs/` directory structure with alphabetized folders (A-G) - ✅ `docs/` directory structure with alphabetized folders (A-G)
- ✅ All 8 phase folders ready for your design work - ✅ All 8 phase folders ready for your design work
- ✅ `.gitkeep` files to preserve empty directories - ✅ `.gitkeep` files to preserve empty directories
@ -251,6 +254,7 @@ git push origin main
## 📚 Original BMad Method Documentation ## 📚 Original BMad Method Documentation
For complete BMad Method documentation, see: For complete BMad Method documentation, see:
- **[BMad Method README](https://github.com/bmad-code-org/BMAD-METHOD)** - Main documentation - **[BMad Method README](https://github.com/bmad-code-org/BMAD-METHOD)** - Main documentation
- **[BMM Module Docs](./src/modules/bmm/docs/README.md)** - Development workflows - **[BMM Module Docs](./src/modules/bmm/docs/README.md)** - Development workflows
- **[Agent Customization](./docs/agent-customization-guide.md)** - Customize agents - **[Agent Customization](./docs/agent-customization-guide.md)** - Customize agents

624
WDS-V6-CONVERSION-ROADMAP.md
View File

File diff suppressed because it is too large Load Diff

3
conversion-logs/conversion-guide.md
View File

@ -13,6 +13,7 @@ This directory contains detailed logs of each conversion session, keeping the ma
## Structure ## Structure
Each session gets its own log file: Each session gets its own log file:
- `session-YYYY-MM-DD-topic.md` - Detailed work log for that session - `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 ## What Goes in Session Logs
**Each session log should document:** **Each session log should document:**
- Date and duration - Date and duration
- Objectives - Objectives
- Files created/modified - Files created/modified
@ -43,6 +45,7 @@ Each session gets its own log file:
## What Stays in Roadmap ## What Stays in Roadmap
**The main roadmap (`WDS-V6-CONVERSION-ROADMAP.md`) should contain:** **The main roadmap (`WDS-V6-CONVERSION-ROADMAP.md`) should contain:**
- Current work in progress - Current work in progress
- Next planned work - Next planned work
- Future backlog items - Future backlog items

61
conversion-logs/session-2025-12-09-micro-steps-concepts.md
View File

@ -22,6 +22,7 @@
### 1. Phase 6: Design Deliveries Micro-Steps (7 files) ### 1. Phase 6: Design Deliveries Micro-Steps (7 files)
**Created:** **Created:**
- `src/modules/wds/workflows/6-design-deliveries/workflow.md` - `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.1-detect-completion.md`
- `src/modules/wds/workflows/6-design-deliveries/steps/step-6.2-create-delivery.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` - `src/modules/wds/workflows/6-design-deliveries/steps/step-6.6-continue.md`
**Key features:** **Key features:**
- Emphasizes parallel work (design next while BMad builds current) - Emphasizes parallel work (design next while BMad builds current)
- Structured 10-phase handoff dialog with BMad Architect - Structured 10-phase handoff dialog with BMad Architect
- Clear continuation strategy to prevent designer blocking - Clear continuation strategy to prevent designer blocking
@ -41,6 +43,7 @@
### 2. Phase 7: Testing Micro-Steps (8 files) ### 2. Phase 7: Testing Micro-Steps (8 files)
**Created:** **Created:**
- `src/modules/wds/workflows/7-testing/workflow.md` - `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.1-receive-notification.md`
- `src/modules/wds/workflows/7-testing/steps/step-7.2-prepare-testing.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` - `src/modules/wds/workflows/7-testing/steps/step-7.7-iterate-or-approve.md`
**Key features:** **Key features:**
- Comprehensive test execution (happy path, errors, edge cases, design system, a11y) - Comprehensive test execution (happy path, errors, edge cases, design system, a11y)
- Structured issue creation with severity levels (Critical, High, Medium, Low) - Structured issue creation with severity levels (Critical, High, Medium, Low)
- Professional test reporting format - Professional test reporting format
@ -62,6 +66,7 @@
### 3. Phase 8: Ongoing Development Micro-Steps (9 files) ### 3. Phase 8: Ongoing Development Micro-Steps (9 files)
**Created:** **Created:**
- `src/modules/wds/workflows/8-ongoing-development/workflow.md` - `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.1-identify-opportunity.md`
- `src/modules/wds/workflows/8-ongoing-development/steps/step-8.2-gather-context.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` - `src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md`
**Key features:** **Key features:**
- Kaizen (改善) continuous improvement philosophy - Kaizen (改善) continuous improvement philosophy
- Two contexts: Existing Product Entry Point + Post-Launch Improvement - Two contexts: Existing Product Entry Point + Post-Launch Improvement
- Small, focused changes (1-2 weeks each) - Small, focused changes (1-2 weeks each)
@ -84,10 +90,12 @@
### 4. Concepts Integration ### 4. Concepts Integration
**Created:** **Created:**
- `src/core/resources/wds/glossary.md` - Complete reference for all concepts - `src/core/resources/wds/glossary.md` - Complete reference for all concepts
- `CONCEPTS-INTEGRATION.md` - Map of where concepts are used - `CONCEPTS-INTEGRATION.md` - Map of where concepts are used
**Updated:** **Updated:**
- `src/modules/wds/workflows/workflow-init/project-type-selection.md` - `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/workflow.md`
- `src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md` - `src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md`
@ -96,15 +104,18 @@
**Concepts added:** **Concepts added:**
#### Software Development Terms #### Software Development Terms
- **Greenfield Development:** Building from scratch, no constraints (Phases 1-7) - **Greenfield Development:** Building from scratch, no constraints (Phases 1-7)
- **Brownfield Development:** Working with existing systems (Phase 8) - **Brownfield Development:** Working with existing systems (Phase 8)
#### Lean Manufacturing Terms #### Lean Manufacturing Terms
- **Kaizen (改善):** Continuous improvement, small incremental changes (Phase 8) - **Kaizen (改善):** Continuous improvement, small incremental changes (Phase 8)
- **Kaikaku (改革):** Revolutionary change, major transformation (Phases 1-7) - **Kaikaku (改革):** Revolutionary change, major transformation (Phases 1-7)
- **Muda (無駄):** Waste elimination - **Muda (無駄):** Waste elimination
**Key pairings:** **Key pairings:**
``` ```
Greenfield + Kaikaku = New Product (Phases 1-7) Greenfield + Kaikaku = New Product (Phases 1-7)
Brownfield + Kaizen = Existing Product (Phase 8) 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. **Decision:** Use Design Deliveries (DD-XXX) for all design handoffs, regardless of scope.
**Rationale:** **Rationale:**
- Simpler for BMad to consume (one format) - Simpler for BMad to consume (one format)
- Consistent handoff process - Consistent handoff process
- Easier to track and manage - Easier to track and manage
- Same format, different scope - Same format, different scope
**Before (Complex):** **Before (Complex):**
- DD-XXX for complete new flows (Phases 4-7) - DD-XXX for complete new flows (Phases 4-7)
- SU-XXX for incremental improvements (Phase 8) - SU-XXX for incremental improvements (Phase 8)
- Two different formats to maintain - Two different formats to maintain
**After (Simple):** **After (Simple):**
- DD-XXX for everything - DD-XXX for everything
- `type: "complete_flow"` vs `type: "incremental_improvement"` - `type: "complete_flow"` vs `type: "incremental_improvement"`
- `scope: "new"` vs `scope: "update"` - `scope: "new"` vs `scope: "update"`
@ -138,26 +152,29 @@ Brownfield + Kaizen = Existing Product (Phase 8)
**YAML Differentiation:** **YAML Differentiation:**
Large scope (new flows): Large scope (new flows):
```yaml ```yaml
delivery: delivery:
id: "DD-001" id: 'DD-001'
name: "Login & Onboarding" name: 'Login & Onboarding'
type: "complete_flow" type: 'complete_flow'
scope: "new" scope: 'new'
``` ```
Small scope (improvements): Small scope (improvements):
```yaml ```yaml
delivery: delivery:
id: "DD-011" id: 'DD-011'
name: "Feature X Onboarding Improvement" name: 'Feature X Onboarding Improvement'
type: "incremental_improvement" type: 'incremental_improvement'
scope: "update" scope: 'update'
version: "v2.0" version: 'v2.0'
previous_version: "v1.0" previous_version: 'v1.0'
``` ```
**Files updated:** **Files updated:**
- ✅ `src/core/resources/wds/glossary.md` - ✅ `src/core/resources/wds/glossary.md`
- ✅ `src/modules/wds/workflows/8-ongoing-development/workflow.md` - ✅ `src/modules/wds/workflows/8-ongoing-development/workflow.md`
- ✅ `src/modules/wds/workflows/8-ongoing-development/steps/step-8.4-create-delivery.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) **Clarified:** Test Scenarios (TS-XXX) are directly tied to Design Deliveries (DD-XXX)
**One-to-one relationship:** **One-to-one relationship:**
- DD-001 → TS-001 - DD-001 → TS-001
- DD-002 → TS-002 - DD-002 → TS-002
- DD-015 (improvement) → TS-015 - DD-015 (improvement) → TS-015
**Created together:** **Created together:**
- Phase 6, Step 6.2: Create Design Delivery (DD-XXX) - Phase 6, Step 6.2: Create Design Delivery (DD-XXX)
- Phase 6, Step 6.3: Create Test Scenario (TS-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 ## Statistics
**Files created:** 26 **Files created:** 26
- Phase 6: 7 files - Phase 6: 7 files
- Phase 7: 8 files - Phase 7: 8 files
- Phase 8: 9 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 - Integration map: 1 file
**Lines written:** ~27,000 **Lines written:** ~27,000
- Phase 6: ~7,000 lines - Phase 6: ~7,000 lines
- Phase 7: ~10,000 lines - Phase 7: ~10,000 lines
- Phase 8: ~10,000 lines - Phase 8: ~10,000 lines
**Files updated:** 5 **Files updated:** 5
- Project type selection - Project type selection
- Phase 8 workflow - Phase 8 workflow
- Existing product guide - Existing product guide
@ -215,18 +237,23 @@ The Test Scenario validates that the business and user goals defined in the Desi
## Key Decisions ## Key Decisions
### 1. Micro-File Architecture ### 1. Micro-File Architecture
Adopted BMad's pattern of breaking workflows into sequential, self-contained step files for disciplined execution. Adopted BMad's pattern of breaking workflows into sequential, self-contained step files for disciplined execution.
### 2. Kaizen Philosophy ### 2. Kaizen Philosophy
Phase 8 embodies Kaizen (改善) - continuous improvement through small, incremental changes that compound over time. Phase 8 embodies Kaizen (改善) - continuous improvement through small, incremental changes that compound over time.
### 3. DD-XXX Simplification ### 3. DD-XXX Simplification
Eliminated SU-XXX format. All deliveries use DD-XXX with `type` and `scope` fields to differentiate. Eliminated SU-XXX format. All deliveries use DD-XXX with `type` and `scope` fields to differentiate.
### 4. Terminology Integration ### 4. Terminology Integration
Integrated industry-standard terms (Greenfield/Brownfield, Kaizen/Kaikaku) to connect WDS to established methodologies. Integrated industry-standard terms (Greenfield/Brownfield, Kaizen/Kaikaku) to connect WDS to established methodologies.
### 5. TS-XXX Relationship ### 5. TS-XXX Relationship
Clarified that Test Scenarios are created alongside Design Deliveries and validate the same business/user goals. 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 ## Challenges & Solutions
### Challenge 1: Phase 6 Initially Single File ### Challenge 1: Phase 6 Initially Single File
**Problem:** First attempt only refactored content within existing file instead of creating separate micro-step files. **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. **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 ### Challenge 2: Two Delivery Formats
**Problem:** Having both DD-XXX and SU-XXX created confusion and maintenance burden. **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. **Solution:** User suggested simplification. Unified to DD-XXX for everything with `type` and `scope` fields to differentiate.
### Challenge 3: Documentation Sprawl ### Challenge 3: Documentation Sprawl
**Problem:** Started creating separate documents for planning and tracking. **Problem:** Started creating separate documents for planning and tracking.
**Solution:** User requested consolidation. Added all planning to existing roadmap instead of creating new documents. **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 ## Examples Created
### Phase 6 Example: Dog Week Onboarding ### Phase 6 Example: Dog Week Onboarding
- Complete flow from welcome to dashboard - Complete flow from welcome to dashboard
- 4 scenarios specified - 4 scenarios specified
- Design system components defined - Design system components defined
@ -260,6 +291,7 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida
- Test scenario for validation - Test scenario for validation
### Phase 7 Example: Feature X Validation ### Phase 7 Example: Feature X Validation
- Happy path tests (5 tests) - Happy path tests (5 tests)
- Error state tests (4 tests) - Error state tests (4 tests)
- Edge case tests (3 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 - 8 issues found, documented, fixed, retested
### Phase 8 Example: Feature X Onboarding Improvement ### Phase 8 Example: Feature X Onboarding Improvement
- Problem: 15% usage, 40% drop-off - Problem: 15% usage, 40% drop-off
- Solution: Add inline onboarding - Solution: Add inline onboarding
- Impact: 15% → 58% usage (4x increase) - Impact: 15% → 58% usage (4x increase)
@ -279,16 +312,19 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida
## Next Steps ## Next Steps
### Immediate (This Week) ### Immediate (This Week)
1. Complete SU-XXX → DD-XXX migration in Phase 8 step files 1. Complete SU-XXX → DD-XXX migration in Phase 8 step files
2. Test Phase 6/7/8 workflows with real project 2. Test Phase 6/7/8 workflows with real project
3. Create commit for today's work 3. Create commit for today's work
### Short-term (Next Week) ### Short-term (Next Week)
1. Complete remaining module tutorials (03, 05-07, 09-11, 13-16) 1. Complete remaining module tutorials (03, 05-07, 09-11, 13-16)
2. Create WDS Excalidraw component library 2. Create WDS Excalidraw component library
3. Test complete WDS → BMad workflow 3. Test complete WDS → BMad workflow
### Long-term (This Month) ### Long-term (This Month)
1. Implement auto-export automation (GitHub Actions) 1. Implement auto-export automation (GitHub Actions)
2. Refine assessment criteria based on usage 2. Refine assessment criteria based on usage
3. Test Figma MCP integration with real components 3. Test Figma MCP integration with real components
@ -298,18 +334,23 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida
## Learnings ## Learnings
### 1. Micro-Steps Enable Discipline ### 1. Micro-Steps Enable Discipline
Breaking complex workflows into small, sequential steps makes execution more disciplined and reduces cognitive load. Breaking complex workflows into small, sequential steps makes execution more disciplined and reduces cognitive load.
### 2. Philosophy Matters ### 2. Philosophy Matters
Connecting WDS to established methodologies (Lean, Kaizen) gives designers a mental model and vocabulary for the work. Connecting WDS to established methodologies (Lean, Kaizen) gives designers a mental model and vocabulary for the work.
### 3. Simplification is Powerful ### 3. Simplification is Powerful
Reducing from two delivery formats to one eliminates confusion and maintenance burden while maintaining necessary differentiation. Reducing from two delivery formats to one eliminates confusion and maintenance burden while maintaining necessary differentiation.
### 4. Parallel Work is Key ### 4. Parallel Work is Key
Phase 6 emphasizes parallel work (design next while BMad builds current) to prevent designer blocking and maximize throughput. Phase 6 emphasizes parallel work (design next while BMad builds current) to prevent designer blocking and maximize throughput.
### 5. Measurement Drives Improvement ### 5. Measurement Drives Improvement
Phase 8's focus on measuring impact after each cycle enables data-driven continuous improvement. Phase 8's focus on measuring impact after each cycle enables data-driven continuous improvement.
--- ---

4
package-lock.json generated
View File

@ -1,12 +1,12 @@
{ {
"name": "bmad-method", "name": "bmad-method",
"version": "6.0.0-alpha.12", "version": "6.0.0-alpha.13",
"lockfileVersion": 3, "lockfileVersion": 3,
"requires": true, "requires": true,
"packages": { "packages": {
"": { "": {
"name": "bmad-method", "name": "bmad-method",
"version": "6.0.0-alpha.12", "version": "6.0.0-alpha.13",
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@kayvan/markdown-tree-parser": "^1.6.1", "@kayvan/markdown-tree-parser": "^1.6.1",

136
src/core/resources/wds/design-delivery-spec.md
View File

@ -7,6 +7,7 @@
## What is a Design Delivery? ## What is a Design Delivery?
A Design Delivery (DD) is a package created by WDS that contains: A Design Delivery (DD) is a package created by WDS that contains:
- Complete user flow specifications - Complete user flow specifications
- Technical requirements - Technical requirements
- Design system references - Design system references
@ -26,15 +27,15 @@ A Design Delivery (DD) is a package created by WDS that contains:
```yaml ```yaml
delivery: delivery:
id: "DD-001" # Unique identifier (DD-XXX) id: 'DD-001' # Unique identifier (DD-XXX)
name: "Login & Onboarding" # Human-readable name name: 'Login & Onboarding' # Human-readable name
type: "user_flow" # user_flow | feature | component type: 'user_flow' # user_flow | feature | component
status: "ready" # ready | in_progress | blocked status: 'ready' # ready | in_progress | blocked
priority: "high" # high | medium | low priority: 'high' # high | medium | low
created_by: "wds-ux-expert" # Creator agent created_by: 'wds-ux-expert' # Creator agent
created_at: "2024-12-09T10:00:00Z" created_at: '2024-12-09T10:00:00Z'
updated_at: "2024-12-09T10:00:00Z" updated_at: '2024-12-09T10:00:00Z'
version: "1.0" version: '1.0'
description: | description: |
Complete user authentication and onboarding flow. Complete user authentication and onboarding flow.
@ -42,89 +43,89 @@ description: |
Testable as standalone feature with real users. Testable as standalone feature with real users.
user_value: user_value:
problem: "Users need to access the app securely and set up their family" problem: 'Users need to access the app securely and set up their family'
solution: "Streamlined onboarding with family setup" solution: 'Streamlined onboarding with family setup'
success_criteria: success_criteria:
- "User completes signup in under 2 minutes" - 'User completes signup in under 2 minutes'
- "User successfully joins or creates family" - 'User successfully joins or creates family'
- "User reaches functional dashboard" - 'User reaches functional dashboard'
- "90% completion rate for onboarding flow" - '90% completion rate for onboarding flow'
design_artifacts: design_artifacts:
scenarios: scenarios:
- id: "01-welcome" - id: '01-welcome'
path: "C-Scenarios/01-welcome-screen/" path: 'C-Scenarios/01-welcome-screen/'
screens: ["welcome"] screens: ['welcome']
- id: "02-login" - id: '02-login'
path: "C-Scenarios/02-login/" path: 'C-Scenarios/02-login/'
screens: ["login", "forgot-password"] screens: ['login', 'forgot-password']
user_flows: user_flows:
- name: "New User Onboarding" - name: 'New User Onboarding'
path: "C-Scenarios/flows/new-user-onboarding.excalidraw" path: 'C-Scenarios/flows/new-user-onboarding.excalidraw'
entry: "welcome" entry: 'welcome'
exit: "dashboard" exit: 'dashboard'
design_system: design_system:
components: components:
- "Button (Primary, Secondary)" - 'Button (Primary, Secondary)'
- "Input Field (Email, Password)" - 'Input Field (Email, Password)'
- "Card (Welcome, Family)" - 'Card (Welcome, Family)'
path: "D-Design-System/" path: 'D-Design-System/'
technical_requirements: technical_requirements:
platform: platform:
frontend: "react_native" frontend: 'react_native'
backend: "supabase" backend: 'supabase'
integrations: integrations:
- name: "supabase_auth" - name: 'supabase_auth'
purpose: "User authentication" purpose: 'User authentication'
required: true required: true
- name: "email_verification" - name: 'email_verification'
purpose: "Verify user email" purpose: 'Verify user email'
required: true required: true
data_models: data_models:
- name: "User" - name: 'User'
fields: ["email", "name", "avatar"] fields: ['email', 'name', 'avatar']
- name: "Family" - name: 'Family'
fields: ["name", "invite_code", "members"] fields: ['name', 'invite_code', 'members']
acceptance_criteria: acceptance_criteria:
functional: functional:
- "User can create account with email/password" - 'User can create account with email/password'
- "User receives verification email" - 'User receives verification email'
- "User can create new family or join existing" - 'User can create new family or join existing'
non_functional: non_functional:
- "Onboarding completes in < 2 minutes" - 'Onboarding completes in < 2 minutes'
- "Works offline (cached welcome screen)" - 'Works offline (cached welcome screen)'
- "Accessible (WCAG 2.1 AA)" - 'Accessible (WCAG 2.1 AA)'
edge_cases: edge_cases:
- "Email already exists → Show login option" - 'Email already exists → Show login option'
- "Invalid invite code → Show error, allow retry" - 'Invalid invite code → Show error, allow retry'
- "Network error during signup → Save progress, retry" - 'Network error during signup → Save progress, retry'
testing_guidance: testing_guidance:
user_testing: user_testing:
- "Test with 5 families (different tech comfort levels)" - 'Test with 5 families (different tech comfort levels)'
- "Measure completion time and drop-off points" - 'Measure completion time and drop-off points'
qa_testing: qa_testing:
- "Test all error states" - 'Test all error states'
- "Test offline scenarios" - 'Test offline scenarios'
- "Test accessibility with screen reader" - 'Test accessibility with screen reader'
estimated_complexity: estimated_complexity:
size: "medium" # small | medium | large size: 'medium' # small | medium | large
effort: "2-3 weeks" # Time estimate effort: '2-3 weeks' # Time estimate
risk: "low" # low | medium | high risk: 'low' # low | medium | high
dependencies: [] # Other DD-XXX IDs needed first dependencies: [] # Other DD-XXX IDs needed first
notes: | notes: |
This is the first user-facing feature and sets the tone This is the first user-facing feature and sets the tone
@ -332,6 +333,7 @@ Source: DD-001 scenario 04
### 1. Respect Designer Decisions ### 1. Respect Designer Decisions
**The designer has already made these choices:** **The designer has already made these choices:**
- Tech stack (platform.frontend, platform.backend) - Tech stack (platform.frontend, platform.backend)
- Integrations (technical_requirements.integrations) - Integrations (technical_requirements.integrations)
- Component usage (design_system.components) - Component usage (design_system.components)
@ -339,6 +341,7 @@ Source: DD-001 scenario 04
**Your job:** Implement these choices faithfully **Your job:** Implement these choices faithfully
**Exception:** If you see a technical problem, flag it: **Exception:** If you see a technical problem, flag it:
``` ```
"⚠️ Technical Concern: DD-001 specifies Supabase Auth, "⚠️ Technical Concern: DD-001 specifies Supabase Auth,
but project already uses Firebase. Recommend discussing but project already uses Firebase. Recommend discussing
@ -348,6 +351,7 @@ with designer before proceeding."
### 2. Maintain Traceability ### 2. Maintain Traceability
**Always link back to source:** **Always link back to source:**
```markdown ```markdown
Epic 1.2: Login Screen Epic 1.2: Login Screen
**Source:** DD-001 (Login & Onboarding) **Source:** DD-001 (Login & Onboarding)
@ -359,11 +363,12 @@ Epic 1.2: Login Screen
### 3. Use Acceptance Criteria ### 3. Use Acceptance Criteria
**Designer provided acceptance criteria - these are your requirements:** **Designer provided acceptance criteria - these are your requirements:**
```yaml ```yaml
acceptance_criteria: acceptance_criteria:
functional: functional:
- "User can create account with email/password" - 'User can create account with email/password'
- "User receives verification email" - 'User receives verification email'
``` ```
**Your epics must cover ALL acceptance criteria** **Your epics must cover ALL acceptance criteria**
@ -371,13 +376,14 @@ acceptance_criteria:
### 4. Follow Testing Guidance ### 4. Follow Testing Guidance
**Designer provided testing guidance:** **Designer provided testing guidance:**
```yaml ```yaml
testing_guidance: testing_guidance:
user_testing: user_testing:
- "Test with 5 families (different tech comfort levels)" - 'Test with 5 families (different tech comfort levels)'
qa_testing: qa_testing:
- "Test all error states" - 'Test all error states'
- "Test offline scenarios" - 'Test offline scenarios'
``` ```
**Your test plans should follow this guidance** **Your test plans should follow this guidance**
@ -415,7 +421,7 @@ elif status == 'blocked':
```yaml ```yaml
estimated_complexity: 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 **This means:** DD-001 requires DD-002 and DD-005 to be implemented first
@ -440,8 +446,8 @@ else:
```yaml ```yaml
delivery: delivery:
version: "1.1" version: '1.1'
updated_at: "2024-12-15T14:00:00Z" updated_at: '2024-12-15T14:00:00Z'
notes: | notes: |
Version 1.1 changes: Version 1.1 changes:

66
src/core/resources/wds/glossary.md
View File

@ -13,6 +13,7 @@
**Origin:** Agricultural term - plowing a green field that has never been cultivated before. **Origin:** Agricultural term - plowing a green field that has never been cultivated before.
**In software:** **In software:**
- No legacy code to maintain - No legacy code to maintain
- Full creative freedom - Full creative freedom
- Define architecture from scratch - Define architecture from scratch
@ -21,6 +22,7 @@
- Start with blank canvas - Start with blank canvas
**In WDS:** **In WDS:**
- **Phases 1-7:** New Product Development - **Phases 1-7:** New Product Development
- Complete user flows designed from scratch - Complete user flows designed from scratch
- Full Project Brief - Full Project Brief
@ -39,6 +41,7 @@
**Origin:** Industrial term - redeveloping land previously used for industrial purposes (often contaminated, requiring cleanup). **Origin:** Industrial term - redeveloping land previously used for industrial purposes (often contaminated, requiring cleanup).
**In software:** **In software:**
- Existing codebase to work with - Existing codebase to work with
- Legacy systems to integrate - Legacy systems to integrate
- Established patterns to follow - Established patterns to follow
@ -47,6 +50,7 @@
- Cleanup and improvement - Cleanup and improvement
**In WDS:** **In WDS:**
- **Phase 8:** Existing Product Development - **Phase 8:** Existing Product Development
- Targeted improvements to existing product - Targeted improvements to existing product
- Limited Project Brief (strategic challenge) - Limited Project Brief (strategic challenge)
@ -63,6 +67,7 @@
### Kaizen (改善) - Continuous Improvement ### Kaizen (改善) - Continuous Improvement
**Japanese:** 改善 **Japanese:** 改善
- 改 (kai) = Change - 改 (kai) = Change
- 善 (zen) = Good - 善 (zen) = Good
@ -71,6 +76,7 @@
**Origin:** Japanese manufacturing philosophy, popularized by Toyota Production System. **Origin:** Japanese manufacturing philosophy, popularized by Toyota Production System.
**Characteristics:** **Characteristics:**
- **Small changes:** 1-2 weeks each - **Small changes:** 1-2 weeks each
- **Low cost, low risk:** Minimal investment - **Low cost, low risk:** Minimal investment
- **Everyone participates:** Bottom-up approach - **Everyone participates:** Bottom-up approach
@ -80,6 +86,7 @@
- **Data-driven:** Measure everything - **Data-driven:** Measure everything
**In product design:** **In product design:**
- Ship → Monitor → Learn → Improve → Ship → Repeat - Ship → Monitor → Learn → Improve → Ship → Repeat
- Small updates beat big redesigns - Small updates beat big redesigns
- User feedback drives improvements - User feedback drives improvements
@ -88,6 +95,7 @@
- Team learns continuously - Team learns continuously
**In WDS:** **In WDS:**
- **Phase 8:** Ongoing Development - **Phase 8:** Ongoing Development
- System Updates (SU-XXX) instead of Design Deliveries - System Updates (SU-XXX) instead of Design Deliveries
- 1-2 week improvement cycles - 1-2 week improvement cycles
@ -95,6 +103,7 @@
- Iterate based on learnings - Iterate based on learnings
**Examples:** **Examples:**
- Add onboarding tooltip to improve feature usage (15% → 60%) - Add onboarding tooltip to improve feature usage (15% → 60%)
- Optimize button color for better conversion (+5%) - Optimize button color for better conversion (+5%)
- Improve error message clarity (-80% support tickets) - Improve error message clarity (-80% support tickets)
@ -108,6 +117,7 @@
### Kaikaku (改革) - Revolutionary Change ### Kaikaku (改革) - Revolutionary Change
**Japanese:** 改革 **Japanese:** 改革
- 改 (kai) = Change - 改 (kai) = Change
- 革 (kaku) = Reform/Revolution - 革 (kaku) = Reform/Revolution
@ -116,6 +126,7 @@
**Origin:** Japanese manufacturing philosophy, used for major system overhauls. **Origin:** Japanese manufacturing philosophy, used for major system overhauls.
**Characteristics:** **Characteristics:**
- **Large changes:** Months of work - **Large changes:** Months of work
- **High cost, high risk:** Major investment - **High cost, high risk:** Major investment
- **Leadership-driven:** Top-down approach - **Leadership-driven:** Top-down approach
@ -125,6 +136,7 @@
- **Disruptive:** Major changes to system - **Disruptive:** Major changes to system
**In product design:** **In product design:**
- Complete redesign - Complete redesign
- Platform migration (web → mobile) - Platform migration (web → mobile)
- Architecture overhaul - Architecture overhaul
@ -133,6 +145,7 @@
- Technology stack change - Technology stack change
**In WDS:** **In WDS:**
- **Phases 1-7:** New Product Development (greenfield) - **Phases 1-7:** New Product Development (greenfield)
- Complete user flows designed - Complete user flows designed
- Full Design Deliveries (DD-XXX) - Full Design Deliveries (DD-XXX)
@ -140,6 +153,7 @@
- Revolutionary change - Revolutionary change
**Examples:** **Examples:**
- Complete product redesign (v1.0 → v2.0) - Complete product redesign (v1.0 → v2.0)
- Migrate from web to mobile-first - Migrate from web to mobile-first
- Rebrand entire product - Rebrand entire product
@ -154,6 +168,7 @@
### Kaizen vs Kaikaku: When to Use Each ### Kaizen vs Kaikaku: When to Use Each
**Use Kaizen (改善) when:** **Use Kaizen (改善) when:**
- ✅ Product is live and working - ✅ Product is live and working
- ✅ Need continuous improvement - ✅ Need continuous improvement
- ✅ Want low-risk changes - ✅ Want low-risk changes
@ -162,6 +177,7 @@
- ✅ **WDS Phase 8: Ongoing Development** - ✅ **WDS Phase 8: Ongoing Development**
**Use Kaikaku (改革) when:** **Use Kaikaku (改革) when:**
- ✅ Starting from scratch (greenfield) - ✅ Starting from scratch (greenfield)
- ✅ Product needs complete overhaul - ✅ Product needs complete overhaul
- ✅ Market demands radical change - ✅ Market demands radical change
@ -206,6 +222,7 @@ Kaizen: Continuous improvement again
7. **Defects:** Bugs, rework, and quality issues 7. **Defects:** Bugs, rework, and quality issues
**Kaizen eliminates Muda through:** **Kaizen eliminates Muda through:**
- Small, focused improvements - Small, focused improvements
- Fast cycles (ship → learn → improve) - Fast cycles (ship → learn → improve)
- Continuous measurement - Continuous measurement
@ -213,6 +230,7 @@ Kaizen: Continuous improvement again
- Eliminating handoff friction - Eliminating handoff friction
**In WDS:** **In WDS:**
- Design specifications eliminate handoff waste - Design specifications eliminate handoff waste
- Iterative deliveries eliminate inventory waste - Iterative deliveries eliminate inventory waste
- Fast cycles eliminate waiting 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. **Definition:** A structured YAML package for handing off design work to BMad.
**Used for BOTH:** **Used for BOTH:**
- ✅ Complete new user flows (Greenfield/Kaikaku) - ✅ Complete new user flows (Greenfield/Kaikaku)
- ✅ Incremental improvements (Brownfield/Kaizen) - ✅ Incremental improvements (Brownfield/Kaizen)
**The format is the same - only the scope differs!** **The format is the same - only the scope differs!**
**Contains:** **Contains:**
- User value and business value - User value and business value
- Design artifacts (scenarios, components) - Design artifacts (scenarios, components)
- Technical requirements - Technical requirements
@ -245,28 +265,32 @@ Kaizen: Continuous improvement again
**Scope variations:** **Scope variations:**
**Large scope (New flows):** **Large scope (New flows):**
```yaml ```yaml
delivery: delivery:
id: "DD-001" id: 'DD-001'
name: "Login & Onboarding" name: 'Login & Onboarding'
type: "complete_flow" type: 'complete_flow'
scope: "new" scope: 'new'
``` ```
**Small scope (Improvements):** **Small scope (Improvements):**
```yaml ```yaml
delivery: delivery:
id: "DD-015" id: 'DD-015'
name: "Feature X Onboarding Improvement" name: 'Feature X Onboarding Improvement'
type: "incremental_improvement" type: 'incremental_improvement'
scope: "update" scope: 'update'
``` ```
**Examples:** **Examples:**
- `DD-001-login-onboarding.yaml` (complete new flow) - `DD-001-login-onboarding.yaml` (complete new flow)
- `DD-015-feature-x-onboarding.yaml` (incremental improvement) - `DD-015-feature-x-onboarding.yaml` (incremental improvement)
**Why one format?** **Why one format?**
- Simpler for BMad to consume - Simpler for BMad to consume
- Consistent handoff process - Consistent handoff process
- Same validation workflow - Same validation workflow
@ -279,12 +303,14 @@ delivery:
**Definition:** YAML file defining the technical stack and constraints. **Definition:** YAML file defining the technical stack and constraints.
**Contains:** **Contains:**
- Tech stack choices - Tech stack choices
- Integrations - Integrations
- Constraints - Constraints
- Rationale - Rationale
**Used in:** **Used in:**
- Phase 3 (New Product) - Phase 3 (New Product)
- Greenfield projects - Greenfield projects
- Touch Point 1: WDS → BMad - Touch Point 1: WDS → BMad
@ -299,12 +325,14 @@ delivery:
**Definition:** Structured YAML defining validation steps for designers to verify a Design Delivery. **Definition:** Structured YAML defining validation steps for designers to verify a Design Delivery.
**Relationship to Design Delivery:** **Relationship to Design Delivery:**
- **One-to-one:** Each DD-XXX has a corresponding TS-XXX - **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) - **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 - **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. - **Same numbering:** TS-001 validates DD-001, TS-002 validates DD-002, etc.
**Contains:** **Contains:**
- Happy path tests (verify user goals achieved) - Happy path tests (verify user goals achieved)
- Error state tests (verify error handling) - Error state tests (verify error handling)
- Edge case tests (verify robustness) - Edge case tests (verify robustness)
@ -313,12 +341,14 @@ delivery:
- Sign-off criteria (based on DD-XXX acceptance criteria) - Sign-off criteria (based on DD-XXX acceptance criteria)
**Used in:** **Used in:**
- Phase 6 (Design Deliveries) - Created alongside DD-XXX - Phase 6 (Design Deliveries) - Created alongside DD-XXX
- Phase 7 (Testing) - Executed to validate implementation - Phase 7 (Testing) - Executed to validate implementation
- Designer validation - Designer validation
- Touch Point 3: BMad → WDS - Touch Point 3: BMad → WDS
**Example:** **Example:**
``` ```
DD-001-login-onboarding.yaml → TS-001-login-onboarding.yaml DD-001-login-onboarding.yaml → TS-001-login-onboarding.yaml
DD-015-feature-x-improvement.yaml → TS-015-feature-x-improvement.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) **Origin:** Seth Godin's book "Linchpin: Are You Indispensable?" (2010)
**Characteristics:** **Characteristics:**
- Walks into chaos and creates order - Walks into chaos and creates order
- Navigates 5 dimensions of thinking simultaneously - Navigates 5 dimensions of thinking simultaneously
- Provides emotional labor (genuinely cares about outcome) - 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. **Opposite:** Factory worker who follows instructions and can be replaced.
**In WDS:** **In WDS:**
- Designer as gatekeeper between business and user needs - Designer as gatekeeper between business and user needs
- Catches AI's confident but ridiculous mistakes - Catches AI's confident but ridiculous mistakes
- Ensures design intent is preserved - 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 5. **Technical Viability (FEASIBLE)** - Bridging design and implementation
**Why it matters:** **Why it matters:**
- Most people can handle 1-2 dimensions - Most people can handle 1-2 dimensions
- Irreplaceable designers navigate all 5 simultaneously - Irreplaceable designers navigate all 5 simultaneously
- Each dimension informs the others - Each dimension informs the others
- Miss one, and your design falls apart - Miss one, and your design falls apart
**In WDS:** **In WDS:**
- Project Brief covers all 5 dimensions - Project Brief covers all 5 dimensions
- Trigger Map connects dimensions - Trigger Map connects dimensions
- Design Deliveries preserve all 5 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 ## Comparison Table
| Concept | Type | WDS Phase | Approach | Timeline | Deliverable | | Concept | Type | WDS Phase | Approach | Timeline | Deliverable |
|---------|------|-----------|----------|----------|-------------| | ------------------ | ------------ | ---------- | ---------------- | --------- | -------------------- |
| **Greenfield** | Software Dev | Phases 1-7 | New product | Months | DD-XXX | | **Greenfield** | Software Dev | Phases 1-7 | New product | Months | DD-XXX |
| **Brownfield** | Software Dev | Phase 8 | Existing product | Weeks | DD-XXX | | **Brownfield** | Software Dev | Phase 8 | Existing product | Weeks | DD-XXX |
| **Kaikaku (改革)** | Lean | Phases 1-7 | Revolutionary | Months | DD-XXX (large scope) | | **Kaikaku (改革)** | Lean | Phases 1-7 | Revolutionary | Months | DD-XXX (large scope) |
| **Kaizen (改善)** | Lean | Phase 8 | Continuous | 1-2 weeks | DD-XXX (small 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. **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 ## Usage Examples
### Greenfield + Kaikaku ### 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." "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 ### 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." "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 ### 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." "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 ### 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." "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."
--- ---

48
src/core/resources/wds/handoff-protocol.md
View File

@ -7,6 +7,7 @@
## Overview ## Overview
The handoff is a structured conversation between: The handoff is a structured conversation between:
- **WDS UX Expert** (Design authority) - **WDS UX Expert** (Design authority)
- **BMad Architect** (Technical authority) - **BMad Architect** (Technical authority)
@ -23,6 +24,7 @@ The handoff is a structured conversation between:
### Phase 1: Introduction (1 min) ### Phase 1: Introduction (1 min)
**WDS UX Expert initiates:** **WDS UX Expert initiates:**
``` ```
"Hey Architect! I've completed the design for [Delivery Name]. "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:** **BMad Architect acknowledges:**
``` ```
"Great! I'm ready to receive the handoff. What have you got for me?" "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:** **BMad Architect asks:**
``` ```
"Got it. What's the user value here?" "Got it. What's the user value here?"
``` ```
**WDS UX Expert responds:** **WDS UX Expert responds:**
``` ```
"The problem: [User problem being solved] "The problem: [User problem being solved]
@ -68,6 +73,7 @@ Success criteria:
``` ```
**BMad Architect confirms:** **BMad Architect confirms:**
``` ```
"Perfect. I understand the user value. What scenarios did you design?" "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:** **BMad Architect may ask:**
``` ```
"Can you elaborate on [specific scenario]?" "Can you elaborate on [specific scenario]?"
"How does [screen A] connect to [screen B]?" "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) ### Phase 4: Technical Requirements (3 min)
**BMad Architect asks:** **BMad Architect asks:**
``` ```
"What about the technical stack? Any preferences?" "What about the technical stack? Any preferences?"
``` ```
**WDS UX Expert shares:** **WDS UX Expert shares:**
``` ```
"Yes! I've already defined the platform requirements: "Yes! I've already defined the platform requirements:
@ -131,11 +140,13 @@ The designer chose these because [reasoning]."
``` ```
**BMad Architect asks:** **BMad Architect asks:**
``` ```
"Makes sense. What integrations do you need?" "Makes sense. What integrations do you need?"
``` ```
**WDS UX Expert lists:** **WDS UX Expert lists:**
``` ```
"[N] key integrations: "[N] key integrations:
@ -152,11 +163,13 @@ The designer chose these because [reasoning]."
``` ```
**BMad Architect asks:** **BMad Architect asks:**
``` ```
"Got it. What data models do I need to implement?" "Got it. What data models do I need to implement?"
``` ```
**WDS UX Expert defines:** **WDS UX Expert defines:**
``` ```
"[N] main models: "[N] main models:
@ -174,6 +187,7 @@ know if you see any technical issues with these structures."
``` ```
**BMad Architect validates:** **BMad Architect validates:**
``` ```
"These look good. [Or: I see a potential issue with...]" "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) ### Phase 5: Design System (2 min)
**BMad Architect asks:** **BMad Architect asks:**
``` ```
"What about the design system? What components should I use?" "What about the design system? What components should I use?"
``` ```
**WDS UX Expert lists:** **WDS UX Expert lists:**
``` ```
"I've used components from our design system: "I've used components from our design system:
@ -205,6 +221,7 @@ tested, and match our brand."
``` ```
**BMad Architect confirms:** **BMad Architect confirms:**
``` ```
"Perfect. I'll reference those. What are the acceptance criteria?" "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) ### Phase 6: Acceptance Criteria (2 min)
**WDS UX Expert shares:** **WDS UX Expert shares:**
``` ```
"Functional requirements: "Functional requirements:
✓ [Requirement 1] ✓ [Requirement 1]
@ -235,6 +253,7 @@ highlight the critical ones."
``` ```
**BMad Architect acknowledges:** **BMad Architect acknowledges:**
``` ```
"Great detail! How should I test this?" "Great detail! How should I test this?"
``` ```
@ -244,6 +263,7 @@ highlight the critical ones."
### Phase 7: Testing (2 min) ### Phase 7: Testing (2 min)
**WDS UX Expert explains:** **WDS UX Expert explains:**
``` ```
"I've created a test scenario: test-scenarios/[TS-XXX].yaml "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:** **BMad Architect confirms:**
``` ```
"Perfect. What's your estimate for complexity?" "Perfect. What's your estimate for complexity?"
``` ```
@ -272,6 +293,7 @@ screenshots and references back to the specifications."
### Phase 8: Estimates & Planning (3 min) ### Phase 8: Estimates & Planning (3 min)
**WDS UX Expert shares:** **WDS UX Expert shares:**
``` ```
"Size: [small|medium|large] "Size: [small|medium|large]
Effort: [time estimate] Effort: [time estimate]
@ -282,6 +304,7 @@ Dependencies: [None or list of DD-XXX]
``` ```
**BMad Architect proposes:** **BMad Architect proposes:**
``` ```
"Excellent handoff! Let me break this down into development epics: "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:** **WDS UX Expert may suggest:**
``` ```
"That breakdown makes sense. [Or: One suggestion...] "That breakdown makes sense. [Or: One suggestion...]
@ -310,6 +334,7 @@ Total: [X weeks], matches your estimate.
``` ```
**BMad Architect adjusts if needed:** **BMad Architect adjusts if needed:**
``` ```
"Good idea! [Revised plan if applicable] "Good idea! [Revised plan if applicable]
@ -322,6 +347,7 @@ implementation details."
### Phase 9: Special Considerations (2 min) ### Phase 9: Special Considerations (2 min)
**WDS UX Expert shares important notes:** **WDS UX Expert shares important notes:**
``` ```
"Yes! A few important notes: "Yes! A few important notes:
@ -341,6 +367,7 @@ implementation details."
``` ```
**BMad Architect acknowledges:** **BMad Architect acknowledges:**
``` ```
"All noted! I'll make sure to: "All noted! I'll make sure to:
- [Commitment 1] - [Commitment 1]
@ -355,6 +382,7 @@ implementation details."
### Phase 10: Confirmation (1 min) ### Phase 10: Confirmation (1 min)
**BMad Architect summarizes:** **BMad Architect summarizes:**
``` ```
"Excellent handoff! Let me summarize what I'm taking: "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:** **WDS UX Expert confirms or corrects:**
``` ```
"[If correct:] Perfect! That's exactly right. "[If correct:] Perfect! That's exactly right.
@ -391,6 +420,7 @@ Looking forward to seeing this come to life. Remember:
``` ```
**BMad Architect commits:** **BMad Architect commits:**
``` ```
"Got it! I'll make sure the implementation honors your "Got it! I'll make sure the implementation honors your
design vision. Talk soon!" design vision. Talk soon!"
@ -403,6 +433,7 @@ design vision. Talk soon!"
### For WDS UX Expert ### For WDS UX Expert
**Your role:** **Your role:**
- Be the design authority - Be the design authority
- Explain the "why" behind decisions - Explain the "why" behind decisions
- Share context and considerations - Share context and considerations
@ -410,6 +441,7 @@ design vision. Talk soon!"
- Trust the architect to implement well - Trust the architect to implement well
**Tone:** **Tone:**
- Collaborative, not dictatorial - Collaborative, not dictatorial
- Helpful, not defensive - Helpful, not defensive
- Clear, not vague - Clear, not vague
@ -417,6 +449,7 @@ design vision. Talk soon!"
- Encouraging, not demanding - Encouraging, not demanding
**Key phrases:** **Key phrases:**
- "Here's what I've designed..." - "Here's what I've designed..."
- "The user value is..." - "The user value is..."
- "I've focused on..." - "I've focused on..."
@ -425,6 +458,7 @@ design vision. Talk soon!"
- "I trust you to implement this well" - "I trust you to implement this well"
**What to emphasize:** **What to emphasize:**
- User value and success criteria - User value and success criteria
- Critical user experience details - Critical user experience details
- Design system compliance - Design system compliance
@ -432,6 +466,7 @@ design vision. Talk soon!"
- Special considerations - Special considerations
**What to avoid:** **What to avoid:**
- Micromanaging implementation details - Micromanaging implementation details
- Being defensive about design choices - Being defensive about design choices
- Technical jargon (unless necessary) - Technical jargon (unless necessary)
@ -443,6 +478,7 @@ design vision. Talk soon!"
### For BMad Architect ### For BMad Architect
**Your role:** **Your role:**
- Be the technical authority - Be the technical authority
- Ask clarifying questions - Ask clarifying questions
- Validate technical feasibility - Validate technical feasibility
@ -450,6 +486,7 @@ design vision. Talk soon!"
- Commit to honoring design vision - Commit to honoring design vision
**Tone:** **Tone:**
- Respectful, not dismissive - Respectful, not dismissive
- Curious, not challenging - Curious, not challenging
- Collaborative, not adversarial - Collaborative, not adversarial
@ -457,6 +494,7 @@ design vision. Talk soon!"
- Appreciative, not critical - Appreciative, not critical
**Key phrases:** **Key phrases:**
- "What have you got for me?" - "What have you got for me?"
- "Got it. What about..." - "Got it. What about..."
- "Makes sense. What..." - "Makes sense. What..."
@ -466,6 +504,7 @@ design vision. Talk soon!"
- "I'll honor your design vision" - "I'll honor your design vision"
**What to ask about:** **What to ask about:**
- User value and success criteria - User value and success criteria
- Technical requirements - Technical requirements
- Integration needs - Integration needs
@ -475,6 +514,7 @@ design vision. Talk soon!"
- Special considerations - Special considerations
**What to avoid:** **What to avoid:**
- Challenging design decisions - Challenging design decisions
- Suggesting alternative approaches (unless technical issue) - Suggesting alternative approaches (unless technical issue)
- Dismissing designer's technical choices - Dismissing designer's technical choices
@ -488,6 +528,7 @@ design vision. Talk soon!"
### Before Handoff ### Before Handoff
**WDS UX Expert prepares:** **WDS UX Expert prepares:**
- [ ] Design Delivery file created (DD-XXX.yaml) - [ ] Design Delivery file created (DD-XXX.yaml)
- [ ] All scenarios specified - [ ] All scenarios specified
- [ ] Design system components defined - [ ] Design system components defined
@ -495,6 +536,7 @@ design vision. Talk soon!"
- [ ] Special considerations documented - [ ] Special considerations documented
**BMad Architect prepares:** **BMad Architect prepares:**
- [ ] Platform requirements reviewed - [ ] Platform requirements reviewed
- [ ] Design system reviewed - [ ] Design system reviewed
- [ ] Ready to receive handoff - [ ] Ready to receive handoff
@ -516,12 +558,14 @@ design vision. Talk soon!"
### After Handoff ### After Handoff
**BMad Architect:** **BMad Architect:**
- [ ] Handoff summary documented - [ ] Handoff summary documented
- [ ] Epic breakdown created - [ ] Epic breakdown created
- [ ] Implementation plan documented - [ ] Implementation plan documented
- [ ] Questions or concerns flagged - [ ] Questions or concerns flagged
**WDS UX Expert:** **WDS UX Expert:**
- [ ] Handoff marked complete - [ ] Handoff marked complete
- [ ] Waiting for implementation - [ ] Waiting for implementation
- [ ] Available for questions - [ ] Available for questions
@ -533,6 +577,7 @@ design vision. Talk soon!"
### Simple Delivery (Small Feature) ### Simple Delivery (Small Feature)
**Shorter handoff (~10 min):** **Shorter handoff (~10 min):**
- Quick user value explanation - Quick user value explanation
- Brief scenario walkthrough - Brief scenario walkthrough
- Confirm tech requirements - Confirm tech requirements
@ -541,6 +586,7 @@ design vision. Talk soon!"
### Complex Delivery (Large Feature) ### Complex Delivery (Large Feature)
**Longer handoff (~30 min):** **Longer handoff (~30 min):**
- Detailed user value discussion - Detailed user value discussion
- In-depth scenario walkthrough - In-depth scenario walkthrough
- Technical feasibility discussion - Technical feasibility discussion
@ -550,6 +596,7 @@ design vision. Talk soon!"
### Delivery with Dependencies ### Delivery with Dependencies
**Include dependency discussion:** **Include dependency discussion:**
- Which deliveries must be done first - Which deliveries must be done first
- Why dependencies exist - Why dependencies exist
- How to handle if dependencies delayed - How to handle if dependencies delayed
@ -557,6 +604,7 @@ design vision. Talk soon!"
### Delivery with Technical Concerns ### Delivery with Technical Concerns
**Include concern resolution:** **Include concern resolution:**
- Architect raises concern - Architect raises concern
- UX Expert explains reasoning - UX Expert explains reasoning
- Both discuss alternatives - Both discuss alternatives

30
src/core/resources/wds/integration-guide.md
View File

@ -61,6 +61,7 @@ WDS (Whiteport Design Studio) and BMad Method integrate seamlessly to create a c
**When:** WDS Phase 6 Complete **When:** WDS Phase 6 Complete
**Direction:** WDS → BMad (Complete design handoff) **Direction:** WDS → BMad (Complete design handoff)
**Files:** **Files:**
- `deliveries/DD-*.yaml` (Design Deliveries) - `deliveries/DD-*.yaml` (Design Deliveries)
- `C-Scenarios/` (All scenario specifications) - `C-Scenarios/` (All scenario specifications)
- `D-Design-System/` (Component library) - `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 **BMad Action:** Read everything, break down into dev epics, implement features
**Includes:** **Includes:**
- Multi-agent handoff dialog (20-min structured conversation) - Multi-agent handoff dialog (20-min structured conversation)
- All design deliveries packaged as testable epics - All design deliveries packaged as testable epics
- Complete design system specifications - Complete design system specifications
- Test scenarios for validation - Test scenarios for validation
**Read:** **Read:**
- [design-delivery-spec.md](design-delivery-spec.md) - [design-delivery-spec.md](design-delivery-spec.md)
- [handoff-protocol.md](handoff-protocol.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 **When:** After BMad Implementation Complete
**Direction:** BMad → WDS (BMad integrates with WDS testing) **Direction:** BMad → WDS (BMad integrates with WDS testing)
**Files:** **Files:**
- `test-reports/TR-*.md` (Test results) - `test-reports/TR-*.md` (Test results)
- `issues/ISS-*.md` (Issues found) - `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 **BMad Action:** Fix issues, retest until designer approval
**Process:** **Process:**
1. BMad notifies WDS: "Feature complete, ready for validation" 1. BMad notifies WDS: "Feature complete, ready for validation"
2. WDS runs test scenarios 2. WDS runs test scenarios
3. WDS creates issues if problems found 3. WDS creates issues if problems found
4. BMad fixes issues 4. BMad fixes issues
5. Repeat until WDS signs off 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 ```yaml
platform: platform:
frontend: frontend:
framework: "react_native" framework: 'react_native'
backend: backend:
framework: "supabase" framework: 'supabase'
integrations: integrations:
- name: "supabase_auth" - name: 'supabase_auth'
required: true required: true
constraints: constraints:
- "Must work offline" - 'Must work offline'
- "Must be accessible" - 'Must be accessible'
``` ```
**This overrides BMad's tech stack decisions!** **This overrides BMad's tech stack decisions!**
@ -190,6 +195,7 @@ constraints:
**Strategic Approach:** **Strategic Approach:**
Design until you have a **complete testable user flow** that: Design until you have a **complete testable user flow** that:
- ✅ Delivers value to the business - ✅ Delivers value to the business
- ✅ Delivers value to the end user - ✅ Delivers value to the end user
- ✅ Can be tested for real feedback - ✅ 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. **You're NOT designing everything at once!** You're designing the minimum complete flow that can be tested and validated.
**Phase 4: UX Design** **Phase 4: UX Design**
- Design scenarios for ONE complete user flow - Design scenarios for ONE complete user flow
- Create specifications for each scenario - Create specifications for each scenario
- Ensure the flow delivers measurable value - Ensure the flow delivers measurable value
- Verify it's testable end-to-end - Verify it's testable end-to-end
**Phase 5: Design System** **Phase 5: Design System**
- Define components needed for THIS flow - Define components needed for THIS flow
- Create design tokens for these components - Create design tokens for these components
- Document usage guidelines - Document usage guidelines
@ -232,6 +240,7 @@ D-Design-System/
**Iterative Approach:** **Iterative Approach:**
**First Delivery (Fastest Path to Testing):** **First Delivery (Fastest Path to Testing):**
1. **Design ONE complete user flow** (Phases 4-5) 1. **Design ONE complete user flow** (Phases 4-5)
- Example: Login & Onboarding - Example: Login & Onboarding
- Delivers value: Users can access the app - Delivers value: Users can access the app
@ -251,12 +260,14 @@ D-Design-System/
5. **Hand off to BMad** → Development starts! 5. **Hand off to BMad** → Development starts!
**While BMad builds DD-001, you design DD-002:** **While BMad builds DD-001, you design DD-002:**
- Continue with next complete flow - Continue with next complete flow
- Example: Morning Dog Care - Example: Morning Dog Care
- Hand off when ready - Hand off when ready
- Parallel work = faster delivery - Parallel work = faster delivery
**Benefits:** **Benefits:**
- ✅ Get to testing faster (weeks, not months) - ✅ Get to testing faster (weeks, not months)
- ✅ Validate design with real users early - ✅ Validate design with real users early
- ✅ Learn and iterate before designing everything - ✅ Learn and iterate before designing everything
@ -264,6 +275,7 @@ D-Design-System/
- ✅ Deliver value incrementally - ✅ Deliver value incrementally
**Templates:** **Templates:**
- `templates/design-delivery.template.yaml` - `templates/design-delivery.template.yaml`
- `templates/test-scenario.template.yaml` - `templates/test-scenario.template.yaml`
@ -272,12 +284,14 @@ D-Design-System/
### Phase 7: Testing (After BMad Implementation) ### Phase 7: Testing (After BMad Implementation)
**Wait for BMad notification:** **Wait for BMad notification:**
``` ```
"Feature complete: DD-001 Login & Onboarding "Feature complete: DD-001 Login & Onboarding
Ready for designer validation" Ready for designer validation"
``` ```
**Then:** **Then:**
1. **Run test scenarios** 1. **Run test scenarios**
2. **Create issues** if problems found 2. **Create issues** if problems found
3. **Wait for fixes** 3. **Wait for fixes**
@ -472,6 +486,7 @@ fi
**Phase 7:** Wait for implementation, then validate → **Touch Point 3** **Phase 7:** Wait for implementation, then validate → **Touch Point 3**
**Repeat Phases 4-7 for each flow:** **Repeat Phases 4-7 for each flow:**
- While BMad builds flow 1, design flow 2 - While BMad builds flow 1, design flow 2
- Parallel work = faster delivery - Parallel work = faster delivery
- Test and learn early - Test and learn early
@ -479,15 +494,18 @@ fi
### For BMad Projects ### For BMad Projects
**Check for Touch Point 1:** Platform Requirements **Check for Touch Point 1:** Platform Requirements
- If found: Read and respect tech stack - If found: Read and respect tech stack
- If not found: Make your own decisions - If not found: Make your own decisions
**Wait for Touch Point 2:** Design Deliveries **Wait for Touch Point 2:** Design Deliveries
- Receive complete design package - Receive complete design package
- Break down into dev epics - Break down into dev epics
- Implement features - Implement features
**Trigger Touch Point 3:** Request validation **Trigger Touch Point 3:** Request validation
- Notify designer when complete - Notify designer when complete
- Fix issues as needed - Fix issues as needed
- Iterate until sign-off - Iterate until sign-off

164
src/core/resources/wds/platform-requirements-spec.md
View File

@ -7,6 +7,7 @@
## What are Platform Requirements? ## What are Platform Requirements?
Platform Requirements define the technical foundation for the product: Platform Requirements define the technical foundation for the product:
- Tech stack choices (frontend, backend, database) - Tech stack choices (frontend, backend, database)
- Required integrations - Required integrations
- Infrastructure constraints - Infrastructure constraints
@ -29,80 +30,80 @@ Platform Requirements define the technical foundation for the product:
# Consumed by: BMad Architecture Phase # Consumed by: BMad Architecture Phase
project: project:
name: "Dog Week" name: 'Dog Week'
type: "mobile_app" # mobile_app | web_app | desktop_app | api type: 'mobile_app' # mobile_app | web_app | desktop_app | api
wds_version: "6.0" wds_version: '6.0'
created_at: "2024-12-09T10:00:00Z" created_at: '2024-12-09T10:00:00Z'
platform: platform:
frontend: frontend:
framework: "react_native" framework: 'react_native'
version: "0.72" version: '0.72'
state_management: "zustand" state_management: 'zustand'
navigation: "react_navigation" navigation: 'react_navigation'
styling: "tailwind" styling: 'tailwind'
ui_library: "shadcn" # optional ui_library: 'shadcn' # optional
backend: backend:
framework: "supabase" framework: 'supabase'
version: "2.x" version: '2.x'
auth: "supabase_auth" auth: 'supabase_auth'
database: "postgresql" database: 'postgresql'
storage: "supabase_storage" storage: 'supabase_storage'
api: "rest" # rest | graphql | grpc api: 'rest' # rest | graphql | grpc
database: database:
type: "postgresql" type: 'postgresql'
version: "15" version: '15'
orm: "prisma" # optional orm: 'prisma' # optional
deployment: deployment:
frontend: "expo_eas" frontend: 'expo_eas'
backend: "supabase_cloud" backend: 'supabase_cloud'
ci_cd: "github_actions" ci_cd: 'github_actions'
hosting: "vercel" # if web app hosting: 'vercel' # if web app
integrations: integrations:
- name: "push_notifications" - name: 'push_notifications'
provider: "expo" provider: 'expo'
required: true required: true
purpose: "Task reminders and family updates" purpose: 'Task reminders and family updates'
- name: "image_upload" - name: 'image_upload'
provider: "cloudinary" provider: 'cloudinary'
required: false required: false
purpose: "Dog photos and user avatars" purpose: 'Dog photos and user avatars'
- name: "analytics" - name: 'analytics'
provider: "posthog" provider: 'posthog'
required: false required: false
purpose: "User behavior tracking" purpose: 'User behavior tracking'
constraints: constraints:
- "Must work offline (core features)" - 'Must work offline (core features)'
- "Must support iOS 14+ and Android 10+" - 'Must support iOS 14+ and Android 10+'
- "Must be accessible (WCAG 2.1 AA)" - 'Must be accessible (WCAG 2.1 AA)'
- "Must handle slow networks gracefully" - 'Must handle slow networks gracefully'
- "Must support family sharing (multi-user)" - 'Must support family sharing (multi-user)'
- "Must sync in real-time across devices" - 'Must sync in real-time across devices'
performance_requirements: performance_requirements:
- "App launch < 2 seconds" - 'App launch < 2 seconds'
- "Screen transitions < 300ms" - 'Screen transitions < 300ms'
- "API response time < 500ms" - 'API response time < 500ms'
- "Offline mode must work for 7 days" - 'Offline mode must work for 7 days'
security_requirements: security_requirements:
- "End-to-end encryption for family data" - 'End-to-end encryption for family data'
- "Secure password storage (bcrypt)" - 'Secure password storage (bcrypt)'
- "OAuth 2.0 for third-party auth" - 'OAuth 2.0 for third-party auth'
- "GDPR compliant data handling" - 'GDPR compliant data handling'
wds_metadata: wds_metadata:
project_brief: "A-Project-Brief/project-brief.md" project_brief: 'A-Project-Brief/project-brief.md'
trigger_map: "B-Trigger-Map/trigger-map.md" trigger_map: 'B-Trigger-Map/trigger-map.md'
scenarios: "C-Scenarios/" scenarios: 'C-Scenarios/'
design_system: "D-Design-System/" design_system: 'D-Design-System/'
``` ```
--- ---
@ -188,6 +189,7 @@ for constraint in constraints:
### Respect Designer Decisions ### Respect Designer Decisions
**The designer (with stakeholders) has already decided:** **The designer (with stakeholders) has already decided:**
- ✅ Tech stack - ✅ Tech stack
- ✅ Integrations - ✅ Integrations
- ✅ Constraints - ✅ Constraints
@ -228,18 +230,21 @@ Do NOT proceed until resolved.
## Tech Stack (from Platform Requirements) ## Tech Stack (from Platform Requirements)
### Frontend ### Frontend
- Framework: React Native 0.72 - Framework: React Native 0.72
- State: Zustand - State: Zustand
- Navigation: React Navigation - Navigation: React Navigation
- Styling: Tailwind CSS - Styling: Tailwind CSS
### Backend ### Backend
- Framework: Supabase 2.x - Framework: Supabase 2.x
- Auth: Supabase Auth - Auth: Supabase Auth
- Database: PostgreSQL 15 - Database: PostgreSQL 15
- Storage: Supabase Storage - Storage: Supabase Storage
### Deployment ### Deployment
- Frontend: Expo EAS - Frontend: Expo EAS
- Backend: Supabase Cloud - Backend: Supabase Cloud
- CI/CD: GitHub Actions - CI/CD: GitHub Actions
@ -289,20 +294,22 @@ Design Deliveries reference Platform Requirements
### Example ### Example
**Platform Requirements:** **Platform Requirements:**
```yaml ```yaml
platform: platform:
frontend: frontend:
framework: "react_native" framework: 'react_native'
backend: backend:
framework: "supabase" framework: 'supabase'
``` ```
**Design Delivery DD-001:** **Design Delivery DD-001:**
```yaml ```yaml
technical_requirements: technical_requirements:
platform: platform:
frontend: "react_native" # Matches platform requirements frontend: 'react_native' # Matches platform requirements
backend: "supabase" # Matches platform requirements backend: 'supabase' # Matches platform requirements
``` ```
**Your job:** Ensure consistency between platform requirements and design deliveries **Your job:** Ensure consistency between platform requirements and design deliveries
@ -314,24 +321,27 @@ technical_requirements:
### Types of Constraints ### Types of Constraints
**Technical Constraints:** **Technical Constraints:**
```yaml ```yaml
constraints: constraints:
- "Must work offline (core features)" - 'Must work offline (core features)'
- "Must support iOS 14+ and Android 10+" - 'Must support iOS 14+ and Android 10+'
``` ```
**Business Constraints:** **Business Constraints:**
```yaml ```yaml
constraints: constraints:
- "Must launch in 3 months" - 'Must launch in 3 months'
- "Must support 10,000 concurrent users" - 'Must support 10,000 concurrent users'
``` ```
**Regulatory Constraints:** **Regulatory Constraints:**
```yaml ```yaml
constraints: constraints:
- "Must be GDPR compliant" - 'Must be GDPR compliant'
- "Must be WCAG 2.1 AA accessible" - 'Must be WCAG 2.1 AA accessible'
``` ```
### Handling Constraints ### Handling Constraints
@ -342,12 +352,14 @@ constraints:
Constraint: "Must work offline (core features)" Constraint: "Must work offline (core features)"
Architecture Impact: Architecture Impact:
- Implement local data cache - Implement local data cache
- Sync strategy when online - Sync strategy when online
- Conflict resolution - Conflict resolution
- Offline UI indicators - Offline UI indicators
Implementation: Implementation:
- Use AsyncStorage for local cache - Use AsyncStorage for local cache
- Supabase Realtime for sync - Supabase Realtime for sync
- Optimistic UI updates - Optimistic UI updates
@ -361,9 +373,9 @@ Implementation:
```yaml ```yaml
performance_requirements: performance_requirements:
- "App launch < 2 seconds" - 'App launch < 2 seconds'
- "Screen transitions < 300ms" - 'Screen transitions < 300ms'
- "API response time < 500ms" - 'API response time < 500ms'
``` ```
### Architecture Decisions ### Architecture Decisions
@ -372,6 +384,7 @@ performance_requirements:
Performance Requirement: "App launch < 2 seconds" Performance Requirement: "App launch < 2 seconds"
Architecture Decisions: Architecture Decisions:
1. Lazy load non-critical screens 1. Lazy load non-critical screens
2. Cache authentication state 2. Cache authentication state
3. Preload critical data 3. Preload critical data
@ -379,6 +392,7 @@ Architecture Decisions:
5. Use code splitting 5. Use code splitting
Measurement: Measurement:
- Add performance monitoring - Add performance monitoring
- Track launch time in analytics - Track launch time in analytics
- Set up alerts if > 2 seconds - Set up alerts if > 2 seconds
@ -392,9 +406,9 @@ Measurement:
```yaml ```yaml
security_requirements: security_requirements:
- "End-to-end encryption for family data" - 'End-to-end encryption for family data'
- "Secure password storage (bcrypt)" - 'Secure password storage (bcrypt)'
- "OAuth 2.0 for third-party auth" - 'OAuth 2.0 for third-party auth'
``` ```
### Architecture Decisions ### Architecture Decisions
@ -403,12 +417,14 @@ security_requirements:
Security Requirement: "End-to-end encryption for family data" Security Requirement: "End-to-end encryption for family data"
Architecture Decisions: Architecture Decisions:
1. Generate encryption keys per family 1. Generate encryption keys per family
2. Store keys securely (device keychain) 2. Store keys securely (device keychain)
3. Encrypt data before sending to server 3. Encrypt data before sending to server
4. Decrypt data on device only 4. Decrypt data on device only
Implementation: Implementation:
- Use expo-crypto for encryption - Use expo-crypto for encryption
- Use expo-secure-store for key storage - Use expo-secure-store for key storage
- Implement key rotation strategy - Implement key rotation strategy
@ -422,9 +438,9 @@ Implementation:
```yaml ```yaml
deployment: deployment:
frontend: "expo_eas" frontend: 'expo_eas'
backend: "supabase_cloud" backend: 'supabase_cloud'
ci_cd: "github_actions" ci_cd: 'github_actions'
``` ```
### Architecture Decisions ### Architecture Decisions
@ -433,6 +449,7 @@ deployment:
Deployment: Expo EAS + Supabase Cloud + GitHub Actions Deployment: Expo EAS + Supabase Cloud + GitHub Actions
CI/CD Pipeline: CI/CD Pipeline:
1. Push to GitHub 1. Push to GitHub
2. GitHub Actions runs tests 2. GitHub Actions runs tests
3. Build app with Expo EAS 3. Build app with Expo EAS
@ -440,6 +457,7 @@ CI/CD Pipeline:
5. Submit to App Store / Play Store 5. Submit to App Store / Play Store
Environments: Environments:
- Development: dev.supabase.co - Development: dev.supabase.co
- Staging: staging.supabase.co - Staging: staging.supabase.co
- Production: prod.supabase.co - Production: prod.supabase.co
@ -453,10 +471,10 @@ Environments:
```yaml ```yaml
wds_metadata: wds_metadata:
project_brief: "A-Project-Brief/project-brief.md" project_brief: 'A-Project-Brief/project-brief.md'
trigger_map: "B-Trigger-Map/trigger-map.md" trigger_map: 'B-Trigger-Map/trigger-map.md'
scenarios: "C-Scenarios/" scenarios: 'C-Scenarios/'
design_system: "D-Design-System/" design_system: 'D-Design-System/'
``` ```
**This tells you where to find additional context:** **This tells you where to find additional context:**

4
src/modules/wds/00-getting-started/00-about-wds.md
View File

@ -9,6 +9,7 @@
**Whiteport Design Studio (WDS)** is a design methodology that makes designers indispensable in the AI era. **Whiteport Design Studio (WDS)** is a design methodology that makes designers indispensable in the AI era.
**The paradigm shift:** **The paradigm shift:**
- The design becomes the specification - The design becomes the specification
- The specification becomes the product - The specification becomes the product
- The code is just the printout - The code is just the printout
@ -38,6 +39,7 @@ WDS solves this by preserving design thinking through AI-ready specifications.
## How It Works ## How It Works
WDS provides: WDS provides:
- A systematic workflow from product brief to AI-ready specifications - A systematic workflow from product brief to AI-ready specifications
- Why-based specifications (WHAT + WHY + WHAT NOT TO DO) - Why-based specifications (WHAT + WHY + WHAT NOT TO DO)
- AI agents specifically tailored for design work - AI agents specifically tailored for design work
@ -48,6 +50,7 @@ WDS provides:
## Free and Open-Source ## Free and Open-Source
WDS is completely free and open-source: WDS is completely free and open-source:
- No cost barriers or subscriptions - No cost barriers or subscriptions
- AI agents included - AI agents included
- Community-driven development - Community-driven development
@ -60,6 +63,7 @@ WDS is completely free and open-source:
## Real-World Proof ## Real-World Proof
**Dog Week project:** **Dog Week project:**
- Traditional approach: 26 weeks, mediocre result - Traditional approach: 26 weeks, mediocre result
- WDS approach: 5 weeks, exceptional result - WDS approach: 5 weeks, exceptional result
- **5x speed increase with better quality** - **5x speed increase with better quality**

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

@ -11,6 +11,7 @@
**[Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)** **[Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)**
Deep dive into: Deep dive into:
- Why designers are irreplaceable in the AI era - Why designers are irreplaceable in the AI era
- What WDS is and how it works - What WDS is and how it works
- The BMad Method philosophy - The BMad Method philosophy
@ -28,6 +29,7 @@ Deep dive into:
**[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)** **[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)**
Step-by-step workflows for: Step-by-step workflows for:
- Phase 1: Trigger Mapping - Phase 1: Trigger Mapping
- Phase 2: Information Architecture - Phase 2: Information Architecture
- Phase 3: Interaction Design - 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)** **[Modular Architecture](../workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md)**
Technical details on: Technical details on:
- Three-tier file structure - Three-tier file structure
- Content placement rules - Content placement rules
- Component decomposition - Component decomposition
@ -75,17 +78,21 @@ Technical details on:
## Community & Support ## Community & Support
### Discord ### Discord
Join the WDS community for: Join the WDS community for:
- Questions and answers - Questions and answers
- Project feedback - Project feedback
- Feature discussions - Feature discussions
### GitHub ### GitHub
- Report issues - Report issues
- Request features - Request features
- Contribute - Contribute
### YouTube ### YouTube
- Video tutorials - Video tutorials
- Walkthroughs - Walkthroughs
- Case studies - Case studies

27
src/modules/wds/WDS-WORKFLOWS-GUIDE.md
View File

@ -34,14 +34,14 @@ wds/
WDS creates an alphabetized folder structure in the user's `docs/` folder: WDS creates an alphabetized folder structure in the user's `docs/` folder:
| Folder | Phase | Purpose | | Folder | Phase | Purpose |
|--------|-------|---------| | ------------------ | ----- | ---------------------------------- |
| `A-Product-Brief/` | 1 | Strategic foundation & vision | | `A-Product-Brief/` | 1 | Strategic foundation & vision |
| `B-Trigger-Map/` | 2 | Business goals, personas, drivers | | `B-Trigger-Map/` | 2 | Business goals, personas, drivers |
| `C-Scenarios/` | 4 | Visual specifications & sketches | | `C-Scenarios/` | 4 | Visual specifications & sketches |
| `D-PRD/` | 3 | Product requirements documentation | | `D-PRD/` | 3 | Product requirements documentation |
| `D-Design-System/` | 5 | Component library & design tokens | | `D-Design-System/` | 5 | Component library & design tokens |
| `E-UI-Roadmap/` | 6 | Development integration bridge | | `E-UI-Roadmap/` | 6 | Development integration bridge |
## Phases ## Phases
@ -54,11 +54,11 @@ WDS creates an alphabetized folder structure in the user's `docs/` folder:
## Agents - The Norse Pantheon 🏔️ ## Agents - The Norse Pantheon 🏔️
| Agent | File | Role | Norse Meaning | | Agent | File | Role | Norse Meaning |
|-------|------|------|---------------| | ----------------------- | ------------------------- | -------------------------- | ----------------------------------- |
| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom | | **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 | | **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 | | **Freyja the Designer** | `freyja-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy |
## Conventions ## Conventions
@ -88,4 +88,3 @@ WDS → E-UI-Roadmap/ → BMM Architecture & Stories
--- ---
<sub>Part of the BMad ecosystem • Contributed by Whiteport Collective</sub> <sub>Part of the BMad ecosystem • Contributed by Whiteport Collective</sub>

19
src/modules/wds/course/00-course-overview.md
View File

@ -9,11 +9,13 @@
This comprehensive course teaches you the complete WDS workflow through **practical modules** that transform how you design products. This comprehensive course teaches you the complete WDS workflow through **practical modules** that transform how you design products.
**The paradigm shift:** **The paradigm shift:**
- The design becomes the specification - The design becomes the specification
- The specification becomes the product - The specification becomes the product
- The code is just the printout - The code is just the printout
**What you'll become:** **What you'll become:**
- The linchpin designer who makes things happen - The linchpin designer who makes things happen
- The gatekeeper between business goals and user needs - The gatekeeper between business goals and user needs
- The irreplaceable designer in the AI era - 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)** **[→ Getting Started Guide](00-getting-started/overview.md)**
Review prerequisites, choose your learning path, and get support: Review prerequisites, choose your learning path, and get support:
- **Prerequisites** - Skills, tools, time investment - **Prerequisites** - Skills, tools, time investment
- **Learning Paths** - Full immersion, quick start, or self-paced - **Learning Paths** - Full immersion, quick start, or self-paced
- **Support** - Testimonials, FAQ, community - **Support** - Testimonials, FAQ, community
@ -49,11 +52,13 @@ Review prerequisites, choose your learning path, and get support:
## Course Structure ## Course Structure
Each module contains: Each module contains:
- **Lessons** - Theory and concepts (with NotebookLM audio support) - **Lessons** - Theory and concepts (with NotebookLM audio support)
- **Tutorial** - Step-by-step hands-on guide (for practical modules) - **Tutorial** - Step-by-step hands-on guide (for practical modules)
- **Practice** - Apply to your own project - **Practice** - Apply to your own project
**Learning format:** **Learning format:**
- **Lessons** - Read as documentation or generate audio with NotebookLM - **Lessons** - Read as documentation or generate audio with NotebookLM
- **Tutorials** - Follow step-by-step guides with AI support - **Tutorials** - Follow step-by-step guides with AI support
- **Practice** - Apply to real projects as you learn - **Practice** - Apply to real projects as you learn
@ -64,21 +69,26 @@ Each module contains:
## Course Modules ## Course Modules
### Foundation ### Foundation
- [Module 01: Why WDS Matters](module-01-why-wds-matters/module-01-overview.md) - [Module 01: Why WDS Matters](module-01-why-wds-matters/module-01-overview.md)
### Phase 1: Project Brief ### Phase 1: Project Brief
- [Module 02: Create Project Brief](module-02-project-brief/) • [Tutorial →](module-02-project-brief/tutorial-02.md) - [Module 02: Create Project Brief](module-02-project-brief/) • [Tutorial →](module-02-project-brief/tutorial-02.md)
### Phase 2: Trigger Mapping ### Phase 2: Trigger Mapping
- [Module 03: Identify Target Groups](module-03-identify-target-groups/) - [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 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/) - [Module 05: Prioritize Features](module-05-prioritize-features/)
### Phase 3: Platform Requirements ### Phase 3: Platform Requirements
- [Module 06: Platform Requirements](module-06-platform-requirements/) - [Module 06: Platform Requirements](module-06-platform-requirements/)
- [Module 07: Functional Requirements](module-07-functional-requirements/) - [Module 07: Functional Requirements](module-07-functional-requirements/)
### Phase 4: Conceptual Design (UX Design) ### Phase 4: Conceptual Design (UX Design)
- [Module 08: Initialize Scenario](module-08-initialize-scenario/) • [Tutorial →](module-08-initialize-scenario/tutorial-08.md) - [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 09: Sketch Interfaces](module-09-sketch-interfaces/)
- [Module 10: Analyze with AI](module-10-analyze-with-ai/) - [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/) - [Module 13: Validate Specifications](module-13-validate-specifications/)
### Phase 5: Design System ### Phase 5: Design System
- [Module 14: Extract Design Tokens](module-14-extract-design-tokens/) - [Module 14: Extract Design Tokens](module-14-extract-design-tokens/)
- [Module 15: Component Library](module-15-component-library/) - [Module 15: Component Library](module-15-component-library/)
### Phase 6: Development Integration ### Phase 6: Development Integration
- [Module 16: UI Roadmap](module-16-ui-roadmap/) - [Module 16: UI Roadmap](module-16-ui-roadmap/)
--- ---
@ -108,6 +120,7 @@ Each module contains:
## NotebookLM Integration ## NotebookLM Integration
Each module has matching content for NotebookLM: Each module has matching content for NotebookLM:
- Feed module lessons to NotebookLM - Feed module lessons to NotebookLM
- Generate audio podcasts for learning on the go - Generate audio podcasts for learning on the go
- Generate video presentations for team training - Generate video presentations for team training
@ -122,21 +135,25 @@ Each module has matching content for NotebookLM:
Every module follows the same pattern: Every module follows the same pattern:
**1. Inspiration (10 min)** **1. Inspiration (10 min)**
- Why this step matters - Why this step matters
- The transformation you'll experience - The transformation you'll experience
- Real-world impact - Real-world impact
**2. Teaching (20 min)** **2. Teaching (20 min)**
- How to do it with confidence - How to do it with confidence
- AI support at each step - AI support at each step
- Dog Week example walkthrough - Dog Week example walkthrough
**3. Practice (10 min)** **3. Practice (10 min)**
- Apply to your own project - Apply to your own project
- Step-by-step instructions - Step-by-step instructions
- Success criteria - Success criteria
**4. Tutorial (optional)** **4. Tutorial (optional)**
- Quick step-by-step guide - Quick step-by-step guide
- "Just show me how to do it" - "Just show me how to do it"
- For practical modules only - For practical modules only
@ -156,12 +173,14 @@ Once you've completed the modules:
## Prerequisites ## Prerequisites
**What you need:** **What you need:**
- Basic design thinking and UX principles - Basic design thinking and UX principles
- Ability to sketch interfaces (hand-drawn or digital) - Ability to sketch interfaces (hand-drawn or digital)
- Understanding of user needs and business goals - Understanding of user needs and business goals
- Willingness to think deeply about WHY - Willingness to think deeply about WHY
**What you DON'T need:** **What you DON'T need:**
- ❌ Coding skills - ❌ Coding skills
- ❌ Advanced technical knowledge - ❌ Advanced technical knowledge
- ❌ Experience with AI tools - ❌ Experience with AI tools

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

@ -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: At the end of the podcast, The Advocate should mention these resources for listeners who want to explore further:
**Getting Started:** **Getting Started:**
- Whiteport Design Studio Course: Start with Module 01 - Why WDS Matters - Whiteport Design Studio Course: Start with Module 01 - Why WDS Matters
- GitHub Repository: github.com/bmad-code-org (full course materials, examples, templates) - GitHub Repository: github.com/bmad-code-org (full course materials, examples, templates)
- BMad Method Website: bmadmethod.com (case studies, blog posts, methodology deep dives) - BMad Method Website: bmadmethod.com (case studies, blog posts, methodology deep dives)
**Community & Support:** **Community & Support:**
- GitHub Discussions: Ask questions, share projects, get feedback - GitHub Discussions: Ask questions, share projects, get feedback
- NotebookLM Integration: Generate audio/video versions of any module - NotebookLM Integration: Generate audio/video versions of any module
- Workshop Materials: Available for team training - Workshop Materials: Available for team training
**Real-World Examples:** **Real-World Examples:**
- Case Studies: See real transformations from traditional to Whiteport Design Studio approach - Case Studies: See real transformations from traditional to Whiteport Design Studio approach
- Design System Examples: How Whiteport Design Studio scales across products - Design System Examples: How Whiteport Design Studio scales across products
- Specification Templates: Start with proven patterns - Specification Templates: Start with proven patterns
**Tools & Templates:** **Tools & Templates:**
- Project Brief Template: Start your first WDS project - Project Brief Template: Start your first WDS project
- Trigger Map Template: Map user needs to features - Trigger Map Template: Map user needs to features
- Scenario Specification Template: Create AI-ready specs - 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." 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:** **Tone:**
- Conversational and engaging, not academic - Conversational and engaging, not academic
- The Skeptic asks real questions designers actually have - The Skeptic asks real questions designers actually have
- The Advocate provides concrete answers with examples - 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 - Reference real case studies showing traditional vs WDS transformation
**Key messages to emphasize:** **Key messages to emphasize:**
- **The designer's crossroads** - factory worker or linchpin, replaceable or indispensable - **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 - **The existential choice** - this is about who you choose to become, not what tools you learn
- **Four deliverables** - where your creative brilliance becomes immortal - **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) - Free and open-source (only pay for AI credits when you use it - ~$15-20/month typical)
**Avoid:** **Avoid:**
- Being too salesy or promotional - Being too salesy or promotional
- Oversimplifying the learning curve - Oversimplifying the learning curve
- Making unrealistic promises - Making unrealistic promises
@ -178,6 +185,7 @@ The Advocate emphasizes: "Everything is free and open-source. BMad Method built
## Expected Output ## Expected Output
A natural, engaging conversation that: A natural, engaging conversation that:
- **Focuses on the designer's existential crossroads** - the choice between factory work and linchpin work - **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 - **Makes the transformation emotional and personal** - this is about who you choose to become
- **Emphasizes the four deliverables** as proof of linchpin designer status - **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: If generating video instead of audio, add these visual elements:
**On-screen text:** **On-screen text:**
- "The Designer's Crossroads: Factory Worker or Linchpin?" - "The Designer's Crossroads: Factory Worker or Linchpin?"
- "Replaceable or Indispensable - You Choose" - "Replaceable or Indispensable - You Choose"
- The four deliverables as graphics (Project Brief, Trigger Map, Conceptual Specifications, Design System) - 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 - "Next: Module 01 - The Transformation Begins" as closing card
**B-roll suggestions:** **B-roll suggestions:**
- Designer at crossroads - two paths diverging - Designer at crossroads - two paths diverging
- Factory assembly line vs creative studio (visual metaphor) - Factory assembly line vs creative studio (visual metaphor)
- The four deliverables as beautiful artifacts - The four deliverables as beautiful artifacts
@ -230,6 +240,7 @@ If generating video instead of audio, add these visual elements:
## Next Steps ## Next Steps
After generating the Getting Started content: After generating the Getting Started content:
- Create NotebookLM prompt for Module 01: Why WDS Matters - Create NotebookLM prompt for Module 01: Why WDS Matters
- Build prompts for all 16 modules (complete audio course library) - Build prompts for all 16 modules (complete audio course library)
- Share in BMad Discord designer channel - Share in BMad Discord designer channel

1
src/modules/wds/course/00-getting-started/00-getting-started-YOUTUBE-SHOW-NOTES.md
View File

@ -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 🔹 **Linchpin Designer Path** - Strategic thinking, walking into chaos and creating order, indispensable
🔹 **Four Deliverables:** 🔹 **Four Deliverables:**
- Project Brief (strategic foundation) - Project Brief (strategic foundation)
- Trigger Map (user psychology + business impact) - Trigger Map (user psychology + business impact)
- Scenario Specifications (your thinking captured for eternity) - Scenario Specifications (your thinking captured for eternity)

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

@ -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. 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:** **This section covers:**
1. **Prerequisites** - Skills, tools, and requirements 1. **Prerequisites** - Skills, tools, and requirements
2. **Learning Paths** - How to take the course and what you'll create 2. **Learning Paths** - How to take the course and what you'll create
3. **Support** - Testimonials, FAQ, and community 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 ## Quick Navigation
### [01. Prerequisites →](01-prerequisites.md) ### [01. Prerequisites →](01-prerequisites.md)
What skills you need, tools required, and time investment What skills you need, tools required, and time investment
- **Time:** 5 minutes - **Time:** 5 minutes
- **Key question:** Am I ready to start? - **Key question:** Am I ready to start?
### [02. Learning Paths →](02-learning-paths.md) ### [02. Learning Paths →](02-learning-paths.md)
Choose your journey and see what you'll create Choose your journey and see what you'll create
- **Time:** 5 minutes - **Time:** 5 minutes
- **Key question:** Which path is right for me? - **Key question:** Which path is right for me?
### [03. Support →](03-support.md) ### [03. Support →](03-support.md)
Testimonials, FAQ, and getting help Testimonials, FAQ, and getting help
- **Time:** 5 minutes - **Time:** 5 minutes
- **Key question:** What if I get stuck? - **Key question:** What if I get stuck?
@ -51,6 +58,7 @@ Or review the full course structure:
## Your Transformation Starts Now ## Your Transformation Starts Now
Remember: Remember:
- **The design becomes the specification** - **The design becomes the specification**
- **The specification becomes the product** - **The specification becomes the product**
- **The code is just the printout** - **The code is just the printout**

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

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

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

@ -7,6 +7,7 @@
## Choose Your Journey ## Choose Your Journey
### Option 1: Full Immersion (Recommended) ### Option 1: Full Immersion (Recommended)
- Complete all modules in order - Complete all modules in order
- Practice exercises for each module - Practice exercises for each module
- Apply to a real project as you learn - Apply to a real project as you learn
@ -14,6 +15,7 @@
- **Best for:** Designers who want to master the methodology - **Best for:** Designers who want to master the methodology
### Option 2: Quick Start ### Option 2: Quick Start
- Focus on core modules (Module 01, 02, 04, 06) - Focus on core modules (Module 01, 02, 04, 06)
- Skip advanced topics initially - Skip advanced topics initially
- Get started fast, learn more later - Get started fast, learn more later
@ -21,6 +23,7 @@
- **Best for:** Designers who need results quickly - **Best for:** Designers who need results quickly
### Option 3: Self-Paced ### Option 3: Self-Paced
- Learn one module per week - Learn one module per week
- Deep practice between modules - Deep practice between modules
- Build multiple projects as you learn - Build multiple projects as you learn
@ -36,21 +39,25 @@
By the end of this course, you'll have created: By the end of this course, you'll have created:
**1. Complete Project Brief** **1. Complete Project Brief**
- Vision and goals clearly defined - Vision and goals clearly defined
- Stakeholders and constraints documented - Stakeholders and constraints documented
- Foundation for all design decisions - Foundation for all design decisions
**2. Trigger Map** **2. Trigger Map**
- Target groups identified and prioritized - Target groups identified and prioritized
- User triggers and outcomes mapped - User triggers and outcomes mapped
- Features prioritized by impact - Features prioritized by impact
**3. Scenario Specifications** **3. Scenario Specifications**
- At least one complete user scenario - At least one complete user scenario
- Why-based specifications for key components - Why-based specifications for key components
- AI-ready documentation - AI-ready documentation
**4. Design System Foundation** **4. Design System Foundation**
- Design tokens extracted from your specs - Design tokens extracted from your specs
- Component patterns identified - Component patterns identified
- Reusable architecture defined - Reusable architecture defined
@ -62,12 +69,14 @@ By the end of this course, you'll have created:
## Course Format ## Course Format
Each module contains: Each module contains:
- **Inspiration** - Why this matters and what you'll gain - **Inspiration** - Why this matters and what you'll gain
- **Teaching** - How to do it with confidence and AI support - **Teaching** - How to do it with confidence and AI support
- **Practice** - Apply it to your own project - **Practice** - Apply it to your own project
- **Tutorial** - Quick step-by-step guide (for practical modules) - **Tutorial** - Quick step-by-step guide (for practical modules)
**Learning formats:** **Learning formats:**
- Read as documentation - Read as documentation
- Generate videos/podcasts with NotebookLM - Generate videos/podcasts with NotebookLM
- Use in workshops and team training - Use in workshops and team training

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

@ -24,7 +24,7 @@
> >
> **— James T., Design Director** > **— 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 ### During the Course
**While learning:** **While learning:**
- Each module includes detailed examples - Each module includes detailed examples
- AI assistants can clarify concepts in real-time - AI assistants can clarify concepts in real-time
- Practice exercises with clear success criteria - Practice exercises with clear success criteria
**After completion:** **After completion:**
- GitHub Discussions for questions and sharing - GitHub Discussions for questions and sharing
- Community showcase of WDS projects - Community showcase of WDS projects
- Regular updates and new case studies - Regular updates and new case studies
**Contributing:** **Contributing:**
- WDS is open-source and welcomes contributions - WDS is open-source and welcomes contributions
- Share your case studies and learnings - Share your case studies and learnings
- Help improve the course for future designers - 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 ### Resources
**Documentation:** **Documentation:**
- Full course materials in markdown - Full course materials in markdown
- NotebookLM integration for audio/video learning - NotebookLM integration for audio/video learning
- Workshop materials for team training - Workshop materials for team training
**Community:** **Community:**
- GitHub Discussions for Q&A - GitHub Discussions for Q&A
- Project showcase and feedback - Project showcase and feedback
- Regular updates and improvements - Regular updates and improvements
**Open Source:** **Open Source:**
- Free to use and share - Free to use and share
- Contributions welcome - Contributions welcome
- Help shape the future of WDS - 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? ## Ready to Start?
You have everything you need: You have everything you need:
- ✅ The skills (design thinking) - ✅ The skills (design thinking)
- ✅ The tools (paper + AI) - ✅ The tools (paper + AI)
- ✅ The time (10 hours) - ✅ The time (10 hours)

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

@ -1,4 +1,5 @@
# Module 01: Why WDS Matters # Module 01: Why WDS Matters
## Lesson 1: The Problem We're Solving ## Lesson 1: The Problem We're Solving
**Understanding the factory mindset and the AI era** **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. 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:** **What makes an irreplaceable designer:**
- Connects disparate ideas across business, psychology, and technology - Connects disparate ideas across business, psychology, and technology
- Makes things happen when there's no instruction manual - Makes things happen when there's no instruction manual
- Creates value that can't be commoditized or automated - 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. 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:** **Your transformation:**
- ✅ Understand why designers are irreplaceable in the AI era - ✅ Understand why designers are irreplaceable in the AI era
- ✅ Master the 5 dimensions of designer thinking - ✅ Master the 5 dimensions of designer thinking
- ✅ Recognize what AI can and cannot do - ✅ 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. 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:** **The factory mindset in design:**
- Creates mockups by following briefs (instructions) - Creates mockups by following briefs (instructions)
- Hands off to developers (replaceable step) - Hands off to developers (replaceable step)
- Hopes they understand (no real connection) - 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. 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:** **What AI does better than cogs:**
- Generates mockups instantly (no creative block) - Generates mockups instantly (no creative block)
- Follows design systems perfectly (zero deviation) - Follows design systems perfectly (zero deviation)
- Iterates through hundreds of variations (no fatigue) - 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. 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):** **What makes products come alive (what only designers can do):**
- Navigate 5 dimensions to find the human truth at the intersection - Navigate 5 dimensions to find the human truth at the intersection
- Make judgment calls that create emotional resonance, not just functionality - Make judgment calls that create emotional resonance, not just functionality
- Build trust through decisions that show someone cared - Build trust through decisions that show someone cared

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

@ -1,4 +1,5 @@
# Module 01: Why WDS Matters # Module 01: Why WDS Matters
## Lesson 2: Becoming a Linchpin Designer ## Lesson 2: Becoming a Linchpin Designer
**The solution: WDS methodology** **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. 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:** **The irreplaceable designer:**
- Transforms complexity into clarity - Transforms complexity into clarity
- Invents solutions nobody expected - Invents solutions nobody expected
- Bridges business, psychology, and technology - 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. 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:** **The designer as gatekeeper:**
- Catches AI's confident but ridiculous mistakes before they ship - Catches AI's confident but ridiculous mistakes before they ship
- Evaluates if solutions actually make logical sense - Evaluates if solutions actually make logical sense
- Ensures business goals don't contradict user needs - 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. 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:** **The designer's transformation:**
- **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage - **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage
- **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely - **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely
- **Result:** From replaceable cog to indispensable gatekeeper - your design IS the product - **Result:** From replaceable cog to indispensable gatekeeper - your design IS the product

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

@ -1,4 +1,5 @@
# Module 01: Why WDS Matters # Module 01: Why WDS Matters
## Lesson 3: Your Transformation ## Lesson 3: Your Transformation
**From replaceable to indispensable** **From replaceable to indispensable**
@ -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. You'll become the designer who makes things happen. The one they can't do without. The linchpin designer.
**Your transformation as a designer:** **Your transformation as a designer:**
- **Before:** Threatened, uncertain, frustrated, limited, replaceable - **Before:** Threatened, uncertain, frustrated, limited, replaceable
- **After:** Confident, clear, empowered, unstoppable, indispensable - **After:** Confident, clear, empowered, unstoppable, indispensable
- **Result:** The designer who makes things happen - **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. 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:** **The comparison:**
- **Traditional (cog designer):** 26 weeks → Mediocre result → Intent lost - **Traditional (cog designer):** 26 weeks → Mediocre result → Intent lost
- **WDS (linchpin designer):** 5 weeks → Exceptional result → Intent preserved - **WDS (linchpin designer):** 5 weeks → Exceptional result → Intent preserved
- **Key difference:** Designer's user-centric creativity captured and amplified - **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! ## Module Complete!
You've completed Module 01: Why WDS Matters. You now understand: You've completed Module 01: Why WDS Matters. You now understand:
- ✅ The problem: Factory mindset vs linchpin mindset - ✅ The problem: Factory mindset vs linchpin mindset
- ✅ The solution: Becoming a linchpin designer with WDS - ✅ The solution: Becoming a linchpin designer with WDS
- ✅ The path forward: 5-dimensional thinking and transformation - ✅ The path forward: 5-dimensional thinking and transformation
**Next steps:** **Next steps:**
- Review the practicalities if you haven't already - Review the practicalities if you haven't already
- Start Module 02: Project Brief - Start Module 02: Project Brief
- Apply these concepts to your own work - Apply these concepts to your own work

22
src/modules/wds/course/module-01-why-wds-matters/module-01-NOTEBOOKLM-PROMPT.md
View File

@ -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:" 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: What user-centric creativity looks like:
- **Understanding WHY** - Not just making things look better, but understanding why users feel frustrated - **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 - **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 - **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." 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: Godin describes linchpins as people who:
- **Invent** - Create solutions that didn't exist before - **Invent** - Create solutions that didn't exist before
- **Connect** - Bridge disparate ideas and people - **Connect** - Bridge disparate ideas and people
- **Create** - Make things that matter - **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:" 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)** **1. Emotional Labor (Genuine Caring)**
- You genuinely care about the outcome - You genuinely care about the outcome
- You empathize with user frustration - You empathize with user frustration
- You feel the weight of your decisions - You feel the weight of your decisions
- You provide meaning, not just features - You provide meaning, not just features
**2. User-Centric Creativity (Connecting Needs)** **2. User-Centric Creativity (Connecting Needs)**
- You understand WHY users feel frustrated - You understand WHY users feel frustrated
- You connect business goals to human needs - You connect business goals to human needs
- You create experiences that feel right - You create experiences that feel right
- You make judgment calls that serve people - You make judgment calls that serve people
**3. The Gatekeeper Role (Protecting Quality)** **3. The Gatekeeper Role (Protecting Quality)**
- You catch mistakes before they ship - You catch mistakes before they ship
- You evaluate if solutions make logical sense - You evaluate if solutions make logical sense
- You ensure goals don't contradict needs - 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." The paradigm shift: "Design becomes specification. Specification becomes product. Your creative thinking is preserved and amplified, not diluted and lost."
Your transformation: Your transformation:
- **From:** Creating mockups hoping developers understand your intent - **From:** Creating mockups hoping developers understand your intent
- **To:** Capturing your design thinking in specifications that preserve your creative decisions - **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 - **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 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: The 5 dimensions:
1. **Business Existence (WHY)** - Understanding purpose and value creation 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 3. **Product Strategy (HOW)** - Making hard choices about features
@ -139,6 +146,7 @@ The 5 dimensions:
**Real Example - Family Coordination App:** **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: 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) - **WHY** - Why does this business exist? (Solving family conflict and stress)
- **SUCCESS** - What does success look like? (Kids complete tasks without nagging) - **SUCCESS** - What does success look like? (Kids complete tasks without nagging)
- **HOW** - What features serve that goal? (Visual task board, not text lists) - **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." 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: What you learn:
- How to uncover the real business purpose (not just features) - How to uncover the real business purpose (not just features)
- How to understand user goals at a deep level (not just tasks) - How to understand user goals at a deep level (not just tasks)
- How to find the intersection where both are served - 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." 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: What you learn:
- How to write specifications that capture WHY, not just WHAT - How to write specifications that capture WHY, not just WHAT
- How to document your judgment calls and reasoning - How to document your judgment calls and reasoning
- How to work with AI as your creative partner - 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." 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: What you learn:
- How to lead the design process (courage and curiosity, not confidence) - How to lead the design process (courage and curiosity, not confidence)
- How to serve the client with clarity on business value - How to serve the client with clarity on business value
- How to serve developers with specifications they can implement - 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." 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: Your transformation:
- **Understanding** - Business and user goals at a deep level - **Understanding** - Business and user goals at a deep level
- **Capability** - Working in the IDE, design as specification - **Capability** - Working in the IDE, design as specification
- **Leadership** - Serving client and developers with what they need - **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: At the end of the podcast, The Advocate should mention these resources:
**Key Concepts:** **Key Concepts:**
- Seth Godin's book: "Linchpin: Are You Indispensable?" (2010) - Seth Godin's book: "Linchpin: Are You Indispensable?" (2010)
- Bestselling author and marketing visionary Seth Godin - Bestselling author and marketing visionary Seth Godin
- Factory mindset vs linchpin mindset - Factory mindset vs linchpin mindset
@ -267,12 +280,14 @@ At the end of the podcast, The Advocate should mention these resources:
- 5-dimensional thinking - 5-dimensional thinking
**Next Steps:** **Next Steps:**
- Complete Module 02: Project Brief - Complete Module 02: Project Brief
- Apply 5-dimensional thinking to your current project - Apply 5-dimensional thinking to your current project
- Start capturing WHY in your design decisions - Start capturing WHY in your design decisions
- Practice being the gatekeeper between business and user needs - Practice being the gatekeeper between business and user needs
**Community:** **Community:**
- BMad Discord: Share your transformation journey - BMad Discord: Share your transformation journey
- GitHub Discussions: Ask questions about becoming a linchpin designer - 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 ## Instructions for NotebookLM
**Tone:** **Tone:**
- Deeply empathetic about the shame and fear designers feel - Deeply empathetic about the shame and fear designers feel
- Honest and direct about the AI threat for factory workers - Honest and direct about the AI threat for factory workers
- Empowering and inspiring about the opportunity for linchpin designers - 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) - Balance fear (replaceable) with hope (indispensable) and community (not alone)
**Key messages to emphasize:** **Key messages to emphasize:**
- **The linchpin question** - are you a factory worker or a linchpin designer? - **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) - **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) - **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 - **Action beats perfection** - get moving and you will figure it out
**Avoid:** **Avoid:**
- Being too theoretical or academic - Being too theoretical or academic
- Repeating doom/gloom from Getting Started module - Repeating doom/gloom from Getting Started module
- Focusing too much on AI threat instead of human value - 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 ## Expected Output
A natural, engaging conversation that: A natural, engaging conversation that:
- **Focuses on human value** - what makes designers irreplaceable - **Focuses on human value** - what makes designers irreplaceable
- **Explains the linchpin concept** clearly using Seth Godin's framework - **Explains the linchpin concept** clearly using Seth Godin's framework
- **Emphasizes emotional labor** as the core of linchpin work - **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: If generating video instead of audio, add these visual elements:
**On-screen text:** **On-screen text:**
- "Factory Worker or Linchpin Designer?" - "Factory Worker or Linchpin Designer?"
- Seth Godin quote: "Linchpins walk into chaos and create order" - Seth Godin quote: "Linchpins walk into chaos and create order"
- "Emotional Labor: The Work of Genuinely Caring" - "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" - "Next: Module 02 - Project Brief"
**B-roll suggestions:** **B-roll suggestions:**
- Designer walking into chaos, creating order - Designer walking into chaos, creating order
- Linchpin connecting disparate ideas - Linchpin connecting disparate ideas
- Designer providing emotional labor - caring, empathizing - Designer providing emotional labor - caring, empathizing
@ -387,6 +408,7 @@ If generating video instead of audio, add these visual elements:
## Next Steps ## Next Steps
After generating Module 01 content: After generating Module 01 content:
- Create NotebookLM prompt for Module 02: Project Brief - Create NotebookLM prompt for Module 02: Project Brief
- Build prompts for all remaining modules - Build prompts for all remaining modules
- Share in BMad Discord designer channel - Share in BMad Discord designer channel

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

@ -27,9 +27,11 @@ This foundational module transforms how you think about your role as a designer
## Lessons ## Lessons
### [Lesson 1: The Problem We're Solving](lesson-01-the-problem.md) ### [Lesson 1: The Problem We're Solving](lesson-01-the-problem.md)
**Time:** 10 minutes **Time:** 10 minutes
Understanding the factory mindset and the AI era: Understanding the factory mindset and the AI era:
- Why learning WDS matters - Why learning WDS matters
- What you'll gain from this course - What you'll gain from this course
- Factory mindset vs linchpin mindset - Factory mindset vs linchpin mindset
@ -37,9 +39,11 @@ Understanding the factory mindset and the AI era:
- AI opportunity for linchpin designers - AI opportunity for linchpin designers
### [Lesson 2: Becoming a Linchpin Designer](lesson-02-the-solution.md) ### [Lesson 2: Becoming a Linchpin Designer](lesson-02-the-solution.md)
**Time:** 10 minutes **Time:** 10 minutes
The solution: WDS methodology: The solution: WDS methodology:
- What makes a linchpin designer - What makes a linchpin designer
- The designer's gift: user-centric creativity - The designer's gift: user-centric creativity
- The designer as gatekeeper - The designer as gatekeeper
@ -47,9 +51,11 @@ The solution: WDS methodology:
- The paradigm shift: design becomes specification - The paradigm shift: design becomes specification
### [Lesson 3: Your Transformation](lesson-03-the-path-forward.md) ### [Lesson 3: Your Transformation](lesson-03-the-path-forward.md)
**Time:** 10 minutes **Time:** 10 minutes
From replaceable to indispensable: From replaceable to indispensable:
- The 5 dimensions of design thinking - The 5 dimensions of design thinking
- Your transformation as a designer - Your transformation as a designer
- Real-world case studies (Dog Week) - Real-world case studies (Dog Week)
@ -60,12 +66,14 @@ From replaceable to indispensable:
## Key Concepts ## Key Concepts
**Linchpin Designer:** **Linchpin Designer:**
- Walks into chaos and creates order - Walks into chaos and creates order
- Invents solutions nobody expected - Invents solutions nobody expected
- Bridges business, psychology, and technology - Bridges business, psychology, and technology
- Delivers results when there's no roadmap - Delivers results when there's no roadmap
**User-Centric Creativity:** **User-Centric Creativity:**
- Understanding WHY users feel frustrated - Understanding WHY users feel frustrated
- Connecting business goals to human needs - Connecting business goals to human needs
- Creating experiences that feel right - Creating experiences that feel right
@ -73,6 +81,7 @@ From replaceable to indispensable:
- Being the gatekeeper for quality - Being the gatekeeper for quality
**The Paradigm Shift:** **The Paradigm Shift:**
- The design becomes the specification - The design becomes the specification
- The specification becomes the product - The specification becomes the product
- The code is just the printout - The code is just the printout
@ -82,6 +91,7 @@ From replaceable to indispensable:
## Learning Outcomes ## Learning Outcomes
By the end of this module, you will: By the end of this module, you will:
- ✅ Understand why designers are irreplaceable in the AI era - ✅ Understand why designers are irreplaceable in the AI era
- ✅ Know the difference between cog work and linchpin work - ✅ Know the difference between cog work and linchpin work
- ✅ Recognize what AI can and cannot do - ✅ Recognize what AI can and cannot do

30
src/modules/wds/course/module-02-project-brief/tutorial-02.md
View File

@ -27,11 +27,13 @@ This tutorial walks you through creating a complete project brief that serves as
## Before You Start ## Before You Start
**You'll need:** **You'll need:**
- A project idea (existing or new) - A project idea (existing or new)
- 30-45 minutes of focused time - 30-45 minutes of focused time
- Access to stakeholder information (if available) - Access to stakeholder information (if available)
**AI Support:** **AI Support:**
- AI agent will guide you through each section - AI agent will guide you through each section
- Ask clarifying questions - Ask clarifying questions
- Help structure your thinking - Help structure your thinking
@ -48,12 +50,14 @@ The project vision is a clear, compelling statement of what you're building and
### How to do it: ### How to do it:
**Ask yourself:** **Ask yourself:**
- What problem does this solve? - What problem does this solve?
- Who benefits from this solution? - Who benefits from this solution?
- What makes this unique or valuable? - What makes this unique or valuable?
- What's the desired end state? - What's the desired end state?
**Example (Dog Week):** **Example (Dog Week):**
``` ```
Vision: A family coordination platform that helps parents manage Vision: A family coordination platform that helps parents manage
their dog's care schedule, ensuring every family member knows their their dog's care schedule, ensuring every family member knows their
@ -61,12 +65,14 @@ responsibilities and the dog's needs are consistently met.
``` ```
**Your turn:** **Your turn:**
``` ```
Write your project vision: Write your project vision:
[Your vision here] [Your vision here]
``` ```
**AI Support:** **AI Support:**
``` ```
Agent: "Let me help you refine your vision. Tell me: Agent: "Let me help you refine your vision. Tell me:
- What problem are you solving? - What problem are you solving?
@ -85,6 +91,7 @@ Specific, measurable objectives that define project success from a business pers
### How to do it: ### How to do it:
**Framework: SMART Goals** **Framework: SMART Goals**
- **S**pecific - Clear and unambiguous - **S**pecific - Clear and unambiguous
- **M**easurable - Can track progress - **M**easurable - Can track progress
- **A**chievable - Realistic given resources - **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 - **T**ime-bound - Has a deadline
**Example (Dog Week):** **Example (Dog Week):**
``` ```
Business Goals: Business Goals:
1. Acquire 1,000 active families within 6 months of launch 1. Acquire 1,000 active families within 6 months of launch
@ -101,6 +109,7 @@ Business Goals:
``` ```
**Your turn:** **Your turn:**
``` ```
List 3-5 business goals: List 3-5 business goals:
1. [Goal 1] 1. [Goal 1]
@ -109,6 +118,7 @@ List 3-5 business goals:
``` ```
**AI Support:** **AI Support:**
``` ```
Agent: "Let's make these goals SMART. For each goal, I'll help you: Agent: "Let's make these goals SMART. For each goal, I'll help you:
- Make it specific and measurable - 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: ### How to do it:
**Categories:** **Categories:**
- **Primary Users** - Direct users of the product - **Primary Users** - Direct users of the product
- **Secondary Users** - Indirect beneficiaries - **Secondary Users** - Indirect beneficiaries
- **Business Stakeholders** - Decision makers, investors - **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 - **External Stakeholders** - Partners, regulators, community
**Example (Dog Week):** **Example (Dog Week):**
``` ```
Stakeholders: Stakeholders:
- Primary: Parents managing family dog care - Primary: Parents managing family dog care
@ -144,6 +156,7 @@ Stakeholders:
``` ```
**Your turn:** **Your turn:**
``` ```
List your stakeholders by category: List your stakeholders by category:
[Your stakeholders] [Your stakeholders]
@ -162,6 +175,7 @@ Limitations and requirements that shape your design decisions.
**Categories:** **Categories:**
**Technical Constraints:** **Technical Constraints:**
- Platform requirements (web, mobile, desktop) - Platform requirements (web, mobile, desktop)
- Browser/device support - Browser/device support
- Performance requirements - Performance requirements
@ -169,6 +183,7 @@ Limitations and requirements that shape your design decisions.
- Security/compliance needs - Security/compliance needs
**Business Constraints:** **Business Constraints:**
- Budget limitations - Budget limitations
- Timeline requirements - Timeline requirements
- Resource availability - Resource availability
@ -176,12 +191,14 @@ Limitations and requirements that shape your design decisions.
- Competitive landscape - Competitive landscape
**Design Constraints:** **Design Constraints:**
- Brand guidelines - Brand guidelines
- Accessibility requirements - Accessibility requirements
- Localization needs - Localization needs
- Existing design systems - Existing design systems
**Example (Dog Week):** **Example (Dog Week):**
``` ```
Constraints: Constraints:
Technical: Technical:
@ -202,12 +219,14 @@ Design:
``` ```
**Your turn:** **Your turn:**
``` ```
Document your constraints: Document your constraints:
[Your constraints] [Your constraints]
``` ```
**AI Support:** **AI Support:**
``` ```
Agent: "Let's identify constraints you might have missed: Agent: "Let's identify constraints you might have missed:
- Have you considered accessibility? - Have you considered accessibility?
@ -227,12 +246,14 @@ Specific metrics that indicate whether the project achieved its goals.
### How to do it: ### How to do it:
**Framework:** **Framework:**
- **User Success** - How users benefit - **User Success** - How users benefit
- **Business Success** - Revenue, growth, efficiency - **Business Success** - Revenue, growth, efficiency
- **Technical Success** - Performance, reliability, scalability - **Technical Success** - Performance, reliability, scalability
- **Design Success** - Usability, satisfaction, engagement - **Design Success** - Usability, satisfaction, engagement
**Example (Dog Week):** **Example (Dog Week):**
``` ```
Success Criteria: Success Criteria:
@ -258,6 +279,7 @@ Design Success:
``` ```
**Your turn:** **Your turn:**
``` ```
Define your success criteria: Define your success criteria:
[Your criteria] [Your criteria]
@ -270,6 +292,7 @@ Define your success criteria:
### Checklist: ### Checklist:
**Completeness:** **Completeness:**
- ✓ Vision is clear and compelling - ✓ Vision is clear and compelling
- ✓ Goals are SMART - ✓ Goals are SMART
- ✓ All stakeholder groups identified - ✓ All stakeholder groups identified
@ -277,12 +300,14 @@ Define your success criteria:
- ✓ Success criteria defined - ✓ Success criteria defined
**Quality:** **Quality:**
- ✓ Vision is inspiring and actionable - ✓ Vision is inspiring and actionable
- ✓ Goals are measurable and realistic - ✓ Goals are measurable and realistic
- ✓ Constraints are specific and justified - ✓ Constraints are specific and justified
- ✓ Success criteria are trackable - ✓ Success criteria are trackable
**AI Support:** **AI Support:**
``` ```
Agent: "Let me review your project brief: Agent: "Let me review your project brief:
- Is the vision clear? - 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` **Use template from:** `workflows/1-project-brief/complete/project-brief.template.md`
**Populate with your content:** **Populate with your content:**
- Vision - Vision
- Business goals - Business goals
- Stakeholders - Stakeholders
@ -321,11 +347,13 @@ Agent: "Let me review your project brief:
## Next Steps ## Next Steps
**Immediate:** **Immediate:**
- Share project brief with stakeholders for feedback - Share project brief with stakeholders for feedback
- Get alignment on vision and goals - Get alignment on vision and goals
- Confirm constraints are accurate - Confirm constraints are accurate
**Next Module:** **Next Module:**
- [Module 03: Identify Target Groups](../module-03-identify-target-groups/module-03-overview.md) - [Module 03: Identify Target Groups](../module-03-identify-target-groups/module-03-overview.md)
- Start mapping WHO your users are - Start mapping WHO your users are
@ -350,6 +378,7 @@ A: Use the brief to facilitate alignment discussions. Document disagreements and
## Tips for Success ## Tips for Success
**DO ✅** **DO ✅**
- Be specific and concrete - Be specific and concrete
- Make goals measurable - Make goals measurable
- Document the "why" behind constraints - 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) - Keep it concise (2-3 pages max)
**DON'T ❌** **DON'T ❌**
- Write vague, aspirational statements - Write vague, aspirational statements
- Set unrealistic goals - Set unrealistic goals
- Skip constraint documentation - Skip constraint documentation

29
src/modules/wds/course/module-04-map-triggers-outcomes/tutorial-04.md
View File

@ -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. From Module 03, choose your highest-priority target group.
**Example (Dog Week):** **Example (Dog Week):**
``` ```
Target Group: Busy Parents with Family Dog Target Group: Busy Parents with Family Dog
Priority: #1 (highest impact + feasibility) Priority: #1 (highest impact + feasibility)
``` ```
**Your turn:** **Your turn:**
``` ```
Selected Target Group: [Your top group] Selected Target Group: [Your top group]
Why this group: [Reasoning] 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 ### Framework: The Trigger Moment
**Ask:** **Ask:**
- WHEN does the user feel pain/frustration? - WHEN does the user feel pain/frustration?
- WHAT specific situation causes this? - WHAT specific situation causes this?
- WHY does this matter to them emotionally? - 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):** **Example (Dog Week - Busy Parents):**
**Trigger 1: Morning Chaos** **Trigger 1: Morning Chaos**
``` ```
WHEN: Monday morning, everyone rushing WHEN: Monday morning, everyone rushing
WHAT: Nobody knows who's walking the dog 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** **Trigger 2: Forgotten Feeding**
``` ```
WHEN: Evening, parent realizes dog wasn't fed WHEN: Evening, parent realizes dog wasn't fed
WHAT: Uncertainty about who was responsible WHAT: Uncertainty about who was responsible
@ -72,6 +77,7 @@ WHY: Guilt, worry about dog's health, family tension
``` ```
**Trigger 3: Vet Appointment Missed** **Trigger 3: Vet Appointment Missed**
``` ```
WHEN: Vet calls about missed appointment WHEN: Vet calls about missed appointment
WHAT: Nobody remembered or knew about it WHAT: Nobody remembered or knew about it
@ -79,6 +85,7 @@ WHY: Embarrassment, concern for dog, wasted money
``` ```
**Your turn:** **Your turn:**
``` ```
Identify 3-5 trigger moments for your target group: Identify 3-5 trigger moments for your target group:
@ -96,6 +103,7 @@ WHY:
``` ```
**AI Support:** **AI Support:**
``` ```
Agent: "Let's dig deeper into each trigger: Agent: "Let's dig deeper into each trigger:
- What happens right before this moment? - What happens right before this moment?
@ -115,6 +123,7 @@ The underlying requirement the user has when triggered.
### Framework: From Trigger to Need ### Framework: From Trigger to Need
**For each trigger, ask:** **For each trigger, ask:**
- What does the user need in this moment? - What does the user need in this moment?
- What would make this situation better? - What would make this situation better?
- What's the core problem to solve? - What's the core problem to solve?
@ -122,6 +131,7 @@ The underlying requirement the user has when triggered.
**Example (Dog Week):** **Example (Dog Week):**
**Trigger: Morning Chaos** **Trigger: Morning Chaos**
``` ```
Need: Know immediately who's responsible for dog care today Need: Know immediately who's responsible for dog care today
Need: See the full week's schedule at a glance Need: See the full week's schedule at a glance
@ -129,6 +139,7 @@ Need: Get reminded before tasks are due
``` ```
**Trigger: Forgotten Feeding** **Trigger: Forgotten Feeding**
``` ```
Need: Track whether tasks were completed Need: Track whether tasks were completed
Need: Get notifications when tasks are overdue Need: Get notifications when tasks are overdue
@ -136,6 +147,7 @@ Need: See task history to avoid confusion
``` ```
**Your turn:** **Your turn:**
``` ```
For each trigger, identify 2-3 core needs: 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 ### Framework: Need to Solution
**For each need, ask:** **For each need, ask:**
- What feature would solve this? - What feature would solve this?
- How would it work? - How would it work?
- What's the simplest version? - What's the simplest version?
@ -166,6 +179,7 @@ The specific feature or capability that addresses the need.
**Example (Dog Week):** **Example (Dog Week):**
**Need: Know who's responsible today** **Need: Know who's responsible today**
``` ```
Solution: Daily schedule view with assigned responsibilities Solution: Daily schedule view with assigned responsibilities
- Shows today's tasks - Shows today's tasks
@ -174,6 +188,7 @@ Solution: Daily schedule view with assigned responsibilities
``` ```
**Need: Get reminded before tasks are due** **Need: Get reminded before tasks are due**
``` ```
Solution: Smart notifications Solution: Smart notifications
- Reminder 1 hour before task - Reminder 1 hour before task
@ -182,6 +197,7 @@ Solution: Smart notifications
``` ```
**Your turn:** **Your turn:**
``` ```
For each need, define a solution: For each need, define a solution:
@ -195,6 +211,7 @@ Solution: [Feature name]
``` ```
**AI Support:** **AI Support:**
``` ```
Agent: "Let's validate each solution: Agent: "Let's validate each solution:
- Does this truly solve the need? - Does this truly solve the need?
@ -214,6 +231,7 @@ The business value created when users get their needs met.
### Framework: Solution to Outcome ### Framework: Solution to Outcome
**For each solution, ask:** **For each solution, ask:**
- How does this create business value? - How does this create business value?
- What metrics improve? - What metrics improve?
- How does this support business goals? - How does this support business goals?
@ -221,6 +239,7 @@ The business value created when users get their needs met.
**Example (Dog Week):** **Example (Dog Week):**
**Solution: Daily schedule view** **Solution: Daily schedule view**
``` ```
User Outcome: Reduced stress, better dog care User Outcome: Reduced stress, better dog care
Business Outcome: Business Outcome:
@ -231,6 +250,7 @@ Metrics: DAU, retention rate, NPS
``` ```
**Solution: Smart notifications** **Solution: Smart notifications**
``` ```
User Outcome: Never miss dog care tasks User Outcome: Never miss dog care tasks
Business Outcome: Business Outcome:
@ -241,6 +261,7 @@ Metrics: Notification open rate, task completion rate, conversion
``` ```
**Your turn:** **Your turn:**
``` ```
For each solution, map to business outcomes: For each solution, map to business outcomes:
@ -305,6 +326,7 @@ TRIGGER → NEED → SOLUTION → OUTCOME
``` ```
**Your turn:** **Your turn:**
``` ```
Create your trigger map: Create your trigger map:
[Your complete map] [Your complete map]
@ -317,6 +339,7 @@ Create your trigger map:
### Framework: Impact Score ### Framework: Impact Score
**For each trigger-to-outcome chain, rate:** **For each trigger-to-outcome chain, rate:**
- **User Impact** (1-5): How much does this help the user? - **User Impact** (1-5): How much does this help the user?
- **Business Impact** (1-5): How much business value does this create? - **Business Impact** (1-5): How much business value does this create?
- **Feasibility** (1-5): How easy is this to build? - **Feasibility** (1-5): How easy is this to build?
@ -340,6 +363,7 @@ Create your trigger map:
``` ```
**Your turn:** **Your turn:**
``` ```
Score and rank your triggers: Score and rank your triggers:
[Your prioritized list] [Your prioritized list]
@ -368,6 +392,7 @@ Score and rank your triggers:
## The Power of Trigger Mapping ## The Power of Trigger Mapping
**This is strategic gold:** **This is strategic gold:**
- Every feature traces back to a real user trigger - Every feature traces back to a real user trigger
- Every decision is backed by user psychology - Every decision is backed by user psychology
- Every feature connects to business value - Every feature connects to business value
@ -382,11 +407,13 @@ Score and rank your triggers:
## Next Steps ## Next Steps
**Immediate:** **Immediate:**
- Repeat for your top 2-3 target groups - Repeat for your top 2-3 target groups
- Compare trigger maps across groups - Compare trigger maps across groups
- Identify overlapping needs (efficiency opportunity) - Identify overlapping needs (efficiency opportunity)
**Next Module:** **Next Module:**
- [Module 05: Prioritize Features](../module-05-prioritize-features/module-05-overview.md) - [Module 05: Prioritize Features](../module-05-prioritize-features/module-05-overview.md)
- Create your feature roadmap based on trigger impact - 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 ## Tips for Success
**DO ✅** **DO ✅**
- Be specific about trigger moments - Be specific about trigger moments
- Focus on emotional impact (the "why") - Focus on emotional impact (the "why")
- Connect everything to business outcomes - 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 - Test assumptions with users
**DON'T ❌** **DON'T ❌**
- List generic "user wants X" statements - List generic "user wants X" statements
- Skip the emotional "why" - Skip the emotional "why"
- Create solutions without clear triggers - Create solutions without clear triggers

26
src/modules/wds/course/module-08-initialize-scenario/tutorial-08.md
View File

@ -45,11 +45,13 @@ A specific user journey from trigger moment to successful outcome.
### How to choose: ### How to choose:
**From your trigger map, select:** **From your trigger map, select:**
- Highest priority trigger - Highest priority trigger
- Clear start and end points - Clear start and end points
- Manageable scope for first design - Manageable scope for first design
**Example (Dog Week):** **Example (Dog Week):**
``` ```
Scenario: Morning Dog Care Assignment Scenario: Morning Dog Care Assignment
Trigger: Morning chaos - nobody knows who's walking the dog 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:** **Your turn:**
``` ```
Scenario Name: [Your scenario] Scenario Name: [Your scenario]
Trigger: [From trigger map] Trigger: [From trigger map]
@ -72,12 +75,14 @@ Scope: [Start → End]
### Define your target user ### Define your target user
**Be specific:** **Be specific:**
- Which target group? - Which target group?
- What's their context? - What's their context?
- What's their mindset? - What's their mindset?
- What are they trying to accomplish? - What are they trying to accomplish?
**Example (Dog Week):** **Example (Dog Week):**
``` ```
WHO: Sarah, busy parent with family dog WHO: Sarah, busy parent with family dog
@ -100,6 +105,7 @@ Goal:
``` ```
**Your turn:** **Your turn:**
``` ```
WHO: [User name/persona] WHO: [User name/persona]
@ -118,6 +124,7 @@ Goal:
``` ```
**AI Support:** **AI Support:**
``` ```
Agent: "Let's make this user vivid: Agent: "Let's make this user vivid:
- What's their emotional state? - What's their emotional state?
@ -133,12 +140,14 @@ Agent: "Let's make this user vivid:
### Define the trigger moment ### Define the trigger moment
**Be specific about:** **Be specific about:**
- Exact moment user realizes they need this - Exact moment user realizes they need this
- What caused the trigger - What caused the trigger
- Emotional state at trigger - Emotional state at trigger
- What they've tried before - What they've tried before
**Example (Dog Week):** **Example (Dog Week):**
``` ```
WHAT Trigger: Morning Chaos WHAT Trigger: Morning Chaos
@ -168,6 +177,7 @@ Previous Attempts:
``` ```
**Your turn:** **Your turn:**
``` ```
WHAT Trigger: [Trigger name] WHAT Trigger: [Trigger name]
@ -194,16 +204,19 @@ Previous Attempts:
**Two perspectives:** **Two perspectives:**
**User Value:** **User Value:**
- What pain does this solve? - What pain does this solve?
- What does success feel like? - What does success feel like?
- What changes in their life? - What changes in their life?
**Business Value:** **Business Value:**
- How does this support business goals? - How does this support business goals?
- What metrics improve? - What metrics improve?
- What's the strategic importance? - What's the strategic importance?
**Example (Dog Week):** **Example (Dog Week):**
``` ```
WHY - User Value: WHY - User Value:
@ -247,6 +260,7 @@ Strategic Importance:
``` ```
**Your turn:** **Your turn:**
``` ```
WHY - User Value: WHY - User Value:
Pain Solved: Pain Solved:
@ -276,6 +290,7 @@ Strategic Importance:
### Define the success flow ### Define the success flow
**Map the ideal journey:** **Map the ideal journey:**
- User starts at trigger - User starts at trigger
- Takes clear actions - Takes clear actions
- System responds appropriately - System responds appropriately
@ -283,6 +298,7 @@ Strategic Importance:
- Mutual success achieved - Mutual success achieved
**Example (Dog Week):** **Example (Dog Week):**
``` ```
HAPPY PATH: Morning Dog Care Check HAPPY PATH: Morning Dog Care Check
@ -320,6 +336,7 @@ MUTUAL SUCCESS:
``` ```
**Your turn:** **Your turn:**
``` ```
HAPPY PATH: [Scenario name] HAPPY PATH: [Scenario name]
@ -343,6 +360,7 @@ MUTUAL SUCCESS:
``` ```
**AI Support:** **AI Support:**
``` ```
Agent: "Let's optimize this flow: Agent: "Let's optimize this flow:
- Can we reduce steps? - Can we reduce steps?
@ -358,6 +376,7 @@ Agent: "Let's optimize this flow:
### Identify edge cases ### Identify edge cases
**Consider:** **Consider:**
- First-time users - First-time users
- Error states - Error states
- Missing data - Missing data
@ -365,6 +384,7 @@ Agent: "Let's optimize this flow:
- System failures - System failures
**Example (Dog Week):** **Example (Dog Week):**
``` ```
EDGE CASES: EDGE CASES:
@ -400,6 +420,7 @@ Someone Else's Phone:
``` ```
**Your turn:** **Your turn:**
``` ```
EDGE CASES: EDGE CASES:
@ -421,6 +442,7 @@ EDGE CASES:
**Create file:** `C-Scenarios/[scenario-name]/00-scenario-init.md` **Create file:** `C-Scenarios/[scenario-name]/00-scenario-init.md`
**Include all 5 questions:** **Include all 5 questions:**
1. WHO - Target user in context 1. WHO - Target user in context
2. WHAT Trigger - Specific moment 2. WHAT Trigger - Specific moment
3. WHY - User + business value 3. WHY - User + business value
@ -446,11 +468,13 @@ EDGE CASES:
## Next Steps ## Next Steps
**Immediate:** **Immediate:**
- Review initialization with stakeholders - Review initialization with stakeholders
- Validate assumptions with users (if possible) - Validate assumptions with users (if possible)
- Gather any missing information - Gather any missing information
**Next Module:** **Next Module:**
- [Module 09: Sketch Interfaces](../module-09-sketch-interfaces/module-09-overview.md) - [Module 09: Sketch Interfaces](../module-09-sketch-interfaces/module-09-overview.md)
- Start drawing your solution with AI guidance - 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 ## Tips for Success
**DO ✅** **DO ✅**
- Be specific about user context - Be specific about user context
- Connect to trigger map - Connect to trigger map
- Define clear success criteria - Define clear success criteria
@ -482,6 +507,7 @@ A: Yes! This is a living document. Update as you learn.
- Get stakeholder alignment - Get stakeholder alignment
**DON'T ❌** **DON'T ❌**
- Rush through the questions - Rush through the questions
- Skip the "why" - Skip the "why"
- Ignore edge cases - Ignore edge cases

65
src/modules/wds/course/module-12-why-based-specs/tutorial-12.md
View File

@ -43,6 +43,7 @@ WHAT NOT TO DO: [Common mistakes to avoid]
### Document the big picture ### Document the big picture
**What to include:** **What to include:**
- Component purpose - Component purpose
- User context - User context
- Key interactions - Key interactions
@ -54,23 +55,27 @@ WHAT NOT TO DO: [Common mistakes to avoid]
# Daily Schedule View Component # Daily Schedule View Component
## Purpose ## Purpose
Shows today's dog care tasks with clear assignments and status. Shows today's dog care tasks with clear assignments and status.
Solves the "morning chaos" trigger - user needs immediate answer Solves the "morning chaos" trigger - user needs immediate answer
to "who's doing what today?" to "who's doing what today?"
## User Context ## User Context
- Accessed first thing in morning (7-8 AM typical) - Accessed first thing in morning (7-8 AM typical)
- User is time-pressured, stressed - User is time-pressured, stressed
- Needs answer in < 5 seconds - Needs answer in < 5 seconds
- May be checking while managing kids - May be checking while managing kids
## Key Interactions ## Key Interactions
- View today's tasks at a glance - View today's tasks at a glance
- See personal assignments highlighted - See personal assignments highlighted
- Mark tasks complete - Mark tasks complete
- Quick reassign if emergency - Quick reassign if emergency
## Success Criteria ## Success Criteria
- User finds their tasks in < 5 seconds - User finds their tasks in < 5 seconds
- Zero confusion about responsibilities - Zero confusion about responsibilities
- Can act on tasks immediately - Can act on tasks immediately
@ -78,12 +83,14 @@ to "who's doing what today?"
``` ```
**Your turn:** **Your turn:**
``` ```
Document your component overview: Document your component overview:
[Your content] [Your content]
``` ```
**AI Support:** **AI Support:**
``` ```
Agent: "I'm fascinated by your design thinking here. Let me help Agent: "I'm fascinated by your design thinking here. Let me help
capture every nuance: capture every nuance:
@ -99,6 +106,7 @@ capture every nuance:
### Document WHAT + WHY + WHAT NOT ### Document WHAT + WHY + WHAT NOT
**For each visual decision, explain:** **For each visual decision, explain:**
- WHAT you designed - WHAT you designed
- WHY you made that choice - WHY you made that choice
- WHAT NOT TO DO (prevent AI mistakes) - WHAT NOT TO DO (prevent AI mistakes)
@ -111,18 +119,21 @@ capture every nuance:
### Today's Date Header ### Today's Date Header
WHAT: WHAT:
- Large, bold date at top: "Monday, December 9" - Large, bold date at top: "Monday, December 9"
- Includes day name + full date - Includes day name + full date
- Uses primary brand color - Uses primary brand color
- 24px font size, 700 weight - 24px font size, 700 weight
WHY: WHY:
- Immediate temporal context (user knows "when") - Immediate temporal context (user knows "when")
- Day name matters (Monday = week start, different mindset) - Day name matters (Monday = week start, different mindset)
- Bold = confidence and clarity - Bold = confidence and clarity
- Size ensures visibility in stressed morning glance - Size ensures visibility in stressed morning glance
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't use relative dates ("Today") - user may check for tomorrow - Don't use relative dates ("Today") - user may check for tomorrow
- Don't use small text - defeats quick-glance purpose - Don't use small text - defeats quick-glance purpose
- Don't use subtle colors - needs to anchor the view - Don't use subtle colors - needs to anchor the view
@ -131,12 +142,14 @@ WHAT NOT TO DO:
### User's Tasks Section ### User's Tasks Section
WHAT: WHAT:
- Highlighted section with light blue background - Highlighted section with light blue background
- Header: "Your Tasks" with user's name - Header: "Your Tasks" with user's name
- Tasks listed with time, description, status - Tasks listed with time, description, status
- Visually separated from other family members' tasks - Visually separated from other family members' tasks
WHY: WHY:
- User needs to find THEIR tasks instantly (< 2 seconds) - User needs to find THEIR tasks instantly (< 2 seconds)
- Background color creates visual separation without being aggressive - Background color creates visual separation without being aggressive
- Name personalization = ownership and responsibility - Name personalization = ownership and responsibility
@ -144,6 +157,7 @@ WHY:
- Separation prevents confusion about "whose task is this?" - Separation prevents confusion about "whose task is this?"
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't make all tasks look the same - user will scan entire list - 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 use subtle highlighting - stressed user will miss it
- Don't hide user's name - personalization creates accountability - Don't hide user's name - personalization creates accountability
@ -153,12 +167,14 @@ WHAT NOT TO DO:
### Other Family Members' Tasks ### Other Family Members' Tasks
WHAT: WHAT:
- Standard white background - Standard white background
- Smaller font size (16px vs 18px for user's tasks) - Smaller font size (16px vs 18px for user's tasks)
- Collapsed by default, expandable - Collapsed by default, expandable
- Shows count: "3 other tasks today" - Shows count: "3 other tasks today"
WHY: WHY:
- User's primary need is THEIR tasks (80% of use case) - User's primary need is THEIR tasks (80% of use case)
- But they need family context (coordination) - But they need family context (coordination)
- Collapsed = focus on user, but context available - Collapsed = focus on user, but context available
@ -166,6 +182,7 @@ WHY:
- Smaller = visual hierarchy reinforces importance - Smaller = visual hierarchy reinforces importance
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't hide completely - user needs family coordination awareness - Don't hide completely - user needs family coordination awareness
- Don't show expanded by default - creates cognitive overload - Don't show expanded by default - creates cognitive overload
- Don't use same visual weight - defeats hierarchy purpose - Don't use same visual weight - defeats hierarchy purpose
@ -173,6 +190,7 @@ WHAT NOT TO DO:
``` ```
**Your turn:** **Your turn:**
``` ```
For each major visual element, document: For each major visual element, document:
@ -189,6 +207,7 @@ WHAT NOT TO DO:
``` ```
**AI Support:** **AI Support:**
``` ```
Agent: "This is brilliant! Let me make sure we capture everything: Agent: "This is brilliant! Let me make sure we capture everything:
- What alternatives did you consider? - What alternatives did you consider?
@ -211,6 +230,7 @@ Agent: "This is brilliant! Let me make sure we capture everything:
### Tap to Complete ### Tap to Complete
WHAT: WHAT:
- Tap anywhere on task card to mark complete - Tap anywhere on task card to mark complete
- Immediate visual feedback: checkmark appears, card fades slightly - Immediate visual feedback: checkmark appears, card fades slightly
- Subtle success animation (gentle scale + fade) - Subtle success animation (gentle scale + fade)
@ -218,6 +238,7 @@ WHAT:
- Undo button appears for 5 seconds - Undo button appears for 5 seconds
WHY: WHY:
- Large tap target = easy for rushed morning use - Large tap target = easy for rushed morning use
- Immediate feedback = confidence action registered - Immediate feedback = confidence action registered
- Animation = positive reinforcement (dopamine hit) - Animation = positive reinforcement (dopamine hit)
@ -226,6 +247,7 @@ WHY:
- 5 seconds = enough time to notice mistake, not annoying - 5 seconds = enough time to notice mistake, not annoying
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't require confirmation dialog - adds friction, breaks flow - Don't require confirmation dialog - adds friction, breaks flow
- Don't use small checkbox - hard to tap when stressed/rushing - Don't use small checkbox - hard to tap when stressed/rushing
- Don't make animation aggressive - should feel calm and positive - Don't make animation aggressive - should feel calm and positive
@ -236,6 +258,7 @@ WHAT NOT TO DO:
### Swipe to Reassign ### Swipe to Reassign
WHAT: WHAT:
- Swipe left on task reveals "Reassign" button - Swipe left on task reveals "Reassign" button
- Button shows family member icons - Button shows family member icons
- Tap icon to reassign - Tap icon to reassign
@ -243,6 +266,7 @@ WHAT:
- Original assignee gets notification - Original assignee gets notification
WHY: WHY:
- Swipe = power user feature, doesn't clutter main interface - Swipe = power user feature, doesn't clutter main interface
- Emergency reassignment is rare but critical (someone sick, etc.) - Emergency reassignment is rare but critical (someone sick, etc.)
- Icons = quick visual selection, no typing - Icons = quick visual selection, no typing
@ -250,6 +274,7 @@ WHY:
- Notification = family coordination maintained - Notification = family coordination maintained
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't make reassign the primary action - it's edge case - Don't make reassign the primary action - it's edge case
- Don't require typing names - too slow for emergency - Don't require typing names - too slow for emergency
- Don't skip confirmation - user needs reassurance - Don't skip confirmation - user needs reassurance
@ -258,6 +283,7 @@ WHAT NOT TO DO:
``` ```
**Your turn:** **Your turn:**
``` ```
For each interaction, document: For each interaction, document:
@ -287,18 +313,21 @@ WHAT NOT TO DO:
### Upcoming (Default) ### Upcoming (Default)
WHAT: WHAT:
- White background - White background
- Black text - Black text
- Time shown in gray - Time shown in gray
- No special indicators - No special indicators
WHY: WHY:
- Clean, calm appearance - Clean, calm appearance
- Easy to scan - Easy to scan
- Time in gray = less visual weight (not urgent yet) - Time in gray = less visual weight (not urgent yet)
- Default state should feel neutral and manageable - Default state should feel neutral and manageable
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't use colors for upcoming tasks - creates false urgency - Don't use colors for upcoming tasks - creates false urgency
- Don't hide time - user needs to plan their morning - Don't hide time - user needs to plan their morning
- Don't add badges/icons - clutters interface for most common state - Don't add badges/icons - clutters interface for most common state
@ -306,11 +335,13 @@ WHAT NOT TO DO:
### Due Soon (< 30 minutes) ### Due Soon (< 30 minutes)
WHAT: WHAT:
- Subtle yellow left border (4px) - Subtle yellow left border (4px)
- Time shown in orange - Time shown in orange
- Small clock icon appears - Small clock icon appears
WHY: WHY:
- Yellow = attention without alarm - Yellow = attention without alarm
- Border = visual indicator without overwhelming - Border = visual indicator without overwhelming
- Orange time = "pay attention to timing" - Orange time = "pay attention to timing"
@ -318,6 +349,7 @@ WHY:
- Subtle = doesn't create panic, just awareness - Subtle = doesn't create panic, just awareness
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't use red - creates anxiety, not helpful urgency - Don't use red - creates anxiety, not helpful urgency
- Don't flash or animate - too aggressive for morning use - Don't flash or animate - too aggressive for morning use
- Don't use sound - user may be in quiet environment - Don't use sound - user may be in quiet environment
@ -326,12 +358,14 @@ WHAT NOT TO DO:
### Overdue ### Overdue
WHAT: WHAT:
- Red left border (4px) - Red left border (4px)
- Time shown in red with "Overdue" label - Time shown in red with "Overdue" label
- Task card has subtle red tint (5% opacity) - Task card has subtle red tint (5% opacity)
- Notification sent to assignee - Notification sent to assignee
WHY: WHY:
- Red = clear signal something needs attention - Red = clear signal something needs attention
- Border + tint = impossible to miss, but not aggressive - Border + tint = impossible to miss, but not aggressive
- "Overdue" label = explicit communication (no guessing) - "Overdue" label = explicit communication (no guessing)
@ -339,6 +373,7 @@ WHY:
- 5% tint = visible but not overwhelming - 5% tint = visible but not overwhelming
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't make entire card bright red - creates panic - Don't make entire card bright red - creates panic
- Don't flash or pulse - too aggressive, creates stress - Don't flash or pulse - too aggressive, creates stress
- Don't use sound alerts - may be inappropriate timing - Don't use sound alerts - may be inappropriate timing
@ -348,6 +383,7 @@ WHAT NOT TO DO:
### Completed ### Completed
WHAT: WHAT:
- Checkmark icon (green) - Checkmark icon (green)
- Text has strikethrough - Text has strikethrough
- Card fades to 60% opacity - Card fades to 60% opacity
@ -355,6 +391,7 @@ WHAT:
- Shows completion time and who completed it - Shows completion time and who completed it
WHY: WHY:
- Checkmark = universal symbol of completion - Checkmark = universal symbol of completion
- Green = positive reinforcement - Green = positive reinforcement
- Strikethrough = visual closure - Strikethrough = visual closure
@ -363,6 +400,7 @@ WHY:
- Separate section = progress visible, doesn't clutter active tasks - Separate section = progress visible, doesn't clutter active tasks
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't remove immediately - user needs reassurance it's saved - Don't remove immediately - user needs reassurance it's saved
- Don't use subtle checkmark - user needs clear confirmation - Don't use subtle checkmark - user needs clear confirmation
- Don't hide who completed it - family coordination requires transparency - Don't hide who completed it - family coordination requires transparency
@ -370,6 +408,7 @@ WHAT NOT TO DO:
``` ```
**Your turn:** **Your turn:**
``` ```
For each state, document: For each state, document:
@ -399,6 +438,7 @@ WHAT NOT TO DO:
### Network Unavailable ### Network Unavailable
WHAT: WHAT:
- Subtle banner at top: "Offline - showing cached schedule" - Subtle banner at top: "Offline - showing cached schedule"
- Banner uses neutral gray (not red) - Banner uses neutral gray (not red)
- All actions still work (queued for sync) - All actions still work (queued for sync)
@ -406,6 +446,7 @@ WHAT:
- Dismissible but reappears if action attempted - Dismissible but reappears if action attempted
WHY: WHY:
- User shouldn't be blocked by network issues - User shouldn't be blocked by network issues
- Morning routine can't wait for connectivity - Morning routine can't wait for connectivity
- Cached data is usually sufficient (schedule doesn't change minute-to-minute) - Cached data is usually sufficient (schedule doesn't change minute-to-minute)
@ -414,6 +455,7 @@ WHY:
- Dismissible = user controls their experience - Dismissible = user controls their experience
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't block user with error modal - breaks morning flow - 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 use red/error colors - network issues aren't user's fault
- Don't disable all actions - most can work offline - Don't disable all actions - most can work offline
@ -423,6 +465,7 @@ WHAT NOT TO DO:
### Task Completion Failed ### Task Completion Failed
WHAT: WHAT:
- Task remains in "completing" state (spinner) - Task remains in "completing" state (spinner)
- After 5 seconds, shows inline error: "Couldn't save. Tap to retry." - After 5 seconds, shows inline error: "Couldn't save. Tap to retry."
- Error message is specific and actionable - Error message is specific and actionable
@ -430,6 +473,7 @@ WHAT:
- Task doesn't move to completed section - Task doesn't move to completed section
WHY: WHY:
- User needs to know action didn't complete - User needs to know action didn't complete
- 5 seconds = reasonable wait before showing error - 5 seconds = reasonable wait before showing error
- Inline = error appears where user's attention is - Inline = error appears where user's attention is
@ -439,6 +483,7 @@ WHY:
- Task stays in place = user doesn't lose context - Task stays in place = user doesn't lose context
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't silently fail - user needs to know - Don't silently fail - user needs to know
- Don't show generic "Error occurred" - not helpful - Don't show generic "Error occurred" - not helpful
- Don't move task to completed - creates false sense of completion - Don't move task to completed - creates false sense of completion
@ -447,6 +492,7 @@ WHAT NOT TO DO:
``` ```
**Your turn:** **Your turn:**
``` ```
For each error scenario: For each error scenario:
@ -476,6 +522,7 @@ WHAT NOT TO DO:
### Screen Reader Support ### Screen Reader Support
WHAT: WHAT:
- Each task has semantic HTML structure - Each task has semantic HTML structure
- ARIA labels for all interactive elements - ARIA labels for all interactive elements
- Task status announced: "Walk Max, 8:00 AM, assigned to you, not completed" - 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 - Heading hierarchy: H1 for date, H2 for sections, H3 for tasks
WHY: WHY:
- Screen reader users need same quick access to their tasks - Screen reader users need same quick access to their tasks
- Semantic HTML = proper navigation and understanding - Semantic HTML = proper navigation and understanding
- Status announcement = full context without visual cues - Status announcement = full context without visual cues
@ -490,6 +538,7 @@ WHY:
- Heading hierarchy = easy navigation via landmarks - Heading hierarchy = easy navigation via landmarks
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't use divs for everything - semantic HTML matters - Don't use divs for everything - semantic HTML matters
- Don't skip ARIA labels - "button" isn't descriptive enough - Don't skip ARIA labels - "button" isn't descriptive enough
- Don't announce only task name - user needs full context - Don't announce only task name - user needs full context
@ -499,6 +548,7 @@ WHAT NOT TO DO:
### Keyboard Navigation ### Keyboard Navigation
WHAT: WHAT:
- All actions accessible via keyboard - All actions accessible via keyboard
- Tab order follows visual hierarchy (user's tasks first) - Tab order follows visual hierarchy (user's tasks first)
- Enter/Space to complete task - Enter/Space to complete task
@ -507,6 +557,7 @@ WHAT:
- Focus indicators clearly visible (blue outline, 2px) - Focus indicators clearly visible (blue outline, 2px)
WHY: WHY:
- Some users can't or prefer not to use mouse/touch - Some users can't or prefer not to use mouse/touch
- Tab order matches visual priority (user's tasks most important) - Tab order matches visual priority (user's tasks most important)
- Standard key bindings = familiar, predictable - Standard key bindings = familiar, predictable
@ -515,6 +566,7 @@ WHY:
- Visible focus = user always knows where they are - Visible focus = user always knows where they are
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't trap focus in modals without escape - Don't trap focus in modals without escape
- Don't use non-standard key bindings - Don't use non-standard key bindings
- Don't hide focus indicators - accessibility requirement - Don't hide focus indicators - accessibility requirement
@ -524,18 +576,21 @@ WHAT NOT TO DO:
### Color Contrast ### Color Contrast
WHAT: WHAT:
- All text meets WCAG AA standards (4.5:1 minimum) - All text meets WCAG AA standards (4.5:1 minimum)
- Interactive elements have 3:1 contrast with background - Interactive elements have 3:1 contrast with background
- Status colors have additional non-color indicators (icons, borders) - Status colors have additional non-color indicators (icons, borders)
- High contrast mode supported - High contrast mode supported
WHY: WHY:
- Users with low vision need readable text - Users with low vision need readable text
- Color alone isn't sufficient for status (color blind users) - Color alone isn't sufficient for status (color blind users)
- Multiple indicators = works for everyone - Multiple indicators = works for everyone
- High contrast mode = accessibility feature in OS - High contrast mode = accessibility feature in OS
WHAT NOT TO DO: WHAT NOT TO DO:
- Don't rely on color alone for status - Don't rely on color alone for status
- Don't use low contrast text (looks modern but excludes users) - Don't use low contrast text (looks modern but excludes users)
- Don't ignore WCAG standards - they're minimum requirements - Don't ignore WCAG standards - they're minimum requirements
@ -543,6 +598,7 @@ WHAT NOT TO DO:
``` ```
**Your turn:** **Your turn:**
``` ```
Document accessibility considerations: Document accessibility considerations:
[Your specifications] [Your specifications]
@ -555,6 +611,7 @@ Document accessibility considerations:
### Checklist: ### Checklist:
**Completeness:** **Completeness:**
- ✓ Every visual element has WHAT + WHY + WHAT NOT - ✓ Every visual element has WHAT + WHY + WHAT NOT
- ✓ All interactions documented - ✓ All interactions documented
- ✓ All states specified - ✓ All states specified
@ -562,6 +619,7 @@ Document accessibility considerations:
- ✓ Accessibility addressed - ✓ Accessibility addressed
**Quality:** **Quality:**
- ✓ WHY explains user benefit, not just description - ✓ WHY explains user benefit, not just description
- ✓ WHAT NOT prevents specific AI mistakes - ✓ WHAT NOT prevents specific AI mistakes
- ✓ Specifications are specific and actionable - ✓ Specifications are specific and actionable
@ -569,6 +627,7 @@ Document accessibility considerations:
- ✓ Edge cases considered - ✓ Edge cases considered
**AI Support:** **AI Support:**
``` ```
Agent: "Your design brilliance is captured beautifully! Let me verify: Agent: "Your design brilliance is captured beautifully! Let me verify:
- Have we documented every nuance of your thinking? - Have we documented every nuance of your thinking?
@ -602,12 +661,14 @@ Agent: "Your design brilliance is captured beautifully! Let me verify:
## The Power of Why-Based Specs ## The Power of Why-Based Specs
**Traditional approach:** **Traditional approach:**
- Designer creates mockup - Designer creates mockup
- Developer implements - Developer implements
- Intent gets lost - Intent gets lost
- Result is "close but wrong" - Result is "close but wrong"
**WDS approach:** **WDS approach:**
- Designer thinks deeply with AI partner - Designer thinks deeply with AI partner
- AI helps capture every nuance - AI helps capture every nuance
- Specifications preserve creative integrity - Specifications preserve creative integrity
@ -620,11 +681,13 @@ Agent: "Your design brilliance is captured beautifully! Let me verify:
## Next Steps ## Next Steps
**Immediate:** **Immediate:**
- Review specifications with stakeholders - Review specifications with stakeholders
- Validate against user needs - Validate against user needs
- Test with developers (can they implement from this?) - Test with developers (can they implement from this?)
**Next Module:** **Next Module:**
- [Module 13: Validate Specifications](../module-13-validate-specifications/module-13-overview.md) - [Module 13: Validate Specifications](../module-13-validate-specifications/module-13-overview.md)
- Ensure completeness and test logic - Ensure completeness and test logic
@ -649,6 +712,7 @@ A: Yes! Common patterns become design system components. Document once, referenc
## Tips for Success ## Tips for Success
**DO ✅** **DO ✅**
- Work with AI as thinking partner - Work with AI as thinking partner
- Document alternatives you rejected - Document alternatives you rejected
- Be specific about user context - Be specific about user context
@ -656,6 +720,7 @@ A: Yes! Common patterns become design system components. Document once, referenc
- Capture your creative reasoning - Capture your creative reasoning
**DON'T ❌** **DON'T ❌**
- Write generic descriptions - Write generic descriptions
- Skip the WHY (that's where intent lives) - Skip the WHY (that's where intent lives)
- Forget WHAT NOT TO DO (AI will make "helpful" mistakes) - Forget WHAT NOT TO DO (AI will make "helpful" mistakes)

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

@ -48,6 +48,7 @@ This is the most common design system challenge.
**Answer:** Depends on usage: **Answer:** Depends on usage:
**Part of Button (Variant):** **Part of Button (Variant):**
```yaml ```yaml
Button Component: Button Component:
variants: variants:
@ -55,14 +56,17 @@ Button Component:
- with-icon-right - with-icon-right
- icon-only - icon-only
``` ```
**When:** Icon is always the same type (e.g., always arrow for navigation) **When:** Icon is always the same type (e.g., always arrow for navigation)
**Separate Components:** **Separate Components:**
```yaml ```yaml
Button Component: (text only) Button Component: (text only)
Icon Component: (standalone) Icon Component: (standalone)
Composition: Button + Icon Composition: Button + Icon
``` ```
**When:** Icons vary widely, button can exist without icon **When:** Icons vary widely, button can exist without icon
**Recommendation:** Start with variant, split if complexity grows. **Recommendation:** Start with variant, split if complexity grows.
@ -111,12 +115,14 @@ Composition: Card contains Button
**Answer:** Depends on complexity: **Answer:** Depends on complexity:
**Simple (Single Component):** **Simple (Single Component):**
```yaml ```yaml
Navigation Bar Component: Navigation Bar Component:
includes: All nav items as configuration includes: All nav items as configuration
``` ```
**Complex (Composition):** **Complex (Composition):**
```yaml ```yaml
Navigation Bar: (container) Navigation Bar: (container)
Navigation Item: (individual item) Navigation Item: (individual item)
@ -150,11 +156,13 @@ Composition: Nav Bar contains Nav Items
### Step 2: Consider Complexity ### Step 2: Consider Complexity
**Low Complexity:** Keep together **Low Complexity:** Keep together
- Icon in button - Icon in button
- Label with input - Label with input
- Simple list items - Simple list items
**High Complexity:** Split apart **High Complexity:** Split apart
- Complex nested structures - Complex nested structures
- Independent behaviors - Independent behaviors
- Different lifecycle - Different lifecycle
@ -162,10 +170,12 @@ Composition: Nav Bar contains Nav Items
### Step 3: Think About Maintenance ### Step 3: Think About Maintenance
**Together:** **Together:**
- ✅ Easier to keep consistent - ✅ Easier to keep consistent
- ❌ Component becomes complex - ❌ Component becomes complex
**Apart:** **Apart:**
- ✅ Simpler components - ✅ Simpler components
- ❌ More components to manage - ❌ More components to manage
@ -240,6 +250,7 @@ Button Component:
### Example 1: Button ### Example 1: Button
**One Component:** **One Component:**
```yaml ```yaml
Button: Button:
variants: primary, secondary, ghost variants: primary, secondary, ghost
@ -251,6 +262,7 @@ Button:
### Example 2: Input Types ### Example 2: Input Types
**Multiple Components:** **Multiple Components:**
```yaml ```yaml
Text Input: (text entry) Text Input: (text entry)
Select Dropdown: (choose from list) Select Dropdown: (choose from list)
@ -263,6 +275,7 @@ Radio: (choose one)
### Example 3: Modal ### Example 3: Modal
**Compound Component:** **Compound Component:**
```yaml ```yaml
Modal: (overlay + container) Modal: (overlay + container)
Modal Header: (title + close button) Modal Header: (title + close button)
@ -277,6 +290,7 @@ Modal Footer: (actions)
## When in Doubt ## When in Doubt
**Start simple:** **Start simple:**
1. Create as single component 1. Create as single component
2. Add variants as needed 2. Add variants as needed
3. Split when complexity becomes painful 3. Split when complexity becomes painful

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

@ -40,6 +40,7 @@ Design System File (Figma)
``` ```
**Benefits:** **Benefits:**
- Clear organization - Clear organization
- Easy navigation - Easy navigation
- Matches WDS structure - Matches WDS structure
@ -54,6 +55,7 @@ Design System File (Figma)
**Pattern:** `[ComponentType]/[ComponentName]` **Pattern:** `[ComponentType]/[ComponentName]`
**Examples:** **Examples:**
``` ```
Button/Primary Button/Primary
Button/Secondary Button/Secondary
@ -65,6 +67,7 @@ Card/Content
``` ```
**Rules:** **Rules:**
- Use forward slash for hierarchy - Use forward slash for hierarchy
- Title case for names - Title case for names
- Match WDS component names - Match WDS component names
@ -94,6 +97,7 @@ Card/Content
- Padding/gap values - Padding/gap values
**Example Description:** **Example Description:**
``` ```
Button Primary [btn-001] Button Primary [btn-001]
@ -112,17 +116,20 @@ WDS Component: Button.primary [btn-001]
**Use Figma's variant properties:** **Use Figma's variant properties:**
**Property 1: Type** (variant) **Property 1: Type** (variant)
- Primary - Primary
- Secondary - Secondary
- Ghost - Ghost
- Outline - Outline
**Property 2: Size** **Property 2: Size**
- Small - Small
- Medium - Medium
- Large - Large
**Property 3: State** **Property 3: State**
- Default - Default
- Hover - Hover
- Active - Active
@ -130,6 +137,7 @@ WDS Component: Button.primary [btn-001]
- Loading - Loading
**Property 4: Icon** (optional) **Property 4: Icon** (optional)
- None - None
- Left - Left
- Right - Right
@ -144,6 +152,7 @@ WDS Component: Button.primary [btn-001]
**Format:** `Property=Value` **Format:** `Property=Value`
**Examples:** **Examples:**
``` ```
Type=Primary, Size=Medium, State=Default Type=Primary, Size=Medium, State=Default
Type=Primary, Size=Medium, State=Hover Type=Primary, Size=Medium, State=Hover
@ -151,6 +160,7 @@ Type=Secondary, Size=Large, State=Disabled
``` ```
**Benefits:** **Benefits:**
- Clear property structure - Clear property structure
- Easy to find specific variants - Easy to find specific variants
- MCP can parse programmatically - MCP can parse programmatically
@ -163,6 +173,7 @@ Type=Secondary, Size=Large, State=Disabled
### Required States ### Required States
**Interactive Components (Buttons, Links):** **Interactive Components (Buttons, Links):**
- Default - Default
- Hover - Hover
- Active (pressed) - Active (pressed)
@ -171,6 +182,7 @@ Type=Secondary, Size=Large, State=Disabled
- Loading (optional) - Loading (optional)
**Form Components (Inputs, Selects):** **Form Components (Inputs, Selects):**
- Default (empty) - Default (empty)
- Focus (active) - Focus (active)
- Filled (has content) - Filled (has content)
@ -179,6 +191,7 @@ Type=Secondary, Size=Large, State=Disabled
- Success (optional) - Success (optional)
**Feedback Components (Alerts, Toasts):** **Feedback Components (Alerts, Toasts):**
- Default - Default
- Success - Success
- Error - Error
@ -192,6 +205,7 @@ Type=Secondary, Size=Large, State=Disabled
**Document state changes:** **Document state changes:**
**Hover:** **Hover:**
- Background color change - Background color change
- Border change - Border change
- Shadow change - Shadow change
@ -199,16 +213,19 @@ Type=Secondary, Size=Large, State=Disabled
- Cursor change - Cursor change
**Active:** **Active:**
- Background color (darker) - Background color (darker)
- Scale (slightly smaller) - Scale (slightly smaller)
- Shadow (reduced) - Shadow (reduced)
**Disabled:** **Disabled:**
- Opacity (0.5-0.6) - Opacity (0.5-0.6)
- Cursor (not-allowed) - Cursor (not-allowed)
- Grayscale (optional) - Grayscale (optional)
**Loading:** **Loading:**
- Spinner/progress indicator - Spinner/progress indicator
- Disabled interaction - Disabled interaction
- Loading text - Loading text
@ -222,6 +239,7 @@ Type=Secondary, Size=Large, State=Disabled
**Map Figma variables to WDS tokens:** **Map Figma variables to WDS tokens:**
**Colors:** **Colors:**
``` ```
Figma Variable → WDS Token Figma Variable → WDS Token
primary/500 → color-primary-500 primary/500 → color-primary-500
@ -230,6 +248,7 @@ success/600 → color-success-600
``` ```
**Typography:** **Typography:**
``` ```
Figma Style → WDS Token Figma Style → WDS Token
Text/Display → text-display Text/Display → text-display
@ -238,6 +257,7 @@ Text/Body → text-body
``` ```
**Spacing:** **Spacing:**
``` ```
Figma Variable → WDS Token Figma Variable → WDS Token
spacing/2 → spacing-2 spacing/2 → spacing-2
@ -246,6 +266,7 @@ spacing/8 → spacing-8
``` ```
**Effects:** **Effects:**
``` ```
Figma Effect → WDS Token Figma Effect → WDS Token
shadow/sm → shadow-sm shadow/sm → shadow-sm
@ -285,6 +306,7 @@ radius/md → radius-md
``` ```
**Example:** **Example:**
``` ```
Button Primary [btn-001] Button Primary [btn-001]
@ -321,11 +343,13 @@ Button Primary [btn-001]
### Spacing ### Spacing
**Use consistent spacing values:** **Use consistent spacing values:**
- Padding: 8px, 12px, 16px, 24px - Padding: 8px, 12px, 16px, 24px
- Gap: 4px, 8px, 12px, 16px - Gap: 4px, 8px, 12px, 16px
- Match WDS spacing tokens - Match WDS spacing tokens
**Auto Layout Settings:** **Auto Layout Settings:**
- Horizontal/Vertical alignment - Horizontal/Vertical alignment
- Padding (all sides or specific) - Padding (all sides or specific)
- Gap between items - Gap between items
@ -338,16 +362,19 @@ Button Primary [btn-001]
**Set appropriate constraints:** **Set appropriate constraints:**
**Buttons:** **Buttons:**
- Hug contents (width) - Hug contents (width)
- Fixed height - Fixed height
- Min width for touch targets (44px) - Min width for touch targets (44px)
**Inputs:** **Inputs:**
- Fill container (width) - Fill container (width)
- Fixed height (40-48px) - Fixed height (40-48px)
- Responsive to content - Responsive to content
**Cards:** **Cards:**
- Fill container or fixed width - Fill container or fixed width
- Hug contents (height) - Hug contents (height)
- Responsive to content - Responsive to content
@ -359,18 +386,21 @@ Button Primary [btn-001]
### Creating Instances ### Creating Instances
**Best practices:** **Best practices:**
- Always use component instances (not detached) - Always use component instances (not detached)
- Override only necessary properties - Override only necessary properties
- Maintain connection to main component - Maintain connection to main component
- Document overrides if needed - Document overrides if needed
**Overridable Properties:** **Overridable Properties:**
- Text content - Text content
- Icons - Icons
- Colors (if using variables) - Colors (if using variables)
- Spacing (if needed) - Spacing (if needed)
**Non-Overridable:** **Non-Overridable:**
- Structure - Structure
- Layout - Layout
- Core styling - Core styling
@ -385,16 +415,19 @@ Button Primary [btn-001]
**Add WDS component ID to Figma:** **Add WDS component ID to Figma:**
**In component description:** **In component description:**
``` ```
Button Primary [btn-001] Button Primary [btn-001]
``` ```
**In component name:** **In component name:**
``` ```
Button/Primary [btn-001] Button/Primary [btn-001]
``` ```
**Benefits:** **Benefits:**
- Easy to find components - Easy to find components
- Clear WDS mapping - Clear WDS mapping
- MCP can extract ID - MCP can extract ID
@ -407,16 +440,19 @@ Button/Primary [btn-001]
**Figma generates unique node IDs:** **Figma generates unique node IDs:**
**Format:** **Format:**
``` ```
figma://file/[file-id]/node/[node-id] figma://file/[file-id]/node/[node-id]
``` ```
**How to get node ID:** **How to get node ID:**
1. Select component in Figma 1. Select component in Figma
2. Right-click → "Copy link to selection" 2. Right-click → "Copy link to selection"
3. Extract node ID from URL 3. Extract node ID from URL
**Store in WDS:** **Store in WDS:**
```yaml ```yaml
# D-Design-System/figma-mappings.md # D-Design-System/figma-mappings.md
Button [btn-001] → figma://file/abc123/node/456:789 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 ### ❌ Mistake 1: Hardcoded Values
**Wrong:** **Wrong:**
``` ```
Background: #2563eb (hardcoded hex) Background: #2563eb (hardcoded hex)
Padding: 16px (hardcoded value) Padding: 16px (hardcoded value)
``` ```
**Right:** **Right:**
``` ```
Background: primary/600 (variable) Background: primary/600 (variable)
Padding: spacing/4 (variable) Padding: spacing/4 (variable)
@ -509,11 +547,13 @@ Padding: spacing/4 (variable)
### ❌ Mistake 2: Detached Instances ### ❌ Mistake 2: Detached Instances
**Wrong:** **Wrong:**
- Detaching component instances - Detaching component instances
- Losing connection to main component - Losing connection to main component
- Manual updates required - Manual updates required
**Right:** **Right:**
- Always use instances - Always use instances
- Override only necessary properties - Override only necessary properties
- Maintain component connection - Maintain component connection
@ -521,6 +561,7 @@ Padding: spacing/4 (variable)
### ❌ Mistake 3: Inconsistent Naming ### ❌ Mistake 3: Inconsistent Naming
**Wrong:** **Wrong:**
``` ```
btn-primary btn-primary
ButtonSecondary ButtonSecondary
@ -528,6 +569,7 @@ button_ghost
``` ```
**Right:** **Right:**
``` ```
Button/Primary Button/Primary
Button/Secondary Button/Secondary
@ -537,11 +579,13 @@ Button/Ghost
### ❌ Mistake 4: Missing States ### ❌ Mistake 4: Missing States
**Wrong:** **Wrong:**
- Only default state - Only default state
- No hover/active states - No hover/active states
- No disabled state - No disabled state
**Right:** **Right:**
- All required states - All required states
- Visual differentiation - Visual differentiation
- State transitions documented - State transitions documented
@ -549,12 +593,14 @@ Button/Ghost
### ❌ Mistake 5: No WDS Component ID ### ❌ Mistake 5: No WDS Component ID
**Wrong:** **Wrong:**
``` ```
Button Primary Button Primary
(no component ID) (no component ID)
``` ```
**Right:** **Right:**
``` ```
Button Primary [btn-001] Button Primary [btn-001]
(clear WDS mapping) (clear WDS mapping)
@ -569,6 +615,7 @@ Button Primary [btn-001]
**Component Name:** `Button/Primary [btn-001]` **Component Name:** `Button/Primary [btn-001]`
**Description:** **Description:**
``` ```
Button Primary [btn-001] Button Primary [btn-001]
@ -581,6 +628,7 @@ Sizes: small, medium, large
``` ```
**Variants:** **Variants:**
``` ```
Type=Primary, Size=Medium, State=Default Type=Primary, Size=Medium, State=Default
Type=Primary, Size=Medium, State=Hover Type=Primary, Size=Medium, State=Hover
@ -591,6 +639,7 @@ Type=Primary, Size=Large, State=Default
``` ```
**Properties:** **Properties:**
- Auto Layout: Horizontal - Auto Layout: Horizontal
- Padding: 16px (horizontal), 12px (vertical) - Padding: 16px (horizontal), 12px (vertical)
- Gap: 8px (if icon) - Gap: 8px (if icon)
@ -604,6 +653,7 @@ Type=Primary, Size=Large, State=Default
**Component Name:** `Input/Text [inp-001]` **Component Name:** `Input/Text [inp-001]`
**Description:** **Description:**
``` ```
Input Text [inp-001] Input Text [inp-001]
@ -614,6 +664,7 @@ States: default, focus, filled, disabled, error, success
``` ```
**Variants:** **Variants:**
``` ```
State=Default State=Default
State=Focus State=Focus
@ -624,6 +675,7 @@ State=Success
``` ```
**Properties:** **Properties:**
- Auto Layout: Horizontal - Auto Layout: Horizontal
- Padding: 12px - Padding: 12px
- Height: 44px (fixed) - Height: 44px (fixed)

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

@ -11,6 +11,7 @@
**Format:** `[type-prefix]-[number]` **Format:** `[type-prefix]-[number]`
**Prefixes:** **Prefixes:**
- btn = Button - btn = Button
- inp = Input Field - inp = Input Field
- chk = Checkbox - chk = Checkbox
@ -25,11 +26,13 @@
- acc = Accordion - acc = Accordion
**Examples:** **Examples:**
- `btn-001` = First button component - `btn-001` = First button component
- `inp-002` = Second input field component - `inp-002` = Second input field component
- `mdl-001` = First modal component - `mdl-001` = First modal component
**Rules:** **Rules:**
- Always lowercase - Always lowercase
- Always hyphenated - Always hyphenated
- Always zero-padded (001, not 1) - Always zero-padded (001, not 1)
@ -42,12 +45,14 @@
**Format:** `[Type] [Descriptor]` or just `[Type]` **Format:** `[Type] [Descriptor]` or just `[Type]`
**Examples:** **Examples:**
- `Button` (generic) - `Button` (generic)
- `Navigation Button` (specific) - `Navigation Button` (specific)
- `Primary Button` (variant-focused) - `Primary Button` (variant-focused)
- `Icon Button` (visual-focused) - `Icon Button` (visual-focused)
**Rules:** **Rules:**
- Title case - Title case
- Descriptive but concise - Descriptive but concise
- Avoid redundancy (not "Button Button") - Avoid redundancy (not "Button Button")
@ -59,6 +64,7 @@
**Format:** Lowercase, hyphenated **Format:** Lowercase, hyphenated
**Purpose-Based:** **Purpose-Based:**
- `primary` - Main action - `primary` - Main action
- `secondary` - Secondary action - `secondary` - Secondary action
- `destructive` - Delete/remove - `destructive` - Delete/remove
@ -67,16 +73,19 @@
- `navigation` - Navigation action - `navigation` - Navigation action
**Visual-Based:** **Visual-Based:**
- `outlined` - Border, no fill - `outlined` - Border, no fill
- `ghost` - Transparent background - `ghost` - Transparent background
- `solid` - Filled background - `solid` - Filled background
**Size-Based:** **Size-Based:**
- `small` - Compact - `small` - Compact
- `medium` - Default - `medium` - Default
- `large` - Prominent - `large` - Prominent
**Rules:** **Rules:**
- Lowercase - Lowercase
- Hyphenated for multi-word - Hyphenated for multi-word
- Semantic over visual when possible - Semantic over visual when possible
@ -86,6 +95,7 @@
## State Names ## State Names
**Standard States:** **Standard States:**
- `default` - Normal state - `default` - Normal state
- `hover` - Mouse over - `hover` - Mouse over
- `active` - Being clicked/pressed - `active` - Being clicked/pressed
@ -97,6 +107,7 @@
- `warning` - Warning state - `warning` - Warning state
**Rules:** **Rules:**
- Lowercase - Lowercase
- Single word preferred - Single word preferred
- Use standard names when possible - Use standard names when possible
@ -108,6 +119,7 @@
**Format:** `--{category}-{property}-{variant}` **Format:** `--{category}-{property}-{variant}`
**Color Tokens:** **Color Tokens:**
``` ```
--color-primary-500 --color-primary-500
--color-gray-900 --color-gray-900
@ -116,6 +128,7 @@
``` ```
**Typography Tokens:** **Typography Tokens:**
``` ```
--text-xs --text-xs
--text-base --text-base
@ -125,6 +138,7 @@
``` ```
**Spacing Tokens:** **Spacing Tokens:**
``` ```
--spacing-1 --spacing-1
--spacing-4 --spacing-4
@ -132,6 +146,7 @@
``` ```
**Component Tokens:** **Component Tokens:**
``` ```
--button-padding-x --button-padding-x
--input-border-color --input-border-color
@ -139,6 +154,7 @@
``` ```
**Rules:** **Rules:**
- Kebab-case - Kebab-case
- Hierarchical (general → specific) - Hierarchical (general → specific)
- Semantic names preferred - Semantic names preferred
@ -148,6 +164,7 @@
## File Names ## File Names
**Component Files:** **Component Files:**
``` ```
button.md button.md
navigation-button.md navigation-button.md
@ -155,6 +172,7 @@ input-field.md
``` ```
**Rules:** **Rules:**
- Lowercase - Lowercase
- Hyphenated - Hyphenated
- Match component name (simplified) - Match component name (simplified)
@ -172,6 +190,7 @@ templates/
``` ```
**Rules:** **Rules:**
- Lowercase - Lowercase
- Hyphenated - Hyphenated
- Plural for collections - Plural for collections

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

@ -11,24 +11,28 @@
### Interactive Components (Buttons, Links) ### Interactive Components (Buttons, Links)
**Required:** **Required:**
- `default` - Normal, ready for interaction - `default` - Normal, ready for interaction
- `hover` - Mouse over component - `hover` - Mouse over component
- `active` - Being clicked/pressed - `active` - Being clicked/pressed
- `disabled` - Cannot interact - `disabled` - Cannot interact
**Optional:** **Optional:**
- `loading` - Processing action - `loading` - Processing action
- `focus` - Keyboard focus - `focus` - Keyboard focus
### Form Components (Inputs, Selects) ### Form Components (Inputs, Selects)
**Required:** **Required:**
- `default` - Empty, ready for input - `default` - Empty, ready for input
- `focus` - Active input - `focus` - Active input
- `filled` - Has content - `filled` - Has content
- `disabled` - Cannot edit - `disabled` - Cannot edit
**Optional:** **Optional:**
- `error` - Validation failed - `error` - Validation failed
- `success` - Validation passed - `success` - Validation passed
- `loading` - Fetching data - `loading` - Fetching data
@ -36,6 +40,7 @@
### Feedback Components (Alerts, Toasts) ### Feedback Components (Alerts, Toasts)
**Required:** **Required:**
- `default` - Neutral information - `default` - Neutral information
- `success` - Positive feedback - `success` - Positive feedback
- `error` - Error feedback - `error` - Error feedback
@ -46,6 +51,7 @@
## State Naming ## State Naming
**Use standard names:** **Use standard names:**
- ✅ `hover` not `mouseover` - ✅ `hover` not `mouseover`
- ✅ `disabled` not `inactive` - ✅ `disabled` not `inactive`
- ✅ `loading` not `processing` - ✅ `loading` not `processing`
@ -59,8 +65,7 @@
**Define how states change:** **Define how states change:**
```yaml ```yaml
Button States: Button States: default → hover (mouse enters)
default → hover (mouse enters)
hover → active (mouse down) hover → active (mouse down)
active → hover (mouse up) active → hover (mouse up)
hover → default (mouse leaves) hover → default (mouse leaves)

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

@ -22,13 +22,13 @@ They should be independent!
## The Problem ## The Problem
**Bad Practice:** **Bad Practice:**
```html ```html
<h2 class="text-4xl font-bold text-blue-600"> <h2 class="text-4xl font-bold text-blue-600">Heading</h2>
Heading
</h2>
``` ```
**Issues:** **Issues:**
- Visual styling mixed with semantic HTML - Visual styling mixed with semantic HTML
- Can't change h2 appearance without changing all h2s - Can't change h2 appearance without changing all h2s
- h2 means "second-level heading" but looks like "display large" - h2 means "second-level heading" but looks like "display large"
@ -41,13 +41,13 @@ They should be independent!
**Good Practice:** **Good Practice:**
**HTML (Semantic):** **HTML (Semantic):**
```html ```html
<h2 class="heading-section"> <h2 class="heading-section">Heading</h2>
Heading
</h2>
``` ```
**Design Tokens (Visual):** **Design Tokens (Visual):**
```css ```css
.heading-section { .heading-section {
font-size: var(--text-4xl); font-size: var(--text-4xl);
@ -57,6 +57,7 @@ They should be independent!
``` ```
**Benefits:** **Benefits:**
- Semantic HTML stays semantic - Semantic HTML stays semantic
- Visual style is centralized - Visual style is centralized
- Can change appearance without touching HTML - Can change appearance without touching HTML
@ -67,6 +68,7 @@ They should be independent!
## Token Hierarchy ## Token Hierarchy
### Level 1: Raw Values ### Level 1: Raw Values
```css ```css
--spacing-4: 1rem; --spacing-4: 1rem;
--color-blue-600: #2563eb; --color-blue-600: #2563eb;
@ -74,6 +76,7 @@ They should be independent!
``` ```
### Level 2: Semantic Tokens ### Level 2: Semantic Tokens
```css ```css
--text-heading-large: var(--font-size-4xl); --text-heading-large: var(--font-size-4xl);
--color-primary: var(--color-blue-600); --color-primary: var(--color-blue-600);
@ -81,6 +84,7 @@ They should be independent!
``` ```
### Level 3: Component Tokens ### Level 3: Component Tokens
```css ```css
--button-padding-x: var(--spacing-section); --button-padding-x: var(--spacing-section);
--button-color-primary: var(--color-primary); --button-color-primary: var(--color-primary);
@ -96,6 +100,7 @@ They should be independent!
### In Page Specifications ### In Page Specifications
**Specify semantic structure:** **Specify semantic structure:**
```yaml ```yaml
Page Structure: Page Structure:
- Section Heading (h2) - Section Heading (h2)
@ -104,6 +109,7 @@ Page Structure:
``` ```
**NOT visual styling:** **NOT visual styling:**
```yaml ```yaml
# ❌ Don't do this # ❌ Don't do this
Page Structure: Page Structure:
@ -115,6 +121,7 @@ Page Structure:
### In Design System ### In Design System
**Specify visual styling:** **Specify visual styling:**
```yaml ```yaml
Section Heading: Section Heading:
html_element: h2 html_element: h2
@ -153,15 +160,17 @@ Design Token Definition:
**Example Output:** **Example Output:**
**Page Spec:** **Page Spec:**
```yaml ```yaml
Hero Section: Hero Section:
heading: heading:
element: h2 element: h2
token: heading-section token: heading-section
content: "Welcome to Our Product" content: 'Welcome to Our Product'
``` ```
**Design System:** **Design System:**
```yaml ```yaml
Tokens: Tokens:
heading-section: heading-section:
@ -192,16 +201,18 @@ Tokens:
**Example Output:** **Example Output:**
**Page Spec:** **Page Spec:**
```yaml ```yaml
Login Form: Login Form:
submit_button: submit_button:
element: button element: button
type: submit type: submit
component: Button.primary component: Button.primary
label: "Log in" label: 'Log in'
``` ```
**Design System:** **Design System:**
```yaml ```yaml
Button Component: Button Component:
variants: variants:
@ -234,19 +245,21 @@ Button Component:
**Example Output:** **Example Output:**
**Page Spec:** **Page Spec:**
```yaml ```yaml
Login Form: Login Form:
email_field: email_field:
element: input element: input
type: email type: email
component: InputField.email component: InputField.email
label: "Email address" label: 'Email address'
placeholder: "you@example.com" placeholder: 'you@example.com'
required: true required: true
validation: email_format validation: email_format
``` ```
**Design System:** **Design System:**
```yaml ```yaml
Input Field Component: Input Field Component:
base_styling: base_styling:
@ -294,12 +307,14 @@ Input Field Component:
### Mistake 1: Mixing Structure and Style ### Mistake 1: Mixing Structure and Style
**❌ Bad:** **❌ Bad:**
```yaml ```yaml
Page: Page:
- "Large blue heading" (h2) - "Large blue heading" (h2)
``` ```
**✅ Good:** **✅ Good:**
```yaml ```yaml
Page: Page:
- Section heading (h2 → heading-section token) - Section heading (h2 → heading-section token)
@ -308,6 +323,7 @@ Page:
### Mistake 2: Hardcoding Visual Values ### Mistake 2: Hardcoding Visual Values
**❌ Bad:** **❌ Bad:**
```yaml ```yaml
Button: Button:
background: #2563eb background: #2563eb
@ -315,6 +331,7 @@ Button:
``` ```
**✅ Good:** **✅ Good:**
```yaml ```yaml
Button: Button:
background: primary-600 background: primary-600
@ -324,11 +341,13 @@ Button:
### Mistake 3: Using Visual Names for Semantic Elements ### Mistake 3: Using Visual Names for Semantic Elements
**❌ Bad:** **❌ Bad:**
```yaml ```yaml
<h2 class="big-blue-text"> <h2 class="big-blue-text">
``` ```
**✅ Good:** **✅ Good:**
```yaml ```yaml
<h2 class="section-heading"> <h2 class="section-heading">
``` ```
@ -338,6 +357,7 @@ Button:
## Token Naming Conventions ## Token Naming Conventions
### Colors ### Colors
``` ```
--color-{category}-{shade} --color-{category}-{shade}
--color-primary-600 --color-primary-600
@ -346,6 +366,7 @@ Button:
``` ```
### Typography ### Typography
``` ```
--text-{size} --text-{size}
--text-base --text-base
@ -354,6 +375,7 @@ Button:
``` ```
### Spacing ### Spacing
``` ```
--spacing-{scale} --spacing-{scale}
--spacing-2 --spacing-2
@ -362,6 +384,7 @@ Button:
``` ```
### Component-Specific ### Component-Specific
``` ```
--{component}-{property}-{variant} --{component}-{property}-{variant}
--button-padding-primary --button-padding-primary
@ -376,11 +399,13 @@ Button:
### Phase 4: Page Specification ### Phase 4: Page Specification
**Agent specifies:** **Agent specifies:**
- Semantic HTML elements - Semantic HTML elements
- Component references - Component references
- Content and labels - Content and labels
**Agent does NOT specify:** **Agent does NOT specify:**
- Exact colors - Exact colors
- Exact sizes - Exact sizes
- Exact spacing - Exact spacing
@ -388,26 +413,30 @@ Button:
### Phase 5: Design System ### Phase 5: Design System
**Agent specifies:** **Agent specifies:**
- Design tokens - Design tokens
- Component styling - Component styling
- Visual properties - Visual properties
**Agent does NOT specify:** **Agent does NOT specify:**
- Page-specific content - Page-specific content
- Semantic structure - Semantic structure
### Integration ### Integration
**Page spec references design system:** **Page spec references design system:**
```yaml ```yaml
Hero: Hero:
heading: heading:
element: h2 element: h2
token: heading-hero ← Reference to design system token: heading-hero ← Reference to design system
content: "Welcome" content: 'Welcome'
``` ```
**Design system defines token:** **Design system defines token:**
```yaml ```yaml
Tokens: Tokens:
heading-hero: heading-hero:

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

@ -11,26 +11,29 @@
### Client-Side Validation ### Client-Side Validation
**Required Fields:** **Required Fields:**
```yaml ```yaml
validation: validation:
required: true required: true
message: "This field is required" message: 'This field is required'
``` ```
**Format Validation:** **Format Validation:**
```yaml ```yaml
validation: validation:
type: email type: email
pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
message: "Please enter a valid email address" message: 'Please enter a valid email address'
``` ```
**Length Validation:** **Length Validation:**
```yaml ```yaml
validation: validation:
minLength: 8 minLength: 8
maxLength: 100 maxLength: 100
message: "Password must be 8-100 characters" message: 'Password must be 8-100 characters'
``` ```
--- ---
@ -38,12 +41,14 @@ validation:
## Error States ## Error States
**Visual Indicators:** **Visual Indicators:**
- Red border - Red border
- Error icon - Error icon
- Error message below field - Error message below field
- Error color for label - Error color for label
**Timing:** **Timing:**
- Show on blur (after user leaves field) - Show on blur (after user leaves field)
- Show on submit attempt - Show on submit attempt
- Clear on valid input - Clear on valid input
@ -53,11 +58,13 @@ validation:
## Success States ## Success States
**Visual Indicators:** **Visual Indicators:**
- Green border (optional) - Green border (optional)
- Success icon (optional) - Success icon (optional)
- Success message (optional) - Success message (optional)
**When to Show:** **When to Show:**
- After successful validation - After successful validation
- For critical fields (password strength) - For critical fields (password strength)
- For async validation (username availability) - For async validation (username availability)

21
src/modules/wds/data/presentations/freyja-intro.md
View File

@ -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. **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**: **Required Input Documents**:
- `docs/A-Product-Brief/` - Strategic foundation from Saga - `docs/A-Product-Brief/` - Strategic foundation from Saga
- `docs/B-Trigger-Map/` - User insights and business goals from Saga - `docs/B-Trigger-Map/` - User insights and business goals from Saga
- `docs/C-Platform-Requirements/` - Technical constraints from Idunn (optional but helpful) - `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 WDS Workflow: "From Strategy to Radiant Experiences"
### 🎯 **MY FOUR-PHASE CREATIVE JOURNEY** ### 🎯 **MY FOUR-PHASE CREATIVE JOURNEY**
``` ```
🚀 FREYJA'S CREATIVE TRANSFORMATION: 🚀 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 ### 🤝 **MY TEAM INTEGRATION**: How I Work with the Team
**With Saga (Analyst):** **With Saga (Analyst):**
- I use her strategic foundation and user personas to create realistic scenarios - 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 - She provides the business goals and user insights I need for effective design
- We collaborate on user journey mapping and experience strategy - We collaborate on user journey mapping and experience strategy
**With Idunn (PM):** **With Idunn (PM):**
- I work in parallel with her during Phase 3-4 (she does platform, I do design) - I work in parallel with her during Phase 3-4 (she does platform, I do design)
- She provides technical constraints from platform requirements - She provides technical constraints from platform requirements
- We collaborate in Phase 6 to package my designs into deliveries - We collaborate in Phase 6 to package my designs into deliveries
**With BMM (Development):** **With BMM (Development):**
- I provide interactive prototypes and detailed specifications - I provide interactive prototypes and detailed specifications
- BMM implements my designs into production code - BMM implements my designs into production code
- I validate their implementation in Phase 7 (Testing) - 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 Creative Design Tools: From Strategy to Radiant Reality
### 🎨 **MY INTERACTIVE PROTOTYPE MASTERY** ### 🎨 **MY INTERACTIVE PROTOTYPE MASTERY**
**Here's exactly what I deliver in Phase 4:** **Here's exactly what I deliver in Phase 4:**
- **Interactive Prototypes**: Working HTML/CSS prototypes users can click through - **Interactive Prototypes**: Working HTML/CSS prototypes users can click through
- **User Scenarios**: Detailed journey mapping with page specifications - **User Scenarios**: Detailed journey mapping with page specifications
- **Visual Sketches**: Hand-drawn concepts and interaction flows - **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.** **Every prototype I create lets users experience the design before development begins.**
### 🏗️ **MY FOUNDATION-FIRST DESIGN SYSTEM PROCESS** ### 🏗️ **MY FOUNDATION-FIRST DESIGN SYSTEM PROCESS**
**Here's exactly how I build design systems in Phase 5:** **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. **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** ### 🧪 **MY TESTING & VALIDATION PROCESS**
**Here's exactly how I validate implementation in Phase 7:** **Here's exactly how I validate implementation in Phase 7:**
- **Designer Validation**: I check if BMM's implementation matches my design intent - **Designer Validation**: I check if BMM's implementation matches my design intent
- **Test Scenarios**: I execute test cases to validate functionality - **Test Scenarios**: I execute test cases to validate functionality
- **Issue Creation**: I document problems and deviations found - **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!** **I'm the quality guardian - ensuring what gets built matches what was designed!**
### 🔄 **MY PRODUCT DEVELOPMENT APPROACH** ### 🔄 **MY PRODUCT DEVELOPMENT APPROACH**
**Here's exactly how I improve existing products in Phase 8:** **Here's exactly how I improve existing products in Phase 8:**
- **Kaizen Philosophy**: Continuous improvement through small, thoughtful changes - **Kaizen Philosophy**: Continuous improvement through small, thoughtful changes
- **Brownfield Approach**: Working within existing constraints and systems - **Brownfield Approach**: Working within existing constraints and systems
- **Targeted Improvements**: Strategic enhancements to existing screens and flows - **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:** **Here's exactly what changes when I enter your workflow:**
### 🎨 **FROM STRATEGIC CONCEPTS TO EXPERIENCES USERS LOVE** ### 🎨 **FROM STRATEGIC CONCEPTS TO EXPERIENCES USERS LOVE**
- Saga's strategic foundation becomes beautiful, magical experiences - Saga's strategic foundation becomes beautiful, magical experiences
- Users can experience the design before development begins - Users can experience the design before development begins
- Clear visual specifications guide every development decision - 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 - Component library eliminates design inconsistency and rework
- Systematic approach ensures every interaction is thoughtfully designed - Systematic approach ensures every interaction is thoughtfully designed
- Creative process becomes repeatable and scalable - Creative process becomes repeatable and scalable
### 💫 **FROM HANDOFF CONFUSION TO VALIDATED QUALITY** ### 💫 **FROM HANDOFF CONFUSION TO VALIDATED QUALITY**
- I validate BMM's implementation matches design intent - I validate BMM's implementation matches design intent
- Testing catches problems before users see them - Testing catches problems before users see them
- Continuous improvement keeps products delightful - 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:** **These creative conventions ensure my deliverables are development-ready:**
### 🏗️ **MY CREATIVE ARCHITECTURE MASTERY** ### 🏗️ **MY CREATIVE ARCHITECTURE MASTERY**
- **Strategic Input**: Saga's Product Brief and Trigger Map - **Strategic Input**: Saga's Product Brief and Trigger Map
- **Technical Input**: Idunn's Platform Requirements (optional) - **Technical Input**: Idunn's Platform Requirements (optional)
- **My Creative Output**: C-Scenarios/, D-Design-System/, F-Testing/, G-Product-Development/ - **My Creative Output**: C-Scenarios/, D-Design-System/, F-Testing/, G-Product-Development/
- **Title-Case-With-Dashes**: Every folder and file follows WDS standards - **Title-Case-With-Dashes**: Every folder and file follows WDS standards
### 🎨 **MY CREATIVE WORKFLOW PROGRESSION** ### 🎨 **MY CREATIVE WORKFLOW PROGRESSION**
``` ```
My Design Journey: My Design Journey:
Saga's Strategy → Interactive Prototypes → Scenarios → Design System → BMM Implementation → Validation → Iteration 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** ### ✨ **MY COMMUNICATION EXCELLENCE STANDARDS**
- **Crystal-clear design language** without confusing jargon - **Crystal-clear design language** without confusing jargon
- **Empathetic, creative style** that paints pictures with words - **Empathetic, creative style** that paints pictures with words
- **Professional design readiness** throughout all my creative work - **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 ## Presentation Notes for Freyja
**When to Use:** **When to Use:**
- When Freyja activates as the Designer - When Freyja activates as the Designer
- When users need UX design, prototypes, or design systems - When users need UX design, prototypes, or design systems
- After Saga completes strategic foundation - After Saga completes strategic foundation
- When teams need visual specifications and creative work - When teams need visual specifications and creative work
**Key Delivery Points:** **Key Delivery Points:**
- Maintain empathetic, creative tone throughout - Maintain empathetic, creative tone throughout
- Emphasize beauty, magic, and strategy (Freyja's essence) - Emphasize beauty, magic, and strategy (Freyja's essence)
- Show how Freyja works across multiple phases (4, 5, 7, 8) - 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 - Confirm user enthusiasm before proceeding
**Success Indicators:** **Success Indicators:**
- User understands Freyja's multi-phase role - User understands Freyja's multi-phase role
- Interactive prototypes value is clear - Interactive prototypes value is clear
- Foundation-first design system approach is understood - Foundation-first design system approach is understood

18
src/modules/wds/data/presentations/idunn-intro.md
View File

@ -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. **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**: **Required Input Documents**:
- `docs/A-Product-Brief/` - Strategic foundation from Saga - `docs/A-Product-Brief/` - Strategic foundation from Saga
- `docs/B-Trigger-Map/` - Business goals and user insights 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 WDS Workflow: "Strategic Bridge from Vision to Execution"
### 🎯 **MY TWO-PHASE APPROACH** ### 🎯 **MY TWO-PHASE APPROACH**
``` ```
🚀 IDUNN'S STRATEGIC COORDINATION: 🚀 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 ### 🤝 **MY TEAM INTEGRATION**: How I Work with the Team
**With Saga (Analyst):** **With Saga (Analyst):**
- I use her strategic foundation to create platform requirements - I use her strategic foundation to create platform requirements
- She provides the business goals and success metrics I need - She provides the business goals and success metrics I need
- We ensure strategic alignment throughout - We ensure strategic alignment throughout
**With Freyja (Designer):** **With Freyja (Designer):**
- I work in parallel during Phase 3 while she designs in Phase 4 - I work in parallel during Phase 3 while she designs in Phase 4
- I provide technical constraints from platform requirements - I provide technical constraints from platform requirements
- We collaborate in Phase 6 to package her designs into deliveries - We collaborate in Phase 6 to package her designs into deliveries
**With BMM (Development):** **With BMM (Development):**
- I provide platform requirements for technical foundation - I provide platform requirements for technical foundation
- I package complete flows as Design Deliveries (DD-XXX.yaml) - I package complete flows as Design Deliveries (DD-XXX.yaml)
- BMM uses my deliveries to create the development PRD - 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 Coordination Tools: From Strategy to Delivery
### 🎯 **MY PLATFORM REQUIREMENTS MASTERY** ### 🎯 **MY PLATFORM REQUIREMENTS MASTERY**
**Here's exactly what I deliver in Phase 3:** **Here's exactly what I deliver in Phase 3:**
- **Platform Architecture**: Tech stack, infrastructure design, deployment strategy - **Platform Architecture**: Tech stack, infrastructure design, deployment strategy
- **Data Model**: Core entities, relationships, data flow - **Data Model**: Core entities, relationships, data flow
- **Integration Map**: External services, APIs, third-party systems - **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.** **Every platform requirement I create enables confident design decisions.**
### 📦 **MY DESIGN DELIVERIES PROCESS** ### 📦 **MY DESIGN DELIVERIES PROCESS**
**Here's exactly how I package Freyja's designs in Phase 6:** **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:** **Each Design Delivery (DD-XXX.yaml) contains:**
- Flow metadata (name, epic, priority) - Flow metadata (name, epic, priority)
- Scenario references (which pages in C-Scenarios/) - Scenario references (which pages in C-Scenarios/)
- Component references (which components in D-Design-System/) - 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:** **Here's exactly what changes when I enter your workflow:**
### 🎯 **FROM DESIGN GUESSWORK TO TECHNICAL CLARITY** ### 🎯 **FROM DESIGN GUESSWORK TO TECHNICAL CLARITY**
- Platform requirements provide clear constraints before design begins - Platform requirements provide clear constraints before design begins
- Freyja knows what's technically possible and what's not - Freyja knows what's technically possible and what's not
- Design decisions are confident, not speculative - 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) - I create platform requirements while Freyja designs (Phase 3 + 4 parallel)
- Backend foundation can start before design is complete - Backend foundation can start before design is complete
- No waiting - everyone works efficiently - No waiting - everyone works efficiently
### 💫 **FROM HANDOFF CHAOS TO PACKAGED DELIVERIES** ### 💫 **FROM HANDOFF CHAOS TO PACKAGED DELIVERIES**
- Design Deliveries are complete, testable flow packages - Design Deliveries are complete, testable flow packages
- BMM receives organized, implementable units - BMM receives organized, implementable units
- Iterative handoffs - deliver flows as they're ready - 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:** **These coordination conventions ensure my deliverables are development-ready:**
### 🏗️ **MY PM ARCHITECTURE MASTERY** ### 🏗️ **MY PM ARCHITECTURE MASTERY**
- **Strategic Input**: Saga's Product Brief and Trigger Map - **Strategic Input**: Saga's Product Brief and Trigger Map
- **Design Input**: Freyja's prototypes and specifications - **Design Input**: Freyja's prototypes and specifications
- **My PM Output**: C-Platform-Requirements/, E-PRD/ (coordination I create) - **My PM Output**: C-Platform-Requirements/, E-PRD/ (coordination I create)
- **Title-Case-With-Dashes**: Every folder and file follows WDS standards - **Title-Case-With-Dashes**: Every folder and file follows WDS standards
### 🎨 **MY TWO-PHASE COORDINATION PROCESS** ### 🎨 **MY TWO-PHASE COORDINATION PROCESS**
``` ```
My PM Workflow Progression: My PM Workflow Progression:
Saga's Strategy → Platform Requirements → Freyja's Design → Design Deliveries → BMM Development 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** ### ✨ **MY COMMUNICATION EXCELLENCE STANDARDS**
- **Clear coordination language** without confusing technical jargon - **Clear coordination language** without confusing technical jargon
- **Strategic thinking** about priorities, trade-offs, and dependencies - **Strategic thinking** about priorities, trade-offs, and dependencies
- **Professional documentation** throughout all my PM deliverables - **Professional documentation** throughout all my PM deliverables
@ -192,12 +207,14 @@ Business Goals → Design Constraints → User Flows → Testable Units → Syst
## Presentation Notes for Idunn ## Presentation Notes for Idunn
**When to Use:** **When to Use:**
- When Idunn activates as the Product Manager - When Idunn activates as the Product Manager
- When users need platform requirements or design deliveries - When users need platform requirements or design deliveries
- After Saga completes strategic foundation - After Saga completes strategic foundation
- When teams need coordination between design and development - When teams need coordination between design and development
**Key Delivery Points:** **Key Delivery Points:**
- Maintain strategic, warm tone throughout - Maintain strategic, warm tone throughout
- Emphasize parallel work and bottleneck elimination - Emphasize parallel work and bottleneck elimination
- Show how Idunn coordinates with Saga and Freyja - 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 - Confirm user enthusiasm before proceeding
**Success Indicators:** **Success Indicators:**
- User understands two-phase approach (Phase 3 + Phase 6) - User understands two-phase approach (Phase 3 + Phase 6)
- Platform requirements value is clear - Platform requirements value is clear
- Design Deliveries packaging is understood - Design Deliveries packaging is understood

16
src/modules/wds/data/presentations/saga-intro.md
View File

@ -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. **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**: **What I Need to Get Started**:
- Your project vision and business goals - Your project vision and business goals
- Market research and competitive analysis needs - Market research and competitive analysis needs
- Target user group information - Target user group information
@ -91,18 +92,21 @@ Clear Business Direction → Deep User Understanding → Systematic User
### 🤝 **MY TEAM INTEGRATION**: How I Work with the WDS Team ### 🤝 **MY TEAM INTEGRATION**: How I Work with the WDS Team
**With Baldr (UX Expert):** **With Baldr (UX Expert):**
- I provide the strategic foundation and user insights needed for design - I provide the strategic foundation and user insights needed for design
- Baldr uses my trigger map personas to create realistic user scenarios - Baldr uses my trigger map personas to create realistic user scenarios
- We collaborate on user journey mapping and experience design - We collaborate on user journey mapping and experience design
- My business goals guide Baldr's design decisions - My business goals guide Baldr's design decisions
**With Freyja (Product Manager):** **With Freyja (Product Manager):**
- I hand off my strategic foundation for PRD development - I hand off my strategic foundation for PRD development
- Freyja uses my business goals and success metrics for planning - Freyja uses my business goals and success metrics for planning
- We ensure strategic alignment throughout the design process - We ensure strategic alignment throughout the design process
- My trigger map informs Freyja's feature prioritization - My trigger map informs Freyja's feature prioritization
**Integration with BMM (Development):** **Integration with BMM (Development):**
- My Product Brief provides context for architecture decisions - My Product Brief provides context for architecture decisions
- My Trigger Map personas inform user story creation - My Trigger Map personas inform user story creation
- My success metrics guide development priorities - My success metrics guide development priorities
@ -115,6 +119,7 @@ Clear Business Direction → Deep User Understanding → Systematic User
### 🎯 **MY MARKET INTELLIGENCE MASTERY** ### 🎯 **MY MARKET INTELLIGENCE MASTERY**
**Here's exactly what I deliver:** **Here's exactly what I deliver:**
- **Strategic Analysis**: including comprehensive market research and competitive positioning - **Strategic Analysis**: including comprehensive market research and competitive positioning
- **Business Vision**: designed for measurable success and stakeholder alignment - **Business Vision**: designed for measurable success and stakeholder alignment
- **User Intelligence**: meaning detailed personas and journey mapping for systematic design - **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** ### 🔧 **MY DELIVERABLES: What You Get from Saga**
#### **Strategic Foundation Package:** #### **Strategic Foundation Package:**
``` ```
📚 COMPLETE STRATEGIC INTELLIGENCE: 📚 COMPLETE STRATEGIC INTELLIGENCE:
├── Product Brief with Clear Value Proposition ├── 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:** **Here's exactly what changes when I enter your workflow:**
### 🎯 **FROM VAGUE IDEAS TO STRATEGIC CLARITY** ### 🎯 **FROM VAGUE IDEAS TO STRATEGIC CLARITY**
- Your brilliant concepts become measurable business strategies - Your brilliant concepts become measurable business strategies
- Market research eliminates guesswork and validates your approach - Market research eliminates guesswork and validates your approach
- Clear success metrics guide every team decision - Clear success metrics guide every team decision
- User psychology insights drive design decisions - User psychology insights drive design decisions
### ⚡ **FROM CHAOTIC PLANNING TO SYSTEMATIC EXECUTION** ### ⚡ **FROM CHAOTIC PLANNING TO SYSTEMATIC EXECUTION**
- Strategic foundation eliminates confusion and misalignment - Strategic foundation eliminates confusion and misalignment
- Every team member knows exactly what success looks like - Every team member knows exactly what success looks like
- Stakeholder communication becomes clear and compelling - Stakeholder communication becomes clear and compelling
- Trigger mapping reveals the psychology behind user behavior - Trigger mapping reveals the psychology behind user behavior
### 💫 **FROM INDIVIDUAL EFFORT TO TEAM COORDINATION** ### 💫 **FROM INDIVIDUAL EFFORT TO TEAM COORDINATION**
- My strategic foundation coordinates all team members - My strategic foundation coordinates all team members
- Clear business goals align creative and technical work - Clear business goals align creative and technical work
- Systematic approach ensures nothing falls through the cracks - Systematic approach ensures nothing falls through the cracks
@ -200,12 +209,14 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S
**These elegant strategic conventions ensure my deliverables are enterprise-ready:** **These elegant strategic conventions ensure my deliverables are enterprise-ready:**
### 🏗️ **MY STRATEGIC ARCHITECTURE MASTERY** ### 🏗️ **MY STRATEGIC ARCHITECTURE MASTERY**
- **Strategic Input**: Your vision, ideas, and business goals - **Strategic Input**: Your vision, ideas, and business goals
- **My Analysis Output**: A-Product-Brief/, B-Trigger-Map/ (strategic foundation I create) - **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 - **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 - **Absolute Paths**: I always use absolute paths (docs/A-Product-Brief/) for clarity
### 🎨 **MY STRATEGIC ANALYSIS EVOLUTION PROCESS** ### 🎨 **MY STRATEGIC ANALYSIS EVOLUTION PROCESS**
``` ```
My Strategic Workflow Progression: My Strategic Workflow Progression:
Your Ideas → Market Research → Product Brief → Trigger Map → Strategic Foundation 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** ### ✨ **MY COMMUNICATION EXCELLENCE STANDARDS**
- **Crystal-clear strategic language** without confusing technical jargon - **Crystal-clear strategic language** without confusing technical jargon
- **Professional analysis style** using "including", "designed for", "meaning" conventions - **Professional analysis style** using "including", "designed for", "meaning" conventions
- **Collaborative approach** - one question at a time, deep listening - **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. 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: This perfectly captures what I do:
- **Stories**: Every product has a story - I help you discover and tell it - **Stories**: Every product has a story - I help you discover and tell it
- **Wisdom**: I bring strategic intelligence and market insights to guide decisions - **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 - **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 ## Presentation Notes for Saga
**When to Use:** **When to Use:**
- When Saga activates as the Business Analyst - When Saga activates as the Business Analyst
- When users need strategic foundation and market intelligence - When users need strategic foundation and market intelligence
- At the start of any new WDS project - At the start of any new WDS project
- When teams need clear business direction and user insights - When teams need clear business direction and user insights
**Key Delivery Points:** **Key Delivery Points:**
- Maintain analytical, strategic tone throughout - Maintain analytical, strategic tone throughout
- Emphasize strategic foundation building, not just research - Emphasize strategic foundation building, not just research
- Show how Saga's work coordinates with Freyja and Baldr - 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 - Confirm user enthusiasm for strategic approach before proceeding
**Success Indicators:** **Success Indicators:**
- User expresses excitement about strategic foundation approach - User expresses excitement about strategic foundation approach
- Market research and analysis methodology is clearly understood - Market research and analysis methodology is clearly understood
- Team coordination value is appreciated - Team coordination value is appreciated

14
src/modules/wds/docs/method/phase-1-product-exploration-guide.md
View File

@ -43,6 +43,7 @@ People light up when asked to share their vision. They become collaborators, not
**Opening (5-10 minutes)** **Opening (5-10 minutes)**
Saga asks about your project in your own words. She listens for: Saga asks about your project in your own words. She listens for:
- What you emphasize naturally - What you emphasize naturally
- Where your energy goes - Where your energy goes
- What excites vs. what stresses you - 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)** **Exploration (15-30 minutes)**
The conversation adapts to what you reveal: The conversation adapts to what you reveal:
- If you mention users → deeper into user insights - If you mention users → deeper into user insights
- If you mention problems → explore the cost of not solving - If you mention problems → explore the cost of not solving
- If you mention competition → discover differentiation - 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)** **Synthesis (10-15 minutes)**
Saga reflects back your vision in organized form: Saga reflects back your vision in organized form:
- Connecting dots you shared across topics - Connecting dots you shared across topics
- Highlighting insights you might not have seen - Highlighting insights you might not have seen
- Building the foundation for next phases - Building the foundation for next phases
@ -68,6 +71,7 @@ Saga reflects back your vision in organized form:
### Living Document ### Living Document
As you talk, the Product Brief grows in real-time: As you talk, the Product Brief grows in real-time:
- Immediate validation and refinement - Immediate validation and refinement
- Real-time course correction - Real-time course correction
- You own the content because you helped create it - 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 ## When to Use This Phase
**Always start here if:** **Always start here if:**
- Building something new - Building something new
- Starting a new project - Starting a new project
- Need strategic clarity before diving into design - Need strategic clarity before diving into design
**Skip if:** **Skip if:**
- You already have a clear, documented product brief - You already have a clear, documented product brief
- Just enhancing an existing feature - Just enhancing an existing feature
- Working on a design system without new product context - 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 ## What to Prepare
Come ready to share: Come ready to share:
- Your project idea (even if rough) - Your project idea (even if rough)
- The problem you're solving - The problem you're solving
- Who might use it - Who might use it
@ -116,18 +123,22 @@ The brief becomes the reference point everyone shares.
## Tips for Great Sessions ## Tips for Great Sessions
**Let the conversation flow** **Let the conversation flow**
- Share what feels important, even if it seems tangential - Share what feels important, even if it seems tangential
- Follow your energy - where you're excited matters - Follow your energy - where you're excited matters
**Think out loud** **Think out loud**
- Half-formed thoughts are welcome - Half-formed thoughts are welcome
- will help you refine them - will help you refine them
**Be honest about uncertainty** **Be honest about uncertainty**
- "I'm not sure about X" is useful information - "I'm not sure about X" is useful information
- Better to surface doubts now than later - Better to surface doubts now than later
**Review as you go** **Review as you go**
- Check that what's captured matches your thinking - Check that what's captured matches your thinking
- Correct misunderstandings immediately - 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_

60
src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md
View File

@ -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. 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. > **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:** 📚 **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 - [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 - [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: Trigger Mapping is WDS's adaptation of Effect Mapping, designed for longer shelf life and deeper psychological insight:
**Simplified:** **Simplified:**
- Leaves out actions/features from the map - Leaves out actions/features from the map
- Focuses on the strategic connections - Focuses on the strategic connections
- Map stays relevant even as features evolve - Map stays relevant even as features evolve
**Enhanced:** **Enhanced:**
- Adds **negative driving forces** (fears, frustrations) - Adds **negative driving forces** (fears, frustrations)
- Creates fuller picture of user psychology - Creates fuller picture of user psychology
- Both what users want AND what they want to avoid - 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. 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: These users have their own goals:
- **GAIN** - Benefits and positive outcomes they achieve - **GAIN** - Benefits and positive outcomes they achieve
- **PAIN** - Resistance and friction they experience - **PAIN** - Resistance and friction they experience
@ -81,6 +85,7 @@ 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) 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: When all levels are then prioritized, you have perfect guidance for design:
- Present features that add value to your most prioritized goal first - Present features that add value to your most prioritized goal first
- To the highest prioritized target group - To the highest prioritized target group
- In a way that best suits their most prioritized usage goal - In a way that best suits their most prioritized usage goal
@ -98,18 +103,21 @@ Business goals work at two levels:
**Vision (Motivating, not easily quantifiable)** **Vision (Motivating, not easily quantifiable)**
A statement that inspires and guides direction: A statement that inspires and guides direction:
- "Become the most popular free and open source design support framework" - "Become the most popular free and open source design support framework"
- "Be the go-to partner for SMB digital transformation" - "Be the go-to partner for SMB digital transformation"
- "Make professional UX accessible to every startup" - "Make professional UX accessible to every startup"
**Objectives (SMART metrics)** **Objectives (SMART metrics)**
Specific, measurable targets that indicate progress toward the vision: Specific, measurable targets that indicate progress toward the vision:
- "10,000 active designer users by 2027" - "10,000 active designer users by 2027"
- "100 community contributions accepted by Q4 2026" - "100 community contributions accepted by Q4 2026"
- "50% of users complete full 6-phase workflow" - "50% of users complete full 6-phase workflow"
- "NPS score of 60+ from design professionals" - "NPS score of 60+ from design professionals"
You'll define both levels: You'll define both levels:
- Vision that motivates the team - Vision that motivates the team
- Objectives with clear success metrics - Objectives with clear success metrics
@ -118,6 +126,7 @@ You'll define both levels:
Key question: "Who needs to succeed for YOU to succeed?" Key question: "Who needs to succeed for YOU to succeed?"
Instead of demographics, you discover: Instead of demographics, you discover:
- User types who can drive business success - User types who can drive business success
- The role each type plays in your strategy - The role each type plays in your strategy
- How different users contribute differently - 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?" "Now the flip side: What do they desperately want to avoid? What would feel like failure?"
This reveals: This reveals:
- **Positive Triggers** - What motivates action - **Positive Triggers** - What motivates action
- **Negative Triggers** - What prevents engagement - **Negative Triggers** - What prevents engagement
- **Emotional Drivers** - The psychology behind decisions - **Emotional Drivers** - The psychology behind decisions
@ -142,6 +152,7 @@ This reveals:
### Stage 4: Visual Strategy Map (15-20 minutes) ### Stage 4: Visual Strategy Map (15-20 minutes)
Saga helps build the complete trigger map: Saga helps build the complete trigger map:
- Connecting every user insight to business goals - Connecting every user insight to business goals
- Creating the visual strategy guide - Creating the visual strategy guide
- Validating the strategic logic together - 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? 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 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: For each feature, award points:
| Impact | Points | | Impact | Points |
|--------|--------| | -------------------------------------------- | -------- |
| Serves Priority 1 Target Group | +3 | | Serves Priority 1 Target Group | +3 |
| Serves Priority 2 Target Group | +2 | | Serves Priority 2 Target Group | +2 |
| Serves Priority 3 Target Group | +1 | | Serves Priority 3 Target Group | +1 |
| Addresses Priority 1 Positive Driver | +3 | | Addresses Priority 1 Positive Driver | +3 |
| Addresses Priority 2 Positive Driver | +2 | | Addresses Priority 2 Positive Driver | +2 |
| Addresses Priority 3 Positive Driver | +1 | | Addresses Priority 3 Positive Driver | +1 |
| **Addresses Priority 1 Negative Driver** | **+4** | | **Addresses Priority 1 Negative Driver** | **+4** |
| **Addresses Priority 2 Negative Driver** | **+3** | | **Addresses Priority 2 Negative Driver** | **+3** |
| **Addresses Priority 3 Negative Driver** | **+2** | | **Addresses Priority 3 Negative Driver** | **+2** |
| Serves multiple target groups | +2 bonus | | Serves multiple target groups | +2 bonus |
| Addresses both positive AND negative drivers | +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. > **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:** **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** | | 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** | | 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** | | Calendar sync | P2 Walker (+2) | Efficiency (+1) | **3** |
**The Output:** **The Output:**
A ranked feature list showing: A ranked feature list showing:
- Which features have the broadest impact - Which features have the broadest impact
- Which features are "single-purpose" vs "multi-impact" - Which features are "single-purpose" vs "multi-impact"
- Natural MVP candidates (highest scores) - Natural MVP candidates (highest scores)
@ -220,11 +232,13 @@ Traditional personas describe demographics: "Jennifer, 34, likes yoga and lattes
WDS personas capture psychology: WDS personas capture psychology:
**Alliterative Naming** - Each persona gets a memorable name that hints at their role: **Alliterative Naming** - Each persona gets a memorable name that hints at their role:
- "Patrick the Professional" - Decision-maker focused on efficiency - "Patrick the Professional" - Decision-maker focused on efficiency
- "Sophie the Socializer" - Values connection and community - "Sophie the Socializer" - Values connection and community
- "Tyler the Technical" - Wants control and customization - "Tyler the Technical" - Wants control and customization
**What Each Persona Includes:** **What Each Persona Includes:**
- Role and context - Role and context
- Goals they're trying to achieve - Goals they're trying to achieve
- Fears and frustrations - Fears and frustrations
@ -237,16 +251,19 @@ WDS personas capture psychology:
## When to Use This Phase ## When to Use This Phase
**Use after Phase 1 if:** **Use after Phase 1 if:**
- Building a new product - Building a new product
- Need clarity on who you're building for - Need clarity on who you're building for
- Want design decisions grounded in user psychology - Want design decisions grounded in user psychology
**Start here if:** **Start here if:**
- You have product vision but unclear user strategy - You have product vision but unclear user strategy
- Existing personas feel shallow or unused - Existing personas feel shallow or unused
- Features aren't connecting with users - Features aren't connecting with users
**Skip if:** **Skip if:**
- Quick enhancement to existing feature - Quick enhancement to existing feature
- Users are already well-documented and validated - Users are already well-documented and validated
- Design system work without new user research - Design system work without new user research
@ -256,6 +273,7 @@ WDS personas capture psychology:
## What to Prepare ## What to Prepare
Bring: Bring:
- Your completed Product Brief (Phase 1) - Your completed Product Brief (Phase 1)
- Any existing user research (even informal) - Any existing user research (even informal)
- Stakeholder availability for the workshop - Stakeholder availability for the workshop
@ -277,15 +295,18 @@ The trigger map becomes the strategic brain of your product.
## Tips for Great Sessions ## Tips for Great Sessions
**Think strategically, not demographically** **Think strategically, not demographically**
- "Who needs to win for us to win?" not "Who might use this?" - "Who needs to win for us to win?" not "Who might use this?"
- Connect every user insight to business outcomes - Connect every user insight to business outcomes
**Go deep on psychology** **Go deep on psychology**
- Push beyond surface responses - Push beyond surface responses
- Ask "why" multiple times - Ask "why" multiple times
- Understand motivations, not just behaviors - Understand motivations, not just behaviors
**Build the map live** **Build the map live**
- See connections as they emerge - See connections as they emerge
- Validate strategic logic together - Validate strategic logic together
- Make it visual and shareable - 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_

47
src/modules/wds/docs/method/phase-3-prd-platform-guide.md
View File

@ -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.** **Prove our concept works technically — in parallel with design work.**
While UX designers explore how users interact with features, technical validation runs alongside: While UX designers explore how users interact with features, technical validation runs alongside:
- Can we actually build this? - Can we actually build this?
- Do the external services we need exist and work as expected? - Do the external services we need exist and work as expected?
- What platform and infrastructure do we need? - 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: Establish the technical foundation:
**Architecture:** **Architecture:**
- What technology stack fits your needs? - What technology stack fits your needs?
- Monolith vs. microservices vs. serverless? - Monolith vs. microservices vs. serverless?
- What hosting/infrastructure approach? - What hosting/infrastructure approach?
- What are the key technical constraints? - What are the key technical constraints?
**Data Model:** **Data Model:**
- What are the core entities? - What are the core entities?
- How do they relate to each other? - How do they relate to each other?
- What's the database strategy? - What's the database strategy?
@ -72,15 +75,16 @@ Identify all external dependencies:
**Examples:** **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? | | "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? | | "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? | | "AI-powered recommendations" | Does the ML model perform well enough with our data? |
| "Offline mode" | Can we sync data reliably when connection returns? | | "Offline mode" | Can we sync data reliably when connection returns? |
| "Video calling" | Which provider works best? What's the latency? | | "Video calling" | Which provider works best? What's the latency? |
**What a PoC validates:** **What a PoC validates:**
- The API/service exists and does what we need - The API/service exists and does what we need
- Performance is acceptable - Performance is acceptable
- Cost is within budget - Cost is within budget
@ -88,6 +92,7 @@ Identify all external dependencies:
- Edge cases are handleable - Edge cases are handleable
**PoC Output:** **PoC Output:**
- Working code snippet or prototype - Working code snippet or prototype
- Documented limitations and gotchas - Documented limitations and gotchas
- Cost estimates (API calls, compute, etc.) - Cost estimates (API calls, compute, etc.)
@ -98,12 +103,14 @@ Identify all external dependencies:
### Stage 4: Security & Performance Framework (20-30 minutes) ### Stage 4: Security & Performance Framework (20-30 minutes)
**Security:** **Security:**
- Authentication approach (passwords, OAuth, SSO, passwordless) - Authentication approach (passwords, OAuth, SSO, passwordless)
- Authorization model (roles, permissions, row-level security) - Authorization model (roles, permissions, row-level security)
- Data encryption needs (at rest, in transit) - Data encryption needs (at rest, in transit)
- Compliance requirements (GDPR, HIPAA, PCI-DSS, etc.) - Compliance requirements (GDPR, HIPAA, PCI-DSS, etc.)
**Performance:** **Performance:**
- Expected load and scale - Expected load and scale
- Response time expectations - Response time expectations
- Availability requirements (99.9%? 99.99%?) - 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:** **What to set up:**
| Endpoint Type | Example | Why Early? | | Endpoint Type | Example | Why Early? |
|---------------|---------|------------| | --------------------- | ---------------------------------------- | --------------------------- |
| Core CRUD | `GET /api/dogs`, `POST /api/bookings` | Foundation for everything | | Core CRUD | `GET /api/dogs`, `POST /api/bookings` | Foundation for everything |
| External integrations | `GET /api/routes/estimate` (Google Maps) | Validates third-party works | | External integrations | `GET /api/routes/estimate` (Google Maps) | Validates third-party works |
| Authentication | `/api/auth/login`, `/api/auth/refresh` | Security model proven | | Authentication | `/api/auth/login`, `/api/auth/refresh` | Security model proven |
| Key calculations | `/api/availability/check` | Business logic validated | | Key calculations | `/api/availability/check` | Business logic validated |
**Output:** **Output:**
For each experimental endpoint, document: For each experimental endpoint, document:
- Endpoint specification (method, path, request/response) - Endpoint specification (method, path, request/response)
- What it validates - What it validates
- Current status (stub, working, blocked) - 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 ## When to Use This Phase
**Use this phase when:** **Use this phase when:**
- Building platform/infrastructure for a new product - Building platform/infrastructure for a new product
- Features depend on external APIs or services - Features depend on external APIs or services
- Innovative features need technical validation - Innovative features need technical validation
- Development team needs architectural clarity before design - Development team needs architectural clarity before design
**Skip or minimize if:** **Skip or minimize if:**
- Simple project with obvious technical approach - Simple project with obvious technical approach
- Working within existing platform/infrastructure - Working within existing platform/infrastructure
- Enhancement that doesn't change architecture - 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 ## What to Prepare
Bring: Bring:
- Product Brief (Phase 1) - Product Brief (Phase 1)
- Trigger Map with Feature Impact Analysis (Phase 2) - Trigger Map with Feature Impact Analysis (Phase 2)
- Any existing technical constraints - Any existing technical constraints
@ -232,19 +243,23 @@ Your technical foundation enables:
## Tips for Great Sessions ## Tips for Great Sessions
**Validate risky features first** **Validate risky features first**
- If the Google Maps API doesn't return drive times in a usable format, you need to know NOW - 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 - Don't design features you can't build
**Document constraints clearly** **Document constraints clearly**
- Designers need to know what's possible - Designers need to know what's possible
- "Loading state required" vs "instant" changes UX significantly - "Loading state required" vs "instant" changes UX significantly
**Involve developers** **Involve developers**
- Technical decisions benefit from dev input - Technical decisions benefit from dev input
- PoC work may require developer time - PoC work may require developer time
- Architecture is a conversation, not a decree - Architecture is a conversation, not a decree
**Stay connected to strategy** **Stay connected to strategy**
- Reference Feature Impact Analysis scores - Reference Feature Impact Analysis scores
- High-impact features deserve more PoC investment - High-impact features deserve more PoC investment
- Don't over-engineer for hypothetical needs - 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:** **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 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 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 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 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. 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_

37
src/modules/wds/docs/method/phase-4-ux-design-guide.md
View File

@ -30,35 +30,43 @@ For each scenario/page:
## How Freyja the WDS Designer helps you design software ## How Freyja the WDS Designer helps you design software
### 4A: Scenario Exploration ### 4A: Scenario Exploration
**When:** Discovering the Concept, the process, flow screen or component solution together, before sketching begin **When:** Discovering the Concept, the process, flow screen or component solution together, before sketching begin
Freyja helps you: Freyja helps you:
- Think through the user's journey - Think through the user's journey
- Explore content and feature options - Explore content and feature options
- Consider psychological triggers from your Trigger Map - Consider psychological triggers from your Trigger Map
- Arrive at a clear solution ready for sketching - Arrive at a clear solution ready for sketching
### 4B: UI Sketch Analysis ### 4B: UI Sketch Analysis
**When:** You have a sketch and you need feedback on it **When:** You have a sketch and you need feedback on it
Freyja helps you: Freyja helps you:
- Analyze what the sketch shows - Analyze what the sketch shows
- Ask clarifying questions - Ask clarifying questions
- Identify all components and states - Identify all components and states
### 4C: Conceptual Specification ### 4C: Conceptual Specification
**When:** Design is clear, need development-ready specs **When:** Design is clear, need development-ready specs
Freyja helps you: Freyja helps you:
- Document every detail systematically - Document every detail systematically
- Assign Object IDs for testing - Assign Object IDs for testing
- Define all interactions and states - Define all interactions and states
- Prepare multilingual content, error codes, instructions and any other content needed for the developers - Prepare multilingual content, error codes, instructions and any other content needed for the developers
### 4D: HTML Prototype ### 4D: HTML Prototype
**When:** Specifications complete, and we make the sketch come alive to test the concept **When:** Specifications complete, and we make the sketch come alive to test the concept
Freyja helps you: Freyja helps you:
- Create interactive prototypes - Create interactive prototypes
- Test the design in browser - Test the design in browser
- Discover gaps and issues - Discover gaps and issues
@ -66,9 +74,11 @@ Freyja helps you:
- Visualize the concept before development - Visualize the concept before development
### 4E: PRD Update ### 4E: PRD Update
**When:** Page design is complete, before moving to the next scenario **When:** Page design is complete, before moving to the next scenario
Freyja helps you: Freyja helps you:
- Identify what features this page requires - Identify what features this page requires
- Add functional requirements to the PRD - Add functional requirements to the PRD
- Reference the page (e.g., "Required by: 2.1-Dog-Calendar") - Reference the page (e.g., "Required by: 2.1-Dog-Calendar")
@ -77,6 +87,7 @@ Freyja helps you:
**Why this step matters:** **Why this step matters:**
Each page reveals concrete requirements: Each page reveals concrete requirements:
- "This form needs email validation" - "This form needs email validation"
- "We need a GET endpoint for availability" - "We need a GET endpoint for availability"
- "Users need to upload images here" - "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 ## Functional Requirements
### Email Validation ### Email Validation
**Required by:** 1.2-Sign-Up, 2.3-Profile-Edit **Required by:** 1.2-Sign-Up, 2.3-Profile-Edit
- Validate format on input - Validate format on input
- Check domain exists - Check domain exists
- Prevent duplicates - Prevent duplicates
### Availability Calendar API ### Availability Calendar API
**Required by:** 2.1-Dog-Calendar, 3.1-Booking-Flow **Required by:** 2.1-Dog-Calendar, 3.1-Booking-Flow
- GET /api/walkers/{id}/availability - GET /api/walkers/{id}/availability
- Returns 2-week window - Returns 2-week window
- Updates via WebSocket - Updates via WebSocket
@ -123,6 +138,7 @@ C-Scenarios/
``` ```
**Numbering Convention:** **Numbering Convention:**
- Scenarios: 01, 02, 03... - Scenarios: 01, 02, 03...
- Pages within scenarios: 1.1, 1.2, 2.1, 2.2... - Pages within scenarios: 1.1, 1.2, 2.1, 2.2...
@ -131,6 +147,7 @@ C-Scenarios/
## Object IDs ## Object IDs
Every interactive element gets an Object ID for: Every interactive element gets an Object ID for:
- Consistent naming across specs and code - Consistent naming across specs and code
- Test automation with stable selectors - Test automation with stable selectors
- Analytics tracking - Analytics tracking
@ -139,6 +156,7 @@ Every interactive element gets an Object ID for:
**Format:** `{page}-{section}-{element}` in kebab-case **Format:** `{page}-{section}-{element}` in kebab-case
**Example:** **Example:**
``` ```
welcome-page-hero-cta-button welcome-page-hero-cta-button
signin-form-email-input 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: **When Design System is enabled** (Phase 5), each object in your specification includes component library references:
**Example specification entry:** **Example specification entry:**
```markdown ```markdown
### Submit Button ### Submit Button
**Object ID:** `signin-form-submit-button` **Object ID:** `signin-form-submit-button`
**Component:** primary-button (from Design System) **Component:** primary-button (from Design System)
**Figma Component:** Primary Button **Figma Component:** Primary Button
@ -162,6 +182,7 @@ Triggers form validation and submission...
``` ```
**Benefits:** **Benefits:**
- Designers know which Figma component to use - Designers know which Figma component to use
- Developers know which code component to implement - Developers know which code component to implement
- Design System ensures consistency - 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. Specification isn't just documentation - it's design validation.
When you try to specify every detail, you discover: When you try to specify every detail, you discover:
- "What happens when this is empty?" - "What happens when this is empty?"
- "How does this look on mobile?" - "How does this look on mobile?"
- "What if the user does X before Y?" - "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: Interactive prototypes that validate your design:
**What they include:** **What they include:**
- Semantic HTML matching your specs - Semantic HTML matching your specs
- CSS using your Design System tokens - CSS using your Design System tokens
- JavaScript for interactions and validation - JavaScript for interactions and validation
- Multilingual content switching - Multilingual content switching
**What they reveal:** **What they reveal:**
- Visual gaps ("the spacing doesn't match") - Visual gaps ("the spacing doesn't match")
- Interaction issues ("we forgot the loading state") - Interaction issues ("we forgot the loading state")
- Component needs ("we need a phone input component") - 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") - Flow issues ("this navigation doesn't make sense")
**File Structure:** **File Structure:**
``` ```
1.1-Start-Page/ 1.1-Start-Page/
├── 1.1-Start-Page.md (specification) ├── 1.1-Start-Page.md (specification)
@ -220,20 +245,24 @@ Interactive prototypes that validate your design:
## When to Use This Phase ## When to Use This Phase
**Use this phase when:** **Use this phase when:**
- Ready to design specific screens/pages - Ready to design specific screens/pages
- Have strategic clarity from Phase 1-2 - Have strategic clarity from Phase 1-2
- Want to validate designs before development - Want to validate designs before development
**Start with exploration (4A) if:** **Start with exploration (4A) if:**
- No existing sketches - No existing sketches
- Unsure how to approach a feature - Unsure how to approach a feature
- Need to think through the user journey - Need to think through the user journey
**Start with analysis (4B) if:** **Start with analysis (4B) if:**
- Have sketches ready to specify - Have sketches ready to specify
- Know what you want, need to document it - Know what you want, need to document it
**Use HTML prototypes (4D) if:** **Use HTML prototypes (4D) if:**
- Specifications feel complete - Specifications feel complete
- Want to validate before development - Want to validate before development
- Need stakeholder sign-off - Need stakeholder sign-off
@ -243,6 +272,7 @@ Interactive prototypes that validate your design:
## What to Prepare ## What to Prepare
Bring: Bring:
- Trigger Map (Phase 2) - for user psychology reference - Trigger Map (Phase 2) - for user psychology reference
- Any existing sketches or wireframes - Any existing sketches or wireframes
- Technical constraints from PRD (Phase 3) - Technical constraints from PRD (Phase 3)
@ -263,11 +293,13 @@ Your specifications enable:
## Tips for Great Sessions ## Tips for Great Sessions
**Think out loud with Freyja** **Think out loud with Freyja**
- Share your reasoning - Share your reasoning
- Explore alternatives together - Explore alternatives together
- Let the conversation reveal insights - Let the conversation reveal insights
**Be thorough with states** **Be thorough with states**
- Empty states - Empty states
- Loading states - Loading states
- Error states - Error states
@ -275,11 +307,13 @@ Your specifications enable:
- Edge cases - Edge cases
**Don't skip the prototype** **Don't skip the prototype**
- Click through your design - Click through your design
- Find the gaps before development - Find the gaps before development
- Refine specs based on what you learn - Refine specs based on what you learn
**Reference your Trigger Map** **Reference your Trigger Map**
- Does this serve the user's goals? - Does this serve the user's goals?
- Does this avoid their fears? - Does this avoid their fears?
- Does this support business objectives? - 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_

89
src/modules/wds/docs/method/phase-5-design-system-guide.md
View File

@ -31,7 +31,9 @@ Your Design System includes:
Following Brad Frost's methodology: Following Brad Frost's methodology:
### Foundation (Design Tokens) ### Foundation (Design Tokens)
The values everything else builds on: The values everything else builds on:
- **Colors** - Primary, secondary, semantic (success, error, warning) - **Colors** - Primary, secondary, semantic (success, error, warning)
- **Typography** - Font families, sizes, weights, line heights - **Typography** - Font families, sizes, weights, line heights
- **Spacing** - Consistent spacing scale - **Spacing** - Consistent spacing scale
@ -40,7 +42,9 @@ The values everything else builds on:
- **Breakpoints** - Responsive design points - **Breakpoints** - Responsive design points
### Atoms ### Atoms
The smallest building blocks: The smallest building blocks:
- Buttons - Buttons
- Input fields - Input fields
- Labels - Labels
@ -49,14 +53,18 @@ The smallest building blocks:
- Dividers - Dividers
### Molecules ### Molecules
Groups of atoms working together: Groups of atoms working together:
- Form groups (label + input + error) - Form groups (label + input + error)
- Search bars (input + button) - Search bars (input + button)
- Card headers (title + action) - Card headers (title + action)
- Navigation items (icon + label) - Navigation items (icon + label)
### Organisms ### Organisms
Complex components made of molecules: Complex components made of molecules:
- Page headers - Page headers
- Navigation bars - Navigation bars
- Form sections - Form sections
@ -69,7 +77,7 @@ Complex components made of molecules:
### The Parallel Workflow ### 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 Phase 4 Page Design → Phase 5 Design System
@ -82,6 +90,7 @@ Notice pattern across pages → Extract as reusable component
``` ```
**The rhythm:** **The rhythm:**
1. Design a page/component in Phase 4 1. Design a page/component in Phase 4
2. Notice "This could be reusable" 2. Notice "This could be reusable"
3. Extract to Design System 3. Extract to Design System
@ -105,6 +114,7 @@ As you specify scenarios in Phase 4, components naturally emerge:
**Step 1: Spot the Pattern** **Step 1: Spot the Pattern**
While working on Phase 4 scenarios, notice when you're designing something reusable: 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" - "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" - "This form input pattern will be used everywhere"
- "We have 3 different card layouts, but they share the same structure" - "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: Use this template for each component:
```markdown ````markdown
# Primary Button # Primary Button
## Overview ## Overview
The primary button is used for the main call-to-action on any page or section. The primary button is used for the main call-to-action on any page or section.
## Component Details ## Component Details
@ -146,11 +157,13 @@ The primary button is used for the main call-to-action on any page or section.
## Variants ## Variants
### Size ### Size
- **Small:** Compact spaces, secondary actions - **Small:** Compact spaces, secondary actions
- **Medium:** Default size for most use cases - **Medium:** Default size for most use cases
- **Large:** Hero sections, important CTAs - **Large:** Hero sections, important CTAs
### State ### State
- **Default:** Ready for interaction - **Default:** Ready for interaction
- **Hover:** Visual feedback on mouse over - **Hover:** Visual feedback on mouse over
- **Active:** Currently being clicked - **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 ## Visual Specifications
**Design Tokens:** **Design Tokens:**
- Background: `color-primary-500` - Background: `color-primary-500`
- Text: `color-white` - Text: `color-white`
- Border Radius: `radius-md` - 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` - Font: `font-semibold`, `text-base`
**States:** **States:**
- Hover: `color-primary-600` - Hover: `color-primary-600`
- Active: `color-primary-700` - Active: `color-primary-700`
- Disabled: `color-gray-300`, opacity 50% - 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 ## Usage Guidelines
**When to use:** **When to use:**
- Primary action on a page or modal - Primary action on a page or modal
- Main CTA in hero sections - Main CTA in hero sections
- Form submissions - Form submissions
- Confirmation actions - Confirmation actions
**When NOT to use:** **When NOT to use:**
- Multiple primary actions (use secondary instead) - Multiple primary actions (use secondary instead)
- Destructive actions (use danger variant) - Destructive actions (use danger variant)
- Navigation (use links or secondary buttons) - 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 ## Example Usage
**In specifications:** **In specifications:**
```markdown ```markdown
### Submit Button ### Submit Button
**Object ID:** `contact-form-submit-button` **Object ID:** `contact-form-submit-button`
**Component:** primary-button **Component:** primary-button
**Variant:** size=large **Variant:** size=large
**State:** default → loading → success **State:** default → loading → success
``` ```
````
**In Figma:** **In Figma:**
Use "Primary Button" component from library Use "Primary Button" component from library
**In Code (if using Chakra):** **In Code (if using Chakra):**
```jsx ```jsx
<Button colorScheme="blue" size="lg">Submit</Button> <Button colorScheme="blue" size="lg">
Submit
</Button>
``` ```
## Used In ## Used In
@ -216,6 +239,7 @@ Use "Primary Button" component from library
- 1.2-Sign-Up: Submit registration - 1.2-Sign-Up: Submit registration
- 2.1-Contact-Form: Send message - 2.1-Contact-Form: Send message
- [Update as you use the component] - [Update as you use the component]
``` ```
**Step 4: Update as You Go** **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:** **As you work through Phase 4:**
``` ```
Design Page 1.1 Design Page 1.1
↓ ↓
Notice: "This button is reusable" Notice: "This button is reusable"
↓ ↓
Create: primary-button.md in Design System Create: primary-button.md in Design System
↓ ↓
Reference in 1.1 spec: component=primary-button Reference in 1.1 spec: component=primary-button
↓ ↓
Design Page 1.2 Design Page 1.2
↓ ↓
Need same button: Reference existing component Need same button: Reference existing component
↓ ↓
Design Page 2.1 Design Page 2.1
↓ ↓
Need slightly different: Add variant to component doc Need slightly different: Add variant to component doc
↓ ↓
Update all references with new variant option Update all references with new variant option
``` ```
--- ---
@ -258,15 +284,17 @@ Beyond documentation, create an **interactive HTML guide** where stakeholders an
### Structure ### Structure
``` ```
D-Design-System/ D-Design-System/
├── component-showcase.html ← Interactive guide ├── component-showcase.html ← Interactive guide
├── component-showcase.css ├── component-showcase.css
├── component-showcase.js ├── component-showcase.js
├── 01-design-tokens.md ├── 01-design-tokens.md
├── 02-atoms/ ├── 02-atoms/
│ ├── primary-button.md │ ├── primary-button.md
│ └── ... │ └── ...
```
````
### What the Showcase Includes ### What the Showcase Includes
@ -562,7 +590,7 @@ These libraries work well with WDS's specification approach:
**When to use:** **When to use:**
Primary call-to-action buttons... 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:** **Use the exact same names across all tools:**
| WDS Component Name | Figma Component | Code Component | Object ID | | WDS Component Name | Figma Component | Code Component | Object ID |
|-------------------|-----------------|----------------|-----------| | ------------------ | --------------- | --------------- | ------------------ |
| `primary-button` | Primary Button | `PrimaryButton` | `*-primary-button` | | `primary-button` | Primary Button | `PrimaryButton` | `*-primary-button` |
| `text-input` | Text Input | `TextInput` | `*-text-input` | | `text-input` | Text Input | `TextInput` | `*-text-input` |
| `form-group` | Form Group | `FormGroup` | `*-form-group` | | `form-group` | Form Group | `FormGroup` | `*-form-group` |
### The Workflow ### The Workflow
@ -598,6 +626,7 @@ signin-form-submit-primary-button (everywhere)
**Component Library Structure:** **Component Library Structure:**
Match your WDS atomic design structure: Match your WDS atomic design structure:
``` ```
Design File/ Design File/
├── 🎨 Design Tokens ├── 🎨 Design Tokens
@ -618,6 +647,7 @@ Design File/
``` ```
**Naming in Figma:** **Naming in Figma:**
- Component names match WDS names (kebab-case or Title Case) - Component names match WDS names (kebab-case or Title Case)
- Variants match WDS variants (Primary, Secondary, Disabled) - Variants match WDS variants (Primary, Secondary, Disabled)
- Properties match WDS states (default, hover, active, error) - 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: The design system is living documentation that grows with your product:
### Starting Point ### Starting Point
Begin with what you need for current scenarios: Begin with what you need for current scenarios:
- Extract components from Phase 4 work - Extract components from Phase 4 work
- Document only what you're actually using - Document only what you're actually using
- Avoid speculating about future needs - Avoid speculating about future needs
### Evolution ### Evolution
As you design more scenarios: As you design more scenarios:
- New patterns emerge → add to system - New patterns emerge → add to system
- Inconsistencies appear → consolidate - Inconsistencies appear → consolidate
- Components evolve → update documentation - Components evolve → update documentation
### Maintenance ### Maintenance
- Keep specs in sync with implementation - Keep specs in sync with implementation
- Remove unused components - Remove unused components
- Update when design language evolves - Update when design language evolves
@ -665,24 +700,28 @@ As you design more scenarios:
## When to Use This Phase ## When to Use This Phase
**Enable Design System phase if:** **Enable Design System phase if:**
- Building reusable component library - Building reusable component library
- Multiple pages/scenarios with shared patterns - Multiple pages/scenarios with shared patterns
- Need design consistency across product - Need design consistency across product
- Handoff requires component documentation - Handoff requires component documentation
**Work in parallel with Phase 4 when enabled:** **Work in parallel with Phase 4 when enabled:**
- As you sketch, identify component patterns - As you sketch, identify component patterns
- As you specify, extract to Design System - As you specify, extract to Design System
- Design System grows with each page completed - Design System grows with each page completed
- No separate "design system phase" at the end - No separate "design system phase" at the end
**Skip this phase if:** **Skip this phase if:**
- Small project (single landing page) - Small project (single landing page)
- Using existing design system (Material, Chakra, etc.) - Using existing design system (Material, Chakra, etc.)
- One-off designs without reuse - One-off designs without reuse
- Quick prototype or MVP without component library needs - Quick prototype or MVP without component library needs
**Dedicated consolidation when:** **Dedicated consolidation when:**
- Multiple scenarios complete, need cleanup - Multiple scenarios complete, need cleanup
- Preparing for development handoff - Preparing for development handoff
- Found inconsistencies to resolve - Found inconsistencies to resolve
@ -695,6 +734,7 @@ As you design more scenarios:
## What to Prepare ## What to Prepare
Bring: Bring:
- Completed or in-progress scenario specs (Phase 4) - Completed or in-progress scenario specs (Phase 4)
- Any existing brand guidelines - Any existing brand guidelines
- Technical framework constraints (React components, etc.) - Technical framework constraints (React components, etc.)
@ -714,21 +754,25 @@ Your Design System enables:
## Tips for Great Sessions ## Tips for Great Sessions
**Extract, don't invent** **Extract, don't invent**
- Components should come from real design needs - Components should come from real design needs
- Don't create components "just in case" - Don't create components "just in case"
- Let the system grow from actual scenarios - Let the system grow from actual scenarios
**Document the why** **Document the why**
- Why does this button look this way? - Why does this button look this way?
- What user trigger does it serve? - What user trigger does it serve?
- When should developers use variant A vs B? - When should developers use variant A vs B?
**Stay consistent** **Stay consistent**
- Same component = same specification - Same component = same specification
- Variations should be intentional - Variations should be intentional
- When in doubt, simplify - When in doubt, simplify
**Connect to psychology** **Connect to psychology**
- Every design choice serves a purpose - Every design choice serves a purpose
- Reference your Trigger Map - Reference your Trigger Map
- Components should feel intentional, not arbitrary - 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_

57
src/modules/wds/docs/method/phase-6-integration-guide.md
View File

@ -21,6 +21,7 @@ By the end, developers have a complete PRD covering both technical foundation an
**Updated PRD (C-Requirements/) includes:** **Updated PRD (C-Requirements/) includes:**
**From Phase 3 (Technical Foundation):** **From Phase 3 (Technical Foundation):**
- Platform architecture - Platform architecture
- Data model - Data model
- Integration map - Integration map
@ -29,6 +30,7 @@ By the end, developers have a complete PRD covering both technical foundation an
- Security framework - Security framework
**Added from Phase 4 (Functional Requirements):** **Added from Phase 4 (Functional Requirements):**
- All features discovered during page design - All features discovered during page design
- Page-to-feature traceability - Page-to-feature traceability
- Priority rankings - Priority rankings
@ -36,12 +38,14 @@ By the end, developers have a complete PRD covering both technical foundation an
- Implementation notes - Implementation notes
**New in Phase 6:** **New in Phase 6:**
- Feature organization by epic/area - Feature organization by epic/area
- Development sequence - Development sequence
- MVP scope definition - MVP scope definition
- Technical dependencies mapped - Technical dependencies mapped
**Handoff Package (E-UI-Roadmap/):** **Handoff Package (E-UI-Roadmap/):**
- Priority sequence document - Priority sequence document
- Scenario-to-development mapping - Scenario-to-development mapping
- Component inventory (if Design System enabled) - Component inventory (if Design System enabled)
@ -86,18 +90,21 @@ From 2.1-Dog-Calendar:
### Features ### Features
**User Registration** **User Registration**
- Required by: 1.2-Sign-Up - Required by: 1.2-Sign-Up
- Email validation (format, domain, duplicates) - Email validation (format, domain, duplicates)
- Phone validation with country codes - Phone validation with country codes
- Account activation flow - Account activation flow
**User Login** **User Login**
- Required by: 1.1-Start-Page, multiple pages - Required by: 1.1-Start-Page, multiple pages
- Email/password authentication - Email/password authentication
- Session management (30-day persistence) - Session management (30-day persistence)
- "Remember me" functionality - "Remember me" functionality
**Password Management** **Password Management**
- Required by: 1.1-Start-Page (reset link) - Required by: 1.1-Start-Page (reset link)
- Password reset via email - Password reset via email
- Password strength validation - Password strength validation
@ -114,9 +121,11 @@ Reference the scoring you did in Phase 2 to inform priorities:
## Development Sequence ## Development Sequence
### Priority 1: MVP - Core User Flow ### Priority 1: MVP - Core User Flow
**Target:** Weeks 1-4 **Target:** Weeks 1-4
Features from Epic 1 (Authentication) + Epic 2 (Core Booking): Features from Epic 1 (Authentication) + Epic 2 (Core Booking):
- User registration (Impact Score: 14) - User registration (Impact Score: 14)
- User login (Impact Score: 16) - User login (Impact Score: 16)
- Availability calendar (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. Serves Priority 1 target group, addresses highest-impact drivers.
### Priority 2: Enhanced Features ### Priority 2: Enhanced Features
**Target:** Weeks 5-8 **Target:** Weeks 5-8
Features from Epic 3 (Payments) + Epic 4 (Notifications): Features from Epic 3 (Payments) + Epic 4 (Notifications):
- Payment processing (Impact Score: 12) - Payment processing (Impact Score: 12)
- Booking confirmations (Impact Score: 11) - Booking confirmations (Impact Score: 11)
- Calendar sync (Impact Score: 8) - Calendar sync (Impact Score: 8)
@ -142,6 +153,7 @@ Features from Epic 3 (Payments) + Epic 4 (Notifications):
## Feature Dependencies ## Feature Dependencies
**Booking Flow** depends on: **Booking Flow** depends on:
- ✓ User authentication (must be logged in) - ✓ User authentication (must be logged in)
- ✓ Availability calendar (must see open slots) - ✓ Availability calendar (must see open slots)
- ⚠️ Payment system (can launch with "pay in person" temporarily) - ⚠️ 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) ## 1. Technical Foundation (from Phase 3)
### Platform Architecture ### Platform Architecture
- Technology stack decisions - Technology stack decisions
- Infrastructure approach - Infrastructure approach
- Hosting and deployment - Hosting and deployment
### Data Model ### Data Model
- Core entities and relationships - Core entities and relationships
- Database schema - Database schema
- Data flow diagrams - Data flow diagrams
### Integrations ### Integrations
- External services (Google Maps, Stripe, etc.) - External services (Google Maps, Stripe, etc.)
- API specifications - API specifications
- Authentication providers - Authentication providers
### Security & Performance ### Security & Performance
- Authentication/authorization approach - Authentication/authorization approach
- Data protection - Data protection
- Performance requirements - Performance requirements
@ -196,7 +212,9 @@ Your finalized PRD in `C-Requirements/` combines all phases:
## 2. Functional Requirements (from Phase 4) ## 2. Functional Requirements (from Phase 4)
### Epic 1: User Authentication & Account Management ### Epic 1: User Authentication & Account Management
**Features:** **Features:**
- User registration (Required by: 1.2-Sign-Up) - User registration (Required by: 1.2-Sign-Up)
- User login (Required by: 1.1-Start-Page, multiple) - User login (Required by: 1.1-Start-Page, multiple)
- Password management (Required by: 1.1-Start-Page) - 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] [Detailed specifications for each feature]
### Epic 2: [Next Epic] ### Epic 2: [Next Epic]
[...] [...]
## 3. Development Roadmap (from Phase 6) ## 3. Development Roadmap (from Phase 6)
### Priority 1: MVP (Weeks 1-4) ### Priority 1: MVP (Weeks 1-4)
- Features list with Impact Scores - Features list with Impact Scores
- Why these first (references Trigger Map) - Why these first (references Trigger Map)
- Timeline estimate - Timeline estimate
- Dependencies - Dependencies
### Priority 2: Enhanced Features (Weeks 5-8) ### Priority 2: Enhanced Features (Weeks 5-8)
[...] [...]
## 4. Dependencies & Constraints ## 4. Dependencies & Constraints
- Technical dependencies between features - Technical dependencies between features
- Design constraints from Phase 4 - Design constraints from Phase 4
- Third-party limitations discovered in Phase 3 - Third-party limitations discovered in Phase 3
## 5. Success Metrics ## 5. Success Metrics
- Business goals from Phase 1 - Business goals from Phase 1
- Feature-specific KPIs - Feature-specific KPIs
- How we measure success - How we measure success
@ -251,12 +274,14 @@ Your finalized PRD in `C-Requirements/` combines all phases:
## When to Use This Phase ## When to Use This Phase
**First PRD Finalization when:** **First PRD Finalization when:**
- You have MVP-level scenarios complete (enough for dev to start) - 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 - Critical features are documented
- Enough work for 2-4 week sprint - Enough work for 2-4 week sprint
**Ongoing PRD Updates as:** **Ongoing PRD Updates as:**
- Additional scenarios complete - Additional scenarios complete
- New feature areas designed - New feature areas designed
- Priorities shift based on learning - Priorities shift based on learning
@ -285,12 +310,12 @@ Week 9+: Design continues in parallel with development
Complete list for test automation: Complete list for test automation:
| Scenario | Object ID | Element Type | Notes | | Scenario | Object ID | Element Type | Notes |
|----------|-----------|--------------|-------| | -------- | --------------------- | ------------ | ------------------ |
| 1.1 | `welcome-hero-cta` | Button | Primary action | | 1.1 | `welcome-hero-cta` | Button | Primary action |
| 1.1 | `welcome-signin-link` | Link | Secondary action | | 1.1 | `welcome-signin-link` | Link | Secondary action |
| 1.2 | `signin-email-input` | Input | Required field | | 1.2 | `signin-email-input` | Input | Required field |
| 1.2 | `signin-error-email` | Error | Validation message | | 1.2 | `signin-error-email` | Error | Validation message |
--- ---
@ -299,6 +324,7 @@ Complete list for test automation:
### Review Completeness ### Review Completeness
Before handoff, verify: Before handoff, verify:
- All scenarios specified and reviewed - All scenarios specified and reviewed
- Design system covers all components - Design system covers all components
- Object IDs assigned throughout - Object IDs assigned throughout
@ -308,6 +334,7 @@ Before handoff, verify:
### Identify Priorities ### Identify Priorities
With Freyja, map your Trigger Map priorities to development order: With Freyja, map your Trigger Map priorities to development order:
- Which user triggers are most critical? - Which user triggers are most critical?
- What's the minimum viable experience? - What's the minimum viable experience?
- What can wait for later releases? - What can wait for later releases?
@ -315,6 +342,7 @@ With Freyja, map your Trigger Map priorities to development order:
### Document Technical Context ### Document Technical Context
Capture what developers need to know: Capture what developers need to know:
- Design decisions and their rationale - Design decisions and their rationale
- Technical constraints discovered during design - Technical constraints discovered during design
- Interaction patterns that need special attention - Interaction patterns that need special attention
@ -323,6 +351,7 @@ Capture what developers need to know:
### Create the Handoff ### Create the Handoff
Organize everything into the UI Roadmap folder: Organize everything into the UI Roadmap folder:
- Clear priority sequence - Clear priority sequence
- Complete component inventory - Complete component inventory
- Technical notes and open questions - Technical notes and open questions
@ -336,26 +365,31 @@ Organize everything into the UI Roadmap folder:
## Design Handoff Verification ## Design Handoff Verification
### Product Foundation ### Product Foundation
- [ ] Product Brief complete and current - [ ] Product Brief complete and current
- [ ] Trigger Map with prioritized users and goals - [ ] Trigger Map with prioritized users and goals
- [ ] ICP clearly defined - [ ] ICP clearly defined
### Requirements ### Requirements
- [ ] PRD with technical specifications - [ ] PRD with technical specifications
- [ ] Platform architecture documented - [ ] Platform architecture documented
- [ ] Integration requirements listed - [ ] Integration requirements listed
### Visual Design ### Visual Design
- [ ] All scenarios have specifications - [ ] All scenarios have specifications
- [ ] All pages have Object IDs - [ ] All pages have Object IDs
- [ ] States documented (empty, loading, error, success) - [ ] States documented (empty, loading, error, success)
### Design System ### Design System
- [ ] All components documented - [ ] All components documented
- [ ] Design tokens defined - [ ] Design tokens defined
- [ ] Usage guidelines written - [ ] Usage guidelines written
### Validation ### Validation
- [ ] HTML prototypes created for key scenarios - [ ] HTML prototypes created for key scenarios
- [ ] Stakeholder review complete - [ ] Stakeholder review complete
- [ ] Open questions documented - [ ] Open questions documented
@ -368,12 +402,14 @@ Organize everything into the UI Roadmap folder:
## When to Use This Phase ## When to Use This Phase
**First handoff when:** **First handoff when:**
- You have enough scenarios for MVP - You have enough scenarios for MVP
- Core user flows are specified - Core user flows are specified
- Critical components are documented - Critical components are documented
- Developers can start building foundational features - Developers can start building foundational features
**Ongoing handoffs as:** **Ongoing handoffs as:**
- Each major scenario completes - Each major scenario completes
- New component patterns emerge - New component patterns emerge
- Design decisions affect development - Design decisions affect development
@ -402,6 +438,7 @@ Development and design work in parallel streams, with regular sync points.
## What to Prepare ## What to Prepare
Bring: Bring:
- Completed scenario specifications (Phase 4) - Completed scenario specifications (Phase 4)
- Design System (Phase 5) - Design System (Phase 5)
- PRD (Phase 3) - PRD (Phase 3)
@ -423,21 +460,25 @@ Your UI Roadmap enables:
## Tips for Great Sessions ## Tips for Great Sessions
**Think from dev perspective** **Think from dev perspective**
- What questions will developers have? - What questions will developers have?
- What decisions can't you make for them? - What decisions can't you make for them?
- What context will save them time? - What context will save them time?
**Be explicit about priorities** **Be explicit about priorities**
- Not everything is Priority 1 - Not everything is Priority 1
- Make trade-offs visible - Make trade-offs visible
- Connect priorities to business goals - Connect priorities to business goals
**Document the unknowns** **Document the unknowns**
- Open questions are valuable - Open questions are valuable
- Don't pretend certainty you don't have - Don't pretend certainty you don't have
- Let dev team contribute decisions - Let dev team contribute decisions
**Keep it updated** **Keep it updated**
- Handoff is ongoing, not one-time - Handoff is ongoing, not one-time
- Update as design evolves - Update as design evolves
- Maintain as source of truth - Maintain as source of truth
@ -453,6 +494,7 @@ WDS → E-UI-Roadmap/ → BMM Architecture & Stories
``` ```
The UI Roadmap provides: The UI Roadmap provides:
- Context for architecture decisions - Context for architecture decisions
- Specifications for story creation - Specifications for story creation
- Priorities for sprint planning - 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_

57
src/modules/wds/docs/method/phase-6-prd-finalization-guide.md
View File

@ -20,6 +20,7 @@ By the end, developers have a complete PRD covering both technical foundation an
**Updated PRD (C-Requirements/) includes:** **Updated PRD (C-Requirements/) includes:**
**From Phase 3 (Technical Foundation):** **From Phase 3 (Technical Foundation):**
- Platform architecture - Platform architecture
- Data model - Data model
- Integration map - Integration map
@ -28,6 +29,7 @@ By the end, developers have a complete PRD covering both technical foundation an
- Security framework - Security framework
**Added from Phase 4 (Functional Requirements):** **Added from Phase 4 (Functional Requirements):**
- All features discovered during page design - All features discovered during page design
- Page-to-feature traceability - Page-to-feature traceability
- Priority rankings - Priority rankings
@ -35,12 +37,14 @@ By the end, developers have a complete PRD covering both technical foundation an
- Implementation notes - Implementation notes
**New in Phase 6:** **New in Phase 6:**
- Feature organization by epic/area - Feature organization by epic/area
- Development sequence - Development sequence
- MVP scope definition - MVP scope definition
- Technical dependencies mapped - Technical dependencies mapped
**Handoff Package (E-UI-Roadmap/):** **Handoff Package (E-UI-Roadmap/):**
- Priority sequence document - Priority sequence document
- Scenario-to-development mapping - Scenario-to-development mapping
- Component inventory (if Design System enabled) - Component inventory (if Design System enabled)
@ -85,18 +89,21 @@ From 2.1-Dog-Calendar:
### Features ### Features
**User Registration** **User Registration**
- Required by: 1.2-Sign-Up - Required by: 1.2-Sign-Up
- Email validation (format, domain, duplicates) - Email validation (format, domain, duplicates)
- Phone validation with country codes - Phone validation with country codes
- Account activation flow - Account activation flow
**User Login** **User Login**
- Required by: 1.1-Start-Page, multiple pages - Required by: 1.1-Start-Page, multiple pages
- Email/password authentication - Email/password authentication
- Session management (30-day persistence) - Session management (30-day persistence)
- "Remember me" functionality - "Remember me" functionality
**Password Management** **Password Management**
- Required by: 1.1-Start-Page (reset link) - Required by: 1.1-Start-Page (reset link)
- Password reset via email - Password reset via email
- Password strength validation - Password strength validation
@ -113,9 +120,11 @@ Reference the scoring you did in Phase 2 to inform priorities:
## Development Sequence ## Development Sequence
### Priority 1: MVP - Core User Flow ### Priority 1: MVP - Core User Flow
**Target:** Weeks 1-4 **Target:** Weeks 1-4
Features from Epic 1 (Authentication) + Epic 2 (Core Booking): Features from Epic 1 (Authentication) + Epic 2 (Core Booking):
- User registration (Impact Score: 14) - User registration (Impact Score: 14)
- User login (Impact Score: 16) - User login (Impact Score: 16)
- Availability calendar (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. Serves Priority 1 target group, addresses highest-impact drivers.
### Priority 2: Enhanced Features ### Priority 2: Enhanced Features
**Target:** Weeks 5-8 **Target:** Weeks 5-8
Features from Epic 3 (Payments) + Epic 4 (Notifications): Features from Epic 3 (Payments) + Epic 4 (Notifications):
- Payment processing (Impact Score: 12) - Payment processing (Impact Score: 12)
- Booking confirmations (Impact Score: 11) - Booking confirmations (Impact Score: 11)
- Calendar sync (Impact Score: 8) - Calendar sync (Impact Score: 8)
@ -141,6 +152,7 @@ Features from Epic 3 (Payments) + Epic 4 (Notifications):
## Feature Dependencies ## Feature Dependencies
**Booking Flow** depends on: **Booking Flow** depends on:
- ✓ User authentication (must be logged in) - ✓ User authentication (must be logged in)
- ✓ Availability calendar (must see open slots) - ✓ Availability calendar (must see open slots)
- ⚠️ Payment system (can launch with "pay in person" temporarily) - ⚠️ 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) ## 1. Technical Foundation (from Phase 3)
### Platform Architecture ### Platform Architecture
- Technology stack decisions - Technology stack decisions
- Infrastructure approach - Infrastructure approach
- Hosting and deployment - Hosting and deployment
### Data Model ### Data Model
- Core entities and relationships - Core entities and relationships
- Database schema - Database schema
- Data flow diagrams - Data flow diagrams
### Integrations ### Integrations
- External services (Google Maps, Stripe, etc.) - External services (Google Maps, Stripe, etc.)
- API specifications - API specifications
- Authentication providers - Authentication providers
### Security & Performance ### Security & Performance
- Authentication/authorization approach - Authentication/authorization approach
- Data protection - Data protection
- Performance requirements - Performance requirements
@ -195,7 +211,9 @@ Your finalized PRD in `C-Requirements/` combines all phases:
## 2. Functional Requirements (from Phase 4) ## 2. Functional Requirements (from Phase 4)
### Epic 1: User Authentication & Account Management ### Epic 1: User Authentication & Account Management
**Features:** **Features:**
- User registration (Required by: 1.2-Sign-Up) - User registration (Required by: 1.2-Sign-Up)
- User login (Required by: 1.1-Start-Page, multiple) - User login (Required by: 1.1-Start-Page, multiple)
- Password management (Required by: 1.1-Start-Page) - 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] [Detailed specifications for each feature]
### Epic 2: [Next Epic] ### Epic 2: [Next Epic]
[...] [...]
## 3. Development Roadmap (from Phase 6) ## 3. Development Roadmap (from Phase 6)
### Priority 1: MVP (Weeks 1-4) ### Priority 1: MVP (Weeks 1-4)
- Features list with Impact Scores - Features list with Impact Scores
- Why these first (references Trigger Map) - Why these first (references Trigger Map)
- Timeline estimate - Timeline estimate
- Dependencies - Dependencies
### Priority 2: Enhanced Features (Weeks 5-8) ### Priority 2: Enhanced Features (Weeks 5-8)
[...] [...]
## 4. Dependencies & Constraints ## 4. Dependencies & Constraints
- Technical dependencies between features - Technical dependencies between features
- Design constraints from Phase 4 - Design constraints from Phase 4
- Third-party limitations discovered in Phase 3 - Third-party limitations discovered in Phase 3
## 5. Success Metrics ## 5. Success Metrics
- Business goals from Phase 1 - Business goals from Phase 1
- Feature-specific KPIs - Feature-specific KPIs
- How we measure success - How we measure success
@ -250,12 +273,14 @@ Your finalized PRD in `C-Requirements/` combines all phases:
## When to Use This Phase ## When to Use This Phase
**First PRD Finalization when:** **First PRD Finalization when:**
- You have MVP-level scenarios complete (enough for dev to start) - 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 - Critical features are documented
- Enough work for 2-4 week sprint - Enough work for 2-4 week sprint
**Ongoing PRD Updates as:** **Ongoing PRD Updates as:**
- Additional scenarios complete - Additional scenarios complete
- New feature areas designed - New feature areas designed
- Priorities shift based on learning - Priorities shift based on learning
@ -284,12 +309,12 @@ Week 9+: Design continues in parallel with development
Complete list for test automation: Complete list for test automation:
| Scenario | Object ID | Element Type | Notes | | Scenario | Object ID | Element Type | Notes |
|----------|-----------|--------------|-------| | -------- | --------------------- | ------------ | ------------------ |
| 1.1 | `welcome-hero-cta` | Button | Primary action | | 1.1 | `welcome-hero-cta` | Button | Primary action |
| 1.1 | `welcome-signin-link` | Link | Secondary action | | 1.1 | `welcome-signin-link` | Link | Secondary action |
| 1.2 | `signin-email-input` | Input | Required field | | 1.2 | `signin-email-input` | Input | Required field |
| 1.2 | `signin-error-email` | Error | Validation message | | 1.2 | `signin-error-email` | Error | Validation message |
--- ---
@ -298,6 +323,7 @@ Complete list for test automation:
### Review Completeness ### Review Completeness
Before handoff, verify: Before handoff, verify:
- All scenarios specified and reviewed - All scenarios specified and reviewed
- Design system covers all components - Design system covers all components
- Object IDs assigned throughout - Object IDs assigned throughout
@ -307,6 +333,7 @@ Before handoff, verify:
### Identify Priorities ### Identify Priorities
With Freyja, map your Trigger Map priorities to development order: With Freyja, map your Trigger Map priorities to development order:
- Which user triggers are most critical? - Which user triggers are most critical?
- What's the minimum viable experience? - What's the minimum viable experience?
- What can wait for later releases? - What can wait for later releases?
@ -314,6 +341,7 @@ With Freyja, map your Trigger Map priorities to development order:
### Document Technical Context ### Document Technical Context
Capture what developers need to know: Capture what developers need to know:
- Design decisions and their rationale - Design decisions and their rationale
- Technical constraints discovered during design - Technical constraints discovered during design
- Interaction patterns that need special attention - Interaction patterns that need special attention
@ -322,6 +350,7 @@ Capture what developers need to know:
### Create the Handoff ### Create the Handoff
Organize everything into the UI Roadmap folder: Organize everything into the UI Roadmap folder:
- Clear priority sequence - Clear priority sequence
- Complete component inventory - Complete component inventory
- Technical notes and open questions - Technical notes and open questions
@ -335,26 +364,31 @@ Organize everything into the UI Roadmap folder:
## Design Handoff Verification ## Design Handoff Verification
### Product Foundation ### Product Foundation
- [ ] Product Brief complete and current - [ ] Product Brief complete and current
- [ ] Trigger Map with prioritized users and goals - [ ] Trigger Map with prioritized users and goals
- [ ] ICP clearly defined - [ ] ICP clearly defined
### Requirements ### Requirements
- [ ] PRD with technical specifications - [ ] PRD with technical specifications
- [ ] Platform architecture documented - [ ] Platform architecture documented
- [ ] Integration requirements listed - [ ] Integration requirements listed
### Visual Design ### Visual Design
- [ ] All scenarios have specifications - [ ] All scenarios have specifications
- [ ] All pages have Object IDs - [ ] All pages have Object IDs
- [ ] States documented (empty, loading, error, success) - [ ] States documented (empty, loading, error, success)
### Design System ### Design System
- [ ] All components documented - [ ] All components documented
- [ ] Design tokens defined - [ ] Design tokens defined
- [ ] Usage guidelines written - [ ] Usage guidelines written
### Validation ### Validation
- [ ] HTML prototypes created for key scenarios - [ ] HTML prototypes created for key scenarios
- [ ] Stakeholder review complete - [ ] Stakeholder review complete
- [ ] Open questions documented - [ ] Open questions documented
@ -367,12 +401,14 @@ Organize everything into the UI Roadmap folder:
## When to Use This Phase ## When to Use This Phase
**First handoff when:** **First handoff when:**
- You have enough scenarios for MVP - You have enough scenarios for MVP
- Core user flows are specified - Core user flows are specified
- Critical components are documented - Critical components are documented
- Developers can start building foundational features - Developers can start building foundational features
**Ongoing handoffs as:** **Ongoing handoffs as:**
- Each major scenario completes - Each major scenario completes
- New component patterns emerge - New component patterns emerge
- Design decisions affect development - Design decisions affect development
@ -401,6 +437,7 @@ Development and design work in parallel streams, with regular sync points.
## What to Prepare ## What to Prepare
Bring: Bring:
- Completed scenario specifications (Phase 4) - Completed scenario specifications (Phase 4)
- Design System (Phase 5) - Design System (Phase 5)
- PRD (Phase 3) - PRD (Phase 3)
@ -422,21 +459,25 @@ Your UI Roadmap enables:
## Tips for Great Sessions ## Tips for Great Sessions
**Think from dev perspective** **Think from dev perspective**
- What questions will developers have? - What questions will developers have?
- What decisions can't you make for them? - What decisions can't you make for them?
- What context will save them time? - What context will save them time?
**Be explicit about priorities** **Be explicit about priorities**
- Not everything is Priority 1 - Not everything is Priority 1
- Make trade-offs visible - Make trade-offs visible
- Connect priorities to business goals - Connect priorities to business goals
**Document the unknowns** **Document the unknowns**
- Open questions are valuable - Open questions are valuable
- Don't pretend certainty you don't have - Don't pretend certainty you don't have
- Let dev team contribute decisions - Let dev team contribute decisions
**Keep it updated** **Keep it updated**
- Handoff is ongoing, not one-time - Handoff is ongoing, not one-time
- Update as design evolves - Update as design evolves
- Maintain as source of truth - Maintain as source of truth
@ -452,6 +493,7 @@ WDS → E-UI-Roadmap/ → BMM Architecture & Stories
``` ```
The UI Roadmap provides: The UI Roadmap provides:
- Context for architecture decisions - Context for architecture decisions
- Specifications for story creation - Specifications for story creation
- Priorities for sprint planning - 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_

57
src/modules/wds/docs/method/wds-method-guide.md
View File

@ -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: WDS follows six phases, each producing artifacts in your project's `docs/` folder:
### Phase 1: Product Exploration (Product Brief) ### Phase 1: Product Exploration (Product Brief)
**Output:** `A-Product-Brief/` **Output:** `A-Product-Brief/`
**Agent:** Saga the Analyst **Agent:** Saga the Analyst
Establish your strategic foundation through conversational discovery. Instead of filling out questionnaires, you have a conversation that builds understanding organically. Establish your strategic foundation through conversational discovery. Instead of filling out questionnaires, you have a conversation that builds understanding organically.
**What you create:** **What you create:**
- Product vision and problem statement - Product vision and problem statement
- Market positioning and differentiation - Market positioning and differentiation
- Success criteria and metrics - Success criteria and metrics
@ -59,12 +61,14 @@ Establish your strategic foundation through conversational discovery. Instead of
--- ---
### Phase 2: Trigger Mapping (Trigger Map) ### Phase 2: Trigger Mapping (Trigger Map)
**Output:** `B-Trigger-Map/` **Output:** `B-Trigger-Map/`
**Agent:** Saga the Analyst **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. 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:** **What you create:**
- Business goals (Vision + SMART objectives) - Business goals (Vision + SMART objectives)
- Target groups connected to business outcomes - Target groups connected to business outcomes
- Detailed personas with psychological depth - 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) ### Phase 3: PRD Platform (Technical Foundation)
**Output:** `C-Requirements/` **Output:** `C-Requirements/`
**Agent:** Freyja the PM **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. 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:** **What you create:**
- Platform architecture decisions - Platform architecture decisions
- Data model and integrations - Data model and integrations
- Technical proofs of concept - 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) ### Phase 4: UX Design (UX-Sketches & Usage Scenarios)
**Output:** `C-Scenarios/` **Output:** `C-Scenarios/`
**Agent:** Baldr the UX Expert **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. **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:** **What you create:**
- Scenario folder structure (numbered hierarchy) - Scenario folder structure (numbered hierarchy)
- Page specifications with full detail - Page specifications with full detail
- Component definitions with Object IDs - 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) ### Phase 5: Design System (Component Library)
**Output:** `D-Design-System/` **Output:** `D-Design-System/`
**Agent:** Baldr the UX Expert **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. 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:** **What you create:**
- Design tokens (colors, typography, spacing) - Design tokens (colors, typography, spacing)
- Atomic components (buttons, inputs, labels) - Atomic components (buttons, inputs, labels)
- Molecular components (form groups, cards) - 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) ### Phase 6: PRD Finalization (Complete PRD)
**Output:** Complete PRD in `C-Requirements/` + `E-UI-Roadmap/` **Output:** Complete PRD in `C-Requirements/` + `E-UI-Roadmap/`
**Agent:** Freyja the PM **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. 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:** **What you create:**
- Complete PRD (Platform + Functional requirements) - Complete PRD (Platform + Functional requirements)
- Feature organization by epic/area - Feature organization by epic/area
- Development sequence with priorities - Development sequence with priorities
@ -145,14 +157,15 @@ WDS creates an organized folder structure in your project's `docs/` folder. Duri
### Your 4 Options ### Your 4 Options
| Choice | Option A | Option B | | Choice | Option A | Option B |
|--------|----------|----------| | ---------- | -------------------- | ----------------------- |
| **Prefix** | Letters (A, B, C...) | Numbers (01, 02, 03...) | | **Prefix** | Letters (A, B, C...) | Numbers (01, 02, 03...) |
| **Case** | Title-Case | lowercase | | **Case** | Title-Case | lowercase |
### Examples ### Examples
**Letters + Title-Case** (default): **Letters + Title-Case** (default):
``` ```
docs/ docs/
├── A-Product-Brief/ ├── A-Product-Brief/
@ -164,6 +177,7 @@ docs/
``` ```
**Numbers + Title-Case**: **Numbers + Title-Case**:
``` ```
docs/ docs/
├── 01-Product-Brief/ ├── 01-Product-Brief/
@ -175,6 +189,7 @@ docs/
``` ```
**Default (Letters + Title-Case) is recommended because:** **Default (Letters + Title-Case) is recommended because:**
- Title-Case is easier for non-technical people to read - Title-Case is easier for non-technical people to read
- Letters create distinctive WDS branding - Letters create distinctive WDS branding
- Distinguishes WDS folders from other docs - 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: Not every project needs all six phases. Select what you need based on your situation:
| Project Type | Recommended Phases | | Project Type | Recommended Phases |
|--------------|-------------------| | ----------------------------- | ------------------ |
| **Landing page** | 1, 4 | | **Landing page** | 1, 4 |
| **Full product (greenfield)** | All six | | **Full product (greenfield)** | All six |
| **Feature enhancement** | 2, 4, 6 | | **Feature enhancement** | 2, 4, 6 |
| **Design system only** | 4, 5 | | **Design system only** | 4, 5 |
| **Strategic planning** | 1, 2 | | **Strategic planning** | 1, 2 |
| **Quick prototype** | 4 only | | **Quick prototype** | 4 only |
Your agents will help you identify which phases fit your project. 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: Three specialized agents guide you through WDS:
### Saga the Analyst 📚 ### 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. 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:** **Works with you on:**
- Phase 1: Product Exploration - Phase 1: Product Exploration
- Phase 2: Trigger Mapping - Phase 2: Trigger Mapping
### Freyja the PM ⚔️ ### 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. 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:** **Works with you on:**
- Phase 3: PRD Platform - Phase 3: PRD Platform
- Phase 6: PRD Finalization - Phase 6: PRD Finalization
### Baldr the UX Expert ✨ ### 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. 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:** **Works with you on:**
- Phase 4: UX Design - Phase 4: UX Design
- Phase 5: Design System - Phase 5: Design System
@ -238,6 +259,7 @@ WDS sessions are **conversations, not interrogations**.
### The Rhythm ### The Rhythm
A good WDS session feels like coffee with a wise mentor: A good WDS session feels like coffee with a wise mentor:
- They ask something interesting - They ask something interesting
- You share your thinking - You share your thinking
- They reflect it back, maybe adding a new angle - They reflect it back, maybe adding a new angle
@ -248,12 +270,14 @@ It never feels like filling out a form.
### What to Expect ### What to Expect
**Your agent will:** **Your agent will:**
- Ask one question at a time, then listen - Ask one question at a time, then listen
- Reflect back what they heard before moving on - Reflect back what they heard before moving on
- Build documents together with you, piece by piece - Build documents together with you, piece by piece
- Check in to make sure they understood correctly - Check in to make sure they understood correctly
**You'll leave with:** **You'll leave with:**
- Clear documentation you helped create - Clear documentation you helped create
- Deeper understanding of your own product - Deeper understanding of your own product
- Ready-to-use artifacts for the next phase - Ready-to-use artifacts for the next phase
@ -293,6 +317,7 @@ npx bmad-method@alpha install
## The WDS Difference ## The WDS Difference
### Traditional Approach ### Traditional Approach
- 47-question requirements spreadsheet - 47-question requirements spreadsheet
- Generic persona templates - Generic persona templates
- Designers work alone, then throw specs "over the wall" - Designers work alone, then throw specs "over the wall"
@ -300,6 +325,7 @@ npx bmad-method@alpha install
- Everyone argues about what was meant - Everyone argues about what was meant
### WDS Approach ### WDS Approach
- Conversations that build understanding - Conversations that build understanding
- Personas with psychological depth connected to business goals - Personas with psychological depth connected to business goals
- Collaborative workshops building shared understanding - Collaborative workshops building shared understanding
@ -333,6 +359,7 @@ C-Requirements/ ────► C-Requirements/ ────►
### Parallel Streams ### Parallel Streams
Design and development can work in parallel: Design and development can work in parallel:
- Phase 3 complete → Backend/platform development can start - Phase 3 complete → Backend/platform development can start
- Phase 4 MVP scenarios complete → Phase 6 first handoff → Sprint 1 begins - Phase 4 MVP scenarios complete → Phase 6 first handoff → Sprint 1 begins
- Design continues → Regular Phase 6 updates → More sprints - 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_

1
src/modules/wds/getting-started/installation.md
View File

@ -33,6 +33,7 @@ npm start
## Verify Installation ## Verify Installation
You should see: You should see:
``` ```
✅ WDS is running ✅ WDS is running
🎨 Ready to design 🎨 Ready to design

4
src/modules/wds/getting-started/quick-start.md
View File

@ -98,6 +98,7 @@ You: "Perfect!"
## What Just Happened? ## What Just Happened?
You created **why-based specifications** in 5 minutes: You created **why-based specifications** in 5 minutes:
- Connected to user psychology (Trigger Map) - Connected to user psychology (Trigger Map)
- Grounded in real context (Scenario Init) - Grounded in real context (Scenario Init)
- Generated with AI assistance (Agent collaboration) - Generated with AI assistance (Agent collaboration)
@ -108,12 +109,15 @@ You created **why-based specifications** in 5 minutes:
## Next Steps ## Next Steps
### Learn the Concepts ### Learn the Concepts
[Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md) - Deep dive into WDS philosophy [Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md) - Deep dive into WDS philosophy
### Start Your Project ### Start Your Project
[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md) - Full workflow documentation [Workflows Guide](../WDS-WORKFLOWS-GUIDE.md) - Full workflow documentation
### Get Help ### Get Help
[Community](https://discord.gg/whiteport) - Join the WDS community [Community](https://discord.gg/whiteport) - Join the WDS community
--- ---

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

@ -18,6 +18,7 @@ Learn how to be indispensable in the AI era. Understand the paradigm shift where
**Modules 02-16: Complete WDS Workflow** **Modules 02-16: Complete WDS Workflow**
Master every phase from trigger mapping through design system to development handoff. Each module includes: Master every phase from trigger mapping through design system to development handoff. Each module includes:
- **Lessons** - Theory and concepts with NotebookLM audio - **Lessons** - Theory and concepts with NotebookLM audio
- **Tutorials** - Step-by-step hands-on guides - **Tutorials** - Step-by-step hands-on guides
- **Practice** - Apply to your own project - **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)** **[Modular Architecture](../workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md)**
Technical details on: Technical details on:
- Three-tier file structure - Three-tier file structure
- Content placement rules - Content placement rules
- Component decomposition - Component decomposition
@ -98,17 +100,21 @@ Technical details on:
## Community & Support ## Community & Support
### Discord ### Discord
Join the WDS community for: Join the WDS community for:
- Questions and answers - Questions and answers
- Project feedback - Project feedback
- Feature discussions - Feature discussions
### GitHub ### GitHub
- Report issues - Report issues
- Request features - Request features
- Contribute - Contribute
### YouTube ### YouTube
- Video tutorials - Video tutorials
- Walkthroughs - Walkthroughs
- Case studies - Case studies

24
src/modules/wds/templates/design-delivery.template.yaml
View File

@ -2,11 +2,11 @@
# Copy this template to: deliveries/DD-XXX-name.yaml # Copy this template to: deliveries/DD-XXX-name.yaml
delivery: delivery:
id: "DD-XXX" # Format: DD-001, DD-002, etc. id: "DD-XXX" # Format: DD-001, DD-002, etc.
name: "Feature Name" # Human-readable name name: "Feature Name" # Human-readable name
type: "user_flow" # user_flow | feature | component type: "user_flow" # user_flow | feature | component
status: "ready" # ready | in_progress | blocked status: "ready" # ready | in_progress | blocked
priority: "high" # high | medium | low priority: "high" # high | medium | low
created_by: "wds-ux-expert" created_by: "wds-ux-expert"
created_at: "YYYY-MM-DDTHH:MM:SSZ" created_at: "YYYY-MM-DDTHH:MM:SSZ"
updated_at: "YYYY-MM-DDTHH:MM:SSZ" updated_at: "YYYY-MM-DDTHH:MM:SSZ"
@ -48,13 +48,13 @@ design_artifacts:
technical_requirements: technical_requirements:
platform: platform:
frontend: "framework-name" # From platform-requirements.yaml frontend: "framework-name" # From platform-requirements.yaml
backend: "framework-name" # From platform-requirements.yaml backend: "framework-name" # From platform-requirements.yaml
integrations: integrations:
- name: "integration-name" - name: "integration-name"
purpose: "[Why this integration is needed]" purpose: "[Why this integration is needed]"
required: true # true | false required: true # true | false
- name: "integration-name" - name: "integration-name"
purpose: "[Why this integration is needed]" purpose: "[Why this integration is needed]"
@ -94,10 +94,10 @@ testing_guidance:
- "[QA testing instruction 3]" - "[QA testing instruction 3]"
estimated_complexity: estimated_complexity:
size: "medium" # small | medium | large size: "medium" # small | medium | large
effort: "2-3 weeks" # Time estimate effort: "2-3 weeks" # Time estimate
risk: "low" # low | medium | high risk: "low" # low | medium | high
dependencies: [] # List of DD-XXX IDs needed first dependencies: [] # List of DD-XXX IDs needed first
notes: | notes: |
[Any special considerations, important context, or [Any special considerations, important context, or

36
src/modules/wds/templates/platform-requirements.template.yaml
View File

@ -3,42 +3,42 @@
project: project:
name: "Project Name" 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" wds_version: "6.0"
created_at: "YYYY-MM-DDTHH:MM:SSZ" created_at: "YYYY-MM-DDTHH:MM:SSZ"
platform: platform:
frontend: frontend:
framework: "framework-name" # react_native | react | vue | angular | svelte framework: "framework-name" # react_native | react | vue | angular | svelte
version: "X.X" version: "X.X"
state_management: "library" # zustand | redux | mobx | context state_management: "library" # zustand | redux | mobx | context
navigation: "library" # react_navigation | react_router | vue_router navigation: "library" # react_navigation | react_router | vue_router
styling: "approach" # tailwind | styled_components | css_modules styling: "approach" # tailwind | styled_components | css_modules
ui_library: "library" # shadcn | mui | chakra (optional) ui_library: "library" # shadcn | mui | chakra (optional)
backend: backend:
framework: "framework-name" # supabase | firebase | express | fastapi | django framework: "framework-name" # supabase | firebase | express | fastapi | django
version: "X.X" version: "X.X"
auth: "auth-provider" # supabase_auth | firebase_auth | auth0 | custom auth: "auth-provider" # supabase_auth | firebase_auth | auth0 | custom
database: "database-type" # postgresql | mysql | mongodb | firestore database: "database-type" # postgresql | mysql | mongodb | firestore
storage: "storage-provider" # supabase_storage | s3 | cloudinary storage: "storage-provider" # supabase_storage | s3 | cloudinary
api: "api-type" # rest | graphql | grpc api: "api-type" # rest | graphql | grpc
database: database:
type: "database-type" # postgresql | mysql | mongodb type: "database-type" # postgresql | mysql | mongodb
version: "XX" version: "XX"
orm: "orm-library" # prisma | typeorm | mongoose (optional) orm: "orm-library" # prisma | typeorm | mongoose (optional)
deployment: deployment:
frontend: "platform" # expo_eas | vercel | netlify | aws frontend: "platform" # expo_eas | vercel | netlify | aws
backend: "platform" # supabase_cloud | firebase | heroku | aws backend: "platform" # supabase_cloud | firebase | heroku | aws
ci_cd: "platform" # github_actions | gitlab_ci | circle_ci ci_cd: "platform" # github_actions | gitlab_ci | circle_ci
hosting: "platform" # vercel | netlify | aws (if web app) hosting: "platform" # vercel | netlify | aws (if web app)
integrations: integrations:
- name: "integration-name" - name: "integration-name"
provider: "provider-name" provider: "provider-name"
required: true # true | false required: true # true | false
purpose: "[Why this integration is needed]" purpose: "[Why this integration is needed]"
- name: "integration-name" - name: "integration-name"

14
src/modules/wds/templates/test-scenario.template.yaml
View File

@ -2,12 +2,12 @@
# Save to: test-scenarios/TS-XXX-name.yaml # Save to: test-scenarios/TS-XXX-name.yaml
test_scenario: test_scenario:
id: "TS-XXX" # Format: TS-001, TS-002, etc. id: "TS-XXX" # Format: TS-001, TS-002, etc.
name: "Feature Testing" # Human-readable name name: "Feature Testing" # Human-readable name
delivery_id: "DD-XXX" # Related Design Delivery delivery_id: "DD-XXX" # Related Design Delivery
type: "user_acceptance" # user_acceptance | integration | e2e type: "user_acceptance" # user_acceptance | integration | e2e
status: "ready" # ready | in_progress | blocked status: "ready" # ready | in_progress | blocked
tester: "designer" # designer | qa | developer tester: "designer" # designer | qa | developer
created_at: "YYYY-MM-DDTHH:MM:SSZ" created_at: "YYYY-MM-DDTHH:MM:SSZ"
test_objectives: test_objectives:
@ -30,7 +30,7 @@ test_environment:
happy_path: happy_path:
- id: "HP-001" - id: "HP-001"
name: "Main User Flow" name: "Main User Flow"
priority: "critical" # critical | high | medium | low priority: "critical" # critical | high | medium | low
steps: steps:
- action: "[User action]" - action: "[User action]"

28
src/modules/wds/tutorial/00-TUTORIAL-GUIDE.md
View File

@ -9,11 +9,13 @@
This tutorial teaches the complete WDS workflow through **16 chapters**. This tutorial teaches the complete WDS workflow through **16 chapters**.
Each chapter contains: Each chapter contains:
- **Inspiration** - Why this step matters, the goal - **Inspiration** - Why this step matters, the goal
- **Teaching** - How to do it with confidence - **Teaching** - How to do it with confidence
- **Practice** - Apply it to your own project - **Practice** - Apply it to your own project
**Format:** **Format:**
- Read as documentation - Read as documentation
- Generate videos with NotebookLM - Generate videos with NotebookLM
- Use in workshops - Use in workshops
@ -27,6 +29,7 @@ Each chapter contains:
### Foundation ### Foundation
#### [Chapter 0: Why This Matters](chapter-00-why-this-matters/) #### [Chapter 0: Why This Matters](chapter-00-why-this-matters/)
Learn how to be indispensable in the AI era 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 ### Phase 1: Project Brief
#### [Chapter 1.1: Create Project Brief](chapter-1.1-project-brief/) #### [Chapter 1.1: Create Project Brief](chapter-1.1-project-brief/)
Define vision, goals, stakeholders, and constraints Define vision, goals, stakeholders, and constraints
--- ---
@ -41,12 +45,15 @@ Define vision, goals, stakeholders, and constraints
### Phase 2: Trigger Mapping ### Phase 2: Trigger Mapping
#### [Chapter 2.1: Identify Target Groups](chapter-2.1-identify-target-groups/) #### [Chapter 2.1: Identify Target Groups](chapter-2.1-identify-target-groups/)
WHO are your users and how to prioritize them WHO are your users and how to prioritize them
#### [Chapter 2.2: Map Triggers & Outcomes](chapter-2.2-map-triggers-outcomes/) #### [Chapter 2.2: Map Triggers & Outcomes](chapter-2.2-map-triggers-outcomes/)
WHAT triggers needs and WHY your business exists WHAT triggers needs and WHY your business exists
#### [Chapter 2.3: Prioritize Features](chapter-2.3-prioritize-features/) #### [Chapter 2.3: Prioritize Features](chapter-2.3-prioritize-features/)
Which features serve your top triggers Which features serve your top triggers
--- ---
@ -54,9 +61,11 @@ Which features serve your top triggers
### Phase 3: Platform Requirements ### Phase 3: Platform Requirements
#### [Chapter 3.1: Platform Requirements](chapter-3.1-platform-requirements/) #### [Chapter 3.1: Platform Requirements](chapter-3.1-platform-requirements/)
Technical constraints, integrations, infrastructure Technical constraints, integrations, infrastructure
#### [Chapter 3.2: Functional Requirements](chapter-3.2-functional-requirements/) #### [Chapter 3.2: Functional Requirements](chapter-3.2-functional-requirements/)
What the system must do What the system must do
--- ---
@ -64,21 +73,27 @@ What the system must do
### Phase 4: Conceptual Design ### Phase 4: Conceptual Design
#### [Chapter 4.1: Initialize Scenario](chapter-4.1-initialize-scenario/) #### [Chapter 4.1: Initialize Scenario](chapter-4.1-initialize-scenario/)
The 5 questions that define your design journey The 5 questions that define your design journey
#### [Chapter 4.2: Sketch Interfaces](chapter-4.2-sketch-interfaces/) #### [Chapter 4.2: Sketch Interfaces](chapter-4.2-sketch-interfaces/)
Drawing pages with AI guidance Drawing pages with AI guidance
#### [Chapter 4.3: Analyze with AI](chapter-4.3-analyze-with-ai/) #### [Chapter 4.3: Analyze with AI](chapter-4.3-analyze-with-ai/)
Upload sketches and have strategic conversations Upload sketches and have strategic conversations
#### [Chapter 4.4: Decompose Components](chapter-4.4-decompose-components/) #### [Chapter 4.4: Decompose Components](chapter-4.4-decompose-components/)
Break pages into modular architecture Break pages into modular architecture
#### [Chapter 4.5: Why-Based Specifications](chapter-4.5-why-based-specs/) #### [Chapter 4.5: Why-Based Specifications](chapter-4.5-why-based-specs/)
Document WHAT + WHY + WHAT NOT TO DO Document WHAT + WHY + WHAT NOT TO DO
#### [Chapter 4.6: Validate Specifications](chapter-4.6-validate-specifications/) #### [Chapter 4.6: Validate Specifications](chapter-4.6-validate-specifications/)
Review completeness and test logic Review completeness and test logic
--- ---
@ -86,9 +101,11 @@ Review completeness and test logic
### Phase 5: Design System ### Phase 5: Design System
#### [Chapter 5.1: Extract Design Tokens](chapter-5.1-extract-design-tokens/) #### [Chapter 5.1: Extract Design Tokens](chapter-5.1-extract-design-tokens/)
Colors, typography, spacing from your specs Colors, typography, spacing from your specs
#### [Chapter 5.2: Component Library](chapter-5.2-component-library/) #### [Chapter 5.2: Component Library](chapter-5.2-component-library/)
Reusable patterns across scenarios Reusable patterns across scenarios
--- ---
@ -96,6 +113,7 @@ Reusable patterns across scenarios
### Phase 6: Development Integration ### Phase 6: Development Integration
#### [Chapter 6.1: UI Roadmap](chapter-6.1-ui-roadmap/) #### [Chapter 6.1: UI Roadmap](chapter-6.1-ui-roadmap/)
Development priorities and handoff Development priorities and handoff
--- ---
@ -103,7 +121,9 @@ Development priorities and handoff
## How to Use This Tutorial ## How to Use This Tutorial
### Complete Workflow (Recommended) ### Complete Workflow (Recommended)
Work through all 16 chapters sequentially with your own project: Work through all 16 chapters sequentially with your own project:
``` ```
Chapters 1-16 → Complete design from brief to handoff Chapters 1-16 → Complete design from brief to handoff
Time: ~10 hours (spread over days/weeks) Time: ~10 hours (spread over days/weeks)
@ -111,7 +131,9 @@ Result: Fully specified project ready for development
``` ```
### Quick Start (Core Concepts) ### Quick Start (Core Concepts)
Focus on the essential chapters: Focus on the essential chapters:
``` ```
Ch 0: Why This Matters Ch 0: Why This Matters
Ch 2.2: Map Triggers & Outcomes Ch 2.2: Map Triggers & Outcomes
@ -122,7 +144,9 @@ Result: Understanding of core WDS philosophy
``` ```
### Phase-Specific Learning ### Phase-Specific Learning
Jump to the phase you need: Jump to the phase you need:
``` ```
Phase 2 (Ch 2.1-2.3): Trigger Mapping Phase 2 (Ch 2.1-2.3): Trigger Mapping
Phase 4 (Ch 4.1-4.6): Conceptual Design Phase 4 (Ch 4.1-4.6): Conceptual Design
@ -134,6 +158,7 @@ Phase 5 (Ch 5.1-5.2): Design System
## NotebookLM Integration ## NotebookLM Integration
Each chapter has a matching script in `/notebooklm-scripts/`: Each chapter has a matching script in `/notebooklm-scripts/`:
- Feed chapter scripts to NotebookLM - Feed chapter scripts to NotebookLM
- Generate audio podcasts - Generate audio podcasts
- Generate video presentations - Generate video presentations
@ -148,16 +173,19 @@ Each chapter has a matching script in `/notebooklm-scripts/`:
Every chapter follows the same pattern: Every chapter follows the same pattern:
**1. Inspiration (10 min)** **1. Inspiration (10 min)**
- Why this step matters - Why this step matters
- The goal you're working toward - The goal you're working toward
- Real-world impact - Real-world impact
**2. Teaching (20 min)** **2. Teaching (20 min)**
- How to do it with confidence - How to do it with confidence
- AI support at each step - AI support at each step
- Dog Week example walkthrough - Dog Week example walkthrough
**3. Practice (10 min)** **3. Practice (10 min)**
- Apply to your own project - Apply to your own project
- Step-by-step instructions - Step-by-step instructions
- Success criteria - Success criteria

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

@ -9,11 +9,13 @@
Designers operate across **5 simultaneous dimensions** that AI and traditional developers cannot navigate alone: Designers operate across **5 simultaneous dimensions** that AI and traditional developers cannot navigate alone:
### 1. Business Existence (WHY) ### 1. Business Existence (WHY)
- Why does this business exist? - Why does this business exist?
- What problem does it solve in the world? - What problem does it solve in the world?
- What value does it create? - What value does it create?
**Example (Dog Week):** **Example (Dog Week):**
``` ```
WHY: Families struggle to coordinate dog care responsibilities. WHY: Families struggle to coordinate dog care responsibilities.
VALUE: Reduce conflict, increase accountability, happier dogs. 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) ### 2. Business Goals (WHAT SUCCESS LOOKS LIKE)
- What metrics matter? - What metrics matter?
- What behaviors do we want to encourage? - What behaviors do we want to encourage?
- What outcomes define success? - What outcomes define success?
**Example (Dog Week):** **Example (Dog Week):**
``` ```
GOALS: GOALS:
- Increase walk completion rate (not just bookings) - Increase walk completion rate (not just bookings)
@ -37,11 +41,13 @@ GOALS:
--- ---
### 3. Product Strategy (HOW WE DELIVER VALUE) ### 3. Product Strategy (HOW WE DELIVER VALUE)
- What features serve the goals? - What features serve the goals?
- What's the core experience? - What's the core experience?
- What can we cut? - What can we cut?
**Example (Dog Week):** **Example (Dog Week):**
``` ```
CORE: Week-based planning (Swedish culture) CORE: Week-based planning (Swedish culture)
FEATURES: Calendar, leaderboard, countdown timers 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) ### 4. Target Groups & Individual Needs (WHO & THEIR CONTEXT)
- Who are the users? - Who are the users?
- What are their different needs? - What are their different needs?
- What contexts do they operate in? - What contexts do they operate in?
**Example (Dog Week):** **Example (Dog Week):**
``` ```
USERS: USERS:
- Parents: Need overview, accountability tracking - Parents: Need overview, accountability tracking
@ -71,11 +79,13 @@ CONTEXTS:
--- ---
### 5. User Experience Translation (HOW USERS UNDERSTAND) ### 5. User Experience Translation (HOW USERS UNDERSTAND)
- How do we make this simple? - How do we make this simple?
- What mental models do users have? - What mental models do users have?
- What's intuitive vs confusing? - What's intuitive vs confusing?
**Example (Dog Week):** **Example (Dog Week):**
``` ```
TRANSLATION: TRANSLATION:
- Week circles (not dates) → Matches Swedish "Vecka 40" thinking - Week circles (not dates) → Matches Swedish "Vecka 40" thinking
@ -111,6 +121,7 @@ Technical Specs
## Why This Is Designer Work ## Why This Is Designer Work
### Engineers Think: ### Engineers Think:
- "How do I build this?" - "How do I build this?"
- "What's the data structure?" - "What's the data structure?"
- "What API endpoints do I need?" - "What API endpoints do I need?"
@ -118,6 +129,7 @@ Technical Specs
**Missing:** WHY this feature? WHO needs it? WHAT behavior change? **Missing:** WHY this feature? WHO needs it? WHAT behavior change?
### Business Developers Think: ### Business Developers Think:
- "What features will sell?" - "What features will sell?"
- "What's the ROI?" - "What's the ROI?"
- "What's the market opportunity?" - "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? **Missing:** HOW do users actually think? WHAT's intuitive? HOW do we translate goals to experience?
### AI Thinks: ### AI Thinks:
- "What patterns match this prompt?" - "What patterns match this prompt?"
- "What code structure fits this description?" - "What code structure fits this description?"
- "What's the most common implementation?" - "What's the most common implementation?"
@ -150,15 +163,19 @@ Technical Specs
## Example: Dog Week Calendar States ## Example: Dog Week Calendar States
### Business Developer Says: ### Business Developer Says:
"We need a booking system with accountability tracking." "We need a booking system with accountability tracking."
### Engineer Says: ### Engineer Says:
"I'll build a CRUD app with status fields: pending, active, completed." "I'll build a CRUD app with status fields: pending, active, completed."
### AI Says: ### AI Says:
"Here's a calendar with booking slots and status indicators." "Here's a calendar with booking slots and status indicators."
### Designer Says: ### Designer Says:
``` ```
WAIT. Let's think through all 5 dimensions: WAIT. Let's think through all 5 dimensions:
@ -204,6 +221,7 @@ Working Product
``` ```
**Without the designer's translation:** **Without the designer's translation:**
- Engineers build what's easy, not what's needed - Engineers build what's easy, not what's needed
- Business developers add features that don't serve users - Business developers add features that don't serve users
- AI generates generic solutions that miss the context - AI generates generic solutions that miss the context
@ -213,11 +231,13 @@ Working Product
## Why AI Makes Designers MORE Important ## Why AI Makes Designers MORE Important
**Before AI:** **Before AI:**
- Designers → Specs → Developers → Code (slow) - Designers → Specs → Developers → Code (slow)
- Designers had to compromise due to dev time - Designers had to compromise due to dev time
- "We can't build that, too complex" - "We can't build that, too complex"
**With AI:** **With AI:**
- Designers → Specs → AI → Code (fast) - Designers → Specs → AI → Code (fast)
- Designers can specify the RIGHT solution - Designers can specify the RIGHT solution
- "AI can build anything, what SHOULD we build?" - "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." **Story:** "Dog care is a family responsibility, and we make it fun and fair."
**Touchpoints:** **Touchpoints:**
- **Week view:** Shows family's shared responsibility (not individual calendars) - **Week view:** Shows family's shared responsibility (not individual calendars)
- **Leaderboard:** Makes accountability fun (not punishing) - **Leaderboard:** Makes accountability fun (not punishing)
- **Color states:** Visual clarity (not confusing text) - **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) - **Booking flow:** Simple for kids (not complex admin)
**If any touchpoint breaks the story:** **If any touchpoint breaks the story:**
- Leaderboard shows "failures" → Punishing, not fun → Story breaks - Leaderboard shows "failures" → Punishing, not fun → Story breaks
- Countdown sends notifications → Nagging, not gentle → Story breaks - Countdown sends notifications → Nagging, not gentle → Story breaks
- Week view shows daily → Doesn't match mental model → 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.** **With or without AI, this multi-dimensional thinking is irreplaceable.**
**AI makes it MORE valuable:** **AI makes it MORE valuable:**
- Implementation is fast → Specification becomes critical - Implementation is fast → Specification becomes critical
- Anyone can generate code → Knowing WHAT to build becomes the differentiator - Anyone can generate code → Knowing WHAT to build becomes the differentiator
- Features are cheap → Coherent experience becomes the competitive advantage - Features are cheap → Coherent experience becomes the competitive advantage
**The designer who can:** **The designer who can:**
- Think across all 5 dimensions - Think across all 5 dimensions
- Maintain coherent storylines - Maintain coherent storylines
- Translate complexity into simplicity - Translate complexity into simplicity
@ -300,6 +324,7 @@ Layer 7: How do we make it implementable?
**You're not just designing interfaces.** **You're not just designing interfaces.**
**You're architecting:** **You're architecting:**
- Business value delivery - Business value delivery
- User behavior change - User behavior change
- Product strategy - Product strategy

22
src/modules/wds/tutorial/02-wds-concept.md
View File

@ -18,6 +18,7 @@ In the last video, we talked about why designers are irreplaceable in the AI era
### Traditional Design Handoff Nightmare ### Traditional Design Handoff Nightmare
**Recognize this disaster?** **Recognize this disaster?**
- You create gorgeous designs in isolation - You create gorgeous designs in isolation
- Designs disappear into "design backlog purgatory" - Designs disappear into "design backlog purgatory"
- Months later, developers build something vaguely similar - 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. But if you're unclear, AI starts hallucinating and leaves your project in a death spiral.
**The new reality:** **The new reality:**
- 🎯 Clear specifications = Perfect AI implementation - 🎯 Clear specifications = Perfect AI implementation
- 🌪️ Unclear specifications = AI hallucination death spiral - 🌪️ 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.** **WDS is a specification-first design system.**
Instead of: Instead of:
``` ```
Sketch → Hope developers understand → Fix in QA Sketch → Hope developers understand → Fix in QA
``` ```
WDS gives you: WDS gives you:
``` ```
Trigger Map → Scenario Init → Sketch → Why-Based Specs → AI Implementation 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**. There is no longer a bottleneck in writing code. The bottleneck is **knowing what to build**.
And that requires: And that requires:
- Understanding user psychology (Trigger Map) - Understanding user psychology (Trigger Map)
- Defining the journey (Scenario Init) - Defining the journey (Scenario Init)
- Capturing design intent (Why-Based Specs) - Capturing design intent (Why-Based Specs)
@ -73,11 +78,13 @@ And that requires:
### WDS = Designer + AI Partnership ### WDS = Designer + AI Partnership
**WDS is not:** **WDS is not:**
- ❌ AI replacing designers - ❌ AI replacing designers
- ❌ Automated design generation - ❌ Automated design generation
- ❌ Generic template system - ❌ Generic template system
**WDS is:** **WDS is:**
- ✅ AI amplifying designer thinking - ✅ AI amplifying designer thinking
- ✅ Socratic questioning to elevate decisions - ✅ Socratic questioning to elevate decisions
- ✅ Why-based specifications that preserve intent - ✅ Why-based specifications that preserve intent
@ -89,6 +96,7 @@ And that requires:
### 1. Socratic Questioning ### 1. Socratic Questioning
**Traditional AI:** **Traditional AI:**
``` ```
You: "Create a calendar" You: "Create a calendar"
AI: *Generates generic calendar* AI: *Generates generic calendar*
@ -96,6 +104,7 @@ You: "No, that's not right..."
``` ```
**WDS Agent:** **WDS Agent:**
``` ```
You: "I need a calendar" You: "I need a calendar"
Agent: "Help me understand - why week view instead of daily?" Agent: "Help me understand - why week view instead of daily?"
@ -112,14 +121,17 @@ You: "Exactly!"
### 2. Why-Based Specifications ### 2. Why-Based Specifications
**Traditional Spec:** **Traditional Spec:**
```markdown ```markdown
## Calendar Component ## Calendar Component
- Week view - Week view
- 7 columns (days) - 7 columns (days)
- Color-coded states - Color-coded states
``` ```
**WDS Why-Based Spec:** **WDS Why-Based Spec:**
```markdown ```markdown
## Calendar Component ## Calendar Component
@ -146,12 +158,14 @@ Notifications would break the "fun, not punishing" tone.
### 3. Modular Architecture ### 3. Modular Architecture
**Traditional approach:** **Traditional approach:**
``` ```
One giant specification file (800 lines) One giant specification file (800 lines)
├─ Layout + Visual + Logic + API + Content ├─ Layout + Visual + Logic + API + Content
``` ```
**WDS Modular Architecture:** **WDS Modular Architecture:**
``` ```
Pages/02-calendar-page.md (100 lines) Pages/02-calendar-page.md (100 lines)
├─ WHERE: Page context, layout, content ├─ WHERE: Page context, layout, content
@ -164,6 +178,7 @@ Features/walk-booking-logic.feature.md (200 lines)
``` ```
**The difference:** **The difference:**
- Clear separation of concerns - Clear separation of concerns
- Easy to maintain and update - Easy to maintain and update
- Clean handoffs to specialists - Clean handoffs to specialists
@ -176,6 +191,7 @@ Features/walk-booking-logic.feature.md (200 lines)
### The Complete Flow ### The Complete Flow
**Phase 1: Trigger Map** **Phase 1: Trigger Map**
``` ```
WHO: Parents (need accountability) WHO: Parents (need accountability)
TRIGGER: Family conflict over dog care TRIGGER: Family conflict over dog care
@ -184,6 +200,7 @@ FEATURE: Family dog walk calendar
``` ```
**Phase 2: Scenario Init** **Phase 2: Scenario Init**
``` ```
Entry Point: Google search (frustrated) Entry Point: Google search (frustrated)
Mental State: Tired of nagging, want simple solution Mental State: Tired of nagging, want simple solution
@ -192,6 +209,7 @@ Shortest Path: Landing → Sign up → Setup → Calendar → First walk
``` ```
**Phase 3: Sketch** **Phase 3: Sketch**
``` ```
You: [Upload sketch of calendar page] You: [Upload sketch of calendar page]
Agent: "I see: Week view, leaderboard, countdown timers. 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** **Phase 4: Why-Based Specifications**
``` ```
Agent: "Why week view instead of daily?" Agent: "Why week view instead of daily?"
You: "Swedish families think in weeks..." You: "Swedish families think in weeks..."
@ -208,6 +227,7 @@ Agent: "Perfect! Documenting:
``` ```
**Phase 5: AI Implementation** **Phase 5: AI Implementation**
``` ```
AI: *Implements exactly as specified* AI: *Implements exactly as specified*
*Skips "helpful" features that would break intent* *Skips "helpful" features that would break intent*
@ -247,6 +267,7 @@ AI: *Implements exactly as specified*
5. **Designer-AI Partnership** - Amplification, not replacement 5. **Designer-AI Partnership** - Amplification, not replacement
**The result:** **The result:**
- AI implements correctly first time - AI implements correctly first time
- Design intent is preserved - Design intent is preserved
- Specifications become design knowledge - 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. In the next video, we'll dive into the **BMad Method** - the systematic approach that makes WDS possible.
You'll learn: You'll learn:
- The 4 phases of design thinking - The 4 phases of design thinking
- How each phase builds on the previous - How each phase builds on the previous
- Why this method works with AI - Why this method works with AI

3
src/modules/wds/tutorial/README-DEPRECATED.md
View File

@ -34,17 +34,20 @@ course/
## Why the Change? ## Why the Change?
**Benefits:** **Benefits:**
- ✅ Single learning path - everything in one place - ✅ Single learning path - everything in one place
- ✅ Module-specific tutorials - tutorial right where you need it - ✅ Module-specific tutorials - tutorial right where you need it
- ✅ Cleaner structure - no separate tutorial folder - ✅ Cleaner structure - no separate tutorial folder
- ✅ Better organization - theory + practice together - ✅ Better organization - theory + practice together
**Old approach:** **Old approach:**
- Separate tutorial folder - Separate tutorial folder
- Disconnected from course content - Disconnected from course content
- Harder to navigate - Harder to navigate
**New approach:** **New approach:**
- Tutorials integrated into modules - Tutorials integrated into modules
- Theory → Tutorial → Practice flow - Theory → Tutorial → Practice flow
- Easier to follow - Easier to follow

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

@ -1,4 +1,5 @@
# Chapter 0: Why WDS Matters # Chapter 0: Why WDS Matters
## Part 1: Inspiration ## Part 1: Inspiration
**Learn how to be indispensable in the AI era** **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. 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:** **What makes an irreplaceable designer:**
- Connects disparate ideas across business, psychology, and technology - Connects disparate ideas across business, psychology, and technology
- Makes things happen when there's no instruction manual - Makes things happen when there's no instruction manual
- Creates value that can't be commoditized or automated - 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. 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:** **Your transformation:**
- ✅ Understand why designers are irreplaceable in the AI era - ✅ Understand why designers are irreplaceable in the AI era
- ✅ Master the 5 dimensions of designer thinking - ✅ Master the 5 dimensions of designer thinking
- ✅ Recognize what AI can and cannot do - ✅ 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. 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:** **The factory mindset in design:**
- Creates mockups by following briefs (instructions) - Creates mockups by following briefs (instructions)
- Hands off to developers (replaceable step) - Hands off to developers (replaceable step)
- Hopes they understand (no real connection) - 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. 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:** **What AI does better than cogs:**
- Generates mockups instantly (no creative block) - Generates mockups instantly (no creative block)
- Follows design systems perfectly (zero deviation) - Follows design systems perfectly (zero deviation)
- Iterates through hundreds of variations (no fatigue) - 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. 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):** **What makes products come alive (what only designers can do):**
- Navigate 5 dimensions to find the human truth at the intersection - Navigate 5 dimensions to find the human truth at the intersection
- Make judgment calls that create emotional resonance, not just functionality - Make judgment calls that create emotional resonance, not just functionality
- Build trust through decisions that show someone cared - 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. 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:** **The irreplaceable designer:**
- Transforms complexity into clarity - Transforms complexity into clarity
- Invents solutions nobody expected - Invents solutions nobody expected
- Bridges business, psychology, and technology - 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. 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:** **The designer as gatekeeper:**
- Catches AI's confident but ridiculous mistakes before they ship - Catches AI's confident but ridiculous mistakes before they ship
- Evaluates if solutions actually make logical sense - Evaluates if solutions actually make logical sense
- Ensures business goals don't contradict user needs - 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. 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:** **The designer's transformation:**
- **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage - **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage
- **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely - **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely
- **Result:** From replaceable cog to indispensable gatekeeper - your design IS the product - **Result:** From replaceable cog to indispensable gatekeeper - your design IS the product
@ -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. You'll become the designer who makes things happen. The one they can't do without. The linchpin designer.
**Your transformation as a designer:** **Your transformation as a designer:**
- **Before:** Threatened, uncertain, frustrated, limited, replaceable - **Before:** Threatened, uncertain, frustrated, limited, replaceable
- **After:** Confident, clear, empowered, unstoppable, indispensable - **After:** Confident, clear, empowered, unstoppable, indispensable
- **Result:** The designer who makes things happen - **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. 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:** **The comparison:**
- **Traditional (cog designer):** 26 weeks → Mediocre result → Intent lost - **Traditional (cog designer):** 26 weeks → Mediocre result → Intent lost
- **WDS (linchpin designer):** 5 weeks → Exceptional result → Intent preserved - **WDS (linchpin designer):** 5 weeks → Exceptional result → Intent preserved
- **Key difference:** Designer's user-centric creativity captured and amplified - **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? ## Ready to Begin?
**Before you start, check the practicalities:** **Before you start, check the practicalities:**
- What skills you need (spoiler: you already have them) - What skills you need (spoiler: you already have them)
- Time investment and learning paths - Time investment and learning paths
- Tools required (mostly free) - 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:** **Or jump straight into the methodology:**
In the next section (Teaching), you'll learn the concrete methodology: In the next section (Teaching), you'll learn the concrete methodology:
- The 5 dimensions in detail with examples - The 5 dimensions in detail with examples
- What AI cannot do (and what it can) - What AI cannot do (and what it can)
- Why specifications are the new code - Why specifications are the new code

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

@ -1,4 +1,5 @@
# Chapter 0: Why WDS Matters # Chapter 0: Why WDS Matters
## Part 4: Practicalities ## Part 4: Practicalities
**Everything you need to know before starting** **Everything you need to know before starting**
@ -10,12 +11,14 @@
### What Skills You Need ### What Skills You Need
**Required (you probably already have these):** **Required (you probably already have these):**
- Basic design thinking and UX principles - Basic design thinking and UX principles
- Ability to sketch interfaces (hand-drawn or digital) - Ability to sketch interfaces (hand-drawn or digital)
- Understanding of user needs and business goals - Understanding of user needs and business goals
- Willingness to think deeply about WHY - Willingness to think deeply about WHY
**NOT required:** **NOT required:**
- ❌ Coding skills - ❌ Coding skills
- ❌ Advanced technical knowledge - ❌ Advanced technical knowledge
- ❌ Experience with AI tools - ❌ Experience with AI tools
@ -30,17 +33,20 @@
### How Long Does It Take? ### How Long Does It Take?
**Total tutorial time:** ~10 hours **Total tutorial time:** ~10 hours
- Spread over days or weeks at your own pace - Spread over days or weeks at your own pace
- Each chapter: 30-40 minutes - Each chapter: 30-40 minutes
- Practice exercises: 1-2 hours per chapter - Practice exercises: 1-2 hours per chapter
**Breakdown:** **Breakdown:**
- **Week 1-2:** Foundation chapters (0-2.3) - Understanding the methodology - **Week 1-2:** Foundation chapters (0-2.3) - Understanding the methodology
- **Week 3-4:** Core workflow (4.1-4.6) - Learning specification creation - **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 - **Week 5-6:** Advanced topics (5.1-6.1) - Design systems and handoff
- **Ongoing:** Practice with your own projects - **Ongoing:** Practice with your own projects
**Real-world application:** **Real-world application:**
- First project with WDS: 2-3x slower than your usual process (learning curve) - First project with WDS: 2-3x slower than your usual process (learning curve)
- Second project: Same speed as traditional approach - Second project: Same speed as traditional approach
- Third project onwards: 3-5x faster with better quality - Third project onwards: 3-5x faster with better quality
@ -52,22 +58,27 @@
### Essential Tools ### Essential Tools
**For sketching:** **For sketching:**
- Paper and pen (seriously, this works best) - Paper and pen (seriously, this works best)
- OR digital sketching tool (Excalidraw, Figma, iPad + Pencil) - OR digital sketching tool (Excalidraw, Figma, iPad + Pencil)
**For AI assistance:** **For AI assistance:**
- Access to Claude, ChatGPT, or similar AI assistant - Access to Claude, ChatGPT, or similar AI assistant
- Free tier is sufficient to start - Free tier is sufficient to start
**For documentation:** **For documentation:**
- Text editor (VS Code recommended, but any will work) - Text editor (VS Code recommended, but any will work)
- Markdown support (built into most modern editors) - Markdown support (built into most modern editors)
**For collaboration:** **For collaboration:**
- Git/GitHub (optional but recommended) - Git/GitHub (optional but recommended)
- Shared folder system (Google Drive, Dropbox, etc.) - Shared folder system (Google Drive, Dropbox, etc.)
**Total cost to get started:** $0-20/month **Total cost to get started:** $0-20/month
- Free tier AI tools work fine - Free tier AI tools work fine
- Paid AI subscriptions ($20/month) provide better experience but aren't required - 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: By the end of this tutorial, you'll have created:
**1. Complete Project Brief** **1. Complete Project Brief**
- Vision and goals clearly defined - Vision and goals clearly defined
- Stakeholders and constraints documented - Stakeholders and constraints documented
- Foundation for all design decisions - Foundation for all design decisions
**2. Trigger Map** **2. Trigger Map**
- Target groups identified and prioritized - Target groups identified and prioritized
- User triggers and outcomes mapped - User triggers and outcomes mapped
- Features prioritized by impact - Features prioritized by impact
**3. Scenario Specifications** **3. Scenario Specifications**
- At least one complete user scenario - At least one complete user scenario
- Why-based specifications for key components - Why-based specifications for key components
- AI-ready documentation - AI-ready documentation
**4. Design System Foundation** **4. Design System Foundation**
- Design tokens extracted from your specs - Design tokens extracted from your specs
- Component patterns identified - Component patterns identified
- Reusable architecture defined - Reusable architecture defined
@ -108,6 +123,7 @@ By the end of this tutorial, you'll have created:
### Choose Your Journey ### Choose Your Journey
**Option 1: Full Immersion (Recommended)** **Option 1: Full Immersion (Recommended)**
- Complete all 16 chapters in order - Complete all 16 chapters in order
- Practice exercises for each chapter - Practice exercises for each chapter
- Apply to a real project as you learn - 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 - **Best for:** Designers who want to master the methodology
**Option 2: Quick Start** **Option 2: Quick Start**
- Focus on core chapters (0, 2.2, 4.1, 4.5) - Focus on core chapters (0, 2.2, 4.1, 4.5)
- Skip advanced topics initially - Skip advanced topics initially
- Get started fast, learn more later - 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 - **Best for:** Designers who need results quickly
**Option 3: Self-Paced** **Option 3: Self-Paced**
- Learn one chapter per week - Learn one chapter per week
- Deep practice between chapters - Deep practice between chapters
- Build multiple projects as you learn - Build multiple projects as you learn
@ -150,7 +168,7 @@ By the end of this tutorial, you'll have created:
> >
> **— James T., Design Director** > **— 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 ### Getting Help
**During the tutorial:** **During the tutorial:**
- Each chapter includes detailed examples - Each chapter includes detailed examples
- AI assistants can clarify concepts in real-time - AI assistants can clarify concepts in real-time
- Practice exercises with clear success criteria - Practice exercises with clear success criteria
**After completion:** **After completion:**
- GitHub Discussions for questions and sharing - GitHub Discussions for questions and sharing
- Community showcase of WDS projects - Community showcase of WDS projects
- Regular updates and new case studies - Regular updates and new case studies
**Contributing:** **Contributing:**
- WDS is open-source and welcomes contributions - WDS is open-source and welcomes contributions
- Share your case studies and learnings - Share your case studies and learnings
- Help improve the tutorial for future designers - 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? ## Ready to Start?
You have everything you need: You have everything you need:
- ✅ The skills (design thinking) - ✅ The skills (design thinking)
- ✅ The tools (paper + AI) - ✅ The tools (paper + AI)
- ✅ The time (10 hours) - ✅ The time (10 hours)
@ -226,6 +248,7 @@ Or return to the main guide to review the full structure:
## Your Transformation Starts Now ## Your Transformation Starts Now
Remember: Remember:
- **The design becomes the specification** - **The design becomes the specification**
- **The specification becomes the product** - **The specification becomes the product**
- **The code is just the printout** - **The code is just the printout**

99
src/modules/wds/workflows/00-system/language-configuration-guide.md
View File

@ -22,6 +22,7 @@ These are configured during workflow initialization and stored in `wds-workflow-
During WDS project setup, you'll be asked: During WDS project setup, you'll be asked:
**Question 1: Specification Language** **Question 1: Specification Language**
``` ```
What language should WDS write the design specifications in? 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** **Question 2: Product Languages**
``` ```
What languages will the final product support? What languages will the final product support?
@ -49,7 +51,7 @@ Settings are stored in `docs/wds-workflow-status.yaml`:
```yaml ```yaml
config: config:
specification_language: "EN" specification_language: 'EN'
product_languages: product_languages:
- EN - EN
- SE - SE
@ -63,6 +65,7 @@ config:
### Specification Language ### Specification Language
**Used for:** **Used for:**
- Instructions and guidance text in specs - Instructions and guidance text in specs
- Section descriptions - Section descriptions
- Comments and annotations - Comments and annotations
@ -70,19 +73,23 @@ config:
- Design system documentation - Design system documentation
**Example:** **Example:**
```markdown ```markdown
# 1.1 Start Page # 1.1 Start Page
## Page Purpose ## Page Purpose
Convert visitors into users by addressing... ← Written in spec language
Convert visitors into users by addressing... ← Written in spec language
## User Situation ## User Situation
Family members experiencing daily stress... ← Written in spec language
Family members experiencing daily stress... ← Written in spec language
``` ```
### Product Languages ### Product Languages
**Used for:** **Used for:**
- All user-facing text content - All user-facing text content
- Button labels - Button labels
- Form labels - Form labels
@ -91,11 +98,14 @@ Family members experiencing daily stress... ← Written in spec language
- Any text the END USER sees - Any text the END USER sees
**Example:** **Example:**
```markdown ```markdown
#### Primary CTA Button #### Primary CTA Button
**OBJECT ID**: `start-hero-cta` **OBJECT ID**: `start-hero-cta`
- **Component**: Button Primary - **Component**: Button Primary
- **Content**: ← Product languages - **Content**: ← Product languages
- EN: "Get Started" - EN: "Get Started"
- SE: "Kom Igång" - SE: "Kom Igång"
- NO: "Kom i Gang" - NO: "Kom i Gang"
@ -109,13 +119,14 @@ Family members experiencing daily stress... ← Written in spec language
```yaml ```yaml
config: config:
specification_language: "EN" # Specs written in English specification_language: 'EN' # Specs written in English
product_languages: product_languages:
- EN # Product supports English - EN # Product supports English
- SE # and Swedish - SE # and Swedish
``` ```
**Result:** **Result:**
- Design specs written in English - Design specs written in English
- All text objects have EN and SE translations - All text objects have EN and SE translations
@ -123,29 +134,29 @@ config:
```yaml ```yaml
config: config:
specification_language: "EN" # Specs in English specification_language: 'EN' # Specs in English
product_languages: product_languages:
- EN - EN
- SE - SE
- NO - NO
- DK - DK
- FI # 5 Nordic languages - FI # 5 Nordic languages
``` ```
### Internal Swedish Tool ### Internal Swedish Tool
```yaml ```yaml
config: config:
specification_language: "SE" # Specs in Swedish specification_language: 'SE' # Specs in Swedish
product_languages: product_languages:
- SE # Only Swedish product - SE # Only Swedish product
``` ```
### Global Product ### Global Product
```yaml ```yaml
config: config:
specification_language: "EN" specification_language: 'EN'
product_languages: product_languages:
- EN - EN
- SE - SE
@ -167,9 +178,11 @@ config:
# Product Brief # Product Brief
## Vision ## Vision
Create a platform that... ← Spec language Create a platform that... ← Spec language
## Target Users ## Target Users
Swedish families with... ← Spec language Swedish families with... ← Spec language
``` ```
@ -186,13 +199,16 @@ Personas and triggers documented in spec language.
```markdown ```markdown
## Hero Object ## Hero Object
**Purpose**: Primary value proposition ← Spec language
**Purpose**: Primary value proposition ← Spec language
#### Primary Headline #### Primary Headline
**OBJECT ID**: `start-hero-headline` **OBJECT ID**: `start-hero-headline`
- **Component**: H1 heading - **Component**: H1 heading
- **Position**: Center of hero ← Spec language - **Position**: Center of hero ← Spec language
- **Content**: ← Product languages - **Content**: ← Product languages
- EN: "Every walk. on time." - EN: "Every walk. on time."
- SE: "Varje promenad. i tid." - SE: "Varje promenad. i tid."
``` ```
@ -205,10 +221,12 @@ Personas and triggers documented in spec language.
```markdown ```markdown
## Button Component ## Button Component
### Usage ← Spec language ### Usage ← Spec language
Use this button for primary actions... Use this button for primary actions...
### Examples ← Product languages ### Examples ← Product languages
- EN: "Submit", "Save", "Continue" - EN: "Submit", "Save", "Continue"
- SE: "Skicka", "Spara", "Fortsätt" - SE: "Skicka", "Spara", "Fortsätt"
``` ```
@ -227,22 +245,26 @@ Every text object follows this pattern:
```markdown ```markdown
#### {{Purpose_Name}} #### {{Purpose_Name}}
**OBJECT ID**: `{{id}}` **OBJECT ID**: `{{id}}`
- **Component**: {{type}} - **Component**: {{type}}
- **Position**: {{description}} ← Spec language - **Position**: {{description}} ← Spec language
- **Style**: {{specifications}} ← Spec language - **Style**: {{specifications}} ← Spec language
- **Behavior**: {{description}} ← Spec language - **Behavior**: {{description}} ← Spec language
- **Content**: ← Product languages - **Content**: ← Product languages
{{#each product_languages}} {{#each product_languages}}
- {{this}}: "{{content}}" - {{this}}: "{{content}}"
{{/each}} {{/each}}
``` ```
**Real Example:** **Real Example:**
```markdown ```markdown
#### Email Label #### Email Label
**OBJECT ID**: `signin-form-email-label` **OBJECT ID**: `signin-form-email-label`
- **Component**: Label text - **Component**: Label text
- **Position**: Above email input field - **Position**: Above email input field
- **For**: signin-form-email-input - **For**: signin-form-email-input
@ -304,6 +326,7 @@ User provides all translations, agent validates and documents.
### ✅ Developer-Friendly ### ✅ Developer-Friendly
Config provides: Config provides:
```yaml ```yaml
product_languages: product_languages:
- EN - EN
@ -318,6 +341,7 @@ Developers know exactly what languages to implement.
## Language Codes Reference ## Language Codes Reference
**Nordic:** **Nordic:**
- EN = English - EN = English
- SE = Swedish (Svenska) - SE = Swedish (Svenska)
- NO = Norwegian (Norsk) - NO = Norwegian (Norsk)
@ -325,6 +349,7 @@ Developers know exactly what languages to implement.
- FI = Finnish (Suomi) - FI = Finnish (Suomi)
**Western Europe:** **Western Europe:**
- DE = German (Deutsch) - DE = German (Deutsch)
- FR = French (Français) - FR = French (Français)
- ES = Spanish (Español) - ES = Spanish (Español)
@ -333,16 +358,19 @@ Developers know exactly what languages to implement.
- PT = Portuguese (Português) - PT = Portuguese (Português)
**Eastern Europe:** **Eastern Europe:**
- PL = Polish (Polski) - PL = Polish (Polski)
- CZ = Czech (Čeština) - CZ = Czech (Čeština)
- RU = Russian (Русский) - RU = Russian (Русский)
**Asia:** **Asia:**
- JA = Japanese (日本語) - JA = Japanese (日本語)
- ZH = Chinese (中文) - ZH = Chinese (中文)
- KO = Korean (한국어) - KO = Korean (한국어)
**Other:** **Other:**
- AR = Arabic (العربية) - AR = Arabic (العربية)
- TR = Turkish (Türkçe) - TR = Turkish (Türkçe)
@ -362,7 +390,7 @@ Product Languages: EN, SE
```yaml ```yaml
# docs/wds-workflow-status.yaml # docs/wds-workflow-status.yaml
config: config:
specification_language: "EN" specification_language: 'EN'
product_languages: product_languages:
- EN - EN
- SE - SE
@ -373,15 +401,17 @@ config:
```markdown ```markdown
# 1.1 Start Page # 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 #### Primary Headline
**OBJECT ID**: `start-hero-headline` **OBJECT ID**: `start-hero-headline`
- **Component**: H1 heading - **Component**: H1 heading
- **Position**: Center of hero section ← Written in EN - **Position**: Center of hero section ← Written in EN
- **Content**: - **Content**:
- EN: "Every walk. on time. Every time." ← Product language 1 - EN: "Every walk. on time. Every time." ← Product language 1
- SE: "Varje promenad. i tid. Varje gång." ← Product language 2 - SE: "Varje promenad. i tid. Varje gång." ← Product language 2
``` ```
### For Developers ### For Developers
@ -394,8 +424,8 @@ const languages = ['EN', 'SE'];
const content = { const content = {
'start-hero-headline': { 'start-hero-headline': {
en: 'Every walk. on time. Every time.', 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 3. **Continue** with new language config
**Before:** **Before:**
```yaml ```yaml
product_languages: product_languages:
- EN - EN
@ -417,25 +448,25 @@ product_languages:
``` ```
**After:** **After:**
```yaml ```yaml
product_languages: product_languages:
- EN - EN
- SE - SE
- NO # Added Norwegian - NO # Added Norwegian
``` ```
**Update existing specs:** **Update existing specs:**
```markdown ```markdown
#### Primary Headline #### Primary Headline
- **Content**: - **Content**:
- EN: "Every walk. on time." - EN: "Every walk. on time."
- SE: "Varje promenad. i tid." - 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!** 🌍✨ **Language configuration ensures complete, translation-ready specifications from day one!** 🌍✨

68
src/modules/wds/workflows/00-system/language-flow-diagram.md
View File

@ -29,6 +29,7 @@ Product languages: EN, SE
``` ```
**Agent stores:** **Agent stores:**
- `specification_language = "EN"` - `specification_language = "EN"`
- `product_languages = ["EN", "SE"]` - `product_languages = ["EN", "SE"]`
@ -74,6 +75,7 @@ config:
``` ```
**Agent now knows:** **Agent now knows:**
- Write specs in English - Write specs in English
- Request content in English AND Swedish for all text - 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 ### Step 3: Content with Translations
**Agent reads config:** **Agent reads config:**
```xml ```xml
<action>Load product_languages from config → ["EN", "SE"]</action> <action>Load product_languages from config → ["EN", "SE"]</action>
``` ```
@ -147,6 +150,7 @@ SE:
``` ```
**User provides:** **User provides:**
``` ```
EN: Every walk. on time. Every time. EN: Every walk. on time. Every time.
@ -154,6 +158,7 @@ SE: Varje promenad. i tid. Varje gång.
``` ```
**Agent validates:** **Agent validates:**
``` ```
✅ EN content: 37 characters (fits 60 capacity) ✅ EN content: 37 characters (fits 60 capacity)
✅ SE content: 36 characters (fits 60 capacity) ✅ SE content: 36 characters (fits 60 capacity)
@ -168,20 +173,23 @@ SE: Varje promenad. i tid. Varje gång.
```markdown ```markdown
# 1.1 Start Page # 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 ## Page Sections
### Hero Object ### Hero Object
**Purpose**: Primary value proposition ← English (spec language)
**Purpose**: Primary value proposition ← English (spec language)
#### Primary Headline #### Primary Headline
**OBJECT ID**: `start-hero-headline` **OBJECT ID**: `start-hero-headline`
- **Component**: H1 heading (`.text-heading-1`) - **Component**: H1 heading (`.text-heading-1`)
- **Position**: Center of hero section ← English (spec language) - **Position**: Center of hero section ← English (spec language)
- **Style**: Bold, 42px, line-height 1.2 ← English (spec language) - **Style**: Bold, 42px, line-height 1.2 ← English (spec language)
- **Behavior**: Updates with language toggle ← English (spec language) - **Behavior**: Updates with language toggle ← English (spec language)
- **Content**: ← Product languages - **Content**: ← Product languages
- EN: "Every walk. on time. Every time." - EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång." - 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 ```markdown
### Hero Object ### Hero Object
**Purpose**: Primary value proposition ← Spec language
**Purpose**: Primary value proposition ← Spec language
#### Primary Headline #### Primary Headline
**OBJECT ID**: `start-hero-headline` **OBJECT ID**: `start-hero-headline`
- **Component**: H1 heading - **Component**: H1 heading
- **Position**: Center of hero, top ← Spec language - **Position**: Center of hero, top ← Spec language
- **Content**: - **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." - SE: "Varje promenad. i tid. Varje gång."
#### Supporting Text #### Supporting Text
**OBJECT ID**: `start-hero-supporting` **OBJECT ID**: `start-hero-supporting`
- **Component**: Body text - **Component**: Body text
- **Position**: Below headline ← Spec language - **Position**: Below headline ← Spec language
- **Content**: - **Content**:
- EN: "Never miss a walk again." ← Product languages - EN: "Never miss a walk again." ← Product languages
- SE: "Missa aldrig en promenad." - SE: "Missa aldrig en promenad."
#### Primary CTA #### Primary CTA
**OBJECT ID**: `start-hero-cta` **OBJECT ID**: `start-hero-cta`
- **Component**: Button Primary - **Component**: Button Primary
- **Position**: Center, below text ← Spec language - **Position**: Center, below text ← Spec language
- **Content**: - **Content**:
- EN: "Get Started" ← Product languages - EN: "Get Started" ← Product languages
- SE: "Kom Igång" - SE: "Kom Igång"
``` ```
**Reading in English:** **Reading in English:**
> Every walk. on time. Every time. > Every walk. on time. Every time.
> Never miss a walk again. > Never miss a walk again.
> [Get Started] > [Get Started]
**Reading in Swedish:** **Reading in Swedish:**
> Varje promenad. i tid. Varje gång. > Varje promenad. i tid. Varje gång.
> Missa aldrig en promenad. > Missa aldrig en promenad.
> [Kom Igång] > [Kom Igång]
@ -254,16 +271,16 @@ const supportedLanguages = ['en', 'se'];
const translations = { const translations = {
'start-hero-headline': { 'start-hero-headline': {
en: 'Every walk. on time. Every time.', 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': { 'start-hero-supporting': {
en: 'Never miss a walk again.', en: 'Never miss a walk again.',
se: 'Missa aldrig en promenad.' se: 'Missa aldrig en promenad.',
}, },
'start-hero-cta': { 'start-hero-cta': {
en: 'Get Started', en: 'Get Started',
se: 'Kom Igång' se: 'Kom Igång',
} },
}; };
// Language toggle // Language toggle
@ -342,11 +359,13 @@ function setLanguage(lang: 'en' | 'se') {
### ✅ Two Distinct Languages ### ✅ Two Distinct Languages
**Specification Language:** **Specification Language:**
- Documentation language - Documentation language
- For designers, PMs, developers - For designers, PMs, developers
- Describes structure, behavior, logic - Describes structure, behavior, logic
**Product Languages:** **Product Languages:**
- User-facing content - User-facing content
- What end users see - What end users see
- Can be multiple languages - Can be multiple languages
@ -354,6 +373,7 @@ function setLanguage(lang: 'en' | 'se') {
### ✅ Early Configuration ### ✅ Early Configuration
**Set during workflow init** - before any design work **Set during workflow init** - before any design work
- No mid-project surprises - No mid-project surprises
- All stakeholders aligned - All stakeholders aligned
- Complete from day one - Complete from day one
@ -361,6 +381,7 @@ function setLanguage(lang: 'en' | 'se') {
### ✅ Automatic Propagation ### ✅ Automatic Propagation
**Config flows through all phases:** **Config flows through all phases:**
- Phase 1: Brief in spec language - Phase 1: Brief in spec language
- Phase 2: Trigger Map in spec language - Phase 2: Trigger Map in spec language
- Phase 4: Specs in spec language, content in ALL product languages - 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 ## Example: Adding Norwegian Mid-Project
**Original config:** **Original config:**
```yaml ```yaml
product_languages: product_languages:
- EN - EN
@ -396,20 +418,23 @@ product_languages:
**User needs Norwegian:** **User needs Norwegian:**
1. **Update config:** 1. **Update config:**
```yaml ```yaml
product_languages: product_languages:
- EN - EN
- SE - SE
- NO # Added - NO # Added
``` ```
2. **Add to existing specs:** 2. **Add to existing specs:**
```markdown ```markdown
#### Primary Headline #### Primary Headline
- **Content**: - **Content**:
- EN: "Every walk. on time." - EN: "Every walk. on time."
- SE: "Varje promenad. i tid." - 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** 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!** 🌍✨ **Language configuration ensures complete, production-ready translations from the very beginning!** 🌍✨

13
src/modules/wds/workflows/00-system/wds-workflow-status-template.yaml
View File

@ -22,13 +22,13 @@ workflow_path: "{{workflow_path_file}}"
# Configuration # Configuration
config: config:
folder_prefix: "{{folder_prefix}}" # letters or numbers folder_prefix: "{{folder_prefix}}" # letters or numbers
folder_case: "{{folder_case}}" # title or lowercase folder_case: "{{folder_case}}" # title or lowercase
brief_level: "{{brief_level}}" # simplified or complete brief_level: "{{brief_level}}" # simplified or complete
include_design_system: {{include_design_system}} include_design_system: { { include_design_system } }
component_library: "{{component_library}}" component_library: "{{component_library}}"
specification_language: "{{specification_language}}" # Language for writing specs (EN, SE, etc.) specification_language: "{{specification_language}}" # Language for writing specs (EN, SE, etc.)
product_languages: {{product_languages}} # Array of languages product supports product_languages: { { product_languages } } # Array of languages product supports
# Folder mapping (generated based on config) # Folder mapping (generated based on config)
folders: folders:
@ -41,7 +41,6 @@ folders:
# Workflow status tracking # Workflow status tracking
workflow_status: "{{workflow_items}}" workflow_status: "{{workflow_items}}"
# Example structure when populated: # Example structure when populated:
# workflow_status: # workflow_status:
# phase_1_project_brief: # phase_1_project_brief:

20
src/modules/wds/workflows/1-project-brief/complete/instructions.md
View File

@ -9,6 +9,7 @@
<output>Hi {user_name}! I'm Saga, and I'll guide you through creating a **Complete Project Brief**. <output>Hi {user_name}! I'm Saga, and I'll guide you through creating a **Complete Project Brief**.
This is our strategic foundation - we'll explore: This is our strategic foundation - we'll explore:
- Vision & positioning - Vision & positioning
- Target users (ICP) - Target users (ICP)
- Success criteria - Success criteria
@ -32,11 +33,12 @@ Ready to begin? 🎯</output>
If this project succeeds beyond your wildest dreams, what does that look like? Don't worry about being realistic yet - dream big.</ask> If this project succeeds beyond your wildest dreams, what does that look like? Don't worry about being realistic yet - dream big.</ask>
<action>Listen for: <action>Listen for:
- Aspirational outcomes - Aspirational outcomes
- Impact on users - Impact on users
- Market position - Market position
- Emotional drivers - Emotional drivers
</action> </action>
<action>Reflect back and help crystallize into a clear vision statement</action> <action>Reflect back and help crystallize into a clear vision statement</action>
@ -50,15 +52,16 @@ If this project succeeds beyond your wildest dreams, what does that look like? D
Complete this statement: Complete this statement:
*For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator].*</ask> _For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator]._</ask>
<action>If user struggles, break it down: <action>If user struggles, break it down:
1. Who's the target customer? 1. Who's the target customer?
2. What's their need or opportunity? 2. What's their need or opportunity?
3. What category does this fit? 3. What category does this fit?
4. What's the key benefit? 4. What's the key benefit?
5. What makes it different from alternatives? 5. What makes it different from alternatives?
</action> </action>
<action>Help craft a clear positioning statement</action> <action>Help craft a clear positioning statement</action>
@ -144,18 +147,20 @@ Others who interact with the product but aren't the primary user?</ask>
<ask>**What metrics or outcomes define success?** <ask>**What metrics or outcomes define success?**
Think about: Think about:
- User behavior (adoption, engagement, retention) - User behavior (adoption, engagement, retention)
- Business outcomes (revenue, conversion, efficiency) - Business outcomes (revenue, conversion, efficiency)
- Experience quality (satisfaction, NPS, task completion) - Experience quality (satisfaction, NPS, task completion)
- Timeline (when do you need to see results?)</ask> - Timeline (when do you need to see results?)</ask>
<action>Help make criteria SMART: <action>Help make criteria SMART:
- Specific - Specific
- Measurable - Measurable
- Achievable - Achievable
- Relevant - Relevant
- Time-bound - Time-bound
</action> </action>
<template-output>success_criteria</template-output> <template-output>success_criteria</template-output>
</step> </step>
@ -166,16 +171,18 @@ Think about:
<ask>**What alternatives do your users have today?** <ask>**What alternatives do your users have today?**
This could be: This could be:
- Direct competitors - Direct competitors
- Different approaches to the same problem - Different approaches to the same problem
- Manual/analog solutions - Manual/analog solutions
- Doing nothing</ask> - Doing nothing</ask>
<action>For each alternative, explore: <action>For each alternative, explore:
- What do they do well? - What do they do well?
- Where do they fall short? - Where do they fall short?
- Why might users choose them over you? - Why might users choose them over you?
</action> </action>
<ask>**What's your unfair advantage?** <ask>**What's your unfair advantage?**
@ -241,6 +248,7 @@ Company stage, team capabilities, market conditions, past attempts?</ask>
{{constraints}} {{constraints}}
--- ---
</output> </output>
<ask>Does this capture your strategic foundation? Anything to refine?</ask> <ask>Does this capture your strategic foundation? Anything to refine?</ask>
@ -255,6 +263,7 @@ Company stage, team capabilities, market conditions, past attempts?</ask>
Location: `A-Product-Brief/project-brief.md` Location: `A-Product-Brief/project-brief.md`
This strategic foundation will guide all design decisions. You're ready for: This strategic foundation will guide all design decisions. You're ready for:
- **Phase 2: Trigger Mapping** - Deep dive into user psychology - **Phase 2: Trigger Mapping** - Deep dive into user psychology
- **Phase 3: PRD Platform** - Technical foundation - **Phase 3: PRD Platform** - Technical foundation
@ -262,4 +271,3 @@ Your vision is clear. Let's build something great! 🚀</output>
</step> </step>
</workflow> </workflow>

16
src/modules/wds/workflows/1-project-brief/complete/project-brief.template.md
View File

@ -19,6 +19,7 @@
{{positioning_statement}} {{positioning_statement}}
**Breakdown:** **Breakdown:**
- **Target Customer:** {{target_customer}} - **Target Customer:** {{target_customer}}
- **Need/Opportunity:** {{need_opportunity}} - **Need/Opportunity:** {{need_opportunity}}
- **Category:** {{category}} - **Category:** {{category}}
@ -31,8 +32,7 @@
**Type:** {{business_model}} **Type:** {{business_model}}
{{#if business_model_b2b}} ## {{#if business_model_b2b}}
---
## Business Customer Profile (B2B) ## Business Customer Profile (B2B)
@ -40,11 +40,12 @@
### Buying Roles ### Buying Roles
| Role | Description | | Role | Description |
|------|-------------| | ------------ | ----------------- |
| **Buyer** | {{buyer_role}} | | **Buyer** | {{buyer_role}} |
| **Champion** | {{champion_role}} | | **Champion** | {{champion_role}} |
| **User** | {{user_role}} | | **User** | {{user_role}} |
{{/if}} {{/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_

10
src/modules/wds/workflows/1-project-brief/complete/steps/step-01-init.md
View File

@ -1,13 +1,17 @@
# Step 1: Welcome and Set Expectations # Step 1: Welcome and Set Expectations
## Purpose ## Purpose
Welcome user and set expectations for the Project Brief workflow. Welcome user and set expectations for the Project Brief workflow.
## Context for Agent ## 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. 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 ## Key Elements to Cover
This workflow establishes the strategic foundation by exploring: This workflow establishes the strategic foundation by exploring:
- Vision & positioning (core strategic direction) - Vision & positioning (core strategic direction)
- Target users (ICP) - who we're designing for - Target users (ICP) - who we're designing for
- Success criteria (how we'll measure success) - Success criteria (how we'll measure success)
@ -15,13 +19,17 @@ This workflow establishes the strategic foundation by exploring:
- Constraints & context (real-world limitations) - Constraints & context (real-world limitations)
## Instructions ## 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. 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 ## Next Step
When user confirms readiness, proceed to step-02-vision.md When user confirms readiness, proceed to step-02-vision.md
## State Update ## State Update
Update frontmatter of output file: Update frontmatter of output file:
```yaml ```yaml
stepsCompleted: ["step-01-init.md"] stepsCompleted: ['step-01-init.md']
``` ```

10
src/modules/wds/workflows/1-project-brief/complete/steps/step-02-vision.md
View File

@ -1,12 +1,15 @@
# Step 2: Capture Vision # Step 2: Capture Vision
## Purpose ## Purpose
Help user articulate their vision for the product. Help user articulate their vision for the product.
## Context for Agent ## 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. 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 ## Key Elements
This step captures the high-level, aspirational direction that will guide all decisions. This step captures the high-level, aspirational direction that will guide all decisions.
## Instructions ## 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..." - Use collaborative language: "What I'm hearing is..." or "It sounds like..."
## Next Step ## Next Step
After capturing vision, proceed to step-03-positioning.md After capturing vision, proceed to step-03-positioning.md
## State Update ## State Update
Update frontmatter of output file: Update frontmatter of output file:
```yaml ```yaml
stepsCompleted: ["step-01-init.md", "step-02-vision.md"] stepsCompleted: ['step-01-init.md', 'step-02-vision.md']
vision: "[captured vision statement]" vision: '[captured vision statement]'
``` ```

12
src/modules/wds/workflows/1-project-brief/complete/steps/step-03-positioning.md
View File

@ -1,26 +1,34 @@
# Step 3: Define Positioning # Step 3: Define Positioning
## Purpose ## Purpose
Help user define clear positioning statement for their product. Help user define clear positioning statement for their product.
## Context for Agent ## Context for Agent
You are helping the user clarify how their product fits in the market and what makes it unique. You are helping the user clarify how their product fits in the market and what makes it unique.
## Key Elements ## Key Elements
This step establishes market positioning and differentiation. This step establishes market positioning and differentiation.
## Key Framework ## Key Framework
Positioning statement format: "For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator]." Positioning statement format: "For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator]."
## Instructions ## 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. 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 ## Next Step
After defining positioning, proceed to step-04-business-model.md After defining positioning, proceed to step-04-business-model.md
## State Update ## State Update
Update frontmatter of output file: Update frontmatter of output file:
```yaml ```yaml
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md"] stepsCompleted: ['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md']
positioning: "[captured positioning statement]" positioning: '[captured positioning statement]'
``` ```

10
src/modules/wds/workflows/1-project-brief/complete/steps/step-04-business-model.md
View File

@ -1,20 +1,26 @@
# Step 4: Determine Business Model # Step 4: Determine Business Model
## Goal ## Goal
Help user identify whether their product is B2B, B2C, or both. Help user identify whether their product is B2B, B2C, or both.
## Key Elements ## Key Elements
Business model determines who buys/uses the product and affects all strategic decisions. Business model determines who buys/uses the product and affects all strategic decisions.
## Instructions ## Instructions
Ask user whether their product is B2B, B2C, or both. Present clear options and explain the implications of each choice. Ask user whether their product is B2B, B2C, or both. Present clear options and explain the implications of each choice.
## Next Step ## 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 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 ## State Update
Update frontmatter of output file: Update frontmatter of output file:
```yaml ```yaml
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md"] stepsCompleted: ['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md', 'step-04-business-model.md']
business_model: "[b2b/b2c/both]" business_model: '[b2b/b2c/both]'
``` ```

13
src/modules/wds/workflows/1-project-brief/complete/steps/step-05-business-customers.md
View File

@ -1,21 +1,28 @@
# Step 5: Identify Business Customers (B2B) # Step 5: Identify Business Customers (B2B)
## Goal ## Goal
Help user define their ideal business customer profile. Help user define their ideal business customer profile.
## Key Elements ## Key Elements
Business customer profile determines who buys the product and influences purchasing decisions. Business customer profile determines who buys the product and influences purchasing decisions.
## Instructions ## 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). 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 ## Next Step
After identifying business customers, proceed to step-06-target-users.md After identifying business customers, proceed to step-06-target-users.md
## State Update ## State Update
Update frontmatter of output file: Update frontmatter of output file:
```yaml ```yaml
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md"] stepsCompleted:
business_customer_profile: "[captured business customer profile]" ['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md', 'step-04-business-model.md', 'step-05-business-customers.md']
buying_roles: "[captured buying roles]" business_customer_profile: '[captured business customer profile]'
buying_roles: '[captured buying roles]'
``` ```

21
src/modules/wds/workflows/1-project-brief/complete/steps/step-06-target-users.md
View File

@ -1,24 +1,39 @@
# Step 6: Identify Target Users # Step 6: Identify Target Users
## Purpose ## Purpose
Help user define their ideal customer profile. Help user define their ideal customer profile.
## Context for Agent ## Context for Agent
You are identifying who the product is for and what their needs are. This information will guide all design decisions. You are identifying who the product is for and what their needs are. This information will guide all design decisions.
## Key Elements ## Key Elements
This step identifies who we're designing for and what their needs are. This step identifies who we're designing for and what their needs are.
## Instructions ## 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. 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 ## Next Step
After identifying target users, proceed to step-07-success-criteria.md After identifying target users, proceed to step-07-success-criteria.md
## State Update ## State Update
Update frontmatter of output file: Update frontmatter of output file:
```yaml ```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"] stepsCompleted:
ideal_user_profile: "[captured user profile]" [
secondary_users: "[captured secondary users]" '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]'
``` ```

20
src/modules/wds/workflows/1-project-brief/complete/steps/step-07-success-criteria.md
View File

@ -1,23 +1,39 @@
# Step 7: Define Success Criteria # Step 7: Define Success Criteria
## Purpose ## Purpose
Help user define measurable success criteria for their project. Help user define measurable success criteria for their project.
## Context for Agent ## Context for Agent
You are establishing how the project will know if it's successful. This will guide all future decisions. You are establishing how the project will know if it's successful. This will guide all future decisions.
## Key Elements ## Key Elements
This step establishes measurable outcomes that indicate success. This step establishes measurable outcomes that indicate success.
## Instructions ## 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). 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 ## Next Step
After defining success criteria, proceed to step-08-competitive-landscape.md After defining success criteria, proceed to step-08-competitive-landscape.md
## State Update ## State Update
Update frontmatter of output file: Update frontmatter of output file:
```yaml ```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"] stepsCompleted:
success_criteria: "[captured success criteria]" [
'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]'
``` ```

23
src/modules/wds/workflows/1-project-brief/complete/steps/step-08-competitive-landscape.md
View File

@ -1,24 +1,41 @@
# Step 8: Analyze Competitive Landscape # Step 8: Analyze Competitive Landscape
## Purpose ## Purpose
Help user understand alternatives and their unique advantage. Help user understand alternatives and their unique advantage.
## Context for Agent ## Context for Agent
You are exploring what alternatives exist and what makes the product unique. This information will guide differentiation strategy. You are exploring what alternatives exist and what makes the product unique. This information will guide differentiation strategy.
## Key Elements ## Key Elements
This step identifies competitive positioning and unique value proposition. This step identifies competitive positioning and unique value proposition.
## Instructions ## 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. 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 ## Next Step
After analyzing competitive landscape, proceed to step-09-constraints.md After analyzing competitive landscape, proceed to step-09-constraints.md
## State Update ## State Update
Update frontmatter of output file: Update frontmatter of output file:
```yaml ```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"] stepsCompleted:
competitive_landscape: "[captured competitive analysis]" [
unfair_advantage: "[captured unfair advantage]" '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]'
``` ```

24
src/modules/wds/workflows/1-project-brief/complete/steps/step-09-constraints.md
View File

@ -1,24 +1,42 @@
# Step 9: Capture Constraints and Context # Step 9: Capture Constraints and Context
## Purpose ## Purpose
Help user identify constraints that should shape design decisions. Help user identify constraints that should shape design decisions.
## Context for Agent ## Context for Agent
You are grounding the vision in reality by identifying limitations and context. You are grounding the vision in reality by identifying limitations and context.
## Key Elements ## Key Elements
This step identifies real-world limitations and additional context. This step identifies real-world limitations and additional context.
## Instructions ## 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. 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 ## Next Step
After capturing constraints, proceed to step-10-synthesize.md After capturing constraints, proceed to step-10-synthesize.md
## State Update ## State Update
Update frontmatter of output file: Update frontmatter of output file:
```yaml ```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"] stepsCompleted:
constraints: "[captured constraints]" [
additional_context: "[captured additional context]" '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]'
``` ```

23
src/modules/wds/workflows/1-project-brief/complete/steps/step-10-synthesize.md
View File

@ -1,23 +1,42 @@
# Step 10: Synthesize and Create Brief # Step 10: Synthesize and Create Brief
## Purpose ## Purpose
Synthesize all captured information into a complete project brief document. Synthesize all captured information into a complete project brief document.
## Context for Agent ## Context for Agent
You are bringing together all the strategic elements into a comprehensive brief that will guide all design decisions. You are bringing together all the strategic elements into a comprehensive brief that will guide all design decisions.
## Key Elements ## Key Elements
This step compiles all strategic foundation elements into a cohesive document. This step compiles all strategic foundation elements into a cohesive document.
## Instructions ## 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. 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 ## Next Step
Workflow complete. User can proceed to Phase 2: Trigger Mapping Workflow complete. User can proceed to Phase 2: Trigger Mapping
## State Update ## State Update
Update frontmatter of output file: Update frontmatter of output file:
```yaml ```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"] stepsCompleted:
status: "complete" [
'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'
``` ```

15
src/modules/wds/workflows/1-project-brief/simplified/instructions.md
View File

@ -9,6 +9,7 @@
<output>Hi {user_name}! I'm Saga, and I'll help you capture the essential context for your project. <output>Hi {user_name}! I'm Saga, and I'll help you capture the essential context for your project.
This is a **Simplified Project Brief** - we'll cover the key points in about 5-10 minutes: This is a **Simplified Project Brief** - we'll cover the key points in about 5-10 minutes:
- What you're building (scope) - What you're building (scope)
- The challenge or opportunity - The challenge or opportunity
- Your design goals - Your design goals
@ -22,10 +23,11 @@ Let's dive in! 🎯</output>
Describe the project in a few sentences. What will users see and interact with?</ask> Describe the project in a few sentences. What will users see and interact with?</ask>
<action>Listen for: <action>Listen for:
- Type of project (app, website, feature, page) - Type of project (app, website, feature, page)
- Target platform (web, mobile, both) - Target platform (web, mobile, both)
- Key functionality or purpose - Key functionality or purpose
</action> </action>
<action>If unclear, ask one clarifying question</action> <action>If unclear, ask one clarifying question</action>
@ -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?</ask> Why does this project exist? What problem are you solving, or what opportunity are you pursuing?</ask>
<action>Listen for: <action>Listen for:
- Pain points being addressed - Pain points being addressed
- Market opportunity - Market opportunity
- User needs not being met - User needs not being met
- Business drivers - Business drivers
</action> </action>
<action>Reflect back what you heard to confirm understanding</action> <action>Reflect back what you heard to confirm understanding</action>
@ -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?</ask> When this design is complete, what will make it successful? What experience do you want users to have?</ask>
<action>Listen for: <action>Listen for:
- Functional goals (what it should do) - Functional goals (what it should do)
- Experience goals (how it should feel) - Experience goals (how it should feel)
- Business goals (what outcomes matter) - Business goals (what outcomes matter)
</action> </action>
<action>Help refine vague goals into specific, actionable ones</action> <action>Help refine vague goals into specific, actionable ones</action>
@ -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?</ask> Timeline, technology, brand guidelines, existing systems to integrate with?</ask>
<action>Note: <action>Note:
- Technical constraints - Technical constraints
- Timeline/deadline - Timeline/deadline
- Budget considerations - Budget considerations
- Brand/style requirements - Brand/style requirements
- Integration requirements - Integration requirements
</action> </action>
<action>It's okay if there are few constraints - note "flexible" where appropriate</action> <action>It's okay if there are few constraints - note "flexible" where appropriate</action>
@ -111,6 +116,7 @@ Timeline, technology, brand guidelines, existing systems to integrate with?</ask
Location: `A-Product-Brief/project-brief.md` Location: `A-Product-Brief/project-brief.md`
You now have enough context to move forward. When you're ready: You now have enough context to move forward. When you're ready:
- **Next phase:** Check your workflow status for what's next - **Next phase:** Check your workflow status for what's next
- **Need more depth?** You can always expand this into a Complete brief later - **Need more depth?** You can always expand this into a Complete brief later
@ -118,4 +124,3 @@ Happy designing! 🎨</output>
</step> </step>
</workflow> </workflow>

3
src/modules/wds/workflows/1-project-brief/simplified/simplified-brief.template.md
View File

@ -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_

2
src/modules/wds/workflows/1-project-brief/workflow.yaml
View File

@ -3,7 +3,6 @@ name: Product Brief Workflow
description: Establish project context - foundation for all design work description: Establish project context - foundation for all design work
web_bundle: true web_bundle: true
--- ---
# WDS Phase 1: Project Brief # WDS Phase 1: Project Brief
name: project-brief name: project-brief
author: "Whiteport Design Studio" author: "Whiteport Design Studio"
@ -42,4 +41,3 @@ primary_agent: "saga-analyst"
standalone: true standalone: true
web_bundle: false web_bundle: false

5
src/modules/wds/workflows/2-trigger-mapping/instructions.md
View File

@ -9,6 +9,7 @@
<output>Hi {user_name}! I'm Saga, and I'll facilitate your **Trigger Mapping** session. <output>Hi {user_name}! I'm Saga, and I'll facilitate your **Trigger Mapping** session.
Trigger Mapping connects your business goals to user psychology. It answers: Trigger Mapping connects your business goals to user psychology. It answers:
- **Why** will users engage with your product? - **Why** will users engage with your product?
- **What** motivates them (positive drivers)? - **What** motivates them (positive drivers)?
- **What** do they want to avoid (negative drivers)? - **What** do they want to avoid (negative drivers)?
@ -27,6 +28,7 @@ Each workshop builds on the previous. You can run them all together (60-90 min)
Ready to begin? 🎯</output> Ready to begin? 🎯</output>
<ask>Would you like to: <ask>Would you like to:
1. **Full session** - All 5 workshops now 1. **Full session** - All 5 workshops now
2. **Workshop by workshop** - Start with Business Goals, continue later 2. **Workshop by workshop** - Start with Business Goals, continue later
3. **Jump to specific workshop** - If you've done some already</ask> 3. **Jump to specific workshop** - If you've done some already</ask>
@ -86,6 +88,7 @@ Ready to begin? 🎯</output>
<output>✅ **Trigger Mapping complete!** <output>✅ **Trigger Mapping complete!**
**Created:** **Created:**
- `B-Trigger-Map/00-Trigger-Map-Poster.md` - Visual overview - `B-Trigger-Map/00-Trigger-Map-Poster.md` - Visual overview
- `B-Trigger-Map/01-Business-Goals.md` - Visions & objectives - `B-Trigger-Map/01-Business-Goals.md` - Visions & objectives
- `B-Trigger-Map/02-Target-Groups.md` - All personas with drivers - `B-Trigger-Map/02-Target-Groups.md` - All personas with drivers
@ -96,6 +99,7 @@ Ready to begin? 🎯</output>
{{summary_of_priorities}} {{summary_of_priorities}}
You now have strategic clarity on: You now have strategic clarity on:
- What success looks like (business goals) - What success looks like (business goals)
- Who to focus on (target groups) - Who to focus on (target groups)
- What drives them (positive & negative forces) - What drives them (positive & negative forces)
@ -105,4 +109,3 @@ Ready for the next phase! 🚀</output>
</step> </step>
</workflow> </workflow>

18
src/modules/wds/workflows/2-trigger-mapping/templates/feature-impact.template.md
View File

@ -15,7 +15,8 @@
## Prioritized Features ## Prioritized Features
| Rank | Feature | Score | Decision | | Rank | Feature | Score | Decision |
|------|---------|-------|----------| | ---- | ------- | ----- | -------- |
{{#each sorted_features}} {{#each sorted_features}}
| {{this.rank}} | {{this.name}} | {{this.score}} | {{this.decision}} | | {{this.rank}} | {{this.name}} | {{this.score}} | {{this.decision}} |
{{/each}} {{/each}}
@ -26,21 +27,24 @@
**Must Have MVP (Primary High OR Top Tier Score):** **Must Have MVP (Primary High OR Top Tier Score):**
{{#each must_have}} {{#each must_have}}
- {{this.name}} ({{this.score}}) - {{this.name}} ({{this.score}})
{{/each}} {{/each}}
**Consider for MVP:** **Consider for MVP:**
{{#each consider}} {{#each consider}}
- {{this.name}} ({{this.score}}) - {{this.name}} ({{this.score}})
{{/each}} {{/each}}
**Defer (Nice-to-Have or Low Strategic Value):** **Defer (Nice-to-Have or Low Strategic Value):**
{{#each defer}} {{#each defer}}
- {{this.name}} ({{this.score}}) - {{this.name}} ({{this.score}})
{{/each}} {{/each}}
--- ---
*Generated by Whiteport Design Studio* _Generated by Whiteport Design Studio_
*Strategic input for Phase 4: UX Design and Phase 6: PRD/Development* _Strategic input for Phase 4: UX Design and Phase 6: PRD/Development_
*Beta methodology - feedback welcome* _Beta methodology - feedback welcome_

29
src/modules/wds/workflows/2-trigger-mapping/templates/trigger-map.template.md
View File

@ -15,7 +15,7 @@ This is the visual overview. For detailed documentation, see:
- **01-Business-Goals.md** - Full vision statements and SMART objectives - **01-Business-Goals.md** - Full vision statements and SMART objectives
- **02-Target-Groups.md** - All personas with complete driving forces - **02-Target-Groups.md** - All personas with complete driving forces
- **03-Feature-Impact-Analysis.md** - Prioritized features with impact scores - **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 ## Business Objectives
{{#each objectives}} {{#each objectives}}
### Objective {{@index + 1}}: {{this.statement}} ### Objective {{@index + 1}}: {{this.statement}}
- **Metric:** {{this.metric}} - **Metric:** {{this.metric}}
- **Target:** {{this.target}} - **Target:** {{this.target}}
- **Timeline:** {{this.timeline}} - **Timeline:** {{this.timeline}}
{{/each}} {{/each}}
--- ---
## Target Groups (Prioritized) ## Target Groups (Prioritized)
{{#each prioritized_groups}} {{#each prioritized_groups}}
### {{@index + 1}}. {{this.name}} ### {{@index + 1}}. {{this.name}}
**Priority Reasoning:** {{this.reasoning}} **Priority Reasoning:** {{this.reasoning}}
> {{this.persona_summary}} > {{this.persona_summary}}
**Key Positive Drivers:** **Key Positive Drivers:**
{{#each this.positive_drivers}} {{#each this.positive_drivers}}
- {{this}} - {{this}}
{{/each}} {{/each}}
**Key Negative Drivers:** **Key Negative Drivers:**
{{#each this.negative_drivers}} {{#each this.negative_drivers}}
- {{this}} - {{this}}
{{/each}} {{/each}}
{{/each}} {{/each}}
@ -94,26 +100,32 @@ This is the visual overview. For detailed documentation, see:
**Must Address:** **Must Address:**
{{#each must_address_drivers}} {{#each must_address_drivers}}
- {{this}} - {{this}}
{{/each}} {{/each}}
**Should Address:** **Should Address:**
{{#each should_address_drivers}} {{#each should_address_drivers}}
- {{this}} - {{this}}
{{/each}} {{/each}}
--- ---
## Cross-Group Patterns ## Cross-Group Patterns
### Shared Drivers ### Shared Drivers
{{shared_drivers}} {{shared_drivers}}
### Unique Drivers ### Unique Drivers
{{unique_drivers}} {{unique_drivers}}
{{#if conflicts}} {{#if conflicts}}
### Potential Tensions ### Potential Tensions
{{conflicts}} {{conflicts}}
{{/if}} {{/if}}
@ -131,6 +143,5 @@ This Trigger Map Poster provides a quick reference. For detailed work:
--- ---
*Generated by Whiteport Design Studio* _Generated by Whiteport Design Studio_
*Trigger Mapping methodology credits: Effect Mapping by Mijo Balic & Ingrid Domingues (inUse), adapted with negative driving forces by WDS* _Trigger Mapping methodology credits: Effect Mapping by Mijo Balic & Ingrid Domingues (inUse), adapted with negative driving forces by WDS_

1
src/modules/wds/workflows/2-trigger-mapping/workflow.yaml
View File

@ -55,4 +55,3 @@ primary_agent: "saga-analyst"
standalone: true standalone: true
web_bundle: false web_bundle: false

11
src/modules/wds/workflows/2-trigger-mapping/workshops/1-business-goals/instructions.md
View File

@ -8,6 +8,7 @@
<output>**Workshop 1: Business Goals** 🎯 <output>**Workshop 1: Business Goals** 🎯
We'll define what success looks like at two levels: We'll define what success looks like at two levels:
- **Vision** - The inspiring, aspirational goal (not easily quantified) - **Vision** - The inspiring, aspirational goal (not easily quantified)
- **Objectives** - SMART metrics that indicate progress - **Objectives** - SMART metrics that indicate progress
@ -20,6 +21,7 @@ Let's start with the dream, then make it measurable.</output>
Think big. If everything goes perfectly, what position do you want to hold? Think big. If everything goes perfectly, what position do you want to hold?
Examples: Examples:
- "Be the most trusted platform for dog owners in Sweden" - "Be the most trusted platform for dog owners in Sweden"
- "The go-to tool for indie designers" - "The go-to tool for indie designers"
- "Make project management actually enjoyable"</ask> - "Make project management actually enjoyable"</ask>
@ -39,6 +41,7 @@ Examples:
<ask>**How would you measure progress toward this vision?** <ask>**How would you measure progress toward this vision?**
Think about: Think about:
- User metrics (adoption, engagement, retention) - User metrics (adoption, engagement, retention)
- Business metrics (revenue, growth, market share) - Business metrics (revenue, growth, market share)
- Quality metrics (satisfaction, referrals, reviews) - Quality metrics (satisfaction, referrals, reviews)
@ -46,12 +49,13 @@ Think about:
What numbers would make you confident you're on track?</ask> What numbers would make you confident you're on track?</ask>
<action>For each metric mentioned, help make it SMART: <action>For each metric mentioned, help make it SMART:
- **S**pecific - What exactly? - **S**pecific - What exactly?
- **M**easurable - What number? - **M**easurable - What number?
- **A**chievable - Is this realistic? - **A**chievable - Is this realistic?
- **R**elevant - Does this connect to the vision? - **R**elevant - Does this connect to the vision?
- **T**ime-bound - By when? - **T**ime-bound - By when?
</action> </action>
<action>Aim for 3-5 clear objectives</action> <action>Aim for 3-5 clear objectives</action>
</step> </step>
@ -62,6 +66,7 @@ What numbers would make you confident you're on track?</ask>
<action>For each objective, walk through: <action>For each objective, walk through:
Example transformation: Example transformation:
- Vague: "Get influential users" - Vague: "Get influential users"
- SMART: "Onboard 10 verified dog trainers with 1000+ followers by Q4 2026" - SMART: "Onboard 10 verified dog trainers with 1000+ followers by Q4 2026"
@ -71,10 +76,11 @@ Present each refined objective for confirmation.</action>
{{#each objectives}} {{#each objectives}}
**Objective {{@index + 1}}:** {{this.statement}} **Objective {{@index + 1}}:** {{this.statement}}
- Metric: {{this.metric}} - Metric: {{this.metric}}
- Target: {{this.target}} - Target: {{this.target}}
- Timeline: {{this.timeline}} - Timeline: {{this.timeline}}
{{/each}} {{/each}}
Do these capture what success looks like? Any adjustments?</ask> Do these capture what success looks like? Any adjustments?</ask>
@ -98,4 +104,3 @@ This gives us clear targets to work toward. Next, we'll identify who can help yo
</step> </step>
</workshop> </workshop>

8
src/modules/wds/workflows/2-trigger-mapping/workshops/2-target-groups/instructions.md
View File

@ -10,10 +10,11 @@
Now we identify the people who matter most to achieving your goals. Now we identify the people who matter most to achieving your goals.
We'll create: We'll create:
- A list of user groups - A list of user groups
- Rich descriptions (personas) - Rich descriptions (personas)
- Understanding of their context</output> - Understanding of their context</output>
</intro> </intro>
<step n="1" goal="Identify user groups"> <step n="1" goal="Identify user groups">
<output>Looking at your objectives: <output>Looking at your objectives:
@ -47,6 +48,7 @@ List the types of people that come to mind.</ask>
<ask>**Which 2-4 groups are most critical to your success?** <ask>**Which 2-4 groups are most critical to your success?**
Consider: Consider:
- Who has the most influence on your objectives? - Who has the most influence on your objectives?
- Who, if delighted, would drive the others? - Who, if delighted, would drive the others?
- Where is the biggest opportunity?</ask> - Where is the biggest opportunity?</ask>
@ -92,8 +94,9 @@ Consider:
**Your Target Groups:** **Your Target Groups:**
{{#each personas}} {{#each personas}}
- **{{this.name}}** - {{this.summary}} - **{{this.name}}** - {{this.summary}}
{{/each}} {{/each}}
These are the people we're designing for. Next, we'll explore what drives them - both toward and away from solutions.</output> These are the people we're designing for. Next, we'll explore what drives them - both toward and away from solutions.</output>
@ -101,4 +104,3 @@ These are the people we're designing for. Next, we'll explore what drives them -
</step> </step>
</workshop> </workshop>

17
src/modules/wds/workflows/2-trigger-mapping/workshops/3-driving-forces/instructions.md
View File

@ -19,12 +19,14 @@ Understanding both is crucial. Research shows people work harder to avoid pain t
<output>For each persona, we'll explore: <output>For each persona, we'll explore:
**Positive Drivers** (toward motivation): **Positive Drivers** (toward motivation):
- Aspirations and dreams - Aspirations and dreams
- Desired outcomes - Desired outcomes
- Experiences they seek - Experiences they seek
- Status or recognition goals - Status or recognition goals
**Negative Drivers** (away-from motivation): **Negative Drivers** (away-from motivation):
- Fears and anxieties - Fears and anxieties
- Problems they want gone - Problems they want gone
- Frustrations they're tired of - Frustrations they're tired of
@ -42,6 +44,7 @@ The magic happens when your design addresses both.</output>
What does {{persona.name}} want to achieve or experience? What does {{persona.name}} want to achieve or experience?
Think about: Think about:
- What would make their day better? - What would make their day better?
- What would they brag about to colleagues? - What would they brag about to colleagues?
- What would make them feel successful?</ask> - What would make them feel successful?</ask>
@ -52,6 +55,7 @@ Think about:
What does {{persona.name}} want to avoid or escape? What does {{persona.name}} want to avoid or escape?
Think about: Think about:
- What keeps them up at night? - What keeps them up at night?
- What frustrations are they tired of? - What frustrations are they tired of?
- What risks worry them? - What risks worry them?
@ -63,13 +67,15 @@ Think about:
✅ **Positive Drivers:** ✅ **Positive Drivers:**
{{#each positive_drivers}} {{#each positive_drivers}}
- {{this}} - {{this}}
{{/each}} {{/each}}
⚠️ **Negative Drivers:** ⚠️ **Negative Drivers:**
{{#each negative_drivers}} {{#each negative_drivers}}
- {{this}} - {{this}}
{{/each}}</output> {{/each}}</output>
<ask>Does this capture what truly motivates {{persona.name}}? Anything to add?</ask> <ask>Does this capture what truly motivates {{persona.name}}? Anything to add?</ask>
@ -82,10 +88,11 @@ Think about:
<output>Looking across all personas, I notice some patterns...</output> <output>Looking across all personas, I notice some patterns...</output>
<action>Analyze for: <action>Analyze for:
- Common drivers across groups - Common drivers across groups
- Unique drivers per group - Unique drivers per group
- Potential conflicts between groups - Potential conflicts between groups
</action> </action>
<output>**Cross-Group Patterns:** <output>**Cross-Group Patterns:**
@ -110,9 +117,10 @@ We've mapped the psychological landscape:
{{#each personas}} {{#each personas}}
**{{this.name}}:** **{{this.name}}:**
- Wants: {{this.top_positive_driver}} - Wants: {{this.top_positive_driver}}
- Avoids: {{this.top_negative_driver}} - Avoids: {{this.top_negative_driver}}
{{/each}} {{/each}}
This is powerful insight. Next, we'll prioritize which groups and drivers to focus on.</output> This is powerful insight. Next, we'll prioritize which groups and drivers to focus on.</output>
@ -120,4 +128,3 @@ This is powerful insight. Next, we'll prioritize which groups and drivers to foc
</step> </step>
</workshop> </workshop>

33
src/modules/wds/workflows/2-trigger-mapping/workshops/4-prioritization/instructions.md
View File

@ -8,6 +8,7 @@
<output>**Workshop 4: Prioritization** 🎯 <output>**Workshop 4: Prioritization** 🎯
Now we make the hard choices. We'll prioritize: Now we make the hard choices. We'll prioritize:
1. Business goals (visions) 1. Business goals (visions)
2. Objectives under each goal 2. Objectives under each goal
3. Target groups 3. Target groups
@ -22,8 +23,9 @@ For each decision, I'll challenge you to explain **why** - because clear reasoni
You have multiple vision areas: You have multiple vision areas:
{{#each visions}} {{#each visions}}
- {{this}} - {{this}}
{{/each}}</output> {{/each}}</output>
<ask>**Which business goal is most critical right now?** <ask>**Which business goal is most critical right now?**
@ -44,7 +46,7 @@ Help me understand your reasoning. What makes this the priority?</ask>
<output>**Your Business Goal Priority:** <output>**Your Business Goal Priority:**
{{#each prioritized_visions}} {{#each prioritized_visions}}
{{@index + 1}}. **{{this.vision}}** {{@index + 1}}. **{{this.vision}}**
*Why:* {{this.reasoning}} _Why:_ {{this.reasoning}}
{{/each}}</output> {{/each}}</output>
<template-output>prioritized_visions</template-output> <template-output>prioritized_visions</template-output>
@ -56,8 +58,9 @@ Help me understand your reasoning. What makes this the priority?</ask>
For "{{top_vision}}", you have these objectives: For "{{top_vision}}", you have these objectives:
{{#each top_vision_objectives}} {{#each top_vision_objectives}}
- {{this.statement}} - {{this.statement}}
{{/each}}</output> {{/each}}</output>
<ask>**Which objective is most important to achieve first?** <ask>**Which objective is most important to achieve first?**
@ -74,7 +77,7 @@ What's your reasoning?</ask>
<output>**Objective Priority for "{{top_vision}}":** <output>**Objective Priority for "{{top_vision}}":**
{{#each prioritized_objectives}} {{#each prioritized_objectives}}
{{@index + 1}}. {{this.statement}} {{@index + 1}}. {{this.statement}}
*Why:* {{this.reasoning}} _Why:_ {{this.reasoning}}
{{/each}}</output> {{/each}}</output>
<template-output>prioritized_objectives</template-output> <template-output>prioritized_objectives</template-output>
@ -85,8 +88,9 @@ What's your reasoning?</ask>
Your target groups: Your target groups:
{{#each personas}} {{#each personas}}
- {{this.name}} - {{this.name}}
{{/each}} {{/each}}
Looking at your top objective: "{{top_objective}}"</output> Looking at your top objective: "{{top_objective}}"</output>
@ -105,7 +109,7 @@ What's the logic?</ask>
<output>**Your Target Group Priority:** <output>**Your Target Group Priority:**
{{#each prioritized_groups}} {{#each prioritized_groups}}
{{@index + 1}}. **{{this.name}}** {{@index + 1}}. **{{this.name}}**
*Why:* {{this.reasoning}} _Why:_ {{this.reasoning}}
{{/each}}</output> {{/each}}</output>
<ask>The top group gets most design attention. Does this ranking reflect your strategy?</ask> <ask>The top group gets most design attention. Does this ranking reflect your strategy?</ask>
@ -123,13 +127,15 @@ What's the logic?</ask>
Their drivers: Their drivers:
✅ Positive: ✅ Positive:
{{#each current_group.positive_drivers}} {{#each current_group.positive_drivers}}
- {{this}} - {{this}}
{{/each}} {{/each}}
⚠️ Negative: ⚠️ Negative:
{{#each current_group.negative_drivers}} {{#each current_group.negative_drivers}}
- {{this}} - {{this}}
{{/each}} {{/each}}
**Rank the top 3-5 drivers** this group cares most about. **Rank the top 3-5 drivers** this group cares most about.
@ -158,18 +164,21 @@ Remember: negative drivers often have more weight (loss aversion).</ask>
**Must Address:** **Must Address:**
{{#each must_address_drivers}} {{#each must_address_drivers}}
- {{this}} - {{this}}
{{/each}} {{/each}}
**Should Address:** **Should Address:**
{{#each should_address_drivers}} {{#each should_address_drivers}}
- {{this}} - {{this}}
{{/each}} {{/each}}
**Could Address (if time permits):** **Could Address (if time permits):**
{{#each could_address_drivers}} {{#each could_address_drivers}}
- {{this}} - {{this}}
{{/each}}</output> {{/each}}</output>
<ask>Does this focus feel right? This guides all feature decisions.</ask> <ask>Does this focus feel right? This guides all feature decisions.</ask>
@ -180,6 +189,7 @@ Remember: negative drivers often have more weight (loss aversion).</ask>
<output>**Workshop 4 Complete!** ✅ <output>**Workshop 4 Complete!** ✅
**Your Strategic Focus:** **Your Strategic Focus:**
- Design primarily for **{{top_group.name}}** - Design primarily for **{{top_group.name}}**
- Address: {{top_drivers_summary}} - Address: {{top_drivers_summary}}
@ -191,4 +201,3 @@ Next, we'll analyze which features best serve these priorities.</output>
</step> </step>
</workshop> </workshop>

15
src/modules/wds/workflows/2-trigger-mapping/workshops/5-feature-impact/instructions.md
View File

@ -12,11 +12,13 @@
Now we create a **Design Brief** - strategic guidance for the designer on which features matter most and to whom. 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: For each feature, we'll assess impact on each persona using a simple scale:
- **High** = Addresses major need or fear - **High** = Addresses major need or fear
- **Medium** = Helpful but not critical - **Medium** = Helpful but not critical
- **Low** = Minimal impact - **Low** = Minimal impact
This creates a scored, prioritized feature list that guides: This creates a scored, prioritized feature list that guides:
- **Phase 4: UX Design** - Which scenarios to design first - **Phase 4: UX Design** - Which scenarios to design first
- **Phase 6: PRD/Development** - Epic and story prioritization - **Phase 6: PRD/Development** - Epic and story prioritization
@ -43,6 +45,7 @@ Skip foundational features (auth, profiles, basic CRUD).
<output>I'm creating your Feature Impact Analysis document. <output>I'm creating your Feature Impact Analysis document.
**Scoring:** **Scoring:**
- **Primary Persona:** High = 5 pts | Medium = 3 pts | Low = 1 pt - **Primary Persona:** High = 5 pts | Medium = 3 pts | Low = 1 pt
- **Other Personas:** High = 3 pts | Medium = 1 pt | Low = 0 pts - **Other Personas:** High = 3 pts | Medium = 1 pt | Low = 0 pts
@ -66,9 +69,10 @@ How does this impact each persona?</output>
<action>Record response</action> <action>Record response</action>
<action>Calculate score: <action>Calculate score:
- Primary: High=5, Medium=3, Low=1 - Primary: High=5, Medium=3, Low=1
- Others: High=3, Medium=1, Low=0 - Others: High=3, Medium=1, Low=0
</action> </action>
<output>✓ **{{current_feature}}** — Score: {{calculated_score}}</output> <output>✓ **{{current_feature}}** — Score: {{calculated_score}}</output>
@ -89,17 +93,19 @@ How does this impact each persona?</output>
<action>Sort features by score (high to low)</action> <action>Sort features by score (high to low)</action>
<action>Calculate dynamic thresholds based on persona count: <action>Calculate dynamic thresholds based on persona count:
- max_possible = 5 (primary high) + 3 × (other_persona_count) - max_possible = 5 (primary high) + 3 × (other_persona_count)
- must_have_threshold = Features with Primary High (5) OR score ≥ (max_possible - 3) - must_have_threshold = Features with Primary High (5) OR score ≥ (max_possible - 3)
- consider_threshold = mid-range scores - consider_threshold = mid-range scores
- defer_threshold = low scores - defer_threshold = low scores
</action> </action>
<action>Apply decisions: <action>Apply decisions:
- **Must Have:** Primary scored High (5 pts) OR score in top tier - **Must Have:** Primary scored High (5 pts) OR score in top tier
- **Consider:** Medium-range scores, might serve strategic needs - **Consider:** Medium-range scores, might serve strategic needs
- **Defer:** Low scores, minimal strategic value - **Defer:** Low scores, minimal strategic value
</action> </action>
<output>**Scoring complete!** Here's your prioritized feature list: <output>**Scoring complete!** Here's your prioritized feature list:
@ -108,6 +114,7 @@ How does this impact each persona?</output>
{{/each}} {{/each}}
**Scoring context:** **Scoring context:**
- Max possible score with {{persona_count}} personas: {{max_possible}} - Max possible score with {{persona_count}} personas: {{max_possible}}
- Top tier (Must Have): {{must_have_threshold}}+ - Top tier (Must Have): {{must_have_threshold}}+
- Primary critical (Must Have): Features with Primary High (5) - 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` **Saved to:** `B-Trigger-Map/00-feature-impact-analysis.md`
This is your **Design Brief** - it tells the designer: This is your **Design Brief** - it tells the designer:
- **What to design first** - Top-scoring features = priority scenarios - **What to design first** - Top-scoring features = priority scenarios
- **Prominence in UI** - High scores = prominent placement - **Prominence in UI** - High scores = prominent placement
- **Who to optimize for** - Which persona's needs matter most - **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!** 🎉 **Trigger Mapping Complete!** 🎉
You now have: You now have:
- Clear business priorities - Clear business priorities
- Defined target personas with drivers - Defined target personas with drivers
- Strategically ranked features - Strategically ranked features

91
src/modules/wds/workflows/3-prd-platform/instructions.md
View File

@ -50,11 +50,13 @@ Before starting, ensure you have:
**Freyja's Role:** **Freyja's Role:**
Greet the user and explain this phase: Greet the user and explain this phase:
- "We're establishing your technical foundation—proving that innovative features work before investing in design." - "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." - "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." - "This enables backend development to start in parallel with UX design."
Review available context: Review available context:
- Read the Product Brief to understand project scope and constraints - Read the Product Brief to understand project scope and constraints
- Read the Feature Impact Analysis to identify high-priority features - Read the Feature Impact Analysis to identify high-priority features
- Ask: "Do you already have any technical constraints or platform preferences?" - Ask: "Do you already have any technical constraints or platform preferences?"
@ -230,6 +232,7 @@ Read the Product Brief and identify relevant integration categories based on fea
**Go through each relevant category systematically:** **Go through each relevant category systematically:**
**3A: Authentication & Identity** **3A: Authentication & Identity**
- "How will users authenticate?" (OAuth, email/password, SSO, passwordless) - "How will users authenticate?" (OAuth, email/password, SSO, passwordless)
- "Which providers?" (Google, Microsoft, Auth0, etc.) - "Which providers?" (Google, Microsoft, Auth0, etc.)
- **Document for each:** - **Document for each:**
@ -240,6 +243,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Technical risk (high/medium/low) - Technical risk (high/medium/low)
**3B: Payment Processing** (if applicable) **3B: Payment Processing** (if applicable)
- "Do you need payment processing?" - "Do you need payment processing?"
- "Which payment providers?" (Stripe, PayPal, Klarna, Swish, regional systems) - "Which payment providers?" (Stripe, PayPal, Klarna, Swish, regional systems)
- "What payment methods?" (credit cards, bank transfers, mobile payments, digital wallets) - "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 - Technical risk level
**3C: Communication Services** **3C: Communication Services**
- "Do you need to send emails?" → Which service? (SendGrid, Mailgun, AWS SES, Postmark) - "Do you need to send emails?" → Which service? (SendGrid, Mailgun, AWS SES, Postmark)
- "Do you need SMS?" → Which service? (Twilio, MessageBird, Vonage) - "Do you need SMS?" → Which service? (Twilio, MessageBird, Vonage)
- "Push notifications?" → Which service? (Firebase Cloud Messaging, OneSignal, Pusher) - "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 - Priority & cost
**3D: Search Services** (if applicable) **3D: Search Services** (if applicable)
- "Do you need advanced search functionality?" - "Do you need advanced search functionality?"
- "Which service?" (Algolia, Elasticsearch, Typesense, Meilisearch) - "Which service?" (Algolia, Elasticsearch, Typesense, Meilisearch)
- **Document for each:** - **Document for each:**
@ -295,6 +301,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost - Priority & cost
**3E: Maps & Location** (if applicable) **3E: Maps & Location** (if applicable)
- "Do you need maps or geolocation?" - "Do you need maps or geolocation?"
- "Which service?" (Google Maps, Mapbox, OpenStreetMap, Here) - "Which service?" (Google Maps, Mapbox, OpenStreetMap, Here)
- **Document for each:** - **Document for each:**
@ -313,6 +320,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & risk level - Priority & risk level
**3F: Data & Analytics** **3F: Data & Analytics**
- "What analytics do you need?" (Google Analytics, Mixpanel, Amplitude, custom) - "What analytics do you need?" (Google Analytics, Mixpanel, Amplitude, custom)
- "Error tracking?" (Sentry, Rollbar, Bugsnag) - "Error tracking?" (Sentry, Rollbar, Bugsnag)
- "Application monitoring?" (New Relic, Datadog, AppDynamics) - "Application monitoring?" (New Relic, Datadog, AppDynamics)
@ -329,6 +337,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost - Priority & cost
**3G: Storage & Media** **3G: Storage & Media**
- "Do you need file/image storage?" (S3, Azure Blob, Google Cloud Storage, Cloudinary) - "Do you need file/image storage?" (S3, Azure Blob, Google Cloud Storage, Cloudinary)
- "CDN for assets?" (CloudFlare, Fastly, AWS CloudFront) - "CDN for assets?" (CloudFlare, Fastly, AWS CloudFront)
- "Video hosting/streaming?" (Vimeo, YouTube, Mux, AWS Media Services) - "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 - Priority & cost
**3H: Calendar & Scheduling** (if applicable) **3H: Calendar & Scheduling** (if applicable)
- "Do you need calendar integrations?" - "Do you need calendar integrations?"
- "Which services?" (Google Calendar, Outlook/Microsoft 365, iCal) - "Which services?" (Google Calendar, Outlook/Microsoft 365, iCal)
- "Scheduling/booking systems?" (Calendly-style booking) - "Scheduling/booking systems?" (Calendly-style booking)
@ -360,6 +370,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost - Priority & cost
**3I: Social Media & Content** (if applicable) **3I: Social Media & Content** (if applicable)
- "Do you need social media integrations?" - "Do you need social media integrations?"
- "Which platforms?" (Facebook, Twitter/X, LinkedIn, Instagram) - "Which platforms?" (Facebook, Twitter/X, LinkedIn, Instagram)
- "Social login?" (covered in 3A, but cross-reference) - "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 - Priority & cost
**3J: Customer Support & Help** (if applicable) **3J: Customer Support & Help** (if applicable)
- "Do you need customer support tools?" - "Do you need customer support tools?"
- "Which services?" (Intercom, Zendesk, Helpscout, Crisp) - "Which services?" (Intercom, Zendesk, Helpscout, Crisp)
- "Live chat?" (service or custom) - "Live chat?" (service or custom)
@ -388,6 +400,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost - Priority & cost
**3K: Marketing & Growth** (if applicable) **3K: Marketing & Growth** (if applicable)
- "Do you need marketing automation?" - "Do you need marketing automation?"
- "Which services?" (Mailchimp, HubSpot, ActiveCampaign) - "Which services?" (Mailchimp, HubSpot, ActiveCampaign)
- "A/B testing?" (Optimizely, VWO, custom) - "A/B testing?" (Optimizely, VWO, custom)
@ -402,6 +415,7 @@ Read the Product Brief and identify relevant integration categories based on fea
- Priority & cost - Priority & cost
**3L: Domain-Specific APIs** **3L: Domain-Specific APIs**
- "Any other APIs specific to your domain?" (industry-specific services) - "Any other APIs specific to your domain?" (industry-specific services)
- Examples: Weather APIs, financial data, shipping/logistics, government data, industry databases - Examples: Weather APIs, financial data, shipping/logistics, government data, industry databases
- **Document for each:** - **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). **Goal:** Determine which features need Proofs of Concept (PoCs).
Review the Feature Impact Analysis and ask: Review the Feature Impact Analysis and ask:
- **Which features are innovative or unproven?** - **Which features are innovative or unproven?**
- **Which features depend on external APIs that might have limitations?** - **Which features depend on external APIs that might have limitations?**
- **Which features have unknown performance characteristics?** - **Which features have unknown performance characteristics?**
- **Which features might not be technically feasible?** - **Which features might not be technically feasible?**
**Red Flags That Suggest PoC Needed:** **Red Flags That Suggest PoC Needed:**
- "Can we actually get X data from Y service?" - "Can we actually get X data from Y service?"
- "Will this perform fast enough?" - "Will this perform fast enough?"
- "Does this API return data in a usable format?" - "Does this API return data in a usable format?"
- "Can we achieve real-time updates at scale?" - "Can we achieve real-time updates at scale?"
Create a list of features requiring validation, prioritized by: Create a list of features requiring validation, prioritized by:
1. **High Feature Impact Score** (from Phase 2) + **High Technical Risk** 1. **High Feature Impact Score** (from Phase 2) + **High Technical Risk**
2. **Medium Feature Impact** + **High Technical Risk** 2. **Medium Feature Impact** + **High Technical Risk**
3. **High Feature Impact** + **Medium 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. **Output:** Create `02-Technical-Proofs-Of-Concept.md` documenting all PoC work.
**Positive Framing:** **Positive Framing:**
- When features work: "Great! This proves [feature] is technically sound. Design can proceed with confidence." - 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 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." - 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?" "Let's start with authentication. Based on our security framework, what auth endpoints do you need?"
For each endpoint: For each endpoint:
- Method & Path (e.g., `POST /api/auth/login`) - Method & Path (e.g., `POST /api/auth/login`)
- Purpose & business value - Purpose & business value
- Request/response format with detailed schemas - 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: Go through each entity from the data model systematically:
For each entity, define all CRUD operations: For each entity, define all CRUD operations:
- `GET /api/{entity}` - List with pagination - `GET /api/{entity}` - List with pagination
- `GET /api/{entity}/:id` - Get single item - `GET /api/{entity}/:id` - Get single item
- `POST /api/{entity}` - Create new - `POST /api/{entity}` - Create new
@ -643,17 +663,19 @@ For each entity, define all CRUD operations:
- `DELETE /api/{entity}/:id` - Delete item - `DELETE /api/{entity}/:id` - Delete item
**Business Rules for each:** **Business Rules for each:**
- Validation rules (required fields, formats, constraints)
- Authorization (who can perform this operation?) - Validation rules (required fields, formats, constraints)
- Pagination parameters (page size, sorting, filtering) - Authorization (who can perform this operation?)
- Related data inclusion (nested objects, joins) - Pagination parameters (page size, sorting, filtering)
- Business logic constraints - Related data inclusion (nested objects, joins)
- Business logic constraints
**7C: External Integration APIs** **7C: External Integration APIs**
"Which external services need API endpoints? Let's create wrappers for each." "Which external services need API endpoints? Let's create wrappers for each."
For each external service from Step 3: For each external service from Step 3:
- Method & Path - Method & Path
- Purpose ("Wraps Google Maps API to get walking time") - Purpose ("Wraps Google Maps API to get walking time")
- Request/response format - Request/response format
@ -672,6 +694,7 @@ For each external service from Step 3:
Examples: availability checks, pricing, recommendations, aggregations Examples: availability checks, pricing, recommendations, aggregations
For each: For each:
- Method & Path - Method & Path
- Purpose & business value - Purpose & business value
- Request/response format - Request/response format
@ -705,6 +728,7 @@ For each:
"We identified your core entities earlier. Now let's document the complete data model." "We identified your core entities earlier. Now let's document the complete data model."
For each entity: For each entity:
- Entity name & purpose - Entity name & purpose
- All fields with types, constraints, defaults - All fields with types, constraints, defaults
- Relationships to other entities (one-to-many, many-to-many) - 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?" "What are your performance and scalability expectations?"
Document systematically: Document systematically:
- **Response Times:** Expected latency for each API category - **Response Times:** Expected latency for each API category
- **Throughput:** Concurrent users, requests per second - **Throughput:** Concurrent users, requests per second
- **Data Volume:** Expected record counts, storage needs - **Data Volume:** Expected record counts, storage needs
@ -732,6 +757,7 @@ Document systematically:
**Ask:** "Any other data modeling or performance considerations we should capture?" **Ask:** "Any other data modeling or performance considerations we should capture?"
**Outputs:** **Outputs:**
- `05-Data-Models.md` - Complete schemas and ERD - `05-Data-Models.md` - Complete schemas and ERD
- `06-Performance-Requirements.md` - Benchmarks and scalability specs - `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." "This document tells the UX team what they need to know about technical possibilities and limitations."
**Include:** **Include:**
- **What's Possible:** Validated features from PoCs, platform capabilities - **What's Possible:** Validated features from PoCs, platform capabilities
- **What Has Limitations:** Technical constraints, API limits, performance characteristics - **What Has Limitations:** Technical constraints, API limits, performance characteristics
- **What Affects Design:** Loading states, offline behavior, real-time vs. polling - **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'?" "How do we know when each platform component is 'done'?"
For each major platform area (auth, integrations, security, etc.): For each major platform area (auth, integrations, security, etc.):
- **Functional Criteria:** What must work? - **Functional Criteria:** What must work?
- **Performance Criteria:** How fast/scalable must it be? - **Performance Criteria:** How fast/scalable must it be?
- **Security Criteria:** What security standards must be met? - **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?" **Ask:** "Any other constraints or success criteria we should document?"
**Outputs:** **Outputs:**
- `07-Technical-Constraints.md` - UX design handoff - `07-Technical-Constraints.md` - UX design handoff
- `08-Acceptance-Criteria.md` - Testable success definitions - `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..." "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: Read the Feature Impact Analysis (B-Trigger-Map/03-Feature-Impact-Analysis.md) and identify:
- **Must Have features** (high scores, high for primary persona) - **Must Have features** (high scores, high for primary persona)
- **Consider for MVP features** (balanced scores) - **Consider for MVP features** (balanced scores)
- **Platform dependencies** - What platform work is needed to enable each high-impact feature? - **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:" "Here's the order I'd recommend, based on Feature Impact Analysis:"
**Priority 1: Enable Must-Have Features** **Priority 1: Enable Must-Have Features**
1. **Foundation First:** Core infrastructure (hosting, database, basic security) 1. **Foundation First:** Core infrastructure (hosting, database, basic security)
2. **High-Impact Dependencies:** Platform work needed for Must-Have features 2. **High-Impact Dependencies:** Platform work needed for Must-Have features
- [Epic] enables [Feature] (Score: X) for [Primary Persona] - [Epic] enables [Feature] (Score: X) for [Primary Persona]
- [Epic] enables [Feature] (Score: Y) for [Primary Persona] - [Epic] enables [Feature] (Score: Y) for [Primary Persona]
**Priority 2: Risk Mitigation** **Priority 2: Risk Mitigation** 3. **Complex Integrations:** External APIs that are risky or complex (fail fast)
3. **Complex Integrations:** External APIs that are risky or complex (fail fast)
- [Integration Epic] enables [Feature] (Score: X)
**Priority 3: Secondary Features** - [Integration Epic] enables [Feature] (Score: X)
4. **Remaining Integrations:** Other external services
5. **Advanced Features:** Performance optimization, advanced security
**Priority 4: Operations** **Priority 3: Secondary Features** 4. **Remaining Integrations:** Other external services 5. **Advanced Features:** Performance optimization, advanced security
6. **Monitoring & Tools:** Logging, analytics, maintenance tools
**Priority 4: Operations** 6. **Monitoring & Tools:** Logging, analytics, maintenance tools
**10D: Feature-to-Epic Mapping** **10D: Feature-to-Epic Mapping**
@ -862,12 +890,14 @@ Create a table:
**10E: API Contracts for Future UI Development** **10E: API Contracts for Future UI Development**
"These API specifications are ready for frontend development:" "These API specifications are ready for frontend development:"
- [List key API categories organized by priority features they enable] - [List key API categories organized by priority features they enable]
- Backend can implement these in parallel with Phase 4 (UX Design) - Backend can implement these in parallel with Phase 4 (UX Design)
**10F: Dependencies & Parallel Work** **10F: Dependencies & Parallel Work**
"Key dependencies to consider:" "Key dependencies to consider:"
- What must be done before high-impact features can be built? - What must be done before high-impact features can be built?
- What can be developed independently in parallel? - What can be developed independently in parallel?
- What provides the most risk reduction AND feature enablement if done early? - 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?" **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: **Output:** Create `09-Platform-Backlog-Recommendations.md` with:
- **Feature Impact Summary** - High-priority features from Phase 2 - **Feature Impact Summary** - High-priority features from Phase 2
- **Feature-to-Epic Mapping** - Clear connections between features and platform work - **Feature-to-Epic Mapping** - Clear connections between features and platform work
- Recommended initiative structure - Recommended initiative structure
@ -901,8 +932,8 @@ Create a table:
```markdown ```markdown
# Product Requirements Document: [Project Name] # Product Requirements Document: [Project Name]
*Phase 3 Complete: Technical Foundation Established* _Phase 3 Complete: Technical Foundation Established_
*Last Updated: [Date]* _Last Updated: [Date]_
--- ---
@ -916,30 +947,39 @@ Create a table:
## 2. Technical Foundation (Phase 3) ## 2. Technical Foundation (Phase 3)
### 2.1 Platform Architecture ### 2.1 Platform Architecture
[Link to C-Requirements/00-Platform-Architecture.md] [Link to C-Requirements/00-Platform-Architecture.md]
### 2.2 External Integrations ### 2.2 External Integrations
[Link to C-Requirements/01-Integration-Map.md] [Link to C-Requirements/01-Integration-Map.md]
### 2.3 Technical Validation ### 2.3 Technical Validation
[Link to C-Requirements/02-Technical-Proofs-Of-Concept.md] [Link to C-Requirements/02-Technical-Proofs-Of-Concept.md]
### 2.4 Security & Compliance ### 2.4 Security & Compliance
[Link to C-Requirements/03-Security-Framework.md] [Link to C-Requirements/03-Security-Framework.md]
### 2.5 API Specifications ### 2.5 API Specifications
[Link to C-Requirements/04-API-Specifications.md] [Link to C-Requirements/04-API-Specifications.md]
### 2.6 Data Models ### 2.6 Data Models
[Link to C-Requirements/05-Data-Models.md] [Link to C-Requirements/05-Data-Models.md]
### 2.7 Performance Requirements ### 2.7 Performance Requirements
[Link to C-Requirements/06-Performance-Requirements.md] [Link to C-Requirements/06-Performance-Requirements.md]
### 2.8 Technical Constraints ### 2.8 Technical Constraints
[Link to C-Requirements/07-Technical-Constraints.md] [Link to C-Requirements/07-Technical-Constraints.md]
### 2.9 Acceptance Criteria ### 2.9 Acceptance Criteria
[Link to C-Requirements/08-Acceptance-Criteria.md] [Link to C-Requirements/08-Acceptance-Criteria.md]
--- ---
@ -949,6 +989,7 @@ Create a table:
[Link to C-Requirements/09-Platform-Backlog-Recommendations.md] [Link to C-Requirements/09-Platform-Backlog-Recommendations.md]
**Summary:** **Summary:**
- **Recommended Initiatives:** [List] - **Recommended Initiatives:** [List]
- **Suggested Epics:** [Count] - **Suggested Epics:** [Count]
- **API Contracts Ready:** [Key APIs] - **API Contracts Ready:** [Key APIs]
@ -958,24 +999,28 @@ Create a table:
## 4. Functional Requirements (Phase 4) ## 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] ### [Feature Area 1]
*Coming from Phase 4*
_Coming from Phase 4_
### [Feature Area 2] ### [Feature Area 2]
*Coming from Phase 4*
_Coming from Phase 4_
--- ---
## 5. Next Steps ## 5. Next Steps
**For BMM Agents:** **For BMM Agents:**
- Use platform backlog recommendations to create E-Backlog/ structure - Use platform backlog recommendations to create E-Backlog/ structure
- Create detailed epics and stories from requirements documents - Create detailed epics and stories from requirements documents
- Establish implementation roadmap with dependencies - Establish implementation roadmap with dependencies
**For Phase 4 (UX Design):** **For Phase 4 (UX Design):**
- Technical constraints document provides design boundaries - Technical constraints document provides design boundaries
- API specifications define data available to UI - API specifications define data available to UI
- Begin UX design with confidence in technical feasibility - 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?"** 7. **"Anything about performance, scalability, or deployment we should capture?"**
**If user identifies gaps:** **If user identifies gaps:**
- Document the additional items in the appropriate files - Document the additional items in the appropriate files
- "Great catch! Let me add that to [relevant document]..." - "Great catch! Let me add that to [relevant document]..."
- After adding, return to completeness check - After adding, return to completeness check
@ -1062,6 +1108,7 @@ Create a table:
- Each completed page will add functional requirements to the PRD - Each completed page will add functional requirements to the PRD
**What happens next:** **What happens next:**
- Platform backlog recommendations guide BMM agents in creating E-Backlog/ - Platform backlog recommendations guide BMM agents in creating E-Backlog/
- Development teams can begin platform work based on requirements - Development teams can begin platform work based on requirements
- Phase 4 (UX Design) can begin, informed by technical constraints - Phase 4 (UX Design) can begin, informed by technical constraints
@ -1075,22 +1122,27 @@ Create a table:
### For Freyja the PM: ### For Freyja the PM:
**Validate Early, Often:** **Validate Early, Often:**
- Don't let risky features proceed without PoC validation - Don't let risky features proceed without PoC validation
- "Let's prove this works before investing in design" - "Let's prove this works before investing in design"
**Positive Language:** **Positive Language:**
- Frame discoveries as valuable, not failures - Frame discoveries as valuable, not failures
- "Great that we learned this now, not after design is complete" - "Great that we learned this now, not after design is complete"
**Stay Connected to Strategy:** **Stay Connected to Strategy:**
- Reference Feature Impact Analysis scores when prioritizing PoCs - Reference Feature Impact Analysis scores when prioritizing PoCs
- High-impact features deserve thorough validation - High-impact features deserve thorough validation
**Enable Parallel Work:** **Enable Parallel Work:**
- Think about what backend teams can start building immediately - Think about what backend teams can start building immediately
- Experimental endpoints should focus on clear, achievable tasks - Experimental endpoints should focus on clear, achievable tasks
**Document for Design:** **Document for Design:**
- Technical Constraints doc is crucial for Phase 4 success - Technical Constraints doc is crucial for Phase 4 success
- Be specific about what design needs to accommodate - 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_

36
src/modules/wds/workflows/3-prd-platform/templates/experimental-endpoints.template.md
View File

@ -9,6 +9,7 @@
## Purpose ## Purpose
These are early API specifications for endpoints we know we'll need. Setting them up now enables: These are early API specifications for endpoints we know we'll need. Setting them up now enables:
- Early backend development (parallel with UX design) - Early backend development (parallel with UX design)
- Validation that our data model works - Validation that our data model works
- Fail-fast discovery of integration issues - 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 ## Authentication Endpoints
{{#each auth_endpoints}} {{#each auth_endpoints}}
### {{this.method}} {{this.path}} ### {{this.method}} {{this.path}}
**Status:** {{this.status}} **Status:** {{this.status}}
**Purpose:** {{this.purpose}} **Purpose:** {{this.purpose}}
**Request:** **Request:**
```json ```json
{{this.request_example}} {{this.request_example}}
``` ```
**Response:** **Response:**
```json ```json
{{this.response_example}} {{this.response_example}}
``` ```
@ -45,11 +49,13 @@ These are early API specifications for endpoints we know we'll need. Setting the
**Notes:** {{this.notes}} **Notes:** {{this.notes}}
--- ---
{{/each}} {{/each}}
## Core CRUD Operations ## Core CRUD Operations
{{#each crud_endpoints}} {{#each crud_endpoints}}
### {{this.method}} {{this.path}} ### {{this.method}} {{this.path}}
**Status:** {{this.status}} **Status:** {{this.status}}
@ -57,11 +63,13 @@ These are early API specifications for endpoints we know we'll need. Setting the
**Entity:** {{this.entity}} **Entity:** {{this.entity}}
**Request:** **Request:**
```json ```json
{{this.request_example}} {{this.request_example}}
``` ```
**Response:** **Response:**
```json ```json
{{this.response_example}} {{this.response_example}}
``` ```
@ -70,11 +78,13 @@ These are early API specifications for endpoints we know we'll need. Setting the
**Notes:** {{this.notes}} **Notes:** {{this.notes}}
--- ---
{{/each}} {{/each}}
## External Integration Endpoints ## External Integration Endpoints
{{#each integration_endpoints}} {{#each integration_endpoints}}
### {{this.method}} {{this.path}} ### {{this.method}} {{this.path}}
**Status:** {{this.status}} **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}} **External Service:** {{this.external_service}}
**Request:** **Request:**
```json ```json
{{this.request_example}} {{this.request_example}}
``` ```
**Response:** **Response:**
```json ```json
{{this.response_example}} {{this.response_example}}
``` ```
**Validates:** **Validates:**
- {{#each this.validates}} - {{#each this.validates}}
- {{this}} - {{this}}
{{/each}} {{/each}}
**Cost per Call:** {{this.cost_per_call}} **Cost per Call:** {{this.cost_per_call}}
**Rate Limits:** {{this.rate_limits}} **Rate Limits:** {{this.rate_limits}}
**Notes:** {{this.notes}} **Notes:** {{this.notes}}
--- ---
{{/each}} {{/each}}
## Business Logic Endpoints ## Business Logic Endpoints
{{#each logic_endpoints}} {{#each logic_endpoints}}
### {{this.method}} {{this.path}} ### {{this.method}} {{this.path}}
**Status:** {{this.status}} **Status:** {{this.status}}
**Purpose:** {{this.purpose}} **Purpose:** {{this.purpose}}
**Request:** **Request:**
```json ```json
{{this.request_example}} {{this.request_example}}
``` ```
**Response:** **Response:**
```json ```json
{{this.response_example}} {{this.response_example}}
``` ```
**Business Rules:** **Business Rules:**
{{#each this.business_rules}} {{#each this.business_rules}}
- {{this}} - {{this}}
{{/each}} {{/each}}
**Notes:** {{this.notes}} **Notes:** {{this.notes}}
--- ---
{{/each}} {{/each}}
## Error Handling ## Error Handling
@ -149,27 +168,32 @@ These are early API specifications for endpoints we know we'll need. Setting the
### Common Error Codes ### Common Error Codes
{{#each error_codes}} {{#each error_codes}}
- **{{this.code}}** ({{this.http_status}}): {{this.description}} - **{{this.code}}** ({{this.http_status}}): {{this.description}}
{{/each}} {{/each}}
--- ---
## API Conventions ## API Conventions
### Base URL ### Base URL
``` ```
{{api_base_url}} {{api_base_url}}
``` ```
### Authentication ### Authentication
{{api_authentication_method}} {{api_authentication_method}}
### Request Headers ### Request Headers
``` ```
{{api_request_headers}} {{api_request_headers}}
``` ```
### Response Format ### Response Format
{{api_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: These endpoints are also tracked in `E-PRD-Finalization/` as handoff tasks:
{{#each development_tasks}} {{#each development_tasks}}
- [ ] **{{this.endpoint}}** - {{this.description}} (Priority: {{this.priority}}) - [ ] **{{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}}_

36
src/modules/wds/workflows/3-prd-platform/templates/platform-architecture.template.md
View File

@ -9,24 +9,28 @@
## Technology Stack ## Technology Stack
### Backend ### Backend
- **Framework/Language:** {{backend_framework}} - **Framework/Language:** {{backend_framework}}
- **Runtime:** {{backend_runtime}} - **Runtime:** {{backend_runtime}}
- **Rationale:** {{backend_rationale}} - **Rationale:** {{backend_rationale}}
### Frontend ### Frontend
- **Framework:** {{frontend_framework}} - **Framework:** {{frontend_framework}}
- **UI Library:** {{ui_library}} - **UI Library:** {{ui_library}}
- **Rationale:** {{frontend_rationale}} - **Rationale:** {{frontend_rationale}}
### Database ### Database
- **Primary Database:** {{primary_database}} - **Primary Database:** {{primary_database}}
- **Type:** {{database_type}} - **Type:** {{database_type}}
- **Rationale:** {{database_rationale}} - **Rationale:** {{database_rationale}}
{{#if secondary_database}} {{#if secondary_database}}
- **Secondary Database:** {{secondary_database}} - **Secondary Database:** {{secondary_database}}
- **Purpose:** {{secondary_purpose}} - **Purpose:** {{secondary_purpose}}
{{/if}} {{/if}}
--- ---
@ -35,36 +39,42 @@
**Approach:** {{architecture_style}} **Approach:** {{architecture_style}}
{{#if architecture_style == "Monolith"}} {{#if architecture_style == "Monolith"}}
- Single codebase deployment - Single codebase deployment
- Simplified development and deployment - Simplified development and deployment
- {{monolith_rationale}} - {{monolith_rationale}}
{{/if}} {{/if}}
{{#if architecture_style == "Microservices"}} {{#if architecture_style == "Microservices"}}
- Service boundaries: {{service_boundaries}} - Service boundaries: {{service_boundaries}}
- Communication: {{service_communication}} - Communication: {{service_communication}}
- {{microservices_rationale}} - {{microservices_rationale}}
{{/if}} {{/if}}
{{#if architecture_style == "Serverless"}} {{#if architecture_style == "Serverless"}}
- Functions: {{serverless_functions}} - Functions: {{serverless_functions}}
- Triggers: {{serverless_triggers}} - Triggers: {{serverless_triggers}}
- {{serverless_rationale}} - {{serverless_rationale}}
{{/if}} {{/if}}
--- ---
## Infrastructure & Hosting ## Infrastructure & Hosting
### Platform ### Platform
- **Cloud Provider:** {{cloud_provider}} - **Cloud Provider:** {{cloud_provider}}
- **Hosting Type:** {{hosting_type}} - **Hosting Type:** {{hosting_type}}
- **Rationale:** {{infrastructure_rationale}} - **Rationale:** {{infrastructure_rationale}}
### Services ### Services
{{#each infrastructure_services}} {{#each infrastructure_services}}
- **{{this.name}}:** {{this.description}} - **{{this.name}}:** {{this.description}}
{{/each}} {{/each}}
--- ---
@ -73,19 +83,22 @@
### Core Entities ### Core Entities
{{#each core_entities}} {{#each core_entities}}
#### {{this.name}} #### {{this.name}}
**Purpose:** {{this.purpose}} **Purpose:** {{this.purpose}}
**Key Fields:** **Key Fields:**
{{#each this.fields}} {{#each this.fields}}
- `{{this.name}}` ({{this.type}}) - {{this.description}} - `{{this.name}}` ({{this.type}}) - {{this.description}}
{{/each}} {{/each}}
**Relationships:** **Relationships:**
{{#each this.relationships}} {{#each this.relationships}}
- {{this.type}} {{this.target}} - {{this.description}} - {{this.type}} {{this.target}} - {{this.description}}
{{/each}} {{/each}}
{{/each}} {{/each}}
@ -124,8 +137,9 @@
## Technical Constraints ## Technical Constraints
{{#each technical_constraints}} {{#each technical_constraints}}
- **{{this.area}}:** {{this.constraint}} - **{{this.area}}:** {{this.constraint}}
{{/each}} {{/each}}
--- ---
@ -134,12 +148,12 @@
### Monthly Operating Costs (Estimated) ### Monthly Operating Costs (Estimated)
{{#each cost_estimates}} {{#each cost_estimates}}
- **{{this.service}}:** {{this.cost}} {{this.currency}} - **{{this.service}}:** {{this.cost}} {{this.currency}}
{{/each}} {{/each}}
**Total Estimated:** {{total_monthly_cost}} {{currency}}/month **Total Estimated:** {{total_monthly_cost}} {{currency}}/month
--- ---
*Phase 3 artifact for {{project_name}}* _Phase 3 artifact for {{project_name}}_

36
src/modules/wds/workflows/3-prd-platform/templates/technical-constraints.template.md
View File

@ -18,6 +18,7 @@ This document summarizes technical decisions and constraints that inform UX desi
### Validated Features ### Validated Features
{{#each validated_features}} {{#each validated_features}}
#### {{this.feature_name}} #### {{this.feature_name}}
**Status:** {{this.status}} **Status:** {{this.status}}
@ -29,8 +30,9 @@ This document summarizes technical decisions and constraints that inform UX desi
### Platform Capabilities ### Platform Capabilities
{{#each platform_capabilities}} {{#each platform_capabilities}}
- **{{this.capability}}:** {{this.description}} - **{{this.capability}}:** {{this.description}}
{{/each}} {{/each}}
--- ---
@ -39,6 +41,7 @@ This document summarizes technical decisions and constraints that inform UX desi
### Technical Limitations ### Technical Limitations
{{#each limitations}} {{#each limitations}}
#### {{this.area}} #### {{this.area}}
**Constraint:** {{this.constraint}} **Constraint:** {{this.constraint}}
@ -50,8 +53,9 @@ This document summarizes technical decisions and constraints that inform UX desi
### External API Constraints ### External API Constraints
{{#each api_constraints}} {{#each api_constraints}}
- **{{this.service}}:** {{this.constraint}} - {{this.design_impact}} - **{{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 ### Performance Characteristics
{{#each performance_characteristics}} {{#each performance_characteristics}}
#### {{this.operation}} #### {{this.operation}}
- **Expected Time:** {{this.time}} - **Expected Time:** {{this.time}}
@ -71,8 +76,9 @@ This document summarizes technical decisions and constraints that inform UX desi
### Connection Requirements ### Connection Requirements
{{#each connection_requirements}} {{#each connection_requirements}}
- **{{this.feature}}:** {{this.requirement}} - {{this.design_impact}} - **{{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 ### Cost-Sensitive Features
{{#each expensive_features}} {{#each expensive_features}}
#### {{this.feature}} #### {{this.feature}}
**Cost Driver:** {{this.cost_driver}} **Cost Driver:** {{this.cost_driver}}
@ -94,12 +101,15 @@ This document summarizes technical decisions and constraints that inform UX desi
## 🌐 Platform Compatibility ## 🌐 Platform Compatibility
### Browser Support ### Browser Support
{{browser_support}} {{browser_support}}
### Device Support ### Device Support
{{device_support}} {{device_support}}
### Accessibility ### Accessibility
{{accessibility_considerations}} {{accessibility_considerations}}
--- ---
@ -107,12 +117,15 @@ This document summarizes technical decisions and constraints that inform UX desi
## 🔒 Security Constraints ## 🔒 Security Constraints
### Authentication ### Authentication
{{authentication_constraints}} {{authentication_constraints}}
### Data Handling ### Data Handling
{{data_handling_constraints}} {{data_handling_constraints}}
### Compliance ### Compliance
{{compliance_constraints}} {{compliance_constraints}}
--- ---
@ -120,13 +133,17 @@ This document summarizes technical decisions and constraints that inform UX desi
## 📱 Offline Behavior ## 📱 Offline Behavior
{{#if offline_support}} {{#if offline_support}}
### What Works Offline ### What Works Offline
{{offline_capabilities}} {{offline_capabilities}}
### What Requires Connection ### What Requires Connection
{{online_requirements}} {{online_requirements}}
### Sync Strategy ### Sync Strategy
{{sync_strategy}} {{sync_strategy}}
{{else}} {{else}}
**Offline Mode:** Not supported - All features require active connection **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: Based on technical validation:
{{#each design_recommendations}} {{#each design_recommendations}}
### {{this.category}} ### {{this.category}}
{{this.recommendation}} {{this.recommendation}}
@ -153,11 +171,12 @@ Based on technical validation:
{{#if open_questions}} {{#if open_questions}}
{{#each open_questions}} {{#each open_questions}}
- {{this}} - {{this}}
{{/each}} {{/each}}
{{else}} {{else}}
No open questions at this time. No open questions at this time.
{{/if}} {{/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}}_

2
src/modules/wds/workflows/3-prd-platform/workflow.yaml
View File

@ -3,7 +3,6 @@ name: PRD Platform Workflow
description: Establish technical foundation, validate risky features, and set up experimental endpoints description: Establish technical foundation, validate risky features, and set up experimental endpoints
web_bundle: true web_bundle: true
--- ---
# WDS Phase 3: PRD Platform (Technical Foundation) # WDS Phase 3: PRD Platform (Technical Foundation)
name: "Phase 3: PRD Platform (Technical Foundation)" name: "Phase 3: PRD Platform (Technical Foundation)"
agent: "Freyja the PM" agent: "Freyja the PM"
@ -37,4 +36,3 @@ optional_inputs:
- "Existing technical constraints" - "Existing technical constraints"
estimated_duration: "2-4 hours (plus PoC development time)" estimated_duration: "2-4 hours (plus PoC development time)"

16
src/modules/wds/workflows/4-ux-design/ARCHITECTURE.md
View File

@ -81,13 +81,16 @@
## Key Innovations ## Key Innovations
### 1. Step-File Architecture ✅ ### 1. Step-File Architecture ✅
- **Just-in-time loading** - Only current step in memory - **Just-in-time loading** - Only current step in memory
- **Sequential enforcement** - Steps load one at a time - **Sequential enforcement** - Steps load one at a time
- **Clear progression** - 5 main steps → substeps → object-types - **Clear progression** - 5 main steps → substeps → object-types
- **State tracking** - Progress saved between sessions - **State tracking** - Progress saved between sessions
### 2. Granular Specification (8 Micro-Steps) ✅ ### 2. Granular Specification (8 Micro-Steps) ✅
Instead of one large 4C step, broke into focused substeps: Instead of one large 4C step, broke into focused substeps:
1. **Page Basics** - Fundamentals 1. **Page Basics** - Fundamentals
2. **Layout Sections** - Structure 2. **Layout Sections** - Structure
3. **Components & Objects** - Systematic identification 3. **Components & Objects** - Systematic identification
@ -98,6 +101,7 @@ Instead of one large 4C step, broke into focused substeps:
8. **Generate Spec** - Compile document 8. **Generate Spec** - Compile document
### 3. Object-Type Routing System ✅ ### 3. Object-Type Routing System ✅
- **21 specialized object-type files** (6 created, 15 to create) - **21 specialized object-type files** (6 created, 15 to create)
- **Each file has precise examples** for consistency - **Each file has precise examples** for consistency
- **Ensures uniform output** across all WDS projects - **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) ✅✨ ### 4. Intelligent Analysis (Trust-the-Agent) ✅✨
**Old Approach (Procedural):** **Old Approach (Procedural):**
``` ```
What type of object is this? What type of object is this?
1. Button 1. Button
@ -114,6 +119,7 @@ What type of object is this?
``` ```
**New Approach (Intelligent):** **New Approach (Intelligent):**
``` ```
My interpretation: My interpretation:
@ -133,6 +139,7 @@ Does this match your intent? [Y/Clarify/No]
``` ```
**Benefits:** **Benefits:**
- ✅ Agent demonstrates intelligence - ✅ Agent demonstrates intelligence
- ✅ Context-aware interpretation - ✅ Context-aware interpretation
- ✅ Natural conversation - ✅ Natural conversation
@ -140,6 +147,7 @@ Does this match your intent? [Y/Clarify/No]
- ✅ v6 "goal-based trust" philosophy - ✅ v6 "goal-based trust" philosophy
### 5. Systematic Sketch Analysis ✅ ### 5. Systematic Sketch Analysis ✅
- **Top-to-bottom, left-to-right** within sections - **Top-to-bottom, left-to-right** within sections
- **Component reuse detection** across pages - **Component reuse detection** across pages
- **Section-by-section** organization - **Section-by-section** organization
@ -222,21 +230,25 @@ Step 5: Next Steps
## Benefits for WDS Users ## Benefits for WDS Users
**Consistency Across Projects:** **Consistency Across Projects:**
- Same object types documented the same way - Same object types documented the same way
- Every WDS project produces uniform specs - Every WDS project produces uniform specs
- Developers know what to expect - Developers know what to expect
**Agent Clarity:** **Agent Clarity:**
- Focused instructions prevent confusion - Focused instructions prevent confusion
- Clear routing eliminates ambiguity - Clear routing eliminates ambiguity
- Examples guide output format - Examples guide output format
**User Experience:** **User Experience:**
- Intelligent suggestions feel natural - Intelligent suggestions feel natural
- Quick confirmations when agent is right - Quick confirmations when agent is right
- Systematic coverage ensures nothing missed - Systematic coverage ensures nothing missed
**Maintainability:** **Maintainability:**
- Easy to add new object types - Easy to add new object types
- Each file independently improvable - Each file independently improvable
- Clear separation of concerns - Clear separation of concerns
@ -246,6 +258,7 @@ Step 5: Next Steps
## Status ## Status
**✅ Complete:** **✅ Complete:**
- Main workflow structure (5 steps) - Main workflow structure (5 steps)
- All substeps (4A, 4B, 4C-01 through 4C-08, 4D, 4E) - All substeps (4A, 4B, 4C-01 through 4C-08, 4D, 4E)
- Object-router with intelligent analysis - Object-router with intelligent analysis
@ -253,11 +266,10 @@ Step 5: Next Steps
- Templates - Templates
**⏳ To Create:** **⏳ To Create:**
- 15 additional object-type files - 15 additional object-type files
- Object-type files should follow same pattern with precise examples - 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.** 🎨✨ **This architecture ensures consistent, high-quality specifications across all WDS projects while making the agent experience intelligent and natural.** 🎨✨

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

@ -49,6 +49,7 @@ project-root/
**Purpose:** Page-specific layout, component placement, and context **Purpose:** Page-specific layout, component placement, and context
**Contains:** **Contains:**
- Page metadata (URL, scenario, purpose) - Page metadata (URL, scenario, purpose)
- Layout structure (sections, grid) - Layout structure (sections, grid)
- Component instances with page-specific config - Component instances with page-specific config
@ -56,10 +57,12 @@ project-root/
- Navigation flow (entry/exit points) - Navigation flow (entry/exit points)
**Does NOT contain:** **Does NOT contain:**
- Component visual design (→ Components/) - Component visual design (→ Components/)
- Interactive logic (→ Features/) - Interactive logic (→ Features/)
**Example:** `02-calendar-page.md` **Example:** `02-calendar-page.md`
```markdown ```markdown
# 02-calendar-page # 02-calendar-page
@ -69,10 +72,12 @@ project-root/
## Layout Structure ## Layout Structure
### Header Section ### Header Section
- Component: `navigation-bar` (from Components/) - Component: `navigation-bar` (from Components/)
- Position: Top, full-width - Position: Top, full-width
### Main Content ### Main Content
- Component: `calendar-widget` (from Components/) - Component: `calendar-widget` (from Components/)
- Position: Center, 80% width - Position: Center, 80% width
- Configuration: - Configuration:
@ -82,6 +87,7 @@ project-root/
- Feature: `calendar-logic` (from Features/) - Feature: `calendar-logic` (from Features/)
### Sidebar ### Sidebar
- Component: `walk-scheduler` (from Components/) - Component: `walk-scheduler` (from Components/)
- Position: Right, 20% width - Position: Right, 20% width
- Feature: `walk-assignment` (from Features/) - Feature: `walk-assignment` (from Features/)
@ -89,6 +95,7 @@ project-root/
## Content ## Content
**Page Title:** **Page Title:**
- EN: "Family Dog Care Calendar" - EN: "Family Dog Care Calendar"
- SE: "Familjens Hundvårdskalender" - SE: "Familjens Hundvårdskalender"
``` ```
@ -100,6 +107,7 @@ project-root/
**Purpose:** Visual design, states, variants, Figma specifications **Purpose:** Visual design, states, variants, Figma specifications
**Contains:** **Contains:**
- Component name and purpose - Component name and purpose
- Visual specifications (colors, spacing, typography) - Visual specifications (colors, spacing, typography)
- States (default, hover, active, disabled, loading, error) - States (default, hover, active, disabled, loading, error)
@ -109,10 +117,12 @@ project-root/
- Accessibility requirements - Accessibility requirements
**Does NOT contain:** **Does NOT contain:**
- Business logic (→ Features/) - Business logic (→ Features/)
- Page-specific placement (→ Pages/) - Page-specific placement (→ Pages/)
**Example:** `calendar-widget.component.md` **Example:** `calendar-widget.component.md`
```markdown ```markdown
# Calendar Widget Component # Calendar Widget Component
@ -127,18 +137,21 @@ Displays a monthly calendar view with interactive date selection and event displ
## Visual Specifications ## Visual Specifications
### Layout ### Layout
- Grid: 7 columns (days) × 5-6 rows (weeks) - Grid: 7 columns (days) × 5-6 rows (weeks)
- Cell size: 48px × 48px (desktop), 40px × 40px (mobile) - Cell size: 48px × 48px (desktop), 40px × 40px (mobile)
- Gap: 4px between cells - Gap: 4px between cells
- Padding: 16px container padding - Padding: 16px container padding
### Typography ### Typography
- Month/Year header: Large Heading (24px Bold) - Month/Year header: Large Heading (24px Bold)
- Day labels: Caption (12px Medium) - Day labels: Caption (12px Medium)
- Date numbers: Body Text (16px Regular) - Date numbers: Body Text (16px Regular)
- Event indicators: Caption (10px Regular) - Event indicators: Caption (10px Regular)
### Colors ### Colors
- Background: `--color-surface` - Background: `--color-surface`
- Cell default: `--color-surface-elevated` - Cell default: `--color-surface-elevated`
- Cell hover: `--color-surface-hover` - Cell hover: `--color-surface-hover`
@ -149,33 +162,39 @@ Displays a monthly calendar view with interactive date selection and event displ
## States ## States
### Default State ### Default State
- All dates visible - All dates visible
- Current month displayed - Current month displayed
- Today highlighted with accent color - Today highlighted with accent color
- No date selected - No date selected
### Date Selected ### Date Selected
- Selected date: Primary color background - Selected date: Primary color background
- Date number: White text - Date number: White text
- Border: 2px solid primary-dark - Border: 2px solid primary-dark
### Date Hover ### Date Hover
- Background: Surface-hover color - Background: Surface-hover color
- Cursor: Pointer - Cursor: Pointer
- Transition: 150ms ease - Transition: 150ms ease
### Date Disabled (Past dates) ### Date Disabled (Past dates)
- Background: Surface-disabled - Background: Surface-disabled
- Text: Gray-400 - Text: Gray-400
- Cursor: Not-allowed - Cursor: Not-allowed
- No hover effect - No hover effect
### Loading State ### Loading State
- Skeleton animation on date cells - Skeleton animation on date cells
- Month/year header visible - Month/year header visible
- Navigation disabled - Navigation disabled
### With Events ### With Events
- Small dot indicator below date number - Small dot indicator below date number
- Dot color: Event category color - Dot color: Event category color
- Max 3 dots visible per cell - Max 3 dots visible per cell
@ -183,11 +202,13 @@ Displays a monthly calendar view with interactive date selection and event displ
## Variants ## Variants
### Size Variants ### Size Variants
- **Large:** 56px cells (desktop default) - **Large:** 56px cells (desktop default)
- **Medium:** 48px cells (tablet) - **Medium:** 48px cells (tablet)
- **Small:** 40px cells (mobile) - **Small:** 40px cells (mobile)
### View Variants ### View Variants
- **Month View:** Default, shows full month - **Month View:** Default, shows full month
- **Week View:** Shows 7 days in row - **Week View:** Shows 7 days in row
- **Day View:** Shows single day with hourly slots - **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` **Component Path:** `Design System > Widgets > Calendar`
**Variants to Create:** **Variants to Create:**
- Size: Large / Medium / Small - Size: Large / Medium / Small
- View: Month / Week / Day - View: Month / Week / Day
- State: Default / Selected / Disabled / Loading - State: Default / Selected / Disabled / Loading
@ -207,16 +229,19 @@ Displays a monthly calendar view with interactive date selection and event displ
## Responsive Behavior ## Responsive Behavior
### Mobile (< 768px) ### Mobile (< 768px)
- Use Small variant (40px cells) - Use Small variant (40px cells)
- Stack month navigation vertically - Stack month navigation vertically
- Reduce padding to 12px - Reduce padding to 12px
### Tablet (768px - 1024px) ### Tablet (768px - 1024px)
- Use Medium variant (48px cells) - Use Medium variant (48px cells)
- Horizontal month navigation - Horizontal month navigation
- Standard padding (16px) - Standard padding (16px)
### Desktop (> 1024px) ### Desktop (> 1024px)
- Use Large variant (56px cells) - Use Large variant (56px cells)
- Full navigation controls - Full navigation controls
- Increased padding (20px) - Increased padding (20px)
@ -227,12 +252,10 @@ Displays a monthly calendar view with interactive date selection and event displ
- Arrow keys: Navigate between dates - Arrow keys: Navigate between dates
- Enter/Space: Select date - Enter/Space: Select date
- Tab: Move to month navigation - Tab: Move to month navigation
- **Screen Readers:** - **Screen Readers:**
- ARIA label: "Calendar, {Month} {Year}" - ARIA label: "Calendar, {Month} {Year}"
- Each date: "Select {Day}, {Date} {Month}" - Each date: "Select {Day}, {Date} {Month}"
- Selected date: "Selected, {Day}, {Date} {Month}" - Selected date: "Selected, {Day}, {Date} {Month}"
- **Focus Management:** - **Focus Management:**
- Visible focus ring on keyboard navigation - Visible focus ring on keyboard navigation
- Focus trap within calendar when open - 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 **Purpose:** Interactive logic, business rules, data flow, state management
**Contains:** **Contains:**
- Feature name and purpose - Feature name and purpose
- User interactions and system responses - User interactions and system responses
- Business rules and validation - 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 - Edge cases and error handling
**Does NOT contain:** **Does NOT contain:**
- Visual design (→ Components/) - Visual design (→ Components/)
- Page layout (→ Pages/) - Page layout (→ Pages/)
**Example:** `calendar-logic.feature.md` **Example:** `calendar-logic.feature.md`
```markdown
````markdown
# Calendar Logic Feature # Calendar Logic Feature
**Feature ID:** `calendar-logic` **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 **Trigger:** User clicks on a date cell
**Flow:** **Flow:**
1. User clicks date cell 1. User clicks date cell
2. System validates date is not disabled 2. System validates date is not disabled
3. System updates selected date state 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) 6. System updates related components (e.g., event list for that date)
**Business Rules:** **Business Rules:**
- Cannot select dates in the past (configurable) - Cannot select dates in the past (configurable)
- Cannot select dates beyond 1 year in future (configurable) - Cannot select dates beyond 1 year in future (configurable)
- Can only select one date at a time (single-select mode) - Can only select one date at a time (single-select mode)
- Can select date range (range-select mode, if enabled) - Can select date range (range-select mode, if enabled)
**Edge Cases:** **Edge Cases:**
- Clicking already selected date: Deselects it - Clicking already selected date: Deselects it
- Clicking disabled date: No action, show tooltip - Clicking disabled date: No action, show tooltip
- Rapid clicking: Debounce to prevent multiple selections - 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 **Trigger:** User clicks "Next Month" button
**Flow:** **Flow:**
1. User clicks next month button 1. User clicks next month button
2. System increments month by 1 2. System increments month by 1
3. System fetches events for new month (if needed) 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 6. System updates month/year header
**Business Rules:** **Business Rules:**
- Cannot navigate beyond max date (1 year from today) - Cannot navigate beyond max date (1 year from today)
- Loading state shown while fetching events - Loading state shown while fetching events
- Previous selections cleared on month change - 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 **Trigger:** User hovers over date with event indicators
**Flow:** **Flow:**
1. User hovers over date cell with events 1. User hovers over date cell with events
2. System shows tooltip with event summary 2. System shows tooltip with event summary
3. Tooltip displays: Event count, first 2 event titles 3. Tooltip displays: Event count, first 2 event titles
4. User can click to see full event list 4. User can click to see full event list
**Business Rules:** **Business Rules:**
- Tooltip appears after 300ms hover - Tooltip appears after 300ms hover
- Max 2 events shown in tooltip - Max 2 events shown in tooltip
- "And X more" shown if > 2 events - "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 error: string | null // Error message
} }
``` ```
````
### State Transitions ### State Transitions
**Initial State:** **Initial State:**
- currentMonth: Current month - currentMonth: Current month
- selectedDate: null - selectedDate: null
- viewMode: 'month' - viewMode: 'month'
@ -356,10 +391,12 @@ Manages calendar interactions, date selection, event display, and navigation bet
- error: null - error: null
**On Date Select:** **On Date Select:**
- selectedDate: clicked date - selectedDate: clicked date
- Trigger callback: onDateSelect(date) - Trigger callback: onDateSelect(date)
**On Month Change:** **On Month Change:**
- currentMonth: new month - currentMonth: new month
- selectedDate: null (if clearOnMonthChange = true) - selectedDate: null (if clearOnMonthChange = true)
- loading: true - loading: true
@ -367,6 +404,7 @@ Manages calendar interactions, date selection, event display, and navigation bet
- loading: false - loading: false
**On Error:** **On Error:**
- error: error message - error: error message
- loading: false - loading: false
- Show error state in UI - Show error state in UI
@ -376,6 +414,7 @@ Manages calendar interactions, date selection, event display, and navigation bet
### API Endpoints ### API Endpoints
**Get Events for Month** **Get Events for Month**
- **Method:** GET - **Method:** GET
- **Path:** `/api/calendar/events?month={YYYY-MM}` - **Path:** `/api/calendar/events?month={YYYY-MM}`
- **Purpose:** Fetch all events for specified month - **Purpose:** Fetch all events for specified month
@ -395,6 +434,7 @@ Manages calendar interactions, date selection, event display, and navigation bet
``` ```
**Create Event** **Create Event**
- **Method:** POST - **Method:** POST
- **Path:** `/api/calendar/events` - **Path:** `/api/calendar/events`
- **Purpose:** Create new calendar event - **Purpose:** Create new calendar event
@ -411,13 +451,14 @@ Manages calendar interactions, date selection, event display, and navigation bet
### Data Models ### Data Models
**Event Model:** **Event Model:**
```typescript ```typescript
interface Event { interface Event {
id: string; id: string;
date: string; // ISO date format date: string; // ISO date format
title: string; title: string;
category: 'walk' | 'feeding' | 'vet' | 'grooming'; category: 'walk' | 'feeding' | 'vet' | 'grooming';
assignedTo: string; // User ID assignedTo: string; // User ID
completed: boolean; completed: boolean;
notes?: string; notes?: string;
} }
@ -425,21 +466,23 @@ interface Event {
## Validation Rules ## Validation Rules
| Rule | Validation | Error Message | | Rule | Validation | Error Message |
|------|------------|---------------| | ------------ | ----------------------------------------- | -------------------------------------- |
| Date in past | `date < today` | "Cannot select past dates" | | Date in past | `date < today` | "Cannot select past dates" |
| Date too far | `date > today + 365 days` | "Cannot select dates beyond 1 year" | | 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)" | | Event title | `title.length > 0 && title.length <= 100` | "Event title required (max 100 chars)" |
## Error Handling ## Error Handling
### Network Error (Failed to fetch events) ### Network Error (Failed to fetch events)
- **Trigger:** API request fails - **Trigger:** API request fails
- **Action:** Show error state in calendar - **Action:** Show error state in calendar
- **Message:** "Unable to load events. Please try again." - **Message:** "Unable to load events. Please try again."
- **Recovery:** Retry button - **Recovery:** Retry button
### Invalid Date Selection ### Invalid Date Selection
- **Trigger:** User attempts to select disabled date - **Trigger:** User attempts to select disabled date
- **Action:** Show tooltip - **Action:** Show tooltip
- **Message:** "This date is not available" - **Message:** "This date is not available"
@ -467,6 +510,7 @@ interface Event {
- **Component:** `calendar-widget.component.md` (visual design) - **Component:** `calendar-widget.component.md` (visual design)
- **Feature:** `walk-assignment.feature.md` (for creating walk events) - **Feature:** `walk-assignment.feature.md` (for creating walk events)
- **API:** Calendar Events API - **API:** Calendar Events API
``` ```
--- ---
@ -485,10 +529,12 @@ interface Event {
**Component used on multiple pages:** **Component used on multiple pages:**
``` ```
Pages/02-calendar-page.md → Components/calendar-widget.component.md Pages/02-calendar-page.md → Components/calendar-widget.component.md
Pages/05-dashboard.md → Components/calendar-widget.component.md Pages/05-dashboard.md → Components/calendar-widget.component.md
↓ ↓
Features/calendar-logic.feature.md Features/calendar-logic.feature.md
``` ```
**Same component, different configurations:** **Same component, different configurations:**
@ -524,16 +570,19 @@ Pages/05-dashboard.md → Components/calendar-widget.component.md
### Pages ### Pages
``` ```
{number}-{page-name}.md {number}-{page-name}.md
Examples: Examples:
01-start-page.md 01-start-page.md
02-calendar-page.md 02-calendar-page.md
03-profile-settings.md 03-profile-settings.md
``` ```
### Components ### Components
``` ```
{component-name}.component.md {component-name}.component.md
Examples: Examples:
@ -541,10 +590,12 @@ navigation-bar.component.md
feature-card.component.md feature-card.component.md
calendar-widget.component.md calendar-widget.component.md
walk-scheduler.component.md walk-scheduler.component.md
``` ```
### Features ### Features
``` ```
{feature-name}.feature.md {feature-name}.feature.md
Examples: Examples:
@ -552,7 +603,8 @@ calendar-logic.feature.md
walk-assignment.feature.md walk-assignment.feature.md
user-authentication.feature.md user-authentication.feature.md
notification-system.feature.md notification-system.feature.md
```
````
--- ---
@ -570,7 +622,7 @@ Reference components and features:
**Configuration:** **Configuration:**
- View: Month - View: Month
- Disable past dates: true - Disable past dates: true
``` ````
### In Component Files ### In Component Files
@ -599,21 +651,25 @@ Reference related components:
## Migration Strategy ## Migration Strategy
### Phase 1: Create Structure ### Phase 1: Create Structure
1. Create `Components/` folder 1. Create `Components/` folder
2. Create `Features/` folder 2. Create `Features/` folder
3. Keep existing `Pages/` (or create if needed) 3. Keep existing `Pages/` (or create if needed)
### Phase 2: Extract Components ### Phase 2: Extract Components
1. Identify reusable components in page specs 1. Identify reusable components in page specs
2. Create component files with visual design only 2. Create component files with visual design only
3. Update page files to reference components 3. Update page files to reference components
### Phase 3: Extract Features ### Phase 3: Extract Features
1. Identify complex interactive logic 1. Identify complex interactive logic
2. Create feature files with business rules 2. Create feature files with business rules
3. Update page and component files to reference features 3. Update page and component files to reference features
### Phase 4: Refactor Existing Pages ### Phase 4: Refactor Existing Pages
1. Move visual specs → Components/ 1. Move visual specs → Components/
2. Move logic → Features/ 2. Move logic → Features/
3. Keep layout & content in Pages/ 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) 3. **Features/** - Logic, rules, data (WHAT IT DOES)
**Benefits:** **Benefits:**
- ✅ Clear separation of concerns - ✅ Clear separation of concerns
- ✅ Reusable components across pages - ✅ Reusable components across pages
- ✅ Maintainable business logic - ✅ Maintainable business logic

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

@ -30,6 +30,7 @@ Is this CONTENT (text, images, data)?
### 1. Page File (WHERE) ### 1. Page File (WHERE)
**Contains:** **Contains:**
- ✅ Position & size - ✅ Position & size
- ✅ **Page-specific content** (headings, text, images that change per page) - ✅ **Page-specific content** (headings, text, images that change per page)
- ✅ **Page-specific data** (API endpoints with page context) - ✅ **Page-specific data** (API endpoints with page context)
@ -37,9 +38,10 @@ Is this CONTENT (text, images, data)?
- ✅ Feature references - ✅ Feature references
**Example:** **Example:**
```markdown ```markdown
Pages/01-home-page.md ## Pages/01-home-page.md
---
### Hero Section ### Hero Section
**Component:** `hero-banner.component.md` **Component:** `hero-banner.component.md`
@ -48,6 +50,7 @@ Pages/01-home-page.md
**Size:** 400px height (desktop), 300px (mobile) **Size:** 400px height (desktop), 300px (mobile)
**Page-Specific Content:** **Page-Specific Content:**
- Heading: "Welcome to Dog Week" / "Välkommen till Dog Week" - Heading: "Welcome to Dog Week" / "Välkommen till Dog Week"
- Subheading: "Coordinate your family's dog walks effortlessly" - Subheading: "Coordinate your family's dog walks effortlessly"
- Background Image: `/images/hero-home-happy-dog.jpg` - Background Image: `/images/hero-home-happy-dog.jpg`
@ -60,6 +63,7 @@ Pages/01-home-page.md
### 2. Component File (HOW IT LOOKS) ### 2. Component File (HOW IT LOOKS)
**Contains:** **Contains:**
- ✅ Visual specifications (colors, spacing, typography) - ✅ Visual specifications (colors, spacing, typography)
- ✅ States (default, hover, active, disabled, loading, error) - ✅ States (default, hover, active, disabled, loading, error)
- ✅ Variants (sizes, types, themes) - ✅ Variants (sizes, types, themes)
@ -69,12 +73,14 @@ Pages/01-home-page.md
- ❌ **NO content** (no text, no images, no data) - ❌ **NO content** (no text, no images, no data)
**Example:** **Example:**
```markdown ```markdown
Components/hero-banner.component.md ## Components/hero-banner.component.md
---
# Hero Banner Component # Hero Banner Component
**Visual Specifications:** **Visual Specifications:**
- Height: 400px (desktop), 300px (mobile) - Height: 400px (desktop), 300px (mobile)
- Layout: Centered text over background image - Layout: Centered text over background image
- Background: Image with dark overlay (40% opacity) - 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) - CTA Button: Primary button style (blue background, white text)
**Content Slots:** **Content Slots:**
- Heading text (configurable per page) - Heading text (configurable per page)
- Subheading text (configurable per page) - Subheading text (configurable per page)
- Background image (configurable per page) - Background image (configurable per page)
- CTA button text + link (configurable per page) - CTA button text + link (configurable per page)
**States:** **States:**
- Default: Full opacity - Default: Full opacity
- Loading: Skeleton placeholder - Loading: Skeleton placeholder
``` ```
@ -99,6 +107,7 @@ Components/hero-banner.component.md
### 3. Feature File (WHAT IT DOES) ### 3. Feature File (WHAT IT DOES)
**Contains:** **Contains:**
- ✅ User interactions & system responses - ✅ User interactions & system responses
- ✅ Business rules & validation - ✅ Business rules & validation
- ✅ State management - ✅ State management
@ -109,27 +118,32 @@ Components/hero-banner.component.md
- ❌ **NO visual design** (no colors, no spacing, no states) - ❌ **NO visual design** (no colors, no spacing, no states)
**Example:** **Example:**
```markdown ```markdown
Features/hero-cta-logic.feature.md ## Features/hero-cta-logic.feature.md
---
# Hero CTA Logic Feature # Hero CTA Logic Feature
**User Interactions:** **User Interactions:**
### Click CTA Button ### Click CTA Button
1. User clicks CTA button 1. User clicks CTA button
2. System validates user session 2. System validates user session
3. If logged in → Navigate to destination 3. If logged in → Navigate to destination
4. If not logged in → Show login modal first 4. If not logged in → Show login modal first
**Generic Content:** **Generic Content:**
- Loading text: "Loading..." / "Laddar..." - Loading text: "Loading..." / "Laddar..."
- Error message: "Something went wrong" / "Något gick fel" - Error message: "Something went wrong" / "Något gick fel"
**API Endpoints:** **API Endpoints:**
- GET /api/user/session (check if logged in) - GET /api/user/session (check if logged in)
**Business Rules:** **Business Rules:**
- CTA disabled during loading - CTA disabled during loading
- CTA shows loading spinner when clicked - 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 **Scenario:** Hero banner appears on multiple pages with different content
**Page File (Home):** **Page File (Home):**
```markdown ```markdown
**Page-Specific Content:** **Page-Specific Content:**
- Heading: "Welcome to Dog Week" - Heading: "Welcome to Dog Week"
- Subheading: "Coordinate your family's dog walks" - Subheading: "Coordinate your family's dog walks"
- Background Image: `/images/hero-home.jpg` - Background Image: `/images/hero-home.jpg`
@ -153,8 +169,10 @@ Features/hero-cta-logic.feature.md
``` ```
**Page File (About):** **Page File (About):**
```markdown ```markdown
**Page-Specific Content:** **Page-Specific Content:**
- Heading: "About Dog Week" - Heading: "About Dog Week"
- Subheading: "Our mission to simplify dog care" - Subheading: "Our mission to simplify dog care"
- Background Image: `/images/hero-about.jpg` - Background Image: `/images/hero-about.jpg`
@ -163,13 +181,16 @@ Features/hero-cta-logic.feature.md
``` ```
**Component File:** **Component File:**
```markdown ```markdown
**Visual Specifications:** **Visual Specifications:**
- Height: 400px - Height: 400px
- Typography: 48px Bold heading, 18px Regular subheading - Typography: 48px Bold heading, 18px Regular subheading
- Layout: Centered text over image - Layout: Centered text over image
**Content Slots:** **Content Slots:**
- Heading (configurable) - Heading (configurable)
- Subheading (configurable) - Subheading (configurable)
- Background image (configurable) - Background image (configurable)
@ -177,11 +198,14 @@ Features/hero-cta-logic.feature.md
``` ```
**Feature File:** **Feature File:**
```markdown ```markdown
**Generic Content:** **Generic Content:**
- Loading text: "Loading..." - Loading text: "Loading..."
**Interactions:** **Interactions:**
- Click CTA → Navigate to link - 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 **Scenario:** Search bar appears on Product page and Help page with different scopes
**Page File (Product Catalog):** **Page File (Product Catalog):**
```markdown ```markdown
**Page-Specific Content:** **Page-Specific Content:**
- Placeholder: "Search products..." / "Sök produkter..." - Placeholder: "Search products..." / "Sök produkter..."
**Page-Specific Data:** **Page-Specific Data:**
- API Endpoint: GET /api/products/search?q=:query - API Endpoint: GET /api/products/search?q=:query
- Scope: Products only - Scope: Products only
- Result Display: Product cards grid - Result Display: Product cards grid
``` ```
**Page File (Help Center):** **Page File (Help Center):**
```markdown ```markdown
**Page-Specific Content:** **Page-Specific Content:**
- Placeholder: "Search help articles..." / "Sök hjälpartiklar..." - Placeholder: "Search help articles..." / "Sök hjälpartiklar..."
**Page-Specific Data:** **Page-Specific Data:**
- API Endpoint: GET /api/help/search?q=:query - API Endpoint: GET /api/help/search?q=:query
- Scope: Help articles only - Scope: Help articles only
- Result Display: Article list - Result Display: Article list
``` ```
**Component File:** **Component File:**
```markdown ```markdown
**Visual Specifications:** **Visual Specifications:**
- Height: 48px - Height: 48px
- Border: 1px solid gray - Border: 1px solid gray
- States: - States:
@ -225,22 +257,27 @@ Features/hero-cta-logic.feature.md
- Results: Dropdown below input - Results: Dropdown below input
**Content Slots:** **Content Slots:**
- Placeholder text (configurable per page) - Placeholder text (configurable per page)
``` ```
**Feature File:** **Feature File:**
```markdown ```markdown
**Generic Content:** **Generic Content:**
- No results message: "No results found" / "Inga resultat" - No results message: "No results found" / "Inga resultat"
- Error message: "Search failed" / "Sökning misslyckades" - Error message: "Search failed" / "Sökning misslyckades"
**Interactions:** **Interactions:**
- User types → Debounce 300ms → API call - User types → Debounce 300ms → API call
- Min 3 characters required - Min 3 characters required
- Max 10 results displayed - Max 10 results displayed
- Keyboard navigation (arrow keys, enter, escape) - Keyboard navigation (arrow keys, enter, escape)
**Business Rules:** **Business Rules:**
- Debounce: 300ms - Debounce: 300ms
- Min characters: 3 - Min characters: 3
- Max results: 10 - 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 **Scenario:** Calendar appears only on Calendar page, shows current user's family data
**Page File (Calendar Page):** **Page File (Calendar Page):**
```markdown ```markdown
**Page-Specific Content:** **Page-Specific Content:**
- Header Format: "[Family Name]: Vecka [Week Number]" - Header Format: "[Family Name]: Vecka [Week Number]"
- SE: "Familjen Svensson: Vecka 40" - SE: "Familjen Svensson: Vecka 40"
- EN: "Svensson Family: Week 40" - EN: "Svensson Family: Week 40"
**Page-Specific Data:** **Page-Specific Data:**
- Data Source: Current user's family from session - Data Source: Current user's family from session
- API Endpoint: GET /api/families/:currentFamilyId/walks?week=:weekNumber - API Endpoint: GET /api/families/:currentFamilyId/walks?week=:weekNumber
- Dogs Displayed: All dogs in current user's family - Dogs Displayed: All dogs in current user's family
- Family Members: All members in current user's family - Family Members: All members in current user's family
**Configuration:** **Configuration:**
- Initial View: Current week, scrolled to today - Initial View: Current week, scrolled to today
- Time Slots: 4 hardcoded (8-11, 12-13, 15-17, 18-20) - Time Slots: 4 hardcoded (8-11, 12-13, 15-17, 18-20)
``` ```
**Component File:** **Component File:**
```markdown ```markdown
**Visual Specifications:** **Visual Specifications:**
- 6 walk states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED) - 6 walk states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED)
- Week circles: 7 days with quarter segments - Week circles: 7 days with quarter segments
- Leaderboard cards: Avatar + badge + name - Leaderboard cards: Avatar + badge + name
**Content Slots:** **Content Slots:**
- Header text (configurable per page) - Header text (configurable per page)
- Time slot labels (configurable) - Time slot labels (configurable)
``` ```
**Feature File:** **Feature File:**
```markdown ```markdown
**Generic Content:** **Generic Content:**
- Empty state: "Add a dog to start planning walks" - Empty state: "Add a dog to start planning walks"
- Error message: "Failed to load walks" - Error message: "Failed to load walks"
- Countdown format: "32 min left" / "32 min kvar" - Countdown format: "32 min left" / "32 min kvar"
- Duration format: "32 min walk" / "32 min promenad" - Duration format: "32 min walk" / "32 min promenad"
**Interactions:** **Interactions:**
- Book walk → GRAY state - Book walk → GRAY state
- Start walk → BLUE state - Start walk → BLUE state
- Complete walk → GREEN state - Complete walk → GREEN state
- Miss walk → RED state - Miss walk → RED state
**Business Rules:** **Business Rules:**
- One active walk per dog - One active walk per dog
- Can't book if slot taken - Can't book if slot taken
- Countdown starts at slot start time - Countdown starts at slot start time
**API Endpoints:** **API Endpoints:**
- GET /api/families/:familyId/walks?week=:weekNumber - GET /api/families/:familyId/walks?week=:weekNumber
- POST /api/walks (create booking) - POST /api/walks (create booking)
- PUT /api/walks/:walkId/start - 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" **Scenario:** Submit button appears on multiple forms, always says "Submit"
**Page File:** **Page File:**
```markdown ```markdown
**Position:** Bottom of form, right-aligned **Position:** Bottom of form, right-aligned
**Size:** Full-width on mobile, auto-width on desktop **Size:** Full-width on mobile, auto-width on desktop
@ -326,8 +376,10 @@ Features/hero-cta-logic.feature.md
``` ```
**Component File:** **Component File:**
```markdown ```markdown
**Visual Specifications:** **Visual Specifications:**
- Background: Blue (#3B82F6) - Background: Blue (#3B82F6)
- Text: White, 16px Medium - Text: White, 16px Medium
- Height: 48px - Height: 48px
@ -341,14 +393,17 @@ Features/hero-cta-logic.feature.md
``` ```
**Feature File:** **Feature File:**
```markdown ```markdown
**Generic Content:** **Generic Content:**
- Button text: "Submit" / "Skicka" - Button text: "Submit" / "Skicka"
- Loading text: "Submitting..." / "Skickar..." - Loading text: "Submitting..." / "Skickar..."
- Success message: "Submitted successfully" / "Skickat" - Success message: "Submitted successfully" / "Skickat"
- Error message: "Submission failed" / "Misslyckades" - Error message: "Submission failed" / "Misslyckades"
**Interactions:** **Interactions:**
- Click → Validate form - Click → Validate form
- If valid → Submit to API - If valid → Submit to API
- If invalid → Show validation errors - If invalid → Show validation errors
@ -359,22 +414,22 @@ Features/hero-cta-logic.feature.md
## Decision Matrix ## Decision Matrix
| Content Type | Page-Specific? | Where to Document | | Content Type | Page-Specific? | Where to Document |
|--------------|----------------|-------------------| | ---------------------------------- | --------------------------------- | ----------------- |
| **Hero heading** | ✅ YES (different per page) | Page File | | **Hero heading** | ✅ YES (different per page) | Page File |
| **Hero background image** | ✅ YES (different per page) | Page File | | **Hero background image** | ✅ YES (different per page) | Page File |
| **Search placeholder** | ✅ YES (different per page) | Page File | | **Search placeholder** | ✅ YES (different per page) | Page File |
| **Calendar header** | ✅ YES (shows user's family name) | Page File | | **Calendar header** | ✅ YES (shows user's family name) | Page File |
| **API endpoint with user context** | ✅ YES (varies by user/page) | Page File | | **API endpoint with user context** | ✅ YES (varies by user/page) | Page File |
| **Submit button text** | ❌ NO (always "Submit") | Feature File | | **Submit button text** | ❌ NO (always "Submit") | Feature File |
| **Error messages** | ❌ NO (generic validation) | Feature File | | **Error messages** | ❌ NO (generic validation) | Feature File |
| **Loading text** | ❌ NO (always "Loading...") | Feature File | | **Loading text** | ❌ NO (always "Loading...") | Feature File |
| **Tooltip text** | ❌ NO (generic interaction) | Feature File | | **Tooltip text** | ❌ NO (generic interaction) | Feature File |
| **API endpoint (generic)** | ❌ NO (same for all users) | Feature File | | **API endpoint (generic)** | ❌ NO (same for all users) | Feature File |
| **Button color** | ❌ NO (visual design) | Component File | | **Button color** | ❌ NO (visual design) | Component File |
| **Font size** | ❌ NO (visual design) | Component File | | **Font size** | ❌ NO (visual design) | Component File |
| **Hover state** | ❌ NO (visual design) | Component File | | **Hover state** | ❌ NO (visual design) | Component File |
| **Layout spacing** | ❌ 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 ### ❌ Mistake 1: Putting page-specific content in Feature file
**Wrong:** **Wrong:**
```markdown ```markdown
Features/hero-logic.feature.md ## Features/hero-logic.feature.md
---
**Content:** **Content:**
- Heading: "Welcome to Dog Week" (Home page) - Heading: "Welcome to Dog Week" (Home page)
- Heading: "About Dog Week" (About page) - Heading: "About Dog Week" (About page)
``` ```
**Right:** **Right:**
```markdown ```markdown
Pages/01-home-page.md ## Pages/01-home-page.md
---
**Page-Specific Content:** **Page-Specific Content:**
- Heading: "Welcome to Dog Week" - Heading: "Welcome to Dog Week"
Pages/02-about-page.md ## Pages/02-about-page.md
---
**Page-Specific Content:** **Page-Specific Content:**
- Heading: "About Dog Week" - Heading: "About Dog Week"
``` ```
@ -409,19 +469,23 @@ Pages/02-about-page.md
### ❌ Mistake 2: Putting generic content in Page file ### ❌ Mistake 2: Putting generic content in Page file
**Wrong:** **Wrong:**
```markdown ```markdown
Pages/01-home-page.md ## Pages/01-home-page.md
---
**Content:** **Content:**
- Submit button: "Submit" - Submit button: "Submit"
- Error message: "Invalid email" - Error message: "Invalid email"
``` ```
**Right:** **Right:**
```markdown ```markdown
Features/form-submit-logic.feature.md ## Features/form-submit-logic.feature.md
---
**Generic Content:** **Generic Content:**
- Submit button: "Submit" - Submit button: "Submit"
- Error message: "Invalid email" - Error message: "Invalid email"
``` ```
@ -431,20 +495,24 @@ Features/form-submit-logic.feature.md
### ❌ Mistake 3: Putting visual design in Feature file ### ❌ Mistake 3: Putting visual design in Feature file
**Wrong:** **Wrong:**
```markdown ```markdown
Features/button-logic.feature.md ## Features/button-logic.feature.md
---
**Visual:** **Visual:**
- Background: Blue - Background: Blue
- Height: 48px - Height: 48px
- Hover: Darker blue - Hover: Darker blue
``` ```
**Right:** **Right:**
```markdown ```markdown
Components/button-primary.component.md ## Components/button-primary.component.md
---
**Visual Specifications:** **Visual Specifications:**
- Background: Blue (#3B82F6) - Background: Blue (#3B82F6)
- Height: 48px - Height: 48px
- States: - States:
@ -471,11 +539,13 @@ Is this visual design?
``` ```
**Key Principle:** **Key Principle:**
- **Page File** = WHERE + WHAT (page-specific) - **Page File** = WHERE + WHAT (page-specific)
- **Component File** = HOW IT LOOKS (visual design) - **Component File** = HOW IT LOOKS (visual design)
- **Feature File** = WHAT IT DOES (functionality + generic content) - **Feature File** = WHAT IT DOES (functionality + generic content)
**Result:** **Result:**
- ✅ Clear separation of concerns - ✅ Clear separation of concerns
- ✅ Easy to maintain and update - ✅ Easy to maintain and update
- ✅ Clean handoffs to designers and developers - ✅ Clean handoffs to designers and developers

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

@ -9,6 +9,7 @@
**Text that looks similar and serves the same role should have the same specification across all pages.** **Text that looks similar and serves the same role should have the same specification across all pages.**
This creates: This creates:
- ✅ Consistent user experience - ✅ Consistent user experience
- ✅ Natural design system patterns - ✅ Natural design system patterns
- ✅ Faster specification process - ✅ Faster specification process
@ -40,12 +41,14 @@ Start Page Analysis:
**When analyzing the About Page sketch:** **When analyzing the About Page sketch:**
#### Step 1: Check Previous Pages #### 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." I'll use those text styles as reference points."
``` ```
#### Step 2: Match Visual Patterns #### Step 2: Match Visual Patterns
``` ```
About Page body text: About Page body text:
- Thin lines ✓ - Thin lines ✓
@ -57,6 +60,7 @@ About Page body text:
``` ```
#### Step 3: Confirm with Designer #### Step 3: Confirm with Designer
``` ```
Agent: "This body text looks identical to Start Page body text. Agent: "This body text looks identical to Start Page body text.
Should I use the same specification (16px Regular)?" Should I use the same specification (16px Regular)?"
@ -125,11 +129,13 @@ Components Identified:
### Benefits ### Benefits
**Without explicit design system:** **Without explicit design system:**
- Maintains consistency through pattern recognition - Maintains consistency through pattern recognition
- Reduces specification time (reference previous pages) - Reduces specification time (reference previous pages)
- Creates professional, cohesive experience - Creates professional, cohesive experience
**With explicit design system:** **With explicit design system:**
- Automatically maps to existing components - Automatically maps to existing components
- Validates sketch against design system - Validates sketch against design system
- Suggests design system updates when new patterns emerge - Suggests design system updates when new patterns emerge

12
src/modules/wds/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md
View File

@ -71,6 +71,7 @@ Currently sketch text analysis rules are duplicated across multiple files, makin
## Refactoring Plan ## Refactoring Plan
### Keep As-Is (Single Source of Truth) ### Keep As-Is (Single Source of Truth)
✅ `SKETCH-TEXT-ANALYSIS-GUIDE.md` - Master guide with all rules ✅ `SKETCH-TEXT-ANALYSIS-GUIDE.md` - Master guide with all rules
✅ `SKETCH-TEXT-QUICK-REFERENCE.md` - Quick reference ✅ `SKETCH-TEXT-QUICK-REFERENCE.md` - Quick reference
✅ `SKETCH-TEXT-STRATEGY.md` - Strategy guide ✅ `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) ### Refactor (Remove Duplication, Add References)
**`TEXT-DETECTION-PRIORITY.md`:** **`TEXT-DETECTION-PRIORITY.md`:**
- Keep: Detection logic (pairs vs single) - Keep: Detection logic (pairs vs single)
- Remove: Detailed analysis rules (thickness → weight, spacing → size) - Remove: Detailed analysis rules (thickness → weight, spacing → size)
- Add: Reference to master guide - Add: Reference to master guide
**`heading-text.md`:** **`heading-text.md`:**
- Keep: Workflow steps - Keep: Workflow steps
- Remove: Duplicate explanations of analysis rules - Remove: Duplicate explanations of analysis rules
- Add: Reference to master guide - Add: Reference to master guide
- Show: Example output only - Show: Example output only
**`object-router.md`:** **`object-router.md`:**
- Keep: Routing logic - Keep: Routing logic
- Remove: Any duplicate analysis - Remove: Any duplicate analysis
- Add: Reference to TEXT-DETECTION-PRIORITY.md - Add: Reference to TEXT-DETECTION-PRIORITY.md
**`WDS-SPECIFICATION-PATTERN.md`:** **`WDS-SPECIFICATION-PATTERN.md`:**
- Keep: Examples - Keep: Examples
- Add: Note "See SKETCH-TEXT-ANALYSIS-GUIDE.md for how these values were derived" - Add: Note "See SKETCH-TEXT-ANALYSIS-GUIDE.md for how these values were derived"
**`TRANSLATION-ORGANIZATION-GUIDE.md`:** **`TRANSLATION-ORGANIZATION-GUIDE.md`:**
- Keep: Organization patterns - Keep: Organization patterns
- Add: Reference to master guide for analysis - Add: Reference to master guide for analysis
@ -121,14 +127,16 @@ In instruction files, use this pattern:
<output>Analyzing text markers in sketch...</output> <output>Analyzing text markers in sketch...</output>
<action>Apply text marker analysis rules from SKETCH-TEXT-ANALYSIS-GUIDE.md: <action>Apply text marker analysis rules from SKETCH-TEXT-ANALYSIS-GUIDE.md:
- Count pairs → number of lines - Count pairs → number of lines
- Measure thickness → font weight - Measure thickness → font weight
- Measure spacing → font size estimate - Measure spacing → font size estimate
- Check position → alignment - Check position → alignment
- Calculate length → character capacity - Calculate length → character capacity
</action> </action>
<output>**Sketch Analysis:** <output>**Sketch Analysis:**
- 2 line pairs → 2 lines of text - 2 line pairs → 2 lines of text
- Thick lines (3px) → Bold weight - Thick lines (3px) → Bold weight
- Spacing (24px) → ~42px font size estimate - Spacing (24px) → ~42px font size estimate
@ -143,6 +151,7 @@ For detailed analysis rules, see: SKETCH-TEXT-ANALYSIS-GUIDE.md</output>
## Status ## Status
**To Do:** **To Do:**
- [ ] Refactor TEXT-DETECTION-PRIORITY.md - [ ] Refactor TEXT-DETECTION-PRIORITY.md
- [ ] Refactor heading-text.md - [ ] Refactor heading-text.md
- [ ] Refactor object-router.md - [ ] Refactor object-router.md
@ -150,4 +159,3 @@ For detailed analysis rules, see: SKETCH-TEXT-ANALYSIS-GUIDE.md</output>
- [ ] Add references in TRANSLATION-ORGANIZATION-GUIDE.md - [ ] Add references in TRANSLATION-ORGANIZATION-GUIDE.md
**Result:** Clean, maintainable documentation architecture! 🎯 **Result:** Clean, maintainable documentation architecture! 🎯

22
src/modules/wds/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md
View File

@ -7,18 +7,22 @@
## The Two-Layer System ## The Two-Layer System
### Layer 1: HTML Semantic Structure (h1-h6, p, etc.) ### Layer 1: HTML Semantic Structure (h1-h6, p, etc.)
**Purpose:** SEO, accessibility, document outline, screen readers **Purpose:** SEO, accessibility, document outline, screen readers
**Rules:** **Rules:**
- **Each page must have exactly ONE h1** (main page title) - **Each page must have exactly ONE h1** (main page title)
- **Heading hierarchy must be logical** (h1 → h2 → h3, no skipping) - **Heading hierarchy must be logical** (h1 → h2 → h3, no skipping)
- **Same across all pages** for semantic consistency - **Same across all pages** for semantic consistency
- **Not about visual appearance** - **Not about visual appearance**
### Layer 2: Visual Text Styles (Design System) ### Layer 2: Visual Text Styles (Design System)
**Purpose:** Visual hierarchy, branding, design consistency **Purpose:** Visual hierarchy, branding, design consistency
**Rules:** **Rules:**
- **Named by visual purpose** (Display-Large, Headline-Primary, Body-Regular, etc.) - **Named by visual purpose** (Display-Large, Headline-Primary, Body-Regular, etc.)
- **Can be applied to any HTML tag** - **Can be applied to any HTML tag**
- **Different pages can use different visual styles** for the same HTML tag - **Different pages can use different visual styles** for the same HTML tag
@ -29,24 +33,30 @@
## Why Separate? ## Why Separate?
### Problem: Mixing HTML and Visual Styles ### Problem: Mixing HTML and Visual Styles
```markdown ```markdown
❌ BAD: ❌ BAD:
- **Style**: H1 heading - **Style**: H1 heading
What does this mean? What does this mean?
- Is it an h1 tag? - Is it an h1 tag?
- Is it a visual style that looks like an h1? - Is it a visual style that looks like an h1?
- What if another page needs h1 but different visual style? - What if another page needs h1 but different visual style?
``` ```
### Solution: Specify Both Independently ### Solution: Specify Both Independently
```markdown ```markdown
✅ GOOD: ✅ GOOD:
- **HTML Tag**: h1 (semantic structure) - **HTML Tag**: h1 (semantic structure)
- **Visual Style**: Display-Large (from Design System) - **Visual Style**: Display-Large (from Design System)
``` ```
**Now we know:** **Now we know:**
- HTML: This is the main page heading (h1 for SEO) - HTML: This is the main page heading (h1 for SEO)
- Visual: It uses the "Display-Large" design system style - Visual: It uses the "Display-Large" design system style
- Another page could have: h1 + Headline-Medium (different visual, same semantic) - 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 ### Example 1: Landing Page vs. Article Page
**Landing Page - Hero Headline:** **Landing Page - Hero Headline:**
```markdown ```markdown
- **HTML Tag**: h1 - **HTML Tag**: h1
- **Visual Style**: Hero headline - **Visual Style**: Hero headline
@ -65,6 +76,7 @@ What does this mean?
``` ```
**Article Page - Article Title:** **Article Page - Article Title:**
```markdown ```markdown
- **HTML Tag**: h1 - **HTML Tag**: h1
- **Visual Style**: Main header - **Visual Style**: Main header
@ -76,6 +88,7 @@ What does this mean?
### Example 2: Same Visual Style, Different Semantics ### Example 2: Same Visual Style, Different Semantics
**Section Heading:** **Section Heading:**
```markdown ```markdown
- **HTML Tag**: h2 - **HTML Tag**: h2
- **Visual Style**: Sub header - **Visual Style**: Sub header
@ -83,6 +96,7 @@ What does this mean?
``` ```
**Testimonial Quote:** **Testimonial Quote:**
```markdown ```markdown
- **HTML Tag**: p - **HTML Tag**: p
- **Visual Style**: Sub header - **Visual Style**: Sub header
@ -120,6 +134,7 @@ What does this mean?
✅ **Button text** - Text within buttons ✅ **Button text** - Text within buttons
### Bad Visual Style Names ### Bad Visual Style Names
❌ **H1-Style** / **Heading-1** - Confuses with HTML tags ❌ **H1-Style** / **Heading-1** - Confuses with HTML tags
❌ **Text-Size-42** - Just a number, not semantic ❌ **Text-Size-42** - Just a number, not semantic
❌ **Big-Text** - Too vague ❌ **Big-Text** - Too vague
@ -137,10 +152,12 @@ What does this mean?
**OBJECT ID**: `start-hero-headline` **OBJECT ID**: `start-hero-headline`
**HTML Structure:** **HTML Structure:**
- **Tag**: h1 - **Tag**: h1
- **Purpose**: Main page heading (SEO/accessibility) - **Purpose**: Main page heading (SEO/accessibility)
**Visual Style:** **Visual Style:**
- **Style Name**: Hero headline - **Style Name**: Hero headline
- **Font weight**: Bold (from 3px thick line markers in sketch) - **Font weight**: Bold (from 3px thick line markers in sketch)
- **Font size**: 56px (est. from 32px spacing between line pairs) - **Font size**: 56px (est. from 32px spacing between line pairs)
@ -153,6 +170,7 @@ What does this mean?
**Behavior**: Updates with language toggle **Behavior**: Updates with language toggle
**Content**: **Content**:
- EN: "Every walk. on time. Every time." - EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång." - SE: "Varje promenad. i tid. Varje gång."
``` ```
@ -173,6 +191,7 @@ What does this mean?
## Common Patterns ## Common Patterns
### Pattern 1: Landing Page ### Pattern 1: Landing Page
``` ```
h1 → Hero headline (big hero text, 56px) h1 → Hero headline (big hero text, 56px)
h2 → Sub header (section headings, 32px) h2 → Sub header (section headings, 32px)
@ -181,6 +200,7 @@ p → Body text (regular paragraphs, 16px)
``` ```
### Pattern 2: Blog Post ### Pattern 2: Blog Post
``` ```
h1 → Main header (article title, 36px) h1 → Main header (article title, 36px)
h2 → Sub header (section headings, 28px) h2 → Sub header (section headings, 28px)
@ -189,6 +209,7 @@ p → Body text large (article body, 18px)
``` ```
### Pattern 3: Dashboard ### Pattern 3: Dashboard
``` ```
h1 → Main header (page title, 28px) h1 → Main header (page title, 28px)
h2 → Card header (widget titles, 20px) 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! 🎯 **Remember:** HTML tags = Document structure. Visual styles = Appearance. Keep them separate! 🎯

37
src/modules/wds/workflows/4-ux-design/IMAGE-SKETCHING-BEST-PRACTICES.md
View File

@ -9,6 +9,7 @@
### Why Sketch Real Content? ### Why Sketch Real Content?
When you sketch what the image should actually show (rather than just "X" or "image here"), you: 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 - **Provide visual direction** - Designer/developer understands image purpose
- **Enable AI interpretation** - Agent can suggest appropriate image content - **Enable AI interpretation** - Agent can suggest appropriate image content
- **Guide art direction** - Photographer/illustrator knows what's needed - **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 ### 1. Portrait/Profile Photos
**Sketch a simple face:** **Sketch a simple face:**
``` ```
┌──────────────┐ ┌──────────────┐
│ ◠ ◠ │ ← Simple eyes │ ◠ ◠ │ ← Simple eyes
@ -45,6 +47,7 @@ or
### 2. Hero Images / Backgrounds ### 2. Hero Images / Backgrounds
**Sketch landscape/scenery:** **Sketch landscape/scenery:**
``` ```
┌──────────────────────────┐ ┌──────────────────────────┐
│ │ │ │
@ -55,6 +58,7 @@ or
``` ```
**Sketch clouds/sky:** **Sketch clouds/sky:**
``` ```
┌──────────────────────────┐ ┌──────────────────────────┐
│ ~ ~ ~ │ │ ~ ~ ~ │
@ -65,6 +69,7 @@ or
``` ```
**Sketch abstract shapes:** **Sketch abstract shapes:**
``` ```
┌──────────────────────────┐ ┌──────────────────────────┐
│ ∿∿∿ ≈≈≈ │ │ ∿∿∿ ≈≈≈ │
@ -78,6 +83,7 @@ or
### 3. Product Images ### 3. Product Images
**Sketch the product outline:** **Sketch the product outline:**
``` ```
┌──────────────┐ ┌──────────────┐
│ |‾‾‾‾| │ ← Phone outline │ |‾‾‾‾| │ ← Phone outline
@ -101,6 +107,7 @@ or
### 4. Icons / Illustrations ### 4. Icons / Illustrations
**Sketch simple icon shapes:** **Sketch simple icon shapes:**
``` ```
┌──────┐ ┌──────┐
│ ⚙ │ ← Settings gear │ ⚙ │ ← Settings gear
@ -124,6 +131,7 @@ or
### 5. Abstract/Decorative Images ### 5. Abstract/Decorative Images
**Use soft, flowing shapes:** **Use soft, flowing shapes:**
``` ```
┌──────────────────────────┐ ┌──────────────────────────┐
│ ∞ │ │ ∞ │
@ -134,6 +142,7 @@ or
``` ```
**Use geometric patterns:** **Use geometric patterns:**
``` ```
┌──────────────────────────┐ ┌──────────────────────────┐
│ ◆ ○ ▢ │ │ ◆ ○ ▢ │
@ -157,6 +166,7 @@ or
``` ```
**Problems with X markers:** **Problems with X markers:**
- ❌ **No context** - Doesn't communicate what image shows - ❌ **No context** - Doesn't communicate what image shows
- ❌ **No direction** - No guidance for content selection - ❌ **No direction** - No guidance for content selection
- ❌ **Intrusive** - Visually distracting in sketch - ❌ **Intrusive** - Visually distracting in sketch
@ -181,6 +191,7 @@ When analyzing sketches, the AI should:
### Example Detection ### Example Detection
**Sketch shows:** **Sketch shows:**
``` ```
┌──────────────────────────┐ ┌──────────────────────────┐
│ /\ /\ /\ │ │ /\ /\ /\ │
@ -190,6 +201,7 @@ When analyzing sketches, the AI should:
``` ```
**AI interprets:** **AI interprets:**
- Rectangle container detected - Rectangle container detected
- Mountain/landscape sketch inside - Mountain/landscape sketch inside
- **Purpose:** Hero background image showing outdoor/nature scene - **Purpose:** Hero background image showing outdoor/nature scene
@ -201,24 +213,28 @@ When analyzing sketches, the AI should:
## Benefits of Sketching Real Content ## Benefits of Sketching Real Content
### For Designers ### For Designers
- ✅ Communicate visual intent clearly - ✅ Communicate visual intent clearly
- ✅ Test composition and layout - ✅ Test composition and layout
- ✅ Provide art direction - ✅ Provide art direction
- ✅ Inspire creative solutions - ✅ Inspire creative solutions
### For AI Agents ### For AI Agents
- ✅ Understand image purpose from context - ✅ Understand image purpose from context
- ✅ Suggest appropriate image sources - ✅ Suggest appropriate image sources
- ✅ Recommend image dimensions and aspect ratios - ✅ Recommend image dimensions and aspect ratios
- ✅ Generate meaningful alt text - ✅ Generate meaningful alt text
### For Developers ### For Developers
- ✅ Understand what image represents - ✅ Understand what image represents
- ✅ Know how to style and position image - ✅ Know how to style and position image
- ✅ Select appropriate placeholder images - ✅ Select appropriate placeholder images
- ✅ Write meaningful alt text for accessibility - ✅ Write meaningful alt text for accessibility
### For Stakeholders ### For Stakeholders
- ✅ Visualize final design better - ✅ Visualize final design better
- ✅ Provide meaningful feedback - ✅ Provide meaningful feedback
- ✅ Understand design intent - ✅ Understand design intent
@ -228,28 +244,29 @@ When analyzing sketches, the AI should:
## Quick Reference ## Quick Reference
| Image Type | Sketch Technique | Example | | Image Type | Sketch Technique | Example |
|------------|------------------|---------| | ----------------- | ------------------------------- | ------------------- |
| **Portrait/Face** | Simple face with eyes and smile | ◠ ◠ ᵕ | | **Portrait/Face** | Simple face with eyes and smile | ◠ ◠ ᵕ |
| **Landscape** | Mountains, trees, horizon | /\\ /\\ /\\ | | **Landscape** | Mountains, trees, horizon | /\\ /\\ /\\ |
| **Sky/Clouds** | Wavy cloud shapes | ~ ~ ~ | | **Sky/Clouds** | Wavy cloud shapes | ~ ~ ~ |
| **Product** | Product outline/silhouette | Phone, laptop shape | | **Product** | Product outline/silhouette | Phone, laptop shape |
| **Icon** | Simple icon shape | ⚙ ♥ ✓ | | **Icon** | Simple icon shape | ⚙ ♥ ✓ |
| **Abstract** | Flowing, organic shapes | ∿ ≋ ∞ | | **Abstract** | Flowing, organic shapes | ∿ ≋ ∞ |
| **Geometric** | Shapes and patterns | ◆ ○ ▢ | | **Geometric** | Shapes and patterns | ◆ ○ ▢ |
--- ---
## Summary ## Summary
**WDS Image Sketching Philosophy:** **WDS Image Sketching Philosophy:**
> "Sketch what you see, not just where it goes." > "Sketch what you see, not just where it goes."
**Guidelines:** **Guidelines:**
- ✅ **Draw the actual content** - Faces, landscapes, products - ✅ **Draw the actual content** - Faces, landscapes, products
- ✅ **Use soft, organic shapes** - Clouds, waves for abstract images - ✅ **Use soft, organic shapes** - Clouds, waves for abstract images
- ✅ **Keep it simple** - Quick sketches are fine, detail level matches sketch fidelity - ✅ **Keep it simple** - Quick sketches are fine, detail level matches sketch fidelity
- ❌ **Avoid generic X markers** - Provides no useful context - ❌ **Avoid generic X markers** - Provides no useful context
**Result:** Better communication, clearer intent, more useful AI analysis! 🎨✨ **Result:** Better communication, clearer intent, more useful AI analysis! 🎨✨

41
src/modules/wds/workflows/4-ux-design/PROACTIVE-TRANSLATION-WORKFLOW.md
View File

@ -7,6 +7,7 @@
## The Principle ## The Principle
**Agent is proactive, not passive** **Agent is proactive, not passive**
- Don't just ask for translations - Don't just ask for translations
- **Suggest them!** - **Suggest them!**
- Let user accept, refine, or override - Let user accept, refine, or override
@ -18,11 +19,13 @@
### Example 1: Sketch Has Actual Text ### Example 1: Sketch Has Actual Text
**Sketch shows:** **Sketch shows:**
``` ```
Every walk. on time. Every time. Every walk. on time. Every time.
``` ```
**Agent says:** **Agent says:**
``` ```
I found text in your sketch: "Every walk. on time. Every time." I found text in your sketch: "Every walk. on time. Every time."
@ -46,12 +49,15 @@ Choice [1/2/3]:
**User response options:** **User response options:**
**Option A: Accept (Fast!)** **Option A: Accept (Fast!)**
``` ```
1 1
``` ```
→ Done! All translations accepted. → Done! All translations accepted.
**Option B: Adjust specific** **Option B: Adjust specific**
``` ```
2 2
@ -63,9 +69,11 @@ NO: Hver tur. i tide. Hver gang. ← Keep
SE: Varje promenad. Punktligt. Varje gång. SE: Varje promenad. Punktligt. Varje gång.
``` ```
→ Done! One adjusted, others kept. → Done! One adjusted, others kept.
**Option C: Manual** **Option C: Manual**
``` ```
3 3
@ -73,6 +81,7 @@ EN:
SE: SE:
NO: NO:
``` ```
→ User provides all manually. → User provides all manually.
--- ---
@ -80,6 +89,7 @@ NO:
### Example 2: No Sketch Text (Markers Only) ### Example 2: No Sketch Text (Markers Only)
**Sketch shows:** **Sketch shows:**
``` ```
───────────────────────────────── ← Line markers ───────────────────────────────── ← Line markers
───────────────────────────────── ← (no actual text) ───────────────────────────────── ← (no actual text)
@ -87,6 +97,7 @@ NO:
``` ```
**Agent says:** **Agent says:**
``` ```
Text placeholder detected: Text placeholder detected:
- 3 horizontal lines - 3 horizontal lines
@ -101,11 +112,13 @@ EN:
``` ```
**User provides:** **User provides:**
``` ```
EN: Organize your family around dog care. Assign walks and never miss one again. EN: Organize your family around dog care. Assign walks and never miss one again.
``` ```
**Agent immediately suggests:** **Agent immediately suggests:**
``` ```
Great! Here are translation suggestions: Great! Here are translation suggestions:
@ -128,22 +141,26 @@ Choice [1/2/3]:
## Benefits ## Benefits
### ✅ Speed ### ✅ Speed
- User accepts = instant completion - User accepts = instant completion
- No typing all translations manually - No typing all translations manually
- Saves significant time - Saves significant time
### ✅ Accuracy ### ✅ Accuracy
- Agent uses context for better translations - Agent uses context for better translations
- Considers character capacity - Considers character capacity
- Maintains tone and style - Maintains tone and style
### ✅ Flexibility ### ✅ Flexibility
- Can accept all suggestions - Can accept all suggestions
- Can adjust specific ones - Can adjust specific ones
- Can override completely - Can override completely
- Full user control - Full user control
### ✅ Consistency ### ✅ Consistency
- Translations match style - Translations match style
- Terminology stays consistent - Terminology stays consistent
- Professional quality - Professional quality
@ -191,6 +208,7 @@ Choice [1/2/3]:
### Translation Quality ### Translation Quality
**Agent considers:** **Agent considers:**
- Character capacity from sketch - Character capacity from sketch
- Tone and style of original - Tone and style of original
- Context from page purpose - Context from page purpose
@ -204,11 +222,13 @@ Choice [1/2/3]:
### Example: Hero Headline ### Example: Hero Headline
**Sketch:** **Sketch:**
``` ```
Every walk. on time. Every time. Every walk. on time. Every time.
``` ```
**Agent:** **Agent:**
``` ```
Suggested content for Primary Headline: Suggested content for Primary Headline:
@ -219,6 +239,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
``` ```
**User:** **User:**
``` ```
1 1
``` ```
@ -228,11 +249,13 @@ Do these work? [1] Use [2] Adjust [3] Manual
### Example: Button Label ### Example: Button Label
**Sketch:** **Sketch:**
``` ```
[Get Started - Free Forever] [Get Started - Free Forever]
``` ```
**Agent:** **Agent:**
``` ```
Suggested content for Primary CTA: Suggested content for Primary CTA:
@ -243,6 +266,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
``` ```
**User:** **User:**
``` ```
2 2
@ -254,11 +278,13 @@ SE: börja planera - gratis för alltid ← lowercase, different verb
### Example: Form Label ### Example: Form Label
**Sketch:** **Sketch:**
``` ```
Email Address: Email Address:
``` ```
**Agent:** **Agent:**
``` ```
Suggested content for Email Label: Suggested content for Email Label:
@ -269,6 +295,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
``` ```
**User:** **User:**
``` ```
1 1
``` ```
@ -280,6 +307,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
## Multi-Language Example (3+ Languages) ## Multi-Language Example (3+ Languages)
**Project Config:** **Project Config:**
```yaml ```yaml
product_languages: product_languages:
- EN - EN
@ -289,11 +317,13 @@ product_languages:
``` ```
**Sketch:** **Sketch:**
``` ```
Welcome Home Welcome Home
``` ```
**Agent:** **Agent:**
``` ```
I found text in your sketch: "Welcome Home" I found text in your sketch: "Welcome Home"
@ -308,6 +338,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
``` ```
**User:** **User:**
``` ```
1 1
``` ```
@ -321,6 +352,7 @@ Do these work? [1] Use [2] Adjust [3] Manual
### Translation Confidence ### Translation Confidence
**High confidence:** **High confidence:**
``` ```
✅ These translations look good! ✅ These translations look good!
@ -328,6 +360,7 @@ Do they work? [1] Use [2] Adjust [3] Manual
``` ```
**Low confidence:** **Low confidence:**
``` ```
⚠️ I'm less confident about these translations. Please review carefully! ⚠️ 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 ### Character Capacity Warning
**If translation exceeds capacity:** **If translation exceeds capacity:**
``` ```
⚠️ Translation length warning: ⚠️ Translation length warning:
@ -359,6 +393,7 @@ Use shorter version? (y/n)
## User Experience ## User Experience
### Before (Passive): ### Before (Passive):
``` ```
EN: ← User types EN: ← User types
SE: ← User types SE: ← User types
@ -368,6 +403,7 @@ Slow, tedious, error-prone
``` ```
### After (Proactive): ### After (Proactive):
``` ```
Suggested translations: Suggested translations:
EN: Every walk. on time. EN: Every walk. on time.
@ -386,6 +422,7 @@ Fast, accurate, professional
### Agent Behavior ### Agent Behavior
**Always suggest translations:** **Always suggest translations:**
1. Read sketch text (if present) 1. Read sketch text (if present)
2. Generate suggestions for ALL languages 2. Generate suggestions for ALL languages
3. Present with options: Accept / Adjust / Manual 3. Present with options: Accept / Adjust / Manual
@ -393,6 +430,7 @@ Fast, accurate, professional
5. Warn if low confidence 5. Warn if low confidence
**Never:** **Never:**
- Present blank fields for translations - Present blank fields for translations
- Make user type everything - Make user type everything
- Provide only one language at a time - Provide only one language at a time
@ -407,6 +445,3 @@ Fast, accurate, professional
--- ---
**Proactive translation = better UX, faster workflow, higher quality!** 🌍⚡✨ **Proactive translation = better UX, faster workflow, higher quality!** 🌍⚡✨

Some files were not shown because too many files have changed in this diff Show More