Release v4.4.0: UI Design Workflow V3 - Layout/Style Separation Architecture

## Breaking Changes - **Command Renamed**: `extract` → `style-extract` - **New Required Phase**: `layout-extract` now mandatory before `generate` - **Workflow Changed**: Old flow (extract → consolidate → generate) → New flow (style-extract → consolidate → layout-extract → generate) ## Added **New Command: layout-extract** - Extract structural layout separate from visual style - Agent-powered with ui-design-agent - Dual-mode: imitate (high-fidelity) / explore (multiple variants) - Device-aware: desktop, mobile, tablet, responsive - MCP-integrated layout pattern research (explore mode) - Output: layout-templates.json with DOM structure + CSS layout rules **Enhanced Architecture** - Layout/Style Separation: Clear responsibility boundaries - Pure Assembler: generate command combines pre-extracted components - Device-Aware Layouts: Optimized structures for different devices - Token-Based CSS: var() placeholders for spacing/breakpoints ## Changed **style-extract (Renamed from extract)** - File renamed: extract.md → style-extract.md - Scope clarified: Visual style only (colors, typography, spacing) - No functionality change, all features preserved **generate (Refactored to Pure Assembler)** - Before: Agent designed layout + applied style - After: Pure assembly - combines layout-templates.json + design-tokens.json - No design logic: All decisions made in previous phases - Simplified agent instructions: Focus on assembly only **Workflow Commands Updated** - imitate-auto: Added Phase 2.5 (layout extraction) - explore-auto: Added Phase 2.5 (layout extraction) - Both workflows now include layout-extract step ## Removed - ❌ V2 Commands: generate-v2, explore-auto-v2 (merged into main commands) - ❌ Old extract command (renamed to style-extract) - ❌ ui-generate-preview-v2.sh (merged into ui-generate-preview.sh) ## Files Changed - Renamed: extract.md → style-extract.md - Added: layout-extract.md (370+ lines) - Modified: generate.md, imitate-auto.md, explore-auto.md, consolidate.md - Removed: 2 deprecated v2 command files - Updated: CHANGELOG.md, README.md ## Benefits - ✅ Single Responsibility: Each phase has one clear job - ✅ Better Layout Variety: Explore mode generates structurally distinct layouts - ✅ Reusability: Layout templates work with any style - ✅ Clarity: All structural decisions visible in layout-templates.json - ✅ Testability: Layout structure and visual style tested independently 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-11 02:33:51 +08:00 · 2025-10-11 16:21:28 +08:00
parent 3857aa44ce
commit 7c8e75f363
9 changed files with 1071 additions and 284 deletions
--- a/.claude/commands/workflow/ui-design/consolidate.md
+++ b/.claude/commands/workflow/ui-design/consolidate.md
@@ -13,7 +13,7 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(*)
 # Design System Consolidation Command

 ## Overview
-Consolidate style variants into independent production-ready design systems. Refines raw token proposals from `extract` into finalized design tokens and style guides.
+Consolidate style variants into independent production-ready design systems. Refines raw token proposals from `style-extract` into finalized design tokens and style guides.

 **Strategy**: Philosophy-Driven Refinement
 - **Agent-Driven**: Uses ui-design-agent for N variant generation
@@ -246,7 +246,7 @@ bash(ls -lh {base_path}/style-consolidation/style-1/)
 ### Common Errors
 ```
 ERROR: No style cards found
-→ Run /workflow:ui-design:extract first
+→ Run /workflow:ui-design:style-extract first

 ERROR: Invalid variant count
 → List available count, auto-select all
@@ -265,6 +265,8 @@ ERROR: Agent file creation failed

 ## Integration

-**Input**: `style-cards.json` from `/workflow:ui-design:extract`
+**Input**: `style-cards.json` from `/workflow:ui-design:style-extract`
 **Output**: `style-consolidation/style-{N}/` for each variant
-**Next**: `/workflow:ui-design:generate --style-variants N --targets "..."`
+**Next**: `/workflow:ui-design:generate --style-variants N`
+
+**Note**: After consolidate, use `/workflow:ui-design:layout-extract` to generate layout templates before running generate.
--- a/.claude/commands/workflow/ui-design/explore-auto.md
+++ b/.claude/commands/workflow/ui-design/explore-auto.md
@@ -27,9 +27,10 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 2. Phase 0c: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 1**
 3. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues
 4. Phase 2 (style-consolidate) → **WAIT for completion** → Auto-continues
-5. **Phase 3 (ui-generate)** → **WAIT for completion** → Auto-continues
-6. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
-7. Phase 5 (batch-plan, optional) → Reports completion
+5. Phase 2.5 (layout-extract) → **WAIT for completion** → Auto-continues
+6. **Phase 3 (ui-assembly)** → **WAIT for completion** → Auto-continues
+7. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
+8. Phase 5 (batch-plan, optional) → Reports completion

 **Phase Transition Mechanism**:
 - **Phase 0c (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 1
@@ -274,7 +275,7 @@ detect_target_type(target_list):

 ### Phase 1: Style Extraction
 ```bash
-command = "/workflow:ui-design:extract --base-path \"{base_path}\" " +
+command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " +
          (--images ? "--images \"{images}\" " : "") +
          (--prompt ? "--prompt \"{prompt}\" " : "") +
          "--mode explore --variants {style_variants}"
@@ -293,33 +294,50 @@ SlashCommand(command)

 # Output: {style_variants} independent design systems with tokens.css
 # SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 2.5 (auto-continue)
+```
+
+### Phase 2.5: Layout Extraction
+```bash
+targets_string = ",".join(inferred_target_list)
+command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " +
+          (--images ? "--images \"{images}\" " : "") +
+          (--prompt ? "--prompt \"{prompt}\" " : "") +
+          "--targets \"{targets_string}\" " +
+          "--mode explore --variants {layout_variants} " +
+          "--device-type \"{device_type}\""
+
+REPORT: "🚀 Phase 2.5: Layout Extraction (explore mode)"
+REPORT: "   → Targets: {targets_string}"
+REPORT: "   → Layout variants: {layout_variants}"
+REPORT: "   → Device: {device_type}"
+
+SlashCommand(command)
+
+# Output: layout-templates.json with {targets × layout_variants} layout structures
+# SlashCommand blocks until phase complete
 # Upon completion, IMMEDIATELY execute Phase 3 (auto-continue)
 ```

-### Phase 3: Style-Centric Matrix UI Generation
+### Phase 3: UI Assembly
 ```bash
-targets_string = ",".join(inferred_target_list)
 command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
-          "--targets \"{targets_string}\" --target-type \"{target_type}\" " +
-          "--style-variants {style_variants} --layout-variants {layout_variants} " +
-          "--device-type \"{device_type}\""
+          "--style-variants {style_variants} --layout-variants {layout_variants}"

 total = style_variants × layout_variants × len(inferred_target_list)
-agent_calls = style_variants

