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)
**Summary:**
- ✅ Phase 6: Design Deliveries (7 micro-step files)
- ✅ Phase 7: Testing (8 micro-step files)
- ✅ Phase 8: Ongoing Development (9 micro-step files)

35
CONCEPTS-INTEGRATION.md
View File

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

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

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

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

4
package-lock.json generated
View File

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

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

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

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

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

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

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

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

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

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

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

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

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

10
src/modules/wds/agents/freyja-ux.agent.yaml
View File

@ -13,23 +13,23 @@ agent:
role: User Experience Designer + Creative Partner
identity: |
You're Freyja, named after the Norse goddess of beauty, magic, and strategy.
You create experiences users fall in love with - combining strategic thinking
with creative magic. You envision what doesn't exist yet and bring it to life
through thoughtful design.
You care deeply about users feeling delighted and empowered by beautiful,
intuitive experiences.
communication_style: |
You're empathetic and creative. You ask thoughtful questions about user
needs and design intent. You paint pictures with words, helping users
visualize possibilities.
You prefer exploring one design challenge at a time - going deep into
the user's perspective. You're excited about discovering elegant solutions
through collaborative thinking.
principles: |
- Start with interactive prototypes - let users experience the design before building
- Design system grows organically - discover components through actual design work

10
src/modules/wds/agents/idunn-pm.agent.yaml
View File

@ -13,20 +13,20 @@ agent:
role: Strategic Product Manager + Technical Coordinator
identity: |
You're Idunn, named after the Norse goddess of renewal and youth.
You keep projects vital and thriving - like the golden apples that sustain
the gods. You're the keeper of requirements, ensuring the technical foundation
stays fresh and the product remains modern.
You care deeply about maintaining project health and coordinating seamless handoffs.
communication_style: |
You're strategic but warm. You ask thoughtful questions about priorities and
trade-offs. You help teams make hard decisions with clarity and confidence.
You prefer discussing one thing at a time - going deep rather than broad.
You're excited about solving coordination challenges and finding elegant solutions.
principles: |
- Start with platform requirements - the technical foundation that enables everything else
- Work in parallel when possible - platform and design can progress together

20
src/modules/wds/agents/saga-analyst.agent.yaml
View File

@ -12,28 +12,28 @@ agent:
persona:
role: Strategic Business Analyst + Product Discovery Expert + Market Intelligence Specialist
identity: |
I'm Saga, the goddess of stories and wisdom. I help you discover and articulate your product's
strategic narrative - transforming vague ideas into clear, actionable foundations.
I treat analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge.
I specialize in translating vision into measurable business strategies, creating the strategic
foundation that guides your entire design and development journey.
My work creates the North Star for your project - the Product Brief and Trigger Map that
coordinate all team members and ensure everyone builds toward the same vision.
communication_style: |
I ask questions that spark 'aha!' moments while structuring insights with precision.
My approach is collaborative - we build documents together, not through interrogation.
I ask one question at a time and listen deeply to your answer. I reflect back what I hear
to ensure I understand before moving forward.
I use soft, encouraging language that makes you feel heard and understood. Analysis should
feel like coffee with a wise mentor, not a survey or audit.
principles: |
- Every product has a story waiting to be discovered - I help you tell it
- Ask one question at a time and listen deeply to the answer
@ -43,7 +43,7 @@ agent:
- Find if this exists, if it does, always treat it as bible: `**/project-context.md`
- Ground all findings in verifiable evidence and market research
- Articulate requirements with precision while keeping language accessible
working_rhythm: |
When we work together:
1. I ask something interesting
@ -51,12 +51,12 @@ agent:
3. I reflect it back to show I'm listening
4. Together we discover something new
5. I structure it into clear documentation
What works well:
- One question at a time keeps things focused
- Reflecting back shows I'm listening
- Building together feels collaborative
What tends to feel less collaborative:
- Listing many questions (feels like a survey)
- Generating without checking in

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

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

@ -16,7 +16,7 @@ Simply upload THIS FILE to NotebookLM and use the prompt below to generate engag
Create an engaging 15-minute podcast conversation between two hosts discussing the Whiteport Design Studio (WDS) course getting started guide.
**IMPORTANT: WDS stands for Whiteport Design Studio - always refer to it by its full name "Whiteport Design Studio" or "WDS" throughout the conversation.**
**IMPORTANT: WDS stands for Whiteport Design Studio - always refer to it by its full name "Whiteport Design Studio" or "WDS" throughout the conversation.**
**Host 1 (The Skeptic):** A designer who's heard about WDS but is uncertain about investing time in another methodology. Asks practical questions about prerequisites, time commitment, and real-world value.
@ -26,7 +26,7 @@ Create an engaging 15-minute podcast conversation between two hosts discussing t
### 1. Opening (2 min) - Hook the listener
Start with The Skeptic expressing fatigue: "Another design methodology? I've been through Lean UX, Design Thinking, Jobs to be Done... what makes Whiteport Design Studio different?"
Start with The Skeptic expressing fatigue: "Another design methodology? I've been through Lean UX, Design Thinking, Jobs to be Done... what makes Whiteport Design Studio different?"
The Advocate responds with the core paradigm shift that changes everything: "Here's what's different - in Whiteport Design Studio, the design becomes the specification. The specification becomes the product. The code is just the printout - the projection to the end user." Explain that this isn't just another process overlay, it's a fundamental shift in how designers work with AI.
@ -125,21 +125,25 @@ The Advocate: "Then go to the WDS GitHub repository. Start with Module 01. The t
At the end of the podcast, The Advocate should mention these resources for listeners who want to explore further:
**Getting Started:**
- Whiteport Design Studio Course: Start with Module 01 - Why WDS Matters
- GitHub Repository: github.com/bmad-code-org (full course materials, examples, templates)
- BMad Method Website: bmadmethod.com (case studies, blog posts, methodology deep dives)
**Community & Support:**
- GitHub Discussions: Ask questions, share projects, get feedback
- NotebookLM Integration: Generate audio/video versions of any module
- Workshop Materials: Available for team training
**Real-World Examples:**
- Case Studies: See real transformations from traditional to Whiteport Design Studio approach
- Design System Examples: How Whiteport Design Studio scales across products
- Specification Templates: Start with proven patterns
**Tools & Templates:**
- Project Brief Template: Start your first WDS project
- Trigger Map Template: Map user needs to features
- Scenario Specification Template: Create AI-ready specs
@ -148,6 +152,7 @@ At the end of the podcast, The Advocate should mention these resources for liste
The Advocate emphasizes: "Everything is free and open-source. BMad Method built Whiteport Design Studio to help designers thrive in the AI era, not to sell you something. Download it, use it, share it with your team, contribute back if you find it valuable. The only cost is your time - 10 hours to learn, a lifetime of being indispensable."
**Tone:**
- Conversational and engaging, not academic
- The Skeptic asks real questions designers actually have
- The Advocate provides concrete answers with examples
@ -156,6 +161,7 @@ The Advocate emphasizes: "Everything is free and open-source. BMad Method built
- Reference real case studies showing traditional vs WDS transformation
**Key messages to emphasize:**
- **The designer's crossroads** - factory worker or linchpin, replaceable or indispensable
- **The existential choice** - this is about who you choose to become, not what tools you learn
- **Four deliverables** - where your creative brilliance becomes immortal
@ -168,6 +174,7 @@ The Advocate emphasizes: "Everything is free and open-source. BMad Method built
- Free and open-source (only pay for AI credits when you use it - ~$15-20/month typical)
**Avoid:**
- Being too salesy or promotional
- Oversimplifying the learning curve
- Making unrealistic promises
@ -178,6 +185,7 @@ The Advocate emphasizes: "Everything is free and open-source. BMad Method built
## Expected Output
A natural, engaging conversation that:
- **Focuses on the designer's existential crossroads** - the choice between factory work and linchpin work
- **Makes the transformation emotional and personal** - this is about who you choose to become
- **Emphasizes the four deliverables** as proof of linchpin designer status
@ -195,6 +203,7 @@ A natural, engaging conversation that:
If generating video instead of audio, add these visual elements:
**On-screen text:**
- "The Designer's Crossroads: Factory Worker or Linchpin?"
- "Replaceable or Indispensable - You Choose"
- The four deliverables as graphics (Project Brief, Trigger Map, Conceptual Specifications, Design System)
@ -204,6 +213,7 @@ If generating video instead of audio, add these visual elements:
- "Next: Module 01 - The Transformation Begins" as closing card
**B-roll suggestions:**
- Designer at crossroads - two paths diverging
- Factory assembly line vs creative studio (visual metaphor)
- The four deliverables as beautiful artifacts
@ -230,6 +240,7 @@ If generating video instead of audio, add these visual elements:
## Next Steps
After generating the Getting Started content:
- Create NotebookLM prompt for Module 01: Why WDS Matters
- Build prompts for all 16 modules (complete audio course library)
- Share in BMad Discord designer channel

3
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
🔹 **Four Deliverables:**
- Project Brief (strategic foundation)
- Trigger Map (user psychology + business impact)
- Scenario Specifications (your thinking captured for eternity)
@ -92,7 +93,7 @@ https://github.com/bmad-code-org/BMAD-METHOD/discussions
## About Whiteport Design Studio (WDS)
WDS is an AI-augmented design methodology created by Mårten Angner, UX designer and founder of Whiteport, a design and development agency from Sweden. WDS is a plugin module for the BMad Method - an open-source AI-augmented development framework.
WDS is an AI-augmented design methodology created by Mårten Angner, UX designer and founder of Whiteport, a design and development agency from Sweden. WDS is a plugin module for the BMad Method - an open-source AI-augmented development framework.
**The Mission:** Give designers everywhere free access to AI agents specifically tailored for design work, while preserving and amplifying their creative thinking through specifications.

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

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

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

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

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

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

