initial commit

2026-03-16 19:54:53 -04:00
commit bfe0e01254
3341 changed files with 483939 additions and 0 deletions
--- a/_bmad/wds/workflows/4-ux-design/data/guides/DESIGN-LOOP-GUIDE.md
+++ b/_bmad/wds/workflows/4-ux-design/data/guides/DESIGN-LOOP-GUIDE.md
@@ -0,0 +1,179 @@
+# The Design Loop
+
+**The default path from scenario to implemented page.**
+
+---
+
+## Overview
+
+Design is not a handoff between phases. It's a loop: discuss → visualize → agree → build → review → refine. This guide documents the loop that emerged from real project work and defines how Phase 4 (UX Design) and Phase 5 (Agentic Development) connect.
+
+---
+
+## The 9-Step Loop
+
+```
+1. DISCUSS    → Talk about what the page needs to do, who it's for, primary actions
+2. SPEC       → Write the page specification (content, structure, object IDs)
+3. WIREFRAME  → Generate Excalidraw wireframe from the spec
+4. ITERATE    → User reviews wireframe, agent updates — fast loop (seconds)
+5. APPROVE    → User exports PNG — the export IS the approval
+6. SYNC SPEC  → Spec updates to match agreed wireframe
+7. IMPLEMENT  → Build the page in code
+8. REFINE     → Browser review via screenshots at real breakpoints
+9. TOKENS     → Extract recurring patterns into design tokens
+```
+
+Steps 4 and 8 are the iteration loops:
+- **Step 4** is fast — Excalidraw JSON manipulation, seconds per change
+- **Step 8** is real — actual browser rendering, actual responsive breakpoints
+
+---
+
+## Why This Works
+
+### Conversation resolves the hard questions first
+
+"What's the primary CTA? What's hidden on mobile? Where do trust signals go?" These are answered in discussion, not by staring at a mockup. The wireframe visualizes decisions that were already made verbally.
+
+**Don't wireframe before discussing.** Producing the wrong thing faster helps nobody.
+
+### Excalidraw is the right fidelity
+
+Nobody argues about 2px of padding in a sketchy wireframe. People focus on the right things: layout, hierarchy, what content goes where. The hand-drawn aesthetic signals "this is a work in progress — push back freely."
+
+**Don't over-detail the wireframe.** It should resolve structure and hierarchy, not typography and color. That's what the browser review phase is for.
+
+### Two-way editing
+
+Excalidraw files are plain JSON. The agent generates wireframes programmatically (creating rectangles, text, groups). The user opens the same file in VS Code's Excalidraw extension and drags elements around visually. Both can modify the same artifact.
+
+No other design tool offers this:
+- Figma requires API access
+- Pencil uses encrypted files
+- AI image generators produce dead images that can't be edited
+
+### Export = approval
+
+The agent can read and write `.excalidraw` JSON, but it cannot export to PNG — that requires the Excalidraw UI. This limitation is a feature: the manual export becomes an approval gate.
+
+**The pattern:**
+1. Agent creates/edits the `.excalidraw` file (JSON)
+2. User reviews in Excalidraw, can tweak things directly
+3. When agreed → user exports PNG and saves it alongside the `.excalidraw` file
+4. PNG becomes the frozen visual reference in the specification
+5. `.excalidraw` file stays as the editable source for future revisions
+
+The PNG serves as both a backup and a confirmation. If the user hasn't exported the image, the wireframe isn't approved yet.
+
+### The spec is the contract
+
+The wireframe helps reach agreement. The spec captures what was agreed. The implementation follows the spec. This prevents "I thought we said..." drift.
+
+**Don't skip the spec sync.** If the wireframe changes but the spec doesn't update, they diverge. The spec is the source of truth for implementation.
+
+### Short jump to code
+
+Because the spec has object IDs, responsive breakpoints, and real content, the agent builds the actual page directly. No "translate the mockup into code" step.
+
+### Browser review catches what wireframes can't
+
+Real fonts, real images, real responsive breakpoints. Screenshots at 375px, 768px, 1280px show exactly what users will see. This is where micro-adjustments happen — spacing, font sizes, proportions.
+
+### Spacing discipline — named scale, never arbitrary values
+
+Agents don't have a trained eye for spacing. Without constraints, they'll use arbitrary values — 17px here, 23px there. The fix: a named spacing scale defined per project.
+
+**The scale lives in** `D-Design-System/00-design-system.md` → Spacing Scale. If the project already has a design system (Tailwind, Material, Carbon, custom tokens), use that. If not, WDS provides a default 9-token scale from `space-3xs` to `space-3xl`, symmetric around `space-md`. The user defines what pixel values they represent.
+
+**First design session:** Freya checks if the project has an existing spacing system. If yes, map those tokens into the design system file. If no, Freya proposes values for the default scale and the user confirms. From that point on, every spec uses token names.
+
+```
+space-3xs  space-2xs  space-xs  space-sm  space-md  space-lg  space-xl  space-2xl  space-3xl
+```
+
+**The rules:**
+- Specs always use token names, never raw pixel values
+- Every section in a page spec declares its padding and element gap using tokens
+- If a spacing value isn't in the scale, it doesn't belong in the spec
+- The scale can be adjusted as the project matures — specs stay valid because they reference names, not numbers
+
+**Optical adjustments:** Sometimes the math is right but the eye says it's wrong — a circular image leaves white corners, a light element looks more spaced than it is. Use token math: `space-lg - space-3xs` (not raw pixels). Always annotate the reason. If adjusting by more than one step, the base token is probably wrong.
+
+---
+
+## Tool Roles
+
+| Tool | Role | When |
+|------|------|------|
+| **Excalidraw** | Wireframes and layout iteration | Steps 3-5 |
+| **Puppeteer** | Browser screenshots for visual review | Step 8 |
+| **Nano Banana** | Image asset generation (photos, illustrations) | Asset creation only |
+| **Design tokens** | Heading scale, spacing scale, component tokens | Step 9 |
+| **Page specs** | Source of truth for structure, content, and spacing | Steps 2, 6 |
+
+### Tool boundaries
+
+- **Excalidraw** = layout and structure. Use it for wireframing.
+- **Nano Banana** = image assets. Use it for hero photos, card images, illustrations. NOT for wireframes or mockups — those are dead images nobody can edit.
+- **Puppeteer** = reality check. Use it to verify implementation at real breakpoints.
+
+---
+
+## Spec Sync Rule
+
+When the wireframe and spec disagree, the spec must be updated before implementation begins.
+
+**The sequence:**
+1. Wireframe changes during iteration (step 4)
+2. Agent and user agree on the wireframe
+3. Agent updates the spec to match (step 5)
+4. Implementation follows the updated spec (step 6)
+
+**Never implement from the wireframe directly.** The spec is the contract. The wireframe is a tool for reaching agreement.
+
+---
+
+## Communication During Refinement
+
+When making spacing or sizing changes during browser review (step 8), state the change in concrete terms:
+
+> "Changed hero top padding from 48px to 64px"
+
+Once design tokens exist (step 9), use token names:
+
+> "Changed hero top padding from **space-2xl** (48px) to **space-3xl** (64px)"
+
+This builds shared vocabulary. Over time, the user learns to say "change from space-md to space-lg" instead of "add more space."
+
+### Pattern recognition — reflect, don't interrogate
+
+When the user requests a spacing adjustment, the agent's job is to **observe and reflect** — not to ask "why?" A trained designer carries spacing patterns unconsciously. Their gut says "more space here" because a pattern is firing in the back of their brain. The agent externalizes that intuition.
+
+**Wrong:** "Why does this need more space?" — breaks the flow, puts the meta-work on the designer.
+
+**Right:** "Got it — large image above a card row needs extra breathing room. I'll use space-xl + space-xs for this relationship going forward."
+
+The designer nods or corrects. The agent records it. The pattern table in the design system builds itself as a byproduct of doing the work.
+
+**The process:**
+1. User says "more space between the photo and the cards"
+2. Agent fixes it: `space-lg + space-xs`
+3. Agent reflects: "So when an image-with-text block sits above a card row, the default gap isn't enough."
+4. First time: one-off adjustment noted in the page spec
+5. Second time: agent says "this is the same pattern as the homepage about section — applying it"
+6. Third time: agent extracts it to `D-Design-System/00-design-system.md` → Patterns
+
+This is how a designer's unconscious expertise becomes a shared, reusable asset. The agent does the tedious classification and recall work. The designer just keeps designing.
+
+---
+
+## When to Use This Loop
+
+**Full loop (all 9 steps):** New pages where layout isn't obvious. Pages with complex information hierarchy. First page of a new scenario.
+
+**Partial loop (skip wireframe):** Pages that follow an established pattern. Second instance of a template page (e.g., vehicle type pages after the first one is done). Simple content pages.
+
+**Discussion only (steps 1-2):** When the user knows exactly what they want. When replicating a reference design.
+
+The loop adapts to the situation. Not every page needs a wireframe. But every page needs a discussion.
--- a/_bmad/wds/workflows/4-ux-design/data/guides/HTML-VS-VISUAL-STYLES.md
+++ b/_bmad/wds/workflows/4-ux-design/data/guides/HTML-VS-VISUAL-STYLES.md
@@ -0,0 +1,243 @@
+# HTML Tags vs. Visual Text Styles
+
+**Critical Best Practice for WDS Specifications**
+
+---
+
+## The Two-Layer System
+
+### Layer 1: HTML Semantic Structure (h1-h6, p, etc.)
+
+**Purpose:** SEO, accessibility, document outline, screen readers
+
+**Rules:**
+
+- **Each page must have exactly ONE h1** (main page title)
+- **Heading hierarchy must be logical** (h1 → h2 → h3, no skipping)
+- **Same across all pages** for semantic consistency
+- **Not about visual appearance**
+
+### Layer 2: Visual Text Styles (Design System)
+
+**Purpose:** Visual hierarchy, branding, design consistency
+
+**Rules:**
+
+- **Named by visual purpose** (Display-Large, Headline-Primary, Body-Regular, etc.)
+- **Can be applied to any HTML tag**
+- **Different pages can use different visual styles** for the same HTML tag
+- **About appearance, not semantics**
+
+---
+
+## Why Separate?
+
+### Problem: Mixing HTML and Visual Styles
+
+```markdown
+❌ BAD:
+
+- **Style**: H1 heading
+
+What does this mean?
+
+- Is it an h1 tag?
+- Is it a visual style that looks like an h1?
+- What if another page needs h1 but different visual style?
+```
+
+### Solution: Specify Both Independently
+
+```markdown
+✅ GOOD:
+
+- **HTML Tag**: h1 (semantic structure)
+- **Visual Style**: Display-Large (from Design System)
+```
+
+**Now we know:**
+
+- HTML: This is the main page heading (h1 for SEO)
+- Visual: It uses the "Display-Large" design system style
+- Another page could have: h1 + Headline-Medium (different visual, same semantic)
+
+---
+
+## Real-World Examples
+
+### Example 1: Landing Page vs. Article Page
+
+**Landing Page - Hero Headline:**
+
+```markdown
+- **HTML Tag**: h1
+- **Visual Style**: Hero headline
+- **Font**: Bold, 56px, line-height 1.1
+```
+
+**Article Page - Article Title:**
+
+```markdown
+- **HTML Tag**: h1
+- **Visual Style**: Main header
+- **Font**: Bold, 32px, line-height 1.3
+```
+
+**Both are h1 (semantic), but different visual styles!**
+
+### Example 2: Same Visual Style, Different Semantics
+
+**Section Heading:**
+
+```markdown
+- **HTML Tag**: h2
+- **Visual Style**: Sub header
+- **Font**: Bold, 28px, line-height 1.2
+```
+
+**Testimonial Quote:**
+
+```markdown
+- **HTML Tag**: p
+- **Visual Style**: Sub header
+- **Font**: Bold, 28px, line-height 1.2
+```
+
+**Same visual style (Sub header), but different HTML tags for proper semantics!**
+
+---
+
+## Design System Visual Style Naming
+
+### Good Visual Style Names (Descriptive & Purpose-Based)
+
+**For Headers:**
+✅ **Main header** - Primary page header
+✅ **Sub header** - Section headers
+✅ **Sub header light** - Lighter variant of section header
+✅ **Card header** - Headers within cards
+✅ **Small header** - Minor headers, labels
+
+**For Body Text:**
+✅ **Body text** - Standard paragraph text
+✅ **Body text large** - Larger body text for emphasis
+✅ **Body text small** - Smaller body text, secondary info
+✅ **Intro text** - Opening paragraph, lead text
+
+**For Special Purposes:**
+✅ **Hero headline** - Large display text for hero sections
+✅ **Caption text** - Image captions, metadata
+✅ **Label text** - Form labels, UI labels
+✅ **Error text** - Error messages
+✅ **Success text** - Success messages
+✅ **Link text** - Link styling
+✅ **Button text** - Text within buttons
+
+### Bad Visual Style Names
+
+❌ **H1-Style** / **Heading-1** - Confuses with HTML tags
+❌ **Text-Size-42** - Just a number, not semantic
+❌ **Big-Text** - Too vague
+❌ **Display-Large** - Too abstract (unless using design system tokens)
+
+---
+
+## WDS Specification Format
+
+### Complete Example
+
+```markdown
+#### Primary Headline
+
+**OBJECT ID**: `start-hero-headline`
+
+**HTML Structure:**
+
+- **Tag**: h1
+- **Purpose**: Main page heading (SEO/accessibility)
+
+**Visual Style:**
+
+- **Style Name**: Hero headline
+- **Font weight**: Bold (from 3px thick line markers in sketch)
+- **Font size**: 56px (est. from 32px spacing between line pairs)
+- **Line-height**: 1.1 (est. calculated from font size)
+- **Color**: #1a1a1a
+- **Letter spacing**: -0.02em
+
+**Position**: Center of hero section, above supporting text
+
+**Behavior**: Updates with language toggle
+
+**Content**:
+
+- EN: "Every walk. on time. Every time."
+- SE: "Varje promenad. i tid. Varje gång."
+```
+
+---
+
+## Benefits of This Approach
+
+✅ **Flexibility** - Different pages can have different visual styles for same semantic tags
+✅ **Consistency** - Design system ensures visual consistency across visual styles
+✅ **SEO/Accessibility** - Proper HTML structure maintained
+✅ **Scalability** - Easy to add new visual styles without breaking semantic structure
+✅ **Clarity** - Designers and developers both understand the specification
+✅ **Reusability** - Visual styles can be reused across different HTML tags
+
+---
+
+## Common Patterns
+
+### Pattern 1: Landing Page
+
+```
+h1 → Hero headline (big hero text, 56px)
+h2 → Sub header (section headings, 32px)
+h3 → Small header (subsection headings, 24px)
+p → Body text (regular paragraphs, 16px)
+```
+
+### Pattern 2: Blog Post
+
+```
+h1 → Main header (article title, 36px)
+h2 → Sub header (section headings, 28px)
+h3 → Sub header light (subsection headings, 22px)
+p → Body text large (article body, 18px)
+```
+
+### Pattern 3: Dashboard
+
+```
+h1 → Main header (page title, 28px)
+h2 → Card header (widget titles, 20px)
+h3 → Small header (section labels, 16px)
+p → Body text small (compact info, 14px)
+```
+
+**Same HTML structure (h1, h2, h3, p) but different visual styles for each context!**
+
+---
+
+## Implementation Note
+
+When generating HTML prototypes or handing off to developers:
+
+```html
+<!-- The HTML tag is semantic, the class references the visual style -->
+<h1 class="hero-headline">Every walk. on time. Every time.</h1>
+
+<!-- Another page might have -->
+<h1 class="main-header">Welcome to Your Profile</h1>
+
+<!-- NOT this (mixing concerns) -->
+<h1 class="h1">Every walk. on time. Every time.</h1>
+```
+
+The CSS class references the **visual style name** (hero-headline, main-header), not the HTML tag.
+
+---
+
+**Remember:** HTML tags = Document structure. Visual styles = Appearance. Keep them separate! 🎯
--- a/_bmad/wds/workflows/4-ux-design/data/guides/NANO-BANANA-PROMPT-GUIDE.md
+++ b/_bmad/wds/workflows/4-ux-design/data/guides/NANO-BANANA-PROMPT-GUIDE.md
@@ -0,0 +1,468 @@
+# Nano Banana Prompt Composition Guide
+
+**Purpose:** How to translate WDS page specifications into effective AI image generation prompts.
+
+---
+
+## The Core Problem
+
+Page specifications are verbose (500–1000+ lines). Nano Banana accepts:
+- **prompt**: max 8192 characters
+- **system_instruction**: max 512 characters
+- **input images**: up to 3 reference images for visual conditioning
+
+This guide defines what to extract, what to skip, and how to balance creativity with spec adherence.
+
+---
+
+## What to Extract from Specs
+
+### Always Include
+
+| Element | Where to find it | Example |
+|---------|-----------------|---------|
+| **Image descriptions** | `Content > Image:` fields | "Öland landscape — open fields, workshop in distance, blue sky" |
+| **Section names + order** | `## Page Sections` headers | Header → Hero → Vehicle Icons → About → Trust → Seasons → Footer |
+| **Section purposes** | `**Purpose:**` lines | "Instant emotional connection and phone number access" |
+| **Primary headlines** | `Content > SE/EN:` (pick one language) | "Vi är Källa Fordonservice" |
+| **CTA / action labels** | Button/link content fields | "Ring 0485-270 70", "Läs mer om oss" |
+| **Color values** | Visual direction or design tokens | Blues/grays, white background, red accent |
+| **Font family** | Typography direction | Inter or similar sans-serif |
+| **Layout pattern** | Layout Structure section | "3 columns desktop, 1 column mobile" |
+| **Brand mood words** | Visual direction | Professional, local, reliable, Nordic |
+
+### Always Skip
+
+| Element | Why |
+|---------|-----|
+| Object IDs (`hem-hero-image`) | Development metadata, irrelevant to visual output |
+| HTML tags (h1, h2, p, section) | Semantic structure, not visual |
+| Component file paths | Internal references |
+| Behavior / interaction states | Hover/active/disabled — static image can't show these |
+| Accessibility attributes (aria-label) | Screen reader metadata |
+| SEO section (meta descriptions, structured data) | Search engine metadata |
+| Object Registry tables | Summary tables with no visual info |
+| Checklists and Open Questions | Process tracking |
+| Secondary/tertiary language content | Pick one language per generation |
+| Font sizes in px | Too prescriptive for AI — describe hierarchy instead ("large bold headline", "smaller body text") |
+
+---
+
+## Prompt Budget Allocation
+
+**Total: 8192 characters**
+
+| Section | Faithful | Expressive | Vision |
+|---------|----------|------------|--------|
+| Creative preamble | 200 | 300 | 500 |
+| Page/section context | 300 | 300 | 200 |
+| Layout structure | 800 | 600 | 200 |
+| Image descriptions | 1000 | 1000 | 1500 |
+| Design tokens (colors, fonts) | 500 | 400 | 300 |
+| Key content (headlines, CTAs) | 2000 | 1500 | 500 |
+| Brand atmosphere | 200 | 500 | 1000 |
+| **Buffer / user additions** | **3192** | **3592** | **3992** |
+
+The buffer is intentionally large — prompt quality comes from clarity, not length.
+
+---
+
+## System Instruction Templates (max 512 chars)
+
+### Faithful Mode
+```
+Professional UI designer creating a clean, realistic interface mockup.
+Use specified colors and typography precisely. Show actual text content,
+not placeholders. Standard mobile/web UI patterns. Sharp, production-ready look.
+```
+
+### Expressive Mode
+```
+Creative UI designer making a polished, visually appealing interface.
+Follow the general layout structure but take creative liberties with
+visual treatments, lighting, depth, and atmosphere. Make it look like
+a real, beautiful product that inspires confidence.
+```
+
+### Vision Mode
+```
+Brand visual artist creating an artistic concept. Capture the emotional
+essence and personality of the brand. Focus on color story, mood, light,
+and feeling. The layout is a rough guide, not a constraint. Create something
+that makes people feel the brand before they read a word.
+```
+
+### Image Asset Mode
+```
+Professional photographer/illustrator creating a single image for use
+on a website. The image should feel authentic, not stock-photo polished.
+Natural lighting, real environments, documentary style. High quality,
+suitable for hero banners or content cards.
+```
+
+---
+
+## Worked Example: Kalla 1.1-hem Hero Image
+
+**Source spec:** 1.1-hem.md, Object `hem-hero-image`
+
+**Spec image description:**
+> "Öland landscape — open fields, the workshop visible in the distance, blue sky. Warm, inviting, unmistakably Öland."
+
+**User creative override:**
+> "Make the sky a dramatic sunset"
+
+**Reference images provided:**
+1. Verkstad-01.jpg (workshop exterior)
+2. Verkstad-02.jpg (workshop angle)
+3. Kalla-Logo.jpg (brand logo — for color/style context)
+
+**Composed system_instruction** (298 chars):
+```
+Professional photographer creating a hero banner image for a Swedish
+car workshop website. Authentic, documentary style. Natural Öland light.
+The workshop is a community hub — warm, trustworthy, approachable.
+Not stock-photo polished. Real place, real feeling.
+```
+
+**Composed prompt** (682 chars):
+```
+Wide landscape photograph of a Swedish car workshop (Källa Fordonservice)
+on northern Öland. The workshop building is visible in the middle distance,
+surrounded by the flat, open Öland landscape with low stone walls and
+sparse vegetation.
+
+The sky is a dramatic sunset — deep oranges, purples and golds spreading
+across a vast Nordic sky. The golden light catches the workshop building,
+making it glow warmly against the landscape.
+
+The mood is warm, inviting, and unmistakably Öland — wide horizons,
+quiet strength, a place you can trust. The workshop feels like it belongs
+to the landscape, not imposed on it.
+
+Colors: warm golden sunset tones, cool blue-gray Swedish twilight,
+earthy workshop browns. Professional but human.
+```
+
+**Parameters:**
+- `aspect_ratio`: `16:9` (hero banner)
+- `model_tier`: `pro`
+- `negative_prompt`: "stock photo, generic, urban, text overlay, watermark"
+
+---
+
+## Worked Example: Full Page Mockup
+
+**Scope:** Full page, Expressive mode, Mobile (9:16)
+
+**Composed prompt** (~2800 chars):
+```
+Mobile UI mockup (portrait) for "Källa Fordonservice" — a car workshop
+website in northern Öland, Sweden. Clean Swedish minimalism, professional
+but warm and approachable.
+
+Page layout from top to bottom:
+
+1. HEADER: Logo "Källa Fordonservice" on left. Phone icon and "Kontakta"
+   button on right. Clean, minimal top bar.
+
+2. SERVICE MENU: Horizontal scrollable menu below header with service
+   categories: Service, Reparationer, AC, Däck, Yrkesmaskiner, Tunga fordon.
+   Subtle, secondary navigation.
+
+3. HERO SECTION: Full-width landscape photo of Öland with workshop in
+   distance, dramatic sunset sky. Phone number "0485-270 70" overlaid
+   in a semi-transparent dark box with white text, centered in lower third.
+   The hero image dominates — emotional first impression.
+
+4. VEHICLE ICON BAR: Row of 4 small vehicle icons below hero:
+   Motorcycle, Car, Motorhome, Bus. Simple line icons with labels.
+   Shows breadth of service.
+
+5. ABOUT PREVIEW: Two-column on desktop, stacked on mobile.
+   Left: Photo of two mechanics (Björn & Nauriz) in workshop, candid,
+   friendly. Right: Heading "Vi är Källa Fordonservice" + short intro
+   paragraph. Trust badges row below (3 small partner logos, muted).
+   "Läs mer om oss →" link.
+
+6. TRUST CARDS: Three cards in a row (stacked on mobile). Each has:
+   image (4:3), heading, 2-line teaser text. White cards with subtle shadow.
+   Topics: "En riktig bilverkstad", "Däck till alla fordon",
+   "Del av Autoexperten".
+
+7. SEASONS SECTION: Heading "Så skiftar säsongerna i Källa" centered.
+   Four cards below (2×2 grid on mobile): Spring, Summer, Autumn, Winter.
+   Each with atmospheric Öland seasonal photo, season name, teaser text.
+   Warm, editorial feel.
+
+8. FOOTER: Contact info, address, phone. Simple, functional.
+
+Design details:
+- Background: white or very light gray
+- Text: dark charcoal, strong readable sans-serif (Inter)
+- Accent: deep blue for links, subtle red for CTAs
+- Cards: white with soft shadow (2-3px), rounded corners (4-8px)
+- Images: warm, authentic, documentary style
+- Generous whitespace between sections
+- Mobile single-column, thumb-friendly
+```
+
+---
+
+## Section Focus Mode
+
+When generating a single section at high fidelity, spend the full prompt budget on that section. Include:
+
+- All object details for that section
+- Full content text (still one language)
+- Precise visual style descriptions
+- Layout relationships between objects
+- Image descriptions with user overrides
+
+This is useful for iterating on hero sections, card layouts, or navigation patterns before generating the full page.
+
+---
+
+## Generation Modes: Generate vs Edit
+
+Nano Banana supports two fundamentally different modes:
+
+### Generate Mode
+Creates images from scratch. Reference images (input_image_path_1/2/3) influence **style and subject** but NOT layout.
+
+**Use for:**
+- Standalone image assets (hero photos, card images)
+- Wireframes from page specifications (no visual input needed)
+- When you have NO layout reference to work from
+
+### Edit Mode
+Transforms an existing image. The primary input image (slot 1) controls **layout structure** — section order, proportions, element placement are preserved. Additional images influence style.
+
+**Use for:**
+- Wireframe → Mockup transformation (recommended pipeline)
+- Sketch → Digital wireframe conversion
+- Iterative refinement of existing mockups
+
+**Critical rules for edit mode:**
+- **Always pin `aspect_ratio`** — if omitted, model may change aspect ratio and lose content
+- **Targeted edits work, broad edits fail** — "add a nav bar to the header" succeeds; "make everything premium" drops sections
+- **Adding > Removing** — model handles adding visible elements well, struggles to remove or restructure existing elements
+- **Slot 1 = layout source** — put the image whose structure you want to keep in input_image_path_1
+
+---
+
+## Recommended Pipeline: Spec → Wireframe → Mockup
+
+The most reliable approach for full-page mockups is a two-step pipeline:
+
+### Step 1: Spec → Clean Wireframe (generate mode)
+
+Use generate mode to create a clean digital wireframe from the page spec's layout structure. No photography, no colors — just gray boxes and text labels.
+
+**Why this works:** Wireframes are NB's strength. Gray boxes + labels don't require photography or realistic text rendering. The structured layout data (column ratios, aspect ratios, element counts) translates directly into accurate placement.
+
+**System instruction template:**
+```
+UX wireframe designer creating clean, precise digital wireframes. Use only
+grayscale — light gray boxes for image placeholders, medium gray for backgrounds,
+dark gray for text labels. No photography, no colors, no decoration. Professional
+wireframe style. Clear section boundaries.
+```
+
+**Prompt structure:**
+Describe each section top-to-bottom with specific layout instructions:
+- Column ratios ("Left column ~50%, Right column ~50%")
+- Element counts ("3 cards side by side", "11 icons in a row")
+- Content labels ("heading: Vi är Källa Fordonservice")
+- Image placeholder labels ("[HERO IMAGE — Öland landscape]")
+
+**Preventing wireframe label leakage into mockups:**
+ANY text in the wireframe will bleed into the mockup. This includes:
+- Section annotations ("SECTION 1 — HEADER", "TRUST CARDS", "FOOTER")
+- Placeholder labels ("[LOGO]", "[HERO IMAGE]", "[PHOTO — Name]")
+- Descriptive text inside gray boxes
+
+To minimize leakage:
+- Use only real content text (actual headings, labels) — these are fine since they belong in the mockup
+- Use empty gray boxes without text labels for image placeholders
+- Avoid section titles that aren't part of the actual page design
+- If labels are needed for your own reference, accept that some may leak and plan to iterate
+
+**Parameters:**
+- `mode`: `generate`
+- `aspect_ratio`: `9:16` (full page portrait scroll)
+- `model_tier`: `pro` (worth the quality for layout accuracy)
+- `negative_prompt`: "photography, realistic images, colorful design, stock photos, polished UI, gradients, shadows"
+
+### Step 2: Wireframe → Polished Mockup (edit mode)
+
+Use edit mode with the generated wireframe as primary input to apply visual design while preserving layout.
+
+**System instruction template:**
+```
+UI designer transforming wireframes into polished website mockups. Follow
+the wireframe layout EXACTLY — section order, proportions, element placement.
+Apply clean [brand style] with warm photography. Professional but human.
+[viewport type] viewport.
+```
+
+**Prompt structure:**
+Describe what to fill each placeholder with:
+- Hero: specific scene description
+- Photos: subject descriptions
+- Cards: imagery for each card
+- Colors: specific palette to apply
+- Typography: font style
+
+**Parameters:**
+- `mode`: `edit`
+- `input_image_path_1`: path to wireframe from step 1
+- `input_image_path_2`: reference photo (optional, for style conditioning)
+- `aspect_ratio`: MUST match step 1 (e.g., `9:16`)
+- `model_tier`: `pro`
+- `negative_prompt`: "wireframe style, gray boxes, placeholder text, section labels, annotations, sketch lines"
+
+### Why This Pipeline Outperforms Direct Generation
+
+| Approach | Layout accuracy | Visual quality | Reliability |
+|----------|----------------|----------------|-------------|
+| Direct generate (no reference) | Low — model invents layout | Medium | Unpredictable |
+| Sketch → Mockup (edit) | Good — follows sketch structure | Medium-High | Good |
+| **Spec → Wireframe → Mockup** | **High — spec-accurate** | **High** | **Best** |
+| Iterative editing | Degrades with each pass | Varies | Poor for removal/restructure |
+
+---
+
+## Multi-Pass Strategy
+
+Alternative workflow for thorough visual exploration (when not using the wireframe pipeline):
+
+1. **Image assets first** — Generate key images (hero photo, card photos) as standalone assets
+2. **Section focus** — Design critical sections (hero, trust cards) at high fidelity
+3. **Full page mockup** — Combine everything into a page overview
+4. **Iterate** — Refine based on user feedback
+
+Each pass builds on the previous — reference images from pass 1 can condition pass 2.
+
+---
+
+## Batch Generation: Similar Page Sequences
+
+Many projects have groups of pages that share the same layout but differ in content: vehicle type pages, service pages, article pages, product pages.
+
+### The Template-and-Swap Pattern
+
+1. **Design once** — Generate and iterate on ONE page until the user approves the visual direction
+2. **Extract the template** — The approved prompt becomes a reusable template with swap points
+3. **Generate the rest** — For each remaining page, swap in the unique content and generate
+
+### Example: 11 Vehicle Type Pages
+
+**Template prompt** (from approved 3.4-personbil):
+```
+Mobile UI mockup for a vehicle type page on "Källa Fordonservice" website.
+Swedish minimalism, professional but warm.
+
+Layout:
+1. HEADER + SERVICE MENU (shared)
+2. HERO: Full-width photo of {VEHICLE_IMAGE_DESCRIPTION}
+   Heading: "{VEHICLE_NAME}" in bold
+3. VEHICLE ICON BAR: {VEHICLE_TYPE} icon highlighted
+4. SERVICES LIST: What we do for {VEHICLE_NAME_LOWERCASE}:
+   {SERVICE_BULLETS}
+5. CTA: "Ring oss: 0485-270 70"
+6. RELATED ARTICLES: 2-3 article cards relevant to {VEHICLE_TYPE}
+7. FOOTER (shared)
+
+Design: white background, dark charcoal text, deep blue accent,
+white cards with subtle shadow, warm authentic imagery.
+```
+
+**Swap table:**
+
+| Page | VEHICLE_NAME | VEHICLE_IMAGE_DESCRIPTION | SERVICE_BULLETS |
+|------|-------------|--------------------------|-----------------|
+| 3.1 | Gräsklippare | Lawn mower on green garden, Öland summer | Service, reparation, vintervård |
+| 3.2 | Moped/Skoter | Moped on coastal road | Service, reparation, besiktning |
+| 3.9 | Traktor | Tractor in agricultural field, earth tones | Service, hydraulik, däck |
+| ... | ... | ... | ... |
+
+### Key Principles for Batch Generation
+
+- **Shared parameters stay fixed:** system_instruction, creative mode, aspect ratio, design tokens, reference images
+- **Only content swaps:** image descriptions, headlines, service lists, section-specific text
+- **Sequential generation:** Generate one at a time, quick-review each, flag outliers for iteration
+- **Use `flash` model tier** for batch runs (faster, cheaper) — save `pro` for the template page
+- **Track everything** in the agent experience file for reproducibility
+
+---
+
+## Known Limitations
+
+Documented from extensive testing on Kalla Fordonservice 1.1-hem (13+ generations, Feb 2026).
+
+### What NB is Good At
+
+| Use case | Quality | Notes |
+|----------|---------|-------|
+| **Wireframe generation from spec** | Excellent | Best use case. Structured layout data → accurate gray-box wireframes |
+| **Single image assets** (hero photos, card images) | Good | Generate mode with descriptive prompts works well |
+| **Style transfer via reference images** | Good | Slot 2-3 photos influence color/mood/subject effectively |
+| **Adding elements** (edit mode) | Fair | Can add nav bars, icons, logos to existing images |
+| **Wireframe → Mockup transformation** | Fair | Layout preserved, but wireframe text/labels leak through |
+
+### What NB Struggles With
+
+| Limitation | Severity | Workaround |
+|------------|----------|------------|
+| **Text rendering** | Critical | ALL generated text is garbled. Spec is source of truth — never trust AI text. Use mockups for layout/mood only |
+| **Logo reproduction** | High | Cannot faithfully reproduce a provided logo. Generates an "inspired by" version. Use real logo in implementation |
+| **Wireframe label leakage** | High | Placeholder text like "[LOGO]", "TRUST CARDS", section annotations bleed from wireframe into mockup. Minimize text in wireframes |
+| **Removing elements** (edit mode) | High | Edit mode cannot reliably remove things (icons, labels, sections). Regenerate from wireframe instead |
+| **Restructuring layout** (edit mode) | High | Cannot move elements to different positions (e.g., nav links from separate row into header). Regenerate |
+| **Broad edit instructions** | High | "Make everything premium" causes section loss. Must use targeted, specific edits |
+| **Aspect ratio drift** (edit mode) | Medium | If `aspect_ratio` not pinned, model changes it and drops below-fold content |
+| **Grid layouts** | Medium | 2×2 grids often flatten to 1×4 rows. Specify "2 rows, 2 columns" explicitly |
+| **Iterative degradation** | Medium | Each edit pass introduces drift. After 2-3 edits, regenerate from wireframe |
+
+### Critical Rules
+
+1. **All text is wrong** — mockups are for layout and visual direction only, never for content accuracy
+2. **Always pin `aspect_ratio` in edit mode** — omitting it is the #1 cause of content loss
+3. **One targeted change per edit** — never combine multiple changes in one edit call
+4. **Regenerate > Edit for structural changes** — if you need to move, remove, or restructure elements, go back to wireframe step
+5. **Pro model for anything structural** — Flash is only for quick image asset iterations
+6. **No section labels in wireframes** — any text in the wireframe will appear in the mockup
+
+### Where NB Fits in the Design Workflow
+
+NB is best as an **image asset production tool**, not a layout or mockup tool. AI-generated wireframes and mockups are dead images — the user cannot drag a section, resize a column, or annotate feedback directly. Use editable tools (Excalidraw, Figma) for layout iteration.
+
+**Use NB for:**
+- Hero photography (landscapes, buildings, environments)
+- People photos (team portraits, candid shots)
+- Card and article imagery (seasonal photos, product shots)
+- Mood and atmosphere exploration
+- Placeholder images during design reviews
+
+**Do NOT use NB for:**
+- Wireframes (use Excalidraw — user can edit directly)
+- Production mockups (use Google Stitch for HTML/CSS or Figma)
+- Anything where text accuracy matters (all NB text is garbled)
+- Anything the user needs to iterate on by hand
+
+### Model Tiers
+
+| Tier | Model | Input images | Strengths | Cost |
+|------|-------|-------------|-----------|------|
+| **Flash** | Gemini 2.5 Flash Image | 3 max | Fast, cheap. Good for single image assets | Low |
+| **Pro** | Gemini 3 Pro Image | 14 objects + 5 characters | Better structural accuracy, higher thinking. Worth it for wireframes and first-pass mockups | Higher |
+
+### Technical Limits
+
+- Prompt: 8192 characters max
+- System instruction: 512 characters max
+- Negative prompt: 1024 characters max
+- Input images don't consume Claude context — sent directly to Gemini via filesystem
+- Output thumbnails returned by default (full image via `return_full_image: true`)
+- `file_id` parameter causes validation errors when combined with `input_image_path` (known NB bug — use paths only)
--- a/_bmad/wds/workflows/4-ux-design/data/guides/SKETCH-TEXT-ANALYSIS-GUIDE.md
+++ b/_bmad/wds/workflows/4-ux-design/data/guides/SKETCH-TEXT-ANALYSIS-GUIDE.md
@@ -0,0 +1,532 @@
+# Sketch Analysis Guide: Reading Text Placeholders
+
+**For Dog Week and All WDS Projects**
+
+---
+
+## Best Practice: When to Use Text vs. Markers
+
+### Use ACTUAL TEXT for:
+
+- **Headlines** - Provides content guidance and context
+- **Button labels** - Shows intended action clearly
+- **Navigation items** - Clarifies structure
+- **Short, important text** - Where specific wording matters
+
+**Example:**
+
+```
+Every walk. on time. Every time.  ← Actual text (readable)
+```
+
+**Benefits:**
+
+- Agent can read and suggest this as starting content
+- Provides context for design decisions
+- Can still be changed during specification
+
+### Use HORIZONTAL LINE MARKERS for:
+
+- **Body paragraphs** - Content TBD, just need length indication
+- **Long descriptions** - Where specific wording isn't decided yet
+- **Placeholder content** - General sizing guidance
+
+**Example:**
+
+```
+─────────────────────────────────────────  ← Line markers
+─────────────────────────────────────────  ← Show length/size
+─────────────────────────────────────────  ← Not final content
+─────────────────────────────────────────
+```
+
+**Benefits:**
+
+- Shows font size and capacity without committing to content
+- Faster for sketching body text
+- Focuses on layout, not copywriting
+
+---
+
+## Understanding Sketch Text Markers
+
+In Dog Week sketches (and most UI sketches), **text is represented by horizontal lines in groups**.
+
+### What You See
+
+```
+Page Title (centered):
+       ═════════════════════════    ← Thick pair, centered = Heading, center-aligned
+       ═════════════════
+
+Body text (left-aligned):
+─────────────────────────────────────────    ← Thin pairs, left edge = Body, left-aligned
+─────────────────────────────────────────
+─────────────────────────────────────────
+─────────────────────────────────────────
+─────────────────────────────────────────
+
+Caption (right-aligned):
+                            ──────────────────    ← Short pair, right edge = Caption, right-aligned
+                            ──────────────────
+
+Justified/Full-width text:
+═════════════════════════════════════════════    ← Extends full width = Justified
+═════════════════════════════════════════════
+```
+
+### 3. Line Count → Number of Text Lines
+
+**Each PAIR of horizontal lines = ONE line of text**
+
+| Number of Pairs | Text Lines | Typical Use                    |
+| --------------- | ---------- | ------------------------------ |
+| 1 pair          | 1 line     | Headlines, labels, buttons     |
+| 2 pairs         | 2 lines    | Short headlines, subheadings   |
+| 3-4 pairs       | 3-4 lines  | Intro paragraphs, descriptions |
+| 5+ pairs        | 5+ lines   | Body copy, long descriptions   |
+
+---
+
+## Step 0: Establish Scale Using Project Context
+
+**Before analyzing individual text elements, establish your reference points:**
+
+### 1. Check Previous Pages in Project
+
+If analyzing multiple pages in the same project:
+
+**Look for established patterns:**
+
+```
+Start Page (already analyzed):
+- Body text: Thin lines, icon-sized spacing → 16px Regular
+- Button labels: Medium lines → 16px Semibold
+- Page title: Thick lines, button-height spacing → 48px Bold
+
+Current Page (About Page):
+- Similar thin lines, icon-sized spacing → **Same: 16px Regular**
+- Similar medium lines in buttons → **Same: 16px Semibold**
+```
+
+**Design System Integration:**
+
+- If project has a design system, match visual patterns to existing components
+- Body text that looks like Start Page body text → Use same specification
+- Buttons that look like Start Page buttons → Use same specification
+
+**Benefits:**
+
+- ✅ Maintains consistency across all pages
+- ✅ Builds reusable design patterns
+- ✅ Reduces specification time for subsequent pages
+- ✅ Creates cohesive user experience
+
+### 2. Find UI Anchors in Current Sketch
+
+- Browser chrome (address bar, scrollbars)
+- Standard UI elements (buttons, icons, form inputs)
+- Use these to calibrate scale for this specific sketch resolution
+
+---
+
+## Analysis Rules
+
+### 1. Line Thickness → Font Weight (Relative)
+
+**Line thickness indicates font weight (bold/regular), NOT font size**
+
+**Compare lines RELATIVE to each other within the sketch:**
+
+| Relative Thickness | Font Weight | CSS Value        | Typical Use                  |
+| ------------------ | ----------- | ---------------- | ---------------------------- |
+| Thickest (═══)     | Bold        | font-weight: 700 | Headlines, strong emphasis   |
+| Thick (═══)        | Semibold    | font-weight: 600 | Subheadings, medium emphasis |
+| Medium (──)        | Medium      | font-weight: 500 | Slightly emphasized text     |
+| Thin (──)          | Regular     | font-weight: 400 | Body text, normal content    |
+| Thinnest (─)       | Light       | font-weight: 300 | Subtle text, de-emphasized   |
+
+**Don't measure pixels—compare thickness relative to other text in the same sketch.**
+
+### 2. Distance Between Lines → Font Size (Context-Based)
+
+**The vertical spacing between lines indicates font size—compare to UI elements**
+
+| Spacing Relative To   | Estimated Font Size | Typical Use                         |
+| --------------------- | ------------------- | ----------------------------------- |
+| Button Height         | ~40-48px            | Large Heading - Page titles         |
+| Address Bar Height    | ~32-40px            | Medium Heading - Section headings   |
+| Between Button & Icon | ~24-32px            | Small Heading - Subsection headings |
+| Icon/Scrollbar Size   | ~16-24px            | Body text / Paragraphs              |
+| Half Icon Size        | ~12-16px            | Captions / Helper text              |
+
+**⚠️ Important:** If spacing seems disproportionately large (>2x button height), verify this is text and not an image placeholder or colored box!
+
+### 2a. Visual Examples: Text vs. Image Confusion
+
+**TEXT - Normal spacing:**
+
+```
+═══════════════════════════════  ← Bold line
+                                  ← ~Button Height
+═══════════════════════════════  ← Bold line
+
+This is clearly TEXT (H1 heading)
+```
+
+**IMAGE - Large spacing (confusion risk):**
+
+```
+═══════════════════════════════  ← Line?
+
+                                  ← Much larger than any UI element!
+
+═══════════════════════════════  ← Line?
+
+This might be an IMAGE PLACEHOLDER or COLORED BOX, not text!
+Ask user to confirm.
+```
+
+**When in doubt:** If spacing is disproportionately large compared to UI elements, ask: "Is this text or an image/box?"
+
+### 3. Text Alignment → Horizontal Position
+
+**The position of line pairs within the section indicates text alignment**
+
+| Alignment          | Visual Indicator                         | Typical Use                       |
+| ------------------ | ---------------------------------------- | --------------------------------- |
+| **Left-aligned**   | Lines start at left edge of container    | Body text, lists, labels          |
+| **Center-aligned** | Lines centered, equal spacing both sides | Headlines, hero text, CTAs        |
+| **Right-aligned**  | Lines end at right edge of container     | Captions, metadata, prices, dates |
+| **Justified**      | Lines extend full width of container     | Dense body text, formal content   |
+
+#### Visual Examples
+
+**Left-Aligned Text:**
+
+```
+Container: |                                                           |
+
+═════════════════════════    ← Starts at left edge
+═════════════════════════
+                                              [empty space →]
+```
+
+**Center-Aligned Text:**
+
+```
+Container: |                                                           |
+
+               ═════════════════════════    ← Centered in container
+               ═════════════════════════
+```
+
+**Right-Aligned Text:**
+
+```
+Container: |                                                           |
+
+                                          ═════════════    ← Ends at right edge
+                                          ═════════════
+```
+
+**Justified/Full-Width Text:**
+
+```
+Container: |                                                           |
+
+═════════════════════════════════════════════════════    ← Spans full width
+═════════════════════════════════════════════════════
+```
+
+---
+
+### 4. Number of Lines → Content Length
+
+| Lines in Sketch | Content Type    | Character Estimate     |
+| --------------- | --------------- | ---------------------- |
+| 1-2 lines       | Heading/Title   | 20-60 characters total |
+| 3-5 lines       | Short paragraph | 150-350 characters     |
+| 6-10 lines      | Full paragraph  | 400-700 characters     |
+| 10+ lines       | Long content    | 700+ characters        |
+
+### 4. Line-Height Calculation
+
+**Line-height is derived from font size and spacing:**
+
+```
+Line-height ratio = (Distance between lines) / (Estimated font size)
+
+Example:
+Distance: 28px
+Font size: 24px
+Line-height: 28 / 24 = 1.16 ≈ 1.2
+```
+
+**Typical ratios:**
+
+- **1.1-1.2** = Tight (headings)
+- **1.4-1.5** = Normal (body text)
+- **1.6-1.8** = Loose (airy text)
+
+```
+Left-aligned:           Center-aligned:        Right-aligned:
+──────────────────     ──────────────────            ──────────────────
+──────────────────        ──────────────         ──────────────────
+──────────────────         ──────────                ──────────────────
+```
+
+### 5. Characters Per Line
+
+**Based on estimated font size and line width:**
+
+```
+Large Heading (~48px):  ═══════════════════     = ~20-25 chars
+Medium Heading (~36px): ═══════════════════════ = ~25-30 chars
+Small Heading (~24px):  ─────────────────────── = ~40-50 chars
+Body Text (~16px):      ──────────────────────────────── = ~60-70 chars
+Caption (~12px):        ──────────────────────────────────── = ~80-90 chars
+```
+
+---
+
+## Dog Week Example Analysis
+
+### Example 1: Landing Page Hero
+
+**Sketch shows:**
+
+```
+═══════════════════════════════  ← Line 1 (thick, center)
+═══════════════════════════      ← Line 2 (thick, center)
+```
+
+**Analysis:**
+
+- **Type:** Large Heading (Page Title)
+- **Lines:** 2
+- **Line thickness:** Thickest in sketch → **Bold** (font-weight: 700)
+- **Distance between lines:** Matches button height → **~40-48px font-size**
+- **Line-height:** ~1.2 (calculated from spacing)
+- **Alignment:** Center
+- **Capacity:** ~25-30 chars per line = 50-60 total
+- **Semantic HTML:** Determined by page structure (likely H1 if page title)
+
+**Content Guidance:**
+
+```
+English: "Welcome to Your / Dog Care Hub" (48 chars) ✅
+Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅
+```
+
+### Example 2: Feature Description
+
+**Sketch shows:**
+
+```
+─────────────────────────────────────────  ← Line 1
+─────────────────────────────────────────  ← Line 2
+─────────────────────────────────────────  ← Line 3
+─────────────────────────────────────────  ← Line 4
+```
+
+**Analysis:**
+
+- **Type:** Body text / Paragraph
+- **Lines:** 4
+- **Line thickness:** Thinnest in sketch → **Regular** (font-weight: 400)
+- **Distance between lines:** Matches icon/scrollbar size → **~16-20px font-size**
+- **Line-height:** ~1.5 (calculated from spacing)
+- **Alignment:** Left
+- **Capacity:** ~60-70 chars per line = 240-280 total
+
+**Content Guidance:**
+
+```
+English: "Organize your family around dog care. Assign walks, track
+feeding schedules, and never miss a walk again. Perfect for busy
+families who want to ensure their dogs get the care they need."
+(206 chars) ✅
+
+Swedish: "Organisera din familj kring hundvård. Tilldela promenader,
+spåra matscheman och missa aldrig en promenad igen. Perfekt för
+upptagna familjer som vill säkerställa att deras hundar får den
+vård de behöver." (218 chars) ✅
+```
+
+### Example 3: Button Text
+
+**Sketch shows:**
+
+```
+[────────────]  ← Single line inside button shape
+```
+
+**Analysis:**
+
+- **Type:** Button label
+- **Lines:** 1
+- **Line thickness:** Medium (relative) → **Semibold** (font-weight: 600)
+- **Estimated font-size:** ~16-18px (button standard)
+- **Capacity:** ~8-12 characters
+
+**Content Guidance:**
+
+```
+English: "Get Started" (11 chars) ✅
+Swedish: "Kom Igång" (9 chars) ✅
+```
+
+---
+
+## Agent Instructions
+
+When analyzing sketches with text placeholders:
+
+### Step 1: Count the Lines
+
+```
+How many horizontal bar groups do you see?
+```
+
+### Step 2: Compare Line Thickness → Font Weight
+
+```
+Line thickness indicates font weight (RELATIVE comparison):
+- Thickest lines → Bold (font-weight: 700)
+- Thick lines → Semibold (font-weight: 600)
+- Medium lines → Medium (font-weight: 500)
+- Thin lines → Regular (font-weight: 400)
+- Thinnest lines → Light (font-weight: 300)
+```
+
+### Step 3: Compare Distance to UI Elements → Font Size
+
+```
+Vertical spacing relative to context anchors:
+- Matches Button Height → ~40-48px font (Large Heading)
+- Matches Address Bar → ~32-40px font (Medium Heading)
+- Between Button & Icon → ~24-32px font (Small Heading)
+- Matches Icon/Scrollbar → ~16-24px font (Body Text)
+- Half Icon Size → ~12-16px font (Caption/Small Text)
+
+⚠️ If spacing is disproportionately large, verify this is text (not image/box)!
+
+NOTE: Visual size ≠ Semantic HTML level (H1/H2/H3).
+Semantic heading levels are determined by content structure, not appearance.
+```
+
+### Step 4: Calculate Line-Height
+
+```
+Line-height = Distance between lines / Font size
+
+Example:
+- Distance: 28px
+- Font size: 24px
+- Line-height: 28 / 24 = 1.16 ≈ 1.2
+```
+
+### Step 5: Calculate Capacity
+
+```
+Lines × Characters-per-line = Total capacity
+
+Example:
+5 lines × 60 chars/line = 300 characters
+```
+
+### Step 6: Generate Content Guidance
+
+```
+"Content should be: [type], [line count] lines, ~[total chars] characters"
+
+Example:
+"Content should be: Full paragraph, 5 lines, ~300 characters"
+```
+
+### Step 7: Validate Content
+
+```
+If user provides content:
+- Count actual characters
+- Compare to capacity
+- Warn if mismatch
+
+Example:
+⚠️ Your content (450 chars) exceeds sketch capacity (300 chars).
+Consider shortening or increasing font size.
+```
+
+---
+
+## Benefits of This Approach
+
+✅ **Accurate Content Generation**
+
+- Content matches design space
+- No overflow or underflow issues
+- Professional fit and finish
+
+✅ **Design Fidelity**
+
+- Specifications match sketches
+- Developers can trust the specs
+- Reduces back-and-forth
+
+✅ **Multilingual Support**
+
+- Can estimate if translation fits
+- Adjust content length per language
+- Prevents UI breaking
+
+✅ **Quality Assurance**
+
+- Catches content length issues early
+- Ensures consistency
+- Professional output
+
+---
+
+## Example in Action
+
+**User shares Dog Week sketch of profile setup page**
+
+**Agent analyzes:**
+
+> "Looking at the profile section heading, I see 2 thick horizontal lines, center-aligned at the top.
+>
+> **Analysis:**
+>
+> - 2 lines of text (thick bars)
+> - Line thickness: Thick (relative) → Bold weight
+> - Spacing: Less than button height → ~28-32px font
+> - Line-height: ~1.3 (calculated)
+> - Alignment: Center
+> - Capacity: ~50-60 characters (25-30 per line)
+>
+> **This heading should be:** Brief, 2 short lines, ~50-60 characters total
+>
+> **Suggested content:**
+>
+> - EN: "Complete Your / Profile Setup" (41 chars) ✅
+> - SV: "Slutför Din / Profilinställning" (45 chars) ✅
+>
+> Both fit comfortably within the designed space. Does this match your intent?"
+
+---
+
+## Integration with WDS Workflow
+
+This analysis happens automatically in:
+
+- **4B: Sketch Analysis** - Initial detection
+- **object-types/heading-text.md** - Detailed analysis
+- **4C-04: Content & Languages** - Content validation
+- **4C-08: Generate Spec** - Final documentation
+
+**Result:** Every text element in WDS specifications includes accurate character capacity and content guidance! 🎨✨
+
+---
+
+_This guide ensures all WDS projects generate content that perfectly fits the designed space._
--- a/_bmad/wds/workflows/4-ux-design/data/guides/SKETCH-TEXT-QUICK-REFERENCE.md
+++ b/_bmad/wds/workflows/4-ux-design/data/guides/SKETCH-TEXT-QUICK-REFERENCE.md
@@ -0,0 +1,222 @@
+# Quick Reference: Sketch Text Analysis
+
+**The Correct Interpretation**
+
+---
+
+## Step 0: Establish Scale (Holistic View)
+
+**Before analyzing specific text, scan the ENTIRE sketch to establish scale.**
+
+1. **Find UI Anchors:** Look for standard UI elements (Browser chrome, Scrollbars, Buttons, Icons).
+2. **Check Project References:** Look at other sketches in the same project for established text styles.
+3. **Determine Base Unit:** If a Scrollbar is "Standard Width" (e.g., 16px), how big is everything else relative to it?
+4. **Calibrate:** Use these known objects to calibrate your eye for this specific image resolution.
+
+### Cross-Page Reference Strategy
+
+**If body text was defined on the Start Page:**
+
+- Start Page body text: Spacing matches icon size → 16px Regular
+- **Current page:** Similar thin lines with icon-sized spacing → **Same: 16px Regular**
+
+**Benefits:**
+
+- ✅ Maintains visual consistency across pages
+- ✅ Builds design system patterns naturally
+- ✅ Reduces guesswork on subsequent pages
+- ✅ Creates coherent user experience
+
+**When to use:**
+
+- Body text, captions, button labels (common across pages)
+- Navigation items (should be identical)
+- Form labels and inputs (standardized patterns)
+
+---
+
+## The Two Key Measurements
+
+### 1. Line Thickness = Font Weight (Relative)
+
+**Compare lines against each other in the sketch:**
+
+```
+═══════════════════  ← Thicker than others = Bold (700)
+───────────────────  ← Medium thickness = Medium (500)
+─────────────────────  ← Thinnest lines = Regular (400)
+```
+
+**Rule:** Relative thickness indicates hierarchy, not absolute pixels.
+
+### 2. Vertical Spacing = Font Size (Context-Based)
+
+**Estimate size by comparing to known UI elements:**
+
+```
+[ Button ]           ← Standard height ref (~40-48px)
+   ↕
+═══════════════════  ← Matches button height? ~40-48px (Large Heading)
+      ↕
+═══════════════════
+```
+
+**Context Anchors:**
+
+- **Browser Address Bar**: ~40px height
+- **Standard Button**: ~40-48px height
+- **Cursor/Icon**: ~16-24px size
+- **Scrollbar**: ~16px width
+
+**Rule:** Use these anchors to estimate the scale of text spacing.
+
+**Note:** Visual size ≠ Semantic HTML (H1/H2/H3). Heading levels are determined by document structure, not appearance.
+
+---
+
+## Complete Analysis Pattern
+
+### Example: Hero Headline
+
+**Sketch:**
+
+```
+═══════════════════════════════  ← Line 1: Thickest lines in sketch
+                                  ↕ Spacing ≈ Same as button height
+═══════════════════              ← Line 2: Thickest lines in sketch
+```
+
+**Analysis:**
+
+- **Context:** Spacing looks similar to the "Sign In" button height nearby.
+- **Inference:** If button is ~48px, this font is ~48px (Large Heading).
+- **Weight:** Thicker than body text markers → **Bold**.
+- **Result:** `font: bold 48px / 1.2`
+
+---
+
+## Common Patterns
+
+### Large Heading (Page Title)
+
+```
+═══════════════════  ← Thickest lines
+      ↕
+═══════════════════
+```
+
+- **Clue:** Spacing matches Address Bar height (~40px)
+- **Est:** ~40-48px, Bold
+
+### Medium Heading (Section Title)
+
+```
+═══════════════════  ← Medium-Thick lines
+      ↕
+═══════════════════
+```
+
+- **Clue:** Spacing is slightly less than button height
+- **Est:** ~32px, Semibold
+
+### Body Text (Paragraph)
+
+```
+─────────────────────  ← Thinnest lines
+    ↕
+─────────────────────
+```
+
+- **Clue:** Spacing matches scrollbar width or small icon (~16-24px)
+- **Est:** ~16px, Regular
+
+---
+
+## ⚠️ Confusion Warning
+
+### Text (Normal)
+
+```
+═══════════════════
+    ↕ Spacing < 2x Button Height
+═══════════════════
+```
+
+✅ Likely TEXT
+
+### Image/Box (Too Large)
+
+```
+═══════════════════
+
+
+    ↕ Spacing > 2x Button Height
+
+
+═══════════════════
+```
+
+❓ Likely IMAGE or CONTAINER
+
+**Rule:** If spacing seems disproportionately large compared to UI elements, verify!
+
+---
+
+## Quick Decision Tree
+
+```
+See horizontal lines?
+    │
+    ├─ Compare THICKNESS (Relative)
+    │   └─ Thicker than avg? → Bold
+    │   └─ Thinner than avg? → Regular
+    │
+    ├─ Compare DISTANCE (Context)
+    │   └─ Matches Button Height? → Large Heading (~40-48px)
+    │   └─ Matches Icon Size? → Body Text (~16-24px)
+    │   └─ Huge Gap? → Image/Container
+    │
+    └─ Check Context Anchors
+        └─ Address Bar, Scrollbar, Buttons
+```
+
+---
+
+## Memory Aid
+
+**THICKNESS = RELATIVE WEIGHT**
+**CONTEXT = SCALE**
+
+Think of it like looking at a map:
+
+- Use the scale key (buttons, bars) to measure distances.
+- Don't guess miles (pixels) without a reference!
+
+---
+
+## Real Dog Week Example
+
+```
+═══════════════════════════════  ← Thickest lines
+                                  ↕ Matches "Sign In" button height
+═══════════════════              ← Thickest lines
+```
+
+**Analysis:**
+
+- Thickness: Bold (relative to body lines)
+- Distance: Matches button (~48px)
+- Result: `font: bold 48px / 1.2`
+
+**Content:**
+
+```
+EN: "Every walk. on time. Every time."
+SE: "Varje promenad. i tid. Varje gång."
+```
+
+Both fit in ~50-60 character capacity! ✅
+
+---
+
+**Remember: Context is King! Compare, don't just measure.** 📏✨
--- a/_bmad/wds/workflows/4-ux-design/data/guides/TRANSLATION-ORGANIZATION-GUIDE.md
+++ b/_bmad/wds/workflows/4-ux-design/data/guides/TRANSLATION-ORGANIZATION-GUIDE.md
@@ -0,0 +1,513 @@
+# Translation Organization Guide
+
+**Part of WDS Specification Pattern**
+
+**Purpose-Based Naming with Grouped Translations**
+
+---
+
+## Overview
+
+This guide explains how to organize text content and translations in WDS specifications using **purpose-based naming** and **grouped translation** patterns.
+
+**Related Documentation:**
+
+- **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** - How to analyze text markers in sketches
+- **`HTML-VS-VISUAL-STYLES.md`** - HTML tags vs visual text styles
+- **`WDS-SPECIFICATION-PATTERN.md`** - Complete specification format with examples
+
+---
+
+## Core Principles
+
+### 1. Name by PURPOSE, Not Content
+
+**❌ WRONG:**
+
+```markdown
+#### Welcome Heading
+
+**OBJECT ID**: `start-hero-welcome-heading`
+
+- Content: "Welcome to Dog Week"
+```
+
+**✅ CORRECT:**
+
+```markdown
+#### Primary Headline
+
+**OBJECT ID**: `start-hero-headline`
+
+- Content:
+  - EN: "Welcome to Dog Week"
+  - SE: "Välkommen till Dog Week"
+```
+
+**Why:** If content changes to "Every walk. on time.", the Object ID still makes sense.
+
+---
+
+### 2. Separate Structure from Content
+
+**Structure (Position/Style):**
+
+```markdown
+- **HTML Tag**: h1 (semantic structure for SEO/accessibility)
+- **Visual Style**: Hero headline (from Design System)
+- **Position**: Center of hero section, above CTA
+- **Style**:
+  - Font weight: Bold (from 3px thick line markers)
+  - Font size: 42px (est. from 24px spacing between line pairs)
+  - Line-height: 1.2 (est. calculated from font size)
+- **Behavior**: Updates with language toggle
+```
+
+> **Important:** HTML tags (h1-h6) define semantic structure for SEO/accessibility. Visual styles (Hero headline, Main header, Sub header, etc.) define appearance and can be applied to any HTML tag.
+
+> **Note:** Values marked `(est. from...)` show sketch analysis reasoning. Designer should confirm or adjust these values, then update with actual specifications.
+
+````
+
+**Content (Translations):**
+```markdown
+- **Content**:
+  - EN: "Every walk. on time. Every time."
+  - SE: "Varje promenad. i tid. Varje gång."
+````
+
+**Why:** Structure rarely changes, content often does. Keeps specs clean.
+
+---
+
+### 3. Group Related Translations
+
+**❌ WRONG (Scattered):**
+
+```markdown
+#### Headline EN
+
+"Every walk. on time."
+
+#### Headline SE
+
+"Varje promenad. i tid."
+
+#### Body EN
+
+"Organize your family..."
+
+#### Body SE
+
+"Organisera din familj..."
+```
+
+**✅ CORRECT (Grouped):**
+
+```markdown
+### Hero Object
+
+**Purpose**: Primary value proposition
+
+#### Primary Headline
+
+**OBJECT ID**: `start-hero-headline`
+
+- **Content**:
+  - EN: "Every walk. on time. Every time."
+  - SE: "Varje promenad. i tid. Varje gång."
+
+#### Supporting Text
+
+**OBJECT ID**: `start-hero-supporting`
+
+- **Content**:
+  - EN: "Organize your family around dog care."
+  - SE: "Organisera din familj kring hundvård."
+```
+
+**Why:** Each language reads as complete, coherent message.
+
+---
+
+## Dog Week Examples
+
+### Example 1: Hero Section (Text Group)
+
+```markdown
+### Hero Object
+
+**Purpose**: Primary value proposition and main conversion action
+
+#### Primary Headline
+
+**OBJECT ID**: `start-hero-headline`
+
+- **Component**: H1 heading (`.text-heading-1`)
+- **Position**: Center of hero, top of section
+- **Style**: Bold, no italic, 42px, line-height 1.2
+- **Behavior**: Updates with language toggle
+- **Content**:
+  - EN: "Every walk. on time. Every time."
+  - SE: "Varje promenad. i tid. Varje gång."
+
+#### Supporting Text
+
+**OBJECT ID**: `start-hero-supporting`
+
+- **Component**: Body text (`.text-body`)
+- **Position**: Below headline, above CTA
+- **Style**: Regular, 16px, line-height 1.5
+- **Behavior**: Updates with language toggle
+- **Content**:
+  - EN: "Organize your family around dog care. Never miss a walk again."
+  - SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen."
+
+#### Primary CTA Button
+
+**OBJECT ID**: `start-hero-cta`
+
+- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md)
+- **Position**: Center, below supporting text
+- **Behavior**: Navigate to registration
+- **Content**:
+  - EN: "start planning - free forever"
+  - SE: "börja planera - gratis för alltid"
+```
+
+**Reading Experience:**
+
+**English:**
+
+> Every walk. on time. Every time.
+> Organize your family around dog care. Never miss a walk again.
+> [start planning - free forever]
+
+**Swedish:**
+
+> Varje promenad. i tid. Varje gång.
+> Organisera din familj kring hundvård. Missa aldrig en promenad igen.
+> [börja planera - gratis för alltid]
+
+Each language flows naturally as a complete message!
+
+---
+
+### Example 2: Form Labels (Individual Elements)
+
+```markdown
+### Sign In Form
+
+**Purpose**: User authentication
+
+#### Email Label
+
+**OBJECT ID**: `signin-form-email-label`
+
+- **Component**: Label text (`.text-label`)
+- **Position**: Above email input field
+- **For**: `signin-form-email-input`
+- **Content**:
+  - EN: "Email Address"
+  - SE: "E-postadress"
+
+#### Email Input
+
+**OBJECT ID**: `signin-form-email-input`
+
+- **Component**: [Text Input](/docs/.../text-input.md)
+- **Placeholder**:
+  - EN: "your@email.com"
+  - SE: "din@epost.com"
+
+#### Password Label
+
+**OBJECT ID**: `signin-form-password-label`
+
+- **Component**: Label text (`.text-label`)
+- **Position**: Above password input
+- **For**: `signin-form-password-input`
+- **Content**:
+  - EN: "Password"
+  - SE: "Lösenord"
+
+#### Password Input
+
+**OBJECT ID**: `signin-form-password-input`
+
+- **Component**: [Password Input](/docs/.../password-input.md)
+- **Placeholder**:
+  - EN: "Enter your password"
+  - SE: "Ange ditt lösenord"
+```
+
+---
+
+### Example 3: Error Messages
+
+```markdown
+### Validation Messages
+
+**Purpose**: User feedback on form errors
+
+#### Email Required Error
+
+**OBJECT ID**: `signin-form-email-error-required`
+
+- **Component**: Error text (`.text-error`)
+- **Position**: Below email input field
+- **Trigger**: When email field is empty on submit
+- **Content**:
+  - EN: "Email address is required"
+  - SE: "E-postadress krävs"
+
+#### Email Invalid Error
+
+**OBJECT ID**: `signin-form-email-error-invalid`
+
+- **Component**: Error text (`.text-error`)
+- **Position**: Below email input field
+- **Trigger**: When email format is invalid
+- **Content**:
+  - EN: "Please enter a valid email address"
+  - SE: "Ange en giltig e-postadress"
+
+#### Auth Failed Error
+
+**OBJECT ID**: `signin-form-auth-error`
+
+- **Component**: Alert banner (`.alert-error`)
+- **Position**: Above form, below page heading
+- **Trigger**: When authentication fails
+- **Content**:
+  - EN: "Invalid email or password. Please try again."
+  - SE: "Ogiltig e-post eller lösenord. Försök igen."
+```
+
+---
+
+## Object ID Naming Patterns
+
+### Format: `{page}-{section}-{purpose}`
+
+**Page Examples:**
+
+- `start` (start/landing page)
+- `signin` (sign in page)
+- `profile` (profile page)
+- `calendar` (calendar page)
+
+**Section Examples:**
+
+- `hero` (hero section)
+- `header` (page header)
+- `form` (form section)
+- `features` (features section)
+- `footer` (page footer)
+
+**Purpose Examples:**
+
+- `headline` (main heading)
+- `subheading` (secondary heading)
+- `description` (descriptive text)
+- `cta` (call-to-action button)
+- `label` (form label)
+- `error` (error message)
+- `success` (success message)
+- `supporting` (supporting/helper text)
+
+**Complete Examples:**
+
+- `start-hero-headline`
+- `signin-form-email-label`
+- `profile-success-message`
+- `calendar-header-title`
+- `features-description-text`
+
+---
+
+## Content Structure
+
+### Required Fields
+
+```markdown
+#### {{Purpose_Title}}
+
+**OBJECT ID**: `{{page-section-purpose}}`
+
+- **Component**: {{component_type}} ({{class_or_reference}})
+- **Position**: {{position_description}}
+- **Content**:
+  - EN: "{{english_content}}"
+  - SE: "{{swedish_content}}"
+    {{#if additional_languages}}
+  - {{lang}}: "{{content}}"
+    {{/if}}
+```
+
+### Optional Fields
+
+```markdown
+- **Behavior**: {{behavior_description}}
+- **Style**: {{style_specifications}}
+- **For**: {{linked_input_id}} (for labels)
+- **Trigger**: {{when_shown}} (for conditional text)
+```
+
+---
+
+## Multi-Language Support
+
+### 2 Languages (Dog Week)
+
+```markdown
+- **Content**:
+  - EN: "Welcome to Dog Week"
+  - SE: "Välkommen till Dog Week"
+```
+
+### 3+ Languages
+
+```markdown
+- **Content**:
+  - EN: "Welcome to Dog Week"
+  - SE: "Välkommen till Dog Week"
+  - DE: "Willkommen bei Dog Week"
+  - FR: "Bienvenue à Dog Week"
+```
+
+### Language Codes
+
+- **EN** = English
+- **SE** = Swedish (Svenska)
+- **NO** = Norwegian
+- **DK** = Danish
+- **FI** = Finnish
+- **DE** = German
+- **FR** = French
+- **ES** = Spanish
+- **IT** = Italian
+
+---
+
+## Benefits of This Pattern
+
+### ✅ For Translators
+
+```markdown
+**Hero Object Translations:**
+
+#### Primary Headline
+
+- EN: "Every walk. on time. Every time."
+- SE: "Varje promenad. i tid. Varje gång."
+
+#### Supporting Text
+
+- EN: "Organize your family around dog care."
+- SE: "Organisera din familj kring hundvård."
+```
+
+Translator can:
+
+- Read entire section in each language
+- Ensure translations flow together
+- See context immediately
+- Verify character lengths
+
+### ✅ For Developers
+
+```typescript
+// Object ID makes purpose clear
+const headline = document.getElementById('start-hero-headline');
+const supportingText = document.getElementById('start-hero-supporting');
+
+// Content referenced by language
+const content = {
+  'start-hero-headline': {
+    en: 'Every walk. on time. Every time.',
+    se: 'Varje promenad. i tid. Varje gång.',
+  },
+};
+```
+
+### ✅ For Maintainability
+
+**Content changes:**
+
+```markdown
+#### Primary Headline
+
+**OBJECT ID**: `start-hero-headline` ← Stays same
+
+- **Content**:
+  - EN: "NEW CONTENT HERE" ← Easy to update
+  - SE: "NYTT INNEHÅLL HÄR"
+```
+
+**No Object ID changes needed!**
+
+---
+
+## Text Group Examples
+
+### Hero Group (Headline + Body + CTA)
+
+All translations grouped so each language reads coherently:
+
+```markdown
+### Hero Object
+
+#### Headline
+
+- EN: "Every walk. on time."
+- SE: "Varje promenad. i tid."
+
+#### Body
+
+- EN: "Never miss a walk again."
+- SE: "Missa aldrig en promenad."
+
+#### CTA
+
+- EN: "Get Started"
+- SE: "Kom Igång"
+```
+
+**English reads:** "Every walk. on time. / Never miss a walk again. / [Get Started]"
+**Swedish reads:** "Varje promenad. i tid. / Missa aldrig en promenad. / [Kom Igång]"
+
+### Feature Group (Icon + Title + Description)
+
+```markdown
+### Feature Card 1
+
+#### Feature Title
+
+- EN: "Smart Scheduling"
+- SE: "Smart Schemaläggning"
+
+#### Feature Description
+
+- EN: "Automatically assign walks based on family availability."
+- SE: "Tilldela promenader automatiskt baserat på familjetillgänglighet."
+```
+
+---
+
+## Validation Checklist
+
+Before finalizing text specifications:
+
+- [ ] Object IDs use purpose-based naming (not content)
+- [ ] Structure (position/style) separated from content
+- [ ] All languages included for each text element
+- [ ] Text groups keep translations together
+- [ ] Each language reads coherently as a group
+- [ ] Character lengths validated against sketch analysis
+- [ ] Component references included
+- [ ] Behavior specified (if applicable)
+
+---
+
+**This pattern ensures professional, maintainable, translation-friendly specifications across all WDS projects!** 🌍✨
--- a/_bmad/wds/workflows/4-ux-design/data/guides/WDS-SPECIFICATION-PATTERN.md
+++ b/_bmad/wds/workflows/4-ux-design/data/guides/WDS-SPECIFICATION-PATTERN.md
@@ -0,0 +1,436 @@
+# WDS Specification Pattern
+
+**Complete specification format for Whiteport Design Studio projects**
+
+---
+
+## Overview
+
+This document defines the **WDS Specification Pattern** used in Phase 4 (UX Design) for all WDS projects.
+
+**Dog Week Start Page** is used as the example implementation to demonstrate the pattern in action.
+
+**Related Documentation:**
+
+- **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** - How sketch analysis values are derived
+- **`HTML-VS-VISUAL-STYLES.md`** - HTML tags vs visual text styles
+- **`TRANSLATION-ORGANIZATION-GUIDE.md`** - Purpose-based text organization
+
+---
+
+## Key Principles
+
+### 1. Purpose-Based Naming
+
+Text objects are named by **function, not content**:
+
+- ✅ `hero-headline` (describes purpose)
+- ❌ `welcome-message` (describes content)
+
+### 2. Grouped Translations
+
+All product languages grouped together per object for coherent review.
+
+### 3. Estimated Values from Sketch Analysis
+
+When text properties are estimated from sketch markers:
+
+- **Spell out the values explicitly** (e.g., `42px (est. from 24px spacing)`)
+- **Mark with analysis note** to show reasoning
+- **Designer confirms or adjusts** during specification dialog
+- **Update with final values** once confirmed
+
+**Analysis methodology:** See `SKETCH-TEXT-ANALYSIS-GUIDE.md` for complete rules on deriving font weight, font size, line-height, and alignment from sketch markers.
+
+This ensures transparency about which values came from AI interpretation vs. designer specification.
+
+---
+
+## The Pattern in Action
+
+### Hero Section Example
+
+```markdown
+### Hero Object
+
+**Purpose**: Primary value proposition and main conversion action
+
+#### Primary Headline
+
+**OBJECT ID**: `start-hero-headline`
+
+**HTML Structure:**
+
+- **Tag**: h1
+- **Semantic Purpose**: Main page heading for SEO and accessibility
+
+**Visual Style:**
+
+- **Style Name**: Hero headline
+- **Font weight**: Bold (from 3px thick line markers in sketch)
+- **Font size**: 56px (est. from 32px vertical spacing between line pairs)
+- **Line-height**: 1.1 (est. calculated as font-size × 1.1)
+- **Color**: #1a1a1a
+- **Letter spacing**: -0.02em
+
+**Position**: Center of hero section, above supporting text
+**Alignment**: center
+
+**Behavior**: Updates with language toggle
+
+**Content**:
+
+- EN: "Every walk. on time. Every time."
+- SE: "Varje promenad. i tid. Varje gång."
+
+> **Sketch Analysis:** Line thickness (3px) → Bold weight. Line spacing (32px) → ~56px font size estimate. Designer should confirm these values.
+
+#### Supporting Text
+
+**OBJECT ID**: `start-hero-supporting`
+
+**HTML Structure:**
+
+- **Tag**: p
+- **Semantic Purpose**: Paragraph text providing additional context
+
+**Visual Style:**
+
+- **Style Name**: Body text large
+- **Font weight**: Regular (from 1px thin line markers in sketch)
+- **Font size**: 18px (est. from 14px vertical spacing between line pairs)
+- **Line-height**: 1.5 (est. calculated as font-size × 1.5)
+- **Color**: #4a4a4a
+
+**Position**: Below headline, above CTA, center-aligned
+**Alignment**: center
+
+**Behavior**: Updates with language toggle
+
+**Content**:
+
+- EN: "Organize your family around dog care. Never miss a walk again."
+- SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen."
+
+> **Sketch Analysis:** Line thickness (1px) → Regular weight. Line spacing (14px) → ~18px font size estimate. Designer should confirm these values.
+
+#### Primary CTA Button
+
+**OBJECT ID**: `start-hero-cta`
+
+- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md)
+- **Position**: Center, below supporting text, 24px margin-top
+- **Behavior**: Navigate to /auth/signup
+- **States**: default, hover, active, loading
+- **Content**:
+  - EN: "start planning - free forever"
+  - SE: "börja planera - gratis för alltid"
+```
+
+**Reading in English:**
+
+> **Every walk. on time. Every time.**
+> Organize your family around dog care. Never miss a walk again.
+> [start planning - free forever]
+
+**Reading in Swedish:**
+
+> **Varje promenad. i tid. Varje gång.**
+> Organisera din familj kring hundvård. Missa aldrig en promenad igen.
+> [börja planera - gratis för alltid]
+
+---
+
+## The Complete Process
+
+### Step 1: Sketch Analysis (4B)
+
+```
+Agent sees sketch with horizontal lines:
+
+═══════════════════════════════  ← Line 1 (thick, 3px)
+═══════════════════════════      ← Line 2 (thick, 3px)
+
+─────────────────────────────────────────  ← Line 3 (thin, 1px)
+─────────────────────────────────────────  ← Line 4 (thin, 1px)
+
+┌─────────────────────────────┐
+│  start planning             │  ← Button
+└─────────────────────────────┘
+
+Agent identifies:
+1. TEXT GROUP (2 thick lines) - Hero headline
+2. TEXT GROUP (2 thin lines) - Supporting text
+3. BUTTON - CTA
+```
+
+### Step 2: Object Detection (4C-03 + object-router)
+
+```
+For Object 1:
+  → Detects horizontal lines
+  → TEXT DETECTED
+  → Routes to heading-text.md
+
+heading-text.md:
+  → Asks: "What's the PURPOSE?" → "Primary Headline"
+  → Object ID: `start-hero-headline`
+  → Sketch analysis: 2 lines, 3px thick, ~50-60 chars
+  → Content guidance: Brief heading, 2 short lines
+  → Requests content with length validation
+```
+
+### Step 3: Content with Grouped Translations
+
+```
+Agent asks:
+
+"What's the content for Primary Headline?
+
+Based on sketch: 2 lines, ~50-60 characters total
+
+I found text in your sketch: 'Every walk. on time. Every time.'
+
+Let me suggest translations...
+
+EN: Every walk. on time. Every time.
+SE: Varje promenad. i tid. Varje gång.
+
+Do these work? [1] Use these [2] Adjust [3] Manual"
+
+User provides:
+1  ← Accepts suggestions!
+
+Agent validates:
+✅ EN: 37 chars (fits 60 capacity)
+✅ SE: 36 chars (fits 60 capacity)
+```
+
+### Step 4: Generate Specification
+
+```markdown
+#### Primary Headline
+
+**OBJECT ID**: `start-hero-headline`
+
+- **Component**: H1 heading
+- **Position**: Center of hero
+- **Style**: Bold, 42px, line-height 1.2
+- **Content**:
+  - EN: "Every walk. on time. Every time."
+  - SE: "Varje promenad. i tid. Varje gång."
+```
+
+---
+
+## Key Advantages
+
+### 1. Purpose-Based Object IDs
+
+**Stable Naming:**
+
+- Content changes don't affect Object IDs
+- IDs remain semantic and meaningful
+- Easy to find by function
+
+**Examples:**
+
+```markdown
+`start-hero-headline` ← Purpose clear
+`signin-form-email-label` ← Function clear
+`profile-success-message` ← Role clear
+```
+
+### 2. Separated Concerns
+
+**Structure/Style** (rarely changes):
+
+```markdown
+- **Component**: H1 heading
+- **Position**: Center of hero
+- **Style**: Bold, 42px
+```
+
+**Content** (often changes):
+
+```markdown
+- **Content**:
+  - EN: "..."
+  - SE: "..."
+```
+
+### 3. Grouped Translations
+
+**Benefits:**
+
+- Each language reads as complete message
+- Translator sees full context
+- Natural language flow
+- Easy to verify coherence
+
+**Format:**
+
+```markdown
+### Text Group
+
+#### Element 1
+
+- EN: "..."
+- SE: "..."
+
+#### Element 2
+
+- EN: "..."
+- SE: "..."
+
+#### Element 3
+
+- EN: "..."
+- SE: "..."
+```
+
+### 4. Character Capacity Validation
+
+**From Sketch Analysis:**
+
+```
+Agent: "Sketch shows 2 lines, ~50-60 chars capacity"
+
+User provides: "Every walk. on time. Every time." (37 chars)
+
+Agent: "✅ Content fits within sketch capacity!"
+```
+
+**If too long:**
+
+```
+Agent: "⚠️ Your content (85 chars) exceeds capacity (60 chars).
+Consider shortening or adjusting font size."
+```
+
+---
+
+## Complete Workflow Integration
+
+```
+4B: Sketch Analysis
+    ↓
+    Identifies text groups, estimates capacity
+    ↓
+4C-03: Components & Objects
+    ↓
+    object-router.md
+        ↓
+        STEP 1: TEXT DETECTION (checks horizontal lines)
+        ↓
+        If text → heading-text.md
+            ↓
+            1. Ask PURPOSE (not content)
+            2. Generate Object ID from purpose
+            3. Specify position/style
+            4. Request content with grouped translations
+            5. Validate against sketch capacity
+            6. Generate specification (Dog Week format)
+            ↓
+        Return to 4C-03
+    ↓
+4C-04: Content & Languages
+    (Already captured in heading-text.md)
+    ↓
+4C-08: Generate Final Spec
+```
+
+---
+
+## Template Structure
+
+**Every text element follows this format:**
+
+```markdown
+#### {{Purpose_Title}}
+
+**OBJECT ID**: `{{page-section-purpose}}`
+
+- **Component**: {{type}} ({{class_or_ref}})
+- **Position**: {{position_description}}
+  {{#if has_behavior}}
+- **Behavior**: {{behavior_description}}
+  {{/if}}
+  {{#if has_style_details}}
+- **Style**: {{style_specifications}}
+  {{/if}}
+  {{#if links_to_input}}
+- **For**: {{input_object_id}}
+  {{/if}}
+- **Content**:
+  - EN: "{{english_text}}"
+  - SE: "{{swedish_text}}"
+    {{#each additional_language}}
+  - {{code}}: "{{text}}"
+    {{/each}}
+```
+
+---
+
+## Real Dog Week Specifications
+
+These follow the exact pattern we're implementing:
+
+**From 1.1-Start-Page.md:**
+
+```markdown
+#### Primary Headline
+
+**OBJECT ID**: `start-hero-headline`
+
+- **Component**: H1 heading (`.text-heading-1`)
+- **Content**:
+  - EN: "Every walk. on time. Every time."
+  - SE: "Varje promenad. i tid. Varje gång."
+
+#### Primary CTA Button
+
+**OBJECT ID**: `start-hero-cta`
+
+- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md)
+- **Content**:
+  - EN: "start planning - free forever"
+  - SE: "börja planera - gratis för alltid"
+```
+
+**From 1.2-Sign-In.md (Header example):**
+
+```markdown
+#### Sign In Button
+
+**OBJECT ID**: `start-header-signin`
+
+- **Component**: [Button Secondary](/docs/D-Design-System/.../Button-Secondary.md)
+- **Content**:
+  - EN: "Sign in"
+  - SE: "Logga in"
+- **Behavior**: Navigate to sign-in page
+```
+
+---
+
+## Specification Checklist
+
+For each text element:
+
+- [ ] **Purpose-based name** (not content-based)
+- [ ] **Object ID** from purpose: `{page}-{section}-{purpose}`
+- [ ] **Component** reference specified
+- [ ] **Position** clearly described
+- [ ] **Style** separated from content
+- [ ] **Behavior** specified if applicable
+- [ ] **Content** with grouped translations:
+  - [ ] EN: "..."
+  - [ ] SE: "..."
+  - [ ] Additional languages if needed
+- [ ] **Character length** validated against sketch
+- [ ] **Part of text group** if applicable
+
+---
+
+**This is the WDS standard for text specifications, proven by Dog Week!** 🎨🌍✨