-REPORT: "🚀 Phase 3: {type_icon} {targets_string} | Matrix: {s}×{l}×{n} = {total} prototypes"
-REPORT: "   → Device: {device_type}"
-REPORT: "   → Agent calls: {agent_calls} style-centric agents"
-REPORT: "   → Layout planning: {len(inferred_target_list)}×{layout_variants} target-specific layouts"
-REPORT: "   → Style-centric generation: Each of {style_variants} agents handles {layout_variants}×{len(inferred_target_list)} combinations"
+REPORT: "🚀 Phase 3: UI Assembly | Matrix: {s}×{l}×{n} = {total} prototypes"
+REPORT: "   → Pure assembly: Combining layout templates + design tokens"
+REPORT: "   → Device: {device_type} (from layout templates)"
+REPORT: "   → Assembly tasks: {total} combinations"

 SlashCommand(command)

 # SlashCommand blocks until phase complete
 # Upon completion, IMMEDIATELY execute Phase 4 (auto-continue)
 # Output:
-# - {target}-layout-{l}.json (target-specific layout plans)
-# - {target}-style-{s}-layout-{l}.html (final prototypes with style-aware structure)
+# - {target}-style-{s}-layout-{l}.html (assembled prototypes)
+# - {target}-style-{s}-layout-{l}.css
 # - compare.html (interactive matrix view)
 # - PREVIEW.md (usage instructions)
 ```
@@ -349,7 +367,8 @@ IF --batch-plan:
 TodoWrite({todos: [
  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
  {"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing..."},
-  {"content": "Execute style-centric UI generation", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing..."},
  {"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."}
 ]})

@@ -429,33 +448,34 @@ Architecture: Style-Centric Batch Generation
 Run ID: {run_id} | Session: {session_id or "standalone"}
 Type: {icon} {target_type} | Device: {device_type} | Matrix: {s}×{l}×{n} = {total} prototypes

-Phase 1: {s} style variants with design_attributes (extract)
+Phase 1: {s} style variants with design_attributes (style-extract)
 Phase 2: {s} design systems with tokens.css (consolidate)
-Phase 3: Style-centric batch generation (generate)
+Phase 2.5: {n×l} layout templates (layout-extract explore mode)
  - Device: {device_type} layouts
-  - {n}×{l} target-specific layout plans
-  - {s} style-centric agents (each handled {l}×{n} combinations)
-  - {s}×{l}×{n} = {total} final prototypes with style-aware structure
+  - {n} targets × {l} layout variants = {n×l} structural templates
+Phase 3: UI Assembly (generate)
+  - Pure assembly: layout templates + design tokens
+  - {s}×{l}×{n} = {total} final prototypes
 Phase 4: Brainstorming artifacts updated
 [Phase 5: {n} implementation tasks created]  # if --batch-plan

-Agent Execution:
-✅ Style-centric agents: {s} agents total
-✅ Each agent handles: {l}×{n} combinations
-✅ Device-optimized: {device_type} layouts
+Assembly Process:
+✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate
+✅ Layout Extraction: {n×l} reusable structural templates
+✅ Pure Assembly: No design decisions in generate phase
+✅ Device-Optimized: Layouts designed for {device_type}

 Design Quality:
-✅ Style-Aware Structure: HTML adapts to design_attributes
-✅ Style Consistency: PERFECT (each style by single agent)
 ✅ Token-Driven Styling: 100% var() usage
+✅ Structural Variety: {l} distinct layouts per target
+✅ Style Variety: {s} independent design systems
 ✅ Device-Optimized: Layouts designed for {device_type}

 📂 {base_path}/
  ├── style-extraction/       ({s} style cards + design-space-analysis.json)
  ├── style-consolidation/    ({s} design systems with tokens.css)
-  ├── prototypes/
-  │   ├── _templates/         ({n}×{l} layout JSON files)
-  │   └── ...                 ({total} final prototypes)
+  ├── layout-extraction/      ({n×l} layout templates + layout-space-analysis.json)
+  ├── prototypes/             ({total} assembled prototypes)
  └── .run-metadata.json      (includes device type)

 🌐 Preview: {base_path}/prototypes/compare.html
--- a/.claude/commands/workflow/ui-design/generate.md
+++ b/.claude/commands/workflow/ui-design/generate.md
@@ -1,27 +1,29 @@
 ---
 name: generate
-description: Generate UI prototypes using target-style-centric batch generation
-usage: /workflow:ui-design:generate [--targets "<list>"] [--target-type "page|component"] [--device-type "desktop|mobile|tablet|responsive"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
+description: Assemble UI prototypes by combining layout templates with design tokens (pure assembler)
+usage: /workflow:ui-design:generate [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
 examples:
-  - /workflow:ui-design:generate --session WFS-auth --targets "dashboard,settings"
-  - /workflow:ui-design:generate --targets "home,pricing" --style-variants 2 --layout-variants 2
-  - /workflow:ui-design:generate --targets "app" --device-type mobile
-  - /workflow:ui-design:generate --targets "dashboard" --device-type desktop
+  - /workflow:ui-design:generate --session WFS-auth
+  - /workflow:ui-design:generate --style-variants 2 --layout-variants 2
+  - /workflow:ui-design:generate --base-path ".workflow/WFS-auth/design-run-20250109-143022"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
 ---

 # Generate UI Prototypes (/workflow:ui-design:generate)

 ## Overview
-Generate matrix of UI prototypes (`style × layout × targets`) using **target-style-centric batch generation**. Each agent handles all layouts for one target × style combination.
+Pure assembler that combines pre-extracted layout templates with design tokens to generate UI prototypes (`style × layout × targets`). No layout design logic - purely combines existing components.

-**Strategy**: Target-Style-Centric
- **Agent scope**: Each of `T × S` agents generates `L` layouts
- **Component isolation**: Complete task independence
- **Style-aware**: HTML adapts to design_attributes
- **Self-contained CSS**: Direct token values (no var() refs)
+**Strategy**: Pure Assembly
+- **Input**: `layout-templates.json` + `design-tokens.json`
+- **Process**: Combine structure (DOM) with style (tokens)
+- **Output**: Complete HTML/CSS prototypes
+- **No Design Logic**: All layout and style decisions already made

-**Supports**: Pages (full layouts) and components (isolated elements)
+**Prerequisite Commands**:
+- `/workflow:ui-design:style-extract` → Style tokens
+- `/workflow:ui-design:consolidate` → Final design tokens
+- `/workflow:ui-design:layout-extract` → Layout structure

 ## Phase 1: Setup & Validation

@@ -30,135 +32,90 @@ Generate matrix of UI prototypes (`style × layout × targets`) using **target-s
 # Determine working directory
 bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect

-# Get counts (defaults: style=auto, layout=3)
+# Get style count
 bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
-
-# Parse targets (Priority: --targets → --pages → synthesis-specification.md → default ["home"])
-# Target type: "page" (default) or "component"
-
-# Parse device type
-device_type = --device-type OR "responsive"  # Default: responsive
-
-# Try to load from .run-metadata.json if exists
-IF exists({base_path}/.run-metadata.json):
-    metadata = Read({base_path}/.run-metadata.json)
-    IF metadata.parameters.device_type:
-        device_type = metadata.parameters.device_type
 ```

