cassel/bi-agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update all documentation and add AI tooling configs

Browse Source 
- Rewrite README.md with current architecture, features and stack
- Update docs/API.md with all current endpoints (corporate, BI, client 360)
- Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL
- Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente)
- Add docs/INDEX.md documentation index
- Add PROJETO.md comprehensive project reference
- Add BI-CCC-Implementation-Guide.md
- Include AI agent configs (.claude, .agents, .gemini, _bmad)
- Add netbird VPN configuration
- Add status report

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Cassel
2026-03-19 13:29:03 -04:00
parent c5b377e788
commit 647cbec54f
3246 changed files with 479789 additions and 983 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
_bmad/wds/workflows/4-ux-design/data/delivery-templates.md Normal file
View File

@@ -0,0 +1,188 @@
# Design Delivery Templates
Templates for handoff communication and tracking.
---
## Handoff Notification Template
```
WDS UX Expert → BMad Architect
Subject: Design Delivery DD-XXX Ready for Implementation
Hi Architect!
Design Delivery DD-XXX ([Flow Name]) is officially handed off
and ready for implementation.
📦 Artifacts:
- Design Delivery: deliveries/DD-XXX-name.yaml
- Test Scenario: test-scenarios/TS-XXX-name.yaml
- Scenarios: C-UX-Scenarios/ ([number] scenarios)
- Components: D-Design-System/ ([number] components)
- Handoff Log: deliveries/DD-XXX-handoff-log.md
✅ What we agreed:
- Epic breakdown: [number] epics
- Estimated effort: [time]
- Implementation approach: [summary]
📋 Next steps:
1. You: Create architecture document
2. You: Break down into dev stories
3. You: Implement features
4. You: Notify me when ready for validation (Touch Point 3)
🔗 Touch Point 3:
When implementation is complete, notify me and I'll run the
test scenarios to validate. We'll iterate until approved.
Questions? I'm available!
Thanks,
[Your name]
WDS UX Expert
```
---
## Project Status Tracker Template
```markdown
# Project Status
## In Progress
### DD-XXX: [Flow Name]
- Status: In Development
- Assigned: BMad Architect
- Started: [Date]
- Estimated completion: [Date]
- Epics: [number]
- Designer: Available for questions
## Next Up
### DD-XXX+1: [Next Flow Name]
- Status: In Design
- Phase: 4-5 (UX Design & Design System)
- Designer: Working on scenarios
- Estimated handoff: [Date]
```
---
## Design Deliveries Tracker Template
```markdown
# Design Deliveries Tracker
## DD-001: [Flow Name]
- Status: In Development (BMad)
- Handed off: [Date]
- Expected completion: [Date]
- Next: Validation (Phase 5 [T] Acceptance Testing)
## DD-002: [Flow Name]
- Status: In Design (WDS)
- Phase: 4 (UX Design)
- Progress: X/Y scenarios complete
- Expected handoff: [Date]
## DD-003: [Flow Name]
- Status: Not Started
- Priority: [High/Medium/Low]
- Planned start: [Date]
```
---
## Weekly Update Template
```
Weekly Update to BMad Architect:
"Hey Architect!
Progress update:
DD-001 ([Flow Name]):
- You're building this
- I'm available for questions
- On track for validation [Date]?
DD-002 ([Flow Name]):
- I'm designing this now
- X/Y scenarios complete
- Expected handoff: [Date]
DD-003 ([Flow Name]):
- Next in queue
- Will start after DD-002 handoff
Questions or blockers on DD-001?"
```
---
## Parallel Work Strategy
```
Week 1: Design Flow 1
Week 2: Handoff Flow 1 → BMad builds Flow 1
Design Flow 2
Week 3: Handoff Flow 2 → BMad builds Flow 2
Test Flow 1 (Phase 5 [T])
Design Flow 3
Week 4: Handoff Flow 3 → BMad builds Flow 3
Test Flow 2 (Phase 5 [T])
Design Flow 4
```
**You're never waiting! Always working!**
---
## Iteration Cadence
```
Week 1-2: Design DD-001
Week 2: Handoff DD-001
Week 2-4: BMad builds DD-001
Week 3-4: Design DD-002
Week 4: Handoff DD-002
Week 4-6: BMad builds DD-002
Week 5: Test DD-001 (Phase 5 [T])
Week 5-6: Design DD-003
Week 6: Handoff DD-003
Week 6-8: BMad builds DD-003
Week 7: Test DD-002 (Phase 5 [T])
Week 7-8: Design DD-004
```
**Continuous flow!**
---
## Communication Tips
### DO ✅
- Answer questions promptly
- Unblock issues quickly
- Provide clarifications
- "How can I help?"
- "Let's figure this out together"
- Be flexible - adjust design if technical constraints arise
### DON'T ❌
- Don't disappear after handoff
- Don't be rigid - be open to technical suggestions
- Don't ignore questions - respond within 24 hours

489
_bmad/wds/workflows/4-ux-design/data/design-deliveries-guide.md Normal file
View File

@@ -0,0 +1,489 @@
# Phase 4 [H] Handover: Design Deliveries
**Package complete testable flows and hand off to development**
---
## Purpose
The Handover activity is where you package complete testable flows and hand off to development.
**This is an iterative phase** - you'll repeat it for each complete flow you design.
---
## Handover Micro-Steps Overview
```
Step 01: Detect Epic Completion
↓ (Is flow complete and testable?)
Step 02: Create Design Delivery
↓ (Package into DD-XXX.yaml)
Step 03: Create Test Scenario
↓ (Define validation tests)
Step 04: Handoff Dialog
↓ (20-30 min with BMad Architect)
Step 05: Hand Off to BMad
↓ (Mark as in_development)
Step 06: Continue with Next Flow
↓ (Return to Phase 4-5)
```
---
## When to Enter Handover
**After completing ONE complete testable user flow:**
✅ **Phase 4 Complete:** All scenarios for this flow are specified
✅ **Phase 5 Complete:** All components for this flow are defined
✅ **Flow is testable:** Entry point → Exit point, complete
✅ **Flow delivers value:** Business value + User value
✅ **Ready for development:** No blockers or dependencies
**Example:**
```
Flow: Login & Onboarding
✓ Scenario 01: Welcome screen
✓ Scenario 02: Login
✓ Scenario 03: Signup
✓ Scenario 04: Family setup
✓ Components: Button, Input, Card
✓ Testable: App open → Dashboard
✓ Value: Users can access the app
→ Ready for Handover!
```
---
## Handover Micro-Steps
### Step 01: Detect Epic Completion
**Check if you have a complete testable flow:**
- ✅ All scenarios for this flow are specified
- ✅ All components for this flow are defined
- ✅ Flow is testable (entry → exit)
- ✅ Flow delivers business value
- ✅ Flow delivers user value
- ✅ No blockers or dependencies
**If YES:** Proceed to Step 02
**If NO:** Return to Phase 4-5 and continue designing
---
### Step 02: Create Design Delivery
**File:** `deliveries/DD-XXX-name.yaml`
**Use template:** `templates/design-delivery.template.yaml`
**Include:**
- All scenarios for this flow
- Technical requirements
- Design system components used
- Acceptance criteria
- Testing guidance
- Complexity estimate
**Example:**
```yaml
delivery:
id: 'DD-001'
name: 'Login & Onboarding Flow'
status: 'ready'
priority: 'high'
design_artifacts:
scenarios:
- id: '01-welcome'
path: 'C-UX-Scenarios/01-welcome-screen/'
- id: '02-login'
path: 'C-UX-Scenarios/02-login/'
# ... etc
user_value:
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'
```
---
### Step 03: Create Test Scenario
**File:** `test-scenarios/TS-XXX-name.yaml`
**Use template:** `templates/test-scenario.template.yaml`
**Include:**
- Happy path tests
- Error state tests
- Edge case tests
- Design system validation
- Accessibility tests
- Usability tests
**Example:**
```yaml
test_scenario:
id: 'TS-001'
name: 'Login & Onboarding Testing'
delivery_id: 'DD-001'
happy_path:
- id: 'HP-001'
name: 'New User Complete Onboarding'
steps:
- action: 'Open app'
expected: 'Welcome screen appears'
design_ref: 'C-UX-Scenarios/01-welcome/Frontend/specifications.md'
# ... etc
```
---
### Step 04: Handoff Dialog
**Initiate conversation with BMad Architect**
**Duration:** 20-30 minutes
**Protocol:** See `src/core/resources/wds/handoff-protocol.md`
**Topics to cover:**
1. User value and success criteria
2. Scenario walkthrough
3. Technical requirements
4. Design system components
5. Acceptance criteria
6. Testing approach
7. Complexity estimate
8. Special considerations
9. Implementation planning
10. Confirmation
**Example:**
```
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
4 development epics. Total: 3 weeks."
WDS UX Expert: "Perfect! I'll start designing the next flow
while you build this one."
```
---
### Step 05: Hand Off to BMad
**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'
```
**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
---
### Step 06: Continue with Next Flow
**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 Handover:**
- 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
Design Flow 2
Week 3: Handoff Flow 2 → BMad builds Flow 2
Design Flow 3
Test Flow 1 (Phase 5 [T])
Week 4: Handoff Flow 3 → BMad builds Flow 3
Test Flow 2 (Phase 5 [T])
Design Flow 4
```
---
## Deliverables
### Design Delivery File
**Location:** `deliveries/DD-XXX-name.yaml`
**Contents:**
- Delivery metadata (id, name, status, priority)
- User value (problem, solution, success criteria)
- Design artifacts (scenarios, flows, components)
- Technical requirements (platform, integrations, data models)
- Acceptance criteria (functional, non-functional, edge cases)
- Testing guidance (user testing, QA testing)
- Complexity estimate (size, effort, risk, dependencies)
---
### Test Scenario File
**Location:** `test-scenarios/TS-XXX-name.yaml`
**Contents:**
- Test metadata (id, name, delivery_id, status)
- Test objectives
- Happy path tests
- Error state tests
- Edge case tests
- Design system validation
- Accessibility tests
- Usability tests
- Performance tests
- Sign-off criteria
---
### Handoff Log
**Location:** `deliveries/DD-XXX-handoff-log.md`
**Contents:**
- Handoff date and duration
- Participants
- Key points discussed
- Epic breakdown agreed
- Questions and answers
- Action items
- Status
---
## Quality Checklist
### Before Creating Delivery
- [ ] All scenarios for this flow are specified
- [ ] All components for this flow are defined
- [ ] Flow is complete (entry → exit)
- [ ] Flow is testable end-to-end
- [ ] Flow delivers business value
- [ ] Flow delivers user value
- [ ] No blockers or dependencies
- [ ] Technical requirements are clear
### Design Delivery Complete
- [ ] Delivery file created (DD-XXX.yaml)
- [ ] All required fields filled
- [ ] Scenarios referenced correctly
- [ ] Components listed accurately
- [ ] Acceptance criteria are clear
- [ ] Testing guidance is complete
- [ ] Complexity estimate is realistic
### Test Scenario Complete
- [ ] Test scenario file created (TS-XXX.yaml)
- [ ] Happy path tests cover full flow
- [ ] Error states are tested
- [ ] Edge cases are covered
- [ ] Design system validation included
- [ ] Accessibility tests included
- [ ] Sign-off criteria are clear
### Handoff Complete
- [ ] Handoff dialog completed
- [ ] BMad Architect understands design
- [ ] Epic breakdown agreed upon
- [ ] Questions answered
- [ ] Special considerations noted
- [ ] Handoff log documented
- [ ] Delivery marked as "in_development"
---
## Common Patterns
### Pattern 1: First Delivery (MVP)
**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
4. Hand off quickly
5. Learn from testing
---
### Pattern 2: Incremental Value
**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
4. Business sees ROI
5. Team stays motivated
---
### Pattern 3: Parallel Streams
**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
4. Continuous flow of work
5. No waiting or blocking
---
## Tips for Success
### 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
- Adjust based on feedback
### 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 5 [T] Acceptance Testing)
---
## Next Steps
**After Handover:**
1. **BMad builds the flow** (Architecture → Implementation)
2. **You design the next flow** (Return to Phase 4-5)
3. **BMad notifies when ready** (Feature complete)
4. **You validate** (Phase 5 [T] Acceptance Testing)
5. **Iterate if needed** (Fix issues, retest)
6. **Sign off** (When quality meets standards)
7. **Repeat** (Next delivery)
---
## 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
---
**Handover is where design becomes development! Package, handoff, and keep moving!** 📦✨

179
_bmad/wds/workflows/4-ux-design/data/guides/DESIGN-LOOP-GUIDE.md Normal file
View File

@@ -0,0 +1,179 @@
# The Design Loop
**The default path from scenario to implemented page.**
---
## Overview
Design is not a handoff between phases. It's a loop: discuss → visualize → agree → build → review → refine. This guide documents the loop that emerged from real project work and defines how Phase 4 (UX Design) and Phase 5 (Agentic Development) connect.
---
## The 9-Step Loop
```
1. DISCUSS → Talk about what the page needs to do, who it's for, primary actions
2. SPEC → Write the page specification (content, structure, object IDs)
3. WIREFRAME → Generate Excalidraw wireframe from the spec
4. ITERATE → User reviews wireframe, agent updates — fast loop (seconds)
5. APPROVE → User exports PNG — the export IS the approval
6. SYNC SPEC → Spec updates to match agreed wireframe
7. IMPLEMENT → Build the page in code
8. REFINE → Browser review via screenshots at real breakpoints
9. TOKENS → Extract recurring patterns into design tokens
```
Steps 4 and 8 are the iteration loops:
- **Step 4** is fast — Excalidraw JSON manipulation, seconds per change
- **Step 8** is real — actual browser rendering, actual responsive breakpoints
---
## Why This Works
### Conversation resolves the hard questions first
"What's the primary CTA? What's hidden on mobile? Where do trust signals go?" These are answered in discussion, not by staring at a mockup. The wireframe visualizes decisions that were already made verbally.
**Don't wireframe before discussing.** Producing the wrong thing faster helps nobody.
### Excalidraw is the right fidelity
Nobody argues about 2px of padding in a sketchy wireframe. People focus on the right things: layout, hierarchy, what content goes where. The hand-drawn aesthetic signals "this is a work in progress — push back freely."
**Don't over-detail the wireframe.** It should resolve structure and hierarchy, not typography and color. That's what the browser review phase is for.
### Two-way editing
Excalidraw files are plain JSON. The agent generates wireframes programmatically (creating rectangles, text, groups). The user opens the same file in VS Code's Excalidraw extension and drags elements around visually. Both can modify the same artifact.
No other design tool offers this:
- Figma requires API access
- Pencil uses encrypted files
- AI image generators produce dead images that can't be edited
### Export = approval
The agent can read and write `.excalidraw` JSON, but it cannot export to PNG — that requires the Excalidraw UI. This limitation is a feature: the manual export becomes an approval gate.
**The pattern:**
1. Agent creates/edits the `.excalidraw` file (JSON)
2. User reviews in Excalidraw, can tweak things directly
3. When agreed → user exports PNG and saves it alongside the `.excalidraw` file
4. PNG becomes the frozen visual reference in the specification
5. `.excalidraw` file stays as the editable source for future revisions
The PNG serves as both a backup and a confirmation. If the user hasn't exported the image, the wireframe isn't approved yet.
### The spec is the contract
The wireframe helps reach agreement. The spec captures what was agreed. The implementation follows the spec. This prevents "I thought we said..." drift.
**Don't skip the spec sync.** If the wireframe changes but the spec doesn't update, they diverge. The spec is the source of truth for implementation.
### Short jump to code
Because the spec has object IDs, responsive breakpoints, and real content, the agent builds the actual page directly. No "translate the mockup into code" step.
### Browser review catches what wireframes can't
Real fonts, real images, real responsive breakpoints. Screenshots at 375px, 768px, 1280px show exactly what users will see. This is where micro-adjustments happen — spacing, font sizes, proportions.
### Spacing discipline — named scale, never arbitrary values
Agents don't have a trained eye for spacing. Without constraints, they'll use arbitrary values — 17px here, 23px there. The fix: a named spacing scale defined per project.
**The scale lives in** `D-Design-System/00-design-system.md` → Spacing Scale. If the project already has a design system (Tailwind, Material, Carbon, custom tokens), use that. If not, WDS provides a default 9-token scale from `space-3xs` to `space-3xl`, symmetric around `space-md`. The user defines what pixel values they represent.
**First design session:** Freya checks if the project has an existing spacing system. If yes, map those tokens into the design system file. If no, Freya proposes values for the default scale and the user confirms. From that point on, every spec uses token names.
```
space-3xs space-2xs space-xs space-sm space-md space-lg space-xl space-2xl space-3xl
```
**The rules:**
- Specs always use token names, never raw pixel values
- Every section in a page spec declares its padding and element gap using tokens
- If a spacing value isn't in the scale, it doesn't belong in the spec
- The scale can be adjusted as the project matures — specs stay valid because they reference names, not numbers
**Optical adjustments:** Sometimes the math is right but the eye says it's wrong — a circular image leaves white corners, a light element looks more spaced than it is. Use token math: `space-lg - space-3xs` (not raw pixels). Always annotate the reason. If adjusting by more than one step, the base token is probably wrong.
---
## Tool Roles
| Tool | Role | When |
|------|------|------|
| **Excalidraw** | Wireframes and layout iteration | Steps 3-5 |
| **Puppeteer** | Browser screenshots for visual review | Step 8 |
| **Nano Banana** | Image asset generation (photos, illustrations) | Asset creation only |
| **Design tokens** | Heading scale, spacing scale, component tokens | Step 9 |
| **Page specs** | Source of truth for structure, content, and spacing | Steps 2, 6 |
### Tool boundaries
- **Excalidraw** = layout and structure. Use it for wireframing.
- **Nano Banana** = image assets. Use it for hero photos, card images, illustrations. NOT for wireframes or mockups — those are dead images nobody can edit.
- **Puppeteer** = reality check. Use it to verify implementation at real breakpoints.
---
## Spec Sync Rule
When the wireframe and spec disagree, the spec must be updated before implementation begins.
**The sequence:**
1. Wireframe changes during iteration (step 4)
2. Agent and user agree on the wireframe
3. Agent updates the spec to match (step 5)
4. Implementation follows the updated spec (step 6)
**Never implement from the wireframe directly.** The spec is the contract. The wireframe is a tool for reaching agreement.
---
## Communication During Refinement
When making spacing or sizing changes during browser review (step 8), state the change in concrete terms:
> "Changed hero top padding from 48px to 64px"
Once design tokens exist (step 9), use token names:
> "Changed hero top padding from **space-2xl** (48px) to **space-3xl** (64px)"
This builds shared vocabulary. Over time, the user learns to say "change from space-md to space-lg" instead of "add more space."
### Pattern recognition — reflect, don't interrogate
When the user requests a spacing adjustment, the agent's job is to **observe and reflect** — not to ask "why?" A trained designer carries spacing patterns unconsciously. Their gut says "more space here" because a pattern is firing in the back of their brain. The agent externalizes that intuition.
**Wrong:** "Why does this need more space?" — breaks the flow, puts the meta-work on the designer.
**Right:** "Got it — large image above a card row needs extra breathing room. I'll use space-xl + space-xs for this relationship going forward."
The designer nods or corrects. The agent records it. The pattern table in the design system builds itself as a byproduct of doing the work.
**The process:**
1. User says "more space between the photo and the cards"
2. Agent fixes it: `space-lg + space-xs`
3. Agent reflects: "So when an image-with-text block sits above a card row, the default gap isn't enough."
4. First time: one-off adjustment noted in the page spec
5. Second time: agent says "this is the same pattern as the homepage about section — applying it"
6. Third time: agent extracts it to `D-Design-System/00-design-system.md` → Patterns
This is how a designer's unconscious expertise becomes a shared, reusable asset. The agent does the tedious classification and recall work. The designer just keeps designing.
---
## When to Use This Loop
**Full loop (all 9 steps):** New pages where layout isn't obvious. Pages with complex information hierarchy. First page of a new scenario.
**Partial loop (skip wireframe):** Pages that follow an established pattern. Second instance of a template page (e.g., vehicle type pages after the first one is done). Simple content pages.
**Discussion only (steps 1-2):** When the user knows exactly what they want. When replicating a reference design.
The loop adapts to the situation. Not every page needs a wireframe. But every page needs a discussion.

243
_bmad/wds/workflows/4-ux-design/data/guides/HTML-VS-VISUAL-STYLES.md Normal file
View File

@@ -0,0 +1,243 @@
# HTML Tags vs. Visual Text Styles
**Critical Best Practice for WDS Specifications**
---
## 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
- **About appearance, not semantics**
---
## 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)
---
## Real-World Examples
### Example 1: Landing Page vs. Article Page
**Landing Page - Hero Headline:**
```markdown
- **HTML Tag**: h1
- **Visual Style**: Hero headline
- **Font**: Bold, 56px, line-height 1.1
```
**Article Page - Article Title:**
```markdown
- **HTML Tag**: h1
- **Visual Style**: Main header
- **Font**: Bold, 32px, line-height 1.3
```
**Both are h1 (semantic), but different visual styles!**
### Example 2: Same Visual Style, Different Semantics
**Section Heading:**
```markdown
- **HTML Tag**: h2
- **Visual Style**: Sub header
- **Font**: Bold, 28px, line-height 1.2
```
**Testimonial Quote:**
```markdown
- **HTML Tag**: p
- **Visual Style**: Sub header
- **Font**: Bold, 28px, line-height 1.2
```
**Same visual style (Sub header), but different HTML tags for proper semantics!**
---
## Design System Visual Style Naming
### Good Visual Style Names (Descriptive & Purpose-Based)
**For Headers:**
✅ **Main header** - Primary page header
✅ **Sub header** - Section headers
✅ **Sub header light** - Lighter variant of section header
✅ **Card header** - Headers within cards
✅ **Small header** - Minor headers, labels
**For Body Text:**
✅ **Body text** - Standard paragraph text
✅ **Body text large** - Larger body text for emphasis
✅ **Body text small** - Smaller body text, secondary info
✅ **Intro text** - Opening paragraph, lead text
**For Special Purposes:**
✅ **Hero headline** - Large display text for hero sections
✅ **Caption text** - Image captions, metadata
✅ **Label text** - Form labels, UI labels
✅ **Error text** - Error messages
✅ **Success text** - Success messages
✅ **Link text** - Link styling
✅ **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
❌ **Display-Large** - Too abstract (unless using design system tokens)
---
## WDS Specification Format
### Complete Example
```markdown
#### Primary Headline
**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)
- **Line-height**: 1.1 (est. calculated from font size)
- **Color**: #1a1a1a
- **Letter spacing**: -0.02em
**Position**: Center of hero section, above supporting text
**Behavior**: Updates with language toggle
**Content**:
- EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång."
```
---
## Benefits of This Approach
✅ **Flexibility** - Different pages can have different visual styles for same semantic tags
✅ **Consistency** - Design system ensures visual consistency across visual styles
✅ **SEO/Accessibility** - Proper HTML structure maintained
✅ **Scalability** - Easy to add new visual styles without breaking semantic structure
✅ **Clarity** - Designers and developers both understand the specification
✅ **Reusability** - Visual styles can be reused across different HTML tags
---
## Common Patterns
### Pattern 1: Landing Page
```
h1 → Hero headline (big hero text, 56px)
h2 → Sub header (section headings, 32px)
h3 → Small header (subsection headings, 24px)
p → Body text (regular paragraphs, 16px)
```
### Pattern 2: Blog Post
```
h1 → Main header (article title, 36px)
h2 → Sub header (section headings, 28px)
h3 → Sub header light (subsection headings, 22px)
p → Body text large (article body, 18px)
```
### Pattern 3: Dashboard
```
h1 → Main header (page title, 28px)
h2 → Card header (widget titles, 20px)
h3 → Small header (section labels, 16px)
p → Body text small (compact info, 14px)
```
**Same HTML structure (h1, h2, h3, p) but different visual styles for each context!**
---
## Implementation Note
When generating HTML prototypes or handing off to developers:
```html
<!-- The HTML tag is semantic, the class references the visual style -->
<h1 class="hero-headline">Every walk. on time. Every time.</h1>
<!-- Another page might have -->
<h1 class="main-header">Welcome to Your Profile</h1>
<!-- NOT this (mixing concerns) -->
<h1 class="h1">Every walk. on time. Every time.</h1>
```
The CSS class references the **visual style name** (hero-headline, main-header), not the HTML tag.
---
**Remember:** HTML tags = Document structure. Visual styles = Appearance. Keep them separate! 🎯

468
_bmad/wds/workflows/4-ux-design/data/guides/NANO-BANANA-PROMPT-GUIDE.md Normal file
View File

