Wds 4 Ux Design

Follow the instructions in ./workflow.md.

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

# 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

# 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

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:

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:

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:

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! 📦✨

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 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.

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

❌ 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

✅ 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:

- **HTML Tag**: h1
- **Visual Style**: Hero headline
- **Font**: Bold, 56px, line-height 1.1

Article Page - Article Title:

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

- **HTML Tag**: h2
- **Visual Style**: Sub header
- **Font**: Bold, 28px, line-height 1.2

Testimonial Quote:

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

#### 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:

<!-- 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! 🎯

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

Always Skip

---

Prompt Budget Allocation

Total: 8192 characters

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

---

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:

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

What NB Struggles With

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

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)

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

---

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:

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

⚠️ 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

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

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

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. 📏✨

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:

#### Welcome Heading

**OBJECT ID**: `start-hero-welcome-heading`

- Content: "Welcome to Dog Week"

✅ CORRECT:

#### 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):

- **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):

- **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):

#### Headline EN

"Every walk. on time."

#### Headline SE

"Varje promenad. i tid."

#### Body EN

"Organize your family..."

#### Body SE

"Organisera din familj..."

✅ CORRECT (Grouped):

### 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)

### 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)

### 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

### 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

#### {{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

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

- **Content**:
  - EN: "Welcome to Dog Week"
  - SE: "Välkommen till Dog Week"

3+ Languages

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

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

// 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:

#### 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:

### 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)

### 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! 🌍✨

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

### 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

#### 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:

`start-hero-headline` ← Purpose clear
`signin-form-email-label` ← Function clear
`profile-success-message` ← Role clear

2. Separated Concerns

Structure/Style (rarely changes):

- **Component**: H1 heading
- **Position**: Center of hero
- **Style**: Bold, 42px

Content (often changes):

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

### 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:

#### {{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:

#### 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):

#### 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! 🎨🌍✨

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

# 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)

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

Modular Component Architecture

Navigation hub for the three-tier specification system

---

Foundation (00-)

Agent-Designer Collaboration

How AI agents optimize designer craft without replacing designer thinking

---

Core Concepts (01-)

Three-Tier Architecture

Overview of Pages, Components, and Features separation

Content Placement Rules

Decision tree for where to document content

Complexity Detection

How to identify simple vs complex components

---

Workflows (02-)

Page Specification Workflow

Step-by-step page decomposition from sketch to specs

Complexity Router Workflow

Guided decomposition for complex components

Storyboard Integration

Using visual storyboards for complex components

---

Examples

Simple Component Example

Button - single file documentation

Complex Component Example

Calendar - three-tier decomposition

Search Bar Example

Search with page-specific content

---

Quick References (03-)

Decision Tree

One-page flowchart for file placement

Benefits Summary

Why this architecture works

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:

❌ 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 - How to decompose
• Examples - See real decompositions

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:

❌ 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:

❌ 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

**Content Slots:**

- Heading text (configurable per page)
- Background image (configurable per page)

⚠️ Common Mistakes:

❌ 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

---

Examples

• Simple Button
• Search Bar
• Calendar Widget

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:

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:

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:

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 - Where does content go?
• Complexity Detection - When to decompose?
• Workflow - How to decompose?

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
• Storyboard Types
• Creation Guide

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
• Creation Guide

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:

Features/walk-booking-logic.feature.md

## Visual Storyboard

![Walk State Transitions](Storyboards/walk-state-transitions.jpg)

From Component File:

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
• Feature File Integration

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

---

Output: Three Files

1. Page File

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

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

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 - See real decompositions
• Storyboards - Visual documentation

Storyboard Integration

Using visual storyboards for complex components

---

Core Concepts (01-)

What Are Storyboards?

Visual documentation of state transitions and flows

When to Use Storyboards

Complexity indicators that require visual documentation

Storyboard Types

State transitions, interaction flows, multi-component sync

---

Storage & Organization (02-)

File Structure

Where to store storyboards in the three-tier architecture

Naming Conventions

How to name storyboard files

---

Creation Guidelines

How to Create Storyboards

Hand-drawn, digital, or annotated screenshots

Annotation Best Practices

Numbering, labels, and visual indicators

---

Integration

Referencing in Feature Files

How to link storyboards from specifications

Referencing in Component Files

Visual state references

---

Examples

TaskFlow Task States

6-state walk booking storyboard

Search Flow

Multi-step interaction storyboard

---

Benefits

Why Storyboards Work

Developer clarity, QA testing, design consistency

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.