-### Step 2: Validate Inputs
+### Step 2: Load Layout Templates
 ```bash
-# Check design systems exist
+# Check layout templates exist
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+
+# Load layout templates
+Read({base_path}/layout-extraction/layout-templates.json)
+# Extract: targets, layout_variants count, device_type, template structures
+```
+
+**Output**: `base_path`, `style_variants`, `layout_templates[]`, `targets[]`, `device_type`
+
+### Step 3: Validate Design Tokens
+```bash
+# Check design tokens exist for all styles
 bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")

-# Validate target names (lowercase, alphanumeric, hyphens only)
-# Load design-space-analysis.json (optional, for style-aware generation)
+# For each style variant: Load design tokens
+Read({base_path}/style-consolidation/style-{id}/design-tokens.json)
 ```

-**Output**: `base_path`, `style_variants`, `layout_variants`, `target_list[]`, `target_type`, `design_space_analysis` (optional), `device_type`
+**Output**: `design_tokens[]` for all style variants

-### Step 3: Detect Token Sources
-```bash
-# Priority 1: consolidated tokens (production-ready from /workflow:ui-design:consolidate)
-# Priority 2: proposed tokens from style-cards.json (fast-track from /workflow:ui-design:extract)
+## Phase 2: Assembly (Agent)

-bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "consolidated")
-# OR
-bash(test -f {base_path}/style-extraction/style-cards.json && echo "proposed")
+**Executor**: `Task(ui-design-agent)` × `T × S × L` tasks (can be batched)

-# If proposed: Create temp consolidation dir + write proposed tokens
-bash(mkdir -p {base_path}/style-consolidation/style-{id})
-Write({base_path}/style-consolidation/style-{id}/design-tokens.json, proposed_tokens)
-```
-
-**Output**: `token_sources{}`, `consolidated_count`, `proposed_count`
-
-### Step 4: Gather Layout Inspiration
-```bash
-bash(mkdir -p {base_path}/prototypes/_inspirations)
-
-# For each target: Research via MCP
-# mcp__exa__web_search_exa(query="{target} {target_type} layout patterns", numResults=5)
-
-# Write simple inspiration file
-Write({base_path}/prototypes/_inspirations/{target}-layout-ideas.txt, inspiration_content)
-```
-
-**Output**: `L` inspiration text files
-
-## Phase 2: Target-Style-Centric Generation (Agent)
-
-**Executor**: `Task(ui-design-agent)` × `T × S` tasks in parallel
-
-### Step 1: Launch Agent Tasks
+### Step 1: Launch Assembly Tasks
 ```bash
 bash(mkdir -p {base_path}/prototypes)
 ```

-For each `target × style_id`:
+For each `target × style_id × layout_id`:
 ```javascript
 Task(ui-design-agent): `
-  [TARGET_STYLE_UI_GENERATION]
-  🎯 ONE component: {target} × Style-{style_id} ({philosophy_name})
-  Generate: {layout_variants} × 2 files (HTML + CSS per layout)
+  [LAYOUT_STYLE_ASSEMBLY]
+  🎯 Assembly task: {target} × Style-{style_id} × Layout-{layout_id}
+  Combine: Pre-extracted layout structure + design tokens → Final HTML/CSS

-  TARGET: {target} | TYPE: {target_type} | STYLE: {style_id}/{style_variants}
+  TARGET: {target} | STYLE: {style_id} | LAYOUT: {layout_id}
  BASE_PATH: {base_path}
-  DEVICE: {device_type}
-  ${design_attributes ? "DESIGN_ATTRIBUTES: " + JSON.stringify(design_attributes) : ""}

-  ## Reference
-  - Layout inspiration: Read("{base_path}/prototypes/_inspirations/{target}-layout-ideas.txt")
-  - Design tokens: Read("{base_path}/style-consolidation/style-{style_id}/design-tokens.json")
-    Parse ALL token values (colors, typography, spacing, borders, shadows, breakpoints)
-  ${design_attributes ? "- Adapt DOM structure to: density, visual_weight, formality, organic_vs_geometric" : ""}
+  ## Inputs (READ ONLY - NO DESIGN DECISIONS)
+  1. Layout Template:
+     Read("{base_path}/layout-extraction/layout-templates.json")
+     Find template where: target={target} AND variant_id="layout-{layout_id}"
+     Extract: dom_structure, css_layout_rules, device_type

-  ## Generation
-  For EACH layout (1 to {layout_variants}):
+  2. Design Tokens:
+     Read("{base_path}/style-consolidation/style-{style_id}/design-tokens.json")
+     Extract: ALL token values (colors, typography, spacing, borders, shadows, breakpoints)

-  1. HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-N.html
-     - Complete HTML5: <!DOCTYPE>, <head>, <body>
-     - CSS ref: <link href="{target}-style-{style_id}-layout-N.css">
-     - Semantic: <header>, <nav>, <main>, <footer>
-     - A11y: ARIA labels, landmarks, responsive meta
-     - Viewport meta: <meta name="viewport" content="width=device-width, initial-scale=1.0">
-     ${design_attributes ? `
-     - DOM adaptation:
-       * density='spacious' → flatter hierarchy
-       * density='compact' → deeper nesting
-       * visual_weight='heavy' → extra wrappers
-       * visual_weight='minimal' → direct structure` : ""}
-     - Device-specific structure:
-       * mobile (375×812px): Single column, stacked sections, touch targets ≥44px
-       * desktop (1920×1080px): Multi-column grids, hover states, larger hit areas
-       * tablet (768×1024px): Hybrid layouts, flexible columns
-       * responsive: Breakpoint-driven adaptive layouts (mobile-first)
+  ## Assembly Process
+  1. Build HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html
+     - Recursively build from template.dom_structure
+     - Add: <!DOCTYPE html>, <head>, <meta viewport>
+     - CSS link: <link href="{target}-style-{style_id}-layout-{layout_id}.css">
+     - Inject placeholder content (Lorem ipsum, sample data)
+     - Preserve all attributes from dom_structure

-  2. CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-N.css
-     - Self-contained: Direct token VALUES (no var())
-     - Use tokens: colors, fonts, spacing, borders, shadows
-     - Device-optimized styles for {device_type}
-     ${device_type === 'responsive' ? '- Responsive: Mobile-first @media(breakpoints)' : '- Fixed device: Optimize for ' + device_type}
-     ${design_attributes ? `
-     - Token selection:
-       * density → spacing scale
-       * visual_weight → shadow strength
-       * organic_vs_geometric → border-radius` : ""}
-     - Device-specific CSS:
-       * mobile: Compact spacing, touch-friendly
-       * desktop: Generous whitespace, hover effects
-       * tablet: Medium spacing, flexible grids
-       * responsive: Fluid typography, breakpoints
+  2. Build CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.css
+     - Start with template.css_layout_rules
+     - Replace ALL var(--*) with actual token values from design-tokens.json
+       Example: var(--spacing-4) → 1rem (from tokens.spacing.4)
+       Example: var(--breakpoint-md) → 768px (from tokens.breakpoints.md)
+     - Add visual styling using design tokens:
+       * Colors: tokens.colors.*
+       * Typography: tokens.typography.*
+       * Shadows: tokens.shadows.*
+       * Border radius: tokens.border_radius.*
+     - Device-optimized for template.device_type

