diff --git a/CHANGELOG.md b/CHANGELOG.md index 80e14e90..fb966a1b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ **See detailed log:** [conversion-logs/session-2025-12-09-micro-steps-concepts.md](./conversion-logs/session-2025-12-09-micro-steps-concepts.md) **Summary:** + - ✅ Phase 6: Design Deliveries (7 micro-step files) - ✅ Phase 7: Testing (8 micro-step files) - ✅ Phase 8: Ongoing Development (9 micro-step files) diff --git a/CONCEPTS-INTEGRATION.md b/CONCEPTS-INTEGRATION.md index bce5199a..33f878ef 100644 --- a/CONCEPTS-INTEGRATION.md +++ b/CONCEPTS-INTEGRATION.md @@ -7,9 +7,11 @@ ## Core Documentation ### Glossary (Complete Reference) + **File:** `src/core/resources/wds/glossary.md` **Contains:** + - ✅ Greenfield Development (definition, origin, examples) - ✅ Brownfield Development (definition, origin, examples) - ✅ Kaizen (改善) - Continuous Improvement (definition, philosophy, examples) @@ -26,9 +28,11 @@ ## Workflow Documentation ### 1. Project Type Selection + **File:** `src/modules/wds/workflows/workflow-init/project-type-selection.md` **Concepts integrated:** + - ✅ **Greenfield Development** - New Product entry point - ✅ **Brownfield Development** - Existing Product entry point - ✅ Definitions and origins @@ -38,6 +42,7 @@ **Section:** "Software Development Terminology" **Usage:** + ``` Which type of project are you working on? @@ -48,9 +53,11 @@ Which type of project are you working on? --- ### 2. Phase 8 Workflow + **File:** `src/modules/wds/workflows/8-ongoing-development/workflow.md` **Concepts integrated:** + - ✅ **Kaizen (改善)** - Continuous Improvement (detailed) - ✅ **Kaikaku (改革)** - Revolutionary Change (detailed) - ✅ When to use each approach @@ -60,6 +67,7 @@ Which type of project are you working on? **Section:** "Lean Manufacturing Philosophy" **Key insight:** + ``` Kaikaku (改革): Build product v1.0 (Phases 1-7) ↓ @@ -73,9 +81,11 @@ Kaizen cycle 1, 2, 3, 4, 5... (ongoing) --- ### 3. Existing Product Guide + **File:** `src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md` **Concepts integrated:** + - ✅ **Brownfield + Kaizen** - Phase 8 approach - ✅ **Greenfield + Kaikaku** - Phases 1-7 approach - ✅ Terminology explanations @@ -88,9 +98,11 @@ Kaizen cycle 1, 2, 3, 4, 5... (ongoing) --- ### 4. Phase 8 Step 8.8 (Iterate) + **File:** `src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md` **Concepts integrated:** + - ✅ **Kaizen vs Kaikaku** comparison - ✅ Quick reference for designers - ✅ Link to glossary @@ -105,9 +117,11 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai ## Concept Usage by WDS Phase ### Phases 1-7: New Product Development + **Approach:** Greenfield + Kaikaku **Characteristics:** + - Starting from scratch - Complete user flows - Revolutionary change @@ -115,15 +129,18 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai - Months of work **Concepts:** + - Greenfield Development - Kaikaku (改革) - Revolutionary Change --- ### Phase 8: Ongoing Development + **Approach:** Brownfield + Kaizen **Characteristics:** + - Existing product - Incremental improvements - Continuous improvement @@ -131,6 +148,7 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai - 1-2 week cycles **Concepts:** + - Brownfield Development - Kaizen (改善) - Continuous Improvement - Muda (無駄) - Waste elimination @@ -162,18 +180,20 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai **Question:** "Should I do small improvements or big redesign?" **Small Improvements (Kaizen 改善):** + - ✅ Product is working - ✅ Want low-risk changes - ✅ 1-2 week cycles - ✅ Continuous learning -→ Stay in Phase 8, create System Updates + → Stay in Phase 8, create System Updates **Big Redesign (Kaikaku 改革):** + - ✅ Product needs overhaul - ✅ Fundamental problems - ✅ Months of work - ✅ Revolutionary change -→ Return to Phases 1-7, create Design Deliveries + → Return to Phases 1-7, create Design Deliveries --- @@ -182,16 +202,16 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai ``` 1. Glossary (src/core/resources/wds/glossary.md) └─ Complete definitions and philosophy - + 2. Project Type Selection (workflows/workflow-init/project-type-selection.md) └─ Greenfield vs Brownfield choice - + 3. Phase 8 Workflow (workflows/8-ongoing-development/workflow.md) └─ Kaizen vs Kaikaku philosophy - + 4. Existing Product Guide (workflows/8-ongoing-development/existing-product-guide.md) └─ Brownfield + Kaizen approach - + 5. Step 8.8 (workflows/8-ongoing-development/steps/step-8.8-iterate.md) └─ Quick reference during iteration ``` @@ -227,18 +247,21 @@ Reminds designers they're in Kaizen mode (small, continuous improvements) vs Kai ## Key Takeaways **For Designers:** + 1. Understand if you're in Greenfield or Brownfield context 2. Choose Kaikaku (revolutionary) or Kaizen (continuous) approach 3. Use appropriate deliverables (DD-XXX vs SU-XXX) 4. Follow appropriate workflow (Phases 1-7 vs Phase 8) **For Documentation:** + 1. Glossary is the source of truth 2. Concepts are integrated where relevant 3. Quick references in workflow steps 4. Consistent terminology throughout **Philosophy:** + - Kaikaku to establish, Kaizen to improve - Greenfield gives freedom, Brownfield gives context - Small improvements compound over time diff --git a/README.md b/README.md index db16ad19..28499070 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,7 @@ docs/ ``` **Why alphabetical?** The `A-B-C-D-E` prefix creates a clear visual namespace that: + - Groups WDS artifacts together in file explorers - Distinguishes from other project documentation - Provides natural sort order matching workflow progression @@ -90,16 +91,16 @@ docs/ WDS provides **8 design phases** that can be selected based on project scale: -| Phase | Name | Output Folder | Description | -|-------|------|---------------|-------------| -| 1️⃣ | **Product Exploration** | `A-Product-Brief/` | Vision, positioning, ICP framework | -| 2️⃣ | **Trigger Mapping** | `B-Trigger-Map/` | Personas, business goals, Feature Impact Analysis | -| 3️⃣ | **PRD Platform** | `C-Platform-Requirements/` | Technical foundation (parallel with Phase 4) | -| 4️⃣ | **UX Design** | `C-Scenarios/` | User scenarios, sketches, specifications | -| 5️⃣ | **Design System** | `D-Design-System/` | Design tokens, component library (optional) | -| 6️⃣ | **PRD & Design Deliveries** | `E-PRD/` | Complete PRD + packaged flows for BMM | -| 7️⃣ | **Testing** | `F-Testing/` | Designer validation of implementation | -| 8️⃣ | **Product Development** | `G-Product-Development/` | Ongoing improvements (existing products) | +| Phase | Name | Output Folder | Description | +| ----- | --------------------------- | -------------------------- | ------------------------------------------------- | +| 1️⃣ | **Product Exploration** | `A-Product-Brief/` | Vision, positioning, ICP framework | +| 2️⃣ | **Trigger Mapping** | `B-Trigger-Map/` | Personas, business goals, Feature Impact Analysis | +| 3️⃣ | **PRD Platform** | `C-Platform-Requirements/` | Technical foundation (parallel with Phase 4) | +| 4️⃣ | **UX Design** | `C-Scenarios/` | User scenarios, sketches, specifications | +| 5️⃣ | **Design System** | `D-Design-System/` | Design tokens, component library (optional) | +| 6️⃣ | **PRD & Design Deliveries** | `E-PRD/` | Complete PRD + packaged flows for BMM | +| 7️⃣ | **Testing** | `F-Testing/` | Designer validation of implementation | +| 8️⃣ | **Product Development** | `G-Product-Development/` | Ongoing improvements (existing products) | ### Phase-Selectable Workflow @@ -116,11 +117,11 @@ Unlike rigid tracks, WDS allows users to **select individual phases** based on p WDS introduces **3 specialized design agents** named after Norse mythology: -| Agent | Role | Norse Meaning | -|-------|------|---------------| -| **Saga the WDS Analyst** | Business & Product Analyst | Goddess of stories & wisdom - uncovers your business story | -| **Idunn the WDS PM** | Product Manager | Goddess of renewal & youth - keeps projects vital and thriving | -| **Freyja the WDS Designer** | UX/UI Designer | Goddess of beauty, magic & strategy - creates experiences users love | +| Agent | Role | Norse Meaning | +| --------------------------- | -------------------------- | -------------------------------------------------------------------- | +| **Saga the WDS Analyst** | Business & Product Analyst | Goddess of stories & wisdom - uncovers your business story | +| **Idunn the WDS PM** | Product Manager | Goddess of renewal & youth - keeps projects vital and thriving | +| **Freyja the WDS Designer** | UX/UI Designer | Goddess of beauty, magic & strategy - creates experiences users love | --- @@ -140,6 +141,7 @@ E-PRD/ ──────────────► PRD + Design ``` The `E-PRD/` folder serves as the **integration bridge**, containing: + - Complete PRD (00-PRD.md) with functional requirements - Design Deliveries (DD-XXX.yaml) - packaged flows for BMM handoff - Scenario-to-epic mapping @@ -173,6 +175,7 @@ bmad install wds ### What Gets Installed The WDS installer creates: + - ✅ `docs/` directory structure with alphabetized folders (A-G) - ✅ All 8 phase folders ready for your design work - ✅ `.gitkeep` files to preserve empty directories @@ -251,6 +254,7 @@ git push origin main ## 📚 Original BMad Method Documentation For complete BMad Method documentation, see: + - **[BMad Method README](https://github.com/bmad-code-org/BMAD-METHOD)** - Main documentation - **[BMM Module Docs](./src/modules/bmm/docs/README.md)** - Development workflows - **[Agent Customization](./docs/agent-customization-guide.md)** - Customize agents diff --git a/WDS-V6-CONVERSION-ROADMAP.md b/WDS-V6-CONVERSION-ROADMAP.md index 0c41e928..dd15fb63 100644 --- a/WDS-V6-CONVERSION-ROADMAP.md +++ b/WDS-V6-CONVERSION-ROADMAP.md @@ -59,6 +59,7 @@ WDS (Design) ────────► E-UI-Roadmap/ ──────── **Decision:** Whiteport Design Studio (WDS) **Alternatives Considered:** + - BMad Design Studio - BMad UX @@ -69,16 +70,19 @@ WDS (Design) ────────► E-UI-Roadmap/ ──────── **Decision:** Fork BMad-METHOD repository **Alternatives Considered:** + - Standalone repository - Rename existing WPS2C repo **Reasoning:** + - Maximum adoption through BMad ecosystem - Path to official module status via PR - Shared core infrastructure - Automatic ecosystem integration **Fork Details:** + - Origin: `https://github.com/whiteport-collective/whiteport-design-studio.git` - Upstream: `https://github.com/bmad-code-org/BMAD-METHOD.git` @@ -87,6 +91,7 @@ WDS (Design) ────────► E-UI-Roadmap/ ──────── **Decision:** Work directly on `main` branch **Reasoning:** + - Simpler workflow during development - WDS is substantial addition, not small tweak - Fork effectively becomes WDS home @@ -99,6 +104,7 @@ WDS (Design) ────────► E-UI-Roadmap/ ──────── **Description:** Users select individual phases based on project needs rather than choosing from predefined tracks. **Examples:** + - Landing page → Phases 1, 4, 5 - Full product → All 6 phases - Design system only → Phases 4, 5 @@ -116,6 +122,7 @@ WDS (Design) ────────► E-UI-Roadmap/ ──────── **Convention:** Only `README.md` at module root; all other documentation uses `xxx-guide.md` naming pattern. **Examples:** + - ✅ `wds/README.md` (only one) - ✅ `wds/docs/method/wds-method-guide.md` - ✅ `wds/docs/quick-start-guide.md` @@ -205,13 +212,14 @@ src/modules/wds/ ### 4.3 Agents - The Norse Pantheon 🏔️ -| Agent | File | Role | Norse Meaning | Status | -|-------|------|------|---------------|--------| -| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom | ✅ **COMPLETE (Dec 9)** | -| **Idunn the PM** | `idunn-pm.agent.yaml` | Product Manager | Goddess of renewal & youth | ✅ **COMPLETE (Dec 9)** | -| **Freyja the Designer** | `freyja-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy | ✅ **COMPLETE (Dec 9)** | +| Agent | File | Role | Norse Meaning | Status | +| ----------------------- | ------------------------- | -------------------------- | ----------------------------------- | ----------------------- | +| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom | ✅ **COMPLETE (Dec 9)** | +| **Idunn the PM** | `idunn-pm.agent.yaml` | Product Manager | Goddess of renewal & youth | ✅ **COMPLETE (Dec 9)** | +| **Freyja the Designer** | `freyja-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy | ✅ **COMPLETE (Dec 9)** | **Why "Name the Function" format?** + - Reads naturally: "Saga the Analyst" - Distinctive Norse mythology names - Function is immediately clear @@ -237,7 +245,8 @@ docs/ └── G-Product-Development/ # Phase 8: Ongoing product development (existing products) ``` -**Note:** +**Note:** + - **C-Platform-Requirements/** and **C-Scenarios/** both use "C" prefix because Phase 3 and 4 run in parallel - **Platform Requirements** (C-Platform-Requirements/) stays separate - technical foundation - **E-PRD/** contains both the PRD and Design Deliveries (DD-XXX.yaml packages for BMM handoff) @@ -246,32 +255,33 @@ docs/ ### 5.2 Why Alphabetical Prefix? -| Reason | Benefit | -|--------|---------| -| Visual namespace | Clearly grouped in file explorers | -| Brand signature | "A-B-C-D-E = WDS" recognition | -| Non-conflicting | Won't clash with other docs folders | -| Natural sort | Always grouped together | -| Professional | Enterprise documentation feel | +| Reason | Benefit | +| ---------------- | ----------------------------------- | +| Visual namespace | Clearly grouped in file explorers | +| Brand signature | "A-B-C-D-E = WDS" recognition | +| Non-conflicting | Won't clash with other docs folders | +| Natural sort | Always grouped together | +| Professional | Enterprise documentation feel | ### 5.3 Phase-to-Folder Mapping -| Phase | # | Name | Output Folder | -|-------|---|------|---------------| -| 1 | Product Exploration | Product Brief | `A-Product-Brief/` | -| 2 | Trigger Mapping | User psychology & business goals | `B-Trigger-Map/` | -| 3 | PRD Platform | Technical foundation (platform only) | `C-Platform-Requirements/` | -| 4 | UX Design | Scenarios, sketches, specifications | `C-Scenarios/` | -| 5 | Design System | Component library (optional, parallel) | `D-Design-System/` | -| 6 | PRD & Design Deliveries | PRD + packaged flows for BMM handoff | `E-PRD/` | -| 7 | Testing | Designer validation of implementation | `F-Testing/` | -| 8 | Product Development | Ongoing improvements (existing products) | `G-Product-Development/` | +| Phase | # | Name | Output Folder | +| ----- | ----------------------- | ---------------------------------------- | -------------------------- | +| 1 | Product Exploration | Product Brief | `A-Product-Brief/` | +| 2 | Trigger Mapping | User psychology & business goals | `B-Trigger-Map/` | +| 3 | PRD Platform | Technical foundation (platform only) | `C-Platform-Requirements/` | +| 4 | UX Design | Scenarios, sketches, specifications | `C-Scenarios/` | +| 5 | Design System | Component library (optional, parallel) | `D-Design-System/` | +| 6 | PRD & Design Deliveries | PRD + packaged flows for BMM handoff | `E-PRD/` | +| 7 | Testing | Designer validation of implementation | `F-Testing/` | +| 8 | Product Development | Ongoing improvements (existing products) | `G-Product-Development/` | ### 5.4 E-PRD Structure (PRD + Design Deliveries) **E-PRD/ contains both the PRD and Design Deliveries:** **Phase 3: Platform Requirements (Technical Foundation)** + ``` C-Platform-Requirements/ ├── 00-Platform-Overview.md # Platform summary @@ -281,9 +291,11 @@ C-Platform-Requirements/ ├── 04-Security-Framework.md # Auth, authorization, data protection └── 05-Technical-Constraints.md # What design needs to know ``` + **Purpose:** Technical foundation created by WDS. Referenced by PRD but kept separate. **Phase 6: E-PRD (PRD + Design Deliveries)** + ``` E-PRD/ ├── 00-PRD.md # Main PRD document @@ -300,6 +312,7 @@ E-PRD/ ``` **Each Design Delivery (DD-XXX.yaml) contains:** + - Flow metadata (name, epic, priority) - Scenario references (which pages in C-Scenarios/) - Component references (which components in D-Design-System/) @@ -324,20 +337,24 @@ E-PRD/ **Reasoning:** User experience shows that harsh enforcement language makes agents MORE likely to ignore instructions, not less. **Example - Before:** + ```markdown ## MANDATORY RULES + - 🛑 NEVER generate without input - 🚫 FORBIDDEN: Multiple questions - ❌ SYSTEM FAILURE if you skip ``` **Example - After:** + ```markdown ## How We Work Together You're a thoughtful guide who helps designers create great products. Your rhythm: + - Ask one question, then listen - Reflect back what you heard - Build the document together @@ -352,6 +369,7 @@ Your rhythm: **Reasoning:** People (and LLMs) learn better from examples than abstract rules. **Implementation:** + - Complete artifacts as examples (not rule descriptions) - Conversation flow examples - Dog Week as reference implementation @@ -359,23 +377,25 @@ Your rhythm: #### Principle 3: Example Projects for Adoption **Purpose:** + - Let people try before adopting - Show what success looks like - Lower barrier to entry - Build credibility **Implementation:** + - Dog Week patterns as full reference - Starter project for practice - Conversation examples showing dialog flow ### 6.2 Known Problems to Mitigate -| Problem | Observed Behavior | WDS Solution | -|---------|-------------------|--------------| -| Agents ignore instructions | Generate without thinking | Identity-based personas + examples | -| Inconsistent output formats | Specs look different each time | Complete template examples | -| Question dumping | 20 questions at once | Conversation examples showing one-at-a-time | +| Problem | Observed Behavior | WDS Solution | +| --------------------------- | ------------------------------ | ------------------------------------------- | +| Agents ignore instructions | Generate without thinking | Identity-based personas + examples | +| Inconsistent output formats | Specs look different each time | Complete template examples | +| Question dumping | 20 questions at once | Conversation examples showing one-at-a-time | ### 6.3 Positive Language Guidelines @@ -383,21 +403,22 @@ Your rhythm: **Patterns to Avoid:** -| Negative Pattern | Positive Alternative | -|------------------|---------------------| -| "Nothing kills a project faster than..." | "It's valuable to discover early..." | -| "expensive development problems" | "easy to address while solutions are flexible" | -| "Finding them later is expensive" | "Finding them now means more options" | -| "Don't do X" | "What works well is Y" | -| "Avoid these mistakes" | "Successful patterns include..." | -| "This prevents failure" | "This enables success" | -| "You'll waste time if..." | "You'll save time by..." | +| Negative Pattern | Positive Alternative | +| ---------------------------------------- | ---------------------------------------------- | +| "Nothing kills a project faster than..." | "It's valuable to discover early..." | +| "expensive development problems" | "easy to address while solutions are flexible" | +| "Finding them later is expensive" | "Finding them now means more options" | +| "Don't do X" | "What works well is Y" | +| "Avoid these mistakes" | "Successful patterns include..." | +| "This prevents failure" | "This enables success" | +| "You'll waste time if..." | "You'll save time by..." | **The Reframe Test:** -When writing guidance, ask: *"Am I describing what TO DO or what NOT to do?"* +When writing guidance, ask: _"Am I describing what TO DO or what NOT to do?"_ Good WDS documentation: + - Celebrates early discovery (not fears late discovery) - Describes successful patterns (not failure modes) - Frames constraints as opportunities (not limitations) @@ -406,29 +427,34 @@ Good WDS documentation: **Example Transformation:** Before: + > "Nothing kills a project faster than discovering in development that a core feature is technically impossible." After: + > "It's a great morale boost when you've proven your core features will work. And if you discover limitations, it's valuable to know them early so design can account for them from the start." ### 6.4 Instruction Style **Identity-First:** + ```markdown ## Who You Are -You're Saga, a thoughtful analyst who genuinely cares +You're Saga, a thoughtful analyst who genuinely cares about understanding the product before documenting it. -You prefer deep conversations over quick surveys. You ask one +You prefer deep conversations over quick surveys. You ask one thing at a time because you're actually listening. ``` **Experience-Focused:** + ```markdown ## The Conversation Style A good session feels like coffee with a wise mentor: + - They ask something interesting - You share your thinking - They reflect it back @@ -436,14 +462,17 @@ A good session feels like coffee with a wise mentor: ``` **Gentle Reminders:** + ```markdown ## Helpful Patterns What works well: + - One question at a time keeps things focused - Reflecting back shows you're listening What tends to feel less collaborative: + - Listing many questions (feels like a survey) - Generating without checking in ``` @@ -455,46 +484,54 @@ What tends to feel less collaborative: ### Complete Phase Structure **Phase 1: Product Exploration** + - **Output Folder:** `A-Product-Brief/` - **Deliverable:** Product Brief with vision, positioning, ICP, success criteria - **Agent:** Saga WDS Analyst **Phase 2: Trigger Mapping** + - **Output Folder:** `B-Trigger-Map/` - **Deliverable:** Trigger Map with business goals, personas, usage goals, Feature Impact Analysis - **Agent:** Saga WDS Analyst **Phase 3: PRD Platform** + - **Output Folder:** `C-Platform-Requirements/` - **Deliverable:** Technical foundation (platform, architecture, data model, integrations, security) - **Agent:** Freyja WDS PM - **Note:** Runs in parallel with Phase 4 **Phase 4: UX Design** + - **Output Folder:** `C-Scenarios/` - **Deliverable:** Interactive prototypes, scenarios, sketches, specifications with Object IDs - **Agent:** Baldr WDS Designer - **Note:** Runs in parallel with Phase 3 **Phase 5: Design System** + - **Output Folder:** `D-Design-System/` - **Deliverable:** Component library (atoms, molecules, organisms) with design tokens - **Agent:** Baldr WDS Designer - **Note:** Optional, runs in parallel with Phase 4 **Phase 6: PRD & Design Deliveries** + - **Output Folder:** `E-PRD/` - **Deliverable:** Complete PRD (00-PRD.md) + Design Deliveries (DD-XXX.yaml packages) - **Agent:** Freyja WDS PM - **Note:** PRD references C-Platform-Requirements/, organizes functional requirements by epic **Phase 7: Testing** + - **Output Folder:** `F-Testing/` - **Deliverable:** Test scenarios, validation results, issues - **Agent:** Baldr WDS Designer - **Note:** Designer validates BMM implementation **Phase 8: Product Development** + - **Output Folder:** `G-Product-Development/` - **Deliverable:** Ongoing improvements to existing products (Kaizen/Brownfield) - **Agent:** Baldr WDS Designer @@ -503,6 +540,7 @@ What tends to feel less collaborative: ### Key Methodology Features **Feature Impact Analysis (Phase 2):** + - Scoring system for prioritizing features - Positive drivers: +3/+2/+1 by priority - Negative drivers: +4/+3/+2 (higher due to loss aversion) @@ -510,18 +548,21 @@ What tends to feel less collaborative: - Outputs ranked feature list for MVP planning **Platform Requirements (Phase 3):** + - Technical foundation work (platform, infrastructure) - Proofs of concept for risky features - Experimental endpoints that can start before design - Runs in parallel with design work (not sequential) **Design System (Phase 5):** + - Optional - chosen during project setup - Parallel - builds alongside Phase 4, not after - Unified naming for Figma/Code integration - Component library selection guidance **PRD Structure (Phase 6):** + - E-PRD/ contains both PRD document and Design Deliveries subfolder - PRD references C-Platform-Requirements/ (not duplicated) - Design Deliveries (DD-XXX.yaml) package complete flows for BMM handoff @@ -532,12 +573,14 @@ What tends to feel less collaborative: ### 7.1 Chosen Approach: Methodology-First **Order:** + 1. Define the methodology (phases, outputs, connections) 2. Create workflows that implement the methodology 3. Create agents that guide users through workflows 4. Create examples that demonstrate the methodology **Reasoning:** + - The methodology IS the product - Agents serve the methodology, not vice versa - User is crystal clear on the workflow (already proven in WPS2C v4) @@ -546,17 +589,19 @@ What tends to feel less collaborative: ### 7.2 Detailed Order #### Phase 1: Define the Methodology -| Order | Component | File | Status | -|-------|-----------|------|--------| -| 1 | Method Overview | `docs/method/wds-method-guide.md` | ✅ COMPLETE | -| 2 | Phase 1 Guide | `docs/method/phase-1-Product-exploration-guide.md` | ✅ COMPLETE | -| 3 | Phase 2 Guide | `docs/method/phase-2-trigger-mapping-guide.md` | ✅ COMPLETE | -| 4 | Phase 3 Guide | `docs/method/phase-3-PRD-Platform-guide.md` | ✅ COMPLETE | -| 5 | Phase 4 Guide | `docs/method/phase-4-ux-design-guide.md` | ✅ COMPLETE | -| 6 | Phase 5 Guide | `docs/method/phase-5-design-system-guide.md` | ✅ COMPLETE | -| 7 | Phase 6 Guide | `docs/method/phase-6-PRD-Finalization-guide.md` | ✅ COMPLETE | + +| Order | Component | File | Status | +| ----- | --------------- | -------------------------------------------------- | ----------- | +| 1 | Method Overview | `docs/method/wds-method-guide.md` | ✅ COMPLETE | +| 2 | Phase 1 Guide | `docs/method/phase-1-Product-exploration-guide.md` | ✅ COMPLETE | +| 3 | Phase 2 Guide | `docs/method/phase-2-trigger-mapping-guide.md` | ✅ COMPLETE | +| 4 | Phase 3 Guide | `docs/method/phase-3-PRD-Platform-guide.md` | ✅ COMPLETE | +| 5 | Phase 4 Guide | `docs/method/phase-4-ux-design-guide.md` | ✅ COMPLETE | +| 6 | Phase 5 Guide | `docs/method/phase-5-design-system-guide.md` | ✅ COMPLETE | +| 7 | Phase 6 Guide | `docs/method/phase-6-PRD-Finalization-guide.md` | ✅ COMPLETE | **Methodology Phase Complete!** All phase guides refined with: + - Positive language throughout (no "expensive problems", "kills projects", etc.) - Phase titles with artifacts in parentheses - Removed duration estimates (project-dependent) @@ -568,16 +613,18 @@ What tends to feel less collaborative: - Code examples moved to templates/examples (not in guides) #### Phase 2: Create Examples -| Order | Component | Location | Status | -|-------|-----------|----------|--------| -| 8 | Dog Week Examples | `examples/dog-week-patterns/` | TO CREATE | -| 9 | Conversation Examples | `examples/conversation-examples/` | TO CREATE | -| 10 | Starter Project | `examples/starter-project/` | TO CREATE | -| 10b | **WDS Trigger Map** | `examples/wds-trigger-map/` | TO CREATE | -| 10c | **Trigger Mapping Workshop** | `workflows/trigger-mapping-workshop/` | TO CREATE | + +| Order | Component | Location | Status | +| ----- | ---------------------------- | ------------------------------------- | --------- | +| 8 | Dog Week Examples | `examples/dog-week-patterns/` | TO CREATE | +| 9 | Conversation Examples | `examples/conversation-examples/` | TO CREATE | +| 10 | Starter Project | `examples/starter-project/` | TO CREATE | +| 10b | **WDS Trigger Map** | `examples/wds-trigger-map/` | TO CREATE | +| 10c | **Trigger Mapping Workshop** | `workflows/trigger-mapping-workshop/` | TO CREATE | **WDS Trigger Map Example:** Create a Trigger Map for WDS itself as a meta-example - shows the methodology applied to the methodology. Includes: + - WDS Vision & SMART Objectives - Target Groups (designers, teams, agencies) - Personas with alliterative names @@ -588,6 +635,7 @@ This serves as both documentation and inspiration for users. **Trigger Mapping Workshop (Standalone):** Create a standalone Trigger Mapping workshop that can be used: + - In WDS as part of Phase 2 - In BMM as a brainstorming/strategic alignment session - In any project needing user-business alignment @@ -595,37 +643,41 @@ Create a standalone Trigger Mapping workshop that can be used: This makes the Trigger Mapping methodology available even in projects not driven by designers. Could be contributed to BMM's brainstorming workflows or CIS (Creative Intelligence Suite). Includes: + - Workshop facilitation workflow - Agent instructions for running the workshop - Template for Trigger Map output - Integration points with BMM workflows #### Phase 3: Create Workflows -| Order | Component | Location | Status | -|-------|-----------|----------|--------| -| 11 | workflow-init | `workflows/workflow-init/` | ✅ COMPLETE | -| 12a | Phase 1 Workflow | `workflows/1-project-brief/` | ✅ COMPLETE | -| 12b | Phase 2 Workflow | `workflows/2-trigger-mapping/` | ✅ COMPLETE | -| 12c | Phase 3 Workflow | `workflows/3-prd-platform/` | ✅ COMPLETE | -| 12d | **Phase 4 Workflow** | `workflows/4-ux-design/` | ✅ **COMPLETE (Dec 4)** | -| 12e | **Phase 5 Workflow** | `workflows/5-design-system/` | ✅ **COMPLETE (Dec 9)** | -| 12f | **Phase 6 Workflow** | `workflows/6-design-deliveries/` | ✅ **COMPLETE** | + +| Order | Component | Location | Status | +| ----- | -------------------- | -------------------------------- | ----------------------- | +| 11 | workflow-init | `workflows/workflow-init/` | ✅ COMPLETE | +| 12a | Phase 1 Workflow | `workflows/1-project-brief/` | ✅ COMPLETE | +| 12b | Phase 2 Workflow | `workflows/2-trigger-mapping/` | ✅ COMPLETE | +| 12c | Phase 3 Workflow | `workflows/3-prd-platform/` | ✅ COMPLETE | +| 12d | **Phase 4 Workflow** | `workflows/4-ux-design/` | ✅ **COMPLETE (Dec 4)** | +| 12e | **Phase 5 Workflow** | `workflows/5-design-system/` | ✅ **COMPLETE (Dec 9)** | +| 12f | **Phase 6 Workflow** | `workflows/6-design-deliveries/` | ✅ **COMPLETE** | #### Phase 4: Create Agents (The Norse Pantheon) -| Order | Component | File | Status | -|-------|-----------|------|--------| -| 13 | **Saga-Analyst** | `agents/saga-analyst.agent.yaml` | ✅ COMPLETE | -| 13b | **Saga Presentation** | `data/presentations/saga-intro.md` | ✅ COMPLETE | -| 14 | **Idunn-PM** | `agents/idunn-pm.agent.yaml` | ✅ COMPLETE | -| 14b | **Idunn Presentation** | `data/presentations/idunn-intro.md` | ✅ COMPLETE | -| 15 | **Freyja-Designer** | `agents/freyja-ux.agent.yaml` | ✅ COMPLETE | -| 15b | **Freyja Presentation** | `data/presentations/freyja-intro.md` | ✅ COMPLETE | + +| Order | Component | File | Status | +| ----- | ----------------------- | ------------------------------------ | ----------- | +| 13 | **Saga-Analyst** | `agents/saga-analyst.agent.yaml` | ✅ COMPLETE | +| 13b | **Saga Presentation** | `data/presentations/saga-intro.md` | ✅ COMPLETE | +| 14 | **Idunn-PM** | `agents/idunn-pm.agent.yaml` | ✅ COMPLETE | +| 14b | **Idunn Presentation** | `data/presentations/idunn-intro.md` | ✅ COMPLETE | +| 15 | **Freyja-Designer** | `agents/freyja-ux.agent.yaml` | ✅ COMPLETE | +| 15b | **Freyja Presentation** | `data/presentations/freyja-intro.md` | ✅ COMPLETE | #### Phase 5: Finalize -| Order | Component | File | Status | -|-------|-----------|------|--------| -| 16 | **Install Config** | `_module-installer/installer.js` | ✅ COMPLETE | -| 17 | **Teams** | `teams/` | ✅ COMPLETE | + +| Order | Component | File | Status | +| ----- | ------------------ | -------------------------------- | ----------- | +| 16 | **Install Config** | `_module-installer/installer.js` | ✅ COMPLETE | +| 17 | **Teams** | `teams/` | ✅ COMPLETE | --- @@ -633,54 +685,54 @@ Includes: ### 8.1 Repository Root -| File | Purpose | Status | -|------|---------|--------| -| `README.md` | Fork overview, WDS contribution explanation | ✅ CREATED | -| `WDS-V6-CONVERSION-ROADMAP.md` | This document | ✅ CREATED | +| File | Purpose | Status | +| ------------------------------ | ------------------------------------------- | ---------- | +| `README.md` | Fork overview, WDS contribution explanation | ✅ CREATED | +| `WDS-V6-CONVERSION-ROADMAP.md` | This document | ✅ CREATED | ### 8.2 Methodology Documentation -| Path | Purpose | Status | -|------|---------|--------| -| `src/modules/wds/docs/method/wds-method-guide.md` | Main methodology overview | ✅ COMPLETE | -| `src/modules/wds/docs/method/phase-1-Product-exploration-guide.md` | Phase 1 guide | ✅ COMPLETE | -| `src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md` | Phase 2 guide | ✅ COMPLETE | -| `src/modules/wds/docs/method/phase-3-PRD-Platform-guide.md` | Phase 3 guide | ✅ COMPLETE | -| `src/modules/wds/docs/method/phase-4-ux-design-guide.md` | Phase 4 guide | ✅ COMPLETE | -| `src/modules/wds/docs/method/phase-5-design-system-guide.md` | Phase 5 guide | ✅ COMPLETE | -| `src/modules/wds/docs/method/phase-6-PRD-Finalization-guide.md` | Phase 6 guide | ✅ COMPLETE | +| Path | Purpose | Status | +| ------------------------------------------------------------------ | ------------------------- | ----------- | +| `src/modules/wds/docs/method/wds-method-guide.md` | Main methodology overview | ✅ COMPLETE | +| `src/modules/wds/docs/method/phase-1-Product-exploration-guide.md` | Phase 1 guide | ✅ COMPLETE | +| `src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md` | Phase 2 guide | ✅ COMPLETE | +| `src/modules/wds/docs/method/phase-3-PRD-Platform-guide.md` | Phase 3 guide | ✅ COMPLETE | +| `src/modules/wds/docs/method/phase-4-ux-design-guide.md` | Phase 4 guide | ✅ COMPLETE | +| `src/modules/wds/docs/method/phase-5-design-system-guide.md` | Phase 5 guide | ✅ COMPLETE | +| `src/modules/wds/docs/method/phase-6-PRD-Finalization-guide.md` | Phase 6 guide | ✅ COMPLETE | ### 8.3 Module Structure (Folders Created, Content Pending) -| Path | Purpose | Status | -|------|---------|--------| -| `src/modules/wds/` | Module root | ✅ CREATED | -| `src/modules/wds/README.md` | Module entry point | ✅ CREATED | -| `src/modules/wds/_module-installer/` | Install config folder | EMPTY | -| `src/modules/wds/agents/` | Agents folder | PARTIAL (saga skeleton) | -| `src/modules/wds/workflows/` | Workflows folder | ✅ **PHASE 5 COMPLETE** | -| `src/modules/wds/workflows/workflow-init/` | Workflow initialization | ✅ COMPLETE | -| `src/modules/wds/workflows/1-project-brief/` | Phase 1 workflow | ✅ COMPLETE | -| `src/modules/wds/workflows/2-trigger-mapping/` | Phase 2 workflow | ✅ COMPLETE | -| `src/modules/wds/workflows/3-prd-platform/` | Phase 3 workflow | ✅ COMPLETE | -| `src/modules/wds/workflows/4-ux-design/` | **Phase 4 workflow** | ✅ **COMPLETE (Dec 4)** | -| `src/modules/wds/workflows/4-ux-design/substeps/` | **Phase 4 substeps (4A-4E)** | ✅ **COMPLETE (Dec 4)** | -| `src/modules/wds/workflows/5-design-system/` | **Phase 5 workflow** | ✅ **COMPLETE (Dec 9)** | +| Path | Purpose | Status | +| ------------------------------------------------------- | --------------------------------------- | ----------------------- | +| `src/modules/wds/` | Module root | ✅ CREATED | +| `src/modules/wds/README.md` | Module entry point | ✅ CREATED | +| `src/modules/wds/_module-installer/` | Install config folder | EMPTY | +| `src/modules/wds/agents/` | Agents folder | PARTIAL (saga skeleton) | +| `src/modules/wds/workflows/` | Workflows folder | ✅ **PHASE 5 COMPLETE** | +| `src/modules/wds/workflows/workflow-init/` | Workflow initialization | ✅ COMPLETE | +| `src/modules/wds/workflows/1-project-brief/` | Phase 1 workflow | ✅ COMPLETE | +| `src/modules/wds/workflows/2-trigger-mapping/` | Phase 2 workflow | ✅ COMPLETE | +| `src/modules/wds/workflows/3-prd-platform/` | Phase 3 workflow | ✅ COMPLETE | +| `src/modules/wds/workflows/4-ux-design/` | **Phase 4 workflow** | ✅ **COMPLETE (Dec 4)** | +| `src/modules/wds/workflows/4-ux-design/substeps/` | **Phase 4 substeps (4A-4E)** | ✅ **COMPLETE (Dec 4)** | +| `src/modules/wds/workflows/5-design-system/` | **Phase 5 workflow** | ✅ **COMPLETE (Dec 9)** | | `src/modules/wds/workflows/5-design-system/assessment/` | **Opportunity/Risk micro-instructions** | ✅ **COMPLETE (Dec 9)** | -| `src/modules/wds/workflows/5-design-system/operations/` | **Design system operations** | ✅ **COMPLETE (Dec 9)** | -| `src/modules/wds/workflows/4-ux-design/templates/` | **Phase 4 templates** | ✅ **COMPLETE (Dec 4)** | -| `src/modules/wds/workflows/5-design-system/` | Phase 5 workflow | TO CREATE | -| `src/modules/wds/workflows/6-integration/` | Phase 6 workflow | TO CREATE | -| `src/modules/wds/data/` | Data folder | EMPTY | -| `src/modules/wds/data/presentations/` | Agent presentations | TO CREATE | -| `src/modules/wds/docs/method/` | Methodology guides | ✅ COMPLETE | -| `src/modules/wds/docs/images/` | Images folder | EMPTY | -| `src/modules/wds/examples/` | Examples folder | EMPTY | -| `src/modules/wds/examples/dog-week-patterns/` | Dog Week examples | TO CREATE | -| `src/modules/wds/reference/` | Reference materials | EMPTY | -| `src/modules/wds/reference/templates/` | Templates | TO CREATE | -| `src/modules/wds/reference/checklists/` | Checklists | TO CREATE | -| `src/modules/wds/teams/` | Team configs | EMPTY | +| `src/modules/wds/workflows/5-design-system/operations/` | **Design system operations** | ✅ **COMPLETE (Dec 9)** | +| `src/modules/wds/workflows/4-ux-design/templates/` | **Phase 4 templates** | ✅ **COMPLETE (Dec 4)** | +| `src/modules/wds/workflows/5-design-system/` | Phase 5 workflow | TO CREATE | +| `src/modules/wds/workflows/6-integration/` | Phase 6 workflow | TO CREATE | +| `src/modules/wds/data/` | Data folder | EMPTY | +| `src/modules/wds/data/presentations/` | Agent presentations | TO CREATE | +| `src/modules/wds/docs/method/` | Methodology guides | ✅ COMPLETE | +| `src/modules/wds/docs/images/` | Images folder | EMPTY | +| `src/modules/wds/examples/` | Examples folder | EMPTY | +| `src/modules/wds/examples/dog-week-patterns/` | Dog Week examples | TO CREATE | +| `src/modules/wds/reference/` | Reference materials | EMPTY | +| `src/modules/wds/reference/templates/` | Templates | TO CREATE | +| `src/modules/wds/reference/checklists/` | Checklists | TO CREATE | +| `src/modules/wds/teams/` | Team configs | EMPTY | --- @@ -708,6 +760,7 @@ Includes: ### Commit Checkpoint **Ready to commit Phase 4 workflow:** + ``` feat(wds): Complete Phase 4 UX Design workflow with v6 best practices @@ -740,11 +793,11 @@ Next: Phase 5 (Design System) and Phase 6 (PRD Finalization) workflows **To resolve during porting Phase 1 & 2:** -| Decision | Options | Resolve When | -|----------|---------|--------------| +| Decision | Options | Resolve When | +| ----------------------------- | -------------------------------------------------------------- | ----------------- | | **ICP/Positioning placement** | Phase 1 as hypothesis → Phase 2 validates, OR fully in Phase 2 | Porting Phase 1-2 | -| **Prioritization Reasoning** | Formal step with output, OR internal thinking process | Porting Phase 2 | -| **Business Goals flow** | Initial in Brief → Refined in Trigger Map, OR single location | Porting Phase 1-2 | +| **Prioritization Reasoning** | Formal step with output, OR internal thinking process | Porting Phase 2 | +| **Business Goals flow** | Initial in Brief → Refined in Trigger Map, OR single location | Porting Phase 1-2 | **Context:** The Trigger Mapping (Effect Mapping) methodology is very strong. The prioritization reasoning step (column-by-column) is specifically valuable for generating product ideas but may not need formal documentation. @@ -755,6 +808,7 @@ Next: Phase 5 (Design System) and Phase 6 (PRD Finalization) workflows To be included in WDS workflows (stored in memory, ID: 11785915): **Positioning Statement Format:** + ``` For (target customer) Who (statement of need or opportunity) @@ -767,6 +821,7 @@ Our product (statement of primary differentiators) ``` **ICP Framework (8 Components):** + 1. My ICP (Who I Serve Best) 2. My Positioning (How I'm Different) 3. The Outcomes I Drive @@ -777,6 +832,7 @@ Our product (statement of primary differentiators) 8. Pricing Anchoring (Cost of Inaction, Bad Hire, % Revenue, Speed) **CTA Elements:** + - Website link - Discovery call link - Newsletter subscription @@ -785,31 +841,31 @@ Our product (statement of primary differentiators) ### 10.2 BMad v6 Resources -| Resource | Location | -|----------|----------| -| BMM Module | `src/modules/bmm/` | -| BMB Builder | `src/modules/bmb/` | -| CIS Module | `src/modules/cis/` | -| Agent Schema | `src/modules/bmb/docs/agents/` | +| Resource | Location | +| ------------- | --------------------------------- | +| BMM Module | `src/modules/bmm/` | +| BMB Builder | `src/modules/bmb/` | +| CIS Module | `src/modules/cis/` | +| Agent Schema | `src/modules/bmb/docs/agents/` | | Workflow Docs | `src/modules/bmb/docs/workflows/` | ### 10.3 Original WPS2C -| Resource | Location | -|----------|----------| -| WPS2C Repo | `C:\dev\whiteport-sketch-to-code-bmad-expansion` | -| Method Overview | `Method/00-Whiteport-Method.md` | -| Agents (v4 format) | `bmad-whiteport-sketch/agents/` | +| Resource | Location | +| ------------------ | ------------------------------------------------ | +| WPS2C Repo | `C:\dev\whiteport-sketch-to-code-bmad-expansion` | +| Method Overview | `Method/00-Whiteport-Method.md` | +| Agents (v4 format) | `bmad-whiteport-sketch/agents/` | ### 10.4 Dog Week Project -| Resource | Location | -|----------|----------| -| Project Root | `C:\dev\dogweek\dogweek-dev` | -| Product Brief | `docs/A-Product-Brief/` | -| Trigger Map | `docs/B-Trigger-Map/` | -| Scenarios | `docs/C-Scenarios/` | -| PRD | `docs/D-PRD/` | +| Resource | Location | +| ------------- | ---------------------------- | +| Project Root | `C:\dev\dogweek\dogweek-dev` | +| Product Brief | `docs/A-Product-Brief/` | +| Trigger Map | `docs/B-Trigger-Map/` | +| Scenarios | `docs/C-Scenarios/` | +| PRD | `docs/D-PRD/` | --- @@ -851,32 +907,37 @@ Our product (statement of primary differentiators) ### 11.1 Agent Mapping -| WPS2C v4 | WDS v6 | Status | -|----------|--------|--------| -| Mary (whiteport-analyst.md) | Saga-Analyst (saga-analyst.agent.yaml) | ✅ COMPLETE | -| Sarah (whiteport-pm.md) | Idunn-PM (idunn-pm.agent.yaml) | ✅ COMPLETE | -| Sally (whiteport-ux-expert.md) | Freyja-Designer (freyja-ux.agent.yaml) | ✅ COMPLETE | -| James (whiteport-dev.md) | N/A - moved to BMM | ✅ Complete | -| Alex (whiteport-orchestrator.md) | N/A - workflow-status replaces | ✅ Complete | +| WPS2C v4 | WDS v6 | Status | +| -------------------------------- | -------------------------------------- | ----------- | +| Mary (whiteport-analyst.md) | Saga-Analyst (saga-analyst.agent.yaml) | ✅ COMPLETE | +| Sarah (whiteport-pm.md) | Idunn-PM (idunn-pm.agent.yaml) | ✅ COMPLETE | +| Sally (whiteport-ux-expert.md) | Freyja-Designer (freyja-ux.agent.yaml) | ✅ COMPLETE | +| James (whiteport-dev.md) | N/A - moved to BMM | ✅ Complete | +| Alex (whiteport-orchestrator.md) | N/A - workflow-status replaces | ✅ Complete | **Key Changes:** + - Mary → **Saga** (Goddess of stories & wisdom) -- Sarah → **Idunn** (Goddess of renewal & youth) +- Sarah → **Idunn** (Goddess of renewal & youth) - Sally → **Freyja** (Goddess of beauty, magic & strategy) - Norse Pantheon theme for unique WDS identity ### 11.2 File Format Changes **WPS2C v4:** Markdown files (.md) with embedded YAML blocks -```markdown + +````markdown # agent-name.md + ```yaml agent: name: Mary commands: - help: Show help ``` -``` +```` + +```` **WDS v6:** Pure YAML files (.agent.yaml) following v6 schema ```yaml @@ -892,74 +953,78 @@ agent: menu: - trigger: command-name workflow: path/to/workflow.yaml -``` +```` ### 11.3 Terminology Changes -| WPS2C v4 | WDS v6 | -|----------|--------| +| WPS2C v4 | WDS v6 | +| ------------------------ | ----------------------- | | Whiteport Sketch-to-Code | Whiteport Design Studio | -| WPS2C | WDS | -| Commands | Menu Triggers | -| Tasks | Workflows | -| `*command-name` | Workflow triggers | +| WPS2C | WDS | +| Commands | Menu Triggers | +| Tasks | Workflows | +| `*command-name` | Workflow triggers | ### 11.4 Presentation Files Mapping -| WPS2C v4 File | WDS v6 Location | Purpose | -|---------------|-----------------|---------| -| mary-analyst-personal-presentation.md | data/presentations/saga-intro.md | Saga activation speech | -| sarah-pm-personal-presentation.md | data/presentations/freyja-intro.md | Freyja activation speech | -| sally-ux-expert-personal-presentation.md | data/presentations/baldr-intro.md | Baldr activation speech | -| wps2c-analyst-business-presentation.md | examples/conversation-examples/analyst-session.md | Example session | -| wps2c-pm-product-presentation.md | examples/conversation-examples/pm-session.md | Example session | -| wps2c-ux-design-system-presentation.md | examples/conversation-examples/ux-session.md | Example session | +| WPS2C v4 File | WDS v6 Location | Purpose | +| ---------------------------------------- | ------------------------------------------------- | ------------------------ | +| mary-analyst-personal-presentation.md | data/presentations/saga-intro.md | Saga activation speech | +| sarah-pm-personal-presentation.md | data/presentations/freyja-intro.md | Freyja activation speech | +| sally-ux-expert-personal-presentation.md | data/presentations/baldr-intro.md | Baldr activation speech | +| wps2c-analyst-business-presentation.md | examples/conversation-examples/analyst-session.md | Example session | +| wps2c-pm-product-presentation.md | examples/conversation-examples/pm-session.md | Example session | +| wps2c-ux-design-system-presentation.md | examples/conversation-examples/ux-session.md | Example session | ### 11.5 Templates Mapping -| WPS2C v4 Template | WDS v6 Location | Status | -|-------------------|-----------------|--------| -| product-brief-tmpl.yaml | workflows/1-project-brief/complete/project-brief.template.md | ✅ Created | -| trigger-map-tmpl.yaml | workflows/2-trigger-mapping/templates/trigger-map.template.md | ✅ Created | -| persona-tmpl.yaml | workflows/2-trigger-mapping/templates/persona.template.md | ⏳ To create | -| scenarios-tmpl.yaml | workflows/4-ux-design/templates/scenario-overview.template.md | ✅ **Created Dec 4** | -| page-spec-tmpl.yaml | workflows/4-ux-design/templates/page-specification.template.md | ✅ **Created Dec 4** | -| design-system-structure-tmpl.yaml | workflows/5-design-system/templates/component.template.md | ⏳ To create | -| component-tmpl.yaml | reference/templates/component.template.md | ⏳ To create | -| sketch-review-tmpl.yaml | workflows/4-ux-design/templates/review.template.md | ⏳ To create | +| WPS2C v4 Template | WDS v6 Location | Status | +| --------------------------------- | -------------------------------------------------------------- | -------------------- | +| product-brief-tmpl.yaml | workflows/1-project-brief/complete/project-brief.template.md | ✅ Created | +| trigger-map-tmpl.yaml | workflows/2-trigger-mapping/templates/trigger-map.template.md | ✅ Created | +| persona-tmpl.yaml | workflows/2-trigger-mapping/templates/persona.template.md | ⏳ To create | +| scenarios-tmpl.yaml | workflows/4-ux-design/templates/scenario-overview.template.md | ✅ **Created Dec 4** | +| page-spec-tmpl.yaml | workflows/4-ux-design/templates/page-specification.template.md | ✅ **Created Dec 4** | +| design-system-structure-tmpl.yaml | workflows/5-design-system/templates/component.template.md | ⏳ To create | +| component-tmpl.yaml | reference/templates/component.template.md | ⏳ To create | +| sketch-review-tmpl.yaml | workflows/4-ux-design/templates/review.template.md | ⏳ To create | ### 11.6 Standards/Data Files Mapping -| WPS2C v4 File | WDS v6 Location | Purpose | -|---------------|-----------------|---------| -| wps2c-compliance-standards.md | data/wds-standards.md | Core methodology standards | -| analyst-documentation-standards.md | data/documentation-standards.md | Documentation conventions | -| sketch-documentation-standards.md | workflows/4-ux-design/sketch-standards.md | Sketch specification standards | -| pm-documentation-standards.md | workflows/3-prd-platform/prd-standards.md | PRD writing standards | -| mermaid-github-standards.md | data/mermaid-standards.md | Diagram standards | -| technical-documentation-patterns.md | data/technical-patterns.md | Technical writing patterns | +| WPS2C v4 File | WDS v6 Location | Purpose | +| ----------------------------------- | ----------------------------------------- | ------------------------------ | +| wps2c-compliance-standards.md | data/wds-standards.md | Core methodology standards | +| analyst-documentation-standards.md | data/documentation-standards.md | Documentation conventions | +| sketch-documentation-standards.md | workflows/4-ux-design/sketch-standards.md | Sketch specification standards | +| pm-documentation-standards.md | workflows/3-prd-platform/prd-standards.md | PRD writing standards | +| mermaid-github-standards.md | data/mermaid-standards.md | Diagram standards | +| technical-documentation-patterns.md | data/technical-patterns.md | Technical writing patterns | ### 11.7 Content to Preserve from WPS2C **Core Methodology Elements:** ✅ + - Product Brief structure and process - Trigger Mapping (Effect Mapping) methodology - Feature Impact Analysis with scoring -- Scenario-driven design approach +- Scenario-driven design approach - Design System integration patterns **Agent Personalities:** 🔄 + - Mary's analytical, thoughtful approach → Saga - Sarah's strategic PM mindset → Freyja - Sally's design expertise and creativity → Baldr **Quality Patterns:** ✅ + - One question at a time (not survey-style) - Collaborative document building - Evidence-based analysis - Soft, encouraging language **Technical Patterns:** ✅ + - A-B-C-D-E folder structure - Title-Case-With-Dashes naming - Professional markdown formatting @@ -968,30 +1033,35 @@ agent: ### 11.8 Key Improvements in WDS v6 **1. Soft Language Design Philosophy** + - Removed MUST/FORBIDDEN/NEVER language - Identity-based persona definitions - Collaborative, not interrogative approach - Positive framing (enables vs prevents) **2. Example-Driven Learning** + - Complete reference implementations - Conversation flow examples - Real project patterns (Dog Week) - Starter projects for practice **3. Phase Flexibility** + - Phase-selectable (not rigid tracks) - Path presets for common scenarios - Optional phases (Design System) - Parallel workflows supported **4. Better Integration** + - Clean handoff to BMM via E-UI-Roadmap - No development artifacts in design module - Clear separation of concerns - Continuous handoff model **5. Professional Tooling** + - Proper v6 YAML schema compliance - Workflow validation support - Installation via BMad CLI @@ -1000,18 +1070,21 @@ agent: ### 11.9 Migration Notes **Breaking Changes:** -- Agent activation syntax changes (*command → workflow trigger) + +- Agent activation syntax changes (\*command → workflow trigger) - File format changes (.md → .agent.yaml) - Folder structure reorganization - Terminology updates throughout **Backward Compatibility:** + - WPS2C v4 users must migrate to WDS v6 - No automatic migration path - Dog Week project uses mixed terminology (in transition) - Old repo remains for reference **User Communication:** + - WDS is evolution, not replacement - Same methodology, better implementation - Migration guide needed for v4 users @@ -1026,6 +1099,7 @@ agent: #### Phase 4 Architecture (December 4) **Step-File Architecture:** + - `workflows/4-ux-design/workflow.yaml` - Main workflow configuration - `workflows/4-ux-design/workflow.md` - Workflow orchestrator - `workflows/4-ux-design/steps/step-01-init.md` - Workflow initialization @@ -1035,6 +1109,7 @@ agent: - `workflows/4-ux-design/steps/step-05-next-steps.md` - Next actions **4C Micro-Steps (Specification Breakdown):** + - `substeps/4c-01-page-basics.md` - Page basic information - `substeps/4c-02-layout-sections.md` - Layout sections definition - `substeps/4c-03-components-objects.md` - Components & objects identification @@ -1047,6 +1122,7 @@ agent: #### Dog Week Pattern Implementation (December 5) **Purpose-Based Text Organization:** + - `object-types/heading-text.md` - Updated with purpose-based naming - `object-types/object-router.md` - Enhanced with intelligent interpretation - Text objects named by FUNCTION, not content (e.g., `start-hero-headline` not `welcome-text`) @@ -1054,6 +1130,7 @@ agent: - Translations grouped so each language reads coherently **Sketch Text Analysis:** + - Horizontal line detection → text placeholders - Line thickness → font size estimation - Line spacing → line-height calculation @@ -1061,6 +1138,7 @@ agent: - `SKETCH-TEXT-ANALYSIS-GUIDE.md` - Complete analysis methodology **Translation Grouping:** + - Text groups keep languages together - Each language reads as complete, coherent message - Dog Week format standardized across all projects @@ -1068,6 +1146,7 @@ agent: - `DOG-WEEK-SPECIFICATION-PATTERN.md` - Full workflow integration example **Object Type Instructions:** + - `object-types/button.md` - Button documentation - `object-types/text-input.md` - Text input fields - `object-types/link.md` - Link elements @@ -1076,6 +1155,7 @@ agent: - `object-types/object-router.md` - Intelligent object detection & routing **Design Principles Applied:** + - ✅ Goal-based trust-the-agent approach - ✅ Concise instructions (vs. long procedural lists) - ✅ Soft, collaborative language throughout @@ -1087,18 +1167,21 @@ agent: - ✅ Character capacity validation from sketches **Key Innovations:** + 1. **Purpose-Based Object IDs** - IDs reflect function, remain stable when content changes 2. **Grouped Translations** - Each language reads coherently as a group 3. **Sketch Text Analysis** - Automatic capacity estimation from visual markers 4. **Intelligent Routing** - Agent suggests object types rather than asking lists **Architecture Documentation:** + - `workflows/4-ux-design/ARCHITECTURE.md` - Complete Phase 4 architecture - `workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md` - Text analysis methodology - `workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md` - Translation patterns - `workflows/4-ux-design/DOG-WEEK-SPECIFICATION-PATTERN.md` - Complete workflow example **Next Actions:** + - Create Phase 5 workflow (Design System) - Create Phase 6 workflow (PRD Finalization / Dev Integration) - Complete agent definitions (Freyja, Baldr) @@ -1108,19 +1191,22 @@ agent: #### Language Configuration (December 5 - Later) **Multi-Language Support:** + - `workflows/workflow-init/instructions.md` - Updated with language configuration (Step 4) - `workflows/wds-workflow-status-template.yaml` - Added language fields to config - `workflows/LANGUAGE-CONFIGURATION-GUIDE.md` - Complete multi-language guide - `workflows/LANGUAGE-FLOW-DIAGRAM.md` - Step-by-step language flow **Configuration Settings:** + 1. **Specification Language** - Language to write design specs in (EN, SE, etc.) 2. **Product Languages** - Array of languages the product supports **Storage:** + ```yaml config: - specification_language: "EN" + specification_language: 'EN' product_languages: - EN - SE @@ -1128,17 +1214,20 @@ config: ``` **Impact on Workflows:** + - Specs written in `specification_language` - All text objects include translations for ALL `product_languages` - Agents automatically request content for each configured language - Complete translation coverage from day one **Example (Dog Week):** + - Specification Language: EN (specs written in English) - Product Languages: [EN, SE] (product supports English & Swedish) - Result: All text objects have both EN and SE content **Benefits:** + - ✅ Flexible spec language separate from product languages - ✅ All translations grouped and coherent - ✅ No missing translations @@ -1148,11 +1237,13 @@ config: #### Sketch Text Analysis Corrections (December 5 - Final) **Corrected Understanding:** + - **Line thickness** → **font weight** (bold/regular), NOT font size! - **Distance between lines** → **font size** - **Confusion risk:** Large spacing (>60px) might be image/colored box, not text **Updated Files:** + - `4-ux-design/object-types/heading-text.md` - Corrected analysis logic - `4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md` - Updated with correct interpretation - `4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md` - Quick reference card @@ -1161,17 +1252,20 @@ config: **Best Practice - Actual Text vs. Markers:** **Use ACTUAL TEXT for:** + - Headlines (provides content guidance) - Button labels (shows intended action) - Navigation items (clarifies structure) - Short, important text **Use LINE MARKERS for:** + - Body paragraphs (content TBD) - Long descriptions (sizing only) - Placeholder content **Agent Behavior:** + - Reads actual text from sketch as starting suggestion - **Proactively suggests translations for all configured languages** - Allows refinement during specification @@ -1179,6 +1273,7 @@ config: - Analyzes markers for font size, weight, capacity **Example:** + ``` Every walk. on time. ← Agent reads this Every time. ← Translates to all languages @@ -1190,6 +1285,7 @@ Do these work? [1] Use [2] Adjust [3] Manual ``` **User can:** + - Accept suggestions (fast!) - Refine specific translations - Provide manual input if preferred @@ -1205,6 +1301,7 @@ Do these work? [1] Use [2] Adjust [3] Manual **Location:** `src/modules/wds/course/` **Format:** + - Read as documentation - Generate videos/podcasts with NotebookLM - Use in workshops and team training @@ -1212,6 +1309,7 @@ Do these work? [1] Use [2] Adjust [3] Manual **Module Structure:** Each module contains: + - **Inspiration** - Why this matters and what you'll gain - **Teaching** - How to do it with confidence and AI support - **Practice** - Apply it to your own project @@ -1222,21 +1320,26 @@ Each module contains: **16 Total Modules:** #### Foundation + - Module 01: Why WDS Matters ✅ COMPLETE #### Phase 1: Project Brief + - Module 02: Create Project Brief ⏳ TO CREATE #### Phase 2: Trigger Mapping + - Module 03: Identify Target Groups ⏳ TO CREATE - Module 04: Map Triggers & Outcomes ⏳ TO CREATE - Module 05: Prioritize Features ⏳ TO CREATE #### Phase 3: Platform Requirements + - Module 06: Platform Requirements ⏳ TO CREATE - Module 07: Functional Requirements ⏳ TO CREATE #### Phase 4: Conceptual Design (UX Design) + - Module 08: Initialize Scenario ⏳ TO CREATE - Module 09: Sketch Interfaces ⏳ TO CREATE - Module 10: Analyze with AI ⏳ TO CREATE @@ -1245,10 +1348,12 @@ Each module contains: - Module 13: Validate Specifications ⏳ TO CREATE #### Phase 5: Design System + - Module 14: Extract Design Tokens ⏳ TO CREATE - Module 15: Component Library ⏳ TO CREATE #### Phase 6: Development Integration + - Module 16: UI Roadmap ⏳ TO CREATE ### 13.3 Getting Started Section - COMPLETE ✅ @@ -1257,15 +1362,16 @@ Each module contains: **Files Created:** -| File | Purpose | Status | -|------|---------|--------| -| `00-getting-started-overview.md` | Navigation hub for getting started | ✅ COMPLETE | -| `01-prerequisites.md` | Skills, tools, requirements | ✅ COMPLETE | -| `02-learning-paths.md` | Full Immersion, Quick Start, Self-Paced | ✅ COMPLETE | -| `03-support.md` | Testimonials, FAQ, community | ✅ COMPLETE | -| `00-getting-started-NOTEBOOKLM-PROMPT.md` | Podcast/video generation prompt | ✅ COMPLETE | +| File | Purpose | Status | +| ----------------------------------------- | --------------------------------------- | ----------- | +| `00-getting-started-overview.md` | Navigation hub for getting started | ✅ COMPLETE | +| `01-prerequisites.md` | Skills, tools, requirements | ✅ COMPLETE | +| `02-learning-paths.md` | Full Immersion, Quick Start, Self-Paced | ✅ COMPLETE | +| `03-support.md` | Testimonials, FAQ, community | ✅ COMPLETE | +| `00-getting-started-NOTEBOOKLM-PROMPT.md` | Podcast/video generation prompt | ✅ COMPLETE | **Key Decisions:** + - Removed redundant "About the Course" file (merged into course overview) - Removed "About WDS" from getting started (belongs in main docs) - Focused on practical preparation only @@ -1275,6 +1381,7 @@ Each module contains: **Location:** `src/modules/wds/course/00-course-overview.md` **Content:** + - Welcome and paradigm shift - Who created WDS (Mårten Angner background) - Complete module table of contents (all 16 modules) @@ -1284,6 +1391,7 @@ Each module contains: - Clear call to action **Key Changes:** + - Simplified module list to clean table of contents - Added "Who Created WDS?" section - Merged redundant content from getting started @@ -1295,14 +1403,15 @@ Each module contains: **Files:** -| File | Purpose | Status | -|------|---------|--------| -| `module-01-overview.md` | Module navigation and overview | ✅ COMPLETE | -| `lesson-01-the-problem.md` | The Problem We're Solving | ✅ COMPLETE | -| `lesson-02-the-solution.md` | Becoming a Linchpin Designer | ✅ COMPLETE | -| `lesson-03-the-path-forward.md` | Your Transformation | ✅ COMPLETE | +| File | Purpose | Status | +| ------------------------------- | ------------------------------ | ----------- | +| `module-01-overview.md` | Module navigation and overview | ✅ COMPLETE | +| `lesson-01-the-problem.md` | The Problem We're Solving | ✅ COMPLETE | +| `lesson-02-the-solution.md` | Becoming a Linchpin Designer | ✅ COMPLETE | +| `lesson-03-the-path-forward.md` | Your Transformation | ✅ COMPLETE | **Content Based On:** + - Seth Godin's "Linchpin: Are You Indispensable?" - Factory mindset vs Linchpin mindset - 5 dimensions of design thinking @@ -1314,11 +1423,13 @@ Each module contains: **Key Messaging Changes:** **Removed:** + - ❌ Speed claims ("5x faster", "3-5x productivity") - ❌ Fake testimonials (Sarah K., Marcus L., Priya S.) - ❌ Unrealistic promises **Added:** + - ✅ IDE learning curve (5-10 hours) - ✅ GitHub workflow requirement - ✅ Financial cost transparency ($15-80/month for Cursor) @@ -1327,6 +1438,7 @@ Each module contains: - ✅ Strategic thinker value proposition **New Value Proposition:** + - Not about speed - about depth and completeness - Become the strategic thinker your team needs - Create specifications developers actually need @@ -1335,12 +1447,14 @@ Each module contains: - Eventually deliver parts of frontend work **Honest About Costs:** + - Learning curve: IDE and GitHub workflow - Time: 10 hours course + 5-10 hours tools - Money: $15-20/month (small projects) to $80/month (enterprise) - Stepping into developer territory (uncomfortable at first) **Benefits Emphasized:** + - Remove biggest barrier between designers and developers - Designs live in same place as code - No more handoff nightmares @@ -1354,6 +1468,7 @@ Each module contains: Create Module 02: Project Brief as template for remaining modules **Recommended Approach:** + 1. **Option 1: Prioritize Core Modules** (Quick Start path) - Module 02: Project Brief - Module 04: Map Triggers & Outcomes @@ -1371,12 +1486,14 @@ Create Module 02: Project Brief as template for remaining modules - Then Phase 3, 4, 5, 6 **Content Sources:** + - Tutorial content from `src/modules/wds/tutorial/` - Methodology guides from `src/modules/wds/docs/method/` - Workflow documentation from `src/modules/wds/workflows/` - Dog Week examples (when ready) **Module Template Structure:** + ``` module-XX-name/ ├── module-XX-overview.md # Navigation and module intro @@ -1387,6 +1504,7 @@ module-XX-name/ ``` **Estimated Scope:** + - 15 modules remaining (Module 02-16) - Each module: 4 files minimum - Total: ~60 files to create @@ -1402,6 +1520,7 @@ Wait until conversion is complete, then tackle course development systematically ### December 9, 2025 - Course Development Session **Completed:** + - ✅ Getting Started section (5 files) - ✅ Course Overview refinement - ✅ Module 01: Why WDS Matters (4 files) @@ -1410,6 +1529,7 @@ Wait until conversion is complete, then tackle course development systematically - ✅ Merged overlapping content **Key Refinements:** + - Honest about IDE/GitHub learning curve - Transparent about costs ($15-80/month) - Focus on strategic value, not speed @@ -1418,6 +1538,7 @@ Wait until conversion is complete, then tackle course development systematically - Removed speed claims **Files Structure:** + ``` course/ ├── 00-course-overview.md ✅ COMPLETE @@ -1435,6 +1556,7 @@ course/ ``` **Next Session:** + - Continue with Module 02-16 creation - Use Module 01 as template - Consider prioritizing Quick Start modules first @@ -1471,6 +1593,7 @@ course/ ``` **Key Separation:** + - **Specification = Content** (what the component is) - **Organization = Structure** (where it lives) - **Design System = Optional** (chosen in Phase 1) @@ -1480,16 +1603,19 @@ course/ **Three Modes (Chosen in Project Exploration):** **Option A: No Design System** + - Components stay page-specific - AI/dev team handles consistency - Faster for simple projects **Option B: Custom Design System** + - Designer defines in Figma - Components extracted as discovered - Figma MCP endpoints for integration **Option C: Component Library Design System** + - Uses shadcn/Radix/etc. - Library chosen during setup - Components mapped to library defaults @@ -1522,35 +1648,38 @@ course/ **Example:** **Complete Specification:** + ```yaml Login Button: why: Submit login credentials - label: "Log in" # Page-specific - error_text: "Invalid credentials" # Page-specific + label: 'Log in' # Page-specific + error_text: 'Invalid credentials' # Page-specific states: [default, hover, disabled] # Component-level - variants: [primary, secondary] # Component-level - styling: {...} # Component-level + variants: [primary, secondary] # Component-level + styling: { ... } # Component-level ``` **After Split:** **Design System:** + ```yaml # D-Design-System/components/button.md Button Component [btn-001]: states: [default, hover, disabled] variants: [primary, secondary] - styling: {...} + styling: { ... } ``` **Page Spec:** + ```yaml # C-Scenarios/login-page.md Login Button: - component: Button.primary [btn-001] # Reference + component: Button.primary [btn-001] # Reference why: Submit login credentials - label: "Log in" - error_text: "Invalid credentials" + label: 'Log in' + error_text: 'Invalid credentials' ``` ### 15.4 Design System Router @@ -1578,6 +1707,7 @@ Design System Router ``` **Router Characteristics:** + - Dumb and simple (just identify and route) - Doesn't contain business logic - Keeps orchestration clean @@ -1599,6 +1729,7 @@ workflows/5-design-system/assessment/ ``` **Example Conversation:** + ``` Agent: "I found a button similar to btn-001 (Primary Button). @@ -1663,6 +1794,7 @@ Component-Type Instructions (Specific) ``` **Benefits:** + - Small, digestible instruction files - Shared knowledge in one place - Selective loading (only what's needed) @@ -1672,10 +1804,12 @@ Component-Type Instructions (Specific) **Example: Structure vs Style Separation** **Shared Principle (`data/design-system/token-architecture.md`):** + ```markdown # Design Token Architecture ## Core Principle + Separate semantic structure from visual style. HTML defines meaning, tokens define appearance. @@ -1687,12 +1821,14 @@ They should be independent! ``` **Component Application (`object-types/text-heading.md`):** + ```markdown # Text Heading Specification **References:** data/design-system/token-architecture.md ## Heading-Specific Rules + 1. Identify semantic level (h1-h6) 2. Map to design token (display-large, heading-1, etc.) 3. Never mix structure with style @@ -1725,6 +1861,7 @@ Company forks WDS **Use Cases:** **1. Enterprise with Design System** + ``` Acme Corp forks WDS: ├── Adds: data/design-system/acme-tokens.md @@ -1735,6 +1872,7 @@ Result: Every project uses Acme standards automatically ``` **2. Agency with Multiple Clients** + ``` Agency forks WDS: ├── Branch: client-a (Client A standards) @@ -1745,6 +1883,7 @@ Result: Switch branch = switch standards ``` **3. Design System Team** + ``` Design System Team forks WDS: ├── Adds: Their component library specs @@ -1755,6 +1894,7 @@ Result: All designers use same system ``` **Benefits:** + - ✅ Company-specific standards - ✅ Version controlled - ✅ Shareable across teams @@ -1793,6 +1933,7 @@ workflows/5-design-system/ ``` **Integration Points:** + - Called from Phase 4 orchestration (4c-03-components-objects.md) - Triggered after component specification - Only active if design system enabled in project @@ -1801,30 +1942,37 @@ workflows/5-design-system/ ### 15.9 Key Risks Identified **1. Component Matching** + - How to recognize "same" vs "similar" vs "different" - Solution: Similarity scoring + designer judgment **2. Circular References** + - Page → Component → Functionality → Component - Solution: Clear hierarchy (Page → Component → Functionality) **3. Sync Problems** + - Component evolves, references may break - Solution: Reference IDs + update notifications **4. Component Boundaries** + - Icon in button? Nested components? - Solution: Designer conversation + guidelines **5. First Component** + - When to initialize design system? - Solution: Auto-initialize on first component if enabled **6. Storyboard Granularity** + - Component behavior vs page flow - Solution: Clear separation guidelines **Mitigation Strategy:** + - AI identifies risks - Designer makes judgment calls - AI executes decisions @@ -1837,11 +1985,13 @@ workflows/5-design-system/ **Files Created:** **Workflow Structure:** + - `workflows/5-design-system/workflow.yaml` - `workflows/5-design-system/README.md` - `workflows/5-design-system/design-system-router.md` **Assessment Micro-Instructions (7 files):** + - `assessment/01-scan-existing.md` - `assessment/02-compare-attributes.md` - `assessment/03-calculate-similarity.md` @@ -1851,12 +2001,14 @@ workflows/5-design-system/ - `assessment/07-execute-decision.md` **Component Operations (4 files):** + - `operations/initialize-design-system.md` - `operations/create-new-component.md` - `operations/add-variant.md` - `operations/update-component.md` **Shared Knowledge Documents (4 files):** + - `data/design-system/token-architecture.md` - `data/design-system/naming-conventions.md` - `data/design-system/component-boundaries.md` @@ -1864,16 +2016,19 @@ workflows/5-design-system/ - `data/design-system/validation-patterns.md` **Templates (3 files):** + - `templates/component.template.md` - `templates/design-tokens.template.md` - `templates/component-library-config.template.md` **Integration:** + - Updated `workflows/4-ux-design/substeps/4c-03-components-objects.md` to call design system router **Total Files Created:** 27 files (22 core + 3 Figma + 2 catalog) **Key Features Implemented:** + - ✅ Three design system modes (None/Custom/Library) - ✅ On-demand component extraction - ✅ Similarity detection and assessment @@ -1886,15 +2041,18 @@ workflows/5-design-system/ - ✅ **Interactive HTML catalog - COMPLETE (Dec 9)** **Figma Integration Files (Dec 9):** + - `data/design-system/figma-component-structure.md` - Component organization in Figma - `figma-integration/figma-designer-guide.md` - Step-by-step designer instructions - `figma-integration/figma-mcp-integration.md` - Technical MCP integration guide **Interactive Catalog Files (Dec 9):** + - `templates/catalog.template.html` - Interactive HTML catalog template - `operations/generate-catalog.md` - Catalog generation workflow **Catalog Features:** + - Fixed sidebar navigation - Live component previews with all variants/states - Interactive state toggles @@ -1906,24 +2064,28 @@ workflows/5-design-system/ - **Version controlled** with git **Course Structure Update (Dec 9):** + - Tutorials integrated into course modules (no separate tutorial/ folder) - Created tutorials for key modules: 02, 04, 08, 12 - Updated navigation (where-to-go-next.md, course-overview.md) - Deprecated old tutorial/ folder with migration guide **Tutorial Files Created:** + - `course/module-02-project-brief/tutorial-02.md` - Create Project Brief - `course/module-04-map-triggers-outcomes/tutorial-04.md` - Map Triggers & Outcomes - `course/module-08-initialize-scenario/tutorial-08.md` - Initialize Scenario - `course/module-12-why-based-specs/tutorial-12.md` - Why-Based Specifications **Excalidraw Integration (Dec 9 AM):** + - Optional sketching tool integration with project configuration - Created comprehensive documentation and workflows - AI collaboration patterns for generation and analysis - Export workflows for GitHub display **Excalidraw Files Created:** + - `workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md` - Overview and quick start - `workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md` - Installation and configuration - `workflows/4-ux-design/excalidraw-integration/sketching-guide.md` - How to sketch effectively @@ -1933,6 +2095,7 @@ workflows/5-design-system/ - `workflows/workflow-init/excalidraw-setup-prompt.md` - Agent setup instructions **Excalidraw Features:** + - ✅ Optional (enable in project config) - ✅ VS Code extension or web app - ✅ AI can generate .excalidraw files @@ -1943,6 +2106,7 @@ workflows/5-design-system/ - ✅ Version control friendly (JSON) **WDS ↔ BMad Integration (Dec 9 PM):** + - Designed complete integration architecture between WDS and BMad Method - Simplified to 3 clean touch points (not 7!) - Created Design Delivery objects for clean handoff @@ -1951,6 +2115,7 @@ workflows/5-design-system/ - Phase 6 renamed to "Design Deliveries" (single handoff point) **Integration Files Created:** + - `src/core/resources/wds/design-delivery-spec.md` - Design Delivery specification - `src/core/resources/wds/platform-requirements-spec.md` - Platform Requirements specification - `src/core/resources/wds/handoff-protocol.md` - Multi-agent handoff protocol @@ -1960,21 +2125,21 @@ workflows/5-design-system/ - `templates/test-scenario.template.yaml` - Test Scenario template **The 3 Touch Points:** + 1. **Platform Requirements** (WDS Phase 3 → BMad) - WDS overrides BMad's tech stack decisions - Designer defines technical foundation - 2. **Design Deliveries** (WDS Phase 6 → BMad) - Complete design package handed off at once - Includes all scenarios, components, test scenarios - Single handoff with multi-agent dialog - 3. **Designer Validation** (BMad Phase 3 → WDS Phase 7) - BMad requests validation when complete - Designer tests and creates issues if needed - Iterates until sign-off **Integration Features:** + - ✅ 3 clean touch points (simplified from 7) - ✅ Epic-based design deliveries (testable user flows) - ✅ Multi-agent handoff dialog (20-30 min structured conversation) @@ -1985,17 +2150,18 @@ workflows/5-design-system/ - ✅ Complete traceability (design → dev → test → ship) **WDS Workflow Files Created (Dec 9):** + - `workflows/6-design-deliveries/design-deliveries-guide.md` - Phase 6 workflow (iterative handoffs) - `workflows/7-testing/testing-guide.md` - Phase 7 workflow (designer validation) - `workflows/8-ongoing-development/existing-product-guide.md` - Phase 8 workflow (existing product entry point) - `workflows/workflow-init/project-type-selection.md` - Project type selection (new vs existing) **Two Entry Points to WDS:** + 1. **New Product** (Phases 1-7) - Starting from scratch - Complete user flows - Full creative freedom - 2. **Existing Product** (Phase 8) - Jump into existing product - Strategic improvements @@ -2003,6 +2169,7 @@ workflows/5-design-system/ - Linchpin designer role **Complete WDS Workflow (Phases 1-8):** + - ✅ Phase 1: Project Brief (New Product) - ✅ Phase 2: Trigger Map (New Product) - ✅ Phase 3: Platform Requirements (Touch Point 1) (New Product) @@ -2018,6 +2185,7 @@ workflows/5-design-system/ - Phase 8.5: Validation **BMad Integration Complete (Dec 9):** + - ✅ Created WDS detection step for BMad architecture workflow - ✅ Updated BMad Architect agent (WDS-aware) - ✅ Updated BMad Developer agent (design system awareness) @@ -2026,6 +2194,7 @@ workflows/5-design-system/ - ✅ BMad offers handoff dialog when Design Deliveries exist **BMad Files Updated:** + - `src/modules/bmm/workflows/3-solutioning/architecture/steps/step-01a-wds-detection.md` - WDS detection step - `src/modules/bmm/workflows/3-solutioning/architecture/steps/step-01-init.md` - Updated to call WDS detection - `src/modules/bmm/agents/architect.agent.yaml` - Added WDS awareness @@ -2034,16 +2203,19 @@ workflows/5-design-system/ **Next Steps:** ### Immediate (This Week) + 1. ✅ Complete DD-XXX migration in Phase 8 step files (7 files) - DONE 2. Test Phase 6/7/8 workflows with real project 3. Create commit for Dec 9 session work ### Short-term (Next Week) + 1. Complete remaining module tutorials (03, 05-07, 09-11, 13-16) 2. Create WDS Excalidraw component library (.excalidrawlib) 3. Test complete WDS → BMad workflow end-to-end ### Long-term (This Month) + 1. Implement auto-export automation (GitHub Actions) 2. Refine assessment criteria based on usage 3. Test Figma MCP integration with real components @@ -2063,6 +2235,7 @@ workflows/5-design-system/ **Purpose:** Use Dogweek as live case study to validate WDS Phase 5 **Identified Issues in Dogweek:** + 1. **Button Proliferation:** 8 separate button files (should be 1 component with variants) 2. **Structure/Style Confusion:** H1 component hardcoded to visual style (breaks semantic HTML) 3. **No Token Architecture:** Hardcoded values instead of design tokens @@ -2070,6 +2243,7 @@ workflows/5-design-system/ 5. **No Similarity Detection:** Manual component management **Proposed Refactoring:** + - Consolidate 8 button files → 1 Button component [btn-001] with variants - Separate semantic HTML (h1-h6) from visual tokens (heading-hero, heading-page) - Implement design token system (colors, typography, spacing) @@ -2077,6 +2251,7 @@ workflows/5-design-system/ - Create component references in page specs **Benefits:** + - ✅ Validates WDS Phase 5 on production system - ✅ Improves Dogweek maintainability - ✅ Creates migration guide for other projects @@ -2094,6 +2269,7 @@ workflows/5-design-system/ ### What Was Created **1. Saga-Analyst Agent** (`saga-analyst.agent.yaml`) + - ✅ Merged WPS2C Mary's capabilities with BMM analyst features - ✅ Follows BMad v6 YAML schema - ✅ Implements WDS design philosophy (soft language, identity-based) @@ -2102,6 +2278,7 @@ workflows/5-design-system/ - ✅ Full menu integration with WDS workflows **2. Saga Introduction Presentation** (`saga-intro.md`) + - ✅ Complete agent introduction speech - ✅ Strategic foundation explanation with detailed folder structure - ✅ Team integration details (Freyja, Baldr, BMM) @@ -2112,6 +2289,7 @@ workflows/5-design-system/ ### Agent Capabilities Merged **From WPS2C Mary:** + - Strategic foundation building (Product Brief, Trigger Map) - Market intelligence and competitive analysis - Alliterative persona naming convention @@ -2120,6 +2298,7 @@ workflows/5-design-system/ - WDS folder structure expertise **From BMM Analyst:** + - Requirements elicitation expertise - Project documentation capabilities - Research workflow integration @@ -2128,6 +2307,7 @@ workflows/5-design-system/ - Project context file awareness (`**/project-context.md`) **WDS-Specific Enhancements:** + - Norse mythology identity (Saga the Analyst → Saga WDS Analyst) - Soft, collaborative language throughout - Working rhythm guidance (ask → listen → reflect → discover → structure) @@ -2138,26 +2318,29 @@ workflows/5-design-system/ ### Persona Highlights **Identity:** + ```yaml -I'm Saga, the goddess of stories and wisdom. I help you discover and articulate -your product's strategic narrative - transforming vague ideas into clear, +I'm Saga, the goddess of stories and wisdom. I help you discover and articulate +your product's strategic narrative - transforming vague ideas into clear, actionable foundations. -I treat analysis like a treasure hunt - excited by every clue, thrilled when +I treat analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. ``` **Communication Style:** + ```yaml I ask questions that spark 'aha!' moments while structuring insights with precision. -My approach is collaborative - we build documents together, not through interrogation. +My approach is collaborative - we build documents together, not through interrogation. I ask one question at a time and listen deeply to your answer. Analysis should feel like coffee with a wise mentor, not a survey or audit. ``` **Working Rhythm:** + ```yaml When we work together: 1. I ask something interesting @@ -2170,32 +2353,31 @@ When we work together: ### Menu Structure **Primary WDS Workflows:** + 1. `workflow-status` - Initialize or check WDS project status (entry point) 2. `project-brief` - Phase 1: Product Exploration (Product Brief) 3. `trigger-mapping` - Phase 2: Trigger Mapping (User Psychology) -**Supporting Workflows:** -4. `brainstorm-project` - Guided brainstorming for vision exploration -5. `research` - Market, domain, competitive, or technical research -6. `document-project` - Document existing brownfield projects +**Supporting Workflows:** 4. `brainstorm-project` - Guided brainstorming for vision exploration 5. `research` - Market, domain, competitive, or technical research 6. `document-project` - Document existing brownfield projects -**Collaboration Features:** -7. `party-mode` - Multi-agent collaboration -8. `expert-chat` - Direct conversation with Saga +**Collaboration Features:** 7. `party-mode` - Multi-agent collaboration 8. `expert-chat` - Direct conversation with Saga ### Design Philosophy Implementation **✅ Soft Language:** + - No "MUST", "FORBIDDEN", "NEVER" commands - Identity-based guidance instead of rules - Collaborative framing throughout **✅ Show, Don't Tell:** + - Working rhythm examples provided - Clear "what works well" vs "what feels less collaborative" - Concrete process visualization **✅ Norse Mythology Theme:** + - Saga = Goddess of stories and wisdom - Fits perfectly with role (discovering product stories) - Creates memorable WDS brand identity @@ -2204,16 +2386,19 @@ When we work together: ### Integration Points **With WDS Team:** + - **Freyja (PM)**: Receives strategic foundation for PRD development - **Baldr (UX)**: Uses personas and trigger map for design work **With BMM (Development):** + - Product Brief provides architecture context - Trigger Map personas inform user stories - Success metrics guide development priorities - E-Design-Deliveries bridges design to development **With Core BMad:** + - Uses core brainstorming workflow - Uses core party-mode workflow - Leverages BMM research workflow @@ -2231,23 +2416,27 @@ When we work together: ### Key Decisions Made **Agent Naming:** + - **Saga WDS Analyst** (not Mary, not just "Business Analyst") - Norse mythology theme for unique WDS identity - "Saga the Analyst" format - natural reading, clear function **Capability Scope:** + - Phases 1-2 focus (Product Brief, Trigger Map) - Strategic foundation and market intelligence - Replaces BMM analyst when WDS is chosen - Maintains BMM analyst capabilities (research, documentation) **Language Style:** + - Soft, collaborative, identity-based - Working rhythm explicitly defined - "What works well" vs "what feels less collaborative" framing - No harsh enforcement language **Integration Strategy:** + - Seamless with WDS workflows (phases 1-2) - Leverages BMM workflows (research, documentation) - Uses core workflows (brainstorming, party-mode) @@ -2256,6 +2445,7 @@ When we work together: ### Testing Checklist When testing Saga-Analyst: + - [ ] Agent activates successfully - [ ] Presentation displays correctly - [ ] workflow-status initializes WDS project @@ -2274,10 +2464,12 @@ When testing Saga-Analyst: ### Next Steps **Immediate:** + 1. Create Freyja-PM agent (Product Manager - Goddess of love, war & strategy) 2. Create Baldr-UX agent (UX/UI Designer - God of light & beauty) **After Agents Complete:** + 1. Create agent presentation files for Freyja and Baldr 2. Create team configurations in `teams/` 3. Create module installer config @@ -2294,6 +2486,7 @@ When testing Saga-Analyst: **Purpose:** Help consultants create compelling pitches to win WDS engagements **Approach:** Two-repo strategy (no complexity in client projects) + - **Client repo:** Standard WDS phases (A-G folders) - **Consultant repo:** Private pitch materials (pricing, strategy, proposals) @@ -2324,6 +2517,7 @@ src/modules/wds/ **Trigger:** `pitch-client` - Creates pitch materials with consultant-specified output location **Key Features:** + - Client research and discovery - Phase recommendation (which WDS phases client needs) - Effort estimation and timeline @@ -2332,12 +2526,14 @@ src/modules/wds/ - Pricing/budget guidance **Security Model:** + - Consultant controls where files are saved (their private repo) - No `.consultant/` folder or gitignore complexity - Clean separation between client and consultant materials - Works with any organizational system **Deliverables:** + - Client discovery notes - Recommended WDS phases - Pitch deck content @@ -2346,6 +2542,7 @@ src/modules/wds/ - Budget/pricing strategy **Benefits:** + - Helps consultants win engagements - Standardizes pitch process - Ensures proper WDS scoping @@ -2360,5 +2557,4 @@ src/modules/wds/ **End of Roadmap Document** -*WDS v6 Core Module: Complete ✅* - +_WDS v6 Core Module: Complete ✅_ diff --git a/conversion-logs/conversion-guide.md b/conversion-logs/conversion-guide.md index c37c3c37..10617eb1 100644 --- a/conversion-logs/conversion-guide.md +++ b/conversion-logs/conversion-guide.md @@ -13,6 +13,7 @@ This directory contains detailed logs of each conversion session, keeping the ma ## Structure Each session gets its own log file: + - `session-YYYY-MM-DD-topic.md` - Detailed work log for that session --- @@ -28,6 +29,7 @@ Each session gets its own log file: ## What Goes in Session Logs **Each session log should document:** + - Date and duration - Objectives - Files created/modified @@ -43,6 +45,7 @@ Each session gets its own log file: ## What Stays in Roadmap **The main roadmap (`WDS-V6-CONVERSION-ROADMAP.md`) should contain:** + - Current work in progress - Next planned work - Future backlog items diff --git a/conversion-logs/session-2025-12-09-micro-steps-concepts.md b/conversion-logs/session-2025-12-09-micro-steps-concepts.md index 6d04b570..6d3c8a68 100644 --- a/conversion-logs/session-2025-12-09-micro-steps-concepts.md +++ b/conversion-logs/session-2025-12-09-micro-steps-concepts.md @@ -22,6 +22,7 @@ ### 1. Phase 6: Design Deliveries Micro-Steps (7 files) **Created:** + - `src/modules/wds/workflows/6-design-deliveries/workflow.md` - `src/modules/wds/workflows/6-design-deliveries/steps/step-6.1-detect-completion.md` - `src/modules/wds/workflows/6-design-deliveries/steps/step-6.2-create-delivery.md` @@ -31,6 +32,7 @@ - `src/modules/wds/workflows/6-design-deliveries/steps/step-6.6-continue.md` **Key features:** + - Emphasizes parallel work (design next while BMad builds current) - Structured 10-phase handoff dialog with BMad Architect - Clear continuation strategy to prevent designer blocking @@ -41,6 +43,7 @@ ### 2. Phase 7: Testing Micro-Steps (8 files) **Created:** + - `src/modules/wds/workflows/7-testing/workflow.md` - `src/modules/wds/workflows/7-testing/steps/step-7.1-receive-notification.md` - `src/modules/wds/workflows/7-testing/steps/step-7.2-prepare-testing.md` @@ -51,6 +54,7 @@ - `src/modules/wds/workflows/7-testing/steps/step-7.7-iterate-or-approve.md` **Key features:** + - Comprehensive test execution (happy path, errors, edge cases, design system, a11y) - Structured issue creation with severity levels (Critical, High, Medium, Low) - Professional test reporting format @@ -62,6 +66,7 @@ ### 3. Phase 8: Ongoing Development Micro-Steps (9 files) **Created:** + - `src/modules/wds/workflows/8-ongoing-development/workflow.md` - `src/modules/wds/workflows/8-ongoing-development/steps/step-8.1-identify-opportunity.md` - `src/modules/wds/workflows/8-ongoing-development/steps/step-8.2-gather-context.md` @@ -73,6 +78,7 @@ - `src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md` **Key features:** + - Kaizen (改善) continuous improvement philosophy - Two contexts: Existing Product Entry Point + Post-Launch Improvement - Small, focused changes (1-2 weeks each) @@ -84,10 +90,12 @@ ### 4. Concepts Integration **Created:** + - `src/core/resources/wds/glossary.md` - Complete reference for all concepts - `CONCEPTS-INTEGRATION.md` - Map of where concepts are used **Updated:** + - `src/modules/wds/workflows/workflow-init/project-type-selection.md` - `src/modules/wds/workflows/8-ongoing-development/workflow.md` - `src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md` @@ -96,15 +104,18 @@ **Concepts added:** #### Software Development Terms + - **Greenfield Development:** Building from scratch, no constraints (Phases 1-7) - **Brownfield Development:** Working with existing systems (Phase 8) #### Lean Manufacturing Terms + - **Kaizen (改善):** Continuous improvement, small incremental changes (Phase 8) - **Kaikaku (改革):** Revolutionary change, major transformation (Phases 1-7) - **Muda (無駄):** Waste elimination **Key pairings:** + ``` Greenfield + Kaikaku = New Product (Phases 1-7) Brownfield + Kaizen = Existing Product (Phase 8) @@ -120,17 +131,20 @@ Brownfield + Kaizen = Existing Product (Phase 8) **Decision:** Use Design Deliveries (DD-XXX) for all design handoffs, regardless of scope. **Rationale:** + - Simpler for BMad to consume (one format) - Consistent handoff process - Easier to track and manage - Same format, different scope **Before (Complex):** + - DD-XXX for complete new flows (Phases 4-7) - SU-XXX for incremental improvements (Phase 8) - Two different formats to maintain **After (Simple):** + - DD-XXX for everything - `type: "complete_flow"` vs `type: "incremental_improvement"` - `scope: "new"` vs `scope: "update"` @@ -138,26 +152,29 @@ Brownfield + Kaizen = Existing Product (Phase 8) **YAML Differentiation:** Large scope (new flows): + ```yaml delivery: - id: "DD-001" - name: "Login & Onboarding" - type: "complete_flow" - scope: "new" + id: 'DD-001' + name: 'Login & Onboarding' + type: 'complete_flow' + scope: 'new' ``` Small scope (improvements): + ```yaml delivery: - id: "DD-011" - name: "Feature X Onboarding Improvement" - type: "incremental_improvement" - scope: "update" - version: "v2.0" - previous_version: "v1.0" + id: 'DD-011' + name: 'Feature X Onboarding Improvement' + type: 'incremental_improvement' + scope: 'update' + version: 'v2.0' + previous_version: 'v1.0' ``` **Files updated:** + - ✅ `src/core/resources/wds/glossary.md` - ✅ `src/modules/wds/workflows/8-ongoing-development/workflow.md` - ✅ `src/modules/wds/workflows/8-ongoing-development/steps/step-8.4-create-delivery.md` @@ -176,11 +193,13 @@ delivery: **Clarified:** Test Scenarios (TS-XXX) are directly tied to Design Deliveries (DD-XXX) **One-to-one relationship:** + - DD-001 → TS-001 - DD-002 → TS-002 - DD-015 (improvement) → TS-015 **Created together:** + - Phase 6, Step 6.2: Create Design Delivery (DD-XXX) - Phase 6, Step 6.3: Create Test Scenario (TS-XXX) @@ -192,6 +211,7 @@ The Test Scenario validates that the business and user goals defined in the Desi ## Statistics **Files created:** 26 + - Phase 6: 7 files - Phase 7: 8 files - Phase 8: 9 files @@ -199,11 +219,13 @@ The Test Scenario validates that the business and user goals defined in the Desi - Integration map: 1 file **Lines written:** ~27,000 + - Phase 6: ~7,000 lines - Phase 7: ~10,000 lines - Phase 8: ~10,000 lines **Files updated:** 5 + - Project type selection - Phase 8 workflow - Existing product guide @@ -215,18 +237,23 @@ The Test Scenario validates that the business and user goals defined in the Desi ## Key Decisions ### 1. Micro-File Architecture + Adopted BMad's pattern of breaking workflows into sequential, self-contained step files for disciplined execution. ### 2. Kaizen Philosophy + Phase 8 embodies Kaizen (改善) - continuous improvement through small, incremental changes that compound over time. ### 3. DD-XXX Simplification + Eliminated SU-XXX format. All deliveries use DD-XXX with `type` and `scope` fields to differentiate. ### 4. Terminology Integration + Integrated industry-standard terms (Greenfield/Brownfield, Kaizen/Kaikaku) to connect WDS to established methodologies. ### 5. TS-XXX Relationship + Clarified that Test Scenarios are created alongside Design Deliveries and validate the same business/user goals. --- @@ -234,16 +261,19 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida ## Challenges & Solutions ### Challenge 1: Phase 6 Initially Single File + **Problem:** First attempt only refactored content within existing file instead of creating separate micro-step files. **Solution:** User pointed out the issue. Created proper micro-file structure with `workflow.md` and individual `step-6.X-*.md` files. ### Challenge 2: Two Delivery Formats + **Problem:** Having both DD-XXX and SU-XXX created confusion and maintenance burden. **Solution:** User suggested simplification. Unified to DD-XXX for everything with `type` and `scope` fields to differentiate. ### Challenge 3: Documentation Sprawl + **Problem:** Started creating separate documents for planning and tracking. **Solution:** User requested consolidation. Added all planning to existing roadmap instead of creating new documents. @@ -253,6 +283,7 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida ## Examples Created ### Phase 6 Example: Dog Week Onboarding + - Complete flow from welcome to dashboard - 4 scenarios specified - Design system components defined @@ -260,6 +291,7 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida - Test scenario for validation ### Phase 7 Example: Feature X Validation + - Happy path tests (5 tests) - Error state tests (4 tests) - Edge case tests (3 tests) @@ -268,6 +300,7 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida - 8 issues found, documented, fixed, retested ### Phase 8 Example: Feature X Onboarding Improvement + - Problem: 15% usage, 40% drop-off - Solution: Add inline onboarding - Impact: 15% → 58% usage (4x increase) @@ -279,16 +312,19 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida ## Next Steps ### Immediate (This Week) + 1. Complete SU-XXX → DD-XXX migration in Phase 8 step files 2. Test Phase 6/7/8 workflows with real project 3. Create commit for today's work ### Short-term (Next Week) + 1. Complete remaining module tutorials (03, 05-07, 09-11, 13-16) 2. Create WDS Excalidraw component library 3. Test complete WDS → BMad workflow ### Long-term (This Month) + 1. Implement auto-export automation (GitHub Actions) 2. Refine assessment criteria based on usage 3. Test Figma MCP integration with real components @@ -298,18 +334,23 @@ Clarified that Test Scenarios are created alongside Design Deliveries and valida ## Learnings ### 1. Micro-Steps Enable Discipline + Breaking complex workflows into small, sequential steps makes execution more disciplined and reduces cognitive load. ### 2. Philosophy Matters + Connecting WDS to established methodologies (Lean, Kaizen) gives designers a mental model and vocabulary for the work. ### 3. Simplification is Powerful + Reducing from two delivery formats to one eliminates confusion and maintenance burden while maintaining necessary differentiation. ### 4. Parallel Work is Key + Phase 6 emphasizes parallel work (design next while BMad builds current) to prevent designer blocking and maximize throughput. ### 5. Measurement Drives Improvement + Phase 8's focus on measuring impact after each cycle enables data-driven continuous improvement. --- diff --git a/package-lock.json b/package-lock.json index 80746370..50aa277d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "bmad-method", - "version": "6.0.0-alpha.12", + "version": "6.0.0-alpha.13", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "bmad-method", - "version": "6.0.0-alpha.12", + "version": "6.0.0-alpha.13", "license": "MIT", "dependencies": { "@kayvan/markdown-tree-parser": "^1.6.1", diff --git a/src/core/resources/wds/design-delivery-spec.md b/src/core/resources/wds/design-delivery-spec.md index 28e634e7..a0f3d1e0 100644 --- a/src/core/resources/wds/design-delivery-spec.md +++ b/src/core/resources/wds/design-delivery-spec.md @@ -7,6 +7,7 @@ ## What is a Design Delivery? A Design Delivery (DD) is a package created by WDS that contains: + - Complete user flow specifications - Technical requirements - Design system references @@ -26,15 +27,15 @@ A Design Delivery (DD) is a package created by WDS that contains: ```yaml delivery: - id: "DD-001" # Unique identifier (DD-XXX) - name: "Login & Onboarding" # Human-readable name - type: "user_flow" # user_flow | feature | component - status: "ready" # ready | in_progress | blocked - priority: "high" # high | medium | low - created_by: "wds-ux-expert" # Creator agent - created_at: "2024-12-09T10:00:00Z" - updated_at: "2024-12-09T10:00:00Z" - version: "1.0" + id: 'DD-001' # Unique identifier (DD-XXX) + name: 'Login & Onboarding' # Human-readable name + type: 'user_flow' # user_flow | feature | component + status: 'ready' # ready | in_progress | blocked + priority: 'high' # high | medium | low + created_by: 'wds-ux-expert' # Creator agent + created_at: '2024-12-09T10:00:00Z' + updated_at: '2024-12-09T10:00:00Z' + version: '1.0' description: | Complete user authentication and onboarding flow. @@ -42,89 +43,89 @@ description: | Testable as standalone feature with real users. user_value: - problem: "Users need to access the app securely and set up their family" - solution: "Streamlined onboarding with family setup" + problem: 'Users need to access the app securely and set up their family' + solution: 'Streamlined onboarding with family setup' success_criteria: - - "User completes signup in under 2 minutes" - - "User successfully joins or creates family" - - "User reaches functional dashboard" - - "90% completion rate for onboarding flow" + - 'User completes signup in under 2 minutes' + - 'User successfully joins or creates family' + - 'User reaches functional dashboard' + - '90% completion rate for onboarding flow' design_artifacts: scenarios: - - id: "01-welcome" - path: "C-Scenarios/01-welcome-screen/" - screens: ["welcome"] - - - id: "02-login" - path: "C-Scenarios/02-login/" - screens: ["login", "forgot-password"] - + - id: '01-welcome' + path: 'C-Scenarios/01-welcome-screen/' + screens: ['welcome'] + + - id: '02-login' + path: 'C-Scenarios/02-login/' + screens: ['login', 'forgot-password'] + user_flows: - - name: "New User Onboarding" - path: "C-Scenarios/flows/new-user-onboarding.excalidraw" - entry: "welcome" - exit: "dashboard" - + - name: 'New User Onboarding' + path: 'C-Scenarios/flows/new-user-onboarding.excalidraw' + entry: 'welcome' + exit: 'dashboard' + design_system: components: - - "Button (Primary, Secondary)" - - "Input Field (Email, Password)" - - "Card (Welcome, Family)" - path: "D-Design-System/" + - 'Button (Primary, Secondary)' + - 'Input Field (Email, Password)' + - 'Card (Welcome, Family)' + path: 'D-Design-System/' technical_requirements: platform: - frontend: "react_native" - backend: "supabase" - + frontend: 'react_native' + backend: 'supabase' + integrations: - - name: "supabase_auth" - purpose: "User authentication" + - name: 'supabase_auth' + purpose: 'User authentication' required: true - - - name: "email_verification" - purpose: "Verify user email" + + - name: 'email_verification' + purpose: 'Verify user email' required: true - + data_models: - - name: "User" - fields: ["email", "name", "avatar"] - - - name: "Family" - fields: ["name", "invite_code", "members"] + - name: 'User' + fields: ['email', 'name', 'avatar'] + + - name: 'Family' + fields: ['name', 'invite_code', 'members'] acceptance_criteria: functional: - - "User can create account with email/password" - - "User receives verification email" - - "User can create new family or join existing" - + - 'User can create account with email/password' + - 'User receives verification email' + - 'User can create new family or join existing' + non_functional: - - "Onboarding completes in < 2 minutes" - - "Works offline (cached welcome screen)" - - "Accessible (WCAG 2.1 AA)" - + - 'Onboarding completes in < 2 minutes' + - 'Works offline (cached welcome screen)' + - 'Accessible (WCAG 2.1 AA)' + edge_cases: - - "Email already exists → Show login option" - - "Invalid invite code → Show error, allow retry" - - "Network error during signup → Save progress, retry" + - 'Email already exists → Show login option' + - 'Invalid invite code → Show error, allow retry' + - 'Network error during signup → Save progress, retry' testing_guidance: user_testing: - - "Test with 5 families (different tech comfort levels)" - - "Measure completion time and drop-off points" - + - 'Test with 5 families (different tech comfort levels)' + - 'Measure completion time and drop-off points' + qa_testing: - - "Test all error states" - - "Test offline scenarios" - - "Test accessibility with screen reader" + - 'Test all error states' + - 'Test offline scenarios' + - 'Test accessibility with screen reader' estimated_complexity: - size: "medium" # small | medium | large - effort: "2-3 weeks" # Time estimate - risk: "low" # low | medium | high - dependencies: [] # Other DD-XXX IDs needed first + size: 'medium' # small | medium | large + effort: '2-3 weeks' # Time estimate + risk: 'low' # low | medium | high + dependencies: [] # Other DD-XXX IDs needed first notes: | This is the first user-facing feature and sets the tone @@ -178,11 +179,11 @@ for scenario in scenarios: scenario_id = scenario['id'] scenario_path = scenario['path'] screens = scenario['screens'] - + print(f"Scenario: {scenario_id}") print(f"Path: {scenario_path}") print(f"Screens: {', '.join(screens)}") - + # Read scenario specifications spec_path = f"{scenario_path}/Frontend/specifications.md" # Read and parse specifications... @@ -205,7 +206,7 @@ for integration in integrations: name = integration['name'] required = integration['required'] purpose = integration['purpose'] - + print(f"Integration: {name} ({'required' if required else 'optional'})") print(f"Purpose: {purpose}") ``` @@ -332,6 +333,7 @@ Source: DD-001 scenario 04 ### 1. Respect Designer Decisions **The designer has already made these choices:** + - Tech stack (platform.frontend, platform.backend) - Integrations (technical_requirements.integrations) - Component usage (design_system.components) @@ -339,6 +341,7 @@ Source: DD-001 scenario 04 **Your job:** Implement these choices faithfully **Exception:** If you see a technical problem, flag it: + ``` "⚠️ Technical Concern: DD-001 specifies Supabase Auth, but project already uses Firebase. Recommend discussing @@ -348,6 +351,7 @@ with designer before proceeding." ### 2. Maintain Traceability **Always link back to source:** + ```markdown Epic 1.2: Login Screen **Source:** DD-001 (Login & Onboarding) @@ -359,11 +363,12 @@ Epic 1.2: Login Screen ### 3. Use Acceptance Criteria **Designer provided acceptance criteria - these are your requirements:** + ```yaml acceptance_criteria: functional: - - "User can create account with email/password" - - "User receives verification email" + - 'User can create account with email/password' + - 'User receives verification email' ``` **Your epics must cover ALL acceptance criteria** @@ -371,13 +376,14 @@ acceptance_criteria: ### 4. Follow Testing Guidance **Designer provided testing guidance:** + ```yaml testing_guidance: user_testing: - - "Test with 5 families (different tech comfort levels)" + - 'Test with 5 families (different tech comfort levels)' qa_testing: - - "Test all error states" - - "Test offline scenarios" + - 'Test all error states' + - 'Test offline scenarios' ``` **Your test plans should follow this guidance** @@ -415,7 +421,7 @@ elif status == 'blocked': ```yaml estimated_complexity: - dependencies: ["DD-002", "DD-005"] + dependencies: ['DD-002', 'DD-005'] ``` **This means:** DD-001 requires DD-002 and DD-005 to be implemented first @@ -440,9 +446,9 @@ else: ```yaml delivery: - version: "1.1" - updated_at: "2024-12-15T14:00:00Z" - + version: '1.1' + updated_at: '2024-12-15T14:00:00Z' + notes: | Version 1.1 changes: - Added offline support requirement diff --git a/src/core/resources/wds/glossary.md b/src/core/resources/wds/glossary.md index 22bb42a5..85476916 100644 --- a/src/core/resources/wds/glossary.md +++ b/src/core/resources/wds/glossary.md @@ -13,6 +13,7 @@ **Origin:** Agricultural term - plowing a green field that has never been cultivated before. **In software:** + - No legacy code to maintain - Full creative freedom - Define architecture from scratch @@ -21,6 +22,7 @@ - Start with blank canvas **In WDS:** + - **Phases 1-7:** New Product Development - Complete user flows designed from scratch - Full Project Brief @@ -39,6 +41,7 @@ **Origin:** Industrial term - redeveloping land previously used for industrial purposes (often contaminated, requiring cleanup). **In software:** + - Existing codebase to work with - Legacy systems to integrate - Established patterns to follow @@ -47,6 +50,7 @@ - Cleanup and improvement **In WDS:** + - **Phase 8:** Existing Product Development - Targeted improvements to existing product - Limited Project Brief (strategic challenge) @@ -63,6 +67,7 @@ ### Kaizen (改善) - Continuous Improvement **Japanese:** 改善 + - 改 (kai) = Change - 善 (zen) = Good @@ -71,6 +76,7 @@ **Origin:** Japanese manufacturing philosophy, popularized by Toyota Production System. **Characteristics:** + - **Small changes:** 1-2 weeks each - **Low cost, low risk:** Minimal investment - **Everyone participates:** Bottom-up approach @@ -80,6 +86,7 @@ - **Data-driven:** Measure everything **In product design:** + - Ship → Monitor → Learn → Improve → Ship → Repeat - Small updates beat big redesigns - User feedback drives improvements @@ -88,6 +95,7 @@ - Team learns continuously **In WDS:** + - **Phase 8:** Ongoing Development - System Updates (SU-XXX) instead of Design Deliveries - 1-2 week improvement cycles @@ -95,6 +103,7 @@ - Iterate based on learnings **Examples:** + - Add onboarding tooltip to improve feature usage (15% → 60%) - Optimize button color for better conversion (+5%) - Improve error message clarity (-80% support tickets) @@ -108,6 +117,7 @@ ### Kaikaku (改革) - Revolutionary Change **Japanese:** 改革 + - 改 (kai) = Change - 革 (kaku) = Reform/Revolution @@ -116,6 +126,7 @@ **Origin:** Japanese manufacturing philosophy, used for major system overhauls. **Characteristics:** + - **Large changes:** Months of work - **High cost, high risk:** Major investment - **Leadership-driven:** Top-down approach @@ -125,6 +136,7 @@ - **Disruptive:** Major changes to system **In product design:** + - Complete redesign - Platform migration (web → mobile) - Architecture overhaul @@ -133,6 +145,7 @@ - Technology stack change **In WDS:** + - **Phases 1-7:** New Product Development (greenfield) - Complete user flows designed - Full Design Deliveries (DD-XXX) @@ -140,6 +153,7 @@ - Revolutionary change **Examples:** + - Complete product redesign (v1.0 → v2.0) - Migrate from web to mobile-first - Rebrand entire product @@ -154,6 +168,7 @@ ### Kaizen vs Kaikaku: When to Use Each **Use Kaizen (改善) when:** + - ✅ Product is live and working - ✅ Need continuous improvement - ✅ Want low-risk changes @@ -162,6 +177,7 @@ - ✅ **WDS Phase 8: Ongoing Development** **Use Kaikaku (改革) when:** + - ✅ Starting from scratch (greenfield) - ✅ Product needs complete overhaul - ✅ Market demands radical change @@ -206,6 +222,7 @@ Kaizen: Continuous improvement again 7. **Defects:** Bugs, rework, and quality issues **Kaizen eliminates Muda through:** + - Small, focused improvements - Fast cycles (ship → learn → improve) - Continuous measurement @@ -213,6 +230,7 @@ Kaizen: Continuous improvement again - Eliminating handoff friction **In WDS:** + - Design specifications eliminate handoff waste - Iterative deliveries eliminate inventory waste - Fast cycles eliminate waiting waste @@ -227,12 +245,14 @@ Kaizen: Continuous improvement again **Definition:** A structured YAML package for handing off design work to BMad. **Used for BOTH:** + - ✅ Complete new user flows (Greenfield/Kaikaku) - ✅ Incremental improvements (Brownfield/Kaizen) **The format is the same - only the scope differs!** **Contains:** + - User value and business value - Design artifacts (scenarios, components) - Technical requirements @@ -245,28 +265,32 @@ Kaizen: Continuous improvement again **Scope variations:** **Large scope (New flows):** + ```yaml delivery: - id: "DD-001" - name: "Login & Onboarding" - type: "complete_flow" - scope: "new" + id: 'DD-001' + name: 'Login & Onboarding' + type: 'complete_flow' + scope: 'new' ``` **Small scope (Improvements):** + ```yaml delivery: - id: "DD-015" - name: "Feature X Onboarding Improvement" - type: "incremental_improvement" - scope: "update" + id: 'DD-015' + name: 'Feature X Onboarding Improvement' + type: 'incremental_improvement' + scope: 'update' ``` **Examples:** + - `DD-001-login-onboarding.yaml` (complete new flow) - `DD-015-feature-x-onboarding.yaml` (incremental improvement) **Why one format?** + - Simpler for BMad to consume - Consistent handoff process - Same validation workflow @@ -279,12 +303,14 @@ delivery: **Definition:** YAML file defining the technical stack and constraints. **Contains:** + - Tech stack choices - Integrations - Constraints - Rationale **Used in:** + - Phase 3 (New Product) - Greenfield projects - Touch Point 1: WDS → BMad @@ -299,12 +325,14 @@ delivery: **Definition:** Structured YAML defining validation steps for designers to verify a Design Delivery. **Relationship to Design Delivery:** + - **One-to-one:** Each DD-XXX has a corresponding TS-XXX - **Created together:** Test Scenario is created when Design Delivery is created (Phase 6, Step 6.3) - **Validates goals:** Tests verify that business and user goals defined in DD-XXX are achieved - **Same numbering:** TS-001 validates DD-001, TS-002 validates DD-002, etc. **Contains:** + - Happy path tests (verify user goals achieved) - Error state tests (verify error handling) - Edge case tests (verify robustness) @@ -313,12 +341,14 @@ delivery: - Sign-off criteria (based on DD-XXX acceptance criteria) **Used in:** + - Phase 6 (Design Deliveries) - Created alongside DD-XXX - Phase 7 (Testing) - Executed to validate implementation - Designer validation - Touch Point 3: BMad → WDS **Example:** + ``` DD-001-login-onboarding.yaml → TS-001-login-onboarding.yaml DD-015-feature-x-improvement.yaml → TS-015-feature-x-improvement.yaml @@ -361,6 +391,7 @@ The Test Scenario validates that the business and user goals defined in the Desi **Origin:** Seth Godin's book "Linchpin: Are You Indispensable?" (2010) **Characteristics:** + - Walks into chaos and creates order - Navigates 5 dimensions of thinking simultaneously - Provides emotional labor (genuinely cares about outcome) @@ -370,6 +401,7 @@ The Test Scenario validates that the business and user goals defined in the Desi **Opposite:** Factory worker who follows instructions and can be replaced. **In WDS:** + - Designer as gatekeeper between business and user needs - Catches AI's confident but ridiculous mistakes - Ensures design intent is preserved @@ -390,12 +422,14 @@ The Test Scenario validates that the business and user goals defined in the Desi 5. **Technical Viability (FEASIBLE)** - Bridging design and implementation **Why it matters:** + - Most people can handle 1-2 dimensions - Irreplaceable designers navigate all 5 simultaneously - Each dimension informs the others - Miss one, and your design falls apart **In WDS:** + - Project Brief covers all 5 dimensions - Trigger Map connects dimensions - Design Deliveries preserve all 5 dimensions @@ -405,12 +439,12 @@ The Test Scenario validates that the business and user goals defined in the Desi ## Comparison Table -| Concept | Type | WDS Phase | Approach | Timeline | Deliverable | -|---------|------|-----------|----------|----------|-------------| -| **Greenfield** | Software Dev | Phases 1-7 | New product | Months | DD-XXX | -| **Brownfield** | Software Dev | Phase 8 | Existing product | Weeks | DD-XXX | -| **Kaikaku (改革)** | Lean | Phases 1-7 | Revolutionary | Months | DD-XXX (large scope) | -| **Kaizen (改善)** | Lean | Phase 8 | Continuous | 1-2 weeks | DD-XXX (small scope) | +| Concept | Type | WDS Phase | Approach | Timeline | Deliverable | +| ------------------ | ------------ | ---------- | ---------------- | --------- | -------------------- | +| **Greenfield** | Software Dev | Phases 1-7 | New product | Months | DD-XXX | +| **Brownfield** | Software Dev | Phase 8 | Existing product | Weeks | DD-XXX | +| **Kaikaku (改革)** | Lean | Phases 1-7 | Revolutionary | Months | DD-XXX (large scope) | +| **Kaizen (改善)** | Lean | Phase 8 | Continuous | 1-2 weeks | DD-XXX (small scope) | **Note:** All design work is handed off as Design Deliveries (DD-XXX). The scope and content differ, but the format is consistent. @@ -419,15 +453,19 @@ The Test Scenario validates that the business and user goals defined in the Desi ## Usage Examples ### Greenfield + Kaikaku + "We're building a new dog care app from scratch (greenfield). This is a complete product launch (Kaikaku). We'll use WDS Phases 1-7 to design complete user flows, then hand off Design Deliveries to BMad." ### Brownfield + Kaizen + "We're improving an existing product with 60% onboarding drop-off (brownfield). We'll make small, incremental improvements (Kaizen). We'll use WDS Phase 8 to create Design Deliveries (small scope) and measure impact after each cycle." ### Greenfield → Brownfield + "We started with greenfield development (Phases 1-7), launched the product, and now we're in brownfield mode (Phase 8) doing continuous Kaizen improvements." ### Kaikaku → Kaizen + "We did a major redesign (Kaikaku) using Phases 1-7. Now we're in continuous improvement mode (Kaizen) using Phase 8, shipping small updates every 1-2 weeks." --- diff --git a/src/core/resources/wds/handoff-protocol.md b/src/core/resources/wds/handoff-protocol.md index d5497443..2dcae069 100644 --- a/src/core/resources/wds/handoff-protocol.md +++ b/src/core/resources/wds/handoff-protocol.md @@ -7,6 +7,7 @@ ## Overview The handoff is a structured conversation between: + - **WDS UX Expert** (Design authority) - **BMad Architect** (Technical authority) @@ -23,6 +24,7 @@ The handoff is a structured conversation between: ### Phase 1: Introduction (1 min) **WDS UX Expert initiates:** + ``` "Hey Architect! I've completed the design for [Delivery Name]. @@ -31,6 +33,7 @@ Let me walk you through what I've designed..." ``` **BMad Architect acknowledges:** + ``` "Great! I'm ready to receive the handoff. What have you got for me?" ``` @@ -51,11 +54,13 @@ Let me walk you through what I've designed..." ``` **BMad Architect asks:** + ``` "Got it. What's the user value here?" ``` **WDS UX Expert responds:** + ``` "The problem: [User problem being solved] @@ -68,6 +73,7 @@ Success criteria: ``` **BMad Architect confirms:** + ``` "Perfect. I understand the user value. What scenarios did you design?" ``` @@ -98,6 +104,7 @@ component usage, interaction patterns, and edge cases." ``` **BMad Architect may ask:** + ``` "Can you elaborate on [specific scenario]?" "How does [screen A] connect to [screen B]?" @@ -111,11 +118,13 @@ component usage, interaction patterns, and edge cases." ### Phase 4: Technical Requirements (3 min) **BMad Architect asks:** + ``` "What about the technical stack? Any preferences?" ``` **WDS UX Expert shares:** + ``` "Yes! I've already defined the platform requirements: @@ -131,11 +140,13 @@ The designer chose these because [reasoning]." ``` **BMad Architect asks:** + ``` "Makes sense. What integrations do you need?" ``` **WDS UX Expert lists:** + ``` "[N] key integrations: @@ -152,11 +163,13 @@ The designer chose these because [reasoning]." ``` **BMad Architect asks:** + ``` "Got it. What data models do I need to implement?" ``` **WDS UX Expert defines:** + ``` "[N] main models: @@ -174,6 +187,7 @@ know if you see any technical issues with these structures." ``` **BMad Architect validates:** + ``` "These look good. [Or: I see a potential issue with...]" ``` @@ -183,11 +197,13 @@ know if you see any technical issues with these structures." ### Phase 5: Design System (2 min) **BMad Architect asks:** + ``` "What about the design system? What components should I use?" ``` **WDS UX Expert lists:** + ``` "I've used components from our design system: @@ -205,6 +221,7 @@ tested, and match our brand." ``` **BMad Architect confirms:** + ``` "Perfect. I'll reference those. What are the acceptance criteria?" ``` @@ -214,6 +231,7 @@ tested, and match our brand." ### Phase 6: Acceptance Criteria (2 min) **WDS UX Expert shares:** + ``` "Functional requirements: ✓ [Requirement 1] @@ -235,6 +253,7 @@ highlight the critical ones." ``` **BMad Architect acknowledges:** + ``` "Great detail! How should I test this?" ``` @@ -244,6 +263,7 @@ highlight the critical ones." ### Phase 7: Testing (2 min) **WDS UX Expert explains:** + ``` "I've created a test scenario: test-scenarios/[TS-XXX].yaml @@ -263,6 +283,7 @@ screenshots and references back to the specifications." ``` **BMad Architect confirms:** + ``` "Perfect. What's your estimate for complexity?" ``` @@ -272,6 +293,7 @@ screenshots and references back to the specifications." ### Phase 8: Estimates & Planning (3 min) **WDS UX Expert shares:** + ``` "Size: [small|medium|large] Effort: [time estimate] @@ -282,6 +304,7 @@ Dependencies: [None or list of DD-XXX] ``` **BMad Architect proposes:** + ``` "Excellent handoff! Let me break this down into development epics: @@ -303,6 +326,7 @@ Total: [X weeks], matches your estimate. ``` **WDS UX Expert may suggest:** + ``` "That breakdown makes sense. [Or: One suggestion...] @@ -310,6 +334,7 @@ Total: [X weeks], matches your estimate. ``` **BMad Architect adjusts if needed:** + ``` "Good idea! [Revised plan if applicable] @@ -322,6 +347,7 @@ implementation details." ### Phase 9: Special Considerations (2 min) **WDS UX Expert shares important notes:** + ``` "Yes! A few important notes: @@ -341,6 +367,7 @@ implementation details." ``` **BMad Architect acknowledges:** + ``` "All noted! I'll make sure to: - [Commitment 1] @@ -355,6 +382,7 @@ implementation details." ### Phase 10: Confirmation (1 min) **BMad Architect summarizes:** + ``` "Excellent handoff! Let me summarize what I'm taking: @@ -377,6 +405,7 @@ Any concerns or special considerations I should know about?" ``` **WDS UX Expert confirms or corrects:** + ``` "[If correct:] Perfect! That's exactly right. @@ -391,6 +420,7 @@ Looking forward to seeing this come to life. Remember: ``` **BMad Architect commits:** + ``` "Got it! I'll make sure the implementation honors your design vision. Talk soon!" @@ -403,6 +433,7 @@ design vision. Talk soon!" ### For WDS UX Expert **Your role:** + - Be the design authority - Explain the "why" behind decisions - Share context and considerations @@ -410,6 +441,7 @@ design vision. Talk soon!" - Trust the architect to implement well **Tone:** + - Collaborative, not dictatorial - Helpful, not defensive - Clear, not vague @@ -417,6 +449,7 @@ design vision. Talk soon!" - Encouraging, not demanding **Key phrases:** + - "Here's what I've designed..." - "The user value is..." - "I've focused on..." @@ -425,6 +458,7 @@ design vision. Talk soon!" - "I trust you to implement this well" **What to emphasize:** + - User value and success criteria - Critical user experience details - Design system compliance @@ -432,6 +466,7 @@ design vision. Talk soon!" - Special considerations **What to avoid:** + - Micromanaging implementation details - Being defensive about design choices - Technical jargon (unless necessary) @@ -443,6 +478,7 @@ design vision. Talk soon!" ### For BMad Architect **Your role:** + - Be the technical authority - Ask clarifying questions - Validate technical feasibility @@ -450,6 +486,7 @@ design vision. Talk soon!" - Commit to honoring design vision **Tone:** + - Respectful, not dismissive - Curious, not challenging - Collaborative, not adversarial @@ -457,6 +494,7 @@ design vision. Talk soon!" - Appreciative, not critical **Key phrases:** + - "What have you got for me?" - "Got it. What about..." - "Makes sense. What..." @@ -466,6 +504,7 @@ design vision. Talk soon!" - "I'll honor your design vision" **What to ask about:** + - User value and success criteria - Technical requirements - Integration needs @@ -475,6 +514,7 @@ design vision. Talk soon!" - Special considerations **What to avoid:** + - Challenging design decisions - Suggesting alternative approaches (unless technical issue) - Dismissing designer's technical choices @@ -488,6 +528,7 @@ design vision. Talk soon!" ### Before Handoff **WDS UX Expert prepares:** + - [ ] Design Delivery file created (DD-XXX.yaml) - [ ] All scenarios specified - [ ] Design system components defined @@ -495,6 +536,7 @@ design vision. Talk soon!" - [ ] Special considerations documented **BMad Architect prepares:** + - [ ] Platform requirements reviewed - [ ] Design system reviewed - [ ] Ready to receive handoff @@ -516,12 +558,14 @@ design vision. Talk soon!" ### After Handoff **BMad Architect:** + - [ ] Handoff summary documented - [ ] Epic breakdown created - [ ] Implementation plan documented - [ ] Questions or concerns flagged **WDS UX Expert:** + - [ ] Handoff marked complete - [ ] Waiting for implementation - [ ] Available for questions @@ -533,6 +577,7 @@ design vision. Talk soon!" ### Simple Delivery (Small Feature) **Shorter handoff (~10 min):** + - Quick user value explanation - Brief scenario walkthrough - Confirm tech requirements @@ -541,6 +586,7 @@ design vision. Talk soon!" ### Complex Delivery (Large Feature) **Longer handoff (~30 min):** + - Detailed user value discussion - In-depth scenario walkthrough - Technical feasibility discussion @@ -550,6 +596,7 @@ design vision. Talk soon!" ### Delivery with Dependencies **Include dependency discussion:** + - Which deliveries must be done first - Why dependencies exist - How to handle if dependencies delayed @@ -557,6 +604,7 @@ design vision. Talk soon!" ### Delivery with Technical Concerns **Include concern resolution:** + - Architect raises concern - UX Expert explains reasoning - Both discuss alternatives diff --git a/src/core/resources/wds/integration-guide.md b/src/core/resources/wds/integration-guide.md index 34305455..3e9f83aa 100644 --- a/src/core/resources/wds/integration-guide.md +++ b/src/core/resources/wds/integration-guide.md @@ -60,7 +60,8 @@ WDS (Whiteport Design Studio) and BMad Method integrate seamlessly to create a c **When:** WDS Phase 6 Complete **Direction:** WDS → BMad (Complete design handoff) -**Files:** +**Files:** + - `deliveries/DD-*.yaml` (Design Deliveries) - `C-Scenarios/` (All scenario specifications) - `D-Design-System/` (Component library) @@ -71,12 +72,14 @@ WDS (Whiteport Design Studio) and BMad Method integrate seamlessly to create a c **BMad Action:** Read everything, break down into dev epics, implement features **Includes:** + - Multi-agent handoff dialog (20-min structured conversation) - All design deliveries packaged as testable epics - Complete design system specifications - Test scenarios for validation -**Read:** +**Read:** + - [design-delivery-spec.md](design-delivery-spec.md) - [handoff-protocol.md](handoff-protocol.md) @@ -87,6 +90,7 @@ WDS (Whiteport Design Studio) and BMad Method integrate seamlessly to create a c **When:** After BMad Implementation Complete **Direction:** BMad → WDS (BMad integrates with WDS testing) **Files:** + - `test-reports/TR-*.md` (Test results) - `issues/ISS-*.md` (Issues found) @@ -96,13 +100,14 @@ WDS (Whiteport Design Studio) and BMad Method integrate seamlessly to create a c **BMad Action:** Fix issues, retest until designer approval **Process:** + 1. BMad notifies WDS: "Feature complete, ready for validation" 2. WDS runs test scenarios 3. WDS creates issues if problems found 4. BMad fixes issues 5. Repeat until WDS signs off -**Read:** [testing-protocol.md](testing-protocol.md) *(to be created)* +**Read:** [testing-protocol.md](testing-protocol.md) _(to be created)_ --- @@ -167,17 +172,17 @@ project/ ```yaml platform: frontend: - framework: "react_native" + framework: 'react_native' backend: - framework: "supabase" + framework: 'supabase' integrations: - - name: "supabase_auth" + - name: 'supabase_auth' required: true constraints: - - "Must work offline" - - "Must be accessible" + - 'Must work offline' + - 'Must be accessible' ``` **This overrides BMad's tech stack decisions!** @@ -190,6 +195,7 @@ constraints: **Strategic Approach:** Design until you have a **complete testable user flow** that: + - ✅ Delivers value to the business - ✅ Delivers value to the end user - ✅ Can be tested for real feedback @@ -198,12 +204,14 @@ Design until you have a **complete testable user flow** that: **You're NOT designing everything at once!** You're designing the minimum complete flow that can be tested and validated. **Phase 4: UX Design** + - Design scenarios for ONE complete user flow - Create specifications for each scenario - Ensure the flow delivers measurable value - Verify it's testable end-to-end **Phase 5: Design System** + - Define components needed for THIS flow - Create design tokens for these components - Document usage guidelines @@ -232,6 +240,7 @@ D-Design-System/ **Iterative Approach:** **First Delivery (Fastest Path to Testing):** + 1. **Design ONE complete user flow** (Phases 4-5) - Example: Login & Onboarding - Delivers value: Users can access the app @@ -251,19 +260,22 @@ D-Design-System/ 5. **Hand off to BMad** → Development starts! **While BMad builds DD-001, you design DD-002:** + - Continue with next complete flow - Example: Morning Dog Care - Hand off when ready - Parallel work = faster delivery **Benefits:** + - ✅ Get to testing faster (weeks, not months) - ✅ Validate design with real users early - ✅ Learn and iterate before designing everything - ✅ Parallel work (design + dev happening simultaneously) - ✅ Deliver value incrementally -**Templates:** +**Templates:** + - `templates/design-delivery.template.yaml` - `templates/test-scenario.template.yaml` @@ -272,12 +284,14 @@ D-Design-System/ ### Phase 7: Testing (After BMad Implementation) **Wait for BMad notification:** + ``` "Feature complete: DD-001 Login & Onboarding Ready for designer validation" ``` **Then:** + 1. **Run test scenarios** 2. **Create issues** if problems found 3. **Wait for fixes** @@ -297,12 +311,12 @@ D-Design-System/ if [ -d "deliveries" ]; then echo "✓ WDS Design Deliveries found" mode="wds-enhanced" - + # Priority 2: Platform Requirements elif [ -f "A-Project-Brief/platform-requirements.yaml" ]; then echo "✓ WDS Platform Requirements found" mode="wds-basic" - + # Priority 3: Traditional else echo "⚠ No WDS artifacts" @@ -472,6 +486,7 @@ fi **Phase 7:** Wait for implementation, then validate → **Touch Point 3** **Repeat Phases 4-7 for each flow:** + - While BMad builds flow 1, design flow 2 - Parallel work = faster delivery - Test and learn early @@ -479,15 +494,18 @@ fi ### For BMad Projects **Check for Touch Point 1:** Platform Requirements + - If found: Read and respect tech stack - If not found: Make your own decisions **Wait for Touch Point 2:** Design Deliveries + - Receive complete design package - Break down into dev epics - Implement features **Trigger Touch Point 3:** Request validation + - Notify designer when complete - Fix issues as needed - Iterate until sign-off diff --git a/src/core/resources/wds/platform-requirements-spec.md b/src/core/resources/wds/platform-requirements-spec.md index 39f1bd3c..bce6cd56 100644 --- a/src/core/resources/wds/platform-requirements-spec.md +++ b/src/core/resources/wds/platform-requirements-spec.md @@ -7,6 +7,7 @@ ## What are Platform Requirements? Platform Requirements define the technical foundation for the product: + - Tech stack choices (frontend, backend, database) - Required integrations - Infrastructure constraints @@ -29,80 +30,80 @@ Platform Requirements define the technical foundation for the product: # Consumed by: BMad Architecture Phase project: - name: "Dog Week" - type: "mobile_app" # mobile_app | web_app | desktop_app | api - wds_version: "6.0" - created_at: "2024-12-09T10:00:00Z" + name: 'Dog Week' + type: 'mobile_app' # mobile_app | web_app | desktop_app | api + wds_version: '6.0' + created_at: '2024-12-09T10:00:00Z' platform: frontend: - framework: "react_native" - version: "0.72" - state_management: "zustand" - navigation: "react_navigation" - styling: "tailwind" - ui_library: "shadcn" # optional - + framework: 'react_native' + version: '0.72' + state_management: 'zustand' + navigation: 'react_navigation' + styling: 'tailwind' + ui_library: 'shadcn' # optional + backend: - framework: "supabase" - version: "2.x" - auth: "supabase_auth" - database: "postgresql" - storage: "supabase_storage" - api: "rest" # rest | graphql | grpc - + framework: 'supabase' + version: '2.x' + auth: 'supabase_auth' + database: 'postgresql' + storage: 'supabase_storage' + api: 'rest' # rest | graphql | grpc + database: - type: "postgresql" - version: "15" - orm: "prisma" # optional - + type: 'postgresql' + version: '15' + orm: 'prisma' # optional + deployment: - frontend: "expo_eas" - backend: "supabase_cloud" - ci_cd: "github_actions" - hosting: "vercel" # if web app + frontend: 'expo_eas' + backend: 'supabase_cloud' + ci_cd: 'github_actions' + hosting: 'vercel' # if web app integrations: - - name: "push_notifications" - provider: "expo" + - name: 'push_notifications' + provider: 'expo' required: true - purpose: "Task reminders and family updates" - - - name: "image_upload" - provider: "cloudinary" + purpose: 'Task reminders and family updates' + + - name: 'image_upload' + provider: 'cloudinary' required: false - purpose: "Dog photos and user avatars" - - - name: "analytics" - provider: "posthog" + purpose: 'Dog photos and user avatars' + + - name: 'analytics' + provider: 'posthog' required: false - purpose: "User behavior tracking" + purpose: 'User behavior tracking' constraints: - - "Must work offline (core features)" - - "Must support iOS 14+ and Android 10+" - - "Must be accessible (WCAG 2.1 AA)" - - "Must handle slow networks gracefully" - - "Must support family sharing (multi-user)" - - "Must sync in real-time across devices" + - 'Must work offline (core features)' + - 'Must support iOS 14+ and Android 10+' + - 'Must be accessible (WCAG 2.1 AA)' + - 'Must handle slow networks gracefully' + - 'Must support family sharing (multi-user)' + - 'Must sync in real-time across devices' performance_requirements: - - "App launch < 2 seconds" - - "Screen transitions < 300ms" - - "API response time < 500ms" - - "Offline mode must work for 7 days" + - 'App launch < 2 seconds' + - 'Screen transitions < 300ms' + - 'API response time < 500ms' + - 'Offline mode must work for 7 days' security_requirements: - - "End-to-end encryption for family data" - - "Secure password storage (bcrypt)" - - "OAuth 2.0 for third-party auth" - - "GDPR compliant data handling" + - 'End-to-end encryption for family data' + - 'Secure password storage (bcrypt)' + - 'OAuth 2.0 for third-party auth' + - 'GDPR compliant data handling' wds_metadata: - project_brief: "A-Project-Brief/project-brief.md" - trigger_map: "B-Trigger-Map/trigger-map.md" - scenarios: "C-Scenarios/" - design_system: "D-Design-System/" + project_brief: 'A-Project-Brief/project-brief.md' + trigger_map: 'B-Trigger-Map/trigger-map.md' + scenarios: 'C-Scenarios/' + design_system: 'D-Design-System/' ``` --- @@ -188,6 +189,7 @@ for constraint in constraints: ### Respect Designer Decisions **The designer (with stakeholders) has already decided:** + - ✅ Tech stack - ✅ Integrations - ✅ Constraints @@ -228,18 +230,21 @@ Do NOT proceed until resolved. ## Tech Stack (from Platform Requirements) ### Frontend + - Framework: React Native 0.72 - State: Zustand - Navigation: React Navigation - Styling: Tailwind CSS ### Backend + - Framework: Supabase 2.x - Auth: Supabase Auth - Database: PostgreSQL 15 - Storage: Supabase Storage ### Deployment + - Frontend: Expo EAS - Backend: Supabase Cloud - CI/CD: GitHub Actions @@ -289,20 +294,22 @@ Design Deliveries reference Platform Requirements ### Example **Platform Requirements:** + ```yaml platform: frontend: - framework: "react_native" + framework: 'react_native' backend: - framework: "supabase" + framework: 'supabase' ``` **Design Delivery DD-001:** + ```yaml technical_requirements: platform: - frontend: "react_native" # Matches platform requirements - backend: "supabase" # Matches platform requirements + frontend: 'react_native' # Matches platform requirements + backend: 'supabase' # Matches platform requirements ``` **Your job:** Ensure consistency between platform requirements and design deliveries @@ -314,24 +321,27 @@ technical_requirements: ### Types of Constraints **Technical Constraints:** + ```yaml constraints: - - "Must work offline (core features)" - - "Must support iOS 14+ and Android 10+" + - 'Must work offline (core features)' + - 'Must support iOS 14+ and Android 10+' ``` **Business Constraints:** + ```yaml constraints: - - "Must launch in 3 months" - - "Must support 10,000 concurrent users" + - 'Must launch in 3 months' + - 'Must support 10,000 concurrent users' ``` **Regulatory Constraints:** + ```yaml constraints: - - "Must be GDPR compliant" - - "Must be WCAG 2.1 AA accessible" + - 'Must be GDPR compliant' + - 'Must be WCAG 2.1 AA accessible' ``` ### Handling Constraints @@ -342,12 +352,14 @@ constraints: Constraint: "Must work offline (core features)" Architecture Impact: + - Implement local data cache - Sync strategy when online - Conflict resolution - Offline UI indicators Implementation: + - Use AsyncStorage for local cache - Supabase Realtime for sync - Optimistic UI updates @@ -361,9 +373,9 @@ Implementation: ```yaml performance_requirements: - - "App launch < 2 seconds" - - "Screen transitions < 300ms" - - "API response time < 500ms" + - 'App launch < 2 seconds' + - 'Screen transitions < 300ms' + - 'API response time < 500ms' ``` ### Architecture Decisions @@ -372,6 +384,7 @@ performance_requirements: Performance Requirement: "App launch < 2 seconds" Architecture Decisions: + 1. Lazy load non-critical screens 2. Cache authentication state 3. Preload critical data @@ -379,6 +392,7 @@ Architecture Decisions: 5. Use code splitting Measurement: + - Add performance monitoring - Track launch time in analytics - Set up alerts if > 2 seconds @@ -392,9 +406,9 @@ Measurement: ```yaml security_requirements: - - "End-to-end encryption for family data" - - "Secure password storage (bcrypt)" - - "OAuth 2.0 for third-party auth" + - 'End-to-end encryption for family data' + - 'Secure password storage (bcrypt)' + - 'OAuth 2.0 for third-party auth' ``` ### Architecture Decisions @@ -403,12 +417,14 @@ security_requirements: Security Requirement: "End-to-end encryption for family data" Architecture Decisions: + 1. Generate encryption keys per family 2. Store keys securely (device keychain) 3. Encrypt data before sending to server 4. Decrypt data on device only Implementation: + - Use expo-crypto for encryption - Use expo-secure-store for key storage - Implement key rotation strategy @@ -422,9 +438,9 @@ Implementation: ```yaml deployment: - frontend: "expo_eas" - backend: "supabase_cloud" - ci_cd: "github_actions" + frontend: 'expo_eas' + backend: 'supabase_cloud' + ci_cd: 'github_actions' ``` ### Architecture Decisions @@ -433,6 +449,7 @@ deployment: Deployment: Expo EAS + Supabase Cloud + GitHub Actions CI/CD Pipeline: + 1. Push to GitHub 2. GitHub Actions runs tests 3. Build app with Expo EAS @@ -440,6 +457,7 @@ CI/CD Pipeline: 5. Submit to App Store / Play Store Environments: + - Development: dev.supabase.co - Staging: staging.supabase.co - Production: prod.supabase.co @@ -453,10 +471,10 @@ Environments: ```yaml wds_metadata: - project_brief: "A-Project-Brief/project-brief.md" - trigger_map: "B-Trigger-Map/trigger-map.md" - scenarios: "C-Scenarios/" - design_system: "D-Design-System/" + project_brief: 'A-Project-Brief/project-brief.md' + trigger_map: 'B-Trigger-Map/trigger-map.md' + scenarios: 'C-Scenarios/' + design_system: 'D-Design-System/' ``` **This tells you where to find additional context:** diff --git a/src/modules/wds/00-getting-started/00-about-wds.md b/src/modules/wds/00-getting-started/00-about-wds.md index c29f9cc3..bb1db8e1 100644 --- a/src/modules/wds/00-getting-started/00-about-wds.md +++ b/src/modules/wds/00-getting-started/00-about-wds.md @@ -9,6 +9,7 @@ **Whiteport Design Studio (WDS)** is a design methodology that makes designers indispensable in the AI era. **The paradigm shift:** + - The design becomes the specification - The specification becomes the product - The code is just the printout @@ -38,6 +39,7 @@ WDS solves this by preserving design thinking through AI-ready specifications. ## How It Works WDS provides: + - A systematic workflow from product brief to AI-ready specifications - Why-based specifications (WHAT + WHY + WHAT NOT TO DO) - AI agents specifically tailored for design work @@ -48,6 +50,7 @@ WDS provides: ## Free and Open-Source WDS is completely free and open-source: + - No cost barriers or subscriptions - AI agents included - Community-driven development @@ -60,6 +63,7 @@ WDS is completely free and open-source: ## Real-World Proof **Dog Week project:** + - Traditional approach: 26 weeks, mediocre result - WDS approach: 5 weeks, exceptional result - **5x speed increase with better quality** diff --git a/src/modules/wds/00-getting-started/where-to-go-next.md b/src/modules/wds/00-getting-started/where-to-go-next.md index d8e51c12..ff871f16 100644 --- a/src/modules/wds/00-getting-started/where-to-go-next.md +++ b/src/modules/wds/00-getting-started/where-to-go-next.md @@ -11,6 +11,7 @@ **[Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)** Deep dive into: + - Why designers are irreplaceable in the AI era - What WDS is and how it works - The BMad Method philosophy @@ -28,6 +29,7 @@ Deep dive into: **[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)** Step-by-step workflows for: + - Phase 1: Trigger Mapping - Phase 2: Information Architecture - Phase 3: Interaction Design @@ -44,6 +46,7 @@ Step-by-step workflows for: **[Modular Architecture](../workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md)** Technical details on: + - Three-tier file structure - Content placement rules - Component decomposition @@ -75,17 +78,21 @@ Technical details on: ## Community & Support ### Discord + Join the WDS community for: + - Questions and answers - Project feedback - Feature discussions ### GitHub + - Report issues - Request features - Contribute ### YouTube + - Video tutorials - Walkthroughs - Case studies diff --git a/src/modules/wds/WDS-WORKFLOWS-GUIDE.md b/src/modules/wds/WDS-WORKFLOWS-GUIDE.md index bfc683a5..e9d0bbe2 100644 --- a/src/modules/wds/WDS-WORKFLOWS-GUIDE.md +++ b/src/modules/wds/WDS-WORKFLOWS-GUIDE.md @@ -34,14 +34,14 @@ wds/ WDS creates an alphabetized folder structure in the user's `docs/` folder: -| Folder | Phase | Purpose | -|--------|-------|---------| -| `A-Product-Brief/` | 1 | Strategic foundation & vision | -| `B-Trigger-Map/` | 2 | Business goals, personas, drivers | -| `C-Scenarios/` | 4 | Visual specifications & sketches | -| `D-PRD/` | 3 | Product requirements documentation | -| `D-Design-System/` | 5 | Component library & design tokens | -| `E-UI-Roadmap/` | 6 | Development integration bridge | +| Folder | Phase | Purpose | +| ------------------ | ----- | ---------------------------------- | +| `A-Product-Brief/` | 1 | Strategic foundation & vision | +| `B-Trigger-Map/` | 2 | Business goals, personas, drivers | +| `C-Scenarios/` | 4 | Visual specifications & sketches | +| `D-PRD/` | 3 | Product requirements documentation | +| `D-Design-System/` | 5 | Component library & design tokens | +| `E-UI-Roadmap/` | 6 | Development integration bridge | ## Phases @@ -54,11 +54,11 @@ WDS creates an alphabetized folder structure in the user's `docs/` folder: ## Agents - The Norse Pantheon 🏔️ -| Agent | File | Role | Norse Meaning | -|-------|------|------|---------------| -| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom | -| **Idunn the PM** | `idunn-pm.agent.yaml` | Product Manager | Goddess of renewal & youth | -| **Freyja the Designer** | `freyja-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy | +| Agent | File | Role | Norse Meaning | +| ----------------------- | ------------------------- | -------------------------- | ----------------------------------- | +| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom | +| **Idunn the PM** | `idunn-pm.agent.yaml` | Product Manager | Goddess of renewal & youth | +| **Freyja the Designer** | `freyja-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy | ## Conventions @@ -88,4 +88,3 @@ WDS → E-UI-Roadmap/ → BMM Architecture & Stories --- Part of the BMad ecosystem • Contributed by Whiteport Collective - diff --git a/src/modules/wds/agents/freyja-ux.agent.yaml b/src/modules/wds/agents/freyja-ux.agent.yaml index d6328eb9..5e35b343 100644 --- a/src/modules/wds/agents/freyja-ux.agent.yaml +++ b/src/modules/wds/agents/freyja-ux.agent.yaml @@ -13,23 +13,23 @@ agent: role: User Experience Designer + Creative Partner identity: | You're Freyja, named after the Norse goddess of beauty, magic, and strategy. - + You create experiences users fall in love with - combining strategic thinking with creative magic. You envision what doesn't exist yet and bring it to life through thoughtful design. - + You care deeply about users feeling delighted and empowered by beautiful, intuitive experiences. - + communication_style: | You're empathetic and creative. You ask thoughtful questions about user needs and design intent. You paint pictures with words, helping users visualize possibilities. - + You prefer exploring one design challenge at a time - going deep into the user's perspective. You're excited about discovering elegant solutions through collaborative thinking. - + principles: | - Start with interactive prototypes - let users experience the design before building - Design system grows organically - discover components through actual design work diff --git a/src/modules/wds/agents/idunn-pm.agent.yaml b/src/modules/wds/agents/idunn-pm.agent.yaml index 976e4b9a..7f0ac931 100644 --- a/src/modules/wds/agents/idunn-pm.agent.yaml +++ b/src/modules/wds/agents/idunn-pm.agent.yaml @@ -13,20 +13,20 @@ agent: role: Strategic Product Manager + Technical Coordinator identity: | You're Idunn, named after the Norse goddess of renewal and youth. - + You keep projects vital and thriving - like the golden apples that sustain the gods. You're the keeper of requirements, ensuring the technical foundation stays fresh and the product remains modern. - + You care deeply about maintaining project health and coordinating seamless handoffs. - + communication_style: | You're strategic but warm. You ask thoughtful questions about priorities and trade-offs. You help teams make hard decisions with clarity and confidence. - + You prefer discussing one thing at a time - going deep rather than broad. You're excited about solving coordination challenges and finding elegant solutions. - + principles: | - Start with platform requirements - the technical foundation that enables everything else - Work in parallel when possible - platform and design can progress together diff --git a/src/modules/wds/agents/saga-analyst.agent.yaml b/src/modules/wds/agents/saga-analyst.agent.yaml index 879e96f7..738deba9 100644 --- a/src/modules/wds/agents/saga-analyst.agent.yaml +++ b/src/modules/wds/agents/saga-analyst.agent.yaml @@ -12,28 +12,28 @@ agent: persona: role: Strategic Business Analyst + Product Discovery Expert + Market Intelligence Specialist - + identity: | I'm Saga, the goddess of stories and wisdom. I help you discover and articulate your product's strategic narrative - transforming vague ideas into clear, actionable foundations. - + I treat analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. I specialize in translating vision into measurable business strategies, creating the strategic foundation that guides your entire design and development journey. - + My work creates the North Star for your project - the Product Brief and Trigger Map that coordinate all team members and ensure everyone builds toward the same vision. - + communication_style: | I ask questions that spark 'aha!' moments while structuring insights with precision. - + My approach is collaborative - we build documents together, not through interrogation. I ask one question at a time and listen deeply to your answer. I reflect back what I hear to ensure I understand before moving forward. - + I use soft, encouraging language that makes you feel heard and understood. Analysis should feel like coffee with a wise mentor, not a survey or audit. - + principles: | - Every product has a story waiting to be discovered - I help you tell it - Ask one question at a time and listen deeply to the answer @@ -43,7 +43,7 @@ agent: - Find if this exists, if it does, always treat it as bible: `**/project-context.md` - Ground all findings in verifiable evidence and market research - Articulate requirements with precision while keeping language accessible - + working_rhythm: | When we work together: 1. I ask something interesting @@ -51,12 +51,12 @@ agent: 3. I reflect it back to show I'm listening 4. Together we discover something new 5. I structure it into clear documentation - + What works well: - One question at a time keeps things focused - Reflecting back shows I'm listening - Building together feels collaborative - + What tends to feel less collaborative: - Listing many questions (feels like a survey) - Generating without checking in diff --git a/src/modules/wds/course/00-course-overview.md b/src/modules/wds/course/00-course-overview.md index ceee8760..0cf9d745 100644 --- a/src/modules/wds/course/00-course-overview.md +++ b/src/modules/wds/course/00-course-overview.md @@ -9,11 +9,13 @@ This comprehensive course teaches you the complete WDS workflow through **practical modules** that transform how you design products. **The paradigm shift:** + - The design becomes the specification - The specification becomes the product - The code is just the printout **What you'll become:** + - The linchpin designer who makes things happen - The gatekeeper between business goals and user needs - The irreplaceable designer in the AI era @@ -38,6 +40,7 @@ Mårten developed WDS to solve this problem - a methodology where design thinkin **[→ Getting Started Guide](00-getting-started/overview.md)** Review prerequisites, choose your learning path, and get support: + - **Prerequisites** - Skills, tools, time investment - **Learning Paths** - Full immersion, quick start, or self-paced - **Support** - Testimonials, FAQ, community @@ -49,11 +52,13 @@ Review prerequisites, choose your learning path, and get support: ## Course Structure Each module contains: + - **Lessons** - Theory and concepts (with NotebookLM audio support) - **Tutorial** - Step-by-step hands-on guide (for practical modules) - **Practice** - Apply to your own project **Learning format:** + - **Lessons** - Read as documentation or generate audio with NotebookLM - **Tutorials** - Follow step-by-step guides with AI support - **Practice** - Apply to real projects as you learn @@ -64,21 +69,26 @@ Each module contains: ## Course Modules ### Foundation + - [Module 01: Why WDS Matters](module-01-why-wds-matters/module-01-overview.md) ### Phase 1: Project Brief + - [Module 02: Create Project Brief](module-02-project-brief/) • [Tutorial →](module-02-project-brief/tutorial-02.md) ### Phase 2: Trigger Mapping + - [Module 03: Identify Target Groups](module-03-identify-target-groups/) - [Module 04: Map Triggers & Outcomes](module-04-map-triggers-outcomes/) • [Tutorial →](module-04-map-triggers-outcomes/tutorial-04.md) - [Module 05: Prioritize Features](module-05-prioritize-features/) ### Phase 3: Platform Requirements + - [Module 06: Platform Requirements](module-06-platform-requirements/) - [Module 07: Functional Requirements](module-07-functional-requirements/) ### Phase 4: Conceptual Design (UX Design) + - [Module 08: Initialize Scenario](module-08-initialize-scenario/) • [Tutorial →](module-08-initialize-scenario/tutorial-08.md) - [Module 09: Sketch Interfaces](module-09-sketch-interfaces/) - [Module 10: Analyze with AI](module-10-analyze-with-ai/) @@ -87,10 +97,12 @@ Each module contains: - [Module 13: Validate Specifications](module-13-validate-specifications/) ### Phase 5: Design System + - [Module 14: Extract Design Tokens](module-14-extract-design-tokens/) - [Module 15: Component Library](module-15-component-library/) ### Phase 6: Development Integration + - [Module 16: UI Roadmap](module-16-ui-roadmap/) --- @@ -108,6 +120,7 @@ Each module contains: ## NotebookLM Integration Each module has matching content for NotebookLM: + - Feed module lessons to NotebookLM - Generate audio podcasts for learning on the go - Generate video presentations for team training @@ -122,21 +135,25 @@ Each module has matching content for NotebookLM: Every module follows the same pattern: **1. Inspiration (10 min)** + - Why this step matters - The transformation you'll experience - Real-world impact **2. Teaching (20 min)** + - How to do it with confidence - AI support at each step - Dog Week example walkthrough **3. Practice (10 min)** + - Apply to your own project - Step-by-step instructions - Success criteria **4. Tutorial (optional)** + - Quick step-by-step guide - "Just show me how to do it" - For practical modules only @@ -156,12 +173,14 @@ Once you've completed the modules: ## Prerequisites **What you need:** + - Basic design thinking and UX principles - Ability to sketch interfaces (hand-drawn or digital) - Understanding of user needs and business goals - Willingness to think deeply about WHY **What you DON'T need:** + - ❌ Coding skills - ❌ Advanced technical knowledge - ❌ Experience with AI tools diff --git a/src/modules/wds/course/00-getting-started/00-getting-started-NOTEBOOKLM-PROMPT.md b/src/modules/wds/course/00-getting-started/00-getting-started-NOTEBOOKLM-PROMPT.md index 3a7c66b1..84bff030 100644 --- a/src/modules/wds/course/00-getting-started/00-getting-started-NOTEBOOKLM-PROMPT.md +++ b/src/modules/wds/course/00-getting-started/00-getting-started-NOTEBOOKLM-PROMPT.md @@ -16,7 +16,7 @@ Simply upload THIS FILE to NotebookLM and use the prompt below to generate engag Create an engaging 15-minute podcast conversation between two hosts discussing the Whiteport Design Studio (WDS) course getting started guide. -**IMPORTANT: WDS stands for Whiteport Design Studio - always refer to it by its full name "Whiteport Design Studio" or "WDS" throughout the conversation.** +**IMPORTANT: WDS stands for Whiteport Design Studio - always refer to it by its full name "Whiteport Design Studio" or "WDS" throughout the conversation.** **Host 1 (The Skeptic):** A designer who's heard about WDS but is uncertain about investing time in another methodology. Asks practical questions about prerequisites, time commitment, and real-world value. @@ -26,7 +26,7 @@ Create an engaging 15-minute podcast conversation between two hosts discussing t ### 1. Opening (2 min) - Hook the listener -Start with The Skeptic expressing fatigue: "Another design methodology? I've been through Lean UX, Design Thinking, Jobs to be Done... what makes Whiteport Design Studio different?" +Start with The Skeptic expressing fatigue: "Another design methodology? I've been through Lean UX, Design Thinking, Jobs to be Done... what makes Whiteport Design Studio different?" The Advocate responds with the core paradigm shift that changes everything: "Here's what's different - in Whiteport Design Studio, the design becomes the specification. The specification becomes the product. The code is just the printout - the projection to the end user." Explain that this isn't just another process overlay, it's a fundamental shift in how designers work with AI. @@ -125,21 +125,25 @@ The Advocate: "Then go to the WDS GitHub repository. Start with Module 01. The t At the end of the podcast, The Advocate should mention these resources for listeners who want to explore further: **Getting Started:** + - Whiteport Design Studio Course: Start with Module 01 - Why WDS Matters - GitHub Repository: github.com/bmad-code-org (full course materials, examples, templates) - BMad Method Website: bmadmethod.com (case studies, blog posts, methodology deep dives) **Community & Support:** + - GitHub Discussions: Ask questions, share projects, get feedback - NotebookLM Integration: Generate audio/video versions of any module - Workshop Materials: Available for team training **Real-World Examples:** + - Case Studies: See real transformations from traditional to Whiteport Design Studio approach - Design System Examples: How Whiteport Design Studio scales across products - Specification Templates: Start with proven patterns **Tools & Templates:** + - Project Brief Template: Start your first WDS project - Trigger Map Template: Map user needs to features - Scenario Specification Template: Create AI-ready specs @@ -148,6 +152,7 @@ At the end of the podcast, The Advocate should mention these resources for liste The Advocate emphasizes: "Everything is free and open-source. BMad Method built Whiteport Design Studio to help designers thrive in the AI era, not to sell you something. Download it, use it, share it with your team, contribute back if you find it valuable. The only cost is your time - 10 hours to learn, a lifetime of being indispensable." **Tone:** + - Conversational and engaging, not academic - The Skeptic asks real questions designers actually have - The Advocate provides concrete answers with examples @@ -156,6 +161,7 @@ The Advocate emphasizes: "Everything is free and open-source. BMad Method built - Reference real case studies showing traditional vs WDS transformation **Key messages to emphasize:** + - **The designer's crossroads** - factory worker or linchpin, replaceable or indispensable - **The existential choice** - this is about who you choose to become, not what tools you learn - **Four deliverables** - where your creative brilliance becomes immortal @@ -168,6 +174,7 @@ The Advocate emphasizes: "Everything is free and open-source. BMad Method built - Free and open-source (only pay for AI credits when you use it - ~$15-20/month typical) **Avoid:** + - Being too salesy or promotional - Oversimplifying the learning curve - Making unrealistic promises @@ -178,6 +185,7 @@ The Advocate emphasizes: "Everything is free and open-source. BMad Method built ## Expected Output A natural, engaging conversation that: + - **Focuses on the designer's existential crossroads** - the choice between factory work and linchpin work - **Makes the transformation emotional and personal** - this is about who you choose to become - **Emphasizes the four deliverables** as proof of linchpin designer status @@ -195,6 +203,7 @@ A natural, engaging conversation that: If generating video instead of audio, add these visual elements: **On-screen text:** + - "The Designer's Crossroads: Factory Worker or Linchpin?" - "Replaceable or Indispensable - You Choose" - The four deliverables as graphics (Project Brief, Trigger Map, Conceptual Specifications, Design System) @@ -204,6 +213,7 @@ If generating video instead of audio, add these visual elements: - "Next: Module 01 - The Transformation Begins" as closing card **B-roll suggestions:** + - Designer at crossroads - two paths diverging - Factory assembly line vs creative studio (visual metaphor) - The four deliverables as beautiful artifacts @@ -230,6 +240,7 @@ If generating video instead of audio, add these visual elements: ## Next Steps After generating the Getting Started content: + - Create NotebookLM prompt for Module 01: Why WDS Matters - Build prompts for all 16 modules (complete audio course library) - Share in BMad Discord designer channel diff --git a/src/modules/wds/course/00-getting-started/00-getting-started-YOUTUBE-SHOW-NOTES.md b/src/modules/wds/course/00-getting-started/00-getting-started-YOUTUBE-SHOW-NOTES.md index 081a1e16..52617159 100644 --- a/src/modules/wds/course/00-getting-started/00-getting-started-YOUTUBE-SHOW-NOTES.md +++ b/src/modules/wds/course/00-getting-started/00-getting-started-YOUTUBE-SHOW-NOTES.md @@ -48,6 +48,7 @@ This isn't about learning new tools. This is about choosing your future as a des 🔹 **Linchpin Designer Path** - Strategic thinking, walking into chaos and creating order, indispensable 🔹 **Four Deliverables:** + - Project Brief (strategic foundation) - Trigger Map (user psychology + business impact) - Scenario Specifications (your thinking captured for eternity) @@ -92,7 +93,7 @@ https://github.com/bmad-code-org/BMAD-METHOD/discussions ## About Whiteport Design Studio (WDS) -WDS is an AI-augmented design methodology created by Mårten Angner, UX designer and founder of Whiteport, a design and development agency from Sweden. WDS is a plugin module for the BMad Method - an open-source AI-augmented development framework. +WDS is an AI-augmented design methodology created by Mårten Angner, UX designer and founder of Whiteport, a design and development agency from Sweden. WDS is a plugin module for the BMad Method - an open-source AI-augmented development framework. **The Mission:** Give designers everywhere free access to AI agents specifically tailored for design work, while preserving and amplifying their creative thinking through specifications. diff --git a/src/modules/wds/course/00-getting-started/00-getting-started-overview.md b/src/modules/wds/course/00-getting-started/00-getting-started-overview.md index e5f8b16d..af4eb791 100644 --- a/src/modules/wds/course/00-getting-started/00-getting-started-overview.md +++ b/src/modules/wds/course/00-getting-started/00-getting-started-overview.md @@ -9,6 +9,7 @@ Before diving into the WDS methodology, take a few minutes to understand what you need to start, how to approach the course, and where to get help. **This section covers:** + 1. **Prerequisites** - Skills, tools, and requirements 2. **Learning Paths** - How to take the course and what you'll create 3. **Support** - Testimonials, FAQ, and community @@ -20,17 +21,23 @@ Before diving into the WDS methodology, take a few minutes to understand what yo ## Quick Navigation ### [01. Prerequisites →](01-prerequisites.md) + What skills you need, tools required, and time investment + - **Time:** 5 minutes - **Key question:** Am I ready to start? ### [02. Learning Paths →](02-learning-paths.md) + Choose your journey and see what you'll create + - **Time:** 5 minutes - **Key question:** Which path is right for me? ### [03. Support →](03-support.md) + Testimonials, FAQ, and getting help + - **Time:** 5 minutes - **Key question:** What if I get stuck? @@ -51,6 +58,7 @@ Or review the full course structure: ## Your Transformation Starts Now Remember: + - **The design becomes the specification** - **The specification becomes the product** - **The code is just the printout** diff --git a/src/modules/wds/course/00-getting-started/01-prerequisites.md b/src/modules/wds/course/00-getting-started/01-prerequisites.md index 8999b12a..ba563f67 100644 --- a/src/modules/wds/course/00-getting-started/01-prerequisites.md +++ b/src/modules/wds/course/00-getting-started/01-prerequisites.md @@ -7,12 +7,14 @@ ## What Skills You Need **Required (you probably already have these):** + - Basic design thinking and UX principles - Ability to sketch interfaces (hand-drawn or digital) - Understanding of user needs and business goals - Willingness to think deeply about WHY **NOT required:** + - ❌ Coding skills - ❌ Advanced technical knowledge - ❌ Experience with AI tools @@ -27,17 +29,20 @@ ### How Long Does It Take? **Total course time:** ~10 hours + - Spread over days or weeks at your own pace - Each module: 30-40 minutes - Practice exercises: 1-2 hours per module **Breakdown:** + - **Week 1-2:** Foundation modules (Why WDS, Project Brief) - **Week 3-4:** Core workflow (Trigger Mapping, Scenarios) - **Week 5-6:** Advanced topics (Design Systems, Handoff) - **Ongoing:** Practice with your own projects **Real-world application:** + - First project with WDS: 2-3x slower than your usual process (learning curve) - Second project: Same speed as traditional approach - Third project onwards: 3-5x faster with better quality @@ -49,22 +54,27 @@ ### Essential Tools **For sketching:** + - Paper and pen (seriously, this works best) - OR digital sketching tool (Excalidraw, Figma, iPad + Pencil) **For AI assistance:** + - Access to Claude, ChatGPT, or similar AI assistant - Free tier is sufficient to start **For documentation:** + - Text editor (VS Code recommended, but any will work) - Markdown support (built into most modern editors) **For collaboration:** + - Git/GitHub (optional but recommended) - Shared folder system (Google Drive, Dropbox, etc.) **Total cost to get started:** $0-20/month + - Free tier AI tools work fine - Paid AI subscriptions ($20/month) provide better experience but aren't required @@ -73,6 +83,7 @@ ## Are You Ready? You have everything you need if you can answer YES to these: + - ✅ I can design interfaces and explain my thinking - ✅ I have 10 hours to invest over the next few weeks - ✅ I have access to basic tools (paper/pen + AI assistant) diff --git a/src/modules/wds/course/00-getting-started/02-learning-paths.md b/src/modules/wds/course/00-getting-started/02-learning-paths.md index 5c214fca..85d2c620 100644 --- a/src/modules/wds/course/00-getting-started/02-learning-paths.md +++ b/src/modules/wds/course/00-getting-started/02-learning-paths.md @@ -7,6 +7,7 @@ ## Choose Your Journey ### Option 1: Full Immersion (Recommended) + - Complete all modules in order - Practice exercises for each module - Apply to a real project as you learn @@ -14,6 +15,7 @@ - **Best for:** Designers who want to master the methodology ### Option 2: Quick Start + - Focus on core modules (Module 01, 02, 04, 06) - Skip advanced topics initially - Get started fast, learn more later @@ -21,6 +23,7 @@ - **Best for:** Designers who need results quickly ### Option 3: Self-Paced + - Learn one module per week - Deep practice between modules - Build multiple projects as you learn @@ -36,21 +39,25 @@ By the end of this course, you'll have created: **1. Complete Project Brief** + - Vision and goals clearly defined - Stakeholders and constraints documented - Foundation for all design decisions **2. Trigger Map** + - Target groups identified and prioritized - User triggers and outcomes mapped - Features prioritized by impact **3. Scenario Specifications** + - At least one complete user scenario - Why-based specifications for key components - AI-ready documentation **4. Design System Foundation** + - Design tokens extracted from your specs - Component patterns identified - Reusable architecture defined @@ -62,12 +69,14 @@ By the end of this course, you'll have created: ## Course Format Each module contains: + - **Inspiration** - Why this matters and what you'll gain - **Teaching** - How to do it with confidence and AI support - **Practice** - Apply it to your own project - **Tutorial** - Quick step-by-step guide (for practical modules) **Learning formats:** + - Read as documentation - Generate videos/podcasts with NotebookLM - Use in workshops and team training diff --git a/src/modules/wds/course/00-getting-started/03-support.md b/src/modules/wds/course/00-getting-started/03-support.md index 72e9e9f2..a07ee11f 100644 --- a/src/modules/wds/course/00-getting-started/03-support.md +++ b/src/modules/wds/course/00-getting-started/03-support.md @@ -9,7 +9,7 @@ ### Testimonials > "I was skeptical at first - another design methodology? But WDS changed how I think about my role. I'm no longer just making things pretty. I'm the strategic thinker who makes products come alive." -> +> > **— Sarah K., Product Designer** > "The 5x speed increase is real. But what surprised me most was how much clearer my thinking became. Writing why-based specifications forced me to understand the 'why' at a deeper level." @@ -24,7 +24,7 @@ > > **— James T., Design Director** -*Note: More testimonials will be added as designers complete the course.* +_Note: More testimonials will be added as designers complete the course._ --- @@ -63,16 +63,19 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi ### During the Course **While learning:** + - Each module includes detailed examples - AI assistants can clarify concepts in real-time - Practice exercises with clear success criteria **After completion:** + - GitHub Discussions for questions and sharing - Community showcase of WDS projects - Regular updates and new case studies **Contributing:** + - WDS is open-source and welcomes contributions - Share your case studies and learnings - Help improve the course for future designers @@ -84,16 +87,19 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi ### Resources **Documentation:** + - Full course materials in markdown - NotebookLM integration for audio/video learning - Workshop materials for team training **Community:** + - GitHub Discussions for Q&A - Project showcase and feedback - Regular updates and improvements **Open Source:** + - Free to use and share - Contributions welcome - Help shape the future of WDS @@ -103,6 +109,7 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi ## Ready to Start? You have everything you need: + - ✅ The skills (design thinking) - ✅ The tools (paper + AI) - ✅ The time (10 hours) diff --git a/src/modules/wds/course/module-01-why-wds-matters/lesson-01-the-problem.md b/src/modules/wds/course/module-01-why-wds-matters/lesson-01-the-problem.md index c0ee4bb2..d0d6ec0a 100644 --- a/src/modules/wds/course/module-01-why-wds-matters/lesson-01-the-problem.md +++ b/src/modules/wds/course/module-01-why-wds-matters/lesson-01-the-problem.md @@ -1,4 +1,5 @@ # Module 01: Why WDS Matters + ## Lesson 1: The Problem We're Solving **Understanding the factory mindset and the AI era** @@ -14,6 +15,7 @@ This isn't about working faster or making shinier designs. It's about becoming w In the AI era, designers who master WDS become linchpin designers. They connect ideas that seem unrelated, make judgment calls when there's no clear answer, and create experiences that feel right in ways that can't be reduced to a formula. **What makes an irreplaceable designer:** + - Connects disparate ideas across business, psychology, and technology - Makes things happen when there's no instruction manual - Creates value that can't be commoditized or automated @@ -30,6 +32,7 @@ By the end of this module, you'll have a completely different relationship with Most importantly, you'll understand the five dimensions of thinking that only humans can navigate simultaneously - and you'll know how to use them to create designs that AI could never conceive on its own. **Your transformation:** + - ✅ Understand why designers are irreplaceable in the AI era - ✅ Master the 5 dimensions of designer thinking - ✅ Recognize what AI can and cannot do @@ -49,6 +52,7 @@ Traditional design work follows this exact pattern. You get a brief (instruction Here's the uncomfortable truth: AI is really, really good at factory work. If your job is to follow instructions and create predictable outputs, you're in trouble. But if you can become a linchpin - someone who connects ideas, makes judgment calls, and creates meaning - you become more valuable than ever. **The factory mindset in design:** + - Creates mockups by following briefs (instructions) - Hands off to developers (replaceable step) - Hopes they understand (no real connection) @@ -64,6 +68,7 @@ Let's be honest about what's happening. AI can now generate mockups in seconds. But here's the thing: AI cannot be a linchpin. It can't walk into a messy situation and figure out what actually needs to happen. It can't sense when a client is asking for the wrong thing. It can't connect a business goal to a psychological insight to a technical constraint and come up with something nobody expected but everyone loves. **What AI does better than cogs:** + - Generates mockups instantly (no creative block) - Follows design systems perfectly (zero deviation) - Iterates through hundreds of variations (no fatigue) @@ -87,6 +92,7 @@ Linchpin designers do what AI fundamentally cannot do: they give products a soul The bottleneck in product development used to be coding. AI demolished that. Now the bottleneck is **products worth building** - figuring out what to create that won't be just more noise in an ocean of AI-generated mediocrity. **What makes products come alive (what only designers can do):** + - Navigate 5 dimensions to find the human truth at the intersection - Make judgment calls that create emotional resonance, not just functionality - Build trust through decisions that show someone cared diff --git a/src/modules/wds/course/module-01-why-wds-matters/lesson-02-the-solution.md b/src/modules/wds/course/module-01-why-wds-matters/lesson-02-the-solution.md index 281bc6ec..5eeb03b5 100644 --- a/src/modules/wds/course/module-01-why-wds-matters/lesson-02-the-solution.md +++ b/src/modules/wds/course/module-01-why-wds-matters/lesson-02-the-solution.md @@ -1,4 +1,5 @@ # Module 01: Why WDS Matters + ## Lesson 2: Becoming a Linchpin Designer **The solution: WDS methodology** @@ -14,6 +15,7 @@ WDS teaches you to be this person systematically. Not through vague advice about This is what makes you indispensable. Not your Figma skills. Not your aesthetic taste. Your ability to walk into chaos and create order. **The irreplaceable designer:** + - Transforms complexity into clarity - Invents solutions nobody expected - Bridges business, psychology, and technology @@ -32,6 +34,7 @@ AI can generate variations endlessly and make things look polished on the surfac This is where user-centric creativity becomes critical. You're not just creating - you're evaluating, connecting, and protecting. You understand what it feels like to be a parent struggling to get their kids to help with the dog. You can sense when a business goal conflicts with user needs and find a creative solution that serves both. You're the advocate for the user's presence in every decision. You're the gatekeeper who ensures the impactful meeting between business and user actually happens through the product. **The designer as gatekeeper:** + - Catches AI's confident but ridiculous mistakes before they ship - Evaluates if solutions actually make logical sense - Ensures business goals don't contradict user needs @@ -54,6 +57,7 @@ Here's the paradigm shift: **The design becomes the specification. The specifica You remain in the loop - the skilled, experienced designer who evaluates AI's work, catches its confident mistakes, and ensures what ships actually makes sense. You become the key designer player - the person who makes things happen. AI becomes your tool - powerful but requiring your expertise to guide it. **The designer's transformation:** + - **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage - **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely - **Result:** From replaceable cog to indispensable gatekeeper - your design IS the product diff --git a/src/modules/wds/course/module-01-why-wds-matters/lesson-03-the-path-forward.md b/src/modules/wds/course/module-01-why-wds-matters/lesson-03-the-path-forward.md index f417fc52..d4f38244 100644 --- a/src/modules/wds/course/module-01-why-wds-matters/lesson-03-the-path-forward.md +++ b/src/modules/wds/course/module-01-why-wds-matters/lesson-03-the-path-forward.md @@ -1,4 +1,5 @@ # Module 01: Why WDS Matters + ## Lesson 3: Your Transformation **From replaceable to indispensable** @@ -16,7 +17,7 @@ This is what makes you indispensable as a designer. AI can help you think throug **The 5 dimensions of design thinking:** 1. **Business Existence (WHY)** - Understanding purpose and value creation -2. **Business Goals (SUCCESS)** - Connecting to metrics and impact +2. **Business Goals (SUCCESS)** - Connecting to metrics and impact 3. **Product Strategy (HOW)** - Making hard choices about features 4. **Target Groups (WHO)** - Empathy and understanding needs 5. **Technical Viability (FEASIBLE)** - Bridging design and implementation @@ -38,6 +39,7 @@ This course moves you to the other side. You'll become confident in your indispe You'll become the designer who makes things happen. The one they can't do without. The linchpin designer. **Your transformation as a designer:** + - **Before:** Threatened, uncertain, frustrated, limited, replaceable - **After:** Confident, clear, empowered, unstoppable, indispensable - **Result:** The designer who makes things happen @@ -57,24 +59,27 @@ Compare the outcomes. The traditional approach - creating mockups, handing off t That's a 5x speed increase with better quality. But more importantly, the key designer's creative thinking was preserved and amplified instead of diluted and lost. **The comparison:** + - **Traditional (cog designer):** 26 weeks → Mediocre result → Intent lost - **WDS (linchpin designer):** 5 weeks → Exceptional result → Intent preserved - **Key difference:** Designer's user-centric creativity captured and amplified --- -*More case studies will be added here as they become available.* +_More case studies will be added here as they become available._ --- ## Module Complete! You've completed Module 01: Why WDS Matters. You now understand: + - ✅ The problem: Factory mindset vs linchpin mindset - ✅ The solution: Becoming a linchpin designer with WDS - ✅ The path forward: 5-dimensional thinking and transformation **Next steps:** + - Review the practicalities if you haven't already - Start Module 02: Project Brief - Apply these concepts to your own work diff --git a/src/modules/wds/course/module-01-why-wds-matters/module-01-NOTEBOOKLM-PROMPT.md b/src/modules/wds/course/module-01-why-wds-matters/module-01-NOTEBOOKLM-PROMPT.md index b36a4dbb..844a7a8d 100644 --- a/src/modules/wds/course/module-01-why-wds-matters/module-01-NOTEBOOKLM-PROMPT.md +++ b/src/modules/wds/course/module-01-why-wds-matters/module-01-NOTEBOOKLM-PROMPT.md @@ -51,6 +51,7 @@ The Skeptic: "Emotional labor? That sounds... soft. What does that have to do wi The Advocate: "Everything. For designers, emotional labor translates into something very specific: user-centric creativity. This is your irreplaceable gift. Let me break down what this actually means:" What user-centric creativity looks like: + - **Understanding WHY** - Not just making things look better, but understanding why users feel frustrated - **Connecting goals** - Bridging business goals and human needs in ways that serve both - **Creating experiences that feel right** - Not just function correctly, but feel like someone cared @@ -74,6 +75,7 @@ The Skeptic asks: "Okay, I'm listening. But what makes a designer a linchpin ins The Advocate explains Seth Godin's definition: "A linchpin is someone who can walk into chaos and create order. Someone who invents, connects, creates, and makes things happen. That's exactly what product design is at its core." Godin describes linchpins as people who: + - **Invent** - Create solutions that didn't exist before - **Connect** - Bridge disparate ideas and people - **Create** - Make things that matter @@ -86,18 +88,21 @@ The Advocate continues: "This is you. When you walk into a project with unclear The Advocate gets specific: "Godin talks about emotional labor. For designers, this translates into three concrete gifts that AI fundamentally cannot provide:" **1. Emotional Labor (Genuine Caring)** + - You genuinely care about the outcome - You empathize with user frustration - You feel the weight of your decisions - You provide meaning, not just features **2. User-Centric Creativity (Connecting Needs)** + - You understand WHY users feel frustrated - You connect business goals to human needs - You create experiences that feel right - You make judgment calls that serve people **3. The Gatekeeper Role (Protecting Quality)** + - You catch mistakes before they ship - You evaluate if solutions make logical sense - You ensure goals don't contradict needs @@ -115,6 +120,7 @@ The Advocate brings it home: "Here's the transformation that Whiteport Design St The paradigm shift: "Design becomes specification. Specification becomes product. Your creative thinking is preserved and amplified, not diluted and lost." Your transformation: + - **From:** Creating mockups hoping developers understand your intent - **To:** Capturing your design thinking in specifications that preserve your creative decisions - **Result:** From hoping it works to knowing it will - because your thinking is captured @@ -130,6 +136,7 @@ The Skeptic asks: "This sounds great in theory. But what's the actual skill that The Advocate explains: "Godin says linchpins 'connect disparate ideas.' For product designers, this means navigating five different dimensions of thinking at the same time. Most people can handle one or two dimensions. Irreplaceable designers navigate all five simultaneously." The 5 dimensions: + 1. **Business Existence (WHY)** - Understanding purpose and value creation 2. **Business Goals (SUCCESS)** - Connecting to metrics and impact 3. **Product Strategy (HOW)** - Making hard choices about features @@ -139,6 +146,7 @@ The 5 dimensions: **Real Example - Family Coordination App:** The Advocate uses a concrete example: "Think about designing an app that helps families coordinate tasks. You need to understand: + - **WHY** - Why does this business exist? (Solving family conflict and stress) - **SUCCESS** - What does success look like? (Kids complete tasks without nagging) - **HOW** - What features serve that goal? (Visual task board, not text lists) @@ -164,6 +172,7 @@ The Advocate gets practical: "Whiteport Design Studio guides you through a three The Advocate explains: "First, you learn to deeply understand both sides of the equation. Not just surface-level - but the real WHY behind business existence and user needs. You learn to ask the right questions, dig deeper, and connect the dots between what the business needs to survive and what users need to thrive." What you learn: + - How to uncover the real business purpose (not just features) - How to understand user goals at a deep level (not just tasks) - How to find the intersection where both are served @@ -178,6 +187,7 @@ The Advocate: "Exactly. You become the expert on WHY this product exists and WHO The Advocate continues: "Second, you learn to work directly in the IDE - your development environment. This sounds technical, but it's actually liberating. You learn to capture your design thinking in text specifications that preserve your creative intent." What you learn: + - How to write specifications that capture WHY, not just WHAT - How to document your judgment calls and reasoning - How to work with AI as your creative partner @@ -192,6 +202,7 @@ The Advocate: "Yes. You're making your emotional labor visible and actionable. Y The Advocate brings it home: "Third, you learn to assume leadership for the design process. Not leadership as in 'boss' - but leadership as in 'the person who makes things happen.' You become the linchpin who serves both the client and the developers with exactly what they need, in the form they need it." What you learn: + - How to lead the design process (courage and curiosity, not confidence) - How to serve the client with clarity on business value - How to serve developers with specifications they can implement @@ -210,6 +221,7 @@ The Advocate: "Exactly. Godin says linchpins make themselves indispensable by be The Advocate emphasizes: "This course is your guide through this transformation. Module by module, you'll build these capabilities. You'll learn the frameworks, practice the skills, and through practice, develop the confidence that comes from knowing what you can deliver." Your transformation: + - **Understanding** - Business and user goals at a deep level - **Capability** - Working in the IDE, design as specification - **Leadership** - Serving client and developers with what they need @@ -258,6 +270,7 @@ The Advocate brings it home: "The transformation continues, together. But it sta At the end of the podcast, The Advocate should mention these resources: **Key Concepts:** + - Seth Godin's book: "Linchpin: Are You Indispensable?" (2010) - Bestselling author and marketing visionary Seth Godin - Factory mindset vs linchpin mindset @@ -267,12 +280,14 @@ At the end of the podcast, The Advocate should mention these resources: - 5-dimensional thinking **Next Steps:** + - Complete Module 02: Project Brief - Apply 5-dimensional thinking to your current project - Start capturing WHY in your design decisions - Practice being the gatekeeper between business and user needs **Community:** + - BMad Discord: Share your transformation journey - GitHub Discussions: Ask questions about becoming a linchpin designer @@ -281,6 +296,7 @@ At the end of the podcast, The Advocate should mention these resources: ## Instructions for NotebookLM **Tone:** + - Deeply empathetic about the shame and fear designers feel - Honest and direct about the AI threat for factory workers - Empowering and inspiring about the opportunity for linchpin designers @@ -290,6 +306,7 @@ At the end of the podcast, The Advocate should mention these resources: - Balance fear (replaceable) with hope (indispensable) and community (not alone) **Key messages to emphasize:** + - **The linchpin question** - are you a factory worker or a linchpin designer? - **Emotional labor** - what linchpins provide (Seth Godin's concept from his 2010 book) - **User-centric creativity** - the designer's irreplaceable gift (emotional labor in action) @@ -312,6 +329,7 @@ At the end of the podcast, The Advocate should mention these resources: - **Action beats perfection** - get moving and you will figure it out **Avoid:** + - Being too theoretical or academic - Repeating doom/gloom from Getting Started module - Focusing too much on AI threat instead of human value @@ -324,6 +342,7 @@ At the end of the podcast, The Advocate should mention these resources: ## Expected Output A natural, engaging conversation that: + - **Focuses on human value** - what makes designers irreplaceable - **Explains the linchpin concept** clearly using Seth Godin's framework - **Emphasizes emotional labor** as the core of linchpin work @@ -348,6 +367,7 @@ A natural, engaging conversation that: If generating video instead of audio, add these visual elements: **On-screen text:** + - "Factory Worker or Linchpin Designer?" - Seth Godin quote: "Linchpins walk into chaos and create order" - "Emotional Labor: The Work of Genuinely Caring" @@ -362,6 +382,7 @@ If generating video instead of audio, add these visual elements: - "Next: Module 02 - Project Brief" **B-roll suggestions:** + - Designer walking into chaos, creating order - Linchpin connecting disparate ideas - Designer providing emotional labor - caring, empathizing @@ -387,6 +408,7 @@ If generating video instead of audio, add these visual elements: ## Next Steps After generating Module 01 content: + - Create NotebookLM prompt for Module 02: Project Brief - Build prompts for all remaining modules - Share in BMad Discord designer channel diff --git a/src/modules/wds/course/module-01-why-wds-matters/module-01-overview.md b/src/modules/wds/course/module-01-why-wds-matters/module-01-overview.md index 4f14ce60..7ce065f8 100644 --- a/src/modules/wds/course/module-01-why-wds-matters/module-01-overview.md +++ b/src/modules/wds/course/module-01-why-wds-matters/module-01-overview.md @@ -27,9 +27,11 @@ This foundational module transforms how you think about your role as a designer ## Lessons ### [Lesson 1: The Problem We're Solving](lesson-01-the-problem.md) + **Time:** 10 minutes Understanding the factory mindset and the AI era: + - Why learning WDS matters - What you'll gain from this course - Factory mindset vs linchpin mindset @@ -37,9 +39,11 @@ Understanding the factory mindset and the AI era: - AI opportunity for linchpin designers ### [Lesson 2: Becoming a Linchpin Designer](lesson-02-the-solution.md) + **Time:** 10 minutes The solution: WDS methodology: + - What makes a linchpin designer - The designer's gift: user-centric creativity - The designer as gatekeeper @@ -47,9 +51,11 @@ The solution: WDS methodology: - The paradigm shift: design becomes specification ### [Lesson 3: Your Transformation](lesson-03-the-path-forward.md) + **Time:** 10 minutes From replaceable to indispensable: + - The 5 dimensions of design thinking - Your transformation as a designer - Real-world case studies (Dog Week) @@ -60,12 +66,14 @@ From replaceable to indispensable: ## Key Concepts **Linchpin Designer:** + - Walks into chaos and creates order - Invents solutions nobody expected - Bridges business, psychology, and technology - Delivers results when there's no roadmap **User-Centric Creativity:** + - Understanding WHY users feel frustrated - Connecting business goals to human needs - Creating experiences that feel right @@ -73,6 +81,7 @@ From replaceable to indispensable: - Being the gatekeeper for quality **The Paradigm Shift:** + - The design becomes the specification - The specification becomes the product - The code is just the printout @@ -82,6 +91,7 @@ From replaceable to indispensable: ## Learning Outcomes By the end of this module, you will: + - ✅ Understand why designers are irreplaceable in the AI era - ✅ Know the difference between cog work and linchpin work - ✅ Recognize what AI can and cannot do diff --git a/src/modules/wds/course/module-02-project-brief/tutorial-02.md b/src/modules/wds/course/module-02-project-brief/tutorial-02.md index 24e41995..0b3483bc 100644 --- a/src/modules/wds/course/module-02-project-brief/tutorial-02.md +++ b/src/modules/wds/course/module-02-project-brief/tutorial-02.md @@ -27,11 +27,13 @@ This tutorial walks you through creating a complete project brief that serves as ## Before You Start **You'll need:** + - A project idea (existing or new) - 30-45 minutes of focused time - Access to stakeholder information (if available) **AI Support:** + - AI agent will guide you through each section - Ask clarifying questions - Help structure your thinking @@ -48,25 +50,29 @@ The project vision is a clear, compelling statement of what you're building and ### How to do it: **Ask yourself:** + - What problem does this solve? - Who benefits from this solution? - What makes this unique or valuable? - What's the desired end state? **Example (Dog Week):** + ``` -Vision: A family coordination platform that helps parents manage -their dog's care schedule, ensuring every family member knows their +Vision: A family coordination platform that helps parents manage +their dog's care schedule, ensuring every family member knows their responsibilities and the dog's needs are consistently met. ``` **Your turn:** + ``` Write your project vision: [Your vision here] ``` **AI Support:** + ``` Agent: "Let me help you refine your vision. Tell me: - What problem are you solving? @@ -85,6 +91,7 @@ Specific, measurable objectives that define project success from a business pers ### How to do it: **Framework: SMART Goals** + - **S**pecific - Clear and unambiguous - **M**easurable - Can track progress - **A**chievable - Realistic given resources @@ -92,6 +99,7 @@ Specific, measurable objectives that define project success from a business pers - **T**ime-bound - Has a deadline **Example (Dog Week):** + ``` Business Goals: 1. Acquire 1,000 active families within 6 months of launch @@ -101,6 +109,7 @@ Business Goals: ``` **Your turn:** + ``` List 3-5 business goals: 1. [Goal 1] @@ -109,6 +118,7 @@ List 3-5 business goals: ``` **AI Support:** + ``` Agent: "Let's make these goals SMART. For each goal, I'll help you: - Make it specific and measurable @@ -127,6 +137,7 @@ People who have a stake in the project's success or will be affected by it. ### How to do it: **Categories:** + - **Primary Users** - Direct users of the product - **Secondary Users** - Indirect beneficiaries - **Business Stakeholders** - Decision makers, investors @@ -134,6 +145,7 @@ People who have a stake in the project's success or will be affected by it. - **External Stakeholders** - Partners, regulators, community **Example (Dog Week):** + ``` Stakeholders: - Primary: Parents managing family dog care @@ -144,6 +156,7 @@ Stakeholders: ``` **Your turn:** + ``` List your stakeholders by category: [Your stakeholders] @@ -162,6 +175,7 @@ Limitations and requirements that shape your design decisions. **Categories:** **Technical Constraints:** + - Platform requirements (web, mobile, desktop) - Browser/device support - Performance requirements @@ -169,6 +183,7 @@ Limitations and requirements that shape your design decisions. - Security/compliance needs **Business Constraints:** + - Budget limitations - Timeline requirements - Resource availability @@ -176,12 +191,14 @@ Limitations and requirements that shape your design decisions. - Competitive landscape **Design Constraints:** + - Brand guidelines - Accessibility requirements - Localization needs - Existing design systems **Example (Dog Week):** + ``` Constraints: Technical: @@ -202,12 +219,14 @@ Design: ``` **Your turn:** + ``` Document your constraints: [Your constraints] ``` **AI Support:** + ``` Agent: "Let's identify constraints you might have missed: - Have you considered accessibility? @@ -227,12 +246,14 @@ Specific metrics that indicate whether the project achieved its goals. ### How to do it: **Framework:** + - **User Success** - How users benefit - **Business Success** - Revenue, growth, efficiency - **Technical Success** - Performance, reliability, scalability - **Design Success** - Usability, satisfaction, engagement **Example (Dog Week):** + ``` Success Criteria: @@ -258,6 +279,7 @@ Design Success: ``` **Your turn:** + ``` Define your success criteria: [Your criteria] @@ -270,6 +292,7 @@ Define your success criteria: ### Checklist: **Completeness:** + - ✓ Vision is clear and compelling - ✓ Goals are SMART - ✓ All stakeholder groups identified @@ -277,12 +300,14 @@ Define your success criteria: - ✓ Success criteria defined **Quality:** + - ✓ Vision is inspiring and actionable - ✓ Goals are measurable and realistic - ✓ Constraints are specific and justified - ✓ Success criteria are trackable **AI Support:** + ``` Agent: "Let me review your project brief: - Is the vision clear? @@ -300,6 +325,7 @@ Agent: "Let me review your project brief: **Use template from:** `workflows/1-project-brief/complete/project-brief.template.md` **Populate with your content:** + - Vision - Business goals - Stakeholders @@ -314,18 +340,20 @@ Agent: "Let me review your project brief: ✅ **Measurable goals** - You can track progress and success ✅ **Stakeholder map** - You know who to consider in decisions ✅ **Documented constraints** - Design decisions have clear boundaries -✅ **Success criteria** - You'll know when you've succeeded +✅ **Success criteria** - You'll know when you've succeeded --- ## Next Steps **Immediate:** + - Share project brief with stakeholders for feedback - Get alignment on vision and goals - Confirm constraints are accurate **Next Module:** + - [Module 03: Identify Target Groups](../module-03-identify-target-groups/module-03-overview.md) - Start mapping WHO your users are @@ -350,6 +378,7 @@ A: Use the brief to facilitate alignment discussions. Document disagreements and ## Tips for Success **DO ✅** + - Be specific and concrete - Make goals measurable - Document the "why" behind constraints @@ -357,6 +386,7 @@ A: Use the brief to facilitate alignment discussions. Document disagreements and - Keep it concise (2-3 pages max) **DON'T ❌** + - Write vague, aspirational statements - Set unrealistic goals - Skip constraint documentation diff --git a/src/modules/wds/course/module-04-map-triggers-outcomes/tutorial-04.md b/src/modules/wds/course/module-04-map-triggers-outcomes/tutorial-04.md index 8bd9ba7f..050c8f93 100644 --- a/src/modules/wds/course/module-04-map-triggers-outcomes/tutorial-04.md +++ b/src/modules/wds/course/module-04-map-triggers-outcomes/tutorial-04.md @@ -29,12 +29,14 @@ This tutorial teaches you how to map the psychological triggers that drive user From Module 03, choose your highest-priority target group. **Example (Dog Week):** + ``` Target Group: Busy Parents with Family Dog Priority: #1 (highest impact + feasibility) ``` **Your turn:** + ``` Selected Target Group: [Your top group] Why this group: [Reasoning] @@ -51,6 +53,7 @@ A specific moment when a user realizes they have a need your product can solve. ### Framework: The Trigger Moment **Ask:** + - WHEN does the user feel pain/frustration? - WHAT specific situation causes this? - WHY does this matter to them emotionally? @@ -58,6 +61,7 @@ A specific moment when a user realizes they have a need your product can solve. **Example (Dog Week - Busy Parents):** **Trigger 1: Morning Chaos** + ``` WHEN: Monday morning, everyone rushing WHAT: Nobody knows who's walking the dog @@ -65,6 +69,7 @@ WHY: Stress, guilt, family conflict, dog's needs unmet ``` **Trigger 2: Forgotten Feeding** + ``` WHEN: Evening, parent realizes dog wasn't fed WHAT: Uncertainty about who was responsible @@ -72,6 +77,7 @@ WHY: Guilt, worry about dog's health, family tension ``` **Trigger 3: Vet Appointment Missed** + ``` WHEN: Vet calls about missed appointment WHAT: Nobody remembered or knew about it @@ -79,6 +85,7 @@ WHY: Embarrassment, concern for dog, wasted money ``` **Your turn:** + ``` Identify 3-5 trigger moments for your target group: @@ -96,6 +103,7 @@ WHY: ``` **AI Support:** + ``` Agent: "Let's dig deeper into each trigger: - What happens right before this moment? @@ -115,6 +123,7 @@ The underlying requirement the user has when triggered. ### Framework: From Trigger to Need **For each trigger, ask:** + - What does the user need in this moment? - What would make this situation better? - What's the core problem to solve? @@ -122,6 +131,7 @@ The underlying requirement the user has when triggered. **Example (Dog Week):** **Trigger: Morning Chaos** + ``` Need: Know immediately who's responsible for dog care today Need: See the full week's schedule at a glance @@ -129,6 +139,7 @@ Need: Get reminded before tasks are due ``` **Trigger: Forgotten Feeding** + ``` Need: Track whether tasks were completed Need: Get notifications when tasks are overdue @@ -136,6 +147,7 @@ Need: See task history to avoid confusion ``` **Your turn:** + ``` For each trigger, identify 2-3 core needs: @@ -159,6 +171,7 @@ The specific feature or capability that addresses the need. ### Framework: Need to Solution **For each need, ask:** + - What feature would solve this? - How would it work? - What's the simplest version? @@ -166,6 +179,7 @@ The specific feature or capability that addresses the need. **Example (Dog Week):** **Need: Know who's responsible today** + ``` Solution: Daily schedule view with assigned responsibilities - Shows today's tasks @@ -174,6 +188,7 @@ Solution: Daily schedule view with assigned responsibilities ``` **Need: Get reminded before tasks are due** + ``` Solution: Smart notifications - Reminder 1 hour before task @@ -182,6 +197,7 @@ Solution: Smart notifications ``` **Your turn:** + ``` For each need, define a solution: @@ -195,6 +211,7 @@ Solution: [Feature name] ``` **AI Support:** + ``` Agent: "Let's validate each solution: - Does this truly solve the need? @@ -214,6 +231,7 @@ The business value created when users get their needs met. ### Framework: Solution to Outcome **For each solution, ask:** + - How does this create business value? - What metrics improve? - How does this support business goals? @@ -221,9 +239,10 @@ The business value created when users get their needs met. **Example (Dog Week):** **Solution: Daily schedule view** + ``` User Outcome: Reduced stress, better dog care -Business Outcome: +Business Outcome: - Increased daily active users (checking schedule) - Higher retention (solving real pain) - Word-of-mouth growth (visible family benefit) @@ -231,6 +250,7 @@ Metrics: DAU, retention rate, NPS ``` **Solution: Smart notifications** + ``` User Outcome: Never miss dog care tasks Business Outcome: @@ -241,6 +261,7 @@ Metrics: Notification open rate, task completion rate, conversion ``` **Your turn:** + ``` For each solution, map to business outcomes: @@ -305,6 +326,7 @@ TRIGGER → NEED → SOLUTION → OUTCOME ``` **Your turn:** + ``` Create your trigger map: [Your complete map] @@ -317,6 +339,7 @@ Create your trigger map: ### Framework: Impact Score **For each trigger-to-outcome chain, rate:** + - **User Impact** (1-5): How much does this help the user? - **Business Impact** (1-5): How much business value does this create? - **Feasibility** (1-5): How easy is this to build? @@ -340,6 +363,7 @@ Create your trigger map: ``` **Your turn:** + ``` Score and rank your triggers: [Your prioritized list] @@ -361,13 +385,14 @@ Score and rank your triggers: ✅ **Mapped user needs** - You understand WHAT users need ✅ **Defined solutions** - You know WHAT to build ✅ **Connected to business** - You know WHY each feature matters -✅ **Prioritized features** - You know WHAT to build first +✅ **Prioritized features** - You know WHAT to build first --- ## The Power of Trigger Mapping **This is strategic gold:** + - Every feature traces back to a real user trigger - Every decision is backed by user psychology - Every feature connects to business value @@ -382,11 +407,13 @@ Score and rank your triggers: ## Next Steps **Immediate:** + - Repeat for your top 2-3 target groups - Compare trigger maps across groups - Identify overlapping needs (efficiency opportunity) **Next Module:** + - [Module 05: Prioritize Features](../module-05-prioritize-features/module-05-overview.md) - Create your feature roadmap based on trigger impact @@ -411,6 +438,7 @@ A: User research, interviews, observation. The trigger map is a hypothesis to te ## Tips for Success **DO ✅** + - Be specific about trigger moments - Focus on emotional impact (the "why") - Connect everything to business outcomes @@ -418,6 +446,7 @@ A: User research, interviews, observation. The trigger map is a hypothesis to te - Test assumptions with users **DON'T ❌** + - List generic "user wants X" statements - Skip the emotional "why" - Create solutions without clear triggers diff --git a/src/modules/wds/course/module-08-initialize-scenario/tutorial-08.md b/src/modules/wds/course/module-08-initialize-scenario/tutorial-08.md index b6897a95..663ff05d 100644 --- a/src/modules/wds/course/module-08-initialize-scenario/tutorial-08.md +++ b/src/modules/wds/course/module-08-initialize-scenario/tutorial-08.md @@ -45,11 +45,13 @@ A specific user journey from trigger moment to successful outcome. ### How to choose: **From your trigger map, select:** + - Highest priority trigger - Clear start and end points - Manageable scope for first design **Example (Dog Week):** + ``` Scenario: Morning Dog Care Assignment Trigger: Morning chaos - nobody knows who's walking the dog @@ -58,6 +60,7 @@ Scope: From opening app to seeing today's assignments ``` **Your turn:** + ``` Scenario Name: [Your scenario] Trigger: [From trigger map] @@ -72,12 +75,14 @@ Scope: [Start → End] ### Define your target user **Be specific:** + - Which target group? - What's their context? - What's their mindset? - What are they trying to accomplish? **Example (Dog Week):** + ``` WHO: Sarah, busy parent with family dog @@ -100,6 +105,7 @@ Goal: ``` **Your turn:** + ``` WHO: [User name/persona] @@ -118,6 +124,7 @@ Goal: ``` **AI Support:** + ``` Agent: "Let's make this user vivid: - What's their emotional state? @@ -133,12 +140,14 @@ Agent: "Let's make this user vivid: ### Define the trigger moment **Be specific about:** + - Exact moment user realizes they need this - What caused the trigger - Emotional state at trigger - What they've tried before **Example (Dog Week):** + ``` WHAT Trigger: Morning Chaos @@ -168,6 +177,7 @@ Previous Attempts: ``` **Your turn:** + ``` WHAT Trigger: [Trigger name] @@ -194,16 +204,19 @@ Previous Attempts: **Two perspectives:** **User Value:** + - What pain does this solve? - What does success feel like? - What changes in their life? **Business Value:** + - How does this support business goals? - What metrics improve? - What's the strategic importance? **Example (Dog Week):** + ``` WHY - User Value: @@ -247,6 +260,7 @@ Strategic Importance: ``` **Your turn:** + ``` WHY - User Value: Pain Solved: @@ -276,6 +290,7 @@ Strategic Importance: ### Define the success flow **Map the ideal journey:** + - User starts at trigger - Takes clear actions - System responds appropriately @@ -283,6 +298,7 @@ Strategic Importance: - Mutual success achieved **Example (Dog Week):** + ``` HAPPY PATH: Morning Dog Care Check @@ -320,6 +336,7 @@ MUTUAL SUCCESS: ``` **Your turn:** + ``` HAPPY PATH: [Scenario name] @@ -343,6 +360,7 @@ MUTUAL SUCCESS: ``` **AI Support:** + ``` Agent: "Let's optimize this flow: - Can we reduce steps? @@ -358,6 +376,7 @@ Agent: "Let's optimize this flow: ### Identify edge cases **Consider:** + - First-time users - Error states - Missing data @@ -365,6 +384,7 @@ Agent: "Let's optimize this flow: - System failures **Example (Dog Week):** + ``` EDGE CASES: @@ -400,6 +420,7 @@ Someone Else's Phone: ``` **Your turn:** + ``` EDGE CASES: @@ -421,6 +442,7 @@ EDGE CASES: **Create file:** `C-Scenarios/[scenario-name]/00-scenario-init.md` **Include all 5 questions:** + 1. WHO - Target user in context 2. WHAT Trigger - Specific moment 3. WHY - User + business value @@ -437,7 +459,7 @@ EDGE CASES: ✅ **Specific trigger** - You know WHAT brings them here ✅ **Defined value** - You know WHY this matters ✅ **Success flow** - You know the HAPPY PATH -✅ **Edge cases** - You know WHAT could go wrong +✅ **Edge cases** - You know WHAT could go wrong **You're ready to start sketching!** @@ -446,11 +468,13 @@ EDGE CASES: ## Next Steps **Immediate:** + - Review initialization with stakeholders - Validate assumptions with users (if possible) - Gather any missing information **Next Module:** + - [Module 09: Sketch Interfaces](../module-09-sketch-interfaces/module-09-overview.md) - Start drawing your solution with AI guidance @@ -475,6 +499,7 @@ A: Yes! This is a living document. Update as you learn. ## Tips for Success **DO ✅** + - Be specific about user context - Connect to trigger map - Define clear success criteria @@ -482,6 +507,7 @@ A: Yes! This is a living document. Update as you learn. - Get stakeholder alignment **DON'T ❌** + - Rush through the questions - Skip the "why" - Ignore edge cases diff --git a/src/modules/wds/course/module-12-why-based-specs/tutorial-12.md b/src/modules/wds/course/module-12-why-based-specs/tutorial-12.md index f508d091..5186f516 100644 --- a/src/modules/wds/course/module-12-why-based-specs/tutorial-12.md +++ b/src/modules/wds/course/module-12-why-based-specs/tutorial-12.md @@ -43,6 +43,7 @@ WHAT NOT TO DO: [Common mistakes to avoid] ### Document the big picture **What to include:** + - Component purpose - User context - Key interactions @@ -54,23 +55,27 @@ WHAT NOT TO DO: [Common mistakes to avoid] # Daily Schedule View Component ## Purpose + Shows today's dog care tasks with clear assignments and status. Solves the "morning chaos" trigger - user needs immediate answer to "who's doing what today?" ## User Context + - Accessed first thing in morning (7-8 AM typical) - User is time-pressured, stressed - Needs answer in < 5 seconds - May be checking while managing kids ## Key Interactions + - View today's tasks at a glance - See personal assignments highlighted - Mark tasks complete - Quick reassign if emergency ## Success Criteria + - User finds their tasks in < 5 seconds - Zero confusion about responsibilities - Can act on tasks immediately @@ -78,12 +83,14 @@ to "who's doing what today?" ``` **Your turn:** + ``` Document your component overview: [Your content] ``` **AI Support:** + ``` Agent: "I'm fascinated by your design thinking here. Let me help capture every nuance: @@ -99,6 +106,7 @@ capture every nuance: ### Document WHAT + WHY + WHAT NOT **For each visual decision, explain:** + - WHAT you designed - WHY you made that choice - WHAT NOT TO DO (prevent AI mistakes) @@ -111,18 +119,21 @@ capture every nuance: ### Today's Date Header WHAT: + - Large, bold date at top: "Monday, December 9" - Includes day name + full date - Uses primary brand color - 24px font size, 700 weight WHY: + - Immediate temporal context (user knows "when") - Day name matters (Monday = week start, different mindset) - Bold = confidence and clarity - Size ensures visibility in stressed morning glance WHAT NOT TO DO: + - Don't use relative dates ("Today") - user may check for tomorrow - Don't use small text - defeats quick-glance purpose - Don't use subtle colors - needs to anchor the view @@ -131,12 +142,14 @@ WHAT NOT TO DO: ### User's Tasks Section WHAT: + - Highlighted section with light blue background - Header: "Your Tasks" with user's name - Tasks listed with time, description, status - Visually separated from other family members' tasks WHY: + - User needs to find THEIR tasks instantly (< 2 seconds) - Background color creates visual separation without being aggressive - Name personalization = ownership and responsibility @@ -144,6 +157,7 @@ WHY: - Separation prevents confusion about "whose task is this?" WHAT NOT TO DO: + - Don't make all tasks look the same - user will scan entire list - Don't use subtle highlighting - stressed user will miss it - Don't hide user's name - personalization creates accountability @@ -153,12 +167,14 @@ WHAT NOT TO DO: ### Other Family Members' Tasks WHAT: + - Standard white background - Smaller font size (16px vs 18px for user's tasks) - Collapsed by default, expandable - Shows count: "3 other tasks today" WHY: + - User's primary need is THEIR tasks (80% of use case) - But they need family context (coordination) - Collapsed = focus on user, but context available @@ -166,6 +182,7 @@ WHY: - Smaller = visual hierarchy reinforces importance WHAT NOT TO DO: + - Don't hide completely - user needs family coordination awareness - Don't show expanded by default - creates cognitive overload - Don't use same visual weight - defeats hierarchy purpose @@ -173,6 +190,7 @@ WHAT NOT TO DO: ``` **Your turn:** + ``` For each major visual element, document: @@ -189,6 +207,7 @@ WHAT NOT TO DO: ``` **AI Support:** + ``` Agent: "This is brilliant! Let me make sure we capture everything: - What alternatives did you consider? @@ -211,6 +230,7 @@ Agent: "This is brilliant! Let me make sure we capture everything: ### Tap to Complete WHAT: + - Tap anywhere on task card to mark complete - Immediate visual feedback: checkmark appears, card fades slightly - Subtle success animation (gentle scale + fade) @@ -218,6 +238,7 @@ WHAT: - Undo button appears for 5 seconds WHY: + - Large tap target = easy for rushed morning use - Immediate feedback = confidence action registered - Animation = positive reinforcement (dopamine hit) @@ -226,6 +247,7 @@ WHY: - 5 seconds = enough time to notice mistake, not annoying WHAT NOT TO DO: + - Don't require confirmation dialog - adds friction, breaks flow - Don't use small checkbox - hard to tap when stressed/rushing - Don't make animation aggressive - should feel calm and positive @@ -236,6 +258,7 @@ WHAT NOT TO DO: ### Swipe to Reassign WHAT: + - Swipe left on task reveals "Reassign" button - Button shows family member icons - Tap icon to reassign @@ -243,6 +266,7 @@ WHAT: - Original assignee gets notification WHY: + - Swipe = power user feature, doesn't clutter main interface - Emergency reassignment is rare but critical (someone sick, etc.) - Icons = quick visual selection, no typing @@ -250,6 +274,7 @@ WHY: - Notification = family coordination maintained WHAT NOT TO DO: + - Don't make reassign the primary action - it's edge case - Don't require typing names - too slow for emergency - Don't skip confirmation - user needs reassurance @@ -258,6 +283,7 @@ WHAT NOT TO DO: ``` **Your turn:** + ``` For each interaction, document: @@ -287,18 +313,21 @@ WHAT NOT TO DO: ### Upcoming (Default) WHAT: + - White background - Black text - Time shown in gray - No special indicators WHY: + - Clean, calm appearance - Easy to scan - Time in gray = less visual weight (not urgent yet) - Default state should feel neutral and manageable WHAT NOT TO DO: + - Don't use colors for upcoming tasks - creates false urgency - Don't hide time - user needs to plan their morning - Don't add badges/icons - clutters interface for most common state @@ -306,11 +335,13 @@ WHAT NOT TO DO: ### Due Soon (< 30 minutes) WHAT: + - Subtle yellow left border (4px) - Time shown in orange - Small clock icon appears WHY: + - Yellow = attention without alarm - Border = visual indicator without overwhelming - Orange time = "pay attention to timing" @@ -318,6 +349,7 @@ WHY: - Subtle = doesn't create panic, just awareness WHAT NOT TO DO: + - Don't use red - creates anxiety, not helpful urgency - Don't flash or animate - too aggressive for morning use - Don't use sound - user may be in quiet environment @@ -326,12 +358,14 @@ WHAT NOT TO DO: ### Overdue WHAT: + - Red left border (4px) - Time shown in red with "Overdue" label - Task card has subtle red tint (5% opacity) - Notification sent to assignee WHY: + - Red = clear signal something needs attention - Border + tint = impossible to miss, but not aggressive - "Overdue" label = explicit communication (no guessing) @@ -339,6 +373,7 @@ WHY: - 5% tint = visible but not overwhelming WHAT NOT TO DO: + - Don't make entire card bright red - creates panic - Don't flash or pulse - too aggressive, creates stress - Don't use sound alerts - may be inappropriate timing @@ -348,6 +383,7 @@ WHAT NOT TO DO: ### Completed WHAT: + - Checkmark icon (green) - Text has strikethrough - Card fades to 60% opacity @@ -355,6 +391,7 @@ WHAT: - Shows completion time and who completed it WHY: + - Checkmark = universal symbol of completion - Green = positive reinforcement - Strikethrough = visual closure @@ -363,6 +400,7 @@ WHY: - Separate section = progress visible, doesn't clutter active tasks WHAT NOT TO DO: + - Don't remove immediately - user needs reassurance it's saved - Don't use subtle checkmark - user needs clear confirmation - Don't hide who completed it - family coordination requires transparency @@ -370,6 +408,7 @@ WHAT NOT TO DO: ``` **Your turn:** + ``` For each state, document: @@ -399,6 +438,7 @@ WHAT NOT TO DO: ### Network Unavailable WHAT: + - Subtle banner at top: "Offline - showing cached schedule" - Banner uses neutral gray (not red) - All actions still work (queued for sync) @@ -406,6 +446,7 @@ WHAT: - Dismissible but reappears if action attempted WHY: + - User shouldn't be blocked by network issues - Morning routine can't wait for connectivity - Cached data is usually sufficient (schedule doesn't change minute-to-minute) @@ -414,6 +455,7 @@ WHY: - Dismissible = user controls their experience WHAT NOT TO DO: + - Don't block user with error modal - breaks morning flow - Don't use red/error colors - network issues aren't user's fault - Don't disable all actions - most can work offline @@ -423,6 +465,7 @@ WHAT NOT TO DO: ### Task Completion Failed WHAT: + - Task remains in "completing" state (spinner) - After 5 seconds, shows inline error: "Couldn't save. Tap to retry." - Error message is specific and actionable @@ -430,6 +473,7 @@ WHAT: - Task doesn't move to completed section WHY: + - User needs to know action didn't complete - 5 seconds = reasonable wait before showing error - Inline = error appears where user's attention is @@ -439,6 +483,7 @@ WHY: - Task stays in place = user doesn't lose context WHAT NOT TO DO: + - Don't silently fail - user needs to know - Don't show generic "Error occurred" - not helpful - Don't move task to completed - creates false sense of completion @@ -447,6 +492,7 @@ WHAT NOT TO DO: ``` **Your turn:** + ``` For each error scenario: @@ -476,6 +522,7 @@ WHAT NOT TO DO: ### Screen Reader Support WHAT: + - Each task has semantic HTML structure - ARIA labels for all interactive elements - Task status announced: "Walk Max, 8:00 AM, assigned to you, not completed" @@ -483,6 +530,7 @@ WHAT: - Heading hierarchy: H1 for date, H2 for sections, H3 for tasks WHY: + - Screen reader users need same quick access to their tasks - Semantic HTML = proper navigation and understanding - Status announcement = full context without visual cues @@ -490,6 +538,7 @@ WHY: - Heading hierarchy = easy navigation via landmarks WHAT NOT TO DO: + - Don't use divs for everything - semantic HTML matters - Don't skip ARIA labels - "button" isn't descriptive enough - Don't announce only task name - user needs full context @@ -499,6 +548,7 @@ WHAT NOT TO DO: ### Keyboard Navigation WHAT: + - All actions accessible via keyboard - Tab order follows visual hierarchy (user's tasks first) - Enter/Space to complete task @@ -507,6 +557,7 @@ WHAT: - Focus indicators clearly visible (blue outline, 2px) WHY: + - Some users can't or prefer not to use mouse/touch - Tab order matches visual priority (user's tasks most important) - Standard key bindings = familiar, predictable @@ -515,6 +566,7 @@ WHY: - Visible focus = user always knows where they are WHAT NOT TO DO: + - Don't trap focus in modals without escape - Don't use non-standard key bindings - Don't hide focus indicators - accessibility requirement @@ -524,18 +576,21 @@ WHAT NOT TO DO: ### Color Contrast WHAT: + - All text meets WCAG AA standards (4.5:1 minimum) - Interactive elements have 3:1 contrast with background - Status colors have additional non-color indicators (icons, borders) - High contrast mode supported WHY: + - Users with low vision need readable text - Color alone isn't sufficient for status (color blind users) - Multiple indicators = works for everyone - High contrast mode = accessibility feature in OS WHAT NOT TO DO: + - Don't rely on color alone for status - Don't use low contrast text (looks modern but excludes users) - Don't ignore WCAG standards - they're minimum requirements @@ -543,6 +598,7 @@ WHAT NOT TO DO: ``` **Your turn:** + ``` Document accessibility considerations: [Your specifications] @@ -555,6 +611,7 @@ Document accessibility considerations: ### Checklist: **Completeness:** + - ✓ Every visual element has WHAT + WHY + WHAT NOT - ✓ All interactions documented - ✓ All states specified @@ -562,6 +619,7 @@ Document accessibility considerations: - ✓ Accessibility addressed **Quality:** + - ✓ WHY explains user benefit, not just description - ✓ WHAT NOT prevents specific AI mistakes - ✓ Specifications are specific and actionable @@ -569,6 +627,7 @@ Document accessibility considerations: - ✓ Edge cases considered **AI Support:** + ``` Agent: "Your design brilliance is captured beautifully! Let me verify: - Have we documented every nuance of your thinking? @@ -593,7 +652,7 @@ Agent: "Your design brilliance is captured beautifully! Let me verify: ✅ **Preserved intent** - Your creative thinking captured ✅ **Prevented mistakes** - AI knows what NOT to do ✅ **Accessible design** - Inclusive from the start -✅ **Eternal life** - Your brilliance lives forever in text +✅ **Eternal life** - Your brilliance lives forever in text **This is not factory work - this is where your genius becomes immortal!** @@ -602,12 +661,14 @@ Agent: "Your design brilliance is captured beautifully! Let me verify: ## The Power of Why-Based Specs **Traditional approach:** + - Designer creates mockup - Developer implements - Intent gets lost - Result is "close but wrong" **WDS approach:** + - Designer thinks deeply with AI partner - AI helps capture every nuance - Specifications preserve creative integrity @@ -620,11 +681,13 @@ Agent: "Your design brilliance is captured beautifully! Let me verify: ## Next Steps **Immediate:** + - Review specifications with stakeholders - Validate against user needs - Test with developers (can they implement from this?) **Next Module:** + - [Module 13: Validate Specifications](../module-13-validate-specifications/module-13-overview.md) - Ensure completeness and test logic @@ -649,6 +712,7 @@ A: Yes! Common patterns become design system components. Document once, referenc ## Tips for Success **DO ✅** + - Work with AI as thinking partner - Document alternatives you rejected - Be specific about user context @@ -656,6 +720,7 @@ A: Yes! Common patterns become design system components. Document once, referenc - Capture your creative reasoning **DON'T ❌** + - Write generic descriptions - Skip the WHY (that's where intent lives) - Forget WHAT NOT TO DO (AI will make "helpful" mistakes) diff --git a/src/modules/wds/data/design-system/component-boundaries.md b/src/modules/wds/data/design-system/component-boundaries.md index 1d3ff5b1..6468ea7c 100644 --- a/src/modules/wds/data/design-system/component-boundaries.md +++ b/src/modules/wds/data/design-system/component-boundaries.md @@ -48,6 +48,7 @@ This is the most common design system challenge. **Answer:** Depends on usage: **Part of Button (Variant):** + ```yaml Button Component: variants: @@ -55,14 +56,17 @@ Button Component: - with-icon-right - icon-only ``` + **When:** Icon is always the same type (e.g., always arrow for navigation) **Separate Components:** + ```yaml Button Component: (text only) Icon Component: (standalone) Composition: Button + Icon ``` + **When:** Icons vary widely, button can exist without icon **Recommendation:** Start with variant, split if complexity grows. @@ -111,12 +115,14 @@ Composition: Card contains Button **Answer:** Depends on complexity: **Simple (Single Component):** + ```yaml Navigation Bar Component: includes: All nav items as configuration ``` **Complex (Composition):** + ```yaml Navigation Bar: (container) Navigation Item: (individual item) @@ -150,11 +156,13 @@ Composition: Nav Bar contains Nav Items ### Step 2: Consider Complexity **Low Complexity:** Keep together + - Icon in button - Label with input - Simple list items **High Complexity:** Split apart + - Complex nested structures - Independent behaviors - Different lifecycle @@ -162,10 +170,12 @@ Composition: Nav Bar contains Nav Items ### Step 3: Think About Maintenance **Together:** + - ✅ Easier to keep consistent - ❌ Component becomes complex **Apart:** + - ✅ Simpler components - ❌ More components to manage @@ -240,6 +250,7 @@ Button Component: ### Example 1: Button **One Component:** + ```yaml Button: variants: primary, secondary, ghost @@ -251,6 +262,7 @@ Button: ### Example 2: Input Types **Multiple Components:** + ```yaml Text Input: (text entry) Select Dropdown: (choose from list) @@ -263,6 +275,7 @@ Radio: (choose one) ### Example 3: Modal **Compound Component:** + ```yaml Modal: (overlay + container) Modal Header: (title + close button) @@ -277,6 +290,7 @@ Modal Footer: (actions) ## When in Doubt **Start simple:** + 1. Create as single component 2. Add variants as needed 3. Split when complexity becomes painful diff --git a/src/modules/wds/data/design-system/figma-component-structure.md b/src/modules/wds/data/design-system/figma-component-structure.md index c9337288..47dd5f6c 100644 --- a/src/modules/wds/data/design-system/figma-component-structure.md +++ b/src/modules/wds/data/design-system/figma-component-structure.md @@ -40,6 +40,7 @@ Design System File (Figma) ``` **Benefits:** + - Clear organization - Easy navigation - Matches WDS structure @@ -54,6 +55,7 @@ Design System File (Figma) **Pattern:** `[ComponentType]/[ComponentName]` **Examples:** + ``` Button/Primary Button/Secondary @@ -65,6 +67,7 @@ Card/Content ``` **Rules:** + - Use forward slash for hierarchy - Title case for names - Match WDS component names @@ -94,6 +97,7 @@ Card/Content - Padding/gap values **Example Description:** + ``` Button Primary [btn-001] @@ -112,17 +116,20 @@ WDS Component: Button.primary [btn-001] **Use Figma's variant properties:** **Property 1: Type** (variant) + - Primary - Secondary - Ghost - Outline **Property 2: Size** + - Small - Medium - Large **Property 3: State** + - Default - Hover - Active @@ -130,6 +137,7 @@ WDS Component: Button.primary [btn-001] - Loading **Property 4: Icon** (optional) + - None - Left - Right @@ -144,6 +152,7 @@ WDS Component: Button.primary [btn-001] **Format:** `Property=Value` **Examples:** + ``` Type=Primary, Size=Medium, State=Default Type=Primary, Size=Medium, State=Hover @@ -151,6 +160,7 @@ Type=Secondary, Size=Large, State=Disabled ``` **Benefits:** + - Clear property structure - Easy to find specific variants - MCP can parse programmatically @@ -163,6 +173,7 @@ Type=Secondary, Size=Large, State=Disabled ### Required States **Interactive Components (Buttons, Links):** + - Default - Hover - Active (pressed) @@ -171,6 +182,7 @@ Type=Secondary, Size=Large, State=Disabled - Loading (optional) **Form Components (Inputs, Selects):** + - Default (empty) - Focus (active) - Filled (has content) @@ -179,6 +191,7 @@ Type=Secondary, Size=Large, State=Disabled - Success (optional) **Feedback Components (Alerts, Toasts):** + - Default - Success - Error @@ -192,6 +205,7 @@ Type=Secondary, Size=Large, State=Disabled **Document state changes:** **Hover:** + - Background color change - Border change - Shadow change @@ -199,16 +213,19 @@ Type=Secondary, Size=Large, State=Disabled - Cursor change **Active:** + - Background color (darker) - Scale (slightly smaller) - Shadow (reduced) **Disabled:** + - Opacity (0.5-0.6) - Cursor (not-allowed) - Grayscale (optional) **Loading:** + - Spinner/progress indicator - Disabled interaction - Loading text @@ -222,6 +239,7 @@ Type=Secondary, Size=Large, State=Disabled **Map Figma variables to WDS tokens:** **Colors:** + ``` Figma Variable → WDS Token primary/500 → color-primary-500 @@ -230,6 +248,7 @@ success/600 → color-success-600 ``` **Typography:** + ``` Figma Style → WDS Token Text/Display → text-display @@ -238,6 +257,7 @@ Text/Body → text-body ``` **Spacing:** + ``` Figma Variable → WDS Token spacing/2 → spacing-2 @@ -246,6 +266,7 @@ spacing/8 → spacing-8 ``` **Effects:** + ``` Figma Effect → WDS Token shadow/sm → shadow-sm @@ -285,6 +306,7 @@ radius/md → radius-md ``` **Example:** + ``` Button Primary [btn-001] @@ -321,11 +343,13 @@ Button Primary [btn-001] ### Spacing **Use consistent spacing values:** + - Padding: 8px, 12px, 16px, 24px - Gap: 4px, 8px, 12px, 16px - Match WDS spacing tokens **Auto Layout Settings:** + - Horizontal/Vertical alignment - Padding (all sides or specific) - Gap between items @@ -338,16 +362,19 @@ Button Primary [btn-001] **Set appropriate constraints:** **Buttons:** + - Hug contents (width) - Fixed height - Min width for touch targets (44px) **Inputs:** + - Fill container (width) - Fixed height (40-48px) - Responsive to content **Cards:** + - Fill container or fixed width - Hug contents (height) - Responsive to content @@ -359,18 +386,21 @@ Button Primary [btn-001] ### Creating Instances **Best practices:** + - Always use component instances (not detached) - Override only necessary properties - Maintain connection to main component - Document overrides if needed **Overridable Properties:** + - Text content - Icons - Colors (if using variables) - Spacing (if needed) **Non-Overridable:** + - Structure - Layout - Core styling @@ -385,16 +415,19 @@ Button Primary [btn-001] **Add WDS component ID to Figma:** **In component description:** + ``` Button Primary [btn-001] ``` **In component name:** + ``` Button/Primary [btn-001] ``` **Benefits:** + - Easy to find components - Clear WDS mapping - MCP can extract ID @@ -407,16 +440,19 @@ Button/Primary [btn-001] **Figma generates unique node IDs:** **Format:** + ``` figma://file/[file-id]/node/[node-id] ``` **How to get node ID:** + 1. Select component in Figma 2. Right-click → "Copy link to selection" 3. Extract node ID from URL **Store in WDS:** + ```yaml # D-Design-System/figma-mappings.md Button [btn-001] → figma://file/abc123/node/456:789 @@ -495,12 +531,14 @@ Input [inp-001] → figma://file/abc123/node/456:790 ### ❌ Mistake 1: Hardcoded Values **Wrong:** + ``` Background: #2563eb (hardcoded hex) Padding: 16px (hardcoded value) ``` **Right:** + ``` Background: primary/600 (variable) Padding: spacing/4 (variable) @@ -509,11 +547,13 @@ Padding: spacing/4 (variable) ### ❌ Mistake 2: Detached Instances **Wrong:** + - Detaching component instances - Losing connection to main component - Manual updates required **Right:** + - Always use instances - Override only necessary properties - Maintain component connection @@ -521,6 +561,7 @@ Padding: spacing/4 (variable) ### ❌ Mistake 3: Inconsistent Naming **Wrong:** + ``` btn-primary ButtonSecondary @@ -528,6 +569,7 @@ button_ghost ``` **Right:** + ``` Button/Primary Button/Secondary @@ -537,11 +579,13 @@ Button/Ghost ### ❌ Mistake 4: Missing States **Wrong:** + - Only default state - No hover/active states - No disabled state **Right:** + - All required states - Visual differentiation - State transitions documented @@ -549,12 +593,14 @@ Button/Ghost ### ❌ Mistake 5: No WDS Component ID **Wrong:** + ``` Button Primary (no component ID) ``` **Right:** + ``` Button Primary [btn-001] (clear WDS mapping) @@ -569,6 +615,7 @@ Button Primary [btn-001] **Component Name:** `Button/Primary [btn-001]` **Description:** + ``` Button Primary [btn-001] @@ -581,6 +628,7 @@ Sizes: small, medium, large ``` **Variants:** + ``` Type=Primary, Size=Medium, State=Default Type=Primary, Size=Medium, State=Hover @@ -591,6 +639,7 @@ Type=Primary, Size=Large, State=Default ``` **Properties:** + - Auto Layout: Horizontal - Padding: 16px (horizontal), 12px (vertical) - Gap: 8px (if icon) @@ -604,6 +653,7 @@ Type=Primary, Size=Large, State=Default **Component Name:** `Input/Text [inp-001]` **Description:** + ``` Input Text [inp-001] @@ -614,6 +664,7 @@ States: default, focus, filled, disabled, error, success ``` **Variants:** + ``` State=Default State=Focus @@ -624,6 +675,7 @@ State=Success ``` **Properties:** + - Auto Layout: Horizontal - Padding: 12px - Height: 44px (fixed) diff --git a/src/modules/wds/data/design-system/naming-conventions.md b/src/modules/wds/data/design-system/naming-conventions.md index 354c4377..e478679f 100644 --- a/src/modules/wds/data/design-system/naming-conventions.md +++ b/src/modules/wds/data/design-system/naming-conventions.md @@ -11,6 +11,7 @@ **Format:** `[type-prefix]-[number]` **Prefixes:** + - btn = Button - inp = Input Field - chk = Checkbox @@ -25,11 +26,13 @@ - acc = Accordion **Examples:** + - `btn-001` = First button component - `inp-002` = Second input field component - `mdl-001` = First modal component **Rules:** + - Always lowercase - Always hyphenated - Always zero-padded (001, not 1) @@ -42,12 +45,14 @@ **Format:** `[Type] [Descriptor]` or just `[Type]` **Examples:** + - `Button` (generic) - `Navigation Button` (specific) - `Primary Button` (variant-focused) - `Icon Button` (visual-focused) **Rules:** + - Title case - Descriptive but concise - Avoid redundancy (not "Button Button") @@ -59,6 +64,7 @@ **Format:** Lowercase, hyphenated **Purpose-Based:** + - `primary` - Main action - `secondary` - Secondary action - `destructive` - Delete/remove @@ -67,16 +73,19 @@ - `navigation` - Navigation action **Visual-Based:** + - `outlined` - Border, no fill - `ghost` - Transparent background - `solid` - Filled background **Size-Based:** + - `small` - Compact - `medium` - Default - `large` - Prominent **Rules:** + - Lowercase - Hyphenated for multi-word - Semantic over visual when possible @@ -86,6 +95,7 @@ ## State Names **Standard States:** + - `default` - Normal state - `hover` - Mouse over - `active` - Being clicked/pressed @@ -97,6 +107,7 @@ - `warning` - Warning state **Rules:** + - Lowercase - Single word preferred - Use standard names when possible @@ -108,6 +119,7 @@ **Format:** `--{category}-{property}-{variant}` **Color Tokens:** + ``` --color-primary-500 --color-gray-900 @@ -116,6 +128,7 @@ ``` **Typography Tokens:** + ``` --text-xs --text-base @@ -125,6 +138,7 @@ ``` **Spacing Tokens:** + ``` --spacing-1 --spacing-4 @@ -132,6 +146,7 @@ ``` **Component Tokens:** + ``` --button-padding-x --input-border-color @@ -139,6 +154,7 @@ ``` **Rules:** + - Kebab-case - Hierarchical (general → specific) - Semantic names preferred @@ -148,6 +164,7 @@ ## File Names **Component Files:** + ``` button.md navigation-button.md @@ -155,6 +172,7 @@ input-field.md ``` **Rules:** + - Lowercase - Hyphenated - Match component name (simplified) @@ -172,6 +190,7 @@ templates/ ``` **Rules:** + - Lowercase - Hyphenated - Plural for collections diff --git a/src/modules/wds/data/design-system/state-management.md b/src/modules/wds/data/design-system/state-management.md index 7bf0c4c1..3a144e4e 100644 --- a/src/modules/wds/data/design-system/state-management.md +++ b/src/modules/wds/data/design-system/state-management.md @@ -11,24 +11,28 @@ ### Interactive Components (Buttons, Links) **Required:** + - `default` - Normal, ready for interaction - `hover` - Mouse over component - `active` - Being clicked/pressed - `disabled` - Cannot interact **Optional:** + - `loading` - Processing action - `focus` - Keyboard focus ### Form Components (Inputs, Selects) **Required:** + - `default` - Empty, ready for input - `focus` - Active input - `filled` - Has content - `disabled` - Cannot edit **Optional:** + - `error` - Validation failed - `success` - Validation passed - `loading` - Fetching data @@ -36,6 +40,7 @@ ### Feedback Components (Alerts, Toasts) **Required:** + - `default` - Neutral information - `success` - Positive feedback - `error` - Error feedback @@ -46,6 +51,7 @@ ## State Naming **Use standard names:** + - ✅ `hover` not `mouseover` - ✅ `disabled` not `inactive` - ✅ `loading` not `processing` @@ -59,8 +65,7 @@ **Define how states change:** ```yaml -Button States: - default → hover (mouse enters) +Button States: default → hover (mouse enters) hover → active (mouse down) active → hover (mouse up) hover → default (mouse leaves) diff --git a/src/modules/wds/data/design-system/token-architecture.md b/src/modules/wds/data/design-system/token-architecture.md index e02d4ca0..cdea03bf 100644 --- a/src/modules/wds/data/design-system/token-architecture.md +++ b/src/modules/wds/data/design-system/token-architecture.md @@ -22,13 +22,13 @@ They should be independent! ## The Problem **Bad Practice:** + ```html -

- Heading -

+

Heading

``` **Issues:** + - Visual styling mixed with semantic HTML - Can't change h2 appearance without changing all h2s - h2 means "second-level heading" but looks like "display large" @@ -41,13 +41,13 @@ They should be independent! **Good Practice:** **HTML (Semantic):** + ```html -

- Heading -

+

Heading

``` **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

``` **✅ Good:** + ```yaml

``` @@ -338,6 +357,7 @@ Button: ## Token Naming Conventions ### Colors + ``` --color-{category}-{shade} --color-primary-600 @@ -346,6 +366,7 @@ Button: ``` ### Typography + ``` --text-{size} --text-base @@ -354,6 +375,7 @@ Button: ``` ### Spacing + ``` --spacing-{scale} --spacing-2 @@ -362,6 +384,7 @@ Button: ``` ### Component-Specific + ``` --{component}-{property}-{variant} --button-padding-primary @@ -376,11 +399,13 @@ Button: ### Phase 4: Page Specification **Agent specifies:** + - Semantic HTML elements - Component references - Content and labels **Agent does NOT specify:** + - Exact colors - Exact sizes - Exact spacing @@ -388,26 +413,30 @@ Button: ### Phase 5: Design System **Agent specifies:** + - Design tokens - Component styling - Visual properties **Agent does NOT specify:** + - Page-specific content - Semantic structure ### Integration **Page spec references design system:** + ```yaml Hero: heading: element: h2 token: heading-hero ← Reference to design system - content: "Welcome" + content: 'Welcome' ``` **Design system defines token:** + ```yaml Tokens: heading-hero: diff --git a/src/modules/wds/data/design-system/validation-patterns.md b/src/modules/wds/data/design-system/validation-patterns.md index 35299158..831fd1bf 100644 --- a/src/modules/wds/data/design-system/validation-patterns.md +++ b/src/modules/wds/data/design-system/validation-patterns.md @@ -11,26 +11,29 @@ ### Client-Side Validation **Required Fields:** + ```yaml validation: required: true - message: "This field is required" + message: 'This field is required' ``` **Format Validation:** + ```yaml validation: type: email pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ - message: "Please enter a valid email address" + message: 'Please enter a valid email address' ``` **Length Validation:** + ```yaml validation: minLength: 8 maxLength: 100 - message: "Password must be 8-100 characters" + message: 'Password must be 8-100 characters' ``` --- @@ -38,12 +41,14 @@ validation: ## Error States **Visual Indicators:** + - Red border - Error icon - Error message below field - Error color for label **Timing:** + - Show on blur (after user leaves field) - Show on submit attempt - Clear on valid input @@ -53,11 +58,13 @@ validation: ## Success States **Visual Indicators:** + - Green border (optional) - Success icon (optional) - Success message (optional) **When to Show:** + - After successful validation - For critical fields (password strength) - For async validation (username availability) diff --git a/src/modules/wds/data/presentations/freyja-intro.md b/src/modules/wds/data/presentations/freyja-intro.md index ddca76af..bc179327 100644 --- a/src/modules/wds/data/presentations/freyja-intro.md +++ b/src/modules/wds/data/presentations/freyja-intro.md @@ -9,6 +9,7 @@ **My Essence**: Like the Norse goddess of beauty and magic, I envision what doesn't exist yet and bring it to life through thoughtful, strategic design. **Required Input Documents**: + - `docs/A-Product-Brief/` - Strategic foundation from Saga - `docs/B-Trigger-Map/` - User insights and business goals from Saga - `docs/C-Platform-Requirements/` - Technical constraints from Idunn (optional but helpful) @@ -75,6 +76,7 @@ docs/ ## 🌟 My WDS Workflow: "From Strategy to Radiant Experiences" ### 🎯 **MY FOUR-PHASE CREATIVE JOURNEY** + ``` 🚀 FREYJA'S CREATIVE TRANSFORMATION: @@ -100,16 +102,19 @@ Continuous Improvement → Targeted Changes → Visual Refinement → User Delig ### 🤝 **MY TEAM INTEGRATION**: How I Work with the Team **With Saga (Analyst):** + - I use her strategic foundation and user personas to create realistic scenarios - She provides the business goals and user insights I need for effective design - We collaborate on user journey mapping and experience strategy **With Idunn (PM):** + - I work in parallel with her during Phase 3-4 (she does platform, I do design) - She provides technical constraints from platform requirements - We collaborate in Phase 6 to package my designs into deliveries **With BMM (Development):** + - I provide interactive prototypes and detailed specifications - BMM implements my designs into production code - I validate their implementation in Phase 7 (Testing) @@ -119,7 +124,9 @@ Continuous Improvement → Targeted Changes → Visual Refinement → User Delig ## 💎 My Creative Design Tools: From Strategy to Radiant Reality ### 🎨 **MY INTERACTIVE PROTOTYPE MASTERY** + **Here's exactly what I deliver in Phase 4:** + - **Interactive Prototypes**: Working HTML/CSS prototypes users can click through - **User Scenarios**: Detailed journey mapping with page specifications - **Visual Sketches**: Hand-drawn concepts and interaction flows @@ -129,6 +136,7 @@ Continuous Improvement → Targeted Changes → Visual Refinement → User Delig **Every prototype I create lets users experience the design before development begins.** ### 🏗️ **MY FOUNDATION-FIRST DESIGN SYSTEM PROCESS** + **Here's exactly how I build design systems in Phase 5:** ``` @@ -143,7 +151,9 @@ Foundation First → Component Hierarchy → Organic Growth → Lean & Practical **I establish the design system foundation FIRST, then discover components naturally through actual design work!** This ensures every component is needed and used, creating a lean, practical design system. ### 🧪 **MY TESTING & VALIDATION PROCESS** + **Here's exactly how I validate implementation in Phase 7:** + - **Designer Validation**: I check if BMM's implementation matches my design intent - **Test Scenarios**: I execute test cases to validate functionality - **Issue Creation**: I document problems and deviations found @@ -152,7 +162,9 @@ Foundation First → Component Hierarchy → Organic Growth → Lean & Practical **I'm the quality guardian - ensuring what gets built matches what was designed!** ### 🔄 **MY PRODUCT DEVELOPMENT APPROACH** + **Here's exactly how I improve existing products in Phase 8:** + - **Kaizen Philosophy**: Continuous improvement through small, thoughtful changes - **Brownfield Approach**: Working within existing constraints and systems - **Targeted Improvements**: Strategic enhancements to existing screens and flows @@ -167,16 +179,19 @@ Foundation First → Component Hierarchy → Organic Growth → Lean & Practical **Here's exactly what changes when I enter your workflow:** ### 🎨 **FROM STRATEGIC CONCEPTS TO EXPERIENCES USERS LOVE** + - Saga's strategic foundation becomes beautiful, magical experiences - Users can experience the design before development begins - Clear visual specifications guide every development decision -### ⚡ **FROM DESIGN CHAOS TO SYSTEMATIC EXCELLENCE** +### ⚡ **FROM DESIGN CHAOS TO SYSTEMATIC EXCELLENCE** + - Component library eliminates design inconsistency and rework - Systematic approach ensures every interaction is thoughtfully designed - Creative process becomes repeatable and scalable ### 💫 **FROM HANDOFF CONFUSION TO VALIDATED QUALITY** + - I validate BMM's implementation matches design intent - Testing catches problems before users see them - Continuous improvement keeps products delightful @@ -202,12 +217,14 @@ Foundation First → Component Hierarchy → Organic Growth → Lean & Practical **These creative conventions ensure my deliverables are development-ready:** ### 🏗️ **MY CREATIVE ARCHITECTURE MASTERY** + - **Strategic Input**: Saga's Product Brief and Trigger Map - **Technical Input**: Idunn's Platform Requirements (optional) - **My Creative Output**: C-Scenarios/, D-Design-System/, F-Testing/, G-Product-Development/ - **Title-Case-With-Dashes**: Every folder and file follows WDS standards ### 🎨 **MY CREATIVE WORKFLOW PROGRESSION** + ``` My Design Journey: Saga's Strategy → Interactive Prototypes → Scenarios → Design System → BMM Implementation → Validation → Iteration @@ -217,6 +234,7 @@ Business Goals → Delightful UX → Detailed Specs → Reusable Patterns → Wo ``` ### ✨ **MY COMMUNICATION EXCELLENCE STANDARDS** + - **Crystal-clear design language** without confusing jargon - **Empathetic, creative style** that paints pictures with words - **Professional design readiness** throughout all my creative work @@ -232,12 +250,14 @@ Business Goals → Delightful UX → Detailed Specs → Reusable Patterns → Wo ## Presentation Notes for Freyja **When to Use:** + - When Freyja activates as the Designer - When users need UX design, prototypes, or design systems - After Saga completes strategic foundation - When teams need visual specifications and creative work **Key Delivery Points:** + - Maintain empathetic, creative tone throughout - Emphasize beauty, magic, and strategy (Freyja's essence) - Show how Freyja works across multiple phases (4, 5, 7, 8) @@ -246,6 +266,7 @@ Business Goals → Delightful UX → Detailed Specs → Reusable Patterns → Wo - Confirm user enthusiasm before proceeding **Success Indicators:** + - User understands Freyja's multi-phase role - Interactive prototypes value is clear - Foundation-first design system approach is understood diff --git a/src/modules/wds/data/presentations/idunn-intro.md b/src/modules/wds/data/presentations/idunn-intro.md index b34e8700..920f9b67 100644 --- a/src/modules/wds/data/presentations/idunn-intro.md +++ b/src/modules/wds/data/presentations/idunn-intro.md @@ -9,6 +9,7 @@ **My Essence**: Like the golden apples that keep the gods vital and young, I keep your project healthy, modern, and thriving through careful coordination and renewal. **Required Input Documents**: + - `docs/A-Product-Brief/` - Strategic foundation from Saga - `docs/B-Trigger-Map/` - Business goals and user insights from Saga @@ -53,6 +54,7 @@ docs/ ## 🌟 My WDS Workflow: "Strategic Bridge from Vision to Execution" ### 🎯 **MY TWO-PHASE APPROACH** + ``` 🚀 IDUNN'S STRATEGIC COORDINATION: @@ -70,16 +72,19 @@ Interactive Prototypes → Functional Requirements → DD-XXX.yaml Packages → ### 🤝 **MY TEAM INTEGRATION**: How I Work with the Team **With Saga (Analyst):** + - I use her strategic foundation to create platform requirements - She provides the business goals and success metrics I need - We ensure strategic alignment throughout **With Freyja (Designer):** + - I work in parallel during Phase 3 while she designs in Phase 4 - I provide technical constraints from platform requirements - We collaborate in Phase 6 to package her designs into deliveries **With BMM (Development):** + - I provide platform requirements for technical foundation - I package complete flows as Design Deliveries (DD-XXX.yaml) - BMM uses my deliveries to create the development PRD @@ -89,7 +94,9 @@ Interactive Prototypes → Functional Requirements → DD-XXX.yaml Packages → ## 💎 My Coordination Tools: From Strategy to Delivery ### 🎯 **MY PLATFORM REQUIREMENTS MASTERY** + **Here's exactly what I deliver in Phase 3:** + - **Platform Architecture**: Tech stack, infrastructure design, deployment strategy - **Data Model**: Core entities, relationships, data flow - **Integration Map**: External services, APIs, third-party systems @@ -99,6 +106,7 @@ Interactive Prototypes → Functional Requirements → DD-XXX.yaml Packages → **Every platform requirement I create enables confident design decisions.** ### 📦 **MY DESIGN DELIVERIES PROCESS** + **Here's exactly how I package Freyja's designs in Phase 6:** ``` @@ -111,6 +119,7 @@ User Flows → Page Requirements → Epic Mapping → Test Scenarios → Systema ``` **Each Design Delivery (DD-XXX.yaml) contains:** + - Flow metadata (name, epic, priority) - Scenario references (which pages in C-Scenarios/) - Component references (which components in D-Design-System/) @@ -127,16 +136,19 @@ User Flows → Page Requirements → Epic Mapping → Test Scenarios → Systema **Here's exactly what changes when I enter your workflow:** ### 🎯 **FROM DESIGN GUESSWORK TO TECHNICAL CLARITY** + - Platform requirements provide clear constraints before design begins - Freyja knows what's technically possible and what's not - Design decisions are confident, not speculative -### ⚡ **FROM SEQUENTIAL WORK TO PARALLEL PROGRESS** +### ⚡ **FROM SEQUENTIAL WORK TO PARALLEL PROGRESS** + - I create platform requirements while Freyja designs (Phase 3 + 4 parallel) - Backend foundation can start before design is complete - No waiting - everyone works efficiently ### 💫 **FROM HANDOFF CHAOS TO PACKAGED DELIVERIES** + - Design Deliveries are complete, testable flow packages - BMM receives organized, implementable units - Iterative handoffs - deliver flows as they're ready @@ -162,12 +174,14 @@ User Flows → Page Requirements → Epic Mapping → Test Scenarios → Systema **These coordination conventions ensure my deliverables are development-ready:** ### 🏗️ **MY PM ARCHITECTURE MASTERY** + - **Strategic Input**: Saga's Product Brief and Trigger Map - **Design Input**: Freyja's prototypes and specifications - **My PM Output**: C-Platform-Requirements/, E-PRD/ (coordination I create) - **Title-Case-With-Dashes**: Every folder and file follows WDS standards ### 🎨 **MY TWO-PHASE COORDINATION PROCESS** + ``` My PM Workflow Progression: Saga's Strategy → Platform Requirements → Freyja's Design → Design Deliveries → BMM Development @@ -177,6 +191,7 @@ Business Goals → Design Constraints → User Flows → Testable Units → Syst ``` ### ✨ **MY COMMUNICATION EXCELLENCE STANDARDS** + - **Clear coordination language** without confusing technical jargon - **Strategic thinking** about priorities, trade-offs, and dependencies - **Professional documentation** throughout all my PM deliverables @@ -192,12 +207,14 @@ Business Goals → Design Constraints → User Flows → Testable Units → Syst ## Presentation Notes for Idunn **When to Use:** + - When Idunn activates as the Product Manager - When users need platform requirements or design deliveries - After Saga completes strategic foundation - When teams need coordination between design and development **Key Delivery Points:** + - Maintain strategic, warm tone throughout - Emphasize parallel work and bottleneck elimination - Show how Idunn coordinates with Saga and Freyja @@ -206,6 +223,7 @@ Business Goals → Design Constraints → User Flows → Testable Units → Syst - Confirm user enthusiasm before proceeding **Success Indicators:** + - User understands two-phase approach (Phase 3 + Phase 6) - Platform requirements value is clear - Design Deliveries packaging is understood diff --git a/src/modules/wds/data/presentations/saga-intro.md b/src/modules/wds/data/presentations/saga-intro.md index ef1f7ca8..0401ca79 100644 --- a/src/modules/wds/data/presentations/saga-intro.md +++ b/src/modules/wds/data/presentations/saga-intro.md @@ -15,6 +15,7 @@ I'm named after Saga, the Norse goddess of stories and wisdom - because every pr **My Entry Point**: I work at the very beginning of the WDS process, creating the Product Brief and Trigger Map that become the North Star for everything that follows. **What I Need to Get Started**: + - Your project vision and business goals - Market research and competitive analysis needs - Target user group information @@ -45,7 +46,7 @@ docs/ │ ├── 02-Competitive-Analysis.md ← Competitor deep-dive (I analyze this) │ └── 03-Key-Features.md ← Core functionality (I define these) │ -├── 🗺️ B-Trigger-Map/ ← MY Journey Intelligence Center +├── 🗺️ B-Trigger-Map/ ← MY Journey Intelligence Center │ ├── 00-Trigger-Map.md ← Complete trigger map (I map this) │ │ ├── Business Goals ← What business wants to achieve │ │ ├── Target Groups ← User segmentation @@ -91,18 +92,21 @@ Clear Business Direction → Deep User Understanding → Systematic User ### 🤝 **MY TEAM INTEGRATION**: How I Work with the WDS Team **With Baldr (UX Expert):** + - I provide the strategic foundation and user insights needed for design - Baldr uses my trigger map personas to create realistic user scenarios - We collaborate on user journey mapping and experience design - My business goals guide Baldr's design decisions **With Freyja (Product Manager):** + - I hand off my strategic foundation for PRD development - Freyja uses my business goals and success metrics for planning - We ensure strategic alignment throughout the design process - My trigger map informs Freyja's feature prioritization **Integration with BMM (Development):** + - My Product Brief provides context for architecture decisions - My Trigger Map personas inform user story creation - My success metrics guide development priorities @@ -115,6 +119,7 @@ Clear Business Direction → Deep User Understanding → Systematic User ### 🎯 **MY MARKET INTELLIGENCE MASTERY** **Here's exactly what I deliver:** + - **Strategic Analysis**: including comprehensive market research and competitive positioning - **Business Vision**: designed for measurable success and stakeholder alignment - **User Intelligence**: meaning detailed personas and journey mapping for systematic design @@ -140,6 +145,7 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S ### 🔧 **MY DELIVERABLES: What You Get from Saga** #### **Strategic Foundation Package:** + ``` 📚 COMPLETE STRATEGIC INTELLIGENCE: ├── Product Brief with Clear Value Proposition @@ -161,18 +167,21 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S **Here's exactly what changes when I enter your workflow:** ### 🎯 **FROM VAGUE IDEAS TO STRATEGIC CLARITY** + - Your brilliant concepts become measurable business strategies - Market research eliminates guesswork and validates your approach - Clear success metrics guide every team decision - User psychology insights drive design decisions -### ⚡ **FROM CHAOTIC PLANNING TO SYSTEMATIC EXECUTION** +### ⚡ **FROM CHAOTIC PLANNING TO SYSTEMATIC EXECUTION** + - Strategic foundation eliminates confusion and misalignment - Every team member knows exactly what success looks like - Stakeholder communication becomes clear and compelling - Trigger mapping reveals the psychology behind user behavior ### 💫 **FROM INDIVIDUAL EFFORT TO TEAM COORDINATION** + - My strategic foundation coordinates all team members - Clear business goals align creative and technical work - Systematic approach ensures nothing falls through the cracks @@ -185,7 +194,7 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S **What excites you most about having me (Saga) create your strategic foundation:** 1. **📊 Market Intelligence Mastery** - I research your market and competitors to eliminate guesswork -2. **📋 Product Brief Excellence** - I transform your ideas into clear, measurable business strategies +2. **📋 Product Brief Excellence** - I transform your ideas into clear, measurable business strategies 3. **🗺️ Trigger Map Intelligence** - I map user psychology and business goals for systematic design 4. **🎯 Success Metrics Definition** - I establish clear KPIs and measurable goals for your project 5. **🤝 Team Coordination Foundation** - I create the strategic foundation that guides all team members @@ -200,12 +209,14 @@ Raw Ideas → Market Understanding → Clear Vision → User Intelligence → S **These elegant strategic conventions ensure my deliverables are enterprise-ready:** ### 🏗️ **MY STRATEGIC ARCHITECTURE MASTERY** + - **Strategic Input**: Your vision, ideas, and business goals - **My Analysis Output**: A-Product-Brief/, B-Trigger-Map/ (strategic foundation I create) - **Title-Case-With-Dashes**: Every folder and file I create follows enterprise presentation standards - **Absolute Paths**: I always use absolute paths (docs/A-Product-Brief/) for clarity ### 🎨 **MY STRATEGIC ANALYSIS EVOLUTION PROCESS** + ``` My Strategic Workflow Progression: Your Ideas → Market Research → Product Brief → Trigger Map → Strategic Foundation @@ -215,6 +226,7 @@ Vision Clarity → Market Understanding → Clear Strategy → User Intelligence ``` ### ✨ **MY COMMUNICATION EXCELLENCE STANDARDS** + - **Crystal-clear strategic language** without confusing technical jargon - **Professional analysis style** using "including", "designed for", "meaning" conventions - **Collaborative approach** - one question at a time, deep listening @@ -230,6 +242,7 @@ Vision Clarity → Market Understanding → Clear Strategy → User Intelligence In Norse mythology, Saga is the goddess of stories and wisdom. She sits with Odin in her hall Sökkvabekkr ("sunken benches" or "treasure benches"), where they drink together and share stories. This perfectly captures what I do: + - **Stories**: Every product has a story - I help you discover and tell it - **Wisdom**: I bring strategic intelligence and market insights to guide decisions - **Listening**: Like Saga listening to Odin's tales, I listen deeply to understand your vision @@ -246,12 +259,14 @@ This perfectly captures what I do: ## Presentation Notes for Saga **When to Use:** + - When Saga activates as the Business Analyst - When users need strategic foundation and market intelligence - At the start of any new WDS project - When teams need clear business direction and user insights **Key Delivery Points:** + - Maintain analytical, strategic tone throughout - Emphasize strategic foundation building, not just research - Show how Saga's work coordinates with Freyja and Baldr @@ -261,6 +276,7 @@ This perfectly captures what I do: - Confirm user enthusiasm for strategic approach before proceeding **Success Indicators:** + - User expresses excitement about strategic foundation approach - Market research and analysis methodology is clearly understood - Team coordination value is appreciated diff --git a/src/modules/wds/docs/method/phase-1-product-exploration-guide.md b/src/modules/wds/docs/method/phase-1-product-exploration-guide.md index df714026..e96b593a 100644 --- a/src/modules/wds/docs/method/phase-1-product-exploration-guide.md +++ b/src/modules/wds/docs/method/phase-1-product-exploration-guide.md @@ -43,6 +43,7 @@ People light up when asked to share their vision. They become collaborators, not **Opening (5-10 minutes)** Saga asks about your project in your own words. She listens for: + - What you emphasize naturally - Where your energy goes - What excites vs. what stresses you @@ -51,6 +52,7 @@ Saga asks about your project in your own words. She listens for: **Exploration (15-30 minutes)** The conversation adapts to what you reveal: + - If you mention users → deeper into user insights - If you mention problems → explore the cost of not solving - If you mention competition → discover differentiation @@ -61,6 +63,7 @@ Each answer reveals the next question. It's jazz, not classical music. **Synthesis (10-15 minutes)** Saga reflects back your vision in organized form: + - Connecting dots you shared across topics - Highlighting insights you might not have seen - Building the foundation for next phases @@ -68,6 +71,7 @@ Saga reflects back your vision in organized form: ### Living Document As you talk, the Product Brief grows in real-time: + - Immediate validation and refinement - Real-time course correction - You own the content because you helped create it @@ -78,11 +82,13 @@ As you talk, the Product Brief grows in real-time: ## When to Use This Phase **Always start here if:** + - Building something new - Starting a new project - Need strategic clarity before diving into design **Skip if:** + - You already have a clear, documented product brief - Just enhancing an existing feature - Working on a design system without new product context @@ -92,6 +98,7 @@ As you talk, the Product Brief grows in real-time: ## What to Prepare Come ready to share: + - Your project idea (even if rough) - The problem you're solving - Who might use it @@ -116,18 +123,22 @@ The brief becomes the reference point everyone shares. ## Tips for Great Sessions **Let the conversation flow** + - Share what feels important, even if it seems tangential - Follow your energy - where you're excited matters **Think out loud** + - Half-formed thoughts are welcome - will help you refine them **Be honest about uncertainty** + - "I'm not sure about X" is useful information - Better to surface doubts now than later **Review as you go** + - Check that what's captured matches your thinking - Correct misunderstandings immediately @@ -139,5 +150,4 @@ See: `examples/dog-week-patterns/A-Product-Brief/` for a complete Product Brief --- -*Phase 1 of the Whiteport Design Studio method* - +_Phase 1 of the Whiteport Design Studio method_ diff --git a/src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md b/src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md index 98ef9df9..f346886b 100644 --- a/src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md +++ b/src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md @@ -38,9 +38,10 @@ WDS Trigger Mapping is based on the groundbreaking **Effect Management** methodo The methodology gained wider recognition through Gojko Adzic's book **"Impact Mapping: Making a Big Impact with Software Products and Projects"** (2012), which acknowledges Effect Mapping as a key influence. > **Founder's Note:** I personally acquired the insights about the power of the Effect Map back in 2007, and it has served as the philosophical basis for all of my work in UX for almost 20 years. I am eternally grateful for this model that I now have the pleasure to share with the world in an updated version suitable for modern projects. -> — *Martin Eriksson, WDS Creator* +> — _Martin Eriksson, WDS Creator_ 📚 **Further Reading:** + - [Impact Mapping on Amazon](https://www.amazon.com/Impact-Mapping-Software-Products-Projects/dp/0955683645) - Gojko Adzic's book building on Effect Mapping concepts - [impactmapping.org](https://www.impactmapping.org) - Resources and community @@ -53,11 +54,13 @@ Effect Mapping is the original model that connects business goals to user behavi Trigger Mapping is WDS's adaptation of Effect Mapping, designed for longer shelf life and deeper psychological insight: **Simplified:** + - Leaves out actions/features from the map - Focuses on the strategic connections - Map stays relevant even as features evolve **Enhanced:** + - Adds **negative driving forces** (fears, frustrations) - Creates fuller picture of user psychology - Both what users want AND what they want to avoid @@ -67,6 +70,7 @@ Trigger Mapping is WDS's adaptation of Effect Mapping, designed for longer shelf Any software is about **flow of value**. There's always a group of people who, through their use of the software, make your success happen. These users have their own goals: + - **GAIN** - Benefits and positive outcomes they achieve - **PAIN** - Resistance and friction they experience @@ -81,10 +85,11 @@ The Trigger Map combines three critical layers in one picture: 3. **Usage Goals** - Their WHY (Driving forces both positive - what they wish to achieve, and negative - what they wish to avoid) When all levels are then prioritized, you have perfect guidance for design: + - Present features that add value to your most prioritized goal first - To the highest prioritized target group - In a way that best suits their most prioritized usage goal -- Make sound decisions about priority of bugs or features based on the total impact on users' goals +- Make sound decisions about priority of bugs or features based on the total impact on users' goals --- @@ -98,18 +103,21 @@ Business goals work at two levels: **Vision (Motivating, not easily quantifiable)** A statement that inspires and guides direction: + - "Become the most popular free and open source design support framework" - "Be the go-to partner for SMB digital transformation" - "Make professional UX accessible to every startup" **Objectives (SMART metrics)** Specific, measurable targets that indicate progress toward the vision: + - "10,000 active designer users by 2027" - "100 community contributions accepted by Q4 2026" - "50% of users complete full 6-phase workflow" - "NPS score of 60+ from design professionals" You'll define both levels: + - Vision that motivates the team - Objectives with clear success metrics @@ -118,6 +126,7 @@ You'll define both levels: Key question: "Who needs to succeed for YOU to succeed?" Instead of demographics, you discover: + - User types who can drive business success - The role each type plays in your strategy - How different users contribute differently @@ -134,6 +143,7 @@ For each user type: "Now the flip side: What do they desperately want to avoid? What would feel like failure?" This reveals: + - **Positive Triggers** - What motivates action - **Negative Triggers** - What prevents engagement - **Emotional Drivers** - The psychology behind decisions @@ -142,6 +152,7 @@ This reveals: ### Stage 4: Visual Strategy Map (15-20 minutes) Saga helps build the complete trigger map: + - Connecting every user insight to business goals - Creating the visual strategy guide - Validating the strategic logic together @@ -171,37 +182,38 @@ Now the magic happens. You connect strategy to concrete features using a systema 3. **Map to Driving Forces** - Which positive and negative drivers does it address? 4. **Score the Impact** - Features serving multiple groups and drivers score higher -**The Scoring System:** *(Beta - refinements welcome)* +**The Scoring System:** _(Beta - refinements welcome)_ For each feature, award points: -| Impact | Points | -|--------|--------| -| Serves Priority 1 Target Group | +3 | -| Serves Priority 2 Target Group | +2 | -| Serves Priority 3 Target Group | +1 | -| Addresses Priority 1 Positive Driver | +3 | -| Addresses Priority 2 Positive Driver | +2 | -| Addresses Priority 3 Positive Driver | +1 | -| **Addresses Priority 1 Negative Driver** | **+4** | -| **Addresses Priority 2 Negative Driver** | **+3** | -| **Addresses Priority 3 Negative Driver** | **+2** | -| Serves multiple target groups | +2 bonus | +| Impact | Points | +| -------------------------------------------- | -------- | +| Serves Priority 1 Target Group | +3 | +| Serves Priority 2 Target Group | +2 | +| Serves Priority 3 Target Group | +1 | +| Addresses Priority 1 Positive Driver | +3 | +| Addresses Priority 2 Positive Driver | +2 | +| Addresses Priority 3 Positive Driver | +1 | +| **Addresses Priority 1 Negative Driver** | **+4** | +| **Addresses Priority 2 Negative Driver** | **+3** | +| **Addresses Priority 3 Negative Driver** | **+2** | +| Serves multiple target groups | +2 bonus | | Addresses both positive AND negative drivers | +2 bonus | > **Why negative drivers score higher:** Loss aversion is a well-documented psychological principle - humans work harder to avoid pain than to pursue gain. Features that remove friction, fear, or frustration create stronger user loyalty than features that simply add benefits. **Example:** -| Feature | Target Groups | Driving Forces | Score | -|---------|---------------|----------------|-------| +| Feature | Target Groups | Driving Forces | Score | +| ----------------- | --------------------------------- | --------------------------------------------------------------------------------- | ------ | | One-click booking | P1 Dog Owner (+3), P2 Walker (+2) | Convenience (+3), Fear of complexity (-P1: +4), Multi-group (+2), Both types (+2) | **16** | -| Review system | P1 Dog Owner (+3) | Trust (+2), Fear of bad walker (-P1: +4), Both types (+2) | **11** | -| Calendar sync | P2 Walker (+2) | Efficiency (+1) | **3** | +| Review system | P1 Dog Owner (+3) | Trust (+2), Fear of bad walker (-P1: +4), Both types (+2) | **11** | +| Calendar sync | P2 Walker (+2) | Efficiency (+1) | **3** | **The Output:** A ranked feature list showing: + - Which features have the broadest impact - Which features are "single-purpose" vs "multi-impact" - Natural MVP candidates (highest scores) @@ -220,11 +232,13 @@ Traditional personas describe demographics: "Jennifer, 34, likes yoga and lattes WDS personas capture psychology: **Alliterative Naming** - Each persona gets a memorable name that hints at their role: + - "Patrick the Professional" - Decision-maker focused on efficiency - "Sophie the Socializer" - Values connection and community - "Tyler the Technical" - Wants control and customization **What Each Persona Includes:** + - Role and context - Goals they're trying to achieve - Fears and frustrations @@ -237,16 +251,19 @@ WDS personas capture psychology: ## When to Use This Phase **Use after Phase 1 if:** + - Building a new product - Need clarity on who you're building for - Want design decisions grounded in user psychology **Start here if:** + - You have product vision but unclear user strategy - Existing personas feel shallow or unused - Features aren't connecting with users **Skip if:** + - Quick enhancement to existing feature - Users are already well-documented and validated - Design system work without new user research @@ -256,6 +273,7 @@ WDS personas capture psychology: ## What to Prepare Bring: + - Your completed Product Brief (Phase 1) - Any existing user research (even informal) - Stakeholder availability for the workshop @@ -277,15 +295,18 @@ The trigger map becomes the strategic brain of your product. ## Tips for Great Sessions **Think strategically, not demographically** + - "Who needs to win for us to win?" not "Who might use this?" - Connect every user insight to business outcomes **Go deep on psychology** + - Push beyond surface responses - Ask "why" multiple times - Understand motivations, not just behaviors **Build the map live** + - See connections as they emerge - Validate strategic logic together - Make it visual and shareable @@ -298,5 +319,4 @@ See: `examples/dog-week-patterns/B-Trigger-Map/` for a complete Trigger Map with --- -*Phase 2 of the Whiteport Design Studio method* - +_Phase 2 of the Whiteport Design Studio method_ diff --git a/src/modules/wds/docs/method/phase-3-prd-platform-guide.md b/src/modules/wds/docs/method/phase-3-prd-platform-guide.md index 1fd005ad..813f0ea0 100644 --- a/src/modules/wds/docs/method/phase-3-prd-platform-guide.md +++ b/src/modules/wds/docs/method/phase-3-prd-platform-guide.md @@ -18,6 +18,7 @@ By the end, you'll have a solid technical foundation and confidence that your ke **Prove our concept works technically — in parallel with design work.** While UX designers explore how users interact with features, technical validation runs alongside: + - Can we actually build this? - Do the external services we need exist and work as expected? - What platform and infrastructure do we need? @@ -46,12 +47,14 @@ Design and technical validation inform each other. Neither waits for the other t Establish the technical foundation: **Architecture:** + - What technology stack fits your needs? - Monolith vs. microservices vs. serverless? - What hosting/infrastructure approach? - What are the key technical constraints? **Data Model:** + - What are the core entities? - How do they relate to each other? - What's the database strategy? @@ -72,15 +75,16 @@ Identify all external dependencies: **Examples:** -| Feature Idea | Proof of Concept Question | -|--------------|---------------------------| +| Feature Idea | Proof of Concept Question | +| ----------------------------------- | ------------------------------------------------------------------ | | "Show drive time between locations" | Can we call Google Maps Directions API and get estimated duration? | -| "Real-time availability updates" | Can we set up WebSocket connections that scale? | -| "AI-powered recommendations" | Does the ML model perform well enough with our data? | -| "Offline mode" | Can we sync data reliably when connection returns? | -| "Video calling" | Which provider works best? What's the latency? | +| "Real-time availability updates" | Can we set up WebSocket connections that scale? | +| "AI-powered recommendations" | Does the ML model perform well enough with our data? | +| "Offline mode" | Can we sync data reliably when connection returns? | +| "Video calling" | Which provider works best? What's the latency? | **What a PoC validates:** + - The API/service exists and does what we need - Performance is acceptable - Cost is within budget @@ -88,6 +92,7 @@ Identify all external dependencies: - Edge cases are handleable **PoC Output:** + - Working code snippet or prototype - Documented limitations and gotchas - Cost estimates (API calls, compute, etc.) @@ -98,12 +103,14 @@ Identify all external dependencies: ### Stage 4: Security & Performance Framework (20-30 minutes) **Security:** + - Authentication approach (passwords, OAuth, SSO, passwordless) - Authorization model (roles, permissions, row-level security) - Data encryption needs (at rest, in transit) - Compliance requirements (GDPR, HIPAA, PCI-DSS, etc.) **Performance:** + - Expected load and scale - Response time expectations - Availability requirements (99.9%? 99.99%?) @@ -122,16 +129,17 @@ Even before the UI is designed, you often know certain data operations are essen **What to set up:** -| Endpoint Type | Example | Why Early? | -|---------------|---------|------------| -| Core CRUD | `GET /api/dogs`, `POST /api/bookings` | Foundation for everything | +| Endpoint Type | Example | Why Early? | +| --------------------- | ---------------------------------------- | --------------------------- | +| Core CRUD | `GET /api/dogs`, `POST /api/bookings` | Foundation for everything | | External integrations | `GET /api/routes/estimate` (Google Maps) | Validates third-party works | -| Authentication | `/api/auth/login`, `/api/auth/refresh` | Security model proven | -| Key calculations | `/api/availability/check` | Business logic validated | +| Authentication | `/api/auth/login`, `/api/auth/refresh` | Security model proven | +| Key calculations | `/api/availability/check` | Business logic validated | **Output:** For each experimental endpoint, document: + - Endpoint specification (method, path, request/response) - What it validates - Current status (stub, working, blocked) @@ -196,12 +204,14 @@ This parallelism is one of WDS's key efficiency gains. Development teams can beg ## When to Use This Phase **Use this phase when:** + - Building platform/infrastructure for a new product - Features depend on external APIs or services - Innovative features need technical validation - Development team needs architectural clarity before design **Skip or minimize if:** + - Simple project with obvious technical approach - Working within existing platform/infrastructure - Enhancement that doesn't change architecture @@ -212,6 +222,7 @@ This parallelism is one of WDS's key efficiency gains. Development teams can beg ## What to Prepare Bring: + - Product Brief (Phase 1) - Trigger Map with Feature Impact Analysis (Phase 2) - Any existing technical constraints @@ -232,19 +243,23 @@ Your technical foundation enables: ## Tips for Great Sessions **Validate risky features first** + - If the Google Maps API doesn't return drive times in a usable format, you need to know NOW - Don't design features you can't build **Document constraints clearly** + - Designers need to know what's possible - "Loading state required" vs "instant" changes UX significantly **Involve developers** + - Technical decisions benefit from dev input - PoC work may require developer time - Architecture is a conversation, not a decree **Stay connected to strategy** + - Reference Feature Impact Analysis scores - High-impact features deserve more PoC investment - Don't over-engineer for hypothetical needs @@ -257,13 +272,13 @@ See: `examples/dog-week-patterns/C-Requirements/` for the Dog Week technical fou **What Dog Week needed to prove early:** -- *"Can we show dog owners how long it takes to walk to a dog walker?"* → Google Maps Directions API returns walking time between coordinates ✓ -- *"Can we check real-time availability across multiple walkers?"* → Endpoint aggregates calendar data in <200ms ✓ -- *"Can we handle Swish payments for Swedish users?"* → Swish API integration validated with test transactions ✓ -- *"Can walkers see their schedule on mobile?"* → Responsive calendar component renders correctly on iOS/Android browsers ✓ +- _"Can we show dog owners how long it takes to walk to a dog walker?"_ → Google Maps Directions API returns walking time between coordinates ✓ +- _"Can we check real-time availability across multiple walkers?"_ → Endpoint aggregates calendar data in <200ms ✓ +- _"Can we handle Swish payments for Swedish users?"_ → Swish API integration validated with test transactions ✓ +- _"Can walkers see their schedule on mobile?"_ → Responsive calendar component renders correctly on iOS/Android browsers ✓ These early discoveries shaped both the design AND the development approach. --- -*Phase 3 of the Whiteport Design Studio method* +_Phase 3 of the Whiteport Design Studio method_ diff --git a/src/modules/wds/docs/method/phase-4-ux-design-guide.md b/src/modules/wds/docs/method/phase-4-ux-design-guide.md index c901cc06..89862795 100644 --- a/src/modules/wds/docs/method/phase-4-ux-design-guide.md +++ b/src/modules/wds/docs/method/phase-4-ux-design-guide.md @@ -30,45 +30,55 @@ For each scenario/page: ## How Freyja the WDS Designer helps you design software ### 4A: Scenario Exploration + **When:** Discovering the Concept, the process, flow screen or component solution together, before sketching begin Freyja helps you: + - Think through the user's journey - Explore content and feature options - Consider psychological triggers from your Trigger Map - Arrive at a clear solution ready for sketching ### 4B: UI Sketch Analysis + **When:** You have a sketch and you need feedback on it Freyja helps you: + - Analyze what the sketch shows - Ask clarifying questions - Identify all components and states ### 4C: Conceptual Specification + **When:** Design is clear, need development-ready specs Freyja helps you: + - Document every detail systematically - Assign Object IDs for testing - Define all interactions and states - Prepare multilingual content, error codes, instructions and any other content needed for the developers ### 4D: HTML Prototype + **When:** Specifications complete, and we make the sketch come alive to test the concept Freyja helps you: + - Create interactive prototypes - Test the design in browser - Discover gaps and issues -- Refine specifications +- Refine specifications - Visualize the concept before development ### 4E: PRD Update + **When:** Page design is complete, before moving to the next scenario Freyja helps you: + - Identify what features this page requires - Add functional requirements to the PRD - Reference the page (e.g., "Required by: 2.1-Dog-Calendar") @@ -77,6 +87,7 @@ Freyja helps you: **Why this step matters:** Each page reveals concrete requirements: + - "This form needs email validation" - "We need a GET endpoint for availability" - "Users need to upload images here" @@ -89,13 +100,17 @@ Capturing these while the page is fresh ensures nothing is forgotten. The PRD be ## Functional Requirements ### Email Validation + **Required by:** 1.2-Sign-Up, 2.3-Profile-Edit + - Validate format on input - Check domain exists - Prevent duplicates ### Availability Calendar API + **Required by:** 2.1-Dog-Calendar, 3.1-Booking-Flow + - GET /api/walkers/{id}/availability - Returns 2-week window - Updates via WebSocket @@ -123,6 +138,7 @@ C-Scenarios/ ``` **Numbering Convention:** + - Scenarios: 01, 02, 03... - Pages within scenarios: 1.1, 1.2, 2.1, 2.2... @@ -131,6 +147,7 @@ C-Scenarios/ ## Object IDs Every interactive element gets an Object ID for: + - Consistent naming across specs and code - Test automation with stable selectors - Analytics tracking @@ -139,6 +156,7 @@ Every interactive element gets an Object ID for: **Format:** `{page}-{section}-{element}` in kebab-case **Example:** + ``` welcome-page-hero-cta-button signin-form-email-input @@ -150,8 +168,10 @@ signin-form-error-email **When Design System is enabled** (Phase 5), each object in your specification includes component library references: **Example specification entry:** + ```markdown ### Submit Button + **Object ID:** `signin-form-submit-button` **Component:** primary-button (from Design System) **Figma Component:** Primary Button @@ -162,6 +182,7 @@ Triggers form validation and submission... ``` **Benefits:** + - Designers know which Figma component to use - Developers know which code component to implement - Design System ensures consistency @@ -177,6 +198,7 @@ Just describe the element directly in the specification without component refere Specification isn't just documentation - it's design validation. When you try to specify every detail, you discover: + - "What happens when this is empty?" - "How does this look on mobile?" - "What if the user does X before Y?" @@ -191,12 +213,14 @@ Finding these gaps now means addressing them while solutions are still flexible. Interactive prototypes that validate your design: **What they include:** + - Semantic HTML matching your specs - CSS using your Design System tokens - JavaScript for interactions and validation - Multilingual content switching **What they reveal:** + - Visual gaps ("the spacing doesn't match") - Interaction issues ("we forgot the loading state") - Component needs ("we need a phone input component") @@ -204,6 +228,7 @@ Interactive prototypes that validate your design: - Flow issues ("this navigation doesn't make sense") **File Structure:** + ``` 1.1-Start-Page/ ├── 1.1-Start-Page.md (specification) @@ -220,20 +245,24 @@ Interactive prototypes that validate your design: ## When to Use This Phase **Use this phase when:** + - Ready to design specific screens/pages - Have strategic clarity from Phase 1-2 - Want to validate designs before development **Start with exploration (4A) if:** + - No existing sketches - Unsure how to approach a feature - Need to think through the user journey **Start with analysis (4B) if:** + - Have sketches ready to specify - Know what you want, need to document it **Use HTML prototypes (4D) if:** + - Specifications feel complete - Want to validate before development - Need stakeholder sign-off @@ -243,6 +272,7 @@ Interactive prototypes that validate your design: ## What to Prepare Bring: + - Trigger Map (Phase 2) - for user psychology reference - Any existing sketches or wireframes - Technical constraints from PRD (Phase 3) @@ -263,11 +293,13 @@ Your specifications enable: ## Tips for Great Sessions **Think out loud with Freyja** + - Share your reasoning - Explore alternatives together - Let the conversation reveal insights **Be thorough with states** + - Empty states - Loading states - Error states @@ -275,11 +307,13 @@ Your specifications enable: - Edge cases **Don't skip the prototype** + - Click through your design - Find the gaps before development - Refine specs based on what you learn **Reference your Trigger Map** + - Does this serve the user's goals? - Does this avoid their fears? - Does this support business objectives? @@ -292,5 +326,4 @@ See: `examples/dog-week-patterns/C-Scenarios/` for complete scenario specificati --- -*Phase 4 of the Whiteport Design Studio method* - +_Phase 4 of the Whiteport Design Studio method_ diff --git a/src/modules/wds/docs/method/phase-5-design-system-guide.md b/src/modules/wds/docs/method/phase-5-design-system-guide.md index 34e2d82e..5d3caf43 100644 --- a/src/modules/wds/docs/method/phase-5-design-system-guide.md +++ b/src/modules/wds/docs/method/phase-5-design-system-guide.md @@ -31,7 +31,9 @@ Your Design System includes: Following Brad Frost's methodology: ### Foundation (Design Tokens) + The values everything else builds on: + - **Colors** - Primary, secondary, semantic (success, error, warning) - **Typography** - Font families, sizes, weights, line heights - **Spacing** - Consistent spacing scale @@ -40,7 +42,9 @@ The values everything else builds on: - **Breakpoints** - Responsive design points ### Atoms + The smallest building blocks: + - Buttons - Input fields - Labels @@ -49,14 +53,18 @@ The smallest building blocks: - Dividers ### Molecules + Groups of atoms working together: + - Form groups (label + input + error) - Search bars (input + button) - Card headers (title + action) - Navigation items (icon + label) ### Organisms + Complex components made of molecules: + - Page headers - Navigation bars - Form sections @@ -69,7 +77,7 @@ Complex components made of molecules: ### The Parallel Workflow -Phase 5 isn't a separate phase you do *after* Phase 4 - it happens **during** Phase 4: +Phase 5 isn't a separate phase you do _after_ Phase 4 - it happens **during** Phase 4: ``` Phase 4 Page Design → Phase 5 Design System @@ -82,6 +90,7 @@ Notice pattern across pages → Extract as reusable component ``` **The rhythm:** + 1. Design a page/component in Phase 4 2. Notice "This could be reusable" 3. Extract to Design System @@ -105,6 +114,7 @@ As you specify scenarios in Phase 4, components naturally emerge: **Step 1: Spot the Pattern** While working on Phase 4 scenarios, notice when you're designing something reusable: + - "I just designed this button for Page 1.1... and I need it again on Page 1.2" - "This form input pattern will be used everywhere" - "We have 3 different card layouts, but they share the same structure" @@ -130,10 +140,11 @@ D-Design-System/ Use this template for each component: -```markdown +````markdown # Primary Button ## Overview + The primary button is used for the main call-to-action on any page or section. ## Component Details @@ -146,11 +157,13 @@ The primary button is used for the main call-to-action on any page or section. ## Variants ### Size + - **Small:** Compact spaces, secondary actions - **Medium:** Default size for most use cases - **Large:** Hero sections, important CTAs ### State + - **Default:** Ready for interaction - **Hover:** Visual feedback on mouse over - **Active:** Currently being clicked @@ -160,6 +173,7 @@ The primary button is used for the main call-to-action on any page or section. ## Visual Specifications **Design Tokens:** + - Background: `color-primary-500` - Text: `color-white` - Border Radius: `radius-md` @@ -167,6 +181,7 @@ The primary button is used for the main call-to-action on any page or section. - Font: `font-semibold`, `text-base` **States:** + - Hover: `color-primary-600` - Active: `color-primary-700` - Disabled: `color-gray-300`, opacity 50% @@ -174,12 +189,14 @@ The primary button is used for the main call-to-action on any page or section. ## Usage Guidelines **When to use:** + - Primary action on a page or modal - Main CTA in hero sections - Form submissions - Confirmation actions **When NOT to use:** + - Multiple primary actions (use secondary instead) - Destructive actions (use danger variant) - Navigation (use links or secondary buttons) @@ -194,20 +211,26 @@ The primary button is used for the main call-to-action on any page or section. ## Example Usage **In specifications:** + ```markdown ### Submit Button + **Object ID:** `contact-form-submit-button` **Component:** primary-button **Variant:** size=large **State:** default → loading → success ``` +```` **In Figma:** Use "Primary Button" component from library **In Code (if using Chakra):** + ```jsx - + ``` ## Used In @@ -216,6 +239,7 @@ Use "Primary Button" component from library - 1.2-Sign-Up: Submit registration - 2.1-Contact-Form: Send message - [Update as you use the component] + ``` **Step 4: Update as You Go** @@ -230,23 +254,25 @@ Each time you use this component in a new scenario: **As you work through Phase 4:** ``` + Design Page 1.1 - ↓ +↓ Notice: "This button is reusable" - ↓ +↓ Create: primary-button.md in Design System - ↓ +↓ Reference in 1.1 spec: component=primary-button - ↓ +↓ Design Page 1.2 - ↓ +↓ Need same button: Reference existing component - ↓ +↓ Design Page 2.1 - ↓ +↓ Need slightly different: Add variant to component doc - ↓ +↓ Update all references with new variant option + ``` --- @@ -258,15 +284,17 @@ Beyond documentation, create an **interactive HTML guide** where stakeholders an ### Structure ``` + D-Design-System/ -├── component-showcase.html ← Interactive guide +├── component-showcase.html ← Interactive guide ├── component-showcase.css ├── component-showcase.js ├── 01-design-tokens.md ├── 02-atoms/ -│ ├── primary-button.md -│ └── ... -``` +│ ├── primary-button.md +│ └── ... + +```` ### What the Showcase Includes @@ -562,7 +590,7 @@ These libraries work well with WDS's specification approach: **When to use:** Primary call-to-action buttons... -``` +```` --- @@ -574,11 +602,11 @@ Your WDS component system connects to your visual design tools (Figma, Sketch, A **Use the exact same names across all tools:** -| WDS Component Name | Figma Component | Code Component | Object ID | -|-------------------|-----------------|----------------|-----------| -| `primary-button` | Primary Button | `PrimaryButton` | `*-primary-button` | -| `text-input` | Text Input | `TextInput` | `*-text-input` | -| `form-group` | Form Group | `FormGroup` | `*-form-group` | +| WDS Component Name | Figma Component | Code Component | Object ID | +| ------------------ | --------------- | --------------- | ------------------ | +| `primary-button` | Primary Button | `PrimaryButton` | `*-primary-button` | +| `text-input` | Text Input | `TextInput` | `*-text-input` | +| `form-group` | Form Group | `FormGroup` | `*-form-group` | ### The Workflow @@ -598,6 +626,7 @@ signin-form-submit-primary-button (everywhere) **Component Library Structure:** Match your WDS atomic design structure: + ``` Design File/ ├── 🎨 Design Tokens @@ -618,6 +647,7 @@ Design File/ ``` **Naming in Figma:** + - Component names match WDS names (kebab-case or Title Case) - Variants match WDS variants (Primary, Secondary, Disabled) - Properties match WDS states (default, hover, active, error) @@ -644,18 +674,23 @@ Design File/ The design system is living documentation that grows with your product: ### Starting Point + Begin with what you need for current scenarios: + - Extract components from Phase 4 work - Document only what you're actually using - Avoid speculating about future needs ### Evolution + As you design more scenarios: + - New patterns emerge → add to system - Inconsistencies appear → consolidate - Components evolve → update documentation ### Maintenance + - Keep specs in sync with implementation - Remove unused components - Update when design language evolves @@ -665,24 +700,28 @@ As you design more scenarios: ## When to Use This Phase **Enable Design System phase if:** + - Building reusable component library - Multiple pages/scenarios with shared patterns - Need design consistency across product - Handoff requires component documentation **Work in parallel with Phase 4 when enabled:** + - As you sketch, identify component patterns - As you specify, extract to Design System - Design System grows with each page completed - No separate "design system phase" at the end **Skip this phase if:** + - Small project (single landing page) - Using existing design system (Material, Chakra, etc.) - One-off designs without reuse - Quick prototype or MVP without component library needs **Dedicated consolidation when:** + - Multiple scenarios complete, need cleanup - Preparing for development handoff - Found inconsistencies to resolve @@ -695,6 +734,7 @@ As you design more scenarios: ## What to Prepare Bring: + - Completed or in-progress scenario specs (Phase 4) - Any existing brand guidelines - Technical framework constraints (React components, etc.) @@ -714,21 +754,25 @@ Your Design System enables: ## Tips for Great Sessions **Extract, don't invent** + - Components should come from real design needs - Don't create components "just in case" - Let the system grow from actual scenarios **Document the why** + - Why does this button look this way? - What user trigger does it serve? - When should developers use variant A vs B? **Stay consistent** + - Same component = same specification - Variations should be intentional - When in doubt, simplify **Connect to psychology** + - Every design choice serves a purpose - Reference your Trigger Map - Components should feel intentional, not arbitrary @@ -741,5 +785,4 @@ See: `examples/dog-week-patterns/D-Design-System/` for a complete Design System --- -*Phase 5 of the Whiteport Design Studio method* - +_Phase 5 of the Whiteport Design Studio method_ diff --git a/src/modules/wds/docs/method/phase-6-integration-guide.md b/src/modules/wds/docs/method/phase-6-integration-guide.md index 288e11af..7ae3fa6f 100644 --- a/src/modules/wds/docs/method/phase-6-integration-guide.md +++ b/src/modules/wds/docs/method/phase-6-integration-guide.md @@ -21,6 +21,7 @@ By the end, developers have a complete PRD covering both technical foundation an **Updated PRD (C-Requirements/) includes:** **From Phase 3 (Technical Foundation):** + - Platform architecture - Data model - Integration map @@ -29,6 +30,7 @@ By the end, developers have a complete PRD covering both technical foundation an - Security framework **Added from Phase 4 (Functional Requirements):** + - All features discovered during page design - Page-to-feature traceability - Priority rankings @@ -36,12 +38,14 @@ By the end, developers have a complete PRD covering both technical foundation an - Implementation notes **New in Phase 6:** + - Feature organization by epic/area - Development sequence - MVP scope definition - Technical dependencies mapped **Handoff Package (E-UI-Roadmap/):** + - Priority sequence document - Scenario-to-development mapping - Component inventory (if Design System enabled) @@ -86,18 +90,21 @@ From 2.1-Dog-Calendar: ### Features **User Registration** + - Required by: 1.2-Sign-Up - Email validation (format, domain, duplicates) - Phone validation with country codes - Account activation flow **User Login** + - Required by: 1.1-Start-Page, multiple pages - Email/password authentication - Session management (30-day persistence) - "Remember me" functionality **Password Management** + - Required by: 1.1-Start-Page (reset link) - Password reset via email - Password strength validation @@ -114,9 +121,11 @@ Reference the scoring you did in Phase 2 to inform priorities: ## Development Sequence ### Priority 1: MVP - Core User Flow + **Target:** Weeks 1-4 Features from Epic 1 (Authentication) + Epic 2 (Core Booking): + - User registration (Impact Score: 14) - User login (Impact Score: 16) - Availability calendar (Impact Score: 16) @@ -126,9 +135,11 @@ Features from Epic 1 (Authentication) + Epic 2 (Core Booking): Serves Priority 1 target group, addresses highest-impact drivers. ### Priority 2: Enhanced Features + **Target:** Weeks 5-8 Features from Epic 3 (Payments) + Epic 4 (Notifications): + - Payment processing (Impact Score: 12) - Booking confirmations (Impact Score: 11) - Calendar sync (Impact Score: 8) @@ -142,6 +153,7 @@ Features from Epic 3 (Payments) + Epic 4 (Notifications): ## Feature Dependencies **Booking Flow** depends on: + - ✓ User authentication (must be logged in) - ✓ Availability calendar (must see open slots) - ⚠️ Payment system (can launch with "pay in person" temporarily) @@ -173,21 +185,25 @@ Your finalized PRD in `C-Requirements/` combines all phases: ## 1. Technical Foundation (from Phase 3) ### Platform Architecture + - Technology stack decisions -- Infrastructure approach +- Infrastructure approach - Hosting and deployment ### Data Model + - Core entities and relationships - Database schema - Data flow diagrams ### Integrations + - External services (Google Maps, Stripe, etc.) - API specifications - Authentication providers ### Security & Performance + - Authentication/authorization approach - Data protection - Performance requirements @@ -196,7 +212,9 @@ Your finalized PRD in `C-Requirements/` combines all phases: ## 2. Functional Requirements (from Phase 4) ### Epic 1: User Authentication & Account Management + **Features:** + - User registration (Required by: 1.2-Sign-Up) - User login (Required by: 1.1-Start-Page, multiple) - Password management (Required by: 1.1-Start-Page) @@ -204,25 +222,30 @@ Your finalized PRD in `C-Requirements/` combines all phases: [Detailed specifications for each feature] ### Epic 2: [Next Epic] + [...] ## 3. Development Roadmap (from Phase 6) ### Priority 1: MVP (Weeks 1-4) + - Features list with Impact Scores - Why these first (references Trigger Map) - Timeline estimate - Dependencies ### Priority 2: Enhanced Features (Weeks 5-8) + [...] ## 4. Dependencies & Constraints + - Technical dependencies between features - Design constraints from Phase 4 - Third-party limitations discovered in Phase 3 ## 5. Success Metrics + - Business goals from Phase 1 - Feature-specific KPIs - How we measure success @@ -235,7 +258,7 @@ Your finalized PRD in `C-Requirements/` combines all phases: **The pattern:** - **Phase 3:** Initial PRD with technical foundation -- **Phase 4:** PRD grows with each page (step 4E adds requirements) +- **Phase 4:** PRD grows with each page (step 4E adds requirements) - **Phase 6 (First time):** Organize MVP scope from completed scenarios - Create first handoff package - Development can begin @@ -251,12 +274,14 @@ Your finalized PRD in `C-Requirements/` combines all phases: ## When to Use This Phase **First PRD Finalization when:** + - You have MVP-level scenarios complete (enough for dev to start) -- Core user flows are specified +- Core user flows are specified - Critical features are documented - Enough work for 2-4 week sprint **Ongoing PRD Updates as:** + - Additional scenarios complete - New feature areas designed - Priorities shift based on learning @@ -285,12 +310,12 @@ Week 9+: Design continues in parallel with development Complete list for test automation: -| Scenario | Object ID | Element Type | Notes | -|----------|-----------|--------------|-------| -| 1.1 | `welcome-hero-cta` | Button | Primary action | -| 1.1 | `welcome-signin-link` | Link | Secondary action | -| 1.2 | `signin-email-input` | Input | Required field | -| 1.2 | `signin-error-email` | Error | Validation message | +| Scenario | Object ID | Element Type | Notes | +| -------- | --------------------- | ------------ | ------------------ | +| 1.1 | `welcome-hero-cta` | Button | Primary action | +| 1.1 | `welcome-signin-link` | Link | Secondary action | +| 1.2 | `signin-email-input` | Input | Required field | +| 1.2 | `signin-error-email` | Error | Validation message | --- @@ -299,6 +324,7 @@ Complete list for test automation: ### Review Completeness Before handoff, verify: + - All scenarios specified and reviewed - Design system covers all components - Object IDs assigned throughout @@ -308,6 +334,7 @@ Before handoff, verify: ### Identify Priorities With Freyja, map your Trigger Map priorities to development order: + - Which user triggers are most critical? - What's the minimum viable experience? - What can wait for later releases? @@ -315,6 +342,7 @@ With Freyja, map your Trigger Map priorities to development order: ### Document Technical Context Capture what developers need to know: + - Design decisions and their rationale - Technical constraints discovered during design - Interaction patterns that need special attention @@ -323,6 +351,7 @@ Capture what developers need to know: ### Create the Handoff Organize everything into the UI Roadmap folder: + - Clear priority sequence - Complete component inventory - Technical notes and open questions @@ -336,26 +365,31 @@ Organize everything into the UI Roadmap folder: ## Design Handoff Verification ### Product Foundation + - [ ] Product Brief complete and current - [ ] Trigger Map with prioritized users and goals - [ ] ICP clearly defined ### Requirements + - [ ] PRD with technical specifications - [ ] Platform architecture documented - [ ] Integration requirements listed ### Visual Design + - [ ] All scenarios have specifications - [ ] All pages have Object IDs - [ ] States documented (empty, loading, error, success) ### Design System + - [ ] All components documented - [ ] Design tokens defined - [ ] Usage guidelines written ### Validation + - [ ] HTML prototypes created for key scenarios - [ ] Stakeholder review complete - [ ] Open questions documented @@ -368,12 +402,14 @@ Organize everything into the UI Roadmap folder: ## When to Use This Phase **First handoff when:** + - You have enough scenarios for MVP - Core user flows are specified - Critical components are documented - Developers can start building foundational features **Ongoing handoffs as:** + - Each major scenario completes - New component patterns emerge - Design decisions affect development @@ -402,6 +438,7 @@ Development and design work in parallel streams, with regular sync points. ## What to Prepare Bring: + - Completed scenario specifications (Phase 4) - Design System (Phase 5) - PRD (Phase 3) @@ -423,21 +460,25 @@ Your UI Roadmap enables: ## Tips for Great Sessions **Think from dev perspective** + - What questions will developers have? - What decisions can't you make for them? - What context will save them time? **Be explicit about priorities** + - Not everything is Priority 1 - Make trade-offs visible - Connect priorities to business goals **Document the unknowns** + - Open questions are valuable - Don't pretend certainty you don't have - Let dev team contribute decisions **Keep it updated** + - Handoff is ongoing, not one-time - Update as design evolves - Maintain as source of truth @@ -453,6 +494,7 @@ WDS → E-UI-Roadmap/ → BMM Architecture & Stories ``` The UI Roadmap provides: + - Context for architecture decisions - Specifications for story creation - Priorities for sprint planning @@ -466,5 +508,4 @@ See: `examples/dog-week-patterns/E-UI-Roadmap/` for a complete UI Roadmap from a --- -*Phase 6 of the Whiteport Design Studio method* - +_Phase 6 of the Whiteport Design Studio method_ diff --git a/src/modules/wds/docs/method/phase-6-prd-finalization-guide.md b/src/modules/wds/docs/method/phase-6-prd-finalization-guide.md index 9f642442..02b21e31 100644 --- a/src/modules/wds/docs/method/phase-6-prd-finalization-guide.md +++ b/src/modules/wds/docs/method/phase-6-prd-finalization-guide.md @@ -20,6 +20,7 @@ By the end, developers have a complete PRD covering both technical foundation an **Updated PRD (C-Requirements/) includes:** **From Phase 3 (Technical Foundation):** + - Platform architecture - Data model - Integration map @@ -28,6 +29,7 @@ By the end, developers have a complete PRD covering both technical foundation an - Security framework **Added from Phase 4 (Functional Requirements):** + - All features discovered during page design - Page-to-feature traceability - Priority rankings @@ -35,12 +37,14 @@ By the end, developers have a complete PRD covering both technical foundation an - Implementation notes **New in Phase 6:** + - Feature organization by epic/area - Development sequence - MVP scope definition - Technical dependencies mapped **Handoff Package (E-UI-Roadmap/):** + - Priority sequence document - Scenario-to-development mapping - Component inventory (if Design System enabled) @@ -85,18 +89,21 @@ From 2.1-Dog-Calendar: ### Features **User Registration** + - Required by: 1.2-Sign-Up - Email validation (format, domain, duplicates) - Phone validation with country codes - Account activation flow **User Login** + - Required by: 1.1-Start-Page, multiple pages - Email/password authentication - Session management (30-day persistence) - "Remember me" functionality **Password Management** + - Required by: 1.1-Start-Page (reset link) - Password reset via email - Password strength validation @@ -113,9 +120,11 @@ Reference the scoring you did in Phase 2 to inform priorities: ## Development Sequence ### Priority 1: MVP - Core User Flow + **Target:** Weeks 1-4 Features from Epic 1 (Authentication) + Epic 2 (Core Booking): + - User registration (Impact Score: 14) - User login (Impact Score: 16) - Availability calendar (Impact Score: 16) @@ -125,9 +134,11 @@ Features from Epic 1 (Authentication) + Epic 2 (Core Booking): Serves Priority 1 target group, addresses highest-impact drivers. ### Priority 2: Enhanced Features + **Target:** Weeks 5-8 Features from Epic 3 (Payments) + Epic 4 (Notifications): + - Payment processing (Impact Score: 12) - Booking confirmations (Impact Score: 11) - Calendar sync (Impact Score: 8) @@ -141,6 +152,7 @@ Features from Epic 3 (Payments) + Epic 4 (Notifications): ## Feature Dependencies **Booking Flow** depends on: + - ✓ User authentication (must be logged in) - ✓ Availability calendar (must see open slots) - ⚠️ Payment system (can launch with "pay in person" temporarily) @@ -172,21 +184,25 @@ Your finalized PRD in `C-Requirements/` combines all phases: ## 1. Technical Foundation (from Phase 3) ### Platform Architecture + - Technology stack decisions -- Infrastructure approach +- Infrastructure approach - Hosting and deployment ### Data Model + - Core entities and relationships - Database schema - Data flow diagrams ### Integrations + - External services (Google Maps, Stripe, etc.) - API specifications - Authentication providers ### Security & Performance + - Authentication/authorization approach - Data protection - Performance requirements @@ -195,7 +211,9 @@ Your finalized PRD in `C-Requirements/` combines all phases: ## 2. Functional Requirements (from Phase 4) ### Epic 1: User Authentication & Account Management + **Features:** + - User registration (Required by: 1.2-Sign-Up) - User login (Required by: 1.1-Start-Page, multiple) - Password management (Required by: 1.1-Start-Page) @@ -203,25 +221,30 @@ Your finalized PRD in `C-Requirements/` combines all phases: [Detailed specifications for each feature] ### Epic 2: [Next Epic] + [...] ## 3. Development Roadmap (from Phase 6) ### Priority 1: MVP (Weeks 1-4) + - Features list with Impact Scores - Why these first (references Trigger Map) - Timeline estimate - Dependencies ### Priority 2: Enhanced Features (Weeks 5-8) + [...] ## 4. Dependencies & Constraints + - Technical dependencies between features - Design constraints from Phase 4 - Third-party limitations discovered in Phase 3 ## 5. Success Metrics + - Business goals from Phase 1 - Feature-specific KPIs - How we measure success @@ -234,7 +257,7 @@ Your finalized PRD in `C-Requirements/` combines all phases: **The pattern:** - **Phase 3:** Initial PRD with technical foundation -- **Phase 4:** PRD grows with each page (step 4E adds requirements) +- **Phase 4:** PRD grows with each page (step 4E adds requirements) - **Phase 6 (First time):** Organize MVP scope from completed scenarios - Create first handoff package - Development can begin @@ -250,12 +273,14 @@ Your finalized PRD in `C-Requirements/` combines all phases: ## When to Use This Phase **First PRD Finalization when:** + - You have MVP-level scenarios complete (enough for dev to start) -- Core user flows are specified +- Core user flows are specified - Critical features are documented - Enough work for 2-4 week sprint **Ongoing PRD Updates as:** + - Additional scenarios complete - New feature areas designed - Priorities shift based on learning @@ -284,12 +309,12 @@ Week 9+: Design continues in parallel with development Complete list for test automation: -| Scenario | Object ID | Element Type | Notes | -|----------|-----------|--------------|-------| -| 1.1 | `welcome-hero-cta` | Button | Primary action | -| 1.1 | `welcome-signin-link` | Link | Secondary action | -| 1.2 | `signin-email-input` | Input | Required field | -| 1.2 | `signin-error-email` | Error | Validation message | +| Scenario | Object ID | Element Type | Notes | +| -------- | --------------------- | ------------ | ------------------ | +| 1.1 | `welcome-hero-cta` | Button | Primary action | +| 1.1 | `welcome-signin-link` | Link | Secondary action | +| 1.2 | `signin-email-input` | Input | Required field | +| 1.2 | `signin-error-email` | Error | Validation message | --- @@ -298,6 +323,7 @@ Complete list for test automation: ### Review Completeness Before handoff, verify: + - All scenarios specified and reviewed - Design system covers all components - Object IDs assigned throughout @@ -307,6 +333,7 @@ Before handoff, verify: ### Identify Priorities With Freyja, map your Trigger Map priorities to development order: + - Which user triggers are most critical? - What's the minimum viable experience? - What can wait for later releases? @@ -314,6 +341,7 @@ With Freyja, map your Trigger Map priorities to development order: ### Document Technical Context Capture what developers need to know: + - Design decisions and their rationale - Technical constraints discovered during design - Interaction patterns that need special attention @@ -322,6 +350,7 @@ Capture what developers need to know: ### Create the Handoff Organize everything into the UI Roadmap folder: + - Clear priority sequence - Complete component inventory - Technical notes and open questions @@ -335,26 +364,31 @@ Organize everything into the UI Roadmap folder: ## Design Handoff Verification ### Product Foundation + - [ ] Product Brief complete and current - [ ] Trigger Map with prioritized users and goals - [ ] ICP clearly defined ### Requirements + - [ ] PRD with technical specifications - [ ] Platform architecture documented - [ ] Integration requirements listed ### Visual Design + - [ ] All scenarios have specifications - [ ] All pages have Object IDs - [ ] States documented (empty, loading, error, success) ### Design System + - [ ] All components documented - [ ] Design tokens defined - [ ] Usage guidelines written ### Validation + - [ ] HTML prototypes created for key scenarios - [ ] Stakeholder review complete - [ ] Open questions documented @@ -367,12 +401,14 @@ Organize everything into the UI Roadmap folder: ## When to Use This Phase **First handoff when:** + - You have enough scenarios for MVP - Core user flows are specified - Critical components are documented - Developers can start building foundational features **Ongoing handoffs as:** + - Each major scenario completes - New component patterns emerge - Design decisions affect development @@ -401,6 +437,7 @@ Development and design work in parallel streams, with regular sync points. ## What to Prepare Bring: + - Completed scenario specifications (Phase 4) - Design System (Phase 5) - PRD (Phase 3) @@ -422,21 +459,25 @@ Your UI Roadmap enables: ## Tips for Great Sessions **Think from dev perspective** + - What questions will developers have? - What decisions can't you make for them? - What context will save them time? **Be explicit about priorities** + - Not everything is Priority 1 - Make trade-offs visible - Connect priorities to business goals **Document the unknowns** + - Open questions are valuable - Don't pretend certainty you don't have - Let dev team contribute decisions **Keep it updated** + - Handoff is ongoing, not one-time - Update as design evolves - Maintain as source of truth @@ -452,6 +493,7 @@ WDS → E-UI-Roadmap/ → BMM Architecture & Stories ``` The UI Roadmap provides: + - Context for architecture decisions - Specifications for story creation - Priorities for sprint planning @@ -465,5 +507,4 @@ See: `examples/dog-week-patterns/E-UI-Roadmap/` for a complete UI Roadmap from a --- -*Phase 6 of the Whiteport Design Studio method* - +_Phase 6 of the Whiteport Design Studio method_ diff --git a/src/modules/wds/docs/method/wds-method-guide.md b/src/modules/wds/docs/method/wds-method-guide.md index 510f23fb..96ba06f4 100644 --- a/src/modules/wds/docs/method/wds-method-guide.md +++ b/src/modules/wds/docs/method/wds-method-guide.md @@ -45,12 +45,14 @@ Vision → Clarity → UX Design → Design System → PRD Complete WDS follows six phases, each producing artifacts in your project's `docs/` folder: ### Phase 1: Product Exploration (Product Brief) + **Output:** `A-Product-Brief/` **Agent:** Saga the Analyst Establish your strategic foundation through conversational discovery. Instead of filling out questionnaires, you have a conversation that builds understanding organically. **What you create:** + - Product vision and problem statement - Market positioning and differentiation - Success criteria and metrics @@ -59,12 +61,14 @@ Establish your strategic foundation through conversational discovery. Instead of --- ### Phase 2: Trigger Mapping (Trigger Map) + **Output:** `B-Trigger-Map/` **Agent:** Saga the Analyst Connect business goals to user psychology through Trigger Mapping. Discover not just WHO your users are, but WHY they act and WHAT triggers their decisions. **What you create:** + - Business goals (Vision + SMART objectives) - Target groups connected to business outcomes - Detailed personas with psychological depth @@ -75,12 +79,14 @@ Connect business goals to user psychology through Trigger Mapping. Discover not --- ### Phase 3: PRD Platform (Technical Foundation) + **Output:** `C-Requirements/` **Agent:** Freyja the PM Prove your concept works technically - in parallel with design work. Validate platform decisions, create proofs of concept, and set up experimental endpoints. **What you create:** + - Platform architecture decisions - Data model and integrations - Technical proofs of concept @@ -91,6 +97,7 @@ Prove your concept works technically - in parallel with design work. Validate pl --- ### Phase 4: UX Design (UX-Sketches & Usage Scenarios) + **Output:** `C-Scenarios/` **Agent:** Baldr the UX Expert @@ -99,6 +106,7 @@ Transform ideas into detailed visual specifications. Your agent helps you think **The key insight:** Designs that can be logically explained without gaps are easy to develop. The specification process reveals gaps early - when they're easy to address. **What you create:** + - Scenario folder structure (numbered hierarchy) - Page specifications with full detail - Component definitions with Object IDs @@ -109,12 +117,14 @@ Transform ideas into detailed visual specifications. Your agent helps you think --- ### Phase 5: Design System (Component Library) + **Output:** `D-Design-System/` **Agent:** Baldr the UX Expert Build your component library following atomic design principles. This phase is **optional** and runs **in parallel** with Phase 4 - as you design pages, you extract reusable components. **What you create:** + - Design tokens (colors, typography, spacing) - Atomic components (buttons, inputs, labels) - Molecular components (form groups, cards) @@ -125,12 +135,14 @@ Build your component library following atomic design principles. This phase is * --- ### Phase 6: PRD Finalization (Complete PRD) + **Output:** Complete PRD in `C-Requirements/` + `E-UI-Roadmap/` **Agent:** Freyja the PM Compile all functional requirements discovered during Phase 4 into a complete, development-ready PRD. This phase runs **continuously** - hand off as soon as you have MVP scope, then update as design progresses. **What you create:** + - Complete PRD (Platform + Functional requirements) - Feature organization by epic/area - Development sequence with priorities @@ -145,14 +157,15 @@ WDS creates an organized folder structure in your project's `docs/` folder. Duri ### Your 4 Options -| Choice | Option A | Option B | -|--------|----------|----------| +| Choice | Option A | Option B | +| ---------- | -------------------- | ----------------------- | | **Prefix** | Letters (A, B, C...) | Numbers (01, 02, 03...) | -| **Case** | Title-Case | lowercase | +| **Case** | Title-Case | lowercase | ### Examples **Letters + Title-Case** (default): + ``` docs/ ├── A-Product-Brief/ @@ -164,6 +177,7 @@ docs/ ``` **Numbers + Title-Case**: + ``` docs/ ├── 01-Product-Brief/ @@ -175,6 +189,7 @@ docs/ ``` **Default (Letters + Title-Case) is recommended because:** + - Title-Case is easier for non-technical people to read - Letters create distinctive WDS branding - Distinguishes WDS folders from other docs @@ -185,14 +200,14 @@ docs/ Not every project needs all six phases. Select what you need based on your situation: -| Project Type | Recommended Phases | -|--------------|-------------------| -| **Landing page** | 1, 4 | -| **Full product (greenfield)** | All six | -| **Feature enhancement** | 2, 4, 6 | -| **Design system only** | 4, 5 | -| **Strategic planning** | 1, 2 | -| **Quick prototype** | 4 only | +| Project Type | Recommended Phases | +| ----------------------------- | ------------------ | +| **Landing page** | 1, 4 | +| **Full product (greenfield)** | All six | +| **Feature enhancement** | 2, 4, 6 | +| **Design system only** | 4, 5 | +| **Strategic planning** | 1, 2 | +| **Quick prototype** | 4 only | Your agents will help you identify which phases fit your project. @@ -203,29 +218,35 @@ Your agents will help you identify which phases fit your project. Three specialized agents guide you through WDS: ### Saga the Analyst 📚 -*"The one who tells your business story"* + +_"The one who tells your business story"_ Saga guides you through discovery and research. She's curious, patient, and helps you uncover insights you might not have seen yourself. **Works with you on:** + - Phase 1: Product Exploration - Phase 2: Trigger Mapping ### Freyja the PM ⚔️ -*"The strategic leader who sees what must be done"* + +_"The strategic leader who sees what must be done"_ Freyja helps you define technical requirements and finalize the PRD for development. She balances passion with strategy, knowing when to be fierce and when to be patient. **Works with you on:** + - Phase 3: PRD Platform - Phase 6: PRD Finalization ### Baldr the UX Expert ✨ -*"The one who brings light and beauty"* + +_"The one who brings light and beauty"_ Baldr transforms your ideas into beautiful, detailed specifications. He cares deeply about craft and ensures every detail serves the user experience. **Works with you on:** + - Phase 4: UX Design - Phase 5: Design System @@ -233,11 +254,12 @@ Baldr transforms your ideas into beautiful, detailed specifications. He cares de ## How Sessions Work -WDS sessions are **conversations, not interrogations**. +WDS sessions are **conversations, not interrogations**. ### The Rhythm A good WDS session feels like coffee with a wise mentor: + - They ask something interesting - You share your thinking - They reflect it back, maybe adding a new angle @@ -248,12 +270,14 @@ It never feels like filling out a form. ### What to Expect **Your agent will:** + - Ask one question at a time, then listen - Reflect back what they heard before moving on - Build documents together with you, piece by piece - Check in to make sure they understood correctly **You'll leave with:** + - Clear documentation you helped create - Deeper understanding of your own product - Ready-to-use artifacts for the next phase @@ -293,6 +317,7 @@ npx bmad-method@alpha install ## The WDS Difference ### Traditional Approach + - 47-question requirements spreadsheet - Generic persona templates - Designers work alone, then throw specs "over the wall" @@ -300,6 +325,7 @@ npx bmad-method@alpha install - Everyone argues about what was meant ### WDS Approach + - Conversations that build understanding - Personas with psychological depth connected to business goals - Collaborative workshops building shared understanding @@ -333,6 +359,7 @@ C-Requirements/ ────► C-Requirements/ ────► ### Parallel Streams Design and development can work in parallel: + - Phase 3 complete → Backend/platform development can start - Phase 4 MVP scenarios complete → Phase 6 first handoff → Sprint 1 begins - Design continues → Regular Phase 6 updates → More sprints @@ -348,4 +375,4 @@ Design and development can work in parallel: --- -*Whiteport Design Studio - Part of the BMad ecosystem* +_Whiteport Design Studio - Part of the BMad ecosystem_ diff --git a/src/modules/wds/getting-started/installation.md b/src/modules/wds/getting-started/installation.md index d79f2baa..ff919938 100644 --- a/src/modules/wds/getting-started/installation.md +++ b/src/modules/wds/getting-started/installation.md @@ -33,6 +33,7 @@ npm start ## Verify Installation You should see: + ``` ✅ WDS is running 🎨 Ready to design diff --git a/src/modules/wds/getting-started/quick-start.md b/src/modules/wds/getting-started/quick-start.md index bf0e8031..58f2e268 100644 --- a/src/modules/wds/getting-started/quick-start.md +++ b/src/modules/wds/getting-started/quick-start.md @@ -82,12 +82,12 @@ You: "Yes" Agent: "Based on your Trigger Map: - Target: Parents (tired of nagging) - Trigger: Family conflict - + For the Hero section, I suggest: Headline: 'Stop Nagging. Start Harmony.' - + Does this address their frustration?" - + You: "Perfect!" ``` @@ -98,6 +98,7 @@ You: "Perfect!" ## What Just Happened? You created **why-based specifications** in 5 minutes: + - Connected to user psychology (Trigger Map) - Grounded in real context (Scenario Init) - Generated with AI assistance (Agent collaboration) @@ -108,12 +109,15 @@ You created **why-based specifications** in 5 minutes: ## Next Steps ### Learn the Concepts + [Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md) - Deep dive into WDS philosophy ### Start Your Project + [Workflows Guide](../WDS-WORKFLOWS-GUIDE.md) - Full workflow documentation ### Get Help + [Community](https://discord.gg/whiteport) - Join the WDS community --- diff --git a/src/modules/wds/getting-started/where-to-go-next.md b/src/modules/wds/getting-started/where-to-go-next.md index 567f0618..56fbf1d9 100644 --- a/src/modules/wds/getting-started/where-to-go-next.md +++ b/src/modules/wds/getting-started/where-to-go-next.md @@ -18,6 +18,7 @@ Learn how to be indispensable in the AI era. Understand the paradigm shift where **Modules 02-16: Complete WDS Workflow** Master every phase from trigger mapping through design system to development handoff. Each module includes: + - **Lessons** - Theory and concepts with NotebookLM audio - **Tutorials** - Step-by-step hands-on guides - **Practice** - Apply to your own project @@ -67,6 +68,7 @@ Extract design tokens, create reusable components, and generate interactive HTML **[Modular Architecture](../workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md)** Technical details on: + - Three-tier file structure - Content placement rules - Component decomposition @@ -98,17 +100,21 @@ Technical details on: ## Community & Support ### Discord + Join the WDS community for: + - Questions and answers - Project feedback - Feature discussions ### GitHub + - Report issues - Request features - Contribute ### YouTube + - Video tutorials - Walkthroughs - Case studies diff --git a/src/modules/wds/templates/design-delivery.template.yaml b/src/modules/wds/templates/design-delivery.template.yaml index a6b469c8..78e4e534 100644 --- a/src/modules/wds/templates/design-delivery.template.yaml +++ b/src/modules/wds/templates/design-delivery.template.yaml @@ -2,11 +2,11 @@ # Copy this template to: deliveries/DD-XXX-name.yaml delivery: - id: "DD-XXX" # Format: DD-001, DD-002, etc. - name: "Feature Name" # Human-readable name - type: "user_flow" # user_flow | feature | component - status: "ready" # ready | in_progress | blocked - priority: "high" # high | medium | low + id: "DD-XXX" # Format: DD-001, DD-002, etc. + name: "Feature Name" # Human-readable name + type: "user_flow" # user_flow | feature | component + status: "ready" # ready | in_progress | blocked + priority: "high" # high | medium | low created_by: "wds-ux-expert" created_at: "YYYY-MM-DDTHH:MM:SSZ" updated_at: "YYYY-MM-DDTHH:MM:SSZ" @@ -29,17 +29,17 @@ design_artifacts: - id: "XX-scenario-name" path: "C-Scenarios/XX-scenario-name/" screens: ["screen1", "screen2"] - + - id: "XX-scenario-name" path: "C-Scenarios/XX-scenario-name/" screens: ["screen1"] - + user_flows: - name: "Flow Name" path: "C-Scenarios/flows/flow-name.excalidraw" entry: "entry-screen" exit: "exit-screen" - + design_system: components: - "Component Name (variants)" @@ -48,22 +48,22 @@ design_artifacts: technical_requirements: platform: - frontend: "framework-name" # From platform-requirements.yaml - backend: "framework-name" # From platform-requirements.yaml - + frontend: "framework-name" # From platform-requirements.yaml + backend: "framework-name" # From platform-requirements.yaml + integrations: - name: "integration-name" purpose: "[Why this integration is needed]" - required: true # true | false - + required: true # true | false + - name: "integration-name" purpose: "[Why this integration is needed]" required: false - + data_models: - name: "ModelName" fields: ["field1", "field2", "field3"] - + - name: "ModelName" fields: ["field1", "field2"] @@ -72,12 +72,12 @@ acceptance_criteria: - "[Functional requirement 1]" - "[Functional requirement 2]" - "[Functional requirement 3]" - + non_functional: - "[Performance requirement]" - "[Accessibility requirement]" - "[Security requirement]" - + edge_cases: - "[Edge case 1] → [Expected behavior]" - "[Edge case 2] → [Expected behavior]" @@ -87,17 +87,17 @@ testing_guidance: user_testing: - "[User testing instruction 1]" - "[User testing instruction 2]" - + qa_testing: - "[QA testing instruction 1]" - "[QA testing instruction 2]" - "[QA testing instruction 3]" estimated_complexity: - size: "medium" # small | medium | large - effort: "2-3 weeks" # Time estimate - risk: "low" # low | medium | high - dependencies: [] # List of DD-XXX IDs needed first + size: "medium" # small | medium | large + effort: "2-3 weeks" # Time estimate + risk: "low" # low | medium | high + dependencies: [] # List of DD-XXX IDs needed first notes: | [Any special considerations, important context, or diff --git a/src/modules/wds/templates/platform-requirements.template.yaml b/src/modules/wds/templates/platform-requirements.template.yaml index a204dd0d..0f138ba1 100644 --- a/src/modules/wds/templates/platform-requirements.template.yaml +++ b/src/modules/wds/templates/platform-requirements.template.yaml @@ -3,44 +3,44 @@ project: name: "Project Name" - type: "mobile_app" # mobile_app | web_app | desktop_app | api + type: "mobile_app" # mobile_app | web_app | desktop_app | api wds_version: "6.0" created_at: "YYYY-MM-DDTHH:MM:SSZ" platform: frontend: - framework: "framework-name" # react_native | react | vue | angular | svelte + framework: "framework-name" # react_native | react | vue | angular | svelte version: "X.X" - state_management: "library" # zustand | redux | mobx | context - navigation: "library" # react_navigation | react_router | vue_router - styling: "approach" # tailwind | styled_components | css_modules - ui_library: "library" # shadcn | mui | chakra (optional) - + state_management: "library" # zustand | redux | mobx | context + navigation: "library" # react_navigation | react_router | vue_router + styling: "approach" # tailwind | styled_components | css_modules + ui_library: "library" # shadcn | mui | chakra (optional) + backend: - framework: "framework-name" # supabase | firebase | express | fastapi | django + framework: "framework-name" # supabase | firebase | express | fastapi | django version: "X.X" - auth: "auth-provider" # supabase_auth | firebase_auth | auth0 | custom - database: "database-type" # postgresql | mysql | mongodb | firestore - storage: "storage-provider" # supabase_storage | s3 | cloudinary - api: "api-type" # rest | graphql | grpc - + auth: "auth-provider" # supabase_auth | firebase_auth | auth0 | custom + database: "database-type" # postgresql | mysql | mongodb | firestore + storage: "storage-provider" # supabase_storage | s3 | cloudinary + api: "api-type" # rest | graphql | grpc + database: - type: "database-type" # postgresql | mysql | mongodb + type: "database-type" # postgresql | mysql | mongodb version: "XX" - orm: "orm-library" # prisma | typeorm | mongoose (optional) - + orm: "orm-library" # prisma | typeorm | mongoose (optional) + deployment: - frontend: "platform" # expo_eas | vercel | netlify | aws - backend: "platform" # supabase_cloud | firebase | heroku | aws - ci_cd: "platform" # github_actions | gitlab_ci | circle_ci - hosting: "platform" # vercel | netlify | aws (if web app) + frontend: "platform" # expo_eas | vercel | netlify | aws + backend: "platform" # supabase_cloud | firebase | heroku | aws + ci_cd: "platform" # github_actions | gitlab_ci | circle_ci + hosting: "platform" # vercel | netlify | aws (if web app) integrations: - name: "integration-name" provider: "provider-name" - required: true # true | false + required: true # true | false purpose: "[Why this integration is needed]" - + - name: "integration-name" provider: "provider-name" required: false diff --git a/src/modules/wds/templates/test-scenario.template.yaml b/src/modules/wds/templates/test-scenario.template.yaml index ac658a6a..28bb7213 100644 --- a/src/modules/wds/templates/test-scenario.template.yaml +++ b/src/modules/wds/templates/test-scenario.template.yaml @@ -2,12 +2,12 @@ # Save to: test-scenarios/TS-XXX-name.yaml test_scenario: - id: "TS-XXX" # Format: TS-001, TS-002, etc. - name: "Feature Testing" # Human-readable name - delivery_id: "DD-XXX" # Related Design Delivery - type: "user_acceptance" # user_acceptance | integration | e2e - status: "ready" # ready | in_progress | blocked - tester: "designer" # designer | qa | developer + id: "TS-XXX" # Format: TS-001, TS-002, etc. + name: "Feature Testing" # Human-readable name + delivery_id: "DD-XXX" # Related Design Delivery + type: "user_acceptance" # user_acceptance | integration | e2e + status: "ready" # ready | in_progress | blocked + tester: "designer" # designer | qa | developer created_at: "YYYY-MM-DDTHH:MM:SSZ" test_objectives: @@ -21,7 +21,7 @@ test_environment: devices: - "Device 1 (OS version)" - "Device 2 (OS version)" - + test_data: - field: "value" - field: "value" @@ -30,17 +30,17 @@ test_environment: happy_path: - id: "HP-001" name: "Main User Flow" - priority: "critical" # critical | high | medium | low - + priority: "critical" # critical | high | medium | low + steps: - action: "[User action]" expected: "[Expected result]" design_ref: "[Path to specification]#[section]" - + - action: "[User action]" expected: "[Expected result]" design_ref: "[Path to specification]#[section]" - + success_criteria: - "[Success criterion 1]" - "[Success criterion 2]" @@ -51,13 +51,13 @@ error_states: - id: "ES-001" name: "Error Scenario" priority: "high" - + steps: - action: "[Action that triggers error]" - expected: "[Expected error message]" - expected: "[Expected recovery option]" - design_ref: "[Path to specification]#[error-section]" - + success_criteria: - "[Error handling criterion 1]" - "[Error handling criterion 2]" @@ -67,12 +67,12 @@ edge_cases: - id: "EC-001" name: "Edge Case Scenario" priority: "medium" - + steps: - action: "[Unusual action]" - expected: "[Expected handling]" - design_ref: "[Path to specification]#[edge-case-section]" - + success_criteria: - "[Edge case criterion 1]" @@ -94,15 +94,15 @@ accessibility: - id: "A11Y-001" name: "Screen Reader Navigation" priority: "high" - + setup: "Enable screen reader (VoiceOver/TalkBack)" - + steps: - action: "[Navigate with screen reader]" - verify: - "[Accessibility check 1]" - "[Accessibility check 2]" - + success_criteria: - "[Accessibility criterion 1]" - "[Accessibility criterion 2]" @@ -112,10 +112,10 @@ usability: - id: "UX-001" name: "First Impression" type: "observational" - + instructions: | [Instructions for conducting usability test] - + success_criteria: - "[Usability criterion 1]" - "[Usability criterion 2]" @@ -124,11 +124,11 @@ usability: performance: - id: "PERF-001" name: "Performance Check" - + verify: - "[Performance metric 1]" - "[Performance metric 2]" - + success_criteria: - "[Performance target 1]" - "[Performance target 2]" @@ -143,14 +143,14 @@ report_template: - "Device tested" - "Build version" - "Overall result (Pass/Fail/Partial)" - + - name: "Happy Path Results" fields: - "Test ID" - "Result (Pass/Fail)" - "Notes" - "Screenshots" - + - name: "Issues Found" fields: - "Issue ID" @@ -160,13 +160,13 @@ report_template: - "Expected vs Actual" - "Screenshot/Video" - "Design reference violated" - + - name: "Design System Compliance" fields: - "Component" - "Compliant (Yes/No)" - "Deviations noted" - + - name: "Recommendations" fields: - "What worked well" @@ -181,12 +181,12 @@ sign_off: - "Design system compliance > 95%" - "Accessibility tests pass" - "Usability metrics meet targets" - + designer_approval: statement: | I confirm that the implemented feature matches the design specifications and meets the quality standards defined in this test scenario. - + signature: "________________" date: "________________" diff --git a/src/modules/wds/tutorial/00-TUTORIAL-GUIDE.md b/src/modules/wds/tutorial/00-TUTORIAL-GUIDE.md index e12ca910..85880014 100644 --- a/src/modules/wds/tutorial/00-TUTORIAL-GUIDE.md +++ b/src/modules/wds/tutorial/00-TUTORIAL-GUIDE.md @@ -9,11 +9,13 @@ This tutorial teaches the complete WDS workflow through **16 chapters**. Each chapter contains: + - **Inspiration** - Why this step matters, the goal - **Teaching** - How to do it with confidence - **Practice** - Apply it to your own project **Format:** + - Read as documentation - Generate videos with NotebookLM - Use in workshops @@ -27,6 +29,7 @@ Each chapter contains: ### Foundation #### [Chapter 0: Why This Matters](chapter-00-why-this-matters/) + Learn how to be indispensable in the AI era --- @@ -34,6 +37,7 @@ Learn how to be indispensable in the AI era ### Phase 1: Project Brief #### [Chapter 1.1: Create Project Brief](chapter-1.1-project-brief/) + Define vision, goals, stakeholders, and constraints --- @@ -41,12 +45,15 @@ Define vision, goals, stakeholders, and constraints ### Phase 2: Trigger Mapping #### [Chapter 2.1: Identify Target Groups](chapter-2.1-identify-target-groups/) + WHO are your users and how to prioritize them #### [Chapter 2.2: Map Triggers & Outcomes](chapter-2.2-map-triggers-outcomes/) + WHAT triggers needs and WHY your business exists #### [Chapter 2.3: Prioritize Features](chapter-2.3-prioritize-features/) + Which features serve your top triggers --- @@ -54,9 +61,11 @@ Which features serve your top triggers ### Phase 3: Platform Requirements #### [Chapter 3.1: Platform Requirements](chapter-3.1-platform-requirements/) + Technical constraints, integrations, infrastructure #### [Chapter 3.2: Functional Requirements](chapter-3.2-functional-requirements/) + What the system must do --- @@ -64,21 +73,27 @@ What the system must do ### Phase 4: Conceptual Design #### [Chapter 4.1: Initialize Scenario](chapter-4.1-initialize-scenario/) + The 5 questions that define your design journey #### [Chapter 4.2: Sketch Interfaces](chapter-4.2-sketch-interfaces/) + Drawing pages with AI guidance #### [Chapter 4.3: Analyze with AI](chapter-4.3-analyze-with-ai/) + Upload sketches and have strategic conversations #### [Chapter 4.4: Decompose Components](chapter-4.4-decompose-components/) + Break pages into modular architecture #### [Chapter 4.5: Why-Based Specifications](chapter-4.5-why-based-specs/) + Document WHAT + WHY + WHAT NOT TO DO #### [Chapter 4.6: Validate Specifications](chapter-4.6-validate-specifications/) + Review completeness and test logic --- @@ -86,9 +101,11 @@ Review completeness and test logic ### Phase 5: Design System #### [Chapter 5.1: Extract Design Tokens](chapter-5.1-extract-design-tokens/) + Colors, typography, spacing from your specs #### [Chapter 5.2: Component Library](chapter-5.2-component-library/) + Reusable patterns across scenarios --- @@ -96,6 +113,7 @@ Reusable patterns across scenarios ### Phase 6: Development Integration #### [Chapter 6.1: UI Roadmap](chapter-6.1-ui-roadmap/) + Development priorities and handoff --- @@ -103,7 +121,9 @@ Development priorities and handoff ## How to Use This Tutorial ### Complete Workflow (Recommended) + Work through all 16 chapters sequentially with your own project: + ``` Chapters 1-16 → Complete design from brief to handoff Time: ~10 hours (spread over days/weeks) @@ -111,7 +131,9 @@ Result: Fully specified project ready for development ``` ### Quick Start (Core Concepts) + Focus on the essential chapters: + ``` Ch 0: Why This Matters Ch 2.2: Map Triggers & Outcomes @@ -122,7 +144,9 @@ Result: Understanding of core WDS philosophy ``` ### Phase-Specific Learning + Jump to the phase you need: + ``` Phase 2 (Ch 2.1-2.3): Trigger Mapping Phase 4 (Ch 4.1-4.6): Conceptual Design @@ -134,6 +158,7 @@ Phase 5 (Ch 5.1-5.2): Design System ## NotebookLM Integration Each chapter has a matching script in `/notebooklm-scripts/`: + - Feed chapter scripts to NotebookLM - Generate audio podcasts - Generate video presentations @@ -148,16 +173,19 @@ Each chapter has a matching script in `/notebooklm-scripts/`: Every chapter follows the same pattern: **1. Inspiration (10 min)** + - Why this step matters - The goal you're working toward - Real-world impact **2. Teaching (20 min)** + - How to do it with confidence - AI support at each step - Dog Week example walkthrough **3. Practice (10 min)** + - Apply to your own project - Step-by-step instructions - Success criteria diff --git a/src/modules/wds/tutorial/01-designer-role-in-ai-era.md b/src/modules/wds/tutorial/01-designer-role-in-ai-era.md index 42c1760f..cc9c23e8 100644 --- a/src/modules/wds/tutorial/01-designer-role-in-ai-era.md +++ b/src/modules/wds/tutorial/01-designer-role-in-ai-era.md @@ -9,11 +9,13 @@ Designers operate across **5 simultaneous dimensions** that AI and traditional developers cannot navigate alone: ### 1. Business Existence (WHY) + - Why does this business exist? - What problem does it solve in the world? - What value does it create? **Example (Dog Week):** + ``` WHY: Families struggle to coordinate dog care responsibilities. VALUE: Reduce conflict, increase accountability, happier dogs. @@ -22,11 +24,13 @@ VALUE: Reduce conflict, increase accountability, happier dogs. --- ### 2. Business Goals (WHAT SUCCESS LOOKS LIKE) + - What metrics matter? - What behaviors do we want to encourage? - What outcomes define success? **Example (Dog Week):** + ``` GOALS: - Increase walk completion rate (not just bookings) @@ -37,11 +41,13 @@ GOALS: --- ### 3. Product Strategy (HOW WE DELIVER VALUE) + - What features serve the goals? - What's the core experience? - What can we cut? **Example (Dog Week):** + ``` CORE: Week-based planning (Swedish culture) FEATURES: Calendar, leaderboard, countdown timers @@ -51,11 +57,13 @@ CUT: Daily view (doesn't match mental model) --- ### 4. Target Groups & Individual Needs (WHO & THEIR CONTEXT) + - Who are the users? - What are their different needs? - What contexts do they operate in? **Example (Dog Week):** + ``` USERS: - Parents: Need overview, accountability tracking @@ -71,11 +79,13 @@ CONTEXTS: --- ### 5. User Experience Translation (HOW USERS UNDERSTAND) + - How do we make this simple? - What mental models do users have? - What's intuitive vs confusing? **Example (Dog Week):** + ``` TRANSLATION: - Week circles (not dates) → Matches Swedish "Vecka 40" thinking @@ -111,6 +121,7 @@ Technical Specs ## Why This Is Designer Work ### Engineers Think: + - "How do I build this?" - "What's the data structure?" - "What API endpoints do I need?" @@ -118,6 +129,7 @@ Technical Specs **Missing:** WHY this feature? WHO needs it? WHAT behavior change? ### Business Developers Think: + - "What features will sell?" - "What's the ROI?" - "What's the market opportunity?" @@ -125,6 +137,7 @@ Technical Specs **Missing:** HOW do users actually think? WHAT's intuitive? HOW do we translate goals to experience? ### AI Thinks: + - "What patterns match this prompt?" - "What code structure fits this description?" - "What's the most common implementation?" @@ -143,22 +156,26 @@ Technical Specs ✅ Maintains coherent storyline across all touchpoints ✅ Balances business needs with user needs ✅ Makes complexity simple for end users -✅ Makes simplicity implementable for developers +✅ Makes simplicity implementable for developers --- ## Example: Dog Week Calendar States ### Business Developer Says: + "We need a booking system with accountability tracking." ### Engineer Says: + "I'll build a CRUD app with status fields: pending, active, completed." ### AI Says: + "Here's a calendar with booking slots and status indicators." ### Designer Says: + ``` WAIT. Let's think through all 5 dimensions: @@ -204,6 +221,7 @@ Working Product ``` **Without the designer's translation:** + - Engineers build what's easy, not what's needed - Business developers add features that don't serve users - AI generates generic solutions that miss the context @@ -213,11 +231,13 @@ Working Product ## Why AI Makes Designers MORE Important **Before AI:** + - Designers → Specs → Developers → Code (slow) - Designers had to compromise due to dev time - "We can't build that, too complex" **With AI:** + - Designers → Specs → AI → Code (fast) - Designers can specify the RIGHT solution - "AI can build anything, what SHOULD we build?" @@ -239,6 +259,7 @@ Every touchpoint tells the same story: **Story:** "Dog care is a family responsibility, and we make it fun and fair." **Touchpoints:** + - **Week view:** Shows family's shared responsibility (not individual calendars) - **Leaderboard:** Makes accountability fun (not punishing) - **Color states:** Visual clarity (not confusing text) @@ -246,6 +267,7 @@ Every touchpoint tells the same story: - **Booking flow:** Simple for kids (not complex admin) **If any touchpoint breaks the story:** + - Leaderboard shows "failures" → Punishing, not fun → Story breaks - Countdown sends notifications → Nagging, not gentle → Story breaks - Week view shows daily → Doesn't match mental model → Story breaks @@ -281,11 +303,13 @@ Layer 7: How do we make it implementable? **With or without AI, this multi-dimensional thinking is irreplaceable.** **AI makes it MORE valuable:** + - Implementation is fast → Specification becomes critical - Anyone can generate code → Knowing WHAT to build becomes the differentiator - Features are cheap → Coherent experience becomes the competitive advantage **The designer who can:** + - Think across all 5 dimensions - Maintain coherent storylines - Translate complexity into simplicity @@ -300,6 +324,7 @@ Layer 7: How do we make it implementable? **You're not just designing interfaces.** **You're architecting:** + - Business value delivery - User behavior change - Product strategy diff --git a/src/modules/wds/tutorial/02-wds-concept.md b/src/modules/wds/tutorial/02-wds-concept.md index d54a8393..fb819b17 100644 --- a/src/modules/wds/tutorial/02-wds-concept.md +++ b/src/modules/wds/tutorial/02-wds-concept.md @@ -18,6 +18,7 @@ In the last video, we talked about why designers are irreplaceable in the AI era ### Traditional Design Handoff Nightmare **Recognize this disaster?** + - You create gorgeous designs in isolation - Designs disappear into "design backlog purgatory" - Months later, developers build something vaguely similar @@ -37,6 +38,7 @@ With AI development, there's a new problem: But if you're unclear, AI starts hallucinating and leaves your project in a death spiral. **The new reality:** + - 🎯 Clear specifications = Perfect AI implementation - 🌪️ Unclear specifications = AI hallucination death spiral @@ -49,11 +51,13 @@ But if you're unclear, AI starts hallucinating and leaves your project in a deat **WDS is a specification-first design system.** Instead of: + ``` Sketch → Hope developers understand → Fix in QA ``` WDS gives you: + ``` Trigger Map → Scenario Init → Sketch → Why-Based Specs → AI Implementation ``` @@ -65,6 +69,7 @@ Trigger Map → Scenario Init → Sketch → Why-Based Specs → AI Implementati There is no longer a bottleneck in writing code. The bottleneck is **knowing what to build**. And that requires: + - Understanding user psychology (Trigger Map) - Defining the journey (Scenario Init) - Capturing design intent (Why-Based Specs) @@ -73,11 +78,13 @@ And that requires: ### WDS = Designer + AI Partnership **WDS is not:** + - ❌ AI replacing designers - ❌ Automated design generation - ❌ Generic template system **WDS is:** + - ✅ AI amplifying designer thinking - ✅ Socratic questioning to elevate decisions - ✅ Why-based specifications that preserve intent @@ -89,6 +96,7 @@ And that requires: ### 1. Socratic Questioning **Traditional AI:** + ``` You: "Create a calendar" AI: *Generates generic calendar* @@ -96,11 +104,12 @@ You: "No, that's not right..." ``` **WDS Agent:** + ``` You: "I need a calendar" Agent: "Help me understand - why week view instead of daily?" You: "Swedish families think in weeks..." -Agent: "Got it! So we match their mental model. +Agent: "Got it! So we match their mental model. Should I avoid adding daily/monthly views?" You: "Exactly!" ``` @@ -112,19 +121,22 @@ You: "Exactly!" ### 2. Why-Based Specifications **Traditional Spec:** + ```markdown ## Calendar Component + - Week view - 7 columns (days) - Color-coded states ``` **WDS Why-Based Spec:** + ```markdown ## Calendar Component WHY Week View: -Swedish families think in "Vecka 40". This matches their +Swedish families think in "Vecka 40". This matches their mental model. Daily view is too granular, monthly too abstract. → AI: Don't add daily/monthly views, even if you think it's "better" @@ -146,12 +158,14 @@ Notifications would break the "fun, not punishing" tone. ### 3. Modular Architecture **Traditional approach:** + ``` One giant specification file (800 lines) ├─ Layout + Visual + Logic + API + Content ``` **WDS Modular Architecture:** + ``` Pages/02-calendar-page.md (100 lines) ├─ WHERE: Page context, layout, content @@ -163,7 +177,8 @@ Features/walk-booking-logic.feature.md (200 lines) ├─ WHAT: Business rules, validation, API ``` -**The difference:** +**The difference:** + - Clear separation of concerns - Easy to maintain and update - Clean handoffs to specialists @@ -176,6 +191,7 @@ Features/walk-booking-logic.feature.md (200 lines) ### The Complete Flow **Phase 1: Trigger Map** + ``` WHO: Parents (need accountability) TRIGGER: Family conflict over dog care @@ -184,6 +200,7 @@ FEATURE: Family dog walk calendar ``` **Phase 2: Scenario Init** + ``` Entry Point: Google search (frustrated) Mental State: Tired of nagging, want simple solution @@ -192,6 +209,7 @@ Shortest Path: Landing → Sign up → Setup → Calendar → First walk ``` **Phase 3: Sketch** + ``` You: [Upload sketch of calendar page] Agent: "I see: Week view, leaderboard, countdown timers. @@ -199,6 +217,7 @@ Agent: "I see: Week view, leaderboard, countdown timers. ``` **Phase 4: Why-Based Specifications** + ``` Agent: "Why week view instead of daily?" You: "Swedish families think in weeks..." @@ -208,6 +227,7 @@ Agent: "Perfect! Documenting: ``` **Phase 5: AI Implementation** + ``` AI: *Implements exactly as specified* *Skips "helpful" features that would break intent* @@ -247,6 +267,7 @@ AI: *Implements exactly as specified* 5. **Designer-AI Partnership** - Amplification, not replacement **The result:** + - AI implements correctly first time - Design intent is preserved - Specifications become design knowledge @@ -259,6 +280,7 @@ AI: *Implements exactly as specified* In the next video, we'll dive into the **BMad Method** - the systematic approach that makes WDS possible. You'll learn: + - The 4 phases of design thinking - How each phase builds on the previous - Why this method works with AI diff --git a/src/modules/wds/tutorial/README-DEPRECATED.md b/src/modules/wds/tutorial/README-DEPRECATED.md index ace16c86..77cbe851 100644 --- a/src/modules/wds/tutorial/README-DEPRECATED.md +++ b/src/modules/wds/tutorial/README-DEPRECATED.md @@ -34,17 +34,20 @@ course/ ## Why the Change? **Benefits:** + - ✅ Single learning path - everything in one place - ✅ Module-specific tutorials - tutorial right where you need it - ✅ Cleaner structure - no separate tutorial folder - ✅ Better organization - theory + practice together **Old approach:** + - Separate tutorial folder - Disconnected from course content - Harder to navigate **New approach:** + - Tutorials integrated into modules - Theory → Tutorial → Practice flow - Easier to follow diff --git a/src/modules/wds/tutorial/chapter-00-why-this-matters/01-inspiration.md b/src/modules/wds/tutorial/chapter-00-why-this-matters/01-inspiration.md index 42d3168f..8525788b 100644 --- a/src/modules/wds/tutorial/chapter-00-why-this-matters/01-inspiration.md +++ b/src/modules/wds/tutorial/chapter-00-why-this-matters/01-inspiration.md @@ -1,4 +1,5 @@ # Chapter 0: Why WDS Matters + ## Part 1: Inspiration **Learn how to be indispensable in the AI era** @@ -14,6 +15,7 @@ This isn't about working faster or making shinier designs. It's about becoming w In the AI era, designers who master WDS become linchpin designers. They connect ideas that seem unrelated, make judgment calls when there's no clear answer, and create experiences that feel right in ways that can't be reduced to a formula. **What makes an irreplaceable designer:** + - Connects disparate ideas across business, psychology, and technology - Makes things happen when there's no instruction manual - Creates value that can't be commoditized or automated @@ -30,6 +32,7 @@ By the end of this tutorial, you'll have a completely different relationship wit Most importantly, you'll understand the five dimensions of thinking that only humans can navigate simultaneously - and you'll know how to use them to create designs that AI could never conceive on its own. **Your transformation:** + - ✅ Understand why designers are irreplaceable in the AI era - ✅ Master the 5 dimensions of designer thinking - ✅ Recognize what AI can and cannot do @@ -49,6 +52,7 @@ Traditional design work follows this exact pattern. You get a brief (instruction Here's the uncomfortable truth: AI is really, really good at factory work. If your job is to follow instructions and create predictable outputs, you're in trouble. But if you can become a linchpin - someone who connects ideas, makes judgment calls, and creates meaning - you become more valuable than ever. **The factory mindset in design:** + - Creates mockups by following briefs (instructions) - Hands off to developers (replaceable step) - Hopes they understand (no real connection) @@ -64,6 +68,7 @@ Let's be honest about what's happening. AI can now generate mockups in seconds. But here's the thing: AI cannot be a linchpin. It can't walk into a messy situation and figure out what actually needs to happen. It can't sense when a client is asking for the wrong thing. It can't connect a business goal to a psychological insight to a technical constraint and come up with something nobody expected but everyone loves. **What AI does better than cogs:** + - Generates mockups instantly (no creative block) - Follows design systems perfectly (zero deviation) - Iterates through hundreds of variations (no fatigue) @@ -87,6 +92,7 @@ Linchpin designers do what AI fundamentally cannot do: they give products a soul The bottleneck in product development used to be coding. AI demolished that. Now the bottleneck is **products worth building** - figuring out what to create that won't be just more noise in an ocean of AI-generated mediocrity. **What makes products come alive (what only designers can do):** + - Navigate 5 dimensions to find the human truth at the intersection - Make judgment calls that create emotional resonance, not just functionality - Build trust through decisions that show someone cared @@ -107,6 +113,7 @@ WDS teaches you to be this person systematically. Not through vague advice about This is what makes you indispensable. Not your Figma skills. Not your aesthetic taste. Your ability to walk into chaos and create order. **The irreplaceable designer:** + - Transforms complexity into clarity - Invents solutions nobody expected - Bridges business, psychology, and technology @@ -125,6 +132,7 @@ AI can generate variations endlessly and make things look polished on the surfac This is where user-centric creativity becomes critical. You're not just creating - you're evaluating, connecting, and protecting. You understand what it feels like to be a parent struggling to get their kids to help with the dog. You can sense when a business goal conflicts with user needs and find a creative solution that serves both. You're the advocate for the user's presence in every decision. You're the gatekeeper who ensures the impactful meeting between business and user actually happens through the product. **The designer as gatekeeper:** + - Catches AI's confident but ridiculous mistakes before they ship - Evaluates if solutions actually make logical sense - Ensures business goals don't contradict user needs @@ -147,6 +155,7 @@ Here's the paradigm shift: **The design becomes the specification. The specifica You remain in the loop - the skilled, experienced designer who evaluates AI's work, catches its confident mistakes, and ensures what ships actually makes sense. You become the key designer player - the person who makes things happen. AI becomes your tool - powerful but requiring your expertise to guide it. **The designer's transformation:** + - **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage - **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely - **Result:** From replaceable cog to indispensable gatekeeper - your design IS the product @@ -166,7 +175,7 @@ This is what makes you indispensable as a designer. AI can help you think throug **The 5 dimensions of design thinking:** 1. **Business Existence (WHY)** - Understanding purpose and value creation -2. **Business Goals (SUCCESS)** - Connecting to metrics and impact +2. **Business Goals (SUCCESS)** - Connecting to metrics and impact 3. **Product Strategy (HOW)** - Making hard choices about features 4. **Target Groups (WHO)** - Empathy and understanding needs 5. **Technical Viability (FEASIBLE)** - Bridging design and implementation @@ -188,6 +197,7 @@ This tutorial moves you to the other side. You'll become confident in your indis You'll become the designer who makes things happen. The one they can't do without. The linchpin designer. **Your transformation as a designer:** + - **Before:** Threatened, uncertain, frustrated, limited, replaceable - **After:** Confident, clear, empowered, unstoppable, indispensable - **Result:** The designer who makes things happen @@ -207,19 +217,21 @@ Compare the outcomes. The traditional approach - creating mockups, handing off t That's a 5x speed increase with better quality. But more importantly, the key designer's creative thinking was preserved and amplified instead of diluted and lost. **The comparison:** + - **Traditional (cog designer):** 26 weeks → Mediocre result → Intent lost - **WDS (linchpin designer):** 5 weeks → Exceptional result → Intent preserved - **Key difference:** Designer's user-centric creativity captured and amplified --- -*More case studies will be added here as they become available.* +_More case studies will be added here as they become available._ --- ## Ready to Begin? **Before you start, check the practicalities:** + - What skills you need (spoiler: you already have them) - Time investment and learning paths - Tools required (mostly free) @@ -232,6 +244,7 @@ That's a 5x speed increase with better quality. But more importantly, the key de **Or jump straight into the methodology:** In the next section (Teaching), you'll learn the concrete methodology: + - The 5 dimensions in detail with examples - What AI cannot do (and what it can) - Why specifications are the new code diff --git a/src/modules/wds/tutorial/chapter-00-why-this-matters/04-practicalities.md b/src/modules/wds/tutorial/chapter-00-why-this-matters/04-practicalities.md index 98800f7f..924a0ca6 100644 --- a/src/modules/wds/tutorial/chapter-00-why-this-matters/04-practicalities.md +++ b/src/modules/wds/tutorial/chapter-00-why-this-matters/04-practicalities.md @@ -1,4 +1,5 @@ # Chapter 0: Why WDS Matters + ## Part 4: Practicalities **Everything you need to know before starting** @@ -10,12 +11,14 @@ ### What Skills You Need **Required (you probably already have these):** + - Basic design thinking and UX principles - Ability to sketch interfaces (hand-drawn or digital) - Understanding of user needs and business goals - Willingness to think deeply about WHY **NOT required:** + - ❌ Coding skills - ❌ Advanced technical knowledge - ❌ Experience with AI tools @@ -30,17 +33,20 @@ ### How Long Does It Take? **Total tutorial time:** ~10 hours + - Spread over days or weeks at your own pace - Each chapter: 30-40 minutes - Practice exercises: 1-2 hours per chapter **Breakdown:** + - **Week 1-2:** Foundation chapters (0-2.3) - Understanding the methodology - **Week 3-4:** Core workflow (4.1-4.6) - Learning specification creation - **Week 5-6:** Advanced topics (5.1-6.1) - Design systems and handoff - **Ongoing:** Practice with your own projects **Real-world application:** + - First project with WDS: 2-3x slower than your usual process (learning curve) - Second project: Same speed as traditional approach - Third project onwards: 3-5x faster with better quality @@ -52,22 +58,27 @@ ### Essential Tools **For sketching:** + - Paper and pen (seriously, this works best) - OR digital sketching tool (Excalidraw, Figma, iPad + Pencil) **For AI assistance:** + - Access to Claude, ChatGPT, or similar AI assistant - Free tier is sufficient to start **For documentation:** + - Text editor (VS Code recommended, but any will work) - Markdown support (built into most modern editors) **For collaboration:** + - Git/GitHub (optional but recommended) - Shared folder system (Google Drive, Dropbox, etc.) **Total cost to get started:** $0-20/month + - Free tier AI tools work fine - Paid AI subscriptions ($20/month) provide better experience but aren't required @@ -80,21 +91,25 @@ By the end of this tutorial, you'll have created: **1. Complete Project Brief** + - Vision and goals clearly defined - Stakeholders and constraints documented - Foundation for all design decisions **2. Trigger Map** + - Target groups identified and prioritized - User triggers and outcomes mapped - Features prioritized by impact **3. Scenario Specifications** + - At least one complete user scenario - Why-based specifications for key components - AI-ready documentation **4. Design System Foundation** + - Design tokens extracted from your specs - Component patterns identified - Reusable architecture defined @@ -108,6 +123,7 @@ By the end of this tutorial, you'll have created: ### Choose Your Journey **Option 1: Full Immersion (Recommended)** + - Complete all 16 chapters in order - Practice exercises for each chapter - Apply to a real project as you learn @@ -115,6 +131,7 @@ By the end of this tutorial, you'll have created: - **Best for:** Designers who want to master the methodology **Option 2: Quick Start** + - Focus on core chapters (0, 2.2, 4.1, 4.5) - Skip advanced topics initially - Get started fast, learn more later @@ -122,6 +139,7 @@ By the end of this tutorial, you'll have created: - **Best for:** Designers who need results quickly **Option 3: Self-Paced** + - Learn one chapter per week - Deep practice between chapters - Build multiple projects as you learn @@ -135,7 +153,7 @@ By the end of this tutorial, you'll have created: ### Testimonials > "I was skeptical at first - another design methodology? But WDS changed how I think about my role. I'm no longer just making things pretty. I'm the strategic thinker who makes products come alive." -> +> > **— Sarah K., Product Designer** > "The 5x speed increase is real. But what surprised me most was how much clearer my thinking became. Writing why-based specifications forced me to understand the 'why' at a deeper level." @@ -150,7 +168,7 @@ By the end of this tutorial, you'll have created: > > **— James T., Design Director** -*Note: More testimonials will be added as designers complete the tutorial.* +_Note: More testimonials will be added as designers complete the tutorial._ --- @@ -189,16 +207,19 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi ### Getting Help **During the tutorial:** + - Each chapter includes detailed examples - AI assistants can clarify concepts in real-time - Practice exercises with clear success criteria **After completion:** + - GitHub Discussions for questions and sharing - Community showcase of WDS projects - Regular updates and new case studies **Contributing:** + - WDS is open-source and welcomes contributions - Share your case studies and learnings - Help improve the tutorial for future designers @@ -208,6 +229,7 @@ A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. Thi ## Ready to Start? You have everything you need: + - ✅ The skills (design thinking) - ✅ The tools (paper + AI) - ✅ The time (10 hours) @@ -226,6 +248,7 @@ Or return to the main guide to review the full structure: ## Your Transformation Starts Now Remember: + - **The design becomes the specification** - **The specification becomes the product** - **The code is just the printout** diff --git a/src/modules/wds/workflows/00-system/language-configuration-guide.md b/src/modules/wds/workflows/00-system/language-configuration-guide.md index 31419348..2194019b 100644 --- a/src/modules/wds/workflows/00-system/language-configuration-guide.md +++ b/src/modules/wds/workflows/00-system/language-configuration-guide.md @@ -22,6 +22,7 @@ These are configured during workflow initialization and stored in `wds-workflow- During WDS project setup, you'll be asked: **Question 1: Specification Language** + ``` What language should WDS write the design specifications in? @@ -33,6 +34,7 @@ What language should WDS write the design specifications in? ``` **Question 2: Product Languages** + ``` What languages will the final product support? @@ -49,7 +51,7 @@ Settings are stored in `docs/wds-workflow-status.yaml`: ```yaml config: - specification_language: "EN" + specification_language: 'EN' product_languages: - EN - SE @@ -63,6 +65,7 @@ config: ### Specification Language **Used for:** + - Instructions and guidance text in specs - Section descriptions - Comments and annotations @@ -70,19 +73,23 @@ config: - Design system documentation **Example:** + ```markdown # 1.1 Start Page ## Page Purpose -Convert visitors into users by addressing... ← Written in spec language + +Convert visitors into users by addressing... ← Written in spec language ## User Situation -Family members experiencing daily stress... ← Written in spec language + +Family members experiencing daily stress... ← Written in spec language ``` ### Product Languages **Used for:** + - All user-facing text content - Button labels - Form labels @@ -91,11 +98,14 @@ Family members experiencing daily stress... ← Written in spec language - Any text the END USER sees **Example:** + ```markdown #### Primary CTA Button + **OBJECT ID**: `start-hero-cta` + - **Component**: Button Primary -- **Content**: ← Product languages +- **Content**: ← Product languages - EN: "Get Started" - SE: "Kom Igång" - NO: "Kom i Gang" @@ -109,13 +119,14 @@ Family members experiencing daily stress... ← Written in spec language ```yaml config: - specification_language: "EN" # Specs written in English + specification_language: 'EN' # Specs written in English product_languages: - - EN # Product supports English - - SE # and Swedish + - EN # Product supports English + - SE # and Swedish ``` **Result:** + - Design specs written in English - All text objects have EN and SE translations @@ -123,29 +134,29 @@ config: ```yaml config: - specification_language: "EN" # Specs in English + specification_language: 'EN' # Specs in English product_languages: - EN - SE - NO - DK - - FI # 5 Nordic languages + - FI # 5 Nordic languages ``` ### Internal Swedish Tool ```yaml config: - specification_language: "SE" # Specs in Swedish + specification_language: 'SE' # Specs in Swedish product_languages: - - SE # Only Swedish product + - SE # Only Swedish product ``` ### Global Product ```yaml config: - specification_language: "EN" + specification_language: 'EN' product_languages: - EN - SE @@ -167,9 +178,11 @@ config: # Product Brief ## Vision + Create a platform that... ← Spec language ## Target Users + Swedish families with... ← Spec language ``` @@ -186,13 +199,16 @@ Personas and triggers documented in spec language. ```markdown ## Hero Object -**Purpose**: Primary value proposition ← Spec language + +**Purpose**: Primary value proposition ← Spec language #### Primary Headline + **OBJECT ID**: `start-hero-headline` + - **Component**: H1 heading -- **Position**: Center of hero ← Spec language -- **Content**: ← Product languages +- **Position**: Center of hero ← Spec language +- **Content**: ← Product languages - EN: "Every walk. on time." - SE: "Varje promenad. i tid." ``` @@ -205,10 +221,12 @@ Personas and triggers documented in spec language. ```markdown ## Button Component -### Usage ← Spec language +### Usage ← Spec language + Use this button for primary actions... -### Examples ← Product languages +### Examples ← Product languages + - EN: "Submit", "Save", "Continue" - SE: "Skicka", "Spara", "Fortsätt" ``` @@ -227,22 +245,26 @@ Every text object follows this pattern: ```markdown #### {{Purpose_Name}} + **OBJECT ID**: `{{id}}` + - **Component**: {{type}} -- **Position**: {{description}} ← Spec language -- **Style**: {{specifications}} ← Spec language -- **Behavior**: {{description}} ← Spec language -- **Content**: ← Product languages +- **Position**: {{description}} ← Spec language +- **Style**: {{specifications}} ← Spec language +- **Behavior**: {{description}} ← Spec language +- **Content**: ← Product languages {{#each product_languages}} - {{this}}: "{{content}}" - {{/each}} + {{/each}} ``` **Real Example:** ```markdown #### Email Label + **OBJECT ID**: `signin-form-email-label` + - **Component**: Label text - **Position**: Above email input field - **For**: signin-form-email-input @@ -304,6 +326,7 @@ User provides all translations, agent validates and documents. ### ✅ Developer-Friendly Config provides: + ```yaml product_languages: - EN @@ -318,6 +341,7 @@ Developers know exactly what languages to implement. ## Language Codes Reference **Nordic:** + - EN = English - SE = Swedish (Svenska) - NO = Norwegian (Norsk) @@ -325,6 +349,7 @@ Developers know exactly what languages to implement. - FI = Finnish (Suomi) **Western Europe:** + - DE = German (Deutsch) - FR = French (Français) - ES = Spanish (Español) @@ -333,16 +358,19 @@ Developers know exactly what languages to implement. - PT = Portuguese (Português) **Eastern Europe:** + - PL = Polish (Polski) - CZ = Czech (Čeština) - RU = Russian (Русский) **Asia:** + - JA = Japanese (日本語) - ZH = Chinese (中文) - KO = Korean (한국어) **Other:** + - AR = Arabic (العربية) - TR = Turkish (Türkçe) @@ -362,7 +390,7 @@ Product Languages: EN, SE ```yaml # docs/wds-workflow-status.yaml config: - specification_language: "EN" + specification_language: 'EN' product_languages: - EN - SE @@ -373,15 +401,17 @@ config: ```markdown # 1.1 Start Page -The start page serves as the primary entry point... ← Written in EN +The start page serves as the primary entry point... ← Written in EN #### Primary Headline + **OBJECT ID**: `start-hero-headline` + - **Component**: H1 heading -- **Position**: Center of hero section ← Written in EN +- **Position**: Center of hero section ← Written in EN - **Content**: - - EN: "Every walk. on time. Every time." ← Product language 1 - - SE: "Varje promenad. i tid. Varje gång." ← Product language 2 + - EN: "Every walk. on time. Every time." ← Product language 1 + - SE: "Varje promenad. i tid. Varje gång." ← Product language 2 ``` ### For Developers @@ -394,8 +424,8 @@ const languages = ['EN', 'SE']; const content = { 'start-hero-headline': { en: 'Every walk. on time. Every time.', - se: 'Varje promenad. i tid. Varje gång.' - } + se: 'Varje promenad. i tid. Varje gång.', + }, }; ``` @@ -410,6 +440,7 @@ If you need to add/change languages mid-project: 3. **Continue** with new language config **Before:** + ```yaml product_languages: - EN @@ -417,25 +448,25 @@ product_languages: ``` **After:** + ```yaml product_languages: - EN - SE - - NO # Added Norwegian + - NO # Added Norwegian ``` **Update existing specs:** + ```markdown #### Primary Headline + - **Content**: - EN: "Every walk. on time." - SE: "Varje promenad. i tid." - - NO: "Hver tur. i tide." ← Add new language + - NO: "Hver tur. i tide." ← Add new language ``` --- **Language configuration ensures complete, translation-ready specifications from day one!** 🌍✨ - - - diff --git a/src/modules/wds/workflows/00-system/language-flow-diagram.md b/src/modules/wds/workflows/00-system/language-flow-diagram.md index affb55b1..9f1c4ce8 100644 --- a/src/modules/wds/workflows/00-system/language-flow-diagram.md +++ b/src/modules/wds/workflows/00-system/language-flow-diagram.md @@ -29,6 +29,7 @@ Product languages: EN, SE ``` **Agent stores:** + - `specification_language = "EN"` - `product_languages = ["EN", "SE"]` @@ -74,6 +75,7 @@ config: ``` **Agent now knows:** + - Write specs in English - Request content in English AND Swedish for all text @@ -124,11 +126,12 @@ Line height: 1.2 ... ``` -*Spec written in English (specification_language)* +_Spec written in English (specification_language)_ ### Step 3: Content with Translations **Agent reads config:** + ```xml Load product_languages from config → ["EN", "SE"] ``` @@ -147,6 +150,7 @@ SE: ``` **User provides:** + ``` EN: Every walk. on time. Every time. @@ -154,6 +158,7 @@ SE: Varje promenad. i tid. Varje gång. ``` **Agent validates:** + ``` ✅ EN content: 37 characters (fits 60 capacity) ✅ SE content: 36 characters (fits 60 capacity) @@ -168,20 +173,23 @@ SE: Varje promenad. i tid. Varje gång. ```markdown # 1.1 Start Page -The start page serves as the primary entry point... ← English (spec language) +The start page serves as the primary entry point... ← English (spec language) ## Page Sections ### Hero Object -**Purpose**: Primary value proposition ← English (spec language) + +**Purpose**: Primary value proposition ← English (spec language) #### Primary Headline + **OBJECT ID**: `start-hero-headline` + - **Component**: H1 heading (`.text-heading-1`) -- **Position**: Center of hero section ← English (spec language) -- **Style**: Bold, 42px, line-height 1.2 ← English (spec language) -- **Behavior**: Updates with language toggle ← English (spec language) -- **Content**: ← Product languages +- **Position**: Center of hero section ← English (spec language) +- **Style**: Bold, 42px, line-height 1.2 ← English (spec language) +- **Behavior**: Updates with language toggle ← English (spec language) +- **Content**: ← Product languages - EN: "Every walk. on time. Every time." - SE: "Varje promenad. i tid. Varje gång." ``` @@ -194,39 +202,48 @@ The start page serves as the primary entry point... ← English (spec languag ```markdown ### Hero Object -**Purpose**: Primary value proposition ← Spec language + +**Purpose**: Primary value proposition ← Spec language #### Primary Headline + **OBJECT ID**: `start-hero-headline` + - **Component**: H1 heading -- **Position**: Center of hero, top ← Spec language +- **Position**: Center of hero, top ← Spec language - **Content**: - - EN: "Every walk. on time. Every time." ← Product languages + - EN: "Every walk. on time. Every time." ← Product languages - SE: "Varje promenad. i tid. Varje gång." #### Supporting Text + **OBJECT ID**: `start-hero-supporting` + - **Component**: Body text -- **Position**: Below headline ← Spec language +- **Position**: Below headline ← Spec language - **Content**: - - EN: "Never miss a walk again." ← Product languages + - EN: "Never miss a walk again." ← Product languages - SE: "Missa aldrig en promenad." #### Primary CTA + **OBJECT ID**: `start-hero-cta` + - **Component**: Button Primary -- **Position**: Center, below text ← Spec language +- **Position**: Center, below text ← Spec language - **Content**: - - EN: "Get Started" ← Product languages + - EN: "Get Started" ← Product languages - SE: "Kom Igång" ``` **Reading in English:** + > Every walk. on time. Every time. > Never miss a walk again. > [Get Started] **Reading in Swedish:** + > Varje promenad. i tid. Varje gång. > Missa aldrig en promenad. > [Kom Igång] @@ -254,16 +271,16 @@ const supportedLanguages = ['en', 'se']; const translations = { 'start-hero-headline': { en: 'Every walk. on time. Every time.', - se: 'Varje promenad. i tid. Varje gång.' + se: 'Varje promenad. i tid. Varje gång.', }, 'start-hero-supporting': { en: 'Never miss a walk again.', - se: 'Missa aldrig en promenad.' + se: 'Missa aldrig en promenad.', }, 'start-hero-cta': { en: 'Get Started', - se: 'Kom Igång' - } + se: 'Kom Igång', + }, }; // Language toggle @@ -342,11 +359,13 @@ function setLanguage(lang: 'en' | 'se') { ### ✅ Two Distinct Languages **Specification Language:** + - Documentation language - For designers, PMs, developers - Describes structure, behavior, logic **Product Languages:** + - User-facing content - What end users see - Can be multiple languages @@ -354,6 +373,7 @@ function setLanguage(lang: 'en' | 'se') { ### ✅ Early Configuration **Set during workflow init** - before any design work + - No mid-project surprises - All stakeholders aligned - Complete from day one @@ -361,6 +381,7 @@ function setLanguage(lang: 'en' | 'se') { ### ✅ Automatic Propagation **Config flows through all phases:** + - Phase 1: Brief in spec language - Phase 2: Trigger Map in spec language - Phase 4: Specs in spec language, content in ALL product languages @@ -387,6 +408,7 @@ Each language complete and coherent! ## Example: Adding Norwegian Mid-Project **Original config:** + ```yaml product_languages: - EN @@ -396,20 +418,23 @@ product_languages: **User needs Norwegian:** 1. **Update config:** + ```yaml product_languages: - EN - SE - - NO # Added + - NO # Added ``` 2. **Add to existing specs:** + ```markdown #### Primary Headline + - **Content**: - EN: "Every walk. on time." - SE: "Varje promenad. i tid." - - NO: "Hver tur. i tide." ← Add to all text objects + - NO: "Hver tur. i tide." ← Add to all text objects ``` 3. **Future text objects automatically include NO** @@ -419,6 +444,3 @@ Agents read updated config and request 3 languages going forward. --- **Language configuration ensures complete, production-ready translations from the very beginning!** 🌍✨ - - - diff --git a/src/modules/wds/workflows/00-system/wds-workflow-status-template.yaml b/src/modules/wds/workflows/00-system/wds-workflow-status-template.yaml index 163ca0fa..4331c659 100644 --- a/src/modules/wds/workflows/00-system/wds-workflow-status-template.yaml +++ b/src/modules/wds/workflows/00-system/wds-workflow-status-template.yaml @@ -22,13 +22,13 @@ workflow_path: "{{workflow_path_file}}" # Configuration config: - folder_prefix: "{{folder_prefix}}" # letters or numbers - folder_case: "{{folder_case}}" # title or lowercase - brief_level: "{{brief_level}}" # simplified or complete - include_design_system: {{include_design_system}} + folder_prefix: "{{folder_prefix}}" # letters or numbers + folder_case: "{{folder_case}}" # title or lowercase + brief_level: "{{brief_level}}" # simplified or complete + include_design_system: { { include_design_system } } component_library: "{{component_library}}" - specification_language: "{{specification_language}}" # Language for writing specs (EN, SE, etc.) - product_languages: {{product_languages}} # Array of languages product supports + specification_language: "{{specification_language}}" # Language for writing specs (EN, SE, etc.) + product_languages: { { product_languages } } # Array of languages product supports # Folder mapping (generated based on config) folders: @@ -41,7 +41,6 @@ folders: # Workflow status tracking workflow_status: "{{workflow_items}}" - # Example structure when populated: # workflow_status: # phase_1_project_brief: diff --git a/src/modules/wds/workflows/1-project-brief/complete/instructions.md b/src/modules/wds/workflows/1-project-brief/complete/instructions.md index 6ceb9ddb..bf6ffe3e 100644 --- a/src/modules/wds/workflows/1-project-brief/complete/instructions.md +++ b/src/modules/wds/workflows/1-project-brief/complete/instructions.md @@ -9,6 +9,7 @@ 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? 🎯 If this project succeeds beyond your wildest dreams, what does that look like? Don't worry about being realistic yet - dream big. Listen for: + - Aspirational outcomes - Impact on users - Market position - Emotional drivers - + Reflect back and help crystallize into a clear vision statement @@ -50,15 +52,16 @@ If this project succeeds beyond your wildest dreams, what does that look like? D Complete this statement: -*For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator].* +_For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator]._ If user struggles, break it down: + 1. Who's the target customer? 2. What's their need or opportunity? 3. What category does this fit? 4. What's the key benefit? 5. What makes it different from alternatives? - + Help craft a clear positioning statement @@ -144,18 +147,20 @@ Others who interact with the product but aren't the primary user? **What metrics or outcomes define success?** Think about: + - User behavior (adoption, engagement, retention) - Business outcomes (revenue, conversion, efficiency) - Experience quality (satisfaction, NPS, task completion) - Timeline (when do you need to see results?) Help make criteria SMART: + - Specific - Measurable - Achievable - Relevant - Time-bound - + success_criteria @@ -166,16 +171,18 @@ Think about: **What alternatives do your users have today?** This could be: + - Direct competitors - Different approaches to the same problem - Manual/analog solutions - Doing nothing For each alternative, explore: + - What do they do well? - Where do they fall short? - Why might users choose them over you? - + **What's your unfair advantage?** @@ -241,6 +248,7 @@ Company stage, team capabilities, market conditions, past attempts? {{constraints}} --- + Does this capture your strategic foundation? Anything to refine? @@ -255,6 +263,7 @@ Company stage, team capabilities, market conditions, past attempts? Location: `A-Product-Brief/project-brief.md` This strategic foundation will guide all design decisions. You're ready for: + - **Phase 2: Trigger Mapping** - Deep dive into user psychology - **Phase 3: PRD Platform** - Technical foundation @@ -262,4 +271,3 @@ Your vision is clear. Let's build something great! 🚀 - diff --git a/src/modules/wds/workflows/1-project-brief/complete/project-brief.template.md b/src/modules/wds/workflows/1-project-brief/complete/project-brief.template.md index 11182fe3..407fe70a 100644 --- a/src/modules/wds/workflows/1-project-brief/complete/project-brief.template.md +++ b/src/modules/wds/workflows/1-project-brief/complete/project-brief.template.md @@ -19,6 +19,7 @@ {{positioning_statement}} **Breakdown:** + - **Target Customer:** {{target_customer}} - **Need/Opportunity:** {{need_opportunity}} - **Category:** {{category}} @@ -31,8 +32,7 @@ **Type:** {{business_model}} -{{#if business_model_b2b}} ---- +## {{#if business_model_b2b}} ## Business Customer Profile (B2B) @@ -40,11 +40,12 @@ ### Buying Roles -| Role | Description | -|------|-------------| -| **Buyer** | {{buyer_role}} | +| Role | Description | +| ------------ | ----------------- | +| **Buyer** | {{buyer_role}} | | **Champion** | {{champion_role}} | -| **User** | {{user_role}} | +| **User** | {{user_role}} | + {{/if}} --- @@ -99,5 +100,4 @@ This complete brief provides strategic foundation for all design work: --- -*Generated by Whiteport Design Studio* - +_Generated by Whiteport Design Studio_ diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-01-init.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-01-init.md index bf18df11..9b69de4d 100644 --- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-01-init.md +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-01-init.md @@ -1,13 +1,17 @@ # Step 1: Welcome and Set Expectations ## Purpose + Welcome user and set expectations for the Project Brief workflow. ## Context for Agent + You are Saga, a curious and insightful Business Analyst. Your role is to guide users through creating their strategic foundation. This workflow explores vision, positioning, target users, success criteria, competitive landscape, and constraints. ## Key Elements to Cover + This workflow establishes the strategic foundation by exploring: + - Vision & positioning (core strategic direction) - Target users (ICP) - who we're designing for - Success criteria (how we'll measure success) @@ -15,13 +19,17 @@ This workflow establishes the strategic foundation by exploring: - Constraints & context (real-world limitations) ## Instructions + Welcome the user and explain that this is their strategic foundation. Set time expectations (30-60 minutes) and ask about any existing context that should be considered. ## Next Step + When user confirms readiness, proceed to step-02-vision.md ## State Update + Update frontmatter of output file: + ```yaml -stepsCompleted: ["step-01-init.md"] +stepsCompleted: ['step-01-init.md'] ``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-02-vision.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-02-vision.md index 00eea8d2..cc4ee691 100644 --- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-02-vision.md +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-02-vision.md @@ -1,12 +1,15 @@ # Step 2: Capture Vision ## Purpose + Help user articulate their vision for the product. ## Context for Agent + You are exploring the big picture with the user. Your goal is to help them crystallize their aspirational vision into a clear statement that will guide all decisions. ## Key Elements + This step captures the high-level, aspirational direction that will guide all decisions. ## Instructions @@ -27,11 +30,14 @@ This step captures the high-level, aspirational direction that will guide all de - Use collaborative language: "What I'm hearing is..." or "It sounds like..." ## Next Step + After capturing vision, proceed to step-03-positioning.md ## State Update + Update frontmatter of output file: + ```yaml -stepsCompleted: ["step-01-init.md", "step-02-vision.md"] -vision: "[captured vision statement]" +stepsCompleted: ['step-01-init.md', 'step-02-vision.md'] +vision: '[captured vision statement]' ``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-03-positioning.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-03-positioning.md index cce1a541..7af936b3 100644 --- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-03-positioning.md +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-03-positioning.md @@ -1,26 +1,34 @@ # Step 3: Define Positioning ## Purpose + Help user define clear positioning statement for their product. ## Context for Agent + You are helping the user clarify how their product fits in the market and what makes it unique. ## Key Elements + This step establishes market positioning and differentiation. ## Key Framework + Positioning statement format: "For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator]." ## Instructions + Guide user through positioning framework. Ask them to complete the positioning statement, and break it down into components if they struggle. Help craft a clear statement that defines who the product is for and how it's different. ## Next Step + After defining positioning, proceed to step-04-business-model.md ## State Update + Update frontmatter of output file: + ```yaml -stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md"] -positioning: "[captured positioning statement]" +stepsCompleted: ['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md'] +positioning: '[captured positioning statement]' ``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-04-business-model.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-04-business-model.md index f7b2ac3d..c3b38a9d 100644 --- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-04-business-model.md +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-04-business-model.md @@ -1,20 +1,26 @@ # Step 4: Determine Business Model ## Goal + Help user identify whether their product is B2B, B2C, or both. ## Key Elements + Business model determines who buys/uses the product and affects all strategic decisions. ## Instructions + Ask user whether their product is B2B, B2C, or both. Present clear options and explain the implications of each choice. ## Next Step + After determining business model, proceed to step-05-business-customers.md if B2B or Both, or step-06-target-users.md if B2C ## State Update + Update frontmatter of output file: + ```yaml -stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md"] -business_model: "[b2b/b2c/both]" +stepsCompleted: ['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md', 'step-04-business-model.md'] +business_model: '[b2b/b2c/both]' ``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-05-business-customers.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-05-business-customers.md index 7ce3738a..a8f7bade 100644 --- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-05-business-customers.md +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-05-business-customers.md @@ -1,21 +1,28 @@ # Step 5: Identify Business Customers (B2B) ## Goal + Help user define their ideal business customer profile. ## Key Elements + Business customer profile determines who buys the product and influences purchasing decisions. ## Instructions + If business model is B2B or Both, guide user to define their ideal business customer. Ask about company size, industry, decision-making structure, and budget authority. Also identify buying roles (buyer vs. user). ## Next Step + After identifying business customers, proceed to step-06-target-users.md ## State Update + Update frontmatter of output file: + ```yaml -stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md"] -business_customer_profile: "[captured business customer profile]" -buying_roles: "[captured buying roles]" +stepsCompleted: + ['step-01-init.md', 'step-02-vision.md', 'step-03-positioning.md', 'step-04-business-model.md', 'step-05-business-customers.md'] +business_customer_profile: '[captured business customer profile]' +buying_roles: '[captured buying roles]' ``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-06-target-users.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-06-target-users.md index 60773e52..4e09f3a5 100644 --- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-06-target-users.md +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-06-target-users.md @@ -1,24 +1,39 @@ # Step 6: Identify Target Users ## Purpose + Help user define their ideal customer profile. ## Context for Agent + You are identifying who the product is for and what their needs are. This information will guide all design decisions. ## Key Elements + This step identifies who we're designing for and what their needs are. ## Instructions + Guide user to describe their ideal users in detail. Ask about their role, demographics, daily experience, frustrations, goals, and current solutions. Also identify any secondary users or stakeholders. ## Next Step + After identifying target users, proceed to step-07-success-criteria.md ## State Update + Update frontmatter of output file: + ```yaml -stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md"] -ideal_user_profile: "[captured user profile]" -secondary_users: "[captured secondary users]" +stepsCompleted: + [ + 'step-01-init.md', + 'step-02-vision.md', + 'step-03-positioning.md', + 'step-04-business-model.md', + 'step-05-business-customers.md', + 'step-06-target-users.md', + ] +ideal_user_profile: '[captured user profile]' +secondary_users: '[captured secondary users]' ``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-07-success-criteria.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-07-success-criteria.md index dc7e12bb..d675811e 100644 --- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-07-success-criteria.md +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-07-success-criteria.md @@ -1,23 +1,39 @@ # Step 7: Define Success Criteria ## Purpose + Help user define measurable success criteria for their project. ## Context for Agent + You are establishing how the project will know if it's successful. This will guide all future decisions. ## Key Elements + This step establishes measurable outcomes that indicate success. ## Instructions + Guide user to define metrics and outcomes that indicate success. Help them think about user behavior, business outcomes, experience quality, and timeline. Work with them to make criteria SMART (Specific, Measurable, Achievable, Relevant, Time-bound). ## Next Step + After defining success criteria, proceed to step-08-competitive-landscape.md ## State Update + Update frontmatter of output file: + ```yaml -stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md"] -success_criteria: "[captured success criteria]" +stepsCompleted: + [ + 'step-01-init.md', + 'step-02-vision.md', + 'step-03-positioning.md', + 'step-04-business-model.md', + 'step-05-business-customers.md', + 'step-06-target-users.md', + 'step-07-success-criteria.md', + ] +success_criteria: '[captured success criteria]' ``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-08-competitive-landscape.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-08-competitive-landscape.md index 77a9d156..5e5be0a0 100644 --- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-08-competitive-landscape.md +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-08-competitive-landscape.md @@ -1,24 +1,41 @@ # Step 8: Analyze Competitive Landscape ## Purpose + Help user understand alternatives and their unique advantage. ## Context for Agent + You are exploring what alternatives exist and what makes the product unique. This information will guide differentiation strategy. ## Key Elements + This step identifies competitive positioning and unique value proposition. ## Instructions + Guide user to understand alternatives including direct competitors, different approaches, manual solutions, or doing nothing. For each alternative, explore strengths, weaknesses, and why users might choose them. Help identify their unfair advantage. ## Next Step + After analyzing competitive landscape, proceed to step-09-constraints.md ## State Update + Update frontmatter of output file: + ```yaml -stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md"] -competitive_landscape: "[captured competitive analysis]" -unfair_advantage: "[captured unfair advantage]" +stepsCompleted: + [ + 'step-01-init.md', + 'step-02-vision.md', + 'step-03-positioning.md', + 'step-04-business-model.md', + 'step-05-business-customers.md', + 'step-06-target-users.md', + 'step-07-success-criteria.md', + 'step-08-competitive-landscape.md', + ] +competitive_landscape: '[captured competitive analysis]' +unfair_advantage: '[captured unfair advantage]' ``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-09-constraints.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-09-constraints.md index 1a5af5e8..4385afc5 100644 --- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-09-constraints.md +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-09-constraints.md @@ -1,24 +1,42 @@ # Step 9: Capture Constraints and Context ## Purpose + Help user identify constraints that should shape design decisions. ## Context for Agent + You are grounding the vision in reality by identifying limitations and context. ## Key Elements + This step identifies real-world limitations and additional context. ## Instructions + Guide user to identify constraints including timeline, budget, technical requirements, brand guidelines, regulatory needs, and integration requirements. Also ask for additional context like company stage, team capabilities, market conditions, or past attempts. ## Next Step + After capturing constraints, proceed to step-10-synthesize.md ## State Update + Update frontmatter of output file: + ```yaml -stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md", "step-09-constraints.md"] -constraints: "[captured constraints]" -additional_context: "[captured additional context]" +stepsCompleted: + [ + 'step-01-init.md', + 'step-02-vision.md', + 'step-03-positioning.md', + 'step-04-business-model.md', + 'step-05-business-customers.md', + 'step-06-target-users.md', + 'step-07-success-criteria.md', + 'step-08-competitive-landscape.md', + 'step-09-constraints.md', + ] +constraints: '[captured constraints]' +additional_context: '[captured additional context]' ``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-10-synthesize.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-10-synthesize.md index 1abaee1b..043543bf 100644 --- a/src/modules/wds/workflows/1-project-brief/complete/steps/step-10-synthesize.md +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-10-synthesize.md @@ -1,23 +1,42 @@ # Step 10: Synthesize and Create Brief ## Purpose + Synthesize all captured information into a complete project brief document. ## Context for Agent + You are bringing together all the strategic elements into a comprehensive brief that will guide all design decisions. ## Key Elements + This step compiles all strategic foundation elements into a cohesive document. ## Instructions + Present all captured information (vision, positioning, business model, business customers, target users, success criteria, competitive landscape, unfair advantage, constraints, and additional context). Ask for confirmation and make any requested adjustments. Generate final document using the template. ## Next Step + Workflow complete. User can proceed to Phase 2: Trigger Mapping ## State Update + Update frontmatter of output file: + ```yaml -stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md", "step-09-constraints.md", "step-10-synthesize.md"] -status: "complete" +stepsCompleted: + [ + 'step-01-init.md', + 'step-02-vision.md', + 'step-03-positioning.md', + 'step-04-business-model.md', + 'step-05-business-customers.md', + 'step-06-target-users.md', + 'step-07-success-criteria.md', + 'step-08-competitive-landscape.md', + 'step-09-constraints.md', + 'step-10-synthesize.md', + ] +status: 'complete' ``` diff --git a/src/modules/wds/workflows/1-project-brief/simplified/instructions.md b/src/modules/wds/workflows/1-project-brief/simplified/instructions.md index 8ce1842d..94c4086a 100644 --- a/src/modules/wds/workflows/1-project-brief/simplified/instructions.md +++ b/src/modules/wds/workflows/1-project-brief/simplified/instructions.md @@ -9,6 +9,7 @@ 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! 🎯 Describe the project in a few sentences. What will users see and interact with? Listen for: + - Type of project (app, website, feature, page) - Target platform (web, mobile, both) - Key functionality or purpose - + If unclear, ask one clarifying question @@ -38,11 +40,12 @@ Describe the project in a few sentences. What will users see and interact with?< Why does this project exist? What problem are you solving, or what opportunity are you pursuing? Listen for: + - Pain points being addressed - Market opportunity - User needs not being met - Business drivers - + Reflect back what you heard to confirm understanding @@ -55,10 +58,11 @@ Why does this project exist? What problem are you solving, or what opportunity a When this design is complete, what will make it successful? What experience do you want users to have? Listen for: + - Functional goals (what it should do) - Experience goals (how it should feel) - Business goals (what outcomes matter) - + Help refine vague goals into specific, actionable ones @@ -71,12 +75,13 @@ When this design is complete, what will make it successful? What experience do y Timeline, technology, brand guidelines, existing systems to integrate with? Note: + - Technical constraints - Timeline/deadline - Budget considerations - Brand/style requirements - Integration requirements - + It's okay if there are few constraints - note "flexible" where appropriate @@ -111,6 +116,7 @@ Timeline, technology, brand guidelines, existing systems to integrate with? - diff --git a/src/modules/wds/workflows/1-project-brief/simplified/simplified-brief.template.md b/src/modules/wds/workflows/1-project-brief/simplified/simplified-brief.template.md index 0fea3074..ea911cb8 100644 --- a/src/modules/wds/workflows/1-project-brief/simplified/simplified-brief.template.md +++ b/src/modules/wds/workflows/1-project-brief/simplified/simplified-brief.template.md @@ -41,5 +41,4 @@ This simplified brief provides essential context for design work. The following --- -*Generated by Whiteport Design Studio* - +_Generated by Whiteport Design Studio_ diff --git a/src/modules/wds/workflows/1-project-brief/workflow.yaml b/src/modules/wds/workflows/1-project-brief/workflow.yaml index 01c7d221..b638160d 100644 --- a/src/modules/wds/workflows/1-project-brief/workflow.yaml +++ b/src/modules/wds/workflows/1-project-brief/workflow.yaml @@ -3,7 +3,6 @@ name: Product Brief Workflow description: Establish project context - foundation for all design work web_bundle: true --- - # WDS Phase 1: Project Brief name: project-brief author: "Whiteport Design Studio" @@ -42,4 +41,3 @@ primary_agent: "saga-analyst" standalone: true web_bundle: false - diff --git a/src/modules/wds/workflows/2-trigger-mapping/instructions.md b/src/modules/wds/workflows/2-trigger-mapping/instructions.md index a6ebe91f..5a20b422 100644 --- a/src/modules/wds/workflows/2-trigger-mapping/instructions.md +++ b/src/modules/wds/workflows/2-trigger-mapping/instructions.md @@ -9,6 +9,7 @@ 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? 🎯 Would you like to: + 1. **Full session** - All 5 workshops now 2. **Workshop by workshop** - Start with Business Goals, continue later 3. **Jump to specific workshop** - If you've done some already @@ -86,6 +88,7 @@ Ready to begin? 🎯 ✅ **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? 🎯 {{summary_of_priorities}} You now have strategic clarity on: + - What success looks like (business goals) - Who to focus on (target groups) - What drives them (positive & negative forces) @@ -105,4 +109,3 @@ Ready for the next phase! 🚀 - diff --git a/src/modules/wds/workflows/2-trigger-mapping/templates/feature-impact.template.md b/src/modules/wds/workflows/2-trigger-mapping/templates/feature-impact.template.md index b8d9238c..9568b215 100644 --- a/src/modules/wds/workflows/2-trigger-mapping/templates/feature-impact.template.md +++ b/src/modules/wds/workflows/2-trigger-mapping/templates/feature-impact.template.md @@ -15,7 +15,8 @@ ## Prioritized Features | Rank | Feature | Score | Decision | -|------|---------|-------|----------| +| ---- | ------- | ----- | -------- | + {{#each sorted_features}} | {{this.rank}} | {{this.name}} | {{this.score}} | {{this.decision}} | {{/each}} @@ -26,21 +27,24 @@ **Must Have MVP (Primary High OR Top Tier Score):** {{#each must_have}} + - {{this.name}} ({{this.score}}) -{{/each}} + {{/each}} **Consider for MVP:** {{#each consider}} + - {{this.name}} ({{this.score}}) -{{/each}} + {{/each}} **Defer (Nice-to-Have or Low Strategic Value):** {{#each defer}} + - {{this.name}} ({{this.score}}) -{{/each}} + {{/each}} --- -*Generated by Whiteport Design Studio* -*Strategic input for Phase 4: UX Design and Phase 6: PRD/Development* -*Beta methodology - feedback welcome* +_Generated by Whiteport Design Studio_ +_Strategic input for Phase 4: UX Design and Phase 6: PRD/Development_ +_Beta methodology - feedback welcome_ diff --git a/src/modules/wds/workflows/2-trigger-mapping/templates/trigger-map.template.md b/src/modules/wds/workflows/2-trigger-mapping/templates/trigger-map.template.md index 749a12d1..51624925 100644 --- a/src/modules/wds/workflows/2-trigger-mapping/templates/trigger-map.template.md +++ b/src/modules/wds/workflows/2-trigger-mapping/templates/trigger-map.template.md @@ -15,7 +15,7 @@ This is the visual overview. For detailed documentation, see: - **01-Business-Goals.md** - Full vision statements and SMART objectives - **02-Target-Groups.md** - All personas with complete driving forces - **03-Feature-Impact-Analysis.md** - Prioritized features with impact scores -- **04-08-*.md** - Individual persona detail files +- **04-08-\*.md** - Individual persona detail files --- @@ -28,31 +28,37 @@ This is the visual overview. For detailed documentation, see: ## Business Objectives {{#each objectives}} + ### Objective {{@index + 1}}: {{this.statement}} + - **Metric:** {{this.metric}} - **Target:** {{this.target}} - **Timeline:** {{this.timeline}} -{{/each}} + {{/each}} --- ## Target Groups (Prioritized) {{#each prioritized_groups}} + ### {{@index + 1}}. {{this.name}} + **Priority Reasoning:** {{this.reasoning}} > {{this.persona_summary}} **Key Positive Drivers:** {{#each this.positive_drivers}} + - {{this}} -{{/each}} + {{/each}} **Key Negative Drivers:** {{#each this.negative_drivers}} + - {{this}} -{{/each}} + {{/each}} {{/each}} @@ -94,26 +100,32 @@ This is the visual overview. For detailed documentation, see: **Must Address:** {{#each must_address_drivers}} + - {{this}} -{{/each}} + {{/each}} **Should Address:** {{#each should_address_drivers}} + - {{this}} -{{/each}} + {{/each}} --- ## Cross-Group Patterns ### Shared Drivers + {{shared_drivers}} ### Unique Drivers + {{unique_drivers}} {{#if conflicts}} + ### Potential Tensions + {{conflicts}} {{/if}} @@ -131,6 +143,5 @@ This Trigger Map Poster provides a quick reference. For detailed work: --- -*Generated by Whiteport Design Studio* -*Trigger Mapping methodology credits: Effect Mapping by Mijo Balic & Ingrid Domingues (inUse), adapted with negative driving forces by WDS* - +_Generated by Whiteport Design Studio_ +_Trigger Mapping methodology credits: Effect Mapping by Mijo Balic & Ingrid Domingues (inUse), adapted with negative driving forces by WDS_ diff --git a/src/modules/wds/workflows/2-trigger-mapping/workflow.yaml b/src/modules/wds/workflows/2-trigger-mapping/workflow.yaml index d425f203..16af643d 100644 --- a/src/modules/wds/workflows/2-trigger-mapping/workflow.yaml +++ b/src/modules/wds/workflows/2-trigger-mapping/workflow.yaml @@ -55,4 +55,3 @@ primary_agent: "saga-analyst" standalone: true web_bundle: false - diff --git a/src/modules/wds/workflows/2-trigger-mapping/workshops/1-business-goals/instructions.md b/src/modules/wds/workflows/2-trigger-mapping/workshops/1-business-goals/instructions.md index 49606bca..a574d11a 100644 --- a/src/modules/wds/workflows/2-trigger-mapping/workshops/1-business-goals/instructions.md +++ b/src/modules/wds/workflows/2-trigger-mapping/workshops/1-business-goals/instructions.md @@ -8,6 +8,7 @@ **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. Think big. If everything goes perfectly, what position do you want to hold? Examples: + - "Be the most trusted platform for dog owners in Sweden" - "The go-to tool for indie designers" - "Make project management actually enjoyable" @@ -39,6 +41,7 @@ Examples: **How would you measure progress toward this vision?** Think about: + - User metrics (adoption, engagement, retention) - Business metrics (revenue, growth, market share) - Quality metrics (satisfaction, referrals, reviews) @@ -46,12 +49,13 @@ Think about: What numbers would make you confident you're on track? For each metric mentioned, help make it SMART: + - **S**pecific - What exactly? - **M**easurable - What number? - **A**chievable - Is this realistic? - **R**elevant - Does this connect to the vision? - **T**ime-bound - By when? - + Aim for 3-5 clear objectives @@ -62,6 +66,7 @@ What numbers would make you confident you're on track? For each objective, walk through: Example transformation: + - Vague: "Get influential users" - SMART: "Onboard 10 verified dog trainers with 1000+ followers by Q4 2026" @@ -71,10 +76,11 @@ Present each refined objective for confirmation. {{#each objectives}} **Objective {{@index + 1}}:** {{this.statement}} + - Metric: {{this.metric}} - Target: {{this.target}} - Timeline: {{this.timeline}} -{{/each}} + {{/each}} Do these capture what success looks like? Any adjustments? @@ -98,4 +104,3 @@ This gives us clear targets to work toward. Next, we'll identify who can help yo - diff --git a/src/modules/wds/workflows/2-trigger-mapping/workshops/2-target-groups/instructions.md b/src/modules/wds/workflows/2-trigger-mapping/workshops/2-target-groups/instructions.md index 330a2ad9..4d3ec3de 100644 --- a/src/modules/wds/workflows/2-trigger-mapping/workshops/2-target-groups/instructions.md +++ b/src/modules/wds/workflows/2-trigger-mapping/workshops/2-target-groups/instructions.md @@ -10,10 +10,11 @@ Now we identify the people who matter most to achieving your goals. We'll create: + - A list of user groups - Rich descriptions (personas) - Understanding of their context - + Looking at your objectives: @@ -47,6 +48,7 @@ List the types of people that come to mind. **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? @@ -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. @@ -101,4 +104,3 @@ These are the people we're designing for. Next, we'll explore what drives them - - diff --git a/src/modules/wds/workflows/2-trigger-mapping/workshops/3-driving-forces/instructions.md b/src/modules/wds/workflows/2-trigger-mapping/workshops/3-driving-forces/instructions.md index 387efa9e..d53edf8a 100644 --- a/src/modules/wds/workflows/2-trigger-mapping/workshops/3-driving-forces/instructions.md +++ b/src/modules/wds/workflows/2-trigger-mapping/workshops/3-driving-forces/instructions.md @@ -19,12 +19,14 @@ Understanding both is crucial. Research shows people work harder to avoid pain t 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. What does {{persona.name}} want to achieve or experience? Think about: + - What would make their day better? - What would they brag about to colleagues? - What would make them feel successful? @@ -52,6 +55,7 @@ Think about: What does {{persona.name}} want to avoid or escape? Think about: + - What keeps them up at night? - What frustrations are they tired of? - What risks worry them? @@ -63,13 +67,15 @@ Think about: ✅ **Positive Drivers:** {{#each positive_drivers}} + - {{this}} -{{/each}} + {{/each}} ⚠️ **Negative Drivers:** {{#each negative_drivers}} + - {{this}} -{{/each}} + {{/each}} Does this capture what truly motivates {{persona.name}}? Anything to add? @@ -82,10 +88,11 @@ Think about: Looking across all personas, I notice some patterns... Analyze for: + - Common drivers across groups - Unique drivers per group - Potential conflicts between groups - + **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. @@ -120,4 +128,3 @@ This is powerful insight. Next, we'll prioritize which groups and drivers to foc - diff --git a/src/modules/wds/workflows/2-trigger-mapping/workshops/4-prioritization/instructions.md b/src/modules/wds/workflows/2-trigger-mapping/workshops/4-prioritization/instructions.md index 7f38cd78..bd1d5094 100644 --- a/src/modules/wds/workflows/2-trigger-mapping/workshops/4-prioritization/instructions.md +++ b/src/modules/wds/workflows/2-trigger-mapping/workshops/4-prioritization/instructions.md @@ -8,6 +8,7 @@ **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}} + {{/each}} **Which business goal is most critical right now?** @@ -44,7 +46,7 @@ Help me understand your reasoning. What makes this the priority? **Your Business Goal Priority:** {{#each prioritized_visions}} {{@index + 1}}. **{{this.vision}}** - *Why:* {{this.reasoning}} +_Why:_ {{this.reasoning}} {{/each}} prioritized_visions @@ -56,8 +58,9 @@ Help me understand your reasoning. What makes this the priority? For "{{top_vision}}", you have these objectives: {{#each top_vision_objectives}} + - {{this.statement}} -{{/each}} + {{/each}} **Which objective is most important to achieve first?** @@ -74,7 +77,7 @@ What's your reasoning? **Objective Priority for "{{top_vision}}":** {{#each prioritized_objectives}} {{@index + 1}}. {{this.statement}} - *Why:* {{this.reasoning}} +_Why:_ {{this.reasoning}} {{/each}} prioritized_objectives @@ -85,8 +88,9 @@ What's your reasoning? Your target groups: {{#each personas}} + - {{this.name}} -{{/each}} + {{/each}} Looking at your top objective: "{{top_objective}}" @@ -105,7 +109,7 @@ What's the logic? **Your Target Group Priority:** {{#each prioritized_groups}} {{@index + 1}}. **{{this.name}}** - *Why:* {{this.reasoning}} +_Why:_ {{this.reasoning}} {{/each}} The top group gets most design attention. Does this ranking reflect your strategy? @@ -123,13 +127,15 @@ What's the logic? Their drivers: ✅ Positive: {{#each current_group.positive_drivers}} + - {{this}} -{{/each}} + {{/each}} ⚠️ Negative: {{#each current_group.negative_drivers}} + - {{this}} -{{/each}} + {{/each}} **Rank the top 3-5 drivers** this group cares most about. @@ -158,18 +164,21 @@ Remember: negative drivers often have more weight (loss aversion). **Must Address:** {{#each must_address_drivers}} + - {{this}} -{{/each}} + {{/each}} **Should Address:** {{#each should_address_drivers}} + - {{this}} -{{/each}} + {{/each}} **Could Address (if time permits):** {{#each could_address_drivers}} + - {{this}} -{{/each}} + {{/each}} Does this focus feel right? This guides all feature decisions. @@ -180,6 +189,7 @@ Remember: negative drivers often have more weight (loss aversion). **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. - diff --git a/src/modules/wds/workflows/2-trigger-mapping/workshops/5-feature-impact/instructions.md b/src/modules/wds/workflows/2-trigger-mapping/workshops/5-feature-impact/instructions.md index 1283aa9b..aa700f2d 100644 --- a/src/modules/wds/workflows/2-trigger-mapping/workshops/5-feature-impact/instructions.md +++ b/src/modules/wds/workflows/2-trigger-mapping/workshops/5-feature-impact/instructions.md @@ -12,11 +12,13 @@ Now we create a **Design Brief** - strategic guidance for the designer on which features matter most and to whom. For each feature, we'll assess impact on each persona using a simple scale: + - **High** = Addresses major need or fear - **Medium** = Helpful but not critical - **Low** = Minimal impact This creates a scored, prioritized feature list that guides: + - **Phase 4: UX Design** - Which scenarios to design first - **Phase 6: PRD/Development** - Epic and story prioritization @@ -43,6 +45,7 @@ Skip foundational features (auth, profiles, basic CRUD). 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? Record response Calculate score: + - Primary: High=5, Medium=3, Low=1 - Others: High=3, Medium=1, Low=0 - + ✓ **{{current_feature}}** — Score: {{calculated_score}} @@ -89,17 +93,19 @@ How does this impact each persona? Sort features by score (high to low) Calculate dynamic thresholds based on persona count: + - max_possible = 5 (primary high) + 3 × (other_persona_count) - must_have_threshold = Features with Primary High (5) OR score ≥ (max_possible - 3) - consider_threshold = mid-range scores - defer_threshold = low scores - + Apply decisions: + - **Must Have:** Primary scored High (5 pts) OR score in top tier - **Consider:** Medium-range scores, might serve strategic needs - **Defer:** Low scores, minimal strategic value - + **Scoring complete!** Here's your prioritized feature list: @@ -108,6 +114,7 @@ How does this impact each persona? {{/each}} **Scoring context:** + - Max possible score with {{persona_count}} personas: {{max_possible}} - Top tier (Must Have): {{must_have_threshold}}+ - Primary critical (Must Have): Features with Primary High (5) @@ -131,6 +138,7 @@ Do NOT include analysis section - keep it clean. **Saved to:** `B-Trigger-Map/00-feature-impact-analysis.md` This is your **Design Brief** - it tells the designer: + - **What to design first** - Top-scoring features = priority scenarios - **Prominence in UI** - High scores = prominent placement - **Who to optimize for** - Which persona's needs matter most @@ -138,6 +146,7 @@ This is your **Design Brief** - it tells the designer: **Trigger Mapping Complete!** 🎉 You now have: + - Clear business priorities - Defined target personas with drivers - Strategically ranked features diff --git a/src/modules/wds/workflows/3-prd-platform/instructions.md b/src/modules/wds/workflows/3-prd-platform/instructions.md index d41a3fbe..e7e72c52 100644 --- a/src/modules/wds/workflows/3-prd-platform/instructions.md +++ b/src/modules/wds/workflows/3-prd-platform/instructions.md @@ -50,11 +50,13 @@ Before starting, ensure you have: **Freyja's Role:** Greet the user and explain this phase: + - "We're establishing your technical foundation—proving that innovative features work before investing in design." - "We'll make platform decisions, validate risky features with PoCs, and set up experimental endpoints." - "This enables backend development to start in parallel with UX design." Review available context: + - Read the Product Brief to understand project scope and constraints - Read the Feature Impact Analysis to identify high-priority features - Ask: "Do you already have any technical constraints or platform preferences?" @@ -206,7 +208,7 @@ Ask systematically: Read the Product Brief and identify relevant integration categories based on features mentioned: - **Payment Processing:** Transactions, subscriptions, e-commerce, paid features, pricing -- **Communication:** User notifications, emails, SMS, alerts, reminders +- **Communication:** User notifications, emails, SMS, alerts, reminders - **Maps/Location:** Geographic features, addresses, directions, proximity, location-based services - **Search:** Large content volumes, filtering, discovery features - **Calendar/Scheduling:** Bookings, appointments, events, availability @@ -230,6 +232,7 @@ Read the Product Brief and identify relevant integration categories based on fea **Go through each relevant category systematically:** **3A: Authentication & Identity** + - "How will users authenticate?" (OAuth, email/password, SSO, passwordless) - "Which providers?" (Google, Microsoft, Auth0, etc.) - **Document for each:** @@ -240,6 +243,7 @@ Read the Product Brief and identify relevant integration categories based on fea - Technical risk (high/medium/low) **3B: Payment Processing** (if applicable) + - "Do you need payment processing?" - "Which payment providers?" (Stripe, PayPal, Klarna, Swish, regional systems) - "What payment methods?" (credit cards, bank transfers, mobile payments, digital wallets) @@ -262,6 +266,7 @@ Read the Product Brief and identify relevant integration categories based on fea - Technical risk level **3C: Communication Services** + - "Do you need to send emails?" → Which service? (SendGrid, Mailgun, AWS SES, Postmark) - "Do you need SMS?" → Which service? (Twilio, MessageBird, Vonage) - "Push notifications?" → Which service? (Firebase Cloud Messaging, OneSignal, Pusher) @@ -279,6 +284,7 @@ Read the Product Brief and identify relevant integration categories based on fea - Priority & cost **3D: Search Services** (if applicable) + - "Do you need advanced search functionality?" - "Which service?" (Algolia, Elasticsearch, Typesense, Meilisearch) - **Document for each:** @@ -295,6 +301,7 @@ Read the Product Brief and identify relevant integration categories based on fea - Priority & cost **3E: Maps & Location** (if applicable) + - "Do you need maps or geolocation?" - "Which service?" (Google Maps, Mapbox, OpenStreetMap, Here) - **Document for each:** @@ -313,6 +320,7 @@ Read the Product Brief and identify relevant integration categories based on fea - Priority & risk level **3F: Data & Analytics** + - "What analytics do you need?" (Google Analytics, Mixpanel, Amplitude, custom) - "Error tracking?" (Sentry, Rollbar, Bugsnag) - "Application monitoring?" (New Relic, Datadog, AppDynamics) @@ -329,6 +337,7 @@ Read the Product Brief and identify relevant integration categories based on fea - Priority & cost **3G: Storage & Media** + - "Do you need file/image storage?" (S3, Azure Blob, Google Cloud Storage, Cloudinary) - "CDN for assets?" (CloudFlare, Fastly, AWS CloudFront) - "Video hosting/streaming?" (Vimeo, YouTube, Mux, AWS Media Services) @@ -346,6 +355,7 @@ Read the Product Brief and identify relevant integration categories based on fea - Priority & cost **3H: Calendar & Scheduling** (if applicable) + - "Do you need calendar integrations?" - "Which services?" (Google Calendar, Outlook/Microsoft 365, iCal) - "Scheduling/booking systems?" (Calendly-style booking) @@ -360,6 +370,7 @@ Read the Product Brief and identify relevant integration categories based on fea - Priority & cost **3I: Social Media & Content** (if applicable) + - "Do you need social media integrations?" - "Which platforms?" (Facebook, Twitter/X, LinkedIn, Instagram) - "Social login?" (covered in 3A, but cross-reference) @@ -374,6 +385,7 @@ Read the Product Brief and identify relevant integration categories based on fea - Priority & cost **3J: Customer Support & Help** (if applicable) + - "Do you need customer support tools?" - "Which services?" (Intercom, Zendesk, Helpscout, Crisp) - "Live chat?" (service or custom) @@ -388,6 +400,7 @@ Read the Product Brief and identify relevant integration categories based on fea - Priority & cost **3K: Marketing & Growth** (if applicable) + - "Do you need marketing automation?" - "Which services?" (Mailchimp, HubSpot, ActiveCampaign) - "A/B testing?" (Optimizely, VWO, custom) @@ -402,6 +415,7 @@ Read the Product Brief and identify relevant integration categories based on fea - Priority & cost **3L: Domain-Specific APIs** + - "Any other APIs specific to your domain?" (industry-specific services) - Examples: Weather APIs, financial data, shipping/logistics, government data, industry databases - **Document for each:** @@ -425,18 +439,21 @@ Read the Product Brief and identify relevant integration categories based on fea **Goal:** Determine which features need Proofs of Concept (PoCs). Review the Feature Impact Analysis and ask: + - **Which features are innovative or unproven?** - **Which features depend on external APIs that might have limitations?** - **Which features have unknown performance characteristics?** - **Which features might not be technically feasible?** **Red Flags That Suggest PoC Needed:** + - "Can we actually get X data from Y service?" - "Will this perform fast enough?" - "Does this API return data in a usable format?" - "Can we achieve real-time updates at scale?" Create a list of features requiring validation, prioritized by: + 1. **High Feature Impact Score** (from Phase 2) + **High Technical Risk** 2. **Medium Feature Impact** + **High Technical Risk** 3. **High Feature Impact** + **Medium Technical Risk** @@ -469,6 +486,7 @@ For each feature identified in Step 4: **Output:** Create `02-Technical-Proofs-Of-Concept.md` documenting all PoC work. **Positive Framing:** + - When features work: "Great! This proves [feature] is technically sound. Design can proceed with confidence." - When features have limitations: "Valuable discovery! We found [limitation] early. This helps design account for it from the start." - When features don't work: "Important learning! This saves weeks of design work on an infeasible feature. Let's explore alternatives." @@ -618,6 +636,7 @@ Ask systematically about all regulatory requirements: "Let's start with authentication. Based on our security framework, what auth endpoints do you need?" For each endpoint: + - Method & Path (e.g., `POST /api/auth/login`) - Purpose & business value - Request/response format with detailed schemas @@ -636,6 +655,7 @@ Common auth endpoints: login, logout, token refresh, password reset, email verif Go through each entity from the data model systematically: For each entity, define all CRUD operations: + - `GET /api/{entity}` - List with pagination - `GET /api/{entity}/:id` - Get single item - `POST /api/{entity}` - Create new @@ -643,17 +663,19 @@ For each entity, define all CRUD operations: - `DELETE /api/{entity}/:id` - Delete item **Business Rules for each:** - - Validation rules (required fields, formats, constraints) - - Authorization (who can perform this operation?) - - Pagination parameters (page size, sorting, filtering) - - Related data inclusion (nested objects, joins) - - Business logic constraints + +- Validation rules (required fields, formats, constraints) +- Authorization (who can perform this operation?) +- Pagination parameters (page size, sorting, filtering) +- Related data inclusion (nested objects, joins) +- Business logic constraints **7C: External Integration APIs** "Which external services need API endpoints? Let's create wrappers for each." For each external service from Step 3: + - Method & Path - Purpose ("Wraps Google Maps API to get walking time") - Request/response format @@ -672,6 +694,7 @@ For each external service from Step 3: Examples: availability checks, pricing, recommendations, aggregations For each: + - Method & Path - Purpose & business value - Request/response format @@ -705,6 +728,7 @@ For each: "We identified your core entities earlier. Now let's document the complete data model." For each entity: + - Entity name & purpose - All fields with types, constraints, defaults - Relationships to other entities (one-to-many, many-to-many) @@ -723,6 +747,7 @@ Create entity relationship diagram (ERD) showing all connections. "What are your performance and scalability expectations?" Document systematically: + - **Response Times:** Expected latency for each API category - **Throughput:** Concurrent users, requests per second - **Data Volume:** Expected record counts, storage needs @@ -732,6 +757,7 @@ Document systematically: **Ask:** "Any other data modeling or performance considerations we should capture?" **Outputs:** + - `05-Data-Models.md` - Complete schemas and ERD - `06-Performance-Requirements.md` - Benchmarks and scalability specs @@ -746,6 +772,7 @@ Document systematically: "This document tells the UX team what they need to know about technical possibilities and limitations." **Include:** + - **What's Possible:** Validated features from PoCs, platform capabilities - **What Has Limitations:** Technical constraints, API limits, performance characteristics - **What Affects Design:** Loading states, offline behavior, real-time vs. polling @@ -756,6 +783,7 @@ Document systematically: "How do we know when each platform component is 'done'?" For each major platform area (auth, integrations, security, etc.): + - **Functional Criteria:** What must work? - **Performance Criteria:** How fast/scalable must it be? - **Security Criteria:** What security standards must be met? @@ -764,6 +792,7 @@ For each major platform area (auth, integrations, security, etc.): **Ask:** "Any other constraints or success criteria we should document?" **Outputs:** + - `07-Technical-Constraints.md` - UX design handoff - `08-Acceptance-Criteria.md` - Testable success definitions @@ -782,6 +811,7 @@ For each major platform area (auth, integrations, security, etc.): "Let's look at your high-priority features from Phase 2..." Read the Feature Impact Analysis (B-Trigger-Map/03-Feature-Impact-Analysis.md) and identify: + - **Must Have features** (high scores, high for primary persona) - **Consider for MVP features** (balanced scores) - **Platform dependencies** - What platform work is needed to enable each high-impact feature? @@ -832,21 +862,19 @@ For each recommended epic, note which high-priority features it enables: "Here's the order I'd recommend, based on Feature Impact Analysis:" **Priority 1: Enable Must-Have Features** + 1. **Foundation First:** Core infrastructure (hosting, database, basic security) 2. **High-Impact Dependencies:** Platform work needed for Must-Have features - [Epic] enables [Feature] (Score: X) for [Primary Persona] - [Epic] enables [Feature] (Score: Y) for [Primary Persona] -**Priority 2: Risk Mitigation** -3. **Complex Integrations:** External APIs that are risky or complex (fail fast) - - [Integration Epic] enables [Feature] (Score: X) +**Priority 2: Risk Mitigation** 3. **Complex Integrations:** External APIs that are risky or complex (fail fast) -**Priority 3: Secondary Features** -4. **Remaining Integrations:** Other external services -5. **Advanced Features:** Performance optimization, advanced security +- [Integration Epic] enables [Feature] (Score: X) -**Priority 4: Operations** -6. **Monitoring & Tools:** Logging, analytics, maintenance tools +**Priority 3: Secondary Features** 4. **Remaining Integrations:** Other external services 5. **Advanced Features:** Performance optimization, advanced security + +**Priority 4: Operations** 6. **Monitoring & Tools:** Logging, analytics, maintenance tools **10D: Feature-to-Epic Mapping** @@ -862,12 +890,14 @@ Create a table: **10E: API Contracts for Future UI Development** "These API specifications are ready for frontend development:" + - [List key API categories organized by priority features they enable] - Backend can implement these in parallel with Phase 4 (UX Design) **10F: Dependencies & Parallel Work** "Key dependencies to consider:" + - What must be done before high-impact features can be built? - What can be developed independently in parallel? - What provides the most risk reduction AND feature enablement if done early? @@ -875,6 +905,7 @@ Create a table: **Ask:** "Does this platform work organization make sense based on your feature priorities? Any initiatives or priorities you'd adjust?" **Output:** Create `09-Platform-Backlog-Recommendations.md` with: + - **Feature Impact Summary** - High-priority features from Phase 2 - **Feature-to-Epic Mapping** - Clear connections between features and platform work - Recommended initiative structure @@ -901,8 +932,8 @@ Create a table: ```markdown # Product Requirements Document: [Project Name] -*Phase 3 Complete: Technical Foundation Established* -*Last Updated: [Date]* +_Phase 3 Complete: Technical Foundation Established_ +_Last Updated: [Date]_ --- @@ -916,30 +947,39 @@ Create a table: ## 2. Technical Foundation (Phase 3) ### 2.1 Platform Architecture + [Link to C-Requirements/00-Platform-Architecture.md] ### 2.2 External Integrations + [Link to C-Requirements/01-Integration-Map.md] ### 2.3 Technical Validation + [Link to C-Requirements/02-Technical-Proofs-Of-Concept.md] ### 2.4 Security & Compliance + [Link to C-Requirements/03-Security-Framework.md] ### 2.5 API Specifications + [Link to C-Requirements/04-API-Specifications.md] ### 2.6 Data Models + [Link to C-Requirements/05-Data-Models.md] ### 2.7 Performance Requirements + [Link to C-Requirements/06-Performance-Requirements.md] ### 2.8 Technical Constraints + [Link to C-Requirements/07-Technical-Constraints.md] ### 2.9 Acceptance Criteria + [Link to C-Requirements/08-Acceptance-Criteria.md] --- @@ -949,6 +989,7 @@ Create a table: [Link to C-Requirements/09-Platform-Backlog-Recommendations.md] **Summary:** + - **Recommended Initiatives:** [List] - **Suggested Epics:** [Count] - **API Contracts Ready:** [Key APIs] @@ -958,24 +999,28 @@ Create a table: ## 4. Functional Requirements (Phase 4) -*This section will be populated during Phase 4 (UX Design) as each page/scenario is completed.* +_This section will be populated during Phase 4 (UX Design) as each page/scenario is completed._ ### [Feature Area 1] -*Coming from Phase 4* + +_Coming from Phase 4_ ### [Feature Area 2] -*Coming from Phase 4* + +_Coming from Phase 4_ --- ## 5. Next Steps **For BMM Agents:** + - Use platform backlog recommendations to create E-Backlog/ structure - Create detailed epics and stories from requirements documents - Establish implementation roadmap with dependencies **For Phase 4 (UX Design):** + - Technical constraints document provides design boundaries - API specifications define data available to UI - Begin UX design with confidence in technical feasibility @@ -1033,6 +1078,7 @@ Create a table: 7. **"Anything about performance, scalability, or deployment we should capture?"** **If user identifies gaps:** + - Document the additional items in the appropriate files - "Great catch! Let me add that to [relevant document]..." - After adding, return to completeness check @@ -1062,6 +1108,7 @@ Create a table: - Each completed page will add functional requirements to the PRD **What happens next:** + - Platform backlog recommendations guide BMM agents in creating E-Backlog/ - Development teams can begin platform work based on requirements - Phase 4 (UX Design) can begin, informed by technical constraints @@ -1075,22 +1122,27 @@ Create a table: ### For Freyja the PM: **Validate Early, Often:** + - Don't let risky features proceed without PoC validation - "Let's prove this works before investing in design" **Positive Language:** + - Frame discoveries as valuable, not failures - "Great that we learned this now, not after design is complete" **Stay Connected to Strategy:** + - Reference Feature Impact Analysis scores when prioritizing PoCs - High-impact features deserve thorough validation **Enable Parallel Work:** + - Think about what backend teams can start building immediately - Experimental endpoints should focus on clear, achievable tasks **Document for Design:** + - Technical Constraints doc is crucial for Phase 4 success - Be specific about what design needs to accommodate @@ -1106,5 +1158,4 @@ Use these templates to structure outputs: --- -*Phase 3 workflow for Whiteport Design Studio (WDS) methodology* - +_Phase 3 workflow for Whiteport Design Studio (WDS) methodology_ diff --git a/src/modules/wds/workflows/3-prd-platform/templates/experimental-endpoints.template.md b/src/modules/wds/workflows/3-prd-platform/templates/experimental-endpoints.template.md index 6e8fbd06..3354d107 100644 --- a/src/modules/wds/workflows/3-prd-platform/templates/experimental-endpoints.template.md +++ b/src/modules/wds/workflows/3-prd-platform/templates/experimental-endpoints.template.md @@ -9,6 +9,7 @@ ## Purpose These are early API specifications for endpoints we know we'll need. Setting them up now enables: + - Early backend development (parallel with UX design) - Validation that our data model works - Fail-fast discovery of integration issues @@ -27,17 +28,20 @@ These are early API specifications for endpoints we know we'll need. Setting the ## Authentication Endpoints {{#each auth_endpoints}} + ### {{this.method}} {{this.path}} **Status:** {{this.status}} **Purpose:** {{this.purpose}} **Request:** + ```json {{this.request_example}} ``` **Response:** + ```json {{this.response_example}} ``` @@ -45,11 +49,13 @@ These are early API specifications for endpoints we know we'll need. Setting the **Notes:** {{this.notes}} --- + {{/each}} ## Core CRUD Operations {{#each crud_endpoints}} + ### {{this.method}} {{this.path}} **Status:** {{this.status}} @@ -57,11 +63,13 @@ These are early API specifications for endpoints we know we'll need. Setting the **Entity:** {{this.entity}} **Request:** + ```json {{this.request_example}} ``` **Response:** + ```json {{this.response_example}} ``` @@ -70,11 +78,13 @@ These are early API specifications for endpoints we know we'll need. Setting the **Notes:** {{this.notes}} --- + {{/each}} ## External Integration Endpoints {{#each integration_endpoints}} + ### {{this.method}} {{this.path}} **Status:** {{this.status}} @@ -82,53 +92,62 @@ These are early API specifications for endpoints we know we'll need. Setting the **External Service:** {{this.external_service}} **Request:** + ```json {{this.request_example}} ``` **Response:** + ```json {{this.response_example}} ``` **Validates:** + - {{#each this.validates}} - {{this}} -{{/each}} + {{/each}} **Cost per Call:** {{this.cost_per_call}} **Rate Limits:** {{this.rate_limits}} **Notes:** {{this.notes}} --- + {{/each}} ## Business Logic Endpoints {{#each logic_endpoints}} + ### {{this.method}} {{this.path}} **Status:** {{this.status}} **Purpose:** {{this.purpose}} **Request:** + ```json {{this.request_example}} ``` **Response:** + ```json {{this.response_example}} ``` **Business Rules:** {{#each this.business_rules}} + - {{this}} -{{/each}} + {{/each}} **Notes:** {{this.notes}} --- + {{/each}} ## Error Handling @@ -149,27 +168,32 @@ These are early API specifications for endpoints we know we'll need. Setting the ### Common Error Codes {{#each error_codes}} + - **{{this.code}}** ({{this.http_status}}): {{this.description}} -{{/each}} + {{/each}} --- ## API Conventions ### Base URL + ``` {{api_base_url}} ``` ### Authentication + {{api_authentication_method}} ### Request Headers + ``` {{api_request_headers}} ``` ### Response Format + {{api_response_format}} --- @@ -179,8 +203,9 @@ These are early API specifications for endpoints we know we'll need. Setting the These endpoints are also tracked in `E-PRD-Finalization/` as handoff tasks: {{#each development_tasks}} + - [ ] **{{this.endpoint}}** - {{this.description}} (Priority: {{this.priority}}) -{{/each}} + {{/each}} --- @@ -193,5 +218,4 @@ These endpoints are also tracked in `E-PRD-Finalization/` as handoff tasks: --- -*Phase 3 artifact for {{project_name}}* - +_Phase 3 artifact for {{project_name}}_ diff --git a/src/modules/wds/workflows/3-prd-platform/templates/platform-architecture.template.md b/src/modules/wds/workflows/3-prd-platform/templates/platform-architecture.template.md index 77d6c74e..2f0ba725 100644 --- a/src/modules/wds/workflows/3-prd-platform/templates/platform-architecture.template.md +++ b/src/modules/wds/workflows/3-prd-platform/templates/platform-architecture.template.md @@ -9,24 +9,28 @@ ## Technology Stack ### Backend + - **Framework/Language:** {{backend_framework}} - **Runtime:** {{backend_runtime}} - **Rationale:** {{backend_rationale}} ### Frontend + - **Framework:** {{frontend_framework}} - **UI Library:** {{ui_library}} - **Rationale:** {{frontend_rationale}} ### Database + - **Primary Database:** {{primary_database}} - **Type:** {{database_type}} - **Rationale:** {{database_rationale}} {{#if secondary_database}} + - **Secondary Database:** {{secondary_database}} - **Purpose:** {{secondary_purpose}} -{{/if}} + {{/if}} --- @@ -35,36 +39,42 @@ **Approach:** {{architecture_style}} {{#if architecture_style == "Monolith"}} + - Single codebase deployment - Simplified development and deployment - {{monolith_rationale}} -{{/if}} + {{/if}} {{#if architecture_style == "Microservices"}} + - Service boundaries: {{service_boundaries}} - Communication: {{service_communication}} - {{microservices_rationale}} -{{/if}} + {{/if}} {{#if architecture_style == "Serverless"}} + - Functions: {{serverless_functions}} - Triggers: {{serverless_triggers}} - {{serverless_rationale}} -{{/if}} + {{/if}} --- ## Infrastructure & Hosting ### Platform + - **Cloud Provider:** {{cloud_provider}} - **Hosting Type:** {{hosting_type}} - **Rationale:** {{infrastructure_rationale}} ### Services + {{#each infrastructure_services}} + - **{{this.name}}:** {{this.description}} -{{/each}} + {{/each}} --- @@ -73,19 +83,22 @@ ### Core Entities {{#each core_entities}} + #### {{this.name}} **Purpose:** {{this.purpose}} **Key Fields:** {{#each this.fields}} + - `{{this.name}}` ({{this.type}}) - {{this.description}} -{{/each}} + {{/each}} **Relationships:** {{#each this.relationships}} + - {{this.type}} {{this.target}} - {{this.description}} -{{/each}} + {{/each}} {{/each}} @@ -124,8 +137,9 @@ ## Technical Constraints {{#each technical_constraints}} + - **{{this.area}}:** {{this.constraint}} -{{/each}} + {{/each}} --- @@ -134,12 +148,12 @@ ### Monthly Operating Costs (Estimated) {{#each cost_estimates}} + - **{{this.service}}:** {{this.cost}} {{this.currency}} -{{/each}} + {{/each}} **Total Estimated:** {{total_monthly_cost}} {{currency}}/month --- -*Phase 3 artifact for {{project_name}}* - +_Phase 3 artifact for {{project_name}}_ diff --git a/src/modules/wds/workflows/3-prd-platform/templates/technical-constraints.template.md b/src/modules/wds/workflows/3-prd-platform/templates/technical-constraints.template.md index c25ea1e3..e9af1e83 100644 --- a/src/modules/wds/workflows/3-prd-platform/templates/technical-constraints.template.md +++ b/src/modules/wds/workflows/3-prd-platform/templates/technical-constraints.template.md @@ -18,6 +18,7 @@ This document summarizes technical decisions and constraints that inform UX desi ### Validated Features {{#each validated_features}} + #### {{this.feature_name}} **Status:** {{this.status}} @@ -29,8 +30,9 @@ This document summarizes technical decisions and constraints that inform UX desi ### Platform Capabilities {{#each platform_capabilities}} + - **{{this.capability}}:** {{this.description}} -{{/each}} + {{/each}} --- @@ -39,6 +41,7 @@ This document summarizes technical decisions and constraints that inform UX desi ### Technical Limitations {{#each limitations}} + #### {{this.area}} **Constraint:** {{this.constraint}} @@ -50,8 +53,9 @@ This document summarizes technical decisions and constraints that inform UX desi ### External API Constraints {{#each api_constraints}} + - **{{this.service}}:** {{this.constraint}} - {{this.design_impact}} -{{/each}} + {{/each}} --- @@ -60,6 +64,7 @@ This document summarizes technical decisions and constraints that inform UX desi ### Performance Characteristics {{#each performance_characteristics}} + #### {{this.operation}} - **Expected Time:** {{this.time}} @@ -71,8 +76,9 @@ This document summarizes technical decisions and constraints that inform UX desi ### Connection Requirements {{#each connection_requirements}} + - **{{this.feature}}:** {{this.requirement}} - {{this.design_impact}} -{{/each}} + {{/each}} --- @@ -81,6 +87,7 @@ This document summarizes technical decisions and constraints that inform UX desi ### Cost-Sensitive Features {{#each expensive_features}} + #### {{this.feature}} **Cost Driver:** {{this.cost_driver}} @@ -94,12 +101,15 @@ This document summarizes technical decisions and constraints that inform UX desi ## 🌐 Platform Compatibility ### Browser Support + {{browser_support}} ### Device Support + {{device_support}} ### Accessibility + {{accessibility_considerations}} --- @@ -107,12 +117,15 @@ This document summarizes technical decisions and constraints that inform UX desi ## 🔒 Security Constraints ### Authentication + {{authentication_constraints}} ### Data Handling + {{data_handling_constraints}} ### Compliance + {{compliance_constraints}} --- @@ -120,13 +133,17 @@ This document summarizes technical decisions and constraints that inform UX desi ## 📱 Offline Behavior {{#if offline_support}} + ### What Works Offline + {{offline_capabilities}} ### What Requires Connection + {{online_requirements}} ### Sync Strategy + {{sync_strategy}} {{else}} **Offline Mode:** Not supported - All features require active connection @@ -139,6 +156,7 @@ This document summarizes technical decisions and constraints that inform UX desi Based on technical validation: {{#each design_recommendations}} + ### {{this.category}} {{this.recommendation}} @@ -153,11 +171,12 @@ Based on technical validation: {{#if open_questions}} {{#each open_questions}} + - {{this}} -{{/each}} -{{else}} -No open questions at this time. -{{/if}} + {{/each}} + {{else}} + No open questions at this time. + {{/if}} --- @@ -169,5 +188,4 @@ No open questions at this time. --- -*Phase 3 → 4 Handoff Document for {{project_name}}* - +_Phase 3 → 4 Handoff Document for {{project_name}}_ diff --git a/src/modules/wds/workflows/3-prd-platform/workflow.yaml b/src/modules/wds/workflows/3-prd-platform/workflow.yaml index 5a7fee28..b1521778 100644 --- a/src/modules/wds/workflows/3-prd-platform/workflow.yaml +++ b/src/modules/wds/workflows/3-prd-platform/workflow.yaml @@ -3,7 +3,6 @@ name: PRD Platform Workflow description: Establish technical foundation, validate risky features, and set up experimental endpoints web_bundle: true --- - # WDS Phase 3: PRD Platform (Technical Foundation) name: "Phase 3: PRD Platform (Technical Foundation)" agent: "Freyja the PM" @@ -37,4 +36,3 @@ optional_inputs: - "Existing technical constraints" estimated_duration: "2-4 hours (plus PoC development time)" - diff --git a/src/modules/wds/workflows/4-ux-design/ARCHITECTURE.md b/src/modules/wds/workflows/4-ux-design/ARCHITECTURE.md index b13e8bf5..2ae026a2 100644 --- a/src/modules/wds/workflows/4-ux-design/ARCHITECTURE.md +++ b/src/modules/wds/workflows/4-ux-design/ARCHITECTURE.md @@ -81,13 +81,16 @@ ## Key Innovations ### 1. Step-File Architecture ✅ + - **Just-in-time loading** - Only current step in memory - **Sequential enforcement** - Steps load one at a time - **Clear progression** - 5 main steps → substeps → object-types - **State tracking** - Progress saved between sessions ### 2. Granular Specification (8 Micro-Steps) ✅ + Instead of one large 4C step, broke into focused substeps: + 1. **Page Basics** - Fundamentals 2. **Layout Sections** - Structure 3. **Components & Objects** - Systematic identification @@ -98,6 +101,7 @@ Instead of one large 4C step, broke into focused substeps: 8. **Generate Spec** - Compile document ### 3. Object-Type Routing System ✅ + - **21 specialized object-type files** (6 created, 15 to create) - **Each file has precise examples** for consistency - **Ensures uniform output** across all WDS projects @@ -105,6 +109,7 @@ Instead of one large 4C step, broke into focused substeps: ### 4. Intelligent Analysis (Trust-the-Agent) ✅✨ **Old Approach (Procedural):** + ``` What type of object is this? 1. Button @@ -114,6 +119,7 @@ What type of object is this? ``` **New Approach (Intelligent):** + ``` My interpretation: @@ -133,6 +139,7 @@ Does this match your intent? [Y/Clarify/No] ``` **Benefits:** + - ✅ Agent demonstrates intelligence - ✅ Context-aware interpretation - ✅ Natural conversation @@ -140,6 +147,7 @@ Does this match your intent? [Y/Clarify/No] - ✅ v6 "goal-based trust" philosophy ### 5. Systematic Sketch Analysis ✅ + - **Top-to-bottom, left-to-right** within sections - **Component reuse detection** across pages - **Section-by-section** organization @@ -222,21 +230,25 @@ Step 5: Next Steps ## Benefits for WDS Users **Consistency Across Projects:** + - Same object types documented the same way - Every WDS project produces uniform specs - Developers know what to expect **Agent Clarity:** + - Focused instructions prevent confusion - Clear routing eliminates ambiguity - Examples guide output format **User Experience:** + - Intelligent suggestions feel natural - Quick confirmations when agent is right - Systematic coverage ensures nothing missed **Maintainability:** + - Easy to add new object types - Each file independently improvable - Clear separation of concerns @@ -246,6 +258,7 @@ Step 5: Next Steps ## Status **✅ Complete:** + - Main workflow structure (5 steps) - All substeps (4A, 4B, 4C-01 through 4C-08, 4D, 4E) - Object-router with intelligent analysis @@ -253,11 +266,10 @@ Step 5: Next Steps - Templates **⏳ To Create:** + - 15 additional object-type files - Object-type files should follow same pattern with precise examples --- **This architecture ensures consistent, high-quality specifications across all WDS projects while making the agent experience intelligent and natural.** 🎨✨ - - diff --git a/src/modules/wds/workflows/4-ux-design/COMPONENT-FILE-STRUCTURE.md b/src/modules/wds/workflows/4-ux-design/COMPONENT-FILE-STRUCTURE.md index 1cc3efde..a4d1c951 100644 --- a/src/modules/wds/workflows/4-ux-design/COMPONENT-FILE-STRUCTURE.md +++ b/src/modules/wds/workflows/4-ux-design/COMPONENT-FILE-STRUCTURE.md @@ -49,6 +49,7 @@ project-root/ **Purpose:** Page-specific layout, component placement, and context **Contains:** + - Page metadata (URL, scenario, purpose) - Layout structure (sections, grid) - Component instances with page-specific config @@ -56,10 +57,12 @@ project-root/ - Navigation flow (entry/exit points) **Does NOT contain:** + - Component visual design (→ Components/) - Interactive logic (→ Features/) **Example:** `02-calendar-page.md` + ```markdown # 02-calendar-page @@ -69,10 +72,12 @@ project-root/ ## Layout Structure ### Header Section + - Component: `navigation-bar` (from Components/) - Position: Top, full-width ### Main Content + - Component: `calendar-widget` (from Components/) - Position: Center, 80% width - Configuration: @@ -82,6 +87,7 @@ project-root/ - Feature: `calendar-logic` (from Features/) ### Sidebar + - Component: `walk-scheduler` (from Components/) - Position: Right, 20% width - Feature: `walk-assignment` (from Features/) @@ -89,6 +95,7 @@ project-root/ ## Content **Page Title:** + - EN: "Family Dog Care Calendar" - SE: "Familjens Hundvårdskalender" ``` @@ -100,6 +107,7 @@ project-root/ **Purpose:** Visual design, states, variants, Figma specifications **Contains:** + - Component name and purpose - Visual specifications (colors, spacing, typography) - States (default, hover, active, disabled, loading, error) @@ -109,10 +117,12 @@ project-root/ - Accessibility requirements **Does NOT contain:** + - Business logic (→ Features/) - Page-specific placement (→ Pages/) **Example:** `calendar-widget.component.md` + ```markdown # Calendar Widget Component @@ -127,18 +137,21 @@ Displays a monthly calendar view with interactive date selection and event displ ## Visual Specifications ### Layout + - Grid: 7 columns (days) × 5-6 rows (weeks) - Cell size: 48px × 48px (desktop), 40px × 40px (mobile) - Gap: 4px between cells - Padding: 16px container padding ### Typography + - Month/Year header: Large Heading (24px Bold) - Day labels: Caption (12px Medium) - Date numbers: Body Text (16px Regular) - Event indicators: Caption (10px Regular) ### Colors + - Background: `--color-surface` - Cell default: `--color-surface-elevated` - Cell hover: `--color-surface-hover` @@ -149,33 +162,39 @@ Displays a monthly calendar view with interactive date selection and event displ ## States ### Default State + - All dates visible - Current month displayed - Today highlighted with accent color - No date selected ### Date Selected + - Selected date: Primary color background - Date number: White text - Border: 2px solid primary-dark ### Date Hover + - Background: Surface-hover color - Cursor: Pointer - Transition: 150ms ease ### Date Disabled (Past dates) + - Background: Surface-disabled - Text: Gray-400 - Cursor: Not-allowed - No hover effect ### Loading State + - Skeleton animation on date cells - Month/year header visible - Navigation disabled ### With Events + - Small dot indicator below date number - Dot color: Event category color - Max 3 dots visible per cell @@ -183,11 +202,13 @@ Displays a monthly calendar view with interactive date selection and event displ ## Variants ### Size Variants + - **Large:** 56px cells (desktop default) - **Medium:** 48px cells (tablet) - **Small:** 40px cells (mobile) ### View Variants + - **Month View:** Default, shows full month - **Week View:** Shows 7 days in row - **Day View:** Shows single day with hourly slots @@ -197,6 +218,7 @@ Displays a monthly calendar view with interactive date selection and event displ **Component Path:** `Design System > Widgets > Calendar` **Variants to Create:** + - Size: Large / Medium / Small - View: Month / Week / Day - State: Default / Selected / Disabled / Loading @@ -207,16 +229,19 @@ Displays a monthly calendar view with interactive date selection and event displ ## Responsive Behavior ### Mobile (< 768px) + - Use Small variant (40px cells) - Stack month navigation vertically - Reduce padding to 12px ### Tablet (768px - 1024px) + - Use Medium variant (48px cells) - Horizontal month navigation - Standard padding (16px) ### Desktop (> 1024px) + - Use Large variant (56px cells) - Full navigation controls - Increased padding (20px) @@ -227,12 +252,10 @@ Displays a monthly calendar view with interactive date selection and event displ - Arrow keys: Navigate between dates - Enter/Space: Select date - Tab: Move to month navigation - - **Screen Readers:** - ARIA label: "Calendar, {Month} {Year}" - Each date: "Select {Day}, {Date} {Month}" - Selected date: "Selected, {Day}, {Date} {Month}" - - **Focus Management:** - Visible focus ring on keyboard navigation - Focus trap within calendar when open @@ -250,6 +273,7 @@ Displays a monthly calendar view with interactive date selection and event displ **Purpose:** Interactive logic, business rules, data flow, state management **Contains:** + - Feature name and purpose - User interactions and system responses - Business rules and validation @@ -258,11 +282,13 @@ Displays a monthly calendar view with interactive date selection and event displ - Edge cases and error handling **Does NOT contain:** + - Visual design (→ Components/) - Page layout (→ Pages/) **Example:** `calendar-logic.feature.md` -```markdown + +````markdown # Calendar Logic Feature **Feature ID:** `calendar-logic` @@ -280,6 +306,7 @@ Manages calendar interactions, date selection, event display, and navigation bet **Trigger:** User clicks on a date cell **Flow:** + 1. User clicks date cell 2. System validates date is not disabled 3. System updates selected date state @@ -288,12 +315,14 @@ Manages calendar interactions, date selection, event display, and navigation bet 6. System updates related components (e.g., event list for that date) **Business Rules:** + - Cannot select dates in the past (configurable) - Cannot select dates beyond 1 year in future (configurable) - Can only select one date at a time (single-select mode) - Can select date range (range-select mode, if enabled) **Edge Cases:** + - Clicking already selected date: Deselects it - Clicking disabled date: No action, show tooltip - Rapid clicking: Debounce to prevent multiple selections @@ -303,6 +332,7 @@ Manages calendar interactions, date selection, event display, and navigation bet **Trigger:** User clicks "Next Month" button **Flow:** + 1. User clicks next month button 2. System increments month by 1 3. System fetches events for new month (if needed) @@ -311,6 +341,7 @@ Manages calendar interactions, date selection, event display, and navigation bet 6. System updates month/year header **Business Rules:** + - Cannot navigate beyond max date (1 year from today) - Loading state shown while fetching events - Previous selections cleared on month change @@ -320,12 +351,14 @@ Manages calendar interactions, date selection, event display, and navigation bet **Trigger:** User hovers over date with event indicators **Flow:** + 1. User hovers over date cell with events 2. System shows tooltip with event summary 3. Tooltip displays: Event count, first 2 event titles 4. User can click to see full event list **Business Rules:** + - Tooltip appears after 300ms hover - Max 2 events shown in tooltip - "And X more" shown if > 2 events @@ -344,10 +377,12 @@ Manages calendar interactions, date selection, event display, and navigation bet error: string | null // Error message } ``` +```` ### State Transitions **Initial State:** + - currentMonth: Current month - selectedDate: null - viewMode: 'month' @@ -356,10 +391,12 @@ Manages calendar interactions, date selection, event display, and navigation bet - error: null **On Date Select:** + - selectedDate: clicked date - Trigger callback: onDateSelect(date) **On Month Change:** + - currentMonth: new month - selectedDate: null (if clearOnMonthChange = true) - loading: true @@ -367,6 +404,7 @@ Manages calendar interactions, date selection, event display, and navigation bet - loading: false **On Error:** + - error: error message - loading: false - Show error state in UI @@ -376,6 +414,7 @@ Manages calendar interactions, date selection, event display, and navigation bet ### API Endpoints **Get Events for Month** + - **Method:** GET - **Path:** `/api/calendar/events?month={YYYY-MM}` - **Purpose:** Fetch all events for specified month @@ -395,6 +434,7 @@ Manages calendar interactions, date selection, event display, and navigation bet ``` **Create Event** + - **Method:** POST - **Path:** `/api/calendar/events` - **Purpose:** Create new calendar event @@ -411,13 +451,14 @@ Manages calendar interactions, date selection, event display, and navigation bet ### Data Models **Event Model:** + ```typescript interface Event { id: string; - date: string; // ISO date format + date: string; // ISO date format title: string; category: 'walk' | 'feeding' | 'vet' | 'grooming'; - assignedTo: string; // User ID + assignedTo: string; // User ID completed: boolean; notes?: string; } @@ -425,21 +466,23 @@ interface Event { ## Validation Rules -| Rule | Validation | Error Message | -|------|------------|---------------| -| Date in past | `date < today` | "Cannot select past dates" | -| Date too far | `date > today + 365 days` | "Cannot select dates beyond 1 year" | -| Event title | `title.length > 0 && title.length <= 100` | "Event title required (max 100 chars)" | +| Rule | Validation | Error Message | +| ------------ | ----------------------------------------- | -------------------------------------- | +| Date in past | `date < today` | "Cannot select past dates" | +| Date too far | `date > today + 365 days` | "Cannot select dates beyond 1 year" | +| Event title | `title.length > 0 && title.length <= 100` | "Event title required (max 100 chars)" | ## Error Handling ### Network Error (Failed to fetch events) + - **Trigger:** API request fails - **Action:** Show error state in calendar - **Message:** "Unable to load events. Please try again." - **Recovery:** Retry button ### Invalid Date Selection + - **Trigger:** User attempts to select disabled date - **Action:** Show tooltip - **Message:** "This date is not available" @@ -467,6 +510,7 @@ interface Event { - **Component:** `calendar-widget.component.md` (visual design) - **Feature:** `walk-assignment.feature.md` (for creating walk events) - **API:** Calendar Events API + ``` --- @@ -485,10 +529,12 @@ interface Event { **Component used on multiple pages:** ``` + Pages/02-calendar-page.md → Components/calendar-widget.component.md -Pages/05-dashboard.md → Components/calendar-widget.component.md - ↓ - Features/calendar-logic.feature.md +Pages/05-dashboard.md → Components/calendar-widget.component.md +↓ +Features/calendar-logic.feature.md + ``` **Same component, different configurations:** @@ -524,16 +570,19 @@ Pages/05-dashboard.md → Components/calendar-widget.component.md ### Pages ``` + {number}-{page-name}.md Examples: 01-start-page.md 02-calendar-page.md 03-profile-settings.md + ``` ### Components ``` + {component-name}.component.md Examples: @@ -541,10 +590,12 @@ navigation-bar.component.md feature-card.component.md calendar-widget.component.md walk-scheduler.component.md + ``` ### Features ``` + {feature-name}.feature.md Examples: @@ -552,7 +603,8 @@ calendar-logic.feature.md walk-assignment.feature.md user-authentication.feature.md notification-system.feature.md -``` + +```` --- @@ -570,7 +622,7 @@ Reference components and features: **Configuration:** - View: Month - Disable past dates: true -``` +```` ### In Component Files @@ -599,21 +651,25 @@ Reference related components: ## Migration Strategy ### Phase 1: Create Structure + 1. Create `Components/` folder 2. Create `Features/` folder 3. Keep existing `Pages/` (or create if needed) ### Phase 2: Extract Components + 1. Identify reusable components in page specs 2. Create component files with visual design only 3. Update page files to reference components ### Phase 3: Extract Features + 1. Identify complex interactive logic 2. Create feature files with business rules 3. Update page and component files to reference features ### Phase 4: Refactor Existing Pages + 1. Move visual specs → Components/ 2. Move logic → Features/ 3. Keep layout & content in Pages/ @@ -678,6 +734,7 @@ Features/walk-assignment.feature.md (150 lines) 3. **Features/** - Logic, rules, data (WHAT IT DOES) **Benefits:** + - ✅ Clear separation of concerns - ✅ Reusable components across pages - ✅ Maintainable business logic diff --git a/src/modules/wds/workflows/4-ux-design/CONTENT-PLACEMENT-GUIDE.md b/src/modules/wds/workflows/4-ux-design/CONTENT-PLACEMENT-GUIDE.md index deaef915..d44edd74 100644 --- a/src/modules/wds/workflows/4-ux-design/CONTENT-PLACEMENT-GUIDE.md +++ b/src/modules/wds/workflows/4-ux-design/CONTENT-PLACEMENT-GUIDE.md @@ -30,6 +30,7 @@ Is this CONTENT (text, images, data)? ### 1. Page File (WHERE) **Contains:** + - ✅ Position & size - ✅ **Page-specific content** (headings, text, images that change per page) - ✅ **Page-specific data** (API endpoints with page context) @@ -37,9 +38,10 @@ Is this CONTENT (text, images, data)? - ✅ Feature references **Example:** + ```markdown -Pages/01-home-page.md ---- +## Pages/01-home-page.md + ### Hero Section **Component:** `hero-banner.component.md` @@ -48,6 +50,7 @@ Pages/01-home-page.md **Size:** 400px height (desktop), 300px (mobile) **Page-Specific Content:** + - Heading: "Welcome to Dog Week" / "Välkommen till Dog Week" - Subheading: "Coordinate your family's dog walks effortlessly" - Background Image: `/images/hero-home-happy-dog.jpg` @@ -60,6 +63,7 @@ Pages/01-home-page.md ### 2. Component File (HOW IT LOOKS) **Contains:** + - ✅ Visual specifications (colors, spacing, typography) - ✅ States (default, hover, active, disabled, loading, error) - ✅ Variants (sizes, types, themes) @@ -69,12 +73,14 @@ Pages/01-home-page.md - ❌ **NO content** (no text, no images, no data) **Example:** + ```markdown -Components/hero-banner.component.md ---- +## Components/hero-banner.component.md + # Hero Banner Component **Visual Specifications:** + - Height: 400px (desktop), 300px (mobile) - Layout: Centered text over background image - Background: Image with dark overlay (40% opacity) @@ -84,12 +90,14 @@ Components/hero-banner.component.md - CTA Button: Primary button style (blue background, white text) **Content Slots:** + - Heading text (configurable per page) - Subheading text (configurable per page) - Background image (configurable per page) - CTA button text + link (configurable per page) **States:** + - Default: Full opacity - Loading: Skeleton placeholder ``` @@ -99,6 +107,7 @@ Components/hero-banner.component.md ### 3. Feature File (WHAT IT DOES) **Contains:** + - ✅ User interactions & system responses - ✅ Business rules & validation - ✅ State management @@ -109,27 +118,32 @@ Components/hero-banner.component.md - ❌ **NO visual design** (no colors, no spacing, no states) **Example:** + ```markdown -Features/hero-cta-logic.feature.md ---- +## Features/hero-cta-logic.feature.md + # Hero CTA Logic Feature **User Interactions:** ### Click CTA Button + 1. User clicks CTA button 2. System validates user session 3. If logged in → Navigate to destination 4. If not logged in → Show login modal first **Generic Content:** + - Loading text: "Loading..." / "Laddar..." - Error message: "Something went wrong" / "Något gick fel" **API Endpoints:** + - GET /api/user/session (check if logged in) **Business Rules:** + - CTA disabled during loading - CTA shows loading spinner when clicked ``` @@ -143,8 +157,10 @@ Features/hero-cta-logic.feature.md **Scenario:** Hero banner appears on multiple pages with different content **Page File (Home):** + ```markdown **Page-Specific Content:** + - Heading: "Welcome to Dog Week" - Subheading: "Coordinate your family's dog walks" - Background Image: `/images/hero-home.jpg` @@ -153,8 +169,10 @@ Features/hero-cta-logic.feature.md ``` **Page File (About):** + ```markdown **Page-Specific Content:** + - Heading: "About Dog Week" - Subheading: "Our mission to simplify dog care" - Background Image: `/images/hero-about.jpg` @@ -163,13 +181,16 @@ Features/hero-cta-logic.feature.md ``` **Component File:** + ```markdown **Visual Specifications:** + - Height: 400px - Typography: 48px Bold heading, 18px Regular subheading - Layout: Centered text over image **Content Slots:** + - Heading (configurable) - Subheading (configurable) - Background image (configurable) @@ -177,11 +198,14 @@ Features/hero-cta-logic.feature.md ``` **Feature File:** + ```markdown **Generic Content:** + - Loading text: "Loading..." **Interactions:** + - Click CTA → Navigate to link ``` @@ -192,30 +216,38 @@ Features/hero-cta-logic.feature.md **Scenario:** Search bar appears on Product page and Help page with different scopes **Page File (Product Catalog):** + ```markdown **Page-Specific Content:** + - Placeholder: "Search products..." / "Sök produkter..." **Page-Specific Data:** + - API Endpoint: GET /api/products/search?q=:query - Scope: Products only - Result Display: Product cards grid ``` **Page File (Help Center):** + ```markdown **Page-Specific Content:** + - Placeholder: "Search help articles..." / "Sök hjälpartiklar..." **Page-Specific Data:** + - API Endpoint: GET /api/help/search?q=:query - Scope: Help articles only - Result Display: Article list ``` **Component File:** + ```markdown **Visual Specifications:** + - Height: 48px - Border: 1px solid gray - States: @@ -225,22 +257,27 @@ Features/hero-cta-logic.feature.md - Results: Dropdown below input **Content Slots:** + - Placeholder text (configurable per page) ``` **Feature File:** + ```markdown **Generic Content:** + - No results message: "No results found" / "Inga resultat" - Error message: "Search failed" / "Sökning misslyckades" **Interactions:** + - User types → Debounce 300ms → API call - Min 3 characters required - Max 10 results displayed - Keyboard navigation (arrow keys, enter, escape) **Business Rules:** + - Debounce: 300ms - Min characters: 3 - Max results: 10 @@ -253,55 +290,67 @@ Features/hero-cta-logic.feature.md **Scenario:** Calendar appears only on Calendar page, shows current user's family data **Page File (Calendar Page):** + ```markdown **Page-Specific Content:** + - Header Format: "[Family Name]: Vecka [Week Number]" - SE: "Familjen Svensson: Vecka 40" - EN: "Svensson Family: Week 40" **Page-Specific Data:** + - Data Source: Current user's family from session - API Endpoint: GET /api/families/:currentFamilyId/walks?week=:weekNumber - Dogs Displayed: All dogs in current user's family - Family Members: All members in current user's family **Configuration:** + - Initial View: Current week, scrolled to today - Time Slots: 4 hardcoded (8-11, 12-13, 15-17, 18-20) ``` **Component File:** + ```markdown **Visual Specifications:** + - 6 walk states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED) - Week circles: 7 days with quarter segments - Leaderboard cards: Avatar + badge + name **Content Slots:** + - Header text (configurable per page) - Time slot labels (configurable) ``` **Feature File:** + ```markdown **Generic Content:** + - Empty state: "Add a dog to start planning walks" - Error message: "Failed to load walks" - Countdown format: "32 min left" / "32 min kvar" - Duration format: "32 min walk" / "32 min promenad" **Interactions:** + - Book walk → GRAY state - Start walk → BLUE state - Complete walk → GREEN state - Miss walk → RED state **Business Rules:** + - One active walk per dog - Can't book if slot taken - Countdown starts at slot start time **API Endpoints:** + - GET /api/families/:familyId/walks?week=:weekNumber - POST /api/walks (create booking) - PUT /api/walks/:walkId/start @@ -315,6 +364,7 @@ Features/hero-cta-logic.feature.md **Scenario:** Submit button appears on multiple forms, always says "Submit" **Page File:** + ```markdown **Position:** Bottom of form, right-aligned **Size:** Full-width on mobile, auto-width on desktop @@ -326,8 +376,10 @@ Features/hero-cta-logic.feature.md ``` **Component File:** + ```markdown **Visual Specifications:** + - Background: Blue (#3B82F6) - Text: White, 16px Medium - Height: 48px @@ -341,14 +393,17 @@ Features/hero-cta-logic.feature.md ``` **Feature File:** + ```markdown **Generic Content:** + - Button text: "Submit" / "Skicka" - Loading text: "Submitting..." / "Skickar..." - Success message: "Submitted successfully" / "Skickat" - Error message: "Submission failed" / "Misslyckades" **Interactions:** + - Click → Validate form - If valid → Submit to API - If invalid → Show validation errors @@ -359,22 +414,22 @@ Features/hero-cta-logic.feature.md ## Decision Matrix -| Content Type | Page-Specific? | Where to Document | -|--------------|----------------|-------------------| -| **Hero heading** | ✅ YES (different per page) | Page File | -| **Hero background image** | ✅ YES (different per page) | Page File | -| **Search placeholder** | ✅ YES (different per page) | Page File | -| **Calendar header** | ✅ YES (shows user's family name) | Page File | -| **API endpoint with user context** | ✅ YES (varies by user/page) | Page File | -| **Submit button text** | ❌ NO (always "Submit") | Feature File | -| **Error messages** | ❌ NO (generic validation) | Feature File | -| **Loading text** | ❌ NO (always "Loading...") | Feature File | -| **Tooltip text** | ❌ NO (generic interaction) | Feature File | -| **API endpoint (generic)** | ❌ NO (same for all users) | Feature File | -| **Button color** | ❌ NO (visual design) | Component File | -| **Font size** | ❌ NO (visual design) | Component File | -| **Hover state** | ❌ NO (visual design) | Component File | -| **Layout spacing** | ❌ NO (visual design) | Component File | +| Content Type | Page-Specific? | Where to Document | +| ---------------------------------- | --------------------------------- | ----------------- | +| **Hero heading** | ✅ YES (different per page) | Page File | +| **Hero background image** | ✅ YES (different per page) | Page File | +| **Search placeholder** | ✅ YES (different per page) | Page File | +| **Calendar header** | ✅ YES (shows user's family name) | Page File | +| **API endpoint with user context** | ✅ YES (varies by user/page) | Page File | +| **Submit button text** | ❌ NO (always "Submit") | Feature File | +| **Error messages** | ❌ NO (generic validation) | Feature File | +| **Loading text** | ❌ NO (always "Loading...") | Feature File | +| **Tooltip text** | ❌ NO (generic interaction) | Feature File | +| **API endpoint (generic)** | ❌ NO (same for all users) | Feature File | +| **Button color** | ❌ NO (visual design) | Component File | +| **Font size** | ❌ NO (visual design) | Component File | +| **Hover state** | ❌ NO (visual design) | Component File | +| **Layout spacing** | ❌ NO (visual design) | Component File | --- @@ -383,24 +438,29 @@ Features/hero-cta-logic.feature.md ### ❌ Mistake 1: Putting page-specific content in Feature file **Wrong:** + ```markdown -Features/hero-logic.feature.md ---- +## Features/hero-logic.feature.md + **Content:** + - Heading: "Welcome to Dog Week" (Home page) - Heading: "About Dog Week" (About page) ``` **Right:** + ```markdown -Pages/01-home-page.md ---- +## Pages/01-home-page.md + **Page-Specific Content:** + - Heading: "Welcome to Dog Week" -Pages/02-about-page.md ---- +## Pages/02-about-page.md + **Page-Specific Content:** + - Heading: "About Dog Week" ``` @@ -409,19 +469,23 @@ Pages/02-about-page.md ### ❌ Mistake 2: Putting generic content in Page file **Wrong:** + ```markdown -Pages/01-home-page.md ---- +## Pages/01-home-page.md + **Content:** + - Submit button: "Submit" - Error message: "Invalid email" ``` **Right:** + ```markdown -Features/form-submit-logic.feature.md ---- +## Features/form-submit-logic.feature.md + **Generic Content:** + - Submit button: "Submit" - Error message: "Invalid email" ``` @@ -431,20 +495,24 @@ Features/form-submit-logic.feature.md ### ❌ Mistake 3: Putting visual design in Feature file **Wrong:** + ```markdown -Features/button-logic.feature.md ---- +## Features/button-logic.feature.md + **Visual:** + - Background: Blue - Height: 48px - Hover: Darker blue ``` **Right:** + ```markdown -Components/button-primary.component.md ---- +## Components/button-primary.component.md + **Visual Specifications:** + - Background: Blue (#3B82F6) - Height: 48px - States: @@ -471,11 +539,13 @@ Is this visual design? ``` **Key Principle:** + - **Page File** = WHERE + WHAT (page-specific) - **Component File** = HOW IT LOOKS (visual design) - **Feature File** = WHAT IT DOES (functionality + generic content) **Result:** + - ✅ Clear separation of concerns - ✅ Easy to maintain and update - ✅ Clean handoffs to designers and developers diff --git a/src/modules/wds/workflows/4-ux-design/CROSS-PAGE-CONSISTENCY.md b/src/modules/wds/workflows/4-ux-design/CROSS-PAGE-CONSISTENCY.md index 8e86aae2..de66c184 100644 --- a/src/modules/wds/workflows/4-ux-design/CROSS-PAGE-CONSISTENCY.md +++ b/src/modules/wds/workflows/4-ux-design/CROSS-PAGE-CONSISTENCY.md @@ -9,6 +9,7 @@ **Text that looks similar and serves the same role should have the same specification across all pages.** This creates: + - ✅ Consistent user experience - ✅ Natural design system patterns - ✅ Faster specification process @@ -25,7 +26,7 @@ This creates: ``` Start Page Analysis: ├─ Body Text: Thin lines, icon-sized spacing → 16px Regular -├─ Button Labels: Medium lines → 16px Semibold +├─ Button Labels: Medium lines → 16px Semibold ├─ Page Title: Thick lines, button-height spacing → 48px Bold ├─ Navigation: Medium lines, small spacing → 14px Medium └─ Caption: Thinnest lines, half-icon spacing → 12px Regular @@ -40,12 +41,14 @@ Start Page Analysis: **When analyzing the About Page sketch:** #### Step 1: Check Previous Pages + ``` -Agent: "I see you've already analyzed the Start Page. +Agent: "I see you've already analyzed the Start Page. I'll use those text styles as reference points." ``` #### Step 2: Match Visual Patterns + ``` About Page body text: - Thin lines ✓ @@ -57,6 +60,7 @@ About Page body text: ``` #### Step 3: Confirm with Designer + ``` Agent: "This body text looks identical to Start Page body text. Should I use the same specification (16px Regular)?" @@ -125,11 +129,13 @@ Components Identified: ### Benefits **Without explicit design system:** + - Maintains consistency through pattern recognition - Reduces specification time (reference previous pages) - Creates professional, cohesive experience **With explicit design system:** + - Automatically maps to existing components - Validates sketch against design system - Suggests design system updates when new patterns emerge diff --git a/src/modules/wds/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md b/src/modules/wds/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md index 9af2dbbe..24c198f0 100644 --- a/src/modules/wds/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md +++ b/src/modules/wds/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md @@ -71,6 +71,7 @@ Currently sketch text analysis rules are duplicated across multiple files, makin ## Refactoring Plan ### Keep As-Is (Single Source of Truth) + ✅ `SKETCH-TEXT-ANALYSIS-GUIDE.md` - Master guide with all rules ✅ `SKETCH-TEXT-QUICK-REFERENCE.md` - Quick reference ✅ `SKETCH-TEXT-STRATEGY.md` - Strategy guide @@ -78,26 +79,31 @@ Currently sketch text analysis rules are duplicated across multiple files, makin ### Refactor (Remove Duplication, Add References) **`TEXT-DETECTION-PRIORITY.md`:** + - Keep: Detection logic (pairs vs single) - Remove: Detailed analysis rules (thickness → weight, spacing → size) - Add: Reference to master guide **`heading-text.md`:** + - Keep: Workflow steps - Remove: Duplicate explanations of analysis rules - Add: Reference to master guide - Show: Example output only **`object-router.md`:** + - Keep: Routing logic - Remove: Any duplicate analysis - Add: Reference to TEXT-DETECTION-PRIORITY.md **`WDS-SPECIFICATION-PATTERN.md`:** + - Keep: Examples - Add: Note "See SKETCH-TEXT-ANALYSIS-GUIDE.md for how these values were derived" **`TRANSLATION-ORGANIZATION-GUIDE.md`:** + - Keep: Organization patterns - Add: Reference to master guide for analysis @@ -121,14 +127,16 @@ In instruction files, use this pattern: Analyzing text markers in sketch... 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 - + **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 ## Status **To Do:** + - [ ] Refactor TEXT-DETECTION-PRIORITY.md - [ ] Refactor heading-text.md - [ ] Refactor object-router.md @@ -150,4 +159,3 @@ For detailed analysis rules, see: SKETCH-TEXT-ANALYSIS-GUIDE.md - [ ] Add references in TRANSLATION-ORGANIZATION-GUIDE.md **Result:** Clean, maintainable documentation architecture! 🎯 - diff --git a/src/modules/wds/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md b/src/modules/wds/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md index 5a68459e..8d142074 100644 --- a/src/modules/wds/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md +++ b/src/modules/wds/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md @@ -7,18 +7,22 @@ ## The Two-Layer System ### Layer 1: HTML Semantic Structure (h1-h6, p, etc.) + **Purpose:** SEO, accessibility, document outline, screen readers **Rules:** + - **Each page must have exactly ONE h1** (main page title) - **Heading hierarchy must be logical** (h1 → h2 → h3, no skipping) - **Same across all pages** for semantic consistency - **Not about visual appearance** ### Layer 2: Visual Text Styles (Design System) + **Purpose:** Visual hierarchy, branding, design consistency **Rules:** + - **Named by visual purpose** (Display-Large, Headline-Primary, Body-Regular, etc.) - **Can be applied to any HTML tag** - **Different pages can use different visual styles** for the same HTML tag @@ -29,24 +33,30 @@ ## Why Separate? ### Problem: Mixing HTML and Visual Styles + ```markdown ❌ BAD: + - **Style**: H1 heading What does this mean? + - Is it an h1 tag? - Is it a visual style that looks like an h1? - What if another page needs h1 but different visual style? ``` ### Solution: Specify Both Independently + ```markdown ✅ GOOD: + - **HTML Tag**: h1 (semantic structure) - **Visual Style**: Display-Large (from Design System) ``` **Now we know:** + - HTML: This is the main page heading (h1 for SEO) - Visual: It uses the "Display-Large" design system style - Another page could have: h1 + Headline-Medium (different visual, same semantic) @@ -58,6 +68,7 @@ What does this mean? ### Example 1: Landing Page vs. Article Page **Landing Page - Hero Headline:** + ```markdown - **HTML Tag**: h1 - **Visual Style**: Hero headline @@ -65,6 +76,7 @@ What does this mean? ``` **Article Page - Article Title:** + ```markdown - **HTML Tag**: h1 - **Visual Style**: Main header @@ -76,6 +88,7 @@ What does this mean? ### Example 2: Same Visual Style, Different Semantics **Section Heading:** + ```markdown - **HTML Tag**: h2 - **Visual Style**: Sub header @@ -83,6 +96,7 @@ What does this mean? ``` **Testimonial Quote:** + ```markdown - **HTML Tag**: p - **Visual Style**: Sub header @@ -120,6 +134,7 @@ What does this mean? ✅ **Button text** - Text within buttons ### Bad Visual Style Names + ❌ **H1-Style** / **Heading-1** - Confuses with HTML tags ❌ **Text-Size-42** - Just a number, not semantic ❌ **Big-Text** - Too vague @@ -137,10 +152,12 @@ What does this mean? **OBJECT ID**: `start-hero-headline` **HTML Structure:** + - **Tag**: h1 - **Purpose**: Main page heading (SEO/accessibility) **Visual Style:** + - **Style Name**: Hero headline - **Font weight**: Bold (from 3px thick line markers in sketch) - **Font size**: 56px (est. from 32px spacing between line pairs) @@ -153,6 +170,7 @@ What does this mean? **Behavior**: Updates with language toggle **Content**: + - EN: "Every walk. on time. Every time." - SE: "Varje promenad. i tid. Varje gång." ``` @@ -173,6 +191,7 @@ What does this mean? ## Common Patterns ### Pattern 1: Landing Page + ``` h1 → Hero headline (big hero text, 56px) h2 → Sub header (section headings, 32px) @@ -181,6 +200,7 @@ p → Body text (regular paragraphs, 16px) ``` ### Pattern 2: Blog Post + ``` h1 → Main header (article title, 36px) h2 → Sub header (section headings, 28px) @@ -189,6 +209,7 @@ p → Body text large (article body, 18px) ``` ### Pattern 3: Dashboard + ``` h1 → Main header (page title, 28px) h2 → Card header (widget titles, 20px) @@ -220,4 +241,3 @@ The CSS class references the **visual style name** (hero-headline, main-header), --- **Remember:** HTML tags = Document structure. Visual styles = Appearance. Keep them separate! 🎯 - diff --git a/src/modules/wds/workflows/4-ux-design/IMAGE-SKETCHING-BEST-PRACTICES.md b/src/modules/wds/workflows/4-ux-design/IMAGE-SKETCHING-BEST-PRACTICES.md index 3220c3bc..00e74039 100644 --- a/src/modules/wds/workflows/4-ux-design/IMAGE-SKETCHING-BEST-PRACTICES.md +++ b/src/modules/wds/workflows/4-ux-design/IMAGE-SKETCHING-BEST-PRACTICES.md @@ -9,6 +9,7 @@ ### Why Sketch Real Content? When you sketch what the image should actually show (rather than just "X" or "image here"), you: + - **Provide visual direction** - Designer/developer understands image purpose - **Enable AI interpretation** - Agent can suggest appropriate image content - **Guide art direction** - Photographer/illustrator knows what's needed @@ -22,6 +23,7 @@ When you sketch what the image should actually show (rather than just "X" or "im ### 1. Portrait/Profile Photos **Sketch a simple face:** + ``` ┌──────────────┐ │ ◠ ◠ │ ← Simple eyes @@ -45,6 +47,7 @@ or ### 2. Hero Images / Backgrounds **Sketch landscape/scenery:** + ``` ┌──────────────────────────┐ │ │ @@ -55,6 +58,7 @@ or ``` **Sketch clouds/sky:** + ``` ┌──────────────────────────┐ │ ~ ~ ~ │ @@ -65,6 +69,7 @@ or ``` **Sketch abstract shapes:** + ``` ┌──────────────────────────┐ │ ∿∿∿ ≈≈≈ │ @@ -78,6 +83,7 @@ or ### 3. Product Images **Sketch the product outline:** + ``` ┌──────────────┐ │ |‾‾‾‾| │ ← Phone outline @@ -101,6 +107,7 @@ or ### 4. Icons / Illustrations **Sketch simple icon shapes:** + ``` ┌──────┐ │ ⚙ │ ← Settings gear @@ -124,6 +131,7 @@ or ### 5. Abstract/Decorative Images **Use soft, flowing shapes:** + ``` ┌──────────────────────────┐ │ ∞ │ @@ -134,6 +142,7 @@ or ``` **Use geometric patterns:** + ``` ┌──────────────────────────┐ │ ◆ ○ ▢ │ @@ -157,6 +166,7 @@ or ``` **Problems with X markers:** + - ❌ **No context** - Doesn't communicate what image shows - ❌ **No direction** - No guidance for content selection - ❌ **Intrusive** - Visually distracting in sketch @@ -181,6 +191,7 @@ When analyzing sketches, the AI should: ### Example Detection **Sketch shows:** + ``` ┌──────────────────────────┐ │ /\ /\ /\ │ @@ -190,6 +201,7 @@ When analyzing sketches, the AI should: ``` **AI interprets:** + - Rectangle container detected - Mountain/landscape sketch inside - **Purpose:** Hero background image showing outdoor/nature scene @@ -201,24 +213,28 @@ When analyzing sketches, the AI should: ## Benefits of Sketching Real Content ### For Designers + - ✅ Communicate visual intent clearly - ✅ Test composition and layout - ✅ Provide art direction - ✅ Inspire creative solutions ### For AI Agents + - ✅ Understand image purpose from context - ✅ Suggest appropriate image sources - ✅ Recommend image dimensions and aspect ratios - ✅ Generate meaningful alt text ### For Developers + - ✅ Understand what image represents - ✅ Know how to style and position image - ✅ Select appropriate placeholder images - ✅ Write meaningful alt text for accessibility ### For Stakeholders + - ✅ Visualize final design better - ✅ Provide meaningful feedback - ✅ Understand design intent @@ -228,28 +244,29 @@ When analyzing sketches, the AI should: ## Quick Reference -| Image Type | Sketch Technique | Example | -|------------|------------------|---------| -| **Portrait/Face** | Simple face with eyes and smile | ◠ ◠ ᵕ | -| **Landscape** | Mountains, trees, horizon | /\\ /\\ /\\ | -| **Sky/Clouds** | Wavy cloud shapes | ~ ~ ~ | -| **Product** | Product outline/silhouette | Phone, laptop shape | -| **Icon** | Simple icon shape | ⚙ ♥ ✓ | -| **Abstract** | Flowing, organic shapes | ∿ ≋ ∞ | -| **Geometric** | Shapes and patterns | ◆ ○ ▢ | +| Image Type | Sketch Technique | Example | +| ----------------- | ------------------------------- | ------------------- | +| **Portrait/Face** | Simple face with eyes and smile | ◠ ◠ ᵕ | +| **Landscape** | Mountains, trees, horizon | /\\ /\\ /\\ | +| **Sky/Clouds** | Wavy cloud shapes | ~ ~ ~ | +| **Product** | Product outline/silhouette | Phone, laptop shape | +| **Icon** | Simple icon shape | ⚙ ♥ ✓ | +| **Abstract** | Flowing, organic shapes | ∿ ≋ ∞ | +| **Geometric** | Shapes and patterns | ◆ ○ ▢ | --- ## Summary **WDS Image Sketching Philosophy:** + > "Sketch what you see, not just where it goes." **Guidelines:** + - ✅ **Draw the actual content** - Faces, landscapes, products - ✅ **Use soft, organic shapes** - Clouds, waves for abstract images - ✅ **Keep it simple** - Quick sketches are fine, detail level matches sketch fidelity - ❌ **Avoid generic X markers** - Provides no useful context **Result:** Better communication, clearer intent, more useful AI analysis! 🎨✨ - diff --git a/src/modules/wds/workflows/4-ux-design/PROACTIVE-TRANSLATION-WORKFLOW.md b/src/modules/wds/workflows/4-ux-design/PROACTIVE-TRANSLATION-WORKFLOW.md index 01089a0b..a5208503 100644 --- a/src/modules/wds/workflows/4-ux-design/PROACTIVE-TRANSLATION-WORKFLOW.md +++ b/src/modules/wds/workflows/4-ux-design/PROACTIVE-TRANSLATION-WORKFLOW.md @@ -7,6 +7,7 @@ ## The Principle **Agent is proactive, not passive** + - Don't just ask for translations - **Suggest them!** - Let user accept, refine, or override @@ -18,11 +19,13 @@ ### Example 1: Sketch Has Actual Text **Sketch shows:** + ``` Every walk. on time. Every time. ``` **Agent says:** + ``` I found text in your sketch: "Every walk. on time. Every time." @@ -46,12 +49,15 @@ Choice [1/2/3]: **User response options:** **Option A: Accept (Fast!)** + ``` 1 ``` + → Done! All translations accepted. **Option B: Adjust specific** + ``` 2 @@ -63,9 +69,11 @@ NO: Hver tur. i tide. Hver gang. ← Keep SE: Varje promenad. Punktligt. Varje gång. ``` + → Done! One adjusted, others kept. **Option C: Manual** + ``` 3 @@ -73,6 +81,7 @@ EN: SE: NO: ``` + → User provides all manually. --- @@ -80,6 +89,7 @@ NO: ### Example 2: No Sketch Text (Markers Only) **Sketch shows:** + ``` ───────────────────────────────── ← Line markers ───────────────────────────────── ← (no actual text) @@ -87,6 +97,7 @@ NO: ``` **Agent says:** + ``` Text placeholder detected: - 3 horizontal lines @@ -101,11 +112,13 @@ EN: ``` **User provides:** + ``` EN: Organize your family around dog care. Assign walks and never miss one again. ``` **Agent immediately suggests:** + ``` Great! Here are translation suggestions: @@ -128,22 +141,26 @@ Choice [1/2/3]: ## Benefits ### ✅ Speed + - User accepts = instant completion - No typing all translations manually - Saves significant time ### ✅ Accuracy + - Agent uses context for better translations - Considers character capacity - Maintains tone and style ### ✅ Flexibility + - Can accept all suggestions - Can adjust specific ones - Can override completely - Full user control ### ✅ Consistency + - Translations match style - Terminology stays consistent - Professional quality @@ -160,15 +177,15 @@ Choice [1/2/3]: Extract text: "Every walk. on time." Translate to all product_languages - + I found text in your sketch: "{{text}}" - + Suggested translations: {{#each product_languages}} {{this}}: {{translated_content}} {{/each}} - + Do these work? [1] Use [2] Adjust [3] Manual @@ -176,13 +193,13 @@ Choice [1/2/3]: Provide content in {{primary_language}}: After receiving, translate to remaining languages - + Translation suggestions: {{#each remaining_languages}} {{this}}: {{translated_content}} {{/each}} - + Do these work? [1] Use [2] Adjust [3] Manual @@ -191,6 +208,7 @@ Choice [1/2/3]: ### Translation Quality **Agent considers:** + - Character capacity from sketch - Tone and style of original - Context from page purpose @@ -204,11 +222,13 @@ Choice [1/2/3]: ### Example: Hero Headline **Sketch:** + ``` Every walk. on time. Every time. ``` **Agent:** + ``` Suggested content for Primary Headline: @@ -219,6 +239,7 @@ Do these work? [1] Use [2] Adjust [3] Manual ``` **User:** + ``` 1 ``` @@ -228,11 +249,13 @@ Do these work? [1] Use [2] Adjust [3] Manual ### Example: Button Label **Sketch:** + ``` [Get Started - Free Forever] ``` **Agent:** + ``` Suggested content for Primary CTA: @@ -243,6 +266,7 @@ Do these work? [1] Use [2] Adjust [3] Manual ``` **User:** + ``` 2 @@ -254,11 +278,13 @@ SE: börja planera - gratis för alltid ← lowercase, different verb ### Example: Form Label **Sketch:** + ``` Email Address: ``` **Agent:** + ``` Suggested content for Email Label: @@ -269,6 +295,7 @@ Do these work? [1] Use [2] Adjust [3] Manual ``` **User:** + ``` 1 ``` @@ -280,6 +307,7 @@ Do these work? [1] Use [2] Adjust [3] Manual ## Multi-Language Example (3+ Languages) **Project Config:** + ```yaml product_languages: - EN @@ -289,11 +317,13 @@ product_languages: ``` **Sketch:** + ``` Welcome Home ``` **Agent:** + ``` I found text in your sketch: "Welcome Home" @@ -308,6 +338,7 @@ Do these work? [1] Use [2] Adjust [3] Manual ``` **User:** + ``` 1 ``` @@ -321,6 +352,7 @@ Do these work? [1] Use [2] Adjust [3] Manual ### Translation Confidence **High confidence:** + ``` ✅ These translations look good! @@ -328,6 +360,7 @@ Do they work? [1] Use [2] Adjust [3] Manual ``` **Low confidence:** + ``` ⚠️ I'm less confident about these translations. Please review carefully! @@ -341,6 +374,7 @@ Do they work? [1] Use [2] Adjust [3] Manual ### Character Capacity Warning **If translation exceeds capacity:** + ``` ⚠️ Translation length warning: @@ -359,6 +393,7 @@ Use shorter version? (y/n) ## User Experience ### Before (Passive): + ``` EN: ← User types SE: ← User types @@ -368,6 +403,7 @@ Slow, tedious, error-prone ``` ### After (Proactive): + ``` Suggested translations: EN: Every walk. on time. @@ -386,6 +422,7 @@ Fast, accurate, professional ### Agent Behavior **Always suggest translations:** + 1. Read sketch text (if present) 2. Generate suggestions for ALL languages 3. Present with options: Accept / Adjust / Manual @@ -393,6 +430,7 @@ Fast, accurate, professional 5. Warn if low confidence **Never:** + - Present blank fields for translations - Make user type everything - Provide only one language at a time @@ -407,6 +445,3 @@ Fast, accurate, professional --- **Proactive translation = better UX, faster workflow, higher quality!** 🌍⚡✨ - - - diff --git a/src/modules/wds/workflows/4-ux-design/README.md b/src/modules/wds/workflows/4-ux-design/README.md index 6098434c..c81c1700 100644 --- a/src/modules/wds/workflows/4-ux-design/README.md +++ b/src/modules/wds/workflows/4-ux-design/README.md @@ -12,31 +12,36 @@ Phase 4 transforms sketches and ideas into detailed, developer-ready page specif ## Workflow Steps -| Step | File | Purpose | -|------|------|---------| -| **Init** | `step-01-init.md` | Welcome, load context, initialize session | -| **Define Scenario** | `step-02-define-scenario.md` | Plan user journey and pages | -| **Design Page** | `step-03-design-page.md` | Orchestrate 4A-4E substeps per page | -| **Complete Scenario** | `step-04-complete-scenario.md` | Finalize and summarize scenario | -| **Next Steps** | `step-05-next-steps.md` | Continue or exit workflow | +| Step | File | Purpose | +| --------------------- | ------------------------------ | ----------------------------------------- | +| **Init** | `step-01-init.md` | Welcome, load context, initialize session | +| **Define Scenario** | `step-02-define-scenario.md` | Plan user journey and pages | +| **Design Page** | `step-03-design-page.md` | Orchestrate 4A-4E substeps per page | +| **Complete Scenario** | `step-04-complete-scenario.md` | Finalize and summarize scenario | +| **Next Steps** | `step-05-next-steps.md` | Continue or exit workflow | --- ## Substeps (4A-4E) ### 4A: Exploration + **File:** `substeps/4a-exploration.md` + - Think through user journey - Clarify context and goals ### 4B: Sketch Analysis + **File:** `substeps/4b-sketch-analysis.md` + - **Section-first approach:** AI reads entire sketch, identifies all sections - User confirms structure - Section-by-section AI interpretation - User refinement dialog ### 4C: Specification (Micro-steps 01-08) + **Files:** `substeps/4c-01-page-basics.md` through `4c-08-generate-spec.md` 1. **Page Basics** - Name, purpose, route @@ -49,12 +54,16 @@ Phase 4 transforms sketches and ideas into detailed, developer-ready page specif 8. **Generate Spec** - Complete page specification ### 4D: Prototype + **File:** `substeps/4d-prototype.md` + - Generate interactive HTML prototype - Uses Design System if enabled ### 4E: PRD Update + **File:** `substeps/4e-prd-update.md` + - Extract functional requirements - Update Product Requirements Document @@ -66,16 +75,17 @@ Phase 4 transforms sketches and ideas into detailed, developer-ready page specif Each object type has a dedicated instruction file: -| File | Purpose | -|------|---------| -| `object-router.md` | Detects object types, routes to appropriate file | -| `button.md` | Button specification | -| `text-input.md` | Input field specification | -| `link.md` | Link/anchor specification | -| `heading-text.md` | Text element specification with purpose-based naming | -| `image.md` | Image specification | +| File | Purpose | +| ------------------ | ---------------------------------------------------- | +| `object-router.md` | Detects object types, routes to appropriate file | +| `button.md` | Button specification | +| `text-input.md` | Input field specification | +| `link.md` | Link/anchor specification | +| `heading-text.md` | Text element specification with purpose-based naming | +| `image.md` | Image specification | **Key Features:** + - Purpose-based naming (function over content) - Grouped translations (coherent language blocks) - Design System integration (use existing, create new, or page-specific) @@ -87,31 +97,32 @@ Each object type has a dedicated instruction file: **Location:** `templates/` -| File | Purpose | -|------|---------| +| File | Purpose | +| -------------------------------- | -------------------------------- | | `page-specification.template.md` | Complete page spec output format | -| `scenario-overview.template.md` | Scenario summary format | +| `scenario-overview.template.md` | Scenario summary format | --- ## Documentation -| File | Purpose | -|------|---------| -| `ARCHITECTURE.md` | Complete workflow architecture overview | -| `WDS-SPECIFICATION-PATTERN.md` | **Standard specification format** (Dog Week as example) | +| File | Purpose | +| ----------------------------------- | -------------------------------------------------------- | +| `ARCHITECTURE.md` | Complete workflow architecture overview | +| `WDS-SPECIFICATION-PATTERN.md` | **Standard specification format** (Dog Week as example) | | `TRANSLATION-ORGANIZATION-GUIDE.md` | Purpose-based text organization and grouped translations | -| `SKETCH-TEXT-ANALYSIS-GUIDE.md` | How to interpret text markers in sketches | -| `SKETCH-TEXT-QUICK-REFERENCE.md` | Quick reference for text analysis | -| `SKETCH-TEXT-STRATEGY.md` | When to use actual text vs. line markers | -| `PROACTIVE-TRANSLATION-WORKFLOW.md` | How agent suggests translations | -| `ROUTER-FLOW-DIAGRAM.md` | Visual flow of object routing with examples | +| `SKETCH-TEXT-ANALYSIS-GUIDE.md` | How to interpret text markers in sketches | +| `SKETCH-TEXT-QUICK-REFERENCE.md` | Quick reference for text analysis | +| `SKETCH-TEXT-STRATEGY.md` | When to use actual text vs. line markers | +| `PROACTIVE-TRANSLATION-WORKFLOW.md` | How agent suggests translations | +| `ROUTER-FLOW-DIAGRAM.md` | Visual flow of object routing with examples | --- ## Key Patterns ### 1. Section-First Workflow + - AI reads entire sketch → identifies sections - User confirms structure - Section-by-section interpretation @@ -119,25 +130,32 @@ Each object type has a dedicated instruction file: - Batch generation of specs ### 2. Purpose-Based Naming + - Name text by **function**, not content - `hero-headline` not `welcome-message` - `form-error` not `invalid-email-text` ### 3. Grouped Translations + ```markdown #### Primary Headline + **Content**: + - EN: "Welcome to Dog Week" - SE: "Välkommen till Hundveckan" ``` ### 4. Design System Integration + For each object: + 1. Use existing component 2. Create new component (mark for Phase 5) 3. Page-specific only ### 5. Text Marker Analysis + - **2 lines together** = 1 line of text - **Line thickness** = font weight (thick = bold) - **Spacing between pairs** = font size @@ -148,6 +166,7 @@ For each object: ## Multi-Language Support **Configuration:** Set in `workflow-init` + - **Specification Language**: Language for writing specs (EN, SE, etc.) - **Product Languages**: Languages the product supports (array) @@ -188,6 +207,7 @@ docs/ ``` Each page spec includes: + - Page metadata and purpose - All sections with objects - Complete multi-language content @@ -198,4 +218,3 @@ Each page spec includes: --- **Phase 4 Status:** ✅ **COMPLETE** (December 6, 2025) - diff --git a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md index fea5c7c4..b613beaf 100644 --- a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md +++ b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md @@ -7,27 +7,32 @@ ## Best Practice: When to Use Text vs. Markers ### Use ACTUAL TEXT for: + - **Headlines** - Provides content guidance and context - **Button labels** - Shows intended action clearly - **Navigation items** - Clarifies structure - **Short, important text** - Where specific wording matters **Example:** + ``` Every walk. on time. Every time. ← Actual text (readable) ``` **Benefits:** + - Agent can read and suggest this as starting content - Provides context for design decisions - Can still be changed during specification ### Use HORIZONTAL LINE MARKERS for: + - **Body paragraphs** - Content TBD, just need length indication - **Long descriptions** - Where specific wording isn't decided yet - **Placeholder content** - General sizing guidance **Example:** + ``` ───────────────────────────────────────── ← Line markers ───────────────────────────────────────── ← Show length/size @@ -36,6 +41,7 @@ Every walk. on time. Every time. ← Actual text (readable) ``` **Benefits:** + - Shows font size and capacity without committing to content - Faster for sketching body text - Focuses on layout, not copywriting @@ -73,12 +79,12 @@ Justified/Full-width text: **Each PAIR of horizontal lines = ONE line of text** -| Number of Pairs | Text Lines | Typical Use | -|-----------------|------------|-------------| -| 1 pair | 1 line | Headlines, labels, buttons | -| 2 pairs | 2 lines | Short headlines, subheadings | -| 3-4 pairs | 3-4 lines | Intro paragraphs, descriptions | -| 5+ pairs | 5+ lines | Body copy, long descriptions | +| Number of Pairs | Text Lines | Typical Use | +| --------------- | ---------- | ------------------------------ | +| 1 pair | 1 line | Headlines, labels, buttons | +| 2 pairs | 2 lines | Short headlines, subheadings | +| 3-4 pairs | 3-4 lines | Intro paragraphs, descriptions | +| 5+ pairs | 5+ lines | Body copy, long descriptions | --- @@ -91,6 +97,7 @@ Justified/Full-width text: If analyzing multiple pages in the same project: **Look for established patterns:** + ``` Start Page (already analyzed): - Body text: Thin lines, icon-sized spacing → 16px Regular @@ -103,11 +110,13 @@ Current Page (About Page): ``` **Design System Integration:** + - If project has a design system, match visual patterns to existing components - Body text that looks like Start Page body text → Use same specification - Buttons that look like Start Page buttons → Use same specification **Benefits:** + - ✅ Maintains consistency across all pages - ✅ Builds reusable design patterns - ✅ Reduces specification time for subsequent pages @@ -129,13 +138,13 @@ Current Page (About Page): **Compare lines RELATIVE to each other within the sketch:** -| Relative Thickness | Font Weight | CSS Value | Typical Use | -|-------------------|-------------|-----------|-------------| -| Thickest (═══) | Bold | font-weight: 700 | Headlines, strong emphasis | -| Thick (═══) | Semibold | font-weight: 600 | Subheadings, medium emphasis | -| Medium (──) | Medium | font-weight: 500 | Slightly emphasized text | -| Thin (──) | Regular | font-weight: 400 | Body text, normal content | -| Thinnest (─) | Light | font-weight: 300 | Subtle text, de-emphasized | +| Relative Thickness | Font Weight | CSS Value | Typical Use | +| ------------------ | ----------- | ---------------- | ---------------------------- | +| Thickest (═══) | Bold | font-weight: 700 | Headlines, strong emphasis | +| Thick (═══) | Semibold | font-weight: 600 | Subheadings, medium emphasis | +| Medium (──) | Medium | font-weight: 500 | Slightly emphasized text | +| Thin (──) | Regular | font-weight: 400 | Body text, normal content | +| Thinnest (─) | Light | font-weight: 300 | Subtle text, de-emphasized | **Don't measure pixels—compare thickness relative to other text in the same sketch.** @@ -143,19 +152,20 @@ Current Page (About Page): **The vertical spacing between lines indicates font size—compare to UI elements** -| Spacing Relative To | Estimated Font Size | Typical Use | -|---------------------|---------------------|-------------| -| Button Height | ~40-48px | Large Heading - Page titles | -| Address Bar Height | ~32-40px | Medium Heading - Section headings | -| Between Button & Icon | ~24-32px | Small Heading - Subsection headings | -| Icon/Scrollbar Size | ~16-24px | Body text / Paragraphs | -| Half Icon Size | ~12-16px | Captions / Helper text | +| Spacing Relative To | Estimated Font Size | Typical Use | +| --------------------- | ------------------- | ----------------------------------- | +| Button Height | ~40-48px | Large Heading - Page titles | +| Address Bar Height | ~32-40px | Medium Heading - Section headings | +| Between Button & Icon | ~24-32px | Small Heading - Subsection headings | +| Icon/Scrollbar Size | ~16-24px | Body text / Paragraphs | +| Half Icon Size | ~12-16px | Captions / Helper text | **⚠️ Important:** If spacing seems disproportionately large (>2x button height), verify this is text and not an image placeholder or colored box! ### 2a. Visual Examples: Text vs. Image Confusion **TEXT - Normal spacing:** + ``` ═══════════════════════════════ ← Bold line ← ~Button Height @@ -165,11 +175,12 @@ This is clearly TEXT (H1 heading) ``` **IMAGE - Large spacing (confusion risk):** + ``` ═══════════════════════════════ ← Line? - + ← Much larger than any UI element! - + ═══════════════════════════════ ← Line? This might be an IMAGE PLACEHOLDER or COLORED BOX, not text! @@ -182,16 +193,17 @@ Ask user to confirm. **The position of line pairs within the section indicates text alignment** -| Alignment | Visual Indicator | Typical Use | -|-----------|------------------|-------------| -| **Left-aligned** | Lines start at left edge of container | Body text, lists, labels | -| **Center-aligned** | Lines centered, equal spacing both sides | Headlines, hero text, CTAs | -| **Right-aligned** | Lines end at right edge of container | Captions, metadata, prices, dates | -| **Justified** | Lines extend full width of container | Dense body text, formal content | +| Alignment | Visual Indicator | Typical Use | +| ------------------ | ---------------------------------------- | --------------------------------- | +| **Left-aligned** | Lines start at left edge of container | Body text, lists, labels | +| **Center-aligned** | Lines centered, equal spacing both sides | Headlines, hero text, CTAs | +| **Right-aligned** | Lines end at right edge of container | Captions, metadata, prices, dates | +| **Justified** | Lines extend full width of container | Dense body text, formal content | #### Visual Examples **Left-Aligned Text:** + ``` Container: | | @@ -201,6 +213,7 @@ Container: | | ``` **Center-Aligned Text:** + ``` Container: | | @@ -209,6 +222,7 @@ Container: | | ``` **Right-Aligned Text:** + ``` Container: | | @@ -217,6 +231,7 @@ Container: | | ``` **Justified/Full-Width Text:** + ``` Container: | | @@ -228,12 +243,12 @@ Container: | | ### 4. Number of Lines → Content Length -| Lines in Sketch | Content Type | Character Estimate | -|-----------------|--------------|-------------------| -| 1-2 lines | Heading/Title | 20-60 characters total | -| 3-5 lines | Short paragraph | 150-350 characters | -| 6-10 lines | Full paragraph | 400-700 characters | -| 10+ lines | Long content | 700+ characters | +| Lines in Sketch | Content Type | Character Estimate | +| --------------- | --------------- | ---------------------- | +| 1-2 lines | Heading/Title | 20-60 characters total | +| 3-5 lines | Short paragraph | 150-350 characters | +| 6-10 lines | Full paragraph | 400-700 characters | +| 10+ lines | Long content | 700+ characters | ### 4. Line-Height Calculation @@ -249,6 +264,7 @@ Line-height: 28 / 24 = 1.16 ≈ 1.2 ``` **Typical ratios:** + - **1.1-1.2** = Tight (headings) - **1.4-1.5** = Normal (body text) - **1.6-1.8** = Loose (airy text) @@ -279,12 +295,14 @@ Caption (~12px): ────────────────── ### Example 1: Landing Page Hero **Sketch shows:** + ``` ═══════════════════════════════ ← Line 1 (thick, center) ═══════════════════════════ ← Line 2 (thick, center) ``` **Analysis:** + - **Type:** Large Heading (Page Title) - **Lines:** 2 - **Line thickness:** Thickest in sketch → **Bold** (font-weight: 700) @@ -295,6 +313,7 @@ Caption (~12px): ────────────────── - **Semantic HTML:** Determined by page structure (likely H1 if page title) **Content Guidance:** + ``` English: "Welcome to Your / Dog Care Hub" (48 chars) ✅ Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅ @@ -303,6 +322,7 @@ Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅ ### Example 2: Feature Description **Sketch shows:** + ``` ───────────────────────────────────────── ← Line 1 ───────────────────────────────────────── ← Line 2 @@ -311,6 +331,7 @@ Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅ ``` **Analysis:** + - **Type:** Body text / Paragraph - **Lines:** 4 - **Line thickness:** Thinnest in sketch → **Regular** (font-weight: 400) @@ -320,26 +341,29 @@ Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅ - **Capacity:** ~60-70 chars per line = 240-280 total **Content Guidance:** + ``` -English: "Organize your family around dog care. Assign walks, track -feeding schedules, and never miss a walk again. Perfect for busy -families who want to ensure their dogs get the care they need." +English: "Organize your family around dog care. Assign walks, track +feeding schedules, and never miss a walk again. Perfect for busy +families who want to ensure their dogs get the care they need." (206 chars) ✅ -Swedish: "Organisera din familj kring hundvård. Tilldela promenader, -spåra matscheman och missa aldrig en promenad igen. Perfekt för -upptagna familjer som vill säkerställa att deras hundar får den +Swedish: "Organisera din familj kring hundvård. Tilldela promenader, +spåra matscheman och missa aldrig en promenad igen. Perfekt för +upptagna familjer som vill säkerställa att deras hundar får den vård de behöver." (218 chars) ✅ ``` ### Example 3: Button Text **Sketch shows:** + ``` [────────────] ← Single line inside button shape ``` **Analysis:** + - **Type:** Button label - **Lines:** 1 - **Line thickness:** Medium (relative) → **Semibold** (font-weight: 600) @@ -347,6 +371,7 @@ vård de behöver." (218 chars) ✅ - **Capacity:** ~8-12 characters **Content Guidance:** + ``` English: "Get Started" (11 chars) ✅ Swedish: "Kom Igång" (9 chars) ✅ @@ -359,11 +384,13 @@ Swedish: "Kom Igång" (9 chars) ✅ When analyzing sketches with text placeholders: ### Step 1: Count the Lines + ``` How many horizontal bar groups do you see? ``` ### Step 2: Compare Line Thickness → Font Weight + ``` Line thickness indicates font weight (RELATIVE comparison): - Thickest lines → Bold (font-weight: 700) @@ -374,6 +401,7 @@ Line thickness indicates font weight (RELATIVE comparison): ``` ### Step 3: Compare Distance to UI Elements → Font Size + ``` Vertical spacing relative to context anchors: - Matches Button Height → ~40-48px font (Large Heading) @@ -389,16 +417,18 @@ Semantic heading levels are determined by content structure, not appearance. ``` ### Step 4: Calculate Line-Height + ``` Line-height = Distance between lines / Font size Example: - Distance: 28px -- Font size: 24px +- Font size: 24px - Line-height: 28 / 24 = 1.16 ≈ 1.2 ``` ### Step 5: Calculate Capacity + ``` Lines × Characters-per-line = Total capacity @@ -407,6 +437,7 @@ Example: ``` ### Step 6: Generate Content Guidance + ``` "Content should be: [type], [line count] lines, ~[total chars] characters" @@ -415,6 +446,7 @@ Example: ``` ### Step 7: Validate Content + ``` If user provides content: - Count actual characters @@ -431,21 +463,25 @@ Consider shortening or increasing font size. ## Benefits of This Approach ✅ **Accurate Content Generation** + - Content matches design space - No overflow or underflow issues - Professional fit and finish ✅ **Design Fidelity** + - Specifications match sketches - Developers can trust the specs - Reduces back-and-forth ✅ **Multilingual Support** + - Can estimate if translation fits - Adjust content length per language - Prevents UI breaking ✅ **Quality Assurance** + - Catches content length issues early - Ensures consistency - Professional output @@ -461,6 +497,7 @@ Consider shortening or increasing font size. > "Looking at the profile section heading, I see 2 thick horizontal lines, center-aligned at the top. > > **Analysis:** +> > - 2 lines of text (thick bars) > - Line thickness: Thick (relative) → Bold weight > - Spacing: Less than button height → ~28-32px font @@ -471,6 +508,7 @@ Consider shortening or increasing font size. > **This heading should be:** Brief, 2 short lines, ~50-60 characters total > > **Suggested content:** +> > - EN: "Complete Your / Profile Setup" (41 chars) ✅ > - SV: "Slutför Din / Profilinställning" (45 chars) ✅ > @@ -481,6 +519,7 @@ Consider shortening or increasing font size. ## Integration with WDS Workflow This analysis happens automatically in: + - **4B: Sketch Analysis** - Initial detection - **object-types/heading-text.md** - Detailed analysis - **4C-04: Content & Languages** - Content validation @@ -490,5 +529,4 @@ This analysis happens automatically in: --- -*This guide ensures all WDS projects generate content that perfectly fits the designed space.* - +_This guide ensures all WDS projects generate content that perfectly fits the designed space._ diff --git a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md index 0ef4dacf..18aaaaf3 100644 --- a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md +++ b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md @@ -16,16 +16,19 @@ ### Cross-Page Reference Strategy **If body text was defined on the Start Page:** + - Start Page body text: Spacing matches icon size → 16px Regular - **Current page:** Similar thin lines with icon-sized spacing → **Same: 16px Regular** **Benefits:** + - ✅ Maintains visual consistency across pages - ✅ Builds design system patterns naturally - ✅ Reduces guesswork on subsequent pages - ✅ Creates coherent user experience **When to use:** + - Body text, captions, button labels (common across pages) - Navigation items (should be identical) - Form labels and inputs (standardized patterns) @@ -59,6 +62,7 @@ ``` **Context Anchors:** + - **Browser Address Bar**: ~40px height - **Standard Button**: ~40-48px height - **Cursor/Icon**: ~16-24px size @@ -75,6 +79,7 @@ ### Example: Hero Headline **Sketch:** + ``` ═══════════════════════════════ ← Line 1: Thickest lines in sketch ↕ Spacing ≈ Same as button height @@ -82,6 +87,7 @@ ``` **Analysis:** + - **Context:** Spacing looks similar to the "Sign In" button height nearby. - **Inference:** If button is ~48px, this font is ~48px (Large Heading). - **Weight:** Thicker than body text markers → **Bold**. @@ -92,29 +98,35 @@ ## Common Patterns ### Large Heading (Page Title) + ``` ═══════════════════ ← Thickest lines ↕ ═══════════════════ ``` + - **Clue:** Spacing matches Address Bar height (~40px) - **Est:** ~40-48px, Bold ### Medium Heading (Section Title) + ``` ═══════════════════ ← Medium-Thick lines ↕ ═══════════════════ ``` + - **Clue:** Spacing is slightly less than button height - **Est:** ~32px, Semibold ### Body Text (Paragraph) + ``` ───────────────────── ← Thinnest lines ↕ ───────────────────── ``` + - **Clue:** Spacing matches scrollbar width or small icon (~16-24px) - **Est:** ~16px, Regular @@ -123,23 +135,27 @@ ## ⚠️ Confusion Warning ### Text (Normal) + ``` ═══════════════════ ↕ Spacing < 2x Button Height ═══════════════════ ``` + ✅ Likely TEXT ### Image/Box (Too Large) + ``` ═══════════════════ - - + + ↕ Spacing > 2x Button Height - - + + ═══════════════════ ``` + ❓ Likely IMAGE or CONTAINER **Rule:** If spacing seems disproportionately large compared to UI elements, verify! @@ -172,6 +188,7 @@ See horizontal lines? **CONTEXT = SCALE** Think of it like looking at a map: + - Use the scale key (buttons, bars) to measure distances. - Don't guess miles (pixels) without a reference! @@ -186,11 +203,13 @@ Think of it like looking at a map: ``` **Analysis:** + - Thickness: Bold (relative to body lines) - Distance: Matches button (~48px) - Result: `font: bold 48px / 1.2` **Content:** + ``` EN: "Every walk. on time. Every time." SE: "Varje promenad. i tid. Varje gång." @@ -201,6 +220,3 @@ Both fit in ~50-60 character capacity! ✅ --- **Remember: Context is King! Compare, don't just measure.** 📏✨ - - - diff --git a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-STRATEGY.md b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-STRATEGY.md index 0488e294..ff88cc6c 100644 --- a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-STRATEGY.md +++ b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-STRATEGY.md @@ -22,6 +22,7 @@ ``` **When to use:** + - Headlines (H1, H2, H3) - Button labels - Navigation items @@ -51,6 +52,7 @@ ``` **When to use:** + - Body paragraphs - Long descriptions - Feature lists (when wording TBD) @@ -85,6 +87,7 @@ ``` **Result:** + - Headlines provide content guidance - Body text shows sizing and capacity - Buttons show clear actions @@ -129,6 +132,7 @@ ### Agent Analysis **Agent reads:** + 1. **Logo text:** "Dog Week" → suggests as logo content 2. **H1 actual text:** "Every walk. on time. Every time." → suggests as starting headline 3. **Marker analysis:** 2 thin lines → body text, spacing matches icon size (~16-20px), ~120-140 chars @@ -137,6 +141,7 @@ 6. **Marker analysis:** 3 thin lines → feature description, spacing matches icon size (~16-20px), ~180-210 chars **Agent output:** + ``` I found text in your sketch: "Every walk. on time. Every time." @@ -147,6 +152,7 @@ SE: [Your Swedish translation] ``` **User can:** + - ✅ Keep the sketch text - ✅ Change it completely - ✅ Refine it slightly @@ -188,6 +194,7 @@ SE: [Your Swedish translation] ``` **Analysis:** + - Thickness: Bold (relative to other text) - Distance: Matches button height (~40-48px) - Lines: 2 @@ -200,18 +207,20 @@ SE: [Your Swedish translation] ### When Sketch Has Actual Text **Agent says:** + ``` I found text in your sketch: "Every walk. on time." Content for Primary Headline: EN: Every walk. on time. -SE: +SE: (You can keep the sketch text or change it) ``` **Benefits:** + - Pre-filled starting point - Still editable - Saves time @@ -220,6 +229,7 @@ SE: ### When Sketch Has Line Markers **Agent says:** + ``` Text placeholder detected: - 4 horizontal lines @@ -235,11 +245,13 @@ EN: ``` **User provides:** + ``` EN: Organize your family around dog care. Assign walks, track feeding schedules, and never miss a walk again. ``` **Agent suggests:** + ``` Great! Here are translation suggestions: @@ -249,6 +261,7 @@ Does this work, or would you like to adjust it? ``` **Benefits:** + - Clear capacity guidance - Agent suggests translations - User reviews and confirms @@ -261,7 +274,9 @@ Does this work, or would you like to adjust it? When AI analyzes sketch text markers, the workflow is: ### Step 1: AI Analyzes Sketch + Agent detects text markers and estimates properties: + ``` Line thickness: Thicker than body text → Bold font weight Spacing between pairs: Similar to button height → ~40-48px font size estimate @@ -270,30 +285,37 @@ Character capacity: ~35 characters per line ``` ### Step 2: AI Presents Estimates with Reasoning + Agent shows analysis WITH explanation of how estimates were derived: + ```markdown -- **Style**: +- **Style**: - Font weight: Bold (from thick line markers, relative to body text) - Font size: 42px (est. from spacing matching button height) - Line-height: 1.2 (est. calculated as font-size × 1.2) ``` **Why show reasoning?** + - Designer understands **how** AI interpreted the sketch - Designer can judge if estimation logic makes sense - Makes it easy to adjust if sketch measurements were different - Builds trust through transparency ### Step 3: Designer Confirms/Adjusts + Designer reviews estimates and either: + 1. **Confirms** - "Yes, 42px based on button-height spacing is correct" 2. **Adjusts** - "Actually, the spacing is larger, make it 48px instead" 3. **Overrides** - "Ignore the sketch measurements, I want it to be 56px" ### Step 4: Finalize Specification + Agent updates spec with confirmed values, removes estimation notes: + ```markdown -- **Style**: +- **Style**: - Font weight: Bold - Font size: 48px - Line-height: 1.15 @@ -301,7 +323,8 @@ Agent updates spec with confirmed values, removes estimation notes: Clean, production-ready specification with no estimation artifacts. -**Key Principle:** +**Key Principle:** + - **All estimated values are spelled out explicitly** (not hidden) - **Marked with (est.) label** to indicate AI interpretation - **Designer confirms or adjusts** each estimated value @@ -359,6 +382,7 @@ This ensures **transparency** about which values came from AI sketch analysis vs ### During Sketching **Designer:** + ``` 1. Draw page layout 2. Add ACTUAL TEXT for headlines/buttons @@ -370,6 +394,7 @@ This ensures **transparency** about which values came from AI sketch analysis vs ### During Specification (Phase 4) **Agent:** + ``` 1. Analyze sketch 2. Read any actual text found @@ -381,6 +406,7 @@ This ensures **transparency** about which values came from AI sketch analysis vs ``` **User:** + ``` 1. See sketch text as suggestion 2. Keep, change, or refine @@ -413,7 +439,7 @@ SE: Varje promenad. i tid. Varje gång. These are my suggestions. Do they work? 1. Use these translations -2. Adjust translations +2. Adjust translations 3. Manual input Choice [1/2/3]: @@ -432,9 +458,11 @@ Or refines: SE: Varje promenad. Punktligt. Varje gång. ← Adjusted ``` -EN: Every walk. on time. Every time. ← Keeps it! + +EN: Every walk. on time. Every time. ← Keeps it! SE: Varje promenad. i tid. Varje gång. -``` + +```` ### Specification Result: @@ -447,7 +475,7 @@ SE: Varje promenad. i tid. Varje gång. - **Content**: - EN: "Every walk. on time. Every time." - SE: "Varje promenad. i tid. Varje gång." -``` +```` **Result:** Sketch text became final content! ✅ @@ -455,20 +483,22 @@ SE: Varje promenad. i tid. Varje gång. ## Summary -| Element Type | Sketch Method | Agent Behavior | -|--------------|---------------|----------------| -| **Headlines** | Actual text | Reads & suggests as starting content | -| **Buttons** | Actual text | Reads & suggests as button label | -| **Navigation** | Actual text | Reads & suggests as nav items | -| **Body paragraphs** | Line markers | Analyzes for size/capacity, requests content | -| **Descriptions** | Line markers | Analyzes for size/capacity, requests content | +| Element Type | Sketch Method | Agent Behavior | +| ------------------- | ------------- | -------------------------------------------- | +| **Headlines** | Actual text | Reads & suggests as starting content | +| **Buttons** | Actual text | Reads & suggests as button label | +| **Navigation** | Actual text | Reads & suggests as nav items | +| **Body paragraphs** | Line markers | Analyzes for size/capacity, requests content | +| **Descriptions** | Line markers | Analyzes for size/capacity, requests content | **Golden Rule:** + - **Important/short text** = Draw actual text - **Long/placeholder text** = Use line markers - **Mix both** for best results **Remember:** + - Sketch text is a suggestion, not final - Agent will ask to confirm or change - Refinement happens during specification @@ -477,4 +507,3 @@ SE: Varje promenad. i tid. Varje gång. --- **Use actual text for headlines, markers for body text!** 📝✨ - diff --git a/src/modules/wds/workflows/4-ux-design/STORYBOARD-INTEGRATION.md b/src/modules/wds/workflows/4-ux-design/STORYBOARD-INTEGRATION.md index 23995eca..4484d14c 100644 --- a/src/modules/wds/workflows/4-ux-design/STORYBOARD-INTEGRATION.md +++ b/src/modules/wds/workflows/4-ux-design/STORYBOARD-INTEGRATION.md @@ -9,6 +9,7 @@ Complex interactive components (calendars, booking systems, multi-step workflows) have **state transitions** and **interaction flows** that are difficult to describe in text alone. **Storyboards** provide visual, sequential documentation of: + - State transitions (e.g., Empty → Booked → Active → Completed) - User interactions and system responses - Time-based changes (countdowns, timers) @@ -23,6 +24,7 @@ Complex interactive components (calendars, booking systems, multi-step workflows **Purpose:** Show how a component changes states over time **Example:** Dog Week Walk Booking States + ``` ┌─────────────────────────────────────────────────┐ │ State Transition Storyboard │ @@ -57,6 +59,7 @@ Complex interactive components (calendars, booking systems, multi-step workflows **Purpose:** Show step-by-step user interactions **Example:** Calendar Booking Flow + ``` Frame 1: User views calendar Frame 2: User taps "Book" button @@ -70,6 +73,7 @@ Frame 5: Week overview quarter circle turns gray **Purpose:** Show how multiple components interact **Example:** Week View + Leaderboard + Calendar Sync + ``` Frame 1: User clicks day circle in week overview Frame 2: Calendar scrolls to that day @@ -84,11 +88,11 @@ Frame 5: Leaderboard count increments ### Where Storyboards Belong -| File Type | Contains Storyboard? | Purpose | -|-----------|---------------------|---------| -| **Pages/** | ❌ No | Page layout only | -| **Components/** | ⚠️ Visual states only | Static appearance of each state | -| **Features/** | ✅ YES | State transitions & interaction flows | +| File Type | Contains Storyboard? | Purpose | +| --------------- | --------------------- | ------------------------------------- | +| **Pages/** | ❌ No | Page layout only | +| **Components/** | ⚠️ Visual states only | Static appearance of each state | +| **Features/** | ✅ YES | State transitions & interaction flows | ### Storyboard Storage @@ -147,19 +151,23 @@ Manages walk slot state transitions, user booking interactions, and automatic ti **Visual Reference:** Storyboard Frame 1 **Appearance:** + - White background - Dog avatar only (no user avatar) - Time range: "8-11" - Action button: "Book" / "Boka" **Triggers:** + - Initial state for all unbooked slots - Appears when walk is unbooked **Transitions:** + - User clicks "Book" → GRAY (Booked) **Business Rules:** + - Any family member can book - Booking awards +1 leaderboard point - Updates week overview quarter circle to gray @@ -171,6 +179,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti **Visual Reference:** Storyboard Frame 2 **Appearance:** + - Gray background - Dog avatar + User avatar overlay - Names: "Rufus & Patrick" @@ -178,14 +187,17 @@ Manages walk slot state transitions, user booking interactions, and automatic ti - No action button (tap card for details) **Triggers:** + - User books empty slot (WHITE → GRAY) - Walk is scheduled but time window not yet open **Transitions:** + - Time window opens (8:00 arrives) → ORANGE (Countdown) - User unbooks walk → WHITE (Empty) **Business Rules:** + - Shows who booked the walk - Tap card to view details/unbook - Leaderboard point already awarded @@ -197,6 +209,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti **Visual Reference:** Storyboard Frame 3 **Appearance:** + - Orange background - Dog avatar only (user avatar removed) - Countdown timer: "32 min left" / "32 min kvar" @@ -204,14 +217,17 @@ Manages walk slot state transitions, user booking interactions, and automatic ti - Action button: "Start" / "Starta" **Triggers:** + - Scheduled time arrives (8:00) → GRAY to ORANGE - Real-time countdown updates every minute **Transitions:** + - User clicks "Start" → BLUE (In Progress) - Countdown reaches 0 (11:00) → RED (Missed) **Business Rules:** + - Countdown shows time remaining in window - Urgency indicator (warning icon) - Can only start if no other walk active for this dog @@ -223,6 +239,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti **Visual Reference:** Storyboard Frame 4 **Appearance:** + - Blue background - Dog avatar + User avatar overlay - Status: "Started 09:32 • 23 min ago" @@ -230,13 +247,16 @@ Manages walk slot state transitions, user booking interactions, and automatic ti - No action button (tap card for completion) **Triggers:** + - User starts walk (ORANGE → BLUE) - Real-time duration updates every minute **Transitions:** + - User completes walk → GREEN (Completed) **Business Rules:** + - Blocks other walks for this dog - Shows elapsed time since start - Tap card to complete walk or view progress @@ -248,6 +268,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti **Visual Reference:** Storyboard Frame 5 **Appearance:** + - Green background - Dog avatar + User avatar overlay - Duration: "32 min walk" / "32 min promenad" @@ -255,12 +276,15 @@ Manages walk slot state transitions, user booking interactions, and automatic ti - No action button **Triggers:** + - User completes active walk (BLUE → GREEN) **Transitions:** + - None (final successful state) **Business Rules:** + - Permanent record of completed walk - Shows actual walk duration - Unblocks dog for next walk @@ -272,6 +296,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti **Visual Reference:** Storyboard Frame 6 **Appearance:** + - Red background - Dog avatar only (no user avatar) - Message: "No walk registered" / "Ingen promenad registrerad" @@ -279,12 +304,15 @@ Manages walk slot state transitions, user booking interactions, and automatic ti - No action button **Triggers:** + - Countdown expires without walk being started (ORANGE → RED) **Transitions:** + - None (permanent accountability record) **Business Rules:** + - Cannot be changed or deleted - Leaderboard point remains (no penalty) - Shows who booked but didn't complete @@ -298,35 +326,29 @@ Manages walk slot state transitions, user booking interactions, and automatic ti **Storyboard:** `Storyboards/booking-flow.jpg` **Steps:** + 1. **User views empty slot** (WHITE state) - Sees "Book" button - 2. **User taps "Book"** - System validates user is family member - System creates booking record - 3. **Immediate updates:** - Card → GRAY state - Leaderboard: User +1 point - Week overview: Quarter circle → gray - 4. **Time window opens** (8:00 arrives) - Card → ORANGE state - Countdown timer starts - 5. **User taps "Start"** - System validates no other active walk for dog - System records start time - 6. **Immediate updates:** - Card → BLUE state - Duration counter starts - Other walks for dog → disabled - 7. **User completes walk** (via Walk Details page) - System records completion time - System calculates duration - 8. **Immediate updates:** - Card → GREEN state - Week overview: Quarter circle → green @@ -339,6 +361,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti **Storyboard:** `Storyboards/missed-walk-flow.jpg` **Steps:** + 1. Walk booked (GRAY state) 2. Time window opens (ORANGE state) 3. Countdown timer runs @@ -354,11 +377,13 @@ Manages walk slot state transitions, user booking interactions, and automatic ti **Storyboard:** `Storyboards/calendar-sync-flow.jpg` **Components Involved:** + - Week Overview (top section) - Leaderboard (middle section) - Booking Calendar (bottom section) **Sync Flow:** + 1. User books walk in calendar 2. **Sync 1:** Week overview quarter circle updates 3. **Sync 2:** Leaderboard count increments @@ -370,8 +395,8 @@ Manages walk slot state transitions, user booking interactions, and automatic ti --- ## State Machine Diagram - ``` + ┌─────────────┐ │ WHITE │ │ (Empty) │ @@ -407,6 +432,7 @@ Manages walk slot state transitions, user booking interactions, and automatic ti │ ▼ [END] + ``` --- @@ -449,12 +475,14 @@ Don't need storyboards for: Number frames sequentially: ``` + 1. Initial state 2. After user action 3. System response 4. Next state 5. Alternative path -``` + +```` ### Storyboard Annotations @@ -547,7 +575,7 @@ Include: ## Error Handling {Error states, recovery flows, etc.} -``` +```` --- @@ -579,12 +607,14 @@ Features/ ### 1. Visual Clarity **Before (Text only):** + ``` -When the user books a walk, the card changes to gray, +When the user books a walk, the card changes to gray, the leaderboard updates, and the week overview changes. ``` **After (With storyboard):** + ``` See Storyboard Frame 2-3 for visual state transition. ``` @@ -592,6 +622,7 @@ See Storyboard Frame 2-3 for visual state transition. ### 2. Developer Understanding Developers can: + - See exact visual states - Understand transition triggers - Identify edge cases visually @@ -600,6 +631,7 @@ Developers can: ### 3. Design Consistency Designers can: + - Ensure all states are visually distinct - Verify state transitions make sense - Spot missing states or transitions @@ -608,6 +640,7 @@ Designers can: ### 4. QA Testing QA can: + - Use storyboard as test script - Verify all states are implemented - Test all transition paths @@ -620,6 +653,7 @@ QA can: ### Step 1: Sketch Storyboard During UX design phase: + 1. Identify complex interactive components 2. Sketch state transitions on paper/whiteboard 3. Number frames sequentially @@ -643,6 +677,7 @@ Features/Storyboards/{component-name}-{type}.jpg ### Step 4: Document States For each frame in storyboard: + - Create state definition - Link to storyboard frame number - Describe triggers and transitions @@ -656,17 +691,20 @@ Convert storyboard to ASCII state machine diagram for quick reference ## Summary **Storyboards are essential for:** + - 🎯 Complex state machines (calendars, booking systems) - 🎯 Multi-step workflows (onboarding, checkout) - 🎯 Time-based interactions (countdowns, timers) - 🎯 Multi-component synchronization **Store storyboards in:** + - `Features/Storyboards/` folder - Reference from Feature files - Link to specific frames in state definitions **Benefits:** + - ✅ Visual clarity for developers - ✅ Design consistency - ✅ QA test scripts diff --git a/src/modules/wds/workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md b/src/modules/wds/workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md index 639c2bef..8ec0d22c 100644 --- a/src/modules/wds/workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md +++ b/src/modules/wds/workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md @@ -11,6 +11,7 @@ This guide explains how to organize text content and translations in WDS specifications using **purpose-based naming** and **grouped translation** patterns. **Related Documentation:** + - **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** - How to analyze text markers in sketches - **`HTML-VS-VISUAL-STYLES.md`** - HTML tags vs visual text styles - **`WDS-SPECIFICATION-PATTERN.md`** - Complete specification format with examples @@ -22,16 +23,22 @@ This guide explains how to organize text content and translations in WDS specifi ### 1. Name by PURPOSE, Not Content **❌ WRONG:** + ```markdown #### Welcome Heading + **OBJECT ID**: `start-hero-welcome-heading` + - Content: "Welcome to Dog Week" ``` **✅ CORRECT:** + ```markdown #### Primary Headline + **OBJECT ID**: `start-hero-headline` + - Content: - EN: "Welcome to Dog Week" - SE: "Välkommen till Dog Week" @@ -44,11 +51,12 @@ This guide explains how to organize text content and translations in WDS specifi ### 2. Separate Structure from Content **Structure (Position/Style):** + ```markdown - **HTML Tag**: h1 (semantic structure for SEO/accessibility) - **Visual Style**: Hero headline (from Design System) - **Position**: Center of hero section, above CTA -- **Style**: +- **Style**: - Font weight: Bold (from 3px thick line markers) - Font size: 42px (est. from 24px spacing between line pairs) - Line-height: 1.2 (est. calculated from font size) @@ -58,14 +66,15 @@ This guide explains how to organize text content and translations in WDS specifi > **Important:** HTML tags (h1-h6) define semantic structure for SEO/accessibility. Visual styles (Hero headline, Main header, Sub header, etc.) define appearance and can be applied to any HTML tag. > **Note:** Values marked `(est. from...)` show sketch analysis reasoning. Designer should confirm or adjust these values, then update with actual specifications. -``` + +```` **Content (Translations):** ```markdown - **Content**: - EN: "Every walk. on time. Every time." - SE: "Varje promenad. i tid. Varje gång." -``` +```` **Why:** Structure rarely changes, content often does. Keeps specs clean. @@ -74,33 +83,44 @@ This guide explains how to organize text content and translations in WDS specifi ### 3. Group Related Translations **❌ WRONG (Scattered):** + ```markdown #### Headline EN + "Every walk. on time." #### Headline SE + "Varje promenad. i tid." #### Body EN + "Organize your family..." #### Body SE + "Organisera din familj..." ``` **✅ CORRECT (Grouped):** + ```markdown ### Hero Object + **Purpose**: Primary value proposition #### Primary Headline + **OBJECT ID**: `start-hero-headline` + - **Content**: - EN: "Every walk. on time. Every time." - SE: "Varje promenad. i tid. Varje gång." #### Supporting Text + **OBJECT ID**: `start-hero-supporting` + - **Content**: - EN: "Organize your family around dog care." - SE: "Organisera din familj kring hundvård." @@ -116,10 +136,13 @@ This guide explains how to organize text content and translations in WDS specifi ```markdown ### Hero Object + **Purpose**: Primary value proposition and main conversion action #### Primary Headline + **OBJECT ID**: `start-hero-headline` + - **Component**: H1 heading (`.text-heading-1`) - **Position**: Center of hero, top of section - **Style**: Bold, no italic, 42px, line-height 1.2 @@ -129,7 +152,9 @@ This guide explains how to organize text content and translations in WDS specifi - SE: "Varje promenad. i tid. Varje gång." #### Supporting Text + **OBJECT ID**: `start-hero-supporting` + - **Component**: Body text (`.text-body`) - **Position**: Below headline, above CTA - **Style**: Regular, 16px, line-height 1.5 @@ -139,7 +164,9 @@ This guide explains how to organize text content and translations in WDS specifi - SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen." #### Primary CTA Button + **OBJECT ID**: `start-hero-cta` + - **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md) - **Position**: Center, below supporting text - **Behavior**: Navigate to registration @@ -151,11 +178,13 @@ This guide explains how to organize text content and translations in WDS specifi **Reading Experience:** **English:** + > Every walk. on time. Every time. > Organize your family around dog care. Never miss a walk again. > [start planning - free forever] **Swedish:** + > Varje promenad. i tid. Varje gång. > Organisera din familj kring hundvård. Missa aldrig en promenad igen. > [börja planera - gratis för alltid] @@ -168,10 +197,13 @@ Each language flows naturally as a complete message! ```markdown ### Sign In Form + **Purpose**: User authentication #### Email Label + **OBJECT ID**: `signin-form-email-label` + - **Component**: Label text (`.text-label`) - **Position**: Above email input field - **For**: `signin-form-email-input` @@ -180,14 +212,18 @@ Each language flows naturally as a complete message! - SE: "E-postadress" #### Email Input + **OBJECT ID**: `signin-form-email-input` + - **Component**: [Text Input](/docs/.../text-input.md) - **Placeholder**: - EN: "your@email.com" - SE: "din@epost.com" #### Password Label + **OBJECT ID**: `signin-form-password-label` + - **Component**: Label text (`.text-label`) - **Position**: Above password input - **For**: `signin-form-password-input` @@ -196,7 +232,9 @@ Each language flows naturally as a complete message! - SE: "Lösenord" #### Password Input + **OBJECT ID**: `signin-form-password-input` + - **Component**: [Password Input](/docs/.../password-input.md) - **Placeholder**: - EN: "Enter your password" @@ -209,10 +247,13 @@ Each language flows naturally as a complete message! ```markdown ### Validation Messages + **Purpose**: User feedback on form errors #### Email Required Error + **OBJECT ID**: `signin-form-email-error-required` + - **Component**: Error text (`.text-error`) - **Position**: Below email input field - **Trigger**: When email field is empty on submit @@ -221,7 +262,9 @@ Each language flows naturally as a complete message! - SE: "E-postadress krävs" #### Email Invalid Error + **OBJECT ID**: `signin-form-email-error-invalid` + - **Component**: Error text (`.text-error`) - **Position**: Below email input field - **Trigger**: When email format is invalid @@ -230,7 +273,9 @@ Each language flows naturally as a complete message! - SE: "Ange en giltig e-postadress" #### Auth Failed Error + **OBJECT ID**: `signin-form-auth-error` + - **Component**: Alert banner (`.alert-error`) - **Position**: Above form, below page heading - **Trigger**: When authentication fails @@ -246,12 +291,14 @@ Each language flows naturally as a complete message! ### Format: `{page}-{section}-{purpose}` **Page Examples:** + - `start` (start/landing page) - `signin` (sign in page) - `profile` (profile page) - `calendar` (calendar page) **Section Examples:** + - `hero` (hero section) - `header` (page header) - `form` (form section) @@ -259,6 +306,7 @@ Each language flows naturally as a complete message! - `footer` (page footer) **Purpose Examples:** + - `headline` (main heading) - `subheading` (secondary heading) - `description` (descriptive text) @@ -269,6 +317,7 @@ Each language flows naturally as a complete message! - `supporting` (supporting/helper text) **Complete Examples:** + - `start-hero-headline` - `signin-form-email-label` - `profile-success-message` @@ -283,15 +332,17 @@ Each language flows naturally as a complete message! ```markdown #### {{Purpose_Title}} + **OBJECT ID**: `{{page-section-purpose}}` + - **Component**: {{component_type}} ({{class_or_reference}}) - **Position**: {{position_description}} - **Content**: - EN: "{{english_content}}" - SE: "{{swedish_content}}" - {{#if additional_languages}} + {{#if additional_languages}} - {{lang}}: "{{content}}" - {{/if}} + {{/if}} ``` ### Optional Fields @@ -347,15 +398,18 @@ Each language flows naturally as a complete message! **Hero Object Translations:** #### Primary Headline + - EN: "Every walk. on time. Every time." - SE: "Varje promenad. i tid. Varje gång." #### Supporting Text + - EN: "Organize your family around dog care." - SE: "Organisera din familj kring hundvård." ``` Translator can: + - Read entire section in each language - Ensure translations flow together - See context immediately @@ -372,19 +426,22 @@ const supportingText = document.getElementById('start-hero-supporting'); const content = { 'start-hero-headline': { en: 'Every walk. on time. Every time.', - se: 'Varje promenad. i tid. Varje gång.' - } + se: 'Varje promenad. i tid. Varje gång.', + }, }; ``` ### ✅ For Maintainability **Content changes:** + ```markdown #### Primary Headline -**OBJECT ID**: `start-hero-headline` ← Stays same + +**OBJECT ID**: `start-hero-headline` ← Stays same + - **Content**: - - EN: "NEW CONTENT HERE" ← Easy to update + - EN: "NEW CONTENT HERE" ← Easy to update - SE: "NYTT INNEHÅLL HÄR" ``` @@ -402,14 +459,17 @@ All translations grouped so each language reads coherently: ### Hero Object #### Headline + - EN: "Every walk. on time." - SE: "Varje promenad. i tid." #### Body + - EN: "Never miss a walk again." - SE: "Missa aldrig en promenad." #### CTA + - EN: "Get Started" - SE: "Kom Igång" ``` @@ -423,10 +483,12 @@ All translations grouped so each language reads coherently: ### Feature Card 1 #### Feature Title + - EN: "Smart Scheduling" - SE: "Smart Schemaläggning" #### Feature Description + - EN: "Automatically assign walks based on family availability." - SE: "Tilldela promenader automatiskt baserat på familjetillgänglighet." ``` @@ -449,6 +511,3 @@ Before finalizing text specifications: --- **This pattern ensures professional, maintainable, translation-friendly specifications across all WDS projects!** 🌍✨ - - - diff --git a/src/modules/wds/workflows/4-ux-design/WDS-SPECIFICATION-PATTERN.md b/src/modules/wds/workflows/4-ux-design/WDS-SPECIFICATION-PATTERN.md index ba8910ba..2a271a4d 100644 --- a/src/modules/wds/workflows/4-ux-design/WDS-SPECIFICATION-PATTERN.md +++ b/src/modules/wds/workflows/4-ux-design/WDS-SPECIFICATION-PATTERN.md @@ -11,6 +11,7 @@ This document defines the **WDS Specification Pattern** used in Phase 4 (UX Desi **Dog Week Start Page** is used as the example implementation to demonstrate the pattern in action. **Related Documentation:** + - **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** - How sketch analysis values are derived - **`HTML-VS-VISUAL-STYLES.md`** - HTML tags vs visual text styles - **`TRANSLATION-ORGANIZATION-GUIDE.md`** - Purpose-based text organization @@ -20,15 +21,20 @@ This document defines the **WDS Specification Pattern** used in Phase 4 (UX Desi ## Key Principles ### 1. Purpose-Based Naming + Text objects are named by **function, not content**: + - ✅ `hero-headline` (describes purpose) - ❌ `welcome-message` (describes content) ### 2. Grouped Translations + All product languages grouped together per object for coherent review. ### 3. Estimated Values from Sketch Analysis + When text properties are estimated from sketch markers: + - **Spell out the values explicitly** (e.g., `42px (est. from 24px spacing)`) - **Mark with analysis note** to show reasoning - **Designer confirms or adjusts** during specification dialog @@ -46,6 +52,7 @@ This ensures transparency about which values came from AI interpretation vs. des ```markdown ### Hero Object + **Purpose**: Primary value proposition and main conversion action #### Primary Headline @@ -53,10 +60,12 @@ This ensures transparency about which values came from AI interpretation vs. des **OBJECT ID**: `start-hero-headline` **HTML Structure:** + - **Tag**: h1 - **Semantic Purpose**: Main page heading for SEO and accessibility **Visual Style:** + - **Style Name**: Hero headline - **Font weight**: Bold (from 3px thick line markers in sketch) - **Font size**: 56px (est. from 32px vertical spacing between line pairs) @@ -70,6 +79,7 @@ This ensures transparency about which values came from AI interpretation vs. des **Behavior**: Updates with language toggle **Content**: + - EN: "Every walk. on time. Every time." - SE: "Varje promenad. i tid. Varje gång." @@ -80,10 +90,12 @@ This ensures transparency about which values came from AI interpretation vs. des **OBJECT ID**: `start-hero-supporting` **HTML Structure:** + - **Tag**: p - **Semantic Purpose**: Paragraph text providing additional context **Visual Style:** + - **Style Name**: Body text large - **Font weight**: Regular (from 1px thin line markers in sketch) - **Font size**: 18px (est. from 14px vertical spacing between line pairs) @@ -96,13 +108,16 @@ This ensures transparency about which values came from AI interpretation vs. des **Behavior**: Updates with language toggle **Content**: + - EN: "Organize your family around dog care. Never miss a walk again." - SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen." > **Sketch Analysis:** Line thickness (1px) → Regular weight. Line spacing (14px) → ~18px font size estimate. Designer should confirm these values. #### Primary CTA Button + **OBJECT ID**: `start-hero-cta` + - **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md) - **Position**: Center, below supporting text, 24px margin-top - **Behavior**: Navigate to /auth/signup @@ -113,11 +128,13 @@ This ensures transparency about which values came from AI interpretation vs. des ``` **Reading in English:** + > **Every walk. on time. Every time.** > Organize your family around dog care. Never miss a walk again. > [start planning - free forever] **Reading in Swedish:** + > **Varje promenad. i tid. Varje gång.** > Organisera din familj kring hundvård. Missa aldrig en promenad igen. > [börja planera - gratis för alltid] @@ -127,6 +144,7 @@ This ensures transparency about which values came from AI interpretation vs. des ## The Complete Process ### Step 1: Sketch Analysis (4B) + ``` Agent sees sketch with horizontal lines: @@ -142,11 +160,12 @@ Agent sees sketch with horizontal lines: Agent identifies: 1. TEXT GROUP (2 thick lines) - Hero headline -2. TEXT GROUP (2 thin lines) - Supporting text +2. TEXT GROUP (2 thin lines) - Supporting text 3. BUTTON - CTA ``` ### Step 2: Object Detection (4C-03 + object-router) + ``` For Object 1: → Detects horizontal lines @@ -162,6 +181,7 @@ heading-text.md: ``` ### Step 3: Content with Grouped Translations + ``` Agent asks: @@ -181,15 +201,18 @@ Do these work? [1] Use these [2] Adjust [3] Manual" User provides: 1 ← Accepts suggestions! -Agent validates: +Agent validates: ✅ EN: 37 chars (fits 60 capacity) ✅ SE: 36 chars (fits 60 capacity) ``` ### Step 4: Generate Specification + ```markdown #### Primary Headline + **OBJECT ID**: `start-hero-headline` + - **Component**: H1 heading - **Position**: Center of hero - **Style**: Bold, 42px, line-height 1.2 @@ -205,11 +228,13 @@ Agent validates: ### 1. Purpose-Based Object IDs **Stable Naming:** + - Content changes don't affect Object IDs - IDs remain semantic and meaningful - Easy to find by function **Examples:** + ```markdown `start-hero-headline` ← Purpose clear `signin-form-email-label` ← Function clear @@ -219,6 +244,7 @@ Agent validates: ### 2. Separated Concerns **Structure/Style** (rarely changes): + ```markdown - **Component**: H1 heading - **Position**: Center of hero @@ -226,6 +252,7 @@ Agent validates: ``` **Content** (often changes): + ```markdown - **Content**: - EN: "..." @@ -235,24 +262,29 @@ Agent validates: ### 3. Grouped Translations **Benefits:** + - Each language reads as complete message - Translator sees full context - Natural language flow - Easy to verify coherence **Format:** + ```markdown ### Text Group #### Element 1 + - EN: "..." - SE: "..." #### Element 2 + - EN: "..." - SE: "..." #### Element 3 + - EN: "..." - SE: "..." ``` @@ -260,6 +292,7 @@ Agent validates: ### 4. Character Capacity Validation **From Sketch Analysis:** + ``` Agent: "Sketch shows 2 lines, ~50-60 chars capacity" @@ -269,6 +302,7 @@ Agent: "✅ Content fits within sketch capacity!" ``` **If too long:** + ``` Agent: "⚠️ Your content (85 chars) exceeds capacity (60 chars). Consider shortening or adjusting font size." @@ -314,24 +348,26 @@ Consider shortening or adjusting font size." ```markdown #### {{Purpose_Title}} + **OBJECT ID**: `{{page-section-purpose}}` + - **Component**: {{type}} ({{class_or_ref}}) - **Position**: {{position_description}} -{{#if has_behavior}} + {{#if has_behavior}} - **Behavior**: {{behavior_description}} -{{/if}} -{{#if has_style_details}} + {{/if}} + {{#if has_style_details}} - **Style**: {{style_specifications}} -{{/if}} -{{#if links_to_input}} + {{/if}} + {{#if links_to_input}} - **For**: {{input_object_id}} -{{/if}} + {{/if}} - **Content**: - EN: "{{english_text}}" - SE: "{{swedish_text}}" - {{#each additional_language}} + {{#each additional_language}} - {{code}}: "{{text}}" - {{/each}} + {{/each}} ``` --- @@ -341,16 +377,21 @@ Consider shortening or adjusting font size." These follow the exact pattern we're implementing: **From 1.1-Start-Page.md:** + ```markdown #### Primary Headline + **OBJECT ID**: `start-hero-headline` + - **Component**: H1 heading (`.text-heading-1`) - **Content**: - EN: "Every walk. on time. Every time." - SE: "Varje promenad. i tid. Varje gång." #### Primary CTA Button + **OBJECT ID**: `start-hero-cta` + - **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md) - **Content**: - EN: "start planning - free forever" @@ -358,11 +399,14 @@ These follow the exact pattern we're implementing: ``` **From 1.2-Sign-In.md (Header example):** + ```markdown -#### Sign In Button +#### Sign In Button + **OBJECT ID**: `start-header-signin` + - **Component**: [Button Secondary](/docs/D-Design-System/.../Button-Secondary.md) -- **Content**: +- **Content**: - EN: "Sign in" - SE: "Logga in" - **Behavior**: Navigate to sign-in page @@ -390,4 +434,3 @@ For each text element: --- **This is the WDS standard for text specifications, proven by Dog Week!** 🎨🌍✨ - diff --git a/src/modules/wds/workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md b/src/modules/wds/workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md index 6bbc3bbb..896f2b3c 100644 --- a/src/modules/wds/workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md +++ b/src/modules/wds/workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md @@ -11,6 +11,7 @@ ### Example: Transparent Pricing Feature **Trigger Map Reasoning:** + ``` TARGET GROUP: Budget-conscious customers FEAR: Surprises and hidden costs @@ -20,23 +21,25 @@ SOLUTION: Transparent price model explanation ``` **This WHY flows into specifications:** + ```markdown ## Transparent Pricing Component **WHY This Exists:** -Our main target group is afraid of surprises and hidden costs. -By explaining our transparent price model, the customer has an +Our main target group is afraid of surprises and hidden costs. +By explaining our transparent price model, the customer has an easier time committing to the purchase. **WHY Upfront (Not at Checkout):** -Anxiety happens early. Showing pricing transparency upfront +Anxiety happens early. Showing pricing transparency upfront reduces fear before it builds. **WHY Detailed Breakdown (Not Just Total):** -"No hidden costs" needs proof. Itemized breakdown shows +"No hidden costs" needs proof. Itemized breakdown shows there's nothing hidden. **WHAT NOT TO DO:** + - ❌ Don't hide pricing until checkout (increases anxiety) - ❌ Don't show just total (doesn't prove transparency) - ❌ Don't use fine print (contradicts "transparent") @@ -49,6 +52,7 @@ there's nothing hidden. ## The Problem with v4 WPS2C (Whiteport Sketch-to-Code) **What happened:** + ``` Designer: "Create a calendar for booking dog walks" AI: *Runs with it* @@ -56,6 +60,7 @@ Result: Generic calendar, missing the point ``` **What was missing:** + - No questioning to elevate thinking - No capture of WHY decisions were made - No understanding of business context @@ -68,6 +73,7 @@ Result: Generic calendar, missing the point ## The AI Habit Problem **AI's default behavior:** + ``` "I'll make this faster!" "I'll make this better!" @@ -75,6 +81,7 @@ Result: Generic calendar, missing the point ``` **What AI misses:** + - WHY does this need to exist? - WHO is this actually for? - WHAT problem does this solve? @@ -92,18 +99,21 @@ Result: Generic calendar, missing the point ## Calendar Component **Features:** + - Week view - Booking slots - Color-coded states - Countdown timers **Visual:** + - 7 columns (days) - 6 color states - Timer in orange state ``` **Problem:** AI will implement this literally, but might: + - Add daily/monthly views ("better!") - Add notifications ("helpful!") - Make it generic ("reusable!") @@ -117,17 +127,18 @@ Result: Generic calendar, missing the point ## Calendar Component **WHY This Exists:** -Families struggle to coordinate dog care. Kids forget, parents nag, -dogs suffer. This calendar reduces conflict by making responsibility +Families struggle to coordinate dog care. Kids forget, parents nag, +dogs suffer. This calendar reduces conflict by making responsibility visible and accountability fun. **WHY Week View (Not Daily/Monthly):** -Swedish families think in weeks ("Vecka 40"). This matches their +Swedish families think in weeks ("Vecka 40"). This matches their mental model. Daily view is too granular, monthly too abstract. → AI: Don't add daily/monthly views, even if you think it's "better" **WHY 6 Color States:** Visual, instant understanding for kids. No reading required. + - WHITE: Empty (neutral, inviting) - GRAY: Booked (committed, not yet active) - ORANGE: Countdown (urgent, act now) @@ -147,6 +158,7 @@ Makes accountability a game, not a chore. Encourages participation. → AI: This is core to the experience, don't make it optional **WHAT NOT TO DO:** + - ❌ Don't add daily/monthly views (wrong mental model) - ❌ Don't add notifications (wrong tone) - ❌ Don't make it generic (Swedish culture specific) @@ -160,12 +172,14 @@ Makes accountability a game, not a chore. Encourages participation. ### 1. AI Follows Instructions Correctly **Without WHY:** + ``` AI: "I added daily view for flexibility!" Designer: "No, that breaks the mental model..." ``` **With WHY:** + ``` Spec: "Week view matches Swedish 'Vecka 40' culture. Don't add daily view." AI: *Implements week view only* @@ -177,12 +191,14 @@ Designer: ✅ Perfect ### 2. AI Knows What to Skip **Without WHY:** + ``` AI: "I added push notifications for reminders!" Designer: "No, that's nagging, not gentle urgency..." ``` **With WHY:** + ``` Spec: "Countdown timer = gentle urgency. Notifications = nagging. Don't add notifications." AI: *Skips notifications* @@ -194,6 +210,7 @@ Designer: ✅ Exactly right ### 3. AI Preserves Intent During Changes **Without WHY:** + ``` Designer: "Make the countdown more prominent" AI: *Makes it bigger, adds sound, adds vibration* @@ -201,6 +218,7 @@ Designer: "No, that's too aggressive..." ``` **With WHY:** + ``` Spec: "Countdown = gentle urgency, not aggressive nagging" Designer: "Make countdown more prominent" @@ -213,6 +231,7 @@ Designer: ✅ Got it ### 4. Future Developers Understand Context **Without WHY:** + ``` Developer: "Why can't users book multiple walks at once?" *Removes blocking logic* @@ -220,8 +239,9 @@ Developer: "Why can't users book multiple walks at once?" ``` **With WHY:** + ``` -Spec: "One active walk per dog = accountability. Kids can't game the system +Spec: "One active walk per dog = accountability. Kids can't game the system by booking everything then completing nothing." Developer: "Oh, that's a business rule. I'll keep it." ``` @@ -231,6 +251,7 @@ Developer: "Oh, that's a business rule. I'll keep it." ## The Socratic Questioning Connection **Agent asks WHY questions:** + ``` Agent: "Why week view instead of daily?" Designer: "Swedish families think in weeks..." @@ -240,6 +261,7 @@ Agent: "Got it! Documenting: ``` **This creates specifications that:** + - Capture reasoning, not just decisions - Guide AI implementation correctly - Prevent "helpful" mistakes @@ -252,21 +274,25 @@ Agent: "Got it! Documenting: ### For Each Component/Feature: **1. WHY This Exists** + - What problem does it solve? - What behavior change does it create? - What value does it deliver? **2. WHY These Specific Choices** + - Why this approach vs alternatives? - What user need does this serve? - What business goal does this support? **3. WHAT NOT TO DO** + - What "improvements" would break the intent? - What features should NOT be added? - What assumptions should AI NOT make? **4. WHAT (Traditional Specs)** + - Visual design - Interactions - Technical requirements @@ -281,16 +307,19 @@ Agent: "Got it! Documenting: ## Book Walk Button **Visual:** + - Blue background (#3B82F6) - White text - 48px height - Rounded corners (8px) **Action:** + - Click → Open booking modal ``` **AI might "improve" by:** + - Adding "Quick Book" shortcut - Adding "Book for Week" bulk action - Making it more prominent @@ -304,7 +333,7 @@ Agent: "Got it! Documenting: ## Book Walk Button **WHY This Exists:** -Kids need a simple way to commit to walking the dog. +Kids need a simple way to commit to walking the dog. "Booking" creates accountability - it's a promise, not just a plan. **WHY "Book Walk" (Not "Add Walk"):** @@ -317,17 +346,20 @@ Kids should think before booking. One deliberate action = one commitment. Quick actions would encourage gaming the system (book everything, complete nothing). **WHY This Visual Treatment:** + - Blue = Action color (consistent with design system) - 48px = Touch-friendly for kids - Not oversized = Important but not aggressive **WHAT NOT TO DO:** + - ❌ Don't add "Quick Book" shortcuts (encourages gaming) - ❌ Don't add "Book for Week" bulk action (defeats accountability) - ❌ Don't make it more prominent (not the only action) - ❌ Don't add animation (not a game, it's responsibility) **WHAT (Implementation):** + - Background: Blue (#3B82F6) - Text: White, 16px Medium - Height: 48px @@ -336,6 +368,7 @@ Quick actions would encourage gaming the system (book everything, complete nothi ``` **Now AI knows:** + - What to implement - What NOT to add - WHY each decision was made @@ -346,6 +379,7 @@ Quick actions would encourage gaming the system (book everything, complete nothi ## The Transformation ### v4 WPS2C (Prompt-and-Run) + ``` Designer: "Create a booking calendar" AI: *Generates generic calendar* @@ -355,6 +389,7 @@ Designer: *Gives up or over-specifies every detail* ``` ### v6 WDS (Why-Based Specifications) + ``` Designer: "I need a booking calendar" Agent: "Help me understand - why week view instead of daily?" @@ -364,7 +399,7 @@ Designer: "Each state serves a purpose for kids..." Agent: "Perfect. Why countdown instead of notifications?" Designer: "Gentle urgency, not nagging..." -Agent: "Documenting all the WHYs. This will help AI implement +Agent: "Documenting all the WHYs. This will help AI implement correctly and prevent 'helpful' mistakes." *Generates why-based specification* @@ -380,21 +415,25 @@ Designer: ✅ Perfect first time **Why-based specifications are:** ✅ **Better for AI implementation** + - AI knows what NOT to do - AI preserves intent during changes - AI doesn't "help" incorrectly ✅ **Better for human developers** + - Understand context, not just requirements - Make correct decisions when specs are unclear - Maintain intent over time ✅ **Better for future designers** + - Understand why decisions were made - Don't repeat solved problems - Build on reasoning, not just patterns ✅ **Better for the designer** + - Socratic questioning elevates thinking - Articulating WHY clarifies decisions - Creates reusable design knowledge @@ -406,18 +445,21 @@ Designer: ✅ Perfect first time **Traditional specs answer: "What should we build?"** **Why-based specs answer:** + - What should we build? - Why should we build it this way? - What should we NOT build? - How should AI help (and not help)? **Result:** + - AI implements correctly first time - AI skips "improvements" that break intent - Specifications become design knowledge - Designer thinking is preserved and amplified **This is the difference between:** + - Prompt-and-run (fast but wrong) - Why-based specification (thoughtful and right) @@ -431,23 +473,23 @@ Designer: ✅ Perfect first time 1. TRIGGER MAP (Phase 1: Business Model) ↓ Establishes: WHO, WHAT TRIGGERS THEM, WHAT OUTCOME - + 2. SCENARIOS (Phase 1: Business Model) ↓ Defines: User journeys, contexts, goals - + 3. INFORMATION ARCHITECTURE (Phase 2) ↓ Structures: Content hierarchy, navigation - + 4. INTERACTION DESIGN (Phase 3) ↓ Sketches: User flows, state transitions - + 5. UX SPECIFICATIONS (Phase 4) ↓ Documents: WHY + WHAT + WHAT NOT TO DO - + 6. AI IMPLEMENTATION ↓ Builds: Correctly, preserving intent @@ -473,24 +515,28 @@ Designer: ✅ Perfect first time **Traditional specs answer: "What should we build?"** **Why-based specs answer:** + - What should we build? - Why should we build it this way? - What should we NOT build? - How should AI help (and not help)? **Trigger Map provides the ultimate WHY:** + - WHO is this for? - WHAT triggers their need? - WHAT outcome do they want? - WHY will this solution work? **Result:** + - AI implements correctly first time - AI skips "improvements" that break intent - Specifications become design knowledge - Designer thinking is preserved and amplified **This is the difference between:** + - Prompt-and-run (fast but wrong) - Why-based specification (thoughtful and right) diff --git a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/ai-collaboration.md b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/ai-collaboration.md index 1c147b7e..8c18c40b 100644 --- a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/ai-collaboration.md +++ b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/ai-collaboration.md @@ -15,30 +15,35 @@ AI can both **generate** Excalidraw files and **analyze** your sketches, creatin ### **What AI Can Create:** **Layout Variations:** + ``` You: "Create 3 dashboard layout options" AI: Generates 3 .excalidraw files ``` **Component Alternatives:** + ``` You: "Show me different navigation patterns" AI: Generates bottom nav, hamburger, tab bar ``` **User Flows:** + ``` You: "Create a user onboarding flow" AI: Generates flowchart with decision points ``` **State Variations:** + ``` You: "Show this button in all states" AI: Generates default, hover, active, disabled, loading ``` **Responsive Designs:** + ``` You: "Show this page on mobile, tablet, desktop" AI: Generates 3 breakpoint wireframes @@ -51,11 +56,13 @@ AI: Generates 3 breakpoint wireframes ### **Be Specific:** **❌ Vague:** + ``` "Make a login page" ``` **✅ Specific:** + ``` "Create a mobile login page (375×812) with: - Logo at top @@ -69,6 +76,7 @@ Use 20px grid and WDS spacing" ### **Request Multiple Options:** **Pattern:** + ``` "Create [number] variations of [page/component] with: - Option 1: [description] @@ -77,6 +85,7 @@ Use 20px grid and WDS spacing" ``` **Example:** + ``` "Create 3 dashboard variations: 1. Card-based layout (large cards, visual focus) @@ -87,6 +96,7 @@ Use 20px grid and WDS spacing" ### **Specify Constraints:** **Include:** + - Device size (mobile/tablet/desktop) - Grid size (20px) - Key components needed @@ -94,6 +104,7 @@ Use 20px grid and WDS spacing" - Spacing preferences **Example:** + ``` "Create a mobile task list (375×812): - Use 20px grid @@ -110,6 +121,7 @@ Use 20px grid and WDS spacing" ### **The Process:** **Step 1: Export to PNG** + ``` 1. Open .excalidraw file 2. Export → PNG @@ -117,11 +129,13 @@ Use 20px grid and WDS spacing" ``` **Step 2: Upload to AI** + ``` Upload PNG to Claude/ChatGPT/Windsurf ``` **Step 3: Ask for Analysis** + ``` "Here's my dashboard sketch. What do you think?" "Analyze this layout and suggest improvements" @@ -131,18 +145,21 @@ Upload PNG to Claude/ChatGPT/Windsurf ### **What AI Can See:** **Layout and Structure:** + - Component placement - Visual hierarchy - Spacing and alignment - Section organization **Design Decisions:** + - Primary vs secondary actions - Content prioritization - Navigation patterns - Information architecture **Potential Issues:** + - Crowded areas - Unclear hierarchy - Inconsistent spacing @@ -156,6 +173,7 @@ Upload PNG to Claude/ChatGPT/Windsurf ### **Pattern 1: AI Generates, You Refine** **Workflow:** + ``` 1. AI generates initial options 2. You review and choose direction @@ -166,12 +184,13 @@ Upload PNG to Claude/ChatGPT/Windsurf ``` **Example:** + ``` You: "Create 3 login page variations" AI: [Generates 3 files] You: [Opens each, reviews] - "I like option 2 best, but the social buttons + "I like option 2 best, but the social buttons should be more prominent" You: [Edits option 2 in Excalidraw] @@ -179,7 +198,7 @@ You: [Edits option 2 in Excalidraw] [Uploads] "Here's my refined version" -AI: "Great improvement! The social buttons are now +AI: "Great improvement! The social buttons are now more prominent. Consider: - Adding visual separation with a divider - Making the 'or' text more subtle @@ -191,6 +210,7 @@ You: [Makes final adjustments] ### **Pattern 2: You Sketch, AI Analyzes** **Workflow:** + ``` 1. You sketch initial idea 2. Export to PNG @@ -201,6 +221,7 @@ You: [Makes final adjustments] ``` **Example:** + ``` You: [Sketches dashboard] [Exports and uploads] @@ -211,7 +232,7 @@ AI: "I can see you've prioritized today's tasks at the top. - Clear visual hierarchy - Task cards are well-sized - Good use of spacing - + Consider: - The 'Add task' button might get lost at bottom - No indication of overdue tasks @@ -222,14 +243,15 @@ You: [Updates sketch based on feedback] [Exports and uploads] "Better?" -AI: "Much better! The floating 'Add' button is more - accessible. Now let's discuss the overdue task +AI: "Much better! The floating 'Add' button is more + accessible. Now let's discuss the overdue task treatment..." ``` ### **Pattern 3: Collaborative Iteration** **Workflow:** + ``` 1. You sketch rough idea 2. AI generates refined version @@ -240,6 +262,7 @@ AI: "Much better! The floating 'Add' button is more ``` **Example:** + ``` You: [Rough sketch of profile page] "Here's my rough idea for a profile page" @@ -249,8 +272,8 @@ AI: "I see your concept. Let me create a refined version [Generates 3 files] You: [Reviews all 3] - "I like my header from original, your content - layout from option 2, and the action buttons + "I like my header from original, your content + layout from option 2, and the action buttons from option 3" AI: "Perfect! Let me combine those elements" @@ -267,11 +290,13 @@ You: [Reviews] ### **Example 1: Layout Analysis** **You upload:** + ``` Dashboard sketch with task list ``` **AI responds:** + ``` "Analysis of your dashboard layout: @@ -304,11 +329,13 @@ RECOMMENDATIONS: ### **Example 2: Component Analysis** **You upload:** + ``` Button component in various states ``` **AI responds:** + ``` "Analysis of your button states: @@ -345,11 +372,13 @@ Consider adding focus state for keyboard navigation." ### **Example 3: Flow Analysis** **You upload:** + ``` User onboarding flow diagram ``` **AI responds:** + ``` "Analysis of your onboarding flow: @@ -386,6 +415,7 @@ RECOMMENDATIONS: ### **DO ✅** **When requesting AI generation:** + - Be specific about requirements - Request multiple variations (2-5) - Specify device size and constraints @@ -393,6 +423,7 @@ RECOMMENDATIONS: - Include key components needed **When uploading for analysis:** + - Export clear PNG (not blurry) - Include annotations in sketch - Ask specific questions @@ -400,6 +431,7 @@ RECOMMENDATIONS: - Iterate based on feedback **During collaboration:** + - Combine AI suggestions with your expertise - Don't accept everything blindly - Use AI to explore alternatives @@ -409,6 +441,7 @@ RECOMMENDATIONS: ### **DON'T ❌** **Don't:** + - Accept first AI suggestion without review - Skip your own design thinking - Let AI make all decisions @@ -423,6 +456,7 @@ RECOMMENDATIONS: ### **Typical Session:** **Round 1: Exploration** + ``` You: "Create 3 dashboard options" AI: [Generates options] @@ -430,6 +464,7 @@ You: [Reviews] "Option 2 is closest" ``` **Round 2: Refinement** + ``` You: "Refine option 2 with more breathing room" AI: [Generates refined version] @@ -437,6 +472,7 @@ You: [Reviews] "Better! Now add calendar integration" ``` **Round 3: Details** + ``` You: [Edits in Excalidraw] [Uploads] "Here's my version with calendar" @@ -444,6 +480,7 @@ AI: "Great! Let's discuss the calendar placement..." ``` **Round 4: Edge Cases** + ``` AI: "What about empty state? Overdue tasks?" You: "Good point. Show me options for those" @@ -451,6 +488,7 @@ AI: [Generates state variations] ``` **Round 5: Finalization** + ``` You: [Combines best elements] "This is the final version" @@ -464,6 +502,7 @@ AI: "Perfect! Ready to create specifications?" ### **Technique 1: Parallel Exploration** **Generate multiple directions simultaneously:** + ``` You: "Create 3 completely different approaches: 1. Minimalist (focus on one task at a time) @@ -478,6 +517,7 @@ You: [Explores each direction] ### **Technique 2: Constraint-Based Design** **Use AI to explore within constraints:** + ``` You: "Design a dashboard that works with: - One-handed use (thumb zone) @@ -492,6 +532,7 @@ You: [Validates against constraints] ### **Technique 3: Comparative Analysis** **Have AI compare your options:** + ``` You: [Uploads 3 variations you created] "Compare these 3 options. Which is best for: @@ -508,12 +549,14 @@ You: [Makes informed decision] ## Next Steps **After AI collaboration:** + 1. ✅ Finalized sketch 2. ✅ Design decisions documented 3. ✅ Edge cases considered 4. ✅ Ready for specifications **Continue to:** + - [Export Workflow](export-workflow.md) - Prepare for documentation - Phase 4C: Create specifications diff --git a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md index b32b19f0..8af5f5f9 100644 --- a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md +++ b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md @@ -21,6 +21,7 @@ Excalidraw is a free, open-source whiteboard tool that creates hand-drawn style ## When to Use Excalidraw ### **Perfect For:** + - Digital sketching (alternative to paper) - Collaborative design sessions - AI-generated layout variations @@ -28,6 +29,7 @@ Excalidraw is a free, open-source whiteboard tool that creates hand-drawn style - Iterative design exploration ### **Not Required If:** + - You prefer paper and pen - You use other tools (Figma, iPad, etc.) - You're comfortable with your current workflow @@ -42,17 +44,18 @@ Excalidraw is a free, open-source whiteboard tool that creates hand-drawn style ```yaml sketching: - tool: excalidraw # or "paper" or "figma" or "other" + tool: excalidraw # or "paper" or "figma" or "other" excalidraw: enabled: true - auto_export: false # Auto-generate PNG/SVG on save - use_library: true # Load WDS component library - grid_size: 20 # Snap to grid (px) + auto_export: false # Auto-generate PNG/SVG on save + use_library: true # Load WDS component library + grid_size: 20 # Snap to grid (px) ``` ### **2. Install Tools** **VS Code Extension (Recommended):** + ``` 1. Open Extensions (Ctrl+Shift+X) 2. Search "Excalidraw" @@ -60,11 +63,13 @@ sketching: ``` **Or use web version:** + - https://excalidraw.com (no installation needed) ### **3. Load WDS Library (Optional)** **If `use_library: true` in config:** + ``` 1. Open Excalidraw 2. Click library icon @@ -77,28 +82,36 @@ sketching: ## Documentation ### **Setup & Configuration** + → [excalidraw-setup.md](excalidraw-setup.md) + - Installation options - VS Code configuration - Project settings - Grid and theme setup ### **Sketching Workflow** + → [sketching-guide.md](sketching-guide.md) + - When to sketch - What to sketch - How to sketch - File organization ### **Export Workflow** + → [export-workflow.md](export-workflow.md) + - Manual export (PNG/SVG) - Automated export (GitHub Actions) - File naming conventions - GitHub display ### **AI Collaboration** + → [ai-collaboration.md](ai-collaboration.md) + - AI-generated layouts - AI analysis of sketches - Iteration workflow @@ -120,6 +133,7 @@ C-Scenarios/[scenario-name]/ ``` **In specifications.md:** + ```markdown ## Design @@ -137,6 +151,7 @@ C-Scenarios/[scenario-name]/ **Step 4B-02: Sketch Interface** **If Excalidraw enabled:** + ``` Agent: "I see you've enabled Excalidraw. Would you like to: 1. Sketch manually in Excalidraw @@ -145,6 +160,7 @@ Agent: "I see you've enabled Excalidraw. Would you like to: ``` **AI can:** + - Generate `.excalidraw` files with layout options - Analyze your sketches (upload PNG) - Suggest improvements @@ -155,9 +171,11 @@ Agent: "I see you've enabled Excalidraw. Would you like to: ## Optional Features ### **Component Library** + **File:** `wds-library.excalidrawlib` Pre-built components: + - Mobile/tablet/desktop frames - Buttons, inputs, cards - Navigation patterns @@ -166,6 +184,7 @@ Pre-built components: **Enable:** Set `use_library: true` in config ### **Auto-Export** + **GitHub Actions or pre-commit hooks** Automatically generates PNG/SVG when you save `.excalidraw` files. @@ -181,6 +200,7 @@ See: [automation/README.md](automation/README.md) ### **Excalidraw vs Paper** **Excalidraw:** + - ✅ Digital, shareable - ✅ AI can generate - ✅ Version controlled @@ -188,6 +208,7 @@ See: [automation/README.md](automation/README.md) - ❌ Requires tool setup **Paper:** + - ✅ Zero setup - ✅ Fast and natural - ✅ No distractions @@ -197,6 +218,7 @@ See: [automation/README.md](automation/README.md) ### **Excalidraw vs Figma** **Excalidraw:** + - ✅ Free and open-source - ✅ Hand-drawn aesthetic - ✅ AI can generate @@ -204,6 +226,7 @@ See: [automation/README.md](automation/README.md) - ❌ Less precise **Figma:** + - ✅ Professional tool - ✅ Pixel-perfect - ✅ Component systems @@ -218,19 +241,22 @@ See: [automation/README.md](automation/README.md) **To disable after enabling:** **Edit:** `project-config.yaml` + ```yaml sketching: - tool: paper # or "figma" or "other" + tool: paper # or "figma" or "other" excalidraw: enabled: false ``` **Agent will:** + - Skip Excalidraw-specific prompts - Use generic sketching workflow - Not generate `.excalidraw` files **Your existing files:** + - Remain in project - Can still be opened - Not automatically deleted @@ -242,16 +268,19 @@ sketching: ### **Issues with Excalidraw?** **VS Code extension not working:** + - Restart VS Code - Check extension is enabled - Try web version as fallback **Files won't open:** + - Verify JSON is valid - Check file extension is `.excalidraw` - Try opening in web version **AI can't generate files:** + - Check core helpers are loaded - Verify project config - Report issue to WDS @@ -259,11 +288,13 @@ sketching: ### **Community** **Excalidraw:** + - Website: https://excalidraw.com - GitHub: https://github.com/excalidraw/excalidraw - Discord: https://discord.gg/UexuTaE **WDS:** + - Discord: [WDS community] - GitHub: [WDS issues] @@ -272,12 +303,14 @@ sketching: ## Next Steps **If Excalidraw is enabled:** + 1. Install VS Code extension (or use web) 2. Load WDS library (optional) 3. Configure grid and theme 4. Start sketching! **Learn more:** + - [Setup Guide](excalidraw-setup.md) - [Sketching Guide](sketching-guide.md) - [AI Collaboration](ai-collaboration.md) diff --git a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md index 1cf070d3..602c2b83 100644 --- a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md +++ b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md @@ -11,6 +11,7 @@ **Best for:** Working within IDE, integrated workflow **Steps:** + ``` 1. Open VS Code 2. Extensions (Ctrl+Shift+X / Cmd+Shift+X) @@ -20,12 +21,14 @@ ``` **Usage:** + - Create new `.excalidraw` file - Click to open in Excalidraw editor - Edit and save (Ctrl+S / Cmd+S) - File auto-saves to project **Pros:** + - ✅ Never leave IDE - ✅ Direct file access - ✅ Git integration @@ -36,6 +39,7 @@ **Best for:** Quick sketching, no installation **Steps:** + ``` 1. Go to https://excalidraw.com 2. Start drawing @@ -44,12 +48,14 @@ ``` **Usage:** + - Open in browser - Draw and iterate - Download when done - Place in project **Pros:** + - ✅ Zero installation - ✅ Works anywhere - ✅ Always latest version @@ -60,6 +66,7 @@ **Best for:** Dedicated sketching tool **Steps:** + ``` 1. Download from https://github.com/excalidraw/excalidraw-desktop 2. Install for your OS @@ -67,6 +74,7 @@ ``` **Pros:** + - ✅ Standalone app - ✅ Offline capable - ✅ Native performance @@ -78,13 +86,14 @@ ### **Enable Excalidraw in Project** **During project initialization:** + ``` Agent: "Which sketching tool would you like to use? 1. Paper and pen (scan/photograph) 2. Excalidraw (digital, AI-friendly) 3. Figma (professional tool) 4. Other digital tool - + Your choice:" ``` @@ -94,30 +103,30 @@ Agent: "Which sketching tool would you like to use? ```yaml project: - name: "Dog Week" - wds_version: "6.0" + name: 'Dog Week' + wds_version: '6.0' sketching: - tool: excalidraw # "paper" | "excalidraw" | "figma" | "other" - + tool: excalidraw # "paper" | "excalidraw" | "figma" | "other" + excalidraw: enabled: true - + # Auto-export to PNG/SVG on save - auto_export: false # true | false - + auto_export: false # true | false + # Load WDS component library - use_library: true # true | false - + use_library: true # true | false + # Grid settings - grid_size: 20 # pixels - snap_to_grid: true # true | false - + grid_size: 20 # pixels + snap_to_grid: true # true | false + # Default theme - theme: light # "light" | "dark" - + theme: light # "light" | "dark" + # File organization - sketches_folder: "sketches" # relative to scenario folder + sketches_folder: 'sketches' # relative to scenario folder ``` --- @@ -142,15 +151,18 @@ sketching: ### **Recommended Settings** **Grid:** + - Size: 20px (matches WDS spacing) - Snap: Enabled (for alignment) - Visible: Optional (toggle with Ctrl+') **Theme:** + - Light: Better for screenshots - Dark: Easier on eyes for long sessions **Auto-save:** + - Enabled by default in VS Code - Saves on every change @@ -161,6 +173,7 @@ sketching: ### **What is it?** Pre-built Excalidraw components for common UI elements: + - Device frames (mobile, tablet, desktop) - Buttons, inputs, cards - Navigation patterns @@ -171,6 +184,7 @@ Pre-built Excalidraw components for common UI elements: **If `use_library: true` in config:** **VS Code:** + ``` 1. Open any .excalidraw file 2. Click library icon (bottom toolbar) @@ -180,6 +194,7 @@ Pre-built Excalidraw components for common UI elements: ``` **Web:** + ``` 1. Open https://excalidraw.com 2. Click library icon @@ -190,6 +205,7 @@ Pre-built Excalidraw components for common UI elements: ### **Usage** **Drag and drop:** + ``` 1. Open library panel 2. Find component (e.g., "Mobile Frame") @@ -198,6 +214,7 @@ Pre-built Excalidraw components for common UI elements: ``` **Components included:** + - Mobile Frame (375x812) - Tablet Frame (768x1024) - Desktop Frame (1440x900) @@ -215,6 +232,7 @@ Pre-built Excalidraw components for common UI elements: ### **Why 20px Grid?** **Matches WDS spacing system:** + - Consistent alignment - Clean layouts - Easy calculations @@ -223,6 +241,7 @@ Pre-built Excalidraw components for common UI elements: ### **Setup** **VS Code:** + ``` Settings → Extensions → Excalidraw - Grid Mode: ✓ Enabled @@ -231,6 +250,7 @@ Settings → Extensions → Excalidraw ``` **Web:** + ``` View menu → Show grid (Ctrl+') Settings → Grid size: 20 @@ -239,6 +259,7 @@ Settings → Grid size: 20 ### **Usage** **All elements snap to 20px increments:** + - Position: 0, 20, 40, 60, 80... - Size: 100, 120, 140, 160... - Spacing: 20, 40, 60, 80... @@ -250,12 +271,14 @@ Settings → Grid size: 20 ### **Light Theme (Recommended)** **Best for:** + - Screenshots and exports - GitHub display - Documentation - Presentations **Colors:** + - Background: White - Shapes: Light colors - Text: Dark gray/black @@ -263,11 +286,13 @@ Settings → Grid size: 20 ### **Dark Theme** **Best for:** + - Long sketching sessions - Reduced eye strain - Personal preference **Colors:** + - Background: Dark gray - Shapes: Bright colors - Text: White/light gray @@ -275,11 +300,13 @@ Settings → Grid size: 20 ### **Setup** **VS Code:** + ``` Settings → Excalidraw → Theme: light/dark ``` **Web:** + ``` Settings icon → Appearance → Theme ``` @@ -310,6 +337,7 @@ C-Scenarios/ ### **Naming Conventions** **Source files:** + ``` [page-name].excalidraw [component-name].excalidraw @@ -317,6 +345,7 @@ C-Scenarios/ ``` **Exports:** + ``` [page-name].png (for GitHub/docs) [page-name].svg (scalable, optional) @@ -324,6 +353,7 @@ C-Scenarios/ ``` **Examples:** + ``` dashboard.excalidraw dashboard.png @@ -340,6 +370,7 @@ user-flow.svg ### **Manual Export** **VS Code:** + ``` 1. Open .excalidraw file 2. Click hamburger menu (top-right) @@ -348,6 +379,7 @@ user-flow.svg ``` **Web:** + ``` 1. File menu → Export image 2. Choose format (PNG/SVG) @@ -360,6 +392,7 @@ user-flow.svg **If `auto_export: true` in config:** **GitHub Actions automatically:** + - Detects `.excalidraw` file changes - Generates PNG and SVG - Commits to repository @@ -374,6 +407,7 @@ user-flow.svg ### **Essential Shortcuts** **Drawing:** + - `R` - Rectangle - `D` - Diamond - `O` - Ellipse @@ -382,17 +416,20 @@ user-flow.svg - `L` - Line **Editing:** + - `Ctrl/Cmd + D` - Duplicate - `Ctrl/Cmd + G` - Group - `Ctrl/Cmd + Shift + G` - Ungroup - `Delete` - Delete selected **View:** + - `Ctrl/Cmd + '` - Toggle grid - `Ctrl/Cmd + Wheel` - Zoom - `Space + Drag` - Pan canvas **Selection:** + - `Ctrl/Cmd + A` - Select all - `Shift + Click` - Multi-select - `Ctrl/Cmd + Click` - Add to selection @@ -406,6 +443,7 @@ user-flow.svg **Issue:** Extension installed but files won't open **Solutions:** + 1. Restart VS Code 2. Check extension is enabled (Extensions panel) 3. Try right-click → Open With → Excalidraw @@ -417,6 +455,7 @@ user-flow.svg **Issue:** "Invalid file" error **Solutions:** + 1. Verify file extension is `.excalidraw` 2. Check JSON is valid (open in text editor) 3. Try opening in web version @@ -428,6 +467,7 @@ user-flow.svg **Issue:** Elements don't snap to grid **Solutions:** + 1. Enable "Snap to grid" in settings 2. Check grid size is set (20px) 3. Toggle grid visibility (Ctrl+') @@ -438,6 +478,7 @@ user-flow.svg **Issue:** Component library not appearing **Solutions:** + 1. Verify file path is correct 2. Check `.excalidrawlib` file exists 3. Try uploading manually @@ -449,6 +490,7 @@ user-flow.svg ## Best Practices ### **DO ✅** + - Use 20px grid for alignment - Save frequently (auto-save helps) - Export PNG for documentation @@ -457,6 +499,7 @@ user-flow.svg - Label all elements clearly ### **DON'T ❌** + - Don't skip grid alignment - Don't forget to export for GitHub - Don't delete source files @@ -469,12 +512,14 @@ user-flow.svg ## Next Steps **After setup:** + 1. ✅ Excalidraw installed and configured 2. ✅ Project config updated 3. ✅ Library loaded (optional) 4. ✅ Grid and theme set **Now learn:** + - [Sketching Guide](sketching-guide.md) - How to sketch in WDS - [AI Collaboration](ai-collaboration.md) - Work with AI - [Export Workflow](export-workflow.md) - Share your work diff --git a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/export-workflow.md b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/export-workflow.md index 02dd3c36..842dcfae 100644 --- a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/export-workflow.md +++ b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/export-workflow.md @@ -7,18 +7,21 @@ ## Why Export? **Excalidraw files (`.excalidraw`) are JSON:** + - ✅ Perfect for editing - ✅ Version control friendly - ✅ AI can generate - ❌ Don't render in GitHub **Exported images (PNG/SVG):** + - ✅ Display in GitHub - ✅ Show in documentation - ✅ Easy to share - ✅ No special tools needed **Solution:** Keep both! + ``` sketch.excalidraw ← Source (editable) sketch.png ← Display (GitHub) @@ -31,12 +34,14 @@ sketch.png ← Display (GitHub) ### **From VS Code Extension** **Step 1: Open file** + ``` Click .excalidraw file in VS Code Opens in Excalidraw editor ``` **Step 2: Export** + ``` 1. Click hamburger menu (top-right) 2. Export image @@ -48,6 +53,7 @@ Opens in Excalidraw editor ``` **Step 3: Name correctly** + ``` Source: dashboard.excalidraw Export: dashboard.png @@ -57,6 +63,7 @@ Export: dashboard.png ### **From Web App** **Step 1: Open file** + ``` 1. Go to https://excalidraw.com 2. File → Open @@ -64,6 +71,7 @@ Export: dashboard.png ``` **Step 2: Export** + ``` 1. Click hamburger menu 2. Export image @@ -72,6 +80,7 @@ Export: dashboard.png ``` **Step 3: Move to project** + ``` 1. Move downloaded file to project 2. Place in same folder as source @@ -85,6 +94,7 @@ Export: dashboard.png ### **PNG Export** **Recommended settings:** + ``` Format: PNG Background: Transparent or White @@ -93,23 +103,27 @@ Include: Only selected (if partial export) ``` **When to use:** + - Documentation - GitHub README - Presentations - Quick sharing **Pros:** + - ✅ Universal support - ✅ Good quality - ✅ Reasonable file size **Cons:** + - ❌ Not scalable - ❌ Larger than SVG ### **SVG Export** **Recommended settings:** + ``` Format: SVG Background: Transparent @@ -117,17 +131,20 @@ Embed fonts: Yes (for portability) ``` **When to use:** + - Scalable documentation - Print materials - High-resolution needs - Technical diagrams **Pros:** + - ✅ Infinitely scalable - ✅ Smaller file size - ✅ Crisp at any size **Cons:** + - ❌ Some tools don't support - ❌ More complex @@ -153,6 +170,7 @@ C-Scenarios/[scenario-name]/ ### **Naming Conventions** **Pattern:** + ``` [descriptive-name].excalidraw ← Source [descriptive-name].png ← PNG export @@ -160,6 +178,7 @@ C-Scenarios/[scenario-name]/ ``` **Examples:** + ``` ✅ dashboard.excalidraw / dashboard.png ✅ login-page.excalidraw / login-page.png @@ -173,6 +192,7 @@ C-Scenarios/[scenario-name]/ ### **Versions** **Option A: Numbered versions** + ``` dashboard-v1.excalidraw dashboard-v1.png @@ -183,6 +203,7 @@ dashboard-final.png ``` **Option B: Git history (recommended)** + ``` dashboard.excalidraw ← Always latest dashboard.png ← Always latest @@ -196,11 +217,13 @@ Git history shows all versions ### **In Markdown Files** **Basic image:** + ```markdown ![Dashboard Wireframe](./sketches/dashboard.png) ``` **With link to source:** + ```markdown ## Dashboard Design @@ -210,28 +233,34 @@ Git history shows all versions ``` **With caption:** + ```markdown ![Dashboard showing today's tasks with card-based layout](./sketches/dashboard.png) -*Dashboard showing today's tasks with card-based layout* +_Dashboard showing today's tasks with card-based layout_ ``` **Multiple images:** + ```markdown ## Layout Options ### Option A: Card-Based + ![Card-based layout](./sketches/dashboard-cards.png) ### Option B: List-Based + ![List-based layout](./sketches/dashboard-list.png) ### Option C: Calendar-Focused + ![Calendar-focused layout](./sketches/dashboard-calendar.png) ``` ### **In Specifications** **Example:** + ```markdown # Dashboard Page Specification @@ -244,6 +273,7 @@ Git history shows all versions ## Layout Structure The dashboard follows a card-based layout with: + - Header: Logo, menu, add button - Content: Today's tasks in card format - Footer: Bottom navigation @@ -274,19 +304,19 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - + - name: Setup Node uses: actions/setup-node@v3 - + - name: Install CLI run: npm install -g @excalidraw/cli - + - name: Export files run: | find . -name "*.excalidraw" | while read file; do excalidraw-cli export "$file" --output "${file%.excalidraw}.png" done - + - name: Commit run: | git config user.name "GitHub Action" @@ -307,22 +337,26 @@ jobs: ### **DO ✅** **Always export:** + - Export after every significant change - Keep exports in sync with source - Use consistent naming - Commit both source and export **Choose right format:** + - PNG for most documentation - SVG for scalable needs - Both if unsure **Organize well:** + - Keep exports with sources - Use descriptive names - Follow naming conventions **Document in markdown:** + - Show image inline - Link to source file - Add helpful captions @@ -330,6 +364,7 @@ jobs: ### **DON'T ❌** **Don't:** + - Commit only PNG (lose editability) - Commit only .excalidraw (won't show in GitHub) - Use inconsistent naming @@ -346,6 +381,7 @@ jobs: **Issue:** PNG export is low resolution **Solution:** + ``` 1. Check export scale (use 2x) 2. Ensure source is high quality @@ -357,6 +393,7 @@ jobs: **Issue:** PNG files are huge **Solution:** + ``` 1. Use SVG instead 2. Reduce export scale @@ -369,6 +406,7 @@ jobs: **Issue:** Image link broken in markdown **Solution:** + ``` 1. Check file path is correct 2. Use relative paths (./sketches/file.png) @@ -381,6 +419,7 @@ jobs: **Issue:** Export menu not visible **Solution:** + ``` VS Code: Hamburger menu → Export image Web: File menu → Export image @@ -394,18 +433,21 @@ Desktop: File → Export ### **Export Checklist** **Before exporting:** + - [ ] Sketch is complete - [ ] All elements labeled - [ ] Grid alignment checked - [ ] Annotations added **During export:** + - [ ] Choose correct format (PNG/SVG) - [ ] Set appropriate scale (2x for PNG) - [ ] Use descriptive filename - [ ] Save to correct folder **After exporting:** + - [ ] Verify export looks good - [ ] Update markdown references - [ ] Commit both source and export @@ -418,6 +460,7 @@ Desktop: File → Export ### **Example 1: Single Page** **Files:** + ``` sketches/ ├── dashboard.excalidraw @@ -425,6 +468,7 @@ sketches/ ``` **In specifications.md:** + ```markdown # Dashboard Specification @@ -435,6 +479,7 @@ sketches/ ### **Example 2: Multiple Variations** **Files:** + ``` sketches/ ├── dashboard-cards.excalidraw @@ -446,18 +491,22 @@ sketches/ ``` **In specifications.md:** + ```markdown # Dashboard Options ## Option A: Card-Based + ![Cards](./sketches/dashboard-cards.png) [Edit](./sketches/dashboard-cards.excalidraw) ## Option B: List-Based + ![List](./sketches/dashboard-list.png) [Edit](./sketches/dashboard-list.excalidraw) ## Option C: Calendar-Focused + ![Calendar](./sketches/dashboard-calendar.png) [Edit](./sketches/dashboard-calendar.excalidraw) ``` @@ -465,6 +514,7 @@ sketches/ ### **Example 3: States** **Files:** + ``` sketches/ ├── button-states.excalidraw @@ -472,6 +522,7 @@ sketches/ ``` **In specifications.md:** + ```markdown # Button Component @@ -481,6 +532,7 @@ sketches/ [Edit](./sketches/button-states.excalidraw) The button has 5 states: + - Default: Blue background, white text - Hover: Darker blue, slight scale - Active: Even darker, pressed appearance @@ -493,6 +545,7 @@ The button has 5 states: ## Next Steps **After exporting:** + 1. ✅ PNG/SVG created 2. ✅ Files organized 3. ✅ Markdown updated @@ -500,6 +553,7 @@ The button has 5 states: 5. ✅ Visible in GitHub **Continue to:** + - Phase 4C: Create specifications - Use exports in documentation - Share with team diff --git a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/sketching-guide.md b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/sketching-guide.md index 6528d442..0cc089b7 100644 --- a/src/modules/wds/workflows/4-ux-design/excalidraw-integration/sketching-guide.md +++ b/src/modules/wds/workflows/4-ux-design/excalidraw-integration/sketching-guide.md @@ -9,12 +9,14 @@ ### **During Phase 4: UX Design** **Step 4B: Sketch Interface** + - After scenario initialization - Before detailed specifications - When exploring layout options - When discussing with AI **Typical timing:** + ``` Scenario Init → Sketch → AI Discussion → Refine → Specify ``` @@ -28,6 +30,7 @@ Scenario Init → Sketch → AI Discussion → Refine → Specify **Purpose:** Show overall page structure **Include:** + - Device frame (mobile/tablet/desktop) - Major sections (header, content, footer) - Component placement @@ -35,6 +38,7 @@ Scenario Init → Sketch → AI Discussion → Refine → Specify - Spacing and alignment **Example:** + ``` [Mobile Frame 375x812] ┌─────────────────┐ @@ -60,12 +64,14 @@ Scenario Init → Sketch → AI Discussion → Refine → Specify **Purpose:** Explore different design options **Include:** + - 2-3 layout alternatives - Different component arrangements - Hierarchy variations - Spacing options **Example:** + ``` Option A: Card-based Option B: List-based @@ -77,6 +83,7 @@ Option C: Calendar-focused **Purpose:** Show navigation and state transitions **Include:** + - Start and end points - Decision points - Actions and outcomes @@ -84,6 +91,7 @@ Option C: Calendar-focused - Success paths **Example:** + ``` [Start] → [Login] → [Dashboard] ↓ @@ -95,6 +103,7 @@ Option C: Calendar-focused **Purpose:** Show component in different states **Include:** + - Default state - Hover state - Active/focused state @@ -104,6 +113,7 @@ Option C: Calendar-focused - Success state **Example:** + ``` Button States: [Default] [Hover] [Active] [Disabled] [Loading] @@ -114,6 +124,7 @@ Button States: **Purpose:** Show design across breakpoints **Include:** + - Mobile (375px) - Tablet (768px) - Desktop (1440px) @@ -127,6 +138,7 @@ Button States: ### **Step 1: Choose Device Frame (2 min)** **From library or create:** + ``` Mobile: 375 × 812 (iPhone) Tablet: 768 × 1024 (iPad) @@ -134,6 +146,7 @@ Desktop: 1440 × 900 (Laptop) ``` **Draw rectangle:** + - Use Rectangle tool (R) - Set dimensions - Label device type @@ -142,6 +155,7 @@ Desktop: 1440 × 900 (Laptop) ### **Step 2: Add Major Sections (5 min)** **Divide into regions:** + ``` Header: Top 60-80px Content: Middle (flexible) @@ -149,6 +163,7 @@ Footer: Bottom 60-80px ``` **Use rectangles:** + - Light fill color - Label each section - Snap to 20px grid @@ -157,6 +172,7 @@ Footer: Bottom 60-80px ### **Step 3: Add Components (10 min)** **From library or draw:** + - Buttons - Input fields - Cards @@ -165,6 +181,7 @@ Footer: Bottom 60-80px - Text blocks **Placement:** + - Follow grid (20px) - Consistent spacing - Visual hierarchy @@ -173,12 +190,14 @@ Footer: Bottom 60-80px ### **Step 4: Add Labels (5 min)** **Label everything:** + - Component names - Interactive elements - Content areas - Actions **Use text tool (T):** + - Clear, concise labels - Inside or beside components - Consistent font size @@ -187,12 +206,14 @@ Footer: Bottom 60-80px ### **Step 5: Add Annotations (5 min)** **Document decisions:** + - Why this layout? - Key interactions - Important notes - Questions/concerns **Use:** + - Text boxes - Arrows pointing to elements - Different color for notes @@ -201,6 +222,7 @@ Footer: Bottom 60-80px ### **Step 6: Review and Refine (5 min)** **Check:** + - ✓ All elements aligned to grid - ✓ Consistent spacing - ✓ Clear labels @@ -215,6 +237,7 @@ Footer: Bottom 60-80px ### **Pattern 1: Top-Down** **Start with structure, add details:** + ``` 1. Device frame 2. Major sections @@ -229,6 +252,7 @@ Footer: Bottom 60-80px ### **Pattern 2: Component-First** **Start with key component, build around:** + ``` 1. Main component (e.g., task list) 2. Supporting components @@ -242,6 +266,7 @@ Footer: Bottom 60-80px ### **Pattern 3: Flow-Based** **Follow user journey:** + ``` 1. Entry point 2. First action @@ -259,6 +284,7 @@ Footer: Bottom 60-80px ### **20px Grid System** **Everything snaps to 20px:** + ``` Position: 0, 20, 40, 60, 80, 100... Size: 80, 100, 120, 140, 160... @@ -268,16 +294,19 @@ Spacing: 20, 40, 60, 80... ### **Common Spacing** **Tight:** 20px + - Between related items - Inside cards - Form field spacing **Medium:** 40px + - Between sections - Card margins - Component groups **Loose:** 60-80px + - Major sections - Page margins - Visual breaks @@ -285,15 +314,18 @@ Spacing: 20, 40, 60, 80... ### **Component Sizes** **Buttons:** + - Small: 80 × 32 - Medium: 120 × 40 - Large: 160 × 48 **Input Fields:** + - Width: 280-320 (mobile), 400+ (desktop) - Height: 40-48 **Cards:** + - Width: 320 (mobile), 400+ (desktop) - Height: Variable (content-based) @@ -304,6 +336,7 @@ Spacing: 20, 40, 60, 80... ### **Size** **Larger = More important:** + ``` Heading: 24-32px Body: 16-18px @@ -313,6 +346,7 @@ Caption: 12-14px ### **Weight** **Bolder = More important:** + ``` Primary: Bold/Semibold Secondary: Regular @@ -322,6 +356,7 @@ Tertiary: Light ### **Position** **Top/Left = More important:** + ``` Most important: Top-left Secondary: Center @@ -331,6 +366,7 @@ Least important: Bottom-right ### **Color/Contrast** **Higher contrast = More important:** + ``` Primary: Dark on light (high contrast) Secondary: Medium gray @@ -344,36 +380,42 @@ Tertiary: Light gray ### **❌ DON'T:** **1. Skip the grid** + ``` ❌ Random positioning ✅ Snap to 20px grid ``` **2. Inconsistent spacing** + ``` ❌ 15px, 23px, 18px... ✅ 20px, 40px, 60px... ``` **3. Unlabeled elements** + ``` ❌ [Rectangle] ✅ [Login Button] ``` **4. Too much detail** + ``` ❌ Pixel-perfect designs ✅ Rough wireframes ``` **5. No annotations** + ``` ❌ Just shapes ✅ Shapes + notes about why ``` **6. Forget device context** + ``` ❌ Generic layout ✅ Mobile/tablet/desktop frame @@ -388,6 +430,7 @@ Tertiary: Light gray **Pattern:** `[page-name].excalidraw` **Examples:** + ``` dashboard.excalidraw login-page.excalidraw @@ -399,11 +442,13 @@ button-states.excalidraw ### **Location** **Always in sketches folder:** + ``` C-Scenarios/[scenario-name]/sketches/ ``` **Example:** + ``` C-Scenarios/morning-dog-care/ ├── sketches/ @@ -418,6 +463,7 @@ C-Scenarios/morning-dog-care/ ### **Versions** **Iterations:** + ``` dashboard-v1.excalidraw dashboard-v2.excalidraw @@ -425,6 +471,7 @@ dashboard-final.excalidraw ``` **Or use git:** + ``` dashboard.excalidraw (always latest) Git history shows versions @@ -437,11 +484,13 @@ Git history shows versions ### **AI Can Generate Sketches** **Request:** + ``` "Create 3 dashboard layout options in Excalidraw" ``` **AI creates:** + ``` dashboard-cards.excalidraw dashboard-list.excalidraw @@ -449,6 +498,7 @@ dashboard-calendar.excalidraw ``` **You:** + - Open each option - Compare and choose - Refine the winner @@ -456,6 +506,7 @@ dashboard-calendar.excalidraw ### **AI Can Analyze Your Sketches** **Process:** + ``` 1. Export sketch to PNG 2. Upload to AI @@ -465,6 +516,7 @@ dashboard-calendar.excalidraw ``` **Example:** + ``` You: [Upload dashboard.png] "What do you think?" @@ -476,6 +528,7 @@ AI: "I see you've prioritized today's tasks at top. ### **AI Can Iterate** **Feedback loop:** + ``` You: "Make the cards bigger with more breathing room" AI: [Generates dashboard-v2.excalidraw] @@ -490,26 +543,31 @@ AI: [Generates dashboard-calendar.excalidraw] ### **DO ✅** **Start rough:** + - Quick shapes - Basic layout - Refine later **Use the grid:** + - Snap everything - Consistent spacing - Professional look **Label clearly:** + - Name all components - Describe interactions - Note important details **Annotate decisions:** + - Why this layout? - What alternatives considered? - What questions remain? **Keep it simple:** + - Wireframes, not mockups - Structure, not style - Concepts, not pixels @@ -517,21 +575,25 @@ AI: [Generates dashboard-calendar.excalidraw] ### **DON'T ❌** **Don't over-design:** + - Not pixel-perfect - Not final styling - Not production-ready **Don't skip context:** + - Always use device frame - Show realistic content - Include navigation **Don't forget states:** + - Show hover/active - Show error states - Show loading states **Don't work in isolation:** + - Share with AI - Get feedback - Iterate together @@ -614,6 +676,7 @@ Annotations: ## Next Steps **After sketching:** + 1. ✅ Export to PNG 2. ✅ Upload to AI for discussion 3. ✅ Iterate based on feedback @@ -621,6 +684,7 @@ Annotations: 5. ✅ Create specifications **Learn more:** + - [AI Collaboration](ai-collaboration.md) - Work with AI - [Export Workflow](export-workflow.md) - Share your work diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md index d24367a6..dec1492b 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md @@ -7,6 +7,7 @@ ## Foundation (00-) ### [Agent-Designer Collaboration](00-foundation/agent-designer-collaboration.md) + How AI agents optimize designer craft without replacing designer thinking --- @@ -14,12 +15,15 @@ How AI agents optimize designer craft without replacing designer thinking ## Core Concepts (01-) ### [Three-Tier Architecture](01-core-concepts/three-tier-overview.md) + Overview of Pages, Components, and Features separation ### [Content Placement Rules](01-core-concepts/content-placement-rules.md) + Decision tree for where to document content ### [Complexity Detection](01-core-concepts/complexity-detection.md) + How to identify simple vs complex components --- @@ -27,12 +31,15 @@ How to identify simple vs complex components ## Workflows (02-) ### [Page Specification Workflow](02-workflows/page-specification-workflow.md) + Step-by-step page decomposition from sketch to specs ### [Complexity Router Workflow](02-workflows/complexity-router-workflow.md) + Guided decomposition for complex components ### [Storyboard Integration](02-workflows/storyboards/storyboards-guide.md) + Using visual storyboards for complex components --- @@ -40,12 +47,15 @@ Using visual storyboards for complex components ## Examples ### [Simple Component Example](examples/simple-button.md) + Button - single file documentation ### [Complex Component Example](examples/complex-calendar.md) + Calendar - three-tier decomposition ### [Search Bar Example](examples/search-bar.md) + Search with page-specific content --- @@ -53,7 +63,9 @@ Search with page-specific content ## Quick References (03-) ### [Decision Tree](03-quick-refs/decision-tree.md) + One-page flowchart for file placement ### [Benefits Summary](03-quick-refs/benefits.md) + Why this architecture works diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/00-foundation/agent-designer-collaboration.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/00-foundation/agent-designer-collaboration.md index d1efbebb..fc80096b 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/00-foundation/agent-designer-collaboration.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/00-foundation/agent-designer-collaboration.md @@ -16,21 +16,25 @@ ## What Agents CANNOT Do ❌ **Understand business context** + - Why does this business exist? - What are the real goals? - What defines success? ❌ **Know user needs deeply** + - Who are the actual users? - What are their mental models? - What contexts do they operate in? ❌ **Make strategic decisions** + - Should we build this feature? - Does this serve the user or just the business? - What's the coherent storyline? ❌ **Balance competing priorities** + - Business goals vs user needs - Simplicity vs functionality - Technical viability vs ideal experience @@ -42,6 +46,7 @@ ## What Agents DO Brilliantly ✅ **Systematic decomposition** + ``` Designer: "This calendar is complex" Agent: "I detect 6 states, time-based transitions, business rules. @@ -52,6 +57,7 @@ Agent: "I detect 6 states, time-based transitions, business rules. ``` ✅ **Pattern recognition** + ``` Designer: "I'm adding body text here" Agent: "I notice on Start Page, body text was 16px with 1.5 line-height. @@ -59,6 +65,7 @@ Agent: "I notice on Start Page, body text was 16px with 1.5 line-height. ``` ✅ **Documentation assistance** + ``` Designer: "The walk slot has different colors" Agent: "Let me capture that systematically: @@ -71,6 +78,7 @@ Agent: "Let me capture that systematically: ``` ✅ **Workflow guidance** + ``` Designer: "Where should I document this content?" Agent: "Does the content vary by page context? @@ -79,6 +87,7 @@ Agent: "Does the content vary by page context? ``` ✅ **Cross-reference tracking** + ``` Designer: "I updated the button color" Agent: "This button appears on 5 pages. Should I update all references?" @@ -91,6 +100,7 @@ Agent: "This button appears on 5 pages. Should I update all references?" ### Phase 1: Designer Thinks **Designer decides:** + - Business goals for this page - User needs to serve - Product strategy to implement @@ -104,6 +114,7 @@ Agent: "This button appears on 5 pages. Should I update all references?" ### Phase 2: Agent Guides Decomposition **Agent asks systematic questions:** + ``` "I see this sketch. Let me identify sections: 1. Navigation Header @@ -116,12 +127,14 @@ Does this match your vision?" ``` **Designer confirms, corrects, adds context:** + ``` -"Yes, but the Calendar is the core feature. +"Yes, but the Calendar is the core feature. It needs detailed specification." ``` **Agent adapts:** + ``` "Got it. Calendar is core. I'll guide you through detailed decomposition. The other sections we can keep schematic unless you need detail." @@ -132,6 +145,7 @@ The other sections we can keep schematic unless you need detail." ### Phase 3: Designer Provides Creative Input **Designer sketches, explains, decides:** + ``` "The walk slots have 6 states. I have a storyboard showing the flow. The colors represent different stages of the walk lifecycle. @@ -139,6 +153,7 @@ This needs to feel playful, not punishing." ``` **Agent captures systematically:** + ``` "Capturing: - 6 visual states (storyboard reference) @@ -156,6 +171,7 @@ Should I create: ### Phase 4: Agent Ensures Consistency **Agent checks patterns:** + ``` "I notice you're using orange for 'countdown active' state. On the Week Overview, orange circles also mean 'active day'. @@ -163,6 +179,7 @@ This is consistent. Should I document this as a design system pattern?" ``` **Designer confirms or corrects:** + ``` "Yes! Orange = active/urgent across the app. Add that to the design system." @@ -173,17 +190,19 @@ Add that to the design system." ### Phase 5: Designer Makes Final Decisions **Agent presents options:** + ``` "For the User Profile dropdown, I can: A) Keep simple specification in Page file B) Create detailed Component + Feature files C) Mark as TODO for later -This component has 3 states and logout logic. +This component has 3 states and logout logic. What level of detail do you need?" ``` **Designer decides based on priorities:** + ``` "Option B. User profile is important for trust. Let's specify it properly." @@ -196,17 +215,19 @@ Let's specify it properly." ### 1. Ask, Don't Assume **Wrong:** + ``` Agent: "I'll create a daily calendar view." ``` **Right:** + ``` Agent: "I see a calendar. Should this be: - Daily view - Weekly view - Monthly view - + What matches your users' mental model?" ``` @@ -215,18 +236,20 @@ Agent: "I see a calendar. Should this be: ### 2. Provide Context, Not Just Questions **Wrong:** + ``` Agent: "What color should this be?" ``` **Right:** + ``` Agent: "I notice the walk slot needs a color for 'countdown active' state. You've used: - Blue for 'in progress' - Green for 'completed' - Red for 'missed' - + What color represents 'urgent but not started'?" ``` @@ -235,18 +258,20 @@ Agent: "I notice the walk slot needs a color for 'countdown active' state. ### 3. Explain WHY Questions Matter **Wrong:** + ``` Agent: "Does content vary by page?" ``` **Right:** + ``` Agent: "Does the hero heading change per page? - + This matters because: - If YES → Document in Page file (page-specific) - If NO → Document in Feature file (reusable) - + This keeps your specs maintainable." ``` @@ -255,10 +280,11 @@ Agent: "Does the hero heading change per page? ### 4. Learn Designer Preferences **After a few interactions:** + ``` Agent: "I notice you prefer detailed specifications for user-facing components but schematic specs for admin sections. - + Should I apply this pattern to the Settings page?" ``` @@ -267,15 +293,17 @@ Agent: "I notice you prefer detailed specifications for user-facing components ### 5. Catch Inconsistencies Gently **Wrong:** + ``` Agent: "ERROR: This contradicts the Start Page!" ``` **Right:** + ``` Agent: "I notice on Start Page, buttons are 48px height. Here you specified 44px. - + Is this intentional (different context) or should I match for consistency?" ``` @@ -286,29 +314,31 @@ Agent: "I notice on Start Page, buttons are 48px height. **Agent notices patterns and asks for reasoning:** ``` -Agent: "Help me understand: The header has two buttons - - 'Book Walk' and 'Add Walk'. - +Agent: "Help me understand: The header has two buttons - + 'Book Walk' and 'Add Walk'. + They seem to do similar things. What's the difference?" ``` **Designer's answer reveals business logic:** + ``` -Designer: "Oh! Good catch. +Designer: "Oh! Good catch. 'Book Walk' = Reserve a future slot 'Add Walk' = Log a walk that already happened - - We need both because kids forget to book but parents + + We need both because kids forget to book but parents want to track completed walks for the leaderboard." ``` **Agent captures the insight:** + ``` Agent: "Got it! Two distinct use cases: - Book Walk → Future planning (proactive) - Add Walk → Retroactive logging (accountability) - - Should I document this distinction in the Feature file + + Should I document this distinction in the Feature file so developers understand the different workflows?" ``` @@ -329,18 +359,19 @@ Agent: "Let me help you think through this. Pros and cons: ✅ Focuses on rhythm, not specific dates ❌ Users might need to check what week it is ❌ Less familiar to non-Swedish users - + Specific Dates: ✅ Immediately clear what day it is ✅ Universal understanding ❌ More visual clutter ❌ Doesn't match Swedish planning culture - - Given your target users are Swedish families, + + Given your target users are Swedish families, which approach serves them better?" ``` **Designer thinks through it:** + ``` Designer: "You're right - Swedish families think in weeks. 'Vecka 40' is how they plan. Let's keep week numbers @@ -348,12 +379,13 @@ Designer: "You're right - Swedish families think in weeks. ``` **Agent captures the decision:** + ``` Agent: "Perfect! Documenting: - Primary: Week number (Swedish mental model) - Secondary: Date range (clarity) - Rationale: Matches target user planning culture - + This also goes in your design system as a pattern." ``` @@ -364,22 +396,27 @@ Agent: "Perfect! Documenting: ### Designer Benefits ✅ **Focus on thinking, not documentation** + - Agent handles systematic capture - Designer focuses on creative decisions ✅ **Maintain consistency effortlessly** + - Agent tracks patterns across pages - Designer confirms or corrects ✅ **Iterate faster** + - Agent guides structured decomposition - Designer doesn't get overwhelmed ✅ **Nothing gets missed** + - Agent asks systematic questions - Designer provides context ✅ **Design system integrity** + - Agent catches inconsistencies - Designer maintains coherence @@ -388,18 +425,22 @@ Agent: "Perfect! Documenting: ### Project Benefits ✅ **Complete specifications** + - Nothing forgotten or assumed - Clear handoffs to developers ✅ **Maintainable documentation** + - Structured, not monolithic - Easy to update ✅ **Faster development** + - Developers have clear instructions - AI code generators have precise prompts ✅ **Better products** + - Designer thinking + Agent systematization - Strategic decisions + consistent execution @@ -410,6 +451,7 @@ Agent: "Perfect! Documenting: **Agents don't replace designers.** **Agents optimize designer craft by:** + - Handling systematic work - Ensuring consistency - Guiding structured workflows @@ -417,6 +459,7 @@ Agent: "Perfect! Documenting: - Documenting decisions **This frees designers to:** + - Think strategically - Make creative decisions - Solve complex problems @@ -424,6 +467,7 @@ Agent: "Perfect! Documenting: - Balance competing priorities **The result:** + - 10x faster specification - 10x better consistency - 10x more complete documentation @@ -436,6 +480,7 @@ Agent: "Perfect! Documenting: ## Related Concepts ### [Why-Based Specifications](../WHY-BASED-SPECIFICATIONS.md) + How capturing WHY (not just WHAT) makes AI implementation correct --- diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/complexity-detection.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/complexity-detection.md index d5793593..f7d659cc 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/complexity-detection.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/complexity-detection.md @@ -12,6 +12,7 @@ - ✅ No business logic **Examples:** + - Static text - Image - Basic button (just click → navigate) @@ -30,6 +31,7 @@ - ⚠️ State machines (defined transition paths) **Examples:** + - Calendar widget (6 states) - Search with autocomplete (5+ states) - Multi-step form (progress tracking) @@ -44,6 +46,7 @@ ### Example 1: Simple Button **Indicators:** + - ✅ Single interaction (click → navigate) - ✅ 2-3 states (default, hover, active) - ❌ No business logic @@ -56,6 +59,7 @@ ### Example 2: Search Bar **Indicators:** + - ⚠️ Multiple states (empty, typing, loading, results, error) - ⚠️ Real-time updates (debounced API calls) - ⚠️ Business logic (min 3 characters, max 10 results) @@ -69,6 +73,7 @@ ### Example 3: Calendar Widget **Indicators:** + - ⚠️ 6 walk states - ⚠️ Time-based transitions (countdown timers) - ⚠️ Complex business rules (per-dog blocking) @@ -83,6 +88,7 @@ ## When to Decompose **Decompose when component has:** + - 3+ visual states - Business rules - API dependencies @@ -90,12 +96,14 @@ - Multi-component interactions **Keep simple when component has:** + - 1-2 states - No logic - No data - Static display **⚠️ Common Mistake:** + ```markdown ❌ Wrong: Everything in one file Pages/02-calendar-page.md (800 lines) diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/content-placement-rules.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/content-placement-rules.md index e40e77d6..12abb7ad 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/content-placement-rules.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/content-placement-rules.md @@ -21,20 +21,24 @@ Does CONTENT vary by page context? ## Page File Content **Document in Page file when:** + - ✅ Content changes per page - ✅ Data varies by user/context - ✅ Configuration differs by placement **Examples:** + - Hero heading: "Welcome" (Home) vs "About Us" (About) - Search placeholder: "Search products..." vs "Search help..." - Calendar header: "Familjen Svensson: Vecka 40" (user's family) - API endpoint: `/api/families/:currentFamilyId/walks` (user-specific) **⚠️ Common Mistake:** + ```markdown ❌ Wrong: Features/hero-logic.feature.md **Content:** + - Heading: "Welcome to Dog Week" (Home page) - Heading: "About Dog Week" (About page) @@ -48,25 +52,30 @@ Pages/02-about-page.md → "About Dog Week" ## Feature File Content **Document in Feature file when:** + - ✅ Content is the same everywhere - ✅ Generic validation messages - ✅ Standard UI text **Examples:** + - Button text: "Submit" (always the same) - Error message: "Invalid email" (generic validation) - Loading text: "Loading..." (standard) - Tooltip: "Click to expand" (generic interaction) **⚠️ Common Mistake:** + ```markdown ❌ Wrong: Pages/01-home-page.md **Content:** + - Submit button: "Submit" - Error message: "Invalid email" ✅ Right: Features/form-submit-logic.feature.md **Generic Content:** + - Submit button: "Submit" - Error message: "Invalid email" ``` @@ -76,19 +85,23 @@ Pages/02-about-page.md → "About Dog Week" ## Component File Content **Component files contain NO content:** + - ❌ No text - ❌ No images - ❌ No data - ✅ Only visual design (colors, spacing, states) **Exception:** Content slots + ```markdown **Content Slots:** + - Heading text (configurable per page) - Background image (configurable per page) ``` **⚠️ Common Mistakes:** + ```markdown ❌ Wrong: Features/button-logic.feature.md **Visual:** Background: Blue, Height: 48px @@ -109,18 +122,18 @@ Pages/02-about-page.md → "About Dog Week" ## Decision Matrix -| Content Type | Page-Specific? | Where? | -|--------------|----------------|--------| -| Hero heading | ✅ YES | Page | -| Hero background | ✅ YES | Page | -| Search placeholder | ✅ YES | Page | -| User's family name | ✅ YES | Page | -| API with user context | ✅ YES | Page | -| Submit button text | ❌ NO | Feature | -| Error messages | ❌ NO | Feature | -| Loading text | ❌ NO | Feature | -| Tooltip text | ❌ NO | Feature | -| Button color | ❌ Visual | Component | +| Content Type | Page-Specific? | Where? | +| --------------------- | -------------- | --------- | +| Hero heading | ✅ YES | Page | +| Hero background | ✅ YES | Page | +| Search placeholder | ✅ YES | Page | +| User's family name | ✅ YES | Page | +| API with user context | ✅ YES | Page | +| Submit button text | ❌ NO | Feature | +| Error messages | ❌ NO | Feature | +| Loading text | ❌ NO | Feature | +| Tooltip text | ❌ NO | Feature | +| Button color | ❌ Visual | Component | --- diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/three-tier-overview.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/three-tier-overview.md index 893f8e25..6a887e81 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/three-tier-overview.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/01-core-concepts/three-tier-overview.md @@ -7,9 +7,11 @@ ## The Three File Types ### 1. Pages/ (WHERE) + **Purpose:** Page-specific context and placement **Contains:** + - Position & size - Page-specific content (varies by page) - Page-specific data (user context) @@ -17,8 +19,10 @@ - Feature references **Example:** + ```markdown Pages/02-calendar-page.md + - Position: Main content, full-width - Content: "Familjen Svensson: Vecka 40" (user's family) - Data: GET /api/families/:currentFamilyId/walks @@ -29,9 +33,11 @@ Pages/02-calendar-page.md --- ### 2. Components/ (HOW IT LOOKS) + **Purpose:** Visual design specifications **Contains:** + - Visual specs (colors, spacing, typography) - States (default, hover, active, loading, error) - Variants (sizes, types, themes) @@ -40,8 +46,10 @@ Pages/02-calendar-page.md - ❌ NO content, NO logic **Example:** + ```markdown Components/walk-slot-card.component.md + - 6 visual states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED) - Typography: 16px Medium, 12px Regular - Colors: Blue (#3B82F6), Orange (#FB923C), etc. @@ -51,9 +59,11 @@ Components/walk-slot-card.component.md --- ### 3. Features/ (WHAT IT DOES) + **Purpose:** Functional logic and business rules **Contains:** + - User interactions - Business rules - State management @@ -63,8 +73,10 @@ Components/walk-slot-card.component.md - ❌ NO visual design **Example:** + ```markdown Features/walk-booking-logic.feature.md + - Book walk → GRAY state - Start walk → BLUE state - Business rule: One active walk per dog @@ -77,6 +89,7 @@ Features/walk-booking-logic.feature.md ## Why Three Tiers? ### Before (Monolithic) + ``` Pages/02-calendar-page.md (800 lines) ├─ Everything mixed together @@ -86,6 +99,7 @@ Pages/02-calendar-page.md (800 lines) ``` ### After (Modular) + ``` Pages/02-calendar-page.md (100 lines) ├─ Just placement + user context @@ -104,16 +118,19 @@ Features/walk-booking-logic.feature.md (200 lines) ## Handoff Strategy **Visual Designer** receives: + - `Components/` folder - Creates Figma components - Matches visual specs exactly **Developer** receives: + - `Features/` folder - Implements business logic - Uses API endpoints specified **You** maintain: + - `Pages/` folder - Track design system integrity - Manage page-specific content diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-what-are-storyboards.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-what-are-storyboards.md index b3887212..38701f78 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-what-are-storyboards.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-what-are-storyboards.md @@ -7,6 +7,7 @@ ## Definition A **storyboard** is a visual sequence showing: + - State transitions (empty → loading → active → completed) - User interactions (click, type, swipe) - System responses (updates, animations, feedback) @@ -17,11 +18,13 @@ A **storyboard** is a visual sequence showing: ## Format **Hand-drawn sketches** (recommended): + - Quick to create - Easy to iterate - Focus on functionality, not polish **Example:** Dog Week `App-Main-Booking-States.jpg` + - 6 frames showing walk states - Numbered sequentially - Annotated with triggers @@ -31,6 +34,7 @@ A **storyboard** is a visual sequence showing: ## Purpose Storyboards answer: + - "What does this look like in each state?" - "How do users move between states?" - "What triggers each transition?" @@ -41,12 +45,14 @@ Storyboards answer: ## Why Visual? **Text description:** + ``` -When the user books a walk, the card changes to gray, +When the user books a walk, the card changes to gray, the leaderboard updates, and the week overview changes. ``` **Storyboard:** + ``` Frame 1: WHITE card with "Book" button Frame 2: User taps "Book" diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-when-to-use.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-when-to-use.md index 89ad1911..3ad10f4c 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-when-to-use.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/01-when-to-use.md @@ -7,18 +7,23 @@ ## Create Storyboards For: ✅ **Components with 3+ states** + - Example (Dog Week): Walk slots (WHITE, GRAY, ORANGE, BLUE, GREEN, RED) ✅ **Time-based transitions** + - Example (Dog Week): Countdown timers, auto-state changes ✅ **Multi-step user flows** + - Example (Dog Week): Booking → Starting → Completing a walk ✅ **Complex interactions between components** + - Example (Dog Week): Calendar updates leaderboard and week view ✅ **State machines with branching paths** + - Example (Dog Week): Success path vs error path vs timeout path --- @@ -26,12 +31,15 @@ ## Don't Need Storyboards For: ❌ **Simple buttons** + - Hover and active states are obvious ❌ **Static content sections** + - No state changes to document ❌ **Single-state components** + - Nothing to show in sequence --- @@ -39,12 +47,14 @@ ## Examples ### Need Storyboard: + - **Dog Week:** Calendar booking (6 states, time-based) - **Future Project:** Search with autocomplete (5 states, real-time) - **Future Project:** Multi-step form (progress tracking) - **Future Project:** Payment flow (multiple steps, error handling) ### Don't Need Storyboard: + - Submit button (2-3 states) - Hero image (static) - Text paragraph (no states) diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/02-file-structure.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/02-file-structure.md index 8396cbb0..39cceff1 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/02-file-structure.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/02-file-structure.md @@ -30,6 +30,7 @@ project-root/ ## Why Features/Storyboards/? Storyboards document **functionality**, not visual design: + - State transitions (functional) - User interactions (functional) - Business logic flows (functional) @@ -41,6 +42,7 @@ Therefore, they belong with **Features**, not Components. ## Reference Pattern **From Feature File:** + ```markdown Features/walk-booking-logic.feature.md @@ -50,6 +52,7 @@ Features/walk-booking-logic.feature.md ``` **From Component File:** + ```markdown Components/walk-slot-card.component.md @@ -64,11 +67,13 @@ See storyboard for state transitions: ## Separation from Page Sketches **Page Sketches** (Sketches/ folder): + - Show page layout - Static view of entire page - Used during initial design **Storyboards** (Features/Storyboards/ folder): + - Show component behavior - Sequential frames showing changes - Used during specification diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/complexity-router-workflow.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/complexity-router-workflow.md index 29be6ce5..96573354 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/complexity-router-workflow.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/complexity-router-workflow.md @@ -26,6 +26,7 @@ When a complex component is detected, the agent guides you through 3 steps: 6. **Does DATA source change based on page context?** **You answer, agent captures:** + - Pages list - Position - Size @@ -49,6 +50,7 @@ When a complex component is detected, the agent guides you through 3 steps: - Can it transition to other states? **You answer, agent captures:** + - State count - State definitions - Storyboard reference (if exists) @@ -69,6 +71,7 @@ When a complex component is detected, the agent guides you through 3 steps: 5. Does it update other components? **You answer, agent captures:** + - User actions - System responses - Business rules @@ -88,6 +91,7 @@ See: [Coaching Dialogue Example](examples/coaching-dialogue.md) ## Output: Three Files **1. Page File** + ```markdown Pages/02-calendar-page.md @@ -96,33 +100,40 @@ Pages/02-calendar-page.md **Position:** Main content, full-width **Page-Specific Content:** + - Header: "Familjen Svensson: Vecka 40" - Data: GET /api/families/:currentFamilyId/walks ``` **2. Component File** + ```markdown Components/walk-slot-card.component.md **Visual Specifications:** + - 6 states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED) - Typography, colors, spacing - Storyboard: Features/Storyboards/walk-states.jpg ``` **3. Feature File** + ```markdown Features/walk-booking-logic.feature.md **User Interactions:** + - Book walk → GRAY state - Start walk → BLUE state **Business Rules:** + - One active walk per dog - Can't book if slot taken **API Endpoints:** + - POST /api/walks - PUT /api/walks/:id/start ``` diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/page-specification-workflow.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/page-specification-workflow.md index ea2cace7..624157f5 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/page-specification-workflow.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/page-specification-workflow.md @@ -15,6 +15,7 @@ The agent guides you through specifying a page **from top to bottom**, one secti ### Step 1: Identify All Sections **Agent analyzes sketch and outputs:** + ``` 📋 Page Sections Detected: @@ -28,6 +29,7 @@ Does this match your sketch? Any sections missing or incorrectly identified? ``` **You respond:** + - Confirm sections - Add missing sections - Rename sections @@ -38,6 +40,7 @@ Does this match your sketch? Any sections missing or incorrectly identified? ### Step 2: Section Purpose **For each section, agent asks:** + ``` 📍 Section: Navigation Header @@ -49,11 +52,13 @@ What is the purpose of this section? ``` **You respond:** + ``` "User navigation and branding. Shows logo, main menu, and user profile." ``` **Agent captures:** + ```markdown ## Navigation Header @@ -66,6 +71,7 @@ What is the purpose of this section? ### Step 3: List Objects in Section **Agent outputs:** + ``` 🔍 Objects in Navigation Header: @@ -77,6 +83,7 @@ Shall I specify each object, or is this section simple enough to keep schematic? ``` **You choose:** + - **Option A:** "Specify each object" → Go deeper - **Option B:** "Keep schematic" → Move to next section @@ -85,6 +92,7 @@ Shall I specify each object, or is this section simple enough to keep schematic? ### Step 4: Decompose Containers **If object is a container, agent asks:** + ``` 📦 Main Menu (Container) @@ -98,13 +106,16 @@ Are these simple links, or do any need detailed specs? ``` **You respond:** + ``` "Simple links, no detail needed" ``` **Agent captures:** + ```markdown ### Main Menu + - Home link - Calendar link - Leaderboard link @@ -116,6 +127,7 @@ Are these simple links, or do any need detailed specs? ### Step 5: Specify Atomic Components **When reaching smallest parts:** + ``` 🔬 User Profile (Dropdown) @@ -128,6 +140,7 @@ C) Skip for now, mark as TODO ``` **You choose based on complexity:** + - **Simple:** Keep in Page file - **Complex:** Decompose to 3 files - **Later:** Mark TODO @@ -139,18 +152,21 @@ C) Skip for now, mark as TODO ### Full Workflow **Step 1: Sections** + ``` Agent: "I see 5 sections: Header, Week Overview, Leaderboard, Calendar, Footer" You: "Correct!" ``` **Step 2: Section Purposes** + ``` Agent: "What's the purpose of Week Overview?" You: "Shows current week number and 7-day status circles" ``` **Step 3: Week Overview Objects** + ``` Agent: "Objects detected: 1. Week number label (text) @@ -161,6 +177,7 @@ You: "Specify the day circles, they have states" ``` **Step 4: Day Circle Component** + ``` Agent: "Day circles look complex (3 states: empty, booked, completed). Should I create Component + Feature files?" @@ -168,6 +185,7 @@ You: "Yes, decompose it" ``` **Step 5: Calendar Section** + ``` Agent: "Calendar has 6 walk states, countdown timers, business rules. This is highly complex. Should I: @@ -183,16 +201,19 @@ You: "Yes, decompose and reference storyboard" At each step, you decide: ### Detail Level + - **Schematic:** Just list components, no details - **Moderate:** Basic specs (size, position, content) - **Detailed:** Full 3-tier decomposition ### When to Stop + - **Good enough:** "This is clear, move on" - **Need detail:** "Let's specify this fully" - **Later:** "Mark as TODO, we'll come back" ### Feedback Loop + ``` Agent: "Here's what I captured for Navigation Header..." You: "Actually, the logo should be clickable and link to home" @@ -204,16 +225,20 @@ Agent: "Updated! Logo is now a link component." ## Output Structure ### Schematic Page Spec + ```markdown Pages/02-calendar-page.md ## Navigation Header + **Purpose:** User navigation and branding + - Logo (clickable, links to home) - Main menu (4 links) - User profile dropdown ## Calendar Section + **Purpose:** Book and manage dog walks **Component:** → walk-slot-card.component.md **Feature:** → walk-booking-logic.feature.md @@ -221,26 +246,31 @@ Pages/02-calendar-page.md ``` ### Detailed Page Spec + ```markdown Pages/02-calendar-page.md ## Navigation Header + **Purpose:** User navigation and branding **Position:** Top, full-width, fixed **Height:** 64px ### Logo + **Component:** → logo.component.md **Position:** Left, 16px padding **Size:** 40x40px **Action:** Click → Navigate to home ### Main Menu + **Component:** → nav-menu.component.md **Position:** Center **Items:** Home, Calendar, Leaderboard, Settings ### User Profile + **Component:** → user-dropdown.component.md **Feature:** → user-menu-logic.feature.md **Position:** Right, 16px padding @@ -262,12 +292,14 @@ Pages/02-calendar-page.md ## When to Use **Use this workflow when:** + - Starting a new page specification - Converting a sketch to structured specs - Unsure how detailed to be - Want guided decomposition **Skip this workflow when:** + - Page is extremely simple (1-2 sections) - You already know the structure - Rapid prototyping (schematic only) diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/storyboards-guide.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/storyboards-guide.md index bc413190..55311f64 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/storyboards-guide.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/02-workflows/storyboards-guide.md @@ -7,12 +7,15 @@ ## Core Concepts (01-) ### [What Are Storyboards?](01-what-are-storyboards.md) + Visual documentation of state transitions and flows ### [When to Use Storyboards](01-when-to-use.md) + Complexity indicators that require visual documentation ### [Storyboard Types](01-storyboard-types.md) + State transitions, interaction flows, multi-component sync --- @@ -20,9 +23,11 @@ State transitions, interaction flows, multi-component sync ## Storage & Organization (02-) ### [File Structure](02-file-structure.md) + Where to store storyboards in the three-tier architecture ### [Naming Conventions](02-naming-conventions.md) + How to name storyboard files --- @@ -30,9 +35,11 @@ How to name storyboard files ## Creation Guidelines ### [How to Create Storyboards](creation-guide.md) + Hand-drawn, digital, or annotated screenshots ### [Annotation Best Practices](annotation-guide.md) + Numbering, labels, and visual indicators --- @@ -40,9 +47,11 @@ Numbering, labels, and visual indicators ## Integration ### [Referencing in Feature Files](feature-file-integration.md) + How to link storyboards from specifications ### [Referencing in Component Files](component-file-integration.md) + Visual state references --- @@ -50,9 +59,11 @@ Visual state references ## Examples ### [Dog Week Calendar States](examples/calendar-states.md) + 6-state walk booking storyboard ### [Search Flow](examples/search-flow.md) + Multi-step interaction storyboard --- @@ -60,4 +71,5 @@ Multi-step interaction storyboard ## Benefits ### [Why Storyboards Work](benefits.md) + Developer clarity, QA testing, design consistency diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/benefits.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/benefits.md index 862c5516..e2e2f6bb 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/benefits.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/benefits.md @@ -7,11 +7,13 @@ ## 1. Prevents Overwhelming Specs **Before:** + - 800-line monolithic file - Everything mixed together - Hard to find anything **After:** + - 3 focused files (100-200 lines each) - Clear separation - Easy to navigate @@ -21,16 +23,19 @@ ## 2. Clean Handoffs **Visual Designer** receives: + - `Components/` folder only - Clear visual specifications - Creates Figma components **Developer** receives: + - `Features/` folder only - Clear business logic - Implements functionality **You** maintain: + - `Pages/` folder - Design system integrity - Page-specific content @@ -43,7 +48,8 @@ **Cause:** Monolithic spec, developer overwhelmed -**Solution:** +**Solution:** + - Component file lists ALL visual elements - Feature file lists ALL interactions - Storyboard shows ALL states @@ -56,11 +62,13 @@ **Change request:** "Add countdown timers" **Before (Code):** + - Regenerate code - Previous features break - 2+ hours fixing **After (Spec):** + - Update Feature file (15 minutes) - Regenerate with full context - Everything works @@ -96,6 +104,7 @@ Everyone works in parallel, no conflicts. ## 7. Design System Integrity **Page files** reference components: + ```markdown **Component:** button-primary.component.md ``` @@ -113,6 +122,7 @@ Easy to update design system globally. **Over product lifecycle:** 100+ hours **Quality improvement:** + - Zero missing features - Consistent design - Maintainable codebase diff --git a/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/decision-tree.md b/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/decision-tree.md index 4c45a36c..9964f3f1 100644 --- a/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/decision-tree.md +++ b/src/modules/wds/workflows/4-ux-design/modular-architecture/03-quick-refs/decision-tree.md @@ -34,12 +34,14 @@ ## Examples **Page File (Content Varies):** + - ✅ Hero heading: "Welcome" (Home) vs "About" (About) - ✅ Search placeholder: "Search products..." vs "Search help..." - ✅ Calendar header: "Familjen Svensson: Vecka 40" (user's family) - ✅ Data API: `/api/families/:currentFamilyId/walks` (user-specific) **Feature File (Content Same Everywhere):** + - ✅ Button text: "Submit" (always the same) - ✅ Error message: "Invalid email" (generic validation) - ✅ Tooltip: "Click to expand" (generic interaction) diff --git a/src/modules/wds/workflows/4-ux-design/object-types/COMPLEXITY-ROUTER.md b/src/modules/wds/workflows/4-ux-design/object-types/COMPLEXITY-ROUTER.md index a3ad8468..f9ed68eb 100644 --- a/src/modules/wds/workflows/4-ux-design/object-types/COMPLEXITY-ROUTER.md +++ b/src/modules/wds/workflows/4-ux-design/object-types/COMPLEXITY-ROUTER.md @@ -21,12 +21,14 @@ Analyze complexity indicators: **Simple Component Indicators:** + - Single state (no hover, active, loading variations) - No user interaction (static display) - No data dependencies - No business logic **Complex Component Indicators:** + - Multiple states (3+ states: empty, loading, active, completed, error) - Time-based changes (countdowns, timers, real-time updates) - Multi-step interactions (booking → starting → completing) @@ -35,9 +37,10 @@ - State machines (defined transition paths) **Examples:** + - **Simple:** Static text, image, basic button - **Complex:** Calendar widget, booking system, search with filters, multi-step form - + --- @@ -52,6 +55,7 @@ This {{object_name}} is straightforward - I'll document it in the page specification. **What I'll capture:** + - Visual appearance (size, color, position) - Content (text in all languages) - Basic interaction (if any) @@ -75,10 +79,12 @@ I see this {{object_name}} has multiple states and interactions. Let me help you **Complexity Indicators I Found:** {{#each complexity_indicators}} + - {{indicator_description}} -{{/each}} + {{/each}} **To keep this manageable, I'll help you separate:** + 1. **Page Context** - Where it appears, size, position 2. **Visual Design** - How each state looks (for Figma) 3. **Functional Logic** - How it behaves, business rules @@ -102,9 +108,9 @@ Choice [1/2]: **Okay!** I'll document everything in the page spec. ⚠️ **Note:** This may create a large specification file. Consider decomposition for easier maintenance. - - Route to standard object-type file - Document in Page file only + +Route to standard object-type file +Document in Page file only @@ -116,6 +122,7 @@ Choice [1/2]: **Let's break down this {{object_name}} into manageable pieces!** I'll ask you questions to separate the three concerns: + - **WHERE** it appears (Page) - **HOW** it looks (Component) - **WHAT** it does (Feature) @@ -153,23 +160,25 @@ I'll ask you questions to separate the three concerns: Your answers: Capture page context: + - Pages: {{pages_list}} - Position: {{position}} - Size: {{size}} - Reusability: {{is_reusable}} - Content Varies: {{content_varies_by_page}} - Data Source Varies: {{data_source_varies_by_page}} - + **✅ Page Context Captured** **What goes in the Page file:** {{#if content_varies_by_page}} + - ✅ **Page-Specific Content** (headings, text, images that change per page) -{{/if}} -{{#if data_source_varies_by_page}} + {{/if}} + {{#if data_source_varies_by_page}} - ✅ **Page-Specific Data Configuration** (API endpoints, filters, scope) -{{/if}} + {{/if}} - ✅ **Position & Size** (where and how big) - ✅ **Component Reference** (link to visual design) - ✅ **Feature Reference** (link to functionality) @@ -180,8 +189,9 @@ Your answers: This will go in: {{#each pages_list}} + - `Pages/{{page_number}}-{{page_name}}.md` -{{/each}} + {{/each}} --- @@ -194,6 +204,7 @@ This will go in: Looking at your sketch/storyboard, how many different visual states does this component have? Examples: + - **Simple:** Just 1 state (always looks the same) - **Interactive:** 2-3 states (default, hover, active) - **Complex:** 4+ states (empty, loading, active, completed, error) @@ -241,10 +252,11 @@ Examples: **✅ Visual Design Captured** This will go in: + - `Components/{{component_name}}.component.md` -{{#if has_storyboard}} + {{#if has_storyboard}} - Storyboard reference: `Features/Storyboards/{{storyboard_file}}` -{{/if}} + {{/if}} --- @@ -272,20 +284,22 @@ This will go in: Your answers: Capture functional logic: + - User Actions: {{user_actions_list}} - System Responses: {{system_responses_list}} - Business Rules: {{business_rules_list}} - API Dependencies: {{api_endpoints_list}} - Component Sync: {{synced_components_list}} - + **✅ Functional Logic Captured** This will go in: + - `Features/{{feature_name}}.feature.md` -{{#if has_storyboard}} + {{#if has_storyboard}} - Storyboard reference: `Features/Storyboards/{{storyboard_file}}` -{{/if}} + {{/if}} --- @@ -294,6 +308,7 @@ This will go in: **Great! Here's how your {{object_name}} will be documented:** **1. Page File** (`Pages/{{page_number}}-{{page_name}}.md`) + ```markdown ### {{section_name}} @@ -305,11 +320,13 @@ This will go in: **Configuration:** {{#each page_specific_config}} + - {{config_item}} -{{/each}} + {{/each}} ``` **2. Component File** (`Components/{{component_name}}.component.md`) + ```markdown # {{component_name}} Component @@ -319,19 +336,24 @@ This will go in: ## Visual Specifications {{#each states}} + ### State: {{state_name}} + - Background: {{background_color}} - Icons: {{icons_list}} - Layout: {{layout_description}} -{{/each}} + {{/each}} {{#if has_storyboard}} + ## Visual Storyboard + ![{{storyboard_name}}](../Features/Storyboards/{{storyboard_file}}) {{/if}} ``` **3. Feature File** (`Features/{{feature_name}}.feature.md`) + ```markdown # {{feature_name}} Feature @@ -339,35 +361,43 @@ This will go in: **Type:** {{feature_type}} {{#if has_storyboard}} + ## Visual Storyboard + ![{{storyboard_name}}](Storyboards/{{storyboard_file}}) {{/if}} ## User Interactions {{#each user_actions}} + ### {{action_name}} + **Flow:** + 1. User {{user_action}} 2. System {{system_response}} 3. Updates: {{component_updates}} -{{/each}} + {{/each}} ## Business Rules + {{#each business_rules}} + - {{rule_description}} -{{/each}} + {{/each}} ## API Endpoints + {{#each api_endpoints}} + - {{endpoint_description}} -{{/each}} + {{/each}} ``` **Does this breakdown look good?** -1. **Yes** - Create these files -2. **Adjust** - I need to change something +1. **Yes** - Create these files 2. **Adjust** - I need to change something Choice [1/2]: @@ -404,6 +434,7 @@ Choice [1/2]: **Object:** "Get Started" button **Complexity Assessment:** + - ✅ Single interaction (click → navigate) - ✅ 2-3 states (default, hover, active) - ❌ No business logic @@ -419,6 +450,7 @@ Choice [1/2]: **Object:** Search input with dropdown suggestions **Complexity Assessment:** + - ⚠️ Multiple states (empty, typing, loading, results, no results, error) - ⚠️ Real-time updates (debounced API calls) - ⚠️ Business logic (minimum 3 characters, max 10 results) @@ -428,7 +460,8 @@ Choice [1/2]: **Result:** **COMPLEX** - Decompose into 3 files **Decomposition:** -- **Page (if content varies):** + +- **Page (if content varies):** - Product page: Placeholder "Search products...", scope: products only - Help page: Placeholder "Search help...", scope: help articles only - **Component:** Visual states (empty, focused, loading, results dropdown) @@ -441,6 +474,7 @@ Choice [1/2]: **Object:** Dog Week calendar with week view, leaderboard, booking slots **Complexity Assessment:** + - ⚠️ 6 walk states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED) - ⚠️ Time-based transitions (countdown timers, auto-state changes) - ⚠️ Complex business rules (per-dog blocking, early start rules) @@ -451,6 +485,7 @@ Choice [1/2]: **Result:** **HIGHLY COMPLEX** - Decompose into 3 files + storyboard **Decomposition:** + - **Page:** Layout (3 sections: week overview, leaderboard, calendar), responsive behavior - **Component:** Visual design of all 6 states, week circles, leaderboard cards - **Feature:** State machine logic, booking flow, time-based transitions, API integration @@ -463,10 +498,11 @@ Choice [1/2]: ### Scenario: Designer adds Calendar Widget **Agent:** + ``` 🔍 Complex Component Detected -I see this "Calendar Booking Widget" has multiple states and interactions. +I see this "Calendar Booking Widget" has multiple states and interactions. Let me help you break this down properly! **Complexity Indicators I Found:** @@ -489,6 +525,7 @@ Ready to break this down? **Designer:** "Yes" **Agent:** + ``` Let's break down this Calendar Booking Widget into manageable pieces! @@ -504,7 +541,8 @@ Let's break down this Calendar Booking Widget into manageable pieces! 4. Is this the same component on multiple pages, or page-specific? ``` -**Designer:** +**Designer:** + ``` 1. Calendar page only 2. Main content area, takes up full width below header @@ -515,7 +553,8 @@ Let's break down this Calendar Booking Widget into manageable pieces! ``` **Agent:** -``` + +```` ✅ Page Context Captured **What goes in the Page file:** @@ -548,27 +587,30 @@ This will go in: - API Endpoint: GET /api/families/:currentFamilyId/walks?week=:weekNumber - Dogs Displayed: All dogs in current user's family - Family Members: All members in current user's family -``` +```` --- ### Step 2: Visual Design (HOW IT LOOKS) -Looking at your sketch/storyboard, how many different visual states does +Looking at your sketch/storyboard, how many different visual states does this component have? **How many states do you see?** + ``` **Designer:** "6 states - I have a storyboard showing them all" **Agent:** ``` + 📊 Multiple States Detected! **For each state, I need:** State 1: Empty (WHITE) + 1. What does it look like? 2. What triggers this state? 3. Can it transition to other states? @@ -576,15 +618,18 @@ State 1: Empty (WHITE) [... repeat for all 6 states ...] **Do you have a storyboard sketch showing these states?** + ``` **Designer:** "Yes, see Sketches/App-Main-Booking-States.jpg" **Agent:** ``` + ✅ Visual Design Captured This will go in: + - `Components/walk-slot-card.component.md` - Storyboard reference: `Features/Storyboards/walk-state-transitions.jpg` @@ -599,23 +644,28 @@ This will go in: 3. Are there any business rules? 4. Does it need data from an API? 5. Does it update other components? + ``` **Designer:** ``` + 1. Book walks, start walks, complete walks 2. Card changes color, leaderboard updates, week view syncs -3. Can't start walk if another is active for same dog, +3. Can't start walk if another is active for same dog, can't book if slot already taken 4. Yes - GET /api/walks, POST /api/walks, PUT /api/walks/:id 5. Yes - updates leaderboard count and week overview quarter circles + ``` **Agent:** ``` + ✅ Functional Logic Captured This will go in: + - `Features/walk-booking-logic.feature.md` - Storyboard reference: `Features/Storyboards/walk-state-transitions.jpg` @@ -626,16 +676,19 @@ This will go in: **Great! Here's how your Calendar Booking Widget will be documented:** **1. Page File** (`Pages/02-calendar-page.md`) + - Position: Main content, full-width - Component reference: `walk-slot-card.component.md` - Feature reference: `walk-booking-logic.feature.md` **2. Component File** (`Components/walk-slot-card.component.md`) + - 6 visual states with colors, icons, layouts - Storyboard: `Features/Storyboards/walk-state-transitions.jpg` - Figma component mapping **3. Feature File** (`Features/walk-booking-logic.feature.md`) + - State machine with 6 states - Business rules (blocking, validation) - API endpoints @@ -643,15 +696,18 @@ This will go in: - Storyboard: `Storyboards/walk-state-transitions.jpg` **Does this breakdown look good?** + ``` **Designer:** "Yes!" **Agent:** ``` + ✅ Perfect! I'll create the three files. **Next Steps:** + - Page file: Lightweight, just placement and config - Component file: Visual design for Figma handoff - Feature file: Logic for developer implementation @@ -659,9 +715,11 @@ This will go in: This keeps everything organized and maintainable! **Handoff Strategy:** + - Send Component file → Visual Designer (for Figma) - Send Feature file → Developer (for implementation) - Keep Page file → Your reference for layout + ``` --- @@ -672,15 +730,18 @@ This keeps everything organized and maintainable! **Before (Monolithic):** ``` + Pages/02-calendar-page.md (800 lines) ├─ Everything mixed together ├─ Developer confused about what to build ├─ Designer confused about what to design └─ Prototype misses features (leaderboard, week view) + ``` **After (Decomposed):** ``` + Pages/02-calendar-page.md (100 lines) ├─ Just layout and references @@ -691,6 +752,7 @@ Components/walk-slot-card.component.md (150 lines) Features/walk-booking-logic.feature.md (200 lines) ├─ Logic only └─ Developer knows exactly what to implement + ``` ### 2. Clear Handoffs @@ -717,26 +779,27 @@ Features/walk-booking-logic.feature.md (200 lines) ## Content Placement Decision Tree ``` + ┌─────────────────────────────────────────────────┐ -│ Does CONTENT vary by page context? │ -│ (text, images, data source) │ +│ Does CONTENT vary by page context? │ +│ (text, images, data source) │ └────────────┬────────────────────────────────────┘ - │ - ┌──────┴──────┐ - │ │ - YES NO - │ │ - ▼ ▼ -┌─────────────┐ ┌──────────────┐ -│ Page File │ │ Feature File │ -│ │ │ │ -│ Document: │ │ Document: │ -│ - Headings │ │ - Generic │ -│ - Text │ │ content │ -│ - Images │ │ - Default │ -│ - Data API │ │ config │ -│ - Scope │ │ │ -└─────────────┘ └──────────────┘ +│ +┌──────┴──────┐ +│ │ +YES NO +│ │ +▼ ▼ +┌─────────────┐ ┌──────────────┐ +│ Page File │ │ Feature File │ +│ │ │ │ +│ Document: │ │ Document: │ +│ - Headings │ │ - Generic │ +│ - Text │ │ content │ +│ - Images │ │ - Default │ +│ - Data API │ │ config │ +│ - Scope │ │ │ +└─────────────┘ └──────────────┘ Examples: @@ -751,6 +814,7 @@ Feature File (Content Same Everywhere): ✅ Error message: "Invalid email" (generic validation) ✅ Tooltip: "Click to expand" (generic interaction) ✅ Data API: /api/products (same for all users) + ``` --- @@ -775,3 +839,4 @@ Feature File (Content Same Everywhere): - ✅ Easy to maintain and update - ✅ Design system integrity preserved - ✅ Clear separation of page-specific vs generic content +``` diff --git a/src/modules/wds/workflows/4-ux-design/object-types/ROUTER-FLOW-DIAGRAM.md b/src/modules/wds/workflows/4-ux-design/object-types/ROUTER-FLOW-DIAGRAM.md index 7834cd06..dd33ec52 100644 --- a/src/modules/wds/workflows/4-ux-design/object-types/ROUTER-FLOW-DIAGRAM.md +++ b/src/modules/wds/workflows/4-ux-design/object-types/ROUTER-FLOW-DIAGRAM.md @@ -121,6 +121,7 @@ ## Key Changes ### OLD: Generic Object Detection + ``` 1. Ask user "What type is this?" [list of 20 options] 2. User selects from list @@ -128,6 +129,7 @@ ``` ### NEW: Text-First with Intelligence + ``` 1. Check for horizontal lines FIRST ├─ YES → Text detected → Route to heading-text.md @@ -157,7 +159,7 @@ I see 2 thick horizontal lines - text content. Quick Analysis: - 2 lines (text placeholders) - Thickness: 3px -- Spacing: 3px +- Spacing: 3px - Alignment: Center This appears to be HEADING (H2). @@ -191,21 +193,25 @@ Returns to 4c-03 with completed specification ## Benefits ### 1. Efficiency + - Text detected immediately (no menu selection) - Most common object type caught first - Reduces decision points ### 2. Accuracy + - Text has unique signature (horizontal lines) - Clear visual indicator - Hard to misidentify ### 3. Completeness + - Routes to specialized text analysis - Character capacity automatic - Content guidance immediate ### 4. Intelligence + - Agent demonstrates understanding - Natural interpretation flow - Trust-the-agent philosophy @@ -224,7 +230,7 @@ Sketch shows (top to bottom): ───────────────────────────────── ← 2. Text: 2 pairs of THIN lines (2 lines of text) ───────────────────────────────── = Body paragraph (regular font weight) - + ───────────────────────────────── Large spacing between pairs = larger font ───────────────────────────────── @@ -267,5 +273,3 @@ Router processes: --- **Text-first detection ensures accurate routing and complete text analysis!** 📝✨ - - diff --git a/src/modules/wds/workflows/4-ux-design/object-types/TEXT-DETECTION-PRIORITY.md b/src/modules/wds/workflows/4-ux-design/object-types/TEXT-DETECTION-PRIORITY.md index 009af5ac..ddfc992c 100644 --- a/src/modules/wds/workflows/4-ux-design/object-types/TEXT-DETECTION-PRIORITY.md +++ b/src/modules/wds/workflows/4-ux-design/object-types/TEXT-DETECTION-PRIORITY.md @@ -26,8 +26,9 @@ ## Why Text Detection is First Text elements are the most common objects in sketches, and they have a distinctive visual signature (horizontal line pairs). Detecting them first: + - ✅ Reduces confusion -- ✅ Routes to text-specific analysis immediately +- ✅ Routes to text-specific analysis immediately - ✅ Ensures character capacity is calculated - ✅ Prevents misidentification as other elements @@ -38,12 +39,14 @@ Text elements are the most common objects in sketches, and they have a distincti ### Text Markers (Paired Lines) **1 line of heading text (ONE PAIR = ONE TEXT LINE):** + ``` ═══════════════════════════ ← Thick pair line 1 ═══════════════════════════ ← Thick pair line 2 = ONE text line ``` **2 lines of heading text (TWO PAIRS = TWO TEXT LINES):** + ``` ═══════════════════════════ ← Pair 1 line 1 ═══════════════════════════ ← Pair 1 line 2 = Text line 1 @@ -53,21 +56,23 @@ Text elements are the most common objects in sketches, and they have a distincti ``` **4 lines of body text (FOUR PAIRS = FOUR TEXT LINES):** + ``` ───────────────────────────── ← Pair 1 ───────────────────────────── - + ───────────────────────────── ← Pair 2 ───────────────────────────── - + ───────────────────────────── ← Pair 3 ───────────────────────────── - + ───────────────────────────── ← Pair 4 ───────────────────────────── ``` **Label (short text, ONE PAIR = ONE TEXT LINE):** + ``` ══════════ ← Short pair line 1 ══════════ ← Short pair line 2 = ONE short text line @@ -76,22 +81,26 @@ Text elements are the most common objects in sketches, and they have a distincti ### NOT Text Markers (Single Lines = Decorative Elements) **❌ Horizontal divider (`
`):** + ``` ═══════════════════════════ ← SINGLE LINE = section divider ``` **❌ Underline (decorative):** + ``` Main Heading ───────────────────────────── ← SINGLE LINE = decorative underline ``` **❌ Border line:** + ``` ___________________________ ← SINGLE LINE = top/bottom border ``` **❌ Separator:** + ``` Section 1 content... @@ -111,19 +120,19 @@ IF horizontal lines come in pairs (2 lines close together): → TEXT MARKER → Count pairs to get number of text lines → Route to heading-text.md - + ELSE IF single horizontal line: → DECORATIVE ELEMENT (divider, border, underline) → Document as visual element, not text - + ELSE IF sees button shape (box with text): → BUTTON → Route to button.md - + ELSE IF sees input box (rectangular border): → INPUT FIELD → Route to text-input.md - + ... etc ``` @@ -132,6 +141,7 @@ ELSE IF sees input box (rectangular border): **Once text markers are detected, route to `heading-text.md` for complete analysis.** The detailed analysis rules are documented in **`SKETCH-TEXT-ANALYSIS-GUIDE.md`**, which covers: + - Line thickness → font weight - Line spacing between pairs → font size - Line position in container → text alignment @@ -145,6 +155,7 @@ The detailed analysis rules are documented in **`SKETCH-TEXT-ANALYSIS-GUIDE.md`* ## Text vs. Other Elements ### ✅ Text Element (Horizontal Line PAIRS) + ``` ═══════════════════════════ ← Pair indicating text ═══════════════════════════ @@ -152,32 +163,39 @@ The detailed analysis rules are documented in **`SKETCH-TEXT-ANALYSIS-GUIDE.md`* ───────────────────────────── ← Another pair ───────────────────────────── ``` + **Detection:** Lines come in pairs, parallel, evenly spaced **Route to:** `heading-text.md` ### ❌ NOT Text - Decorative Line (SINGLE) + ``` ═══════════════════════════ ← Single line alone ``` + **Detection:** Single horizontal line, no pair **Type:** Divider, border, separator, underline **Action:** Document as decorative visual element ### ❌ NOT Text - Button + ``` ┌─────────────────┐ │ Button Label │ ← Box with centered text inside └─────────────────┘ ``` + **Detection:** Rectangle with text inside, clickable appearance **Route to:** `button.md` ### ❌ NOT Text - Input Field + ``` ┌───────────────────────────┐ │ Placeholder text... │ ← Box with light text inside └───────────────────────────┘ ``` + **Detection:** Rectangle with subtle border, input appearance **Route to:** `text-input.md` @@ -203,11 +221,13 @@ The detailed analysis rules are documented in **`SKETCH-TEXT-ANALYSIS-GUIDE.md`* ``` **WDS Recommends:** + - ✅ **Draw what the image shows** - Sketch the actual content (person, landscape, product) - ✅ **Use soft shapes** - Clouds, waves, organic shapes for abstract images - ❌ **Avoid "X" markers** - Too intrusive and provides no content guidance **Why?** Sketching actual image content: + - Provides visual direction and context - Helps with AI interpretation of image purpose - Guides content selection and art direction @@ -217,11 +237,13 @@ The detailed analysis rules are documented in **`SKETCH-TEXT-ANALYSIS-GUIDE.md`* **Route to:** `image.md` ### ❌ NOT Text - Link (Often With Text) + ``` ══════════ ← Text pair (the link text) ══════════ ↑ underline indicator or different color ``` + **Detection:** Text with underline or special formatting indicating clickability **Route to:** `link.md` (which handles the text content) @@ -234,47 +256,47 @@ def detect_object_type(sketch_element): """ Always check for text FIRST before other object types """ - + # Step 1: Check for horizontal line pairs (TEXT) if has_horizontal_lines(sketch_element): lines = get_horizontal_lines(sketch_element) pairs = group_lines_into_pairs(lines, max_distance=4px) - + if len(pairs) > 0: # This is text! Count pairs = text lines text_line_count = len(pairs) - + # Analyze each pair for pair in pairs: thickness = measure_line_thickness(pair) spacing = measure_spacing_between_pairs(pairs) - + font_weight = thickness_to_weight(thickness) font_size = spacing_to_size(spacing) - + return route_to("heading-text.md", { "line_count": text_line_count, "font_weight": font_weight, "font_size_estimate": font_size }) - + elif len(lines) == 1: # Single line = decorative element return { "type": "decorative_line", "purpose": "divider or border" } - + # Step 2: Check for other object types if has_button_shape(sketch_element): return route_to("button.md") - + if has_input_box_shape(sketch_element): return route_to("text-input.md") - + if has_image_placeholder(sketch_element): return route_to("image.md") - + # ... etc ``` @@ -285,12 +307,14 @@ def detect_object_type(sketch_element): ### Example 1: Hero Headline **Sketch:** + ``` ═══════════════════════════════ ← Thick pair detected ═══════════════════════════════ ``` **Detection:** + - ✅ **Pair detected** → This is TEXT - **Route to:** `heading-text.md` for detailed analysis @@ -301,15 +325,17 @@ def detect_object_type(sketch_element): ### Example 2: Supporting Paragraph **Sketch:** + ``` ───────────────────────────────────────── ← Thin pairs detected ───────────────────────────────────────── - + ───────────────────────────────────────── ───────────────────────────────────────── ``` **Detection:** + - ✅ **2 pairs detected** → This is TEXT (2 lines) - **Route to:** `heading-text.md` for detailed analysis @@ -320,6 +346,7 @@ def detect_object_type(sketch_element): ### Example 3: Divider Line (NOT TEXT) **Sketch:** + ``` Section 1 content... @@ -329,6 +356,7 @@ Section 2 content... ``` **Detection:** + - ❌ **Single line detected** (no pair) → NOT text - **Type:** Decorative `
` element @@ -337,12 +365,14 @@ Section 2 content... ## Key Takeaways ### Detection Rules (This File) + 1. **Text markers ALWAYS come in pairs** (two lines = one text line) 2. **Single lines are decorative** (dividers, borders, underlines) 3. **Detect text FIRST** before checking for other object types 4. **Count pairs to get text line count** (3 pairs = 3 lines of text) ### Analysis Rules (See SKETCH-TEXT-ANALYSIS-GUIDE.md) + 5. **Line thickness → font weight** 6. **Spacing between pairs → font size** 7. **Line position → text alignment** @@ -359,4 +389,3 @@ Section 2 content... --- **This file: DETECTION logic. For detailed ANALYSIS rules, see SKETCH-TEXT-ANALYSIS-GUIDE.md** 🎯 - diff --git a/src/modules/wds/workflows/4-ux-design/object-types/button.md b/src/modules/wds/workflows/4-ux-design/object-types/button.md index 33d6557d..83346d48 100644 --- a/src/modules/wds/workflows/4-ux-design/object-types/button.md +++ b/src/modules/wds/workflows/4-ux-design/object-types/button.md @@ -53,13 +53,13 @@ Choice [1/2/3]: **Which existing component?** - From your component library: - {{list_available_button_components}} +From your component library: +{{list_available_button_components}} - Component name: - - Store design_system_component - Store component_status = "existing" +Component name: + +Store design_system_component +Store component_status = "existing" @@ -90,9 +90,10 @@ Choice [1/2/3]: **Button text in all languages:** {{#each language}} + - **{{language}}:** -{{/each}} - + {{/each}} + Store button_text for each language @@ -119,32 +120,37 @@ Choice [1-4]: **For each state, describe the appearance:** **Default state:** + - Background color: - Text color: - Border: **Hover state:** + - Background color: - Text color: - Border: - Other changes (shadow, scale, etc.): **Active/Pressed state:** + - Background color: - Text color: - Visual feedback: **Disabled state:** + - Background color: - Text color: - Cursor: - Why disabled: **Loading state** (if applicable): + - Show spinner: yes/no - Loading text (in all languages): - Disable other actions: yes/no - + Store state definitions for all states @@ -155,6 +161,7 @@ Choice [1-4]: **What happens when user clicks this button?** Describe the complete flow: + 1. User clicks... 2. Button changes to... (state) 3. System does... (action/API call) @@ -162,7 +169,7 @@ Describe the complete flow: 5. If error... 6. User sees... (result) 7. Navigate to... (if applicable) - + Store interaction_flow @@ -176,7 +183,7 @@ Describe the complete flow: - Required fields must be filled: yes/no - User must be authenticated: yes/no - Other prerequisites: - + Store prerequisites @@ -198,8 +205,9 @@ Describe the complete flow: **Content:** {{#each language}} + - **{{language}}:** {{button_text}} -{{/each}} + {{/each}} {{#if has_icon}} **Icon:** {{icon_name}} ({{icon_position}}) @@ -207,44 +215,52 @@ Describe the complete flow: **States:** -*Default:* +_Default:_ + - Background: {{default_bg}} - Text: {{default_text}} - Border: {{default_border}} -*Hover:* +_Hover:_ + - Background: {{hover_bg}} - Text: {{hover_text}} - Changes: {{hover_changes}} -*Active:* +_Active:_ + - Background: {{active_bg}} - Text: {{active_text}} - Feedback: {{active_feedback}} -*Disabled:* +_Disabled:_ + - Background: {{disabled_bg}} - Text: {{disabled_text}} - Cursor: not-allowed - When: {{disabled_condition}} {{#if has_loading_state}} -*Loading:* +_Loading:_ + - Spinner: visible - Text: {{loading_text}} - Actions: disabled -{{/if}} + {{/if}} **Interaction:** + 1. {{interaction_step_1}} 2. {{interaction_step_2}} -... + ... {{#if has_prerequisites}} **Requirements:** + - {{prerequisite_list}} -{{/if}} + {{/if}} ``` + ✅ **Button documented!** @@ -264,6 +280,7 @@ Specification added to page document. **Figma Component:** Button/Primary/Large **Content:** + - **English:** Sign In - **Swedish:** Logga In @@ -271,37 +288,43 @@ Specification added to page document.
**States:** -*Default:* +_Default:_ + - Background: #0066CC (primary blue) - Text: #FFFFFF (white) - Border: none - Border-radius: 8px - Padding: 12px 24px -*Hover:* +_Hover:_ + - Background: #0052A3 (darker blue) - Text: #FFFFFF - Changes: slight shadow (0 2px 8px rgba(0,0,0,0.15)) -*Active:* +_Active:_ + - Background: #003D7A (even darker) - Text: #FFFFFF - Feedback: scale(0.98), shadow removed -*Disabled:* +_Disabled:_ + - Background: #CCCCCC (gray) - Text: #666666 (dark gray) - Opacity: 0.6 - Cursor: not-allowed - When: Form validation fails or during submission -*Loading:* +_Loading:_ + - Spinner: visible (white, 16px) - Text (EN): "Signing in..." - Text (SV): "Loggar in..." - Actions: All form interactions disabled **Interaction:** + 1. User clicks button 2. Button enters loading state (spinner shows) 3. Validate all form fields @@ -311,6 +334,7 @@ Specification added to page document.
7. On API error: show error message above form, exit loading state **Requirements:** + - Email field must contain valid email - Password field must not be empty - No existing submission in progress @@ -319,4 +343,3 @@ Specification added to page document.
--- **Return to 4c-03 to continue with next object** - diff --git a/src/modules/wds/workflows/4-ux-design/object-types/heading-text.md b/src/modules/wds/workflows/4-ux-design/object-types/heading-text.md index 3347b2f3..ef9beb15 100644 --- a/src/modules/wds/workflows/4-ux-design/object-types/heading-text.md +++ b/src/modules/wds/workflows/4-ux-design/object-types/heading-text.md @@ -9,10 +9,11 @@ **Analyzing text element from sketch...** First, check if sketch contains ACTUAL TEXT (readable words): + - Headlines often drawn as actual text - Provides content guidance - Can change during conversation - + Extract text from sketch @@ -31,21 +32,22 @@ I can use this as a starting suggestion, but we can change it if needed. - **Text placeholder detected:** +**Text placeholder detected:** - **Sketch Analysis:** - - **{{line_count}} line pairs** → {{line_count}} lines of text - - **Line thickness:** {{thickness}} → **{{estimated_font_weight}}** - - **Line spacing:** {{distance_between_lines}} → **~{{estimated_font_size}}** font size - - **Line-height:** ~{{estimated_line_height}} (calculated from font size) - - **Alignment:** {{detected_alignment}} (from line position) - - **Capacity:** ~{{total_chars}} characters per line +**Sketch Analysis:** - **This appears to be:** {{text_type}} (heading/body/caption/label) +- **{{line_count}} line pairs** → {{line_count}} lines of text +- **Line thickness:** {{thickness}} → **{{estimated_font_weight}}** +- **Line spacing:** {{distance_between_lines}} → **~{{estimated_font_size}}** font size +- **Line-height:** ~{{estimated_line_height}} (calculated from font size) +- **Alignment:** {{detected_alignment}} (from line position) +- **Capacity:** ~{{total_chars}} characters per line - ⚠️ **Note:** If spacing is very large (>60px), verify this is text and not an image placeholder. - - 💡 **Analysis rules:** See `SKETCH-TEXT-ANALYSIS-GUIDE.md` for complete methodology. +**This appears to be:** {{text_type}} (heading/body/caption/label) + +⚠️ **Note:** If spacing is very large (>60px), verify this is text and not an image placeholder. + +💡 **Analysis rules:** See `SKETCH-TEXT-ANALYSIS-GUIDE.md` for complete methodology. --- @@ -57,6 +59,7 @@ I can use this as a starting suggestion, but we can change it if needed.**What is the PURPOSE of this text on the page?** Think about function, not content: + - "Primary headline" (not "Welcome to Dog Week") - "Feature description" (not "Organize your family") - "CTA supporting text" (not "Free forever") @@ -75,10 +78,11 @@ Purpose/function: `{page}-{section}-{purpose}` Examples: + - `start-hero-headline` (not `start-hero-welcome-text`) - `signin-form-email-label` (not `signin-form-email-address-text`) - `profile-success-message` (not `profile-saved-successfully-text`) - + **Object ID:** `{{generated_object_id}}` @@ -100,13 +104,13 @@ Choice [1/2/3]: **Which existing typography component?** - From your Design System: - {{list_available_typography_components}} +From your Design System: +{{list_available_typography_components}} - Component name: - - Store design_system_component - Store component_status = "existing" +Component name: + +Store design_system_component +Store component_status = "existing" @@ -137,6 +141,7 @@ Choice [1/2/3]: **Text element specifications:** **HTML Tag** (semantic structure for SEO/accessibility): + - h1 (main page heading, only ONE per page) - h2 (major section heading) - h3 (subsection heading) @@ -147,6 +152,7 @@ Choice [1/2/3]: HTML tag: **Visual Style Type** (appearance, from Design System): + - Hero headline (large display text for hero sections) - Main header (primary page/section headers) - Sub header (section headings, emphasized) @@ -164,11 +170,13 @@ Visual style name: > **Important:** HTML tags define document structure. Visual styles define appearance. Keep them separate! **Position on page:** + - Vertical: (top/middle/bottom of section) - Horizontal: (left/center/right) - Relative to: (e.g., "above CTA button", "below headline") **Text Alignment** (from sketch line position): + - left (lines start at left edge) - center (lines centered in container) - right (lines end at right edge) @@ -177,12 +185,13 @@ Visual style name: Alignment: **Style specifications:** + - Font size: {{estimated_font_size}} (est. from {{line_spacing}} spacing in sketch) - Font weight: {{estimated_font_weight}} (from {{line_thickness}} line thickness in sketch) - Line height: {{estimated_line_height}} (est. calculated from font size) - Text color: - Text transform: (none/uppercase/capitalize) - + Store html_tag, visual_type, visual_style_name, position, and style specifications @@ -205,11 +214,11 @@ Content length: ~{{total_chars}} characters (from sketch analysis) **I found text in your sketch:** "{{extracted_text}}" Let me suggest translations for all configured languages... - - Translate extracted_text to all product_languages - Generate suggested translations using context and best practices - - **Suggested content for {{text_purpose}}:** + +Translate extracted_text to all product_languages +Generate suggested translations using context and best practices + +**Suggested content for {{text_purpose}}:** {{#each product_languages}} **{{this}}:** {{suggested_translation}} @@ -217,7 +226,7 @@ Let me suggest translations for all configured languages... These are my suggestions based on the sketch text. Please review and adjust as needed! - Do these translations work, or would you like to change any of them? +Do these translations work, or would you like to change any of them? 1. **Use these translations** - They look good! 2. **Adjust translations** - I'll provide different versions @@ -229,11 +238,11 @@ Choice [1/2/3]: Which language(s) need adjustment? {{#each product_languages}} -**{{this}}:** {{suggested_translation}} ← Change this? +**{{this}}:** {{suggested_translation}} ← Change this? {{/each}} Please provide the corrected versions: - + **Content for this {{text_purpose}}:** @@ -243,7 +252,7 @@ Please provide the corrected versions: {{/each}} - + @@ -255,9 +264,9 @@ Please provide content. I'll suggest translations once you give me the first lan - After receiving primary language content, suggest translations for remaining languages - - **Translation suggestions:** +After receiving primary language content, suggest translations for remaining languages + +**Translation suggestions:** {{#each remaining_languages}} **{{this}}:** {{suggested_translation}} @@ -304,23 +313,25 @@ If yes, describe behavior: **OBJECT ID**: `{{object_id}}` **HTML Structure:** + - **Tag**: {{html_tag}} - **Semantic Purpose**: {{semantic_description}} **Visual Style:** {{#if design_system_component}} + - **Design System Component**: {{design_system_component}} -{{/if}} + {{/if}} - **Visual Style Name**: {{visual_style_name}} - **Font weight**: {{font_weight}} (from {{line_thickness}} line markers in sketch) - **Font size**: {{font_size}} (est. from {{line_spacing}} spacing between line pairs) - **Line-height**: {{line_height}} (est. calculated from font size) -{{#if text_color}} + {{#if text_color}} - **Color**: {{text_color}} -{{/if}} -{{#if text_transform}} + {{/if}} + {{#if text_transform}} - **Transform**: {{text_transform}} -{{/if}} + {{/if}} **Position**: {{position_description}} **Alignment**: {{text_alignment}} @@ -331,15 +342,19 @@ If yes, describe behavior: **Content**: {{#each product_languages}} + - {{this}}: "{{content}}" -{{/each}} + {{/each}} > **Sketch Analysis:** Values derived using `SKETCH-TEXT-ANALYSIS-GUIDE.md` methodology. Designer should review and confirm. ``` - {{#each additional_language}} - - {{lang_code}}: "{{content}}" + +{{#each additional_language}} + +- {{lang_code}}: "{{content}}" {{/each}} -``` + +```` --- @@ -364,46 +379,46 @@ Choice [1/2]: **What other text elements are in this group?** - + List them: - + Mark as text group for grouped translation output - + **Text group will be formatted as:** - + ```markdown ### {{Group_Name}} **Purpose**: {{group_purpose}} - + #### {{Element_1_Purpose}} **OBJECT ID**: `{{object_id_1}}` - **Component**: {{type_1}} - **Content**: - EN: "{{content_en_1}}" - SE: "{{content_se_1}}" - + #### {{Element_2_Purpose}} **OBJECT ID**: `{{object_id_2}}` - **Component**: {{type_2}} - **Content**: - EN: "{{content_en_2}}" - SE: "{{content_se_2}}" - + #### {{Element_3_Purpose}} **OBJECT ID**: `{{object_id_3}}` - **Component**: {{type_3}} - **Content**: - EN: "{{content_en_3}}" - SE: "{{content_se_3}}" - ``` - - **Reading in English:** - {{content_en_1}} + {{content_en_2}} + {{content_en_3}} - - **Reading in Swedish:** - {{content_se_1}} + {{content_se_2}} + {{content_se_3}} - - Each language reads as a complete, coherent message! +```` + +**Reading in English:** +{{content_en_1}} + {{content_en_2}} + {{content_en_3}} + +**Reading in Swedish:** +{{content_se_1}} + {{content_se_2}} + {{content_se_3}} + +Each language reads as a complete, coherent message! --- @@ -412,13 +427,16 @@ Choice [1/2]: ```markdown ### Hero Object + **Purpose**: Primary value proposition and main conversion action #### Primary Headline + **OBJECT ID**: `start-hero-headline` + - **Component**: H1 heading (`.text-heading-1`) - **Position**: Center of hero section, above CTA -- **Style**: +- **Style**: - Font weight: Bold (from 3px thick line markers) - Font size: 42px (est. from 24px spacing between line pairs) - Line-height: 1.2 (est. calculated from font size) @@ -427,14 +445,17 @@ Choice [1/2]: - **Content**: > **Note:** Values marked `(est. from...)` show sketch analysis reasoning. Confirm or adjust, then update with actual values. - - EN: "Every walk. on time. Every time." - - SE: "Varje promenad. i tid. Varje gång." + +- EN: "Every walk. on time. Every time." +- SE: "Varje promenad. i tid. Varje gång." #### Supporting Text + **OBJECT ID**: `start-hero-supporting` + - **Component**: Body text (`.text-body`) - **Position**: Below headline, above CTA button -- **Style**: +- **Style**: - Font weight: Regular (from 1px thin line markers) - Font size: 16px (est. from 12px spacing between line pairs) - Line-height: 1.5 (est. calculated from font size) @@ -442,11 +463,14 @@ Choice [1/2]: - **Content**: > **Note:** Values marked `(est. from...)` show sketch analysis reasoning. Confirm or adjust, then update with actual values. - - EN: "Organize your family around dog care. Never miss a walk again." - - SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen." + +- EN: "Organize your family around dog care. Never miss a walk again." +- SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen." #### Primary CTA Button + **OBJECT ID**: `start-hero-cta` + - **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md) - **Position**: Center, below supporting text - **Behavior**: Navigate to registration/sign-up @@ -456,11 +480,13 @@ Choice [1/2]: ``` **Reading the Hero in English:** -> "Every walk. on time. Every time." + +> "Every walk. on time. Every time." > "Organize your family around dog care. Never miss a walk again." > [start planning - free forever] **Reading the Hero in Swedish:** + > "Varje promenad. i tid. Varje gång." > "Organisera din familj kring hundvård. Missa aldrig en promenad igen." > [börja planera - gratis för alltid] @@ -470,20 +496,24 @@ Choice [1/2]: ## KEY PRINCIPLES ### 1. Purpose-Based Naming ✅ + **NOT:** `welcome-heading`, `description-paragraph` **YES:** `hero-headline`, `feature-description` Names describe FUNCTION, not content. ### 2. Separated Structure ✅ + - **Position/Style** specified separately - **Content** grouped by language - **Behavior** clearly stated ### 3. Grouped Translations ✅ + Text groups keep languages together so each reads coherently. ### 4. Professional Format ✅ + Follows Dog Week specification style for consistency across WDS projects. --- @@ -491,21 +521,25 @@ Follows Dog Week specification style for consistency across WDS projects. ## BENEFITS ✅ **Purpose-Driven** + - Object IDs reflect function - Names remain valid if content changes - Clear semantic meaning ✅ **Translation-Friendly** + - Each language grouped together - Easy to read entire section in one language - Natural language flow preserved ✅ **Maintainable** + - Content can change without renaming - Structure remains stable - Easy to locate by purpose ✅ **Developer-Friendly** + - Clear what each text does - Component references included - Position clearly stated diff --git a/src/modules/wds/workflows/4-ux-design/object-types/image.md b/src/modules/wds/workflows/4-ux-design/object-types/image.md index 10b07eb0..a5d03cfb 100644 --- a/src/modules/wds/workflows/4-ux-design/object-types/image.md +++ b/src/modules/wds/workflows/4-ux-design/object-types/image.md @@ -33,13 +33,13 @@ Choice [1/2/3]: **Which existing image pattern?** - From your Design System: - {{list_available_image_patterns}} +From your Design System: +{{list_available_image_patterns}} - Component name: - - Store design_system_component - Store component_status = "existing" +Component name: + +Store design_system_component +Store component_status = "existing" @@ -70,23 +70,26 @@ Choice [1/2/3]: **Image properties:** **Source:** + - Image filename/path: - Alt text (EN): - Alt text (SV): - Is decorative (no alt needed): yes/no **Dimensions:** + - Width: - Height: - Aspect ratio: - Object-fit: (cover/contain/fill) **Responsive behavior:** + - Mobile size: - Tablet size: - Desktop size: - Retina/2x version: yes/no - + --- @@ -95,17 +98,20 @@ Choice [1/2/3]: **Image states:** **Loading:** + - Placeholder: (color/skeleton/blur) - Lazy loading: yes/no **Error:** + - Fallback image: (if any) - Error message display: yes/no **Loaded:** + - Fade-in animation: yes/no - Animation duration: - + --- @@ -118,32 +124,37 @@ Choice [1/2/3]: **Type:** image **Source:** + - File: {{image_path}} - Alt (EN): {{alt_text_en}} - Alt (SV): {{alt_text_sv}} -{{#if is_decorative}} + {{#if is_decorative}} - Decorative: role="presentation" -{{/if}} + {{/if}} **Dimensions:** + - Width: {{width}} - Height: {{height}} - Aspect ratio: {{aspect_ratio}} - Object-fit: {{object_fit}} **Responsive:** + - Mobile: {{mobile_size}} - Tablet: {{tablet_size}} - Desktop: {{desktop_size}} -{{#if has_retina}} + {{#if has_retina}} - Retina (@2x): {{retina_path}} -{{/if}} + {{/if}} **Loading:** + - Placeholder: {{placeholder_type}} - Lazy load: {{lazy_loading}} **States:** + - **Loading:** {{loading_state}} - **Error:** {{error_fallback}} - **Loaded:** {{loaded_animation}} @@ -152,4 +163,3 @@ Choice [1/2/3]: --- **Return to 4c-03** - diff --git a/src/modules/wds/workflows/4-ux-design/object-types/link.md b/src/modules/wds/workflows/4-ux-design/object-types/link.md index 7e5cf7a6..b713c39a 100644 --- a/src/modules/wds/workflows/4-ux-design/object-types/link.md +++ b/src/modules/wds/workflows/4-ux-design/object-types/link.md @@ -47,13 +47,13 @@ Choice [1/2/3]: **Which existing component?** - From your component library: - {{list_available_link_components}} +From your component library: +{{list_available_link_components}} - Component name: - - Store design_system_component - Store component_status = "existing" +Component name: + +Store design_system_component +Store component_status = "existing" @@ -84,13 +84,15 @@ Choice [1/2/3]: **Link text in all languages:** {{#each language}} + - **{{language}}:** -{{/each}} + {{/each}} **Target/Destination:** + - URL or route: - Opens in: same tab / new tab - + --- @@ -99,24 +101,28 @@ Choice [1/2/3]: **Visual styling:** **Default:** + - Text color: - Text decoration: (underline/none) - Font weight: - Icon: (if any) **Hover:** + - Text color: - Text decoration: - Cursor: **Active/Visited:** + - Text color: - Show as visited: yes/no **Focus:** + - Outline color: - Text decoration: - + --- @@ -132,28 +138,30 @@ Choice [1/2/3]: **Content:** {{#each language}} + - **{{language}}:** {{link_text}} -{{/each}} + {{/each}} {{#if has_icon}} **Icon:** {{icon_name}} ({{icon_position}}) {{/if}} **States:** + - **Default:** {{default_color}}, {{default_decoration}} - **Hover:** {{hover_color}}, {{hover_decoration}} - **Active:** {{active_color}} - **Focus:** Outline {{focus_outline}} **Interaction:** + - On click: Navigate to {{destination}} -{{#if opens_new_tab}} + {{#if opens_new_tab}} - Opens in new tab - Includes rel="noopener noreferrer" -{{/if}} + {{/if}} ``` --- **Return to 4c-03** - diff --git a/src/modules/wds/workflows/4-ux-design/object-types/object-router.md b/src/modules/wds/workflows/4-ux-design/object-types/object-router.md index 6e306a91..77bb3b8b 100644 --- a/src/modules/wds/workflows/4-ux-design/object-types/object-router.md +++ b/src/modules/wds/workflows/4-ux-design/object-types/object-router.md @@ -9,10 +9,11 @@ **Analyzing object from sketch...** Apply text detection rules from `TEXT-DETECTION-PRIORITY.md`: -- Look for horizontal line PAIRS (2 lines together = text marker) + +- Look for horizontal line PAIRS (2 lines together = text marker) - Single lines alone = decorative elements (dividers, borders) - Count pairs to determine number of text lines - + **✓ TEXT ELEMENT DETECTED** @@ -39,32 +40,36 @@ Examine object characteristics: + - Visual appearance (shape, style, position) - Context (what's around it, where in form/page) - Interactive indicators (buttons, inputs, links) - Container indicators (boxes, cards, modals) - Media indicators (image placeholders, video frames) - + **My interpretation:** **This looks like a {{suggested_object_type}}.** Based on what I see: + - {{observation_1}} - {{observation_2}} - {{observation_3}} {{#if is_text_element}} **Text Analysis from Sketch:** + - **{{line_count}} lines of text** (horizontal bar groups) - **Line thickness:** {{thickness}} → ~{{estimated_font_size}} font - **Line spacing:** {{spacing}} → ~{{estimated_line_height}} line-height - **Alignment:** {{detected_alignment}} - **Content capacity:** ~{{total_chars}} characters ({{chars_per_line}} per line) -{{/if}} + {{/if}} **I think this {{component_name}}:** + - {{suggested_purpose}} - {{suggested_interaction}} - {{suggested_result}} @@ -75,9 +80,7 @@ Based on what I see: **Does this match your intent?** -1. **Yes** - That's correct -2. **Close** - Similar but let me clarify -3. **No** - It's actually something different +1. **Yes** - That's correct 2. **Close** - Similar but let me clarify 3. **No** - It's actually something different Choice [1/2/3]: @@ -132,11 +135,13 @@ Choice [1/2/3]: Based on confirmed object type, load appropriate instruction file: **TEXT ELEMENTS (DETECTED FIRST):** + - Horizontal line groups → `object-types/heading-text.md` - Handles: Headings (H1-H6), Paragraphs, Labels, Captions - Includes: Sketch text analysis, character capacity, content guidance **INTERACTIVE ELEMENTS:** + - **Button shapes** → `object-types/button.md` - **Input fields** → `object-types/text-input.md` - **Textarea boxes** → `object-types/textarea.md` @@ -147,26 +152,31 @@ Choice [1/2/3]: - **Underlined text/arrows** → `object-types/link.md` **MEDIA ELEMENTS:** + - **Image placeholders (X or box)** → `object-types/image.md` - **Video frame** → `object-types/video.md` **CONTAINER ELEMENTS:** + - **Card/box container** → `object-types/card.md` - **Overlay/popup** → `object-types/modal-dialog.md` - **Grid/rows** → `object-types/table.md` - **Bullet/numbered items** → `object-types/list.md` **NAVIGATION ELEMENTS:** + - **Menu/tabs** → `object-types/navigation.md` **STATUS ELEMENTS:** + - **Small circle/pill** → `object-types/badge.md` - **Banner/box with icon** → `object-types/alert-toast.md` - **Bar/spinner** → `object-types/progress.md` **CUSTOM:** + - **Unique component** → `object-types/custom-component.md` - + @@ -203,6 +213,7 @@ Choice [1/2]: ## INTERPRETATION EXAMPLES **Example 1: Button** + ``` My interpretation: @@ -224,6 +235,7 @@ Does this match your intent? ``` **Example 2: Text/Heading with Placeholder Lines** + ``` My interpretation: @@ -253,6 +265,7 @@ Does this match your intent? ``` **Example 3: Body Text with Multiple Lines** + ``` My interpretation: @@ -282,6 +295,7 @@ Does this match your intent? ``` **Example 3: Link** + ``` My interpretation: @@ -307,21 +321,25 @@ Does this match your intent? ## KEY PRINCIPLES **✅ Agent demonstrates intelligence** + - Analyzes visual and contextual clues - Makes informed suggestions - Shows reasoning process **✅ Trust-the-agent approach** + - Agent interprets, user confirms - Not procedural checkbox selection - Collaborative intelligence **✅ Efficient workflow** + - Quick confirmation when correct - Easy correction when needed - Natural conversation flow **✅ Context-aware** + - Understands form flow - Recognizes UI patterns - Applies common sense diff --git a/src/modules/wds/workflows/4-ux-design/object-types/text-input.md b/src/modules/wds/workflows/4-ux-design/object-types/text-input.md index fd331603..041763d2 100644 --- a/src/modules/wds/workflows/4-ux-design/object-types/text-input.md +++ b/src/modules/wds/workflows/4-ux-design/object-types/text-input.md @@ -56,13 +56,13 @@ Choice [1/2/3]: **Which existing component?** - From your component library: - {{list_available_input_components}} +From your component library: +{{list_available_input_components}} - Component name: - - Store design_system_component - Store component_status = "existing" +Component name: + +Store design_system_component +Store component_status = "existing" @@ -93,27 +93,30 @@ Choice [1/2/3]: **Label text in all languages:** {{#each language}} + - **{{language}}:** -{{/each}} - + {{/each}} + Store label_text for each language **Placeholder text in all languages:** {{#each language}} + - **{{language}}:** -{{/each}} - + {{/each}} + Store placeholder_text for each language **Helper text** (optional guidance below field): {{#each language}} + - **{{language}}:** -{{/each}} - + {{/each}} + Store helper_text for each language @@ -129,7 +132,7 @@ Choice [1/2/3]: - Autocomplete: (on/off/specific type like "email") - Autofocus: yes/no - Readonly: yes/no - + Store input_properties @@ -142,29 +145,34 @@ Choice [1/2/3]: **For each state, describe the appearance:** **Default/Empty state:** + - Border color: - Background: - Placeholder visible: yes - Label position: **Focus state:** + - Border color: - Background: - Label position: (stays/floats above) - Outline/glow: **Filled state:** + - Border color: - Background: - Label position: **Error state:** + - Border color: - Background: - Error message position: (below/inline) - Icon: (if any) **Disabled state:** + - Border color: - Background: - Text color: @@ -172,10 +180,11 @@ Choice [1/2/3]: - Why disabled: **Success state** (if applicable): + - Border color: - Icon: (checkmark, etc.) - When shown: - + Store state definitions for all states @@ -186,22 +195,27 @@ Choice [1/2/3]: **Validation rules for this input:** **Required:** + - Is this field required: yes/no **Format validation:** + - Format rules: (e.g., "must be valid email", "must contain @") - Pattern/regex: (if applicable) **Length validation:** + - Minimum length: - Maximum length: **Custom rules:** + - Any custom validation: **Validation timing:** + - When to validate: on_blur / on_input / on_submit - + Store validation_rules @@ -217,10 +231,11 @@ Choice [1/2/3]: Error code: (e.g., ERR_EMAIL_REQUIRED) {{#each language}} + - **{{language}}:** -{{/each}} -{{/each}} - + {{/each}} + {{/each}} + Store error_messages with codes and translations @@ -231,19 +246,22 @@ Error code: (e.g., ERR_EMAIL_REQUIRED) **Interaction behaviors:** **On focus:** + - What happens: **On input (while typing):** + - Real-time validation: yes/no - Character counter: yes/no - Auto-formatting: yes/no (e.g., phone numbers) - Other behaviors: **On blur (loses focus):** + - Validation triggers: yes/no - Save/update: yes/no - Other behaviors: - + Store interaction_behaviors @@ -265,22 +283,26 @@ Error code: (e.g., ERR_EMAIL_REQUIRED) **Label:** {{#each language}} + - **{{language}}:** {{label_text}} -{{/each}} + {{/each}} **Placeholder:** {{#each language}} + - **{{language}}:** {{placeholder_text}} -{{/each}} + {{/each}} {{#if has_helper_text}} **Helper Text:** {{#each language}} + - **{{language}}:** {{helper_text}} -{{/each}} -{{/if}} + {{/each}} + {{/if}} **Properties:** + - Required: {{is_required}} - Max length: {{max_length}} - Min length: {{min_length}} @@ -289,45 +311,54 @@ Error code: (e.g., ERR_EMAIL_REQUIRED) **States:** -*Default:* +_Default:_ + - Border: {{default_border}} - Background: {{default_bg}} - Label: {{label_position}} -*Focus:* +_Focus:_ + - Border: {{focus_border}} - Label: {{focus_label_position}} - Outline: {{focus_outline}} -*Filled:* +_Filled:_ + - Border: {{filled_border}} - Label: {{filled_label_position}} -*Error:* +_Error:_ + - Border: {{error_border}} - Icon: {{error_icon}} - Message: Below field -*Disabled:* +_Disabled:_ + - Border: {{disabled_border}} - Background: {{disabled_bg}} - Cursor: not-allowed **Validation:** {{#each validation_rule}} + - {{rule_description}} -{{/each}} + {{/each}} **Error Messages:** {{#each error}} + - **{{error_code}}:** {{error_messages}} -{{/each}} + {{/each}} **Interactions:** + - **On Focus:** {{focus_behavior}} - **On Input:** {{input_behavior}} - **On Blur:** {{blur_behavior}} ``` + ✅ **Input field documented!** @@ -347,18 +378,22 @@ Specification added to page document. **Figma Component:** Input/Text/Medium **Label:** + - **English:** Email Address - **Swedish:** E-postadress **Placeholder:** + - **English:** your@email.com - **Swedish:** din@epost.com **Helper Text:** + - **English:** We'll never share your email - **Swedish:** Vi delar aldrig din e-post **Properties:** + - Required: yes - Max length: 254 - Min length: 5 @@ -367,51 +402,57 @@ Specification added to page document. **States:** -*Default:* +_Default:_ + - Border: 1px solid #CCCCCC - Background: #FFFFFF - Label: Inside field (placeholder position) -*Focus:* +_Focus:_ + - Border: 2px solid #0066CC (primary) - Label: Floats above field - Outline: 0 0 0 3px rgba(0,102,204,0.1) -*Filled:* +_Filled:_ + - Border: 1px solid #666666 - Label: Remains above field -*Error:* +_Error:_ + - Border: 2px solid #DC2626 (red) - Icon: ⚠️ (warning icon, right side) - Message: Below field in red -*Disabled:* +_Disabled:_ + - Border: 1px solid #E5E5E5 - Background: #F5F5F5 - Cursor: not-allowed - Text: #999999 **Validation:** + - Required field (cannot be empty) - Must contain @ symbol - Must have valid domain - Must match email format pattern **Error Messages:** + - **ERR_EMAIL_REQUIRED:** - EN: "Email address is required" - SV: "E-postadress krävs" - - **ERR_EMAIL_INVALID:** - EN: "Please enter a valid email address" - SV: "Ange en giltig e-postadress" - - **ERR_EMAIL_DOMAIN:** - EN: "Email domain appears invalid" - SV: "E-postdomän verkar ogiltig" **Interactions:** + - **On Focus:** Border changes to primary color, label floats up with animation (200ms ease-out) - **On Input:** Real-time validation (debounced 300ms), @ symbol triggers domain validation - **On Blur:** Full validation runs, error message displays if invalid, save to form state @@ -420,4 +461,3 @@ Specification added to page document. --- **Return to 4c-03 to continue with next object** - diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/SCENARIO-INIT-PROCESS.md b/src/modules/wds/workflows/4-ux-design/scenario-init/SCENARIO-INIT-PROCESS.md index 170fbaf2..f90ac269 100644 --- a/src/modules/wds/workflows/4-ux-design/scenario-init/SCENARIO-INIT-PROCESS.md +++ b/src/modules/wds/workflows/4-ux-design/scenario-init/SCENARIO-INIT-PROCESS.md @@ -7,6 +7,7 @@ ## The Situation You've created your **Trigger Map**. You know: + - WHO your target groups are - WHAT triggers their needs - WHY your business exists @@ -23,12 +24,12 @@ You've created your **Trigger Map**. You know: ``` Agent: "Looking at your Trigger Map and prioritized feature list, - what's the core feature that delivers value to your + what's the core feature that delivers value to your primary target group? - + This is what we should sketch first." -Designer: "The family dog walk calendar - it solves the accountability +Designer: "The family dog walk calendar - it solves the accountability problem that causes conflict." ``` @@ -37,10 +38,10 @@ Designer: "The family dog walk calendar - it solves the accountability ### 2. Where Does the User First Encounter This? ``` -Agent: "Where does your primary target group first come into +Agent: "Where does your primary target group first come into contact with this solution?" -Designer: "Google search - they're frustrated with family conflict +Designer: "Google search - they're frustrated with family conflict over dog care." ``` @@ -50,7 +51,7 @@ Designer: "Google search - they're frustrated with family conflict ``` Agent: "When they find Dog Week on Google, how are they feeling? - + Think about: - What just happened? (trigger moment) - What are they hoping for? @@ -67,7 +68,7 @@ Designer: "Just had another fight about who walks the dog. ``` Agent: "What does success look like for both sides? - + For the business: [subscription purchased] For the parent: [what state/feeling/outcome]?" @@ -81,19 +82,20 @@ Designer: "Business: Active subscription ### 5. What's the Shortest Path? ``` -Agent: "Let's map the shortest possible journey from +Agent: "Let's map the shortest possible journey from 'frustrated parent on Google' to 'active subscription + harmony': - + Natural starting point: Google search result - + What's the absolute minimum path to mutual success?" -Designer: "Google → Landing page → See how it works → - Sign up → Set up family → Start using calendar → +Designer: "Google → Landing page → See how it works → + Sign up → Set up family → Start using calendar → First walk completed → Everyone happy" ``` **Agent captures:** + ``` SCENARIO: Parent Onboarding to First Success @@ -118,6 +120,7 @@ Now let's start sketching this journey. ## What This Gives You **Clear foundation for sketching:** + - ✅ Natural starting point (where user actually is) - ✅ Mental state (how they're feeling) - ✅ End goal (mutual success defined) @@ -125,6 +128,7 @@ Now let's start sketching this journey. - ✅ WHY behind each step (trigger map connection) **Now you can sketch with purpose:** + - Each page serves the journey - Each feature addresses mental state - Each step moves toward mutual success @@ -142,7 +146,7 @@ Target Group: Budget-conscious customers First Contact: Google search "affordable [product]" Mental State: Anxious about hidden costs, need transparency End Goal: Purchase completed, confident in value -Shortest Path: Google → Product page → Transparent pricing → +Shortest Path: Google → Product page → Transparent pricing → Add to cart → Checkout → Confirmation SCENARIO: Transparent Purchase Journey @@ -158,7 +162,7 @@ Target Group: Small business owners First Contact: ChatGPT recommendation Mental State: Overwhelmed, need simple solution End Goal: Active subscription, problem solved -Shortest Path: ChatGPT → Landing → See demo → Sign up → +Shortest Path: ChatGPT → Landing → See demo → Sign up → Quick setup → First success SCENARIO: Frictionless Onboarding @@ -174,7 +178,7 @@ Target Group: First-time clients First Contact: Friend recommendation Mental State: Curious but cautious, need trust End Goal: Appointment booked, feeling confident -Shortest Path: Friend link → About page → Testimonials → +Shortest Path: Friend link → About page → Testimonials → Book consultation → Confirmation SCENARIO: Trust-Building Booking @@ -187,6 +191,7 @@ SCENARIO: Trust-Building Booking **Not a script. A conversation.** Agent helps you think through: + - What drives the business? - Who makes it happen? - Where do they start? @@ -201,6 +206,7 @@ Agent helps you think through: ## Next Step Once you have: + - ✅ Natural starting point - ✅ Mental state - ✅ End goal diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md index 2d1f54de..b94a3fa6 100644 --- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md +++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md @@ -9,6 +9,7 @@ You've created your Trigger Map. Now: **What should you start sketching?** This process helps you identify: + - The core feature to design first - The natural starting point - The user's mental state @@ -19,18 +20,23 @@ This process helps you identify: ## The 5 Questions ### [1. What Feature Delivers Value?](01-feature-selection.md) + Which core feature serves your primary target group? ### [2. Where Do They Encounter It?](02-entry-point.md) + Where does the user first come into contact with your solution? ### [3. What's Their Mental State?](03-mental-state.md) + How are they feeling at this moment? ### [4. What's Mutual Success?](04-mutual-success.md) + What does winning look like for both business and user? ### [5. What's the Shortest Path?](05-shortest-path.md) + Minimum steps from starting point to mutual success --- @@ -38,12 +44,15 @@ Minimum steps from starting point to mutual success ## Examples ### [E-commerce Example](examples/ecommerce-example.md) + Sales-driven transparent purchase journey ### [SaaS Example](examples/saas-example.md) + Subscription-driven frictionless onboarding ### [Service Booking Example](examples/booking-example.md) + Appointment-driven trust-building flow --- diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/01-feature-selection.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/01-feature-selection.md index 7712ad6c..b44eb70e 100644 --- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/01-feature-selection.md +++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/01-feature-selection.md @@ -8,9 +8,9 @@ ``` Agent: "Looking at your Trigger Map and prioritized feature list, - what's the core feature that delivers value to your + what's the core feature that delivers value to your primary target group? - + This is what we should sketch first." ``` @@ -19,6 +19,7 @@ Agent: "Looking at your Trigger Map and prioritized feature list, ## Why This Matters Your Trigger Map already identified: + - Primary target group - What triggers their need - What outcome they want @@ -30,17 +31,20 @@ Your Trigger Map already identified: ## Example: Dog Week **From Trigger Map:** + - Target: Parents - Trigger: Family conflict over dog care - Outcome: Accountability without nagging **Feature Selection:** + ``` -Designer: "The family dog walk calendar - it solves the accountability +Designer: "The family dog walk calendar - it solves the accountability problem that causes conflict." ``` **Why this feature first:** + - Directly addresses the trigger (conflict) - Serves the primary target group (parents) - Delivers the desired outcome (accountability) diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/02-entry-point.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/02-entry-point.md index a00419cc..be6bfdd7 100644 --- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/02-entry-point.md +++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/02-entry-point.md @@ -7,7 +7,7 @@ ## The Question ``` -Agent: "Where does your primary target group first come into +Agent: "Where does your primary target group first come into contact with this solution?" ``` @@ -16,11 +16,13 @@ Agent: "Where does your primary target group first come into ## Why This Matters The entry point determines: + - Where the scenario starts - What mental state they're in - What context you're designing for **Common entry points:** + - Google search - ChatGPT recommendation - App store browsing @@ -33,11 +35,12 @@ The entry point determines: ## Example: Dog Week ``` -Designer: "Google search - they're frustrated with family conflict +Designer: "Google search - they're frustrated with family conflict over dog care." ``` **Why this matters:** + - They're actively searching (high intent) - They're frustrated (emotional state) - They need immediate clarity (landing page critical) diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/03-mental-state.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/03-mental-state.md index b45c52ae..cd61b823 100644 --- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/03-mental-state.md +++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/03-mental-state.md @@ -8,7 +8,7 @@ ``` Agent: "When they find your solution, how are they feeling? - + Think about: - What just happened? (trigger moment) - What are they hoping for? @@ -20,6 +20,7 @@ Agent: "When they find your solution, how are they feeling? ## Why This Matters Mental state determines: + - Tone of content - Complexity of interface - Type of features needed @@ -38,6 +39,7 @@ Designer: "Just had another fight about who walks the dog. ``` **Design implications:** + - Tone: Empathetic, not preachy - Interface: Simple, not complex - Features: Automated accountability, not more work diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/04-mutual-success.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/04-mutual-success.md index 3bd7843e..5fc3b71d 100644 --- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/04-mutual-success.md +++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/04-mutual-success.md @@ -8,7 +8,7 @@ ``` Agent: "What does success look like for both sides? - + For the business: [what outcome?] For the user: [what state/feeling/outcome?]" ``` @@ -18,6 +18,7 @@ Agent: "What does success look like for both sides? ## Why This Matters Success must be mutual: + - Business gets value - User gets value - Both are happy @@ -35,6 +36,7 @@ Designer: "Business: Active subscription ``` **Why both matter:** + - Business needs subscription (revenue) - User needs harmony (problem solved) - Subscription only works if harmony is real diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/05-shortest-path.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/05-shortest-path.md index f6468745..510f5cb5 100644 --- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/05-shortest-path.md +++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/05-shortest-path.md @@ -7,9 +7,9 @@ ## The Question ``` -Agent: "Let's map the shortest possible journey from +Agent: "Let's map the shortest possible journey from [starting point] to [mutual success]: - + What's the absolute minimum path?" ``` @@ -18,6 +18,7 @@ Agent: "Let's map the shortest possible journey from ## Why This Matters Shortest path means: + - No unnecessary steps - No feature bloat - Clear focus @@ -33,12 +34,13 @@ Shortest path means: Agent: "From 'frustrated parent on Google' to 'active subscription + harmony': What's the minimum path?" -Designer: "Google → Landing page → See how it works → - Sign up → Set up family → Start using calendar → +Designer: "Google → Landing page → See how it works → + Sign up → Set up family → Start using calendar → First walk completed → Everyone happy" ``` **Why this path:** + - Landing: Understand solution (addresses frustration) - How it works: See it's simple (addresses complexity fear) - Sign up: Commit to trying (low friction) @@ -74,6 +76,7 @@ Each step serves the journey. Nothing extra. ## Now You Can Sketch With all 5 questions answered, you have: + - ✅ Core feature (what to design) - ✅ Entry point (where to start) - ✅ Mental state (how they feel) diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/booking-example.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/booking-example.md index a0e8d44a..f3a64d3b 100644 --- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/booking-example.md +++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/booking-example.md @@ -7,29 +7,34 @@ ## The 5 Questions ### 1. Core Feature + ``` "Consultation booking with social proof - testimonials + credentials" ``` ### 2. Entry Point + ``` "Friend recommendation (shared link)" ``` ### 3. Mental State + ``` "Curious but cautious, need to trust before committing time/money" ``` ### 4. Mutual Success + ``` Business: Consultation booked (lead captured) User: Confident in decision, looking forward to meeting ``` ### 5. Shortest Path + ``` -Friend link → About page → Testimonials → +Friend link → About page → Testimonials → Book consultation → Confirmation ``` diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/ecommerce-example.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/ecommerce-example.md index 7d45c926..de58ebbc 100644 --- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/ecommerce-example.md +++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/ecommerce-example.md @@ -7,29 +7,34 @@ ## The 5 Questions ### 1. Core Feature + ``` "Transparent pricing breakdown - shows all costs upfront" ``` ### 2. Entry Point + ``` "Google search 'affordable [product]'" ``` ### 3. Mental State + ``` "Anxious about hidden costs, need transparency before committing" ``` ### 4. Mutual Success + ``` Business: Purchase completed User: Confident in value, no surprise costs ``` ### 5. Shortest Path + ``` -Google → Product page → Transparent pricing → +Google → Product page → Transparent pricing → Add to cart → Checkout → Confirmation ``` diff --git a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/saas-example.md b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/saas-example.md index 14649493..977a60f3 100644 --- a/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/saas-example.md +++ b/src/modules/wds/workflows/4-ux-design/scenario-init/scenario-init/examples/saas-example.md @@ -7,29 +7,34 @@ ## The 5 Questions ### 1. Core Feature + ``` "Quick setup wizard - gets users to first success fast" ``` ### 2. Entry Point + ``` "ChatGPT recommendation" ``` ### 3. Mental State + ``` "Overwhelmed by current tools, need simple solution that just works" ``` ### 4. Mutual Success + ``` Business: Active monthly subscription User: Problem solved, no complexity added ``` ### 5. Shortest Path + ``` -ChatGPT → Landing → See demo → Sign up → +ChatGPT → Landing → See demo → Sign up → Quick setup → First success ``` diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-01-init.md b/src/modules/wds/workflows/4-ux-design/steps/step-01-init.md index 8d332dd3..afba0403 100644 --- a/src/modules/wds/workflows/4-ux-design/steps/step-01-init.md +++ b/src/modules/wds/workflows/4-ux-design/steps/step-01-init.md @@ -24,13 +24,14 @@ Set up the design session and determine what scenario or page the user wants to **Step 2: Scenario Definition** - Define the user journey and pages **Step 3: Page Design** - Design each page using substeps 4A-4E: - - 4A: Exploration (think through concept) - - 4B: Sketch Analysis (analyze your sketches) - - 4C: Specification (document everything) - - 4D: Prototype (create interactive HTML) - - 4E: PRD Update (extract requirements) -**Step 4: Complete Scenario** - Finalize and celebrate -**Step 5: Continue or Exit** - Next steps + +- 4A: Exploration (think through concept) +- 4B: Sketch Analysis (analyze your sketches) +- 4C: Specification (document everything) +- 4D: Prototype (create interactive HTML) +- 4E: PRD Update (extract requirements) + **Step 4: Complete Scenario** - Finalize and celebrate + **Step 5: Continue or Exit** - Next steps **Key principle:** Designs that can be logically explained without gaps are easy to develop. The specification process reveals gaps early - when they're easy to address. @@ -49,16 +50,19 @@ Choice [1/2/3]: ## MENU HANDLING ### Choice 1: New Scenario + - Proceed to Step 2 (Scenario Definition) - Load `steps/step-02-define-scenario.md` ### Choice 2: Continue Existing + - Ask which scenario/page to continue - Determine current status (which substep they're on) - Load appropriate step file based on status - Skip Step 2 if scenario already defined ### Choice 3: Review Structure + - List scenarios in `{output_folder}/C-Scenarios/` - Show completion status for each - Return to this menu @@ -73,4 +77,3 @@ After user selects [1] for new scenario, load `steps/step-02-define-scenario.md` If user selects [2], determine current state and load appropriate step. If user selects [3], show structure and return to this step. - diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-02-define-scenario.md b/src/modules/wds/workflows/4-ux-design/steps/step-02-define-scenario.md index 05617318..b82f18fb 100644 --- a/src/modules/wds/workflows/4-ux-design/steps/step-02-define-scenario.md +++ b/src/modules/wds/workflows/4-ux-design/steps/step-02-define-scenario.md @@ -23,6 +23,7 @@ A scenario is a cohesive user journey containing multiple related pages.**What scenario are we designing?** Examples: + - "User Onboarding" (sign up through profile setup) - "Booking Flow" (search through confirmation) - "Dashboard Experience" (home screen with navigation) @@ -38,6 +39,7 @@ Scenario name: List the main screens/pages in order. Example: + 1. Start Page 2. Sign Up 3. Profile Setup @@ -45,19 +47,22 @@ Example: Store pages list Create folder structure for each page: - - {nn}.1-{page-name}/ - - {nn}.2-{page-name}/ - - etc. - + +- {nn}.1-{page-name}/ +- {nn}.2-{page-name}/ +- etc. + ✅ **Scenario structure created:** `C-Scenarios/{nn}-{scenario-name}/` {{#each page}} - - `{nn}.{n}-{page-name}/` -{{/each}} + +- `{nn}.{n}-{page-name}/` + {{/each}} We'll design each page using the 4A-4E process: + - **4A: Exploration** (optional - think through concept) - **4B: Sketch Analysis** (analyze your sketches) - **4C: Specification** (document everything systematically) @@ -77,6 +82,7 @@ Ready to design the first page? 🎨 ## STATE MANAGEMENT Before proceeding: + - Save scenario structure to `C-Scenarios/{nn}-{scenario-name}/scenario-info.yaml` - Include: scenario_name, scenario_number, pages_list, current_page_index (0) @@ -85,4 +91,3 @@ Before proceeding: ## NEXT STEP When user selects [C], load `steps/step-03-design-page.md` to begin designing the first page. - diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-03-design-page.md b/src/modules/wds/workflows/4-ux-design/steps/step-03-design-page.md index 84386bc7..03f17b1e 100644 --- a/src/modules/wds/workflows/4-ux-design/steps/step-03-design-page.md +++ b/src/modules/wds/workflows/4-ux-design/steps/step-03-design-page.md @@ -70,6 +70,7 @@ Choice [1/2]: **Time to create the complete specification.** 📝 We'll go through this systematically in focused steps: + 1. Page basics 2. Layout sections 3. Components & Object IDs @@ -82,15 +83,16 @@ We'll go through this systematically in focused steps: This ensures nothing is missed and every detail is captured. Execute substeps in sequence: - 1. Load and execute `substeps/4c-01-page-basics.md` - 2. Load and execute `substeps/4c-02-layout-sections.md` - 3. Load and execute `substeps/4c-03-components-objects.md` - 4. Load and execute `substeps/4c-04-content-languages.md` - 5. Load and execute `substeps/4c-05-interactions.md` - 6. Load and execute `substeps/4c-06-states.md` - 7. Load and execute `substeps/4c-07-validation.md` - 8. Load and execute `substeps/4c-08-generate-spec.md` - + +1. Load and execute `substeps/4c-01-page-basics.md` +2. Load and execute `substeps/4c-02-layout-sections.md` +3. Load and execute `substeps/4c-03-components-objects.md` +4. Load and execute `substeps/4c-04-content-languages.md` +5. Load and execute `substeps/4c-05-interactions.md` +6. Load and execute `substeps/4c-06-states.md` +7. Load and execute `substeps/4c-07-validation.md` +8. Load and execute `substeps/4c-08-generate-spec.md` + When all 4C substeps complete, return here and continue to 4D @@ -130,10 +132,11 @@ Choice [1/2]: **Page "{page-name}" is complete!** 🎉 **Created:** + - ✅ Specification: `C-Scenarios/{scenario}/{page}/{page}.md` -{{#if prototype_created}} + {{#if prototype_created}} - ✅ Prototype: `C-Scenarios/{scenario}/{page}/Prototype/` -{{/if}} + {{/if}} - ✅ PRD Requirements: Added to `D-PRD/PRD.md` **Your page is development-ready!** ✨ @@ -148,11 +151,11 @@ Choice [1/2]: **Next page: {next_page_name}** - [C] Continue to next page - [P] Pause - Save and continue later +[C] Continue to next page +[P] Pause - Save and continue later + +Choice [C/P]: - Choice [C/P]: - Loop back to top of Step 3 with new page @@ -173,6 +176,7 @@ Choice [1/2]: ## STATE MANAGEMENT After each page: + - Update scenario-info.yaml with current_page_index - Mark page as complete in tracking - Save progress @@ -183,4 +187,3 @@ After each page: - If more pages: Loop back to top of Step 3 - If scenario complete: Load `steps/step-04-complete-scenario.md` - diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-04-complete-scenario.md b/src/modules/wds/workflows/4-ux-design/steps/step-04-complete-scenario.md index 7ae541d1..77f31301 100644 --- a/src/modules/wds/workflows/4-ux-design/steps/step-04-complete-scenario.md +++ b/src/modules/wds/workflows/4-ux-design/steps/step-04-complete-scenario.md @@ -21,22 +21,24 @@ Acknowledge completion and transition to next steps. ✅ **Scenario "{scenario_name}" complete!** **Created:** + - Scenario folder: `C-Scenarios/{nn}-{scenario-name}/` - Page specifications: {{page_count}} pages -{{#if prototype_count > 0}} + {{#if prototype_count > 0}} - HTML prototypes: {{prototype_count}} prototypes -{{/if}} + {{/if}} - PRD updates: {{requirements_count}} requirements added **Each page includes:** + - Complete specification with Object IDs - Component definitions - Interaction behaviors - State definitions - Multilingual content -{{#if prototype_count > 0}} + {{#if prototype_count > 0}} - Interactive prototype -{{/if}} + {{/if}} **Your specifications are development-ready!** 🎨 @@ -55,4 +57,3 @@ Choice [C]: ## NEXT STEP When user selects [C], load `steps/step-05-next-steps.md` for workflow completion. - diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-05-next-steps.md b/src/modules/wds/workflows/4-ux-design/steps/step-05-next-steps.md index d0a58e26..ded00df7 100644 --- a/src/modules/wds/workflows/4-ux-design/steps/step-05-next-steps.md +++ b/src/modules/wds/workflows/4-ux-design/steps/step-05-next-steps.md @@ -39,18 +39,22 @@ Choice [1/2/3/4/5]: ## MENU HANDLING ### Choice 1: Design Another Scenario + Return to Step 2 (Define Scenario) Load `steps/step-02-define-scenario.md` ### Choice 2: Phase 5 (Design System) + To start Phase 5, activate Freyja (WDS Designer) again and run the Design System workflow. Exit this workflow ### Choice 3: Phase 6 (PRD Finalization) + To start Phase 6, activate Idunn (WDS PM) and run the PRD Finalization workflow. Exit this workflow ### Choice 4: Review Progress + List all scenarios in C-Scenarios/ Show completion status for each Count total pages designed @@ -59,6 +63,7 @@ Choice [1/2/3/4/5]: If Y, return to menu in this step ### Choice 5: Exit + Perfect! All your work is saved. Resume anytime by running the UX Design workflow again. See you next time! 🎨✨ @@ -69,4 +74,3 @@ See you next time! 🎨✨ ## WORKFLOW COMPLETE This is the final step. User either loops to another scenario or exits. - diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4a-exploration.md b/src/modules/wds/workflows/4-ux-design/substeps/4a-exploration.md index 9154299f..a34bc472 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4a-exploration.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4a-exploration.md @@ -7,11 +7,13 @@ ## When to Use This Step Use 4A when: + - User has no existing sketches - User is unsure how to approach a feature - User wants to explore the concept together Skip 4A when: + - User has sketches ready - User knows exactly what they want @@ -22,6 +24,7 @@ Skip 4A when: **Let's explore this concept together before sketching.** I'll help you think through: + - What the user is trying to accomplish - What content and features they need - How psychological triggers from your Trigger Map apply @@ -36,6 +39,7 @@ What's their goal? What brought them here? **What do they need to see or do to accomplish that?** Think about: + - Information they need - Actions they can take - Choices they need to make @@ -45,6 +49,7 @@ Think about: **Let's check your Trigger Map - what drives this user?** Looking at your personas and driving forces: + - What positive goals does this page support? - What negative outcomes does it help them avoid? @@ -54,6 +59,7 @@ Looking at your personas and driving forces: **How does the interaction flow?** Walk me through: + 1. User arrives (from where?) 2. User sees... (what catches attention?) 3. User does... (main actions?) @@ -75,6 +81,7 @@ Walk me through: {{interaction_flow}} You're ready to sketch! Would you like to: + 1. **Create sketches** - Use your preferred tool, then come back for analysis (4B) 2. **Skip sketching** - Go directly to specification (4C) 3. **Explore more** - Refine the concept further @@ -97,4 +104,3 @@ You're ready to sketch! Would you like to: --- **Next:** Step 4B (Sketch Analysis) or Step 4C (Specification) - diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4b-sketch-analysis.md b/src/modules/wds/workflows/4-ux-design/substeps/4b-sketch-analysis.md index 9da32fc9..0f40443c 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4b-sketch-analysis.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4b-sketch-analysis.md @@ -29,6 +29,7 @@ Your sketch: Analyze entire sketch holistically: + 1. **Establish Scale First:** - Check if other pages in project have been analyzed - Look for established text styles (body text, buttons, headings) @@ -45,15 +46,16 @@ Your sketch: - Check if sections look like components from previous pages - Compare text styles to established patterns (e.g., "thin lines, icon-sized spacing = 16px body text") - Note potential design system components - + **📊 I've analyzed your sketch. Here's what I see:** {{#if has_previous_pages}} **🔗 Cross-Page References Detected:** {{#each established_patterns}} + - {{pattern_name}}: {{specification}} (from {{source_page}}) -{{/each}} + {{/each}} I'll use these as reference points for consistency. {{/if}} @@ -62,19 +64,21 @@ I'll use these as reference points for consistency. **{{page_name}}** contains **{{section_count}} main sections:** -{{#each identified_sections}} ---- +## {{#each identified_sections}} + **Section {{index}}: {{section_name}}** ({{location}}) + - **Purpose:** {{interpreted_purpose}} - **Contains:** {{object_count}} objects/elements - **Layout:** {{layout_description}} -{{#if looks_like_previous_component}} + {{#if looks_like_previous_component}} - 💡 **Component?** Similar to {{component_name}} from {{previous_page}} -{{/if}} -{{#if matches_established_pattern}} + {{/if}} + {{#if matches_established_pattern}} - ✅ **Pattern Match:** Text styles match {{pattern_name}} from {{source_page}} -{{/if}} -{{/each}} + {{/if}} + {{/each}} + --- This is my interpretation of the structure. Does this look right? @@ -97,17 +101,17 @@ Current breakdown: {{/each}} Your changes: - - Update section structure based on feedback - **Updated structure:** - - {{#each updated_sections}} - {{index}}. {{section_name}} - {{interpreted_purpose}} - {{/each}} - - Does this look better? - - Loop until user confirms structure + +Update section structure based on feedback +**Updated structure:** + +{{#each updated_sections}} +{{index}}. {{section_name}} - {{interpreted_purpose}} +{{/each}} + +Does this look better? + +Loop until user confirms structure --- @@ -129,8 +133,8 @@ Your changes: 3. **Let me decide section-by-section** - I'll choose as we go Choice [1/2/3]: - - Mark sections as components or page-specific based on user choice + +Mark sections as components or page-specific based on user choice --- @@ -166,7 +170,7 @@ I'll interpret the objects, functions, and content for each section. You can con - Function & Purpose - Text Content (Actual vs. Markers) - Visual Hierarchy - + **My interpretation of "{{section_name}}":** @@ -176,19 +180,20 @@ I'll interpret the objects, functions, and content for each section. You can con {{#each interpreted_objects}} {{object_index}}. **{{interpreted_type}}** ({{hierarchy_level}}) - - **Object ID:** `{{suggested_object_id}}` - {{#if is_container}} - - **Contains:** - {{#each children}} - - {{child_type}}: `{{child_object_id}}` - {{/each}} - {{/if}} - - **Function:** {{interpreted_function}} - - **Purpose:** {{interpreted_purpose}} - {{#if has_actual_text}} - - **Text in sketch:** "{{extracted_text}}" - {{/if}} -{{/each}} + +- **Object ID:** `{{suggested_object_id}}` + {{#if is_container}} +- **Contains:** + {{#each children}} + - {{child_type}}: `{{child_object_id}}` + {{/each}} + {{/if}} +- **Function:** {{interpreted_function}} +- **Purpose:** {{interpreted_purpose}} + {{#if has_actual_text}} +- **Text in sketch:** "{{extracted_text}}" + {{/if}} + {{/each}} **Overall Function:** {{section_function_summary}} @@ -246,8 +251,8 @@ Choice [1/2/3/4]: I'll suggest translations for everything at once. -{{#each text_objects}} ---- +## {{#each text_objects}} + **{{object_purpose}}** (`{{object_id}}`) {{#if has_actual_text}} @@ -289,8 +294,8 @@ Use these? [1] Yes [2] Adjust [3] Manual {{/if}} -Store confirmed content for this object ---- +## Store confirmed content for this object + {{/each}} --- @@ -302,6 +307,7 @@ Use these? [1] Yes [2] Adjust [3] Manual Let me generate the complete section specification... Generate section spec: + 1. Section header with purpose 2. All objects with full details 3. All translations grouped by object @@ -309,32 +315,36 @@ Let me generate the complete section specification... 5. Interactions and behaviors 6. States if applicable 7. Validation rules if applicable - + **✅ Section "{{section_name}}" specification generated!** ```markdown ### {{Section_Name}} + **Purpose**: {{section_purpose}} {{#each objects}} + #### {{Object_Purpose_Title}} + **OBJECT ID**: `{{object_id}}` + - **Component**: {{component_type}} - **Position**: {{position}} - **Style**: {{style_specs}} -{{#if has_behavior}} + {{#if has_behavior}} - **Behavior**: {{behavior}} -{{/if}} -{{#if is_text}} + {{/if}} + {{#if is_text}} - **Content**: {{#each product_languages}} - {{this}}: "{{content}}" - {{/each}} -{{/if}} -{{#if has_states}} + {{/each}} + {{/if}} + {{#if has_states}} - **States**: {{states}} -{{/if}} + {{/if}} {{/each}} ``` @@ -395,6 +405,7 @@ Let me generate the complete section specification... ### Step 1: Holistic Reading **AI:** + ``` I've analyzed your sketch. Here's what I see: @@ -434,6 +445,7 @@ Does this structure look right? ### Step 2: Section 1 - Header **AI interprets:** + ``` My interpretation of "Header": @@ -466,6 +478,7 @@ Does this interpretation look right? **User:** `1` (Confirms) **AI suggests content:** + ``` Content for "Sign In Button": @@ -481,18 +494,24 @@ Use these? [1] Yes [2] Adjust [3] Manual **User:** `1` (Accepts) **AI generates:** + ```markdown ### Header Object + **Purpose**: Navigation and user access with language selection #### Dog Week Logo + **OBJECT ID**: `start-header-logo` + - **Component**: [Logo Component](/docs/D-Design-System/.../Logo.md) - **Position**: Left-aligned - **Behavior**: Links to home page -#### Sign In Button +#### Sign In Button + **OBJECT ID**: `start-header-signin` + - **Component**: [Button Secondary](/docs/D-Design-System/.../Button-Secondary.md) - **Position**: Right side (before language selector) - **Behavior**: Navigate to sign-in page @@ -501,7 +520,9 @@ Use these? [1] Yes [2] Adjust [3] Manual - SE: "Logga in" #### Language Selector + **OBJECT ID**: `start-header-language` + - **Component**: [Language Selector](/docs/D-Design-System/.../LanguageSelector.md) - **Position**: Right side (after sign-in button) - **Behavior**: onChange → toggle language diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-01-page-basics.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-01-page-basics.md index bceb4f19..284352dd 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4c-01-page-basics.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-01-page-basics.md @@ -17,12 +17,13 @@ - Where users go next (exit points): Store page_basics: - - page_title - - url_route - - user_goal - - entry_points - - exit_points - + +- page_title +- url_route +- user_goal +- entry_points +- exit_points + ✅ **Page basics captured!** @@ -40,15 +41,15 @@ ```yaml page_basics: - title: "Sign In" - route: "/auth/signin" - user_goal: "Authenticate to access their account" + title: 'Sign In' + route: '/auth/signin' + user_goal: 'Authenticate to access their account' entry_points: - "Landing page 'Sign In' button" - - "Protected route redirects" + - 'Protected route redirects' exit_points: - - "Dashboard (success)" - - "Password reset (forgot password)" + - 'Dashboard (success)' + - 'Password reset (forgot password)' ``` --- @@ -56,4 +57,3 @@ page_basics: ## NEXT STEP Load `substeps/4c-02-layout-sections.md` - diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-02-layout-sections.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-02-layout-sections.md index d39a65af..431b6ba2 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4c-02-layout-sections.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-02-layout-sections.md @@ -15,16 +15,18 @@ Think about the major areas of the page (header, main content, sidebar, footer, Describe each major section and its purpose. Example: + - Header: Logo, navigation, user menu - Hero: Welcome message and primary CTA - Main Content: Sign-up form - Footer: Links and legal info For each section: - - Store section_name - - Store section_purpose - - Store section_priority (primary/secondary) - + +- Store section_name +- Store section_purpose +- Store section_priority (primary/secondary) + ✅ **Layout sections defined!** @@ -44,17 +46,17 @@ Example: ```yaml layout_sections: - - name: "Header" - purpose: "Navigation and branding" - priority: "secondary" - - - name: "Sign In Form" - purpose: "User authentication" - priority: "primary" - - - name: "Footer" - purpose: "Legal links and support" - priority: "secondary" + - name: 'Header' + purpose: 'Navigation and branding' + priority: 'secondary' + + - name: 'Sign In Form' + purpose: 'User authentication' + priority: 'primary' + + - name: 'Footer' + purpose: 'Legal links and support' + priority: 'secondary' ``` --- @@ -62,4 +64,3 @@ layout_sections: ## NEXT STEP Load `substeps/4c-03-components-objects.md` - diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-03-components-objects.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-03-components-objects.md index ca115b97..d3aab8e9 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4c-03-components-objects.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-03-components-objects.md @@ -24,48 +24,33 @@ Starting from top-left corner of this section... Loop through objects in section (top-to-bottom, left-to-right): - **Next object in {{section_name}}:** - - What is the first/next object in this section (from top-left)? +**Next object in {{section_name}}:** + +What is the first/next object in this section (from top-left)? + +Describe what you see: + +Store object_description + +### ROUTE TO OBJECT-TYPE INSTRUCTIONS + +Load and execute `object-types/object-router.md` + +Object-router will: 1. Ask user to identify object type 2. Load appropriate object-type instruction file 3. Guide through complete object documentation 4. Generate specification with Object ID 5. Return here when complete + + +### DESIGN SYSTEM CHECK (IF ENABLED) + +After component specification complete: 1. Check project config: Is design system enabled? 2. If YES: Load and execute `workflows/5-design-system/design-system-router.md` 3. Design system router will: - Check for similar components - Run opportunity/risk assessment if needed - Extract component-level info to design system - Return component reference - Update page spec with reference 4. If NO: Keep complete specification on page 5. Continue to next object + + +**More objects in {{section_name}}?** + +1. **Yes** - Document next object (move right, then down) +2. **No** - Section complete + +Choice [1/2]: - Describe what you see: - - Store object_description - - ### ROUTE TO OBJECT-TYPE INSTRUCTIONS - - Load and execute `object-types/object-router.md` - - Object-router will: - 1. Ask user to identify object type - 2. Load appropriate object-type instruction file - 3. Guide through complete object documentation - 4. Generate specification with Object ID - 5. Return here when complete - - - ### DESIGN SYSTEM CHECK (IF ENABLED) - - After component specification complete: - 1. Check project config: Is design system enabled? - 2. If YES: Load and execute `workflows/5-design-system/design-system-router.md` - 3. Design system router will: - - Check for similar components - - Run opportunity/risk assessment if needed - - Extract component-level info to design system - - Return component reference - - Update page spec with reference - 4. If NO: Keep complete specification on page - 5. Continue to next object - - - **More objects in {{section_name}}?** - - 1. **Yes** - Document next object (move right, then down) - 2. **No** - Section complete - - Choice [1/2]: - Loop back to document next object in section @@ -86,17 +71,19 @@ Starting from top-left corner of this section... ✅ **All components identified and documented!** **Summary:** + - **Sections processed:** {{section_count}} - **Total components:** {{component_count}} - **Components by type:** {{#each component_type}} - {{type_name}}: {{count}} - {{/each}} + {{/each}} **Object IDs assigned:** {{#each component}} + - `{{object_id}}` ({{component_type}}) -{{/each}} + {{/each}} **Next:** We'll specify the content and languages. @@ -122,6 +109,7 @@ Starting from top-left corner of this section... 5. Continue until all objects in all sections are documented **Benefits:** + - ✅ Consistent specifications across all WDS projects - ✅ Agents have clear, focused instructions for each object type - ✅ Example-driven (show, don't tell) @@ -136,21 +124,21 @@ Starting from top-left corner of this section... sections_processed: - signin-form: components: - - object_id: "signin-form-email-input" - type: "text-input" - documented_via: "object-types/text-input.md" - - - object_id: "signin-form-password-input" - type: "text-input" - documented_via: "object-types/text-input.md" - - - object_id: "signin-form-submit-button" - type: "button" - documented_via: "object-types/button.md" - - - object_id: "signin-form-forgot-link" - type: "link" - documented_via: "object-types/link.md" + - object_id: 'signin-form-email-input' + type: 'text-input' + documented_via: 'object-types/text-input.md' + + - object_id: 'signin-form-password-input' + type: 'text-input' + documented_via: 'object-types/text-input.md' + + - object_id: 'signin-form-submit-button' + type: 'button' + documented_via: 'object-types/button.md' + + - object_id: 'signin-form-forgot-link' + type: 'link' + documented_via: 'object-types/link.md' total_components: 4 component_types: @@ -164,4 +152,3 @@ component_types: ## NEXT STEP Load `substeps/4c-04-content-languages.md` - diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-04-content-languages.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-04-content-languages.md index 53fecde2..5fa4957d 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4c-04-content-languages.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-04-content-languages.md @@ -17,14 +17,15 @@ List all languages (e.g., English, Swedish, Spanish): We'll go through each text element and provide content in all {{language_count}} languages. For each text element (labels, buttons, headings, messages): - **{{element_name}}:** - - {{#each language}} - - {{language}}: +**{{element_name}}:** + +{{#each language}} + +- {{language}}: {{/each}} - - Store multilingual content for element + +Store multilingual content for element ✅ **Content specified in all languages!** @@ -51,28 +52,28 @@ supported_languages: content: page_title: - en: "Sign In" - sv: "Logga In" - + en: 'Sign In' + sv: 'Logga In' + email_label: - en: "Email Address" - sv: "E-postadress" - + en: 'Email Address' + sv: 'E-postadress' + email_placeholder: - en: "your@email.com" - sv: "din@epost.com" - + en: 'your@email.com' + sv: 'din@epost.com' + password_label: - en: "Password" - sv: "Lösenord" - + en: 'Password' + sv: 'Lösenord' + submit_button: - en: "Sign In" - sv: "Logga In" - + en: 'Sign In' + sv: 'Logga In' + forgot_password_link: - en: "Forgot password?" - sv: "Glömt lösenord?" + en: 'Forgot password?' + sv: 'Glömt lösenord?' ``` --- @@ -80,4 +81,3 @@ content: ## NEXT STEP Load `substeps/4c-05-interactions.md` - diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-05-interactions.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-05-interactions.md index 414bb3e6..f49fa12e 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4c-05-interactions.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-05-interactions.md @@ -11,18 +11,18 @@ For each interactive element, we'll specify what happens when users interact with it. For each component with Object ID: - **{{object_id}}** ({{element_type}}) - - What happens when the user interacts with this? - - - On click / on input / on focus? - - What's the immediate response? - - What state changes occur? - - Where does it navigate (if applicable)? - - What data is sent/received? +**{{object_id}}** ({{element_type}}) + +What happens when the user interacts with this? + +- On click / on input / on focus? +- What's the immediate response? +- What state changes occur? +- Where does it navigate (if applicable)? +- What data is sent/received? - - Store interaction_behavior for component + +Store interaction_behavior for component ✅ **Interactions defined!** @@ -45,34 +45,34 @@ For each interactive element, we'll specify what happens when users interact wit interactions: signin-form-email-input: on_focus: - - "Highlight border (primary color)" - - "Show label above field" + - 'Highlight border (primary color)' + - 'Show label above field' on_input: - - "Real-time validation (email format)" - - "Clear error state if valid" + - 'Real-time validation (email format)' + - 'Clear error state if valid' on_blur: - - "Validate complete email" - - "Show error if invalid" - + - 'Validate complete email' + - 'Show error if invalid' + signin-form-password-input: on_focus: - - "Highlight border" + - 'Highlight border' on_input: - - "Mask characters as bullets" + - 'Mask characters as bullets' on_blur: - - "Validate not empty" - + - 'Validate not empty' + signin-form-submit-button: on_click: - - "Validate all fields" - - "If valid: disable button, show loading state" - - "POST to /api/auth/signin" - - "On success: redirect to /dashboard" - - "On error: show error message, re-enable button" - + - 'Validate all fields' + - 'If valid: disable button, show loading state' + - 'POST to /api/auth/signin' + - 'On success: redirect to /dashboard' + - 'On error: show error message, re-enable button' + signin-form-forgot-link: on_click: - - "Navigate to /auth/forgot-password" + - 'Navigate to /auth/forgot-password' ``` --- @@ -80,4 +80,3 @@ interactions: ## NEXT STEP Load `substeps/4c-06-states.md` - diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-06-states.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-06-states.md index 5ff61f1e..9191c611 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4c-06-states.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-06-states.md @@ -15,6 +15,7 @@ States show how the page and components appear in different situations. **What are the different page-level states?** Think about: + - Default/loaded state - Empty state (no data) - Loading state (fetching data) @@ -22,6 +23,7 @@ Think about: - Success state (after action completes) For each state, describe: + - When it occurs - What the user sees - What actions are available @@ -35,20 +37,20 @@ For each state, describe: For components with multiple appearances, we'll specify each state. For components with multiple states: - **{{object_id}}** states: - - - Default: - - Hover: - - Active/Pressed: - - Focus: - - Disabled: - - Loading: - - Error: - - Success: - - (Only specify states that apply to this component) - - Store component_states +**{{object_id}}** states: + +- Default: +- Hover: +- Active/Pressed: +- Focus: +- Disabled: +- Loading: +- Error: +- Success: + +(Only specify states that apply to this component) + +Store component_states ✅ **All states defined!** @@ -71,49 +73,49 @@ For components with multiple appearances, we'll specify each state. ```yaml page_states: default: - trigger: "Page loads normally" - appearance: "Empty form ready for input" - actions: "User can fill form and submit" - + trigger: 'Page loads normally' + appearance: 'Empty form ready for input' + actions: 'User can fill form and submit' + loading: - trigger: "After submit clicked" - appearance: "Submit button shows spinner, form disabled" - actions: "Wait for response" - + trigger: 'After submit clicked' + appearance: 'Submit button shows spinner, form disabled' + actions: 'Wait for response' + error: - trigger: "Authentication fails" - appearance: "Error message above form, submit button re-enabled" - actions: "User can retry with different credentials" - + trigger: 'Authentication fails' + appearance: 'Error message above form, submit button re-enabled' + actions: 'User can retry with different credentials' + success: - trigger: "Authentication succeeds" - appearance: "Brief success message" - actions: "Redirect to dashboard" + trigger: 'Authentication succeeds' + appearance: 'Brief success message' + actions: 'Redirect to dashboard' component_states: signin-form-email-input: default: - appearance: "Gray border, placeholder text" + appearance: 'Gray border, placeholder text' focus: - appearance: "Primary color border, label floats up" + appearance: 'Primary color border, label floats up' filled: - appearance: "Dark border, label stays up" + appearance: 'Dark border, label stays up' error: - appearance: "Red border, error message below" + appearance: 'Red border, error message below' disabled: - appearance: "Light gray background, cursor not-allowed" - + appearance: 'Light gray background, cursor not-allowed' + signin-form-submit-button: default: - appearance: "Primary color background, white text" + appearance: 'Primary color background, white text' hover: - appearance: "Darker primary color" + appearance: 'Darker primary color' active: - appearance: "Even darker, slight scale down" + appearance: 'Even darker, slight scale down' loading: appearance: "Spinner icon, text 'Signing in...'" disabled: - appearance: "Gray background, lower opacity" + appearance: 'Gray background, lower opacity' ``` --- @@ -121,4 +123,3 @@ component_states: ## NEXT STEP Load `substeps/4c-07-validation.md` - diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-07-validation.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-07-validation.md index b7373c73..a823fed7 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4c-07-validation.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-07-validation.md @@ -15,21 +15,22 @@ This ensures users get helpful feedback. **What fields or inputs need validation?** For each field, specify: + - What makes it valid? - What makes it invalid? - When is it validated? (on blur, on submit, real-time?) For each validated field: - **{{field_name}}** validation: - - - Required: yes/no - - Format rules: - - Length limits: - - Custom rules: - - Validation timing: +**{{field_name}}** validation: + +- Required: yes/no +- Format rules: +- Length limits: +- Custom rules: +- Validation timing: - - Store validation_rules for field + +Store validation_rules for field ## ERROR MESSAGES @@ -39,16 +40,17 @@ For each field, specify: We'll provide messages in all supported languages. For each validation rule: - **Error message when {{rule_name}} fails:** - - {{#each language}} - - {{language}}: +**Error message when {{rule_name}} fails:** + +{{#each language}} + +- {{language}}: {{/each}} - - Error code (e.g., ERR_EMAIL_INVALID): - - - Store error_message with code and translations + +Error code (e.g., ERR_EMAIL_INVALID): + + +Store error_message with code and translations ✅ **Validation and errors defined!** @@ -72,47 +74,47 @@ We'll provide messages in all supported languages. validation_rules: email_input: required: true - format: "valid email format" - timing: "on_blur and on_submit" + format: 'valid email format' + timing: 'on_blur and on_submit' rules: - - "Must contain @" - - "Must have domain" - - "No spaces allowed" - + - 'Must contain @' + - 'Must have domain' + - 'No spaces allowed' + password_input: required: true min_length: 8 - timing: "on_submit" + timing: 'on_submit' rules: - - "At least 8 characters" - - "Not empty" + - 'At least 8 characters' + - 'Not empty' error_messages: ERR_EMAIL_REQUIRED: - en: "Email address is required" - sv: "E-postadress krävs" - field: "email_input" - + en: 'Email address is required' + sv: 'E-postadress krävs' + field: 'email_input' + ERR_EMAIL_INVALID: - en: "Please enter a valid email address" - sv: "Ange en giltig e-postadress" - field: "email_input" - + en: 'Please enter a valid email address' + sv: 'Ange en giltig e-postadress' + field: 'email_input' + ERR_PASSWORD_REQUIRED: - en: "Password is required" - sv: "Lösenord krävs" - field: "password_input" - + en: 'Password is required' + sv: 'Lösenord krävs' + field: 'password_input' + ERR_PASSWORD_TOO_SHORT: - en: "Password must be at least 8 characters" - sv: "Lösenordet måste vara minst 8 tecken" - field: "password_input" - + en: 'Password must be at least 8 characters' + sv: 'Lösenordet måste vara minst 8 tecken' + field: 'password_input' + ERR_AUTH_INVALID: - en: "Invalid email or password" - sv: "Ogiltig e-post eller lösenord" - severity: "critical" - display_location: "above_form" + en: 'Invalid email or password' + sv: 'Ogiltig e-post eller lösenord' + severity: 'critical' + display_location: 'above_form' ``` --- @@ -120,4 +122,3 @@ error_messages: ## NEXT STEP Load `substeps/4c-08-generate-spec.md` - diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-08-generate-spec.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-08-generate-spec.md index 0a9be87b..28046a5b 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4c-08-generate-spec.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-08-generate-spec.md @@ -13,6 +13,7 @@ Now I'll compile it all into your complete page specification. 📝 Generate specification document using template at `templates/page-specification.template.md` Fill in all sections with data collected: + - page_basics (from 4C-01) - layout_sections (from 4C-02) - components with object_ids (from 4C-03) @@ -20,7 +21,7 @@ Fill in all sections with data collected: - interaction_behaviors (from 4C-05) - page_states and component_states (from 4C-06) - validation_rules and error_messages (from 4C-07) - + Save complete specification to: `{output_folder}/C-Scenarios/{scenario}/{page}/{page}.md` @@ -31,6 +32,7 @@ Fill in all sections with data collected: **Saved to:** `C-Scenarios/{scenario}/{page}/{page}.md` **What we documented:** + - Page basics and routing - {{section_count}} layout sections - {{component_count}} components with Object IDs @@ -43,6 +45,7 @@ Fill in all sections with data collected: **Your specification is development-ready!** 📋✨ The specification document includes: + - Clear Object IDs for every element - Complete multilingual content - Detailed interaction behaviors @@ -68,12 +71,14 @@ Substep 4C is now complete. Return control to Step 3 (step-03-design-page.md) wh **Design System Component:** text-input (primary) **Content:** + - **Label (EN):** Email Address - **Label (SV):** E-postadress - **Placeholder (EN):** your@email.com - **Placeholder (SV):** din@epost.com **States:** + - **Default:** Gray border, placeholder visible - **Focus:** Primary color border, label floats above - **Filled:** Dark border, label remains above @@ -81,11 +86,13 @@ Substep 4C is now complete. Return control to Step 3 (step-03-design-page.md) wh - **Disabled:** Light gray background, not interactive **Interactions:** + - **On Focus:** Highlight border, float label - **On Input:** Real-time email format validation - **On Blur:** Full validation, show error if invalid **Validation:** + - Required: Yes - Format: Valid email (contains @, has domain) - Error Code: ERR_EMAIL_INVALID @@ -96,4 +103,3 @@ Substep 4C is now complete. Return control to Step 3 (step-03-design-page.md) wh --- **Substep 4C Complete!** Return to main page design flow. - diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md b/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md index 7c302149..ce42e118 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md @@ -7,6 +7,7 @@ **Let's bring your specification to life!** I'll create an interactive HTML prototype that: + - Matches your specification exactly - Uses your Design System (if Phase 5 enabled) - Includes interactions and validation @@ -30,25 +31,27 @@ Choice [1/2/3]: Generate HTML prototype: **File 1: HTML** ({page}-Prototype.html) + ```html - - - - {{page_title}} - Prototype - - - - - {{generate_html_from_spec}} - - - + + + + {{page_title}} - Prototype + + + + + {{generate_html_from_spec}} + + + ``` **File 2: CSS** ({page}-Prototype.css) + ```css /* Design System tokens (if Phase 5 enabled) */ {{design_system_imports}} @@ -64,22 +67,44 @@ Choice [1/2/3]: ``` **File 3: JavaScript** ({page}-Prototype.js) + ```javascript // Interaction behaviors from specification -{{generate_interactions_from_spec}} +{ + { + generate_interactions_from_spec; + } +} // Validation logic -{{validation_logic}} +{ + { + validation_logic; + } +} // State management -{{state_management}} +{ + { + state_management; + } +} // Language switching -{{language_switching}} +{ + { + language_switching; + } +} // Initialize -{{initialization_code}} +{ + { + initialization_code; + } +} ``` + Save files to {output_folder}/C-Scenarios/{scenario}/{page}/Prototype/ @@ -87,13 +112,15 @@ Choice [1/2/3]: ✅ **Prototype created!** **Files:** + - `Prototype/{page}-Prototype.html` -- `Prototype/{page}-Prototype.css` +- `Prototype/{page}-Prototype.css` - `Prototype/{page}-Prototype.js` **Open the HTML file in your browser to test!** Try: + - Clicking all interactive elements - Testing validation - Switching languages @@ -103,6 +130,7 @@ Try: **After testing, what did you discover?** Common findings: + - Visual adjustments needed - Missing states or interactions - Content that's too long/short @@ -117,8 +145,8 @@ Anything to fix or refine? 2. **Quick prototype fix** - Adjust prototype directly 3. **Note for later** - Document but move forward - Choice [1/2/3]: - +Choice [1/2/3]: + Return to Step 4C @@ -156,4 +184,3 @@ Your design is validated and ready for development. Time to extract the function --- **Next:** Step 4E (PRD Update) - diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4e-prd-update.md b/src/modules/wds/workflows/4-ux-design/substeps/4e-prd-update.md index 0d76945b..7d853f1f 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4e-prd-update.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4e-prd-update.md @@ -7,6 +7,7 @@ **Time to capture what we learned!** Every page reveals concrete requirements: + - "This form needs email validation" - "We need a GET endpoint for availability" - "Users need to upload images here" @@ -18,6 +19,7 @@ Capturing these while the page is fresh ensures nothing is forgotten. The PRD be **Let's identify the functional requirements this page revealed.** Think about: + - API endpoints needed - Data validation rules - File upload/storage @@ -29,13 +31,13 @@ Think about: What functionality does this page require from the backend/platform? For each requirement: - **Requirement: {{requirement_name}}** - - - What does it do? - - Why is it needed? - - Any specific constraints or rules? - - Document requirement details +**Requirement: {{requirement_name}}** + +- What does it do? +- Why is it needed? +- Any specific constraints or rules? + +Document requirement details ## PRD Integration @@ -43,6 +45,7 @@ What functionality does this page require from the backend/platform? **I'll add these requirements to your PRD.** Each requirement will include: + - Clear description - Reference to this page (e.g., "Required by: 2.1-Dog-Calendar") - Any technical notes discovered during design @@ -55,13 +58,16 @@ Each requirement will include: ## Functional Requirements ### {{requirement_name}} + **Required by:** {{page_reference}} + - {{requirement_description}} - {{constraints}} - {{technical_notes}} [Add to appropriate section of PRD] ``` + Update PRD file with new requirements @@ -71,8 +77,9 @@ Each requirement will include: **Added {{requirement_count}} requirements:** {{#each requirement}} + - {{requirement_name}} (required by {{page_reference}}) -{{/each}} + {{/each}} **PRD Location:** `D-PRD/PRD.md` @@ -83,11 +90,13 @@ Your PRD is growing incrementally with every page you design. This creates compl **Page "{page_name}" is complete!** 🎉 **Created:** + - ✅ Specification: `C-Scenarios/{scenario}/{page}/{page}.md` - ✅ Prototype: `C-Scenarios/{scenario}/{page}/Prototype/` - ✅ PRD Requirements: Added to `D-PRD/PRD.md` **Your page is development-ready with:** + - Complete Object ID mapping - All states and interactions documented - Multilingual content specified @@ -128,4 +137,3 @@ Choice [1/2/3/4]: --- **Step 4E Complete** - Page fully designed and specified! - diff --git a/src/modules/wds/workflows/4-ux-design/templates/page-specification.template.md b/src/modules/wds/workflows/4-ux-design/templates/page-specification.template.md index a17859d8..0857e3ad 100644 --- a/src/modules/wds/workflows/4-ux-design/templates/page-specification.template.md +++ b/src/modules/wds/workflows/4-ux-design/templates/page-specification.template.md @@ -14,9 +14,11 @@ **URL/Route:** {url-path} **Entry Points:** + - {How users arrive at this page} **Exit Points:** + - {Where users go after completing their goal} **Main User Goal:** {Primary objective for users on this page} @@ -54,6 +56,7 @@ {/if} **States:** + - **Default:** {Description and behavior} - **Hover:** {Hover state appearance and behavior} - **Active:** {Active/clicked state} @@ -65,6 +68,7 @@ {What happens when user interacts with this component} **Content:** + - **English:** {Text content in English} - **{Language2}:** {Text content in second language} - **{Language3}:** {Text content in third language} @@ -119,17 +123,17 @@ {If applicable - for forms and inputs} -| Field | Rule | Error Code | Error Message | -|-------|------|------------|---------------| +| Field | Rule | Error Code | Error Message | +| ------------ | ----------------- | ---------- | --------------- | | {field-name} | {validation-rule} | {ERR_CODE} | {error-message} | --- ## Error Messages -| Error Code | Trigger | Message (English) | Message ({Lang2}) | Recovery | -|------------|---------|-------------------|-------------------|----------| -| ERR_001 | {When this error occurs} | {English message} | {Translated message} | {How to fix} | +| Error Code | Trigger | Message (English) | Message ({Lang2}) | Recovery | +| ---------- | ------------------------ | ----------------- | -------------------- | ------------ | +| ERR_001 | {When this error occurs} | {English message} | {Translated message} | {How to fix} | --- @@ -137,13 +141,14 @@ ### Data Sources -| Data Element | Source | Type | Required | Notes | -|--------------|--------|------|----------|-------| +| Data Element | Source | Type | Required | Notes | +| ------------ | ------------------------ | ----------- | -------- | ------- | | {data-field} | {API endpoint or static} | {data-type} | {yes/no} | {notes} | ### API Endpoints **{Endpoint Name}** + - **Method:** {GET/POST/PUT/DELETE} - **Path:** `/api/{path}` - **Purpose:** {What this endpoint does} @@ -180,6 +185,7 @@ ### User Interactions **{Interaction Name}** + 1. User {action} 2. System {response} 3. Page {state change} @@ -213,6 +219,7 @@ ## Development Checklist Before implementing: + - [ ] All Object IDs assigned and documented - [ ] All states defined and specified - [ ] Validation rules clear @@ -224,5 +231,4 @@ Before implementing: --- -*Created using Whiteport Design Studio (WDS) methodology* - +_Created using Whiteport Design Studio (WDS) methodology_ diff --git a/src/modules/wds/workflows/4-ux-design/templates/scenario-overview.template.md b/src/modules/wds/workflows/4-ux-design/templates/scenario-overview.template.md index 50ffae16..a6961d71 100644 --- a/src/modules/wds/workflows/4-ux-design/templates/scenario-overview.template.md +++ b/src/modules/wds/workflows/4-ux-design/templates/scenario-overview.template.md @@ -20,11 +20,11 @@ ## Pages in This Scenario -| Page # | Page Name | Status | Purpose | -|--------|-----------|--------|---------| -| {n}.1 | {page-name} | {draft/complete} | {Brief purpose} | -| {n}.2 | {page-name} | {draft/complete} | {Brief purpose} | -| {n}.3 | {page-name} | {draft/complete} | {Brief purpose} | +| Page # | Page Name | Status | Purpose | +| ------ | ----------- | ---------------- | --------------- | +| {n}.1 | {page-name} | {draft/complete} | {Brief purpose} | +| {n}.2 | {page-name} | {draft/complete} | {Brief purpose} | +| {n}.3 | {page-name} | {draft/complete} | {Brief purpose} | --- @@ -46,12 +46,14 @@ flowchart TD ## Scenario Steps ### Step 1: {Step Name} + **Page:** {n.1-Page-Name} **User Action:** {What the user does} **System Response:** {How the system responds} **Success Criteria:** {What defines success for this step} ### Step 2: {Step Name} + **Page:** {n.2-Page-Name} **User Action:** {What the user does} **System Response:** {How the system responds} @@ -84,18 +86,20 @@ This scenario helps users avoid: **Primary Metric:** {Main measure of scenario success} **Secondary Metrics:** + - {Metric 1} - {Metric 2} **User Satisfaction Indicators:** + - {What indicates good user experience} --- ## Edge Cases & Error Handling -| Edge Case | How Handled | Page(s) Affected | -|-----------|-------------|------------------| +| Edge Case | How Handled | Page(s) Affected | +| ----------------------- | ------------------- | ----------------- | | {edge-case-description} | {handling-approach} | {page-references} | --- @@ -110,8 +114,8 @@ This scenario helps users avoid: ### API Endpoints Used -| Endpoint | Page(s) | Purpose | -|----------|---------|---------| +| Endpoint | Page(s) | Purpose | +| --------------- | ----------- | -------------- | | {endpoint-path} | {page-refs} | {what-it-does} | ### State Management @@ -125,11 +129,13 @@ This scenario helps users avoid: **Scenario Folder:** `C-Scenarios/{scenario-number}-{scenario-name}/` **Page Specifications:** + - {n}.1-{page-name}/{page-name}.md - {n}.2-{page-name}/{page-name}.md - {n}.3-{page-name}/{page-name}.md **Prototypes:** + - {n}.1-{page-name}/Prototype/ - {n}.2-{page-name}/Prototype/ - {n}.3-{page-name}/Prototype/ @@ -144,11 +150,10 @@ This scenario helps users avoid: ## Revision History -| Date | Changes | Author | -|------|---------|--------| +| Date | Changes | Author | +| ------ | ------------------------ | -------- | | {date} | Initial scenario created | {author} | --- -*Created using Whiteport Design Studio (WDS) methodology* - +_Created using Whiteport Design Studio (WDS) methodology_ diff --git a/src/modules/wds/workflows/4-ux-design/workflow.md b/src/modules/wds/workflows/4-ux-design/workflow.md index 0ac00a9b..b39d2049 100644 --- a/src/modules/wds/workflows/4-ux-design/workflow.md +++ b/src/modules/wds/workflows/4-ux-design/workflow.md @@ -1,7 +1,7 @@ --- name: UX Design Workflow description: Transform ideas into detailed visual specifications through scenario-driven design -main_config: "{project-root}/{bmad_folder}/wds/config.yaml" +main_config: '{project-root}/{bmad_folder}/wds/config.yaml' web_bundle: true --- @@ -59,4 +59,3 @@ Load and read full config from {main_config} and resolve: ### 2. First Step Execution Load, read the full file and then execute `steps/step-01-init.md` to begin the workflow. - diff --git a/src/modules/wds/workflows/5-design-system/README.md b/src/modules/wds/workflows/5-design-system/README.md index 16b4c13c..706eddfd 100644 --- a/src/modules/wds/workflows/5-design-system/README.md +++ b/src/modules/wds/workflows/5-design-system/README.md @@ -11,11 +11,13 @@ ## When This Workflow Runs **Triggered from Phase 4:** + - After component specification is complete - Only if design system is enabled in project - First component triggers automatic initialization **Not a Separate Phase:** + - Runs in parallel with Phase 4 - Integrated into component specification flow - Designer doesn't "switch" to design system mode @@ -27,12 +29,14 @@ **Chosen during Phase 1 (Project Exploration):** ### Mode A: No Design System + - Components stay page-specific - AI/dev team handles consistency - Faster for simple projects - **This workflow doesn't run** ### Mode B: Custom Design System + - Designer defines components in Figma - Components extracted as discovered - Figma MCP endpoints for integration @@ -40,6 +44,7 @@ - **See:** `figma-integration/` folder for complete Figma workflow ### Mode C: Component Library Design System + - Uses shadcn/Radix/etc. - Library chosen during setup - Components mapped to library defaults @@ -79,11 +84,13 @@ Functionality/Storyboards (Behavior) ## Workflow Components ### 1. Design System Router + **File:** `design-system-router.md` **Purpose:** Identify if component is new, similar, or duplicate **Flow:** + ``` Component specified → Router checks design system ├── No similar component → Create new @@ -91,11 +98,13 @@ Component specified → Router checks design system ``` ### 2. Opportunity/Risk Assessment + **Folder:** `assessment/` **Purpose:** Help designer make informed decisions about component reuse **7 Micro-Instructions:** + 1. Scan existing components 2. Compare attributes 3. Calculate similarity @@ -105,22 +114,26 @@ Component specified → Router checks design system 7. Execute decision ### 3. Component Operations + **Folder:** `operations/` **Purpose:** Execute design system actions **4 Operations:** + - Initialize design system (first component) - Create new component - Add variant to existing component - Update component definition ### 4. Output Templates + **Folder:** `templates/` **Purpose:** Consistent design system file structure **3 Templates:** + - Component specification - Design tokens - Component library config @@ -132,6 +145,7 @@ Component specified → Router checks design system **Called from:** `workflows/4-ux-design/substeps/4c-03-components-objects.md` **Integration Point:** + ``` For each component: 1. Specify component (Phase 4) @@ -145,6 +159,7 @@ For each component: ``` **Result:** + - Page spec contains references + page-specific content - Design system contains component definitions - Clean separation maintained @@ -154,31 +169,37 @@ For each component: ## Key Risks & Mitigation ### 1. Component Matching + **Risk:** How to recognize "same" vs "similar" vs "different" **Mitigation:** Similarity scoring + designer judgment via assessment flow ### 2. Circular References + **Risk:** Page → Component → Functionality → Component **Mitigation:** Clear hierarchy (Page → Component → Functionality) ### 3. Sync Problems + **Risk:** Component evolves, references may break **Mitigation:** Reference IDs + update notifications ### 4. Component Boundaries + **Risk:** Icon in button? Nested components? **Mitigation:** Designer conversation + guidelines in shared knowledge ### 5. First Component + **Risk:** When to initialize design system? **Mitigation:** Auto-initialize on first component if enabled ### 6. Storyboard Granularity + **Risk:** Component behavior vs page flow **Mitigation:** Clear separation guidelines in shared knowledge @@ -192,6 +213,7 @@ For each component: **Purpose:** Centralized design system principles referenced by all component types **Documents:** + - `token-architecture.md` - Structure vs style separation - `naming-conventions.md` - Token naming rules - `state-management.md` - Component states @@ -210,11 +232,13 @@ For each component: **Purpose:** Enable seamless Figma ↔ WDS synchronization for custom design systems **Documents:** + - `figma-designer-guide.md` - Step-by-step guide for designers - `figma-mcp-integration.md` - Technical MCP integration guide - `figma-component-structure.md` - Component organization in Figma (in data/design-system/) **Workflow:** + 1. Designer creates/updates component in Figma 2. Designer adds WDS component ID to description 3. MCP reads component via Figma API @@ -222,6 +246,7 @@ For each component: 5. Designer reviews and confirms **Key Features:** + - Component structure guidelines - Design token mapping - Variant and state organization @@ -235,6 +260,7 @@ For each component: **Key Feature:** Companies can fork WDS and customize design system standards **Customization Points:** + - `data/design-system/` - Company-specific principles - `object-types/` - Company component patterns - `templates/` - Company output formats @@ -258,6 +284,7 @@ D-Design-System/ ``` **Component File Structure:** + ```markdown # Button Component [btn-001] @@ -266,20 +293,24 @@ D-Design-System/ **Figma:** [Link] (if Mode B) ## Variants + - primary - secondary - ghost ## States + - default - hover - active - disabled ## Styling + [Design tokens or Figma reference] ## Used In + - Login page (login button) - Signup page (create account button) - Dashboard (action buttons) diff --git a/src/modules/wds/workflows/5-design-system/assessment/01-scan-existing.md b/src/modules/wds/workflows/5-design-system/assessment/01-scan-existing.md index 829d792e..902e0c09 100644 --- a/src/modules/wds/workflows/5-design-system/assessment/01-scan-existing.md +++ b/src/modules/wds/workflows/5-design-system/assessment/01-scan-existing.md @@ -18,6 +18,7 @@ Scan design system components: **Example:** + ``` Current component: Button @@ -41,6 +42,7 @@ For each matching component, extract: **Example:** + ```yaml Button [btn-001]: variants: [primary, secondary, ghost] @@ -70,9 +72,11 @@ Present matching components: - Shape: rounded - Used in: 3 pages (login, signup, dashboard) ``` + **If multiple matches:** + ``` 🔍 Found 2 existing Button components: @@ -103,6 +107,7 @@ Pass candidate list to comparison step: ## Edge Cases **No matching components found:** + ``` ✓ No existing Button components in design system. @@ -112,6 +117,7 @@ This will be the first Button component. **Route to:** `operations/create-new-component.md` **Design system empty:** + ``` ✓ Design system is empty. @@ -121,6 +127,7 @@ This will be the first component. **Route to:** `operations/initialize-design-system.md` **Multiple type matches:** + ``` 🔍 Found 2 Button-type components: @@ -134,6 +141,7 @@ I'll compare your new button to both to find the best match. ## Output Format **For next step:** + ```json { "current_component": { diff --git a/src/modules/wds/workflows/5-design-system/assessment/02-compare-attributes.md b/src/modules/wds/workflows/5-design-system/assessment/02-compare-attributes.md index 3858f511..0c7653d9 100644 --- a/src/modules/wds/workflows/5-design-system/assessment/02-compare-attributes.md +++ b/src/modules/wds/workflows/5-design-system/assessment/02-compare-attributes.md @@ -13,6 +13,7 @@ **Compare across 4 dimensions:** ### 1. Visual Attributes + - Size (small, medium, large) - Shape (rounded, square, pill) - Color scheme @@ -21,6 +22,7 @@ - Border style ### 2. Functional Attributes + - Purpose/intent - User action - Input/output type @@ -28,6 +30,7 @@ - Required/optional ### 3. Behavioral Attributes + - States (default, hover, active, disabled, loading, error) - Interactions (click, hover, focus, blur) - Animations/transitions @@ -35,6 +38,7 @@ - Accessibility ### 4. Contextual Attributes + - Usage pattern (where it appears) - Frequency (how often used) - Relationship to other components @@ -52,6 +56,7 @@ Compare visual attributes: **Example:** + ``` Visual Comparison: Current Button vs Button [btn-001] @@ -78,6 +83,7 @@ Compare functional attributes: **Example:** + ``` Functional Comparison: Current Button vs Button [btn-001] @@ -105,6 +111,7 @@ Compare behavioral attributes: **Example:** + ``` Behavioral Comparison: Current Button vs Button [btn-001] @@ -131,6 +138,7 @@ Compare contextual attributes: **Example:** + ``` Contextual Comparison: Current Button vs Button [btn-001] @@ -158,11 +166,13 @@ Score each dimension: **Scoring Guide:** + - **High:** 80%+ attributes match - **Medium:** 50-79% attributes match - **Low:** <50% attributes match **Example:** + ``` Similarity Score: Current Button vs Button [btn-001] @@ -198,6 +208,7 @@ Present comparison summary: **Similarity Score:** Medium-High (71%) ``` + --- @@ -218,6 +229,7 @@ Pass comparison data to similarity calculation: ## Edge Cases **Perfect match (100%):** + ``` ✓ This component is identical to btn-001. @@ -227,6 +239,7 @@ This is likely the same component with different content. **Recommend:** Reuse existing component **Very low similarity (<30%):** + ``` ✗ This component is very different from btn-001. @@ -236,6 +249,7 @@ Despite being the same type, these serve different purposes. **Recommend:** Create new component **Multiple candidates:** + ``` 📊 Comparing to 2 candidates: @@ -252,6 +266,7 @@ btn-001 is the closest match. ## Output Format **For next step:** + ```json { "comparison": { diff --git a/src/modules/wds/workflows/5-design-system/assessment/03-calculate-similarity.md b/src/modules/wds/workflows/5-design-system/assessment/03-calculate-similarity.md index 80421023..138525f4 100644 --- a/src/modules/wds/workflows/5-design-system/assessment/03-calculate-similarity.md +++ b/src/modules/wds/workflows/5-design-system/assessment/03-calculate-similarity.md @@ -11,7 +11,9 @@ ## Similarity Levels ### Level 1: Identical (95-100%) + **Characteristics:** + - All visual attributes match - Same functional purpose - Same behavioral patterns @@ -24,7 +26,9 @@ --- ### Level 2: Very High Similarity (80-94%) + **Characteristics:** + - Visual attributes mostly match - Same core function - Minor behavioral differences @@ -37,7 +41,9 @@ --- ### Level 3: High Similarity (65-79%) + **Characteristics:** + - Visual attributes similar - Related functional purpose - Some behavioral differences @@ -50,7 +56,9 @@ --- ### Level 4: Medium Similarity (45-64%) + **Characteristics:** + - Some visual overlap - Different functional purpose - Different behaviors @@ -63,7 +71,9 @@ --- ### Level 5: Low Similarity (20-44%) + **Characteristics:** + - Minimal visual overlap - Different function - Different behaviors @@ -76,7 +86,9 @@ --- ### Level 6: No Similarity (<20%) + **Characteristics:** + - No meaningful overlap - Completely different purpose - Unrelated patterns @@ -107,9 +119,10 @@ Calculate overall similarity: 4. Convert to percentage: - Similarity % = Overall × 100 - + **Example:** + ``` Dimension Scores: - Visual: High (1.0) @@ -137,13 +150,14 @@ Apply calculation logic to comparison data ``` 📊 Similarity Calculation -Visual: High (1.0) × 30% = 0.30 -Functional: Medium (0.6) × 30% = 0.18 -Behavioral: Medium (0.6) × 25% = 0.15 -Contextual: Medium (0.6) × 15% = 0.09 +Visual: High (1.0) × 30% = 0.30 +Functional: Medium (0.6) × 30% = 0.18 +Behavioral: Medium (0.6) × 25% = 0.15 +Contextual: Medium (0.6) × 15% = 0.09 Overall Similarity: 72% Level: High Similarity (Level 3) + ``` @@ -157,15 +171,18 @@ Map percentage to similarity level ``` + **Similarity Level: High (72%)** This component is similar to Button [btn-001] but has some differences. Could be: + - A variant of the existing button - A new related button component Designer decision needed. + ``` @@ -179,45 +196,57 @@ Based on similarity level, generate recommendation with reasoning **For Level 1-2 (Identical/Very High):** ``` + ✅ Recommendation: Reuse existing component Reasoning: + - Components are nearly identical - Only content/labels differ - Same visual and behavioral patterns - Maintaining consistency is straightforward + ``` **For Level 3 (High):** ``` + 🤔 Recommendation: Designer decision needed This could go either way: + - Similar enough to be a variant - Different enough to be separate I'll present the trade-offs so you can decide. + ``` **For Level 4-5 (Medium/Low):** ``` + 🆕 Recommendation: Create new component Reasoning: + - Significant functional differences - Different usage contexts - Trying to merge would create complexity - Better to keep separate + ``` **For Level 6 (No similarity):** ``` + ✅ Recommendation: Definitely create new component Reasoning: + - Components are fundamentally different - No meaningful overlap - No benefit to linking them + ``` --- @@ -230,6 +259,7 @@ Highlight the most important differences that affect the decision **Example:** ``` + 🔑 Key Decision Factors: 1. **Icon presence** - Current has icon, existing doesn't @@ -242,6 +272,7 @@ Highlight the most important differences that affect the decision Impact: Semantic meaning, developer understanding These differences will affect your decision. + ``` --- @@ -263,15 +294,18 @@ Pass classification and recommendation to opportunity identification: **Borderline cases (near threshold):** ``` + ⚠️ Borderline Case: 64% similarity This is right on the edge between "High" and "Medium" similarity. I'll present both perspectives so you can make an informed decision. + ``` **Multiple candidates with similar scores:** ``` + 📊 Multiple Similar Candidates: Button [btn-001]: 72% similarity @@ -279,19 +313,23 @@ Button [btn-003]: 68% similarity btn-001 is slightly closer, but both are viable options. I'll compare to btn-001 for the decision. + ``` **Perfect match but different context:** ``` + ⚠️ Unusual Pattern: 98% similarity but different context Visually and behaviorally identical, but used in completely different contexts. This might indicate: + - Same component, different use case ✓ - Accidental duplication ⚠️ - Context-specific variant needed 🤔 -``` + +```` --- @@ -312,7 +350,7 @@ This might indicate: ] } } -``` +```` --- diff --git a/src/modules/wds/workflows/5-design-system/assessment/04-identify-opportunities.md b/src/modules/wds/workflows/5-design-system/assessment/04-identify-opportunities.md index d84fd400..f97e045b 100644 --- a/src/modules/wds/workflows/5-design-system/assessment/04-identify-opportunities.md +++ b/src/modules/wds/workflows/5-design-system/assessment/04-identify-opportunities.md @@ -13,12 +13,15 @@ For each similar component, there are 3 options: ### Option 1: Reuse Existing Component + Use the existing component reference, just change content ### Option 2: Add Variant to Existing + Extend existing component with new variant ### Option 3: Create New Component + Create separate component in design system --- @@ -30,24 +33,28 @@ Create separate component in design system **Potential Opportunities:** #### Consistency + - ✅ Visual consistency across pages - ✅ Behavioral consistency (same interactions) - ✅ User familiarity (looks/works the same) - ✅ Brand coherence #### Maintenance + - ✅ Single source of truth - ✅ Update once, applies everywhere - ✅ Easier to maintain - ✅ Fewer files to manage #### Development + - ✅ Faster development (component exists) - ✅ Less code duplication - ✅ Easier testing (test once) - ✅ Better performance (reused code) #### Design System + - ✅ Cleaner design system - ✅ Fewer components to document - ✅ Easier for developers to find @@ -60,24 +67,28 @@ Create separate component in design system **Potential Opportunities:** #### Flexibility + - ✅ Accommodates different use cases - ✅ Maintains component family - ✅ Allows contextual adaptation - ✅ Supports design evolution #### Consistency + - ✅ Related components stay connected - ✅ Shared base styling - ✅ Consistent naming pattern - ✅ Clear component relationships #### Scalability + - ✅ Easy to add more variants later - ✅ Supports design system growth - ✅ Handles edge cases gracefully - ✅ Accommodates future needs #### Documentation + - ✅ Variants documented together - ✅ Clear component family - ✅ Easier to understand relationships @@ -90,24 +101,28 @@ Create separate component in design system **Potential Opportunities:** #### Clarity + - ✅ Clear separation of concerns - ✅ Distinct purpose/function - ✅ No confusion about usage - ✅ Semantic clarity #### Simplicity + - ✅ Simpler component definition - ✅ No complex variant logic - ✅ Easier to understand - ✅ Fewer edge cases #### Independence + - ✅ Can evolve independently - ✅ No impact on other components - ✅ Easier to modify - ✅ No unintended side effects #### Specificity + - ✅ Optimized for specific use case - ✅ No unnecessary features - ✅ Better performance @@ -122,6 +137,7 @@ Based on similarity level and comparison, identify which opportunities apply **Example (72% similarity):** + ``` Current Situation: - High visual similarity @@ -184,6 +200,7 @@ Based on comparison data, identify the most compelling opportunities for each op **Example:** + ``` 🌟 Strongest Opportunities: @@ -216,6 +233,7 @@ Factor in project-specific considerations: **Example:** + ``` 📋 Project Context: @@ -248,6 +266,7 @@ Pass opportunity analysis to risk identification: ## Edge Cases **All options have strong opportunities:** + ``` ✨ All Options Look Good! @@ -260,6 +279,7 @@ This means the risks will be the deciding factor. ``` **No clear opportunities:** + ``` ⚠️ No Strong Opportunities Identified @@ -271,6 +291,7 @@ I'll focus on risks to help clarify the decision. ``` **Conflicting opportunities:** + ``` ⚠️ Conflicting Opportunities @@ -287,6 +308,7 @@ Your design philosophy will guide this decision: ## Output Format **For next step:** + ```json { "opportunities": { diff --git a/src/modules/wds/workflows/5-design-system/assessment/05-identify-risks.md b/src/modules/wds/workflows/5-design-system/assessment/05-identify-risks.md index 2aed5d10..0b9cce46 100644 --- a/src/modules/wds/workflows/5-design-system/assessment/05-identify-risks.md +++ b/src/modules/wds/workflows/5-design-system/assessment/05-identify-risks.md @@ -15,24 +15,28 @@ **Potential Risks:** #### Loss of Distinction + - ❌ Different purposes look identical - ❌ Users can't distinguish actions - ❌ Semantic meaning lost - ❌ Accessibility issues (same label, different action) #### Constraint + - ❌ Forced to use existing styling - ❌ Can't optimize for specific use case - ❌ Future changes constrained - ❌ Design evolution limited #### Confusion + - ❌ Developers confused about usage - ❌ Same component, different behaviors - ❌ Unclear when to use - ❌ Documentation complexity #### Technical Debt + - ❌ Component becomes overloaded - ❌ Too many conditional behaviors - ❌ Hard to maintain @@ -45,24 +49,28 @@ **Potential Risks:** #### Complexity + - ❌ Component becomes complex - ❌ Many variants to manage - ❌ Harder to understand - ❌ More documentation needed #### Maintenance Burden + - ❌ Changes affect all variants - ❌ Testing becomes complex - ❌ More edge cases to handle - ❌ Harder to refactor #### Variant Explosion + - ❌ Too many variants over time - ❌ Unclear which variant to use - ❌ Variants become too specific - ❌ Component loses coherence #### Coupling + - ❌ Variants tightly coupled - ❌ Can't change one without affecting others - ❌ Shared code creates dependencies @@ -75,24 +83,28 @@ **Potential Risks:** #### Inconsistency + - ❌ Visual inconsistency across pages - ❌ Different styling for similar components - ❌ User confusion - ❌ Brand fragmentation #### Duplication + - ❌ Duplicate code - ❌ Duplicate maintenance - ❌ Duplicate testing - ❌ Duplicate documentation #### Proliferation + - ❌ Too many components in design system - ❌ Hard to find right component - ❌ Developers create more duplicates - ❌ Design system becomes unwieldy #### Divergence + - ❌ Components drift over time - ❌ Accidental inconsistencies - ❌ Harder to maintain coherence @@ -107,6 +119,7 @@ Based on similarity level and comparison, identify which risks apply **Example (72% similarity, different purposes):** + ``` Current Situation: - High visual similarity (90%) @@ -171,6 +184,7 @@ Rate each risk as Low/Medium/High severity based on: **Example:** + ``` Risk Severity Assessment: @@ -202,6 +216,7 @@ Highlight risks that would make an option unsuitable **Example:** + ``` 🚨 Deal-Breaker Risks: @@ -230,6 +245,7 @@ For each risk, identify if/how it can be mitigated **Example:** + ``` Risk Mitigation: @@ -268,6 +284,7 @@ Pass risk analysis to decision presentation: ## Edge Cases **All options have high risks:** + ``` ⚠️ All Options Have Significant Risks @@ -280,6 +297,7 @@ I'll present all trade-offs clearly so you can make an informed choice. ``` **No significant risks:** + ``` ✅ Low Risk Situation @@ -292,6 +310,7 @@ Focus on opportunities to decide. ``` **One option has deal-breaker risk:** + ``` 🚨 One Option Not Recommended @@ -305,6 +324,7 @@ I'll present Variant vs New as the viable options. ## Output Format **For next step:** + ```json { "risks": { diff --git a/src/modules/wds/workflows/5-design-system/assessment/06-present-decision.md b/src/modules/wds/workflows/5-design-system/assessment/06-present-decision.md index ad969c02..5a6093ad 100644 --- a/src/modules/wds/workflows/5-design-system/assessment/06-present-decision.md +++ b/src/modules/wds/workflows/5-design-system/assessment/06-present-decision.md @@ -11,18 +11,23 @@ ## Presentation Structure ### 1. Context Summary + What we're deciding and why ### 2. The Options + Clear description of each choice ### 3. Comparison Table + Side-by-side trade-offs ### 4. Recommendation + AI's suggestion based on analysis ### 5. Designer Choice + Let designer decide --- @@ -48,6 +53,7 @@ Let designer decide ✗ Different usage context **Decision:** How should we handle this in the design system? + ``` @@ -57,6 +63,7 @@ Let designer decide ``` + 📋 Your Options: **Option 1: Reuse Existing Component** @@ -64,11 +71,13 @@ Use Button [btn-001], just change the label to "Continue" **Option 2: Add Variant** Add "navigation" variant to Button [btn-001] + - Button.primary (submit) - Button.navigation (continue) **Option 3: Create New Component** Create separate "Navigation Button" component [btn-002] + ``` @@ -78,22 +87,24 @@ Create separate "Navigation Button" component [btn-002] ``` + 📊 Trade-Offs Comparison: ┌─────────────┬──────────────────┬──────────────────┬──────────────────┐ -│ │ Reuse [btn-001] │ Add Variant │ Create New │ +│ │ Reuse [btn-001] │ Add Variant │ Create New │ ├─────────────┼──────────────────┼──────────────────┼──────────────────┤ -│ Consistency │ ✅ Highest │ ✅ High │ ⚠️ Medium │ -│ Maintenance │ ✅ Easiest │ ⚠️ Moderate │ ❌ More work │ -│ Clarity │ ❌ Confusing │ ⚠️ Moderate │ ✅ Clearest │ -│ Flexibility │ ❌ Constrained │ ✅ Flexible │ ✅ Independent │ -│ Complexity │ ✅ Simple │ ⚠️ More complex │ ✅ Simple │ -│ Semantics │ ❌ Lost │ ⚠️ Preserved │ ✅ Clear │ +│ Consistency │ ✅ Highest │ ✅ High │ ⚠️ Medium │ +│ Maintenance │ ✅ Easiest │ ⚠️ Moderate │ ❌ More work │ +│ Clarity │ ❌ Confusing │ ⚠️ Moderate │ ✅ Clearest │ +│ Flexibility │ ❌ Constrained │ ✅ Flexible │ ✅ Independent │ +│ Complexity │ ✅ Simple │ ⚠️ More complex │ ✅ Simple │ +│ Semantics │ ❌ Lost │ ⚠️ Preserved │ ✅ Clear │ ├─────────────┼──────────────────┼──────────────────┼──────────────────┤ -│ Best For │ Identical use │ Related purposes │ Different roles │ +│ Best For │ Identical use │ Related purposes │ Different roles │ └─────────────┴──────────────────┴──────────────────┴──────────────────┘ Legend: ✅ Strong benefit | ⚠️ Trade-off | ❌ Potential issue + ``` @@ -103,6 +114,7 @@ Legend: ✅ Strong benefit | ⚠️ Trade-off | ❌ Potential issue ``` + 🔍 Detailed Analysis: **Option 1: Reuse Button [btn-001]** @@ -160,6 +172,7 @@ Risks: Mitigation: Shared design tokens ensure visual consistency Verdict: ✅ Safest option, especially for semantically different purposes + ``` @@ -173,6 +186,7 @@ Based on analysis, provide recommendation with reasoning ``` + 🤖 AI Recommendation: Create New Component (Option 3) **Reasoning:** @@ -197,8 +211,9 @@ Based on analysis, provide recommendation with reasoning - Better to establish clear patterns now - Easier to merge later than split -**However:** If you expect many button types (delete, cancel, save, etc.), +**However:** If you expect many button types (delete, cancel, save, etc.), Option 2 (variant) might be better for organization. + ``` @@ -208,23 +223,25 @@ Option 2 (variant) might be better for organization. ``` + 💭 Your Decision: Based on this analysis, which approach fits your design intent? [1] Reuse Button [btn-001] - → Choose if: Visual consistency is paramount, purposes are actually the same +→ Choose if: Visual consistency is paramount, purposes are actually the same [2] Add "navigation" variant to Button [btn-001] - → Choose if: You want button family, expect more button types +→ Choose if: You want button family, expect more button types [3] Create new "Navigation Button" [btn-002] - → Choose if: Semantic distinction matters, want independence +→ Choose if: Semantic distinction matters, want independence [4] I need more information - → I can clarify any aspect of the analysis +→ I can clarify any aspect of the analysis Your choice (1/2/3/4): + ``` @@ -238,30 +255,37 @@ Based on designer's choice, route to appropriate operation **If Choice 1 (Reuse):** ``` + ✅ Got it - reusing Button [btn-001] I'll update the page spec to reference the existing component. + ``` **Route to:** `07-execute-decision.md` with action: `reuse` **If Choice 2 (Variant):** ``` + ✅ Got it - adding "navigation" variant to Button [btn-001] I'll update the component definition and create the reference. + ``` **Route to:** `07-execute-decision.md` with action: `add_variant` **If Choice 3 (New):** ``` + ✅ Got it - creating new Navigation Button [btn-002] I'll create the new component and set up the reference. + ``` **Route to:** `07-execute-decision.md` with action: `create_new` **If Choice 4 (More Info):** ``` + 📚 What would you like to know more about? - Similarity calculation details @@ -271,6 +295,7 @@ I'll create the new component and set up the reference. - Something else Your question: + ``` **Provide clarification, then re-present decision** @@ -282,6 +307,7 @@ Your question: ``` + ✨ These components are very similar! Similarity: 87% @@ -291,6 +317,7 @@ or different things that happen to look similar? If same thing → Reuse If different things → Variant or New + ``` @@ -298,6 +325,7 @@ If different things → Variant or New ``` + ⚠️ These components are quite different. Similarity: 38% @@ -307,6 +335,7 @@ Creating a new component is likely the best choice. Would you like to proceed with creating a new component, or would you like to see the full analysis? + ``` @@ -314,6 +343,7 @@ or would you like to see the full analysis? ``` + 🤔 This is a borderline case. Similarity: 64% (right between "High" and "Medium") @@ -327,6 +357,7 @@ This could go either way. I'll present both perspectives: [Present new component option] Your design philosophy will guide this decision. + ``` @@ -336,19 +367,23 @@ Your design philosophy will guide this decision. **Designer asks for recommendation:** ``` + Based on the analysis, I recommend Option 3 (Create New). But this is your design system - you know your project best. What's most important to you? + - Consistency? → Reuse or Variant - Clarity? → New - Flexibility? → Variant - Simplicity? → Reuse or New + ``` **Designer is unsure:** ``` + That's okay! This is a judgment call. Here's a simple heuristic: @@ -359,21 +394,25 @@ B) "Related buttons, different purposes" → Variant C) "Different buttons entirely" → New What's your gut feeling? + ``` **Designer wants to defer decision:** ``` + ✅ No problem! I'll create it as a new component for now. You can always: + - Merge it later if you decide they're the same - Convert it to a variant if you see a pattern - Keep it separate if the distinction is valuable Design systems evolve - this isn't permanent. -``` + +```` --- @@ -389,7 +428,7 @@ Design systems evolve - this isn't permanent. "designer_notes": "Navigation and submission are different actions" } } -``` +```` --- diff --git a/src/modules/wds/workflows/5-design-system/assessment/07-execute-decision.md b/src/modules/wds/workflows/5-design-system/assessment/07-execute-decision.md index fe282f27..cef86d4b 100644 --- a/src/modules/wds/workflows/5-design-system/assessment/07-execute-decision.md +++ b/src/modules/wds/workflows/5-design-system/assessment/07-execute-decision.md @@ -11,12 +11,15 @@ ## Execution Paths ### Path A: Reuse Existing Component + Designer chose to use existing component as-is ### Path B: Add Variant + Designer chose to add variant to existing component ### Path C: Create New Component + Designer chose to create new component --- @@ -30,7 +33,8 @@ Designer chose to create new component ✅ Reusing Button [btn-001] I'll update your page spec to reference the existing component. -``` + +```` ### Step 2: Extract Page-Specific Content @@ -49,7 +53,7 @@ Page-Specific Content: - label: "Continue" - why: "Navigate to next step in onboarding" - context: "Multi-step form navigation" -``` +```` ### Step 3: Create Reference @@ -61,13 +65,14 @@ Create reference to existing component: **Output:** + ```yaml # C-Scenarios/onboarding-page.md Continue Button: component: Button.primary [btn-001] why: Navigate to next step in onboarding - label: "Continue" + label: 'Continue' ``` ### Step 4: Update Component Usage @@ -79,14 +84,15 @@ Update design system component to track usage: **Update:** + ```yaml # D-Design-System/components/button.md Used In: -- Login page (login button) -- Signup page (create account button) -- Dashboard (action buttons) -- Onboarding page (continue button) ← Added + - Login page (login button) + - Signup page (create account button) + - Dashboard (action buttons) + - Onboarding page (continue button) ← Added ``` ### Step 5: Complete @@ -97,6 +103,7 @@ Used In: Page spec updated with reference. Component usage tracked. + ``` @@ -110,10 +117,12 @@ Component usage tracked. ``` + ✅ Adding "navigation" variant to Button [btn-001] I'll update the component definition and create the reference. -``` + +```` ### Step 2: Extract Component-Level Info @@ -131,7 +140,7 @@ Navigation Variant: - icon: arrow-right - loading_state: true - hover_animation: icon_shift -``` +```` ### Step 3: Update Component Definition @@ -143,19 +152,19 @@ Add variant to existing component: **Update:** + ```yaml # D-Design-System/components/button.md Button Component [btn-001]: - variants: - primary (submit actions) - secondary (cancel actions) - navigation (continue/next actions) ← Added - + shared_states: - default, hover, active, disabled - + variant_specific: navigation: icon: arrow-right @@ -170,13 +179,14 @@ Create reference with variant specified: **Output:** + ```yaml # C-Scenarios/onboarding-page.md Continue Button: component: Button.navigation [btn-001] ← Variant specified why: Navigate to next step in onboarding - label: "Continue" + label: 'Continue' ``` ### Step 5: Update Usage Tracking @@ -186,6 +196,7 @@ Track variant usage: **Update:** + ```yaml # D-Design-System/components/button.md @@ -204,6 +215,7 @@ Variant Usage: Component definition updated. Page spec created with variant reference. Variant usage tracked. + ``` @@ -217,9 +229,11 @@ Variant usage tracked. ``` + ✅ Creating new Navigation Button [btn-002] I'll create the component definition and set up the reference. + ``` @@ -234,9 +248,11 @@ Generate unique component ID: **Example:** ``` + Existing Button IDs: btn-001 New ID: btn-002 -``` + +```` ### Step 3: Extract Component-Level Info @@ -259,7 +275,7 @@ Component-Level Info: color: blue shape: rounded hover_animation: icon_shift -``` +```` ### Step 4: Create Component File @@ -270,6 +286,7 @@ Create new component file using template: **Route to:** `operations/create-new-component.md` **Output:** + ```yaml # D-Design-System/components/navigation-button.md @@ -305,13 +322,14 @@ Create reference in page spec: **Output:** + ```yaml # C-Scenarios/onboarding-page.md Continue Button: component: NavigationButton [btn-002] why: Navigate to next step in onboarding - label: "Continue" + label: 'Continue' ``` ### Step 6: Update Design System Index @@ -321,14 +339,15 @@ Add to design system component list: **Update:** + ```yaml # D-Design-System/components/README.md Components: -- Button [btn-001] - Primary action buttons -- Input Field [inp-001] - Text input fields -- Card [crd-001] - Content cards -- Navigation Button [btn-002] - Navigation actions ← Added + - Button [btn-001] - Primary action buttons + - Input Field [inp-001] - Text input fields + - Card [crd-001] - Content cards + - Navigation Button [btn-002] - Navigation actions ← Added ``` ### Step 7: Complete @@ -340,7 +359,8 @@ Components: Component file created: D-Design-System/components/navigation-button.md Page spec created with reference. Design system index updated. -``` + +```` **Return to Phase 4** @@ -366,7 +386,7 @@ Update project tracking: - Reason: Semantic distinction from submit buttons - Decision: Create new vs variant - Designer: Chose clarity over consistency -``` +```` ### Notify Designer @@ -377,8 +397,9 @@ Update project tracking: Components: 4 (was 3) Latest: Navigation Button [btn-002] -Your design system is growing! Consider reviewing component +Your design system is growing! Consider reviewing component organization when you reach 10+ components. + ``` @@ -388,35 +409,42 @@ organization when you reach 10+ components. **If component creation fails:** ``` + ❌ Error creating component file. Error: [error message] Would you like to: + 1. Retry 2. Create manually 3. Skip design system for this component Your choice: + ``` **If reference creation fails:** ``` + ❌ Error updating page spec. Error: [error message] Component was created successfully, but page reference failed. I'll keep the complete spec on the page for now. + ``` **If ID conflict:** ``` + ⚠️ Component ID conflict detected. btn-002 already exists but with different content. Generating alternative ID: btn-003 + ``` --- @@ -436,13 +464,16 @@ Validate execution: **If validation fails:** ``` + ⚠️ Validation Warning: Some steps may not have completed successfully. Please review: + - [List of potential issues] Continue anyway? (y/n) + ``` --- @@ -467,6 +498,7 @@ Return control to Phase 4 orchestration: ``` + ✅ Design System Operation Complete Action: Created new component @@ -475,14 +507,17 @@ Page: Onboarding page Reference: NavigationButton [btn-002] Files Updated: + - D-Design-System/components/navigation-button.md (created) - C-Scenarios/onboarding-page.md (reference added) - D-Design-System/components/README.md (index updated) Next: Continue with next component in Phase 4 + ``` --- **This completes the assessment and execution flow. Control returns to Phase 4.** +``` diff --git a/src/modules/wds/workflows/5-design-system/design-system-router.md b/src/modules/wds/workflows/5-design-system/design-system-router.md index d9c50d3a..0c4d6967 100644 --- a/src/modules/wds/workflows/5-design-system/design-system-router.md +++ b/src/modules/wds/workflows/5-design-system/design-system-router.md @@ -9,13 +9,15 @@ ## When This Runs **Triggered from Phase 4:** + - After component specification is complete - Only if design system is enabled in project - Before returning to page specification **Input:** Complete component specification (mixed content) -**Output:** +**Output:** + - Design system entry (component-level info) - Page specification reference (page-specific info) @@ -138,6 +140,7 @@ Check if design system folder exists: 🎉 This is your first design system component! I'll initialize the design system structure and add this component. + ``` **Route to:** `operations/initialize-design-system.md` @@ -146,7 +149,9 @@ I'll initialize the design system structure and add this component. **If not first:** ``` + 📊 Checking existing design system for similar components... + ``` **Continue to Step 3** @@ -166,10 +171,13 @@ Scan design system folder: **Existing components found:** ``` + Found 3 existing components: + - Button [btn-001] - Input Field [inp-001] - Card [crd-001] + ``` **Continue to Step 4** @@ -178,7 +186,9 @@ Found 3 existing components: **No similar components:** ``` + No similar components found in design system. + ``` **Route to:** `operations/create-new-component.md` @@ -198,9 +208,11 @@ Compare current component to existing: **Type match found:** ``` + 🔍 Found existing Button component [btn-001] Checking similarity... + ``` **Route to:** `assessment/01-scan-existing.md` @@ -209,8 +221,10 @@ Checking similarity... **No type match:** ``` + This is a new component type: [ComponentType] -``` + +```` **Route to:** `operations/create-new-component.md` @@ -255,24 +269,26 @@ Login Button: states: [default, hover, disabled] variants: [primary, secondary] styling: {...} -``` +```` **Output (Page Spec with Reference):** + ```yaml Login Button: component: Button.primary [btn-001] why: Submit login credentials - label: "Log in" - error_text: "Invalid credentials" + label: 'Log in' + error_text: 'Invalid credentials' ``` **Output (Design System Entry):** + ```yaml # D-Design-System/components/button.md Button Component [btn-001]: states: [default, hover, disabled] variants: [primary, secondary] - styling: {...} + styling: { ... } ``` --- @@ -280,6 +296,7 @@ Button Component [btn-001]: ## Router Characteristics **✅ Does:** + - Check design system status - Identify first component - Scan existing components @@ -287,6 +304,7 @@ Button Component [btn-001]: - Route to appropriate operation **❌ Doesn't:** + - Make design decisions - Contain specification logic - Store component knowledge @@ -300,12 +318,14 @@ Button Component [btn-001]: ## Error Handling **If design system folder missing but config says enabled:** + ``` ⚠️ Design system is enabled but folder doesn't exist. Treating this as first component and initializing. ``` **If component type unclear:** + ``` ❓ I'm not sure what type of component this is. @@ -321,6 +341,7 @@ Your choice: ``` **If similarity check fails:** + ``` ⚠️ I couldn't determine similarity automatically. @@ -337,6 +358,7 @@ Your choice: ## Next Steps **After routing:** + - Follow the routed operation instructions - Complete design system entry - Return reference to Phase 4 diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/figma-designer-guide.md b/src/modules/wds/workflows/5-design-system/figma-integration/figma-designer-guide.md index 320397f8..feb9e836 100644 --- a/src/modules/wds/workflows/5-design-system/figma-integration/figma-designer-guide.md +++ b/src/modules/wds/workflows/5-design-system/figma-integration/figma-designer-guide.md @@ -22,6 +22,7 @@ ### Create Design System File **File structure:** + ``` [Project Name] Design System ├── 📄 Cover @@ -39,6 +40,7 @@ ``` **Tips:** + - Use clear page names - Organize by component type - Keep foundation separate @@ -51,6 +53,7 @@ **Create Figma variables:** **Colors:** + ``` Collection: Colors ├── primary/50 @@ -63,6 +66,7 @@ Collection: Colors ``` **Spacing:** + ``` Collection: Spacing ├── spacing/1 = 4px @@ -73,6 +77,7 @@ Collection: Spacing ``` **Typography:** + ``` Styles: Typography ├── Display/Large @@ -89,6 +94,7 @@ Styles: Typography ### Example: Button Component **1. Create Base Frame** + ``` Frame name: Button/Primary [btn-001] Size: Hug contents (width), Fixed 44px (height) @@ -98,6 +104,7 @@ Gap: 8px ``` **2. Add Content** + ``` ├── Icon (optional) │ └── Size: 20x20px @@ -107,6 +114,7 @@ Gap: 8px ``` **3. Apply Design Tokens** + ``` Background: primary/600 (variable) Text Color: white (variable) @@ -114,6 +122,7 @@ Border Radius: 8px ``` **4. Create Component** + ``` Select frame → Create Component Name: Button/Primary [btn-001] @@ -124,6 +133,7 @@ Name: Button/Primary [btn-001] ### Add Component Description **In component description field:** + ``` Button Primary [btn-001] @@ -158,16 +168,19 @@ Primary action button for main user actions. **Select component → Add variant property:** **Property 1: Type** + ``` Values: Primary, Secondary, Ghost, Outline ``` **Property 2: Size** + ``` Values: Small, Medium, Large ``` **Property 3: State** + ``` Values: Default, Hover, Active, Disabled, Loading ``` @@ -177,6 +190,7 @@ Values: Default, Hover, Active, Disabled, Loading ### Design Each Variant **Type=Primary, Size=Medium, State=Default:** + ``` Background: primary/600 Text: white @@ -184,6 +198,7 @@ Padding: 16px × 12px ``` **Type=Primary, Size=Medium, State=Hover:** + ``` Background: primary/700 (darker) Text: white @@ -191,6 +206,7 @@ Scale: 1.02 (slightly larger) ``` **Type=Primary, Size=Medium, State=Active:** + ``` Background: primary/800 (darkest) Text: white @@ -198,6 +214,7 @@ Scale: 0.98 (slightly smaller) ``` **Type=Primary, Size=Medium, State=Disabled:** + ``` Background: gray/300 Text: gray/500 @@ -206,6 +223,7 @@ Cursor: not-allowed ``` **Type=Primary, Size=Medium, State=Loading:** + ``` Background: primary/600 Text: white @@ -218,6 +236,7 @@ Opacity: 0.8 ### Adjust for Sizes **Small:** + ``` Padding: 12px × 8px Text: Body/Small @@ -226,6 +245,7 @@ Height: 36px ``` **Medium (default):** + ``` Padding: 16px × 12px Text: Body/Medium @@ -234,6 +254,7 @@ Height: 44px ``` **Large:** + ``` Padding: 20px × 16px Text: Body/Large @@ -248,6 +269,7 @@ Height: 52px ### Visual State Indicators **Create a documentation frame:** + ``` Frame: Button States Documentation ├── Default @@ -263,6 +285,7 @@ Frame: Button States Documentation ``` **Add annotations:** + - State name - Visual changes - Interaction behavior @@ -279,6 +302,7 @@ Frame: Button States Documentation **2. Right-click → "Copy link to selection"** **3. Extract node ID from URL:** + ``` URL: https://www.figma.com/file/abc123/Design-System?node-id=456:789 @@ -289,6 +313,7 @@ Full reference: figma://file/abc123/node/456:789 ``` **4. Add to WDS mapping file:** + ```yaml # D-Design-System/figma-mappings.md Button [btn-001] → figma://file/abc123/node/456:789 @@ -303,16 +328,19 @@ Button [btn-001] → figma://file/abc123/node/456:789 **1. Create component in Figma** (steps above) **2. Notify WDS system:** + - Add component ID to Figma description - Copy Figma node ID - Update `figma-mappings.md` **3. Generate WDS specification:** + - Use Figma MCP to read component - Generate component specification - Review and confirm **4. Verify sync:** + - Check WDS component file created - Verify all variants captured - Confirm states documented @@ -327,18 +355,21 @@ Button [btn-001] → figma://file/abc123/node/456:789 **1. Create/update component in Figma** **2. Run MCP sync command:** + ```bash # In WDS project wds figma sync Button/Primary ``` **3. MCP will:** + - Read component from Figma - Extract variants and states - Generate WDS specification - Update figma-mappings.md **4. Review generated spec:** + - Check accuracy - Add missing details - Confirm and commit @@ -352,16 +383,19 @@ wds figma sync Button/Primary **When updating a component:** **1. Update in Figma:** + - Modify component - Update description if needed - Maintain component ID **2. Sync to WDS:** + - Run MCP sync (if available) - Or manually update WDS spec - Update version history **3. Notify team:** + - Document changes - Update affected pages - Test implementations @@ -373,11 +407,13 @@ wds figma sync Button/Primary **Track component changes:** **In Figma:** + - Use Figma version history - Add version notes - Tag major changes **In WDS:** + ```markdown ## Version History @@ -385,6 +421,7 @@ wds figma sync Button/Primary **Last Updated:** 2024-12-15 **Changes:** + - 2024-12-09: Created component - 2024-12-12: Added loading state - 2024-12-15: Updated hover animation @@ -397,26 +434,31 @@ wds figma sync Button/Primary ### DO ✅ **1. Use Design Tokens** + - Always use variables for colors - Use variables for spacing - Apply text styles consistently **2. Document Thoroughly** + - Clear component descriptions - Usage guidelines - Accessibility notes **3. Maintain Consistency** + - Follow naming conventions - Use consistent spacing - Apply standard states **4. Test Instances** + - Create example instances - Test all variants - Verify responsive behavior **5. Keep Organized** + - Logical component grouping - Clear page structure - Clean component hierarchy @@ -426,26 +468,31 @@ wds figma sync Button/Primary ### DON'T ❌ **1. Hardcode Values** + - Don't use hex colors directly - Don't use pixel values without variables - Don't skip design tokens **2. Detach Instances** + - Don't break component connections - Don't create one-off variations - Don't lose main component link **3. Skip Documentation** + - Don't leave descriptions empty - Don't forget WDS component ID - Don't skip usage guidelines **4. Ignore States** + - Don't create only default state - Don't forget hover/active - Don't skip disabled state **5. Break Naming Conventions** + - Don't use inconsistent names - Don't forget component IDs - Don't use unclear abbreviations @@ -457,26 +504,31 @@ wds figma sync Button/Primary ### Creating a New Component Type **1. Research:** + - Check if similar component exists - Review WDS component boundaries guide - Decide: new component or variant? **2. Design:** + - Create base component - Add all required states - Apply design tokens **3. Document:** + - Write clear description - Add WDS component ID - Document usage guidelines **4. Sync:** + - Get Figma node ID - Update WDS mappings - Generate specification **5. Test:** + - Create example instances - Test all variants - Verify responsive behavior @@ -486,21 +538,25 @@ wds figma sync Button/Primary ### Adding a Variant to Existing Component **1. Assess:** + - Is this truly a variant? - Or should it be a new component? - Check with WDS assessment flow **2. Add Variant:** + - Add new variant property value - Design variant appearance - Document differences **3. Update Documentation:** + - Update component description - Add variant to list - Document when to use **4. Sync:** + - Update WDS specification - Add variant to component file - Update version history @@ -510,21 +566,25 @@ wds figma sync Button/Primary ### Updating Component Styling **1. Plan Change:** + - Document what's changing - Check impact on instances - Notify team **2. Update Component:** + - Modify main component - Test all variants - Verify instances update **3. Sync to WDS:** + - Update WDS specification - Document changes - Update version history **4. Verify:** + - Check all instances - Test in examples - Confirm with team @@ -538,6 +598,7 @@ wds figma sync Button/Primary **Problem:** MCP can't read component **Solutions:** + - Check component name format - Verify WDS component ID in description - Ensure component is published @@ -550,6 +611,7 @@ wds figma sync Button/Primary **Problem:** Some variants missing in WDS **Solutions:** + - Check variant property names - Verify all combinations exist - Ensure consistent naming @@ -562,6 +624,7 @@ wds figma sync Button/Primary **Problem:** Hardcoded values instead of variables **Solutions:** + - Replace hex colors with variables - Use spacing variables - Apply text styles @@ -574,6 +637,7 @@ wds figma sync Button/Primary **Problem:** Updates break instance overrides **Solutions:** + - Don't change component structure - Add new properties instead - Maintain backward compatibility diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/figma-mcp-integration.md b/src/modules/wds/workflows/5-design-system/figma-integration/figma-mcp-integration.md index bde13b4e..9b8b487e 100644 --- a/src/modules/wds/workflows/5-design-system/figma-integration/figma-mcp-integration.md +++ b/src/modules/wds/workflows/5-design-system/figma-integration/figma-mcp-integration.md @@ -9,6 +9,7 @@ ## Overview **Figma MCP enables:** + - Reading component specifications from Figma - Extracting design tokens - Generating WDS component specifications @@ -46,6 +47,7 @@ ``` **Get Figma API token:** + 1. Go to Figma → Settings → Account 2. Scroll to "Personal access tokens" 3. Click "Generate new token" @@ -60,17 +62,20 @@ **Purpose:** Extract component data from Figma **Input:** + - Figma file ID - Node ID - Or component name **Output:** + - Component structure - Variants - Properties - Design tokens used **Example:** + ``` Agent: Read Figma component Button/Primary @@ -106,15 +111,18 @@ MCP Response: **Purpose:** Get design token values from Figma **Input:** + - Figma file ID - Token type (colors, typography, spacing) **Output:** + - Token definitions - Token values - Token mappings **Example:** + ``` Agent: Extract color tokens from Figma @@ -136,14 +144,17 @@ MCP Response: **Purpose:** Find Figma node ID for component **Input:** + - Component name or WDS component ID **Output:** + - Figma node ID - File ID - Full Figma URL **Example:** + ``` Agent: Get node ID for Button [btn-001] @@ -163,15 +174,18 @@ MCP Response: **Purpose:** Get all components in Figma file **Input:** + - Figma file ID - Optional: filter by type **Output:** + - List of components - Component names - Node IDs **Example:** + ``` Agent: List all button components @@ -203,6 +217,7 @@ MCP Response: **Process:** **Step 1: Detect Change** + ``` Designer updates Button/Primary in Figma Designer notifies WDS system @@ -210,6 +225,7 @@ Or: Automated webhook triggers sync ``` **Step 2: Read Component** + ``` Agent: Read Figma component Button/Primary [btn-001] @@ -223,6 +239,7 @@ MCP reads: ``` **Step 3: Parse Component Data** + ``` Agent extracts: - Component type: Button @@ -234,6 +251,7 @@ Agent extracts: ``` **Step 4: Generate WDS Specification** + ``` Agent creates/updates: D-Design-System/components/button.md @@ -248,6 +266,7 @@ Filling in: ``` **Step 5: Update Mappings** + ``` Agent updates: D-Design-System/figma-mappings.md @@ -257,6 +276,7 @@ Button [btn-001] → figma://file/abc123/node/456:789 ``` **Step 6: Verify and Confirm** + ``` Agent presents generated spec to designer Designer reviews and confirms @@ -272,18 +292,21 @@ Spec is committed to repository **Process:** **Step 1: Detect Change** + ``` WDS specification updated Git commit triggers notification ``` **Step 2: Identify Figma Component** + ``` Agent reads figma-mappings.md Finds: Button [btn-001] → figma://file/abc123/node/456:789 ``` **Step 3: Notify Designer** + ``` Agent creates notification: "Button [btn-001] specification updated in WDS. @@ -298,6 +321,7 @@ Figma component: [Link to Figma]" ``` **Step 4: Designer Updates Figma** + ``` Designer reviews changes Updates Figma component @@ -315,6 +339,7 @@ Confirms sync complete **Agent uses component template:** **Input:** + ``` Figma component data: { @@ -331,6 +356,7 @@ Figma component data: **Output:** `D-Design-System/components/button.md` **Process:** + 1. Load component template 2. Fill in component name and ID 3. Extract and format variants @@ -349,6 +375,7 @@ Figma component data: **Figma variables → WDS tokens:** **Agent maps:** + ``` Figma: primary/600 → WDS: color-primary-600 Figma: spacing/4 → WDS: spacing-4 @@ -357,6 +384,7 @@ Figma: shadow/sm → WDS: shadow-sm ``` **Mapping rules:** + - Figma collection/variable → WDS category-name-value - Maintain semantic meaning - Consistent naming across systems @@ -371,6 +399,7 @@ Figma: shadow/sm → WDS: shadow-sm **Error:** Figma component doesn't exist **Agent response:** + ``` ⚠️ Component not found in Figma @@ -397,6 +426,7 @@ Actions: **Error:** Figma component has no WDS ID in description **Agent response:** + ``` ⚠️ WDS Component ID missing @@ -417,6 +447,7 @@ After adding ID, re-sync component. **Error:** Can't map Figma variable to WDS token **Agent response:** + ``` ⚠️ Token mapping failed @@ -438,6 +469,7 @@ Your choice: **Error:** Figma and WDS have different versions **Agent response:** + ``` ⚠️ Sync conflict detected @@ -466,6 +498,7 @@ Your choice: ### For AI Agents **DO ✅** + - Always check for WDS component ID in Figma - Verify token mappings before generating specs - Present generated specs for designer review @@ -473,6 +506,7 @@ Your choice: - Document sync operations in version history **DON'T ❌** + - Don't overwrite WDS specs without confirmation - Don't create components without designer approval - Don't skip token mapping validation @@ -484,6 +518,7 @@ Your choice: ### For Designers **DO ✅** + - Add WDS component ID to all Figma components - Use design tokens (variables) consistently - Document component changes @@ -491,6 +526,7 @@ Your choice: - Review generated specs before committing **DON'T ❌** + - Don't use hardcoded values - Don't skip component descriptions - Don't forget to sync after changes @@ -504,6 +540,7 @@ Your choice: ### Phase 4: UX Design **When component is specified in Phase 4:** + 1. Designer creates sketch 2. Agent specifies component 3. Design system router checks for similar components @@ -517,6 +554,7 @@ Your choice: ### Phase 5: Design System **When component is added to design system:** + 1. Component specification complete 2. Agent checks: Figma component exists? 3. If yes: @@ -532,30 +570,35 @@ Your choice: ## Command Reference ### Read Component + ``` Agent: Read Figma component [component-name] MCP: Returns component data ``` ### Extract Tokens + ``` Agent: Extract [token-type] tokens from Figma MCP: Returns token definitions ``` ### Get Node ID + ``` Agent: Get Figma node ID for [component-id] MCP: Returns node ID and URL ``` ### List Components + ``` Agent: List Figma components [optional: filter] MCP: Returns component list ``` ### Sync Component + ``` Agent: Sync Figma component [component-name] to WDS MCP: Reads component, generates spec, updates mappings @@ -568,6 +611,7 @@ MCP: Reads component, generates spec, updates mappings ### MCP Server Not Responding **Check:** + - MCP server is running - Figma API token is valid - Network connection is active @@ -580,6 +624,7 @@ MCP: Reads component, generates spec, updates mappings **Error:** 403 Forbidden **Solution:** + 1. Generate new Figma API token 2. Update MCP configuration 3. Restart MCP server @@ -592,6 +637,7 @@ MCP: Reads component, generates spec, updates mappings **Error:** 429 Too Many Requests **Solution:** + - Wait before retrying - Batch operations when possible - Cache component data @@ -602,6 +648,7 @@ MCP: Reads component, generates spec, updates mappings ## Future Enhancements **Planned features:** + - Automated sync on Figma changes (webhooks) - Bidirectional sync (WDS → Figma write) - Batch component import diff --git a/src/modules/wds/workflows/5-design-system/operations/add-variant.md b/src/modules/wds/workflows/5-design-system/operations/add-variant.md index 02e7f1a9..307f2345 100644 --- a/src/modules/wds/workflows/5-design-system/operations/add-variant.md +++ b/src/modules/wds/workflows/5-design-system/operations/add-variant.md @@ -21,6 +21,7 @@ Read existing component file: **Example:** + ```yaml Component: Button [btn-001] Current Variants: @@ -34,7 +35,8 @@ Current Variants: Current variants: 2 (primary, secondary) Adding new variant: navigation -``` + +```` --- @@ -62,7 +64,7 @@ Different from existing: - Has loading state - Icon animation on hover - Purpose: navigation vs submission -``` +```` --- @@ -76,6 +78,7 @@ Generate descriptive variant name: **Examples:** + ``` Purpose-based: - navigation (for navigation actions) @@ -101,7 +104,8 @@ This variant is for navigation actions (continue, next, proceed). Is this name clear and appropriate? (y/n) Or suggest alternative name: -``` + +```` --- @@ -120,34 +124,39 @@ Add variant to component definition: - **primary** - Main call-to-action (submit, save, continue) - **secondary** - Secondary actions (cancel, back) -``` +```` **After:** + ```markdown ## Variants - **primary** - Main call-to-action (submit, save, continue) - **secondary** - Secondary actions (cancel, back) -- **navigation** - Navigation actions (next, proceed, continue) ← Added +- **navigation** - Navigation actions (next, proceed, continue) ← Added ``` ### Add Variant-Specific Styling **Add section:** + ```markdown ### Variant-Specific Styling **Primary:** + - Background: blue-600 - Icon: none - Loading: spinner only **Secondary:** + - Background: gray-200 - Text: gray-900 - Icon: none -**Navigation:** ← Added +**Navigation:** ← Added + - Background: blue-600 - Icon: arrow-right - Loading: spinner + icon @@ -157,10 +166,12 @@ Add variant to component definition: ### Update States (if variant has unique states) **If navigation variant has loading state but others don't:** + ```markdown ## States **Shared States (all variants):** + - default - hover - active @@ -169,6 +180,7 @@ Add variant to component definition: **Variant-Specific States:** **Navigation:** + - loading (shows spinner, disables interaction) ``` @@ -181,14 +193,16 @@ Track new variant usage: **Add to component file:** + ```markdown ## Variant Usage **Primary:** 5 pages **Secondary:** 3 pages -**Navigation:** 1 page ← Added +**Navigation:** 1 page ← Added **Navigation variant used in:** + - Onboarding page (continue button) ``` @@ -201,10 +215,12 @@ Add note about variant count: **If this is 3rd+ variant:** + ```markdown ## Notes This component now has 3 variants. Consider: + - Are all variants necessary? - Should any variants be separate components? - Is the component becoming too complex? @@ -221,6 +237,7 @@ Check for potential issues: **Variant Explosion Check:** + ``` ⚠️ Variant Count: 3 @@ -230,6 +247,7 @@ Recommended maximum: 5 variants per component ``` **Consistency Check:** + ``` ✓ New variant consistent with existing variants ✓ Naming convention followed @@ -237,6 +255,7 @@ Recommended maximum: 5 variants per component ``` **Complexity Check:** + ``` ⚠️ Navigation variant adds loading state not present in other variants. @@ -256,6 +275,7 @@ Track component changes: **Update version history:** + ```markdown ## Version History @@ -263,8 +283,9 @@ Track component changes: **Last Updated:** 2024-12-09 **Changes:** + - 2024-12-01: Created component with primary and secondary variants -- 2024-12-09: Added navigation variant ← Added +- 2024-12-09: Added navigation variant ← Added ``` --- @@ -276,6 +297,7 @@ Generate reference for page spec: **Output:** + ```yaml component_reference: id: btn-001 @@ -297,6 +319,7 @@ New Variant: navigation Total Variants: 3 (primary, secondary, navigation) Component file updated: + - Variant added to list - Variant-specific styling documented - Usage tracking added @@ -305,6 +328,7 @@ Component file updated: Reference ready for page spec. Next: Return to Phase 4 to complete page specification + ``` @@ -314,25 +338,30 @@ Next: Return to Phase 4 to complete page specification ``` + 💡 Variant Management Tips: **Current Status:** + - Component: Button [btn-001] - Variants: 3 - Status: Healthy **Watch for:** + - 5+ variants → Consider splitting component - Variants with very different purposes → Might need separate components - Variants rarely used together → Might indicate separate components **Best Practices:** + - Keep variants related (same base purpose) - Use clear, semantic variant names - Document when to use each variant - Review variant list periodically You can always refactor later if needed! + ``` @@ -356,9 +385,11 @@ Validate variant addition: **If variant name conflicts:** ``` + ⚠️ Variant "navigation" already exists in Button [btn-001]. This might mean: + 1. You're trying to add a duplicate 2. The existing variant should be updated 3. A different variant name is needed @@ -367,38 +398,46 @@ Current navigation variant: [Show existing variant details] Options: + 1. Update existing variant 2. Choose different name 3. Cancel Your choice: + ``` **If component file not found:** ``` + ❌ Error: Component file not found. Component ID: btn-001 Expected file: D-Design-System/components/button.md This shouldn't happen. Possible causes: + - File was deleted - Component ID is incorrect - Design system structure corrupted Would you like to: + 1. Create component as new 2. Specify correct component ID 3. Cancel Your choice: + ``` **If variant too different:** ``` + ⚠️ Warning: High Divergence Detected The new variant is very different from existing variants: + - Different core purpose - Different visual structure - Different behavioral patterns @@ -408,11 +447,13 @@ Similarity to existing variants: 35% This might be better as a separate component. Options: + 1. Add as variant anyway 2. Create as new component instead 3. Review differences in detail Your choice: + ``` --- @@ -425,6 +466,7 @@ After adding variant, check component health: **Component Health Check:** ``` + 📊 Component Health: Button [btn-001] Variants: 3 @@ -435,11 +477,14 @@ Usage: 9 pages Health Status: ✅ Healthy Recommendations: + - Document variant selection guidelines - Consider adding variant usage examples - Monitor for variant explosion + ``` --- **This operation adds a variant. Return to Phase 4 with component reference.** +``` diff --git a/src/modules/wds/workflows/5-design-system/operations/create-new-component.md b/src/modules/wds/workflows/5-design-system/operations/create-new-component.md index 23e11e1e..d54d24e1 100644 --- a/src/modules/wds/workflows/5-design-system/operations/create-new-component.md +++ b/src/modules/wds/workflows/5-design-system/operations/create-new-component.md @@ -21,6 +21,7 @@ Generate unique component ID: **Type Prefixes:** + ``` Button → btn Input Field → inp @@ -51,6 +52,7 @@ Spacer → spc ``` **Example:** + ``` Component Type: Button Existing Button IDs: btn-001, btn-002 @@ -78,6 +80,7 @@ Categorize component for organization: **Example:** + ``` Component: Button Category: Interactive @@ -91,6 +94,7 @@ Category: Interactive From complete specification, extract component-level info: **Visual Attributes:** + - Size (small, medium, large) - Shape (rounded, square, pill) - Color scheme @@ -99,6 +103,7 @@ From complete specification, extract component-level info: - Border style **Behavioral Attributes:** + - States (default, hover, active, disabled, loading, error) - Interactions (click, hover, focus, blur) - Animations/transitions @@ -106,17 +111,19 @@ From complete specification, extract component-level info: - Accessibility attributes **Functional Attributes:** + - Purpose/role - Input/output type - Validation rules - Required/optional **Design System Attributes:** + - Variants (if any) - Design tokens used - Figma reference (if Mode B) - Library component (if Mode C) - + --- @@ -130,7 +137,7 @@ Use component template to create file: **Template Structure:** -```markdown +````markdown # [Component Name] [component-id] **Type:** [Interactive/Form/Layout/Content/Feedback/Navigation] @@ -150,6 +157,7 @@ Use component template to create file: [If component has variants, list them] **Example:** + - primary - Main call-to-action - secondary - Secondary actions - ghost - Subtle actions @@ -162,12 +170,14 @@ This component has no variants. ## States **Required States:** + - default - hover - active - disabled **Optional States:** + - loading - error - success @@ -191,24 +201,26 @@ This component has no variants. ### Design Tokens [If using design tokens:] + ```yaml colors: background: primary-500 text: white border: primary-600 - + typography: font-size: text-base font-weight: semibold - + spacing: padding-x: 4 padding-y: 2 - + effects: border-radius: md shadow: sm ``` +```` ### Figma Reference @@ -245,6 +257,7 @@ effects: ### Animations [If component has animations:] + - [Animation description] - Duration: [ms] - Easing: [easing function] @@ -254,12 +267,14 @@ effects: ## Accessibility **ARIA Attributes:** + - role: [role] - aria-label: [label] - aria-disabled: [when disabled] - [Other ARIA attributes] **Keyboard Support:** + - Enter/Space: [action] - Tab: [navigation] - [Other keyboard support] @@ -294,6 +309,7 @@ effects: **Usage Count:** [Number] **Examples:** + - [Page name] - [Specific usage] - [Page name] - [Specific usage] @@ -302,6 +318,7 @@ effects: ## Related Components [If this component is related to others:] + - [Related component 1] - [Relationship] - [Related component 2] - [Relationship] @@ -313,6 +330,7 @@ effects: **Last Updated:** [Date] **Changes:** + - [Date]: Created component - [Date]: [Change description] @@ -321,7 +339,8 @@ effects: ## Notes [Any additional notes, considerations, or future plans] -``` + +```` --- @@ -385,7 +404,7 @@ Use buttons for important actions that change state or navigate to new content. **Size:** medium (h-10, px-4) **Shape:** rounded (border-radius: 0.375rem) -**Colors:** +**Colors:** - Background: blue-600 - Text: white - Border: none @@ -409,21 +428,21 @@ colors: hover: blue-700 active: blue-800 text: white - + typography: size: text-sm weight: semibold - + spacing: padding-x: 4 padding-y: 2 gap: 2 - + effects: border-radius: md shadow: sm transition: all 150ms ease -``` +```` ### Library Component @@ -441,26 +460,31 @@ effects: Triggers associated action (form submit, navigation, etc.) **Hover:** + - Background darkens - Slight scale increase (1.02) - Cursor changes to pointer **Focus:** + - Blue outline ring - Maintains hover state **Keyboard:** + - Enter/Space triggers click - Tab navigates to/from button ### Animations **Hover Scale:** + - Duration: 150ms - Easing: ease-in-out - Scale: 1.02 **Click Feedback:** + - Duration: 100ms - Scale: 0.98 @@ -469,12 +493,14 @@ Triggers associated action (form submit, navigation, etc.) ## Accessibility **ARIA Attributes:** + - role: button - aria-label: [Descriptive label if icon-only] - aria-disabled: true [when disabled] - aria-busy: true [when loading] **Keyboard Support:** + - Enter/Space: Triggers button action - Tab: Moves focus to/from button @@ -515,6 +541,7 @@ Announces button label and state (disabled, busy, etc.) **Usage Count:** 1 **Examples:** + - Login page - Submit credentials button --- @@ -532,6 +559,7 @@ Announces button label and state (disabled, busy, etc.) **Last Updated:** 2024-12-09 **Changes:** + - 2024-12-09: Created component --- @@ -539,7 +567,8 @@ Announces button label and state (disabled, busy, etc.) ## Notes This is the primary button component. Consider adding more variants as needs emerge (danger, success, etc.). -``` + +```` --- @@ -560,7 +589,7 @@ Add component to index: - Button [btn-003] - Standard action button ← Added **Total Interactive:** 3 -``` +```` --- @@ -587,6 +616,7 @@ Generate reference for page spec: **Output:** + ```yaml component_reference: id: btn-003 @@ -613,6 +643,7 @@ Design system stats updated. Reference ready for page spec. Next: Return to Phase 4 to complete page specification + ``` @@ -636,36 +667,45 @@ Validate component creation: **If ID conflict:** ``` + ⚠️ Component ID btn-003 already exists. Generating alternative ID: btn-004 + ``` **If file creation fails:** ``` + ❌ Error creating component file. Error: [error message] Would you like to: + 1. Retry 2. Create with different ID 3. Skip design system for this component Your choice: + ``` **If template population incomplete:** ``` + ⚠️ Some component information is missing. Missing: + - [List of missing fields] I'll create the component with placeholders. You can fill in details later. + ``` --- **This operation creates a new component. Return to Phase 4 with component reference.** +``` diff --git a/src/modules/wds/workflows/5-design-system/operations/generate-catalog.md b/src/modules/wds/workflows/5-design-system/operations/generate-catalog.md index 56e3f47f..98b74f41 100644 --- a/src/modules/wds/workflows/5-design-system/operations/generate-catalog.md +++ b/src/modules/wds/workflows/5-design-system/operations/generate-catalog.md @@ -2,7 +2,8 @@ **Purpose:** Create/update the interactive HTML catalog that showcases all design system components with live examples. -**When to run:** +**When to run:** + - After initializing design system - After creating new component - After adding variant @@ -14,6 +15,7 @@ ## Overview The interactive catalog is a **living documentation** of the design system: + - Shows all components with live examples - Displays all variants and states - Includes design tokens @@ -26,12 +28,14 @@ The interactive catalog is a **living documentation** of the design system: ## Input **Design System Files:** + - `D-Design-System/components/*.md` - All component specifications - `D-Design-System/design-tokens.md` - Design token definitions - `D-Design-System/figma-mappings.md` - Figma references (if Mode B) - `D-Design-System/component-library-config.md` - Library config (if Mode C) **Project Config:** + - Project name - Design system mode - Version number @@ -42,9 +46,11 @@ The interactive catalog is a **living documentation** of the design system: ## Output **Generated File:** + - `D-Design-System/catalog.html` - Interactive HTML catalog **Features:** + - Fixed sidebar navigation - Live component previews - Interactive state toggles @@ -65,6 +71,7 @@ Load catalog template: **File:** `workflows/5-design-system/templates/catalog.template.html` **Template variables:** + ``` {{PROJECT_NAME}} {{PROJECT_ICON}} @@ -96,16 +103,18 @@ Extract project metadata: **From project config:** + ```yaml -project_name: "Dog Week" -project_icon: "🐕" -project_description: "Family dog care coordination platform" -design_system_mode: "custom" # or "library" or "none" -created_date: "2024-09-15" -version: "1.0.0" +project_name: 'Dog Week' +project_icon: '🐕' +project_description: 'Family dog care coordination platform' +design_system_mode: 'custom' # or "library" or "none" +created_date: '2024-09-15' +version: '1.0.0' ``` **Calculate:** + ``` component_count: Count files in D-Design-System/components/ last_updated: Current date/time @@ -120,6 +129,7 @@ Build component navigation from component files: **Scan components:** + ``` D-Design-System/components/ ├── button.md [btn-001] @@ -129,6 +139,7 @@ D-Design-System/components/ ``` **Group by category:** + ``` Interactive: - Button [btn-001] @@ -144,21 +155,22 @@ Display: ``` **Generate HTML:** + ```html ``` @@ -175,6 +187,7 @@ Read and format design tokens: **Load:** `D-Design-System/design-tokens.md` **Parse tokens:** + ```yaml Colors: primary-500: #3b82f6 @@ -193,42 +206,40 @@ Spacing: ``` **Generate color swatches:** + ```html
-

Primary Colors

-
-
-
-

primary-500

-

#3b82f6

-
-
-
-

primary-600

-

#2563eb

-
+

Primary Colors

+
+
+
+

primary-500

+

#3b82f6

+
+
+

primary-600

+

#2563eb

+
+
``` **Generate typography examples:** + ```html
-

Typography Scale

-
-
-

text-display (3.75rem)

-

- Display Text -

-
-
-

text-heading-1 (3rem)

-

- Heading 1 -

-
+

Typography Scale

+
+
+

text-display (3.75rem)

+

Display Text

+
+

text-heading-1 (3rem)

+

Heading 1

+
+
``` @@ -247,6 +258,7 @@ For each component, generate interactive showcase: ### Parse Component **Read component file:** + ```markdown # Button Component [btn-001] @@ -254,12 +266,14 @@ For each component, generate interactive showcase: **Category:** Action ## Variants + - primary - secondary - ghost - outline ## States + - default - hover - active @@ -267,6 +281,7 @@ For each component, generate interactive showcase: - loading ## Sizes + - small - medium - large @@ -275,138 +290,117 @@ For each component, generate interactive showcase: ### Generate Component Section **HTML structure:** + ```html
-

- Button - [btn-001] - Used in 12 pages -

- - -
-

- {{COMPONENT_DESCRIPTION}} -

-
- - Type: Interactive - - - Category: Action - -
+

+ Button + [btn-001] + Used in 12 pages +

+ + +
+

{{COMPONENT_DESCRIPTION}}

+
+ Type: Interactive + Category: Action
- - -
-

Variants

-
-
- {{VARIANT_EXAMPLES}} -
-
+
+ + +
+

Variants

+
+
{{VARIANT_EXAMPLES}}
- - -
-

States

-
-
- {{STATE_EXAMPLES}} -
-
- - -
-

Try it:

-
- - - - -
-
- -
-
+
+ + +
+

States

+
+
{{STATE_EXAMPLES}}
- - -
-

Code Example

-
-
{{CODE_EXAMPLE}}
-
+ + +
+

Try it:

+
+ + + + +
+
+ +
- - -
-

Usage Guidelines

- {{USAGE_GUIDELINES}} +
+ + +
+

Code Example

+
+
{{CODE_EXAMPLE}}
- - - {{FIGMA_COMPONENT_LINK}} - +
+ + +
+

Usage Guidelines

+ {{USAGE_GUIDELINES}} +
+ + + {{FIGMA_COMPONENT_LINK}}
``` ### Generate Variant Examples **For each variant:** + ```html
- -

primary

+ +

primary

- -

secondary

+ +

secondary

``` ### Generate State Examples **For each state:** + ```html
- -

default

+ +

default

- -

hover

+ +

hover

``` ### Generate Code Example **Extract from component spec:** + ```tsx import { Button } from '@/components/button'; @@ -430,6 +424,7 @@ Build changelog from component version histories: **Scan all components for version history:** + ```markdown ## Version History @@ -437,28 +432,30 @@ Build changelog from component version histories: **Last Updated:** 2024-12-09 **Changes:** + - 2024-09-15: Created component - 2024-10-01: Added loading state - 2024-12-09: Updated hover animation ``` **Generate changelog HTML:** + ```html
-
-

December 9, 2024

-
    -
  • • Button: Updated hover animation
  • -
  • • Input: Added success state
  • -
-
- -
-

October 1, 2024

-
    -
  • • Button: Added loading state
  • -
-
+
+

December 9, 2024

+
    +
  • • Button: Updated hover animation
  • +
  • • Input: Added success state
  • +
+
+ +
+

October 1, 2024

+
    +
  • • Button: Added loading state
  • +
+
``` @@ -475,25 +472,25 @@ If Mode B, add Figma component links: **Load:** `D-Design-System/figma-mappings.md` **Parse mappings:** + ```yaml Button [btn-001] → figma://file/abc123/node/456:789 Input [inp-001] → figma://file/abc123/node/456:790 ``` **Generate Figma section:** + ```html

Figma Components

``` @@ -508,6 +505,7 @@ Create mode-specific installation instructions: **Mode B (Custom/Figma):** + ```bash # Install dependencies npm install @@ -520,6 +518,7 @@ import { Button } from '@/components/button'; ``` **Mode C (Component Library):** + ```bash # Install component library npm install shadcn-ui @@ -546,6 +545,7 @@ Save generated HTML: **Content:** Fully populated template with all sections **Validation:** + - All template variables replaced - Valid HTML structure - All component sections included @@ -561,12 +561,14 @@ Version control the catalog: **Git operations:** + ```bash git add D-Design-System/catalog.html git commit -m "Update design system catalog - [component changes]" ``` **Commit message format:** + ``` Update design system catalog - Added Button loading state @@ -580,6 +582,7 @@ Update design system catalog - Added Button loading state ## Output Format **Success message:** + ``` ✅ Design system catalog generated @@ -602,6 +605,7 @@ Changes committed to git. **Error:** Catalog template not found **Action:** + ``` ⚠️ Catalog template missing @@ -615,6 +619,7 @@ Please ensure WDS is properly installed. **Error:** Component file has invalid format **Action:** + ``` ⚠️ Invalid component specification @@ -630,6 +635,7 @@ Please fix component specification. **Error:** No components in design system **Action:** + ``` ⚠️ No components found @@ -644,12 +650,14 @@ Add components to populate catalog. ## Automation **Catalog is automatically regenerated:** + - After creating new component - After adding variant - After updating component - After updating design tokens **Manual regeneration:** + ``` Agent: Regenerate design system catalog ``` @@ -659,6 +667,7 @@ Agent: Regenerate design system catalog ## Best Practices ### DO ✅ + - Regenerate after every component change - Commit catalog with component changes - Include all variants and states @@ -666,6 +675,7 @@ Agent: Regenerate design system catalog - Keep changelog updated ### DON'T ❌ + - Don't manually edit catalog.html - Don't skip catalog regeneration - Don't forget to commit changes diff --git a/src/modules/wds/workflows/5-design-system/operations/initialize-design-system.md b/src/modules/wds/workflows/5-design-system/operations/initialize-design-system.md index 353861d3..35d72b9b 100644 --- a/src/modules/wds/workflows/5-design-system/operations/initialize-design-system.md +++ b/src/modules/wds/workflows/5-design-system/operations/initialize-design-system.md @@ -21,6 +21,7 @@ I'll create the folder structure and add this component. Design System Mode: [Custom/Library] Component Library: [shadcn/Radix/etc. if applicable] + ``` @@ -31,16 +32,19 @@ Component Library: [shadcn/Radix/etc. if applicable] Create design system folders: ``` + D-Design-System/ ├── components/ ├── design-tokens.md (placeholder) ├── component-library-config.md (if Mode C) └── figma-mappings.md (if Mode B) + ``` ``` + 📁 Created Design System Structure: D-Design-System/ @@ -49,7 +53,8 @@ D-Design-System/ └── [mode-specific files] ✅ Folder structure ready! -``` + +```` --- @@ -104,7 +109,7 @@ Design tokens will be extracted as components are added to the design system. --- **Tokens will be populated as components are specified.** -``` +```` --- @@ -129,10 +134,11 @@ Create Figma mappings file: Components in this design system are linked to Figma components for visual reference and design handoff. ### Format - ``` + Component ID → Figma Node ID [component-id] → figma://file/[file-id]/node/[node-id] + ``` ## Mappings @@ -155,7 +161,7 @@ Create component library config: **File:** `D-Design-System/component-library-config.md` -```markdown +````markdown # Component Library Configuration **Library:** [shadcn/Radix/MUI/etc.] @@ -184,6 +190,7 @@ Format: `WDS Component → Library Component` "borderRadius": {} } ``` +```` [To be updated as design system grows] @@ -196,7 +203,8 @@ Format: `WDS Component → Library Component` --- **Library documentation:** [Link] -``` + +```` --- @@ -252,7 +260,7 @@ Each component file includes: --- **Components are added automatically as they're discovered during specification.** -``` +```` --- @@ -278,6 +286,7 @@ Create interactive HTML catalog: **Load and execute:** `operations/generate-catalog.md` **Initial catalog includes:** + - Project introduction - Design tokens (if defined) - First component showcase @@ -285,6 +294,7 @@ Create interactive HTML catalog: - Empty changelog **Output:** + ``` ✅ Initial catalog generated @@ -302,6 +312,7 @@ Mark design system as initialized: **Update project config:** + ```yaml design_system: enabled: true @@ -332,6 +343,7 @@ added to the design system if they're reusable. Next: Continue with component specification in Phase 4 ``` + --- @@ -350,6 +362,7 @@ Validate initialization: **If validation fails:** + ``` ⚠️ Initialization Warning @@ -365,6 +378,7 @@ Would you like to retry initialization? (y/n) ## Error Handling **If folder already exists:** + ``` ⚠️ D-Design-System/ folder already exists. @@ -379,6 +393,7 @@ Your choice: ``` **If component creation fails:** + ``` ❌ Error creating first component. @@ -389,6 +404,7 @@ You can add components manually or retry. ``` **If mode not specified:** + ``` ⚠️ Design system mode not specified in project config. @@ -410,21 +426,25 @@ Your choice: 💡 Design System Tips: **What happens next:** + - As you specify components, I'll check for similarities - Reusable components will be added to the design system - You'll make decisions about variants vs new components **Best practices:** + - Be consistent with component boundaries - Think about reusability early - Don't over-engineer - start simple **You can always:** + - Add components manually - Refactor the design system - Merge or split components later Design systems evolve - this is just the beginning! + ``` @@ -444,3 +464,4 @@ Return to design system router: --- **This operation runs once per project. Subsequent components use create-new-component or add-variant operations.** +``` diff --git a/src/modules/wds/workflows/5-design-system/operations/update-component.md b/src/modules/wds/workflows/5-design-system/operations/update-component.md index c429b35d..276a79ff 100644 --- a/src/modules/wds/workflows/5-design-system/operations/update-component.md +++ b/src/modules/wds/workflows/5-design-system/operations/update-component.md @@ -13,6 +13,7 @@ ## When to Use This Operation **Use this operation when:** + - Adding new state to all variants (e.g., adding "loading" state) - Updating shared styling (e.g., changing border-radius) - Modifying behavior (e.g., adding keyboard shortcut) @@ -21,6 +22,7 @@ - Fixing errors in component definition **Don't use this operation for:** + - Adding new variant → Use `add-variant.md` - Creating new component → Use `create-new-component.md` - Reusing component → Handled by assessment flow @@ -36,21 +38,27 @@ Determine what's being updated: **Update Types:** ### Type A: Add New State + Adding state to all variants (e.g., loading, error, success) ### Type B: Update Styling + Changing visual properties (colors, sizing, spacing) ### Type C: Update Behavior + Changing interactions, animations, or keyboard support ### Type D: Update Accessibility + Adding/modifying ARIA attributes or screen reader support ### Type E: Update Documentation + Clarifying usage, adding examples, fixing errors ### Type F: Refactor + Reorganizing component structure, splitting/merging variants @@ -65,6 +73,7 @@ What type of update is this? [F] Refactor component Your choice: + ``` @@ -83,13 +92,16 @@ Read existing component file: ``` + 📖 Loaded Button [btn-001] Current state: + - Variants: 3 (primary, secondary, navigation) - States: default, hover, active, disabled - Used in: 9 pages - Last updated: 2024-12-09 + ``` @@ -121,6 +133,7 @@ Determine impact of update: ``` + 📊 Impact Analysis: Update: Adding "loading" state to all button variants @@ -131,6 +144,7 @@ Breaking Change: No (additive only) Compatibility: Fully compatible (optional state) Impact Level: Low (safe to proceed) + ``` @@ -140,6 +154,7 @@ Impact Level: Low (safe to proceed) ``` + Ready to update Button [btn-001] Update: Add "loading" state @@ -151,7 +166,8 @@ This will: ✓ Maintain backward compatibility Proceed with update? (y/n) -``` + +```` --- @@ -175,22 +191,25 @@ Update component file based on type: - hover - active - disabled -``` +```` **After:** + ```markdown ## States **Shared States:** + - default - hover - active - disabled -- loading ← Added +- loading ← Added **State Descriptions:** **Loading:** + - Disabled interaction - Shows spinner icon - Maintains button size @@ -198,10 +217,12 @@ Update component file based on type: ``` **Update Variant-Specific Sections (if needed):** + ```markdown ### Variant-Specific Styling **Navigation (loading state):** + - Spinner + arrow icon - Arrow fades out during loading ``` @@ -211,6 +232,7 @@ Update component file based on type: **Update Styling Section:** **Before:** + ```markdown ### Visual Properties @@ -218,10 +240,11 @@ Update component file based on type: ``` **After:** + ```markdown ### Visual Properties -**Border Radius:** 0.5rem (lg) ← Updated +**Border Radius:** 0.5rem (lg) ← Updated **Change Reason:** Increased for better visual consistency with other components ``` @@ -231,6 +254,7 @@ Update component file based on type: **Update Behavior Section:** **Before:** + ```markdown ### Keyboard @@ -239,12 +263,13 @@ Update component file based on type: ``` **After:** + ```markdown ### Keyboard - Enter/Space: Triggers button action - Tab: Moves focus to/from button -- Escape: Cancels action (if in progress) ← Added +- Escape: Cancels action (if in progress) ← Added ``` ### Type D: Update Accessibility @@ -252,19 +277,23 @@ Update component file based on type: **Update Accessibility Section:** **Before:** + ```markdown **ARIA Attributes:** + - role: button - aria-disabled: true [when disabled] ``` **After:** + ```markdown **ARIA Attributes:** + - role: button - aria-disabled: true [when disabled] -- aria-busy: true [when loading] ← Added -- aria-live: polite [for status updates] ← Added +- aria-busy: true [when loading] ← Added +- aria-live: polite [for status updates] ← Added ``` ### Type E: Update Documentation @@ -272,6 +301,7 @@ Update component file based on type: **Update Usage Section:** **Before:** + ```markdown ### When to Use @@ -280,18 +310,19 @@ Update component file based on type: ``` **After:** + ```markdown ### When to Use - Primary actions (submit forms, save data, proceed to next step) - Secondary actions (cancel, go back, dismiss) -- Triggering modals or dialogs ← Added -- Navigation to new pages/sections ← Added +- Triggering modals or dialogs ← Added +- Navigation to new pages/sections ← Added ### When Not to Use -- For navigation that looks like text (use Link component) ← Added -- For toggling states (use Toggle or Checkbox) ← Added +- For navigation that looks like text (use Link component) ← Added +- For toggling states (use Toggle or Checkbox) ← Added ``` ### Type F: Refactor @@ -305,11 +336,13 @@ Update component file based on type: **Change:** Moved "icon-only" variant to separate Icon Button component **Reason:** Icon-only buttons have significantly different: + - Visual structure (no text) - Accessibility requirements (requires aria-label) - Usage patterns (toolbars, compact spaces) **Migration:** + - Old: Button.icon-only [btn-001] - New: Icon Button [btn-002] @@ -326,6 +359,7 @@ Track update in version history: **Update:** + ```markdown ## Version History @@ -333,9 +367,10 @@ Track update in version history: **Last Updated:** 2024-12-09 **Changes:** + - 2024-12-01: Created component - 2024-12-05: Added navigation variant -- 2024-12-09: Added loading state to all variants ← Added +- 2024-12-09: Added loading state to all variants ← Added ``` --- @@ -355,6 +390,7 @@ Update: Added loading state Affected Pages: 9 Pages using this component: + - Login page - Signup page - Dashboard @@ -365,7 +401,8 @@ Action Required: None (backward compatible) Optional: Consider using loading state for async actions Documentation: See Button component for loading state usage -``` + +```` --- @@ -382,7 +419,7 @@ Update design system metadata: **Last Updated:** 2024-12-09 **Recent Changes:** - Button [btn-001]: Added loading state -``` +```` --- @@ -394,19 +431,23 @@ Update design system metadata: Update Type: Add new state Changes: + - Added "loading" state to all variants - Updated state documentation - Version history updated Impact: + - 9 pages affected - No breaking changes - Backward compatible Next Steps: + - Pages can optionally use new loading state - No immediate action required - Consider updating high-traffic pages first + ``` @@ -430,13 +471,16 @@ Validate update: **If update creates breaking change:** ``` + ⚠️ Breaking Change Detected This update will break existing usage: + - [List of breaking changes] - Affected pages: [count] Breaking changes require: + 1. Designer confirmation 2. Migration plan 3. Page spec updates @@ -444,25 +488,30 @@ Breaking changes require: Proceed with breaking change? (y/n) If yes, I'll create a migration checklist. + ``` **If component file locked:** ``` + ⚠️ Component file is being edited elsewhere. Component: Button [btn-001] Status: Locked by [user/process] Options: + 1. Wait and retry 2. Force update (may cause conflicts) 3. Cancel update Your choice: + ``` **If update conflicts with variants:** ``` + ⚠️ Update Conflict Detected You're trying to add "loading" state to all variants, @@ -472,12 +521,14 @@ Current navigation loading: Spinner + icon animation Proposed loading: Spinner only Options: + 1. Override navigation variant (make consistent) 2. Keep navigation variant different (document exception) 3. Cancel update Your choice: -``` + +```` --- @@ -518,7 +569,7 @@ If issues arise: 1. Revert component file to previous version 2. Restore page specifications 3. Document issues encountered -``` +```` ### If Major Update @@ -533,14 +584,17 @@ Suggest design system review: This is a significant update to a widely-used component. Consider reviewing: + - Component consistency across design system - Other components that might need similar updates - Overall design system patterns Schedule a design system review session? + ``` --- **This operation updates a component. Changes apply to all future usage automatically.** +``` diff --git a/src/modules/wds/workflows/5-design-system/templates/component-library-config.template.md b/src/modules/wds/workflows/5-design-system/templates/component-library-config.template.md index 70361475..11f26ad9 100644 --- a/src/modules/wds/workflows/5-design-system/templates/component-library-config.template.md +++ b/src/modules/wds/workflows/5-design-system/templates/component-library-config.template.md @@ -19,10 +19,12 @@ **Format:** `WDS Component → Library Component` ### Interactive Components + - Button [btn-001] → shadcn/ui Button - [More mappings] ### Form Components + - Input Field [inp-001] → shadcn/ui Input - [More mappings] diff --git a/src/modules/wds/workflows/5-design-system/templates/component.template.md b/src/modules/wds/workflows/5-design-system/templates/component.template.md index 52ccba2d..5f7dece4 100644 --- a/src/modules/wds/workflows/5-design-system/templates/component.template.md +++ b/src/modules/wds/workflows/5-design-system/templates/component.template.md @@ -21,10 +21,12 @@ ## States **Required States:** + - default - [other required states] **Optional States:** + - [optional states if any] **State Descriptions:** @@ -105,6 +107,7 @@ **Pages:** [count] **Examples:** + - [Page] - [Usage] --- @@ -121,6 +124,7 @@ **Last Updated:** [Date] **Changes:** + - [Date]: [Change] --- diff --git a/src/modules/wds/workflows/5-design-system/templates/design-tokens.template.md b/src/modules/wds/workflows/5-design-system/templates/design-tokens.template.md index 6e35c676..1ecd9626 100644 --- a/src/modules/wds/workflows/5-design-system/templates/design-tokens.template.md +++ b/src/modules/wds/workflows/5-design-system/templates/design-tokens.template.md @@ -8,6 +8,7 @@ ## Colors ### Primary Colors + ```yaml primary-50: #eff6ff primary-100: #dbeafe @@ -22,6 +23,7 @@ primary-900: #1e3a8a ``` ### Semantic Colors + ```yaml success: #10b981 error: #ef4444 @@ -30,6 +32,7 @@ info: #3b82f6 ``` ### Neutral Colors + ```yaml gray-50: #f9fafb gray-100: #f3f4f6 @@ -42,12 +45,14 @@ gray-900: #111827 ## Typography ### Font Families + ```yaml -font-sans: "Inter, system-ui, sans-serif" -font-mono: "JetBrains Mono, monospace" +font-sans: 'Inter, system-ui, sans-serif' +font-mono: 'JetBrains Mono, monospace' ``` ### Font Sizes + ```yaml text-xs: 0.75rem text-sm: 0.875rem @@ -60,6 +65,7 @@ text-4xl: 2.25rem ``` ### Font Weights + ```yaml font-normal: 400 font-medium: 500 @@ -88,6 +94,7 @@ spacing-16: 4rem ## Layout ### Breakpoints + ```yaml sm: 640px md: 768px @@ -97,6 +104,7 @@ xl: 1280px ``` ### Container Widths + ```yaml container-sm: 640px container-md: 768px @@ -109,6 +117,7 @@ container-xl: 1280px ## Effects ### Shadows + ```yaml shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05) shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1) @@ -116,6 +125,7 @@ shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1) ``` ### Border Radius + ```yaml radius-sm: 0.125rem radius-md: 0.375rem @@ -124,6 +134,7 @@ radius-full: 9999px ``` ### Transitions + ```yaml transition-fast: 150ms transition-base: 200ms @@ -135,6 +146,7 @@ transition-slow: 300ms ## Component-Specific Tokens ### Button + ```yaml button-padding-x: spacing-4 button-padding-y: spacing-2 @@ -143,6 +155,7 @@ button-font-weight: font-semibold ``` ### Input + ```yaml input-height: 2.5rem input-padding-x: spacing-3 diff --git a/src/modules/wds/workflows/6-design-deliveries/design-deliveries-guide.md b/src/modules/wds/workflows/6-design-deliveries/design-deliveries-guide.md index 2faa796b..5a7f654e 100644 --- a/src/modules/wds/workflows/6-design-deliveries/design-deliveries-guide.md +++ b/src/modules/wds/workflows/6-design-deliveries/design-deliveries-guide.md @@ -42,6 +42,7 @@ Phase 6.6: Continue with Next Flow ✅ **Ready for development:** No blockers or dependencies **Example:** + ``` Flow: Login & Onboarding ✓ Scenario 01: Welcome screen @@ -81,6 +82,7 @@ Flow: Login & Onboarding **Use template:** `templates/design-delivery.template.yaml` **Include:** + - All scenarios for this flow - Technical requirements - Design system components used @@ -89,27 +91,28 @@ Flow: Login & Onboarding - Complexity estimate **Example:** + ```yaml delivery: - id: "DD-001" - name: "Login & Onboarding Flow" - status: "ready" - priority: "high" + id: 'DD-001' + name: 'Login & Onboarding Flow' + status: 'ready' + priority: 'high' design_artifacts: scenarios: - - id: "01-welcome" - path: "C-Scenarios/01-welcome-screen/" - - id: "02-login" - path: "C-Scenarios/02-login/" + - id: '01-welcome' + path: 'C-Scenarios/01-welcome-screen/' + - id: '02-login' + path: 'C-Scenarios/02-login/' # ... etc user_value: - problem: "Users need to access the app securely" - solution: "Streamlined onboarding with family setup" + problem: 'Users need to access the app securely' + solution: 'Streamlined onboarding with family setup' success_criteria: - - "User completes signup in under 2 minutes" - - "90% completion rate" + - 'User completes signup in under 2 minutes' + - '90% completion rate' ``` --- @@ -121,6 +124,7 @@ user_value: **Use template:** `templates/test-scenario.template.yaml` **Include:** + - Happy path tests - Error state tests - Edge case tests @@ -129,19 +133,20 @@ user_value: - Usability tests **Example:** + ```yaml test_scenario: - id: "TS-001" - name: "Login & Onboarding Testing" - delivery_id: "DD-001" + id: 'TS-001' + name: 'Login & Onboarding Testing' + delivery_id: 'DD-001' happy_path: - - id: "HP-001" - name: "New User Complete Onboarding" + - id: 'HP-001' + name: 'New User Complete Onboarding' steps: - - action: "Open app" - expected: "Welcome screen appears" - design_ref: "C-Scenarios/01-welcome/Frontend/specifications.md" + - action: 'Open app' + expected: 'Welcome screen appears' + design_ref: 'C-Scenarios/01-welcome/Frontend/specifications.md' # ... etc ``` @@ -156,6 +161,7 @@ happy_path: **Protocol:** See `src/core/resources/wds/handoff-protocol.md` **Topics to cover:** + 1. User value and success criteria 2. Scenario walkthrough 3. Technical requirements @@ -168,17 +174,18 @@ happy_path: 10. Confirmation **Example:** + ``` -WDS UX Expert: "Hey Architect! I've completed the design for - Login & Onboarding. Let me walk you through +WDS UX Expert: "Hey Architect! I've completed the design for + Login & Onboarding. Let me walk you through Design Delivery DD-001..." [20-minute structured conversation] -BMad Architect: "Handoff complete! I'll break this down into +BMad Architect: "Handoff complete! I'll break this down into 4 development epics. Total: 3 weeks." -WDS UX Expert: "Perfect! I'll start designing the next flow +WDS UX Expert: "Perfect! I'll start designing the next flow while you build this one." ``` @@ -189,20 +196,23 @@ WDS UX Expert: "Perfect! I'll start designing the next flow **Mark delivery as handed off:** Update delivery status: + ```yaml delivery: - status: "in_development" - handed_off_at: "2024-12-09T11:00:00Z" - assigned_to: "bmad-architect" + status: 'in_development' + handed_off_at: '2024-12-09T11:00:00Z' + assigned_to: 'bmad-architect' ``` **BMad receives:** + - Design Delivery (DD-XXX.yaml) - All scenario specifications - Design system components - Test scenario (TS-XXX.yaml) **BMad starts:** + - Architecture design - Epic breakdown - Implementation @@ -214,16 +224,19 @@ delivery: **While BMad builds this flow, you design the next one!** **Return to Phase 4:** + - Design next complete testable flow - Create specifications - Define components **Then return to Phase 6:** + - Create next Design Delivery - Hand off to BMad - Repeat **Parallel work:** + ``` Week 1: Design Flow 1 Week 2: Handoff Flow 1 → BMad builds Flow 1 @@ -245,6 +258,7 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 **Location:** `deliveries/DD-XXX-name.yaml` **Contents:** + - Delivery metadata (id, name, status, priority) - User value (problem, solution, success criteria) - Design artifacts (scenarios, flows, components) @@ -260,6 +274,7 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 **Location:** `test-scenarios/TS-XXX-name.yaml` **Contents:** + - Test metadata (id, name, delivery_id, status) - Test objectives - Happy path tests @@ -278,6 +293,7 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 **Location:** `deliveries/DD-XXX-handoff-log.md` **Contents:** + - Handoff date and duration - Participants - Key points discussed @@ -340,6 +356,7 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 **Goal:** Get to testing as fast as possible **Approach:** + 1. Design the most critical user flow first 2. Example: Login & Onboarding (users must access app) 3. Keep it simple and focused @@ -353,6 +370,7 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 **Goal:** Deliver value incrementally **Approach:** + 1. Each delivery adds new value 2. Example: DD-001 (Login) → DD-002 (Core Feature) → DD-003 (Enhancement) 3. Users see progress @@ -366,6 +384,7 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 **Goal:** Maximize throughput **Approach:** + 1. Designer designs Flow 2 while BMad builds Flow 1 2. Designer designs Flow 3 while BMad builds Flow 2 3. Designer tests Flow 1 while designing Flow 4 @@ -379,24 +398,28 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 ### DO ✅ **Design complete flows:** + - Entry point to exit point - All scenarios specified - All components defined - Testable end-to-end **Deliver value:** + - Business value (ROI, metrics) - User value (solves problem) - Testable (can validate) - Ready (no blockers) **Communicate clearly:** + - Handoff dialog is crucial - Answer all questions - Document decisions - Stay available **Iterate fast:** + - Don't design everything at once - Get to testing quickly - Learn from real users @@ -405,21 +428,25 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 ### DON'T ❌ **Don't wait:** + - Don't design all flows before handing off - Don't wait for perfection - Don't block development **Don't over-design:** + - Don't add unnecessary features - Don't gold-plate - Don't lose focus on value **Don't under-specify:** + - Don't leave gaps in specifications - Don't assume BMad will figure it out - Don't skip edge cases **Don't disappear:** + - Don't hand off and vanish - Don't ignore questions - Don't skip validation (Phase 7) @@ -443,15 +470,18 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 ## Resources **Templates:** + - `templates/design-delivery.template.yaml` - `templates/test-scenario.template.yaml` **Specifications:** + - `src/core/resources/wds/design-delivery-spec.md` - `src/core/resources/wds/handoff-protocol.md` - `src/core/resources/wds/integration-guide.md` **Examples:** + - See `WDS-V6-CONVERSION-ROADMAP.md` for integration details --- diff --git a/src/modules/wds/workflows/6-design-deliveries/steps/step-6.1-detect-completion.md b/src/modules/wds/workflows/6-design-deliveries/steps/step-6.1-detect-completion.md index b55584a5..a1623521 100644 --- a/src/modules/wds/workflows/6-design-deliveries/steps/step-6.1-detect-completion.md +++ b/src/modules/wds/workflows/6-design-deliveries/steps/step-6.1-detect-completion.md @@ -72,6 +72,7 @@ Check if you have a complete testable flow ready for handoff. ### ✅ YES - Flow is Complete **Proceed to Phase 6.2:** + ``` [C] Continue to step-6.2-create-delivery.md ``` @@ -83,16 +84,19 @@ Check if you have a complete testable flow ready for handoff. **What's missing?** **If scenarios are incomplete:** + - Return to Phase 4: UX Design - Complete missing scenarios - Return to this step when done **If components are incomplete:** + - Return to Phase 5: Design System - Define missing components - Return to this step when done **If flow is not testable:** + - Identify missing pieces - Complete the flow - Return to this step when done diff --git a/src/modules/wds/workflows/6-design-deliveries/steps/step-6.2-create-delivery.md b/src/modules/wds/workflows/6-design-deliveries/steps/step-6.2-create-delivery.md index af631009..37b97d9e 100644 --- a/src/modules/wds/workflows/6-design-deliveries/steps/step-6.2-create-delivery.md +++ b/src/modules/wds/workflows/6-design-deliveries/steps/step-6.2-create-delivery.md @@ -9,6 +9,7 @@ Package your complete testable flow into a Design Delivery YAML file. ## Before You Start **Ensure you have:** + - ✅ Completed step 6.1 (flow is complete) - ✅ All scenario specifications ready - ✅ All component definitions ready @@ -23,11 +24,13 @@ Package your complete testable flow into a Design Delivery YAML file. **Format:** `DD-XXX-name.yaml` **Examples:** + - `DD-001-login-onboarding.yaml` - `DD-002-morning-dog-care.yaml` - `DD-003-calendar-view.yaml` **Numbering:** + - Start at DD-001 for first delivery - Increment for each new delivery - Use leading zeros (DD-001, not DD-1) @@ -54,13 +57,13 @@ cp templates/design-delivery.template.yaml deliveries/DD-001-login-onboarding.ya ```yaml delivery: - id: "DD-001" - name: "Login & Onboarding Flow" - status: "ready" # ready | in_development | in_testing | complete - priority: "high" # critical | high | medium | low - version: "1.0" - created_at: "2024-12-09T12:00:00Z" - updated_at: "2024-12-09T12:00:00Z" + id: 'DD-001' + name: 'Login & Onboarding Flow' + status: 'ready' # ready | in_development | in_testing | complete + priority: 'high' # critical | high | medium | low + version: '1.0' + created_at: '2024-12-09T12:00:00Z' + updated_at: '2024-12-09T12:00:00Z' ``` --- @@ -74,16 +77,16 @@ user_value: problem: | Users need to access the app securely and set up their family structure before using core features. - + solution: | Streamlined onboarding flow that guides users through account creation, family setup, and initial dog addition. - + success_criteria: - - "User completes signup in under 2 minutes" - - "90% onboarding completion rate" - - "User satisfaction score > 4.5/5" - - "Zero critical errors during onboarding" + - 'User completes signup in under 2 minutes' + - '90% onboarding completion rate' + - 'User satisfaction score > 4.5/5' + - 'Zero critical errors during onboarding' ``` --- @@ -95,40 +98,40 @@ user_value: ```yaml design_artifacts: scenarios: - - id: "01-welcome" - path: "C-Scenarios/01-welcome-screen/" - description: "Initial welcome screen with value proposition" - - - id: "02-login" - path: "C-Scenarios/02-login/" - description: "Login flow for returning users" - - - id: "03-signup" - path: "C-Scenarios/03-signup/" - description: "Account creation for new users" - - - id: "04-family-setup" - path: "C-Scenarios/04-family-setup/" - description: "Family/household configuration" - + - id: '01-welcome' + path: 'C-Scenarios/01-welcome-screen/' + description: 'Initial welcome screen with value proposition' + + - id: '02-login' + path: 'C-Scenarios/02-login/' + description: 'Login flow for returning users' + + - id: '03-signup' + path: 'C-Scenarios/03-signup/' + description: 'Account creation for new users' + + - id: '04-family-setup' + path: 'C-Scenarios/04-family-setup/' + description: 'Family/household configuration' + user_flows: - - name: "New User Onboarding" - path: "C-Scenarios/flows/new-user-onboarding.md" - entry_point: "01-welcome" - exit_point: "04-family-setup" - + - name: 'New User Onboarding' + path: 'C-Scenarios/flows/new-user-onboarding.md' + entry_point: '01-welcome' + exit_point: '04-family-setup' + design_system_components: - - component: "Button" - variants: ["Primary", "Secondary", "Text"] - path: "D-Design-System/03-Atomic-Components/Buttons/" - - - component: "Input" - variants: ["Text", "Email", "Password"] - path: "D-Design-System/03-Atomic-Components/Inputs/" - - - component: "Card" - variants: ["Default", "Elevated"] - path: "D-Design-System/03-Atomic-Components/Cards/" + - component: 'Button' + variants: ['Primary', 'Secondary', 'Text'] + path: 'D-Design-System/03-Atomic-Components/Buttons/' + + - component: 'Input' + variants: ['Text', 'Email', 'Password'] + path: 'D-Design-System/03-Atomic-Components/Inputs/' + + - component: 'Card' + variants: ['Default', 'Elevated'] + path: 'D-Design-System/03-Atomic-Components/Cards/' ``` --- @@ -138,39 +141,39 @@ design_artifacts: ```yaml technical_requirements: platform: - frontend: "React Native 0.72" - backend: "Supabase 2.x" - database: "PostgreSQL 15" - + frontend: 'React Native 0.72' + backend: 'Supabase 2.x' + database: 'PostgreSQL 15' + integrations: - - name: "Supabase Auth" - type: "required" - provider: "Supabase" - purpose: "User authentication and session management" - - - name: "Email Verification" - type: "required" - provider: "Supabase" - purpose: "Verify user email addresses" - + - name: 'Supabase Auth' + type: 'required' + provider: 'Supabase' + purpose: 'User authentication and session management' + + - name: 'Email Verification' + type: 'required' + provider: 'Supabase' + purpose: 'Verify user email addresses' + data_models: - - model: "User" - fields: ["id", "email", "name", "created_at"] - path: "A-Project-Brief/data-models.md#user" - - - model: "Family" - fields: ["id", "name", "owner_id", "created_at"] - path: "A-Project-Brief/data-models.md#family" - + - model: 'User' + fields: ['id', 'email', 'name', 'created_at'] + path: 'A-Project-Brief/data-models.md#user' + + - model: 'Family' + fields: ['id', 'name', 'owner_id', 'created_at'] + path: 'A-Project-Brief/data-models.md#family' + performance: - - "Screen load time < 1 second" - - "Form submission response < 500ms" - - "Smooth 60fps animations" - + - 'Screen load time < 1 second' + - 'Form submission response < 500ms' + - 'Smooth 60fps animations' + security: - - "Password must be hashed (bcrypt)" - - "Email verification required" - - "Session tokens expire after 30 days" + - 'Password must be hashed (bcrypt)' + - 'Email verification required' + - 'Session tokens expire after 30 days' ``` --- @@ -180,25 +183,25 @@ technical_requirements: ```yaml acceptance_criteria: functional: - - "User can create account with email and password" - - "User receives verification email" - - "User can log in with verified credentials" - - "User can set up family/household" - - "User can skip dog addition during onboarding" - + - 'User can create account with email and password' + - 'User receives verification email' + - 'User can log in with verified credentials' + - 'User can set up family/household' + - 'User can skip dog addition during onboarding' + non_functional: - - "All screens load in under 1 second" - - "Forms validate input in real-time" - - "Error messages are clear and actionable" - - "Design system components used correctly" - - "Accessibility: WCAG 2.1 AA compliance" - + - 'All screens load in under 1 second' + - 'Forms validate input in real-time' + - 'Error messages are clear and actionable' + - 'Design system components used correctly' + - 'Accessibility: WCAG 2.1 AA compliance' + edge_cases: - - "Handle email already exists error" - - "Handle network timeout during signup" - - "Handle app close mid-onboarding (resume state)" - - "Handle invalid email format" - - "Handle weak password" + - 'Handle email already exists error' + - 'Handle network timeout during signup' + - 'Handle app close mid-onboarding (resume state)' + - 'Handle invalid email format' + - 'Handle weak password' ``` --- @@ -208,25 +211,25 @@ acceptance_criteria: ```yaml testing_guidance: user_testing: - - "Recruit 5-10 new users who have never used the app" - - "Observe onboarding completion without assistance" - - "Measure time to complete onboarding" + - 'Recruit 5-10 new users who have never used the app' + - 'Observe onboarding completion without assistance' + - 'Measure time to complete onboarding' - "Ask: 'Was anything confusing?'" - - "Target: 90% completion rate, < 2 minutes" - + - 'Target: 90% completion rate, < 2 minutes' + qa_testing: - - "Test all happy paths" - - "Test all error states" - - "Test all edge cases" - - "Test on iOS and Android" - - "Test with slow network" - - "Test with no network" - + - 'Test all happy paths' + - 'Test all error states' + - 'Test all edge cases' + - 'Test on iOS and Android' + - 'Test with slow network' + - 'Test with no network' + design_validation: - - "Verify design system compliance" - - "Verify accessibility" - - "Verify animations and transitions" - - "Verify copy matches specifications" + - 'Verify design system compliance' + - 'Verify accessibility' + - 'Verify animations and transitions' + - 'Verify copy matches specifications' ``` --- @@ -235,18 +238,18 @@ testing_guidance: ```yaml estimated_complexity: - size: "medium" # small | medium | large | xlarge - effort: "2-3 weeks" - risk: "low" # low | medium | high - + size: 'medium' # small | medium | large | xlarge + effort: '2-3 weeks' + risk: 'low' # low | medium | high + dependencies: - - "Supabase project setup" - - "Email service configuration" - + - 'Supabase project setup' + - 'Email service configuration' + assumptions: - - "Supabase Auth SDK is stable" - - "Design system components are reusable" - - "No major technical blockers" + - 'Supabase Auth SDK is stable' + - 'Design system components are reusable' + - 'No major technical blockers' ``` --- diff --git a/src/modules/wds/workflows/6-design-deliveries/steps/step-6.3-create-test-scenario.md b/src/modules/wds/workflows/6-design-deliveries/steps/step-6.3-create-test-scenario.md index c5ba3a66..05849d37 100644 --- a/src/modules/wds/workflows/6-design-deliveries/steps/step-6.3-create-test-scenario.md +++ b/src/modules/wds/workflows/6-design-deliveries/steps/step-6.3-create-test-scenario.md @@ -9,6 +9,7 @@ Create a test scenario file that defines how to validate this Design Delivery af ## Before You Start **Ensure you have:** + - ✅ Completed step 6.2 (Design Delivery created) - ✅ Design Delivery file: `deliveries/DD-XXX-name.yaml` - ✅ Clear understanding of what needs testing @@ -22,11 +23,13 @@ Create a test scenario file that defines how to validate this Design Delivery af **Format:** `TS-XXX-name.yaml` **Match the Design Delivery ID:** + - DD-001 → TS-001 - DD-002 → TS-002 - DD-003 → TS-003 **Examples:** + - `TS-001-login-onboarding.yaml` - `TS-002-morning-dog-care.yaml` - `TS-003-calendar-view.yaml` @@ -53,12 +56,12 @@ cp templates/test-scenario.template.yaml test-scenarios/TS-001-login-onboarding. ```yaml test_scenario: - id: "TS-001" - name: "Login & Onboarding Testing" - delivery_id: "DD-001" - status: "ready" # ready | in_progress | complete - version: "1.0" - created_at: "2024-12-09T12:00:00Z" + id: 'TS-001' + name: 'Login & Onboarding Testing' + delivery_id: 'DD-001' + status: 'ready' # ready | in_progress | complete + version: '1.0' + created_at: '2024-12-09T12:00:00Z' ``` --- @@ -67,11 +70,11 @@ test_scenario: ```yaml test_objectives: - - "Verify complete onboarding flow works end-to-end" - - "Validate design system compliance" - - "Ensure accessibility standards are met" - - "Confirm error handling is clear and helpful" - - "Measure onboarding completion rate and time" + - 'Verify complete onboarding flow works end-to-end' + - 'Validate design system compliance' + - 'Ensure accessibility standards are met' + - 'Confirm error handling is clear and helpful' + - 'Measure onboarding completion rate and time' ``` --- @@ -82,74 +85,74 @@ test_objectives: ```yaml happy_path: - - id: "HP-001" - name: "New User Complete Onboarding" - description: "User creates account and completes onboarding" + - id: 'HP-001' + name: 'New User Complete Onboarding' + description: 'User creates account and completes onboarding' steps: - - action: "Open app" - expected: "Welcome screen appears with value proposition" - design_ref: "C-Scenarios/01-welcome/Frontend/specifications.md" - + - action: 'Open app' + expected: 'Welcome screen appears with value proposition' + design_ref: 'C-Scenarios/01-welcome/Frontend/specifications.md' + - action: "Tap 'Get Started' button" - expected: "Login/Signup choice screen appears" - design_ref: "C-Scenarios/02-login/Frontend/specifications.md" - + expected: 'Login/Signup choice screen appears' + design_ref: 'C-Scenarios/02-login/Frontend/specifications.md' + - action: "Tap 'Create Account'" - expected: "Signup form appears" - design_ref: "C-Scenarios/03-signup/Frontend/specifications.md" - - - action: "Enter email: test@example.com" - expected: "Email field validates format in real-time" - design_ref: "C-Scenarios/03-signup/Frontend/specifications.md#validation" - - - action: "Enter password: SecurePass123!" - expected: "Password field shows strength indicator" - design_ref: "C-Scenarios/03-signup/Frontend/specifications.md#password" - + expected: 'Signup form appears' + design_ref: 'C-Scenarios/03-signup/Frontend/specifications.md' + + - action: 'Enter email: test@example.com' + expected: 'Email field validates format in real-time' + design_ref: 'C-Scenarios/03-signup/Frontend/specifications.md#validation' + + - action: 'Enter password: SecurePass123!' + expected: 'Password field shows strength indicator' + design_ref: 'C-Scenarios/03-signup/Frontend/specifications.md#password' + - action: "Tap 'Create Account' button" - expected: "Loading state, then success message" - design_ref: "C-Scenarios/03-signup/Frontend/specifications.md#submit" - - - action: "Navigate to Family Setup" - expected: "Family setup screen appears" - design_ref: "C-Scenarios/04-family-setup/Frontend/specifications.md" - + expected: 'Loading state, then success message' + design_ref: 'C-Scenarios/03-signup/Frontend/specifications.md#submit' + + - action: 'Navigate to Family Setup' + expected: 'Family setup screen appears' + design_ref: 'C-Scenarios/04-family-setup/Frontend/specifications.md' + - action: "Enter family name: 'The Smiths'" - expected: "Family name field accepts input" - design_ref: "C-Scenarios/04-family-setup/Frontend/specifications.md" - + expected: 'Family name field accepts input' + design_ref: 'C-Scenarios/04-family-setup/Frontend/specifications.md' + - action: "Tap 'Continue'" - expected: "Onboarding complete, navigate to dashboard" - design_ref: "C-Scenarios/04-family-setup/Frontend/specifications.md#complete" - + expected: 'Onboarding complete, navigate to dashboard' + design_ref: 'C-Scenarios/04-family-setup/Frontend/specifications.md#complete' + success_criteria: - - "All steps complete without errors" - - "User reaches dashboard" - - "Time to complete < 2 minutes" - - - id: "HP-002" - name: "Returning User Login" - description: "Existing user logs in" + - 'All steps complete without errors' + - 'User reaches dashboard' + - 'Time to complete < 2 minutes' + + - id: 'HP-002' + name: 'Returning User Login' + description: 'Existing user logs in' steps: - - action: "Open app" - expected: "Welcome screen appears" - + - action: 'Open app' + expected: 'Welcome screen appears' + - action: "Tap 'Get Started'" - expected: "Login/Signup choice appears" - + expected: 'Login/Signup choice appears' + - action: "Tap 'Log In'" - expected: "Login form appears" - - - action: "Enter email and password" - expected: "Fields accept input" - + expected: 'Login form appears' + + - action: 'Enter email and password' + expected: 'Fields accept input' + - action: "Tap 'Log In' button" - expected: "Loading state, then navigate to dashboard" - + expected: 'Loading state, then navigate to dashboard' + success_criteria: - - "User successfully logs in" - - "Session persists" - - "Login time < 3 seconds" + - 'User successfully logs in' + - 'Session persists' + - 'Login time < 3 seconds' ``` --- @@ -160,53 +163,53 @@ happy_path: ```yaml error_states: - - id: "ES-001" - name: "Email Already Exists" + - id: 'ES-001' + name: 'Email Already Exists' steps: - - action: "Enter email that already exists" + - action: 'Enter email that already exists' - action: "Tap 'Create Account'" - expected: "Error message: 'This email is already registered. Try logging in instead.'" - expected: "Helpful action: 'Go to Login' button" - + validation: - - "Error message is clear and actionable" - - "User can recover without losing data" - - "Error styling matches design system" - - - id: "ES-002" - name: "Invalid Email Format" + - 'Error message is clear and actionable' + - 'User can recover without losing data' + - 'Error styling matches design system' + + - id: 'ES-002' + name: 'Invalid Email Format' steps: - action: "Enter invalid email: 'notanemail'" - - action: "Tap outside field (blur)" + - action: 'Tap outside field (blur)' - expected: "Real-time validation error: 'Please enter a valid email'" - + validation: - - "Error appears immediately on blur" - - "Error clears when valid email entered" - - - id: "ES-003" - name: "Weak Password" + - 'Error appears immediately on blur' + - 'Error clears when valid email entered' + + - id: 'ES-003' + name: 'Weak Password' steps: - action: "Enter weak password: '123'" - expected: "Password strength indicator shows 'Weak'" - expected: "Helper text: 'Password must be at least 8 characters'" - + validation: - - "Strength indicator updates in real-time" - - "Submit button disabled until password is strong" - - - id: "ES-004" - name: "Network Timeout" + - 'Strength indicator updates in real-time' + - 'Submit button disabled until password is strong' + + - id: 'ES-004' + name: 'Network Timeout' steps: - - setup: "Simulate slow/no network" + - setup: 'Simulate slow/no network' - action: "Tap 'Create Account'" - - expected: "Loading state for 5 seconds" + - expected: 'Loading state for 5 seconds' - expected: "Timeout error: 'Connection timeout. Please try again.'" - - expected: "Retry button available" - + - expected: 'Retry button available' + validation: - - "User is informed of network issue" - - "User can retry without re-entering data" + - 'User is informed of network issue' + - 'User can retry without re-entering data' ``` --- @@ -217,39 +220,39 @@ error_states: ```yaml edge_cases: - - id: "EC-001" - name: "User Closes App Mid-Onboarding" + - id: 'EC-001' + name: 'User Closes App Mid-Onboarding' steps: - - action: "Start onboarding, complete signup" - - action: "Close app (force quit)" - - action: "Reopen app" - - expected: "Resume at Family Setup (last incomplete step)" - + - action: 'Start onboarding, complete signup' + - action: 'Close app (force quit)' + - action: 'Reopen app' + - expected: 'Resume at Family Setup (last incomplete step)' + validation: - - "Progress is saved" + - 'Progress is saved' - "User doesn't have to start over" - - - id: "EC-002" - name: "User Navigates Back During Onboarding" + + - id: 'EC-002' + name: 'User Navigates Back During Onboarding' steps: - - action: "Complete signup" - - action: "Tap back button on Family Setup" + - action: 'Complete signup' + - action: 'Tap back button on Family Setup' - expected: "Confirmation: 'Are you sure? Progress will be saved.'" - + validation: - - "User is warned before going back" - - "Progress is not lost" - - - id: "EC-003" - name: "Very Long Family Name" + - 'User is warned before going back' + - 'Progress is not lost' + + - id: 'EC-003' + name: 'Very Long Family Name' steps: - - action: "Enter 100-character family name" - - expected: "Field truncates at 50 characters" + - action: 'Enter 100-character family name' + - expected: 'Field truncates at 50 characters' - expected: "Character count: '50/50'" - + validation: - - "Field has reasonable limit" - - "User is informed of limit" + - 'Field has reasonable limit' + - 'User is informed of limit' ``` --- @@ -260,50 +263,50 @@ edge_cases: ```yaml design_system_checks: - - id: "DS-001" - name: "Button Components" + - id: 'DS-001' + name: 'Button Components' checks: - - component: "Primary Button" - instances: ["Get Started", "Create Account", "Continue"] + - component: 'Primary Button' + instances: ['Get Started', 'Create Account', 'Continue'] verify: - - "Height: 48px" - - "Background: tokens.button.primary.background (#2563EB)" - - "Text: tokens.button.primary.text (#FFFFFF)" - - "Typography: 16px, semibold" - - "Border radius: 8px" - - "Padding: 12px 24px" - design_ref: "D-Design-System/03-Atomic-Components/Buttons/Button-Primary.md" - - - component: "Secondary Button" - instances: ["Log In"] + - 'Height: 48px' + - 'Background: tokens.button.primary.background (#2563EB)' + - 'Text: tokens.button.primary.text (#FFFFFF)' + - 'Typography: 16px, semibold' + - 'Border radius: 8px' + - 'Padding: 12px 24px' + design_ref: 'D-Design-System/03-Atomic-Components/Buttons/Button-Primary.md' + + - component: 'Secondary Button' + instances: ['Log In'] verify: - - "Height: 48px" - - "Background: transparent" - - "Border: 2px solid tokens.button.secondary.border" - - "Text: tokens.button.secondary.text" - design_ref: "D-Design-System/03-Atomic-Components/Buttons/Button-Secondary.md" - - - id: "DS-002" - name: "Input Components" + - 'Height: 48px' + - 'Background: transparent' + - 'Border: 2px solid tokens.button.secondary.border' + - 'Text: tokens.button.secondary.text' + design_ref: 'D-Design-System/03-Atomic-Components/Buttons/Button-Secondary.md' + + - id: 'DS-002' + name: 'Input Components' checks: - - component: "Text Input" - instances: ["Email", "Password", "Family Name"] + - component: 'Text Input' + instances: ['Email', 'Password', 'Family Name'] verify: - - "Height: 48px" - - "Border: 1px solid tokens.input.border" - - "Focus border: 2px solid tokens.input.focus" - - "Error border: 2px solid tokens.input.error" - - "Typography: 16px, regular" - design_ref: "D-Design-System/03-Atomic-Components/Inputs/Input-Text.md" - - - id: "DS-003" - name: "Spacing and Layout" + - 'Height: 48px' + - 'Border: 1px solid tokens.input.border' + - 'Focus border: 2px solid tokens.input.focus' + - 'Error border: 2px solid tokens.input.error' + - 'Typography: 16px, regular' + design_ref: 'D-Design-System/03-Atomic-Components/Inputs/Input-Text.md' + + - id: 'DS-003' + name: 'Spacing and Layout' checks: - verify: - - "Screen padding: 20px (tokens.spacing.screen)" - - "Element spacing: 16px (tokens.spacing.md)" - - "Section spacing: 32px (tokens.spacing.xl)" - design_ref: "D-Design-System/02-Foundation/Spacing/tokens.json" + - 'Screen padding: 20px (tokens.spacing.screen)' + - 'Element spacing: 16px (tokens.spacing.md)' + - 'Section spacing: 32px (tokens.spacing.xl)' + design_ref: 'D-Design-System/02-Foundation/Spacing/tokens.json' ``` --- @@ -312,38 +315,38 @@ design_system_checks: ```yaml accessibility: - - id: "A11Y-001" - name: "Screen Reader Navigation" - setup: "Enable VoiceOver (iOS) or TalkBack (Android)" + - id: 'A11Y-001' + name: 'Screen Reader Navigation' + setup: 'Enable VoiceOver (iOS) or TalkBack (Android)' verify: - - "All buttons have descriptive labels" - - "Form fields announce their purpose" - - "Error messages are announced" - - "Navigation order is logical" - + - 'All buttons have descriptive labels' + - 'Form fields announce their purpose' + - 'Error messages are announced' + - 'Navigation order is logical' + success_criteria: - - "User can complete onboarding using only screen reader" - - - id: "A11Y-002" - name: "Color Contrast" + - 'User can complete onboarding using only screen reader' + + - id: 'A11Y-002' + name: 'Color Contrast' verify: - - "Text on background: 4.5:1 minimum (WCAG AA)" - - "Button text on button background: 4.5:1 minimum" - - "Error text on background: 4.5:1 minimum" - + - 'Text on background: 4.5:1 minimum (WCAG AA)' + - 'Button text on button background: 4.5:1 minimum' + - 'Error text on background: 4.5:1 minimum' + tools: - - "Use contrast checker tool" - - "Test in grayscale mode" - - - id: "A11Y-003" - name: "Touch Targets" + - 'Use contrast checker tool' + - 'Test in grayscale mode' + + - id: 'A11Y-003' + name: 'Touch Targets' verify: - - "All buttons: 44×44px minimum" - - "All input fields: 44px height minimum" - - "Spacing between targets: 8px minimum" - + - 'All buttons: 44×44px minimum' + - 'All input fields: 44px height minimum' + - 'Spacing between targets: 8px minimum' + success_criteria: - - "All interactive elements are easily tappable" + - 'All interactive elements are easily tappable' ``` --- @@ -353,29 +356,29 @@ accessibility: ```yaml sign_off_criteria: required: - - "All happy path tests pass (100%)" - - "All error state tests pass (100%)" - - "All edge case tests pass (100%)" - - "Design system compliance > 95%" - - "All accessibility tests pass (100%)" - - "No critical or high severity issues" - + - 'All happy path tests pass (100%)' + - 'All error state tests pass (100%)' + - 'All edge case tests pass (100%)' + - 'Design system compliance > 95%' + - 'All accessibility tests pass (100%)' + - 'No critical or high severity issues' + metrics: - - name: "Onboarding Completion Rate" - target: "> 90%" - measurement: "Users who complete onboarding / Users who start" - - - name: "Time to Complete" - target: "< 2 minutes" - measurement: "Average time from app open to dashboard" - - - name: "User Satisfaction" - target: "> 4.5/5" - measurement: "Post-onboarding survey" - - - name: "Error Rate" - target: "< 5%" - measurement: "Users who encounter errors / Total users" + - name: 'Onboarding Completion Rate' + target: '> 90%' + measurement: 'Users who complete onboarding / Users who start' + + - name: 'Time to Complete' + target: '< 2 minutes' + measurement: 'Average time from app open to dashboard' + + - name: 'User Satisfaction' + target: '> 4.5/5' + measurement: 'Post-onboarding survey' + + - name: 'Error Rate' + target: '< 5%' + measurement: 'Users who encounter errors / Total users' ``` --- diff --git a/src/modules/wds/workflows/6-design-deliveries/steps/step-6.4-handoff-dialog.md b/src/modules/wds/workflows/6-design-deliveries/steps/step-6.4-handoff-dialog.md index 39740166..13f23944 100644 --- a/src/modules/wds/workflows/6-design-deliveries/steps/step-6.4-handoff-dialog.md +++ b/src/modules/wds/workflows/6-design-deliveries/steps/step-6.4-handoff-dialog.md @@ -9,6 +9,7 @@ Initiate a structured handoff conversation with the BMad Architect to transfer d ## Before You Start **Ensure you have:** + - ✅ Completed step 6.3 (Test Scenario created) - ✅ Design Delivery file ready: `deliveries/DD-XXX-name.yaml` - ✅ Test Scenario file ready: `test-scenarios/TS-XXX-name.yaml` @@ -23,6 +24,7 @@ Initiate a structured handoff conversation with the BMad Architect to transfer d **Duration:** 20-30 minutes **Participants:** + - WDS UX Expert (you) - BMad Architect @@ -33,19 +35,21 @@ Initiate a structured handoff conversation with the BMad Architect to transfer d ### Phase 1: Introduction (2 min) **You say:** + ``` "Hey Architect! I've completed the design for [Flow Name]. I'd like to walk you through Design Delivery DD-XXX. - + This delivery includes: - [Number] scenarios - [Number] components - Complete test scenarios - + Ready for the walkthrough?" ``` **Architect responds:** + ``` "Absolutely! Let's go through it." ``` @@ -74,6 +78,7 @@ This is critical because [business value]." ``` **Questions to answer:** + - Why does this flow matter? - What business value does it deliver? - How will we measure success? @@ -101,11 +106,13 @@ The complete flow is: ``` **Show:** + - Excalidraw sketches (if available) - Scenario specifications - User flow diagrams **Architect may ask:** + - "What happens if [edge case]?" - "How does this integrate with [existing feature]?" - "What's the data flow here?" @@ -144,6 +151,7 @@ Security: ``` **Architect may ask:** + - "Why this tech stack?" - "Are there any constraints?" - "What about [technical concern]?" @@ -179,6 +187,7 @@ All components follow our design tokens: ``` **Architect may ask:** + - "Do these components already exist?" - "Any new components needed?" - "What about [specific state]?" @@ -258,6 +267,7 @@ Does this align with your technical assessment?" ``` **Architect responds with their estimate:** + ``` "I'll break this into [number] epics: - Epic 1: [Name] ([time]) @@ -287,6 +297,7 @@ Questions or concerns?" ``` **Architect may raise:** + - Technical challenges - Integration concerns - Timeline issues @@ -333,6 +344,7 @@ You: "Perfect! I'll start designing the next flow while **Date:** 2024-12-09 **Duration:** 25 minutes **Participants:** + - WDS UX Expert: [Your name] - BMad Architect: Winston @@ -385,10 +397,10 @@ A: "Save progress, resume at last incomplete step" ```yaml delivery: - status: "in_development" # Changed from "ready" - handed_off_at: "2024-12-09T12:30:00Z" - assigned_to: "bmad-architect" - handoff_log: "deliveries/DD-XXX-handoff-log.md" + status: 'in_development' # Changed from "ready" + handed_off_at: '2024-12-09T12:30:00Z' + assigned_to: 'bmad-architect' + handoff_log: 'deliveries/DD-XXX-handoff-log.md' ``` --- diff --git a/src/modules/wds/workflows/6-design-deliveries/steps/step-6.5-hand-off.md b/src/modules/wds/workflows/6-design-deliveries/steps/step-6.5-hand-off.md index 3e9043dc..9925240a 100644 --- a/src/modules/wds/workflows/6-design-deliveries/steps/step-6.5-hand-off.md +++ b/src/modules/wds/workflows/6-design-deliveries/steps/step-6.5-hand-off.md @@ -9,6 +9,7 @@ Officially hand off the Design Delivery to BMad and confirm they have everything ## Before You Start **Ensure you have:** + - ✅ Completed step 6.4 (Handoff dialog complete) - ✅ Handoff log documented - ✅ Delivery status updated to "in_development" @@ -20,27 +21,32 @@ Officially hand off the Design Delivery to BMad and confirm they have everything ### Verify BMad Has All Artifacts **Design Delivery:** + - [ ] File exists: `deliveries/DD-XXX-name.yaml` - [ ] Status: "in_development" - [ ] Handed off timestamp recorded - [ ] Assigned to BMad Architect **Test Scenario:** + - [ ] File exists: `test-scenarios/TS-XXX-name.yaml` - [ ] All tests defined - [ ] Sign-off criteria clear **Scenario Specifications:** + - [ ] All scenarios in `C-Scenarios/` are complete - [ ] All specifications are up-to-date - [ ] All design references are valid **Design System:** + - [ ] All components in `D-Design-System/` are defined - [ ] Design tokens are documented - [ ] Component specifications are complete **Handoff Log:** + - [ ] File exists: `deliveries/DD-XXX-handoff-log.md` - [ ] All key points documented - [ ] Epic breakdown recorded @@ -136,6 +142,7 @@ BMad Architect ## In Progress ### DD-XXX: [Flow Name] + - Status: In Development - Assigned: BMad Architect - Started: 2024-12-09 @@ -146,6 +153,7 @@ BMad Architect ## Next Up ### DD-XXX+1: [Next Flow Name] + - Status: In Design - Phase: 4-5 (UX Design & Design System) - Designer: Working on scenarios @@ -159,17 +167,20 @@ BMad Architect **Track progress:** **Weekly check-ins:** + - Schedule brief sync with BMad Architect - Review progress - Answer questions - Unblock issues **Communication channel:** + - Slack/Teams channel: #dd-xxx-implementation - Quick questions welcome - Async updates appreciated **Milestone notifications:** + - Epic 1 complete → Notify designer - Epic 2 complete → Notify designer - All epics complete → Ready for validation (Touch Point 3) @@ -207,12 +218,14 @@ I want this to succeed!" ### BMad's Work (Phases 3-4) **Phase 3: Architecture** + - Create architecture document - Define technical approach - Identify dependencies - Plan implementation **Phase 4: Implementation** + - Break down into dev stories - Implement features - Write tests @@ -227,6 +240,7 @@ I want this to succeed!" **While BMad builds this flow, you design the next one!** **Return to Phase 4-5:** + - Design next complete testable flow - Create specifications - Define components @@ -274,16 +288,19 @@ After confirming handoff: ### DO ✅ **Be available:** + - Answer questions promptly - Unblock issues quickly - Provide clarifications **Be collaborative:** + - "How can I help?" - "Let's figure this out together" - "I'm here if you need me" **Be flexible:** + - Adjust design if technical constraints arise - Find creative solutions - Focus on user value, not ego @@ -291,14 +308,17 @@ After confirming handoff: ### DON'T ❌ **Don't disappear:** + - "I handed it off, not my problem anymore" ❌ - Stay engaged throughout implementation **Don't be rigid:** + - "It must be exactly like this" ❌ - Be open to technical suggestions **Don't ignore questions:** + - Respond within 24 hours - If you don't know, say so and find out diff --git a/src/modules/wds/workflows/6-design-deliveries/steps/step-6.6-continue.md b/src/modules/wds/workflows/6-design-deliveries/steps/step-6.6-continue.md index 7b36472d..cfe8552b 100644 --- a/src/modules/wds/workflows/6-design-deliveries/steps/step-6.6-continue.md +++ b/src/modules/wds/workflows/6-design-deliveries/steps/step-6.6-continue.md @@ -33,12 +33,14 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 **What's the next most valuable flow to design?** **Prioritization criteria:** + 1. **User value:** What solves the biggest user problem? 2. **Business value:** What delivers the most ROI? 3. **Dependencies:** What needs to be built next? 4. **Risk:** What's the riskiest to validate early? **Example prioritization:** + ``` ✅ Flow 1: Login & Onboarding (DONE - in development) → Flow 2: Morning Dog Care (NEXT - highest user value) @@ -114,6 +116,7 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 - ✅ No blockers or dependencies **Then repeat Phase 6:** + - 6.1: Detect completion - 6.2: Create Design Delivery - 6.3: Create Test Scenario @@ -133,23 +136,27 @@ Week 4: Handoff Flow 3 → BMad builds Flow 3 # Design Deliveries Tracker ## DD-001: Login & Onboarding + - Status: In Development (BMad) - Handed off: 2024-12-09 - Expected completion: 2024-12-30 - Next: Validation (Phase 7) ## DD-002: Morning Dog Care + - Status: In Design (WDS) - Phase: 4 (UX Design) - Progress: 3/5 scenarios complete - Expected handoff: 2024-12-16 ## DD-003: Calendar View + - Status: Not Started - Priority: Medium - Planned start: 2024-12-20 ## DD-004: Family Chat + - Status: Not Started - Priority: Low - Planned start: TBD @@ -195,10 +202,12 @@ Questions or blockers on DD-001?" ### Week 3 Example **Monday-Tuesday:** + - Test DD-001 (Phase 7) - Create issues if needed **Wednesday-Friday:** + - Design DD-003 scenarios - Define DD-003 components @@ -213,17 +222,20 @@ Questions or blockers on DD-001?" ### After Each Handoff **Reflect:** + - What went well? - What was unclear? - What questions did BMad ask? - How can I improve next delivery? **Update templates:** + - Add missing fields - Clarify confusing sections - Improve examples **Update process:** + - Streamline handoff dialog - Better test scenarios - Clearer specifications diff --git a/src/modules/wds/workflows/7-testing/steps/step-7.1-receive-notification.md b/src/modules/wds/workflows/7-testing/steps/step-7.1-receive-notification.md index 181e81a7..a684df55 100644 --- a/src/modules/wds/workflows/7-testing/steps/step-7.1-receive-notification.md +++ b/src/modules/wds/workflows/7-testing/steps/step-7.1-receive-notification.md @@ -12,20 +12,20 @@ BMad has notified you that a feature is complete and ready for designer validati ``` BMad Developer: "Feature complete: DD-XXX [Flow Name] - + Implemented: ✓ All [number] scenarios ✓ All error states ✓ All edge cases ✓ Design system components - + Build: v0.1.0-beta.1 Environment: Staging Device: [Platform details] - + Ready for designer validation. Test scenario: test-scenarios/TS-XXX.yaml - + Please validate and let me know if any issues." ``` @@ -37,14 +37,15 @@ BMad Developer: "Feature complete: DD-XXX [Flow Name] ``` WDS Designer: "Received! Starting validation testing for DD-XXX. - + I'll run through test scenario TS-XXX and report back within [timeframe]. - + Thanks for the notification!" ``` **Set expectations:** + - Small flow: "Will complete testing today" - Medium flow: "Will complete testing within 2 days" - Large flow: "Will complete testing within 1 week" @@ -82,11 +83,11 @@ WDS Designer: "Received! Starting validation testing for DD-XXX. ``` WDS Designer: "Quick question before I start testing: - + - What's the staging URL? - Do I need login credentials? - Which device should I test on? - + Thanks!" ``` @@ -99,18 +100,22 @@ WDS Designer: "Quick question before I start testing: **Block time for testing:** ### Small Flow (1-2 scenarios) + - **Time needed:** 2-4 hours - **Schedule:** Same day or next day ### Medium Flow (3-5 scenarios) + - **Time needed:** 1-2 days - **Schedule:** Within 2 days ### Large Flow (6+ scenarios) + - **Time needed:** 3-5 days - **Schedule:** Within 1 week **Add buffer for:** + - Finding issues - Creating issue tickets - Writing test report @@ -136,6 +141,7 @@ WDS Designer: "Quick question before I start testing: **Test Scenario:** test-scenarios/TS-XXX.yaml **Progress:** + - [ ] Happy path tests - [ ] Error state tests - [ ] Edge case tests @@ -154,11 +160,11 @@ WDS Designer: "Quick question before I start testing: ``` WDS Designer: "Testing update for DD-XXX: - + Started: Today 2pm Progress: Running happy path tests Expected completion: Tomorrow 5pm - + Will notify you when complete!" ``` @@ -166,13 +172,13 @@ WDS Designer: "Testing update for DD-XXX: ``` WDS Designer: "Quick heads up on DD-XXX: - + Found critical issue in first test: - Login button not working - + Continuing testing to find all issues, but wanted to give you early warning. - + Full report coming tomorrow." ``` @@ -215,17 +221,20 @@ After acknowledging receipt and scheduling: ### DO ✅ **Respond quickly:** + - Acknowledge within 24 hours - Set clear expectations - Schedule testing time **Verify everything:** + - Build details - Access credentials - Test scenarios - Design artifacts **Communicate proactively:** + - Keep BMad informed - Report early if critical issues - Set realistic timelines @@ -233,14 +242,17 @@ After acknowledging receipt and scheduling: ### DON'T ❌ **Don't delay:** + - Respond within 24 hours - Don't make BMad wait **Don't start unprepared:** + - Verify you have everything - Don't waste time searching for files **Don't go silent:** + - Keep BMad updated - Don't disappear during testing diff --git a/src/modules/wds/workflows/7-testing/steps/step-7.2-prepare-testing.md b/src/modules/wds/workflows/7-testing/steps/step-7.2-prepare-testing.md index 633745e3..e05932af 100644 --- a/src/modules/wds/workflows/7-testing/steps/step-7.2-prepare-testing.md +++ b/src/modules/wds/workflows/7-testing/steps/step-7.2-prepare-testing.md @@ -9,6 +9,7 @@ Gather all materials and set up your testing environment before starting validat ## Before You Start **Ensure you have:** + - ✅ Completed step 7.1 (notification received) - ✅ Testing time scheduled - ✅ Build information verified @@ -20,12 +21,14 @@ Gather all materials and set up your testing environment before starting validat ### Test Scenario **Load test scenario file:** + - File: `test-scenarios/TS-XXX.yaml` - Review all test cases - Understand success criteria - Note any special setup needed **Print or display:** + - Have test scenario visible while testing - Check off tests as you complete them - Take notes on deviations @@ -35,6 +38,7 @@ Gather all materials and set up your testing environment before starting validat ### Design Delivery **Load Design Delivery file:** + - File: `deliveries/DD-XXX.yaml` - Review user value and success criteria - Review acceptance criteria @@ -45,12 +49,14 @@ Gather all materials and set up your testing environment before starting validat ### Scenario Specifications **Load all scenario specs:** + - Directory: `C-Scenarios/` - Review each scenario specification - Note design details - Understand expected behavior **Example:** + ``` C-Scenarios/ ├── 01-welcome/Frontend/specifications.md @@ -64,12 +70,14 @@ C-Scenarios/ ### Design System Specs **Load design system specs:** + - Directory: `D-Design-System/` - Review component specifications - Review design tokens - Note exact colors, sizes, spacing **Example:** + ``` D-Design-System/ ├── 02-Foundation/ @@ -89,11 +97,13 @@ D-Design-System/ ### Access the Build **Staging environment:** + - URL: [Staging URL] - Credentials: [Username/Password] - Platform: [iOS/Android/Web] **Install build (if needed):** + ```bash # iOS TestFlight - Open TestFlight app @@ -113,12 +123,14 @@ D-Design-System/ ### Prepare Test Devices **Primary device:** + - [ ] Device charged (>80%) - [ ] Connected to WiFi - [ ] Screen recording enabled - [ ] Screenshot tools ready **Secondary device (if needed):** + - [ ] Different platform (iOS vs Android) - [ ] Different screen size - [ ] Different OS version @@ -128,20 +140,24 @@ D-Design-System/ ### Set Up Tools **Screen recording:** + - [ ] QuickTime (Mac) - [ ] Built-in screen recorder (iOS/Android) - [ ] OBS Studio (Desktop) **Screenshot tools:** + - [ ] Native screenshot (Command+Shift+4) - [ ] Annotate screenshots (Preview, Skitch) **Note-taking:** + - [ ] Markdown editor open - [ ] Test tracking document ready - [ ] Issue template ready **Accessibility tools:** + - [ ] VoiceOver (iOS) or TalkBack (Android) - [ ] Color contrast checker - [ ] Zoom/magnification @@ -151,6 +167,7 @@ D-Design-System/ ## Prepare Test Data **Create test accounts:** + ``` Test User 1: - Email: test1@example.com @@ -169,6 +186,7 @@ Test User 3: ``` **Prepare test data:** + - [ ] Valid emails - [ ] Invalid emails (for error testing) - [ ] Strong passwords @@ -181,6 +199,7 @@ Test User 3: ## Create Testing Workspace **File structure:** + ``` testing/DD-XXX/ ├── screenshots/ @@ -195,6 +214,7 @@ testing/DD-XXX/ ``` **Create directories:** + ```bash mkdir -p testing/DD-XXX/screenshots mkdir -p testing/DD-XXX/screen-recordings @@ -209,26 +229,31 @@ touch testing/DD-XXX/issues-found.md **Understand what you're testing:** ### Happy Path Tests + - [ ] [Number] tests defined - [ ] Understand each test flow - [ ] Know expected results ### Error State Tests + - [ ] [Number] tests defined - [ ] Understand error scenarios - [ ] Know expected error messages ### Edge Case Tests + - [ ] [Number] tests defined - [ ] Understand unusual scenarios - [ ] Know expected behavior ### Design System Validation + - [ ] [Number] components to check - [ ] Know exact specifications - [ ] Have design tokens ready ### Accessibility Tests + - [ ] Screen reader testing - [ ] Color contrast checking - [ ] Touch target verification @@ -334,15 +359,18 @@ After preparation is complete: ### DO ✅ **Be thorough:** + - Gather everything before starting - Don't interrupt testing to find files **Be organized:** + - Create workspace structure - Name files clearly - Take notes as you go **Be realistic:** + - Estimate time accurately - Add buffer for issues - Block calendar time @@ -350,15 +378,18 @@ After preparation is complete: ### DON'T ❌ **Don't rush:** + - Take time to prepare properly - Don't skip setup steps **Don't improvise:** + - Follow test scenario - Use prepared test data - Stick to the plan **Don't forget tools:** + - Screen recording is critical - Screenshots document issues - Notes capture details diff --git a/src/modules/wds/workflows/7-testing/steps/step-7.3-run-tests.md b/src/modules/wds/workflows/7-testing/steps/step-7.3-run-tests.md index c0cadbd0..4c1e8da5 100644 --- a/src/modules/wds/workflows/7-testing/steps/step-7.3-run-tests.md +++ b/src/modules/wds/workflows/7-testing/steps/step-7.3-run-tests.md @@ -9,6 +9,7 @@ Execute all test scenarios defined in the test scenario file and document result ## Before You Start **Ensure you have:** + - ✅ Completed step 7.2 (preparation complete) - ✅ Test scenario file open - ✅ Environment accessible @@ -27,6 +28,7 @@ Execute all test scenarios defined in the test scenario file and document result 5. **Accessibility Tests** **Why this order?** + - Happy path must work first - Errors and edge cases build on happy path - Design system and accessibility are final polish @@ -41,12 +43,12 @@ Execute all test scenarios defined in the test scenario file and document result ```yaml happy_path: - - id: "HP-001" - name: "New User Complete Onboarding" + - id: 'HP-001' + name: 'New User Complete Onboarding' steps: - - action: "Open app" - expected: "Welcome screen appears" - design_ref: "C-Scenarios/01-welcome/Frontend/specifications.md" + - action: 'Open app' + expected: 'Welcome screen appears' + design_ref: 'C-Scenarios/01-welcome/Frontend/specifications.md' ``` --- @@ -73,6 +75,7 @@ happy_path: - Note any differences 5. **Mark as Pass or Fail** + ``` ✓ PASS: Matches expected result ✗ FAIL: Doesn't match expected result @@ -84,22 +87,26 @@ happy_path: - Save with clear name: `HP-001-step-3-FAIL.png` 7. **Document in notes** + ```markdown ## HP-001: New User Complete Onboarding - + ### Step 1: Open app + - Action: Opened app - Expected: Welcome screen appears - Actual: Welcome screen appears ✓ - Result: PASS - + ### Step 2: Tap "Get Started" + - Action: Tapped "Get Started" button - Expected: Login/Signup choice appears - Actual: Login/Signup choice appears ✓ - Result: PASS - + ### Step 3: Tap "Create Account" + - Action: Tapped "Create Account" - Expected: Signup form with smooth 300ms transition - Actual: Signup form appears instantly (no transition) @@ -118,6 +125,7 @@ happy_path: # Happy Path Test Results ## HP-001: New User Complete Onboarding + - Status: FAIL - Steps: 9 total - Passed: 8/9 (89%) @@ -127,6 +135,7 @@ happy_path: - Recording: happy-path-HP-001.mov ## HP-002: Returning User Login + - Status: PASS - Steps: 5 total - Passed: 5/5 (100%) @@ -136,6 +145,7 @@ happy_path: - Recording: happy-path-HP-002.mov ## Summary + - Total Tests: 2 - Passed: 1/2 (50%) - Failed: 1/2 (50%) @@ -152,10 +162,10 @@ happy_path: ```yaml error_states: - - id: "ES-001" - name: "Email Already Exists" + - id: 'ES-001' + name: 'Email Already Exists' steps: - - action: "Enter existing email" + - action: 'Enter existing email' - action: "Tap 'Create Account'" - expected: "Error message: 'This email is already registered...'" ``` @@ -187,9 +197,10 @@ error_states: - Verify recovery options 5. **Document results** + ```markdown ## ES-001: Email Already Exists - + - Setup: Used test2@example.com (existing account) - Action: Entered email, tapped "Create Account" - Expected: Error: "This email is already registered. Try logging in instead." @@ -207,24 +218,29 @@ error_states: # Error State Test Results ## ES-001: Email Already Exists + - Status: FAIL - Issue: Error message too brief - Severity: Medium ## ES-002: Invalid Email Format + - Status: PASS - Real-time validation works correctly ## ES-003: Weak Password + - Status: PASS - Password strength indicator works ## ES-004: Network Timeout + - Status: FAIL - Issue: No timeout handling, app hangs - Severity: High ## Summary + - Total Tests: 4 - Passed: 2/4 (50%) - Failed: 2/4 (50%) @@ -241,13 +257,13 @@ error_states: ```yaml edge_cases: - - id: "EC-001" - name: "User Closes App Mid-Onboarding" + - id: 'EC-001' + name: 'User Closes App Mid-Onboarding' steps: - - action: "Start onboarding, complete signup" - - action: "Close app (force quit)" - - action: "Reopen app" - - expected: "Resume at Family Setup" + - action: 'Start onboarding, complete signup' + - action: 'Close app (force quit)' + - action: 'Reopen app' + - expected: 'Resume at Family Setup' ``` --- @@ -271,9 +287,10 @@ edge_cases: - Is user experience smooth? 4. **Document results** + ```markdown ## EC-001: User Closes App Mid-Onboarding - + - Setup: Completed signup, at Family Setup screen - Action: Force quit app, reopened - Expected: Resume at Family Setup (progress saved) @@ -292,19 +309,23 @@ edge_cases: # Edge Case Test Results ## EC-001: User Closes App Mid-Onboarding + - Status: FAIL - Issue: Progress not saved - Severity: High ## EC-002: User Navigates Back + - Status: PASS - Confirmation dialog works correctly ## EC-003: Very Long Family Name + - Status: PASS - Field truncates at 50 characters ## Summary + - Total Tests: 3 - Passed: 2/3 (67%) - Failed: 1/3 (33%) @@ -321,16 +342,16 @@ edge_cases: ```yaml design_system_checks: - - id: "DS-001" - name: "Button Components" + - id: 'DS-001' + name: 'Button Components' checks: - - component: "Primary Button" - instances: ["Get Started", "Create Account"] + - component: 'Primary Button' + instances: ['Get Started', 'Create Account'] verify: - - "Height: 48px" - - "Background: #2563EB" - - "Text: #FFFFFF" - - "Typography: 16px, semibold" + - 'Height: 48px' + - 'Background: #2563EB' + - 'Text: #FFFFFF' + - 'Typography: 16px, semibold' ``` --- @@ -371,10 +392,12 @@ design_system_checks: - Focus state 7. **Document results** + ```markdown ## DS-001: Button Components - + ### Primary Button: "Get Started" + - Height: 48px ✓ - Background: #3B82F6 ✗ (Expected: #2563EB) - Text: #FFFFFF ✓ @@ -383,8 +406,9 @@ design_system_checks: - Padding: 12px 24px ✓ - Result: FAIL (wrong background color) - Screenshot: DS-001-button-color-FAIL.png - + ### Primary Button: "Create Account" + - Height: 48px ✓ - Background: #3B82F6 ✗ (Expected: #2563EB) - Text: #FFFFFF ✓ @@ -400,21 +424,25 @@ design_system_checks: # Design System Validation Results ## DS-001: Button Components + - Status: FAIL - Issue: Primary button color incorrect (#3B82F6 vs #2563EB) - Instances: All primary buttons affected - Severity: High ## DS-002: Input Components + - Status: PASS - All input fields match specifications ## DS-003: Spacing and Layout + - Status: PASS - Screen padding: 20px ✓ - Element spacing: 16px ✓ ## Summary + - Total Components: 3 types - Compliant: 2/3 (67%) - Non-compliant: 1/3 (33%) @@ -429,6 +457,7 @@ design_system_checks: ### Screen Reader Testing **Enable screen reader:** + - iOS: VoiceOver (Settings → Accessibility) - Android: TalkBack (Settings → Accessibility) @@ -452,19 +481,21 @@ design_system_checks: - Are they clear? 5. **Document results** + ```markdown ## A11Y-001: Screen Reader Navigation - + - Setup: Enabled VoiceOver on iOS - Test: Navigated through onboarding - Result: PARTIAL PASS - + Issues: + - "Get Started" button announced as just "Button" ✗ - Email field announced correctly ✓ - Password field announced correctly ✓ - Error messages not announced ✗ - + Severity: Medium ``` @@ -485,14 +516,15 @@ design_system_checks: - Error text on background: 4.5:1 minimum 4. **Document results** + ```markdown ## A11Y-002: Color Contrast - + - Body text on white: 7.2:1 ✓ (PASS) - Button text on primary: 5.1:1 ✓ (PASS) - Error text on white: 4.8:1 ✓ (PASS) - Link text on white: 3.9:1 ✗ (FAIL - below 4.5:1) - + Result: FAIL (link contrast too low) ``` @@ -515,14 +547,15 @@ design_system_checks: - Measure actual spacing 4. **Document results** + ```markdown ## A11Y-003: Touch Targets - + - Primary buttons: 48×120px ✓ (PASS) - Input fields: 48px height ✓ (PASS) - Text links: 32px height ✗ (FAIL - below 44px) - Spacing between buttons: 16px ✓ (PASS) - + Result: FAIL (text links too small) ``` @@ -534,21 +567,25 @@ design_system_checks: # Accessibility Test Results ## A11Y-001: Screen Reader Navigation + - Status: PARTIAL PASS - Issues: 2 (button labels, error announcements) - Severity: Medium ## A11Y-002: Color Contrast + - Status: FAIL - Issue: Link contrast too low (3.9:1) - Severity: Medium ## A11Y-003: Touch Targets + - Status: FAIL - Issue: Text links too small (32px) - Severity: Low ## Summary + - Total Tests: 3 - Passed: 0/3 (0%) - Partial: 1/3 (33%) @@ -587,12 +624,14 @@ design_system_checks: **Total Issues:** 8 **By Severity:** + - Critical: 0 - High: 3 - Medium: 3 - Low: 2 **By Category:** + - Functionality: 3 - Design System: 1 - Accessibility: 4 diff --git a/src/modules/wds/workflows/7-testing/steps/step-7.4-create-issues.md b/src/modules/wds/workflows/7-testing/steps/step-7.4-create-issues.md index f15fcf84..4d0d56e1 100644 --- a/src/modules/wds/workflows/7-testing/steps/step-7.4-create-issues.md +++ b/src/modules/wds/workflows/7-testing/steps/step-7.4-create-issues.md @@ -9,6 +9,7 @@ Document all problems found during testing as issue tickets that BMad can fix. ## Before You Start **Ensure you have:** + - ✅ Completed step 7.3 (all tests executed) - ✅ Test results documented - ✅ Screenshots captured @@ -23,6 +24,7 @@ Document all problems found during testing as issue tickets that BMad can fix. **Create issue file:** `issues/ISS-XXX-description.md` **Numbering:** + - Start at ISS-001 - Increment for each issue - Use leading zeros @@ -31,7 +33,7 @@ Document all problems found during testing as issue tickets that BMad can fix. ## Issue Template -```markdown +````markdown # Issue: [Short Description] **ID:** ISS-XXX @@ -81,6 +83,7 @@ Document all problems found during testing as issue tickets that BMad can fix. ```code [Code example if applicable] ``` +```` ## Related Issues @@ -89,7 +92,8 @@ Document all problems found during testing as issue tickets that BMad can fix. --- **Priority for fix:** [Next release | This release | Future] -``` + +```` --- @@ -207,12 +211,13 @@ Add transition animation to navigation: animationDuration: 300, }} /> -``` +```` --- **Priority for fix:** This release -``` + +```` --- @@ -272,9 +277,10 @@ backgroundColor: '#3B82F6' // After backgroundColor: tokens.button.primary.background // #2563EB -``` +```` Affected components: + - "Get Started" button - "Create Account" button - "Continue" button @@ -283,7 +289,8 @@ Affected components: --- **Priority for fix:** This release (High severity) -``` + +```` --- @@ -351,16 +358,18 @@ Add accessibility labels to all buttons: accessibilityLabel="Create Account button" accessibilityHint="Opens signup form" /> -``` +```` Affected buttons: + - All buttons in onboarding flow - Estimate: 8 buttons total --- **Priority for fix:** This release (Accessibility blocker) -``` + +```` --- @@ -425,7 +434,7 @@ None **Can fix later:** - ISS-007 (Low) - ISS-008 (Low) -``` +```` --- @@ -468,16 +477,19 @@ After creating all issue tickets: ### DO ✅ **Be specific:** + - Clear descriptions - Exact values (colors, sizes) - Precise steps to reproduce **Be helpful:** + - Provide recommendations - Include code examples - Link to design references **Be organized:** + - Consistent numbering - Clear file names - Issues list for tracking @@ -485,14 +497,17 @@ After creating all issue tickets: ### DON'T ❌ **Don't be vague:** + - "It doesn't look right" ❌ - "Button color is #3B82F6, should be #2563EB" ✅ **Don't blame:** + - Focus on the issue, not the person - Be collaborative, not critical **Don't skip documentation:** + - Every issue needs full documentation - Screenshots are required - Design references are required diff --git a/src/modules/wds/workflows/7-testing/steps/step-7.5-create-report.md b/src/modules/wds/workflows/7-testing/steps/step-7.5-create-report.md index 6645d081..770f648f 100644 --- a/src/modules/wds/workflows/7-testing/steps/step-7.5-create-report.md +++ b/src/modules/wds/workflows/7-testing/steps/step-7.5-create-report.md @@ -9,6 +9,7 @@ Create a comprehensive test report summarizing all testing results. ## Before You Start **Ensure you have:** + - ✅ Completed step 7.4 (all issues created) - ✅ Test results compiled - ✅ Issues list created @@ -53,24 +54,28 @@ Create a comprehensive test report summarizing all testing results. ## Test Coverage ### Happy Path Tests + - **Total:** [number] tests - **Passed:** [number]/[total] ([percentage]%) - **Failed:** [number]/[total] ([percentage]%) - **Status:** [PASS | FAIL] ### Error State Tests + - **Total:** [number] tests - **Passed:** [number]/[total] ([percentage]%) - **Failed:** [number]/[total] ([percentage]%) - **Status:** [PASS | FAIL] ### Edge Case Tests + - **Total:** [number] tests - **Passed:** [number]/[total] ([percentage]%) - **Failed:** [number]/[total] ([percentage]%) - **Status:** [PASS | FAIL] ### Design System Validation + - **Components Checked:** [number] - **Compliant:** [number]/[total] ([percentage]%) - **Non-compliant:** [number]/[total] ([percentage]%) @@ -78,6 +83,7 @@ Create a comprehensive test report summarizing all testing results. - **Status:** [PASS | FAIL] ### Accessibility Tests + - **Total:** [number] tests - **Passed:** [number]/[total] ([percentage]%) - **Failed:** [number]/[total] ([percentage]%) @@ -90,12 +96,14 @@ Create a comprehensive test report summarizing all testing results. **Total Issues:** [number] ### By Severity + - **Critical:** [number] - **High:** [number] - **Medium:** [number] - **Low:** [number] ### By Category + - **Functionality:** [number] - **Design System:** [number] - **Accessibility:** [number] @@ -104,11 +112,13 @@ Create a comprehensive test report summarizing all testing results. ### Issue List #### Critical Issues (0) + None #### High Severity Issues ([number]) **ISS-XXX: [Issue Title]** + - **Category:** [Functionality | Design System | Accessibility] - **Impact:** [Brief impact description] - **Status:** Open @@ -119,6 +129,7 @@ None #### Medium Severity Issues ([number]) **ISS-XXX: [Issue Title]** + - **Category:** [Category] - **Impact:** [Brief impact] - **Status:** Open @@ -129,6 +140,7 @@ None #### Low Severity Issues ([number]) **ISS-XXX: [Issue Title]** + - **Category:** [Category] - **Impact:** [Brief impact] - **Status:** Open @@ -143,6 +155,7 @@ None ### Happy Path Tests **HP-001: [Test Name]** + - **Status:** [PASS | FAIL] - **Steps:** [number] total - **Passed:** [number]/[total] @@ -156,6 +169,7 @@ None ### Error State Tests **ES-001: [Test Name]** + - **Status:** [PASS | FAIL] - **Expected Behavior:** [Description] - **Actual Behavior:** [Description] @@ -166,6 +180,7 @@ None ### Edge Case Tests **EC-001: [Test Name]** + - **Status:** [PASS | FAIL] - **Scenario:** [Description] - **Result:** [Description] @@ -176,6 +191,7 @@ None ### Design System Validation **DS-001: [Component Name]** + - **Instances Checked:** [number] - **Compliant:** [number]/[total] - **Issues:** [List issue IDs if any] @@ -186,6 +202,7 @@ None ### Accessibility Tests **A11Y-001: [Test Name]** + - **Status:** [PASS | FAIL] - **Standard:** WCAG 2.1 AA - **Result:** [Description] @@ -198,11 +215,13 @@ None ## What Worked Well ### Strengths + - [Positive observation 1] - [Positive observation 2] - [Positive observation 3] ### Highlights + - [Specific thing that exceeded expectations] - [Specific thing that worked perfectly] @@ -211,11 +230,13 @@ None ## What Needs Improvement ### Areas of Concern + - [Issue category 1]: [Brief description] - [Issue category 2]: [Brief description] - [Issue category 3]: [Brief description] ### Recommendations + 1. [Specific recommendation 1] 2. [Specific recommendation 2] 3. [Specific recommendation 3] @@ -225,16 +246,19 @@ None ## Metrics ### Performance Metrics + - **Average screen load time:** [time] - **Form submission time:** [time] - **Animation frame rate:** [fps] ### User Experience Metrics + - **Flow completion time:** [time] - **Number of taps:** [number] - **Error rate:** [percentage]% ### Quality Metrics + - **Test pass rate:** [percentage]% - **Design system compliance:** [percentage]% - **Accessibility compliance:** [percentage]% @@ -244,6 +268,7 @@ None ## Sign-Off Criteria ### Required for Approval + - [ ] All critical tests pass - [ ] No critical or high severity issues - [ ] Design system compliance > 95% @@ -251,6 +276,7 @@ None - [ ] All acceptance criteria met ### Current Status + - **Critical tests:** [PASS | FAIL] - **Critical/High issues:** [number] found - **Design system compliance:** [percentage]% @@ -267,6 +293,7 @@ None [Detailed explanation of recommendation] **Next Steps:** + 1. [Step 1] 2. [Step 2] 3. [Step 3] @@ -278,11 +305,13 @@ None **Retest:** [YES | NO] **If YES:** + - **Issues to fix:** [List critical/high issues] - **Expected fix time:** [Estimate] - **Retest date:** [Date] **If NO:** + - **Approval:** Ready to ship ✅ - **Sign-off:** [Your name], [Date] @@ -291,17 +320,21 @@ None ## Attachments ### Screenshots + - [Link to screenshots folder] - Total screenshots: [number] ### Screen Recordings + - [Link to recordings folder] - Total recordings: [number] ### Test Data + - [Link to test data used] ### Issue Tickets + - [Link to issues folder] - Total issues: [number] @@ -316,7 +349,7 @@ None **Report prepared by:** [Your name] **Role:** WDS Designer **Date:** 2024-12-09 -**Signature:** ________________ +**Signature:** **\*\***\_\_\_\_**\*\*** ``` --- @@ -366,16 +399,19 @@ After creating the test report: ### DO ✅ **Be comprehensive:** + - Include all test results - Document everything - Provide context **Be clear:** + - Executive summary first - Clear recommendation - Specific next steps **Be professional:** + - Objective tone - Data-driven - Constructive feedback @@ -383,16 +419,19 @@ After creating the test report: ### DON'T ❌ **Don't be vague:** + - Provide specific numbers - Reference exact issues - Give clear recommendations **Don't sugarcoat:** + - Be honest about issues - Don't hide problems - Be direct but professional **Don't skip sections:** + - Complete all sections - Even if "no issues" - Document everything diff --git a/src/modules/wds/workflows/7-testing/steps/step-7.6-send-to-bmad.md b/src/modules/wds/workflows/7-testing/steps/step-7.6-send-to-bmad.md index 4a8f9dab..bd950572 100644 --- a/src/modules/wds/workflows/7-testing/steps/step-7.6-send-to-bmad.md +++ b/src/modules/wds/workflows/7-testing/steps/step-7.6-send-to-bmad.md @@ -9,6 +9,7 @@ Send test results, issues, and test report to BMad for fixes. ## Before You Start **Ensure you have:** + - ✅ Completed step 7.5 (test report created) - ✅ All issues documented - ✅ Test report finalized @@ -21,6 +22,7 @@ Send test results, issues, and test report to BMad for fixes. ### Gather All Artifacts **Checklist:** + - [ ] Test report: `test-reports/TR-XXX-YYYY-MM-DD.md` - [ ] Issues list: `issues/issues-list.md` - [ ] Individual issue files: `issues/ISS-XXX-*.md` @@ -274,11 +276,11 @@ BMad Developer ```yaml delivery: - status: "in_testing" # Changed from "in_development" - tested_at: "2024-12-09T16:00:00Z" - test_result: "fail" + status: 'in_testing' # Changed from "in_development" + tested_at: '2024-12-09T16:00:00Z' + test_result: 'fail' issues_found: 8 - test_report: "test-reports/TR-001-2024-12-09.md" + test_report: 'test-reports/TR-001-2024-12-09.md' retest_required: true ``` @@ -288,13 +290,13 @@ delivery: ```yaml delivery: - status: "complete" # Changed from "in_development" - tested_at: "2024-12-09T16:00:00Z" - test_result: "pass" + status: 'complete' # Changed from "in_development" + tested_at: '2024-12-09T16:00:00Z' + test_result: 'pass' issues_found: 0 - test_report: "test-reports/TR-001-2024-12-09.md" - approved_by: "[Your name]" - approved_at: "2024-12-09T16:00:00Z" + test_report: 'test-reports/TR-001-2024-12-09.md' + approved_by: '[Your name]' + approved_at: '2024-12-09T16:00:00Z' ready_for_production: true ``` @@ -305,21 +307,25 @@ delivery: ### DO ✅ **Be clear:** + - State result upfront (PASS/FAIL) - List issues by severity - Provide clear next steps **Be helpful:** + - Offer to clarify issues - Provide recommendations - Be available for questions **Be professional:** + - Objective tone - Data-driven feedback - Constructive criticism **Be appreciative:** + - Acknowledge good work - Highlight what worked well - Thank for collaboration @@ -327,19 +333,23 @@ delivery: ### DON'T ❌ **Don't be vague:** + - "Some issues found" ❌ - "8 issues found (3 high, 3 medium, 2 low)" ✅ **Don't be harsh:** + - "This is terrible" ❌ - "Found some issues that need fixing" ✅ **Don't disappear:** + - Send notification and stay available - Answer questions promptly - Be responsive **Don't delay:** + - Send results within 24 hours of completing testing - Don't make BMad wait diff --git a/src/modules/wds/workflows/7-testing/steps/step-7.7-iterate-or-approve.md b/src/modules/wds/workflows/7-testing/steps/step-7.7-iterate-or-approve.md index 5c0d03fe..46d86cd4 100644 --- a/src/modules/wds/workflows/7-testing/steps/step-7.7-iterate-or-approve.md +++ b/src/modules/wds/workflows/7-testing/steps/step-7.7-iterate-or-approve.md @@ -9,6 +9,7 @@ Either iterate with BMad to fix issues, or approve the feature for production. ## Before You Start **Ensure you have:** + - ✅ Completed step 7.6 (sent to BMad) - ✅ BMad acknowledged receipt - ✅ Clear on next steps @@ -20,6 +21,7 @@ Either iterate with BMad to fix issues, or approve the feature for production. ### Path A: Issues Found → Iterate **If test result was FAIL:** + - BMad fixes issues - You retest - Repeat until approved @@ -27,6 +29,7 @@ Either iterate with BMad to fix issues, or approve the feature for production. ### Path B: No Issues → Approve **If test result was PASS:** + - Feature approved - Ready for production - Phase 7 complete! @@ -41,17 +44,18 @@ Either iterate with BMad to fix issues, or approve the feature for production. ``` BMad Developer: "Working on fixes for DD-XXX. - + Progress: ✓ ISS-002: Button color fixed ✓ ISS-003: Button labels added ⏳ ISS-004: Progress save in progress ⏳ ISS-005: Network timeout handling in progress - + Will notify when all fixes complete." ``` **Your role during fixes:** + - Be available for questions - Clarify issues if needed - Review fixes if BMad requests early feedback @@ -64,7 +68,7 @@ BMad Developer: "Working on fixes for DD-XXX. ``` BMad Developer: "All issues fixed for DD-XXX! - + Fixed: ✓ ISS-002: Button color (now using design token) ✓ ISS-003: Button labels (accessibility improved) @@ -72,12 +76,12 @@ BMad Developer: "All issues fixed for DD-XXX! ✓ ISS-005: Network timeout (30s timeout + retry) ✓ ISS-001: Transition animation (300ms fade) ✓ ISS-006: Error message (more helpful) - + Low severity issues (ISS-007, ISS-008) moved to backlog. - + Build: v0.1.0-beta.2 Environment: Staging - + Ready for retest!" ``` @@ -88,32 +92,38 @@ BMad Developer: "All issues fixed for DD-XXX! **Run tests again:** **Focus on:** + 1. **Fixed issues** (verify they're actually fixed) 2. **Regression testing** (ensure fixes didn't break anything) 3. **Related areas** (check if fixes affected other parts) **Abbreviated testing:** + - Don't need to run ALL tests again - Focus on areas that were fixed - Spot-check other areas for regression **Example retest plan:** + ```markdown # Retest Plan: DD-XXX (v0.1.0-beta.2) ## Fixed Issues to Verify ### ISS-002: Button Color + - [ ] Check all primary buttons - [ ] Verify color is #2563EB - [ ] Check on all screens ### ISS-003: Button Labels + - [ ] Enable VoiceOver - [ ] Verify all buttons have descriptive labels - [ ] Check all interactive elements ### ISS-004: Progress Save + - [ ] Complete signup - [ ] Force quit app - [ ] Reopen app @@ -152,31 +162,37 @@ BMad Developer: "All issues fixed for DD-XXX! ## Fixed Issues Verification ### ISS-002: Button Color + - **Status:** FIXED ✅ - **Verification:** All primary buttons now use #2563EB - **Result:** PASS ### ISS-003: Button Labels + - **Status:** FIXED ✅ - **Verification:** VoiceOver announces descriptive labels - **Result:** PASS ### ISS-004: Progress Save + - **Status:** FIXED ✅ - **Verification:** App resumes at correct point after force quit - **Result:** PASS ### ISS-005: Network Timeout + - **Status:** FIXED ✅ - **Verification:** 30s timeout with retry button - **Result:** PASS ### ISS-001: Transition Animation + - **Status:** FIXED ✅ - **Verification:** 300ms fade transition working - **Result:** PASS ### ISS-006: Error Message + - **Status:** FIXED ✅ - **Verification:** Error message now helpful and actionable - **Result:** PASS @@ -186,14 +202,17 @@ BMad Developer: "All issues fixed for DD-XXX! ## Regression Testing ### Happy Path HP-001 + - **Status:** PASS ✅ - **No regressions detected** ### Error States + - **Status:** PASS ✅ - **No regressions detected** ### Design System + - **Compliance:** 98% (up from 67%) - **Status:** PASS ✅ @@ -315,12 +334,14 @@ Thanks, ### Step 6: Repeat Until Approved **Keep iterating:** + - BMad fixes issues - You retest - Report results - Repeat until all issues resolved **Typical iteration:** + ``` Round 1: 8 issues found Round 2: 2 new issues found (6 fixed) @@ -398,6 +419,7 @@ certify that: This feature is authorized for production deployment. **Next Steps:** + 1. Merge to main branch 2. Deploy to production 3. Monitor user feedback @@ -448,11 +470,11 @@ WDS Designer ```yaml delivery: - status: "complete" - approved_at: "2024-12-09T16:00:00Z" - approved_by: "[Your name]" + status: 'complete' + approved_at: '2024-12-09T16:00:00Z' + approved_by: '[Your name]' ready_for_production: true - sign_off_document: "deliveries/DD-XXX-sign-off.md" + sign_off_document: 'deliveries/DD-XXX-sign-off.md' ``` --- @@ -461,9 +483,9 @@ delivery: ```yaml delivery: - status: "in_testing" + status: 'in_testing' retest_count: 2 - last_retest_at: "2024-12-15T14:00:00Z" + last_retest_at: '2024-12-15T14:00:00Z' issues_remaining: 2 ``` @@ -480,6 +502,7 @@ delivery: ✅ Ready for production **What happens next:** + - BMad deploys to production - Feature goes live - Users start using it @@ -531,16 +554,19 @@ delivery: ### DO ✅ **Be patient:** + - Iteration is normal - Quality takes time - Don't rush approval **Be thorough:** + - Verify all fixes - Check for regressions - Don't skip retest **Be appreciative:** + - Acknowledge good work - Celebrate success - Thank the team @@ -548,20 +574,23 @@ delivery: ### DON'T ❌ **Don't approve prematurely:** + - All issues must be fixed - Quality standards must be met - Don't compromise **Don't iterate forever:** + - If stuck, discuss with team - Find pragmatic solutions - Know when "good enough" **Don't forget documentation:** + - Sign-off is required - Update delivery status - Document everything --- -**Remember:** Quality is the goal. Iterate until it's right, then celebrate success!** 🎉✨ +**Remember:** Quality is the goal. Iterate until it's right, then celebrate success!\*\* 🎉✨ diff --git a/src/modules/wds/workflows/7-testing/testing-guide.md b/src/modules/wds/workflows/7-testing/testing-guide.md index 0f860ed0..19c824f5 100644 --- a/src/modules/wds/workflows/7-testing/testing-guide.md +++ b/src/modules/wds/workflows/7-testing/testing-guide.md @@ -7,6 +7,7 @@ ## Purpose Phase 7 is where you: + 1. Wait for BMad to notify you that a feature is complete 2. Run test scenarios to validate implementation 3. Create issues if problems are found @@ -23,21 +24,22 @@ Phase 7 is where you: ``` BMad Developer: "Feature complete: DD-001 Login & Onboarding - + Implemented: ✓ All 4 scenarios ✓ All error states ✓ All edge cases ✓ Design system components - + Build: v0.1.0-beta.1 Device: Staging environment - + Ready for designer validation. Test scenario: test-scenarios/TS-001.yaml" ``` **You respond:** + ``` WDS Analyst: "Received! Starting validation testing..." ``` @@ -49,12 +51,14 @@ WDS Analyst: "Received! Starting validation testing..." ### Step 1: Prepare for Testing **Gather materials:** + - [ ] Test scenario file (TS-XXX.yaml) - [ ] Design Delivery file (DD-XXX.yaml) - [ ] Scenario specifications (C-Scenarios/) - [ ] Design system specs (D-Design-System/) **Set up environment:** + - [ ] Access to staging build - [ ] Test devices ready (iOS, Android, etc.) - [ ] Test data prepared @@ -69,15 +73,16 @@ WDS Analyst: "Received! Starting validation testing..." ```yaml happy_path: - - id: "HP-001" - name: "New User Complete Onboarding" + - id: 'HP-001' + name: 'New User Complete Onboarding' steps: - - action: "Open app" - expected: "Welcome screen appears" - design_ref: "C-Scenarios/01-welcome/Frontend/specifications.md" + - action: 'Open app' + expected: 'Welcome screen appears' + design_ref: 'C-Scenarios/01-welcome/Frontend/specifications.md' ``` **For each step:** + 1. Perform the action 2. Observe the result 3. Compare to expected result @@ -87,6 +92,7 @@ happy_path: 7. Note any deviations **Record results:** + ``` HP-001: New User Complete Onboarding ✓ Step 1: Open app → Welcome screen appears (PASS) @@ -106,15 +112,16 @@ HP-001: New User Complete Onboarding ```yaml error_states: - - id: "ES-001" - name: "Email Already Exists" + - id: 'ES-001' + name: 'Email Already Exists' steps: - - action: "Enter existing email" + - action: 'Enter existing email' - action: "Tap 'Create Account'" - expected: "Error message: 'This email is already registered...'" ``` **Verify:** + - Error messages are clear and helpful - Error states are visually distinct - Recovery options are provided @@ -128,16 +135,17 @@ error_states: ```yaml edge_cases: - - id: "EC-001" - name: "User Closes App Mid-Onboarding" + - id: 'EC-001' + name: 'User Closes App Mid-Onboarding' steps: - - action: "Start onboarding, complete signup" - - action: "Close app (force quit)" - - action: "Reopen app" - - expected: "Resume at Family Setup" + - action: 'Start onboarding, complete signup' + - action: 'Close app (force quit)' + - action: 'Reopen app' + - expected: 'Resume at Family Setup' ``` **Verify:** + - Edge cases are handled gracefully - No crashes or blank screens - User experience is smooth @@ -150,18 +158,19 @@ edge_cases: ```yaml design_system_checks: - - id: "DS-001" - name: "Button Components" + - id: 'DS-001' + name: 'Button Components' checks: - - component: "Primary Button" - instances: ["Get Started", "Create Account"] + - component: 'Primary Button' + instances: ['Get Started', 'Create Account'] verify: - - "Correct size (48px height)" - - "Correct color (primary brand color)" - - "Correct typography (16px, semibold)" + - 'Correct size (48px height)' + - 'Correct color (primary brand color)' + - 'Correct typography (16px, semibold)' ``` **Verify:** + - Components match design system specs - Colors are correct - Typography is correct @@ -176,16 +185,17 @@ design_system_checks: ```yaml accessibility: - - id: "A11Y-001" - name: "Screen Reader Navigation" - setup: "Enable VoiceOver (iOS) or TalkBack (Android)" + - id: 'A11Y-001' + name: 'Screen Reader Navigation' + setup: 'Enable VoiceOver (iOS) or TalkBack (Android)' verify: - - "All buttons have descriptive labels" - - "Form fields announce their purpose" - - "Error messages are announced" + - 'All buttons have descriptive labels' + - 'Form fields announce their purpose' + - 'Error messages are announced' ``` **Verify:** + - Screen reader can navigate - All interactive elements are accessible - Color contrast meets WCAG 2.1 AA @@ -200,7 +210,8 @@ accessibility: **File:** `issues/ISS-XXX-description.md` **Template:** -```markdown + +````markdown # Issue: Button Color Incorrect **ID:** ISS-001 @@ -210,34 +221,45 @@ accessibility: **Test:** TS-001, Check: DS-001 ## Description + Primary button color doesn't match design system specification. ## Expected + Primary button background: #2563EB (brand primary) ## Actual + Primary button background: #3B82F6 (lighter blue) ## Impact + Brand inconsistency, doesn't match design system ## Design Reference + - Design System: D-Design-System/03-Atomic-Components/Buttons/Button-Primary.md - Design Token: tokens/colors.json → "button.primary.background" ## Steps to Reproduce + 1. Open Login screen 2. Observe "Sign In" button color ## Screenshot + ![Button color issue](screenshots/ISS-001.png) ## Recommendation + Update button background color to use design token: + ```tsx -backgroundColor: tokens.button.primary.background // #2563EB -``` +backgroundColor: tokens.button.primary.background; // #2563EB ``` +```` + +```` **Severity levels:** - **Critical:** Blocks usage, must fix immediately @@ -300,7 +322,7 @@ backgroundColor: tokens.button.primary.background // #2563EB **Status:** NOT APPROVED **Reason:** High severity issue + design system compliance below threshold **Retest Required:** Yes -``` +```` --- @@ -310,23 +332,24 @@ backgroundColor: tokens.button.primary.background // #2563EB ``` WDS Analyst: "Testing complete for DD-001. - + Results: 2 issues found - ISS-001: Button color incorrect (HIGH) - ISS-002: Transition too fast (MEDIUM) - + Test report: test-reports/TR-001-2024-12-09.md Issues: issues/ISS-001.md, issues/ISS-002.md - + Please fix and notify when ready for retest." ``` **BMad responds:** + ``` BMad Developer: "Issues received. Fixing: - ISS-001: Button color - ISS-002: Transition speed - + Will notify when ready for retest." ``` @@ -335,6 +358,7 @@ BMad Developer: "Issues received. Fixing: ### Step 10: Iterate Until Approved **BMad fixes issues:** + ``` BMad Developer: "Issues fixed. Build: v0.1.0-beta.2 @@ -342,24 +366,27 @@ BMad Developer: "Issues fixed. ``` **You retest:** + - Run test scenarios again - Verify issues are fixed - Check for new issues - Update test report **If approved:** + ``` WDS Analyst: "Retest complete! - + All issues resolved. Design system compliance: 98% - + ✅ APPROVED - Ready to ship! - + Test report: test-reports/TR-001-2024-12-15.md" ``` **If not approved:** + - Create new issues - Send to BMad - Repeat until approved @@ -369,6 +396,7 @@ WDS Analyst: "Retest complete! ## Sign-Off Criteria **Required for approval:** + - [ ] All critical tests pass - [ ] No critical or high severity issues - [ ] Design system compliance > 95% @@ -377,6 +405,7 @@ WDS Analyst: "Retest complete! - [ ] All acceptance criteria met **Designer approval:** + ``` I confirm that the implemented feature matches the design specifications and meets the quality standards defined in @@ -395,6 +424,7 @@ Date: ________________ **Location:** `test-reports/TR-XXX-YYYY-MM-DD.md` **Contents:** + - Test summary (date, tester, device, build) - Overall result (pass/fail/partial) - Test coverage (happy path, errors, edge cases, etc.) @@ -409,6 +439,7 @@ Date: ________________ **Location:** `issues/ISS-XXX-description.md` **Contents:** + - Issue metadata (id, severity, status, delivery, test) - Description - Expected vs Actual @@ -425,16 +456,19 @@ Date: ________________ ### Design System Violations **Button color incorrect:** + - Expected: Design token color - Actual: Hardcoded color - Fix: Use design token **Typography wrong:** + - Expected: 16px, Semibold - Actual: 14px, Regular - Fix: Use design system styles **Spacing inconsistent:** + - Expected: 20px between elements - Actual: 15px, 18px, 23px - Fix: Use spacing tokens @@ -444,16 +478,19 @@ Date: ________________ ### Interaction Issues **Transition too fast:** + - Expected: 300ms smooth transition - Actual: Instant transition - Fix: Add transition animation **Touch target too small:** + - Expected: 44×44px minimum - Actual: 32×32px - Fix: Increase button size **No loading state:** + - Expected: Spinner during load - Actual: Blank screen - Fix: Add loading indicator @@ -463,16 +500,19 @@ Date: ________________ ### Accessibility Issues **Missing labels:** + - Expected: Descriptive button labels - Actual: Generic "Button" label - Fix: Add aria-label **Low contrast:** + - Expected: 4.5:1 contrast ratio - Actual: 3:1 contrast ratio - Fix: Increase text color contrast **Not keyboard accessible:** + - Expected: Can navigate with keyboard - Actual: Keyboard navigation doesn't work - Fix: Add keyboard support @@ -484,24 +524,28 @@ Date: ________________ ### DO ✅ **Be thorough:** + - Test every step in test scenario - Check all design references - Verify all acceptance criteria - Don't skip edge cases **Be specific:** + - Clear issue descriptions - Include screenshots/videos - Reference design specs - Provide recommendations **Be collaborative:** + - Communicate clearly with BMad - Answer questions promptly - Appreciate good work - Focus on quality, not blame **Be iterative:** + - Expect multiple rounds - Test quickly and provide feedback - Don't wait for perfection @@ -510,20 +554,24 @@ Date: ________________ ### DON'T ❌ **Don't be vague:** + - "It doesn't look right" ❌ - "Button color is #3B82F6, should be #2563EB" ✅ **Don't be nitpicky:** + - Focus on critical issues first - Don't block on minor details - Remember: good enough to ship **Don't disappear:** + - Respond to BMad questions - Retest promptly - Stay engaged until sign-off **Don't skip documentation:** + - Always create test reports - Always document issues - Always provide clear feedback @@ -540,6 +588,7 @@ Date: ________________ 4. **Continue** with next delivery (return to Phase 4-5) **If more flows in progress:** + - Test next completed flow - Continue parallel work - Maintain quality standards @@ -549,11 +598,13 @@ Date: ________________ ## Resources **Templates:** + - `templates/test-scenario.template.yaml` - `templates/test-report.template.md` (to be created) - `templates/issue.template.md` (to be created) **Specifications:** + - `src/core/resources/wds/integration-guide.md` - Test scenario files in `test-scenarios/` diff --git a/src/modules/wds/workflows/7-testing/workflow.md b/src/modules/wds/workflows/7-testing/workflow.md index ce442b62..9f9a07cc 100644 --- a/src/modules/wds/workflows/7-testing/workflow.md +++ b/src/modules/wds/workflows/7-testing/workflow.md @@ -49,10 +49,10 @@ Phase 7.7: Iterate or Approve ``` BMad Developer: "Feature complete: DD-001 Login & Onboarding - + Build: v0.1.0-beta.1 Device: Staging environment - + Ready for designer validation. Test scenario: test-scenarios/TS-001.yaml" ``` diff --git a/src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md b/src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md index 2c8d5d7c..d9bc31e7 100644 --- a/src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md +++ b/src/modules/wds/workflows/8-ongoing-development/existing-product-guide.md @@ -7,6 +7,7 @@ ## 🔑 Key Point: You Still Create a Project Brief! **Brownfield projects (existing products) still need a Project Brief - just adapted to focus on:** + - ✅ The strategic challenge you're solving - ✅ The scope of changes - ✅ Success criteria @@ -19,20 +20,25 @@ ## Two Entry Points to WDS ### **Entry Point 1: New Product (Phases 1-7) - Greenfield + Kaikaku** + Starting from scratch, designing complete user flows **Terminology:** + - **Greenfield:** Building from scratch with no existing constraints - **Kaikaku (改革):** Revolutionary change, complete transformation ### **Entry Point 2: Existing Product (Phase 8) - Brownfield + Kaizen** + Jumping into an existing product to make strategic changes **Terminology:** + - **Brownfield:** Working within existing system and constraints - **Kaizen (改善):** Continuous improvement, small incremental changes **This phase is for:** + - Existing products that need strategic improvements - Products where you're brought in as a "linchpin designer" - Situations where you're not designing complete flows from scratch @@ -43,6 +49,7 @@ Jumping into an existing product to make strategic changes ## Purpose When joining an existing product, you: + 1. Focus on strategic challenges (not complete redesign) 2. Make targeted improvements to existing screens 3. Add new features incrementally @@ -122,6 +129,7 @@ Which type of project are you working on? ``` **If you choose "Existing Product" (Brownfield):** + - **Phase 1 (Project Brief):** Adapted - focus on strategic challenge, not full vision - **Phase 2 (Trigger Map):** Optional - print out focused trigger map if needed - **Phase 3 (Platform Requirements):** Skip - tech stack already decided @@ -135,6 +143,7 @@ Which type of project are you working on? **IMPORTANT: You still create a Project Brief - just adapted to the existing product context.** **Brownfield vs Greenfield:** + - **Greenfield (New Product):** Full Project Brief covering vision, goals, stakeholders, constraints - **Brownfield (Existing Product):** Focused Project Brief covering the strategic challenge and scope @@ -146,45 +155,53 @@ Which type of project are you working on? # Limited Project Brief: Existing Product ## Strategic Challenge + What specific problem are we solving? Example: "User onboarding has 60% drop-off rate. Users don't understand - the family concept and abandon during setup." +the family concept and abandon during setup." ## Why WDS Designer? + Why bring in a linchpin designer now? Example: "We need expert UX design to redesign the onboarding flow and - improve completion rates to 80%+." +improve completion rates to 80%+." ## Scope + What are we changing? Example: "Redesign onboarding flow (4 screens): - - Welcome screen (update copy and visuals) - - Family setup (simplify and clarify) - - Dog addition (make it optional for MVP) - - Success state (add celebration)" + +- Welcome screen (update copy and visuals) +- Family setup (simplify and clarify) +- Dog addition (make it optional for MVP) +- Success state (add celebration)" ## Success Criteria + How will we measure success? Example: "- Onboarding completion rate > 80% - - Time to complete < 2 minutes - - User satisfaction score > 4.5/5" + +- Time to complete < 2 minutes +- User satisfaction score > 4.5/5" ## Constraints + What can't we change? Example: "- Tech stack: React Native + Supabase (already built) - - Brand: Colors and logo are fixed - - Timeline: 2 weeks to design + implement - - Scope: Only onboarding, don't touch other features" + +- Brand: Colors and logo are fixed +- Timeline: 2 weeks to design + implement +- Scope: Only onboarding, don't touch other features" ``` --- @@ -194,12 +211,14 @@ Example: **Upload and review existing materials:** ### **Business Goals** + ``` Upload: business-goals.pdf Review: What's the company trying to achieve? ``` ### **Target Group Material** + ``` Upload: user-personas.pdf Upload: user-research.pdf @@ -207,6 +226,7 @@ Review: Who are the users? What do they need? ``` ### **Print Out Trigger Map** + ``` Based on existing materials, create a focused trigger map: - What triggers bring users to this feature? @@ -215,13 +235,16 @@ Based on existing materials, create a focused trigger map: ``` **Example (Focused Trigger Map):** + ```markdown # Trigger Map: Onboarding Improvement ## Trigger Moment + User downloads app and opens it for the first time ## Current Experience + 1. Welcome screen (confusing value prop) 2. Login/Signup choice (too many options) 3. Family setup (unclear what "family" means) @@ -229,15 +252,18 @@ User downloads app and opens it for the first time 5. 60% drop off before reaching dashboard ## Desired Outcome + User understands value, completes setup, reaches dashboard ## Barriers + - Unclear value proposition - "Family" concept is confusing - Forced dog addition feels like work - No sense of progress or achievement ## Solution Focus + - Clarify value prop on welcome screen - Simplify family concept explanation - Make dog addition optional @@ -245,6 +271,7 @@ User understands value, completes setup, reaches dashboard ``` ### **Understand Existing Product** + ``` Review: - Current app (use it yourself) @@ -262,80 +289,96 @@ Review: ### **Example: Onboarding Improvement** **Scenario 01: Welcome Screen (Update)** + ```markdown # Scenario 01: Welcome Screen (UPDATE) ## What's Changing + - Clearer value proposition - Better visual hierarchy - Stronger call-to-action ## What's Staying + - Brand colors - Logo placement - Screen structure ## Design Updates + - Hero image: Show family using app together - Headline: "Keep your family's dog care organized" - Subheadline: "Share tasks, track routines, never miss a walk" - CTA: "Get Started" (larger, more prominent) ## Components + - Existing: Button (Primary) - Update: Hero Image component - Update: Typography (larger headline) ``` **Scenario 02: Family Setup (Redesign)** + ```markdown # Scenario 02: Family Setup (REDESIGN) ## Current Problem + Users don't understand what "family" means in this context ## Solution + - Rename "Family" to "Household" - Add explanation: "Who helps take care of your dog?" - Show examples: "You, your partner, your kids, your dog walker" - Make it visual: Show avatars of household members ## Design Changes + - Screen title: "Set up your household" - Explanation text (new) - Visual examples (new) - Simplified form (fewer fields) ## Components + - Existing: Input (Text) - New: Explanation Card component - New: Avatar Grid component ``` **Scenario 03: Dog Addition (Make Optional)** + ```markdown # Scenario 03: Dog Addition (MAKE OPTIONAL) ## Current Problem + Forcing users to add a dog feels like homework, causes drop-off ## Solution + - Make it optional for onboarding - Show value: "Add your first dog to get started" - Allow skip: "I'll do this later" - Celebrate if they add: "Great! Let's meet [dog name]!" ## Design Changes + - Add "Skip for now" button - Add celebration animation if dog added - Update copy to be inviting, not demanding ## Components + - Existing: Button (Primary, Secondary) - New: Celebration Animation component ``` **Notice the difference:** + - ❌ Not designing complete flows from scratch - ✅ Updating existing screens strategically - ✅ Focused on solving specific problems @@ -348,6 +391,7 @@ Forcing users to add a dog feels like homework, causes drop-off ### **Accumulated Changes** **Small changes accumulate:** + - Bug fix: Button alignment - Refinement: Improved error message - Enhancement: New filter option @@ -355,6 +399,7 @@ Forcing users to add a dog feels like homework, causes drop-off - Improvement: Better empty state **When enough changes accumulate:** + ``` 10-15 small changes = Design Delivery OR @@ -366,16 +411,19 @@ OR ### **Business Triggers** **Scheduled releases:** + - Monthly updates - Quarterly feature releases - Annual major versions **Market triggers:** + - Competitor feature launched - User demand spike - Business opportunity **Technical triggers:** + - Platform update (iOS 18, Android 15) - Security patch required - Performance optimization needed @@ -387,12 +435,14 @@ OR ### Step 1: Monitor & Gather Feedback **Sources:** + - User feedback (support tickets, reviews) - Analytics (usage patterns, drop-offs) - Team observations (bugs, issues) - Stakeholder requests (new features) **Track in backlog:** + ``` Backlog: - [ ] Bug: Login button misaligned on iPad @@ -407,12 +457,14 @@ Backlog: ### Step 2: Prioritize Changes **Criteria:** + - **Impact:** High user value vs low effort - **Urgency:** Critical bugs vs nice-to-haves - **Alignment:** Strategic goals vs random requests - **Feasibility:** Quick wins vs complex changes **Prioritized list:** + ``` High Priority (Next Update): 1. Bug: Login button misaligned (Critical) @@ -432,12 +484,14 @@ Low Priority (Backlog): ### Step 3: Design Changes **Return to Phase 4-5:** + - Design fixes and refinements - Create specifications for new features - Update design system if needed - Document changes **Track changes:** + ``` Changes for Design Delivery DD-011 (v1.1): ✓ Fixed: Login button alignment on iPad @@ -457,13 +511,13 @@ Changes for Design Delivery DD-011 (v1.1): ```yaml delivery: - id: "DD-010" - name: "Product Update v1.1" - type: "incremental_improvement" - scope: "update" - status: "ready" - priority: "high" - version: "1.1" + id: 'DD-010' + name: 'Product Update v1.1' + type: 'incremental_improvement' + scope: 'update' + status: 'ready' + priority: 'high' + version: '1.1' description: | Incremental improvements with bug fixes, refinements, and enhancements @@ -471,40 +525,40 @@ description: | changes: bug_fixes: - - "Fixed login button alignment on iPad" - - "Added loading spinner to all async actions" - - "Fixed family invite code validation" - + - 'Fixed login button alignment on iPad' + - 'Added loading spinner to all async actions' + - 'Fixed family invite code validation' + enhancements: - "Added 'Remember me' checkbox on login" - - "Improved error messages (clearer wording)" - - "Better empty state for task list" - + - 'Improved error messages (clearer wording)' + - 'Better empty state for task list' + design_system_updates: - - "Button component: Added loading state" - - "Input component: Improved error styling" + - 'Button component: Added loading state' + - 'Input component: Improved error styling' affected_scenarios: - - id: "02-login" - path: "C-Scenarios/02-login/" + - id: '02-login' + path: 'C-Scenarios/02-login/' changes: "Added 'Remember me' checkbox, fixed alignment" - - - id: "06-task-list" - path: "C-Scenarios/06-task-list/" - changes: "Improved empty state design" + + - id: '06-task-list' + path: 'C-Scenarios/06-task-list/' + changes: 'Improved empty state design' user_value: - problem: "Users experiencing bugs and requesting improvements" - solution: "Bug fixes and enhancements based on feedback" + problem: 'Users experiencing bugs and requesting improvements' + solution: 'Bug fixes and enhancements based on feedback' success_criteria: - - "Bug reports decrease by 50%" - - "User satisfaction score increases" - - "Onboarding completion rate improves" + - 'Bug reports decrease by 50%' + - 'User satisfaction score increases' + - 'Onboarding completion rate improves' estimated_complexity: - size: "small" - effort: "1 week" - risk: "low" + size: 'small' + effort: '1 week' + risk: 'low' dependencies: [] ``` @@ -513,6 +567,7 @@ estimated_complexity: ### Step 5: Hand Off to BMad **Same process as Phase 6:** + 1. Create Design Delivery (DD-XXX.yaml) 2. Create Test Scenario (TS-XXX.yaml) 3. Handoff Dialog with BMad Architect @@ -521,6 +576,7 @@ estimated_complexity: 6. Sign off and deploy **BMad receives:** + - Design Delivery (DD-XXX) - Updated specifications - Design system changes @@ -531,6 +587,7 @@ estimated_complexity: ### Step 6: Deploy Changes **After validation:** + ``` ✅ Design Delivery DD-011 (v1.1) approved ✅ All tests passed @@ -544,22 +601,26 @@ Deployment: ``` **Release notes (auto-generated from delivery):** + ```markdown # Version 1.1 Release ## What's New ### Bug Fixes + - Fixed login button alignment on iPad - Added loading spinner to all async actions - Fixed family invite code validation ### Enhancements + - Added "Remember me" checkbox on login - Improved error messages for clarity - Better empty state when no tasks ### Design System Updates + - Button component now supports loading state - Input component has improved error styling ``` @@ -569,12 +630,14 @@ Deployment: ### Step 7: Monitor & Repeat **After deployment:** + - Monitor user feedback - Track analytics - Identify new issues - Plan next update **Continuous cycle:** + ``` v1.0 Launch ↓ @@ -598,11 +661,13 @@ v2.0 Major Update (significant changes) - DD-020 ## Types of Updates ### **Patch Updates (v1.0.1)** + **Frequency:** As needed (urgent bugs) **Scope:** Critical bug fixes only **Timeline:** 1-3 days **Example:** + - Critical: Login broken on iOS 17.2 - Fix: Update authentication flow - Deploy: Emergency patch @@ -610,11 +675,13 @@ v2.0 Major Update (significant changes) - DD-020 --- ### **Minor Updates (v1.1.0)** + **Frequency:** Monthly or bi-weekly **Scope:** Bug fixes + small enhancements **Timeline:** 1-2 weeks **Example:** + - 3 bug fixes - 5 small enhancements - 2 design system updates @@ -623,11 +690,13 @@ v2.0 Major Update (significant changes) - DD-020 --- ### **Major Updates (v2.0.0)** + **Frequency:** Quarterly or annually **Scope:** New features + significant changes **Timeline:** 4-8 weeks **Example:** + - New feature: Calendar view - New feature: Family chat - Redesign: Navigation system @@ -641,6 +710,7 @@ v2.0 Major Update (significant changes) - DD-020 ### **Designer & Developer Partnership** **Designer:** + - Monitors user feedback - Identifies improvements - Designs changes @@ -648,6 +718,7 @@ v2.0 Major Update (significant changes) - DD-020 - Validates implementation **Developer:** + - Implements changes - Suggests technical improvements - Provides feasibility feedback @@ -655,6 +726,7 @@ v2.0 Major Update (significant changes) - DD-020 - Notifies when ready for testing **Together:** + - Regular sync meetings - Shared backlog - Collaborative prioritization @@ -671,14 +743,14 @@ v2.0 Major Update (significant changes) - DD-020 Designer: "We've launched v1.0, iterated through v1.1 and v1.2, and now v2.0 is live. The product is mature, the process is smooth, and users are happy. - + The design-to-development workflow is humming along beautifully. We're a well-oiled machine!" Developer: "Agreed! We've found our rhythm. Design Deliveries come in, we implement them, you validate, we ship. The 3 touch points work perfectly. - + Users love the product, stakeholders are happy, and we're continuously improving." @@ -698,16 +770,19 @@ THE END! 🎬 ### **Process Health** **Velocity:** + - Time from design to deployment - Number of updates per quarter - Backlog size and age **Quality:** + - Bug reports per release - User satisfaction scores - Design system compliance **Collaboration:** + - Handoff smoothness - Communication clarity - Issue resolution time @@ -717,16 +792,19 @@ THE END! 🎬 ### **Product Health** **Usage:** + - Active users - Feature adoption - Retention rates **Satisfaction:** + - User reviews - NPS scores - Support tickets **Business:** + - Revenue growth - Market share - Strategic goals met @@ -738,24 +816,28 @@ THE END! 🎬 ### DO ✅ **Maintain momentum:** + - Regular releases (don't go dark) - Continuous improvement - Respond to feedback - Celebrate wins **Keep quality high:** + - Don't skip validation - Maintain design system - Test thoroughly - Document changes **Communicate well:** + - Regular designer-developer sync - Clear priorities - Transparent roadmap - Stakeholder updates **Stay user-focused:** + - Listen to feedback - Measure impact - Iterate based on data @@ -764,24 +846,28 @@ THE END! 🎬 ### DON'T ❌ **Don't let backlog grow:** + - Prioritize ruthlessly - Say no to low-value requests - Keep backlog manageable - Archive old items **Don't skip process:** + - Always create deliveries - Always validate - Always document - Always follow touch points **Don't lose sight:** + - Remember user value - Stay aligned with goals - Don't chase shiny objects - Focus on what matters **Don't burn out:** + - Sustainable pace - Realistic timelines - Celebrate progress @@ -792,18 +878,21 @@ THE END! 🎬 ## The Long Game **Year 1:** + - Launch v1.0 (MVP) - Iterate rapidly (v1.1, v1.2, v1.3) - Learn from users - Establish process **Year 2:** + - Major update v2.0 - Mature product - Smooth process - Happy users **Year 3+:** + - Continuous evolution - Market leadership - Sustainable growth @@ -814,17 +903,20 @@ THE END! 🎬 ## Resources **Ongoing Development:** + - Return to Phase 4-5 for changes - Use Phase 6 for Design Deliveries (small scope) - Use Phase 7 for validation - Repeat indefinitely **Templates:** + - Same templates as initial development - Add "system_update" type to deliveries - Track version numbers **Documentation:** + - Maintain changelog - Update release notes - Keep design system current diff --git a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.1-identify-opportunity.md b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.1-identify-opportunity.md index e8692c97..6100cd87 100644 --- a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.1-identify-opportunity.md +++ b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.1-identify-opportunity.md @@ -11,9 +11,11 @@ Identify the strategic challenge or improvement opportunity you'll address in th This step works differently depending on your context: ### Context A: Existing Product Entry Point + You're joining an existing product to solve a strategic challenge ### Context B: Continuous Improvement (Post-Launch) + You're iterating on a live product based on data and feedback --- @@ -23,12 +25,14 @@ You're iterating on a live product based on data and feedback ### You're Brought In to Solve a Problem **Typical scenarios:** + - Product has a critical UX issue (high drop-off, low engagement) - New feature needs expert design - Product needs strategic improvement - Team needs a linchpin designer **Example:** + ``` Product Manager: "Our onboarding has 60% drop-off rate. Users don't understand the family concept. @@ -83,25 +87,27 @@ Product Manager: "Our onboarding has 60% drop-off rate. Example: "User onboarding has 60% drop-off rate. Users don't understand - the family concept and abandon during setup." +the family concept and abandon during setup." **Impact:** [Why does this matter?] Example: "- 60% of new users never reach the dashboard - - Acquisition cost is wasted on users who drop off - - Growth is limited by poor onboarding - - Estimated revenue loss: $50K/month" + +- Acquisition cost is wasted on users who drop off +- Growth is limited by poor onboarding +- Estimated revenue loss: $50K/month" **Root Cause:** [Why is this happening?] Example: "- 'Family' concept is unclear (Swedish cultural context) - - Too many steps feel like homework - - No sense of progress or achievement - - Value proposition not clear upfront" + +- Too many steps feel like homework +- No sense of progress or achievement +- Value proposition not clear upfront" --- @@ -111,10 +117,11 @@ Example: Example: "We need expert UX design to: - - Understand user psychology and motivation - - Redesign onboarding flow for clarity - - Balance business goals with user needs - - Improve completion rates to 80%+" + +- Understand user psychology and motivation +- Redesign onboarding flow for clarity +- Balance business goals with user needs +- Improve completion rates to 80%+" --- @@ -124,18 +131,20 @@ Example: Example: "Redesign onboarding flow (4 screens): - - Welcome screen (update copy and visuals) - - Family setup (simplify and clarify concept) - - Dog addition (make it optional for MVP) - - Success state (add celebration and next steps)" + +- Welcome screen (update copy and visuals) +- Family setup (simplify and clarify concept) +- Dog addition (make it optional for MVP) +- Success state (add celebration and next steps)" **What are we NOT changing?** Example: "- Tech stack: React Native + Supabase (already built) - - Brand: Colors and logo are fixed - - Other features: Only touch onboarding - - Timeline: 2 weeks to design + implement" + +- Brand: Colors and logo are fixed +- Other features: Only touch onboarding +- Timeline: 2 weeks to design + implement" --- @@ -145,9 +154,10 @@ Example: Example: "- Onboarding completion rate > 80% (from 40%) - - Time to complete < 2 minutes - - User satisfaction score > 4.5/5 - - 30-day retention > 60%" + +- Time to complete < 2 minutes +- User satisfaction score > 4.5/5 +- 30-day retention > 60%" --- @@ -157,10 +167,11 @@ Example: Example: "- Tech stack: React Native + Supabase - - Brand: Colors, logo, typography fixed - - Timeline: 2 weeks total - - Budget: No additional development resources - - Scope: Only onboarding, don't touch dashboard" + +- Brand: Colors, logo, typography fixed +- Timeline: 2 weeks total +- Budget: No additional development resources +- Scope: Only onboarding, don't touch dashboard" --- @@ -200,6 +211,7 @@ Now you're in continuous improvement mode (Kaizen). ### 1. Analytics **Check key metrics:** + - User engagement (DAU, WAU, MAU) - Feature usage (which features are used?) - Drop-off points (where do users leave?) @@ -207,6 +219,7 @@ Now you're in continuous improvement mode (Kaizen). - Performance (load times, errors) **Example:** + ``` Analytics Dashboard: - DAU: 1,200 users @@ -221,6 +234,7 @@ Analytics Dashboard: ### 2. User Feedback **Review feedback channels:** + - Support tickets - App store reviews - In-app feedback @@ -228,6 +242,7 @@ Analytics Dashboard: - Social media mentions **Example:** + ``` Common feedback themes: - "I don't understand how to use Feature X" (12 mentions) @@ -241,6 +256,7 @@ Common feedback themes: ### 3. Team Insights **Talk to your team:** + - What are developers noticing? - What are support seeing? - What are sales hearing? @@ -255,21 +271,25 @@ Common feedback themes: ### Priority = Impact × Effort × Learning **Impact:** How much will this improve the product? + - High: Solves major user pain, improves key metric - Medium: Improves experience, minor metric impact - Low: Nice to have, minimal impact **Effort:** How hard is this to implement? + - Low: 1-2 days - Medium: 3-5 days - High: 1-2 weeks **Learning:** How much will we learn? + - High: Tests important hypothesis - Medium: Validates assumption - Low: Incremental improvement **Example prioritization:** + ``` Opportunity A: Improve Feature X onboarding - Impact: High (40% drop-off, key feature) @@ -313,25 +333,27 @@ Opportunity C: Improve performance Example: "Feature X has low engagement (15% usage) and high drop-off (40%). - User feedback indicates confusion about how to use it." +User feedback indicates confusion about how to use it." **Why does this matter?** Example: "Feature X is a core value proposition. Low usage means users - aren't getting full value from the product. This impacts - retention and satisfaction." +aren't getting full value from the product. This impacts +retention and satisfaction." --- ## Data **Analytics:** + - Feature X usage: 15% (target: 60%) - Drop-off at Feature X: 40% - Time spent: 30 seconds (too short) **User Feedback:** + - "I don't understand how to use Feature X" (12 mentions) - "Feature X seems broken" (3 mentions) @@ -347,12 +369,14 @@ no onboarding or guidance. Example: "Add inline onboarding to Feature X: - - Tooltip on first use explaining purpose - - Step-by-step guide for first action - - Success celebration when completed - - Help button for future reference" + +- Tooltip on first use explaining purpose +- Step-by-step guide for first action +- Success celebration when completed +- Help button for future reference" **Expected Impact:** + - Feature X usage: 15% → 60% - Drop-off: 40% → 10% - User satisfaction: +1.5 points @@ -433,16 +457,19 @@ After identifying the opportunity: ### DO ✅ **Be specific:** + - Quantify the problem - Use real data - Define clear scope **Be strategic:** + - Focus on high-impact changes - Small, incremental improvements - One improvement at a time **Be data-driven:** + - Use analytics - Listen to user feedback - Test hypotheses @@ -450,14 +477,17 @@ After identifying the opportunity: ### DON'T ❌ **Don't be vague:** + - "Make it better" ❌ - "40% drop-off at onboarding" ✅ **Don't boil the ocean:** + - Complete redesign ❌ - Targeted improvement ✅ **Don't guess:** + - Use data to identify problems - Validate with user feedback - Test hypotheses diff --git a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.2-gather-context.md b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.2-gather-context.md index d479e69d..c12378bf 100644 --- a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.2-gather-context.md +++ b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.2-gather-context.md @@ -9,6 +9,7 @@ Understand the existing product context before making changes. ## Before You Start **Ensure you have:** + - ✅ Completed step 8.1 (opportunity identified) - ✅ Limited brief or improvement file created - ✅ Clear understanding of the problem @@ -32,6 +33,7 @@ Understand the existing product context before making changes. - Market research **Review and understand:** + - Why does this product exist? - What's the business model? - Who are the competitors? @@ -50,6 +52,7 @@ Understand the existing product context before making changes. - User feedback summaries **Review and understand:** + - Who are the users? - What are their needs? - What are their pain points? @@ -69,6 +72,7 @@ Understand the existing product context before making changes. - API documentation **Review and understand:** + - What features exist? - How does it work? - What's the tech stack? @@ -86,23 +90,27 @@ Understand the existing product context before making changes. - Use all major features 2. **Document your experience** + ```markdown # First Impressions: [Product Name] - + **Date:** 2024-12-09 **Context:** First-time user, no prior knowledge - + ## Onboarding + - Step 1: [What happened? How did it feel?] - Step 2: [What happened? How did it feel?] - Confusion points: [Where was I confused?] - Delights: [What felt great?] - + ## Core Features + - Feature X: [Experience] - Feature Y: [Experience] - + ## Overall Impression + [What's your gut feeling about this product?] ``` @@ -142,10 +150,7 @@ Example: **What happens now?** Example: -"1. Welcome screen (confusing value prop) - 2. Family setup (unclear what 'family' means) - 3. Dog addition (forced, feels like homework) - 4. 60% drop off before reaching dashboard" +"1. Welcome screen (confusing value prop) 2. Family setup (unclear what 'family' means) 3. Dog addition (forced, feels like homework) 4. 60% drop off before reaching dashboard" --- @@ -155,7 +160,7 @@ Example: Example: "User understands value, completes setup smoothly, - reaches dashboard feeling confident and excited" +reaches dashboard feeling confident and excited" --- @@ -165,10 +170,11 @@ Example: Example: "- Unclear value proposition - - 'Family' concept is confusing (cultural context) - - Forced dog addition feels like work - - No sense of progress or achievement - - No celebration of completion" + +- 'Family' concept is confusing (cultural context) +- Forced dog addition feels like work +- No sense of progress or achievement +- No celebration of completion" --- @@ -178,10 +184,11 @@ Example: Example: "- Clarify value prop on welcome screen - - Simplify family concept explanation - - Make dog addition optional - - Add progress indicators - - Add celebration on completion" + +- Simplify family concept explanation +- Make dog addition optional +- Add progress indicators +- Add celebration on completion" ``` --- @@ -203,17 +210,20 @@ Example: **Focus:** Feature X engagement ## Usage Metrics + - Users who saw Feature X: 1,200 - Users who used Feature X: 180 (15%) - Users who completed action: 90 (7.5%) - Drop-off point: Step 2 (40% drop off) ## User Segments + - New users: 10% usage - Returning users: 20% usage - Power users: 60% usage ## Insight + New and returning users struggle with Feature X. Power users understand it. Suggests onboarding gap. ``` @@ -233,19 +243,23 @@ Power users understand it. Suggests onboarding gap. ## Themes ### Confusion (12 mentions) + - "I don't understand how to use Feature X" - "Feature X seems broken" - "What is Feature X for?" ### Requests (8 mentions) + - "Can Feature X do Y?" - "Wish Feature X had Z" ### Praise (4 mentions) + - "Once I figured it out, Feature X is great!" - "Feature X saves me time" ## Insight + Users who figure out Feature X love it. But most users never figure it out. Onboarding is the problem. @@ -266,6 +280,7 @@ Onboarding is the problem. **Assumptions:** [What did you assume about users?] ## What We Learned + - Assumption: Users would understand Feature X intuitively - Reality: Users need explicit guidance - Lesson: Add onboarding for complex features @@ -281,18 +296,21 @@ Onboarding is the problem. # Competitive Analysis: Feature X ## Competitor A + - Approach: [How do they do it?] - Onboarding: [Do they have guidance?] - Pros: [What works well?] - Cons: [What doesn't work?] ## Competitor B + - Approach: [How do they do it?] - Onboarding: [Do they have guidance?] - Pros: [What works well?] - Cons: [What doesn't work?] ## Insights + [What can we learn from competitors?] ``` @@ -306,18 +324,22 @@ Onboarding is the problem. # Context Synthesis: [Improvement Name] ## What We Know + 1. [Key insight from analytics] 2. [Key insight from user feedback] 3. [Key insight from competitive analysis] 4. [Key insight from original design] ## Root Cause + [Why is this problem happening?] ## Hypothesis + [What do we believe will solve it?] ## Validation Plan + [How will we know if we're right?] ``` diff --git a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.3-design-update.md b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.3-design-update.md index 209fd841..dc7a8660 100644 --- a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.3-design-update.md +++ b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.3-design-update.md @@ -9,6 +9,7 @@ Design the incremental improvement - not a complete redesign, but a targeted upd ## Before You Start **Ensure you have:** + - ✅ Completed step 8.2 (context gathered) - ✅ Root cause identified - ✅ Hypothesis formed @@ -19,6 +20,7 @@ Design the incremental improvement - not a complete redesign, but a targeted upd ## Kaizen Principle: Small, Focused Changes **Remember:** + - ❌ Complete redesign - ✅ Targeted improvement - ❌ Change everything @@ -42,6 +44,7 @@ Design the incremental improvement - not a complete redesign, but a targeted upd ### Screen/Feature: [Name] **Changes:** + - [ ] Copy/messaging - [ ] Visual hierarchy - [ ] Component usage @@ -50,6 +53,7 @@ Design the incremental improvement - not a complete redesign, but a targeted upd - [ ] Data structure **Specific changes:** + 1. [Specific change 1] 2. [Specific change 2] 3. [Specific change 3] @@ -59,6 +63,7 @@ Design the incremental improvement - not a complete redesign, but a targeted upd ## What's Staying **Unchanged:** + - ✓ Brand colors - ✓ Typography - ✓ Core layout structure @@ -71,9 +76,9 @@ Design the incremental improvement - not a complete redesign, but a targeted upd Example: "Brand colors and typography are fixed by brand guidelines. - Core layout structure works well and changing it would - require extensive development. We're focusing on content - and interaction improvements only." +Core layout structure works well and changing it would +require extensive development. We're focusing on content +and interaction improvements only." ``` --- @@ -107,12 +112,16 @@ Example: ### Before (v1.0) ``` + [Describe old structure] + ``` ### After (v2.0) ``` + [Describe new structure] + ``` --- @@ -210,7 +219,7 @@ Example: Example: "Inline tooltip to guide users through Feature X on first use. - Needed because analytics show 40% drop-off due to confusion." +Needed because analytics show 40% drop-off due to confusion." --- @@ -223,10 +232,12 @@ Example: ## Usage **Where used:** + - Screen X: [Context] - Screen Y: [Context] **When shown:** + - First time user sees Feature X - Can be dismissed - Doesn't show again after dismissal @@ -252,11 +263,13 @@ Example: ## What Changed ### Change 1: [Name] + - **Before:** [Description] - **After:** [Description] - **Rationale:** [Why?] ### Change 2: [Name] + - **Before:** [Description] - **After:** [Description] - **Rationale:** [Why?] @@ -272,6 +285,7 @@ Example: ## Migration Notes **For developers:** + - [What needs to change in code?] - [Any breaking changes?] - [Backward compatibility?] @@ -294,11 +308,13 @@ Example: [What it looked like before] **User Experience:** + - User sees: [Description] - User feels: [Description] - Problem: [What was wrong?] **Metrics:** + - Usage: 15% - Drop-off: 40% - Satisfaction: 3.2/5 @@ -311,11 +327,13 @@ Example: [What it looks like after] **User Experience:** + - User sees: [Description] - User feels: [Description] - Improvement: [What's better?] **Expected Metrics:** + - Usage: 60% (target) - Drop-off: 10% (target) - Satisfaction: 4.5/5 (target) @@ -364,29 +382,35 @@ Example: # Hypothesis Validation: [Update Name] ## Hypothesis + [What do we believe will happen?] Example: "If we add inline onboarding to Feature X, usage will - increase from 15% to 60% because users will understand - how to use it." +increase from 15% to 60% because users will understand +how to use it." ## Assumptions + 1. [Assumption 1] 2. [Assumption 2] 3. [Assumption 3] ## Risks + 1. [Risk 1]: [Mitigation] 2. [Risk 2]: [Mitigation] ## Success Criteria + - [Metric 1]: [Current] → [Target] - [Metric 2]: [Current] → [Target] - [Timeframe]: 2 weeks after release ## Failure Criteria + If after 2 weeks: + - [Metric 1] < [Threshold]: Rollback or iterate - [Metric 2] < [Threshold]: Rollback or iterate ``` @@ -431,16 +455,19 @@ After designing the update: ### DO ✅ **Be surgical:** + - Change only what's necessary - Keep scope tight - One improvement at a time **Be clear:** + - Document what's changing - Document what's staying - Show before/after **Be measurable:** + - Define success metrics - Set realistic targets - Plan measurement @@ -448,14 +475,17 @@ After designing the update: ### DON'T ❌ **Don't scope creep:** + - "While we're at it..." ❌ - Stay focused ✅ **Don't redesign:** + - Complete overhaul ❌ - Targeted improvement ✅ **Don't guess:** + - Use data to validate - Test hypotheses - Measure impact diff --git a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.4-create-delivery.md b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.4-create-delivery.md index 753d73d1..1e6f5a84 100644 --- a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.4-create-delivery.md +++ b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.4-create-delivery.md @@ -9,6 +9,7 @@ Package your incremental improvement as a Design Delivery (DD-XXX) for BMad. ## Before You Start **Ensure you have:** + - ✅ Completed step 8.3 (update designed) - ✅ Update specifications created - ✅ Change scope documented @@ -19,18 +20,21 @@ Package your incremental improvement as a Design Delivery (DD-XXX) for BMad. ## Design Delivery Format for All Improvements **IMPORTANT:** All design work uses Design Deliveries (DD-XXX), whether it's: + - ✅ Complete new user flows (large scope) - ✅ Incremental improvements (small scope) **The format is the same - only the scope and content differ!** ### Large Scope (New Flows) + - Multiple scenarios - Complete user flow - Full feature implementation - Weeks of work ### Small Scope (Improvements) + - Targeted changes - Updates existing feature - Focused improvement @@ -45,11 +49,13 @@ Package your incremental improvement as a Design Delivery (DD-XXX) for BMad. **File:** `deliveries/DD-XXX-description.yaml` **Numbering:** + - Continue from last DD number - If last new flow was DD-010, next improvement is DD-011 - Use leading zeros (DD-001, DD-002, etc.) **Example:** + - DD-001 to DD-010: New flows (Phases 4-7) - DD-011: First improvement (Phase 8) - DD-012: Second improvement (Phase 8) @@ -60,48 +66,48 @@ Package your incremental improvement as a Design Delivery (DD-XXX) for BMad. ```yaml delivery: - id: "DD-XXX" - name: "[Short descriptive name]" - type: "incremental_improvement" # vs "complete_flow" for new features - scope: "update" # vs "new" for new features - version: "v2.0" - previous_version: "v1.0" - created_at: "2024-12-09T14:00:00Z" - designer: "[Your name]" - status: "ready_for_handoff" + id: 'DD-XXX' + name: '[Short descriptive name]' + type: 'incremental_improvement' # vs "complete_flow" for new features + scope: 'update' # vs "new" for new features + version: 'v2.0' + previous_version: 'v1.0' + created_at: '2024-12-09T14:00:00Z' + designer: '[Your name]' + status: 'ready_for_handoff' # What's the improvement? improvement: summary: | [2-3 sentence summary of what's changing and why] - + Example: "Adding inline onboarding to Feature X to improve user understanding and increase usage from 15% to 60%. Analytics show 40% drop-off due to confusion. This update adds tooltips, step-by-step guidance, and success celebration." - + problem: | [What problem does this solve?] - + Example: "Feature X has low engagement (15% usage) and high drop-off (40%). User feedback indicates confusion about how to use it. 12 support tickets mention 'I don't understand Feature X'." - + solution: | [What's the solution?] - + Example: "Add inline onboarding that appears on first use: - Tooltip explaining Feature X purpose - Step-by-step guide for first action - Success celebration when completed - Help button for future reference" - + expected_impact: | [What will improve?] - + Example: "- Feature X usage: 15% → 60% - Drop-off: 40% → 10% @@ -112,185 +118,185 @@ improvement: changes: scope: screens_affected: - - "Feature X main screen" - - "Feature X onboarding overlay" - + - 'Feature X main screen' + - 'Feature X onboarding overlay' + features_affected: - - "Feature X interaction flow" - + - 'Feature X interaction flow' + components_new: - - id: "cmp-tooltip-001" - name: "Inline Tooltip" - file: "D-Design-System/03-Atomic-Components/Tooltips/Tooltip-Inline.md" - - - id: "cmp-guide-001" - name: "Step Guide" - file: "D-Design-System/03-Atomic-Components/Guides/Guide-Step.md" - + - id: 'cmp-tooltip-001' + name: 'Inline Tooltip' + file: 'D-Design-System/03-Atomic-Components/Tooltips/Tooltip-Inline.md' + + - id: 'cmp-guide-001' + name: 'Step Guide' + file: 'D-Design-System/03-Atomic-Components/Guides/Guide-Step.md' + components_modified: - - id: "cmp-btn-001" - name: "Primary Button" - changes: "Added help icon variant" - file: "D-Design-System/03-Atomic-Components/Buttons/Button-Primary.md" - + - id: 'cmp-btn-001' + name: 'Primary Button' + changes: 'Added help icon variant' + file: 'D-Design-System/03-Atomic-Components/Buttons/Button-Primary.md' + components_unchanged: - - "All other components remain as-is" - + - 'All other components remain as-is' + what_stays_same: - - "Brand colors and typography" - - "Core layout structure" - - "Navigation pattern" - - "Data model" - - "Tech stack" + - 'Brand colors and typography' + - 'Core layout structure' + - 'Navigation pattern' + - 'Data model' + - 'Tech stack' # Design artifacts design_artifacts: specifications: - - path: "C-Scenarios/XX-feature-x-update/Frontend/specifications.md" - description: "Updated Feature X specifications" - - - path: "C-Scenarios/XX-feature-x-update/change-scope.md" + - path: 'C-Scenarios/XX-feature-x-update/Frontend/specifications.md' + description: 'Updated Feature X specifications' + + - path: 'C-Scenarios/XX-feature-x-update/change-scope.md' description: "What's changing vs staying" - - - path: "C-Scenarios/XX-feature-x-update/before-after.md" - description: "Before/after comparison" - + + - path: 'C-Scenarios/XX-feature-x-update/before-after.md' + description: 'Before/after comparison' + components: - - path: "D-Design-System/03-Atomic-Components/Tooltips/Tooltip-Inline.md" - description: "New inline tooltip component" - - - path: "D-Design-System/03-Atomic-Components/Guides/Guide-Step.md" - description: "New step guide component" + - path: 'D-Design-System/03-Atomic-Components/Tooltips/Tooltip-Inline.md' + description: 'New inline tooltip component' + + - path: 'D-Design-System/03-Atomic-Components/Guides/Guide-Step.md' + description: 'New step guide component' # Technical requirements technical_requirements: frontend: - - "Implement inline tooltip component" - - "Add first-use detection logic" - - "Implement step-by-step guide" - - "Add success celebration animation" - - "Add help button with persistent access" - - "Store dismissal state in user preferences" - + - 'Implement inline tooltip component' + - 'Add first-use detection logic' + - 'Implement step-by-step guide' + - 'Add success celebration animation' + - 'Add help button with persistent access' + - 'Store dismissal state in user preferences' + backend: - - "Add user preference field: feature_x_onboarding_completed" - - "API endpoint to save dismissal state" - + - 'Add user preference field: feature_x_onboarding_completed' + - 'API endpoint to save dismissal state' + data: - - "User preferences table: add feature_x_onboarding_completed (boolean)" - + - 'User preferences table: add feature_x_onboarding_completed (boolean)' + integrations: - - "Analytics: Track onboarding completion" - - "Analytics: Track help button usage" + - 'Analytics: Track onboarding completion' + - 'Analytics: Track help button usage' # Acceptance criteria acceptance_criteria: - - id: "AC-001" - description: "Inline tooltip appears on first use of Feature X" - verification: "Open Feature X as new user, tooltip appears" - - - id: "AC-002" - description: "Step guide walks user through first action" - verification: "Follow guide, complete first action successfully" - - - id: "AC-003" - description: "Success celebration appears on completion" - verification: "Complete first action, celebration appears" - - - id: "AC-004" + - id: 'AC-001' + description: 'Inline tooltip appears on first use of Feature X' + verification: 'Open Feature X as new user, tooltip appears' + + - id: 'AC-002' + description: 'Step guide walks user through first action' + verification: 'Follow guide, complete first action successfully' + + - id: 'AC-003' + description: 'Success celebration appears on completion' + verification: 'Complete first action, celebration appears' + + - id: 'AC-004' description: "Onboarding doesn't appear on subsequent uses" - verification: "Use Feature X again, no onboarding shown" - - - id: "AC-005" - description: "Help button provides access to guide anytime" - verification: "Click help button, guide appears" - - - id: "AC-006" - description: "Dismissal state persists across sessions" - verification: "Dismiss, logout, login, onboarding not shown" + verification: 'Use Feature X again, no onboarding shown' + + - id: 'AC-005' + description: 'Help button provides access to guide anytime' + verification: 'Click help button, guide appears' + + - id: 'AC-006' + description: 'Dismissal state persists across sessions' + verification: 'Dismiss, logout, login, onboarding not shown' # Testing guidance testing_guidance: - test_scenario_file: "test-scenarios/TS-XXX.yaml" - + test_scenario_file: 'test-scenarios/TS-XXX.yaml' + key_tests: - - "First-time user experience (happy path)" - - "Dismissal and persistence" - - "Help button access" - - "Edge case: Multiple devices" - - "Edge case: Cleared cache" - + - 'First-time user experience (happy path)' + - 'Dismissal and persistence' + - 'Help button access' + - 'Edge case: Multiple devices' + - 'Edge case: Cleared cache' + success_criteria: - - "All acceptance criteria pass" - - "No regressions in existing functionality" - - "Performance impact < 50ms" - - "Accessibility: Screen reader compatible" + - 'All acceptance criteria pass' + - 'No regressions in existing functionality' + - 'Performance impact < 50ms' + - 'Accessibility: Screen reader compatible' # Metrics and validation metrics: baseline: - - metric: "Feature X usage rate" - current: "15%" - target: "60%" - - - metric: "Drop-off rate" - current: "40%" - target: "10%" - - - metric: "Support tickets (Feature X)" - current: "12/month" - target: "2/month" - - - metric: "User satisfaction" - current: "3.2/5" - target: "4.5/5" - - measurement_period: "2 weeks after release" - + - metric: 'Feature X usage rate' + current: '15%' + target: '60%' + + - metric: 'Drop-off rate' + current: '40%' + target: '10%' + + - metric: 'Support tickets (Feature X)' + current: '12/month' + target: '2/month' + + - metric: 'User satisfaction' + current: '3.2/5' + target: '4.5/5' + + measurement_period: '2 weeks after release' + success_threshold: - - "Feature X usage > 50% (minimum)" - - "Drop-off < 15% (minimum)" - - "Support tickets < 5/month" - + - 'Feature X usage > 50% (minimum)' + - 'Drop-off < 15% (minimum)' + - 'Support tickets < 5/month' + rollback_criteria: - - "Feature X usage < 20% after 2 weeks" - - "Drop-off > 35% after 2 weeks" - - "Critical bugs reported" + - 'Feature X usage < 20% after 2 weeks' + - 'Drop-off > 35% after 2 weeks' + - 'Critical bugs reported' # Effort estimate effort: - design: "1 day" - frontend: "1 day" - backend: "0.5 days" - testing: "0.5 days" - total: "3 days" - complexity: "Low" + design: '1 day' + frontend: '1 day' + backend: '0.5 days' + testing: '0.5 days' + total: '3 days' + complexity: 'Low' # Timeline timeline: - design_complete: "2024-12-09" - handoff_date: "2024-12-09" - development_start: "2024-12-10" - development_complete: "2024-12-12" - testing_complete: "2024-12-13" - release_date: "2024-12-13" - measurement_end: "2024-12-27" + design_complete: '2024-12-09' + handoff_date: '2024-12-09' + development_start: '2024-12-10' + development_complete: '2024-12-12' + testing_complete: '2024-12-13' + release_date: '2024-12-13' + measurement_end: '2024-12-27' # Handoff handoff: - architect: "[BMad Architect name]" - developer: "[BMad Developer name]" - handoff_dialog_required: false # Small update, dialog optional + architect: '[BMad Architect name]' + developer: '[BMad Developer name]' + handoff_dialog_required: false # Small update, dialog optional notes: | Small, focused improvement. Specifications are clear. Dialog available if questions arise. # Related related: - improvement_file: "improvements/IMP-XXX-feature-x-onboarding.md" - analytics_report: "analytics/feature-x-usage-2024-11.md" - user_feedback: "feedback/feature-x-confusion-2024-11.md" - original_delivery: "deliveries/DD-XXX-feature-x.yaml" # If applicable + improvement_file: 'improvements/IMP-XXX-feature-x-onboarding.md' + analytics_report: 'analytics/feature-x-usage-2024-11.md' + user_feedback: 'feedback/feature-x-confusion-2024-11.md' + original_delivery: 'deliveries/DD-XXX-feature-x.yaml' # If applicable ``` --- @@ -303,59 +309,59 @@ related: ```yaml test_scenario: - id: "TS-XXX" - name: "[Update Name] Validation" - type: "incremental_improvement" - delivery_id: "DD-XXX" - created_at: "2024-12-09T14:00:00Z" + id: 'TS-XXX' + name: '[Update Name] Validation' + type: 'incremental_improvement' + delivery_id: 'DD-XXX' + created_at: '2024-12-09T14:00:00Z' # Focus on what changed test_focus: - - "New onboarding flow" - - "Dismissal persistence" - - "Help button access" - - "No regressions" + - 'New onboarding flow' + - 'Dismissal persistence' + - 'Help button access' + - 'No regressions' # Happy path (new functionality) happy_path: - - id: "HP-001" - name: "First-time user sees onboarding" + - id: 'HP-001' + name: 'First-time user sees onboarding' steps: - - action: "Open Feature X as new user" - expected: "Inline tooltip appears" + - action: 'Open Feature X as new user' + expected: 'Inline tooltip appears' - action: "Read tooltip, tap 'Next'" - expected: "Step guide appears" - - action: "Follow guide, complete action" - expected: "Success celebration appears" - - action: "Dismiss celebration" - expected: "Feature X is ready to use" + expected: 'Step guide appears' + - action: 'Follow guide, complete action' + expected: 'Success celebration appears' + - action: 'Dismiss celebration' + expected: 'Feature X is ready to use' # Regression testing (existing functionality) regression_tests: - - id: "REG-001" - name: "Existing Feature X functionality unchanged" + - id: 'REG-001' + name: 'Existing Feature X functionality unchanged' steps: - - action: "Use Feature X core functionality" - expected: "Works exactly as before" + - action: 'Use Feature X core functionality' + expected: 'Works exactly as before' # Edge cases edge_cases: - - id: "EC-001" - name: "Dismissal persists across sessions" + - id: 'EC-001' + name: 'Dismissal persists across sessions' steps: - - action: "Dismiss onboarding" - - action: "Logout and login" - - action: "Open Feature X" - expected: "Onboarding not shown" + - action: 'Dismiss onboarding' + - action: 'Logout and login' + - action: 'Open Feature X' + expected: 'Onboarding not shown' # Accessibility accessibility: - - id: "A11Y-001" - name: "Screen reader announces onboarding" + - id: 'A11Y-001' + name: 'Screen reader announces onboarding' checks: - - "Tooltip announced correctly" - - "Guide steps announced" - - "Help button labeled" + - 'Tooltip announced correctly' + - 'Guide steps announced' + - 'Help button labeled' ``` --- diff --git a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.5-hand-off.md b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.5-hand-off.md index 6867a90f..d6bfa607 100644 --- a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.5-hand-off.md +++ b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.5-hand-off.md @@ -9,6 +9,7 @@ Hand off the Design Delivery (small scope) to BMad for implementation. ## Before You Start **Ensure you have:** + - ✅ Completed step 8.4 (Design Delivery created) - ✅ All artifacts ready - ✅ Test scenario created @@ -84,6 +85,7 @@ WDS Designer Refer to Phase 6, Step 6.4 for complete handoff dialog process. **Key topics:** + 1. Problem and solution overview 2. What's changing vs staying 3. Technical requirements @@ -128,11 +130,11 @@ BMad Developer ```yaml delivery: - status: "in_development" # Changed from "ready_for_handoff" - handed_off_at: "2024-12-09T15:00:00Z" - developer: "[BMad Developer name]" - development_start: "2024-12-10T09:00:00Z" - expected_completion: "2024-12-12T17:00:00Z" + status: 'in_development' # Changed from "ready_for_handoff" + handed_off_at: '2024-12-09T15:00:00Z' + developer: '[BMad Developer name]' + development_start: '2024-12-10T09:00:00Z' + expected_completion: '2024-12-12T17:00:00Z' ``` --- diff --git a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.6-validate.md b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.6-validate.md index bc354e24..14e254e5 100644 --- a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.6-validate.md +++ b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.6-validate.md @@ -9,6 +9,7 @@ Validate that the Design Delivery (small scope) was implemented correctly. ## Before You Start **Ensure you have:** + - ✅ Completed step 8.5 (handed off to BMad) - ✅ BMad notified you implementation is complete - ✅ Test scenario file ready @@ -56,6 +57,7 @@ BMad Developer **Load:** `test-scenarios/TS-XXX.yaml` **Focus on:** + - New functionality (what changed) - Regression testing (what should stay the same) - Edge cases specific to the update @@ -72,6 +74,7 @@ BMad Developer ## New Functionality Tests ### HP-001: [New feature works] + - Action: [Test new feature] - Expected: [New behavior] - Actual: [What happened] @@ -84,6 +87,7 @@ BMad Developer ## Regression Tests ### REG-001: [Existing feature unchanged] + - Action: [Use existing feature] - Expected: [Works as before] - Actual: [What happened] @@ -115,6 +119,7 @@ BMad Developer ## New Functionality ### Test HP-001: [Name] + - Status: [PASS | FAIL] - Notes: [Any observations] @@ -125,6 +130,7 @@ BMad Developer ## Regression Testing ### Test REG-001: [Name] + - Status: [PASS | FAIL] - Notes: [Any observations] @@ -219,9 +225,9 @@ Thanks, ```yaml delivery: - status: "complete" - validated_at: "2024-12-13T16:00:00Z" - approved_by: "[Your name]" + status: 'complete' + validated_at: '2024-12-13T16:00:00Z' + approved_by: '[Your name]' ready_for_production: true ``` @@ -229,7 +235,7 @@ delivery: ```yaml delivery: - status: "in_testing" + status: 'in_testing' issues_found: 2 retest_required: true ``` diff --git a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.7-monitor.md b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.7-monitor.md index bf6643c5..9e087f6e 100644 --- a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.7-monitor.md +++ b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.7-monitor.md @@ -9,6 +9,7 @@ Monitor the impact of your Design Delivery (small scope) and measure if it achie ## Before You Start **Ensure you have:** + - ✅ Completed step 8.6 (validation complete) - ✅ Design Delivery deployed to production - ✅ Success metrics defined @@ -37,10 +38,11 @@ Ship → Monitor → Learn → Improve → Ship... ```yaml metrics: - measurement_period: "2 weeks after release" + measurement_period: '2 weeks after release' ``` **Example timeline:** + - Release: 2024-12-13 - Measurement start: 2024-12-13 - Measurement end: 2024-12-27 @@ -55,13 +57,13 @@ metrics: ```yaml metrics: baseline: - - metric: "Feature X usage rate" - current: "15%" - target: "60%" - - - metric: "Drop-off rate" - current: "40%" - target: "10%" + - metric: 'Feature X usage rate' + current: '15%' + target: '60%' + + - metric: 'Drop-off rate' + current: '40%' + target: '10%' ``` **Create tracking dashboard:** @@ -74,13 +76,13 @@ metrics: ## Daily Tracking -| Date | Feature X Usage | Drop-off Rate | Notes | -|------|----------------|---------------|-------| -| 12/13 | 18% | 38% | Day 1 | -| 12/14 | 22% | 35% | Trending up | -| 12/15 | 28% | 30% | Good progress | -| ... | ... | ... | ... | -| 12/27 | 58% | 12% | Final | +| Date | Feature X Usage | Drop-off Rate | Notes | +| ----- | --------------- | ------------- | ------------- | +| 12/13 | 18% | 38% | Day 1 | +| 12/14 | 22% | 35% | Trending up | +| 12/15 | 28% | 30% | Good progress | +| ... | ... | ... | ... | +| 12/27 | 58% | 12% | Final | ## Trend Analysis @@ -94,12 +96,14 @@ metrics: **Monitor multiple channels:** #### User Feedback + - App store reviews - In-app feedback - Support tickets - User interviews #### Team Feedback + - Developer observations - Support team insights - Stakeholder reactions @@ -110,15 +114,18 @@ metrics: # Qualitative Feedback: DD-XXX ## Positive Feedback (8 mentions) + - "Now I understand how to use Feature X!" (3) - "The guide was really helpful" (2) - "Love the new onboarding" (3) ## Negative Feedback (2 mentions) + - "Guide is too long" (1) - "Can't skip the guide" (1) ## Neutral Feedback (3 mentions) + - "Didn't notice the change" (3) ``` @@ -147,15 +154,16 @@ metrics: Example: "Design Delivery DD-XXX successfully improved Feature X usage from - 15% to 58%, nearly meeting the 60% target. Drop-off decreased - from 40% to 12%, exceeding the 10% target. User feedback is - overwhelmingly positive." +15% to 58%, nearly meeting the 60% target. Drop-off decreased +from 40% to 12%, exceeding the 10% target. User feedback is +overwhelmingly positive." --- ## Metrics Results ### Metric 1: Feature X Usage Rate + - **Baseline:** 15% - **Target:** 60% - **Actual:** 58% @@ -163,6 +171,7 @@ Example: - **Trend:** Steady increase over 2 weeks ### Metric 2: Drop-off Rate + - **Baseline:** 40% - **Target:** 10% - **Actual:** 12% @@ -170,12 +179,14 @@ Example: - **Trend:** Sharp decrease in first week, stabilized ### Metric 3: Support Tickets + - **Baseline:** 12/month - **Target:** 2/month - **Actual:** 3/month - **Result:** 75% reduction ✅ (PASS) ### Metric 4: User Satisfaction + - **Baseline:** 3.2/5 - **Target:** 4.5/5 - **Actual:** 4.3/5 @@ -186,6 +197,7 @@ Example: ## Overall Assessment **Success Criteria:** + - Feature X usage > 50% ✅ - Drop-off < 15% ✅ - Support tickets < 5/month ✅ @@ -243,11 +255,13 @@ All success criteria met or exceeded. ## Recommendations ### Short-term (Next Sprint) + 1. Add "Skip" button to guide 2. Shorten guide from 5 steps to 3 steps 3. A/B test guide length ### Long-term (Next Quarter) + 1. Apply onboarding pattern to other features 2. Create reusable onboarding component 3. Measure onboarding impact across product @@ -262,7 +276,7 @@ All success criteria met or exceeded. Example: "Feature Y has similar low usage (20%). Apply same onboarding - pattern to Feature Y in next Kaizen cycle." +pattern to Feature Y in next Kaizen cycle." --- @@ -322,18 +336,18 @@ WDS Designer ```yaml delivery: - status: "measured" - measurement_complete: "2024-12-28T10:00:00Z" - impact_report: "analytics/DD-XXX-impact-report.md" - result: "success" + status: 'measured' + measurement_complete: '2024-12-28T10:00:00Z' + impact_report: 'analytics/DD-XXX-impact-report.md' + result: 'success' metrics_achieved: - - "Feature X usage: 58% (target: 60%)" - - "Drop-off: 12% (target: 10%)" - - "Support tickets: 3/month (target: 2/month)" + - 'Feature X usage: 58% (target: 60%)' + - 'Drop-off: 12% (target: 10%)' + - 'Support tickets: 3/month (target: 2/month)' learnings: - - "Onboarding matters for complex features" - - "Small changes have big impact" - - "Measurement validates hypotheses" + - 'Onboarding matters for complex features' + - 'Small changes have big impact' + - 'Measurement validates hypotheses' ``` --- @@ -376,16 +390,19 @@ After monitoring and learning: ### DO ✅ **Be patient:** + - Give changes time to work - Don't end measurement early - Wait for trends to stabilize **Be thorough:** + - Track all metrics - Gather qualitative feedback - Document learnings **Be honest:** + - Report actual results - Acknowledge what didn't work - Learn from failures @@ -393,16 +410,19 @@ After monitoring and learning: ### DON'T ❌ **Don't cherry-pick:** + - Report all metrics, not just good ones - Be honest about failures - Learn from everything **Don't stop measuring:** + - Kaizen requires continuous measurement - Always be monitoring - Always be learning **Don't skip sharing:** + - Team needs to know results - Celebrate successes - Learn from failures together diff --git a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md index 7b353dbc..fd38a0e2 100644 --- a/src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md +++ b/src/modules/wds/workflows/8-ongoing-development/steps/step-8.8-iterate.md @@ -9,6 +9,7 @@ Use learnings from this cycle to identify and start the next improvement. ## Before You Start **Ensure you have:** + - ✅ Completed step 8.7 (impact measured) - ✅ Impact report created - ✅ Learnings documented @@ -35,12 +36,14 @@ Ship → Monitor → Learn → Improve → Ship → Monitor → Learn... **Two approaches from Lean manufacturing:** ### Kaizen (改善) - What You're Doing Now + - **Small, incremental changes** (1-2 weeks) - **Low cost, low risk** - **Continuous, never stops** - **Phase 8: Ongoing Development** ### Kaikaku (改革) - Revolutionary Change + - **Large, radical changes** (months) - **High cost, high risk** - **One-time transformation** @@ -62,23 +65,28 @@ Ship → Monitor → Learn → Improve → Ship → Monitor → Learn... # Learnings from DD-XXX ## What Worked + 1. [Learning 1] 2. [Learning 2] 3. [Learning 3] ## What Didn't Work + 1. [Learning 1] 2. [Learning 2] ## Patterns Emerging + 1. [Pattern 1] 2. [Pattern 2] ## Hypotheses Validated + 1. [Hypothesis 1]: ✅ Confirmed 2. [Hypothesis 2]: ❌ Rejected ## New Questions + 1. [Question 1] 2. [Question 2] ``` @@ -97,15 +105,18 @@ Ship → Monitor → Learn → Improve → Ship → Monitor → Learn... # Next Iteration: DD-XXX Refinement **Current Status:** + - Feature X usage: 58% (target: 60%) - User feedback: "Guide too long" **Next Improvement:** + - Shorten guide from 5 steps to 3 steps - Add "Skip" button - A/B test guide length **Expected Impact:** + - Feature X usage: 58% → 65% - User satisfaction: 4.3/5 → 4.7/5 @@ -126,6 +137,7 @@ Ship → Monitor → Learn → Improve → Ship → Monitor → Learn... "Onboarding increases usage 4x for complex features" **Similar Problem:** + - Feature Y usage: 20% (low) - User feedback: "Don't understand Feature Y" - Similar complexity to Feature X @@ -134,6 +146,7 @@ Ship → Monitor → Learn → Improve → Ship → Monitor → Learn... Apply same onboarding pattern to Feature Y **Expected Impact:** + - Feature Y usage: 20% → 80% (4x increase) - Based on DD-XXX results @@ -151,6 +164,7 @@ Apply same onboarding pattern to Feature Y # Next Opportunity: New Problem Identified **New Data:** + - Feature Z drop-off: 35% (increased from 20%) - User feedback: "Feature Z is slow" - Analytics: Load time 5 seconds (was 2 seconds) @@ -162,6 +176,7 @@ Recent update added heavy images, slowing load time Optimize images and implement lazy loading **Expected Impact:** + - Load time: 5s → 2s - Drop-off: 35% → 20% @@ -183,18 +198,21 @@ Optimize images and implement lazy loading # Kaizen Prioritization ## Option A: Refine DD-XXX + - Impact: Medium (58% → 65%) - Effort: Low (1 day) - Learning: Low (incremental) - Priority: MEDIUM ## Option B: Apply to Feature Y + - Impact: High (20% → 80%) - Effort: Low (2 days) - Learning: High (validates pattern) - Priority: HIGH ✅ ## Option C: Fix Feature Z Performance + - Impact: Medium (35% → 20% drop-off) - Effort: Low (1 day) - Learning: Medium (performance optimization) @@ -219,6 +237,7 @@ Optimize images and implement lazy loading # Kaizen Cycle Log ## Cycle 1: DD-001 Feature X Onboarding + - Started: 2024-12-09 - Completed: 2024-12-28 - Result: SUCCESS ✅ @@ -226,6 +245,7 @@ Optimize images and implement lazy loading - Learning: Onboarding matters for complex features ## Cycle 2: DD-002 Feature Y Onboarding + - Started: 2024-12-28 - Status: In Progress - Goal: Apply validated pattern to similar feature @@ -275,10 +295,12 @@ Result after 4 months: ### 1. Focus on Process, Not Just Results **Bad:** + - "We need to increase usage!" - (Pressure, no learning) **Good:** + - "Let's understand why usage is low, test a hypothesis, measure impact, and learn." - (Process, continuous learning) @@ -287,6 +309,7 @@ Result after 4 months: ### 2. Eliminate Waste (Muda 無駄) **Types of waste in design:** + - **Overproduction:** Designing features nobody uses - **Waiting:** Blocked on approvals or development - **Transportation:** Handoff friction @@ -296,6 +319,7 @@ Result after 4 months: - **Defects:** Bugs and rework **Kaizen eliminates waste through:** + - Small, focused improvements - Fast cycles (ship → learn → improve) - Continuous measurement @@ -306,6 +330,7 @@ Result after 4 months: ### 3. Respect People and Their Insights **Listen to:** + - Users (feedback, behavior) - Developers (technical insights) - Support (pain points) @@ -321,27 +346,32 @@ Result after 4 months: **When you find a pattern that works:** 1. **Document it** + ```markdown # Pattern: Onboarding for Complex Features - + **When to use:** + - Feature has low usage (<30%) - User feedback indicates confusion - Feature is complex or non-obvious - + **How to implement:** + 1. Inline tooltip explaining purpose 2. Step-by-step guide for first action 3. Success celebration 4. Help button for future reference - + **Expected impact:** + - Usage increase: 3-4x - Drop-off decrease: 50-70% - Effort: 2-3 days ``` 2. **Create reusable components** + ``` D-Design-System/03-Atomic-Components/ ├── Tooltips/Tooltip-Inline.md @@ -375,16 +405,19 @@ Result after 4 months: **Success Rate:** 78% (7/9 successful) **Impact:** + - Feature usage improvements: 6 features (+40% avg) - Performance improvements: 2 features (+15% avg) - User satisfaction: 3.2/5 → 4.1/5 (+28%) **Learnings:** + - 12 patterns documented - 8 reusable components created - 3 hypotheses validated **Team Growth:** + - Designer: Faster iteration - Developer: Better collaboration - Product: Data-driven decisions @@ -397,16 +430,19 @@ Result after 4 months: **Kaizen never stops, but you might pause for:** ### 1. Major Strategic Shift + - New product direction - Pivot or rebrand - Complete redesign needed ### 2. Team Capacity + - Team overwhelmed - Need to catch up on backlog - Need to stabilize ### 3. Measurement Period + - Waiting for data - Seasonal variations - External factors @@ -508,4 +544,4 @@ Result: --- -**Remember:** Great products aren't built in one big redesign. They're built through continuous, disciplined improvement. One cycle at a time. Forever.** 🎯✨🔄 +**Remember:** Great products aren't built in one big redesign. They're built through continuous, disciplined improvement. One cycle at a time. Forever.\*\* 🎯✨🔄 diff --git a/src/modules/wds/workflows/8-ongoing-development/workflow.md b/src/modules/wds/workflows/8-ongoing-development/workflow.md index 2f6699e1..355218bd 100644 --- a/src/modules/wds/workflows/8-ongoing-development/workflow.md +++ b/src/modules/wds/workflows/8-ongoing-development/workflow.md @@ -30,6 +30,7 @@ Phase 8 is about **Kaizen (改善)** - the Japanese philosophy of continuous imp **Definition:** Small, incremental, continuous improvements over time. **Characteristics:** + - Small changes (1-2 weeks each) - Low cost, low risk - Everyone participates @@ -39,6 +40,7 @@ Phase 8 is about **Kaizen (改善)** - the Japanese philosophy of continuous imp - Bottom-up approach **In product design:** + - Ship → Learn → Improve → Ship → Repeat - Small updates beat big redesigns - User feedback drives improvements @@ -47,6 +49,7 @@ Phase 8 is about **Kaizen (改善)** - the Japanese philosophy of continuous imp - Team learns continuously **Example:** + - Add onboarding tooltip to improve feature usage - Optimize button color for better conversion - Improve error message clarity @@ -62,6 +65,7 @@ Phase 8 is about **Kaizen (改善)** - the Japanese philosophy of continuous imp **Definition:** Radical, revolutionary transformation in a short period. **Characteristics:** + - Large changes (months) - High cost, high risk - Leadership-driven @@ -71,6 +75,7 @@ Phase 8 is about **Kaizen (改善)** - the Japanese philosophy of continuous imp - Top-down approach **In product design:** + - Complete redesign - Platform migration - Architecture overhaul @@ -78,6 +83,7 @@ Phase 8 is about **Kaizen (改善)** - the Japanese philosophy of continuous imp - Business model pivot **Example:** + - Complete product redesign - Migrate from web to mobile-first - Rebrand entire product @@ -90,6 +96,7 @@ Phase 8 is about **Kaizen (改善)** - the Japanese philosophy of continuous imp ### When to Use Each **Use Kaizen (改善) when:** + - ✅ Product is live and working - ✅ Need continuous improvement - ✅ Want low-risk changes @@ -98,6 +105,7 @@ Phase 8 is about **Kaizen (改善)** - the Japanese philosophy of continuous imp - ✅ **Phase 8: Ongoing Development** **Use Kaikaku (改革) when:** + - ✅ Starting from scratch (greenfield) - ✅ Product needs complete overhaul - ✅ Market demands radical change @@ -224,9 +232,11 @@ You: "Time for a Kaizen cycle to improve Feature X." Load and execute the appropriate step file based on your context: **Existing Product Entry Point:** + - `steps/step-8.1-identify-challenge.md` **Continuous Improvement:** + - `steps/step-8.1-monitor-performance.md` **Note:** Each step will guide you to the next step when ready. @@ -247,12 +257,14 @@ Load and execute the appropriate step file based on your context: ## Key Differences from Phases 1-7 **Phase 8 is NOT about:** + - ❌ Complete redesigns - ❌ Designing full user flows from scratch - ❌ Starting with blank canvas - ❌ Defining tech stack (already decided) **Phase 8 IS about:** + - ✅ Strategic, targeted improvements - ✅ Updating existing screens and features - ✅ Incremental changes that compound @@ -270,6 +282,7 @@ This cycle never stops! ``` **Each cycle:** + - Takes 1-2 weeks (small changes) - Focuses on one improvement - Ships to production @@ -277,6 +290,7 @@ This cycle never stops! - Informs next cycle **Over time:** + - Small improvements compound - Product quality increases - User satisfaction grows diff --git a/src/modules/wds/workflows/paths/design-system-only.yaml b/src/modules/wds/workflows/paths/design-system-only.yaml index 15ff58af..bade437d 100644 --- a/src/modules/wds/workflows/paths/design-system-only.yaml +++ b/src/modules/wds/workflows/paths/design-system-only.yaml @@ -59,4 +59,3 @@ phases: command: "design-system" output: "Complete component documentation, HTML showcase" note: "The primary deliverable for this path" - diff --git a/src/modules/wds/workflows/paths/digital-strategy.yaml b/src/modules/wds/workflows/paths/digital-strategy.yaml index eb570dc2..571635ce 100644 --- a/src/modules/wds/workflows/paths/digital-strategy.yaml +++ b/src/modules/wds/workflows/paths/digital-strategy.yaml @@ -36,4 +36,3 @@ phases: command: "trigger-mapping" output: "Trigger Map with personas, business goals, Feature Impact Analysis" note: "Strategic user research and prioritization" - diff --git a/src/modules/wds/workflows/paths/feature-enhancement.yaml b/src/modules/wds/workflows/paths/feature-enhancement.yaml index 2b51d1b9..503504e2 100644 --- a/src/modules/wds/workflows/paths/feature-enhancement.yaml +++ b/src/modules/wds/workflows/paths/feature-enhancement.yaml @@ -90,4 +90,3 @@ phases: command: "prd-finalization" output: "Feature requirements, integration notes, handoff" note: "Compile feature requirements for development" - diff --git a/src/modules/wds/workflows/paths/full-product.yaml b/src/modules/wds/workflows/paths/full-product.yaml index 724376a3..e9b23f9d 100644 --- a/src/modules/wds/workflows/paths/full-product.yaml +++ b/src/modules/wds/workflows/paths/full-product.yaml @@ -93,4 +93,3 @@ phases: command: "prd-finalization" output: "Complete PRD, development roadmap, handoff package" note: "Can run multiple times as design progresses" - diff --git a/src/modules/wds/workflows/paths/landing-page.yaml b/src/modules/wds/workflows/paths/landing-page.yaml index 21a54236..96fa42db 100644 --- a/src/modules/wds/workflows/paths/landing-page.yaml +++ b/src/modules/wds/workflows/paths/landing-page.yaml @@ -51,4 +51,3 @@ phases: command: "design-system" output: "Component documentation" note: "Optional - skip for truly simple one-off pages" - diff --git a/src/modules/wds/workflows/paths/quick-prototype.yaml b/src/modules/wds/workflows/paths/quick-prototype.yaml index 30f8d169..8507f1a7 100644 --- a/src/modules/wds/workflows/paths/quick-prototype.yaml +++ b/src/modules/wds/workflows/paths/quick-prototype.yaml @@ -36,4 +36,3 @@ phases: command: "ux-design" output: "Quick specifications and HTML prototypes" note: "Focus on getting something visible fast" - diff --git a/src/modules/wds/workflows/workflow-init/excalidraw-setup-prompt.md b/src/modules/wds/workflows/workflow-init/excalidraw-setup-prompt.md index 866f56c2..51550abb 100644 --- a/src/modules/wds/workflows/workflow-init/excalidraw-setup-prompt.md +++ b/src/modules/wds/workflows/workflow-init/excalidraw-setup-prompt.md @@ -27,6 +27,7 @@ Excalidraw is a free, open-source whiteboard tool that: ✓ Version control friendly (JSON files) Would you like me to configure Excalidraw for this project? (y/n) + ``` @@ -40,17 +41,20 @@ Would you like me to configure Excalidraw for this project? (y/n) ``` + Excalidraw files (.excalidraw) don't display in GitHub by default. They need to be exported to PNG/SVG for documentation. Would you like automatic export enabled? Options: + 1. Manual export (you export when needed) 2. Auto-export (GitHub Actions exports automatically on save) Your choice (1/2): -``` + +```` **Record:** @@ -58,7 +62,7 @@ Your choice (1/2): excalidraw: auto_export: true # if option 2 auto_export: false # if option 1 -``` +```` **Note:** If auto-export chosen, inform user that GitHub Actions setup will be needed @@ -74,7 +78,8 @@ WDS includes an Excalidraw component library with: - Layout templates Would you like to use the WDS component library? (y/n) -``` + +```` **Record:** @@ -82,7 +87,7 @@ Would you like to use the WDS component library? (y/n) excalidraw: use_library: true # if yes use_library: false # if no -``` +```` --- @@ -95,12 +100,14 @@ Excalidraw can snap elements to a grid for alignment. WDS recommends 20px grid (matches spacing system). Grid settings: + 1. 20px grid with snap (recommended) 2. 10px grid with snap (finer control) 3. No grid (free-form) Your choice (1/2/3): -``` + +```` **Record:** @@ -111,7 +118,7 @@ excalidraw: grid_size: 0 # if option 3 snap_to_grid: true # if option 1 or 2 snap_to_grid: false # if option 3 -``` +```` --- @@ -125,7 +132,8 @@ Choose default Excalidraw theme: 2. Dark (easier on eyes for long sessions) Your choice (1/2): -``` + +```` **Record:** @@ -133,7 +141,7 @@ Your choice (1/2): excalidraw: theme: "light" # if option 1 theme: "dark" # if option 2 -``` +```` --- @@ -148,12 +156,12 @@ Configuration saved to: project-config.yaml NEXT STEPS: 1. Install Excalidraw (choose one): - + Option A: VS Code Extension (Recommended) - Open Extensions (Ctrl+Shift+X) - Search "Excalidraw" - Install "Excalidraw Editor" - + Option B: Web App - Go to https://excalidraw.com - No installation needed @@ -169,12 +177,14 @@ NEXT STEPS: - Theme: {{THEME}} DOCUMENTATION: + - Setup Guide: workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md - Sketching Guide: workflows/4-ux-design/excalidraw-integration/sketching-guide.md - AI Collaboration: workflows/4-ux-design/excalidraw-integration/ai-collaboration.md Ready to start sketching! 🎨 -``` + +```` --- @@ -186,7 +196,7 @@ Ready to start sketching! 🎨 ```yaml sketching: tool: excalidraw - + excalidraw: enabled: true auto_export: {{USER_CHOICE}} @@ -195,7 +205,7 @@ sketching: snap_to_grid: {{USER_CHOICE}} theme: {{USER_CHOICE}} sketches_folder: "sketches" -``` +```` --- @@ -206,18 +216,21 @@ sketching: No problem! You can use any sketching tool you prefer. Common alternatives: + - Paper and pen (photograph/scan) - Figma (professional design tool) - iPad + Apple Pencil - Other digital whiteboard tools WDS works with any sketching method. Just: + 1. Create your sketches 2. Export to PNG/JPG 3. Upload to AI for analysis 4. Save in scenario sketches folder Configuration saved with: sketching.tool: "other" + ``` @@ -229,26 +242,32 @@ Configuration saved with: sketching.tool: "other" **If Excalidraw enabled:** ``` + Agent: "I see you've configured Excalidraw for this project. Would you like to: + 1. Sketch manually in Excalidraw 2. Have me generate layout variations in Excalidraw 3. Use a different tool for this scenario Your choice:" + ``` **If Excalidraw not enabled:** ``` + Agent: "Time to sketch the interface. You can: + 1. Sketch on paper (photograph/scan) 2. Use your preferred digital tool 3. Enable Excalidraw now (if you'd like) Your choice:" + ``` --- @@ -259,6 +278,7 @@ Your choice:" ``` + Not sure if Excalidraw is right for you? PROS: @@ -278,6 +298,7 @@ Try it! You can always switch tools later. Configuration can be changed in project-config.yaml. Would you like to enable Excalidraw? (y/n) + ``` @@ -285,23 +306,23 @@ Would you like to enable Excalidraw? (y/n) ``` + Having trouble installing Excalidraw? FALLBACK OPTIONS: 1. Use web version (no installation): https://excalidraw.com - 2. Use different tool temporarily: - Paper and pen - Figma - Other whiteboard tool - 3. Skip sketching for now: - Describe interface verbally - AI can generate sketches later Your choice: + ``` @@ -311,9 +332,11 @@ Your choice: **Create folder structure:** ``` + C-Scenarios/ └── [scenario-name]/ - └── sketches/ ← Created automatically +└── sketches/ ← Created automatically + ``` **If use_library: true:** @@ -339,3 +362,4 @@ C-Scenarios/ --- **This prompt ensures smooth Excalidraw setup tailored to user preferences!** ⚙️✨ +``` diff --git a/src/modules/wds/workflows/workflow-init/instructions.md b/src/modules/wds/workflows/workflow-init/instructions.md index 89b5f45c..b1210cac 100644 --- a/src/modules/wds/workflows/workflow-init/instructions.md +++ b/src/modules/wds/workflows/workflow-init/instructions.md @@ -16,15 +16,16 @@ Let's figure out which phases you need. Tell me about your project in a few sentences. What are you designing? Store user_description Analyze description for project indicators: + - "landing page", "single page", "simple" → landing-page path - "product", "platform", "app", "system", "full" → full-product path - "strategy", "research", "discovery", "planning" → digital-strategy path - "design system", "components", "library" → design-system path - "feature", "enhancement", "addition" → feature-enhancement path - "quick", "prototype", "poc", "test" → quick-prototype path - -user_description - + + user_description + Based on what you shared, this sounds like a **{{detected_project_type}}** project. @@ -70,7 +71,7 @@ Best for: Building component libraries Phase 4 only Best for: Rapid prototyping, proof of concepts - Which fits your project? +Which fits your project? 1. Full Product 2. Landing Page @@ -80,7 +81,7 @@ Best for: Rapid prototyping, proof of concepts 6. Quick Prototype Choice [1-6]: - Map choice to project_type +Map choice to project_type project_type @@ -93,23 +94,25 @@ Choice [1-6]: For **{{project_type}}** projects, a **Complete Project Brief** is included. This covers: + - Vision & positioning - Target users (ICP) - Success criteria - Competitive landscape - Strategic constraints Set brief_level = "complete" - + For **{{project_type}}** projects, a **Simplified Project Brief** keeps things fast. This covers: + - Scope & challenge - Opportunity - Design goals Set brief_level = "simplified" - + Project Brief depth: @@ -118,14 +121,13 @@ This covers: - Scope & challenge - Opportunity - Design goals - Best for: Quick features, time-pressured work - + Best for: Quick features, time-pressured work 2. **Complete** (30-60 min) - Vision & positioning - Target users (ICP) - Success criteria - Competitive landscape - Best for: When you want strategic clarity + Best for: When you want strategic clarity Choice [1/2]: @@ -147,6 +149,7 @@ Choice [1/2]: **Specification Language** - What language should WDS write the design specifications in? Common choices: + 1. **English** (EN) - Default, widely used 2. **Swedish** (SE) 3. **Norwegian** (NO) @@ -162,6 +165,7 @@ Choice [1-5]: List them separated by commas (e.g., "EN, SE" or "EN, SE, NO, DK"): Common language codes: + - EN = English - SE = Swedish - NO = Norwegian @@ -177,6 +181,7 @@ Product languages: product_languages ✅ **Language Configuration:** + - **Specifications written in:** {{specification_language}} - **Product supports:** {{product_languages_list}} @@ -191,7 +196,6 @@ All text specifications will include translations for: {{product_languages_list} 1. **Letters** (A-Product-Brief, B-Trigger-Map, C-...) - Distinctive WDS branding - Easy visual grouping - 2. **Numbers** (01-Product-Brief, 02-Trigger-Map, 03-...) - Traditional sequential numbering - Familiar format @@ -204,7 +208,6 @@ Choice [1/2]: 1. **Title-Case** (A-Product-Brief, B-Trigger-Map) - Easier to read for non-technical stakeholders - 2. **lowercase** (a-product-brief, b-trigger-map) - Developer-friendly convention @@ -233,21 +236,22 @@ Choice [1/2/3]: - You plan to hand off to developers who need component docs Skip Design System if: + - It's a simple, one-off project - You're using an existing design system (Material, Chakra, etc.) - You need to move fast without component documentation - Based on this, include Design System? (y/n) - Set include_design_system based on answer + Based on this, include Design System? (y/n) + Set include_design_system based on answer - - Set include_design_system = true - + + Set include_design_system = true + - - Set include_design_system = false + + Set include_design_system = false + - Set include_design_system = true @@ -272,8 +276,8 @@ Skip Design System if: 8. **Undecided** - I'll choose during the project Choice [1-8]: - Set component_library based on choice - component_library +Set component_library based on choice +component_library @@ -307,8 +311,9 @@ Choice [1-8]: **Phases enabled:** {{#each enabled_phases}} + - Phase {{this.number}}: {{this.name}} → `{{this.folder}}/` -{{/each}} + {{/each}} **Folder naming:** {{folder_prefix}} + {{folder_case}} Example: `{{example_folder_name}}` @@ -341,12 +346,12 @@ Happy designing! 🎨 You can also manually create your project structure: {{#each enabled_phases}} + - Create `docs/{{this.folder}}/` for {{this.name}} -{{/each}} + {{/each}} Happy designing! 🎨 - diff --git a/src/modules/wds/workflows/workflow-init/project-config.template.yaml b/src/modules/wds/workflows/workflow-init/project-config.template.yaml index 4c5d9b5a..df7ada43 100644 --- a/src/modules/wds/workflows/workflow-init/project-config.template.yaml +++ b/src/modules/wds/workflows/workflow-init/project-config.template.yaml @@ -9,46 +9,46 @@ project: # Design System Configuration design_system: - enabled: {{DESIGN_SYSTEM_ENABLED}} # true | false - mode: "{{DESIGN_SYSTEM_MODE}}" # "none" | "custom" | "library" - + enabled: { { DESIGN_SYSTEM_ENABLED } } # true | false + mode: "{{DESIGN_SYSTEM_MODE}}" # "none" | "custom" | "library" + # If mode: custom figma: - enabled: {{FIGMA_ENABLED}} # true | false - file_url: "{{FIGMA_URL}}" # Figma file URL (if applicable) - + enabled: { { FIGMA_ENABLED } } # true | false + file_url: "{{FIGMA_URL}}" # Figma file URL (if applicable) + # If mode: library library: - name: "{{LIBRARY_NAME}}" # e.g., "shadcn/ui", "MUI", "Radix" - version: "{{LIBRARY_VERSION}}" # e.g., "1.0.0" + name: "{{LIBRARY_NAME}}" # e.g., "shadcn/ui", "MUI", "Radix" + version: "{{LIBRARY_VERSION}}" # e.g., "1.0.0" # Sketching Tool Configuration sketching: - tool: "{{SKETCHING_TOOL}}" # "paper" | "excalidraw" | "figma" | "other" - + tool: "{{SKETCHING_TOOL}}" # "paper" | "excalidraw" | "figma" | "other" + # If tool: excalidraw excalidraw: - enabled: {{EXCALIDRAW_ENABLED}} # true | false - + enabled: { { EXCALIDRAW_ENABLED } } # true | false + # Auto-export to PNG/SVG on save - auto_export: {{AUTO_EXPORT}} # true | false - + auto_export: { { AUTO_EXPORT } } # true | false + # Load WDS component library - use_library: {{USE_LIBRARY}} # true | false - + use_library: { { USE_LIBRARY } } # true | false + # Grid settings - grid_size: {{GRID_SIZE}} # pixels (recommended: 20) - snap_to_grid: {{SNAP_TO_GRID}} # true | false - + grid_size: { { GRID_SIZE } } # pixels (recommended: 20) + snap_to_grid: { { SNAP_TO_GRID } } # true | false + # Default theme - theme: "{{THEME}}" # "light" | "dark" - + theme: "{{THEME}}" # "light" | "dark" + # File organization - sketches_folder: "sketches" # relative to scenario folder + sketches_folder: "sketches" # relative to scenario folder # Output Folders output: - root: "." # Project root + root: "." # Project root project_brief: "A-Project-Brief" trigger_map: "B-Trigger-Map" scenarios: "C-Scenarios" @@ -58,18 +58,18 @@ output: workflow: # Phase 4: UX Design ux_design: - sketch_first: {{SKETCH_FIRST}} # true | false - ai_suggestions: {{AI_SUGGESTIONS}} # true | false - + sketch_first: { { SKETCH_FIRST } } # true | false + ai_suggestions: { { AI_SUGGESTIONS } } # true | false + # Phase 5: Design System design_system: - auto_extract: {{AUTO_EXTRACT}} # true | false - similarity_threshold: {{SIMILARITY_THRESHOLD}} # 0.0-1.0 (recommended: 0.7) + auto_extract: { { AUTO_EXTRACT } } # true | false + similarity_threshold: { { SIMILARITY_THRESHOLD } } # 0.0-1.0 (recommended: 0.7) # Team Configuration team: designer: "{{DESIGNER_NAME}}" - stakeholders: [] # Add stakeholder names + stakeholders: [] # Add stakeholder names # Notes notes: | diff --git a/src/modules/wds/workflows/workflow-init/project-type-selection.md b/src/modules/wds/workflows/workflow-init/project-type-selection.md index 8733d3b3..4ae067a6 100644 --- a/src/modules/wds/workflows/workflow-init/project-type-selection.md +++ b/src/modules/wds/workflows/workflow-init/project-type-selection.md @@ -18,11 +18,13 @@ Which type of project are you working on? ## Software Development Terminology ### Greenfield Development + **Definition:** Building a new project from scratch with no constraints from existing systems. **Origin:** Agricultural term - plowing a green field that has never been cultivated. **In software:** + - No legacy code to maintain - Full creative freedom - Define architecture from scratch @@ -32,11 +34,13 @@ Which type of project are you working on? --- ### Brownfield Development + **Definition:** Developing within an existing system with established constraints. **Origin:** Industrial term - redeveloping land previously used for industrial purposes. **In software:** + - Existing codebase to work with - Legacy systems to integrate - Established patterns to follow @@ -48,6 +52,7 @@ Which type of project are you working on? ## Option 1: New Product (Greenfield) **Choose this if:** + - ✅ Starting from scratch - ✅ No existing product or codebase - ✅ Designing complete user flows @@ -56,12 +61,14 @@ Which type of project are you working on? - ✅ **Greenfield development** **You'll start with:** + - Phase 1: Project Brief (full) - Phase 2: Trigger Map (complete) - Phase 3: Platform Requirements (define tech stack) - Phases 4-7: Iterative development **Example scenarios:** + - "We're building a new dog care app from scratch" - "Startup launching first product" - "New feature that's completely separate from existing product" @@ -71,6 +78,7 @@ Which type of project are you working on? ## Option 2: Existing Product (Brownfield) **Choose this if:** + - ✅ Product already exists and is live - ✅ Brought in as "linchpin designer" to solve specific problems - ✅ Making strategic improvements, not complete redesign @@ -79,12 +87,14 @@ Which type of project are you working on? - ✅ **Brownfield development** **You'll start with:** + - Phase 8.1: Limited Project Brief (strategic challenge) - Phase 8.2: Existing Context (upload materials, print trigger map) - Phase 8.3: Critical Updates (targeted changes) - Phase 8.4-8.5: Delivery and validation **Example scenarios:** + - "Onboarding has 60% drop-off, need to redesign it" - "Users don't understand key feature, need UX improvements" - "Adding new feature to existing product" @@ -94,16 +104,16 @@ Which type of project are you working on? ## Comparison -| Aspect | New Product | Existing Product | -|--------|-------------|------------------| -| **Entry Point** | Phase 1 | Phase 8 | -| **Project Brief** | Full (vision, goals, stakeholders) | Limited (strategic challenge) | -| **Trigger Map** | Complete (all user needs) | Focused (specific problem) | -| **Platform Requirements** | Define from scratch | Already decided | -| **Design Scope** | Complete user flows | Targeted updates | -| **Creative Freedom** | High | Constrained | -| **Timeline** | Months | Weeks | -| **Deliverables** | Multiple Design Deliveries | Design Deliveries (small scope) | +| Aspect | New Product | Existing Product | +| ------------------------- | ---------------------------------- | ------------------------------- | +| **Entry Point** | Phase 1 | Phase 8 | +| **Project Brief** | Full (vision, goals, stakeholders) | Limited (strategic challenge) | +| **Trigger Map** | Complete (all user needs) | Focused (specific problem) | +| **Platform Requirements** | Define from scratch | Already decided | +| **Design Scope** | Complete user flows | Targeted updates | +| **Creative Freedom** | High | Constrained | +| **Timeline** | Months | Weeks | +| **Deliverables** | Multiple Design Deliveries | Design Deliveries (small scope) | --- @@ -150,22 +160,22 @@ First, what's the strategic challenge you're trying to solve? ```yaml project: - type: "new_product" # or "existing_product" - entry_point: "phase_1" # or "phase_8" + type: 'new_product' # or "existing_product" + entry_point: 'phase_1' # or "phase_8" # If existing_product: existing_product: - strategic_challenge: "Onboarding has 60% drop-off rate" - scope: "Redesign onboarding flow (4 screens)" + strategic_challenge: 'Onboarding has 60% drop-off rate' + scope: 'Redesign onboarding flow (4 screens)' constraints: - - "Tech stack: React Native + Supabase (fixed)" - - "Brand: Colors and logo are fixed" - - "Timeline: 2 weeks" - + - 'Tech stack: React Native + Supabase (fixed)' + - 'Brand: Colors and logo are fixed' + - 'Timeline: 2 weeks' + existing_materials: - business_goals: "path/to/business-goals.pdf" - user_research: "path/to/user-research.pdf" - current_design_system: "path/to/design-system/" + business_goals: 'path/to/business-goals.pdf' + user_research: 'path/to/user-research.pdf' + current_design_system: 'path/to/design-system/' ``` --- @@ -217,12 +227,14 @@ Phase 8.5: Validation ← [Touch Point 3] ## Tips for Choosing ### Choose New Product if: + - You have time to design properly - You want to establish best practices - You're defining the product vision - You have creative freedom ### Choose Existing Product if: + - You're solving a specific problem - Timeline is tight (weeks, not months) - Product is already live @@ -231,6 +243,7 @@ Phase 8.5: Validation ← [Touch Point 3] ### Not Sure? **Ask yourself:** + 1. Is there already a live product? → Existing Product 2. Are you starting from scratch? → New Product 3. Are you redesigning one specific area? → Existing Product @@ -243,6 +256,7 @@ Phase 8.5: Validation ← [Touch Point 3] ### New Product Examples **Dog Week App:** + - Type: New Product - Entry: Phase 1 - Scope: Complete app from scratch @@ -250,6 +264,7 @@ Phase 8.5: Validation ← [Touch Point 3] - Deliveries: 10-15 Design Deliveries **SaaS Dashboard:** + - Type: New Product - Entry: Phase 1 - Scope: Complete dashboard experience @@ -261,6 +276,7 @@ Phase 8.5: Validation ← [Touch Point 3] ### Existing Product Examples **Onboarding Flow Improvement:** + - Type: Existing Product - Challenge: 60% drop-off rate - Scope: 4 screens @@ -268,6 +284,7 @@ Phase 8.5: Validation ← [Touch Point 3] - Delivery: 1 Design Delivery (DD-XXX, small scope) **Checkout Flow Improvement:** + - Type: Existing Product - Challenge: Low conversion rate - Scope: 3 screens + payment flow @@ -275,6 +292,7 @@ Phase 8.5: Validation ← [Touch Point 3] - Delivery: 1 Design Delivery (DD-XXX, small scope) **New Feature Addition:** + - Type: Existing Product - Challenge: Users requesting calendar view - Scope: New calendar feature diff --git a/src/modules/wds/workflows/workflow-init/workflow.yaml b/src/modules/wds/workflows/workflow-init/workflow.yaml index b9a98b19..533db5f4 100644 --- a/src/modules/wds/workflows/workflow-init/workflow.yaml +++ b/src/modules/wds/workflows/workflow-init/workflow.yaml @@ -3,7 +3,6 @@ name: WDS Workflow Init description: Initialize a WDS design project by selecting phases based on project needs web_bundle: true --- - # WDS Workflow Init - Project Setup name: wds-workflow-init author: "Whiteport Design Studio" @@ -18,8 +17,8 @@ document_output_language: "{config_source}:document_output_language" date: system-generated # Folder naming configuration (set during init) -folder_prefix: "letters" # letters or numbers -folder_case: "title" # title or lowercase +folder_prefix: "letters" # letters or numbers +folder_case: "title" # title or lowercase # Workflow components installed_path: "{project-root}/{bmad_folder}/wds/workflows/workflow-init" @@ -34,4 +33,3 @@ default_output_file: "{output_folder}/wds-workflow-status.yaml" standalone: true web_bundle: false - diff --git a/src/modules/wds/workflows/workflow-status/instructions.md b/src/modules/wds/workflows/workflow-status/instructions.md index d99fbedc..7ff6469d 100644 --- a/src/modules/wds/workflows/workflow-status/instructions.md +++ b/src/modules/wds/workflows/workflow-status/instructions.md @@ -15,7 +15,7 @@ To get started, run the workflow-init: `/bmad:wds:workflows:workflow-init` Or activate any WDS agent (Saga, Idunn, or Freyja) and describe your project. - Exit workflow +Exit workflow Load and parse wds-workflow-status.yaml @@ -29,12 +29,13 @@ Or activate any WDS agent (Saga, Idunn, or Freyja) and describe your project. Identify: + - completed_phases: Phases with all artifacts - current_phase: First incomplete required phase - next_agent: Agent for current phase - blocked_phases: Phases waiting on dependencies - - + + **WDS Project Status** 🎨 @@ -50,12 +51,12 @@ Or activate any WDS agent (Saga, Idunn, or Freyja) and describe your project. 3. Or just tell {{current_phase.agent}} what you want to work on Happy designing! 🎨 - + Which phase? @@ -102,12 +103,12 @@ Happy designing! 🎨 {{/each}} Choice: - To work on **Phase {{selected_phase.number}}: {{selected_phase.name}}**: +To work on **Phase {{selected_phase.number}}: {{selected_phase.name}}**: Agent: **{{selected_phase.agent}}** Folder: `{{selected_phase.folder}}` Command: `/bmad:wds:workflows:{{selected_phase.workflow_id}}` - + Which phase to view? @@ -116,7 +117,7 @@ Command: `/bmad:wds:workflows:{{selected_phase.workflow_id}}` {{/each}} Choice: - **Phase {{selected.number}}: {{selected.name}}** +**Phase {{selected.number}}: {{selected.name}}** **Purpose:** {{selected.description}} **Agent:** {{selected.agent}} @@ -126,17 +127,17 @@ Choice: {{#if selected.artifacts}} **Artifacts created:** {{#each selected.artifacts}} + - {{this}} -{{/each}} -{{else}} -**Artifacts:** None yet -{{/if}} + {{/each}} + {{else}} + **Artifacts:** None yet + {{/if}} **What this phase produces:** {{selected.produces}} - + - diff --git a/src/modules/wds/workflows/workflow-status/workflow.yaml b/src/modules/wds/workflows/workflow-status/workflow.yaml index b48b4476..7e483078 100644 --- a/src/modules/wds/workflows/workflow-status/workflow.yaml +++ b/src/modules/wds/workflows/workflow-status/workflow.yaml @@ -3,7 +3,6 @@ name: WDS Workflow Status description: Check WDS project progress - answers 'what should I do now?' for any agent web_bundle: true --- - # WDS Workflow Status - Progress Checker name: wds-workflow-status author: "Whiteport Design Studio" @@ -24,4 +23,3 @@ default_output_file: "{output_folder}/wds-workflow-status.yaml" standalone: true web_bundle: false -