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

name: layout-extract description: Extract structural layout information from reference images, URLs, or text prompts argument-hint: [--base-path ] [--session ] [--images ""] [--urls ""] [--prompt ""] [--targets ""] [--mode <imitate|explore>] [--variants ] [--device-type <desktop|mobile|tablet|responsive>] 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

# 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

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

# 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

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

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")
  - source_image_path (string, REQUIRED): Path to the primary reference image used for this layout analysis
    * For image input: Use the actual image file path from {images_pattern}
    * For URL input: Use the screenshot path if available, or empty string
    * For text/prompt input: Use empty string
    * Example: "{base_path}/screenshots/home.png"
  - 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

# 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

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

# 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

# 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

# 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

{
  "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",
      "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 (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}