@@ -0,0 +1,468 @@
# Nano Banana Prompt Composition Guide
**Purpose:** How to translate WDS page specifications into effective AI image generation prompts.
---
## The Core Problem
Page specifications are verbose (500–1000+ lines). Nano Banana accepts:
- **prompt**: max 8192 characters
- **system_instruction**: max 512 characters
- **input images**: up to 3 reference images for visual conditioning
This guide defines what to extract, what to skip, and how to balance creativity with spec adherence.
---
## What to Extract from Specs
### Always Include
| Element | Where to find it | Example |
|---------|-----------------|---------|
| **Image descriptions** | `Content > Image:` fields | "Öland landscape — open fields, workshop in distance, blue sky" |
| **Section names + order** | `## Page Sections` headers | Header → Hero → Vehicle Icons → About → Trust → Seasons → Footer |
| **Section purposes** | `**Purpose:**` lines | "Instant emotional connection and phone number access" |
| **Primary headlines** | `Content > SE/EN:` (pick one language) | "Vi är Källa Fordonservice" |
| **CTA / action labels** | Button/link content fields | "Ring 0485-270 70", "Läs mer om oss" |
| **Color values** | Visual direction or design tokens | Blues/grays, white background, red accent |
| **Font family** | Typography direction | Inter or similar sans-serif |
| **Layout pattern** | Layout Structure section | "3 columns desktop, 1 column mobile" |
| **Brand mood words** | Visual direction | Professional, local, reliable, Nordic |
### Always Skip
| Element | Why |
|---------|-----|
| Object IDs (`hem-hero-image`) | Development metadata, irrelevant to visual output |
| HTML tags (h1, h2, p, section) | Semantic structure, not visual |
| Component file paths | Internal references |
| Behavior / interaction states | Hover/active/disabled — static image can't show these |
| Accessibility attributes (aria-label) | Screen reader metadata |
| SEO section (meta descriptions, structured data) | Search engine metadata |
| Object Registry tables | Summary tables with no visual info |
| Checklists and Open Questions | Process tracking |
| Secondary/tertiary language content | Pick one language per generation |
| Font sizes in px | Too prescriptive for AI — describe hierarchy instead ("large bold headline", "smaller body text") |
---
## Prompt Budget Allocation
**Total: 8192 characters**
| Section | Faithful | Expressive | Vision |
|---------|----------|------------|--------|
| Creative preamble | 200 | 300 | 500 |
| Page/section context | 300 | 300 | 200 |
| Layout structure | 800 | 600 | 200 |
| Image descriptions | 1000 | 1000 | 1500 |
| Design tokens (colors, fonts) | 500 | 400 | 300 |
| Key content (headlines, CTAs) | 2000 | 1500 | 500 |
| Brand atmosphere | 200 | 500 | 1000 |
| **Buffer / user additions** | **3192** | **3592** | **3992** |
The buffer is intentionally large — prompt quality comes from clarity, not length.
---
## System Instruction Templates (max 512 chars)
### Faithful Mode
```
Professional UI designer creating a clean, realistic interface mockup.
Use specified colors and typography precisely. Show actual text content,
not placeholders. Standard mobile/web UI patterns. Sharp, production-ready look.
```
### Expressive Mode
```
Creative UI designer making a polished, visually appealing interface.
Follow the general layout structure but take creative liberties with
visual treatments, lighting, depth, and atmosphere. Make it look like
a real, beautiful product that inspires confidence.
```
### Vision Mode
```
Brand visual artist creating an artistic concept. Capture the emotional
essence and personality of the brand. Focus on color story, mood, light,
and feeling. The layout is a rough guide, not a constraint. Create something
that makes people feel the brand before they read a word.
```
### Image Asset Mode
```
Professional photographer/illustrator creating a single image for use
on a website. The image should feel authentic, not stock-photo polished.
Natural lighting, real environments, documentary style. High quality,
suitable for hero banners or content cards.
```
---
## Worked Example: Kalla 1.1-hem Hero Image
**Source spec:** 1.1-hem.md, Object `hem-hero-image`
**Spec image description:**
> "Öland landscape — open fields, the workshop visible in the distance, blue sky. Warm, inviting, unmistakably Öland."
**User creative override:**
> "Make the sky a dramatic sunset"
**Reference images provided:**
1. Verkstad-01.jpg (workshop exterior)
2. Verkstad-02.jpg (workshop angle)
3. Kalla-Logo.jpg (brand logo — for color/style context)
**Composed system_instruction** (298 chars):
```
Professional photographer creating a hero banner image for a Swedish
car workshop website. Authentic, documentary style. Natural Öland light.
The workshop is a community hub — warm, trustworthy, approachable.
Not stock-photo polished. Real place, real feeling.
```
**Composed prompt** (682 chars):
```
Wide landscape photograph of a Swedish car workshop (Källa Fordonservice)
on northern Öland. The workshop building is visible in the middle distance,
surrounded by the flat, open Öland landscape with low stone walls and
sparse vegetation.
The sky is a dramatic sunset — deep oranges, purples and golds spreading
across a vast Nordic sky. The golden light catches the workshop building,
making it glow warmly against the landscape.
The mood is warm, inviting, and unmistakably Öland — wide horizons,
quiet strength, a place you can trust. The workshop feels like it belongs
to the landscape, not imposed on it.
Colors: warm golden sunset tones, cool blue-gray Swedish twilight,
earthy workshop browns. Professional but human.
```
**Parameters:**
- `aspect_ratio`: `16:9` (hero banner)
- `model_tier`: `pro`
- `negative_prompt`: "stock photo, generic, urban, text overlay, watermark"
---
## Worked Example: Full Page Mockup
**Scope:** Full page, Expressive mode, Mobile (9:16)
**Composed prompt** (~2800 chars):
```
Mobile UI mockup (portrait) for "Källa Fordonservice" — a car workshop
website in northern Öland, Sweden. Clean Swedish minimalism, professional
but warm and approachable.
Page layout from top to bottom:
1. HEADER: Logo "Källa Fordonservice" on left. Phone icon and "Kontakta"
button on right. Clean, minimal top bar.
2. SERVICE MENU: Horizontal scrollable menu below header with service
categories: Service, Reparationer, AC, Däck, Yrkesmaskiner, Tunga fordon.
Subtle, secondary navigation.
3. HERO SECTION: Full-width landscape photo of Öland with workshop in
distance, dramatic sunset sky. Phone number "0485-270 70" overlaid
in a semi-transparent dark box with white text, centered in lower third.
The hero image dominates — emotional first impression.
4. VEHICLE ICON BAR: Row of 4 small vehicle icons below hero:
Motorcycle, Car, Motorhome, Bus. Simple line icons with labels.
Shows breadth of service.
5. ABOUT PREVIEW: Two-column on desktop, stacked on mobile.
Left: Photo of two mechanics (Björn & Nauriz) in workshop, candid,
friendly. Right: Heading "Vi är Källa Fordonservice" + short intro
paragraph. Trust badges row below (3 small partner logos, muted).
"Läs mer om oss →" link.
6. TRUST CARDS: Three cards in a row (stacked on mobile). Each has:
image (4:3), heading, 2-line teaser text. White cards with subtle shadow.
Topics: "En riktig bilverkstad", "Däck till alla fordon",
"Del av Autoexperten".
7. SEASONS SECTION: Heading "Så skiftar säsongerna i Källa" centered.
Four cards below (2×2 grid on mobile): Spring, Summer, Autumn, Winter.
Each with atmospheric Öland seasonal photo, season name, teaser text.
Warm, editorial feel.
8. FOOTER: Contact info, address, phone. Simple, functional.
Design details:
- Background: white or very light gray
- Text: dark charcoal, strong readable sans-serif (Inter)
- Accent: deep blue for links, subtle red for CTAs
- Cards: white with soft shadow (2-3px), rounded corners (4-8px)
- Images: warm, authentic, documentary style
- Generous whitespace between sections
- Mobile single-column, thumb-friendly
```
---
## Section Focus Mode
When generating a single section at high fidelity, spend the full prompt budget on that section. Include:
- All object details for that section
- Full content text (still one language)
- Precise visual style descriptions
- Layout relationships between objects
- Image descriptions with user overrides
This is useful for iterating on hero sections, card layouts, or navigation patterns before generating the full page.
---
## Generation Modes: Generate vs Edit
Nano Banana supports two fundamentally different modes:
### Generate Mode
Creates images from scratch. Reference images (input_image_path_1/2/3) influence **style and subject** but NOT layout.
**Use for:**
- Standalone image assets (hero photos, card images)
- Wireframes from page specifications (no visual input needed)
- When you have NO layout reference to work from
### Edit Mode
Transforms an existing image. The primary input image (slot 1) controls **layout structure** — section order, proportions, element placement are preserved. Additional images influence style.
**Use for:**
- Wireframe → Mockup transformation (recommended pipeline)
- Sketch → Digital wireframe conversion
- Iterative refinement of existing mockups
**Critical rules for edit mode:**
- **Always pin `aspect_ratio`** — if omitted, model may change aspect ratio and lose content
- **Targeted edits work, broad edits fail** — "add a nav bar to the header" succeeds; "make everything premium" drops sections
- **Adding > Removing** — model handles adding visible elements well, struggles to remove or restructure existing elements
- **Slot 1 = layout source** — put the image whose structure you want to keep in input_image_path_1
---
## Recommended Pipeline: Spec → Wireframe → Mockup
The most reliable approach for full-page mockups is a two-step pipeline:
### Step 1: Spec → Clean Wireframe (generate mode)
Use generate mode to create a clean digital wireframe from the page spec's layout structure. No photography, no colors — just gray boxes and text labels.
**Why this works:** Wireframes are NB's strength. Gray boxes + labels don't require photography or realistic text rendering. The structured layout data (column ratios, aspect ratios, element counts) translates directly into accurate placement.
**System instruction template:**
```
UX wireframe designer creating clean, precise digital wireframes. Use only
grayscale — light gray boxes for image placeholders, medium gray for backgrounds,
dark gray for text labels. No photography, no colors, no decoration. Professional
wireframe style. Clear section boundaries.
```
**Prompt structure:**
Describe each section top-to-bottom with specific layout instructions:
- Column ratios ("Left column ~50%, Right column ~50%")
- Element counts ("3 cards side by side", "11 icons in a row")
- Content labels ("heading: Vi är Källa Fordonservice")
- Image placeholder labels ("[HERO IMAGE — Öland landscape]")
**Preventing wireframe label leakage into mockups:**
ANY text in the wireframe will bleed into the mockup. This includes:
- Section annotations ("SECTION 1 — HEADER", "TRUST CARDS", "FOOTER")
- Placeholder labels ("[LOGO]", "[HERO IMAGE]", "[PHOTO — Name]")
- Descriptive text inside gray boxes
To minimize leakage:
- Use only real content text (actual headings, labels) — these are fine since they belong in the mockup
- Use empty gray boxes without text labels for image placeholders
- Avoid section titles that aren't part of the actual page design
- If labels are needed for your own reference, accept that some may leak and plan to iterate
**Parameters:**
- `mode`: `generate`
- `aspect_ratio`: `9:16` (full page portrait scroll)
- `model_tier`: `pro` (worth the quality for layout accuracy)
- `negative_prompt`: "photography, realistic images, colorful design, stock photos, polished UI, gradients, shadows"
### Step 2: Wireframe → Polished Mockup (edit mode)
Use edit mode with the generated wireframe as primary input to apply visual design while preserving layout.
**System instruction template:**
```
UI designer transforming wireframes into polished website mockups. Follow
the wireframe layout EXACTLY — section order, proportions, element placement.
Apply clean [brand style] with warm photography. Professional but human.
[viewport type] viewport.
```
**Prompt structure:**
Describe what to fill each placeholder with:
- Hero: specific scene description
- Photos: subject descriptions
- Cards: imagery for each card
- Colors: specific palette to apply
- Typography: font style
**Parameters:**
- `mode`: `edit`
- `input_image_path_1`: path to wireframe from step 1
- `input_image_path_2`: reference photo (optional, for style conditioning)
- `aspect_ratio`: MUST match step 1 (e.g., `9:16`)
- `model_tier`: `pro`
- `negative_prompt`: "wireframe style, gray boxes, placeholder text, section labels, annotations, sketch lines"
### Why This Pipeline Outperforms Direct Generation
| Approach | Layout accuracy | Visual quality | Reliability |
|----------|----------------|----------------|-------------|
| Direct generate (no reference) | Low — model invents layout | Medium | Unpredictable |
| Sketch → Mockup (edit) | Good — follows sketch structure | Medium-High | Good |
| **Spec → Wireframe → Mockup** | **High — spec-accurate** | **High** | **Best** |
| Iterative editing | Degrades with each pass | Varies | Poor for removal/restructure |
---
## Multi-Pass Strategy
Alternative workflow for thorough visual exploration (when not using the wireframe pipeline):
1. **Image assets first** — Generate key images (hero photo, card photos) as standalone assets
2. **Section focus** — Design critical sections (hero, trust cards) at high fidelity
3. **Full page mockup** — Combine everything into a page overview
4. **Iterate** — Refine based on user feedback
Each pass builds on the previous — reference images from pass 1 can condition pass 2.
---
## Batch Generation: Similar Page Sequences
Many projects have groups of pages that share the same layout but differ in content: vehicle type pages, service pages, article pages, product pages.
### The Template-and-Swap Pattern
1. **Design once** — Generate and iterate on ONE page until the user approves the visual direction
2. **Extract the template** — The approved prompt becomes a reusable template with swap points
3. **Generate the rest** — For each remaining page, swap in the unique content and generate
### Example: 11 Vehicle Type Pages
**Template prompt** (from approved 3.4-personbil):
```
Mobile UI mockup for a vehicle type page on "Källa Fordonservice" website.
Swedish minimalism, professional but warm.
Layout:
1. HEADER + SERVICE MENU (shared)
2. HERO: Full-width photo of {VEHICLE_IMAGE_DESCRIPTION}
Heading: "{VEHICLE_NAME}" in bold
3. VEHICLE ICON BAR: {VEHICLE_TYPE} icon highlighted
4. SERVICES LIST: What we do for {VEHICLE_NAME_LOWERCASE}:
{SERVICE_BULLETS}
5. CTA: "Ring oss: 0485-270 70"
6. RELATED ARTICLES: 2-3 article cards relevant to {VEHICLE_TYPE}
7. FOOTER (shared)
Design: white background, dark charcoal text, deep blue accent,
white cards with subtle shadow, warm authentic imagery.
```
**Swap table:**
| Page | VEHICLE_NAME | VEHICLE_IMAGE_DESCRIPTION | SERVICE_BULLETS |
|------|-------------|--------------------------|-----------------|
| 3.1 | Gräsklippare | Lawn mower on green garden, Öland summer | Service, reparation, vintervård |
| 3.2 | Moped/Skoter | Moped on coastal road | Service, reparation, besiktning |
| 3.9 | Traktor | Tractor in agricultural field, earth tones | Service, hydraulik, däck |
| ... | ... | ... | ... |
### Key Principles for Batch Generation
- **Shared parameters stay fixed:** system_instruction, creative mode, aspect ratio, design tokens, reference images
- **Only content swaps:** image descriptions, headlines, service lists, section-specific text
- **Sequential generation:** Generate one at a time, quick-review each, flag outliers for iteration
- **Use `flash` model tier** for batch runs (faster, cheaper) — save `pro` for the template page
- **Track everything** in the agent experience file for reproducibility
---
## Known Limitations
Documented from extensive testing on Kalla Fordonservice 1.1-hem (13+ generations, Feb 2026).
### What NB is Good At
| Use case | Quality | Notes |
|----------|---------|-------|
| **Wireframe generation from spec** | Excellent | Best use case. Structured layout data → accurate gray-box wireframes |
| **Single image assets** (hero photos, card images) | Good | Generate mode with descriptive prompts works well |
| **Style transfer via reference images** | Good | Slot 2-3 photos influence color/mood/subject effectively |
| **Adding elements** (edit mode) | Fair | Can add nav bars, icons, logos to existing images |
| **Wireframe → Mockup transformation** | Fair | Layout preserved, but wireframe text/labels leak through |
### What NB Struggles With
| Limitation | Severity | Workaround |
|------------|----------|------------|
| **Text rendering** | Critical | ALL generated text is garbled. Spec is source of truth — never trust AI text. Use mockups for layout/mood only |
| **Logo reproduction** | High | Cannot faithfully reproduce a provided logo. Generates an "inspired by" version. Use real logo in implementation |
| **Wireframe label leakage** | High | Placeholder text like "[LOGO]", "TRUST CARDS", section annotations bleed from wireframe into mockup. Minimize text in wireframes |
| **Removing elements** (edit mode) | High | Edit mode cannot reliably remove things (icons, labels, sections). Regenerate from wireframe instead |
| **Restructuring layout** (edit mode) | High | Cannot move elements to different positions (e.g., nav links from separate row into header). Regenerate |
| **Broad edit instructions** | High | "Make everything premium" causes section loss. Must use targeted, specific edits |
| **Aspect ratio drift** (edit mode) | Medium | If `aspect_ratio` not pinned, model changes it and drops below-fold content |
| **Grid layouts** | Medium | 2×2 grids often flatten to 1×4 rows. Specify "2 rows, 2 columns" explicitly |
| **Iterative degradation** | Medium | Each edit pass introduces drift. After 2-3 edits, regenerate from wireframe |
### Critical Rules
1. **All text is wrong** — mockups are for layout and visual direction only, never for content accuracy
2. **Always pin `aspect_ratio` in edit mode** — omitting it is the #1 cause of content loss
3. **One targeted change per edit** — never combine multiple changes in one edit call
4. **Regenerate > Edit for structural changes** — if you need to move, remove, or restructure elements, go back to wireframe step
5. **Pro model for anything structural** — Flash is only for quick image asset iterations
6. **No section labels in wireframes** — any text in the wireframe will appear in the mockup
### Where NB Fits in the Design Workflow
NB is best as an **image asset production tool**, not a layout or mockup tool. AI-generated wireframes and mockups are dead images — the user cannot drag a section, resize a column, or annotate feedback directly. Use editable tools (Excalidraw, Figma) for layout iteration.
**Use NB for:**
- Hero photography (landscapes, buildings, environments)
- People photos (team portraits, candid shots)
- Card and article imagery (seasonal photos, product shots)
- Mood and atmosphere exploration
- Placeholder images during design reviews
**Do NOT use NB for:**
- Wireframes (use Excalidraw — user can edit directly)
- Production mockups (use Google Stitch for HTML/CSS or Figma)
- Anything where text accuracy matters (all NB text is garbled)
- Anything the user needs to iterate on by hand
### Model Tiers
| Tier | Model | Input images | Strengths | Cost |
|------|-------|-------------|-----------|------|
| **Flash** | Gemini 2.5 Flash Image | 3 max | Fast, cheap. Good for single image assets | Low |
| **Pro** | Gemini 3 Pro Image | 14 objects + 5 characters | Better structural accuracy, higher thinking. Worth it for wireframes and first-pass mockups | Higher |
### Technical Limits
- Prompt: 8192 characters max
- System instruction: 512 characters max
- Negative prompt: 1024 characters max
- Input images don't consume Claude context — sent directly to Gemini via filesystem
- Output thumbnails returned by default (full image via `return_full_image: true`)
- `file_id` parameter causes validation errors when combined with `input_image_path` (known NB bug — use paths only)

532
_bmad/wds/workflows/4-ux-design/data/guides/SKETCH-TEXT-ANALYSIS-GUIDE.md Normal file
View File

@@ -0,0 +1,532 @@
# Sketch Analysis Guide: Reading Text Placeholders
**For Dog Week and All WDS Projects**
---
## 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
───────────────────────────────────────── ← Not final content
─────────────────────────────────────────
```
**Benefits:**
- Shows font size and capacity without committing to content
- Faster for sketching body text
- Focuses on layout, not copywriting
---
## Understanding Sketch Text Markers
In Dog Week sketches (and most UI sketches), **text is represented by horizontal lines in groups**.
### What You See
```
Page Title (centered):
═════════════════════════ ← Thick pair, centered = Heading, center-aligned
═════════════════
Body text (left-aligned):
───────────────────────────────────────── ← Thin pairs, left edge = Body, left-aligned
─────────────────────────────────────────
─────────────────────────────────────────
─────────────────────────────────────────
─────────────────────────────────────────
Caption (right-aligned):
────────────────── ← Short pair, right edge = Caption, right-aligned
──────────────────
Justified/Full-width text:
═════════════════════════════════════════════ ← Extends full width = Justified
═════════════════════════════════════════════
```
### 3. Line Count → Number of Text Lines
**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 |
---
## Step 0: Establish Scale Using Project Context
**Before analyzing individual text elements, establish your reference points:**
### 1. Check Previous Pages in Project
If analyzing multiple pages in the same project:
**Look for established patterns:**
```
Start Page (already analyzed):
- Body text: Thin lines, icon-sized spacing → 16px Regular
- Button labels: Medium lines → 16px Semibold
- Page title: Thick lines, button-height spacing → 48px Bold
Current Page (About Page):
- Similar thin lines, icon-sized spacing → **Same: 16px Regular**
- Similar medium lines in buttons → **Same: 16px Semibold**
```
**Design System Integration:**
- If project has a design system, match visual patterns to existing components
- Body text that looks like Start Page body text → Use same specification
- Buttons that look like Start Page buttons → Use same specification
**Benefits:**
- ✅ Maintains consistency across all pages
- ✅ Builds reusable design patterns
- ✅ Reduces specification time for subsequent pages
- ✅ Creates cohesive user experience
### 2. Find UI Anchors in Current Sketch
- Browser chrome (address bar, scrollbars)
- Standard UI elements (buttons, icons, form inputs)
- Use these to calibrate scale for this specific sketch resolution
---
## Analysis Rules
### 1. Line Thickness → Font Weight (Relative)
**Line thickness indicates font weight (bold/regular), NOT font size**
**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 |
**Don't measure pixels—compare thickness relative to other text in the same sketch.**
### 2. Distance Between Lines → Font Size (Context-Based)
**The vertical spacing between lines indicates font size—compare to UI elements**
| Spacing Relative To | Estimated Font Size | Typical Use |
| --------------------- | ------------------- | ----------------------------------- |
| Button Height | ~40-48px | Large Heading - Page titles |
| Address Bar Height | ~32-40px | Medium Heading - Section headings |
| Between Button & Icon | ~24-32px | Small Heading - Subsection headings |
| Icon/Scrollbar Size | ~16-24px | Body text / Paragraphs |
| Half Icon Size | ~12-16px | Captions / Helper text |
**⚠️ Important:** If spacing seems disproportionately large (>2x button height), verify this is text and not an image placeholder or colored box!
### 2a. Visual Examples: Text vs. Image Confusion
**TEXT - Normal spacing:**
```
═══════════════════════════════ ← Bold line
← ~Button Height
═══════════════════════════════ ← Bold line
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!
Ask user to confirm.
```
**When in doubt:** If spacing is disproportionately large compared to UI elements, ask: "Is this text or an image/box?"
### 3. Text Alignment → Horizontal Position
**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 |
#### Visual Examples
**Left-Aligned Text:**
```
Container: | |
═════════════════════════ ← Starts at left edge
═════════════════════════
[empty space →]
```
**Center-Aligned Text:**
```
Container: | |
═════════════════════════ ← Centered in container
═════════════════════════
```
**Right-Aligned Text:**
```
Container: | |
═════════════ ← Ends at right edge
═════════════
```
**Justified/Full-Width Text:**
```
Container: | |
═════════════════════════════════════════════════════ ← Spans full width
═════════════════════════════════════════════════════
```
---
### 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 |
### 4. Line-Height Calculation
**Line-height is derived from font size and spacing:**
```
Line-height ratio = (Distance between lines) / (Estimated font size)
Example:
Distance: 28px
Font size: 24px
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)
```
Left-aligned: Center-aligned: Right-aligned:
────────────────── ────────────────── ──────────────────
────────────────── ────────────── ──────────────────
────────────────── ────────── ──────────────────
```
### 5. Characters Per Line
**Based on estimated font size and line width:**
```
Large Heading (~48px): ═══════════════════ = ~20-25 chars
Medium Heading (~36px): ═══════════════════════ = ~25-30 chars
Small Heading (~24px): ─────────────────────── = ~40-50 chars
Body Text (~16px): ──────────────────────────────── = ~60-70 chars
Caption (~12px): ──────────────────────────────────── = ~80-90 chars
```
---
## Dog Week Example Analysis
### 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)
- **Distance between lines:** Matches button height → **~40-48px font-size**
- **Line-height:** ~1.2 (calculated from spacing)
- **Alignment:** Center
- **Capacity:** ~25-30 chars per line = 50-60 total
- **Semantic HTML:** Determined by page structure (likely H1 if page title)
**Content Guidance:**
```
English: "Welcome to Your / Dog Care Hub" (48 chars) ✅
Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅
```
### Example 2: Feature Description
**Sketch shows:**
```
───────────────────────────────────────── ← Line 1
───────────────────────────────────────── ← Line 2
───────────────────────────────────────── ← Line 3
───────────────────────────────────────── ← Line 4
```
**Analysis:**
- **Type:** Body text / Paragraph
- **Lines:** 4
- **Line thickness:** Thinnest in sketch → **Regular** (font-weight: 400)
- **Distance between lines:** Matches icon/scrollbar size → **~16-20px font-size**
- **Line-height:** ~1.5 (calculated from spacing)
- **Alignment:** Left
- **Capacity:** ~60-70 chars per line = 240-280 total
**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."
(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
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)
- **Estimated font-size:** ~16-18px (button standard)
- **Capacity:** ~8-12 characters
**Content Guidance:**
```
English: "Get Started" (11 chars) ✅
Swedish: "Kom Igång" (9 chars) ✅
```
---
## Agent Instructions
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)
- Thick lines → Semibold (font-weight: 600)
- Medium lines → Medium (font-weight: 500)
- Thin lines → Regular (font-weight: 400)
- Thinnest lines → Light (font-weight: 300)
```
### Step 3: Compare Distance to UI Elements → Font Size
```
Vertical spacing relative to context anchors:
- Matches Button Height → ~40-48px font (Large Heading)
- Matches Address Bar → ~32-40px font (Medium Heading)
- Between Button & Icon → ~24-32px font (Small Heading)
- Matches Icon/Scrollbar → ~16-24px font (Body Text)
- Half Icon Size → ~12-16px font (Caption/Small Text)
⚠️ If spacing is disproportionately large, verify this is text (not image/box)!
NOTE: Visual size ≠ Semantic HTML level (H1/H2/H3).
Semantic heading levels are determined by content structure, not appearance.
```
### Step 4: Calculate Line-Height
```
Line-height = Distance between lines / Font size
Example:
- Distance: 28px
- Font size: 24px
- Line-height: 28 / 24 = 1.16 ≈ 1.2
```
### Step 5: Calculate Capacity
```
Lines × Characters-per-line = Total capacity
Example:
5 lines × 60 chars/line = 300 characters
```
### Step 6: Generate Content Guidance
```
"Content should be: [type], [line count] lines, ~[total chars] characters"
Example:
"Content should be: Full paragraph, 5 lines, ~300 characters"
```
### Step 7: Validate Content
```
If user provides content:
- Count actual characters
- Compare to capacity
- Warn if mismatch
Example:
⚠️ Your content (450 chars) exceeds sketch capacity (300 chars).
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
---
## Example in Action
**User shares Dog Week sketch of profile setup page**
**Agent analyzes:**
> "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
> - Line-height: ~1.3 (calculated)
> - Alignment: Center
> - Capacity: ~50-60 characters (25-30 per line)
>
> **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) ✅
>
> Both fit comfortably within the designed space. Does this match your intent?"
---
## 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
- **4C-08: Generate Spec** - Final documentation
**Result:** Every text element in WDS specifications includes accurate character capacity and content guidance! 🎨✨
---
_This guide ensures all WDS projects generate content that perfectly fits the designed space._

222
_bmad/wds/workflows/4-ux-design/data/guides/SKETCH-TEXT-QUICK-REFERENCE.md Normal file
View File