-  ## Notes
-  - ✅ Use token VALUES directly from design-tokens.json
-  - ✅ Optimize for {device_type} device
-  - ❌ NO var() references, NO external dependencies
-  - Layouts structurally DISTINCT (different grids/regions)
-  - Write files IMMEDIATELY (per layout, no accumulation)
+  ## Assembly Rules
+  - ✅ Pure assembly: Combine existing structure + existing style
+  - ❌ NO layout design decisions (structure pre-defined)
+  - ❌ NO style design decisions (tokens pre-defined)
+  - ✅ Replace var() with actual values
+  - ✅ Add placeholder content only
+  - Write files IMMEDIATELY
  - CSS filename MUST match HTML <link href="...">
-  - No text output, write to filesystem only
-  - Device-first approach: Design specifically for {device_type} user experience
 `
 ```

@@ -199,8 +156,8 @@ bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {b
 ```javascript
 TodoWrite({todos: [
  {content: "Setup and validation", status: "completed", activeForm: "Loading design systems"},
-  {content: "Gather layout inspiration", status: "completed", activeForm: "Researching layouts"},
-  {content: "Target-style generation (agent)", status: "completed", activeForm: "Generating prototypes"},
+  {content: "Load layout templates", status: "completed", activeForm: "Reading layout templates"},
+  {content: "Assembly (agent)", status: "completed", activeForm: "Assembling prototypes"},
  {content: "Verify files", status: "completed", activeForm: "Validating output"},
  {content: "Generate previews", status: "completed", activeForm: "Creating preview files"}
 ]});
@@ -208,32 +165,30 @@ TodoWrite({todos: [

 ### Output Message
 ```
-✅ Target-Style-Centric UI generation complete!
+✅ UI prototype assembly complete!

 Configuration:
 - Style Variants: {style_variants}
- Layout Variants: {layout_variants} (inspiration-based)
- Target Type: {target_type}
+- Layout Variants: {layout_variants} (from layout-templates.json)
 - Device Type: {device_type}
- Targets: {target_list}
+- Targets: {targets}
 - Total Prototypes: {S × L × T}

-Agent Execution:
- Target-style agents: T×S = {T}×{S} = {T×S} agents
- Each agent scope: {L} layouts for one component
- Component isolation: Complete task independence
- Device-specific: All layouts optimized for {device_type}
+Assembly Process:
+- Pure assembly: Combined pre-extracted layouts + design tokens
+- No design decisions: All structure and style pre-defined
+- Assembly tasks: T×S×L = {T}×{S}×{L} = {T×S×L} combinations

 Quality:
- Style-aware: {design_space_analysis ? 'HTML adapts to design_attributes' : 'Standard structure'}
- CSS: Self-contained (direct token values, no var())
- Device-optimized: {device_type} layouts
- Tokens: {consolidated_count} consolidated, {proposed_count} proposed
-{IF proposed_count > 0: '  💡 For production: /workflow:ui-design:consolidate'}
+- Structure: From layout-extract (DOM, CSS layout rules)
+- Style: From consolidate (design tokens)
+- CSS: Token values directly applied (var() replaced)
+- Device-optimized: Layouts match device_type from templates

 Generated Files:
 {base_path}/prototypes/
-├── _inspirations/ ({T} text files)
+├── _templates/
+│   └── layout-templates.json (input, pre-extracted)
 ├── {target}-style-{s}-layout-{l}.html ({S×L×T} prototypes)
 ├── {target}-style-{s}-layout-{l}.css
 ├── compare.html (interactive matrix)
@@ -257,14 +212,13 @@ bash(find .workflow -type d -name "design-*" | head -1)

 # Count style variants
 bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
-
-# Check token sources
-bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "consolidated")
-bash(test -f {base_path}/style-extraction/style-cards.json && echo "proposed")
 ```

 ### Validation Commands
 ```bash
+# Check layout templates exist
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+
 # Check design tokens exist
 bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")

@@ -278,7 +232,7 @@ bash(test -f {base_path}/prototypes/compare.html && echo "exists")
 ### File Operations
 ```bash
 # Create directories
-bash(mkdir -p {base_path}/prototypes/_inspirations)
+bash(mkdir -p {base_path}/prototypes)

 # Run preview script
 bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
@@ -288,63 +242,68 @@ bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")

 ```
 {base_path}/
-├── prototypes/
-│   ├── _inspirations/
-│   │   └── {target}-layout-ideas.txt  # Layout inspiration
-│   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
-│   ├── {target}-style-{s}-layout-{l}.css
-│   ├── compare.html
-│   ├── index.html
-│   └── PREVIEW.md
-└── style-consolidation/
-    └── style-{s}/
-        ├── design-tokens.json
-        └── style-guide.md
+├── layout-extraction/
+│   └── layout-templates.json      # Input (from layout-extract)
+├── style-consolidation/
+│   └── style-{s}/
+│       ├── design-tokens.json     # Input (from consolidate)
+│       └── style-guide.md
+└── prototypes/
+    ├── {target}-style-{s}-layout-{l}.html  # Assembled prototypes
+    ├── {target}-style-{s}-layout-{l}.css
+    ├── compare.html
+    ├── index.html
+    └── PREVIEW.md
 ```

 ## Error Handling

 ### Common Errors
 ```
-ERROR: No token sources found
-→ Run /workflow:ui-design:extract or /workflow:ui-design:consolidate
+ERROR: Layout templates not found
+→ Run /workflow:ui-design:layout-extract first

-ERROR: MCP search failed
-→ Check network, retry
+ERROR: Design tokens not found
+→ Run /workflow:ui-design:consolidate first

