Add design loop guide, make Excalidraw the default wireframing tool

New: DESIGN-LOOP-GUIDE.md — documents the 8-step design loop
(discuss → spec → wireframe → iterate → sync spec → implement →
browser review → extract tokens) from Källa project experience.

Updates:
- step-01-exploration: Wireframe is now recommended first option,
  adds iteration loop and spec sync rule
- workflow-conceptualize: References design loop guide
- workflow.md: Updated reference content description

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/workflows/4-ux-design/data/guides/DESIGN-LOOP-GUIDE.md

@@ -0,0 +1,131 @@
+# 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 8-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. SYNC SPEC  → Spec updates to match agreed wireframe
+6. IMPLEMENT  → Build the page in code
+7. REFINE     → Browser review via screenshots at real breakpoints
+8. TOKENS     → Extract recurring patterns into design tokens
+```
+
+Steps 4 and 7 are the iteration loops:
+- **Step 4** is fast — Excalidraw JSON manipulation, seconds per change
+- **Step 7** 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
+
+### 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.
+
+### Tokens emerge from usage
+
+Don't design a heading scale and spacing system before building the page. Build the page, notice you're making the same kinds of adjustments ("make this heading bigger," "more space here"), and extract the patterns into tokens. The design system grows from real needs.
+
+**Don't design tokens upfront.** Build pages first. Extract patterns when they recur across 3+ pages.
+
+---
+
+## Tool Roles
+
+| Tool | Role | When |
+|------|------|------|
+| **Excalidraw** | Wireframes and layout iteration | Steps 3-4 |
+| **Puppeteer** | Browser screenshots for visual review | Step 7 |
+| **Nano Banana** | Image asset generation (photos, illustrations) | Asset creation only |
+| **Design tokens** | Heading scale, spacing scale, component tokens | Step 8 |
+| **Page specs** | Source of truth for structure and content | Steps 2, 5 |
+
+### 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 7), state the change in concrete terms:
+
+> "Changed hero top padding from 48px to 64px"
+
+Once design tokens exist (step 8), 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."
+
+---
+
+## When to Use This Loop
+
+**Full loop (all 8 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.

src/workflows/4-ux-design/steps-c/step-01-exploration.md

@@ -136,24 +136,28 @@ Walk me through:
 **Flow:**
 {{interaction_flow}}
 
-You're ready for next steps! Would you like to:
+You're ready to visualize! Would you like to:
 
-1. **I have a sketch** - You provide a sketch, I'll analyze it
-2. **Sketch it for me** - I create a wireframe in Excalidraw
-3. **Skip sketching** - Go directly to specification
-4. **Explore more** - Refine the concept further</output>
+1. **Wireframe it** (recommended) — I create an Excalidraw wireframe, we iterate together
+2. **I have a sketch** — You provide a sketch, I'll analyze it
+3. **Skip to spec** — Go directly to specification (for pages following established patterns)
+4. **Explore more** — Refine the concept further</output>
 
 <check if="choice == 1">
-  <output>Go sketch your concept and come back when ready. I'll analyze it with [K].</output>
-  <action>Update the page specification with exploration findings (fill empty sections, not a separate file)</action>
-  <action>Pause workflow - user will return to sketch analysis</action>
-</check>
-
-<check if="choice == 2">
   <action>Update the page specification with exploration findings (fill empty sections, not a separate file)</action>
   <action>BEFORE drawing: Read existing completed page specs AND their sketches to understand the established page structure — navigation, service menus, footer, card patterns, shared components. Do NOT draw from memory.</action>
   <action>Create wireframe in Excalidraw at page folder `Sketches/{page-slug}-wireframe.excalidraw`</action>
   <action>Wireframe must be CLEAN — no annotations, no labels outside the page area. Design decisions belong in the page specification, not on the sketch.</action>
+  <action>Present wireframe for review. The user can open the same .excalidraw file in VS Code and edit visually — both agent and user can modify the same artifact.</action>
+  <action>ITERATE: When user gives feedback, update the wireframe. This loop is fast — JSON manipulation, seconds per change. Repeat until agreed.</action>
+  <action>SYNC SPEC: When wireframe is agreed, update the page specification to match. The spec is the source of truth — never implement from wireframe directly.</action>
+  <output>See `data/guides/DESIGN-LOOP-GUIDE.md` for the full design loop reference.</output>
+</check>
+
+<check if="choice == 2">
+  <output>Go sketch your concept and come back when ready. I'll analyze it with [K].</output>
+  <action>Update the page specification with exploration findings (fill empty sections, not a separate file)</action>
+  <action>Pause workflow - user will return to sketch analysis</action>
 </check>
 
 <check if="choice == 3">
@@ -196,6 +200,7 @@ ONLY WHEN the user has completed their exploration and chosen a next action (ske
 - Interaction flow mapped verbally
 - Exploration findings saved to the page specification (not a separate file)
 - User chose next action with clear understanding
+- When wireframing: iterated with user until agreed, then synced spec to match
 
 ### ❌ SYSTEM FAILURE:
 
@@ -208,5 +213,7 @@ ONLY WHEN the user has completed their exploration and chosen a next action (ske
 - Saving exploration findings to a separate notes file instead of updating the page spec
 - Drawing wireframes with annotations or labels outside the page area
 - Drawing shared elements (nav, footer) from memory instead of reading existing specs
+- Implementing from wireframe without updating the spec first
+- Using AI image generators (Nano Banana) for wireframes instead of Excalidraw
 
 **Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

src/workflows/4-ux-design/workflow-conceptualize.md

@@ -33,6 +33,7 @@ Execute steps in `./steps-c/`:
 | 01 | step-01-exploration.md | Open-ended design exploration |
 
 **Reference data:**
+- `./data/guides/DESIGN-LOOP-GUIDE.md` — the 8-step design loop (discuss → wireframe → iterate → spec sync → implement → refine)
 - `./data/scenario-init/` — scenario initialization guides
 - `./data/page-creation-flows/` — page creation flow options
 

src/workflows/4-ux-design/workflow.md

@@ -117,7 +117,7 @@ If the scenario has a `design_intent` from Phase 3 handover, pre-select that act
 | Location | Purpose |
 |----------|---------|
 | `data/object-types/` | Component type definitions and templates |
-| `data/guides/` | Sketch analysis, specification patterns, styling |
+| `data/guides/` | Design loop, sketch analysis, specification patterns, styling |
 | `data/modular-architecture/` | Three-tier architecture documentation |
 | `data/scenario-init/` | Scenario initialization guides and examples |
 | `data/page-creation-flows/` | Page creation flow approaches |