@@ -0,0 +1,222 @@
# Quick Reference: Sketch Text Analysis
**The Correct Interpretation**
---
## Step 0: Establish Scale (Holistic View)
**Before analyzing specific text, scan the ENTIRE sketch to establish scale.**
1. **Find UI Anchors:** Look for standard UI elements (Browser chrome, Scrollbars, Buttons, Icons).
2. **Check Project References:** Look at other sketches in the same project for established text styles.
3. **Determine Base Unit:** If a Scrollbar is "Standard Width" (e.g., 16px), how big is everything else relative to it?
4. **Calibrate:** Use these known objects to calibrate your eye for this specific image resolution.
### Cross-Page Reference Strategy
**If body text was defined on the Start Page:**
- Start Page body text: Spacing matches icon size → 16px Regular
- **Current page:** Similar thin lines with icon-sized spacing → **Same: 16px Regular**
**Benefits:**
- ✅ Maintains visual consistency across pages
- ✅ Builds design system patterns naturally
- ✅ Reduces guesswork on subsequent pages
- ✅ Creates coherent user experience
**When to use:**
- Body text, captions, button labels (common across pages)
- Navigation items (should be identical)
- Form labels and inputs (standardized patterns)
---
## The Two Key Measurements
### 1. Line Thickness = Font Weight (Relative)
**Compare lines against each other in the sketch:**
```
═══════════════════ ← Thicker than others = Bold (700)
─────────────────── ← Medium thickness = Medium (500)
───────────────────── ← Thinnest lines = Regular (400)
```
**Rule:** Relative thickness indicates hierarchy, not absolute pixels.
### 2. Vertical Spacing = Font Size (Context-Based)
**Estimate size by comparing to known UI elements:**
```
[ Button ] ← Standard height ref (~40-48px)
↕
═══════════════════ ← Matches button height? ~40-48px (Large Heading)
↕
═══════════════════
```
**Context Anchors:**
- **Browser Address Bar**: ~40px height
- **Standard Button**: ~40-48px height
- **Cursor/Icon**: ~16-24px size
- **Scrollbar**: ~16px width
**Rule:** Use these anchors to estimate the scale of text spacing.
**Note:** Visual size ≠ Semantic HTML (H1/H2/H3). Heading levels are determined by document structure, not appearance.
---
## Complete Analysis Pattern
### Example: Hero Headline
**Sketch:**
```
═══════════════════════════════ ← Line 1: Thickest lines in sketch
↕ Spacing ≈ Same as button height
═══════════════════ ← Line 2: Thickest lines in sketch
```
**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**.
- **Result:** `font: bold 48px / 1.2`
---
## 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
---
## ⚠️ 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!
---
## Quick Decision Tree
```
See horizontal lines?
│
├─ Compare THICKNESS (Relative)
│ └─ Thicker than avg? → Bold
│ └─ Thinner than avg? → Regular
│
├─ Compare DISTANCE (Context)
│ └─ Matches Button Height? → Large Heading (~40-48px)
│ └─ Matches Icon Size? → Body Text (~16-24px)
│ └─ Huge Gap? → Image/Container
│
└─ Check Context Anchors
└─ Address Bar, Scrollbar, Buttons
```
---
## Memory Aid
**THICKNESS = RELATIVE WEIGHT**
**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!
---
## Real Dog Week Example
```
═══════════════════════════════ ← Thickest lines
↕ Matches "Sign In" button height
═══════════════════ ← Thickest lines
```
**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."
```
Both fit in ~50-60 character capacity! ✅
---
**Remember: Context is King! Compare, don't just measure.** 📏✨

513
_bmad/wds/workflows/4-ux-design/data/guides/TRANSLATION-ORGANIZATION-GUIDE.md Normal file
View File

@@ -0,0 +1,513 @@
# Translation Organization Guide
**Part of WDS Specification Pattern**
**Purpose-Based Naming with Grouped Translations**
---
## Overview
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
---
## Core Principles
### 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"
```
**Why:** If content changes to "Every walk. on time.", the Object ID still makes sense.
---
### 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**:
- 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)
- **Behavior**: Updates with language toggle
```
> **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.
---
### 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."
```
**Why:** Each language reads as complete, coherent message.
---
## Dog Week Examples
### Example 1: Hero Section (Text Group)
```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
- **Behavior**: Updates with language toggle
- **Content**:
- 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
- **Style**: Regular, 16px, line-height 1.5
- **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."
#### 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
- **Content**:
- EN: "start planning - free forever"
- SE: "börja planera - gratis för alltid"
```
**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]
Each language flows naturally as a complete message!
---
### Example 2: Form Labels (Individual Elements)
```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`
- **Content**:
- EN: "Email Address"
- 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`
- **Content**:
- EN: "Password"
- SE: "Lösenord"
#### Password Input
**OBJECT ID**: `signin-form-password-input`
- **Component**: [Password Input](/docs/.../password-input.md)
- **Placeholder**:
- EN: "Enter your password"
- SE: "Ange ditt lösenord"
```
---
### Example 3: Error Messages
```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
- **Content**:
- EN: "Email address is required"
- 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
- **Content**:
- EN: "Please enter a valid email address"
- 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
- **Content**:
- EN: "Invalid email or password. Please try again."
- SE: "Ogiltig e-post eller lösenord. Försök igen."
```
---
## Object ID Naming Patterns
### 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)
- `features` (features section)
- `footer` (page footer)
**Purpose Examples:**
- `headline` (main heading)
- `subheading` (secondary heading)
- `description` (descriptive text)
- `cta` (call-to-action button)
- `label` (form label)
- `error` (error message)
- `success` (success message)
- `supporting` (supporting/helper text)
**Complete Examples:**
- `start-hero-headline`
- `signin-form-email-label`
- `profile-success-message`
- `calendar-header-title`
- `features-description-text`
---
## Content Structure
### Required Fields
```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}}
- {{lang}}: "{{content}}"
{{/if}}
```
### Optional Fields
```markdown
- **Behavior**: {{behavior_description}}
- **Style**: {{style_specifications}}
- **For**: {{linked_input_id}} (for labels)
- **Trigger**: {{when_shown}} (for conditional text)
```
---
## Multi-Language Support
### 2 Languages (Dog Week)
```markdown
- **Content**:
- EN: "Welcome to Dog Week"
- SE: "Välkommen till Dog Week"
```
### 3+ Languages
```markdown
- **Content**:
- EN: "Welcome to Dog Week"
- SE: "Välkommen till Dog Week"
- DE: "Willkommen bei Dog Week"
- FR: "Bienvenue à Dog Week"
```
### Language Codes
- **EN** = English
- **SE** = Swedish (Svenska)
- **NO** = Norwegian
- **DK** = Danish
- **FI** = Finnish
- **DE** = German
- **FR** = French
- **ES** = Spanish
- **IT** = Italian
---
## Benefits of This Pattern
### ✅ For Translators
```markdown
**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
- Verify character lengths
### ✅ For Developers
```typescript
// Object ID makes purpose clear
const headline = document.getElementById('start-hero-headline');
const supportingText = document.getElementById('start-hero-supporting');
// Content referenced by language
const content = {
'start-hero-headline': {
en: 'Every walk. on time. Every time.',
se: 'Varje promenad. i tid. Varje gång.',
},
};
```
### ✅ For Maintainability
**Content changes:**
```markdown
#### Primary Headline
**OBJECT ID**: `start-hero-headline` ← Stays same
- **Content**:
- EN: "NEW CONTENT HERE" ← Easy to update
- SE: "NYTT INNEHÅLL HÄR"
```
**No Object ID changes needed!**
---
## Text Group Examples
### Hero Group (Headline + Body + CTA)
All translations grouped so each language reads coherently:
```markdown
### 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"
```
**English reads:** "Every walk. on time. / Never miss a walk again. / [Get Started]"
**Swedish reads:** "Varje promenad. i tid. / Missa aldrig en promenad. / [Kom Igång]"
### Feature Group (Icon + Title + Description)
```markdown
### 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."
```
---
## Validation Checklist
Before finalizing text specifications:
- [ ] Object IDs use purpose-based naming (not content)
- [ ] Structure (position/style) separated from content
- [ ] All languages included for each text element
- [ ] Text groups keep translations together
- [ ] Each language reads coherently as a group
- [ ] Character lengths validated against sketch analysis
- [ ] Component references included
- [ ] Behavior specified (if applicable)
---
**This pattern ensures professional, maintainable, translation-friendly specifications across all WDS projects!** 🌍✨

436
_bmad/wds/workflows/4-ux-design/data/guides/WDS-SPECIFICATION-PATTERN.md Normal file
View File

@@ -0,0 +1,436 @@
# WDS Specification Pattern
**Complete specification format for Whiteport Design Studio projects**
---
## Overview
This document defines the **WDS Specification Pattern** used in Phase 4 (UX Design) for all WDS projects.
**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
---
## 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
- **Update with final values** once confirmed
**Analysis methodology:** See `SKETCH-TEXT-ANALYSIS-GUIDE.md` for complete rules on deriving font weight, font size, line-height, and alignment from sketch markers.
This ensures transparency about which values came from AI interpretation vs. designer specification.
---
## The Pattern in Action
### Hero Section Example
```markdown
### Hero Object
**Purpose**: Primary value proposition and main conversion action
#### Primary Headline
**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)
- **Line-height**: 1.1 (est. calculated as font-size × 1.1)
- **Color**: #1a1a1a
- **Letter spacing**: -0.02em
**Position**: Center of hero section, above supporting text
**Alignment**: center
**Behavior**: Updates with language toggle
**Content**:
- EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång."
> **Sketch Analysis:** Line thickness (3px) → Bold weight. Line spacing (32px) → ~56px font size estimate. Designer should confirm these values.
#### Supporting Text
**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)
- **Line-height**: 1.5 (est. calculated as font-size × 1.5)
- **Color**: #4a4a4a
**Position**: Below headline, above CTA, center-aligned
**Alignment**: center
**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
- **States**: default, hover, active, loading
- **Content**:
- EN: "start planning - free forever"
- SE: "börja planera - gratis för alltid"
```
**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]
---
## The Complete Process
### Step 1: Sketch Analysis (4B)
```
Agent sees sketch with horizontal lines:
═══════════════════════════════ ← Line 1 (thick, 3px)
═══════════════════════════ ← Line 2 (thick, 3px)
───────────────────────────────────────── ← Line 3 (thin, 1px)
───────────────────────────────────────── ← Line 4 (thin, 1px)
┌─────────────────────────────┐
│ start planning │ ← Button
└─────────────────────────────┘
Agent identifies:
1. TEXT GROUP (2 thick lines) - Hero headline
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
→ TEXT DETECTED
→ Routes to heading-text.md
heading-text.md:
→ Asks: "What's the PURPOSE?" → "Primary Headline"
→ Object ID: `start-hero-headline`
→ Sketch analysis: 2 lines, 3px thick, ~50-60 chars
→ Content guidance: Brief heading, 2 short lines
→ Requests content with length validation
```
### Step 3: Content with Grouped Translations
```
Agent asks:
"What's the content for Primary Headline?
Based on sketch: 2 lines, ~50-60 characters total
I found text in your sketch: 'Every walk. on time. Every time.'
Let me suggest translations...
EN: Every walk. on time. Every time.
SE: Varje promenad. i tid. Varje gång.
Do these work? [1] Use these [2] Adjust [3] Manual"
User provides:
1 ← Accepts suggestions!
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
- **Content**:
- EN: "Every walk. on time. Every time."
- SE: "Varje promenad. i tid. Varje gång."
```
---
## Key Advantages
### 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
`profile-success-message` ← Role clear
```
### 2. Separated Concerns
**Structure/Style** (rarely changes):
```markdown
- **Component**: H1 heading
- **Position**: Center of hero
- **Style**: Bold, 42px
```
**Content** (often changes):
```markdown
- **Content**:
- EN: "..."
- SE: "..."
```
### 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: "..."
```
### 4. Character Capacity Validation
**From Sketch Analysis:**
```
Agent: "Sketch shows 2 lines, ~50-60 chars capacity"
User provides: "Every walk. on time. Every time." (37 chars)
Agent: "✅ Content fits within sketch capacity!"
```
**If too long:**
```
Agent: "⚠️ Your content (85 chars) exceeds capacity (60 chars).
Consider shortening or adjusting font size."
```
---
## Complete Workflow Integration
```
4B: Sketch Analysis
↓
Identifies text groups, estimates capacity
↓
4C-03: Components & Objects
↓
object-router.md
↓
STEP 1: TEXT DETECTION (checks horizontal lines)
↓
If text → heading-text.md
↓
1. Ask PURPOSE (not content)
2. Generate Object ID from purpose
3. Specify position/style
4. Request content with grouped translations
5. Validate against sketch capacity
6. Generate specification (Dog Week format)
↓
Return to 4C-03
↓
4C-04: Content & Languages
(Already captured in heading-text.md)
↓
4C-08: Generate Final Spec
```
---
## Template Structure
**Every text element follows this format:**
```markdown
#### {{Purpose_Title}}
**OBJECT ID**: `{{page-section-purpose}}`
- **Component**: {{type}} ({{class_or_ref}})
- **Position**: {{position_description}}
{{#if has_behavior}}
- **Behavior**: {{behavior_description}}
{{/if}}
{{#if has_style_details}}
- **Style**: {{style_specifications}}
{{/if}}
{{#if links_to_input}}
- **For**: {{input_object_id}}
{{/if}}
- **Content**:
- EN: "{{english_text}}"
- SE: "{{swedish_text}}"
{{#each additional_language}}
- {{code}}: "{{text}}"
{{/each}}
```
---
## Real Dog Week Specifications
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"
- SE: "börja planera - gratis för alltid"
```
**From 1.2-Sign-In.md (Header example):**
```markdown
#### Sign In Button
**OBJECT ID**: `start-header-signin`
- **Component**: [Button Secondary](/docs/D-Design-System/.../Button-Secondary.md)
- **Content**:
- EN: "Sign in"
- SE: "Logga in"
- **Behavior**: Navigate to sign-in page
```
---
## Specification Checklist
For each text element:
- [ ] **Purpose-based name** (not content-based)
- [ ] **Object ID** from purpose: `{page}-{section}-{purpose}`
- [ ] **Component** reference specified
- [ ] **Position** clearly described
- [ ] **Style** separated from content
- [ ] **Behavior** specified if applicable
- [ ] **Content** with grouped translations:
- [ ] EN: "..."
- [ ] SE: "..."
- [ ] Additional languages if needed
- [ ] **Character length** validated against sketch
- [ ] **Part of text group** if applicable
---
**This is the WDS standard for text specifications, proven by Dog Week!** 🎨🌍✨

276
_bmad/wds/workflows/4-ux-design/data/handoff-dialog-scripts.md Normal file
View File

@@ -0,0 +1,276 @@
# Handoff Dialog Scripts
Detailed conversation scripts for each phase of the handoff dialog.
---
## 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?"
```
---
## Phase 2: User Value (3 min)
**You say:**
```
"First, let me explain what problem we're solving:
Problem:
[Describe the user problem]
Solution:
[Describe how this flow solves it]
Success Criteria:
- [Metric 1]
- [Metric 2]
- [Metric 3]
This is critical because [business value]."
```
---
## Phase 3: Scenario Walkthrough (8 min)
**You say:**
```
"Let me walk you through the user flow:
Scenario 1: [Name]
- User starts at: [Entry point]
- User action: [What they do]
- System response: [What happens]
- User sees: [What's displayed]
- Design reference: C-UX-Scenarios/XX-name/
[Repeat for each scenario]
The complete flow is:
[Entry point] → [Step 1] → [Step 2] → [Exit point]"
```
**Show:** Excalidraw sketches, Scenario specifications, User flow diagrams
---
## Phase 4: Technical Requirements (4 min)
**You say:**
```
"Technical requirements:
Platform:
- Frontend: [Framework + version]
- Backend: [Framework + version]
- Database: [Database + version]
Integrations:
- [Integration 1]: [Purpose]
- [Integration 2]: [Purpose]
Data Models:
- [Model 1]: [Fields]
- [Model 2]: [Fields]
Performance:
- [Requirement 1]
- [Requirement 2]
Security:
- [Requirement 1]
- [Requirement 2]"
```
---
## Phase 5: Design System Components (3 min)
**You say:**
```
"Design system components used:
Button:
- Primary variant: [Usage]
- Secondary variant: [Usage]
- Specs: D-Design-System/.../Buttons/
Input:
- Text variant: [Usage]
- Email variant: [Usage]
- Password variant: [Usage]
- Specs: D-Design-System/.../Inputs/
[List all components]
All components follow our design tokens:
- Colors: tokens/colors.json
- Typography: tokens/typography.json
- Spacing: tokens/spacing.json"
```
---
## Phase 6: Acceptance Criteria (3 min)
**You say:**
```
"Acceptance criteria:
Functional:
- [Criterion 1]
- [Criterion 2]
- [Criterion 3]
Non-Functional:
- [Criterion 1]
- [Criterion 2]
Edge Cases:
- [Case 1]
- [Case 2]
All criteria are testable and defined in TS-XXX.yaml"
```
---
## Phase 7: Testing Approach (2 min)
**You say:**
```
"Testing approach:
I've created test scenario TS-XXX which includes:
- Happy path tests ([number] tests)
- Error state tests ([number] tests)
- Edge case tests ([number] tests)
- Design system validation
- Accessibility tests
When you're done implementing, I'll:
1. Run these test scenarios
2. Create issues if problems found
3. Iterate with you until approved
4. Sign off when quality meets standards"
```
---
## Phase 8: Complexity Estimate (2 min)
**You say:**
```
"My complexity estimate:
Size: [Small/Medium/Large]
Effort: [Time estimate]
Risk: [Low/Medium/High]
Dependencies:
- [Dependency 1]
- [Dependency 2]
Assumptions:
- [Assumption 1]
- [Assumption 2]
Does this align with your technical assessment?"
```
---
## Phase 9: Special Considerations (2 min)
**You say:**
```
"Special considerations:
- [Important note 1]
- [Important note 2]
- [Potential gotcha]
- [Critical requirement]
Questions or concerns?"
```
---
## Phase 10: Confirmation & Next Steps (1 min)
**You say:**
```
"So to confirm:
- You have DD-XXX.yaml (Design Delivery)
- You have TS-XXX.yaml (Test Scenario)
- You have all scenario specs in C-UX-Scenarios/
- You have all component specs in D-Design-System/
- You'll break this into [number] epics
- Estimated [time] to implement
- You'll notify me when ready for validation
Anything else you need?"
```
---
## Handoff Log Template
File: `deliveries/DD-XXX-handoff-log.md`
```markdown
# Handoff Log: DD-XXX
**Date:** [Date]
**Duration:** [Duration] minutes
**Participants:**
- WDS UX Expert: [Your name]
- BMad Architect: [Architect name]
## Key Points Discussed
- User value and success criteria
- Complete scenario walkthrough
- Technical requirements confirmed
- Design system components reviewed
- Acceptance criteria agreed
- Testing approach explained
- Complexity estimate aligned
## Epic Breakdown Agreed
1. Epic 1: [Name] ([time])
2. Epic 2: [Name] ([time])
**Total:** [time estimate]
## Questions & Answers
Q: "[Question]"
A: "[Answer]"
## Action Items
- [ ] Architect: Create architecture document
- [ ] Architect: Break down into dev stories
- [ ] Architect: Notify designer when ready for validation
- [ ] Designer: Start designing next flow
## Status
**Handoff:** Complete ✅
**Delivery Status:** in_development
**Next Touch Point:** Designer validation (Phase 5 [T] Acceptance Testing)
```

71
_bmad/wds/workflows/4-ux-design/data/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md Normal file
View File

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

488
_bmad/wds/workflows/4-ux-design/data/modular-architecture/00-foundation/agent-designer-collaboration.md Normal file
View File

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

123
_bmad/wds/workflows/4-ux-design/data/modular-architecture/01-core-concepts/complexity-detection.md Normal file
View File

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

144
_bmad/wds/workflows/4-ux-design/data/modular-architecture/01-core-concepts/content-placement-rules.md Normal file
View File

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

144
_bmad/wds/workflows/4-ux-design/data/modular-architecture/01-core-concepts/three-tier-overview.md Normal file
View File

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

70
_bmad/wds/workflows/4-ux-design/data/modular-architecture/02-workflows/01-what-are-storyboards.md Normal file
View File

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

68
_bmad/wds/workflows/4-ux-design/data/modular-architecture/02-workflows/01-when-to-use.md Normal file
View File

@@ -0,0 +1,68 @@
# When to Use Storyboards
**Complexity indicators that require visual documentation**
---
## Create Storyboards For:
✅ **Components with 3+ states**
- Example (TaskFlow): Task status (TODO, IN_PROGRESS, BLOCKED, DONE, ARCHIVED)
✅ **Time-based transitions**
- Example (TaskFlow): Deadline reminders, auto-status updates
✅ **Multi-step user flows**
- Example (TaskFlow): Creating → Assigning → Completing a task
✅ **Complex interactions between components**
- Example (TaskFlow): Task completion updates dashboard and team notifications
✅ **State machines with branching paths**
- Example (TaskFlow): Happy path vs validation error vs timeout
---
## Don't Need Storyboards For:
❌ **Simple buttons**
- Hover and active states are obvious
❌ **Static content sections**
- No state changes to document
❌ **Single-state components**
- Nothing to show in sequence
---
## Examples
### Need Storyboard:
- **TaskFlow:** Task status board (5 states, time-based reminders)
- **Future Project:** Search with autocomplete (5 states, real-time)
- **Future Project:** Multi-step form (progress tracking)
- **Future Project:** Payment flow (multiple steps, error handling)
### Don't Need Storyboard:
- Submit button (2-3 states)
- Hero image (static)
- Text paragraph (no states)
- Logo (no interaction)
---
## Next Steps
- [Storyboard Types](01-storyboard-types.md)
- [Creation Guide](creation-guide.md)

86
_bmad/wds/workflows/4-ux-design/data/modular-architecture/02-workflows/02-file-structure.md Normal file
View File

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

155
_bmad/wds/workflows/4-ux-design/data/modular-architecture/02-workflows/complexity-router-workflow.md Normal file
View File

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

312
_bmad/wds/workflows/4-ux-design/data/modular-architecture/02-workflows/page-specification-workflow.md Normal file
View File

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

75
_bmad/wds/workflows/4-ux-design/data/modular-architecture/02-workflows/storyboards-guide.md Normal file
View File

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

128
_bmad/wds/workflows/4-ux-design/data/modular-architecture/03-quick-refs/benefits.md Normal file
View File

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

67
_bmad/wds/workflows/4-ux-design/data/modular-architecture/03-quick-refs/decision-tree.md Normal file
View File

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

742
_bmad/wds/workflows/4-ux-design/data/modular-architecture/COMPONENT-FILE-STRUCTURE.md Normal file
View File

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

552
_bmad/wds/workflows/4-ux-design/data/modular-architecture/CONTENT-PLACEMENT-GUIDE.md Normal file
View File

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

301
_bmad/wds/workflows/4-ux-design/data/modular-architecture/CROSS-PAGE-CONSISTENCY.md Normal file
View File

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

714
_bmad/wds/workflows/4-ux-design/data/modular-architecture/STORYBOARD-INTEGRATION.md Normal file
View File

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

289
_bmad/wds/workflows/4-ux-design/data/modular-architecture/workflow.md Normal file
View File

@@ -0,0 +1,289 @@
---
name: Modular Component Architecture
description: Reference guides for three-tier specification system (Pages, Components, Features)
web_bundle: true
---
# Modular Component Architecture
**Goal:** Understand and apply three-tier architecture for component specification
**Your Role:** Architecture reference for designing modular, maintainable component systems
---
## OVERVIEW
This is a **guide collection** for three-tier modular architecture, not a step-by-step workflow.
**Three-Tier System:**
- **Pages** - Full page layouts and compositions
- **Components** - Reusable UI elements (simple and complex)
- **Features** - Complex component decompositions
**Purpose:** Separate concerns, reduce duplication, enable modularity
---
## WHEN TO USE
**Use these guides when:**
- ✅ Writing page specifications
- ✅ Decomposing complex components
- ✅ Deciding where to document content
- ✅ Need to understand component complexity
- ✅ Want to optimize agent-designer collaboration
**Skip these guides when:**
- ❌ Building simple prototypes without specs
- ❌ Already familiar with the architecture
- ❌ Using different specification system
---
## THE FOUR SECTIONS
### 00. Foundation
**[Agent-Designer Collaboration](00-foundation/agent-designer-collaboration.md)**
How AI agents optimize designer craft without replacing designer thinking.
**Use when:** Understanding the philosophy behind modular architecture
**Topics:**
- Designer maintains creative control
- AI handles decomposition and optimization
- Collaborative workflow patterns
---
### 01. Core Concepts
Three fundamental concepts of the architecture:
**[Three-Tier Overview](01-core-concepts/three-tier-overview.md)**
- Overview of Pages, Components, and Features separation
- When to use each tier
- Benefits of separation
**[Content Placement Rules](01-core-concepts/content-placement-rules.md)**
- Decision tree for where to document content
- Simple vs complex component rules
- Page-specific vs shared content
**[Complexity Detection](01-core-concepts/complexity-detection.md)**
- How to identify simple vs complex components
- When to decompose further
- Complexity indicators
**Use when:** Learning the architecture or making placement decisions
---
### 02. Workflows
Practical workflows for applying the architecture:
**[Page Specification Workflow](02-workflows/page-specification-workflow.md)**
- Step-by-step page decomposition from sketch to specs
- Extracting components from page layouts
- Handling page-specific content
**[Complexity Router Workflow](02-workflows/complexity-router-workflow.md)**
- Guided decomposition for complex components
- When to create feature folders
- Substep breakdown patterns
**[Storyboards Guide](02-workflows/storyboards-guide.md)**
- Using visual storyboards for complex components
- State documentation
- Interaction flows
**Use when:** Actively creating specifications
---
### 03. Quick References
Fast lookup guides for common questions:
**[Decision Tree](03-quick-refs/decision-tree.md)**
- One-page flowchart for file placement
- Quick decision making
- Common scenarios
**[Benefits Summary](03-quick-refs/benefits.md)**
- Why this architecture works
- Advantages of three-tier system
- Problem it solves
**Use when:** Need quick answers or reminders
---
## DETAILED NAVIGATION
For comprehensive navigation of all guides and substeps:
**[Modular Architecture Guide](00-MODULAR-ARCHITECTURE-GUIDE.md)**
This provides detailed index of all files including examples and substeps.
---
## QUICK START
### "Where do I document this component?"
Start here: [Content Placement Rules](01-core-concepts/content-placement-rules.md)
Then use: [Decision Tree](03-quick-refs/decision-tree.md)
---
### "How do I write a page specification?"
Start here: [Page Specification Workflow](02-workflows/page-specification-workflow.md)
Reference: [Three-Tier Overview](01-core-concepts/three-tier-overview.md)
---
### "When should I decompose a component?"
Start here: [Complexity Detection](01-core-concepts/complexity-detection.md)
Then use: [Complexity Router Workflow](02-workflows/complexity-router-workflow.md)
---
### "How do I document complex interactions?"
Start here: [Storyboards Guide](02-workflows/storyboards-guide.md)
Reference: [Complexity Router Workflow](02-workflows/complexity-router-workflow.md)
---
## INTEGRATION WITH WDS
### During Page Specification Phase
After sketching, before implementation:
1. Review page sketch
2. Apply [Page Specification Workflow](02-workflows/page-specification-workflow.md)
3. Use [Content Placement Rules](01-core-concepts/content-placement-rules.md) for each component
4. Document simple components inline
5. Create feature folders for complex components
6. Use [Complexity Router](02-workflows/complexity-router-workflow.md) for decomposition
### During Prototype Implementation
When building from specs:
1. Read page specification
2. Identify shared vs page-specific components
3. Build modular component library
4. Reference storyboards for complex interactions
---
## ARCHITECTURE BENEFITS
**For Designers:**
- ✅ Reduced duplication
- ✅ Clear decision framework
- ✅ Maintain creative control
- ✅ Better AI collaboration
**For Developers:**
- ✅ Modular component structure
- ✅ Clear implementation boundaries
- ✅ Reusable components identified
- ✅ Less ambiguity
**For Teams:**
- ✅ Consistent specification format
- ✅ Scalable architecture
- ✅ Easier maintenance
- ✅ Better handoff quality
---
## KEY PRINCIPLES
**1. Separation of Concerns**
- Pages handle layout and composition
- Components define reusable elements
- Features decompose complex components
**2. DRY (Don't Repeat Yourself)**
- Define once, reference everywhere
- Shared components in component library
- Page-specific variants documented inline
**3. Progressive Complexity**
- Start simple
- Decompose only when needed
- Use complexity detection to guide decisions
**4. Designer Agency**
- AI assists but doesn't replace designer thinking
- Designer makes final placement decisions
- Architecture enables, doesn't constrain
---
## TROUBLESHOOTING
### "I don't know if my component is complex enough to decompose"
Use: [Complexity Detection](01-core-concepts/complexity-detection.md)
Look for: Multiple states, conditional logic, nested interactions
### "I'm not sure where to document this content"
Use: [Decision Tree](03-quick-refs/decision-tree.md)
Ask: Is it page-specific or shared? Simple or complex?
### "The page specification feels too long"
Use: [Complexity Router Workflow](02-workflows/complexity-router-workflow.md)
Extract complex components to feature folders
---
## EXAMPLES
Throughout the guides, you'll find examples:
- **Simple Button** - Single file documentation
- **Complex Calendar** - Three-tier decomposition
- **Search Bar** - Page-specific content handling
These demonstrate the architecture in practice.
---
## NOTES
**This is architecture guidance** - not mandatory workflow steps.
Apply as needed based on:
- Project complexity
- Team size
- Specification requirements
- Development process
The architecture scales from small to large projects.
**Start simple, add structure when needed.**
---
_Modular Component Architecture - Clear structure, better collaboration_

842
_bmad/wds/workflows/4-ux-design/data/object-types/COMPLEXITY-ROUTER.md Normal file
View File

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

275
_bmad/wds/workflows/4-ux-design/data/object-types/ROUTER-FLOW-DIAGRAM.md Normal file
View File

@@ -0,0 +1,275 @@
# Object Router Flow Diagram
**Updated with Text-First Detection**
---
## Complete Flow
```
┌─────────────────────────────────────────────────────────┐
│ 4C-03: Components & Objects │
│ (For each object, top-left to bottom-right) │
└─────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ OBJECT-ROUTER.MD │
│ Step 1: TEXT DETECTION FIRST │
└─────────────────────┬───────────────────────────────────┘
│
▼
┌────────────────────────┐
│ Horizontal lines │
│ detected in sketch? │
└────────┬───────┬───────┘
│ │
YES ◄─────┘ └─────► NO
│ │
▼ ▼
┌──────────────────────┐ ┌──────────────────────────┐
│ ✓ TEXT DETECTED │ │ Step 2: ANALYZE │
│ │ │ OTHER OBJECT TYPE │
│ Quick Analysis: │ │ │
│ - Line count │ │ Check for: │
│ - Thickness │ │ - Button shapes │
│ - Spacing │ │ - Input boxes │
│ - Alignment │ │ - Image placeholders │
│ │ │ - Containers │
│ Appears to be: │ │ - Interactive elements │
│ {{text_type}} │ └────────┬─────────────────┘
└──────┬───────────────┘ │
│ ▼
│ ┌────────────────────────────┐
│ │ Agent suggests │
│ │ interpretation with │
│ │ reasoning │
│ └────────┬───────────────────┘
│ │
│ ▼
│ ┌────────────────────────────┐
│ │ User confirms: │
│ │ 1. Yes │
│ │ 2. Close - clarify │
│ │ 3. No - different │
│ └────────┬───────────────────┘
│ │
│ ▼
│ ┌────────────────────────────┐
│ │ Confirmed object type │
│ └────────┬───────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────┐
│ ROUTE TO OBJECT-SPECIFIC INSTRUCTION FILE │
└─────────────────────┬───────────────────────────────────┘
│
┌─────────────┴─────────────────────┐
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────────┐
│ heading-text.md │ │ Other object files: │
│ │ │ │
│ Complete text │ │ • button.md │
│ analysis: │ │ • text-input.md │
│ │ │ • link.md │
│ 1. Object ID │ │ • image.md │
│ 2. Text type │ │ • card.md │
│ 3. Sketch │ │ • modal-dialog.md │
│ analysis: │ │ • table.md │
│ - Lines │ │ • list.md │
│ - Thickness │ │ • navigation.md │
│ - Spacing │ │ • badge.md │
│ - Capacity │ │ • alert-toast.md │
│ 4. Content │ │ • progress.md │
│ guidance │ │ • video.md │
│ 5. Styling │ │ • custom.md │
│ 6. Responsive │ │ │
│ 7. Generate │ │ Each with: │
│ spec │ │ - Object ID │
└────────┬─────────┘ │ - Type-specific │
│ │ analysis │
│ │ - Complete examples │
│ │ - Generate spec │
│ └──────────┬───────────┘
│ │
└─────────────┬───────────────────┘
│
▼
┌─────────────────────────────┐
│ Specification Complete │
│ │
│ Object documented with: │
│ - Object ID assigned │
│ - Complete specification │
│ - Examples included │
│ - Consistent format │
└─────────────┬───────────────┘
│
▼
┌─────────────────────────────┐
│ Return to 4C-03 │
│ │
│ Next object? [Y/N] │
│ - YES: Loop back to router │
│ - NO: Section complete │
└─────────────────────────────┘
```
---
## Key Changes
### OLD: Generic Object Detection
```
1. Ask user "What type is this?" [list of 20 options]
2. User selects from list
3. Route to file
```
### NEW: Text-First with Intelligence
```
1. Check for horizontal lines FIRST
├─ YES → Text detected → Route to heading-text.md
└─ NO → Continue analysis
2. Agent analyzes and suggests with reasoning
3. User confirms quickly
4. Route to appropriate file
```
---
## Text Detection Flow (Detailed)
```
Object Router detects horizontal lines:
═══════════════════════════════
═══════════════════════════
↓
Agent says:
"✓ TEXT ELEMENT DETECTED
I see 2 thick horizontal lines - text content.
Quick Analysis:
- 2 lines (text placeholders)
- Thickness: 3px
- Spacing: 3px
- Alignment: Center
This appears to be HEADING (H2).
→ Loading text-specific instructions..."
↓
Routes to heading-text.md
↓
heading-text.md executes:
1. Confirms text type
2. Analyzes sketch in detail:
- Estimates font size (28-32px)
- Estimates line-height (1.3)
- Calculates capacity (50-60 chars)
3. Requests content with guidance
4. Validates content length
5. Specifies styling
6. Generates complete spec
↓
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
---
## Example Scenarios
### Scenario 1: Page with Heading + Paragraph + Button
```
Sketch shows (top to bottom):
═══════════════════════════════ ← 1. Text: pair of THICK lines (1 line of text)
═══════════════════════════════ = Heading (bold font weight)
───────────────────────────────── ← 2. Text: 2 pairs of THIN lines (2 lines of text)
───────────────────────────────── = Body paragraph (regular font weight)
───────────────────────────────── Large spacing between pairs = larger font
─────────────────────────────────
┌──────────────────┐
│ Get Started │ ← 3. Button
└──────────────────┘
Router processes:
1. Object 1: Detects 1 pair of thick lines → heading-text.md → H2 heading (bold, ~1 line)
2. Object 2: Detects 2 pairs of thin lines → heading-text.md → Body paragraph (~2 lines)
3. Object 3: Detects button shape → button.md → Primary button
```
### Scenario 2: Form with Labels + Inputs
```
Sketch shows:
══════════ ← 1. Text: pair of thin lines (1 line = label)
══════════ Small spacing = smaller font
┌───────────────────────────────┐
│ │ ← 2. Input box
└───────────────────────────────┘
────────── ← 3. Text: pair of thin lines (1 line = label)
────────── Small spacing = smaller font
┌───────────────────────────────┐
│ │ ← 4. Input box
└───────────────────────────────┘
Router processes:
1. Object 1: Detects pair of lines → heading-text.md → Label text (~20-30 chars)
2. Object 2: Detects input box → text-input.md → Email input
3. Object 3: Detects pair of lines → heading-text.md → Label text (~20-30 chars)
4. Object 4: Detects input box → text-input.md → Password input
```
---
**Text-first detection ensures accurate routing and complete text analysis!** 📝✨

391
_bmad/wds/workflows/4-ux-design/data/object-types/TEXT-DETECTION-PRIORITY.md Normal file
View File

@@ -0,0 +1,391 @@
# Text Detection Priority Rules
**For Object Router - Always Check for Text FIRST**
---
## Critical Rule: Text Markers = PAIRS of Lines
**✅ Text = Two horizontal lines together** (representing one line of text)
```
═══════════════════════════ ← Line 1 of pair
═══════════════════════════ ← Line 2 of pair = ONE line of text
```
**❌ Single line alone = NOT text** (it's a decorative element)
```
═══════════════════════════ ← SINGLE LINE = divider, border, underline (NOT text)
```
**Important Exception:** Very schematic sketches or miniatures (rare cases) might use single lines for text, but the default assumption should be: **single line = decorative element**.
---
## 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
- ✅ Ensures character capacity is calculated
- ✅ Prevents misidentification as other elements
---
## Text Detection Signatures
### 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
Small gap
═══════════════════════════ ← Pair 2 line 1
═══════════════════════════ ← Pair 2 line 2 = Text line 2
```
**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
```
### NOT Text Markers (Single Lines = Decorative Elements)
**❌ Horizontal divider (`<hr>`):**
```
═══════════════════════════ ← SINGLE LINE = section divider
```
**❌ Underline (decorative):**
```
Main Heading
───────────────────────────── ← SINGLE LINE = decorative underline
```
**❌ Border line:**
```
___________________________ ← SINGLE LINE = top/bottom border
```
**❌ Separator:**
```
Section 1 content...
───────────────────────────── ← SINGLE LINE = visual separator
Section 2 content...
```
---
## Detection Logic
### Step 1: Look for Paired Horizontal Lines
```
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
```
### Step 2: Analyze Text Marker Pairs
**Once text markers are detected, route to `heading-text.md` for complete analysis.**
The detailed analysis rules are documented in **`guides/SKETCH-TEXT-ANALYSIS-GUIDE.md`**, which covers:
- Line thickness → font weight
- Line spacing between pairs → font size
- Line position in container → text alignment
- Line count → number of text lines
- Line length → character capacity
**This file focuses on DETECTION only. For ANALYSIS, see `guides/SKETCH-TEXT-ANALYSIS-GUIDE.md`.**
---
## Text vs. Other Elements
### ✅ Text Element (Horizontal Line PAIRS)
```
═══════════════════════════ ← Pair indicating text
═══════════════════════════
───────────────────────────── ← 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`
### ❌ NOT Text - Image
**WDS Best Practice: Sketch the actual image content**
```
┌─────────────────┐
│ ~ ~ ~ │ ← Sketch of clouds (hero image background)
│ ~ ~ ~ │
└─────────────────┘
┌─────────────────┐
│ ◠ ◠ │ ← Sketch of face/person (profile photo)
│ ᵕ │
└─────────────────┘
┌─────────────────┐
│ /\ /\ │ ← Sketch of mountains/landscape
│ / \/ \ │
└─────────────────┘
```
**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
- More inspiring and communicative than placeholder X
**Detection:** Rectangle containing sketch/drawing, not text markers
**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)
---
## Detection Algorithm (Pseudo-code)
```python
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
```
---
## Examples from Dog Week
### Example 1: Hero Headline
**Sketch:**
```
═══════════════════════════════ ← Thick pair detected
═══════════════════════════════
```
**Detection:**
- ✅ **Pair detected** → This is TEXT
- **Route to:** `heading-text.md` for detailed analysis
**For complete analysis of thickness, spacing, size, see:** `guides/SKETCH-TEXT-ANALYSIS-GUIDE.md`
---
### 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
**For complete analysis of thickness, spacing, size, see:** `guides/SKETCH-TEXT-ANALYSIS-GUIDE.md`
---
### Example 3: Divider Line (NOT TEXT)
**Sketch:**
```
Section 1 content...
───────────────────────────────────────── ← Single line
Section 2 content...
```
**Detection:**
- ❌ **Single line detected** (no pair) → NOT text
- **Type:** Decorative `<hr>` element
---
## 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 guides/SKETCH-TEXT-ANALYSIS-GUIDE.md)
5. **Line thickness → font weight**
6. **Spacing between pairs → font size**
7. **Line position → text alignment**
8. **Line length → character capacity**
---
## Related Documentation
- **`guides/SKETCH-TEXT-ANALYSIS-GUIDE.md`** ← Complete analysis rules (MASTER GUIDE)
- **`heading-text.md`** ← Text object instruction file (uses analysis rules)
- **`guides/SKETCH-TEXT-QUICK-REFERENCE.md`** ← Quick lookup table
---
**This file: DETECTION logic. For detailed ANALYSIS rules, see guides/SKETCH-TEXT-ANALYSIS-GUIDE.md** 🎯

349
_bmad/wds/workflows/4-ux-design/data/object-types/object-router.md Normal file
View File

@@ -0,0 +1,349 @@
# Object Type Router
**Goal:** Intelligently analyze object, suggest interpretation, and route to appropriate specification instructions
---
## STEP 1: TEXT ELEMENT DETECTION
<output>**Analyzing object from sketch...**</output>
<action>Apply text detection rules from `TEXT-DETECTION-PRIORITY.md`:
- 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
</action>
<check if="horizontal_lines_detected">
<output>**✓ TEXT ELEMENT DETECTED**
I see horizontal line pairs in the sketch - this is text content.
**Quick Detection:**
- **{{pair_count}} line pairs** → {{pair_count}} lines of text
- Routing to text analysis for detailed specification...
</output>
<action>Route immediately to `object-types/templates/heading-text.md`</action>
<action>Pass detected pairs to heading-text.md for analysis using guides/SKETCH-TEXT-ANALYSIS-GUIDE.md</action>
**→ Loading text-specific instructions...**
> **Reference:** Text detection rules in `TEXT-DETECTION-PRIORITY.md`, analysis methodology in `guides/SKETCH-TEXT-ANALYSIS-GUIDE.md`
</check>
---
## STEP 2: OTHER OBJECT ANALYSIS
<check if="not_text_element">
<action>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)
</action>
<output>**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}}
**I think this {{component_name}}:**
- {{suggested_purpose}}
- {{suggested_interaction}}
- {{suggested_result}}
{{#if is_text_element}}
**Content should be:** {{content_guidance}} ({{line_count}} lines, ~{{total_chars}} characters)
{{/if}}
**Does this match your intent?**</output>
<ask>1. **Yes** - That's correct 2. **Close** - Similar but let me clarify 3. **No** - It's actually something different
Choice [1/2/3]:</ask>
---
## HANDLE USER RESPONSE
<check if="choice == 1">
<output>✅ Great! Proceeding with {{suggested_object_type}} documentation.</output>
<action>Store confirmed_object_type</action>
<action>Store confirmed_purpose</action>
<action>Route to appropriate object-type file</action>
</check>
<check if="choice == 2">
<ask>**What should I adjust in my interpretation?**
Please clarify:</ask>
<action>Listen to clarification</action>
<action>Adjust interpretation</action>
<output>**Updated interpretation:**
This {{adjusted_object_type}}:
- {{adjusted_purpose}}
Correct now?</output>
<action>Once confirmed, route to appropriate object-type file</action>
</check>
<check if="choice == 3">
<ask>**What is this object?**
Please describe what it is and what it does:</ask>
<action>Listen to user description</action>
<action>Determine correct object type</action>
<output>**Got it!** This is a {{corrected_object_type}}.
I'll document it accordingly.</output>
<action>Route to appropriate object-type file</action>
</check>
---
## STEP 3: ROUTE TO OBJECT-SPECIFIC INSTRUCTIONS
<action>Based on confirmed object type, load appropriate instruction file:
**TEXT ELEMENTS (DETECTED FIRST):**
- Horizontal line groups → `object-types/templates/heading-text.md`
- Handles: Headings (H1-H6), Paragraphs, Labels, Captions
- Includes: Sketch text analysis, character capacity, content guidance
**INTERACTIVE ELEMENTS:**
- **Button shapes** → `object-types/templates/button.md`
- **Input fields** → `object-types/templates/text-input.md`
- **Textarea boxes** → `object-types/textarea.md`
- **Dropdown indicators** → `object-types/select-dropdown.md`
- **Checkbox squares** → `object-types/checkbox.md`
- **Radio circles** → `object-types/radio-button.md`
- **Toggle switches** → `object-types/toggle-switch.md`
- **Underlined text/arrows** → `object-types/templates/link.md`
**MEDIA ELEMENTS:**
- **Image placeholders (X or box)** → `object-types/templates/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`
</action>
</check>
---
## AFTER OBJECT DOCUMENTATION
<action>After object-specific instructions complete, return here</action>
<output>✅ **{{object_name}} documented!**</output>
<ask>**More objects in this section?**
Looking at the sketch, I can see {{describe_remaining_objects}}.
Should I analyze the next object?
1. **Yes** - Continue with next object
2. **No** - Section complete
Choice [1/2]:</ask>
<check if="choice == 1">
<action>Loop back to top for next object analysis</action>
</check>
<check if="choice == 2">
<output>✅ Section complete!</output>
<action>Return to 4c-03</action>
</check>
---
## INTERPRETATION EXAMPLES
**Example 1: Button**
```
My interpretation:
This looks like a PRIMARY BUTTON.
Based on what I see:
- Prominent placement at bottom of form
- Bright blue background (primary color)
- White text saying "Save Profile"
- Located after all form fields
I think this "Save Profile Button":
- Saves the form data to the database
- Updates the user's profile information
- Shows loading state during save
- Navigates to profile view on success
Does this match your intent?
```
**Example 2: Text/Heading with Placeholder Lines**
```
My interpretation:
This looks like a HEADING (H2).
Based on what I see:
- Located at top of section, center-aligned
- Group of 2 horizontal bars (text placeholders)
- Thick lines suggesting larger font
- Positioned above body content
Text Analysis from Sketch:
- 2 lines of text (2 horizontal bar groups)
- Line thickness: 3px → ~28-32px font size
- Line spacing: 3px between lines → ~1.3 line-height
- Alignment: Center
- Content capacity: ~50-60 characters (25-30 per line)
I think this "Section Heading":
- Introduces the content section
- Draws attention to key message
- Should be brief and impactful
Content should be: Brief heading, 2 short lines (2 lines, ~50-60 characters)
Does this match your intent?
```
**Example 3: Body Text with Multiple Lines**
```
My interpretation:
This looks like BODY TEXT / PARAGRAPH.
Based on what I see:
- Below heading in main content area
- Group of 5 thin horizontal bars
- Left-aligned
- Comfortable spacing between lines
Text Analysis from Sketch:
- 5 lines of text (5 horizontal bar groups)
- Line thickness: 1px → ~16px font size
- Line spacing: 3px between lines → ~1.5 line-height
- Alignment: Left
- Content capacity: ~300-350 characters (60-70 per line)
I think this "Description Paragraph":
- Explains the feature or product
- Provides detailed information
- Engages the user
Content should be: Full paragraph (5 lines, ~300-350 characters)
Does this match your intent?
```
**Example 3: Link**
```
My interpretation:
This looks like a TEXT LINK.
Based on what I see:
- Underlined text saying "Forgot password?"
- Positioned below password field
- Smaller, less prominent than submit button
- Typical recovery flow placement
I think this "Forgot Password Link":
- Navigates to password reset flow
- Opens in same window
- For users who can't remember password
- Common authentication pattern
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
---
**Return to 4c-03 after documentation complete**

345
_bmad/wds/workflows/4-ux-design/data/object-types/templates/button.md Normal file
View File

@@ -0,0 +1,345 @@
# Object Type: Button
**Goal:** Document button component with complete specification
---
## BUTTON IDENTIFICATION
<output>**Documenting button: {{button_description}}**</output>
---
## OBJECT ID
<action>Generate Object ID using format:
`{page}-{section}-{element}-button`
Example: `signin-form-submit-button`
</action>
<output>**Object ID:** `{{generated_object_id}}`</output>
---
## BUTTON TYPE
<ask>**What type of button is this?**
1. **Primary** - Main action (e.g., Submit, Save, Continue)
2. **Secondary** - Alternative action (e.g., Cancel, Back)
3. **Tertiary/Text** - Low priority (e.g., Skip, Learn More)
4. **Destructive** - Dangerous action (e.g., Delete, Remove)
5. **Icon Button** - Icon only, no text
6. **Link Button** - Styled as button but navigates
Choice [1-6]:</ask>
<action>Store button_type</action>
---
## DESIGN SYSTEM COMPONENT
{{#if design_system_enabled}}
<ask>**Design System component:**
1. **Use existing component** - From your component library
2. **Create new component** - Add this to the Design System
3. **Page-specific only** - Not a reusable component
Choice [1/2/3]:</ask>
<check if="choice == 1">
<ask>**Which existing component?**
From your component library:
{{list_available_button_components}}
Component name:</ask>
<action>Store design_system_component</action>
<action>Store component_status = "existing"</action>
</check>
<check if="choice == 2">
<ask>**New component name:**
Suggested: `Button-{{button_type}}`
Component name:</ask>
<action>Store design_system_component</action>
<action>Store component_status = "new"</action>
<action>Mark for Design System addition in Phase 5</action>
<output>✅ This button will be added to your Design System in Phase 5.</output>
</check>
<check if="choice == 3">
<action>Store component_status = "page-specific"</action>
</check>
{{else}}
<action>Store component_status = "page-specific"</action>
{{/if}}
---
## BUTTON CONTENT
<ask>**Button text in all languages:**
{{#each language}}
- **{{language}}:**
{{/each}}
</ask>
<action>Store button_text for each language</action>
<ask>**Does the button have an icon?**
1. Yes - Icon before text
2. Yes - Icon after text
3. Yes - Icon only (no text)
4. No - Text only
Choice [1-4]:</ask>
<check if="has_icon">
<ask>**Icon name/type:** (e.g., arrow-right, check, trash)</ask>
<action>Store icon_name and icon_position</action>
</check>
---
## BUTTON STATES
<output>**Let's define all button states.**</output>
<ask>**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
</ask>
<action>Store state definitions for all states</action>
---
## BUTTON INTERACTION
<ask>**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)
4. If success...
5. If error...
6. User sees... (result)
7. Navigate to... (if applicable)
</ask>
<action>Store interaction_flow</action>
---
## VALIDATION & REQUIREMENTS
<ask>**Any requirements before button can be clicked?**
- Form validation needed: yes/no
- Required fields must be filled: yes/no
- User must be authenticated: yes/no
- Other prerequisites:
</ask>
<action>Store prerequisites</action>
---
## GENERATE BUTTON SPECIFICATION
<action>Generate button specification using format:
```markdown
### {{button_name}}
**Object ID:** `{{object_id}}`
**Type:** {{button_type}}
{{#if design_system_enabled}}
**Design System Component:** {{design_system_component}}
**Figma Component:** {{figma_component_name}}
{{/if}}
**Content:**
{{#each language}}
- **{{language}}:** {{button_text}}
{{/each}}
{{#if has_icon}}
**Icon:** {{icon_name}} ({{icon_position}})
{{/if}}
**States:**
_Default:_
- Background: {{default_bg}}
- Text: {{default_text}}
- Border: {{default_border}}
_Hover:_
- Background: {{hover_bg}}
- Text: {{hover_text}}
- Changes: {{hover_changes}}
_Active:_
- Background: {{active_bg}}
- Text: {{active_text}}
- Feedback: {{active_feedback}}
_Disabled:_
- Background: {{disabled_bg}}
- Text: {{disabled_text}}
- Cursor: not-allowed
- When: {{disabled_condition}}
{{#if has_loading_state}}
_Loading:_
- Spinner: visible
- Text: {{loading_text}}
- Actions: disabled
{{/if}}
**Interaction:**
1. {{interaction_step_1}}
2. {{interaction_step_2}}
...
{{#if has_prerequisites}}
**Requirements:**
- {{prerequisite_list}}
{{/if}}
```
</action>
<output>✅ **Button documented!**
Specification added to page document.</output>
---
## EXAMPLE OUTPUT
```markdown
### Submit Button
**Object ID:** `signin-form-submit-button`
**Type:** Primary
**Design System Component:** primary-button-large
**Figma Component:** Button/Primary/Large
**Content:**
- **English:** Sign In
- **Swedish:** Logga In
**Icon:** None
**States:**
_Default:_
- Background: #0066CC (primary blue)
- Text: #FFFFFF (white)
- Border: none
- Border-radius: 8px
- Padding: 12px 24px
_Hover:_
- Background: #0052A3 (darker blue)
- Text: #FFFFFF
- Changes: slight shadow (0 2px 8px rgba(0,0,0,0.15))
_Active:_
- Background: #003D7A (even darker)
- Text: #FFFFFF
- Feedback: scale(0.98), shadow removed
_Disabled:_
- Background: #CCCCCC (gray)
- Text: #666666 (dark gray)
- Opacity: 0.6
- Cursor: not-allowed
- When: Form validation fails or during submission
_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
4. If validation fails: show field errors, exit loading
5. If validation passes: POST to /api/auth/signin
6. On API success: redirect to /dashboard
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
```
---
**Return to 4c-03 to continue with next object**

549
_bmad/wds/workflows/4-ux-design/data/object-types/templates/heading-text.md Normal file
View File

@@ -0,0 +1,549 @@
# Object Type: Heading/Text (with Purpose-Based Organization)
**Goal:** Document text element with purpose-based naming and grouped translations
---
## TEXT IDENTIFICATION & ANALYSIS
<output>**Analyzing text element from sketch...**</output>
<action>First, check if sketch contains ACTUAL TEXT (readable words):
- Headlines often drawn as actual text
- Provides content guidance
- Can change during conversation
</action>
<check if="sketch_has_readable_text">
<action>Extract text from sketch</action>
<output>**Text found in sketch:** "{{extracted_text}}"
I can use this as a starting suggestion, but we can change it if needed.</output>
</check>
<check if="sketch_has_line_markers">
<action>Analyze text placeholders using rules from guides/SKETCH-TEXT-ANALYSIS-GUIDE.md:
- Count horizontal line pairs (pairs = text lines)
- Measure line thickness (thickness → font weight)
- Measure distance between line pairs (spacing → font size estimate)
- Check line position in container (position → text alignment)
- Calculate line-height from font size
- Estimate character capacity from line length
</action>
<output>**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
**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 `guides/SKETCH-TEXT-ANALYSIS-GUIDE.md` for complete methodology.</output>
</check>
---
## STEP 1: PURPOSE-BASED NAMING
<output>**Let's define this text element by its PURPOSE, not its content.**</output>
<ask>**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")
- "Error message" (not "Invalid email")
- "Form label" (not "Email Address")
Purpose/function:</ask>
<action>Store text_purpose (e.g., "hero-headline", "feature-description", "error-message")</action>
---
## STEP 2: OBJECT ID (Based on Purpose)
<action>Generate Object ID from purpose:
`{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`)
</action>
<output>**Object ID:** `{{generated_object_id}}`
Based on purpose: {{text_purpose}}</output>
---
## STEP 3: DESIGN SYSTEM COMPONENT
{{#if design_system_enabled}}
<ask>**Design System component:**
1. **Use existing typography** - From your Design System
2. **Create new typography** - Add this style to the Design System
3. **Page-specific only** - Not a reusable style
Choice [1/2/3]:</ask>
<check if="choice == 1">
<ask>**Which existing typography component?**
From your Design System:
{{list_available_typography_components}}
Component name:</ask>
<action>Store design_system_component</action>
<action>Store component_status = "existing"</action>
</check>
<check if="choice == 2">
<ask>**New typography component name:**
Suggested: `Typography-{{text_type}}` (e.g., Typography-H1, Typography-Body)
Component name:</ask>
<action>Store design_system_component</action>
<action>Store component_status = "new"</action>
<action>Mark for Design System addition in Phase 5</action>
<output>✅ This typography style will be added to your Design System in Phase 5.</output>
</check>
<check if="choice == 3">
<action>Store component_status = "page-specific"</action>
</check>
{{else}}
<action>Store component_status = "page-specific"</action>
{{/if}}
---
## STEP 4: TEXT TYPE & POSITIONING
<ask>**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)
- h4/h5/h6 (minor headings)
- p (paragraph)
- span (inline, no semantic meaning)
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)
- Sub header light (lighter section headings)
- Card header (headers within cards/panels)
- Small header (minor headers, labels)
- Body text (standard paragraphs)
- Body text large (larger body, intro text)
- Body text small (smaller body, secondary info)
- Caption text (image captions, metadata)
- Label text (form labels, UI labels)
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)
- justified (lines span full width)
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)
</ask>
<action>Store html_tag, visual_type, visual_style_name, position, and style specifications</action>
---
## STEP 5: CONTENT WITH GROUPED TRANSLATIONS
<output>**Now let's specify the actual content.**
**IMPORTANT:** Translations will be grouped so each language reads coherently.
{{#if sketch_has_text}}
Content length: Based on sketch text "{{extracted_text}}"
{{else}}
Content length: ~{{total_chars}} characters (from sketch analysis)
{{/if}}
**Project languages:** {{product_languages}} (from workflow config)</output>
<check if="sketch_has_readable_text">
<output>**I found text in your sketch:** "{{extracted_text}}"
Let me suggest translations for all configured languages...</output>
<action>Translate extracted_text to all product_languages</action>
<action>Generate suggested translations using context and best practices</action>
<output>**Suggested content for {{text_purpose}}:**
{{#each product_languages}}
**{{this}}:** {{suggested_translation}}
{{/each}}
These are my suggestions based on the sketch text. Please review and adjust as needed!</output>
<ask>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
3. **Manual input** - I'll enter them myself
Choice [1/2/3]:</ask>
<check if="choice == 2">
<ask>Which language(s) need adjustment?
{{#each product_languages}}
**{{this}}:** {{suggested_translation}} ← Change this?
{{/each}}
Please provide the corrected versions:</ask>
</check>
<check if="choice == 3">
<ask>**Content for this {{text_purpose}}:**
{{#each product_languages}}
**{{this}}:**
{{/each}}
</ask>
</check>
</check>
<check if="!sketch_has_readable_text">
<ask>**Content for this {{text_purpose}}:**
Please provide content. I'll suggest translations once you give me the first language!
**{{primary_language}}:**
</ask>
<action>After receiving primary language content, suggest translations for remaining languages</action>
<output>**Translation suggestions:**
{{#each remaining_languages}}
**{{this}}:** {{suggested_translation}}
{{/each}}
Would you like to use these, or provide your own?</output>
</check>
<action>Store content for each language</action>
<action>Validate length against sketch capacity (if applicable)</action>
<check if="content_exceeds_capacity">
<output>⚠️ **Length Warning:**
- Sketch capacity: ~{{sketch_capacity}} characters
- Your content: {{actual_chars}} characters
Consider shortening or adjusting design.</output>
</check>
---
## STEP 6: BEHAVIOR (if applicable)
<ask>**Does this text change or have behavior?**
- Static (never changes): no
- Updates with language toggle: yes
- Dynamic content (from API/user): yes
- Conditional display: yes
If yes, describe behavior:</ask>
<action>Store behavior if applicable</action>
---
## STEP 7: GENERATE SPECIFICATION (WDS Pattern)
<action>Generate specification following WDS specification pattern:
```markdown
#### {{Text_Purpose_Title}}
**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}}
- **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}}
- **Color**: {{text_color}}
{{/if}}
{{#if text_transform}}
- **Transform**: {{text_transform}}
{{/if}}
**Position**: {{position_description}}
**Alignment**: {{text_alignment}}
{{#if behavior}}
**Behavior**: {{behavior_description}}
{{/if}}
**Content**:
{{#each product_languages}}
- {{this}}: "{{content}}"
{{/each}}
> **Sketch Analysis:** Values derived using `guides/SKETCH-TEXT-ANALYSIS-GUIDE.md` methodology. Designer should review and confirm.
```
{{#each additional_language}}
- {{lang_code}}: "{{content}}"
{{/each}}
````
</action>
---
## TEXT GROUP ORGANIZATION
<output>**Is this text part of a GROUP?**
Many pages have text groups that should be read together:
- Headline + Body + Link
- Label + Helper text
- Heading + Subheading + Description
Grouping translations allows reading the entire section in one language.</output>
<ask>**Is this text part of a group?**
1. **Yes** - Part of a text group
2. **No** - Standalone text element
Choice [1/2]:</ask>
<check if="part_of_group">
<ask>**What other text elements are in this group?**
List them:</ask>
<action>Mark as text group for grouped translation output</action>
<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!</output>
</check>
---
## COMPLETE SPECIFICATION EXAMPLE (Dog Week Style)
```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**:
- 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)
- No italic, color: #1a1a1a
- **Behavior**: Updates with language toggle
- **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."
#### Supporting Text
**OBJECT ID**: `start-hero-supporting`
- **Component**: Body text (`.text-body`)
- **Position**: Below headline, above CTA button
- **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)
- **Behavior**: Updates with language toggle
- **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."
#### 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
- **Content**:
- EN: "start planning - free forever"
- SE: "börja planera - gratis för alltid"
```
**Reading the Hero in English:**
> "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]
---
## 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.
---
## 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
---
**Return to object-router after documentation complete**

165
_bmad/wds/workflows/4-ux-design/data/object-types/templates/image.md Normal file
View File

@@ -0,0 +1,165 @@
# Object Type: Image
**Goal:** Document image element with complete specification
---
## IMAGE IDENTIFICATION
<output>**Documenting image: {{image_description}}**</output>
---
## OBJECT ID
<action>Generate Object ID: `{page}-{section}-{element}-image`
Example: `landing-hero-illustration-image`
</action>
---
## DESIGN SYSTEM COMPONENT
{{#if design_system_enabled}}
<ask>**Design System component:**
1. **Use existing pattern** - From your Design System
2. **Create new pattern** - Add this image pattern to the Design System
3. **Page-specific only** - Not a reusable pattern
Choice [1/2/3]:</ask>
<check if="choice == 1">
<ask>**Which existing image pattern?**
From your Design System:
{{list_available_image_patterns}}
Component name:</ask>
<action>Store design_system_component</action>
<action>Store component_status = "existing"</action>
</check>
<check if="choice == 2">
<ask>**New image pattern name:**
Suggested: `Image-{{pattern_type}}` (e.g., Image-Hero, Image-Avatar, Image-Card)
Component name:</ask>
<action>Store design_system_component</action>
<action>Store component_status = "new"</action>
<action>Mark for Design System addition in Phase 5</action>
<output>✅ This image pattern will be added to your Design System in Phase 5.</output>
</check>
<check if="choice == 3">
<action>Store component_status = "page-specific"</action>
</check>
{{else}}
<action>Store component_status = "page-specific"</action>
{{/if}}
---
## IMAGE PROPERTIES
<ask>**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
</ask>
---
## IMAGE STATES
<ask>**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:
</ask>
---
## GENERATE SPECIFICATION
```markdown
### {{image_name}}
**Object ID:** `{{object_id}}`
**Type:** image
**Source:**
- File: {{image_path}}
- Alt (EN): {{alt_text_en}}
- Alt (SV): {{alt_text_sv}}
{{#if is_decorative}}
- Decorative: role="presentation"
{{/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}}
- Retina (@2x): {{retina_path}}
{{/if}}
**Loading:**
- Placeholder: {{placeholder_type}}
- Lazy load: {{lazy_loading}}
**States:**
- **Loading:** {{loading_state}}
- **Error:** {{error_fallback}}
- **Loaded:** {{loaded_animation}}
```
---
**Return to 4c-03**

167
_bmad/wds/workflows/4-ux-design/data/object-types/templates/link.md Normal file
View File

@@ -0,0 +1,167 @@
# Object Type: Link
**Goal:** Document link/anchor element with complete specification
---
## LINK IDENTIFICATION
<output>**Documenting link: {{link_description}}**</output>
---
## OBJECT ID
<action>Generate Object ID: `{page}-{section}-{element}-link`
Example: `signin-form-forgot-link`
</action>
---
## LINK TYPE
<ask>**What type of link?**
1. **Internal** - Same app navigation
2. **External** - External website (opens new tab)
3. **Email** - mailto: link
4. **Phone** - tel: link
5. **Download** - File download
Choice [1-5]:</ask>
---
## DESIGN SYSTEM COMPONENT
{{#if design_system_enabled}}
<ask>**Design System component:**
1. **Use existing component** - From your component library
2. **Create new component** - Add this to the Design System
3. **Page-specific only** - Not a reusable component
Choice [1/2/3]:</ask>
<check if="choice == 1">
<ask>**Which existing component?**
From your component library:
{{list_available_link_components}}
Component name:</ask>
<action>Store design_system_component</action>
<action>Store component_status = "existing"</action>
</check>
<check if="choice == 2">
<ask>**New component name:**
Suggested: `Link-{{link_type}}` or `Link-{{style_variant}}`
Component name:</ask>
<action>Store design_system_component</action>
<action>Store component_status = "new"</action>
<action>Mark for Design System addition in Phase 5</action>
<output>✅ This link style will be added to your Design System in Phase 5.</output>
</check>
<check if="choice == 3">
<action>Store component_status = "page-specific"</action>
</check>
{{else}}
<action>Store component_status = "page-specific"</action>
{{/if}}
---
## LINK CONTENT & TARGET
<ask>**Link text in all languages:**
{{#each language}}
- **{{language}}:**
{{/each}}
**Target/Destination:**
- URL or route:
- Opens in: same tab / new tab
</ask>
---
## LINK STATES & STYLING
<ask>**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:
</ask>
---
## GENERATE SPECIFICATION
```markdown
### {{link_name}}
**Object ID:** `{{object_id}}`
**Type:** {{link_type}}
**Destination:** {{target_url}}
**Opens:** {{same_or_new_tab}}
**Content:**
{{#each language}}
- **{{language}}:** {{link_text}}
{{/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}}
- Opens in new tab
- Includes rel="noopener noreferrer"
{{/if}}
```
---
**Return to 4c-03**

463
_bmad/wds/workflows/4-ux-design/data/object-types/templates/text-input.md Normal file
View File

@@ -0,0 +1,463 @@
# Object Type: Text Input
**Goal:** Document text input field with complete specification
---
## INPUT IDENTIFICATION
<output>**Documenting text input: {{input_description}}**</output>
---
## OBJECT ID
<action>Generate Object ID using format:
`{page}-{section}-{field}-input`
Example: `signin-form-email-input`
</action>
<output>**Object ID:** `{{generated_object_id}}`</output>
---
## INPUT TYPE
<ask>**What type of text input is this?**
1. **Text** - General text (name, title, etc.)
2. **Email** - Email address
3. **Password** - Password (masked)
4. **Tel** - Phone number
5. **URL** - Website address
6. **Search** - Search query
7. **Number** - Numeric input
8. **Date** - Date picker
9. **Textarea** - Multi-line text
Choice [1-9]:</ask>
<action>Store input_type</action>
---
## DESIGN SYSTEM COMPONENT
{{#if design_system_enabled}}
<ask>**Design System component:**
1. **Use existing component** - From your component library
2. **Create new component** - Add this to the Design System
3. **Page-specific only** - Not a reusable component
Choice [1/2/3]:</ask>
<check if="choice == 1">
<ask>**Which existing component?**
From your component library:
{{list_available_input_components}}
Component name:</ask>
<action>Store design_system_component</action>
<action>Store component_status = "existing"</action>
</check>
<check if="choice == 2">
<ask>**New component name:**
Suggested: `Input-{{input_type}}`
Component name:</ask>
<action>Store design_system_component</action>
<action>Store component_status = "new"</action>
<action>Mark for Design System addition in Phase 5</action>
<output>✅ This input will be added to your Design System in Phase 5.</output>
</check>
<check if="choice == 3">
<action>Store component_status = "page-specific"</action>
</check>
{{else}}
<action>Store component_status = "page-specific"</action>
{{/if}}
---
## INPUT CONTENT
<ask>**Label text in all languages:**
{{#each language}}
- **{{language}}:**
{{/each}}
</ask>
<action>Store label_text for each language</action>
<ask>**Placeholder text in all languages:**
{{#each language}}
- **{{language}}:**
{{/each}}
</ask>
<action>Store placeholder_text for each language</action>
<ask>**Helper text** (optional guidance below field):
{{#each language}}
- **{{language}}:**
{{/each}}
</ask>
<action>Store helper_text for each language</action>
---
## INPUT PROPERTIES
<ask>**Input properties:**
- Required field: yes/no
- Max length: (number or "none")
- Min length: (number or "none")
- Autocomplete: (on/off/specific type like "email")
- Autofocus: yes/no
- Readonly: yes/no
</ask>
<action>Store input_properties</action>
---
## INPUT STATES
<output>**Let's define all input states.**</output>
<ask>**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:
- Cursor:
- Why disabled:
**Success state** (if applicable):
- Border color:
- Icon: (checkmark, etc.)
- When shown:
</ask>
<action>Store state definitions for all states</action>
---
## VALIDATION RULES
<ask>**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
</ask>
<action>Store validation_rules</action>
---
## ERROR MESSAGES
<ask>**Error messages for validation failures:**
{{#each validation_rule}}
**When {{rule_name}} fails:**
Error code: (e.g., ERR_EMAIL_REQUIRED)
{{#each language}}
- **{{language}}:**
{{/each}}
{{/each}}
</ask>
<action>Store error_messages with codes and translations</action>
---
## INPUT INTERACTION
<ask>**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:
</ask>
<action>Store interaction_behaviors</action>
---
## GENERATE INPUT SPECIFICATION
<action>Generate input specification using format:
```markdown
### {{input_name}}
**Object ID:** `{{object_id}}`
**Type:** {{input_type}}
{{#if design_system_enabled}}
**Design System Component:** {{design_system_component}}
**Figma Component:** {{figma_component_name}}
{{/if}}
**Label:**
{{#each language}}
- **{{language}}:** {{label_text}}
{{/each}}
**Placeholder:**
{{#each language}}
- **{{language}}:** {{placeholder_text}}
{{/each}}
{{#if has_helper_text}}
**Helper Text:**
{{#each language}}
- **{{language}}:** {{helper_text}}
{{/each}}
{{/if}}
**Properties:**
- Required: {{is_required}}
- Max length: {{max_length}}
- Min length: {{min_length}}
- Autocomplete: {{autocomplete}}
- Autofocus: {{autofocus}}
**States:**
_Default:_
- Border: {{default_border}}
- Background: {{default_bg}}
- Label: {{label_position}}
_Focus:_
- Border: {{focus_border}}
- Label: {{focus_label_position}}
- Outline: {{focus_outline}}
_Filled:_
- Border: {{filled_border}}
- Label: {{filled_label_position}}
_Error:_
- Border: {{error_border}}
- Icon: {{error_icon}}
- Message: Below field
_Disabled:_
- Border: {{disabled_border}}
- Background: {{disabled_bg}}
- Cursor: not-allowed
**Validation:**
{{#each validation_rule}}
- {{rule_description}}
{{/each}}
**Error Messages:**
{{#each error}}
- **{{error_code}}:** {{error_messages}}
{{/each}}
**Interactions:**
- **On Focus:** {{focus_behavior}}
- **On Input:** {{input_behavior}}
- **On Blur:** {{blur_behavior}}
```
</action>
<output>✅ **Input field documented!**
Specification added to page document.</output>
---
## EXAMPLE OUTPUT
```markdown
### Email Input Field
**Object ID:** `signin-form-email-input`
**Type:** email
**Design System Component:** text-input
**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
- Autocomplete: email
- Autofocus: yes
**States:**
_Default:_
- Border: 1px solid #CCCCCC
- Background: #FFFFFF
- Label: Inside field (placeholder position)
_Focus:_
- Border: 2px solid #0066CC (primary)
- Label: Floats above field
- Outline: 0 0 0 3px rgba(0,102,204,0.1)
_Filled:_
- Border: 1px solid #666666
- Label: Remains above field
_Error:_
- Border: 2px solid #DC2626 (red)
- Icon: ⚠️ (warning icon, right side)
- Message: Below field in red
_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
```
---
**Return to 4c-03 to continue with next object**

128
_bmad/wds/workflows/4-ux-design/data/object-types/workflow.md Normal file
View File

@@ -0,0 +1,128 @@
---
name: Object Type Router
description: Intelligent object detection and routing system for page specification
web_bundle: true
---
# Object Type Router
**Goal:** Analyze sketch objects, detect type, assess complexity, and route to appropriate specification template
**Your Role:** Intelligent router providing object analysis and specification guidance
---
## OVERVIEW
Router workflow used within the page specification process (called from step 4c-03).
**Not a standalone workflow** — only used within page specification.
---
## THE 3-STEP PROCESS
### Step 1: Text Detection (Priority)
**FIRST:** Check for horizontal line pairs
- 2 parallel lines = 1 line of text
- Multiple pairs = multiple text lines
- Single lines = decorative (borders, dividers)
**If text detected** → Route to [heading-text.md](templates/heading-text.md)
**Reference:** [TEXT-DETECTION-PRIORITY.md](TEXT-DETECTION-PRIORITY.md)
### Step 2: Object Analysis (if not text)
- Analyze visual shape, style, interactive indicators, context
- Suggest object type with reasoning
- Get user confirmation
**Reference:** [object-router.md](object-router.md)
### Step 3: Complexity Assessment
**Simple Component** (single state, no business logic):
→ Document in page specification only
**Complex Component** (3+ states, business rules, multi-step interactions):
→ Route to decomposition coaching
**Reference:** [COMPLEXITY-ROUTER.md](COMPLEXITY-ROUTER.md)
---
## ROUTING FLOW
```
Start
↓
[1] Text Detection Priority
├─ Horizontal line pairs?
│ ├─ YES → Route to heading-text.md
│ └─ NO → Continue to [2]
↓
[2] Object Analysis
├─ Analyze visual/context
├─ Suggest interpretation
├─ Get user confirmation
└─ Confirmed type → Continue to [3]
↓
[3] Complexity Assessment
├─ Simple → Route to object template
└─ Complex → Complexity Router (decomposition)
```
**Full diagram:** [ROUTER-FLOW-DIAGRAM.md](ROUTER-FLOW-DIAGRAM.md)
---
## AVAILABLE OBJECT TYPES
### Text Elements
**[Heading / Text](templates/heading-text.md)** — Headings, paragraphs, labels, captions
### Interactive Elements
- **[Button](templates/button.md)** — Primary, secondary, icon buttons
- **[Text Input](templates/text-input.md)** — Single-line inputs, search, forms
- **[Link](templates/link.md)** — Text, navigation, action links
- **[Image](templates/image.md)** — Static, responsive, placeholders
- Additional: Textarea, Select, Checkbox, Radio, Toggle
### Container Elements
Card, Modal/Dialog, Table, List
### Navigation Elements
Navigation menu, Tabs, Breadcrumbs
### Status Elements
Badge, Alert/Toast, Progress indicator
### Custom Components
Unique to project — decomposed via Complexity Router
---
## INTERPRETATION APPROACH
**Trust-the-Agent:** Agent interprets with reasoning, user confirms.
When interpreting, explain:
- What visual cues you see (placement, color, shape)
- What you think it does (purpose, behavior)
- Why you chose this type
User can confirm, clarify, or correct.
---
## FILES REFERENCE
**Router Files:**
- [object-router.md](object-router.md) — Main routing logic
- [COMPLEXITY-ROUTER.md](COMPLEXITY-ROUTER.md) — Complexity assessment
- [ROUTER-FLOW-DIAGRAM.md](ROUTER-FLOW-DIAGRAM.md) — Visual flow
- [TEXT-DETECTION-PRIORITY.md](TEXT-DETECTION-PRIORITY.md) — Text detection rules
**Object Templates:** All in [templates/](templates/) — button.md, heading-text.md, text-input.md, image.md, link.md

28
_bmad/wds/workflows/4-ux-design/data/page-creation-flows/flow-a-sketch.md Normal file
View File

@@ -0,0 +1,28 @@
# Flow A: Sketch Path
**Activates when:** User chooses to draw a sketch (physical/digital)
---
## Process
<output>**Perfect! Let's set up for your sketch.**
I'll create:
1. Page placeholder with navigation
2. Sketches folder ready for upload
3. Basic page structure
When you're ready, upload your sketch and we'll analyze it together using the Page Process Workshop.</output>
---
## Actions
1. Run `page-init-lightweight.md` to create structure
2. User uploads sketch when ready
3. Return to `workshop-page-process.md` for analysis
---
**This is the preferred path - sketches capture design intent best.**

138
_bmad/wds/workflows/4-ux-design/data/page-creation-flows/flow-b-verbal.md Normal file
View File

@@ -0,0 +1,138 @@
# Flow B: Verbal Specification
**Activates when:** User chooses to describe the page through discussion
---
## Introduction
<output>**Great! Let's build the page concept through conversation.**
We'll define:
- Page sections (what areas exist?)
- Section purposes (why does each section exist?)
- Key objects (what interactive elements?)
- User flow (how do they move through the page?)
This creates a conceptual specification - the page where concept meets description.</output>
---
## SUBSTEP B1: Identify Sections
<ask>**What are the main SECTIONS of this page?**
Think about areas/blocks, like:
- Header/Navigation
- Hero/Banner
- Content areas
- Forms
- Footer
List the sections from top to bottom:</ask>
<action>Store sections_list</action>
---
## SUBSTEP B2: Section Purposes
<output>**Now let's define each section's purpose:**</output>
<action>
For each section in sections_list:
<ask>
**{{section.name}}**
What is the PURPOSE of this section?
- What should the user understand/do here?
- Why does this section exist?
Purpose:
</ask>
Store section.purpose
End
</action>
---
## SUBSTEP B3: Key Objects
<ask>**What are the KEY INTERACTIVE OBJECTS on this page?**
Think about:
- Buttons (CTAs, actions)
- Forms (inputs, selectors)
- Links (navigation, external)
- Media (images, videos)
List the most important interactive elements:</ask>
<action>Store key_objects</action>
---
## SUBSTEP B4: User Flow
<ask>**How does the user move through this page?**
- Where do they enter?
- What's their first action?
- What's the desired outcome?
- Where do they go next?
Describe the flow:</ask>
<action>Store user_flow</action>
---
## SUBSTEP B5: Generate Specification
<output>**Creating conceptual specification...**</output>
<action>
Generate page specification document:
- Page name and purpose
- Navigation (prev/next)
- For each section:
- Section name
- Section purpose
- Status: "CONCEPTUAL - Needs visualization"
- For each key object:
- Object name
- Object type
- Object purpose
- Status: "CONCEPTUAL - Needs specification"
- User flow description
- Next steps: "Create visualization (sketch/wireframe)"
Save to: C-UX-Scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/{{page_number}}-{{page_slug}}.md
</action>
---
## Completion
<output>✅ **Conceptual page specification created!**
**What we defined:**
- {{sections_list.length}} sections with purposes
- {{key_objects.length}} key interactive objects
- Complete user flow
**Status:** CONCEPTUAL - Ready for visualization
**Next steps:**
1. Create sketch/wireframe based on this concept
2. Upload visualization
3. Run Page Process Workshop to enhance specification
Or:
[A] Create ASCII layout now (quick visual)
[B] Done - I'll create sketch later
[C] Actually, let's refine the concept more
Choice:</output>

92
_bmad/wds/workflows/4-ux-design/data/page-creation-flows/flow-c-ascii.md Normal file
View File

@@ -0,0 +1,92 @@
# Flow C: ASCII Layout
**Activates when:** User chooses to create an ASCII layout
---
## Introduction
<output>**Let's create a simple ASCII layout together.**
⚠️ **Note:** ASCII is a last resort - sketches are much better for capturing design intent!
We'll create a basic box-and-text layout to show structure.</output>
---
## Gather Sections
<ask>**What are the main sections from top to bottom?**
Example:
- Header
- Hero
- Features (3 columns)
- CTA
- Footer
List sections:</ask>
<action>Store sections_for_ascii</action>
---
## Generate ASCII
<action>
Generate ASCII layout:
```
┌─────────────────────────────────────────┐
│ [HEADER] │
│ Logo | Nav | Contact │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────┐
│ │
│ [HERO SECTION] │
│ │
│ Headline Goes Here │
│ Subheadline text here │
│ │
│ [CTA Button] │
│ │
└─────────────────────────────────────────┘
┌───────────┬───────────┬───────────┐
│ │ │ │
│ [Feature] │ [Feature] │ [Feature] │
│ 1 │ 2 │ 3 │
│ │ │ │
│ Icon │ Icon │ Icon │
│ Text │ Text │ Text │
│ │ │ │
└───────────┴───────────┴───────────┘
... (for each section)
```
Save as conceptual specification with ASCII visualization
</action>
---
## Completion
<output>✅ **ASCII layout created!**
⚠️ **Remember:** This is a rough structural guide.
**Recommended next steps:**
1. Use this ASCII as a reference
2. Create a proper sketch/wireframe
3. Upload and run Page Process Workshop
**ASCII is helpful for structure, but lacks:**
- Visual hierarchy
- Spacing and proportions
- Typography details
- Color and visual design
- Actual content flow
Ready to move forward?</output>

69
_bmad/wds/workflows/4-ux-design/data/page-creation-flows/flow-d-reference.md Normal file
View File

@@ -0,0 +1,69 @@
# Flow D: Reference Page
**Activates when:** User has a similar page to reference
---
## Gather Reference
<ask>**Which page is this similar to?**
Provide:
- Page name or URL
- What file path (if internal project)
- Or description of reference page
Reference:</ask>
<action>Store reference_page</action>
---
## Identify Differences
<ask>**What are the KEY DIFFERENCES from the reference?**
What changes from the reference page?
Differences:</ask>
<action>Store differences</action>
---
## Generate Specification
<output>**Creating page based on reference...**</output>
<action>
If internal reference exists:
1. Copy reference specification structure
2. Update with differences
3. Mark sections that need updates
4. Preserve navigation pattern
If external reference:
1. Describe reference structure
2. Note differences
3. Create conceptual specification
4. Recommend creating sketch showing changes
Generate specification document
</action>
---
## Completion
<output>✅ **Reference-based page specification created!**
**Based on:** {{reference_page}}
**Key differences noted:** {{differences}}
**Next steps:**
- Review generated specification
- Create sketch showing unique elements
- Run Page Process Workshop to refine
Ready?</output>

131
_bmad/wds/workflows/4-ux-design/data/page-creation-flows/flow-e-html.md Normal file
View File

@@ -0,0 +1,131 @@
# Flow E: Generate HTML Prototype
**Activates when:** User chooses to generate HTML and screenshot it
---
## Introduction
<output>**Perfect! Let's generate an HTML prototype based on your concept.**
This creates a working page that you can:
- View in browser
- Screenshot for documentation
- Test responsive behavior
- Use as starting point for development
The screenshot becomes your "sketch" for the specification.</output>
---
## Benefits
- ✅ Professional, pixel-perfect visualization
- ✅ Tests actual layout behavior
- ✅ Responsive/mobile preview available
- ✅ Can iterate quickly
- ✅ Screenshot becomes the "sketch"
- ✅ Prototype is already built!
**Perfect for:**
- Users who can describe but can't draw
- Testing responsive layouts
- Quick professional mockups
- When prototype comes before final design
---
## SUBSTEP E1: Define Basic Structure
<output>**Based on your page concept:**
**Page:** {{page_name}}
**Sections:** {{sections_list}}
**Key Objects:** {{key_objects}}
I'll generate a clean HTML prototype with:
- Semantic HTML structure
- Basic Tailwind CSS styling (or vanilla CSS)
- Placeholder content based on your descriptions
- Responsive layout
- Interactive elements (buttons, forms, etc.)</output>
<ask>**Any specific styling preferences?**
[A] Clean, minimal (default)
[B] Modern SaaS style
[C] Professional/corporate
[D] Creative/bold
[E] Match an existing site (describe)
Styling:</ask>
<action>Store styling_preference</action>
---
## SUBSTEP E2: Generate HTML
<action>
**Generate HTML prototype:**
1. Create semantic HTML structure for each section
2. Add Tailwind CSS classes (or vanilla CSS)
3. Include placeholder content from user's descriptions
4. Add interactive elements with proper attributes
5. Make responsive (mobile-first)
6. Include basic states (hover, focus, etc.)
File: `prototypes/{{page_slug}}-prototype.html`
Save to: `C-UX-Scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/prototypes/`
</action>
---
## SUBSTEP E3: View and Capture
<output>**Prototype generated!** 🎉
**File location:**
`C-UX-Scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/prototypes/{{page_slug}}-prototype.html`
**Next steps:**
1. **Open in browser** - Double-click the HTML file
2. **Review the layout** - Does it match your vision?
3. **Test responsive** - Resize browser window
4. **Take screenshots:**
- Desktop view (full page)
- Mobile view (if needed)
- Key sections (close-ups)
5. **Save screenshots** to `sketches/` folder
**Screenshot naming:**
- `{{page_slug}}-desktop.jpg` - Full desktop view
- `{{page_slug}}-mobile.jpg` - Mobile view
- `{{page_slug}}-section-name.jpg` - Section close-ups</output>
<ask>**Ready to capture screenshots?**
Once you've saved the screenshots, type "done" and I'll analyze them:
Status:</ask>
<action>Wait for user confirmation</action>
---
## SUBSTEP E4: Iterate If Needed
<ask>**How does the prototype look?**
[A] Perfect - I've captured screenshots
[B] Need adjustments - let me describe changes
[C] Completely different direction - let's revise
Choice:</ask>
**If A:** Route to `workshop-page-process.md` for analysis
**If B:** Update HTML based on feedback, return to E3
**If C:** Return to main workshop STEP 1 to redefine concept

135
_bmad/wds/workflows/4-ux-design/data/page-creation-flows/lightweight-page-template.md Normal file
View File

@@ -0,0 +1,135 @@
# Lightweight Page Template
Template for generating page placeholder documents in page-init-lightweight workflow.
---
## File Location
`C-UX-Scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/{{page_number}}-{{page_slug}}.md`
---
## Template
```markdown
{{#if previous_page != "none"}}
← [{{previous_page}}](../{{previous_page_slug}}/{{previous_page_slug}}.md)
{{/if}}
{{#if next_page != "none" and next_page != "TBD"}}
| [{{next_page}}](../{{next_page_slug}}/{{next_page_slug}}.md) →
{{/if}}
{{#if next_page == "TBD"}}
| Next: TBD
{{/if}}
![{{page_name}}](sketches/{{page_slug}}-concept.jpg)
{{#if previous_page != "none"}}
← [{{previous_page}}](../{{previous_page_slug}}/{{previous_page_slug}}.md)
{{/if}}
{{#if next_page != "none" and next_page != "TBD"}}
| [{{next_page}}](../{{next_page_slug}}/{{next_page_slug}}.md) →
{{/if}}
# {{page_number}} {{page_name}}
**User Situation:** {{user_situation}}
**Page Purpose:** {{page_purpose}}
---
## Status
⚠️ **PLACEHOLDER** - This page needs:
- [ ] Sketch or screenshot
- [ ] Section breakdown
- [ ] Object specifications
- [ ] Component links
- [ ] Interaction definitions
- [ ] States and variants
---
## Navigation Context
{{#if previous_page != "none"}}
**Previous:** {{previous_page}}
{{else}}
**This is the first page in the scenario**
{{/if}}
{{#if next_page == "TBD"}}
**Next:** TBD (to be defined)
{{else if next_page != "none"}}
**Next:** {{next_page}}
{{else}}
**This is the last page in the scenario**
{{/if}}
---
## Open Questions
<!--
Auto-populate questions based on page characteristics.
Reference: instructions/open-questions.instructions.md
Check for:
- Responsive breakpoints
- Loading/Error/Empty states
- SEO (if public)
- Accessibility
- User permissions
- Time-sensitive behaviors
- Form validation
- Navigation/back behavior
-->
_No open questions at this time._
---
## Next Steps
To complete this page specification:
1. **Add a sketch**: Place your sketch in `sketches/` folder
2. **Run Page Process Workshop**: Analyze your sketch
3. **Specify sections**: Define all page sections
4. **Specify objects**: Define all interactive elements with Object IDs
5. **Link components**: Connect to design system components
6. **Document states**: Define loading, error, success, empty states
7. **Review open-questions.instructions.md**: Add relevant questions to Open Questions section
8. **Generate prototype**: Create interactive HTML preview
---
{{#if previous_page != "none"}}
**Previous Step**: ← [{{previous_page}}](../{{previous_page_slug}}/{{previous_page_slug}}.md)
{{/if}}
{{#if next_page != "none" and next_page != "TBD"}}
**Next Step**: → [{{next_page}}](../{{next_page_slug}}/{{next_page_slug}}.md)
{{/if}}
---
_Placeholder created using Whiteport Design Studio (WDS) methodology_
```
---
## Key Principles
### ✅ **Navigation is Critical**
- Appears three times (above sketch, below sketch, document bottom)
- Links to previous/next pages
- Creates navigable flow
- Essential for comprehension
### ✅ **Open Questions Ready**
- Section included from start
- Reference `open-questions.instructions.md` during spec creation
- Auto-populate based on page characteristics
- Ensures no edge cases are missed

196
_bmad/wds/workflows/4-ux-design/data/page-creation-flows/page-init-lightweight.md Normal file
View File

@@ -0,0 +1,196 @@
# Page Init (Lightweight)
**Purpose:** Quick page setup - establish context, create structure, ready for iteration
---
## CONTEXT
**This workflow activates when:** User wants quick page setup without full specification yet.
**Creates:** Minimal structure (name, purpose, navigation, folders) ready for iteration.
**Critical:** Navigation links must be established for page comprehension.
---
## STEP 1: PAGE BASICS
<ask>**What's the name of this page?**
Examples:
- "Start Page"
- "Sign In"
- "Dashboard"
- "User Profile"
Page name:</ask>
<action>
Store page_name
Generate page_slug from page_name (lowercase, hyphenated)
</action>
---
## STEP 2: PURPOSE & SITUATION
<ask>**What's the PURPOSE of this page?**
What should this page accomplish?
Purpose:</ask>
<action>Store page_purpose</action>
<ask>**What's the USER'S SITUATION when they arrive?**
What just happened? What are they trying to do?
User situation:</ask>
<action>Store user_situation</action>
---
## STEP 3: SCENARIO CONTEXT
<action>
**Determine scenario context:**
- Read project structure from wds-workflow-status.yaml
- Check existing scenarios
- Determine page placement
</action>
<check if="multiple_scenarios_exist">
<ask>**Which scenario does this page belong to?**
Existing scenarios:
{{#each scenario in existing_scenarios}}
- {{scenario.number}}: {{scenario.name}}
{{/each}}
Choose scenario [number] or "new" for a new scenario:</ask>
<action>Store scenario_number</action>
</check>
<check if="single_scenario or no_scenarios">
<output>This page will be in your main user flow.</output>
<action>Set scenario_number = 1</action>
</check>
---
## STEP 4: NAVIGATION FLOW (CRITICAL!)
<output>**Now let's establish navigation - this is crucial for comprehension!**</output>
<action>
**Determine page number:**
- Count existing pages in scenario
- Calculate next page number
- Store page_number (e.g., "1.1", "1.2", "2.1")
</action>
<ask>**What page comes BEFORE this one?**
Type page number, or "none" if this is the first page:
Previous page:</ask>
<action>Store previous_page</action>
<ask>**What page comes AFTER this one?**
- If you know: Type the page name (we'll create it next)
- If unsure: Type "TBD"
- If last page: Type "none"
Next page:</ask>
<action>Store next_page</action>
---
## STEP 5: CREATE STRUCTURE
<output>**Creating page structure...**</output>
<action>
**Create folder structure:**
Path: `C-UX-Scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/`
Create:
1. Page folder: `{{page_number}}-{{page_slug}}/`
2. Sketches folder: `{{page_number}}-{{page_slug}}/sketches/`
3. Placeholder document using template
**See:** [lightweight-page-template.md](lightweight-page-template.md)
</action>
---
## STEP 6: UPDATE NAVIGATION
<check if="previous_page != 'none'">
<action>
**Update previous page document:**
- Open previous page .md file
- Update "Next" link to point to this page
- Save
</action>
</check>
---
## STEP 7: COMPLETION
<output>✅ **Page initialized!**
**Created:**
- Folder: `{{page_number}}-{{page_slug}}/`
- Document: `{{page_number}}-{{page_slug}}.md`
- Sketches folder: `sketches/`
**Page details:**
- **Number:** {{page_number}}
- **Name:** {{page_name}}
- **Purpose:** {{page_purpose}}
**Navigation:**
- Previous: {{previous_page}} {{#if linked}}✅ linked{{/if}}
- Next: {{next_page}}
---
**Next steps:**
1. **Add your sketch** to `sketches/` folder
2. **Run Page Process Workshop** to analyze it
Or:
[A] Add sketch now and analyze
[B] Create another page first
[C] Back to scenario overview
Choice:</output>
---
## ROUTING
<action>
Based on user choice:
- [A] → workshop-page-process.md (with this page context)
- [B] → Repeat page-init for next page
- [C] → Return to scenario overview / main menu
</action>
---
**Created:** December 28, 2025
**Purpose:** Quick page initialization with navigation
**Status:** Ready for WDS Presentation page

130
_bmad/wds/workflows/4-ux-design/data/page-creation-flows/page-process-templates.md Normal file
View File

@@ -0,0 +1,130 @@
# Page Process Workshop Templates
Templates for comparison output and change detection displays.
---
## Change Detection Output Template
```handlebars
{{#if has_changes}}
🔍 **Changes detected:**
{{#if unchanged_sections.length > 0}}
✅ **Unchanged sections** ({{unchanged_sections.length}}):
{{#each section in unchanged_sections}}
- {{section.name}}
{{/each}}
{{/if}}
{{#if modified_sections.length > 0}}
✏️ **Modified sections** ({{modified_sections.length}}):
{{#each section in modified_sections}}
- {{section.name}}: {{section.change_description}}
{{/each}}
{{/if}}
{{#if new_sections.length > 0}}
➕ **New sections added** ({{new_sections.length}}):
{{#each section in new_sections}}
- {{section.name}}: {{section.description}}
{{/each}}
{{/if}}
{{#if completed_sections.length > 0}}
✨ **TBD sections now complete** ({{completed_sections.length}}):
{{#each section in completed_sections}}
- {{section.name}}: Ready to specify
{{/each}}
{{/if}}
{{#if removed_sections.length > 0}}
⚠️ **Sections removed** ({{removed_sections.length}}):
{{#each section in removed_sections}}
- {{section.name}}
{{/each}}
{{/if}}
{{else}}
✅ **No changes detected**
This sketch appears identical to the existing specification.
{{/if}}
```
---
## Detailed Comparison Template
```handlebars
**Detailed Section-by-Section Comparison:**
{{#each section in modified_sections}}
---
### {{section.name}}
**Current specification:**
{{section.current_spec_summary}}
**New sketch shows:**
{{section.new_sketch_summary}}
**Detected changes:**
{{#each change in section.changes}}
- {{change.description}}
{{/each}}
**Confidence:** {{section.confidence}}%
---
{{/each}}
```
---
## Update Summary Template
```handlebars
✅ **Page specification updated!**
**Summary:**
{{#if updated_count > 0}}
- {{updated_count}} sections updated
{{/if}}
{{#if added_count > 0}}
- {{added_count}} sections added
{{/if}}
{{#if preserved_count > 0}}
- {{preserved_count}} sections preserved (unchanged)
{{/if}}
{{#if removed_count > 0}}
- {{removed_count}} sections removed
{{/if}}
**Updated file:** `{{page_spec_path}}`
**Sketch saved to:** `{{sketch_path}}`
```
---
## Menu Options
**Update Strategy Menu (with changes):**
- [A] Update all changed/new/completed sections
- [B] Pick specific sections to update
- [C] Show me detailed comparison first
- [D] Actually, this is the same - cancel
**Update Strategy Menu (only removals):**
- [A] Remove deleted sections from spec
- [B] Keep them marked as "removed from design"
- [C] Cancel - I'll fix the sketch
**Completion Menu:**
- [A] Generate HTML prototype
- [B] Add another page
- [C] Update another section
- [D] Done with this page

153
_bmad/wds/workflows/4-ux-design/data/page-creation-flows/placeholder-templates.md Normal file
View File

@@ -0,0 +1,153 @@
# Placeholder Page Templates
Templates for generating placeholder page documents.
---
## Page Placeholder Document Template
File: `C-UX-Scenarios/{{scenario_path}}/{{page.number}}-{{page.slug}}/{{page.number}}-{{page.slug}}.md`
```markdown
{{#if @index > 0}}
← [{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}](../{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}/{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}.md)
{{/if}}
{{#if @index < pages_list.length - 1}}
| [{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}](../{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}/{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}.md) →
{{/if}}
# {{page.number}} {{page.name}}
**User Situation:** {{page.situation}}
**Page Purpose:** {{page.purpose}}
---
## Status
⚠️ **PLACEHOLDER** - This page needs:
- [ ] Sketch or screenshot
- [ ] Section breakdown
- [ ] Object specifications
- [ ] Component links
- [ ] Interaction definitions
- [ ] States and variants
---
## Next Steps
To complete this page specification:
1. **Add a sketch**: Place sketch in `sketches/` folder
2. **Run Workshop A**: Sketch Analysis Workshop to break down the visual
3. **Specify objects**: Define all interactive elements with Object IDs
4. **Link components**: Connect to design system components
5. **Document states**: Define loading, error, success, empty states
---
{{#if @index > 0}}
**Previous Step**: ← [{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}](../{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}/{{pages_list[@index - 1].number}}-{{pages_list[@index - 1].slug}}.md)
{{/if}}
{{#if @index < pages_list.length - 1}}
**Next Step**: → [{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}](../{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}/{{pages_list[@index + 1].number}}-{{pages_list[@index + 1].slug}}.md)
{{/if}}
---
_Placeholder created using Whiteport Design Studio (WDS) methodology_
```
---
## Scenario Overview Template
File: `C-UX-Scenarios/{{scenario_path}}/00-{{scenario_slug}}-scenario.md`
```markdown
# {{scenario_number}} {{scenario_name}} - Scenario Overview
**Project**: {{project_name}}
**Date Created**: {{date}}
**Last Updated**: {{date}}
## Scenario Overview
[Brief description of this scenario - to be filled in]
## Scenario Steps
{{#each page in pages_list}}
### **{{page.number}} {{page.name}}**
**Purpose**: {{page.purpose}}
**Status**: ⚠️ Placeholder
**Files**: [{{page.number}}-{{page.slug}}.md]({{page.number}}-{{page.slug}}/{{page.number}}-{{page.slug}}.md)
{{/each}}
## User Journey Flow
```
{{#each page in pages_list}}
{{page.number}}-{{page.slug}}{{#unless @last}} → {{/unless}}
{{/each}}
```
## Status
{{pages_list.length}} placeholder pages created. Each page needs:
- Sketch or visual concept
- Detailed specifications
- Object definitions
- Component links
---
_Created using Whiteport Design Studio (WDS) methodology_
```
---
## Scenario Tracking Template
File: `C-UX-Scenarios/{{scenario_path}}/scenario-tracking.yaml`
```yaml
scenario_number: {{scenario_number}}
scenario_name: "{{scenario_name}}"
pages_list:
{{#each page in pages_list}}
- name: "{{page.name}}"
slug: "{{page.slug}}"
page_number: "{{page.number}}"
purpose: "{{page.purpose}}"
status: "placeholder"
{{/each}}
current_page_index: 0
total_pages: {{pages_list.length}}
created_date: "{{date}}"
```
---
## When to Use Placeholders
**Advantages:**
- Quick mapping of entire flow
- Clear navigation before details
- Easy to see gaps or redundancies
- Can be reviewed by stakeholders early
- Team can work on different pages in parallel
**Use when:**
- New projects starting from scratch
- Complex multi-page scenarios
- When need for early stakeholder review
- Before diving into visual design
**Don't use when:**
- Single page projects
- When sketch already exists (use Workshop A)
- Small modifications to existing flow

168
_bmad/wds/workflows/4-ux-design/data/page-creation-flows/workshop-c-placeholder-pages.md Normal file
View File

@@ -0,0 +1,168 @@
# Workshop C: Placeholder Pages
**Trigger:** User wants to quickly map out a scenario structure without full specifications
---
## WORKSHOP GOAL
Rapidly create placeholder page documents with:
- Navigation structure
- Page names
- Page purposes
- Scenario context
This gives clarity to the overall flow before diving into detailed specifications.
---
## PHASE 1: TRIGGER DETECTION
<output>**Let's map out your scenario structure!**
Sometimes it helps to create placeholder pages first - just the names, purposes, and navigation - before diving into detailed specifications. This gives you a clear roadmap.
Would you like to:
- Create placeholders for a whole scenario flow
- Add individual placeholder pages as you plan
Let's start! 📋</output>
---
## PHASE 2: SCENARIO CONTEXT
<action>
**Determine scenario context:**
- Read project structure from wds-workflow-status.yaml
- Check existing scenarios
- Determine if working with existing or new scenario
</action>
<ask>**Which scenario are we mapping out?**
{{#if existing_scenarios}}
Existing scenarios:
{{#each scenario in existing_scenarios}}
- {{scenario.number}}: {{scenario.name}}
{{/each}}
Type scenario number or "new" for a new scenario:
{{else}}
This will be your first scenario. What should we call it?
Scenario name:
{{/if}}</ask>
<action>Store scenario_number and scenario_name</action>
---
## PHASE 3: FLOW MAPPING
<output>**Great! Let's map out the pages in this flow.**
Think about the user journey through "{{scenario_name}}"</output>
<ask>**How many pages will be in this scenario?**
Think about the steps a user goes through:
- Entry point / first page
- Middle steps (actions, decisions, inputs)
- Completion / exit page
Number of pages:</ask>
<action>Store pages_count</action>
---
## PHASE 4: PAGE ENUMERATION
<output>**Perfect! Let's name and define each page.**
I'll guide you through {{pages_count}} pages...</output>
For each page, gather:
1. **Page name** (examples: "Start Page", "Sign In", "Checkout")
2. **Page purpose** (1-2 sentences: what user accomplishes)
3. **User situation** (what just happened, what they're trying to do)
<action>Store page_name, page_purpose, user_situation for each page</action>
---
## PHASE 5: FLOW REVIEW
<output>**Here's your complete scenario flow:**
**Scenario {{scenario_number}}: {{scenario_name}}**
[Display numbered list of all pages with purposes]
Does this flow make sense? Any pages missing or in wrong order?</output>
<ask>**Review the flow:**
- Type "good" to proceed
- Type "add" to insert a page
- Type "remove N" to remove page N
- Type "move N to M" to reorder
Action:</ask>
---
## PHASE 6: GENERATE DOCUMENTS
<output>**Perfect! Creating your placeholder pages now...**</output>
<action>
For each page in pages_list:
1. Create folder structure with sketches subfolder
2. Generate placeholder document using template
3. Create scenario overview document
4. Create scenario tracking file
**See:** [placeholder-templates.md](placeholder-templates.md) for all templates
</action>
---
## PHASE 7: COMPLETION
<output>✅ **Placeholder pages created!**
**Scenario:** {{scenario_number}} - {{scenario_name}}
**Created:**
- {{pages_list.length}} page folders with navigation
- {{pages_list.length}} placeholder documents
- 1 scenario overview document
- 1 scenario tracking file
**Next Steps:**
1. **Add sketches** - Upload visuals for each page
2. **Complete specifications** - Run Workshop A (Sketch Analysis) for each page
3. **Add more pages** - Come back and add pages to this scenario
4. **Create another scenario** - Start a new user journey
**Ready to work on a specific page?**
Pick a page to work on:
[1-N] Page name
[N] Add another scenario
[D] Done for now
Choice:</output>
---
## ROUTING
<action>
**Based on user choice:**
- If user picks a page number → Route to Workshop B (Sketch Creation) for that page
- If user selects [N] → Route to scenario-init workshop
- If user selects [D] → Return to main UX design menu
</action>

134
_bmad/wds/workflows/4-ux-design/data/page-creation-flows/workshop-page-creation.md Normal file
View File

@@ -0,0 +1,134 @@
# Workshop: Page Creation (Discussion-Based)
**Purpose:** Define a page concept through conversation, create visualization method based on need
---
## CONTEXT
**This workflow activates when:** User needs to define a page concept but doesn't have a visualization yet.
**Goal:** Define what the page IS, then choose how to visualize it.
**Philosophy:** The page (concept) comes first. Visualization (method) follows.
---
## STEP 1: PAGE CONCEPT
<ask>**What is this page about?**
Tell me in your own words:
- What is this page called?
- What should it accomplish?
- Who uses it and why?
Describe the page concept:</ask>
<action>Store page_concept</action>
---
## STEP 2: VISUALIZATION PREFERENCE
<ask>**How would you like to visualize this page?**
[A] I'll draw a sketch (physical/digital) and upload it
[B] Let's describe it verbally - I'll specify sections through discussion
[C] Create a simple ASCII layout together
[D] It's similar to another page I can reference
[E] Generate HTML prototype - I'll screenshot it for documentation
Choice:</ask>
<action>Store visualization_method</action>
---
## FLOW ROUTING
Based on user choice, load the appropriate flow:
| Choice | Flow | File |
|--------|------|------|
| **A** | Sketch Path | [flow-a-sketch.md](flow-a-sketch.md) |
| **B** | Verbal Specification | [flow-b-verbal.md](flow-b-verbal.md) |
| **C** | ASCII Layout | [flow-c-ascii.md](flow-c-ascii.md) |
| **D** | Reference Page | [flow-d-reference.md](flow-d-reference.md) |
| **E** | HTML Prototype | [flow-e-html.md](flow-e-html.md) |
<action>Load and execute the selected flow substep</action>
---
## COMPLETION
<output>**Page concept defined!** 🎯
**Page:** {{page_name}}
**Method:** {{visualization_method_description}}
**Status:** Conceptual specification complete
**The page is the place where visualization meets specification.**
**What would you like to do next?**
[A] Create/upload sketch for this page
[B] Create another page
[C] Review what we've created
[D] Back to scenario overview
Choice:</output>
---
## KEY PHILOSOPHY
### ✅ **Page-Centric Thinking**
The **page** is the conceptual entity:
- Has a purpose
- Serves users
- Contains sections
- Has interactive objects
- Exists in a flow
The **visualization** is one representation:
- Sketch (preferred)
- Wireframe
- ASCII (last resort)
- Verbal description
- Reference to similar page
**The page comes first. Visualization follows.**
### ✅ **Flexible Methods**
Different projects need different approaches:
- Early concept → Verbal/ASCII → Sketch later
- Clear vision → Sketch directly
- Existing patterns → Reference + differences
- Iterative → Mix of methods
**The workshop adapts to YOUR process.**
---
## INTEGRATION
This workshop creates:
1. **Conceptual page specification** (always)
2. **Placeholder for visualization** (always)
3. **Guidance for next steps** (always)
Next workshops use:
- **workshop-page-process.md** - When sketch is ready
- **page-init-lightweight.md** - For quick structure
- **4b-sketch-analysis.md** - For detailed analysis
---
**Created:** December 28, 2025
**Purpose:** Define page concept, choose visualization method
**Philosophy:** Page first, visualization second
**Status:** Ready for use

235
_bmad/wds/workflows/4-ux-design/data/page-creation-flows/workshop-page-process.md Normal file
View File

@@ -0,0 +1,235 @@
# Page Process Workshop
**Purpose:** Intelligent sketch analysis with context detection - handles both new and updated sketches
---
## CONTEXT
**This workflow activates when:** User has a sketch/visualization ready to analyze.
**Intelligence:** Detects if this is a new page or update to existing specification.
**Behavior:**
- New page → Full analysis
- Updated page → Change detection, incremental update
- Partial completion → Specify ready sections, mark TBD
---
## STEP 1: CONTEXT DETECTION
<action>
**Determine page context:**
1. Read current page specification (if exists)
2. Check for existing sketch versions
3. Identify project structure (scenarios, pages)
4. Store context information
</action>
<check if="!page_spec_exists">
<output>**This is the first sketch for this page!**
Let me analyze what you've drawn and create the initial specification.</output>
<action>Route to: `../../steps-k/step-01-sketch-analysis.md` (existing workflow)</action>
</check>
<check if="page_spec_exists">
<output>**I see we already have specifications for this page.**
Let me compare this sketch to what we have...</output>
<action>Proceed to STEP 2: Change Detection</action>
</check>
---
## STEP 2: CHANGE DETECTION (For Existing Pages)
<action>
**Compare new sketch to existing specifications:**
1. Load existing specification document
2. Identify which sections are already specified
3. Analyze new sketch for:
- Unchanged sections
- Modified sections
- New sections added
- Removed sections
- TBD sections now complete
- Complete sections now TBD
4. Calculate confidence for each comparison
</action>
<output>**Comparison Results:**
**See:** [page-process-templates.md](page-process-templates.md) for output templates
Display:
- Unchanged sections (✅)
- Modified sections (✏️)
- New sections added (➕)
- TBD sections now complete (✨)
- Sections removed (⚠️)
</output>
---
## STEP 3: UPDATE STRATEGY
<check if="has_changes">
<ask>**How would you like to proceed?**
[A] Update all changed/new/completed sections
[B] Pick specific sections to update
[C] Show me detailed comparison first
[D] Actually, this is the same - cancel
Choice:</ask>
<action>Store user_choice</action>
</check>
---
## STEP 4A: UPDATE ALL (If user chose A)
<check if="user_choice == 'A'">
<output>**Updating all changed sections:**
I'll process all modified, new, and completed sections while preserving unchanged sections.
Ready to analyze sections?</output>
<action>
For each section in (modified_sections + new_sections + completed_sections):
Run 4b-sketch-analysis.md workflow for that section only
Update specification document
Preserve unchanged sections
End
</action>
</check>
---
## STEP 4B: SELECTIVE UPDATE (If user chose B)
<check if="user_choice == 'B'">
<ask>**Which sections should I update?**
[List numbered sections with change type]
Enter numbers separated by commas (e.g., 1,3,5):</ask>
<action>
Parse selected_sections
For each selected section:
Run 4b-sketch-analysis.md workflow for that section
Update specification document
End
</action>
</check>
---
## STEP 4C: DETAILED COMPARISON (If user chose C)
<check if="user_choice == 'C'">
<output>**Detailed Section-by-Section Comparison:**
**See:** [page-process-templates.md](page-process-templates.md) for comparison template
Display for each modified section:
- Current specification summary
- New sketch interpretation
- Detected changes
- Confidence level
After reviewing, what would you like to do?
[A] Update all
[B] Pick specific sections
[C] Cancel</output>
<action>Return to STEP 3 with user's choice</action>
</check>
---
## STEP 5: COMPLETION
<output>✅ **Page specification updated!**
**Summary:**
- [X] sections updated
- [X] sections added
- [X] sections preserved (unchanged)
- [X] sections removed
**Updated file:** `{{page_spec_path}}`
**Sketch saved to:** `{{sketch_path}}`
Would you like to:
[A] Generate HTML prototype
[B] Add another page
[C] Update another section
[D] Done with this page
Choice:</output>
---
## ROUTING
<action>
Based on user choice:
- [A] → Load prototype generation workflow
- [B] → Return to page-init/step-01-page-context.md
- [C] → Return to STEP 3 (pick sections)
- [D] → Return to main UX design menu
</action>
---
## KEY FEATURES
### ✅ **Intelligent Context Detection**
- Automatically knows if new or update
- Compares sketches to existing specs
- Identifies unchanged sections
### ✅ **Incremental Updates**
- Only updates what changed
- Preserves existing work
- No data loss
### ✅ **Flexible Control**
- Update all or select specific
- See detailed comparison
- Cancel anytime
---
## INTEGRATION
This workshop uses:
- **4b-sketch-analysis.md** - For actual section analysis
- **guides/SKETCH-TEXT-ANALYSIS-GUIDE.md** - For reading text markers
- **page-specification.template.md** - For document structure
- **object-types/*.md** - For component specifications
---
**Created:** December 28, 2025
**For:** Iterative page specification workflow
**Status:** Ready to test with WDS Presentation page

653
_bmad/wds/workflows/4-ux-design/data/quality-guide.md Normal file
View File

@@ -0,0 +1,653 @@
# Page Specification Quality Guide
**Purpose:** Reference guide explaining what the Page Specification Quality Workflow checks and why each validation matters.
**Note:** This is a reference document. To execute the workflow, see `workflow.md`.
---
## Overview
The Page Specification Quality Workflow ensures every WDS page specification meets quality standards with complete structure, Object IDs, and traceability. This guide explains each validation check and its importance.
---
## When to Use Quality Workflow
### During Page Creation ✨
Build specifications correctly from the start:
- Creating a new page specification from a sketch
- Converting rough notes into proper spec format
- Building specs incrementally as design evolves
### After Page Updates 🔄
Validate changes maintain standards:
- Updated sketch with new elements
- Content revisions
- Added sections or components
- Design iteration
### Quality Audits 🔍
Check existing specifications:
- Pre-handoff quality check
- Sprint review preparation
- Onboarding new team members
- Fixing legacy specs
---
## Workflow Architecture
The workflow uses **BMAD v6 micro-step architecture** with 8 sequential validation steps:
```
Step 1: Page Metadata
↓
Step 2: Navigation Structure
↓
Step 3: Page Overview
↓
Step 4: Page Sections & Objects
↓
Step 5: Section Order & Structure
↓
Step 6: Object Registry
↓
Step 7: Design System Separation & Unnecessary Information
↓
Step 8: Final Validation
```
**Workflow Philosophy:**
- **Diagnose, don't rewrite** - Identify issues and suggest specific fixes
- **Report findings** - Generate clear, actionable reports for each section
- **Recommend solutions** - Provide examples of correct patterns
- **Let designer decide** - Agent suggests, designer implements (unless asked to fix)
---
## How to Execute Workflow
### For AI Agents (Freya)
Load and execute: `workflow.md`
### For Human Designers
1. Open your page specification
2. Follow the 8 steps sequentially
3. Use the checklists in each step file
4. Generate quality report at Step 8
---
## What This Workflow Checks
### ✅ Step 1: Page Metadata
- Platform declaration present
- Page type specified
- Primary viewport identified
- Interaction model documented
- Navigation context defined
- Inherits from scenario platform strategy
**Why This Matters:**
- Establishes technical context before design decisions
- Ensures platform-appropriate design patterns
- Clarifies device priorities and constraints
- Guides responsive design approach
- Prevents platform-incompatible features
- 📖 **Reference:** [Page Specification Template](../templates/page-specification.template.md)
**Audit Report Example:**
```markdown
🔍 Page Metadata Audit
**Status:** ⚠️ WARNING - Missing platform metadata
**Issues Found:**
1. ❌ No Page Metadata section (should be after page title)
- Missing: Platform, Page Type, Viewport, Interaction Model
- Should add: Complete Page Metadata section
- Why: Developers need platform context before implementation
2. ℹ️ Platform not inherited from scenario
- Check: Does scenario overview define platform strategy?
- Action: Confirm platform strategy in scenario, then add to page
**Recommendation:**
Add Page Metadata section with:
- Platform (from Product Brief/Scenario)
- Page Type (Full Page, Modal, etc.)
- Primary Viewport (Mobile-first, Desktop-first, etc.)
- Interaction Model (Touch, Mouse/keyboard, etc.)
- Navigation Context (Public, Authenticated, etc.)
Would you like me to add the Page Metadata section?
```
### ✅ Step 2: Navigation Structure
- H3 and H1 headers with page numbers
- "Next Step" links before and after sketch
- Embedded sketch image
- Correct relative paths
**Why This Matters:**
- Provides immediate context for where page fits in user journey
- Embedded sketch gives visual reference without leaving document
- Consistent navigation enables automated tooling and cross-linking
- 📖 **Reference:** [step-01-navigation.md](step-01-navigation.md)
### ✅ Step 3: Page Overview
- Page description (1-2 paragraphs)
- User Situation section
- Page Purpose section
- Emotional context and pain points
**Why This Matters:**
- Captures strategic intent (WHY) before implementation details (HOW)
- Connects design decisions to user needs and trigger map
- Provides context for developers and stakeholders
- 📖 **Reference:** [step-02-page-overview.md](step-02-page-overview.md)
### ✅ Step 4: Page Sections
- "## Page Sections" header
- Section Objects (H3) with Purpose
- Component specs (H4) with Object IDs
- Design system links
- Content specifications
- Behavior specifications
**Why This Matters:**
- OBJECT IDs enable traceability from spec → code → Figma
- Component references ensure design system consistency
- Content with language tags prevents "lorem ipsum" in production
- Behavior specs reduce developer guesswork
- 📖 **Reference:** [step-03-page-sections.md](step-03-page-sections.md)
- 📖 **Related:** [Page Specifications Deliverable](../../../docs/deliverables/page-specifications.md)
### ✅ Step 6: Object Registry
- "## Object Registry" header
- Introduction paragraph
- Master Object List tables
- 100% coverage of all Object IDs
- Proper table formatting
**Why This Matters:**
- Single source of truth for all page elements
- Enables automated testing (test by OBJECT ID)
- Facilitates content updates and translations
- Supports Figma export workflows (aria-label mapping)
- 📖 **Reference:** [step-04-object-registry.md](step-04-object-registry.md)
### ✅ Step 5: Section Order & Structure
- Sections appear in standard WDS order
- Required sections are present
- Optional sections are appropriately placed
- No duplicate or redundant sections
**Standard Section Order:**
1. Navigation (H3 + Next Step + Sketch + Next Step + H1)
2. Page description paragraph
3. User Situation
4. Page Purpose
5. Reference Materials
6. Page Sections
7. Page-Specific Layout Notes (optional)
8. Object Registry
**Why This Matters:**
- Consistent structure across all page specifications
- Strategic context (WHY) before implementation (WHAT)
- Easy navigation for developers and stakeholders
- Enables automated tooling and validation
- 📖 **Reference:** [Page Specification Standards](../../../docs/deliverables/page-specifications.md)
**Audit Report Example:**
```markdown
🔍 Section Structure Audit
**Status:** ⚠️ WARNING - Sections out of order
**Issues Found:**
1. ⚠️ "Reference Materials" appears after "Page Sections" (Line 250)
- Should be: Before "Page Sections" (around Line 20)
- Why: Strategic context should come before implementation details
2. ⚠️ Missing "Object Registry" section
- Should be: At end of document
- Why: Required for traceability and automated testing
Would you like me to reorder these sections?
```
### ✅ Step 7: Design System Separation
- NO CSS classes, hex codes, or styling values in page specs
- NO font sizes, padding, margins, or layout measurements
- Component references link to Design System
- Color/typography references use Design System tokens
- Styling details documented in Design System, not page specs
**Why This Matters:**
- Page specs focus on WHAT/WHY (strategic), not HOW (implementation)
- Prevents specifications from becoming outdated when styles change
- Enables design system to be single source of truth for styling
- Reduces specification maintenance burden
- Prevents "reverse-engineering from Figma" anti-pattern
- 📖 **Reference:** [Design System Deliverable](../../../docs/deliverables/design-system.md)
- 📖 **Related:** [Prepare for Figma Export](../../../docs/tools/prepare-for-figma-export.md)
**Common Violations to Check:**
- ❌ CSS class names in component descriptions (`.btn-primary`, `.hero-section`)
- ❌ Color hex codes in content (`#2F1A0C`, `rgb(255, 100, 50)`)
- ❌ Font sizes and weights (`18px Fredoka SemiBold`, `font-size: 2rem`)
- ❌ Spacing values (`padding: 20px`, `margin-bottom: 16px`)
- ❌ Layout measurements (`max-width: 1200px`, `border-radius: 8px`)
- ✅ Component references (`[Button Primary]`, `H1 heading`)
- ✅ Design System links (`See [Color Palette]`, `Uses [Typography System]`)
**Audit Report Example:**
```markdown
## Design System Separation Audit
**Status:** ❌ FAIL - CSS implementation details found in specification
**Critical Issues:**
1. ❌ CSS styling in Hero section (Lines 45-78)
- Found: Font sizes, colors, padding values
- Example: "18px Fredoka SemiBold, #2F1A0C, padding: 20px"
- Should be: Component references and Design System links
- Action: Move to /docs/D-Design-System/03-Components/
2. ❌ Responsive CSS in component descriptions (Lines 120-145)
- Found: Media queries and breakpoint values
- Example: "@media (min-width: 768px) { ... }"
- Should be: High-level layout notes only
- Action: Move to Design System Breakpoints documentation
**Recommendation:**
- Keep: OBJECT IDs, content, behavior, strategic rationale
- Remove: All CSS classes, hex codes, measurements, styling
- Add: Links to Design System components
- Add: "Page-Specific Layout Notes" section for high-level responsive behavior
**Next Steps:**
1. Extract styling to Design System documentation
2. Replace CSS details with component references
3. Add Design System links for colors/typography
4. Keep page-specific layout notes (mobile vs desktop behavior)
Would you like me to help extract these styles to the Design System?
```
### ✅ Step 7 (continued): Unnecessary Information Detection
- NO implementation code snippets (HTML, CSS, JavaScript)
- NO developer instructions or technical setup steps
- NO version control information (commit messages, PR notes)
- NO internal project management notes
- NO duplicate content across sections
- NO outdated/deprecated information
**Why This Matters:**
- Keeps specifications focused on design intent
- Prevents confusion between spec and implementation
- Reduces maintenance burden (less to update)
- Improves readability for all stakeholders
- Separates concerns (design specs vs. developer docs)
**Common Unnecessary Content:**
- ❌ Code examples (`<div class="hero">`, `const handleClick = () => {}`)
- ❌ Build instructions ("Run npm install", "Deploy to staging")
- ❌ Git history ("Added in PR #123", "Fixed by John on 2024-01-15")
- ❌ Internal notes ("TODO: Ask PM about this", "Waiting for approval")
- ❌ Duplicate sketches or redundant descriptions
- ❌ Old design iterations that are no longer relevant
- ✅ OBJECT IDs, content, behavior, strategic rationale
- ✅ Component references and Design System links
- ✅ User context and page purpose
**Audit Report Example:**
```markdown
🔍 Unnecessary Information Audit
**Status:** ⚠️ WARNING - Non-specification content found
**Issues Found:**
1. ⚠️ HTML code snippets in component descriptions (Lines 85-92)
- Found: `<button class="btn-primary">Click me</button>`
- Why problematic: Implementation details, not design intent
- Action: Remove code, keep OBJECT ID and behavior description
2. ⚠️ Developer setup instructions (Lines 200-215)
- Found: "Run npm install, configure .env file..."
- Why problematic: Belongs in developer documentation
- Action: Move to /docs/developer-setup.md or remove
3. ⚠️ Duplicate sketch references (Lines 15, 45, 120)
- Found: Same sketch linked multiple times
- Why problematic: Clutters document, causes confusion
- Action: Keep sketch in navigation section only
4. ℹ️ Old design iteration notes (Lines 300-320)
- Found: "Previous version used blue, changed to green"
- Why problematic: Historical notes not needed in final spec
- Action: Remove or move to design decision log
Would you like me to clean up this unnecessary content?
```
### ✅ Step 8: Final Validation
- Cross-reference all sections
- Verify sketch coverage
- Check for broken links
- Validate naming conventions
- Generate quality report
**Why This Matters:**
- Catches inconsistencies before handoff
- Ensures specification completeness
- Provides confidence for developers
- Documents quality metrics for project tracking
- 📖 **Reference:** [step-05-final-validation.md](step-05-final-validation.md)
---
## Example: Standard WDS Pattern
This workflow ensures all WDS page specifications follow a consistent, high-quality pattern.
**Key Pattern Elements:**
- Clear navigation with scenario context
- Embedded sketch images
- Section Objects with Purpose statements
- Component specs with Object IDs
- Complete Object Registry table
- Design system component links
---
## Output: Quality Report
At the end of Step 5, you'll have:
**Comprehensive Quality Report** including:
- Pass/Fail status for each section
- List of critical issues (must fix) with **specific line numbers**
- List of warnings (should fix) with **examples of violations**
- List of recommendations (nice to have)
- Object ID audit (duplicates, missing, orphans)
- Sketch coverage analysis (missing elements)
- Broken links report
- **Suggested fixes** with before/after examples
- Next actions for handoff
**Report Format Example:**
```markdown
## Navigation Structure Audit
**Status:** ❌ FAIL
**Issues Found:**
1. ❌ Missing H3 header before H1
- Location: Line 1
- Current: `# 1.1 Start Page`
- Should be: `### 1.1 Start Page` (add H3 before H1)
2. ❌ Missing embedded sketch in navigation
- Location: Between lines 3-5
- Should add: `![Start Page Concept](sketches/...)`
**Recommendation:**
Add H3 header and embed sketch between dual "Next Step" links.
See: step-01-navigation.md for correct format.
```
**Report Status Levels:**
- ✅ **READY FOR HANDOFF** - Zero critical issues, ready for dev
- ⚠️ **NEEDS REVISION** - 1-3 critical issues, fixable quickly
- ❌ **INCOMPLETE** - 4+ critical issues, needs substantial work
**Agent Behavior:**
- **Report findings** - Don't automatically fix unless asked
- **Provide line numbers** - Make issues easy to locate
- **Show examples** - Include correct patterns for reference
- **Ask before editing** - "Would you like me to fix these issues?"
- **Offer audit stamp** - "Would you like me to add an audit stamp to the page for handoff tracking?"
---
## Optional: Audit Stamp for Handoff
When a page specification passes all quality checks and is ready for development handoff, the agent can offer to add a brief audit stamp at the bottom of the document.
**When to Add:**
- Page passes all quality checks (✅ READY FOR HANDOFF)
- Designer confirms page is ready for development
- Team wants handoff tracking in the document itself
**When NOT to Add:**
- Page still has critical issues
- Specification is work-in-progress
- Team prefers external audit tracking
**Audit Stamp Format:**
```markdown
---
## Quality Audit
**Status:** ✅ READY FOR HANDOFF
**Audit Date:** 2026-01-21
**Audited By:** Freya (WDS Page Audit Workflow v1.0)
**Compliance:**
- ✅ Navigation Structure (WDS Standard)
- ✅ Page Overview (Strategic Context)
- ✅ Section Order & Structure
- ✅ Object Registry (100% Coverage)
- ✅ Design System Separation
- ✅ No Unnecessary Information
**Notes:** All OBJECT IDs validated, Design System references confirmed, ready for implementation.
```
**Design Log:**
```
🎉 Audit Complete - All Checks Passed!
**Status:** ✅ READY FOR HANDOFF
This page specification meets all WDS quality standards and is ready for development.
Would you like me to add a quality audit stamp at the bottom of the page?
This can be useful for:
- Tracking when the page was validated
- Confirming handoff readiness to developers
- Project documentation and history
[Yes, add audit stamp] [No, keep page clean]
```
**Removing Audit Stamp:**
The audit stamp can be easily removed later if needed (it's always at the bottom of the document). Some teams prefer to remove it after implementation is complete.
---
## Common Use Cases
### Use Case 1: New Page from Sketch
**Scenario:** Designer uploads a new sketch and needs to create specification.
**Process:**
1. Run Step 1: Confirm page metadata from scenario
2. Run Step 2: Generate navigation structure
3. Run Step 3: Define page overview based on trigger map
4. Run Step 4: Analyze sketch, create sections and Object IDs
5. Run Step 5: Validate section order
6. Run Step 6: Auto-generate Object Registry from sections
7. Run Step 7: Check Design System separation
8. Run Step 8: Validate and generate report
**Outcome:** Complete, validated specification ready for handoff.
---
### Use Case 2: Updated Sketch
**Scenario:** Designer updates existing sketch with new elements.
**Process:**
1. Skip to Step 4: Check existing sections
2. Add new sections/objects from updated sketch
3. Run Step 6: Update Object Registry with new IDs
4. Run Step 8: Validate changes and generate report
**Outcome:** Updated specification with change tracking.
---
### Use Case 3: Quality Audit Before Handoff
**Scenario:** Team lead wants to verify spec quality before developer handoff.
**Process:**
1. Run entire workflow in "validation mode"
2. Step 1-7: Check each section against checklists
3. Step 8: Generate comprehensive quality report
4. Share report with team, fix critical issues
5. Re-run Step 8 after fixes
**Outcome:** Confidence in specification completeness.
---
### Use Case 4: Fixing Legacy Spec
**Scenario:** Old specification doesn't follow WDS standards.
**Process:**
1. Run Step 1-4 in "validation mode" to identify gaps
2. Fix missing navigation structure
3. Add missing Object IDs to all interactive elements
4. Create Object Registry if missing
5. Run Step 5 to verify all issues resolved
**Outcome:** Legacy spec brought up to current standards.
---
## Benefits
### For Designers 🎨
- Clear checklist to follow
- Confidence nothing is missed
- Professional, consistent output
- Easy communication with developers
### For Developers 💻
- Complete, trustworthy specifications
- All interactive elements have Object IDs
- Clear implementation order (top to bottom)
- Easy to test (Object IDs as test targets)
### For Teams 👥
- Shared quality standards
- Consistent specification format
- Easy onboarding for new members
- Reduced back-and-forth during handoff
### For Project Management 📊
- Clear completion criteria
- Quality metrics tracking
- Reduced rework
- Faster handoffs
---
## Integration with WDS Workflows
This quality workflow integrates with:
**Before:**
- [Page Init Workflow](../steps-s/ and ../data/page-creation-flows/) - Creates initial page structure
- [Sketch Analysis](../steps-k/step-01-sketch-analysis.md) - Identifies page elements
**After:**
- [Agentic Development](../../5-agentic-development/) - Builds HTML demos from specs
- [Handover](../steps-h/) - Packages specs for handoff
- [Platform Requirements](../../../1-project-brief/steps-c/ (steps 27-32)) - Technical boundaries from specs
---
## Tips for Success
### Do:
- ✅ Run the workflow every time you create or update a page
- ✅ Use checklists systematically (don't skip items)
- ✅ Fix critical issues before proceeding to next step
- ✅ Save quality reports for project history
- ✅ Track metrics over time to improve process
### Don't:
- ❌ Skip steps (each builds on the previous)
- ❌ Ignore warnings (they become critical issues later)
- ❌ Rush through validation (thoroughness matters)
- ❌ Mix validation with creation (separate concerns)
- ❌ Forget to re-validate after fixes
---
## Customization
### For Your Project
You can customize this workflow by:
**Adjusting Standards:**
- Modify Object ID naming conventions
- Add project-specific sections
- Extend validation checklists
- Add custom quality metrics
**Adding Steps:**
- Step 3.5: Accessibility audit
- Step 4.5: Content strategy review
- Step 5.5: Stakeholder approval
**Location:**
Customizations should be documented in:
`/examples/[PROJECT]/docs/quality-standards.md`
---
## Support
### Questions or Issues?
**Documentation:**
- [WDS Specification Pattern](../guides/WDS-SPECIFICATION-PATTERN.md)
- [Object Types](../object-types/)
- [Component File Structure](../modular-architecture/COMPONENT-FILE-STRUCTURE.md)
**Examples:**
- See fictional TaskFlow examples in workflow steps
- Check existing WDS project specifications for real-world patterns
**Contact:**
- File issues in project repo
- Discuss in team channel
- Reference this workflow in PRs
---
## Version History
**v1.0.0** - 2025-12-28
- Initial release
- Pattern extracted from successful WDS projects
- 6-step sequential workflow
- Quality report generation
---
**Start the workflow:** [workflow.md](workflow.md)

167
_bmad/wds/workflows/4-ux-design/data/scenario-init/01-platform-confirmation.md Normal file
View File

@@ -0,0 +1,167 @@
# Step 0A: Confirm Platform Strategy for Scenario
**Inherit from Product Brief, confirm for this scenario**
---
## Purpose
Before starting scenario design, confirm that the platform strategy from the Product Brief applies to this scenario, or identify if this scenario requires different platform considerations.
## Context for Agent
The Product Brief defines the overall platform strategy for the product. However, some scenarios might have different platform requirements. For example:
- Onboarding might be web-only while daily use is mobile app
- Admin features might be desktop-only while customer features are mobile
- Some scenarios might span multiple platforms (start on web, continue on mobile)
## Instructions
### 1. Load Platform Strategy from Product Brief
<action>
Read the Product Brief and extract the Platform & Device Strategy section:
- primary_platform
- supported_devices
- device_priority
- interaction_models
- offline_requirements
- native_features_needed
</action>
### 2. Present Platform Strategy
<output>
**Platform Strategy from Product Brief:**
**Primary Platform:** {primary_platform}
**Supported Devices:** {supported_devices}
**Device Priority:** {device_priority}
**Interaction Models:** {interaction_models}
---
**For this scenario: {scenario_name}**
Does this platform strategy apply to this entire scenario, or does this scenario have specific platform requirements?
</output>
### 3. Ask Scenario-Specific Platform Questions
<ask>
**Scenario Platform Questions:**
1. **Does this scenario use the same platform as the Product Brief?**
- Yes, same platform strategy applies
- No, this scenario has different platform requirements
- Partially, this scenario spans multiple platforms
2. **If different or spanning platforms:**
- Which platforms are involved in this scenario?
- How does the user move between platforms?
- What is the primary platform for this scenario?
3. **Are there scenario-specific device considerations?**
- Does this scenario prioritize different devices?
- Are there device-specific features in this scenario?
- Any device limitations for this scenario?
4. **Page type expectations for this scenario:**
- Full pages (standard navigation flow)
- Modal dialogs (overlays, popups)
- Embedded components (widgets, iframes)
- System notifications (email, SMS, push)
- Mixed (specify which pages are which type)
Your answers:
</ask>
### 4. Document Scenario Platform Strategy
<action>
Create or update scenario overview document with platform information:
```markdown
# Scenario {number}: {scenario_name}
## Scenario Platform Strategy
**Inherits From:** Product Brief Platform Strategy
**Platform Alignment:** {same/different/spanning}
### Platform Details for This Scenario
**Primary Platform:** {platform for this scenario}
**Devices Used:** {devices in this scenario}
**Device Priority:** {device priority for this scenario}
**Cross-Platform Flow (if applicable):**
{describe how user moves between platforms in this scenario}
**Page Types in This Scenario:**
- {Page 1}: Full page (responsive web)
- {Page 2}: Modal dialog (overlay)
- {Page 3}: Email template
- etc.
**Scenario-Specific Considerations:**
{any unique platform requirements or constraints for this scenario}
---
```
</action>
### 5. Confirm Understanding
<output>
**Scenario Platform Summary:**
This scenario will be designed for:
- **Platform:** {platform}
- **Primary Device:** {device}
- **Page Types:** {types}
All pages in this scenario will inherit this platform context, ensuring consistent design decisions.
Ready to proceed with scenario initialization?
</output>
<ask>
**Confirm scenario platform strategy:**
- [C] Continue - platform strategy is clear
- [R] Revise - need to adjust platform for this scenario
- [D] Discuss - have questions about platform implications
</ask>
## Next Step
After confirming platform strategy, proceed to 01-feature-selection.md
## State Update
Store scenario platform information for reference during page specification:
```yaml
scenario_platform:
inherits_from: 'product_brief'
alignment: '{same/different/spanning}'
primary_platform: '{platform}'
devices_used: '{devices}'
device_priority: '{priority}'
page_types: '{types}'
cross_platform_flow: '{flow if applicable}'
```
---
**Why This Matters:**
Platform context affects every design decision:
- **Layout:** Mobile-first vs desktop-first
- **Navigation:** Touch gestures vs mouse clicks
- **Interactions:** Native patterns vs web patterns
- **Content:** Concise for mobile vs detailed for desktop
- **Features:** What's possible on each platform
Confirming this upfront ensures all scenario pages are designed consistently for the right platform.

70
_bmad/wds/workflows/4-ux-design/data/scenario-init/02-feature-selection.md Normal file
View File

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

67
_bmad/wds/workflows/4-ux-design/data/scenario-init/03-entry-point.md Normal file
View File

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

74
_bmad/wds/workflows/4-ux-design/data/scenario-init/04-mental-state.md Normal file
View File

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

69
_bmad/wds/workflows/4-ux-design/data/scenario-init/05-mutual-success.md Normal file
View File

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

92
_bmad/wds/workflows/4-ux-design/data/scenario-init/06-shortest-path.md Normal file
View File

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

80
_bmad/wds/workflows/4-ux-design/data/scenario-init/07-reference-trigger-map.md Normal file
View File

@@ -0,0 +1,80 @@
# 7. Reference Trigger Map for Scenario
**Purpose:** Identify the relevant Trigger Map nodes for this scenario before sketching
---
## Why Now?
You've defined:
- Feature that delivers value
- Entry point
- Mental state
- Mutual success
- Shortest path
**Perfect time to anchor the scenario to the Trigger Map.** Pick the specific business goal, persona, and driving forces that apply to this scenario.
---
## Agent Instructions
> "Before we start sketching, let's identify the Trigger Map context for this scenario.
>
> From your Trigger Map, which of these apply to this scenario?
> - **Business Goal** — which goal does this scenario serve?
> - **User** — which persona is this scenario for?
> - **Driving Forces** — which positive and negative drivers are most relevant?
>
> This anchors every design decision to strategy."
---
## Process
1. **Load the Trigger Map** from `{output_folder}/B-Trigger-Map/00-trigger-map.md`
2. **Present the business goals** — ask which one this scenario primarily serves
3. **Present the personas** — confirm which persona this scenario targets
4. **Present driving forces** for that persona — ask which 2-4 are most relevant here
5. **Summarize** the selected context
This is a **selection exercise**, not a workshop. It takes 2-3 minutes.
---
## Save Context
Note the selected Trigger Map context in the scenario overview file:
```markdown
## Trigger Map Context
**Business Goal:** [selected goal from Trigger Map]
**Persona:** [selected persona]
**Key Driving Forces:**
- Positive: [selected positive drivers]
- Negative: [selected negative drivers]
```
---
## If No Trigger Map Exists
If the Trigger Map hasn't been created yet:
- Inform the user: "There's no Trigger Map for this project yet. I'd recommend completing Phase 2 (Trigger Mapping) first — it gives us the strategic foundation for design decisions."
- If the user wants to proceed anyway, use whatever business context is available from the Product Brief and note the gap.
---
## Next Step
**Start sketching the scenario journey!**
Each sketch should:
- Serve the selected driving forces
- Support the shortest path to mutual success
- Address the target persona's needs
---
*Strategic context identified — now sketch with purpose!*

64
_bmad/wds/workflows/4-ux-design/data/scenario-init/examples/booking-example.md Normal file
View File

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

64
_bmad/wds/workflows/4-ux-design/data/scenario-init/examples/ecommerce-example.md Normal file
View File

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

64
_bmad/wds/workflows/4-ux-design/data/scenario-init/examples/saas-example.md Normal file
View File

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

536
_bmad/wds/workflows/4-ux-design/data/scenario-init/scenario-init-dialog.md Normal file
View File

@@ -0,0 +1,536 @@
# Scenario Initialization Dialog
**Agent**: Freya WDS Designer Agent
**Purpose**: Define a complete user scenario before creating page specifications or prototypes
**Output**: `[Scenario-Number]-[Scenario-Name].md` (scenario specification)
---
## 🎯 **When to Use This Workflow**
**Use when**:
- Starting a new user journey/scenario
- No scenario specification exists yet
- Need to define what pages belong in this scenario
**Skip when**:
- Scenario specification already exists
- Just adding one new page to existing scenario
---
## 🤝 **Collaboration Approach**
**Freya contributes both**:
- **Business perspective** (goals, metrics, value)
- **UX perspective** (flow, interactions, usability)
---
## 📝 **The Dialog**
### **Step 1: Scenario Overview**
> "**Let's define this user scenario together!**
>
> **What is the high-level purpose of this scenario?**
>
> In one sentence, what is the user trying to accomplish?"
**Wait for response**
**Example**: "Family members coordinate who walks the dog each day"
**Record**:
- `scenario.overview`
---
### **Step 2: User Context**
> "**Who is the user and what's their situation?**
>
> Tell me about:
> - Who is the primary user? (role, characteristics)
> - What's their context? (where are they, what's happening)
> - What triggered them to start this journey?"
**Wait for response**
**Example**:
- User: Family member (parent or child)
- Context: Planning the upcoming week, needs to coordinate dog care
- Trigger: New week starting, family needs to divide dog walking responsibilities
**Record**:
- `scenario.user_context`
- `scenario.trigger_points`
---
### **Step 2b: Link to Trigger Map** (if Trigger Map exists)
**Check**: Does `docs/B-Trigger-Map/` folder exist?
**If YES**:
> "**I see you have a Trigger Map defined!**
>
> **Which trigger(s) from your Trigger Map does this scenario address?**
>
> [Agent reads Trigger Map and lists triggers]
>
> Available triggers:
> - [Trigger ID] [Trigger name]
> - [Trigger ID] [Trigger name]
> ...
>
> **Which trigger(s) does this scenario solve?** (list IDs or 'none')"
**Wait for response**
**Example**:
- TM-03: "Dog forgotten at home all day"
- TM-07: "Family arguments about who's not pulling their weight"
- TM-12: "Kids not taking responsibility for pet care"
**Record**:
- `scenario.trigger_map_links` (array of trigger IDs)
**If NO Trigger Map**: Skip this step
---
### **Step 3: User Goals**
> "**What are the user's specific goals?**
>
> List 2-5 concrete goals they want to achieve."
**Wait for response**
**Example**:
1. See who has walked the dog this week
2. Book a time slot to walk the dog
3. Track their contributions vs. other family members
4. Get reminded when it's their turn
**Record**:
- `scenario.user_goals` (array)
---
### **Step 4: User Value & Fears**
> "**How will completing this scenario add value to the user?**
>
> **Positive Goals** (what they want to achieve):
> - [Suggest 3-5 positive goals based on scenario]
>
> **Fears to Avoid** (what they want to prevent):
> - [Suggest 3-5 fears/concerns based on scenario]
>
> **Does this match their motivations? Any adjustments?**"
**Wait for response**
**Example**:
**Positive Goals**:
- Feel organized and in control of dog care
- Contribute fairly without being nagged
- See appreciation for their efforts
- Spend quality time with the dog
- Maintain family harmony
**Fears to Avoid**:
- Dog being neglected or forgotten
- Unfair distribution of responsibilities
- Family conflict over who's doing more
- Being blamed for missed walks
- Feeling guilty about not contributing
**Record**:
- `scenario.user_positive_goals` (array)
- `scenario.user_fears` (array)
---
### **Step 5: Success Criteria**
> "**How do we know the user succeeded?**
>
> What does success look like? What metrics matter?"
**Wait for response**
**Example**:
- User successfully books a walk
- Family coordination is visible
- Dog gets walked regularly (all slots filled)
- Fair distribution of responsibilities
**Record**:
- `scenario.success_criteria` (array)
---
### **Step 5: Entry Points**
> "**How does the user enter this scenario?**
>
> Where are they coming from? What actions lead them here?"
**Wait for response**
**Example**:
- From home dashboard ("Dog Calendar" tab)
- From notification ("Your turn to walk Rufus!")
- From family chat ("Who's walking the dog?")
**Record**:
- `scenario.entry_points` (array)
---
### **Step 6: Exit Points**
> "**Where does the user go after completing this scenario?**
>
> What are the natural next steps?"
**Wait for response**
**Example**:
- Back to home dashboard
- To dog health tracking (after walk completed)
- To family leaderboard (check standings)
- Exit app (done for now)
**Record**:
- `scenario.exit_points` (array)
---
### **Step 7: Pages in Scenario**
> "**Let's map out the pages needed for this journey.**
>
> I'll suggest pages based on the goals, you can adjust.
>
> **Proposed pages**:
> 1. [Page number] [Page name] - [Purpose]
> 2. [Page number] [Page name] - [Purpose]
> ...
>
> **Does this flow make sense? Any pages to add/remove/change?**"
**Wait for response**
**Example**:
1. 3.1 Dog Calendar Booking - View week, book walks, see family contributions
2. 3.2 Walk In Progress - Start/complete walk with timer
3. 3.3 Walk Summary - Review completed walk, add notes
**Record**:
- `scenario.pages` (array with page_number, page_name, purpose, sequence)
---
### **Step 8: Key Interactions**
> "**What are the critical moments in this journey?**
>
> What interactions are most important to get right?"
**Wait for response**
**Example**:
- Viewing available time slots (must be clear and fast)
- Booking a walk (must be instant feedback)
- Seeing real-time updates (when someone else books)
- Starting a walk (clear transition, timer visible)
**Record**:
- `scenario.key_interactions` (array)
---
### **Step 9: Edge Cases & Challenges**
> "**What could go wrong? What edge cases should we handle?**"
**Wait for response**
**Example**:
- Someone books same slot simultaneously
- User tries to book when dog already out walking
- No one has booked upcoming slots (motivation needed)
- Child vs. parent permissions (can child edit others' bookings?)
**Record**:
- `scenario.edge_cases` (array)
---
### **Step 10: Business Value** (Freya's focus)
> "**Freya, what's the business value of this scenario?**
>
> **How will users completing this scenario add value to business goals?**
>
> I'll suggest based on what we've discussed:
>
> **Suggested Business Value**:
> - [Value 1]
> - [Value 2]
> - [Value 3]
>
> **Metrics to track**:
> - [Metric 1]
> - [Metric 2]
> - [Metric 3]
>
> **Does this align with business goals? Any adjustments?**"
**Wait for response**
**Example**:
**Business Value**:
- Increases family engagement (active users per family)
- Reduces pet neglect (walks completed per week)
- Demonstrates app value (feature usage = retention)
- Drives word-of-mouth (families share success)
- Premium feature potential (leaderboard, insights)
**Metrics**:
- Walks booked vs. completed ratio
- Family participation rate (% of members active)
- Daily active users
- Feature retention (return rate)
- NPS increase
**Record**:
- `scenario.business_value`
- `scenario.metrics` (array)
---
### **Step 11: UX Priorities** (Freya's focus)
> "**Freya, what are the top UX priorities for this scenario?**
>
> What must we get right for great user experience?"
**Wait for response**
**Example**:
- Speed: Calendar loads instantly
- Clarity: Week view shows all info at a glance
- Feedback: Booking feels immediate and satisfying
- Gamification: Leaderboard motivates participation
- Mobile-first: Easy to book on-the-go
**Record**:
- `scenario.ux_priorities` (array)
---
## ✅ **Step 12: Create Scenario Specification**
**Agent creates**: `docs/C-UX-Scenarios/[Number]-[Name]/[Number]-[Name].md`
**File structure**:
```markdown
# [Scenario Number]: [Scenario Name]
## Overview
[One sentence purpose]
## User Context
**Who**: [Primary user role/characteristics]
**Context**: [Situation/environment]
**Trigger**: [What prompted this journey]
## Trigger Map Links
**Addresses these pain points**:
- [Trigger ID] [Trigger name from Trigger Map]
- [Trigger ID] [Trigger name from Trigger Map]
...
_(If no Trigger Map exists, omit this section)_
## User Goals
1. [Goal 1]
2. [Goal 2]
...
## User Value & Fears
### Positive Goals (What Users Want)
- [Positive goal 1]
- [Positive goal 2]
...
### Fears to Avoid (What Users Want to Prevent)
- [Fear 1]
- [Fear 2]
...
## Success Criteria
- [Criterion 1]
- [Criterion 2]
...
## Entry Points
- [Entry point 1]
- [Entry point 2]
...
## Exit Points
- [Exit point 1]
- [Exit point 2]
...
## Pages in This Scenario
### [Page Number] [Page Name]
**Purpose**: [Why this page exists]
**Sequence**: [When it appears in journey]
**Key Actions**: [What user does here]
[Repeat for each page...]
## Key Interactions
- [Interaction 1]
- [Interaction 2]
...
## Edge Cases
- [Edge case 1]
- [Edge case 2]
...
## Business Value
[Why this matters]
**Metrics**:
- [Metric 1]
- [Metric 2]
...
## UX Priorities
1. [Priority 1]
2. [Priority 2]
...
## Notes
[Any additional context]
---
**Status**: Defined
**Created by**: [Agent name]
**Date**: [Date]
```
---
## 🎉 **Step 13: Completion**
> "✅ **Scenario specification created!**
>
> **File**: `docs/C-UX-Scenarios/[Number]-[Name]/[Number]-[Name].md`
>
> **Next steps**:
> 1. **Update Trigger Map** (add link to this scenario from triggers)
> 2. **Create page specifications** (for each page in scenario)
> 3. **Create interactive prototypes** (if needed)
> 4. **Validate with stakeholders** (review scenario flow)
>
> **Would you like to**:
> - Update the Trigger Map with this scenario link?
> - Start defining page specifications?
> - Create prototypes?
> - Review the scenario doc?"
**If user wants to update Trigger Map**:
**Actions**:
1. Read `docs/B-Trigger-Map/[Trigger-Map-File].md` for each linked trigger
2. Add scenario link to each trigger's "How We Address This" or "Related Scenarios" section:
```markdown
**Addressed in**: [Scenario 03: Booking Dog Walks](../C-UX-Scenarios/03-Booking-Dog-Walks/03-Booking-Dog-Walks.md)
```
3. Confirm updates complete
---
## 📋 **Example Complete Exchange**
**User**: "I want to create a scenario for booking dog walks"
**Freya**: "Great! Let's define this together. What's the high-level purpose?"
**User**: "Family members coordinate who walks the dog each day"
**Freya**: "Perfect! Who is the primary user and what's their context?"
**User**: "Any family member - parent or child - planning the week ahead"
**Freya**: "What are their specific goals?"
**User**: "See who walked the dog, book a time slot, track contributions, get fair distribution"
**Freya**: "How do we know they succeeded?"
**User**: "They book a walk, see it confirmed, family coordination is visible"
[Dialog continues through all questions...]
**Freya**: "✅ Scenario specification created! Ready to create page specs?"
---
## 💡 **Tips for Both Agents**
**Business perspective focus**:
- Business goals and metrics
- Value to users and business
- Priority and scope
- Success measurement
**Freya focuses on**:
- User experience flow
- Key interactions
- Visual journey
- Usability and delight
**Both contribute to**:
- Complete scenario understanding
- Page identification and sequencing
- Edge case identification
- Overall quality
- Linking scenarios back to Trigger Map (traceability)
---
## 🔗 **Trigger Map Integration**
**Why link scenarios to triggers?**:
- ✅ **Traceability**: See which pain points are addressed
- ✅ **Coverage**: Identify triggers not yet solved
- ✅ **Validation**: Ensure solutions match problems
- ✅ **Stakeholder clarity**: Show how software solves real problems
- ✅ **Prioritization**: Focus on high-impact triggers first
**Bidirectional linking**:
- **In Trigger Map**: "Addressed in Scenario X"
- **In Scenario**: "Solves Trigger Y, Z from Trigger Map"
**This creates a complete story**: Problem → Solution → Implementation
---
**This dialog should take 10-15 minutes and result in a complete scenario specification!** 🎯

76
_bmad/wds/workflows/4-ux-design/data/scenario-init/scenario-init-guide.md Normal file
View File

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

221
_bmad/wds/workflows/4-ux-design/data/scenario-init/scenario-init-process.md Normal file
View File

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

722
_bmad/wds/workflows/4-ux-design/data/specification-audit-workflow.md Normal file
View File

@@ -0,0 +1,722 @@
# Specification Audit Workflow
**Phase:** 4 - UX Design
**Agent:** Freya (WDS Designer)
**Purpose:** Systematically validate page and scenario specifications for completeness, consistency, and quality
---
## When to Use This Workflow
**Triggers:**
- Before handoff to development (Phase 4 [H] Handover)
- After completing scenario specifications
- When reviewing existing specifications
- Quality gate before prototype creation
- On-demand specification review
---
## Audit Levels
### Quick Audit (15-30 minutes)
Essential checks only - use for rapid validation during active design work.
### Standard Audit (1-2 hours)
Comprehensive review - use before development handoff.
### Complete Audit (2-4 hours)
Full validation including visual-spec alignment - use for critical pages or final quality gate.
---
## Audit Structure
The audit follows a hierarchical approach from formatting → scenario → page → component → content.
### Level 0: Specification Formatting & Standards
**WDS Formatting Compliance**
### Level 1: Scenario-Level Audit
**Strategic Foundation**
### Level 2: Page-Level Audit
**Structure & Organization**
### Level 3: Component-Level Audit
**Componentization & Design System**
### Level 4: Feature-Level Audit
**Shared Functionality**
### Level 5: Content Audit
**Text & Accessibility Content**
---
## Level 0: Specification Formatting & Standards
**Purpose:** Validate specification follows WDS formatting conventions and standards
### Checklist
**Markdown Structure:**
- [ ] Proper heading hierarchy (H1 → H2 → H3 → H4, no skipped levels)
- [ ] Only one H1 per page (page title)
- [ ] H2 for major sections
- [ ] H3 for subsections
- [ ] H4 for component details
**Area Label Format:**
- [ ] Format: `**AREA LABEL**: `{label}`` (bold, all caps, backticks)
- [ ] Naming convention: `{page}-{section}-{element}` (lowercase, hyphens)
- [ ] Consistent throughout specification
**Translation Format:**
- [ ] Each language on separate line
- [ ] Format: `- {LANG}: "{content}"`
- [ ] All product languages present for each content item
- [ ] Consistent language order throughout spec
- [ ] No inline translations (e.g., "Text (EN), Text (SE)")
**List Formatting:**
- [ ] Use `-` for unordered lists (not `*` or `+`)
- [ ] Consistent indentation (2 spaces per level)
- [ ] Proper spacing (blank line before/after lists)
- [ ] No unnecessary blank lines between items
**Code Blocks:**
- [ ] Language specified for syntax highlighting
- [ ] Triple backticks used
- [ ] Proper indentation
**Section Organization:**
- [ ] Sections in standard order (per template)
- [ ] No missing required sections
- [ ] No duplicate sections
- [ ] Logical flow maintained
- [ ] **Open Questions section present** (even if empty)
**Spacing & Formatting:**
- [ ] Consistent spacing between sections
- [ ] Proper use of bold for field labels
- [ ] No excessive blank lines
- [ ] Consistent indentation throughout
**Links:**
- [ ] Descriptive link text (not "here" or "click here")
- [ ] Valid relative paths for internal links
- [ ] Proper markdown format: `[Text](path)`
**File Naming:**
- [ ] Follows WDS naming conventions
- [ ] No generic names (README.md, GUIDE.md)
- [ ] Descriptive and specific
### Common Formatting Violations
**Inline Translations:**
```markdown
❌ **Content:** "Sign In" (EN), "Logga In" (SE)
✅ **Content:**
- EN: "Sign In"
- SE: "Logga In"
```
**Inconsistent Area Label Format:**
```markdown
❌ Area Label: signin-form-email
❌ **area-label**: `signin-form-email`
✅ **AREA LABEL**: `signin-form-email`
```
**Skipped Heading Levels:**
```markdown
❌ # Page Title
#### Component
✅ # Page Title
## Section
### Subsection
#### Component
```
**Missing Translations:**
```markdown
❌ **Content:**
- EN: "Submit"
(Missing SE)
✅ **Content:**
- EN: "Submit"
- SE: "Skicka"
```
### Navigation Best Practice
**Navigation Placement (Required for Long Specs):**
Long specifications must have navigation links in THREE locations so users can navigate without scrolling:
```markdown
✅ Above the sketch:
**Previous Step:** ← [3.1 Page Name](path)
**Next Step:** → [3.3 Page Name](path)
![Page Sketch](Sketches/page-sketch.jpg)
✅ Below the sketch (still in header area):
**Previous Step:** ← [3.1 Page Name](path)
**Next Step:** → [3.3 Page Name](path)
... specification content ...
✅ Bottom of document:
**Previous Step:** ← [3.1 Page Name](path)
**Next Step:** → [3.3 Page Name](path)
```
This is especially important for storyboards and multi-state specifications where sketches and content can be very long.
### Output
- List of formatting violations by type
- Specific line numbers or sections with issues
- Recommendations for corrections
- Severity (Critical/Warning/Suggestion)
**Reference:** `../../workflows/00-system/SPECIFICATION-FORMATTING-STANDARDS.md`
---
## Level 1: Scenario-Level Audit
**Purpose:** Validate strategic foundation and navigation flow
### Checklist
**Strategic Foundation**
- [ ] User situation clearly defined
- [ ] Usage context documented
- [ ] Strategic context (Trigger Map) defined and linked
- [ ] Scenario purpose stated
- [ ] Success criteria defined
**Navigation Flow**
- [ ] All pages in scenario identified
- [ ] Entry points documented for each page
- [ ] Exit points documented for each page
- [ ] User can navigate through all pages
- [ ] Navigation paths logical and complete
- [ ] Dead ends identified and resolved
**Scenario Overview**
- [ ] Scenario overview file exists
- [ ] Overview describes user journey
- [ ] Page sequence makes sense
- [ ] Links to all page specifications work
### Output
- List of missing strategic elements
- Navigation flow gaps
- Broken links or missing pages
---
## Level 2: Page-Level Audit
**Purpose:** Validate page structure, organization, and visual alignment
### A. Template Check
**Determine which template applies:**
- [ ] Single sketch → uses page-specification.template.md
- [ ] Multiple sketches → uses storyboard extension
- [ ] If storyboard: State Flow Overview present with ASCII diagram
- [ ] If storyboard: State 1 fully documented as baseline
- [ ] If storyboard: States 2+ document only changes
### B. Structure & Organization
**Checklist:**
- [ ] Page purpose clearly stated
- [ ] Success criteria defined
- [ ] Trigger Map reference present
- [ ] Sections properly separated and named
- [ ] Section purposes defined
- [ ] Page layout logical and flows well
- [ ] Layout structure diagram present
- [ ] Navigation present (Previous/Next links: above sketch, below sketch, and at document bottom)
**Structural Area Labels:**
- [ ] Page container (`{page-name}-page`)
- [ ] Header section (`{page-name}-header`)
- [ ] Main content area (`{page-name}-main`)
- [ ] Form container if applicable (`{page-name}-form`)
- [ ] Section containers (`{page-name}-{section}-section`)
- [ ] Section header bars if visible (`{page-name}-{section}-header-bar`)
### C. Visual-Spec Alignment
**Checklist:**
- [ ] Sketch/visualization exists in Sketches/ folder
- [ ] Sketch linked in specification
- [ ] All objects in sketch documented in spec
- [ ] All objects in spec visible in sketch
- [ ] Visual hierarchy matches spec structure
- [ ] Component placement matches sketch
**Gap Analysis:**
- Objects in sketch but missing from spec → Add to spec
- Objects in spec but missing from sketch → Update sketch or remove from spec
- Visual elements don't match description → Align sketch and spec
### D. Area Label Coverage
**Checklist:**
- [ ] All interactive elements have Area Labels (OBJECT IDs)
- [ ] Labels follow naming convention (`{page}-{section}-{element}`)
- [ ] Labels are unique within page
- [ ] ARIA labels match Area Labels
- [ ] Labels support html.to.design layer naming
### Output
- Structure issues list
- Visual-spec misalignment report
- Missing Area Labels list
- Recommendations for fixes
---
## Level 3: Component-Level Audit
**Purpose:** Validate componentization and design system integration
### A. Componentization
**Checklist:**
- [ ] Reusable sections identified (header, footer, navigation)
- [ ] Components properly separated from page specs
- [ ] Component specifications exist
- [ ] Component references valid and linked
- [ ] Shared patterns documented
**Common Reusable Components:**
- Navigation header
- Footer
- Form fields (inputs, selects, textareas)
- Buttons (primary, secondary, tertiary)
- Cards
- Modals/dialogs
- Error messages
- Loading indicators
### B. Cross-Page Duplicate Detection
**Purpose:** Compare sections across all pages in the scenario and flag identical or near-identical content that should be shared components.
**Process:**
1. Collect all section definitions from completed page specs in the scenario
2. Compare sections by structure (heading patterns, object types, layout)
3. Flag matches:
- **Exact duplicate** — identical section structure and content across 2+ pages (e.g., navigation header, footer)
- **Near duplicate** — same structure with minor content differences (e.g., hero sections with different text but identical layout)
- **Repeated pattern** — same object types appearing in multiple pages (e.g., card grids, form fields)
**Checklist:**
- [ ] All completed pages in scenario scanned
- [ ] Exact duplicates flagged with source pages listed
- [ ] Near duplicates flagged with diff summary
- [ ] Repeated patterns identified
- [ ] Extraction recommendation for each finding (extract / leave as-is / parameterize)
**Severity:**
- **Critical** — Exact duplicate in 3+ pages (must extract)
- **Warning** — Exact duplicate in 2 pages or near duplicate in 3+ (should extract)
- **Suggestion** — Repeated pattern (consider extracting)
### C. Design System Integration (if enabled)
**Checklist:**
- [ ] All components added to design system
- [ ] Components at proper hierarchy level:
- Atomic: Buttons, inputs, icons, labels
- Molecular: Form fields, cards, list items
- Organism: Headers, forms, sections
- [ ] Design tokens applied (colors, spacing, typography)
- [ ] Figma components linked
- [ ] Component variants documented
### Output
- Cross-page duplicate report (from B)
- List of components needing extraction
- Design system gaps
- Component hierarchy recommendations
---
## Level 4: Feature-Level Audit
**Purpose:** Validate shared functionality is properly extracted
### Checklist
**Shared Features:**
- [ ] Common features identified (e.g., image upload, validation)
- [ ] Feature files created and documented
- [ ] Feature references consistent across pages
- [ ] Validation rules centralized
- [ ] Error handling standardized
**Common Shared Features:**
- Image upload/cropping
- Form validation
- Authentication flows
- Payment processing
- Search functionality
- Filtering/sorting
- Pagination
- Date/time selection
### Output
- List of features needing extraction
- Feature documentation gaps
- Inconsistencies across pages
---
## Level 5: Content Audit
**Purpose:** Validate all content is defined and accessible
### A. Text Content
**Checklist:**
- [ ] **All Text Defined** - No placeholder content?
- [ ] **Error Messages** - All error states have messages in all languages?
- [ ] **Success Messages** - Confirmation messages defined?
- [ ] **Empty States** - Messages for no-data scenarios?
- [ ] **Loading States** - Loading indicators and messages?
- [ ] **Meta Content** - Page title and meta description for public pages?
- [ ] **Social Sharing** - Social media title, description, and image for public pages?
- [ ] Field labels present and clear
- [ ] Button text defined and action-oriented
- [ ] Help text/tooltips documented
### B. Accessibility Content
**Checklist:**
**ARIA Labels:**
- [ ] All interactive elements have aria-label attributes
- [ ] ARIA labels descriptive and meaningful
- [ ] ARIA labels match Area Labels
**Images:**
- [ ] All images have alt text specified
- [ ] Alt text descriptive (not just filename)
- [ ] Decorative images marked as such (alt="")
**Forms:**
- [ ] All inputs have associated labels (visible or aria-label)
- [ ] Required fields marked with aria-required
- [ ] Field instructions associated with aria-describedby
- [ ] Error messages announced to screen readers
**Keyboard Navigation:**
- [ ] Tab order documented
- [ ] Focus management specified
- [ ] Keyboard shortcuts documented (if any)
- [ ] Skip links present
**Screen Reader Support:**
- [ ] Semantic HTML specified (header, main, nav, section)
- [ ] Heading hierarchy logical (H1 → H2 → H3)
- [ ] ARIA live regions for dynamic content
- [ ] Loading states announced
**Visual Accessibility:**
- [ ] Color contrast meets WCAG AA (4.5:1 for text)
- [ ] Information not conveyed by color alone
- [ ] Focus indicators visible (3:1 contrast)
- [ ] Text readable at 200% zoom
**WCAG Compliance:**
- [ ] Target compliance level documented (AA/AAA)
- [ ] Known accessibility issues documented
- [ ] Testing approach specified
### Output
- Missing content list
- Accessibility gaps
- WCAG compliance issues
- Recommendations for fixes
---
## Audit Report Template
```markdown
# Specification Audit Report
**Date:** {YYYY-MM-DD}
**Auditor:** {Name}
**Scope:** {Scenario/Page name}
**Audit Level:** {Quick/Standard/Complete}
---
## Executive Summary
**Overall Status:** {Pass/Pass with Issues/Fail}
**Critical Issues:** {count}
**Warnings:** {count}
**Suggestions:** {count}
---
## Level 1: Scenario-Level Findings
### Strategic Foundation
- ✅ Pass / ⚠️ Warning / ❌ Fail
- Issues: {list}
### Navigation Flow
- ✅ Pass / ⚠️ Warning / ❌ Fail
- Issues: {list}
---
## Level 2: Page-Level Findings
### Structure & Organization
- ✅ Pass / ⚠️ Warning / ❌ Fail
- Issues: {list}
### Visual-Spec Alignment
- ✅ Pass / ⚠️ Warning / ❌ Fail
- Misalignments: {list}
### Area Label Coverage
- ✅ Pass / ⚠️ Warning / ❌ Fail
- Missing Labels: {list}
---
## Level 3: Component-Level Findings
### Componentization
- ✅ Pass / ⚠️ Warning / ❌ Fail
- Issues: {list}
### Design System Integration
- ✅ Pass / ⚠️ Warning / ❌ Fail
- Issues: {list}
---
## Level 4: Feature-Level Findings
### Shared Functionality
- ✅ Pass / ⚠️ Warning / ❌ Fail
- Issues: {list}
---
## Level 5: Content Audit Findings
### Text Content
- ✅ Pass / ⚠️ Warning / ❌ Fail
- Missing content: {list}
### Accessibility Content
- ✅ Pass / ⚠️ Warning / ❌ Fail
- Accessibility gaps: {list}
---
## Recommendations
### Critical (Must Fix Before Development)
1. {Issue and recommended fix}
2. {Issue and recommended fix}
### Warnings (Should Fix)
1. {Issue and recommended fix}
2. {Issue and recommended fix}
### Suggestions (Nice to Have)
1. {Issue and recommended fix}
2. {Issue and recommended fix}
---
## Next Steps
- [ ] {Action item}
- [ ] {Action item}
- [ ] Re-audit after fixes
---
**Audit Complete:** {YYYY-MM-DD}
```
---
## Quick Audit Checklist
For rapid validation during active design work:
**Formatting (Level 0):**
- [ ] Proper heading hierarchy
- [ ] Area Label format correct
- [ ] Translations on separate lines
- [ ] All product languages present
**Content (Levels 1-5):**
- [ ] Page purpose clear
- [ ] Trigger Map reference present
- [ ] Structural Area Labels complete
- [ ] Interactive Area Labels complete
- [ ] Multi-language content present
- [ ] ARIA labels on interactive elements
- [ ] Alt text on images
- [ ] Form labels present
- [ ] Error messages defined
- [ ] Sketch exists and linked
- [ ] **Open Questions section present** (populate using open-questions.instructions.md)
---
## Standard Audit Checklist
For comprehensive review before development handoff:
**All Quick Audit items, plus:**
**Formatting (Level 0):**
- [ ] Section organization follows template
- [ ] Consistent spacing and indentation
- [ ] Code blocks have language specified
- [ ] Links properly formatted
- [ ] No formatting violations
**Content (Levels 1-5):**
- [ ] Scenario navigation complete
- [ ] Section purposes defined
- [ ] Visual-spec alignment verified
- [ ] Components properly extracted
- [ ] Design system integration complete
- [ ] Shared features documented
- [ ] All content defined (no placeholders)
- [ ] Open Questions section reviewed (all resolved or acceptable for dev handoff)
- [ ] Accessibility requirements complete
- [ ] WCAG compliance documented
- [ ] API endpoints defined
- [ ] Validation rules specified
---
## Complete Audit Checklist
For full validation including visual verification:
**All Standard Audit items, plus:**
- [ ] Sketch matches spec exactly
- [ ] All sketch objects documented
- [ ] All spec objects in sketch
- [ ] Component hierarchy optimal
- [ ] Feature extraction complete
- [ ] Keyboard navigation tested
- [ ] Screen reader compatibility verified
- [ ] Color contrast checked
- [ ] Focus management validated
- [ ] Responsive behavior specified
---
## Integration with WDS
**Workflow Placement:**
- Phase 4 (UX Design) - Before prototype creation
- Phase 4 [H] Handover (Design Deliveries) - Before development handoff
- Phase 8 (Product Evolution) - When updating specifications
**Agent Integration:**
- Freya runs audits on page specifications
- Freya can request audits before development
- Saga can audit for strategic alignment
**Menu Trigger:**
Add to Freya's menu:
```yaml
- trigger: audit-spec
exec: "{project-root}/_bmad/wds/workflows/4-ux-design/specification-audit-workflow.md"
description: "[AS] Audit page or scenario specifications for completeness and quality"
```
---
## Related Resources
### Templates
- **Page Specification:** `./templates/page-specification.template.md`
- **Storyboard Extension:** `./templates/storyboard-specification.template.md` (for multi-sketch pages)
### Micro-Instructions (conditional sections)
- **Open Questions (always):** `./templates/instructions/open-questions.instructions.md` ← Auto-populate questions
- **SEO/Social:** `./templates/instructions/meta-content.instructions.md`
- **Forms:** `./templates/instructions/form-validation.instructions.md`
- **API Data:** `./templates/instructions/data-api.instructions.md`
- **Responsive:** `./templates/instructions/responsive.instructions.md`
- **Accessibility:** `./templates/instructions/accessibility.instructions.md`
- **Accessibility Audit:** `./templates/instructions/accessibility-audit.workflow.md`
### Guides
- **Specification Quality Guide:** `../../data/agent-guides/freya/specification-quality.md`
- **Accessibility Guidelines:** WCAG 2.1 Level AA
---
## Template Router
**Before auditing, determine which template applies:**
| Condition | Template |
|-----------|----------|
| Single sketch | page-specification.template.md |
| Multiple sketches (states, flows) | page-specification + storyboard extension |
**Check for required micro-instructions:**
| Page Has | Include |
|----------|---------|
| **All pages** | **open-questions.instructions.md** (auto-populate questions) |
| Public visibility | meta-content.instructions.md |
| Forms/inputs | form-validation.instructions.md |
| API data | data-api.instructions.md |
| Multiple breakpoints | responsive.instructions.md |
---
## Object Hierarchy Check
Verify specs follow the hierarchy:
```
Page
└── Section (OBJECT ID: page-section)
├── Object (OBJECT ID: page-object)
└── Group/Container (OBJECT ID: page-group)
└── Nested Object (OBJECT ID: page-group-object)
```
**Storyboard pages also need:**
- State Flow Overview (ASCII diagram + state table)
- State 1 fully documented (baseline)
- States 2+ document only changes (reuse OBJECT IDs)
---
**Use this workflow to ensure specifications are complete, consistent, and ready for confident implementation.**

110
_bmad/wds/workflows/4-ux-design/data/substeps-guide.md Normal file
View File

@@ -0,0 +1,110 @@
# Step 02 Substeps: Reusable Workshops
This folder contains reusable workshop micro-instructions for scenario and page initialization.
---
## Structure
### scenario-init/
**Reusable scenario definition workshop** (7 micro-steps)
Used to define a scenario (user flow context):
- Core feature/experience
- User entry point
- Mental state at entry
- Mutual success goals (business + user)
- Shortest path (page sequence)
- Scenario name
- Create scenario folder structure
**Usage:**
- **Single page projects:** NOT USED (no scenarios)
- **Single scenario projects:** Used ONCE (defines the one scenario)
- **Multiple scenarios projects:** Used MULTIPLE TIMES (scenario 1, 2, 3...)
After completion, automatically routes to `page-init/`.
---
### page-init/
**Reusable page definition workshop** (8 micro-steps)
Used to define an individual page:
- Page context (determine scenario, page number)
- Page name
- Page purpose/goal
- Entry point(s)
- User mental state at entry
- Desired outcome (business + user goals)
- Page variants (if any)
- Create page folder and initial specification document
**Usage:**
- **Single page projects:** Used MULTIPLE TIMES (separate pages or variants)
- **Single scenario projects:** Used MULTIPLE TIMES (page 1.1, 1.2, 1.3...)
- **Multiple scenarios projects:** Used MULTIPLE TIMES (page 1.1, 1.2, 2.1, 2.2...)
The page-init workshop is the fundamental reusable building block for ALL page definitions.
---
## Flow
### Single Page Projects
```
step-02-setup-scenario-structure.md
↓
page-init/ (page 1)
↓
[User can add more pages]
↓
page-init/ (page 2)
```
### Single Scenario Projects
```
step-02-setup-scenario-structure.md
↓
scenario-init/ (define scenario)
↓
page-init/ (page 1.1)
↓
[User can add more pages]
↓
page-init/ (page 1.2)
```
### Multiple Scenarios Projects
```
step-02-setup-scenario-structure.md
↓
scenario-init/ (scenario 1)
↓
page-init/ (page 1.1)
↓
[User can add more pages to scenario 1]
↓
page-init/ (page 1.2)
↓
[User can add more scenarios]
↓
scenario-init/ (scenario 2)
↓
page-init/ (page 2.1)
```
---
## Key Design Principles
1. **One question per file** - Prevents agent from skipping steps
2. **Strict sequential flow** - Each step explicitly loads the next
3. **Reusable workshops** - Can be called multiple times as project grows
4. **Clear separation** - Scenario definition vs. page definition
5. **Context-aware** - Workshops adapt based on project structure
---
**Last Updated:** 2025-12-27

215
_bmad/wds/workflows/4-ux-design/data/validation-standards.md Normal file
View File

@@ -0,0 +1,215 @@
# Page Specification Validation Standards
**Purpose:** Reference standards for validating WDS page specifications.
---
## Standard Section Order
Page specifications must follow this section order:
1. **Page Metadata** (after title)
2. **Navigation** (H3 + Next Step + Sketch + Next Step + H1)
3. **Page Description** (1-2 paragraphs)
4. **User Situation**
5. **Page Purpose**
6. **Page Sections**
7. **Object Registry**
8. **Reference Materials** (optional)
9. **Technical Notes** (optional)
10. **Development Checklist** (optional)
---
## Required Sections
### Mandatory
- Page Metadata
- Navigation structure
- Page description
- User Situation
- Page Purpose
- Page Sections
- Object Registry
### Optional
- Reference Materials
- Technical Notes
- Development Checklist
- Responsive Behavior (if responsive platform)
---
## Page Metadata Requirements
**Required Fields:**
- Platform (from Product Brief/Scenario)
- Page Type (Full Page, Modal, Drawer, etc.)
- Primary Viewport (Mobile-first, Desktop-first, etc.)
- Interaction Model (Touch, Mouse/keyboard, etc.)
- Navigation Context (Public, Authenticated, etc.)
- Inherits From (Scenario reference)
**Example:**
```markdown
## Page Metadata
**Platform**: Mobile web app (responsive PWA)
**Page Type**: Full Page
**Primary Viewport**: Mobile-first (< 768px)
**Interaction Model**: Touch-first
**Navigation Context**: Authenticated
**Inherits From**: Scenario 03 Platform Strategy (see scenario overview)
```
---
## Object ID Format
**Standard Format:** `object-name` (lowercase, hyphen-separated)
**Examples:**
- ✅ `booking-detail-header`
- ✅ `calendar-week-navigation`
- ✅ `user-profile-avatar`
- ❌ `bookingDetailHeader` (camelCase)
- ❌ `Booking_Detail_Header` (PascalCase with underscores)
**Component Declaration:**
```markdown
#### Component Name
**OBJECT ID**: `object-name`
- **Component**: [Component Name](link-to-design-system)
- **Content**: Description
- **Behavior**: Interactions
```
---
## Design System Separation
**Forbidden in Page Specs:**
- ❌ CSS classes (`.button-primary`, `.flex-container`)
- ❌ Hex color codes (`#FF5733`, `#000000`)
- ❌ Pixel values (`16px`, `margin: 20px`)
- ❌ Font specifications (`font-size: 14px`, `font-family: Inter`)
- ❌ Layout measurements (`padding: 10px 20px`)
- ❌ CSS properties (`display: flex`, `justify-content: center`)
**Allowed in Page Specs:**
- ✅ Component references with Design System links
- ✅ Design System token references (`primary-color`, `heading-large`)
- ✅ Behavioral descriptions ("button changes to active state")
- ✅ Layout intent ("elements stack vertically on mobile")
- ✅ Content specifications ("displays user's full name")
---
## Responsive Behavior Documentation
**When Required:**
- Platform: Responsive Web Application
- Primary Viewport: Mobile-first or Desktop-first
**What to Document:**
- Layout changes across viewports
- Navigation pattern adaptations
- Content reflow strategies
- Viewport-specific interactions
- Breakpoint behavior
**Example:**
```markdown
**Responsive Behavior:**
- **Mobile (< 768px)**: Navigation collapses to hamburger menu
- **Tablet (768px - 1024px)**: Side-by-side layout with condensed sidebar
- **Desktop (≥ 1024px)**: Full three-column layout with expanded navigation
```
---
## Object Registry Requirements
**Coverage:** 100% of all Object IDs from Page Sections
**Format:**
```markdown
## Object Registry
This registry provides a complete index of all interactive and structural elements on this page, enabling traceability from specification to code to Figma.
| Object ID | Type | Description |
|-----------|------|-------------|
| object-name | Component Type | Brief description |
```
**Validation:**
- Every Object ID in Page Sections must appear in registry
- No orphaned Object IDs (in registry but not in sections)
- Consistent naming across sections and registry
---
## Unnecessary Information
**Should NOT appear in page specs:**
- Implementation code snippets (HTML, CSS, JavaScript)
- Developer setup instructions
- Version control information (commit messages, PR notes)
- Internal project management notes
- Duplicate content across sections
- Outdated/deprecated information
- Design iteration history
**Belongs elsewhere:**
- Code → Implementation files
- Setup → Developer documentation
- Version control → Git history
- Project management → Project management tools
- Design decisions → Design decision log
---
## Navigation Structure
**Required Elements:**
1. H3 header with page number and name
2. "Previous Step" and "Next Step" links before sketch
3. Embedded sketch image
4. "Previous Step" and "Next Step" links after sketch (duplicate)
5. H1 header matching H3
**Format:**
```markdown
### X.X Page Name
**Previous Step**: ← [Link] | **Next Step**: → [Link]
![Sketch Description](Sketches/filename.jpg)
**Previous Step**: ← [Link] | **Next Step**: → [Link]
# X.X Page Name
```
---
## File Size Limits
**Step Files:** < 250 lines (< 200 recommended)
**Reference Documents:** No strict limit (quality-guide.md can be larger)
**Data Files:** < 500 lines (use sharding for larger datasets)
---
## Validation Checklist Template
```yaml
validation_checklist:
section_exists: [true/false]
required_fields_present: [true/false]
format_correct: [true/false]
standards_compliant: [true/false]
status: [pass/warning/critical]
```