Claude-Code-Workflow/.claude/commands/workflow/ui-design/layout-extract.md

---
name: layout-extract
description: Extract structural layout information from reference images or text prompts using Claude analysis with variant generation or refinement mode
argument-hint: [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestion(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
---

# Layout Extraction Command

## Overview

Extract structural layout information from reference images or text prompts using AI analysis. Supports two modes:
1. **Exploration Mode** (default): Generate multiple contrasting layout variants
2. **Refinement Mode** (`--refine`): Refine a single existing layout through detailed adjustments

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**: Exploration (multiple contrasting variants) or Refinement (single layout fine-tuning)
- **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

## Execution Process

```
Input Parsing:
   ├─ Parse flags: --design-id, --session, --images, --prompt, --targets, --variants, --device-type, --interactive, --refine
   └─ Decision (mode detection):
      ├─ --refine flag → Refinement Mode (variants_count = 1)
      └─ No --refine → Exploration Mode (variants_count = --variants OR 3)

Phase 0: Setup & Input Validation
   ├─ Step 1: Detect input, mode & targets
   ├─ Step 2: Load inputs & create directories
   └─ Step 3: Memory check (skip if cached)

Phase 1: Layout Concept/Refinement Options Generation
   ├─ Step 0.5: Load existing layout (Refinement Mode only)
   ├─ Step 1: Generate options (Agent Task 1)
   │  └─ Decision:
   │     ├─ Exploration Mode → Generate contrasting layout concepts
   │     └─ Refinement Mode → Generate refinement options
   └─ Step 2: Verify options file created

Phase 1.5: User Confirmation (Optional)
   └─ Decision (--interactive flag):
      ├─ --interactive present → Present options, capture selection
      └─ No --interactive → Skip to Phase 2

Phase 2: Layout Template Generation
   ├─ Step 1: Load user selections or default to all
   ├─ Step 2: Launch parallel agent tasks
   └─ Step 3: Verify output files
```

## Phase 0: Setup & Input Validation

### Step 1: Detect Input, Mode & Targets

```bash
# Detect input source
# Priority: --images → image | --prompt → text

# Detect refinement mode
refine_mode = --refine OR false

# Set variants count
# Refinement mode: Force variants_count = 1 (ignore user-provided --variants)
# Exploration mode: Use --variants or default to 3 (range: 1-5)
IF refine_mode:
    variants_count = 1
    REPORT: "🔧 Refinement mode enabled: Will generate 1 refined layout per target"
ELSE:
    variants_count = --variants OR 3
    VALIDATE: 1 <= variants_count <= 5
    REPORT: "🔍 Exploration mode: Will generate {variants_count} contrasting layout concepts per target"

# Resolve targets
# Priority: --targets → prompt analysis → default ["page"]
IF --targets:
    targets = split(--targets, ",")
ELSE IF --prompt:
    # Extract targets from prompt using pattern matching
    # Looks for keywords: "page names", target descriptors (login, dashboard, etc.)
    # Returns lowercase, hyphenated strings (e.g., ["login", "dashboard"])
    targets = extract_from_prompt(--prompt)
ELSE:
    targets = ["page"]

# Resolve device type
device_type = --device-type OR "responsive"  # desktop|mobile|tablet|responsive

# Determine base path with priority: --design-id > --session > auto-detect
if [ -n "$DESIGN_ID" ]; then
  # Exact match by design ID
  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
elif [ -n "$SESSION_ID" ]; then
  # Latest in session
  relative_path=$(find .workflow/active/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
else
  # Latest globally
  relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
fi

# Validate and convert to absolute path
if [ -z "$relative_path" ] || [ ! -d "$relative_path" ]; then
  echo "❌ ERROR: Design run not found"
  echo "💡 HINT: Run '/workflow:ui-design:list' to see available design runs"
  exit 1
fi

base_path=$(cd "$relative_path" && pwd)
bash(echo "✓ Base path: $base_path")
```

### Step 2: Load Inputs & Create Directories
```bash
# For image mode
bash(ls {images_pattern})  # Expand glob pattern
Read({image_path})  # Load each image

# For text mode
# Validate --prompt is non-empty

# Create output directory
bash(mkdir -p {base_path}/layout-extraction)
```

### Step 3: Memory Check
```bash
# 1. Check if inputs cached in session memory
IF session_has_inputs: SKIP Step 2 file reading

# 2. Check if output already exists
bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists")
IF exists: SKIP to completion
```

---

**Phase 0 Output**: `input_mode`, `base_path`, `variants_count`, `targets[]`, `device_type`, loaded inputs

## Phase 1: Layout Concept or Refinement Options Generation

### Step 0.5: Load Existing Layout (Refinement Mode)
```bash
IF refine_mode:
    # Load existing layout for refinement
    existing_layouts = {}
    FOR target IN targets:
        layout_files = bash(find {base_path}/layout-extraction -name "layout-{target}-*.json" -print)
        IF layout_files:
            # Use first/latest layout file for this target
            existing_layouts[target] = Read(first_layout_file)
```

### Step 1: Generate Options (Agent Task 1 - Mode-Specific)
**Executor**: `Task(ui-design-agent)`

**Exploration Mode** (default): Generate contrasting layout concepts
**Refinement Mode** (`--refine`): Generate refinement options for existing layouts

```javascript
// Conditional agent task based on refine_mode
IF NOT refine_mode:
    // EXPLORATION MODE
    Task(ui-design-agent): `
      [LAYOUT_CONCEPT_GENERATION_TASK]
      Generate {variants_count} structurally distinct layout concepts for each target

      SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
      TARGETS: {targets} | DEVICE_TYPE: {device_type}

      ## Input Analysis
      - Targets: {targets.join(", ")}
      - Device type: {device_type}
      - Visual references: {loaded_images if available}
      ${dom_structure_available ? "- DOM Structure: Read from .intermediates/layout-analysis/dom-structure-*.json" : ""}

      ## Analysis Rules
      - For EACH target, generate {variants_count} structurally DIFFERENT layout concepts
      - Concepts must differ in: grid structure, component arrangement, visual hierarchy
  - Each concept should have distinct navigation pattern, content flow, and responsive behavior

  ## Generate for EACH Target
  For target in {targets}:
    For concept_index in 1..{variants_count}:
      1. **Concept Definition**:
         - concept_name (descriptive, e.g., "Classic Three-Column Holy Grail")
         - design_philosophy (1-2 sentences explaining the structural approach)
         - layout_pattern (e.g., "grid-3col", "flex-row", "single-column", "asymmetric-grid")
         - key_components (array of main layout regions)
         - structural_features (list of distinguishing characteristics)

      2. **Wireframe Preview** (simple text representation):
         - ascii_art (simple ASCII box diagram showing layout structure)
         - Example:
           ┌─────────────────┐
           │     HEADER      │
           ├──┬─────────┬────┤
           │ L│  MAIN   │ R  │
           └──┴─────────┴────┘

  ## Output
  Write single JSON file: {base_path}/.intermediates/layout-analysis/analysis-options.json

  Use schema from INTERACTIVE-DATA-SPEC.md (Layout Extract: analysis-options.json)

  CRITICAL: Use Write() tool immediately after generating complete JSON
    `
ELSE:
    // REFINEMENT MODE
    Task(ui-design-agent): `
      [LAYOUT_REFINEMENT_OPTIONS_TASK]
      Generate refinement options for existing layout(s)

      SESSION: {session_id} | MODE: refine | BASE_PATH: {base_path}
      TARGETS: {targets} | DEVICE_TYPE: {device_type}

      ## Existing Layouts
      ${FOR target IN targets: "- {target}: {existing_layouts[target]}"}

      ## Input Guidance
      - User prompt: {prompt_guidance if available}
      - Visual references: {loaded_images if available}

      ## Refinement Categories
      Generate 8-12 refinement options per target across these categories:

      1. **Density Adjustments** (2-3 options per target):
         - More compact: Tighter spacing, reduced whitespace
         - More spacious: Increased margins, breathing room
         - Balanced: Moderate adjustments

      2. **Responsiveness Tuning** (2-3 options per target):
         - Breakpoint behavior: Earlier/later column stacking
         - Mobile layout: Different navigation/content priority
         - Tablet optimization: Hybrid desktop/mobile approach

      3. **Grid/Flex Specifics** (2-3 options per target):
         - Column counts: 2-col ↔ 3-col ↔ 4-col
         - Gap sizes: Tighter ↔ wider gutters
         - Alignment: Different flex/grid justification

      4. **Component Arrangement** (1-2 options per target):
         - Navigation placement: Top ↔ side ↔ bottom
         - Sidebar position: Left ↔ right ↔ none
         - Content hierarchy: Different section ordering

      ## Output Format
      Each option (per target):
      - target: Which target this refinement applies to
      - category: "density|responsiveness|grid|arrangement"
      - option_id: unique identifier
      - label: Short descriptive name (e.g., "More Compact Spacing")
      - description: What changes (2-3 sentences)
      - preview_changes: Key structural adjustments
      - impact_scope: Which layout regions affected

      ## Output
      Write single JSON file: {base_path}/.intermediates/layout-analysis/analysis-options.json

      Use refinement schema:
      {
        "mode": "refinement",
        "device_type": "{device_type}",
        "refinement_options": {
          "{target1}": [array of refinement options],
          "{target2}": [array of refinement options]
        }
      }

      CRITICAL: Use Write() tool immediately after generating complete JSON
    `
```

### Step 2: Verify Options File Created
```bash
bash(test -f {base_path}/.intermediates/layout-analysis/analysis-options.json && echo "created")

# Quick validation
bash(cat {base_path}/.intermediates/layout-analysis/analysis-options.json | grep -q "layout_concepts" && echo "valid")
```

**Output**: `analysis-options.json` with layout concept options for all targets

---

## Phase 1.5: User Confirmation (Optional - Triggered by --interactive)

**Purpose**:
- **Exploration Mode**: Allow user to select preferred layout concept(s) per target
- **Refinement Mode**: Allow user to select refinement options to apply per target

**Trigger Condition**: Execute this phase ONLY if `--interactive` flag is present

### Step 1: Check Interactive Flag
```bash
# Skip this entire phase if --interactive flag is not present
IF NOT --interactive:
    SKIP to Phase 2
    IF refine_mode:
        REPORT: "ℹ️ Non-interactive refinement mode: Will apply all suggested refinements"
    ELSE:
        REPORT: "ℹ️ Non-interactive mode: Will generate all {variants_count} variants per target"

# Interactive mode enabled
REPORT: "🎯 Interactive mode: User selection required for {targets.length} target(s)"
```

### Step 2: Load and Present Options (Mode-Specific)
```bash
# Read options file
options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)

# Branch based on mode
IF NOT refine_mode:
    # EXPLORATION MODE
    layout_concepts = options.layout_concepts
ELSE:
    # REFINEMENT MODE
    refinement_options = options.refinement_options
```

### Step 2: Present Options to User (Per Target)
For each target, present layout concept options and capture selection:

```
📋 Layout Concept Options for Target: {target}

We've generated {variants_count} structurally different layout concepts for review.
Please select your preferred concept for this target.

{FOR each concept in layout_concepts[target]:
  ═══════════════════════════════════════════════════
  Concept {concept.index}: {concept.concept_name}
  ═══════════════════════════════════════════════════

  Philosophy: {concept.design_philosophy}
  Pattern: {concept.layout_pattern}

  Components:
  {FOR each component in concept.key_components:
    • {component}
  }

  Features:
  {FOR each feature in concept.structural_features:
    • {feature}
  }

  Wireframe:
  {concept.wireframe_preview.ascii_art}

  ═══════════════════════════════════════════════════
}
```

### Step 3: Capture User Selection and Update Options File (Per Target)

**Interaction Strategy**: If total concepts > 4 OR any target has > 3 concepts, use batch text format:

```
【目标[N] - [target]】选择布局方案
[key]) Concept [index]: [concept_name]
   [design_philosophy]
[key]) Concept [index]: [concept_name]
   [design_philosophy]
...
请回答 (格式: 1a 2b 或 1a,b 2c 多选)：

User input:
  "[N][key] [N][key] ..." → Single selection per target
  "[N][key1,key2] [N][key3] ..." → Multi-selection per target
```

Otherwise, use `AskUserQuestion` below.

```javascript
// Use AskUserQuestion tool for each target (multi-select enabled)
FOR each target:
  AskUserQuestion({
    questions: [{
      question: "Which layout concept(s) do you prefer for '{target}'?",
      header: "Layout for " + target,
      multiSelect: true,  // Multi-selection enabled (default behavior)
      options: [
        {FOR each concept in layout_concepts[target]:
          label: "Concept {concept.index}: {concept.concept_name}",
          description: "{concept.design_philosophy}"
        }
      ]
    }]
  })

  // Parse user response (array of selections)
  selected_options = user_answer

  // Check for user cancellation
  IF selected_options == null OR selected_options.length == 0:
      REPORT: "⚠️ User canceled selection. Workflow terminated."
      EXIT workflow

  // Extract concept indices from array
  selected_indices = []
  FOR each selected_option_text IN selected_options:
      match = selected_option_text.match(/Concept (\d+):/)
      IF match:
          selected_indices.push(parseInt(match[1]))
      ELSE:
          ERROR: "Invalid selection format. Expected 'Concept N: ...' format"
          EXIT workflow

  // Store selections for this target (array of indices)
  selections[target] = {
    selected_indices: selected_indices,  // Array of selected indices
    concept_names: selected_indices.map(i => layout_concepts[target][i-1].concept_name)
  }

  REPORT: "✅ Selected {selected_indices.length} layout(s) for {target}"

// Calculate total selections across all targets
total_selections = sum([len(selections[t].selected_indices) for t in targets])

// Update analysis-options.json with user selection (embedded in same file)
options_file = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
options_file.user_selection = {
  "selected_at": "{current_timestamp}",
  "selection_type": "per_target_multi",
  "session_id": "{session_id}",
  "total_selections": total_selections,
  "selected_variants": selections  // {target: {selected_indices: [...], concept_names: [...]}}
}

// Write updated file back
Write({base_path}/.intermediates/layout-analysis/analysis-options.json, JSON.stringify(options_file, indent=2))
```

### Step 4: Confirmation Message
```
✅ Selections recorded! Total: {total_selections} layout(s)

{FOR each target, selection in selections:
  • {target}: {selection.selected_indices.length} layout(s) selected
    {FOR each index IN selection.selected_indices:
      - Concept {index}: {layout_concepts[target][index-1].concept_name}
    }
}

Proceeding to generate {total_selections} detailed layout template(s)...
```

**Output**: `analysis-options.json` updated with embedded `user_selection` field

## Phase 2: Layout Template Generation (Agent Task 2)

**Executor**: `Task(ui-design-agent)` × `Total_Selected_Templates` in **parallel**

### Step 1: Load User Selections or Default to All
```bash
# Read analysis-options.json which may contain user_selection
options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
layout_concepts = options.layout_concepts

# Check if user_selection field exists (interactive mode)
IF options.user_selection AND options.user_selection.selected_variants:
    # Interactive mode: Use user-selected variants
    selections_per_target = options.user_selection.selected_variants
    total_selections = options.user_selection.total_selections
ELSE:
    # Non-interactive mode: Generate ALL variants for ALL targets (default behavior)
    selections_per_target = {}
    total_selections = 0

    FOR each target in targets:
        selections_per_target[target] = {
            "selected_indices": [1, 2, ..., variants_count],  # All indices
            "concept_names": []  # Will be filled from options
        }
        total_selections += variants_count

# Build task list for all selected concepts across all targets
task_list = []
FOR each target in targets:
    selected_indices = selections_per_target[target].selected_indices  # Array
    concept_names = selections_per_target[target].concept_names        # Array

    FOR i in range(len(selected_indices)):
        idx = selected_indices[i]
        concept = layout_concepts[target][idx - 1]  # 0-indexed array
        variant_id = i + 1  # 1-based variant numbering

        task_list.push({
            target: target,
            variant_id: variant_id,
            concept: concept,
            output_file: "{base_path}/layout-extraction/layout-{target}-{variant_id}.json"
        })

total_tasks = task_list.length
REPORT: "Generating {total_tasks} layout templates across {targets.length} targets"
```

### Step 2: Launch Parallel Agent Tasks
Generate layout templates for ALL selected concepts in parallel:
```javascript
FOR each task in task_list:
    Task(ui-design-agent): `
      [LAYOUT_TEMPLATE_GENERATION_TASK #{task.variant_id} for {task.target}]
      Generate detailed layout template based on user-selected concept.
      Focus ONLY on structure and layout. DO NOT concern with visual style (colors, fonts, etc.).

      SESSION: {session_id} | BASE_PATH: {base_path}
      TARGET: {task.target} | VARIANT: {task.variant_id}
      DEVICE_TYPE: {device_type}

      USER SELECTION:
      - Selected Concept: {task.concept.concept_name}
      - Philosophy: {task.concept.design_philosophy}
      - Pattern: {task.concept.layout_pattern}
      - Key Components: {task.concept.key_components.join(", ")}
      - Structural Features: {task.concept.structural_features.join(", ")}

      ## Input Analysis
      - Target: {task.target}
      - Device type: {device_type}
      - Visual references: {loaded_images if available}
      ${dom_structure_available ? "- DOM Structure Data: Read from .intermediates/layout-analysis/dom-structure-{task.target}.json - USE THIS for accurate layout properties" : ""}

      ## Generation Rules
      - Develop the user-selected layout concept into a detailed template
      - Use the selected concept's key_components as foundation
      - Apply the selected layout_pattern (grid-3col, flex-row, etc.)
      - Honor the structural_features defined in the concept
      - Expand the concept with complete DOM structure and CSS layout rules
      ${dom_structure_available ? `
      - IMPORTANT: You have access to real DOM structure data with accurate flex/grid properties
      - Use DOM data as primary source for layout properties
      - Extract real flex/grid configurations (display, flexDirection, justifyContent, alignItems, gap)
      - Use actual element bounds for responsive breakpoint decisions
      - Preserve identified patterns from DOM structure
      ` : ""}

      ## Template Generation

      1. **DOM Structure**:
         - Semantic HTML5 tags: <header>, <nav>, <main>, <aside>, <section>, <footer>
         - ARIA roles and accessibility attributes
         - Use key_components from selected concept
         ${dom_structure_available ? "- Base on extracted DOM tree from .intermediates" : "- Infer from visual analysis"}
         - Device-specific optimizations for {device_type}

      2. **Component Hierarchy**:
         - Array of main layout regions
         - Derived from selected concept's key_components

      3. **CSS Layout Rules**:
         - Implement selected layout_pattern
         ${dom_structure_available ? "- Use real layout properties from DOM structure data" : "- Focus on Grid, Flexbox, position, alignment"}
         - Use CSS Custom Properties: var(--spacing-*), var(--breakpoint-*)
         - Device-specific styles (mobile-first @media for responsive)
         - NO colors, NO fonts, NO shadows - layout structure only

      ## Output Files

      Generate 2 files:

      1. **layout-templates.json** - {task.output_file}
         Write single-template JSON object with:
         - target: "{task.target}"
         - variant_id: "layout-{task.variant_id}"
         - source_image_path (string): Reference image path
         - device_type: "{device_type}"
         - design_philosophy (string from selected concept)
         - dom_structure (JSON object)
         - component_hierarchy (array of strings)
         - css_layout_rules (string)

      ## Critical Requirements
      - ✅ Use Write() tool to generate JSON file
      - ✅ Single template for {task.target} variant {task.variant_id}
      - ✅ Structure only, no visual styling
      - ✅ Token-based CSS (var())
      - ✅ Can use Exa MCP to research modern layout patterns and obtain code examples (Explore/Text mode)
      - ✅ Maintain consistency with selected concept
    `
```

**Output**: Agent generates multiple layout template files (one per selected concept)

### Step 3: Verify Output Files
```bash
# Count generated files
expected_count = total_tasks
actual_count = bash(ls {base_path}/layout-extraction/layout-*.json | wc -l)

# Verify all files were created
IF actual_count == expected_count:
    REPORT: "✓ All {expected_count} layout template files generated"
ELSE:
    ERROR: "Expected {expected_count} files, found {actual_count}"

# Verify file structure (sample check)
bash(cat {base_path}/layout-extraction/layout-{first_target}-1.json | grep -q "variant_id" && echo "valid structure")
```

**Output**: All layout template files created and verified (one file per selected concept)

## Completion

### Todo Update
```javascript
TodoWrite({todos: [
  {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
  {content: "Layout concept analysis (agent)", status: "completed", activeForm: "Analyzing layout patterns"},
  {content: "User selection confirmation", status: "completed", activeForm: "Confirming selections"},
  {content: "Generate layout templates (parallel)", status: "completed", activeForm: "Generating templates"},
  {content: "Verify output files", status: "completed", activeForm: "Verifying files"}
]});
```

### Output Message
```
✅ Layout extraction complete!

Configuration:
- Session: {session_id}
- Device Type: {device_type}
- Targets: {targets.join(", ")}
- Total Templates: {total_tasks} ({targets.length} targets with multi-selection)

User Selections:
{FOR each target in targets:
- {target}: {selections_per_target[target].concept_names.join(", ")} ({selections_per_target[target].selected_indices.length} variants)
}

Generated Templates:
{base_path}/layout-extraction/
{FOR each target in targets:
  {FOR each variant_id in range(1, selections_per_target[target].selected_indices.length + 1):
    └── layout-{target}-{variant_id}.json
  }
}

Intermediate Files:
- {base_path}/.intermediates/layout-analysis/
  └── analysis-options.json (concept proposals + user selections embedded)

Next: /workflow:ui-design:generate will combine these structural templates with design systems to produce final prototypes.
```

## Simple Bash Commands

### Path Operations
```bash
# Find design directory
bash(find .workflow -type d -name "design-run-*" | head -1)

# Create output directories
bash(mkdir -p {base_path}/layout-extraction)
```

### Validation Commands
```bash
# Check if already extracted
bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists")

# Count generated files
bash(ls {base_path}/layout-extraction/layout-*.json | wc -l)

# Validate JSON structure (sample check)
bash(cat {base_path}/layout-extraction/layout-{first_target}-1.json | grep -q "variant_id" && echo "valid")
```

### File Operations
```bash
# Load image references
bash(ls {images_pattern})
Read({image_path})

# Write layout templates
bash(echo '{json}' > {base_path}/layout-extraction/layout-templates.json)
```

## Output Structure

```
{base_path}/
├── .intermediates/                    # Intermediate analysis files
│   └── layout-analysis/
│       ├── analysis-options.json      # Generated layout concepts + user selections (embedded)
│       └── dom-structure-{target}.json   # Extracted DOM structure (URL mode only)
└── layout-extraction/                 # Final layout templates
    └── layout-{target}-{variant}.json # Structural layout template JSON
```

## Layout Template File Format

Each `layout-{target}-{variant}.json` file contains a single template:

```json
{
  "extraction_metadata": {
    "session_id": "...",
    "input_mode": "image|url|prompt|hybrid",
    "device_type": "desktop|mobile|tablet|responsive",
    "timestamp": "...",
    "target": "home",
    "variant_id": "layout-1"
  },
  "template":
    {
      "target": "home",
      "variant_id": "layout-1",
      "source_image_path": "{base_path}/screenshots/home.png",
      "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
→ Check network connection, retry command
```

### 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)
- **Multi-Selection Workflow** - Generate N concepts → User selects multiple → Parallel template generation
- **Structural Exploration** - Enables A/B testing of different layouts through multi-selection
- **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 prototype generation
- **Agent-Powered** - Deep structural analysis with AI