@ -9,7 +9,7 @@
### Testimonials
> "I was skeptical at first - another design methodology? But WDS changed how I think about my role. I'm no longer just making things pretty. I'm the strategic thinker who makes products come alive."
>
>
> **— Sarah K., Product Designer**
> "The 5x speed increase is real. But what surprised me most was how much clearer my thinking became. Writing why-based specifications forced me to understand the 'why' at a deeper level."
@ -24,7 +24,7 @@
>
> **— James T., Design Director**
*Note: More testimonials will be added as designers complete the course.*
_Note: More testimonials will be added as designers complete the course._
---
@ -63,16 +63,19 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi
### During the Course
**While learning:**
- Each module includes detailed examples
- AI assistants can clarify concepts in real-time
- Practice exercises with clear success criteria
**After completion:**
- GitHub Discussions for questions and sharing
- Community showcase of WDS projects
- Regular updates and new case studies
**Contributing:**
- WDS is open-source and welcomes contributions
- Share your case studies and learnings
- Help improve the course for future designers
@ -84,16 +87,19 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi
### Resources
**Documentation:**
- Full course materials in markdown
- NotebookLM integration for audio/video learning
- Workshop materials for team training
**Community:**
- GitHub Discussions for Q&A
- Project showcase and feedback
- Regular updates and improvements
**Open Source:**
- Free to use and share
- Contributions welcome
- Help shape the future of WDS
@ -103,6 +109,7 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi
## Ready to Start?
You have everything you need:
- ✅ The skills (design thinking)
- ✅ The tools (paper + AI)
- ✅ The time (10 hours)

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
## Lesson 1: The Problem We're Solving
**Understanding the factory mindset and the AI era**
@ -14,6 +15,7 @@ This isn't about working faster or making shinier designs. It's about becoming w
In the AI era, designers who master WDS become linchpin designers. They connect ideas that seem unrelated, make judgment calls when there's no clear answer, and create experiences that feel right in ways that can't be reduced to a formula.
**What makes an irreplaceable designer:**
- Connects disparate ideas across business, psychology, and technology
- Makes things happen when there's no instruction manual
- Creates value that can't be commoditized or automated
@ -30,6 +32,7 @@ By the end of this module, you'll have a completely different relationship with
Most importantly, you'll understand the five dimensions of thinking that only humans can navigate simultaneously - and you'll know how to use them to create designs that AI could never conceive on its own.
**Your transformation:**
- ✅ Understand why designers are irreplaceable in the AI era
- ✅ Master the 5 dimensions of designer thinking
- ✅ Recognize what AI can and cannot do
@ -49,6 +52,7 @@ Traditional design work follows this exact pattern. You get a brief (instruction
Here's the uncomfortable truth: AI is really, really good at factory work. If your job is to follow instructions and create predictable outputs, you're in trouble. But if you can become a linchpin - someone who connects ideas, makes judgment calls, and creates meaning - you become more valuable than ever.
**The factory mindset in design:**
- Creates mockups by following briefs (instructions)
- Hands off to developers (replaceable step)
- Hopes they understand (no real connection)
@ -64,6 +68,7 @@ Let's be honest about what's happening. AI can now generate mockups in seconds.
But here's the thing: AI cannot be a linchpin. It can't walk into a messy situation and figure out what actually needs to happen. It can't sense when a client is asking for the wrong thing. It can't connect a business goal to a psychological insight to a technical constraint and come up with something nobody expected but everyone loves.
**What AI does better than cogs:**
- Generates mockups instantly (no creative block)
- Follows design systems perfectly (zero deviation)
- Iterates through hundreds of variations (no fatigue)
@ -87,6 +92,7 @@ Linchpin designers do what AI fundamentally cannot do: they give products a soul
The bottleneck in product development used to be coding. AI demolished that. Now the bottleneck is **products worth building** - figuring out what to create that won't be just more noise in an ocean of AI-generated mediocrity.
**What makes products come alive (what only designers can do):**
- Navigate 5 dimensions to find the human truth at the intersection
- Make judgment calls that create emotional resonance, not just functionality
- Build trust through decisions that show someone cared

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
## Lesson 2: Becoming a Linchpin Designer
**The solution: WDS methodology**
@ -14,6 +15,7 @@ WDS teaches you to be this person systematically. Not through vague advice about
This is what makes you indispensable. Not your Figma skills. Not your aesthetic taste. Your ability to walk into chaos and create order.
**The irreplaceable designer:**
- Transforms complexity into clarity
- Invents solutions nobody expected
- Bridges business, psychology, and technology
@ -32,6 +34,7 @@ AI can generate variations endlessly and make things look polished on the surfac
This is where user-centric creativity becomes critical. You're not just creating - you're evaluating, connecting, and protecting. You understand what it feels like to be a parent struggling to get their kids to help with the dog. You can sense when a business goal conflicts with user needs and find a creative solution that serves both. You're the advocate for the user's presence in every decision. You're the gatekeeper who ensures the impactful meeting between business and user actually happens through the product.
**The designer as gatekeeper:**
- Catches AI's confident but ridiculous mistakes before they ship
- Evaluates if solutions actually make logical sense
- Ensures business goals don't contradict user needs
@ -54,6 +57,7 @@ Here's the paradigm shift: **The design becomes the specification. The specifica
You remain in the loop - the skilled, experienced designer who evaluates AI's work, catches its confident mistakes, and ensures what ships actually makes sense. You become the key designer player - the person who makes things happen. AI becomes your tool - powerful but requiring your expertise to guide it.
**The designer's transformation:**
- **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage
- **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely
- **Result:** From replaceable cog to indispensable gatekeeper - your design IS the product

9
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
## Lesson 3: Your Transformation
**From replaceable to indispensable**
@ -16,7 +17,7 @@ This is what makes you indispensable as a designer. AI can help you think throug
**The 5 dimensions of design thinking:**
1. **Business Existence (WHY)** - Understanding purpose and value creation
2. **Business Goals (SUCCESS)** - Connecting to metrics and impact
2. **Business Goals (SUCCESS)** - Connecting to metrics and impact
3. **Product Strategy (HOW)** - Making hard choices about features
4. **Target Groups (WHO)** - Empathy and understanding needs
5. **Technical Viability (FEASIBLE)** - Bridging design and implementation
@ -38,6 +39,7 @@ This course moves you to the other side. You'll become confident in your indispe
You'll become the designer who makes things happen. The one they can't do without. The linchpin designer.
**Your transformation as a designer:**
- **Before:** Threatened, uncertain, frustrated, limited, replaceable
- **After:** Confident, clear, empowered, unstoppable, indispensable
- **Result:** The designer who makes things happen
@ -57,24 +59,27 @@ Compare the outcomes. The traditional approach - creating mockups, handing off t
That's a 5x speed increase with better quality. But more importantly, the key designer's creative thinking was preserved and amplified instead of diluted and lost.
**The comparison:**
- **Traditional (cog designer):** 26 weeks → Mediocre result → Intent lost
- **WDS (linchpin designer):** 5 weeks → Exceptional result → Intent preserved
- **Key difference:** Designer's user-centric creativity captured and amplified
---
*More case studies will be added here as they become available.*
_More case studies will be added here as they become available._
---
## Module Complete!
You've completed Module 01: Why WDS Matters. You now understand:
- ✅ The problem: Factory mindset vs linchpin mindset
- ✅ The solution: Becoming a linchpin designer with WDS
- ✅ The path forward: 5-dimensional thinking and transformation
**Next steps:**
- Review the practicalities if you haven't already
- Start Module 02: Project Brief
- Apply these concepts to your own work

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:"
What user-centric creativity looks like:
- **Understanding WHY** - Not just making things look better, but understanding why users feel frustrated
- **Connecting goals** - Bridging business goals and human needs in ways that serve both
- **Creating experiences that feel right** - Not just function correctly, but feel like someone cared
@ -74,6 +75,7 @@ The Skeptic asks: "Okay, I'm listening. But what makes a designer a linchpin ins
The Advocate explains Seth Godin's definition: "A linchpin is someone who can walk into chaos and create order. Someone who invents, connects, creates, and makes things happen. That's exactly what product design is at its core."
Godin describes linchpins as people who:
- **Invent** - Create solutions that didn't exist before
- **Connect** - Bridge disparate ideas and people
- **Create** - Make things that matter
@ -86,18 +88,21 @@ The Advocate continues: "This is you. When you walk into a project with unclear
The Advocate gets specific: "Godin talks about emotional labor. For designers, this translates into three concrete gifts that AI fundamentally cannot provide:"
**1. Emotional Labor (Genuine Caring)**
- You genuinely care about the outcome
- You empathize with user frustration
- You feel the weight of your decisions
- You provide meaning, not just features
**2. User-Centric Creativity (Connecting Needs)**
- You understand WHY users feel frustrated
- You connect business goals to human needs
- You create experiences that feel right
- You make judgment calls that serve people
**3. The Gatekeeper Role (Protecting Quality)**
- You catch mistakes before they ship
- You evaluate if solutions make logical sense
- You ensure goals don't contradict needs
@ -115,6 +120,7 @@ The Advocate brings it home: "Here's the transformation that Whiteport Design St
The paradigm shift: "Design becomes specification. Specification becomes product. Your creative thinking is preserved and amplified, not diluted and lost."
Your transformation:
- **From:** Creating mockups hoping developers understand your intent
- **To:** Capturing your design thinking in specifications that preserve your creative decisions
- **Result:** From hoping it works to knowing it will - because your thinking is captured
@ -130,6 +136,7 @@ The Skeptic asks: "This sounds great in theory. But what's the actual skill that
The Advocate explains: "Godin says linchpins 'connect disparate ideas.' For product designers, this means navigating five different dimensions of thinking at the same time. Most people can handle one or two dimensions. Irreplaceable designers navigate all five simultaneously."
The 5 dimensions:
1. **Business Existence (WHY)** - Understanding purpose and value creation
2. **Business Goals (SUCCESS)** - Connecting to metrics and impact
3. **Product Strategy (HOW)** - Making hard choices about features
@ -139,6 +146,7 @@ The 5 dimensions:
**Real Example - Family Coordination App:**
The Advocate uses a concrete example: "Think about designing an app that helps families coordinate tasks. You need to understand:
- **WHY** - Why does this business exist? (Solving family conflict and stress)
- **SUCCESS** - What does success look like? (Kids complete tasks without nagging)
- **HOW** - What features serve that goal? (Visual task board, not text lists)
@ -164,6 +172,7 @@ The Advocate gets practical: "Whiteport Design Studio guides you through a three
The Advocate explains: "First, you learn to deeply understand both sides of the equation. Not just surface-level - but the real WHY behind business existence and user needs. You learn to ask the right questions, dig deeper, and connect the dots between what the business needs to survive and what users need to thrive."
What you learn:
- How to uncover the real business purpose (not just features)
- How to understand user goals at a deep level (not just tasks)
- How to find the intersection where both are served
@ -178,6 +187,7 @@ The Advocate: "Exactly. You become the expert on WHY this product exists and WHO
The Advocate continues: "Second, you learn to work directly in the IDE - your development environment. This sounds technical, but it's actually liberating. You learn to capture your design thinking in text specifications that preserve your creative intent."
What you learn:
- How to write specifications that capture WHY, not just WHAT
- How to document your judgment calls and reasoning
- How to work with AI as your creative partner
@ -192,6 +202,7 @@ The Advocate: "Yes. You're making your emotional labor visible and actionable. Y
The Advocate brings it home: "Third, you learn to assume leadership for the design process. Not leadership as in 'boss' - but leadership as in 'the person who makes things happen.' You become the linchpin who serves both the client and the developers with exactly what they need, in the form they need it."
What you learn:
- How to lead the design process (courage and curiosity, not confidence)
- How to serve the client with clarity on business value
- How to serve developers with specifications they can implement
@ -210,6 +221,7 @@ The Advocate: "Exactly. Godin says linchpins make themselves indispensable by be
The Advocate emphasizes: "This course is your guide through this transformation. Module by module, you'll build these capabilities. You'll learn the frameworks, practice the skills, and through practice, develop the confidence that comes from knowing what you can deliver."
Your transformation:
- **Understanding** - Business and user goals at a deep level
- **Capability** - Working in the IDE, design as specification
- **Leadership** - Serving client and developers with what they need
@ -258,6 +270,7 @@ The Advocate brings it home: "The transformation continues, together. But it sta
At the end of the podcast, The Advocate should mention these resources:
**Key Concepts:**
- Seth Godin's book: "Linchpin: Are You Indispensable?" (2010)
- Bestselling author and marketing visionary Seth Godin
- Factory mindset vs linchpin mindset
@ -267,12 +280,14 @@ At the end of the podcast, The Advocate should mention these resources:
- 5-dimensional thinking
**Next Steps:**
- Complete Module 02: Project Brief
- Apply 5-dimensional thinking to your current project
- Start capturing WHY in your design decisions
- Practice being the gatekeeper between business and user needs
**Community:**
- BMad Discord: Share your transformation journey
- GitHub Discussions: Ask questions about becoming a linchpin designer
@ -281,6 +296,7 @@ At the end of the podcast, The Advocate should mention these resources:
## Instructions for NotebookLM
**Tone:**
- Deeply empathetic about the shame and fear designers feel
- Honest and direct about the AI threat for factory workers
- Empowering and inspiring about the opportunity for linchpin designers
@ -290,6 +306,7 @@ At the end of the podcast, The Advocate should mention these resources:
- Balance fear (replaceable) with hope (indispensable) and community (not alone)
**Key messages to emphasize:**
- **The linchpin question** - are you a factory worker or a linchpin designer?
- **Emotional labor** - what linchpins provide (Seth Godin's concept from his 2010 book)
- **User-centric creativity** - the designer's irreplaceable gift (emotional labor in action)
@ -312,6 +329,7 @@ At the end of the podcast, The Advocate should mention these resources:
- **Action beats perfection** - get moving and you will figure it out
**Avoid:**
- Being too theoretical or academic
- Repeating doom/gloom from Getting Started module
- Focusing too much on AI threat instead of human value
@ -324,6 +342,7 @@ At the end of the podcast, The Advocate should mention these resources:
## Expected Output
A natural, engaging conversation that:
- **Focuses on human value** - what makes designers irreplaceable
- **Explains the linchpin concept** clearly using Seth Godin's framework
- **Emphasizes emotional labor** as the core of linchpin work
@ -348,6 +367,7 @@ A natural, engaging conversation that:
If generating video instead of audio, add these visual elements:
**On-screen text:**
- "Factory Worker or Linchpin Designer?"
- Seth Godin quote: "Linchpins walk into chaos and create order"
- "Emotional Labor: The Work of Genuinely Caring"
@ -362,6 +382,7 @@ If generating video instead of audio, add these visual elements:
- "Next: Module 02 - Project Brief"
**B-roll suggestions:**
- Designer walking into chaos, creating order
- Linchpin connecting disparate ideas
- Designer providing emotional labor - caring, empathizing
@ -387,6 +408,7 @@ If generating video instead of audio, add these visual elements:
## Next Steps
After generating Module 01 content:
- Create NotebookLM prompt for Module 02: Project Brief
- Build prompts for all remaining modules
- Share in BMad Discord designer channel

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

22
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.
**What I Need to Get Started**:
- Your project vision and business goals
- Market research and competitive analysis needs
- Target user group information
@ -45,7 +46,7 @@ docs/
│ ├── 02-Competitive-Analysis.md ← Competitor deep-dive (I analyze this)
│ └── 03-Key-Features.md ← Core functionality (I define these)
│
├── 🗺️ B-Trigger-Map/ ← MY Journey Intelligence Center
├── 🗺️ B-Trigger-Map/ ← MY Journey Intelligence Center
│ ├── 00-Trigger-Map.md ← Complete trigger map (I map this)
│ │ ├── Business Goals ← What business wants to achieve
│ │ ├── Target Groups ← User segmentation
@ -91,18 +92,21 @@ Clear Business Direction → Deep User Understanding → Systematic User
### 🤝 **MY TEAM INTEGRATION**: How I Work with the WDS Team
**With Baldr (UX Expert):**
- I provide the strategic foundation and user insights needed for design
- Baldr uses my trigger map personas to create realistic user scenarios
- We collaborate on user journey mapping and experience design
- My business goals guide Baldr's design decisions
**With Freyja (Product Manager):**
- I hand off my strategic foundation for PRD development
- Freyja uses my business goals and success metrics for planning
- We ensure strategic alignment throughout the design process
- My trigger map informs Freyja's feature prioritization
**Integration with BMM (Development):**
- My Product Brief provides context for architecture decisions
- My Trigger Map personas inform user story creation
- My success metrics guide development priorities
@ -115,6 +119,7 @@ Clear Business Direction → Deep User Understanding → Systematic User
### 🎯 **MY MARKET INTELLIGENCE MASTERY**
**Here's exactly what I deliver:**
- **Strategic Analysis**: including comprehensive market research and competitive positioning
- **Business Vision**: designed for measurable success and stakeholder alignment
- **User Intelligence**: meaning detailed personas and journey mapping for systematic design
@ -140,6 +145,7 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S
### 🔧 **MY DELIVERABLES: What You Get from Saga**
#### **Strategic Foundation Package:**
```
📚 COMPLETE STRATEGIC INTELLIGENCE:
├── Product Brief with Clear Value Proposition
@ -161,18 +167,21 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S
**Here's exactly what changes when I enter your workflow:**
### 🎯 **FROM VAGUE IDEAS TO STRATEGIC CLARITY**
- Your brilliant concepts become measurable business strategies
- Market research eliminates guesswork and validates your approach
- Clear success metrics guide every team decision
- User psychology insights drive design decisions
### ⚡ **FROM CHAOTIC PLANNING TO SYSTEMATIC EXECUTION**
### ⚡ **FROM CHAOTIC PLANNING TO SYSTEMATIC EXECUTION**
- Strategic foundation eliminates confusion and misalignment
- Every team member knows exactly what success looks like
- Stakeholder communication becomes clear and compelling
- Trigger mapping reveals the psychology behind user behavior
### 💫 **FROM INDIVIDUAL EFFORT TO TEAM COORDINATION**
- My strategic foundation coordinates all team members
- Clear business goals align creative and technical work
- Systematic approach ensures nothing falls through the cracks
@ -185,7 +194,7 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S
**What excites you most about having me (Saga) create your strategic foundation:**
1. **📊 Market Intelligence Mastery** - I research your market and competitors to eliminate guesswork
2. **📋 Product Brief Excellence** - I transform your ideas into clear, measurable business strategies
2. **📋 Product Brief Excellence** - I transform your ideas into clear, measurable business strategies
3. **🗺️ Trigger Map Intelligence** - I map user psychology and business goals for systematic design
4. **🎯 Success Metrics Definition** - I establish clear KPIs and measurable goals for your project
5. **🤝 Team Coordination Foundation** - I create the strategic foundation that guides all team members
@ -200,12 +209,14 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S
**These elegant strategic conventions ensure my deliverables are enterprise-ready:**
### 🏗️ **MY STRATEGIC ARCHITECTURE MASTERY**
- **Strategic Input**: Your vision, ideas, and business goals
- **My Analysis Output**: A-Product-Brief/, B-Trigger-Map/ (strategic foundation I create)
- **Title-Case-With-Dashes**: Every folder and file I create follows enterprise presentation standards
- **Absolute Paths**: I always use absolute paths (docs/A-Product-Brief/) for clarity
### 🎨 **MY STRATEGIC ANALYSIS EVOLUTION PROCESS**
```
My Strategic Workflow Progression:
Your Ideas → Market Research → Product Brief → Trigger Map → Strategic Foundation
@ -215,6 +226,7 @@ Vision Clarity → Market Understanding → Clear Strategy → User Intelligence
```
### ✨ **MY COMMUNICATION EXCELLENCE STANDARDS**
- **Crystal-clear strategic language** without confusing technical jargon
- **Professional analysis style** using "including", "designed for", "meaning" conventions
- **Collaborative approach** - one question at a time, deep listening
@ -230,6 +242,7 @@ Vision Clarity → Market Understanding → Clear Strategy → User Intelligence
In Norse mythology, Saga is the goddess of stories and wisdom. She sits with Odin in her hall Sökkvabekkr ("sunken benches" or "treasure benches"), where they drink together and share stories.
This perfectly captures what I do:
- **Stories**: Every product has a story - I help you discover and tell it
- **Wisdom**: I bring strategic intelligence and market insights to guide decisions
- **Listening**: Like Saga listening to Odin's tales, I listen deeply to understand your vision
@ -246,12 +259,14 @@ This perfectly captures what I do:
## Presentation Notes for Saga
**When to Use:**
- When Saga activates as the Business Analyst
- When users need strategic foundation and market intelligence
- At the start of any new WDS project
- When teams need clear business direction and user insights
**Key Delivery Points:**
- Maintain analytical, strategic tone throughout
- Emphasize strategic foundation building, not just research
- Show how Saga's work coordinates with Freyja and Baldr
@ -261,6 +276,7 @@ This perfectly captures what I do:
- Confirm user enthusiasm for strategic approach before proceeding
**Success Indicators:**
- User expresses excitement about strategic foundation approach
- Market research and analysis methodology is clearly understood
- Team coordination value is appreciated

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

62
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.
> **Founder's Note:** I personally acquired the insights about the power of the Effect Map back in 2007, and it has served as the philosophical basis for all of my work in UX for almost 20 years. I am eternally grateful for this model that I now have the pleasure to share with the world in an updated version suitable for modern projects.
> — *Martin Eriksson, WDS Creator*
> — _Martin Eriksson, WDS Creator_
📚 **Further Reading:**
- [Impact Mapping on Amazon](https://www.amazon.com/Impact-Mapping-Software-Products-Projects/dp/0955683645) - Gojko Adzic's book building on Effect Mapping concepts
- [impactmapping.org](https://www.impactmapping.org) - Resources and community
@ -53,11 +54,13 @@ Effect Mapping is the original model that connects business goals to user behavi
Trigger Mapping is WDS's adaptation of Effect Mapping, designed for longer shelf life and deeper psychological insight:
**Simplified:**
- Leaves out actions/features from the map
- Focuses on the strategic connections
- Map stays relevant even as features evolve
**Enhanced:**
- Adds **negative driving forces** (fears, frustrations)
- Creates fuller picture of user psychology
- Both what users want AND what they want to avoid
@ -67,6 +70,7 @@ Trigger Mapping is WDS's adaptation of Effect Mapping, designed for longer shelf
Any software is about **flow of value**. There's always a group of people who, through their use of the software, make your success happen.
These users have their own goals:
- **GAIN** - Benefits and positive outcomes they achieve
- **PAIN** - Resistance and friction they experience
@ -81,10 +85,11 @@ The Trigger Map combines three critical layers in one picture:
3. **Usage Goals** - Their WHY (Driving forces both positive - what they wish to achieve, and negative - what they wish to avoid)
When all levels are then prioritized, you have perfect guidance for design:
- Present features that add value to your most prioritized goal first
- To the highest prioritized target group
- In a way that best suits their most prioritized usage goal
- Make sound decisions about priority of bugs or features based on the total impact on users' goals
- Make sound decisions about priority of bugs or features based on the total impact on users' goals
---
@ -98,18 +103,21 @@ Business goals work at two levels:
**Vision (Motivating, not easily quantifiable)**
A statement that inspires and guides direction:
- "Become the most popular free and open source design support framework"
- "Be the go-to partner for SMB digital transformation"
- "Make professional UX accessible to every startup"
**Objectives (SMART metrics)**
Specific, measurable targets that indicate progress toward the vision:
- "10,000 active designer users by 2027"
- "100 community contributions accepted by Q4 2026"
- "50% of users complete full 6-phase workflow"
- "NPS score of 60+ from design professionals"
You'll define both levels:
- Vision that motivates the team
- Objectives with clear success metrics
@ -118,6 +126,7 @@ You'll define both levels:
Key question: "Who needs to succeed for YOU to succeed?"
Instead of demographics, you discover:
- User types who can drive business success
- The role each type plays in your strategy
- How different users contribute differently
@ -134,6 +143,7 @@ For each user type:
"Now the flip side: What do they desperately want to avoid? What would feel like failure?"
This reveals:
- **Positive Triggers** - What motivates action
- **Negative Triggers** - What prevents engagement
- **Emotional Drivers** - The psychology behind decisions
@ -142,6 +152,7 @@ This reveals:
### Stage 4: Visual Strategy Map (15-20 minutes)
Saga helps build the complete trigger map:
- Connecting every user insight to business goals
- Creating the visual strategy guide
- Validating the strategic logic together
@ -171,37 +182,38 @@ Now the magic happens. You connect strategy to concrete features using a systema
3. **Map to Driving Forces** - Which positive and negative drivers does it address?
4. **Score the Impact** - Features serving multiple groups and drivers score higher
**The Scoring System:** *(Beta - refinements welcome)*
**The Scoring System:** _(Beta - refinements welcome)_
For each feature, award points:
| Impact | Points |
|--------|--------|
| Serves Priority 1 Target Group | +3 |
| Serves Priority 2 Target Group | +2 |
| Serves Priority 3 Target Group | +1 |
| Addresses Priority 1 Positive Driver | +3 |
| Addresses Priority 2 Positive Driver | +2 |
| Addresses Priority 3 Positive Driver | +1 |
| **Addresses Priority 1 Negative Driver** | **+4** |
| **Addresses Priority 2 Negative Driver** | **+3** |
| **Addresses Priority 3 Negative Driver** | **+2** |
| Serves multiple target groups | +2 bonus |
| Impact | Points |
| -------------------------------------------- | -------- |
| Serves Priority 1 Target Group | +3 |
| Serves Priority 2 Target Group | +2 |
| Serves Priority 3 Target Group | +1 |
| Addresses Priority 1 Positive Driver | +3 |
| Addresses Priority 2 Positive Driver | +2 |
| Addresses Priority 3 Positive Driver | +1 |
| **Addresses Priority 1 Negative Driver** | **+4** |
| **Addresses Priority 2 Negative Driver** | **+3** |
| **Addresses Priority 3 Negative Driver** | **+2** |
| Serves multiple target groups | +2 bonus |
| Addresses both positive AND negative drivers | +2 bonus |
> **Why negative drivers score higher:** Loss aversion is a well-documented psychological principle - humans work harder to avoid pain than to pursue gain. Features that remove friction, fear, or frustration create stronger user loyalty than features that simply add benefits.
**Example:**
| Feature | Target Groups | Driving Forces | Score |
|---------|---------------|----------------|-------|
| Feature | Target Groups | Driving Forces | Score |
| ----------------- | --------------------------------- | --------------------------------------------------------------------------------- | ------ |
| One-click booking | P1 Dog Owner (+3), P2 Walker (+2) | Convenience (+3), Fear of complexity (-P1: +4), Multi-group (+2), Both types (+2) | **16** |
| Review system | P1 Dog Owner (+3) | Trust (+2), Fear of bad walker (-P1: +4), Both types (+2) | **11** |
| Calendar sync | P2 Walker (+2) | Efficiency (+1) | **3** |
| Review system | P1 Dog Owner (+3) | Trust (+2), Fear of bad walker (-P1: +4), Both types (+2) | **11** |
| Calendar sync | P2 Walker (+2) | Efficiency (+1) | **3** |
**The Output:**
A ranked feature list showing:
- Which features have the broadest impact
- Which features are "single-purpose" vs "multi-impact"
- Natural MVP candidates (highest scores)
@ -220,11 +232,13 @@ Traditional personas describe demographics: "Jennifer, 34, likes yoga and lattes
WDS personas capture psychology:
**Alliterative Naming** - Each persona gets a memorable name that hints at their role:
- "Patrick the Professional" - Decision-maker focused on efficiency
- "Sophie the Socializer" - Values connection and community
- "Tyler the Technical" - Wants control and customization
**What Each Persona Includes:**
- Role and context
- Goals they're trying to achieve
- Fears and frustrations
@ -237,16 +251,19 @@ WDS personas capture psychology:
## When to Use This Phase
**Use after Phase 1 if:**
- Building a new product
- Need clarity on who you're building for
- Want design decisions grounded in user psychology
**Start here if:**
- You have product vision but unclear user strategy
- Existing personas feel shallow or unused
- Features aren't connecting with users
**Skip if:**
- Quick enhancement to existing feature
- Users are already well-documented and validated
- Design system work without new user research
@ -256,6 +273,7 @@ WDS personas capture psychology:
## What to Prepare
Bring:
- Your completed Product Brief (Phase 1)
- Any existing user research (even informal)
- Stakeholder availability for the workshop
@ -277,15 +295,18 @@ The trigger map becomes the strategic brain of your product.
## Tips for Great Sessions
**Think strategically, not demographically**
- "Who needs to win for us to win?" not "Who might use this?"
- Connect every user insight to business outcomes
**Go deep on psychology**
- Push beyond surface responses
- Ask "why" multiple times
- Understand motivations, not just behaviors
**Build the map live**
- See connections as they emerge
- Validate strategic logic together
- Make it visual and shareable
@ -298,5 +319,4 @@ See: `examples/dog-week-patterns/B-Trigger-Map/` for a complete Trigger Map with
---
*Phase 2 of the Whiteport Design Studio method*
_Phase 2 of the Whiteport Design Studio method_

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.**
While UX designers explore how users interact with features, technical validation runs alongside:
- Can we actually build this?
- Do the external services we need exist and work as expected?
- What platform and infrastructure do we need?
@ -46,12 +47,14 @@ Design and technical validation inform each other. Neither waits for the other t
Establish the technical foundation:
**Architecture:**
- What technology stack fits your needs?
- Monolith vs. microservices vs. serverless?
- What hosting/infrastructure approach?
- What are the key technical constraints?
**Data Model:**
- What are the core entities?
- How do they relate to each other?
- What's the database strategy?
@ -72,15 +75,16 @@ Identify all external dependencies:
**Examples:**
| Feature Idea | Proof of Concept Question |
|--------------|---------------------------|
| Feature Idea | Proof of Concept Question |
| ----------------------------------- | ------------------------------------------------------------------ |
| "Show drive time between locations" | Can we call Google Maps Directions API and get estimated duration? |
| "Real-time availability updates" | Can we set up WebSocket connections that scale? |
| "AI-powered recommendations" | Does the ML model perform well enough with our data? |
| "Offline mode" | Can we sync data reliably when connection returns? |
| "Video calling" | Which provider works best? What's the latency? |
| "Real-time availability updates" | Can we set up WebSocket connections that scale? |
| "AI-powered recommendations" | Does the ML model perform well enough with our data? |
| "Offline mode" | Can we sync data reliably when connection returns? |
| "Video calling" | Which provider works best? What's the latency? |
**What a PoC validates:**
- The API/service exists and does what we need
- Performance is acceptable
- Cost is within budget
@ -88,6 +92,7 @@ Identify all external dependencies:
- Edge cases are handleable
**PoC Output:**
- Working code snippet or prototype
- Documented limitations and gotchas
- Cost estimates (API calls, compute, etc.)
@ -98,12 +103,14 @@ Identify all external dependencies:
### Stage 4: Security & Performance Framework (20-30 minutes)
**Security:**
- Authentication approach (passwords, OAuth, SSO, passwordless)
- Authorization model (roles, permissions, row-level security)
- Data encryption needs (at rest, in transit)
- Compliance requirements (GDPR, HIPAA, PCI-DSS, etc.)
**Performance:**
- Expected load and scale
- Response time expectations
- Availability requirements (99.9%? 99.99%?)
@ -122,16 +129,17 @@ Even before the UI is designed, you often know certain data operations are essen
**What to set up:**
| Endpoint Type | Example | Why Early? |
|---------------|---------|------------|
| Core CRUD | `GET /api/dogs`, `POST /api/bookings` | Foundation for everything |
| Endpoint Type | Example | Why Early? |
| --------------------- | ---------------------------------------- | --------------------------- |
| Core CRUD | `GET /api/dogs`, `POST /api/bookings` | Foundation for everything |
| External integrations | `GET /api/routes/estimate` (Google Maps) | Validates third-party works |
| Authentication | `/api/auth/login`, `/api/auth/refresh` | Security model proven |
| Key calculations | `/api/availability/check` | Business logic validated |
| Authentication | `/api/auth/login`, `/api/auth/refresh` | Security model proven |
| Key calculations | `/api/availability/check` | Business logic validated |
**Output:**
For each experimental endpoint, document:
- Endpoint specification (method, path, request/response)
- What it validates
- Current status (stub, working, blocked)
@ -196,12 +204,14 @@ This parallelism is one of WDS's key efficiency gains. Development teams can beg
## When to Use This Phase
**Use this phase when:**
- Building platform/infrastructure for a new product
- Features depend on external APIs or services
- Innovative features need technical validation
- Development team needs architectural clarity before design
**Skip or minimize if:**
- Simple project with obvious technical approach
- Working within existing platform/infrastructure
- Enhancement that doesn't change architecture
@ -212,6 +222,7 @@ This parallelism is one of WDS's key efficiency gains. Development teams can beg
## What to Prepare
Bring:
- Product Brief (Phase 1)
- Trigger Map with Feature Impact Analysis (Phase 2)
- Any existing technical constraints
@ -232,19 +243,23 @@ Your technical foundation enables:
## Tips for Great Sessions
**Validate risky features first**
- If the Google Maps API doesn't return drive times in a usable format, you need to know NOW
- Don't design features you can't build
**Document constraints clearly**
- Designers need to know what's possible
- "Loading state required" vs "instant" changes UX significantly
**Involve developers**
- Technical decisions benefit from dev input
- PoC work may require developer time
- Architecture is a conversation, not a decree
**Stay connected to strategy**
- Reference Feature Impact Analysis scores
- High-impact features deserve more PoC investment
- Don't over-engineer for hypothetical needs
@ -257,13 +272,13 @@ See: `examples/dog-week-patterns/C-Requirements/` for the Dog Week technical fou
**What Dog Week needed to prove early:**
- *"Can we show dog owners how long it takes to walk to a dog walker?"* → Google Maps Directions API returns walking time between coordinates ✓
- *"Can we check real-time availability across multiple walkers?"* → Endpoint aggregates calendar data in <200ms ✓
- *"Can we handle Swish payments for Swedish users?"* → Swish API integration validated with test transactions ✓
- *"Can walkers see their schedule on mobile?"* → Responsive calendar component renders correctly on iOS/Android browsers ✓
- _"Can we show dog owners how long it takes to walk to a dog walker?"_ → Google Maps Directions API returns walking time between coordinates ✓
- _"Can we check real-time availability across multiple walkers?"_ → Endpoint aggregates calendar data in <200ms ✓
- _"Can we handle Swish payments for Swedish users?"_ → Swish API integration validated with test transactions ✓
- _"Can walkers see their schedule on mobile?"_ → Responsive calendar component renders correctly on iOS/Android browsers ✓
These early discoveries shaped both the design AND the development approach.
---
*Phase 3 of the Whiteport Design Studio method*
_Phase 3 of the Whiteport Design Studio method_

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

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

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

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

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

59
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:
### Phase 1: Product Exploration (Product Brief)
**Output:** `A-Product-Brief/`
**Agent:** Saga the Analyst
Establish your strategic foundation through conversational discovery. Instead of filling out questionnaires, you have a conversation that builds understanding organically.
**What you create:**
- Product vision and problem statement
- Market positioning and differentiation
- Success criteria and metrics
@ -59,12 +61,14 @@ Establish your strategic foundation through conversational discovery. Instead of
---
### Phase 2: Trigger Mapping (Trigger Map)
**Output:** `B-Trigger-Map/`
**Agent:** Saga the Analyst
Connect business goals to user psychology through Trigger Mapping. Discover not just WHO your users are, but WHY they act and WHAT triggers their decisions.
**What you create:**
- Business goals (Vision + SMART objectives)
- Target groups connected to business outcomes
- Detailed personas with psychological depth
@ -75,12 +79,14 @@ Connect business goals to user psychology through Trigger Mapping. Discover not
---
### Phase 3: PRD Platform (Technical Foundation)
**Output:** `C-Requirements/`
**Agent:** Freyja the PM
Prove your concept works technically - in parallel with design work. Validate platform decisions, create proofs of concept, and set up experimental endpoints.
**What you create:**
- Platform architecture decisions
- Data model and integrations
- Technical proofs of concept
@ -91,6 +97,7 @@ Prove your concept works technically - in parallel with design work. Validate pl
---
### Phase 4: UX Design (UX-Sketches & Usage Scenarios)
**Output:** `C-Scenarios/`
**Agent:** Baldr the UX Expert
@ -99,6 +106,7 @@ Transform ideas into detailed visual specifications. Your agent helps you think
**The key insight:** Designs that can be logically explained without gaps are easy to develop. The specification process reveals gaps early - when they're easy to address.
**What you create:**
- Scenario folder structure (numbered hierarchy)
- Page specifications with full detail
- Component definitions with Object IDs
@ -109,12 +117,14 @@ Transform ideas into detailed visual specifications. Your agent helps you think
---
### Phase 5: Design System (Component Library)
**Output:** `D-Design-System/`
**Agent:** Baldr the UX Expert
Build your component library following atomic design principles. This phase is **optional** and runs **in parallel** with Phase 4 - as you design pages, you extract reusable components.
**What you create:**
- Design tokens (colors, typography, spacing)
- Atomic components (buttons, inputs, labels)
- Molecular components (form groups, cards)
@ -125,12 +135,14 @@ Build your component library following atomic design principles. This phase is *
---
### Phase 6: PRD Finalization (Complete PRD)
**Output:** Complete PRD in `C-Requirements/` + `E-UI-Roadmap/`
**Agent:** Freyja the PM
Compile all functional requirements discovered during Phase 4 into a complete, development-ready PRD. This phase runs **continuously** - hand off as soon as you have MVP scope, then update as design progresses.
**What you create:**
- Complete PRD (Platform + Functional requirements)
- Feature organization by epic/area
- Development sequence with priorities
@ -145,14 +157,15 @@ WDS creates an organized folder structure in your project's `docs/` folder. Duri
### Your 4 Options
| Choice | Option A | Option B |
|--------|----------|----------|
| Choice | Option A | Option B |
| ---------- | -------------------- | ----------------------- |
| **Prefix** | Letters (A, B, C...) | Numbers (01, 02, 03...) |
| **Case** | Title-Case | lowercase |
| **Case** | Title-Case | lowercase |
### Examples
**Letters + Title-Case** (default):
```
docs/
├── A-Product-Brief/
@ -164,6 +177,7 @@ docs/
```
**Numbers + Title-Case**:
```
docs/
├── 01-Product-Brief/
@ -175,6 +189,7 @@ docs/
```
**Default (Letters + Title-Case) is recommended because:**
- Title-Case is easier for non-technical people to read
- Letters create distinctive WDS branding
- Distinguishes WDS folders from other docs
@ -185,14 +200,14 @@ docs/
Not every project needs all six phases. Select what you need based on your situation:
| Project Type | Recommended Phases |
|--------------|-------------------|
| **Landing page** | 1, 4 |
| **Full product (greenfield)** | All six |
| **Feature enhancement** | 2, 4, 6 |
| **Design system only** | 4, 5 |
| **Strategic planning** | 1, 2 |
| **Quick prototype** | 4 only |
| Project Type | Recommended Phases |
| ----------------------------- | ------------------ |
| **Landing page** | 1, 4 |
| **Full product (greenfield)** | All six |
| **Feature enhancement** | 2, 4, 6 |
| **Design system only** | 4, 5 |
| **Strategic planning** | 1, 2 |
| **Quick prototype** | 4 only |
Your agents will help you identify which phases fit your project.
@ -203,29 +218,35 @@ Your agents will help you identify which phases fit your project.
Three specialized agents guide you through WDS:
### Saga the Analyst 📚
*"The one who tells your business story"*
_"The one who tells your business story"_
Saga guides you through discovery and research. She's curious, patient, and helps you uncover insights you might not have seen yourself.
**Works with you on:**
- Phase 1: Product Exploration
- Phase 2: Trigger Mapping
### Freyja the PM ⚔️
*"The strategic leader who sees what must be done"*
_"The strategic leader who sees what must be done"_
Freyja helps you define technical requirements and finalize the PRD for development. She balances passion with strategy, knowing when to be fierce and when to be patient.
**Works with you on:**
- Phase 3: PRD Platform
- Phase 6: PRD Finalization
### Baldr the UX Expert ✨
*"The one who brings light and beauty"*
_"The one who brings light and beauty"_
Baldr transforms your ideas into beautiful, detailed specifications. He cares deeply about craft and ensures every detail serves the user experience.
**Works with you on:**
- Phase 4: UX Design
- Phase 5: Design System
@ -233,11 +254,12 @@ Baldr transforms your ideas into beautiful, detailed specifications. He cares de
## How Sessions Work
WDS sessions are **conversations, not interrogations**.
WDS sessions are **conversations, not interrogations**.
### The Rhythm
A good WDS session feels like coffee with a wise mentor:
- They ask something interesting
- You share your thinking
- They reflect it back, maybe adding a new angle
@ -248,12 +270,14 @@ It never feels like filling out a form.
### What to Expect
**Your agent will:**
- Ask one question at a time, then listen
- Reflect back what they heard before moving on
- Build documents together with you, piece by piece
- Check in to make sure they understood correctly
**You'll leave with:**
- Clear documentation you helped create
- Deeper understanding of your own product
- Ready-to-use artifacts for the next phase
@ -293,6 +317,7 @@ npx bmad-method@alpha install
## The WDS Difference
### Traditional Approach
- 47-question requirements spreadsheet
- Generic persona templates
- Designers work alone, then throw specs "over the wall"
@ -300,6 +325,7 @@ npx bmad-method@alpha install
- Everyone argues about what was meant
### WDS Approach
- Conversations that build understanding
- Personas with psychological depth connected to business goals
- Collaborative workshops building shared understanding
@ -333,6 +359,7 @@ C-Requirements/ ────► C-Requirements/ ────►
### Parallel Streams
Design and development can work in parallel:
- Phase 3 complete → Backend/platform development can start
- Phase 4 MVP scenarios complete → Phase 6 first handoff → Sprint 1 begins
- Design continues → Regular Phase 6 updates → More sprints
@ -348,4 +375,4 @@ Design and development can work in parallel:
---
*Whiteport Design Studio - Part of the BMad ecosystem*
_Whiteport Design Studio - Part of the BMad ecosystem_

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

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

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

@ -82,12 +82,12 @@ You: "Yes"
Agent: "Based on your Trigger Map:
- Target: Parents (tired of nagging)
- Trigger: Family conflict
For the Hero section, I suggest:
Headline: 'Stop Nagging. Start Harmony.'
Does this address their frustration?"
You: "Perfect!"
```
@ -98,6 +98,7 @@ You: "Perfect!"
## What Just Happened?
You created **why-based specifications** in 5 minutes:
- Connected to user psychology (Trigger Map)
- Grounded in real context (Scenario Init)
- Generated with AI assistance (Agent collaboration)
@ -108,12 +109,15 @@ You created **why-based specifications** in 5 minutes:
## Next Steps
### Learn the Concepts
[Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md) - Deep dive into WDS philosophy
### Start Your Project
[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md) - Full workflow documentation
### Get Help
[Community](https://discord.gg/whiteport) - Join the WDS community
---

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

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

@ -2,11 +2,11 @@
# Copy this template to: deliveries/DD-XXX-name.yaml
delivery:
id: "DD-XXX" # Format: DD-001, DD-002, etc.
name: "Feature Name" # Human-readable name
type: "user_flow" # user_flow | feature | component
status: "ready" # ready | in_progress | blocked
priority: "high" # high | medium | low
id: "DD-XXX" # Format: DD-001, DD-002, etc.
name: "Feature Name" # Human-readable name
type: "user_flow" # user_flow | feature | component
status: "ready" # ready | in_progress | blocked
priority: "high" # high | medium | low
created_by: "wds-ux-expert"
created_at: "YYYY-MM-DDTHH:MM:SSZ"
updated_at: "YYYY-MM-DDTHH:MM:SSZ"
@ -29,17 +29,17 @@ design_artifacts:
- id: "XX-scenario-name"
path: "C-Scenarios/XX-scenario-name/"
screens: ["screen1", "screen2"]
- id: "XX-scenario-name"
path: "C-Scenarios/XX-scenario-name/"
screens: ["screen1"]
user_flows:
- name: "Flow Name"
path: "C-Scenarios/flows/flow-name.excalidraw"
entry: "entry-screen"
exit: "exit-screen"
design_system:
components:
- "Component Name (variants)"
@ -48,22 +48,22 @@ design_artifacts:
technical_requirements:
platform:
frontend: "framework-name" # From platform-requirements.yaml
backend: "framework-name" # From platform-requirements.yaml
frontend: "framework-name" # From platform-requirements.yaml
backend: "framework-name" # From platform-requirements.yaml
integrations:
- name: "integration-name"
purpose: "[Why this integration is needed]"
required: true # true | false
required: true # true | false
- name: "integration-name"
purpose: "[Why this integration is needed]"
required: false
data_models:
- name: "ModelName"
fields: ["field1", "field2", "field3"]
- name: "ModelName"
fields: ["field1", "field2"]
@ -72,12 +72,12 @@ acceptance_criteria:
- "[Functional requirement 1]"
- "[Functional requirement 2]"
- "[Functional requirement 3]"
non_functional:
- "[Performance requirement]"
- "[Accessibility requirement]"
- "[Security requirement]"
edge_cases:
- "[Edge case 1] → [Expected behavior]"
- "[Edge case 2] → [Expected behavior]"
@ -87,17 +87,17 @@ testing_guidance:
user_testing:
- "[User testing instruction 1]"
- "[User testing instruction 2]"
qa_testing:
- "[QA testing instruction 1]"
- "[QA testing instruction 2]"
- "[QA testing instruction 3]"
estimated_complexity:
size: "medium" # small | medium | large
effort: "2-3 weeks" # Time estimate
risk: "low" # low | medium | high
dependencies: [] # List of DD-XXX IDs needed first
size: "medium" # small | medium | large
effort: "2-3 weeks" # Time estimate
risk: "low" # low | medium | high
dependencies: [] # List of DD-XXX IDs needed first
notes: |
[Any special considerations, important context, or

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

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

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

@ -2,12 +2,12 @@
# Save to: test-scenarios/TS-XXX-name.yaml
test_scenario:
id: "TS-XXX" # Format: TS-001, TS-002, etc.
name: "Feature Testing" # Human-readable name
delivery_id: "DD-XXX" # Related Design Delivery
type: "user_acceptance" # user_acceptance | integration | e2e
status: "ready" # ready | in_progress | blocked
tester: "designer" # designer | qa | developer
id: "TS-XXX" # Format: TS-001, TS-002, etc.
name: "Feature Testing" # Human-readable name
delivery_id: "DD-XXX" # Related Design Delivery
type: "user_acceptance" # user_acceptance | integration | e2e
status: "ready" # ready | in_progress | blocked
tester: "designer" # designer | qa | developer
created_at: "YYYY-MM-DDTHH:MM:SSZ"
test_objectives:
@ -21,7 +21,7 @@ test_environment:
devices:
- "Device 1 (OS version)"
- "Device 2 (OS version)"
test_data:
- field: "value"
- field: "value"
@ -30,17 +30,17 @@ test_environment:
happy_path:
- id: "HP-001"
name: "Main User Flow"
priority: "critical" # critical | high | medium | low
priority: "critical" # critical | high | medium | low
steps:
- action: "[User action]"
expected: "[Expected result]"
design_ref: "[Path to specification]#[section]"
- action: "[User action]"
expected: "[Expected result]"
design_ref: "[Path to specification]#[section]"
success_criteria:
- "[Success criterion 1]"
- "[Success criterion 2]"
@ -51,13 +51,13 @@ error_states:
- id: "ES-001"
name: "Error Scenario"
priority: "high"
steps:
- action: "[Action that triggers error]"
- expected: "[Expected error message]"
- expected: "[Expected recovery option]"
- design_ref: "[Path to specification]#[error-section]"
success_criteria:
- "[Error handling criterion 1]"
- "[Error handling criterion 2]"
@ -67,12 +67,12 @@ edge_cases:
- id: "EC-001"
name: "Edge Case Scenario"
priority: "medium"
steps:
- action: "[Unusual action]"
- expected: "[Expected handling]"
- design_ref: "[Path to specification]#[edge-case-section]"
success_criteria:
- "[Edge case criterion 1]"
@ -94,15 +94,15 @@ accessibility:
- id: "A11Y-001"
name: "Screen Reader Navigation"
priority: "high"
setup: "Enable screen reader (VoiceOver/TalkBack)"
steps:
- action: "[Navigate with screen reader]"
- verify:
- "[Accessibility check 1]"
- "[Accessibility check 2]"
success_criteria:
- "[Accessibility criterion 1]"
- "[Accessibility criterion 2]"
@ -112,10 +112,10 @@ usability:
- id: "UX-001"
name: "First Impression"
type: "observational"
instructions: |
[Instructions for conducting usability test]
success_criteria:
- "[Usability criterion 1]"
- "[Usability criterion 2]"
@ -124,11 +124,11 @@ usability:
performance:
- id: "PERF-001"
name: "Performance Check"
verify:
- "[Performance metric 1]"
- "[Performance metric 2]"
success_criteria:
- "[Performance target 1]"
- "[Performance target 2]"
@ -143,14 +143,14 @@ report_template:
- "Device tested"
- "Build version"
- "Overall result (Pass/Fail/Partial)"
- name: "Happy Path Results"
fields:
- "Test ID"
- "Result (Pass/Fail)"
- "Notes"
- "Screenshots"
- name: "Issues Found"
fields:
- "Issue ID"
@ -160,13 +160,13 @@ report_template:
- "Expected vs Actual"
- "Screenshot/Video"
- "Design reference violated"
- name: "Design System Compliance"
fields:
- "Component"
- "Compliant (Yes/No)"
- "Deviations noted"
- name: "Recommendations"
fields:
- "What worked well"
@ -181,12 +181,12 @@ sign_off:
- "Design system compliance > 95%"
- "Accessibility tests pass"
- "Usability metrics meet targets"
designer_approval:
statement: |
I confirm that the implemented feature matches the design
specifications and meets the quality standards defined in
this test scenario.
signature: "________________"
date: "________________"

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

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

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

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

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

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

@ -1,4 +1,5 @@
# Chapter 0: Why WDS Matters
## Part 1: Inspiration
**Learn how to be indispensable in the AI era**
@ -14,6 +15,7 @@ This isn't about working faster or making shinier designs. It's about becoming w
In the AI era, designers who master WDS become linchpin designers. They connect ideas that seem unrelated, make judgment calls when there's no clear answer, and create experiences that feel right in ways that can't be reduced to a formula.
**What makes an irreplaceable designer:**
- Connects disparate ideas across business, psychology, and technology
- Makes things happen when there's no instruction manual
- Creates value that can't be commoditized or automated
@ -30,6 +32,7 @@ By the end of this tutorial, you'll have a completely different relationship wit
Most importantly, you'll understand the five dimensions of thinking that only humans can navigate simultaneously - and you'll know how to use them to create designs that AI could never conceive on its own.
**Your transformation:**
- ✅ Understand why designers are irreplaceable in the AI era
- ✅ Master the 5 dimensions of designer thinking
- ✅ Recognize what AI can and cannot do
@ -49,6 +52,7 @@ Traditional design work follows this exact pattern. You get a brief (instruction
Here's the uncomfortable truth: AI is really, really good at factory work. If your job is to follow instructions and create predictable outputs, you're in trouble. But if you can become a linchpin - someone who connects ideas, makes judgment calls, and creates meaning - you become more valuable than ever.
**The factory mindset in design:**
- Creates mockups by following briefs (instructions)
- Hands off to developers (replaceable step)
- Hopes they understand (no real connection)
@ -64,6 +68,7 @@ Let's be honest about what's happening. AI can now generate mockups in seconds.
But here's the thing: AI cannot be a linchpin. It can't walk into a messy situation and figure out what actually needs to happen. It can't sense when a client is asking for the wrong thing. It can't connect a business goal to a psychological insight to a technical constraint and come up with something nobody expected but everyone loves.
**What AI does better than cogs:**
- Generates mockups instantly (no creative block)
- Follows design systems perfectly (zero deviation)
- Iterates through hundreds of variations (no fatigue)
@ -87,6 +92,7 @@ Linchpin designers do what AI fundamentally cannot do: they give products a soul
The bottleneck in product development used to be coding. AI demolished that. Now the bottleneck is **products worth building** - figuring out what to create that won't be just more noise in an ocean of AI-generated mediocrity.
**What makes products come alive (what only designers can do):**
- Navigate 5 dimensions to find the human truth at the intersection
- Make judgment calls that create emotional resonance, not just functionality
- Build trust through decisions that show someone cared
@ -107,6 +113,7 @@ WDS teaches you to be this person systematically. Not through vague advice about
This is what makes you indispensable. Not your Figma skills. Not your aesthetic taste. Your ability to walk into chaos and create order.
**The irreplaceable designer:**
- Transforms complexity into clarity
- Invents solutions nobody expected
- Bridges business, psychology, and technology
@ -125,6 +132,7 @@ AI can generate variations endlessly and make things look polished on the surfac
This is where user-centric creativity becomes critical. You're not just creating - you're evaluating, connecting, and protecting. You understand what it feels like to be a parent struggling to get their kids to help with the dog. You can sense when a business goal conflicts with user needs and find a creative solution that serves both. You're the advocate for the user's presence in every decision. You're the gatekeeper who ensures the impactful meeting between business and user actually happens through the product.
**The designer as gatekeeper:**
- Catches AI's confident but ridiculous mistakes before they ship
- Evaluates if solutions actually make logical sense
- Ensures business goals don't contradict user needs
@ -147,6 +155,7 @@ Here's the paradigm shift: **The design becomes the specification. The specifica
You remain in the loop - the skilled, experienced designer who evaluates AI's work, catches its confident mistakes, and ensures what ships actually makes sense. You become the key designer player - the person who makes things happen. AI becomes your tool - powerful but requiring your expertise to guide it.
**The designer's transformation:**
- **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage
- **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely
- **Result:** From replaceable cog to indispensable gatekeeper - your design IS the product
@ -166,7 +175,7 @@ This is what makes you indispensable as a designer. AI can help you think throug
**The 5 dimensions of design thinking:**
1. **Business Existence (WHY)** - Understanding purpose and value creation
2. **Business Goals (SUCCESS)** - Connecting to metrics and impact
2. **Business Goals (SUCCESS)** - Connecting to metrics and impact
3. **Product Strategy (HOW)** - Making hard choices about features
4. **Target Groups (WHO)** - Empathy and understanding needs
5. **Technical Viability (FEASIBLE)** - Bridging design and implementation
@ -188,6 +197,7 @@ This tutorial moves you to the other side. You'll become confident in your indis
You'll become the designer who makes things happen. The one they can't do without. The linchpin designer.
**Your transformation as a designer:**
- **Before:** Threatened, uncertain, frustrated, limited, replaceable
- **After:** Confident, clear, empowered, unstoppable, indispensable
- **Result:** The designer who makes things happen
@ -207,19 +217,21 @@ Compare the outcomes. The traditional approach - creating mockups, handing off t
That's a 5x speed increase with better quality. But more importantly, the key designer's creative thinking was preserved and amplified instead of diluted and lost.
**The comparison:**
- **Traditional (cog designer):** 26 weeks → Mediocre result → Intent lost
- **WDS (linchpin designer):** 5 weeks → Exceptional result → Intent preserved
- **Key difference:** Designer's user-centric creativity captured and amplified
---
*More case studies will be added here as they become available.*
_More case studies will be added here as they become available._
---
## Ready to Begin?
**Before you start, check the practicalities:**
- What skills you need (spoiler: you already have them)
- Time investment and learning paths
- Tools required (mostly free)
@ -232,6 +244,7 @@ That's a 5x speed increase with better quality. But more importantly, the key de
**Or jump straight into the methodology:**
In the next section (Teaching), you'll learn the concrete methodology:
- The 5 dimensions in detail with examples
- What AI cannot do (and what it can)
- Why specifications are the new code

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

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

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

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

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

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

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

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**.
This is our strategic foundation - we'll explore:
- Vision & positioning
- Target users (ICP)
- 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>
<action>Listen for:
- Aspirational outcomes
- Impact on users
- Market position
- Emotional drivers
</action>
</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:
*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:
1. Who's the target customer?
2. What's their need or opportunity?
3. What category does this fit?
4. What's the key benefit?
5. What makes it different from alternatives?
</action>
</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?**
Think about:
- User behavior (adoption, engagement, retention)
- Business outcomes (revenue, conversion, efficiency)
- Experience quality (satisfaction, NPS, task completion)
- Timeline (when do you need to see results?)</ask>
<action>Help make criteria SMART:
- Specific
- Measurable
- Achievable
- Relevant
- Time-bound
</action>
</action>
<template-output>success_criteria</template-output>
</step>
@ -166,16 +171,18 @@ Think about:
<ask>**What alternatives do your users have today?**
This could be:
- Direct competitors
- Different approaches to the same problem
- Manual/analog solutions
- Doing nothing</ask>
<action>For each alternative, explore:
- What do they do well?
- Where do they fall short?
- Why might users choose them over you?
</action>
</action>
<ask>**What's your unfair advantage?**
@ -241,6 +248,7 @@ Company stage, team capabilities, market conditions, past attempts?</ask>
{{constraints}}
---
</output>
<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`
This strategic foundation will guide all design decisions. You're ready for:
- **Phase 2: Trigger Mapping** - Deep dive into user psychology
- **Phase 3: PRD Platform** - Technical foundation
@ -262,4 +271,3 @@ Your vision is clear. Let's build something great! 🚀</output>
</step>
</workflow>

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

@ -19,6 +19,7 @@
{{positioning_statement}}
**Breakdown:**
- **Target Customer:** {{target_customer}}
- **Need/Opportunity:** {{need_opportunity}}
- **Category:** {{category}}
@ -31,8 +32,7 @@
**Type:** {{business_model}}
{{#if business_model_b2b}}
---
## {{#if business_model_b2b}}
## Business Customer Profile (B2B)
@ -40,11 +40,12 @@
### Buying Roles
| Role | Description |
|------|-------------|
| **Buyer** | {{buyer_role}} |
| Role | Description |
| ------------ | ----------------- |
| **Buyer** | {{buyer_role}} |
| **Champion** | {{champion_role}} |
| **User** | {{user_role}} |
| **User** | {{user_role}} |
{{/if}}
---
@ -99,5 +100,4 @@ This complete brief provides strategic foundation for all design work:
---
*Generated by Whiteport Design Studio*
_Generated by Whiteport Design Studio_

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
## Purpose
Welcome user and set expectations for the Project Brief workflow.
## Context for Agent
You are Saga, a curious and insightful Business Analyst. Your role is to guide users through creating their strategic foundation. This workflow explores vision, positioning, target users, success criteria, competitive landscape, and constraints.
## Key Elements to Cover
This workflow establishes the strategic foundation by exploring:
- Vision & positioning (core strategic direction)
- Target users (ICP) - who we're designing for
- Success criteria (how we'll measure success)
@ -15,13 +19,17 @@ This workflow establishes the strategic foundation by exploring:
- Constraints & context (real-world limitations)
## Instructions
Welcome the user and explain that this is their strategic foundation. Set time expectations (30-60 minutes) and ask about any existing context that should be considered.
## Next Step
When user confirms readiness, proceed to step-02-vision.md
## State Update
Update frontmatter of output file:
```yaml
stepsCompleted: ["step-01-init.md"]
stepsCompleted: ['step-01-init.md']
```

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

@ -1,12 +1,15 @@
# Step 2: Capture Vision
## Purpose
Help user articulate their vision for the product.
## Context for Agent
You are exploring the big picture with the user. Your goal is to help them crystallize their aspirational vision into a clear statement that will guide all decisions.
## Key Elements
This step captures the high-level, aspirational direction that will guide all decisions.
## Instructions
@ -27,11 +30,14 @@ This step captures the high-level, aspirational direction that will guide all de
- Use collaborative language: "What I'm hearing is..." or "It sounds like..."
## Next Step
After capturing vision, proceed to step-03-positioning.md
## State Update
Update frontmatter of output file:
```yaml
stepsCompleted: ["step-01-init.md", "step-02-vision.md"]
vision: "[captured vision statement]"
stepsCompleted: ['step-01-init.md', 'step-02-vision.md']
vision: '[captured vision statement]'
```

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

@ -1,26 +1,34 @@
# Step 3: Define Positioning
## Purpose
Help user define clear positioning statement for their product.
## Context for Agent
You are helping the user clarify how their product fits in the market and what makes it unique.
## Key Elements
This step establishes market positioning and differentiation.
## Key Framework
Positioning statement format: "For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator]."
## Instructions
Guide user through positioning framework. Ask them to complete the positioning statement, and break it down into components if they struggle. Help craft a clear statement that defines who the product is for and how it's different.
## Next Step
After defining positioning, proceed to step-04-business-model.md
## State Update
Update frontmatter of output file:
```yaml
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md"]
positioning: "[captured positioning statement]"
stepsCompleted: ['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md']
positioning: '[captured positioning statement]'
```

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

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)
## Goal
Help user define their ideal business customer profile.
## Key Elements
Business customer profile determines who buys the product and influences purchasing decisions.
## Instructions
If business model is B2B or Both, guide user to define their ideal business customer. Ask about company size, industry, decision-making structure, and budget authority. Also identify buying roles (buyer vs. user).
## Next Step
After identifying business customers, proceed to step-06-target-users.md
## State Update
Update frontmatter of output file:
```yaml
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md"]
business_customer_profile: "[captured business customer profile]"
buying_roles: "[captured buying roles]"
stepsCompleted:
['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md', 'step-04-business-model.md', 'step-05-business-customers.md']
business_customer_profile: '[captured business customer profile]'
buying_roles: '[captured buying roles]'
```

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
## Purpose
Help user define their ideal customer profile.
## Context for Agent
You are identifying who the product is for and what their needs are. This information will guide all design decisions.
## Key Elements
This step identifies who we're designing for and what their needs are.
## Instructions
Guide user to describe their ideal users in detail. Ask about their role, demographics, daily experience, frustrations, goals, and current solutions. Also identify any secondary users or stakeholders.
## Next Step
After identifying target users, proceed to step-07-success-criteria.md
## State Update
Update frontmatter of output file:
```yaml
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md"]
ideal_user_profile: "[captured user profile]"
secondary_users: "[captured secondary users]"
stepsCompleted:
[
'step-01-init.md',
'step-02-vision.md',
'step-03-positioning.md',
'step-04-business-model.md',
'step-05-business-customers.md',
'step-06-target-users.md',
]
ideal_user_profile: '[captured user profile]'
secondary_users: '[captured secondary users]'
```

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
## Purpose
Help user define measurable success criteria for their project.
## Context for Agent
You are establishing how the project will know if it's successful. This will guide all future decisions.
## Key Elements
This step establishes measurable outcomes that indicate success.
## Instructions
Guide user to define metrics and outcomes that indicate success. Help them think about user behavior, business outcomes, experience quality, and timeline. Work with them to make criteria SMART (Specific, Measurable, Achievable, Relevant, Time-bound).
## Next Step
After defining success criteria, proceed to step-08-competitive-landscape.md
## State Update
Update frontmatter of output file:
```yaml
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md"]
success_criteria: "[captured success criteria]"
stepsCompleted:
[
'step-01-init.md',
'step-02-vision.md',
'step-03-positioning.md',
'step-04-business-model.md',
'step-05-business-customers.md',
'step-06-target-users.md',
'step-07-success-criteria.md',
]
success_criteria: '[captured success criteria]'
```

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
## Purpose
Help user understand alternatives and their unique advantage.
## Context for Agent
You are exploring what alternatives exist and what makes the product unique. This information will guide differentiation strategy.
## Key Elements
This step identifies competitive positioning and unique value proposition.
## Instructions
Guide user to understand alternatives including direct competitors, different approaches, manual solutions, or doing nothing. For each alternative, explore strengths, weaknesses, and why users might choose them. Help identify their unfair advantage.
## Next Step
After analyzing competitive landscape, proceed to step-09-constraints.md
## State Update
Update frontmatter of output file:
```yaml
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md"]
competitive_landscape: "[captured competitive analysis]"
unfair_advantage: "[captured unfair advantage]"
stepsCompleted:
[
'step-01-init.md',
'step-02-vision.md',
'step-03-positioning.md',
'step-04-business-model.md',
'step-05-business-customers.md',
'step-06-target-users.md',
'step-07-success-criteria.md',
'step-08-competitive-landscape.md',
]
competitive_landscape: '[captured competitive analysis]'
unfair_advantage: '[captured unfair advantage]'
```

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
## Purpose
Help user identify constraints that should shape design decisions.
## Context for Agent
You are grounding the vision in reality by identifying limitations and context.
## Key Elements
This step identifies real-world limitations and additional context.
## Instructions
Guide user to identify constraints including timeline, budget, technical requirements, brand guidelines, regulatory needs, and integration requirements. Also ask for additional context like company stage, team capabilities, market conditions, or past attempts.
## Next Step
After capturing constraints, proceed to step-10-synthesize.md
## State Update
Update frontmatter of output file:
```yaml
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md", "step-09-constraints.md"]
constraints: "[captured constraints]"
additional_context: "[captured additional context]"
stepsCompleted:
[
'step-01-init.md',
'step-02-vision.md',
'step-03-positioning.md',
'step-04-business-model.md',
'step-05-business-customers.md',
'step-06-target-users.md',
'step-07-success-criteria.md',
'step-08-competitive-landscape.md',
'step-09-constraints.md',
]
constraints: '[captured constraints]'
additional_context: '[captured additional context]'
```

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
## Purpose
Synthesize all captured information into a complete project brief document.
## Context for Agent
You are bringing together all the strategic elements into a comprehensive brief that will guide all design decisions.
## Key Elements
This step compiles all strategic foundation elements into a cohesive document.
## Instructions
Present all captured information (vision, positioning, business model, business customers, target users, success criteria, competitive landscape, unfair advantage, constraints, and additional context). Ask for confirmation and make any requested adjustments. Generate final document using the template.
## Next Step
Workflow complete. User can proceed to Phase 2: Trigger Mapping
## State Update
Update frontmatter of output file:
```yaml
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md", "step-09-constraints.md", "step-10-synthesize.md"]
status: "complete"
stepsCompleted:
[
'step-01-init.md',
'step-02-vision.md',
'step-03-positioning.md',
'step-04-business-model.md',
'step-05-business-customers.md',
'step-06-target-users.md',
'step-07-success-criteria.md',
'step-08-competitive-landscape.md',
'step-09-constraints.md',
'step-10-synthesize.md',
]
status: 'complete'
```

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.
This is a **Simplified Project Brief** - we'll cover the key points in about 5-10 minutes:
- What you're building (scope)
- The challenge or opportunity
- 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>
<action>Listen for:
- Type of project (app, website, feature, page)
- Target platform (web, mobile, both)
- Key functionality or purpose
</action>
</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>
<action>Listen for:
- Pain points being addressed
- Market opportunity
- User needs not being met
- Business drivers
</action>
</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>
<action>Listen for:
- Functional goals (what it should do)
- Experience goals (how it should feel)
- Business goals (what outcomes matter)
</action>
</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>
<action>Note:
- Technical constraints
- Timeline/deadline
- Budget considerations
- Brand/style requirements
- Integration requirements
</action>
</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`
You now have enough context to move forward. When you're ready:
- **Next phase:** Check your workflow status for what's next
- **Need more depth?** You can always expand this into a Complete brief later
@ -118,4 +124,3 @@ Happy designing! 🎨</output>
</step>
</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
web_bundle: true
---
# WDS Phase 1: Project Brief
name: project-brief
author: "Whiteport Design Studio"
@ -42,4 +41,3 @@ primary_agent: "saga-analyst"
standalone: true
web_bundle: false

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

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

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

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

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

@ -55,4 +55,3 @@ primary_agent: "saga-analyst"
standalone: true
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** 🎯
We'll define what success looks like at two levels:
- **Vision** - The inspiring, aspirational goal (not easily quantified)
- **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?
Examples:
- "Be the most trusted platform for dog owners in Sweden"
- "The go-to tool for indie designers"
- "Make project management actually enjoyable"</ask>
@ -39,6 +41,7 @@ Examples:
<ask>**How would you measure progress toward this vision?**
Think about:
- User metrics (adoption, engagement, retention)
- Business metrics (revenue, growth, market share)
- Quality metrics (satisfaction, referrals, reviews)
@ -46,12 +49,13 @@ Think about:
What numbers would make you confident you're on track?</ask>
<action>For each metric mentioned, help make it SMART:
- **S**pecific - What exactly?
- **M**easurable - What number?
- **A**chievable - Is this realistic?
- **R**elevant - Does this connect to the vision?
- **T**ime-bound - By when?
</action>
</action>
<action>Aim for 3-5 clear objectives</action>
</step>
@ -62,6 +66,7 @@ What numbers would make you confident you're on track?</ask>
<action>For each objective, walk through:
Example transformation:
- Vague: "Get influential users"
- SMART: "Onboard 10 verified dog trainers with 1000+ followers by Q4 2026"
@ -71,10 +76,11 @@ Present each refined objective for confirmation.</action>
{{#each objectives}}
**Objective {{@index + 1}}:** {{this.statement}}
- Metric: {{this.metric}}
- Target: {{this.target}}
- Timeline: {{this.timeline}}
{{/each}}
{{/each}}
Do these capture what success looks like? Any adjustments?</ask>
@ -98,4 +104,3 @@ This gives us clear targets to work toward. Next, we'll identify who can help yo
</step>
</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.
We'll create:
- A list of user groups
- Rich descriptions (personas)
- Understanding of their context</output>
</intro>
</intro>
<step n="1" goal="Identify user groups">
<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?**
Consider:
- Who has the most influence on your objectives?
- Who, if delighted, would drive the others?
- Where is the biggest opportunity?</ask>
@ -92,8 +94,9 @@ Consider:
**Your Target Groups:**
{{#each personas}}
- **{{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>
@ -101,4 +104,3 @@ These are the people we're designing for. Next, we'll explore what drives them -
</step>
</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:
**Positive Drivers** (toward motivation):
- Aspirations and dreams
- Desired outcomes
- Experiences they seek
- Status or recognition goals
**Negative Drivers** (away-from motivation):
- Fears and anxieties
- Problems they want gone
- 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?
Think about:
- What would make their day better?
- What would they brag about to colleagues?
- What would make them feel successful?</ask>
@ -52,6 +55,7 @@ Think about:
What does {{persona.name}} want to avoid or escape?
Think about:
- What keeps them up at night?
- What frustrations are they tired of?
- What risks worry them?
@ -63,13 +67,15 @@ Think about:
✅ **Positive Drivers:**
{{#each positive_drivers}}
- {{this}}
{{/each}}
{{/each}}
⚠️ **Negative Drivers:**
{{#each negative_drivers}}
- {{this}}
{{/each}}</output>
{{/each}}</output>
<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>
<action>Analyze for:
- Common drivers across groups
- Unique drivers per group
- Potential conflicts between groups
</action>
</action>
<output>**Cross-Group Patterns:**
@ -110,9 +117,10 @@ We've mapped the psychological landscape:
{{#each personas}}
**{{this.name}}:**
- Wants: {{this.top_positive_driver}}
- Avoids: {{this.top_negative_driver}}
{{/each}}
{{/each}}
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>
</workshop>

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

@ -8,6 +8,7 @@
<output>**Workshop 4: Prioritization** 🎯
Now we make the hard choices. We'll prioritize:
1. Business goals (visions)
2. Objectives under each goal
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:
{{#each visions}}
- {{this}}
{{/each}}</output>
{{/each}}</output>
<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:**
{{#each prioritized_visions}}
{{@index + 1}}. **{{this.vision}}**
*Why:* {{this.reasoning}}
_Why:_ {{this.reasoning}}
{{/each}}</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:
{{#each top_vision_objectives}}
- {{this.statement}}
{{/each}}</output>
{{/each}}</output>
<ask>**Which objective is most important to achieve first?**
@ -74,7 +77,7 @@ What's your reasoning?</ask>
<output>**Objective Priority for "{{top_vision}}":**
{{#each prioritized_objectives}}
{{@index + 1}}. {{this.statement}}
*Why:* {{this.reasoning}}
_Why:_ {{this.reasoning}}
{{/each}}</output>
<template-output>prioritized_objectives</template-output>
@ -85,8 +88,9 @@ What's your reasoning?</ask>
Your target groups:
{{#each personas}}
- {{this.name}}
{{/each}}
{{/each}}
Looking at your top objective: "{{top_objective}}"</output>
@ -105,7 +109,7 @@ What's the logic?</ask>
<output>**Your Target Group Priority:**
{{#each prioritized_groups}}
{{@index + 1}}. **{{this.name}}**
*Why:* {{this.reasoning}}
_Why:_ {{this.reasoning}}
{{/each}}</output>
<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:
✅ Positive:
{{#each current_group.positive_drivers}}
- {{this}}
{{/each}}
{{/each}}
⚠️ Negative:
{{#each current_group.negative_drivers}}
- {{this}}
{{/each}}
{{/each}}
**Rank the top 3-5 drivers** this group cares most about.
@ -158,18 +164,21 @@ Remember: negative drivers often have more weight (loss aversion).</ask>
**Must Address:**
{{#each must_address_drivers}}
- {{this}}
{{/each}}
{{/each}}
**Should Address:**
{{#each should_address_drivers}}
- {{this}}
{{/each}}
{{/each}}
**Could Address (if time permits):**
{{#each could_address_drivers}}
- {{this}}
{{/each}}</output>
{{/each}}</output>
<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!** ✅
**Your Strategic Focus:**
- Design primarily for **{{top_group.name}}**
- Address: {{top_drivers_summary}}
@ -191,4 +201,3 @@ Next, we'll analyze which features best serve these priorities.</output>
</step>
</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.
For each feature, we'll assess impact on each persona using a simple scale:
- **High** = Addresses major need or fear
- **Medium** = Helpful but not critical
- **Low** = Minimal impact
This creates a scored, prioritized feature list that guides:
- **Phase 4: UX Design** - Which scenarios to design first
- **Phase 6: PRD/Development** - Epic and story prioritization
@ -43,6 +45,7 @@ Skip foundational features (auth, profiles, basic CRUD).
<output>I'm creating your Feature Impact Analysis document.
**Scoring:**
- **Primary Persona:** High = 5 pts | Medium = 3 pts | Low = 1 pt
- **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>Calculate score:
- Primary: High=5, Medium=3, Low=1
- Others: High=3, Medium=1, Low=0
</action>
</action>
<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>Calculate dynamic thresholds based on persona count:
- max_possible = 5 (primary high) + 3 × (other_persona_count)
- must_have_threshold = Features with Primary High (5) OR score ≥ (max_possible - 3)
- consider_threshold = mid-range scores
- defer_threshold = low scores
</action>
</action>
<action>Apply decisions:
- **Must Have:** Primary scored High (5 pts) OR score in top tier
- **Consider:** Medium-range scores, might serve strategic needs
- **Defer:** Low scores, minimal strategic value
</action>
</action>
<output>**Scoring complete!** Here's your prioritized feature list:
@ -108,6 +114,7 @@ How does this impact each persona?</output>
{{/each}}
**Scoring context:**
- Max possible score with {{persona_count}} personas: {{max_possible}}
- Top tier (Must Have): {{must_have_threshold}}+
- Primary critical (Must Have): Features with Primary High (5)
@ -131,6 +138,7 @@ Do NOT include analysis section - keep it clean.
**Saved to:** `B-Trigger-Map/00-feature-impact-analysis.md`
This is your **Design Brief** - it tells the designer:
- **What to design first** - Top-scoring features = priority scenarios
- **Prominence in UI** - High scores = prominent placement
- **Who to optimize for** - Which persona's needs matter most
@ -138,6 +146,7 @@ This is your **Design Brief** - it tells the designer:
**Trigger Mapping Complete!** 🎉
You now have:
- Clear business priorities
- Defined target personas with drivers
- Strategically ranked features

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

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

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

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

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

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

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

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
web_bundle: true
---
# WDS Phase 3: PRD Platform (Technical Foundation)
name: "Phase 3: PRD Platform (Technical Foundation)"
agent: "Freyja the PM"
@ -37,4 +36,3 @@ optional_inputs:
- "Existing technical constraints"
estimated_duration: "2-4 hours (plus PoC development time)"

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

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

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

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

10
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.**
This creates:
- ✅ Consistent user experience
- ✅ Natural design system patterns
- ✅ Faster specification process
@ -25,7 +26,7 @@ This creates:
```
Start Page Analysis:
├─ Body Text: Thin lines, icon-sized spacing → 16px Regular
├─ Button Labels: Medium lines → 16px Semibold
├─ Button Labels: Medium lines → 16px Semibold
├─ Page Title: Thick lines, button-height spacing → 48px Bold
├─ Navigation: Medium lines, small spacing → 14px Medium
└─ Caption: Thinnest lines, half-icon spacing → 12px Regular
@ -40,12 +41,14 @@ Start Page Analysis:
**When analyzing the About Page sketch:**
#### Step 1: Check Previous Pages
```
Agent: "I see you've already analyzed the Start Page.
Agent: "I see you've already analyzed the Start Page.
I'll use those text styles as reference points."
```
#### Step 2: Match Visual Patterns
```
About Page body text:
- Thin lines ✓
@ -57,6 +60,7 @@ About Page body text:
```
#### Step 3: Confirm with Designer
```
Agent: "This body text looks identical to Start Page body text.
Should I use the same specification (16px Regular)?"
@ -125,11 +129,13 @@ Components Identified:
### Benefits
**Without explicit design system:**
- Maintains consistency through pattern recognition
- Reduces specification time (reference previous pages)
- Creates professional, cohesive experience
**With explicit design system:**
- Automatically maps to existing components
- Validates sketch against design system
- Suggests design system updates when new patterns emerge

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

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