-ERROR: Agent task failed
-→ Check agent output, retry specific target×style
+ERROR: Agent assembly failed
+→ Check inputs exist, validate JSON structure

 ERROR: Script permission denied
 → chmod +x ~/.claude/scripts/ui-generate-preview.sh
 ```

 ### Recovery Strategies
- **Partial success**: Keep successful target×style combinations
- **Missing design_attributes**: Works without (less style-aware)
+- **Partial success**: Keep successful assembly combinations
+- **Invalid template structure**: Validate layout-templates.json
 - **Invalid tokens**: Validate design-tokens.json structure

 ## Quality Checklist

- [ ] CSS uses direct token values (no var())
- [ ] HTML structure adapts to design_attributes (if available)
- [ ] Semantic HTML5 structure
- [ ] ARIA attributes present
- [ ] Mobile-first responsive
- [ ] Layouts structurally distinct
+- [ ] CSS uses direct token values (var() replaced)
+- [ ] HTML structure matches layout template exactly
+- [ ] Semantic HTML5 structure preserved
+- [ ] ARIA attributes from template present
+- [ ] Device-specific optimizations applied
+- [ ] All token references resolved
 - [ ] compare.html works

 ## Key Features

- **Target-Style-Centric**: `T×S` agents, each handles `L` layouts
- **Component Isolation**: Complete task independence
- **Style-Aware**: HTML adapts to design_attributes
- **Self-Contained CSS**: Direct token values (no var())
- **Inspiration-Based**: Simple text research vs complex JSON
- **Production-Ready**: Semantic, accessible, responsive
+- **Pure Assembly**: No design decisions, only combination
+- **Separation of Concerns**: Layout (structure) + Style (tokens) kept separate until final assembly
+- **Token Resolution**: var() placeholders replaced with actual values
+- **Pre-validated**: Inputs already validated by extract/consolidate
+- **Efficient**: Simple assembly vs complex generation
+- **Production-Ready**: Semantic, accessible, token-driven

 ## Integration

-**Input**: design-tokens.json, design-space-analysis.json (optional), targets
+**Prerequisites**:
+- `/workflow:ui-design:style-extract` → `style-cards.json`
+- `/workflow:ui-design:consolidate` → `design-tokens.json`
+- `/workflow:ui-design:layout-extract` → `layout-templates.json`
+
+**Input**: `layout-templates.json` + `design-tokens.json`
 **Output**: S×L×T prototypes for `/workflow:ui-design:update`
 **Called by**: `/workflow:ui-design:explore-auto`, `/workflow:ui-design:imitate-auto`
--- a/.claude/commands/workflow/ui-design/imitate-auto.md
+++ b/.claude/commands/workflow/ui-design/imitate-auto.md
@@ -25,10 +25,11 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 1. User triggers: `/workflow:ui-design:imitate-auto --url-map "..."`
 2. Phase 0: Initialize and parse parameters
 3. Phase 1: Screenshot capture (batch or deep mode) → **WAIT for completion** → Auto-continues
-4. Phase 2: Unified design system extraction → **WAIT for completion** → Auto-continues
-5. Phase 3: Token processing (conditional consolidate) → **WAIT for completion** → Auto-continues
-6. Phase 4: Batch UI generation → **WAIT for completion** → Auto-continues
-7. Phase 5: Design system integration → Reports completion
+4. Phase 2: Style extraction (visual tokens) → **WAIT for completion** → Auto-continues
+5. Phase 2.5: Layout extraction (structure templates) → **WAIT for completion** → Auto-continues
+6. Phase 3: Token processing (conditional consolidate) → **WAIT for completion** → Auto-continues
+7. Phase 4: Batch UI assembly → **WAIT for completion** → Auto-continues
+8. Phase 5: Design system integration → Reports completion

 **Phase Transition Mechanism**:
 - `SlashCommand` is BLOCKING - execution pauses until completion
@@ -231,9 +232,10 @@ REPORT: ""
 TodoWrite({todos: [
  {content: "Initialize and parse url-map", status: "completed", activeForm: "Initializing"},
  {content: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})", status: "pending", activeForm: "Capturing screenshots"},
-  {content: "Extract unified design system", status: "pending", activeForm: "Extracting style"},
+  {content: "Extract style (visual tokens)", status: "pending", activeForm: "Extracting style"},
+  {content: "Extract layout (structure templates)", status: "pending", activeForm: "Extracting layout"},
  {content: refine_tokens_mode ? "Refine design tokens via consolidate" : "Fast token adaptation (skip consolidate)", status: "pending", activeForm: "Processing tokens"},
-  {content: f"Generate UI for {len(target_names)} targets", status: "pending", activeForm: "Generating UI"},
+  {content: f"Assemble UI for {len(target_names)} targets", status: "pending", activeForm: "Assembling UI"},
  {content: session_id ? "Integrate design system" : "Standalone completion", status: "pending", activeForm: "Completing"}
 ]})
 ```
@@ -335,15 +337,15 @@ ELSE:  # capture_mode == "deep"
    total_requested = captured_count  # For consistency with batch mode

 TodoWrite(mark_completed: f"Batch screenshot capture ({len(target_names)} targets)" IF capture_mode == "batch" ELSE f"Deep exploration (depth {depth})",
-          mark_in_progress: "Extract unified design system")
+          mark_in_progress: "Extract style (visual tokens)")
 ```

-### Phase 2: Unified Design System Extraction
+### Phase 2: Style Extraction (Visual Tokens)

 ```bash
 REPORT: ""
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 2: Extract Unified Design System"
+REPORT: "🚀 Phase 2: Extract Style (Visual Tokens)"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

 # Use all screenshots as input to extract single design system
@@ -355,14 +357,14 @@ ELSE:  # deep mode
 # Build extraction prompt
 IF --prompt:
    user_guidance = {--prompt}
-    extraction_prompt = f"Extract a single, high-fidelity design system that accurately imitates the visual style from the '{primary_target}' page. Use other screenshots for component consistency. User guidance: {user_guidance}"
+    extraction_prompt = f"Extract visual style tokens (colors, typography, spacing) from the '{primary_target}' page. Use other screenshots for consistency. User guidance: {user_guidance}"
 ELSE:
-    extraction_prompt = f"Extract a single, high-fidelity design system that accurately imitates the visual style from the '{primary_target}' page. Use other screenshots to ensure component and pattern consistency across all pages."
+    extraction_prompt = f"Extract visual style tokens (colors, typography, spacing) from the '{primary_target}' page. Use other screenshots for consistency across all pages."

-# Call extract command (imitate mode, automatically uses single variant)
-extract_command = f"/workflow:ui-design:extract --base-path \"{base_path}\" --images \"{images_glob}\" --prompt \"{extraction_prompt}\" --mode imitate"
+# Call style-extract command (imitate mode, automatically uses single variant)
+extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --prompt \"{extraction_prompt}\" --mode imitate"

-REPORT: "Calling extract command..."
+REPORT: "Calling style-extract command..."
 REPORT: f"  Mode: imitate (high-fidelity single style, auto variants=1)"
 REPORT: f"  Primary source: '{primary_target}'"
 REPORT: f"  Images: {images_glob}"
@@ -371,16 +373,16 @@ TRY:
    SlashCommand(extract_command)
 CATCH error:
    ERROR: "Style extraction failed: {error}"
-    ERROR: "Cannot proceed without design system"
+    ERROR: "Cannot proceed without visual tokens"
    EXIT 1

-# extract outputs to: {base_path}/style-extraction/style-cards.json
+# style-extract outputs to: {base_path}/style-extraction/style-cards.json

 # Verify extraction results
 style_cards_path = "{base_path}/style-extraction/style-cards.json"

 IF NOT exists(style_cards_path):
-    ERROR: "extract command did not generate style-cards.json"
+    ERROR: "style-extract command did not generate style-cards.json"
    ERROR: "Expected: {style_cards_path}"
    EXIT 1

@@ -396,9 +398,58 @@ REPORT: ""
 REPORT: "✅ Phase 2 complete:"
 REPORT: "   Style: '{extracted_style.name}'"
 REPORT: "   Philosophy: {extracted_style.design_philosophy}"
-REPORT: "   Tokens: {count_tokens(extracted_style.proposed_tokens)} proposed tokens"
+REPORT: "   Tokens: {count_tokens(extracted_style.proposed_tokens)} visual tokens"

-TodoWrite(mark_completed: "Extract unified design system",
+TodoWrite(mark_completed: "Extract style (visual tokens)",
+          mark_in_progress: "Extract layout (structure templates)")
+```
+
+### Phase 2.5: Layout Extraction (Structure Templates)
+
+```bash
+REPORT: ""
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 Phase 2.5: Extract Layout (Structure Templates)"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Reuse same screenshots for layout extraction
+# Build URL map for layout-extract (uses first URL from each target)
+url_map_for_layout = ",".join([f"{target}:{url}" for target, url in url_map.items()])
+
+# Call layout-extract command (imitate mode for structure replication)
+layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --targets \"{','.join(target_names)}\" --mode imitate"
+
+REPORT: "Calling layout-extract command..."
+REPORT: f"  Mode: imitate (high-fidelity structure replication)"
+REPORT: f"  Targets: {', '.join(target_names)}"
+REPORT: f"  Images: {images_glob}"
+
+TRY:
+    SlashCommand(layout_extract_command)
+CATCH error:
+    ERROR: "Layout extraction failed: {error}"
+    ERROR: "Cannot proceed without layout templates"
+    EXIT 1
+
+# layout-extract outputs to: {base_path}/layout-extraction/layout-templates.json
+
+# Verify layout extraction results
+layout_templates_path = "{base_path}/layout-extraction/layout-templates.json"
+
+IF NOT exists(layout_templates_path):
+    ERROR: "layout-extract command did not generate layout-templates.json"
+    ERROR: "Expected: {layout_templates_path}"
+    EXIT 1
+
+layout_templates = Read(layout_templates_path)
+template_count = len(layout_templates.layout_templates)
+
+REPORT: ""
+REPORT: "✅ Phase 2.5 complete:"
+REPORT: "   Templates: {template_count} layout structures"
+REPORT: "   Targets: {', '.join(target_names)}"
+
+TodoWrite(mark_completed: "Extract layout (structure templates)",
          mark_in_progress: refine_tokens_mode ? "Refine design tokens via consolidate" : "Fast token adaptation")
 ```

@@ -507,53 +558,53 @@ REPORT: "   Quality: {token_quality}"
 REPORT: "   Time: {time_spent_estimate}"

 TodoWrite(mark_completed: refine_tokens_mode ? "Refine design tokens via consolidate" : "Fast token adaptation",
-          mark_in_progress: f"Generate UI for {len(target_names)} targets")
+          mark_in_progress: f"Assemble UI for {len(target_names)} targets")
 ```

-### Phase 4: Batch UI Generation
+### Phase 4: Batch UI Assembly

 ```bash
 REPORT: ""
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 4: Batch UI Generation"
+REPORT: "🚀 Phase 4: Batch UI Assembly"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

 # Build targets string
 targets_string = ",".join(target_names)

-# Call generate command (smart token source detection will auto-select tokens)
-generate_command = f"/workflow:ui-design:generate --base-path \"{base_path}\" --targets \"{targets_string}\" --target-type page --style-variants 1 --layout-variants 1"
+# Call generate command (now pure assembler - combines layout templates + design tokens)
+generate_command = f"/workflow:ui-design:generate --base-path \"{base_path}\" --style-variants 1 --layout-variants 1"

-REPORT: "Calling generate command..."
-REPORT: f"  Targets: {targets_string}"
+REPORT: "Calling generate command (pure assembler)..."
+REPORT: f"  Targets: {targets_string} (from layout templates)"
 REPORT: f"  Configuration: 1 style × 1 layout × {len(target_names)} pages"
-REPORT: f"  Token source: generate will auto-detect ({token_quality})"
+REPORT: f"  Inputs: layout-templates.json + design-tokens.json"

 TRY:
    SlashCommand(generate_command)
 CATCH error:
-    ERROR: "UI generation failed: {error}"
-    ERROR: "Design tokens may be invalid"
+    ERROR: "UI assembly failed: {error}"
+    ERROR: "Layout templates or design tokens may be invalid"
    EXIT 1

 # generate outputs to: {base_path}/prototypes/{target}-style-1-layout-1.html

-# Verify generation results
+# Verify assembly results
 prototypes_dir = "{base_path}/prototypes"
 generated_html_files = Glob(f"{prototypes_dir}/*-style-1-layout-1.html")
 generated_count = len(generated_html_files)

 REPORT: ""
 REPORT: "✅ Phase 4 complete:"
-REPORT: "   Generated: {generated_count} HTML prototypes"
+REPORT: "   Assembled: {generated_count} HTML prototypes"
 REPORT: "   Targets: {', '.join(target_names)}"
 REPORT: "   Output: {prototypes_dir}/"

 IF generated_count < len(target_names):
-    WARN: "   ⚠️ Expected {len(target_names)} prototypes, generated {generated_count}"
+    WARN: "   ⚠️ Expected {len(target_names)} prototypes, assembled {generated_count}"
    WARN: "   Some targets may have failed - check generate output"

-TodoWrite(mark_completed: f"Generate UI for {len(target_names)} targets",
+TodoWrite(mark_completed: f"Assemble UI for {len(target_names)} targets",
          mark_in_progress: session_id ? "Integrate design system" : "Standalone completion")
 ```

--- a/.claude/commands/workflow/ui-design/layout-extract.md
+++ b/.claude/commands/workflow/ui-design/layout-extract.md
@@ -0,0 +1,371 @@
+---
+name: layout-extract
+description: Extract structural layout information from reference images, URLs, or text prompts
+usage: /workflow:ui-design:layout-extract [--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]
+examples:
+  - /workflow:ui-design:layout-extract --urls "home:https://linear.app" --mode imitate --targets "home"
+  - /workflow:ui-design:layout-extract --images "refs/*.png" --mode explore --variants 3 --targets "dashboard"
+  - /workflow:ui-design:layout-extract --prompt "Two-column blog with sticky sidebar" --mode explore --variants 2 --targets "blog-post"
+  - /workflow:ui-design:layout-extract --session WFS-auth --urls "login:https://clerk.dev" --device-type mobile --targets "login"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
+---
+
+# Layout Extraction Command
+
+## Overview
+Extract structural layout information from reference images, URLs, or text prompts using AI analysis. This command separates the "scaffolding" (HTML structure and CSS layout) from the "paint" (visual tokens handled by `style-extract`).
+
+**Strategy**: AI-Driven Structural Analysis
+- **Agent-Powered**: Uses `ui-design-agent` for deep structural analysis
+- **Dual-Mode**:
+  - `imitate`: High-fidelity replication of single layout structure
+  - `explore`: Multiple structurally distinct layout variations
+- **Single Output**: `layout-templates.json` with DOM structure, component hierarchy, and CSS layout rules
+- **Device-Aware**: Optimized for specific device types (desktop, mobile, tablet, responsive)
+- **Token-Based**: CSS uses `var()` placeholders for spacing and breakpoints
+
+## Phase 0: Setup & Input Validation
+
+### Step 1: Detect Input, Mode & Targets
+```bash
+# Detect input source
+# Priority: --urls + --images → hybrid | --urls → url | --images → image | --prompt → text
+
+# Determine extraction mode
+extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
+
+# Set variants count based on mode
+IF extraction_mode == "imitate":
+    variants_count = 1  # Force single variant (ignore --variants)
+ELSE IF extraction_mode == "explore":
+    variants_count = --variants OR 3  # Default to 3
+    VALIDATE: 1 <= variants_count <= 5
+
+# Resolve targets
+# Priority: --targets → prompt analysis → default ["page"]
+targets = --targets OR extract_from_prompt(--prompt) OR ["page"]
+
+# Resolve device type
+device_type = --device-type OR "responsive"  # desktop|mobile|tablet|responsive
+
+# Determine base path
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# OR use --base-path / --session parameters
+```
+
+### Step 2: Load Inputs & Create Directories
+```bash
+# For image mode
+bash(ls {images_pattern})  # Expand glob pattern
+Read({image_path})  # Load each image
+
+# For URL mode
+# Parse URL list format: "target:url,target:url"
+# Validate URLs are accessible
+
+# For text mode
+# Validate --prompt is non-empty
+
+# Create output directory
+bash(mkdir -p {base_path}/layout-extraction)
+```
+
+### Step 3: Memory Check (Skip if Already Done)
+```bash
+# Check if layouts already extracted
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+```
+
+**If exists**: Skip to completion message
+
+**Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `targets[]`, `device_type`, loaded inputs
+
+## Phase 1: Layout Research (Explore Mode Only)
+
+### Step 1: Check Extraction Mode
+```bash
+# extraction_mode == "imitate" → skip this phase
+# extraction_mode == "explore" → execute this phase
+```
+
+**If imitate mode**: Skip to Phase 2
+
+### Step 2: Gather Layout Inspiration (Explore Mode)
+```bash
+bash(mkdir -p {base_path}/layout-extraction/_inspirations)
+
+# For each target: Research via MCP
+# mcp__exa__web_search_exa(query="{target} layout patterns {device_type}", numResults=5)
+
+# Write inspiration file
+Write({base_path}/layout-extraction/_inspirations/{target}-layout-ideas.txt, inspiration_content)
+```
+
+**Output**: Inspiration text files for each target (explore mode only)
+
+## Phase 2: Layout Analysis & Synthesis (Agent)
+
+**Executor**: `Task(ui-design-agent)`
+
+### Step 1: Launch Agent Task
+```javascript
+Task(ui-design-agent): `
+  [LAYOUT_EXTRACTION_TASK]
+  Analyze references and extract structural layout templates.
+  Focus ONLY on structure and layout. DO NOT concern with visual style (colors, fonts, etc.).
+
+  REFERENCES:
+  - Input: {reference_material}  // Images, URLs, or prompt
+  - Mode: {extraction_mode}  // 'imitate' or 'explore'
+  - Targets: {targets}  // List of page/component names
+  - Variants per Target: {variants_count}
+  - Device Type: {device_type}
+  ${exploration_mode ? "- Layout Inspiration: Read('" + base_path + "/layout-extraction/_inspirations/{target}-layout-ideas.txt')" : ""}
+
+  ## Analysis & Generation
+  For EACH target in {targets}:
+    For EACH variant (1 to {variants_count}):
+      1. **Analyze Structure**: Deconstruct reference to understand layout, hierarchy, responsiveness
+      2. **Define Philosophy**: Short description (e.g., "Asymmetrical grid with overlapping content areas")
+      3. **Generate DOM Structure**: JSON object representing semantic HTML5 structure
+         - Semantic tags: <header>, <nav>, <main>, <aside>, <section>, <footer>
+         - ARIA roles and accessibility attributes
+         - Device-specific structure:
+           * mobile: Single column, stacked sections, touch targets ≥44px
+           * desktop: Multi-column grids, hover states, larger hit areas
+           * tablet: Hybrid layouts, flexible columns
+           * responsive: Breakpoint-driven adaptive layouts (mobile-first)
+         - In 'explore' mode: Each variant structurally DISTINCT
+      4. **Define Component Hierarchy**: High-level array of main layout regions
+         Example: ["header", "main-content", "sidebar", "footer"]
+      5. **Generate CSS Layout Rules**:
+         - Focus ONLY on layout (Grid, Flexbox, position, alignment, gap, etc.)
+         - Use CSS Custom Properties for spacing/breakpoints: var(--spacing-4), var(--breakpoint-md)
+         - Device-specific styles (mobile-first @media for responsive)
+         - NO colors, NO fonts, NO shadows - layout structure only
+
+  ## Output Format
+  Return JSON object with layout_templates array.
+  Each template must include:
+  - target (string)
+  - variant_id (string, e.g., "layout-1")
+  - device_type (string)
+  - design_philosophy (string)
+  - dom_structure (JSON object)
+  - component_hierarchy (array of strings)
+  - css_layout_rules (string)
+
+  ## Notes
+  - Structure only, no visual styling
+  - Use var() for all spacing/sizing
+  - Layouts must be structurally distinct in explore mode
+  - Write complete layout-templates.json
+`
+```
+
+**Output**: Agent returns JSON with `layout_templates` array
+
+### Step 2: Write Output File
+```bash
+# Take JSON output from agent
+bash(echo '{agent_json_output}' > {base_path}/layout-extraction/layout-templates.json)
+
+# Verify output
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+bash(cat {base_path}/layout-extraction/layout-templates.json | grep -q "layout_templates" && echo "valid")
+```
+
+**Output**: `layout-templates.json` created and verified
+
+## Completion
+
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
+  {content: "Layout research (explore mode)", status: "completed", activeForm: "Researching layout patterns"},
+  {content: "Layout analysis and synthesis (agent)", status: "completed", activeForm: "Generating layout templates"},
+  {content: "Write layout-templates.json", status: "completed", activeForm: "Saving templates"}
+]});
+```
+
+### Output Message
+```
+✅ Layout extraction complete!
+
+Configuration:
+- Session: {session_id}
+- Extraction Mode: {extraction_mode} (imitate/explore)
+- Device Type: {device_type}
+- Targets: {targets}
+- Variants per Target: {variants_count}
+- Total Templates: {targets.length × variants_count}
+
+{IF extraction_mode == "explore":
+Layout Research:
+- {targets.length} inspiration files generated
+- Pattern search focused on {device_type} layouts
+}
+
+Generated Templates:
+{FOR each template: - Target: {template.target} | Variant: {template.variant_id} | Philosophy: {template.design_philosophy}}
+
+Output File:
+- {base_path}/layout-extraction/layout-templates.json
+
+Next: /workflow:ui-design:generate will combine these structural templates with style systems to produce final prototypes.
+```
+
+## Simple Bash Commands
+
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Create output directories
+bash(mkdir -p {base_path}/layout-extraction)
+bash(mkdir -p {base_path}/layout-extraction/_inspirations)  # explore mode only
+```
+
+### Validation Commands
+```bash
+# Check if already extracted
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+
+# Validate JSON structure
+bash(cat layout-templates.json | grep -q "layout_templates" && echo "valid")
+
+# Count templates
+bash(cat layout-templates.json | grep -c "\"target\":")
+```
+
+### File Operations
+```bash
+# Load image references
+bash(ls {images_pattern})
+Read({image_path})
+
+# Write inspiration files (explore mode)
+Write({base_path}/layout-extraction/_inspirations/{target}-layout-ideas.txt, content)
+
+# Write layout templates
+bash(echo '{json}' > {base_path}/layout-extraction/layout-templates.json)
+```
+
+## Output Structure
+
+```
+{base_path}/
+└── layout-extraction/
+    ├── layout-templates.json         # Structural layout templates
+    ├── layout-space-analysis.json    # Layout directions (explore mode only)
+    └── _inspirations/                 # Explore mode only
+        └── {target}-layout-ideas.txt  # Layout inspiration research
+```
+
+## layout-templates.json Format
+
+```json
+{
+  "extraction_metadata": {
+    "session_id": "...",
+    "input_mode": "image|url|prompt|hybrid",
+    "extraction_mode": "imitate|explore",
+    "device_type": "desktop|mobile|tablet|responsive",
+    "timestamp": "...",
+    "variants_count": 3,
+    "targets": ["home", "dashboard"]
+  },
+  "layout_templates": [
+    {
+      "target": "home",
+      "variant_id": "layout-1",
+      "device_type": "responsive",
+      "design_philosophy": "Responsive 3-column holy grail layout with fixed header and footer",
+      "dom_structure": {
+        "tag": "body",
+        "children": [
+          {
+            "tag": "header",
+            "attributes": {"class": "layout-header"},
+            "children": [{"tag": "nav"}]
+          },
+          {
+            "tag": "div",
+            "attributes": {"class": "layout-main-wrapper"},
+            "children": [
+              {"tag": "main", "attributes": {"class": "layout-main-content"}},
+              {"tag": "aside", "attributes": {"class": "layout-sidebar-left"}},
+              {"tag": "aside", "attributes": {"class": "layout-sidebar-right"}}
+            ]
+          },
+          {"tag": "footer", "attributes": {"class": "layout-footer"}}
+        ]
+      },
+      "component_hierarchy": [
+        "header",
+        "main-content",
+        "sidebar-left",
+        "sidebar-right",
+        "footer"
+      ],
+      "css_layout_rules": ".layout-main-wrapper { display: grid; grid-template-columns: 1fr 3fr 1fr; gap: var(--spacing-6); } @media (max-width: var(--breakpoint-md)) { .layout-main-wrapper { grid-template-columns: 1fr; } }"
+    }
+  ]
+}
+```
+
+**Requirements**: Token-based CSS (var()), semantic HTML5, device-specific structure, accessibility attributes
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: No inputs provided
+→ Provide --images, --urls, or --prompt
+
+ERROR: Invalid target name
+→ Use lowercase, alphanumeric, hyphens only
+
+ERROR: Agent task failed
+→ Check agent output, retry with simplified prompt
+
+ERROR: MCP search failed (explore mode)
+→ Check network, retry
+```
+
+### Recovery Strategies
+- **Partial success**: Keep successfully extracted templates
+- **Invalid JSON**: Retry with stricter format requirements
+- **Missing inspiration**: Works without (less informed exploration)
+
+## Key Features
+
+- **Separation of Concerns** - Decouples layout (structure) from style (visuals)
+- **Structural Exploration** - Explore mode enables A/B testing of different layouts
+- **Token-Based Layout** - CSS uses `var()` placeholders for instant design system adaptation
+- **Device-Specific** - Tailored structures for different screen sizes
+- **Foundation for Assembly** - Provides structural blueprint for refactored `generate` command
+- **Agent-Powered** - Deep structural analysis with AI
+
+## Integration
+
+**Workflow Position**: Between style extraction and prototype generation
+
+**New Workflow**:
+1. `/workflow:ui-design:style-extract` → `style-cards.json` (Visual tokens)
+2. `/workflow:ui-design:consolidate` → `design-tokens.json` (Final visual system)
+3. `/workflow:ui-design:layout-extract` → `layout-templates.json` (Structural templates)
+4. `/workflow:ui-design:generate` (Refactored as assembler):
+   - **Reads**: `design-tokens.json` + `layout-templates.json`
+   - **Action**: For each style × layout combination:
+     1. Build HTML from `dom_structure`
+     2. Create layout CSS from `css_layout_rules`
+     3. Link design tokens CSS
+     4. Inject placeholder content
+   - **Output**: Complete token-driven HTML/CSS prototypes
+
+**Input**: Reference images, URLs, or text prompts
+**Output**: `layout-templates.json` for `/workflow:ui-design:generate`
+**Next**: `/workflow:ui-design:generate --session {session_id}`
--- a/.claude/commands/workflow/ui-design/style-extract.md
+++ b/.claude/commands/workflow/ui-design/style-extract.md
@@ -1,13 +1,13 @@
 ---
-name: extract
+name: style-extract
 description: Extract design style from reference images or text prompts using Claude's analysis
-usage: /workflow:ui-design:extract [--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]
+usage: /workflow:ui-design:style-extract [--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]
 examples:
-  - /workflow:ui-design:extract --images "design-refs/*.png" --mode explore --variants 3
-  - /workflow:ui-design:extract --prompt "Modern minimalist blog, dark theme" --mode explore --variants 3
-  - /workflow:ui-design:extract --session WFS-auth --images "refs/*.png" --prompt "Linear.app style" --mode imitate
-  - /workflow:ui-design:extract --base-path ".workflow/WFS-auth/design-run-20250109-143022" --images "refs/*.png" --mode explore --variants 3
-  - /workflow:ui-design:extract --prompt "Bold vibrant" --mode imitate  # High-fidelity single style
+  - /workflow:ui-design:style-extract --images "design-refs/*.png" --mode explore --variants 3
+  - /workflow:ui-design:style-extract --prompt "Modern minimalist blog, dark theme" --mode explore --variants 3
+  - /workflow:ui-design:style-extract --session WFS-auth --images "refs/*.png" --prompt "Linear.app style" --mode imitate
+  - /workflow:ui-design:style-extract --base-path ".workflow/WFS-auth/design-run-20250109-143022" --images "refs/*.png" --mode explore --variants 3
+  - /workflow:ui-design:style-extract --prompt "Bold vibrant" --mode imitate  # High-fidelity single style
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
 ---

@@ -271,5 +271,7 @@ ERROR: Claude JSON parsing error
 ## Integration

 **Input**: Reference images or text prompts
-**Output**: `style-cards.json` for `/workflow:ui-design:consolidate`
+**Output**: `style-cards.json` for consolidation
 **Next**: `/workflow:ui-design:consolidate --session {session_id} --variants {count}`
+
+**Note**: This command only extracts visual style (colors, typography, spacing). For layout structure extraction, use `/workflow:ui-design:layout-extract`.
--- a/.claude/scripts/ui-generate-preview-v2.sh
+++ b/.claude/scripts/ui-generate-preview-v2.sh
@@ -4,7 +4,7 @@
 # Purpose: Generate compare.html and index.html using template substitution
 # Template: ~/.claude/workflows/_template-compare-matrix.html
 #
-# Usage: ui-generate-preview-v2.sh <prototypes_dir> [--template <path>]
+# Usage: ui-generate-preview.sh <prototypes_dir> [--template <path>]
 #

 set -e