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>

.claude/commands/workflow/concept-clarify.md

@@ -1,11 +1,11 @@
 ---
-name: concept-verify
+name: concept-clarify
 description: Identify underspecified areas in brainstorming artifacts through targeted clarification questions before action planning
-usage: /workflow:concept-verify [--session <session-id>]
+usage: /workflow:concept-clarify [--session <session-id>]
 argument-hint: "optional: --session <session-id>"
 examples:
-  - /workflow:concept-verify
-  - /workflow:concept-verify --session WFS-auth
+  - /workflow:concept-clarify
+  - /workflow:concept-clarify --session WFS-auth
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
@@ -255,7 +255,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
    - ✅ **PROCEED to /workflow:plan**: Conceptual foundation is clear
    - OR ⚠️ **Address Outstanding Items First**: {list critical outstanding items}
-   - OR 🔄 **Run /workflow:concept-verify Again**: If new information available
+   - OR 🔄 **Run /workflow:concept-clarify Again**: If new information available
 
    ### Next Steps
    ```bash

.claude/commands/workflow/ui-design/auto.md

@@ -1,383 +0,0 @@
----
-name: auto
-description: Fully autonomous UI design workflow with style extraction, consolidation, prototype generation (3×3 matrix), and design system integration
-usage: /workflow:ui-design:auto [--prompt "<desc>"] [--images "<glob>"] [--pages "<list>"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]
-argument-hint: "[--prompt \"Modern SaaS with 3 styles\"] [--images \"refs/*.png\"] [--pages \"dashboard,auth\"] [--session WFS-xxx] [--style-variants 3] [--layout-variants 3]"
-examples:
-  - /workflow:ui-design:auto --prompt "Generate 3 style variants for modern blog: home, article, author"
-  - /workflow:ui-design:auto --prompt "SaaS dashboard and settings with 2 layout options"
-  - /workflow:ui-design:auto --images "refs/*.png" --prompt "E-commerce: home, product, cart" --style-variants 3 --layout-variants 3
-  - /workflow:ui-design:auto --session WFS-auth --images "refs/*.png"
-allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
----
-
-# UI Design Auto Workflow Command
-
-## Overview
-Fully autonomous UI design workflow: style extraction → consolidation → UI generation → design update → optional batch planning. This command orchestrates the entire design process without user intervention.
-
-## Coordinator Role
-**Fully autonomous orchestrator**: Executes all phases sequentially, parsing outputs from one phase to construct the inputs for the next. Supports both standard sequential mode and parallel creative mode for generating diverse design variants.
-
-## Execution Model - Autonomous Workflow
-
-This workflow runs **fully autonomously** from start to finish:
-
-1. **User triggers**: `/workflow:ui-design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard,auth" [--batch-plan]`
-2. **Phase 1 executes** (style-extract) → Auto-continues
-3. **Phase 2 executes** (style-consolidate) → Auto-continues
-4. **Phase 3 executes** (ui-generate) → Auto-continues
-5. **Phase 4 executes** (design-update) → Auto-continues
-6. **Phase 5 executes** (batch-plan, optional) → Reports task files
-
-**Auto-Continue Mechanism**:
-- The workflow uses `TodoWrite` to track the state of each phase
-- Upon successful completion of a phase, the coordinator immediately constructs and executes the command for the next phase
-- This pattern ensures a seamless flow
-
-## Core Rules
-
-1. **Start Immediately**: First action is `TodoWrite` initialization, second action is Phase 1 command execution
-2. **No Preliminary Analysis**: Do not read files or validate before Phase 1 (sub-commands handle their own validation)
-3. **Parse Every Output**: Extract required data from each command's output for the next phase
-4. **Auto-Continue**: After each phase, automatically proceed to the next without pausing
-5. **Track Progress**: Update `TodoWrite` after every phase completion
-6. **Default to All**: When selecting variants or prototypes for the next phase, the autonomous workflow defaults to using **all** generated items
-
-## Parameter Requirements
-
-**Optional Parameters** (all have smart defaults):
-- `--pages "<page_list>"`: Pages to generate (if omitted, inferred from prompt/session)
-- `--session <session_id>`: Workflow session ID (if omitted, runs in standalone mode)
-- `--images "<glob_pattern>"`: Reference image paths (default: `design-refs/*`)
-- `--prompt "<description>"`: Text description of design style and pages (supports intelligent parsing)
-- `--style-variants <count>`: Number of style variants to generate (default: inferred from prompt or 3, range: 1-5)
-- `--layout-variants <count>`: Number of layout variants per style (default: inferred from prompt or 3, range: 1-5)
-- `--batch-plan`: Auto-generate implementation tasks after design-update (integrated mode only)
-
-**Input Source Rules**:
-- Must provide at least one of: `--images` or `--prompt`
-- Both can be combined for guided style analysis
-
-**Intelligent Prompt Parsing**:
-The workflow extracts variant counts from natural language:
-- "Generate **3 style variants**" → `--style-variants 3`
-- "**2 layout options**" → `--layout-variants 2`
-- "Create **4 styles** with **2 layouts each**" → `--style-variants 4 --layout-variants 2`
-- Explicit flags override prompt inference
-
-## Execution Modes
-
-### Matrix Mode (Default and Only)
-- Generates `style_variants × layout_variants × pages` prototypes in 3×3 matrix pattern
-- **Phase 1 (Style Extraction)**: Generates `style_variants` style options
-- **Phase 2 (Style Consolidation)**: Creates `style_variants` independent design systems
-- **Phase 3 (Matrix Generation)**: Generates `style_variants × layout_variants` prototypes per page
-- This is the only supported mode - focused on systematic design exploration
-
-### Integrated vs. Standalone Mode
-- `--session` flag determines if the workflow is integrated with a larger session or runs standalone
-
-## 6-Phase Execution
-
-### Phase 0a: Intelligent Prompt Parsing
-```bash
-# Extract variant counts from prompt if not explicitly provided
-IF --prompt provided AND (NOT --style-variants OR NOT --layout-variants):
-    prompt_text = {--prompt value}
-
-    # Parse style variants: "3 style variants", "generate 4 styles", etc.
-    style_match = regex_search(prompt_text, r"(\d+)\s*(style\s*variants?|styles?)")
-    IF style_match AND NOT --style-variants:
-        style_variants = int(style_match.group(1))
-    ELSE:
-        style_variants = --style-variants OR 3  # Default to 3
-
-    # Parse layout variants: "2 layout options", "3 layouts each", etc.
-    layout_match = regex_search(prompt_text, r"(\d+)\s*(layout\s*(variants?|options?)|layouts?)")
-    IF layout_match AND NOT --layout-variants:
-        layout_variants = int(layout_match.group(1))
-    ELSE:
-        layout_variants = --layout-variants OR 3  # Default to 3
-ELSE:
-    style_variants = --style-variants OR 3
-    layout_variants = --layout-variants OR 3
-
-VALIDATE: 1 <= style_variants <= 5
-VALIDATE: 1 <= layout_variants <= 5
-
-STORE: style_variants, layout_variants  # For Phase 1 and Phase 3
-```
-
-### Phase 0b: Run Initialization & Directory Setup
-```bash
-# Generate run ID with timestamp
-run_id = "run-$(date +%Y%m%d-%H%M%S)"
-
-# Determine base path
-IF --session:
-    session_id = {provided_session}
-    base_path = ".workflow/WFS-{session_id}/runs/${run_id}"
-ELSE:
-    # Standalone mode: use scratchpad
-    session_id = "design-session-$(date +%Y%m%d-%H%M%S)"
-    base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}"
-
-# Create run directory structure
-Bash(mkdir -p "${base_path}/.design/style-extraction")
-Bash(mkdir -p "${base_path}/.design/style-consolidation")
-Bash(mkdir -p "${base_path}/.design/prototypes")
-
-# Initialize run metadata
-Write({base_path}/.run-metadata.json):
-{
-  "run_id": "${run_id}",
-  "session_id": "${session_id}",
-  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
-  "workflow": "ui-design:auto",
-  "parameters": {
-    "style_variants": ${style_variants},
-    "layout_variants": ${layout_variants},
-    "pages": "${inferred_page_list}",
-    "prompt": "${prompt_text}",
-    "images": "${images_pattern}"
-  },
-  "status": "in_progress"
-}
-
-# Update "latest" symlink (Windows-compatible)
-IF --session:
-    Bash(cd ".workflow/WFS-{session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}")
-ELSE:
-    # Standalone mode: create symlink in scratchpad session dir
-    Bash(cd ".workflow/.scratchpad/${session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}")
-
-STORE: run_id, base_path  # Use throughout workflow
-```
-
-### Phase 0c: Page Inference
-```bash
-# Infer page list if not explicitly provided
-IF --pages provided:
-    page_list = parse_csv({--pages value})
-ELSE IF --prompt provided:
-    # Extract page names from prompt (e.g., "blog with home, article, author pages")
-    page_list = extract_pages_from_prompt({--prompt value})
-ELSE IF --session AND exists(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md):
-    synthesis = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
-    page_list = extract_pages_from_synthesis(synthesis)
-ELSE:
-    page_list = ["home"]  # Default fallback
-
-STORE: inferred_page_list = page_list  # For Phase 3
-```
-
-### Phase 1: Style Extraction
-**Command Construction**:
-```bash
-images_flag = --images present ? "--images \"{image_glob}\"" : ""
-prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : ""
-
-# Use run-scoped base path
-run_base_flag = "--base-path \"{base_path}/.design\""
-
-# Use style_variants from Phase 0a
-command = "/workflow:ui-design:extract {run_base_flag} {images_flag} {prompt_flag} --variants {style_variants}"
-SlashCommand(command=command)
-```
-**Auto-Continue**: On completion, proceeds to Phase 2
-
----
-
-### Phase 2: Style Consolidation with Separation (Auto-Triggered)
-**Action**: Consolidates each style variant into separate design systems for matrix generation
-
-**Command Construction**:
-```bash
-# Use run-scoped base path and keep styles separate
-run_base_flag = "--base-path \"{base_path}/.design\""
-
-# Use count-based parameter (automatically uses all style_variants)
-command = "/workflow:ui-design:consolidate {run_base_flag} --variants {style_variants} --keep-separate"
-```
-**Command**: `SlashCommand(command=command)`
-**Result**: Generates `style_variants` independent design systems:
-- `.design/style-consolidation/style-1/design-tokens.json`
-- `.design/style-consolidation/style-2/design-tokens.json`
-- `.design/style-consolidation/style-3/design-tokens.json`
-
-**Auto-Continue**: On completion, proceeds to Phase 3
-
----
-
-### Phase 3: Matrix UI Generation (Auto-Triggered)
-**Action**: Generates `style_variants × layout_variants × pages` prototypes using matrix mode
-
-**Command Construction**:
-```bash
-run_base_flag = "--base-path \"{base_path}/.design\""
-pages_flag = "--pages \"{inferred_page_list}\""
-
-# Matrix mode is default in generate.md, no mode flag needed
-command = "/workflow:ui-design:generate {run_base_flag} {pages_flag} --style-variants {style_variants} --layout-variants {layout_variants}"
-SlashCommand(command=command)
-```
-
-**Result**: Generates `style_variants × layout_variants × pages` prototypes:
-- File naming: `{page}-style-{s}-layout-{l}.html`
-- Total prototypes: `style_variants * layout_variants * len(inferred_page_list)`
-- Matrix visualization: `compare.html` with interactive 3×3 grid
-
-**Auto-Continue**: On completion, proceeds to Phase 4
-
----
-
-### Phase 4: Design System Integration (Auto-Triggered)
-**Action**: Integrates all generated prototypes and the design system into the brainstorming artifacts
-
-**Command Construction**:
-```bash
-session_flag = --session present ? "--session {session_id}" : ""
-# --selected-prototypes is omitted to default to ALL generated prototypes
-command = "/workflow:ui-design:update {session_flag}"
-```
-**Command**: `SlashCommand(command=command)`
-**Auto-Continue**: If `--batch-plan` is present, proceeds to Phase 5. Otherwise, the workflow completes
-
----
-
-### Phase 5: Batch Task Generation (Optional, Auto-Triggered)
-**Condition**: Only executes if `--batch-plan` flag is present
-
-**Execution**:
-```bash
-FOR each page IN inferred_page_list:
-  SlashCommand(command="/workflow:plan --agent \"Implement {page} page based on design system\"")
-```
-**Completion**: The workflow is now complete
-
-## TodoWrite Pattern (Autonomous)
-
-```javascript
-// Initialize (before Phase 1)
-TodoWrite({todos: [
-  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing style extraction"},
-  {"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing style consolidation"},
-  {"content": "Execute UI prototype generation", "status": "pending", "activeForm": "Executing UI generation"},
-  {"content": "Execute design system integration", "status": "pending", "activeForm": "Executing design system integration"}
-]})
-
-// After Phase 1 completes, before Phase 2 starts
-TodoWrite({todos: [
-  {"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
-  {"content": "Execute style consolidation", "status": "in_progress", "activeForm": "Executing style consolidation"},
-  // ... rest are pending
-]})
-
-// After Phase 2 completes, before Phase 3 starts
-TodoWrite({todos: [
-  {"content": "Execute style extraction", "status": "completed"},
-  {"content": "Execute style consolidation", "status": "completed", "activeForm": "Executing style consolidation"},
-  {"content": "Execute UI prototype generation", "status": "in_progress", "activeForm": "Executing UI generation"},
-  // ... rest are pending
-]})
-
-// This pattern continues until all phases are complete
-```
-
-## Error Handling
-
-- **Phase Execution Failures**: The workflow will halt, keeping the failed phase `in_progress`. It will report the error and provide recovery instructions, suggesting a manual command execution with corrected parameters
-- **Default Behavior**: In case of ambiguity (e.g., which variants to select), the system defaults to selecting ALL available items to ensure the workflow can proceed autonomously
-
-## Key Improvements Over Previous Version
-
-1. **Zero External Dependencies**: Pure Claude + agents, no CLI tools
-2. **Streamlined Commands**: Removed `--tool` parameter and all CLI tool flags
-3. **Consistent Execution**: All sub-commands use unified patterns
-4. **Reproducible**: Deterministic flow with clear phase dependencies
-5. **Simpler**: Fewer moving parts, easier to understand and debug
-
-## Workflow Position
-
-The workflow acts as the bridge between brainstorming (`synthesis-specification.md`) and planning (`/workflow:plan`), providing this connection in a fully automated fashion with options for deep creative exploration through parallel agents.
-
-## Example Execution Flows
-
-### Example 1: Default 3×3 Matrix (Prompt Inference)
-```bash
-/workflow:ui-design:auto --prompt "Modern minimalist blog with home, article, and author pages"
-
-# Inferred: 3 style variants, 3 layout variants (default)
-# Executes:
-# 1. /workflow:ui-design:extract --base-path ".../run-xxx/.design" --prompt "..." --variants 3
-# 2. /workflow:ui-design:consolidate --base-path ".../run-xxx/.design" --variants 3 --keep-separate
-# 3. /workflow:ui-design:generate --base-path ".../run-xxx/.design" --pages "home,article,author" --style-variants 3 --layout-variants 3
-# 4. /workflow:ui-design:update
-# Total: 27 prototypes (3 styles × 3 layouts × 3 pages)
-```
-
-### Example 2: Custom 2×2 Matrix with Explicit Parameters
-```bash
-/workflow:ui-design:auto --session WFS-ecommerce --images "refs/*.png" --prompt "E-commerce" --style-variants 2 --layout-variants 2
-
-# Executes:
-# 1. /workflow:ui-design:extract --base-path ".workflow/WFS-ecommerce/runs/run-xxx/.design" --images "refs/*.png" --variants 2
-# 2. /workflow:ui-design:consolidate --base-path "..." --variants 2 --keep-separate
-# 3. /workflow:ui-design:generate --base-path "..." --pages "{inferred}" --style-variants 2 --layout-variants 2
-# 4. /workflow:ui-design:update --session WFS-ecommerce
-# Total: 2×2×N prototypes
-```
-
-### Example 3: Intelligent Parsing with Batch Planning
-```bash
-/workflow:ui-design:auto --session WFS-saas --prompt "Create 4 styles with 2 layouts for SaaS dashboard and settings" --batch-plan
-
-# Parsed: --style-variants 4, --layout-variants 2
-# Executes:
-# 1. /workflow:ui-design:extract --variants 4
-# 2. /workflow:ui-design:consolidate --variants 4 --keep-separate
-# 3. /workflow:ui-design:generate --pages "dashboard,settings" --style-variants 4 --layout-variants 2
-#    (generates 16 prototypes: 4 styles × 2 layouts × 2 pages)
-# 4. /workflow:ui-design:update --session WFS-saas
-# 5. /workflow:plan --agent "Implement dashboard page..."
-#    /workflow:plan --agent "Implement settings page..."
-```
-
-## Final Completion Message
-
-```
-✅ UI Design Auto Workflow Complete!
-
-Run ID: {run_id}
-Session: {session_id or "standalone"}
-Matrix: {style_variants}×{layout_variants} ({total_prototypes} total prototypes)
-Input: {images and/or prompt summary}
-
-Phase 1 - Style Extraction: {style_variants} style variants
-Phase 2 - Style Consolidation: {style_variants} independent design systems
-Phase 3 - Matrix Generation: {style_variants}×{layout_variants}×{pages_count} = {total_prototypes} prototypes
-Phase 4 - Design Update: Brainstorming artifacts updated
-{IF batch-plan: Phase 5 - Task Generation: {task_count} implementation tasks created}
-
-📂 Run Output: {base_path}/
-  ├── .design/style-consolidation/  ({style_variants} design systems)
-  ├── .design/prototypes/           ({total_prototypes} HTML/CSS files)
-  └── .run-metadata.json            (run configuration)
-
-🌐 Interactive Preview: {base_path}/.design/prototypes/compare.html
-  - 3×3 matrix view with synchronized scrolling
-  - Zoom controls and fullscreen mode
-  - Selection export for implementation
-
-{IF batch-plan:
-📋 Implementation Tasks: .workflow/WFS-{session}/.task/
-Next: /workflow:execute to begin implementation
-}
-{ELSE:
-Next Steps:
-1. Open compare.html to preview all variants
-2. Select preferred style×layout combinations
-3. Run /workflow:plan to create implementation tasks
-}
-```

.claude/commands/workflow/ui-design/batch-generate.md

@@ -0,0 +1,469 @@
+---
+name: batch-generate
+description: Prompt-driven batch UI generation using target-style-centric parallel execution
+usage: /workflow:ui-design:batch-generate --prompt "<description>" [--targets "<list>"] [--target-type "page|component"] [--device-type "desktop|mobile|tablet|responsive"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
+examples:
+  - /workflow:ui-design:batch-generate --prompt "Dashboard with metrics cards" --style-variants 3
+  - /workflow:ui-design:batch-generate --prompt "Auth pages: login, signup" --session WFS-auth
+  - /workflow:ui-design:batch-generate --prompt "Navbar, hero, footer components" --target-type component
+  - /workflow:ui-design:batch-generate --prompt "Mobile e-commerce app" --device-type mobile
+allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*), mcp__exa__web_search_exa(*)
+---
+
+# Batch Generate UI Prototypes (/workflow:ui-design:batch-generate)
+
+## Overview
+Prompt-driven UI generation with intelligent target extraction and **target-style-centric batch execution**. Each agent handles all layouts for one target × style combination.
+
+**Strategy**: Prompt → Targets → Batched Generation
+- **Prompt-driven**: Describe what to build, command extracts targets
+- **Agent scope**: Each of `T × S` agents generates `L` layouts
+- **Parallel batching**: Max 6 concurrent agents for optimal throughput
+- **Component isolation**: Complete task independence
+- **Style-aware**: HTML adapts to design_attributes
+- **Self-contained CSS**: Direct token values (no var() refs)
+
+**Supports**: Pages (full layouts) and components (isolated elements)
+
+## Phase 1: Setup & Validation
+
+### Step 1: Parse Prompt & Resolve Configuration
+```bash
+# Parse required parameters
+prompt_text = --prompt
+device_type = --device-type OR "responsive"
+
+# Extract targets from prompt
+IF --targets:
+    target_list = split_and_clean(--targets)
+ELSE:
+    target_list = extract_targets_from_prompt(prompt_text)  # See helpers
+    IF NOT target_list: target_list = ["home"]  # Fallback
+
+# Detect target type
+target_type = --target-type OR detect_target_type(target_list)
+
+# Resolve base path
+IF --base-path:
+    base_path = --base-path
+ELSE IF --session:
+    bash(find .workflow/WFS-{session} -type d -name "design-*" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2)
+ELSE:
+    bash(find .workflow -type d -name "design-*" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2)
+
+# Get variant counts
+style_variants = --style-variants OR bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
+layout_variants = --layout-variants OR 3
+```
+
+**Output**: `base_path`, `target_list[]`, `target_type`, `device_type`, `style_variants`, `layout_variants`
+
+### Step 2: Detect Token Sources
+```bash
+# Check consolidated (priority 1) or proposed (priority 2)
+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")
+
+# If proposed: Create temp consolidation dirs + write tokens
+FOR style_id IN 1..style_variants:
+    bash(mkdir -p {base_path}/style-consolidation/style-{style_id})
+    Write({base_path}/style-consolidation/style-{style_id}/design-tokens.json, proposed_tokens)
+
+# Load design space analysis (optional)
+IF exists({base_path}/style-extraction/design-space-analysis.json):
+    design_space_analysis = Read({base_path}/style-extraction/design-space-analysis.json)
+```
+
+**Output**: `token_sources{}`, `consolidated_count`, `proposed_count`, `design_space_analysis`
+
+### Step 3: Gather Layout Inspiration
+```bash
+bash(mkdir -p {base_path}/prototypes/_inspirations)
+
+# For each target: Research via MCP
+FOR target IN target_list:
+    search_query = "{target} {target_type} layout patterns variations"
+    mcp__exa__web_search_exa(query=search_query, numResults=5)
+
+    # Extract context from prompt for this target
+    target_requirements = extract_relevant_context_from_prompt(prompt_text, target)
+
+    # Write simple inspiration file
+    Write({base_path}/prototypes/_inspirations/{target}-layout-ideas.txt, inspiration_content)
+```
+
+**Output**: `T` inspiration text files
+
+## Phase 2: Target-Style-Centric Batch Generation (Agent)
+
+**Executor**: `Task(ui-design-agent)` × `T × S` tasks in **batched parallel** (max 6 concurrent)
+
+### Step 1: Calculate Batch Execution Plan
+```bash
+bash(mkdir -p {base_path}/prototypes)
+
+# Build task list: T × S combinations
+MAX_PARALLEL = 6
+total_tasks = T × S
+total_batches = ceil(total_tasks / MAX_PARALLEL)
+
+# Initialize batch tracking
+TodoWrite({todos: [
+  {content: "Batch 1/{batches}: Generate 6 tasks", status: "in_progress"},
+  {content: "Batch 2/{batches}: Generate 6 tasks", status: "pending"},
+  ...
+]})
+```
+
+### Step 2: Launch Batched Agent Tasks
+For each batch (up to 6 parallel tasks):
+```javascript
+Task(ui-design-agent): `
+  [TARGET_STYLE_UI_GENERATION_FROM_PROMPT]
+  🎯 ONE component: {target} × Style-{style_id} ({philosophy_name})
+  Generate: {layout_variants} × 2 files (HTML + CSS per layout)
+
+  PROMPT CONTEXT: {target_requirements}  # Extracted from original prompt
+  TARGET: {target} | TYPE: {target_type} | STYLE: {style_id}/{style_variants}
+  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 to: density, visual_weight, formality, organic_vs_geometric" : ""}
+
+  ## Generation
+  For EACH layout (1 to {layout_variants}):
+
+  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 name="viewport" content="width=device-width, initial-scale=1.0">
+     - Follow user requirements from prompt
+     ${design_attributes ? `
+     - DOM adaptation:
+       * density='spacious' → flatter hierarchy
+       * density='compact' → deeper nesting
+       * visual_weight='heavy' → extra wrappers
+       * visual_weight='minimal' → direct structure` : ""}
+     - Device-specific: Optimize for {device_type}
+
+  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: {device_type} styles
+     ${device_type === 'responsive' ? '- Responsive: Mobile-first @media' : '- Fixed: ' + device_type}
+     ${design_attributes ? `
+     - Token selection: density → spacing, visual_weight → shadows` : ""}
+
+  ## Notes
+  - ✅ Token VALUES directly from design-tokens.json
+  - ✅ Follow prompt requirements for {target}
+  - ✅ Optimize for {device_type}
+  - ❌ NO var() refs, NO external deps
+  - Layouts structurally DISTINCT
+  - Write files IMMEDIATELY (per layout)
+  - CSS filename MUST match HTML <link href>
+`
+
+# After each batch completes
+TodoWrite: Mark batch completed, next batch in_progress
+```
+
+## Phase 3: Verify & Generate Previews
+
+### Step 1: Verify Generated Files
+```bash
+# Count expected vs found
+bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
+# Expected: S × L × T × 2
+
+# Validate samples
+Read({base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html)
+# Check: <!DOCTYPE html>, correct CSS href, sufficient CSS length
+```
+
+**Output**: `S × L × T × 2` files verified
+
+### Step 2: Run Preview Generation Script
+```bash
+bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
+```
+
+**Script generates**:
+- `compare.html` (interactive matrix)
+- `index.html` (navigation)
+- `PREVIEW.md` (instructions)
+
+### Step 3: Verify Preview Files
+```bash
+bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {base_path}/prototypes/PREVIEW.md)
+```
+
+**Output**: 3 preview files
+
+## Completion
+
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and parse prompt", status: "completed", activeForm: "Parsing prompt"},
+  {content: "Detect token sources", status: "completed", activeForm: "Loading design systems"},
+  {content: "Gather layout inspiration", status: "completed", activeForm: "Researching layouts"},
+  {content: "Batch 1/{batches}: Generate 6 tasks", status: "completed", activeForm: "Generating batch 1"},
+  ... (all batches completed)
+  {content: "Verify files & generate previews", status: "completed", activeForm: "Creating previews"}
+]});
+```
+
+### Output Message
+```
+✅ Prompt-driven batch UI generation complete!
+
+Prompt: {prompt_text}
+
+Configuration:
+- Style Variants: {style_variants}
+- Layout Variants: {layout_variants}
+- Target Type: {target_type}
+- Device Type: {device_type}
+- Targets: {target_list} ({T} targets)
+- Total Prototypes: {S × L × T}
+
+Batch Execution:
+- Total tasks: {T × S} (targets × styles)
+- Batches: {batches} (max 6 parallel per batch)
+- Agent scope: {L} layouts per target×style
+- Component isolation: Complete task independence
+- Device-specific: All layouts optimized for {device_type}
+
+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'}
+
+Generated Files:
+{base_path}/prototypes/
+├── _inspirations/ ({T} text files)
+├── {target}-style-{s}-layout-{l}.html ({S×L×T} prototypes)
+├── {target}-style-{s}-layout-{l}.css
+├── compare.html (interactive matrix)
+├── index.html (navigation)
+└── PREVIEW.md (instructions)
+
+Preview:
+1. Open compare.html (recommended)
+2. Open index.html
+3. Read PREVIEW.md
+
+Next: /workflow:ui-design:update
+```
+
+## Simple Bash Commands
+
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2)
+
+# 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
+# Count generated files
+bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
+
+# Verify preview
+bash(test -f {base_path}/prototypes/compare.html && echo "exists")
+```
+
+### File Operations
+```bash
+# Create directories
+bash(mkdir -p {base_path}/prototypes/_inspirations)
+
+# Run preview script
+bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
+```
+
+## Output Structure
+
+```
+{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
+```
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: No token sources found
+→ Run /workflow:ui-design:extract or /workflow:ui-design:consolidate
+
+ERROR: No targets extracted from prompt
+→ Use --targets explicitly or rephrase prompt
+
+ERROR: MCP search failed
+→ Check network, retry
+
+ERROR: Batch {N} agent tasks failed
+→ Check agent output, retry specific target×style combinations
+
+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)
+- **Invalid tokens**: Validate design-tokens.json structure
+- **Failed batch**: Re-run command, only failed combinations will retry
+
+## Quality Checklist
+
+- [ ] Prompt clearly describes targets
+- [ ] CSS uses direct token values (no var())
+- [ ] HTML adapts to design_attributes (if available)
+- [ ] Semantic HTML5 structure
+- [ ] ARIA attributes present
+- [ ] Device-optimized layouts
+- [ ] Layouts structurally distinct
+- [ ] compare.html works
+
+## Key Features
+
+- **Prompt-Driven**: Describe what to build, command extracts targets
+- **Target-Style-Centric**: `T×S` agents, each handles `L` layouts
+- **Parallel Batching**: Max 6 concurrent agents with progress tracking
+- **Component Isolation**: Complete task independence
+- **Style-Aware**: HTML adapts to design_attributes
+- **Self-Contained CSS**: Direct token values (no var())
+- **Device-Specific**: Optimized for desktop/mobile/tablet/responsive
+- **Inspiration-Based**: MCP-powered layout research
+- **Production-Ready**: Semantic, accessible, responsive
+
+## Integration
+
+**Input**: Prompt, design-tokens.json, design-space-analysis.json (optional)
+**Output**: S×L×T prototypes for `/workflow:ui-design:update`
+**Compatible**: extract, consolidate, explore-auto, imitate-auto outputs
+
+## Usage Examples
+
+### Basic: Auto-detection
+```bash
+/workflow:ui-design:batch-generate \
+  --prompt "Dashboard with metric cards and charts"
+
+# Auto: latest design run, extracts "dashboard" target
+# Output: S × L × 1 prototypes
+```
+
+### With Session
+```bash
+/workflow:ui-design:batch-generate \
+  --prompt "Auth pages: login, signup, password reset" \
+  --session WFS-auth
+
+# Uses WFS-auth's design run
+# Extracts: ["login", "signup", "password-reset"]
+# Batches: 2 (if S=3: 9 tasks = 6+3)
+# Output: S × L × 3 prototypes
+```
+
+### Components with Device Type
+```bash
+/workflow:ui-design:batch-generate \
+  --prompt "Mobile UI components: navbar, card, footer" \
+  --target-type component \
+  --device-type mobile
+
+# Mobile-optimized component generation
+# Output: S × L × 3 prototypes
+```
+
+### Large Scale (Multi-batch)
+```bash
+/workflow:ui-design:batch-generate \
+  --prompt "E-commerce site" \
+  --targets "home,shop,product,cart,checkout" \
+  --style-variants 4 \
+  --layout-variants 2
+
+# Tasks: 5 × 4 = 20 (4 batches: 6+6+6+2)
+# Output: 4 × 2 × 5 = 40 prototypes
+```
+
+## Helper Functions Reference
+
+### Target Extraction
+```python
+# extract_targets_from_prompt(prompt_text)
+# Patterns: "Create X and Y", "Generate X, Y, Z pages", "Build X"
+# Returns: ["x", "y", "z"] (normalized lowercase with hyphens)
+
+# detect_target_type(target_list)
+# Keywords: page (home, dashboard, login) vs component (navbar, card, button)
+# Returns: "page" or "component"
+
+# extract_relevant_context_from_prompt(prompt_text, target)
+# Extracts sentences mentioning specific target
+# Returns: Relevant context string
+```
+
+## Batch Execution Details
+
+### Parallel Control
+- **Max concurrent**: 6 agents per batch
+- **Task distribution**: T × S tasks = ceil(T×S/6) batches
+- **Progress tracking**: TodoWrite per-batch status
+- **Examples**:
+  - 3 tasks → 1 batch
+  - 9 tasks → 2 batches (6+3)
+  - 20 tasks → 4 batches (6+6+6+2)
+
+### Performance
+| Tasks | Batches | Est. Time | Efficiency |
+|-------|---------|-----------|------------|
+| 1-6   | 1       | 3-5 min   | 100%       |
+| 7-12  | 2       | 6-10 min  | ~85%       |
+| 13-18 | 3       | 9-15 min  | ~80%       |
+| 19-30 | 4-5     | 12-25 min | ~75%       |
+
+### Optimization Tips
+1. **Reduce tasks**: Fewer targets or styles
+2. **Adjust layouts**: L=2 instead of L=3 for faster iteration
+3. **Stage generation**: Core pages first, secondary pages later
+
+## Notes
+
+- **Prompt quality**: Clear descriptions improve target extraction
+- **Token sources**: Consolidated (production) or proposed (fast-track)
+- **Batch parallelism**: Max 6 concurrent for stability
+- **Scalability**: Tested up to 30+ tasks (5+ batches)
+- **Dependencies**: MCP web search, ui-generate-preview.sh script

.claude/commands/workflow/ui-design/capture.md

@@ -0,0 +1,366 @@
+---
+name: capture
+description: Batch screenshot capture for UI design workflows using MCP or local fallback
+usage: /workflow:ui-design:capture --url-map "<map>" [--base-path <path>] [--session <id>]
+argument-hint: --url-map "target:url,..." [--base-path path] [--session id]
+examples:
+  - /workflow:ui-design:capture --url-map "home:https://linear.app, pricing:https://linear.app/pricing"
+  - /workflow:ui-design:capture --session WFS-auth --url-map "dashboard:https://app.com/dash"
+  - /workflow:ui-design:capture --base-path ".workflow/.design/run-20250110" --url-map "hero:https://example.com#hero"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), ListMcpResourcesTool(*), mcp__chrome-devtools__*, mcp__playwright__*
+---
+
+# Batch Screenshot Capture (/workflow:ui-design:capture)
+
+## Overview
+Batch screenshot tool with MCP-first strategy and multi-tier fallback. Processes multiple URLs in parallel.
+
+**Strategy**: MCP → Playwright → Chrome → Manual
+**Output**: Flat structure `screenshots/{target}.png`
+
+## Phase 1: Initialize & Parse
+
+### Step 1: Determine Base Path
+```bash
+# Priority: --base-path > session > standalone
+bash(if [ -n "$BASE_PATH" ]; then
+  echo "$BASE_PATH"
+elif [ -n "$SESSION_ID" ]; then
+  find .workflow/WFS-$SESSION_ID/design-* -type d | head -1 || \
+  echo ".workflow/WFS-$SESSION_ID/design-run-$(date +%Y%m%d-%H%M%S)"
+else
+  echo ".workflow/.design/run-$(date +%Y%m%d-%H%M%S)"
+fi)
+
+bash(mkdir -p $BASE_PATH/screenshots)
+```
+
+### Step 2: Parse URL Map
+```javascript
+// Input: "home:https://linear.app, pricing:https://linear.app/pricing"
+url_entries = []
+
+FOR pair IN split(params["--url-map"], ","):
+  parts = pair.split(":", 1)
+
+  IF len(parts) != 2:
+    ERROR: "Invalid format: {pair}. Expected: 'target:url'"
+    EXIT 1
+
+  target = parts[0].strip().lower().replace(" ", "-")
+  url = parts[1].strip()
+
+  // Validate target name
+  IF NOT regex_match(target, r"^[a-z0-9][a-z0-9_-]*$"):
+    ERROR: "Invalid target: {target}"
+    EXIT 1
+
+  // Add https:// if missing
+  IF NOT url.startswith("http"):
+    url = f"https://{url}"
+
+  url_entries.append({target, url})
+```
+
+**Output**: `base_path`, `url_entries[]`
+
+### Step 3: Initialize Todos
+```javascript
+TodoWrite({todos: [
+  {content: "Parse url-map", status: "completed", activeForm: "Parsing"},
+  {content: "Detect MCP tools", status: "in_progress", activeForm: "Detecting"},
+  {content: "Capture screenshots", status: "pending", activeForm: "Capturing"},
+  {content: "Verify results", status: "pending", activeForm: "Verifying"}
+]})
+```
+
+## Phase 2: Detect Screenshot Tools
+
+### Step 1: Check MCP Availability
+```javascript
+// List available MCP servers
+all_resources = ListMcpResourcesTool()
+available_servers = unique([r.server for r in all_resources])
+
+// Check Chrome DevTools MCP
+chrome_devtools = "chrome-devtools" IN available_servers
+chrome_screenshot = check_tool_exists("mcp__chrome-devtools__take_screenshot")
+
+// Check Playwright MCP
+playwright_mcp = "playwright" IN available_servers
+playwright_screenshot = check_tool_exists("mcp__playwright__screenshot")
+
+// Determine primary tool
+IF chrome_devtools AND chrome_screenshot:
+  tool = "chrome-devtools"
+ELSE IF playwright_mcp AND playwright_screenshot:
+  tool = "playwright"
+ELSE:
+  tool = null
+```
+
+**Output**: `tool` (chrome-devtools | playwright | null)
+
+### Step 2: Check Local Fallback
+```bash
+# Only if MCP unavailable
+bash(which playwright 2>/dev/null || echo "")
+bash(which google-chrome || which chrome || which chromium 2>/dev/null || echo "")
+```
+
+**Output**: `local_tools[]`
+
+## Phase 3: Capture Screenshots
+
+### Screenshot Format Options
+
+**PNG Format** (default, lossless):
+- **Pros**: Lossless quality, best for detailed UI screenshots
+- **Cons**: Larger file sizes (typically 200-500 KB per screenshot)
+- **Parameters**: `format: "png"` (no quality parameter)
+- **Use case**: High-fidelity UI replication, design system extraction
+
+**WebP Format** (optional, lossy/lossless):
+- **Pros**: Smaller file sizes with good quality (50-70% smaller than PNG)
+- **Cons**: Requires quality parameter, slight quality loss at high compression
+- **Parameters**: `format: "webp", quality: 90` (80-100 recommended)
+- **Use case**: Batch captures, network-constrained environments
+
+**JPEG Format** (optional, lossy):
+- **Pros**: Smallest file sizes
+- **Cons**: Lossy compression, not recommended for UI screenshots
+- **Parameters**: `format: "jpeg", quality: 90`
+- **Use case**: Photo-heavy pages, not recommended for UI design
+
+### Step 1: MCP Capture (If Available)
+```javascript
+IF tool == "chrome-devtools":
+  // Get or create page
+  pages = mcp__chrome-devtools__list_pages()
+
+  IF pages.length == 0:
+    mcp__chrome-devtools__new_page({url: url_entries[0].url})
+    page_idx = 0
+  ELSE:
+    page_idx = 0
+
+  mcp__chrome-devtools__select_page({pageIdx: page_idx})
+
+  // Capture each URL
+  FOR entry IN url_entries:
+    mcp__chrome-devtools__navigate_page({url: entry.url, timeout: 30000})
+    bash(sleep 2)
+
+    // PNG format doesn't support quality parameter
+    // Use PNG for lossless quality (larger files)
+    mcp__chrome-devtools__take_screenshot({
+      fullPage: true,
+      format: "png",
+      filePath: f"{base_path}/screenshots/{entry.target}.png"
+    })
+
+    // Alternative: Use WebP with quality for smaller files
+    // mcp__chrome-devtools__take_screenshot({
+    //   fullPage: true,
+    //   format: "webp",
+    //   quality: 90,
+    //   filePath: f"{base_path}/screenshots/{entry.target}.webp"
+    // })
+
+ELSE IF tool == "playwright":
+  FOR entry IN url_entries:
+    mcp__playwright__screenshot({
+      url: entry.url,
+      output_path: f"{base_path}/screenshots/{entry.target}.png",
+      full_page: true,
+      timeout: 30000
+    })
+```
+
+### Step 2: Local Fallback (If MCP Failed)
+```bash
+# Try Playwright CLI
+bash(playwright screenshot "$url" "$output_file" --full-page --timeout 30000)
+
+# Try Chrome headless
+bash($chrome --headless --screenshot="$output_file" --window-size=1920,1080 "$url")
+```
+
+### Step 3: Manual Mode (If All Failed)
+```
+⚠️ Manual Screenshot Required
+
+Failed URLs:
+  home: https://linear.app
+  Save to: .workflow/.design/run-20250110/screenshots/home.png
+
+Steps:
+  1. Visit URL in browser
+  2. Take full-page screenshot
+  3. Save to path above
+  4. Type 'ready' to continue
+
+Options: ready | skip | abort
+```
+
+## Phase 4: Verification
+
+### Step 1: Scan Captured Files
+```bash
+bash(ls -1 $base_path/screenshots/*.{png,jpg,jpeg,webp} 2>/dev/null)
+bash(du -h $base_path/screenshots/*.png 2>/dev/null)
+```
+
+### Step 2: Generate Metadata
+```javascript
+captured_files = Glob(f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}")
+captured_targets = [basename_no_ext(f) for f in captured_files]
+
+metadata = {
+  "timestamp": current_timestamp(),
+  "total_requested": len(url_entries),
+  "total_captured": len(captured_targets),
+  "screenshots": []
+}
+
+FOR entry IN url_entries:
+  is_captured = entry.target IN captured_targets
+
+  metadata.screenshots.append({
+    "target": entry.target,
+    "url": entry.url,
+    "captured": is_captured,
+    "path": f"{base_path}/screenshots/{entry.target}.png" IF is_captured ELSE null,
+    "size_kb": file_size_kb IF is_captured ELSE null
+  })
+
+Write(f"{base_path}/screenshots/capture-metadata.json", JSON.stringify(metadata))
+```
+
+**Output**: `capture-metadata.json`
+
+## Completion
+
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Parse url-map", status: "completed", activeForm: "Parsing"},
+  {content: "Detect MCP tools", status: "completed", activeForm: "Detecting"},
+  {content: "Capture screenshots", status: "completed", activeForm: "Capturing"},
+  {content: "Verify results", status: "completed", activeForm: "Verifying"}
+]})
+```
+
+### Output Message
+```
+✅ Batch screenshot capture complete!
+
+Summary:
+- Requested: {total_requested}
+- Captured: {total_captured}
+- Success rate: {success_rate}%
+- Method: {tool || "Local fallback"}
+
+Output:
+{base_path}/screenshots/
+├── home.png (245.3 KB)
+├── pricing.png (198.7 KB)
+└── capture-metadata.json
+
+Next: /workflow:ui-design:extract --images "screenshots/*.png"
+```
+
+## Simple Bash Commands
+
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Create screenshot directory
+bash(mkdir -p $BASE_PATH/screenshots)
+```
+
+### Tool Detection
+```bash
+# Check MCP
+all_resources = ListMcpResourcesTool()
+
+# Check local tools
+bash(which playwright 2>/dev/null)
+bash(which google-chrome 2>/dev/null)
+```
+
+### Verification
+```bash
+# List captures
+bash(ls -1 $base_path/screenshots/*.png 2>/dev/null)
+
+# File sizes
+bash(du -h $base_path/screenshots/*.png)
+```
+
+## Output Structure
+
+```
+{base_path}/
+└── screenshots/
+    ├── home.png
+    ├── pricing.png
+    ├── about.png
+    └── capture-metadata.json
+```
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: Invalid url-map format
+→ Use: "target:url, target2:url2"
+
+ERROR: png screenshots do not support 'quality'
+→ PNG format is lossless, no quality parameter needed
+→ Remove quality parameter OR switch to webp/jpeg format
+
+ERROR: MCP unavailable
+→ Using local fallback
+
+ERROR: All tools failed
+→ Manual mode activated
+```
+
+### Format-Specific Errors
+```
+❌ Wrong: format: "png", quality: 90
+✅ Right: format: "png"
+
+✅ Or use: format: "webp", quality: 90
+✅ Or use: format: "jpeg", quality: 90
+```
+
+### Recovery
+- **Partial success**: Keep successful captures
+- **Retry**: Re-run with failed targets only
+- **Manual**: Follow interactive guidance
+
+## Quality Checklist
+
+- [ ] All requested URLs processed
+- [ ] File sizes > 1KB (valid images)
+- [ ] Metadata JSON generated
+- [ ] No missing targets (or documented)
+
+## Key Features
+
+- **MCP-first**: Prioritize managed tools
+- **Multi-tier fallback**: 4 layers (MCP → Local → Manual)
+- **Batch processing**: Parallel capture
+- **Error tolerance**: Partial failures handled
+- **Structured output**: Flat, predictable
+
+## Integration
+
+**Input**: `--url-map` (multiple target:url pairs)
+**Output**: `screenshots/*.png` + `capture-metadata.json`
+**Called by**: `/workflow:ui-design:imitate-auto`, `/workflow:ui-design:explore-auto`
+**Next**: `/workflow:ui-design:extract` or `/workflow:ui-design:explore-layers`

.claude/commands/workflow/ui-design/consolidate.md

@@ -1,501 +1,272 @@
 ---
 name: consolidate
-description: Consolidate style variants into unified or separate design systems
-usage: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--keep-separate]
-argument-hint: "[--base-path \".workflow/WFS-xxx/runs/run-xxx/.design\"] [--variants 3] [--keep-separate]"
+description: Consolidate style variants into independent design systems and plan layout strategies
+usage: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--layout-variants <count>]
 examples:
-  - /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/latest/.design" --variants 3 --keep-separate
+  - /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --variants 3
   - /workflow:ui-design:consolidate --session WFS-auth --variants 2
-  - /workflow:ui-design:consolidate --base-path "./design-session-xxx/.design"
-allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*)
+  - /workflow:ui-design:consolidate --base-path "./.workflow/.design/run-20250109-150533"  # Uses all variants
+  - /workflow:ui-design:consolidate --session WFS-auth  # Process all variants from extraction
+allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(*)
 ---
 
-# Style Consolidation Command
+# Design System Consolidation Command
 
 ## Overview
-Consolidate user-selected style variants into a unified, production-ready design system using Claude's native synthesis capabilities. Merges token proposals from multiple style cards into a cohesive design language.
+Consolidate style variants into independent production-ready design systems. Refines raw token proposals from `style-extract` into finalized design tokens and style guides.
 
-## Core Philosophy
-- **Claude-Native**: 100% Claude-driven consolidation, no external tools
-- **Token Merging**: Combines `proposed_tokens` from selected variants
-- **Intelligent Synthesis**: Resolves conflicts, ensures consistency
-- **Production-Ready**: Complete design system with documentation
+**Strategy**: Philosophy-Driven Refinement
+- **Agent-Driven**: Uses ui-design-agent for N variant generation
+- **Token Refinement**: Transforms proposed_tokens into complete systems
+- **Production-Ready**: design-tokens.json + style-guide.md per variant
+- **Matrix-Ready**: Provides style variants for generate phase
 
-## Execution Protocol
+## Phase 1: Setup & Validation
 
-### Phase 1: Path Resolution & Variant Loading
+### Step 1: Resolve Base Path & Load Style Cards
 ```bash
 # Determine base path
-IF --base-path provided:
-    base_path = {provided_base_path}  # e.g., ".workflow/WFS-xxx/runs/run-xxx/.design"
-ELSE IF --session provided:
-    session_id = {provided_session}
-    base_path = ".workflow/WFS-{session_id}/latest/.design"  # Use latest run
-ELSE:
-    # Standalone mode: search for most recent design-session in scratchpad
-    base_path = find_latest_design_session(".workflow/.scratchpad/")
-
-# Verify extraction output exists
-style_cards_path = "{base_path}/style-extraction/style-cards.json"
-VERIFY: exists(style_cards_path)
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# OR use --base-path / --session parameters
 
 # Load style cards
-style_cards = Read(style_cards_path)
-total_variants = len(style_cards.style_cards)
+bash(cat {base_path}/style-extraction/style-cards.json)
 ```
 
-### Phase 2: Variant Selection (Count-Based)
+### Step 2: Memory Check (Skip if Already Done)
 ```bash
-# Determine how many variants to consolidate
-IF --variants provided:
-    variants_count = {provided_count}
-    VALIDATE: 1 <= variants_count <= total_variants
-ELSE:
-    # Default to all variants
-    variants_count = total_variants
-
-# Select first N variants
-selected_variants = style_cards.style_cards[0:variants_count]
-VERIFY: selected_variants.length > 0
-
-# Determine consolidation mode
-IF --keep-separate provided:
-    consolidation_mode = "separate"  # Generate N independent design systems
-ELSE:
-    consolidation_mode = "unified"    # Merge into 1 design system
+# Check if already consolidated
+bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "exists")
 ```
 
-### Phase 3: Load Design Context (Optional)
+**If exists**: Skip to completion message
+
+### Step 3: Select Variants
 ```bash
-# Load brainstorming context if available
-design_context = ""
-IF exists({base_path}/.brainstorming/synthesis-specification.md):
-    design_context = Read({base_path}/.brainstorming/synthesis-specification.md)
-ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md):
-    design_context = Read({base_path}/.brainstorming/ui-designer/analysis.md)
+# Determine variant count (default: all from style-cards.json)
+bash(cat style-cards.json | grep -c "\"id\": \"variant-")
+
+# Validate variant count
+# Priority: --variants parameter → total_variants from style-cards.json
 ```
 
-### Phase 4: Design System Synthesis (Claude)
+**Output**: `variants_count`, `selected_variants[]`
 
-**Route based on consolidation_mode**:
-
-#### Mode A: Unified Consolidation (Default)
-Merges all style variants into a single, cohesive design system.
-
-**Synthesis Prompt Template**:
-```
-Create a unified, production-ready design system by consolidating the following style variants.
-
-SESSION: {session_id}
-SELECTED VARIANTS: {variant_ids}
-
-VARIANT DATA:
-{FOR each variant IN selected_variants:
-  ---
-  Variant ID: {variant.id}
-  Name: {variant.name}
-  Description: {variant.description}
-  Design Philosophy: {variant.design_philosophy}
-
-  Proposed Tokens:
-  {JSON.stringify(variant.proposed_tokens, null, 2)}
-  ---
-}
-
-{IF design_context:
-DESIGN CONTEXT (from brainstorming):
-{design_context}
-}
-
-TASK: Consolidate these {selected_variants.length} style variant(s) into a single, cohesive design system.
-
-CONSOLIDATION RULES:
-1. **Merge Token Proposals**: Combine all `proposed_tokens` into one unified system
-2. **Resolve Conflicts**: When variants disagree (e.g., different primary colors), choose the most appropriate value or create a balanced compromise
-3. **Maintain Completeness**: Ensure all token categories are present (colors, typography, spacing, etc.)
-4. **Semantic Naming**: Use clear, semantic names (e.g., "brand-primary" not "color-1")
-5. **Accessibility**: Validate WCAG AA contrast ratios (4.5:1 text, 3:1 UI)
-6. **OKLCH Format**: All colors must use oklch(L C H / A) format
-7. **Design Philosophy**: Synthesize a unified philosophy statement from variant descriptions
-
-OUTPUT: Generate the following files as JSON/Markdown:
-
-FILE 1: design-tokens.json
-{
-  "colors": {
-    "brand": {
-      "primary": "oklch(...)",
-      "secondary": "oklch(...)",
-      "accent": "oklch(...)"
-    },
-    "surface": {
-      "background": "oklch(...)",
-      "elevated": "oklch(...)",
-      "overlay": "oklch(...)"
-    },
-    "semantic": {
-      "success": "oklch(...)",
-      "warning": "oklch(...)",
-      "error": "oklch(...)",
-      "info": "oklch(...)"
-    },
-    "text": {
-      "primary": "oklch(...)",
-      "secondary": "oklch(...)",
-      "tertiary": "oklch(...)",
-      "inverse": "oklch(...)"
-    },
-    "border": {
-      "default": "oklch(...)",
-      "strong": "oklch(...)",
-      "subtle": "oklch(...)"
-    }
-  },
-  "typography": {
-    "font_family": { "heading": "...", "body": "...", "mono": "..." },
-    "font_size": { "xs": "...", ..., "4xl": "..." },
-    "font_weight": { "normal": "...", "medium": "...", "semibold": "...", "bold": "..." },
-    "line_height": { "tight": "...", "normal": "...", "relaxed": "..." },
-    "letter_spacing": { "tight": "...", "normal": "...", "wide": "..." }
-  },
-  "spacing": { "0": "0", "1": "0.25rem", ..., "24": "6rem" },
-  "border_radius": { "none": "0", "sm": "0.25rem", ..., "full": "9999px" },
-  "shadows": { "sm": "...", "md": "...", "lg": "...", "xl": "..." },
-  "breakpoints": { "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" }
-}
-
-FILE 2: style-guide.md
-# Design System Style Guide
-
-## Design Philosophy
-{Synthesized philosophy from all variants}
-
-## Color System
-### Brand Colors
-- **Primary**: {value} - {usage description}
-- **Secondary**: {value} - {usage description}
-- **Accent**: {value} - {usage description}
-
-### Surface Colors
-{List all surface colors with usage}
-
-### Semantic Colors
-{List semantic colors with accessibility notes}
-
-### Text Colors
-{List text colors with contrast ratios}
-
-## Typography
-### Font Families
-{List font families with fallbacks}
-
-### Type Scale
-{Show scale with examples}
-
-### Usage Examples
-```css
-.heading-primary {
-  font-family: var(--font-family-heading);
-  font-size: var(--font-size-3xl);
-  font-weight: var(--font-weight-bold);
-}
-```
-
-## Spacing System
-{Describe spacing scale and usage patterns}
-
-## Component Guidelines
-### Buttons
-{Token-based button styling examples}
-
-### Cards
-{Token-based card styling examples}
-
-### Forms
-{Token-based form styling examples}
-
-## Accessibility
-- All text meets WCAG AA (4.5:1 minimum)
-- UI components meet WCAG AA (3:1 minimum)
-- Focus indicators are clearly visible
-
-FILE 3: tailwind.config.js
-module.exports = {
-  theme: {
-    extend: {
-      colors: {
-        brand: {
-          primary: '{value}',
-          secondary: '{value}',
-          accent: '{value}'
-        },
-        // ... all color tokens
-      },
-      fontFamily: {
-        heading: [{fonts}],
-        body: [{fonts}],
-        mono: [{fonts}]
-      },
-      fontSize: {
-        // ... all size tokens
-      },
-      spacing: {
-        // ... all spacing tokens
-      },
-      borderRadius: {
-        // ... all radius tokens
-      },
-      boxShadow: {
-        // ... all shadow tokens
-      },
-      screens: {
-        // ... all breakpoint tokens
-      }
-    }
-  }
-}
-
-FILE 4: validation-report.json
-{
-  "session_id": "{session_id}",
-  "consolidated_variants": {variant_ids},
-  "timestamp": "{ISO timestamp}",
-  "validation_results": {
-    "colors": {
-      "total": {count},
-      "wcag_aa_compliant": {count},
-      "warnings": [{any contrast issues}]
-    },
-    "typography": {
-      "font_families": {count},
-      "scale_sizes": {count}
-    },
-    "spacing": {
-      "scale_values": {count}
-    },
-    "accessibility": {
-      "status": "pass|warnings",
-      "issues": [{list any issues}]
-    },
-    "completeness": {
-      "required_categories": ["colors", "typography", "spacing", "border_radius", "shadows", "breakpoints"],
-      "present_categories": [{list}],
-      "missing_categories": [{list if any}]
-    }
-  }
-}
-
-RESPONSE FORMAT:
-Provide each file's content in clearly labeled sections:
-
-===== design-tokens.json =====
-{JSON content}
-
-===== style-guide.md =====
-{Markdown content}
-
-===== tailwind.config.js =====
-{JavaScript content}
-
-===== validation-report.json =====
-{JSON content}
-```
-
-### Phase 5: Parse & Write Output Files
+### Step 4: Load Design Context (Optional)
 ```bash
-# Parse Claude's response into separate files
-CREATE: {base_path}/.design/style-consolidation/
+# Load brainstorming context
+bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it)
 
-# Extract and write each file
-parsed_output = parse_claude_response(claude_response)
-
-Write({
-  file_path: "{base_path}/.design/style-consolidation/design-tokens.json",
-  content: parsed_output.design_tokens
-})
-
-Write({
-  file_path: "{base_path}/.design/style-consolidation/style-guide.md",
-  content: parsed_output.style_guide
-})
-
-Write({
-  file_path: "{base_path}/.design/style-consolidation/tailwind.config.js",
-  content: parsed_output.tailwind_config
-})
-
-Write({
-  file_path: "{base_path}/.design/style-consolidation/validation-report.json",
-  content: parsed_output.validation_report
-})
+# Load design space analysis
+bash(test -f {base_path}/style-extraction/design-space-analysis.json && cat it)
 ```
 
-### Phase 6: TodoWrite & Completion
+**Output**: `design_context`, `design_space_analysis`
+
+## Phase 2: Design System Synthesis (Agent)
+
+**Executor**: `Task(ui-design-agent)` for all variants
+
+### Step 1: Create Output Directories
+```bash
+bash(mkdir -p {base_path}/style-consolidation/style-{{1..{variants_count}}})
+```
+
+### Step 2: Launch Agent Task
+For all variants (1 to {variants_count}):
 ```javascript
-TodoWrite({
-  todos: [
-    {content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"},
-    {content: "Select and validate variant IDs", status: "completed", activeForm: "Selecting variants"},
-    {content: "Load design context from brainstorming", status: "completed", activeForm: "Loading context"},
-    {content: "Synthesize unified design system with Claude", status: "completed", activeForm: "Synthesizing design system"},
-    {content: "Write consolidated design system files", status: "completed", activeForm: "Writing output files"}
-  ]
-});
+Task(ui-design-agent): `
+  [DESIGN_TOKEN_GENERATION_TASK]
+  Generate {variants_count} independent design systems using philosophy-driven refinement
+
+  SESSION: {session_id} | MODE: Philosophy-driven refinement | BASE_PATH: {base_path}
+
+  CRITICAL PATH: Use loop index (N) for directories: style-1/, style-2/, ..., style-N/
+
+  VARIANT DATA:
+  {FOR each variant with index N:
+    VARIANT INDEX: {N} | ID: {variant.id} | NAME: {variant.name}
+    Design Philosophy: {variant.design_philosophy}
+    Proposed Tokens: {variant.proposed_tokens}
+    {IF design_space_analysis: Design Attributes: {attributes}, Anti-keywords: {anti_keywords}}
+  }
+
+  ## 参考
+  - Style cards: Each variant's proposed_tokens and design_philosophy
+  - Design space analysis: design_attributes (saturation, weight, formality, organic/geometric, innovation, density)
+  - Anti-keywords: Explicit constraints to avoid
+  - WCAG AA: 4.5:1 text, 3:1 UI (use built-in AI knowledge)
+
+  ## 生成
+  For EACH variant (use loop index N for paths):
+  1. {base_path}/style-consolidation/style-{N}/design-tokens.json
+     - Complete token structure: colors, typography, spacing, border_radius, shadows, breakpoints
+     - All colors in OKLCH format
+     - Apply design_attributes to token values (saturation→chroma, density→spacing, etc.)
+
+  2. {base_path}/style-consolidation/style-{N}/style-guide.md
+     - Expanded design philosophy
+     - Complete color system with accessibility notes
+     - Typography documentation
+     - Usage guidelines
+
+  ## 注意
+  - ✅ Use Write() tool immediately for each file
+  - ✅ Use loop index N for directory names: style-1/, style-2/, etc.
+  - ❌ DO NOT use variant.id in paths (metadata only)
+  - ❌ NO external research or MCP calls (pure AI refinement)
+  - Apply philosophy-driven refinement: design_attributes guide token values
+  - Maintain divergence: Use anti_keywords to prevent variant convergence
+  - Complete each variant's files before moving to next variant
+`
 ```
 
-**Completion Message**:
+**Output**: Agent generates `variants_count × 2` files
+
+## Phase 3: Verify Output
+
+### Step 1: Check Files Created
+```bash
+# Verify all design systems created
+bash(ls {base_path}/style-consolidation/style-*/design-tokens.json | wc -l)
+
+# Validate structure
+bash(cat {base_path}/style-consolidation/style-1/design-tokens.json | grep -q "colors" && echo "valid")
 ```
-✅ Style consolidation complete for session: {session_id}
 
-Consolidated {selected_variants.length} variant(s):
-{FOR each variant: - {variant.name} ({variant.id})}
+### Step 2: Verify File Sizes
+```bash
+bash(ls -lh {base_path}/style-consolidation/style-1/)
+```
 
-Validation Summary:
-- Colors: {total_colors} (WCAG AA: {compliant_count}/{total_colors})
-- Typography: {scale_count} sizes
-- Spacing: {scale_count} values
-- Accessibility: {status}
+**Output**: `variants_count × 2` files verified
 
-📂 Output: {base_path}/.design/style-consolidation/
-  ├── design-tokens.json        (Final token definitions)
-  ├── style-guide.md             (Design system documentation)
-  ├── tailwind.config.js         (Tailwind configuration)
-  └── validation-report.json     (Validation audit)
+## Completion
 
-Next: /workflow:ui-design:generate --session {session_id} --pages "dashboard,auth"
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and load style cards", status: "completed", activeForm: "Loading style cards"},
+  {content: "Select variants and load context", status: "completed", activeForm: "Loading context"},
+  {content: "Generate design systems (agent)", status: "completed", activeForm: "Generating systems"},
+  {content: "Verify output files", status: "completed", activeForm: "Verifying files"}
+]});
+```
 
-Note: When called from /workflow:ui-design:auto, UI generation is triggered automatically.
+### Output Message
+```
+✅ Design system consolidation complete!
+
+Configuration:
+- Session: {session_id}
+- Variants: {variants_count}
+- Philosophy-driven refinement (zero MCP calls)
+
+Generated Files:
+{base_path}/style-consolidation/
+├── style-1/ (design-tokens.json, style-guide.md)
+├── style-2/ (same structure)
+└── style-{variants_count}/ (same structure)
+
+Next: /workflow:ui-design:generate --session {session_id} --style-variants {variants_count} --targets "dashboard,auth"
+```
+
+## Simple Bash Commands
+
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Load style cards
+bash(cat {base_path}/style-extraction/style-cards.json)
+
+# Count variants
+bash(cat style-cards.json | grep -c "\"id\": \"variant-")
+```
+
+### Validation Commands
+```bash
+# Check if already consolidated
+bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "exists")
+
+# Verify output
+bash(ls {base_path}/style-consolidation/style-*/design-tokens.json | wc -l)
+
+# Validate structure
+bash(cat design-tokens.json | grep -q "colors" && echo "valid")
+```
+
+### File Operations
+```bash
+# Create directories
+bash(mkdir -p {base_path}/style-consolidation/style-{{1..3}})
+
+# Check file sizes
+bash(ls -lh {base_path}/style-consolidation/style-1/)
 ```
 
 ## Output Structure
 
 ```
-.workflow/WFS-{session}/.design/style-consolidation/
-├── design-tokens.json           # Final validated CSS tokens
-├── style-guide.md               # Comprehensive design system documentation
-├── tailwind.config.js           # Tailwind theme configuration
-└── validation-report.json       # Validation audit results
+{base_path}/
+└── style-consolidation/
+    ├── style-1/
+    │   ├── design-tokens.json
+    │   └── style-guide.md
+    ├── style-2/
+    │   ├── design-tokens.json
+    │   └── style-guide.md
+    └── style-N/ (same structure)
 ```
 
-### design-tokens.json Format
+## design-tokens.json Format
+
 ```json
 {
   "colors": {
-    "brand": {
-      "primary": "oklch(0.45 0.20 270 / 1)",
-      "secondary": "oklch(0.60 0.15 320 / 1)",
-      "accent": "oklch(0.70 0.18 150 / 1)"
-    },
-    "surface": {
-      "background": "oklch(0.98 0.01 270 / 1)",
-      "elevated": "oklch(1.00 0.00 0 / 1)",
-      "overlay": "oklch(0.95 0.01 270 / 1)"
-    },
-    "semantic": {
-      "success": "oklch(0.60 0.15 142 / 1)",
-      "warning": "oklch(0.75 0.12 85 / 1)",
-      "error": "oklch(0.55 0.22 27 / 1)",
-      "info": "oklch(0.55 0.18 252 / 1)"
-    },
-    "text": {
-      "primary": "oklch(0.20 0.01 270 / 1)",
-      "secondary": "oklch(0.45 0.01 270 / 1)",
-      "tertiary": "oklch(0.60 0.01 270 / 1)",
-      "inverse": "oklch(0.95 0.01 270 / 1)"
-    },
-    "border": {
-      "default": "oklch(0.85 0.01 270 / 1)",
-      "strong": "oklch(0.70 0.01 270 / 1)",
-      "subtle": "oklch(0.92 0.01 270 / 1)"
-    }
+    "brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"},
+    "surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"},
+    "semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"},
+    "text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"},
+    "border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"}
   },
-  "typography": {
-    "font_family": {
-      "heading": "Inter, system-ui, sans-serif",
-      "body": "Inter, system-ui, sans-serif",
-      "mono": "JetBrains Mono, Consolas, monospace"
-    },
-    "font_size": {
-      "xs": "0.75rem",
-      "sm": "0.875rem",
-      "base": "1rem",
-      "lg": "1.125rem",
-      "xl": "1.25rem",
-      "2xl": "1.5rem",
-      "3xl": "1.875rem",
-      "4xl": "2.25rem"
-    },
-    "font_weight": {
-      "normal": "400",
-      "medium": "500",
-      "semibold": "600",
-      "bold": "700"
-    },
-    "line_height": {
-      "tight": "1.25",
-      "normal": "1.5",
-      "relaxed": "1.75"
-    },
-    "letter_spacing": {
-      "tight": "-0.025em",
-      "normal": "0",
-      "wide": "0.025em"
-    }
-  },
-  "spacing": {
-    "0": "0",
-    "1": "0.25rem",
-    "2": "0.5rem",
-    "3": "0.75rem",
-    "4": "1rem",
-    "5": "1.25rem",
-    "6": "1.5rem",
-    "8": "2rem",
-    "10": "2.5rem",
-    "12": "3rem",
-    "16": "4rem",
-    "20": "5rem",
-    "24": "6rem"
-  },
-  "border_radius": {
-    "none": "0",
-    "sm": "0.25rem",
-    "md": "0.5rem",
-    "lg": "0.75rem",
-    "xl": "1rem",
-    "full": "9999px"
-  },
-  "shadows": {
-    "sm": "0 1px 2px oklch(0.00 0.00 0 / 0.05)",
-    "md": "0 4px 6px oklch(0.00 0.00 0 / 0.07)",
-    "lg": "0 10px 15px oklch(0.00 0.00 0 / 0.10)",
-    "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.15)"
-  },
-  "breakpoints": {
-    "sm": "640px",
-    "md": "768px",
-    "lg": "1024px",
-    "xl": "1280px",
-    "2xl": "1536px"
-  }
+  "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}},
+  "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
+  "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
+  "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
+  "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
 }
 ```
 
+**Requirements**: OKLCH colors, complete coverage, semantic naming
+
 ## Error Handling
-- **No style cards found**: Report error, suggest running `/workflow:ui-design:extract` first
-- **Invalid variant IDs**: List available IDs, auto-select all if called from auto workflow
-- **Parsing errors**: Retry with stricter format instructions
-- **Validation warnings**: Report but continue (non-blocking)
 
-## Key Improvements Over Previous Version
+### Common Errors
+```
+ERROR: No style cards found
+→ Run /workflow:ui-design:style-extract first
 
-1. **Zero External Dependencies**: No `gemini-wrapper`, no `codex` - pure Claude
-2. **Direct Token Merging**: Reads `proposed_tokens` from style cards directly
-3. **Single-Pass Synthesis**: One comprehensive prompt generates all outputs
-4. **Reproducible**: Deterministic structure with clear consolidation rules
-5. **Streamlined**: `Load → Synthesize → Write` (3 steps vs 7+ previously)
+ERROR: Invalid variant count
+→ List available count, auto-select all
 
-## Integration Points
-- **Input**: `style-cards.json` from `/workflow:ui-design:extract` (with `proposed_tokens`)
-- **Output**: `design-tokens.json` for `/workflow:ui-design:generate`
-- **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md`
+ERROR: Agent file creation failed
+→ Check agent output, verify Write() operations
+```
+
+## Key Features
+
+- **Philosophy-Driven Refinement** - Pure AI token refinement using design_attributes
+- **Agent-Driven** - Uses ui-design-agent for multi-file generation
+- **Separate Design Systems** - N independent systems (one per variant)
+- **Production-Ready** - WCAG AA compliant, OKLCH colors, semantic naming
+- **Zero MCP Calls** - Faster execution, better divergence preservation
+
+## Integration
+
+**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`
+
+**Note**: After consolidate, use `/workflow:ui-design:layout-extract` to generate layout templates before running generate.

.claude/commands/workflow/ui-design/explore-auto.md

@@ -0,0 +1,495 @@
+---
+name: explore-auto
+description: Exploratory UI design workflow with style-centric batch generation
+usage: /workflow:ui-design:explore-auto [--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]
+examples:
+  - /workflow:ui-design:explore-auto --prompt "Generate 3 style variants for modern blog: home, article, author"
+  - /workflow:ui-design:explore-auto --prompt "SaaS dashboard and settings with 2 layout options"
+  - /workflow:ui-design:explore-auto --images "refs/*.png" --prompt "E-commerce: home, product, cart" --style-variants 3 --layout-variants 3
+  - /workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png"
+  - /workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --style-variants 3 --layout-variants 2
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
+---
+
+# UI Design Auto Workflow Command
+
+## Overview & Execution Model
+
+**Fully autonomous orchestrator**: Executes all design phases sequentially from style extraction to design integration, with optional batch planning.
+
+**Unified Target System**: Generates `style_variants × layout_variants × targets` prototypes, where targets can be:
+- **Pages** (full-page layouts): home, dashboard, settings, etc.
+- **Components** (isolated UI elements): navbar, card, hero, form, etc.
+- **Mixed**: Can combine both in a single workflow
+
+**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
+1. User triggers: `/workflow:ui-design:explore-auto [params]`
+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 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
+- **Phase 1-5 (Autonomous)**: `SlashCommand` is BLOCKING - execution pauses until completion
+- Upon each phase completion: Automatically process output and execute next phase
+- No additional user interaction after Phase 0c confirmation
+
+**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 4 (or Phase 5 if --batch-plan).
+
+**Target Type Detection**: Automatically inferred from prompt/targets, or explicitly set via `--target-type`.
+
+## Core Rules
+
+1. **Start Immediately**: TodoWrite initialization → Phase 1 execution
+2. **No Preliminary Validation**: Sub-commands handle their own validation
+3. **Parse & Pass**: Extract data from each output for next phase
+4. **Default to All**: When selecting variants/prototypes, use ALL generated items
+5. **Track Progress**: Update TodoWrite after each phase
+6. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After each SlashCommand completes, you MUST wait for completion, then immediately execute the next phase. Workflow is NOT complete until Phase 4 (or Phase 5 if --batch-plan).
+
+## Parameter Requirements
+
+**Optional Parameters** (all have smart defaults):
+- `--targets "<list>"`: Comma-separated targets (pages/components) to generate (inferred from prompt/session if omitted)
+- `--target-type "page|component|auto"`: Explicitly set target type (default: `auto` - intelligent detection)
+- `--device-type "desktop|mobile|tablet|responsive|auto"`: Device type for layout optimization (default: `auto` - intelligent detection)
+  - **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
+  - **Mobile**: 375×812px - Touch-friendly, compact layouts
+  - **Tablet**: 768×1024px - Hybrid touch/mouse layouts
+  - **Responsive**: 1920×1080px base with mobile-first breakpoints
+- `--session <id>`: Workflow session ID (standalone mode if omitted)
+- `--images "<glob>"`: Reference image paths (default: `design-refs/*`)
+- `--prompt "<description>"`: Design style and target description
+- `--style-variants <count>`: Style variants (default: inferred from prompt or 3, range: 1-5)
+- `--layout-variants <count>`: Layout variants per style (default: inferred or 3, range: 1-5)
+- `--batch-plan`: Auto-generate implementation tasks after design-update
+
+**Legacy Parameters** (maintained for backward compatibility):
+- `--pages "<list>"`: Alias for `--targets` with `--target-type page`
+- `--components "<list>"`: Alias for `--targets` with `--target-type component`
+
+**Input Rules**:
+- Must provide at least one: `--images` or `--prompt` or `--targets`
+- Multiple parameters can be combined for guided analysis
+- If `--targets` not provided, intelligently inferred from prompt/session
+
+**Supported Target Types**:
+- **Pages** (full layouts): home, dashboard, settings, profile, login, etc.
+- **Components** (UI elements):
+  - Navigation: navbar, header, menu, breadcrumb, tabs, sidebar
+  - Content: hero, card, list, table, grid, timeline
+  - Input: form, search, filter, input-group
+  - Feedback: modal, alert, toast, badge, progress
+  - Media: gallery, carousel, video-player, image-card
+  - Other: footer, pagination, dropdown, tooltip, avatar
+
+**Intelligent Prompt Parsing**: Extracts variant counts from natural language:
+- "Generate **3 style variants**" → `--style-variants 3`
+- "**2 layout options**" → `--layout-variants 2`
+- "Create **4 styles** with **2 layouts each**" → `--style-variants 4 --layout-variants 2`
+- Explicit flags override prompt inference
+
+## Execution Modes
+
+**Matrix Mode** (style-centric):
+- Generates `style_variants × layout_variants × targets` prototypes
+- **Phase 1**: `style_variants` style options with design_attributes (extract)
+- **Phase 2**: `style_variants` independent design systems (consolidate)
+- **Phase 3**: Style-centric batch generation (generate)
+  - Sub-phase 1: `targets × layout_variants` target-specific layout plans
+  - **Sub-phase 2**: `S` style-centric agents (each handles `L×T` combinations)
+  - Sub-phase 3: `style_variants × layout_variants × targets` final prototypes
+  - Performance: Efficient parallel execution with S agents
+  - Quality: HTML structure adapts to design_attributes
+  - Pages: Full-page layouts with complete structure
+  - Components: Isolated elements with minimal wrapper
+
+**Integrated vs. Standalone**:
+- `--session` flag determines session integration or standalone execution
+
+## 6-Phase Execution
+
+### Phase 0a: Intelligent Prompt Parsing
+```bash
+# Parse variant counts from prompt or use explicit/default values
+IF --prompt AND (NOT --style-variants OR NOT --layout-variants):
+    style_variants = regex_extract(prompt, r"(\d+)\s*style") OR --style-variants OR 3
+    layout_variants = regex_extract(prompt, r"(\d+)\s*layout") OR --layout-variants OR 3
+ELSE:
+    style_variants = --style-variants OR 3
+    layout_variants = --layout-variants OR 3
+
+VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
+```
+
+### Phase 0a-2: Device Type Inference
+```bash
+# Device type inference
+device_type = "auto"
+
+# Step 1: Explicit parameter (highest priority)
+IF --device-type AND --device-type != "auto":
+    device_type = --device-type
+    device_source = "explicit"
+ELSE:
+    # Step 2: Prompt analysis
+    IF --prompt:
+        device_keywords = {
+            "desktop": ["desktop", "web", "laptop", "widescreen", "large screen"],
+            "mobile": ["mobile", "phone", "smartphone", "ios", "android"],
+            "tablet": ["tablet", "ipad", "medium screen"],
+            "responsive": ["responsive", "adaptive", "multi-device", "cross-platform"]
+        }
+        detected_device = detect_device_from_prompt(--prompt, device_keywords)
+        IF detected_device:
+            device_type = detected_device
+            device_source = "prompt_inference"
+
+    # Step 3: Target type inference
+    IF device_type == "auto":
+        # Components are typically desktop-first, pages can vary
+        device_type = target_type == "component" ? "desktop" : "responsive"
+        device_source = "target_type_inference"
+
+STORE: device_type, device_source
+```
+
+**Device Type Presets**:
+- **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
+- **Mobile**: 375×812px - Touch-friendly, compact layouts
+- **Tablet**: 768×1024px - Hybrid touch/mouse layouts
+- **Responsive**: 1920×1080px base with mobile-first breakpoints
+
+**Detection Keywords**:
+- Prompt contains "mobile", "phone", "smartphone" → mobile
+- Prompt contains "tablet", "ipad" → tablet
+- Prompt contains "desktop", "web", "laptop" → desktop
+- Prompt contains "responsive", "adaptive" → responsive
+- Otherwise: Inferred from target type (components→desktop, pages→responsive)
+
+### Phase 0b: Run Initialization & Directory Setup
+```bash
+run_id = "run-$(date +%Y%m%d-%H%M%S)"
+base_path = --session ? ".workflow/WFS-{session}/design-${run_id}" : ".workflow/.design/${run_id}"
+
+Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
+
+Write({base_path}/.run-metadata.json): {
+  "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "...",
+  "workflow": "ui-design:auto",
+  "architecture": "style-centric-batch-generation",
+  "parameters": { "style_variants": ${style_variants}, "layout_variants": ${layout_variants},
+                  "targets": "${inferred_target_list}", "target_type": "${target_type}",
+                  "prompt": "${prompt_text}", "images": "${images_pattern}",
+                  "device_type": "${device_type}", "device_source": "${device_source}" },
+  "status": "in_progress",
+  "performance_mode": "optimized"
+}
+```
+
+### Phase 0c: Unified Target Inference with Intelligent Type Detection
+```bash
+# Priority: --pages/--components (legacy) → --targets → --prompt analysis → synthesis → default
+target_list = []; target_type = "auto"; target_source = "none"
+
+# Step 1-2: Explicit parameters (legacy or unified)
+IF --pages: target_list = split(--pages); target_type = "page"; target_source = "explicit_legacy"
+ELSE IF --components: target_list = split(--components); target_type = "component"; target_source = "explicit_legacy"
+ELSE IF --targets:
+    target_list = split(--targets); target_source = "explicit"
+    target_type = --target-type != "auto" ? --target-type : detect_target_type(target_list)
+
+# Step 3: Prompt analysis (Claude internal analysis)
+ELSE IF --prompt:
+    analysis_result = analyze_prompt("{prompt_text}")  # Extract targets, types, purpose
+    target_list = analysis_result.targets
+    target_type = analysis_result.primary_type OR detect_target_type(target_list)
+    target_source = "prompt_analysis"
+
+# Step 4: Session synthesis
+ELSE IF --session AND exists(synthesis-specification.md):
+    target_list = extract_targets_from_synthesis(); target_type = "page"; target_source = "synthesis"
+
+# Step 5: Fallback
+IF NOT target_list: target_list = ["home"]; target_type = "page"; target_source = "default"
+
+# Validate and clean
+validated_targets = [normalize(t) for t in target_list if is_valid(t)]
+IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
+IF --target-type != "auto": target_type = --target-type
+
+# Interactive confirmation
+DISPLAY_CONFIRMATION(target_type, target_source, validated_targets, device_type, device_source):
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "{emoji} {LABEL} CONFIRMATION (Style-Centric)"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Type: {target_type} | Source: {target_source}"
+  "Targets ({count}): {', '.join(validated_targets)}"
+  "Device: {device_type} | Source: {device_source}"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Performance: {style_variants} agent calls"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Modification Options:"
+  "  • 'continue/yes/ok' - Proceed with current configuration"
+  "  • 'targets: a,b,c' - Replace target list"
+  "  • 'skip: x,y' - Remove specific targets"
+  "  • 'add: z' - Add new targets"
+  "  • 'type: page|component' - Change target type"
+  "  • 'device: desktop|mobile|tablet|responsive' - Change device type"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+user_input = WAIT_FOR_USER_INPUT()
+
+# Process user modifications
+MATCH user_input:
+  "continue|yes|ok" → proceed
+  "targets: ..." → validated_targets = parse_new_list()
+  "skip: ..." → validated_targets = remove_items()
+  "add: ..." → validated_targets = add_items()
+  "type: ..." → target_type = extract_type()
+  "device: ..." → device_type = extract_device()
+  default → proceed with current list
+
+STORE: inferred_target_list, target_type, target_inference_source
+
+# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 1
+# This is the only user interaction point in the workflow
+# After this point, all subsequent phases execute automatically without user intervention
+```
+
+**Helper Function: detect_target_type()**
+```bash
+detect_target_type(target_list):
+    page_keywords = ["home", "dashboard", "settings", "profile", "login", "signup", "auth", ...]
+    component_keywords = ["navbar", "header", "footer", "hero", "card", "button", "form", ...]
+
+    page_matches = count_matches(target_list, page_keywords + ["page", "screen", "view"])
+    component_matches = count_matches(target_list, component_keywords + ["component", "widget"])
+
+    RETURN "component" IF component_matches > page_matches ELSE "page"
+```
+
+### Phase 1: Style Extraction
+```bash
+command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " +
+          (--images ? "--images \"{images}\" " : "") +
+          (--prompt ? "--prompt \"{prompt}\" " : "") +
+          "--mode explore --variants {style_variants}"
+SlashCommand(command)
+
+# Output: {style_variants} style cards with design_attributes
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 2 (auto-continue)
+```
+
+### Phase 2: Style Consolidation
+```bash
+command = "/workflow:ui-design:consolidate --base-path \"{base_path}\" " +
+          "--variants {style_variants}"
+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: UI Assembly
+```bash
+command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
+          "--style-variants {style_variants} --layout-variants {layout_variants}"
+
+total = style_variants × layout_variants × len(inferred_target_list)
+
+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}-style-{s}-layout-{l}.html (assembled prototypes)
+# - {target}-style-{s}-layout-{l}.css
+# - compare.html (interactive matrix view)
+# - PREVIEW.md (usage instructions)
+```
+
+### Phase 4: Design System Integration
+```bash
+command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
+SlashCommand(command)
+
+# SlashCommand blocks until phase complete
+# Upon completion:
+#   - If --batch-plan flag present: IMMEDIATELY execute Phase 5 (auto-continue)
+#   - If no --batch-plan: Workflow complete, display final report
+```
+
+### Phase 5: Batch Task Generation (Optional)
+```bash
+IF --batch-plan:
+    FOR target IN inferred_target_list:
+        task_desc = "Implement {target} {target_type} based on design system"
+        SlashCommand("/workflow:plan --agent \"{task_desc}\"")
+```
+
+## TodoWrite Pattern
+```javascript
+// Initialize IMMEDIATELY after Phase 0c user confirmation to track multi-phase execution
+TodoWrite({todos: [
+  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
+  {"content": "Execute style consolidation", "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..."}
+]})
+
+// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
+// 1. SlashCommand blocks and returns when phase is complete
+// 2. Update current phase: status → "completed"
+// 3. Update next phase: status → "in_progress"
+// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
+// This ensures continuous workflow tracking and prevents premature stopping
+```
+
+## Key Features
+
+- **🚀 Performance**: Style-centric batch generation with S agent calls
+- **🎨 Style-Aware**: HTML structure adapts to design_attributes
+- **✅ Perfect Consistency**: Each style by single agent
+- **📦 Autonomous**: No user intervention required between phases
+- **🧠 Intelligent**: Parses natural language, infers targets/types
+- **🔄 Reproducible**: Deterministic flow with isolated run directories
+- **🎯 Flexible**: Supports pages, components, or mixed targets
+
+## Examples
+
+### 1. Page Mode (Prompt Inference)
+```bash
+/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author"
+# Result: 27 prototypes (3×3×3) - responsive layouts (default)
+```
+
+### 2. Mobile-First Design
+```bash
+/workflow:ui-design:explore-auto --prompt "Mobile shopping app: home, product, cart" --device-type mobile
+# Result: 27 prototypes (3×3×3) - mobile layouts (375×812px)
+```
+
+### 3. Desktop Application
+```bash
+/workflow:ui-design:explore-auto --targets "dashboard,analytics,settings" --device-type desktop --style-variants 2 --layout-variants 2
+# Result: 12 prototypes (2×2×3) - desktop layouts (1920×1080px)
+```
+
+### 4. Tablet Interface
+```bash
+/workflow:ui-design:explore-auto --prompt "Educational app for tablets" --device-type tablet --targets "courses,lessons,profile"
+# Result: 27 prototypes (3×3×3) - tablet layouts (768×1024px)
+```
+
+### 5. Custom Matrix with Session
+```bash
+/workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
+# Result: 2×2×N prototypes - device type inferred from session
+```
+
+### 6. Component Mode (Desktop)
+```bash
+/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --device-type desktop --style-variants 3 --layout-variants 2
+# Result: 12 prototypes (3×2×2) - desktop components
+```
+
+### 7. Intelligent Parsing + Batch Planning
+```bash
+/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for mobile dashboard and settings" --batch-plan
+# Result: 16 prototypes (4×2×2) + auto-generated tasks - mobile-optimized (inferred from prompt)
+```
+
+### 8. Large Scale Responsive
+```bash
+/workflow:ui-design:explore-auto --targets "home,dashboard,settings,profile" --device-type responsive --style-variants 3 --layout-variants 3
+# Result: 36 prototypes (3×3×4) - responsive layouts
+```
+
+## Completion Output
+```
+✅ UI Design Explore-Auto Workflow Complete!
+
+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 (style-extract)
+Phase 2: {s} design systems with tokens.css (consolidate)
+Phase 2.5: {n×l} layout templates (layout-extract explore mode)
+  - Device: {device_type} layouts
+  - {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
+
+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:
+✅ 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)
+  ├── 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
+  - Interactive {s}×{l} matrix view
+  - Side-by-side comparison
+  - Target-specific layouts with style-aware structure
+  - Toggle between {n} targets
+
+{icon} Targets: {', '.join(targets)} (type: {target_type})
+  - Each target has {l} custom-designed layouts
+  - Each style × target × layout has unique HTML structure (not just CSS!)
+  - Layout plans stored as structured JSON
+  - Optimized for {device_type} viewing
+
+Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
+```
+

.claude/commands/workflow/ui-design/explore-layers.md

@@ -0,0 +1,594 @@
+---
+name: explore-layers
+description: Interactive deep UI capture with depth-controlled layer exploration
+usage: /workflow:ui-design:explore-layers --url <url> --depth <1-5> [--session <id>] [--base-path <path>]
+argument-hint: --url <url> --depth <1-5> [--session id] [--base-path path]
+examples:
+  - /workflow:ui-design:explore-layers --url "https://app.linear.app" --depth 3
+  - /workflow:ui-design:explore-layers --url "https://notion.so" --depth 2 --session WFS-notion-ui
+  - /workflow:ui-design:explore-layers --url "https://app.com/dashboard" --depth 4
+allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), mcp__chrome-devtools__*
+---
+
+# Interactive Layer Exploration (/workflow:ui-design:explore-layers)
+
+## Overview
+Single-URL depth-controlled interactive capture. Progressively explores UI layers from pages to Shadow DOM.
+
+**Depth Levels**:
+- `1` = Page (full-page screenshot)
+- `2` = Elements (key components)
+- `3` = Interactions (modals, dropdowns)
+- `4` = Embedded (iframes, widgets)
+- `5` = Shadow DOM (web components)
+
+**Requirements**: Chrome DevTools MCP
+
+## Phase 1: Setup & Validation
+
+### Step 1: Parse Parameters
+```javascript
+url = params["--url"]
+depth = int(params["--depth"])
+
+// Validate URL
+IF NOT url.startswith("http"):
+  url = f"https://{url}"
+
+// Validate depth
+IF depth NOT IN [1, 2, 3, 4, 5]:
+  ERROR: "Invalid depth: {depth}. Use 1-5"
+  EXIT 1
+```
+
+### Step 2: Determine Base Path
+```bash
+bash(if [ -n "$BASE_PATH" ]; then
+  echo "$BASE_PATH"
+elif [ -n "$SESSION_ID" ]; then
+  find .workflow/WFS-$SESSION_ID/design-* -type d | head -1 || \
+  echo ".workflow/WFS-$SESSION_ID/design-layers-$(date +%Y%m%d-%H%M%S)"
+else
+  echo ".workflow/.design/layers-$(date +%Y%m%d-%H%M%S)"
+fi)
+
+# Create depth directories
+bash(for i in $(seq 1 $depth); do mkdir -p $BASE_PATH/screenshots/depth-$i; done)
+```
+
+**Output**: `url`, `depth`, `base_path`
+
+### Step 3: Validate MCP Availability
+```javascript
+all_resources = ListMcpResourcesTool()
+chrome_devtools = "chrome-devtools" IN [r.server for r in all_resources]
+
+IF NOT chrome_devtools:
+  ERROR: "explore-layers requires Chrome DevTools MCP"
+  ERROR: "Install: npm i -g @modelcontextprotocol/server-chrome-devtools"
+  EXIT 1
+```
+
+### Step 4: Initialize Todos
+```javascript
+todos = [
+  {content: "Setup and validation", status: "completed", activeForm: "Setting up"}
+]
+
+FOR level IN range(1, depth + 1):
+  todos.append({
+    content: f"Depth {level}: {DEPTH_NAMES[level]}",
+    status: "pending",
+    activeForm: f"Capturing depth {level}"
+  })
+
+todos.append({content: "Generate layer map", status: "pending", activeForm: "Mapping"})
+
+TodoWrite({todos})
+```
+
+## Phase 2: Navigate & Load Page
+
+### Step 1: Get or Create Browser Page
+```javascript
+pages = mcp__chrome-devtools__list_pages()
+
+IF pages.length == 0:
+  mcp__chrome-devtools__new_page({url: url, timeout: 30000})
+  page_idx = 0
+ELSE:
+  page_idx = 0
+  mcp__chrome-devtools__select_page({pageIdx: page_idx})
+  mcp__chrome-devtools__navigate_page({url: url, timeout: 30000})
+
+bash(sleep 3)  // Wait for page load
+```
+
+**Output**: `page_idx`
+
+## Phase 3: Depth 1 - Page Level
+
+### Step 1: Capture Full Page
+```javascript
+TodoWrite(mark_in_progress: "Depth 1: Page")
+
+output_file = f"{base_path}/screenshots/depth-1/full-page.png"
+
+mcp__chrome-devtools__take_screenshot({
+  fullPage: true,
+  format: "png",
+  quality: 90,
+  filePath: output_file
+})
+
+layer_map = {
+  "url": url,
+  "depth": depth,
+  "layers": {
+    "depth-1": {
+      "type": "page",
+      "captures": [{
+        "name": "full-page",
+        "path": output_file,
+        "size_kb": file_size_kb(output_file)
+      }]
+    }
+  }
+}
+
+TodoWrite(mark_completed: "Depth 1: Page")
+```
+
+**Output**: `depth-1/full-page.png`
+
+## Phase 4: Depth 2 - Element Level (If depth >= 2)
+
+### Step 1: Analyze Page Structure
+```javascript
+IF depth < 2: SKIP
+
+TodoWrite(mark_in_progress: "Depth 2: Elements")
+
+snapshot = mcp__chrome-devtools__take_snapshot()
+
+// Filter key elements
+key_types = ["nav", "header", "footer", "aside", "button", "form", "article"]
+key_elements = [
+  el for el in snapshot.interactiveElements
+  if el.type IN key_types OR el.role IN ["navigation", "banner", "main"]
+][:10]  // Limit to top 10
+```
+
+### Step 2: Capture Element Screenshots
+```javascript
+depth_2_captures = []
+
+FOR idx, element IN enumerate(key_elements):
+  element_name = sanitize(element.text[:20] or element.type) or f"element-{idx}"
+  output_file = f"{base_path}/screenshots/depth-2/{element_name}.png"
+
+  TRY:
+    mcp__chrome-devtools__take_screenshot({
+      uid: element.uid,
+      format: "png",
+      quality: 85,
+      filePath: output_file
+    })
+
+    depth_2_captures.append({
+      "name": element_name,
+      "type": element.type,
+      "path": output_file,
+      "size_kb": file_size_kb(output_file)
+    })
+  CATCH error:
+    REPORT: f"Skip {element_name}: {error}"
+
+layer_map.layers["depth-2"] = {
+  "type": "elements",
+  "captures": depth_2_captures
+}
+
+TodoWrite(mark_completed: "Depth 2: Elements")
+```
+
+**Output**: `depth-2/{element}.png` × N
+
+## Phase 5: Depth 3 - Interaction Level (If depth >= 3)
+
+### Step 1: Analyze Interactive Triggers
+```javascript
+IF depth < 3: SKIP
+
+TodoWrite(mark_in_progress: "Depth 3: Interactions")
+
+// Detect structure
+structure = mcp__chrome-devtools__evaluate_script({
+  function: `() => ({
+    modals: document.querySelectorAll('[role="dialog"], .modal').length,
+    dropdowns: document.querySelectorAll('[role="menu"], .dropdown').length,
+    tooltips: document.querySelectorAll('[role="tooltip"], [title]').length
+  })`
+})
+
+// Identify triggers
+triggers = []
+FOR element IN snapshot.interactiveElements:
+  IF element.attributes CONTAINS ("data-toggle", "aria-haspopup"):
+    triggers.append({
+      uid: element.uid,
+      type: "modal" IF "modal" IN element.classes ELSE "dropdown",
+      trigger: "click",
+      text: element.text
+    })
+  ELSE IF element.attributes CONTAINS ("title", "data-tooltip"):
+    triggers.append({
+      uid: element.uid,
+      type: "tooltip",
+      trigger: "hover",
+      text: element.text
+    })
+
+triggers = triggers[:10]  // Limit
+```
+
+### Step 2: Trigger Interactions & Capture
+```javascript
+depth_3_captures = []
+
+FOR idx, trigger IN enumerate(triggers):
+  layer_name = f"{trigger.type}-{sanitize(trigger.text[:15]) or idx}"
+  output_file = f"{base_path}/screenshots/depth-3/{layer_name}.png"
+
+  TRY:
+    // Trigger interaction
+    IF trigger.trigger == "click":
+      mcp__chrome-devtools__click({uid: trigger.uid})
+    ELSE:
+      mcp__chrome-devtools__hover({uid: trigger.uid})
+
+    bash(sleep 1)
+
+    // Capture
+    mcp__chrome-devtools__take_screenshot({
+      fullPage: false,  // Viewport only
+      format: "png",
+      quality: 90,
+      filePath: output_file
+    })
+
+    depth_3_captures.append({
+      "name": layer_name,
+      "type": trigger.type,
+      "trigger_method": trigger.trigger,
+      "path": output_file,
+      "size_kb": file_size_kb(output_file)
+    })
+
+    // Dismiss (ESC key)
+    mcp__chrome-devtools__evaluate_script({
+      function: `() => {
+        document.dispatchEvent(new KeyboardEvent('keydown', {key: 'Escape'}));
+      }`
+    })
+    bash(sleep 0.5)
+
+  CATCH error:
+    REPORT: f"Skip {layer_name}: {error}"
+
+layer_map.layers["depth-3"] = {
+  "type": "interactions",
+  "triggers": structure,
+  "captures": depth_3_captures
+}
+
+TodoWrite(mark_completed: "Depth 3: Interactions")
+```
+
+**Output**: `depth-3/{interaction}.png` × N
+
+## Phase 6: Depth 4 - Embedded Level (If depth >= 4)
+
+### Step 1: Detect Iframes
+```javascript
+IF depth < 4: SKIP
+
+TodoWrite(mark_in_progress: "Depth 4: Embedded")
+
+iframes = mcp__chrome-devtools__evaluate_script({
+  function: `() => {
+    return Array.from(document.querySelectorAll('iframe')).map(iframe => ({
+      src: iframe.src,
+      id: iframe.id || 'iframe',
+      title: iframe.title || 'untitled'
+    })).filter(i => i.src && i.src.startsWith('http'));
+  }`
+})
+```
+
+### Step 2: Capture Iframe Content
+```javascript
+depth_4_captures = []
+
+FOR idx, iframe IN enumerate(iframes):
+  iframe_name = f"iframe-{sanitize(iframe.title or iframe.id)}-{idx}"
+  output_file = f"{base_path}/screenshots/depth-4/{iframe_name}.png"
+
+  TRY:
+    // Navigate to iframe URL in new tab
+    mcp__chrome-devtools__new_page({url: iframe.src, timeout: 30000})
+    bash(sleep 2)
+
+    mcp__chrome-devtools__take_screenshot({
+      fullPage: true,
+      format: "png",
+      quality: 90,
+      filePath: output_file
+    })
+
+    depth_4_captures.append({
+      "name": iframe_name,
+      "url": iframe.src,
+      "path": output_file,
+      "size_kb": file_size_kb(output_file)
+    })
+
+    // Close iframe tab
+    current_pages = mcp__chrome-devtools__list_pages()
+    mcp__chrome-devtools__close_page({pageIdx: current_pages.length - 1})
+
+  CATCH error:
+    REPORT: f"Skip {iframe_name}: {error}"
+
+layer_map.layers["depth-4"] = {
+  "type": "embedded",
+  "captures": depth_4_captures
+}
+
+TodoWrite(mark_completed: "Depth 4: Embedded")
+```
+
+**Output**: `depth-4/iframe-*.png` × N
+
+## Phase 7: Depth 5 - Shadow DOM (If depth = 5)
+
+### Step 1: Detect Shadow Roots
+```javascript
+IF depth < 5: SKIP
+
+TodoWrite(mark_in_progress: "Depth 5: Shadow DOM")
+
+shadow_elements = mcp__chrome-devtools__evaluate_script({
+  function: `() => {
+    const elements = Array.from(document.querySelectorAll('*'));
+    return elements
+      .filter(el => el.shadowRoot)
+      .map((el, idx) => ({
+        tag: el.tagName.toLowerCase(),
+        id: el.id || \`shadow-\${idx}\`,
+        innerHTML: el.shadowRoot.innerHTML.substring(0, 100)
+      }));
+  }`
+})
+```
+
+### Step 2: Capture Shadow DOM Components
+```javascript
+depth_5_captures = []
+
+FOR idx, shadow IN enumerate(shadow_elements):
+  shadow_name = f"shadow-{sanitize(shadow.id)}"
+  output_file = f"{base_path}/screenshots/depth-5/{shadow_name}.png"
+
+  TRY:
+    // Inject highlight script
+    mcp__chrome-devtools__evaluate_script({
+      function: `() => {
+        const el = document.querySelector('${shadow.tag}${shadow.id ? "#" + shadow.id : ""}');
+        if (el) {
+          el.scrollIntoView({behavior: 'smooth', block: 'center'});
+          el.style.outline = '3px solid red';
+        }
+      }`
+    })
+
+    bash(sleep 0.5)
+
+    // Full-page screenshot (component highlighted)
+    mcp__chrome-devtools__take_screenshot({
+      fullPage: false,
+      format: "png",
+      quality: 90,
+      filePath: output_file
+    })
+
+    depth_5_captures.append({
+      "name": shadow_name,
+      "tag": shadow.tag,
+      "path": output_file,
+      "size_kb": file_size_kb(output_file)
+    })
+
+  CATCH error:
+    REPORT: f"Skip {shadow_name}: {error}"
+
+layer_map.layers["depth-5"] = {
+  "type": "shadow-dom",
+  "captures": depth_5_captures
+}
+
+TodoWrite(mark_completed: "Depth 5: Shadow DOM")
+```
+
+**Output**: `depth-5/shadow-*.png` × N
+
+## Phase 8: Generate Layer Map
+
+### Step 1: Compile Metadata
+```javascript
+TodoWrite(mark_in_progress: "Generate layer map")
+
+// Calculate totals
+total_captures = sum(len(layer.captures) for layer in layer_map.layers.values())
+total_size_kb = sum(
+  sum(c.size_kb for c in layer.captures)
+  for layer in layer_map.layers.values()
+)
+
+layer_map["summary"] = {
+  "timestamp": current_timestamp(),
+  "total_depth": depth,
+  "total_captures": total_captures,
+  "total_size_kb": total_size_kb
+}
+
+Write(f"{base_path}/screenshots/layer-map.json", JSON.stringify(layer_map, indent=2))
+
+TodoWrite(mark_completed: "Generate layer map")
+```
+
+**Output**: `layer-map.json`
+
+## Completion
+
+### Todo Update
+```javascript
+all_todos_completed = true
+TodoWrite({todos: all_completed_todos})
+```
+
+### Output Message
+```
+✅ Interactive layer exploration complete!
+
+Configuration:
+- URL: {url}
+- Max depth: {depth}
+- Layers explored: {len(layer_map.layers)}
+
+Capture Summary:
+  Depth 1 (Page):        {depth_1_count} screenshot(s)
+  Depth 2 (Elements):    {depth_2_count} screenshot(s)
+  Depth 3 (Interactions): {depth_3_count} screenshot(s)
+  Depth 4 (Embedded):    {depth_4_count} screenshot(s)
+  Depth 5 (Shadow DOM):  {depth_5_count} screenshot(s)
+
+Total: {total_captures} captures ({total_size_kb:.1f} KB)
+
+Output Structure:
+{base_path}/screenshots/
+├── depth-1/
+│   └── full-page.png
+├── depth-2/
+│   ├── navbar.png
+│   └── footer.png
+├── depth-3/
+│   ├── modal-login.png
+│   └── dropdown-menu.png
+├── depth-4/
+│   └── iframe-analytics.png
+├── depth-5/
+│   └── shadow-button.png
+└── layer-map.json
+
+Next: /workflow:ui-design:extract --images "screenshots/**/*.png"
+```
+
+## Simple Bash Commands
+
+### Directory Setup
+```bash
+# Create depth directories
+bash(for i in $(seq 1 $depth); do mkdir -p $BASE_PATH/screenshots/depth-$i; done)
+```
+
+### Validation
+```bash
+# Check MCP
+all_resources = ListMcpResourcesTool()
+
+# Count captures per depth
+bash(ls $base_path/screenshots/depth-{1..5}/*.png 2>/dev/null | wc -l)
+```
+
+### File Operations
+```bash
+# List all captures
+bash(find $base_path/screenshots -name "*.png" -type f)
+
+# Total size
+bash(du -sh $base_path/screenshots)
+```
+
+## Output Structure
+
+```
+{base_path}/screenshots/
+├── depth-1/
+│   └── full-page.png
+├── depth-2/
+│   ├── {element}.png
+│   └── ...
+├── depth-3/
+│   ├── {interaction}.png
+│   └── ...
+├── depth-4/
+│   ├── iframe-*.png
+│   └── ...
+├── depth-5/
+│   ├── shadow-*.png
+│   └── ...
+└── layer-map.json
+```
+
+## Depth Level Details
+
+| Depth | Name | Captures | Time | Use Case |
+|-------|------|----------|------|----------|
+| 1 | Page | Full page | 30s | Quick preview |
+| 2 | Elements | Key components | 1-2min | Component library |
+| 3 | Interactions | Modals, dropdowns | 2-4min | UI flows |
+| 4 | Embedded | Iframes | 3-6min | Complete context |
+| 5 | Shadow DOM | Web components | 4-8min | Full coverage |
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: Chrome DevTools MCP required
+→ Install: npm i -g @modelcontextprotocol/server-chrome-devtools
+
+ERROR: Invalid depth
+→ Use: 1-5
+
+ERROR: Interaction trigger failed
+→ Some modals may be skipped, check layer-map.json
+```
+
+### Recovery
+- **Partial success**: Lower depth captures preserved
+- **Trigger failures**: Interaction layer may be incomplete
+- **Iframe restrictions**: Cross-origin iframes skipped
+
+## Quality Checklist
+
+- [ ] All depths up to specified level captured
+- [ ] layer-map.json generated with metadata
+- [ ] File sizes valid (> 500 bytes)
+- [ ] Interaction triggers executed
+- [ ] Shadow DOM elements highlighted
+
+## Key Features
+
+- **Depth-controlled**: Progressive capture 1-5 levels
+- **Interactive triggers**: Click/hover for hidden layers
+- **Iframe support**: Embedded content captured
+- **Shadow DOM**: Web component internals
+- **Structured output**: Organized by depth
+
+## Integration
+
+**Input**: Single URL + depth level (1-5)
+**Output**: Hierarchical screenshots + layer-map.json
+**Complements**: `/workflow:ui-design:capture` (multi-URL batch)
+**Next**: `/workflow:ui-design:extract` for design analysis

.claude/commands/workflow/ui-design/extract.md

@@ -1,327 +0,0 @@
----
-name: extract
-description: Extract design style from reference images or text prompts using Claude's analysis
-usage: /workflow:ui-design:extract [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--variants <count>]
-argument-hint: "[--session WFS-xxx] [--images \"refs/*.png\"] [--prompt \"Modern minimalist\"] [--variants 3]"
-examples:
-  - /workflow:ui-design:extract --images "design-refs/*.png" --variants 3
-  - /workflow:ui-design:extract --prompt "Modern minimalist blog, dark theme" --variants 3
-  - /workflow:ui-design:extract --session WFS-auth --images "refs/*.png" --prompt "Linear.app style" --variants 2
-allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
----
-
-# Style Extraction Command
-
-## Overview
-Extract design style elements from reference images or text prompts using Claude's built-in analysis capabilities. Generates a single, comprehensive `style-cards.json` file containing multiple design variants with complete token proposals.
-
-## Core Philosophy
-- **Claude-Native**: 100% Claude-driven analysis, no external tools
-- **Single Output**: Only `style-cards.json` with embedded token proposals
-- **Sequential Execution**: Generate multiple style variants in one pass
-- **Flexible Input**: Images, text prompts, or both
-- **Reproducible**: Deterministic output structure
-
-## Execution Protocol
-
-### Phase 0: Parameter Detection & Validation
-```bash
-# Detect input source
-IF --images AND --prompt:
-    input_mode = "hybrid"  # Text guides image analysis
-ELSE IF --images:
-    input_mode = "image"
-ELSE IF --prompt:
-    input_mode = "text"
-ELSE:
-    ERROR: "Must provide --images or --prompt"
-
-# Detect session mode
-IF --session:
-    session_mode = "integrated"
-    session_id = {provided_session}
-    base_path = ".workflow/WFS-{session_id}/"
-ELSE:
-    session_mode = "standalone"
-    session_id = "design-session-" + timestamp()
-    base_path = ".workflow/.scratchpad/{session_id}/"
-
-# Set variant count
-variants_count = --variants provided ? {count} : 1
-VALIDATE: 1 <= variants_count <= 5
-```
-
-### Phase 1: Input Loading & Validation
-```bash
-# Expand and validate inputs
-IF input_mode IN ["image", "hybrid"]:
-    expanded_images = Glob({--images pattern})
-    VERIFY: expanded_images.length > 0
-    FOR each image IN expanded_images:
-        image_data[i] = Read({image_path})  # Load for analysis
-
-IF input_mode IN ["text", "hybrid"]:
-    VALIDATE: --prompt is non-empty string
-    prompt_guidance = {--prompt value}
-
-# Create output directory
-CREATE: {base_path}/.design/style-extraction/
-```
-
-### Phase 2: Unified Style Analysis (Claude)
-This is a single-pass analysis that replaces all external tool calls.
-
-**Analysis Prompt Template**:
-```
-Analyze the following design references and generate {variants_count} distinct design style proposals.
-
-INPUT MODE: {input_mode}
-
-{IF input_mode IN ["image", "hybrid"]}
-VISUAL REFERENCES: {list of loaded images}
-Identify: color palettes, typography patterns, spacing rhythms, visual hierarchy, component styles
-{ENDIF}
-
-{IF input_mode IN ["text", "hybrid"]}
-TEXT GUIDANCE: "{prompt_guidance}"
-Use this to guide the aesthetic direction and feature requirements
-{ENDIF}
-
-TASK: Generate {variants_count} design style variants that:
-1. Each have a distinct visual identity and design philosophy
-2. Use OKLCH color space for all color values
-3. Include complete, production-ready design token proposals
-4. Are semantically organized (brand, surface, semantic colors)
-
-OUTPUT FORMAT: JSON matching this exact structure:
-{
-  "extraction_metadata": {
-    "session_id": "{session_id}",
-    "input_mode": "{input_mode}",
-    "timestamp": "{ISO timestamp}",
-    "variants_count": {variants_count}
-  },
-  "style_cards": [
-    {
-      "id": "variant-1",
-      "name": "Concise Style Name (e.g., Modern Minimalist)",
-      "description": "2-3 sentence description of this style's visual language and user experience",
-      "design_philosophy": "Core design principles for this variant",
-      "preview": {
-        "primary": "oklch(0.45 0.20 270 / 1)",
-        "background": "oklch(0.98 0.01 270 / 1)",
-        "font_heading": "Inter, system-ui, sans-serif",
-        "border_radius": "0.5rem"
-      },
-      "proposed_tokens": {
-        "colors": {
-          "brand": {
-            "primary": "oklch(0.45 0.20 270 / 1)",
-            "secondary": "oklch(0.60 0.15 320 / 1)",
-            "accent": "oklch(0.70 0.18 150 / 1)"
-          },
-          "surface": {
-            "background": "oklch(0.98 0.01 270 / 1)",
-            "elevated": "oklch(1.00 0.00 0 / 1)",
-            "overlay": "oklch(0.95 0.01 270 / 1)"
-          },
-          "semantic": {
-            "success": "oklch(0.60 0.15 142 / 1)",
-            "warning": "oklch(0.75 0.12 85 / 1)",
-            "error": "oklch(0.55 0.22 27 / 1)",
-            "info": "oklch(0.55 0.18 252 / 1)"
-          },
-          "text": {
-            "primary": "oklch(0.20 0.01 270 / 1)",
-            "secondary": "oklch(0.45 0.01 270 / 1)",
-            "tertiary": "oklch(0.60 0.01 270 / 1)",
-            "inverse": "oklch(0.95 0.01 270 / 1)"
-          },
-          "border": {
-            "default": "oklch(0.85 0.01 270 / 1)",
-            "strong": "oklch(0.70 0.01 270 / 1)",
-            "subtle": "oklch(0.92 0.01 270 / 1)"
-          }
-        },
-        "typography": {
-          "font_family": {
-            "heading": "Inter, system-ui, sans-serif",
-            "body": "Inter, system-ui, sans-serif",
-            "mono": "JetBrains Mono, Consolas, monospace"
-          },
-          "font_size": {
-            "xs": "0.75rem",
-            "sm": "0.875rem",
-            "base": "1rem",
-            "lg": "1.125rem",
-            "xl": "1.25rem",
-            "2xl": "1.5rem",
-            "3xl": "1.875rem",
-            "4xl": "2.25rem"
-          },
-          "font_weight": {
-            "normal": "400",
-            "medium": "500",
-            "semibold": "600",
-            "bold": "700"
-          },
-          "line_height": {
-            "tight": "1.25",
-            "normal": "1.5",
-            "relaxed": "1.75"
-          },
-          "letter_spacing": {
-            "tight": "-0.025em",
-            "normal": "0",
-            "wide": "0.025em"
-          }
-        },
-        "spacing": {
-          "0": "0",
-          "1": "0.25rem",
-          "2": "0.5rem",
-          "3": "0.75rem",
-          "4": "1rem",
-          "5": "1.25rem",
-          "6": "1.5rem",
-          "8": "2rem",
-          "10": "2.5rem",
-          "12": "3rem",
-          "16": "4rem",
-          "20": "5rem",
-          "24": "6rem"
-        },
-        "border_radius": {
-          "none": "0",
-          "sm": "0.25rem",
-          "md": "0.5rem",
-          "lg": "0.75rem",
-          "xl": "1rem",
-          "full": "9999px"
-        },
-        "shadows": {
-          "sm": "0 1px 2px oklch(0.00 0.00 0 / 0.05)",
-          "md": "0 4px 6px oklch(0.00 0.00 0 / 0.07)",
-          "lg": "0 10px 15px oklch(0.00 0.00 0 / 0.10)",
-          "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.15)"
-        },
-        "breakpoints": {
-          "sm": "640px",
-          "md": "768px",
-          "lg": "1024px",
-          "xl": "1280px",
-          "2xl": "1536px"
-        }
-      }
-    }
-  ]
-}
-
-RULES:
-- Each variant must be distinct in visual character
-- All colors MUST use OKLCH format: oklch(L C H / A)
-- Token structures must be complete and production-ready
-- Use semantic naming throughout
-- Ensure accessibility (contrast ratios, readable font sizes)
-```
-
-### Phase 3: Generate & Write Output
-```bash
-# Parse Claude's JSON response
-style_cards_data = parse_json(claude_response)
-
-# Write single output file
-Write({
-  file_path: "{base_path}/.design/style-extraction/style-cards.json",
-  content: style_cards_data
-})
-```
-
-### Phase 4: TodoWrite & Completion
-```javascript
-TodoWrite({
-  todos: [
-    {content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"},
-    {content: "Analyze design references with Claude", status: "completed", activeForm: "Analyzing design"},
-    {content: "Generate {variants_count} style cards with token proposals", status: "completed", activeForm: "Generating style cards"}
-  ]
-});
-```
-
-**Completion Message**:
-```
-✅ Style extraction complete for session: {session_id}
-
-Input mode: {input_mode}
-{IF image mode: Images analyzed: {count}}
-{IF prompt mode: Prompt: "{truncated_prompt}"}
-
-Generated {variants_count} style variant(s):
-{FOR each card: - {card.name} ({card.id})}
-
-📂 Output: {base_path}/.design/style-extraction/style-cards.json
-
-Next: /workflow:ui-design:consolidate --session {session_id} --variants "{all_variant_ids}"
-
-Note: When called from /workflow:ui-design:auto, consolidation is triggered automatically.
-```
-
-## Output Structure
-
-```
-.workflow/WFS-{session}/.design/style-extraction/
-└── style-cards.json    # Single comprehensive output
-```
-
-### style-cards.json Format (Enhanced)
-```json
-{
-  "extraction_metadata": {
-    "session_id": "WFS-xxx or design-session-xxx",
-    "input_mode": "image|text|hybrid",
-    "timestamp": "2025-01-15T10:30:00Z",
-    "variants_count": 3
-  },
-  "style_cards": [
-    {
-      "id": "variant-1",
-      "name": "Modern Minimalist",
-      "description": "Clean, high-contrast design with bold typography and ample whitespace",
-      "design_philosophy": "Less is more - focus on content clarity and visual breathing room",
-      "preview": {
-        "primary": "oklch(0.45 0.20 270 / 1)",
-        "background": "oklch(0.98 0.01 270 / 1)",
-        "font_heading": "Inter, system-ui, sans-serif",
-        "border_radius": "0.5rem"
-      },
-      "proposed_tokens": {
-        "colors": { /* complete color system */ },
-        "typography": { /* complete typography system */ },
-        "spacing": { /* complete spacing scale */ },
-        "border_radius": { /* border radius scale */ },
-        "shadows": { /* shadow system */ },
-        "breakpoints": { /* responsive breakpoints */ }
-      }
-    }
-  ]
-}
-```
-
-## Error Handling
-- **No images found**: Report glob pattern and suggest corrections
-- **Invalid prompt**: Require non-empty string for text mode
-- **Claude JSON parsing error**: Retry with stricter format instructions
-- **Invalid session**: Create standalone session automatically
-
-## Key Improvements Over Previous Version
-
-1. **Zero External Dependencies**: No `gemini-wrapper`, no `codex` - pure Claude
-2. **Single Output File**: Eliminates `semantic_style_analysis.json`, `design-tokens.json`, `tailwind-tokens.js` clutter
-3. **Complete Token Proposals**: Each style card contains a full design system proposal
-4. **Reproducible**: Same inputs = same output structure (content may vary based on Claude model)
-5. **Streamlined Flow**: `Input → Analysis → style-cards.json` (3 steps vs 7+ previously)
-
-## Integration Points
-- **Input**: Reference images (PNG, JPG, WebP) or text prompts
-- **Output**: `style-cards.json` for `/workflow:ui-design:consolidate`
-- **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md` can guide prompts

.claude/commands/workflow/ui-design/generate.md

@@ -1,441 +1,309 @@
 ---
 name: generate
-description: Generate UI prototypes in matrix mode (style × layout combinations)
-usage: /workflow:ui-design:generate [--pages "<list>"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
-argument-hint: "[--pages \"dashboard,auth\"] [--base-path \".workflow/WFS-xxx/runs/run-xxx/.design\"] [--style-variants 3] [--layout-variants 3]"
+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 --base-path ".workflow/WFS-auth/runs/run-xxx/.design" --pages "dashboard,settings" --style-variants 3 --layout-variants 3
-  - /workflow:ui-design:generate --session WFS-auth --pages "home,pricing" --style-variants 2 --layout-variants 2
-  - /workflow:ui-design:generate --base-path "./design-session-xxx/.design" --style-variants 3 --layout-variants 3
-allowed-tools: TodoWrite(*), Read(*), Write(*), Task(conceptual-planning-agent), Bash(*)
+  - /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(*)
 ---
 
-# UI Generation Command (Matrix Mode)
+# Generate UI Prototypes (/workflow:ui-design:generate)
 
 ## Overview
-Generate production-ready UI prototypes (HTML/CSS) in `style × layout` matrix mode, strictly adhering to consolidated design tokens from separate style design systems.
+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.
 
-## Core Philosophy
-- **Matrix-Only**: Single mode generating `style_variants × layout_variants × pages` prototypes
-- **Agent-Driven**: Uses `Task(conceptual-planning-agent)` for parallel generation
-- **Token-Driven**: All styles reference per-style design-tokens.json; no hardcoded values
-- **Production-Ready**: Semantic HTML5, ARIA attributes, responsive design
+**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
 
-## Execution Protocol
+**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: Path Resolution & Context Loading
+## Phase 1: Setup & Validation
+
+### Step 1: Resolve Base Path & Parse Configuration
 ```bash
-# Determine base path
-IF --base-path provided:
-    base_path = {provided_base_path}  # e.g., ".workflow/WFS-xxx/runs/run-xxx/.design"
-ELSE IF --session provided:
-    session_id = {provided_session}
-    base_path = ".workflow/WFS-{session_id}/latest/.design"  # Use latest run
-ELSE:
-    # Standalone mode: search for most recent design-session in scratchpad
-    base_path = find_latest_design_session(".workflow/.scratchpad/")
+# Determine working directory
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
 
-# Determine style and layout variant counts
-style_variants = --style-variants OR 3  # Default to 3
-layout_variants = --layout-variants OR 3  # Default to 3
-
-VALIDATE: 1 <= style_variants <= 5
-VALIDATE: 1 <= layout_variants <= 5
-
-# Infer page list if not provided
-IF --pages provided:
-    page_list = parse_csv({--pages value})
-ELSE IF --session:
-    # Read synthesis-specification.md to extract page requirements
-    synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
-    page_list = extract_pages_from_synthesis(synthesis_spec)
-ELSE:
-    # Infer from existing prototypes or default
-    page_list = detect_from_prototypes({base_path}/prototypes/) OR ["home"]
-
-VALIDATE: page_list not empty
-
-# Verify design systems exist for all styles
-FOR style_id IN range(1, style_variants + 1):
-    VERIFY: {base_path}/style-consolidation/style-{style_id}/design-tokens.json exists
-    VERIFY: {base_path}/style-consolidation/style-{style_id}/style-guide.md exists
-
-# Load requirements (if integrated mode)
-IF --session:
-    synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
+# Get style count
+bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
 ```
 
-### Phase 2: Matrix UI Generation (Parallel, Layout-Based)
-Execute parallel agents to generate `style_variants × layout_variants × pages` prototypes.
-Each agent handles ONE layout strategy across MULTIPLE styles (batched to max 8 styles per agent).
-
+### Step 2: Load Layout Templates
 ```bash
-# Create output directory
-CREATE: {base_path}/prototypes/
+# Check layout templates exist
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
 
-# Calculate style batches (max 8 styles per agent)
-batch_size = 8
-all_style_ids = range(1, style_variants + 1)
-style_batches = split_into_chunks(all_style_ids, batch_size)  # e.g., [[1-8], [9-16]]
-
-# Launch layout_variants × num_batches parallel tasks
-FOR layout_id IN range(1, layout_variants + 1):
-    FOR style_batch IN style_batches:
-        Task(conceptual-planning-agent): "
-          [UI_GENERATION_MATRIX_BATCH]
-
-          Generate prototypes for layout-{layout_id} across a batch of styles.
-
-          ## Context
-          LAYOUT_ID: {layout_id}
-          STYLE_IDS_BATCH: {style_batch}  # e.g., [1, 2, 3, 4, 5, 6, 7, 8]
-          PAGES: {page_list}
-          BASE_PATH: {base_path}
-
-          ## Input Files
-          For each style_id in your batch, you MUST load its corresponding files:
-          - Design Tokens: {base_path}/style-consolidation/style-{style_id}/design-tokens.json
-          - Style Guide: {base_path}/style-consolidation/style-{style_id}/style-guide.md
-          {IF --session: - Requirements: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md}
-
-          ## Task
-          For each style_id in {style_batch}:
-            For each page in [{page_list}]:
-              Generate the prototype files for the specific combination:
-              - {page}-style-{style_id}-layout-{layout_id}.html (semantic HTML5)
-              - {page}-style-{style_id}-layout-{layout_id}.css (token-driven, no hardcoded values)
-              - {page}-style-{style_id}-layout-{layout_id}-notes.md (implementation notes)
-
-          ## Layout Diversity Strategy
-          You are responsible for Layout {layout_id}. Apply this strategy CONSISTENTLY to all styles in your batch.
-
-          {IF layout_id == 1}
-          **Layout 1: Classic Hierarchy**
-          - Traditional F-pattern reading flow
-          - Top navigation with sidebar
-          - Card-based content sections
-          {ELSE IF layout_id == 2}
-          **Layout 2: Modern Asymmetric**
-          - Z-pattern visual flow
-          - Split-screen hero sections
-          - Grid-based modular content
-          {ELSE IF layout_id == 3}
-          **Layout 3: Minimal Focus**
-          - Centered single-column content
-          - Floating navigation
-          - Generous whitespace and breathing room
-          {ELSE}
-          **Layout {layout_id}: Custom Variant**
-          - Develop a unique and consistent layout structure different from the standard three
-          {ENDIF}
-
-          Adapt this strategy to each page's purpose while maintaining layout consistency.
-
-          ## Token Usage Requirements (STRICT)
-          - For each style, load design tokens from its specific file: {base_path}/style-consolidation/style-{style_id}/design-tokens.json
-          - All colors: var(--color-brand-primary), var(--color-surface-background), etc.
-          - All spacing: var(--spacing-4), var(--spacing-6), etc.
-          - All typography: var(--font-family-heading), var(--font-size-lg), etc.
-          - NO hardcoded values (e.g., #4F46E5, 16px) allowed
-
-          ## HTML Requirements
-          - Semantic HTML5 elements (<header>, <nav>, <main>, <section>, <article>)
-          - ARIA attributes for accessibility (role, aria-label, aria-labelledby)
-          - Proper heading hierarchy (h1 → h2 → h3)
-          - Mobile-first responsive design
-
-          ## CSS Requirements
-          - Link to design-tokens.css: <link rel=\"stylesheet\" href=\"../../design-tokens.css\">
-          - Use CSS custom properties from design-tokens.json
-          - Mobile-first media queries using token breakpoints
-          - No inline styles
-          - BEM or semantic class naming
-
-          ## Responsive Design
-          - Mobile: 375px+ (single column, stacked)
-          - Tablet: var(--breakpoint-md) (adapted layout)
-          - Desktop: var(--breakpoint-lg)+ (full layout)
-
-          ## Output Location
-          {base_path}/prototypes/
-
-          ## Deliverables
-          For each page-style-layout combination in your assigned batch:
-          1. HTML file with token-driven structure
-          2. CSS file with custom property references
-          3. Notes file with implementation details and layout rationale
-
-          Total files to generate: {len(page_list) * len(style_batch) * 3}
-        "
-
-# Wait for all {layout_variants * len(style_batches)} parallel tasks to complete
-# Total prototypes: {style_variants * layout_variants * len(page_list)}
+# Load layout templates
+Read({base_path}/layout-extraction/layout-templates.json)
+# Extract: targets, layout_variants count, device_type, template structures
 ```
 
-### Phase 3: Generate Preview Files
+**Output**: `base_path`, `style_variants`, `layout_templates[]`, `targets[]`, `device_type`
 
+### Step 3: Validate Design Tokens
 ```bash
-# Read matrix visualization template
-template_content = Read("~/.claude/workflows/_template-compare-matrix.html")
+# Check design tokens exist for all styles
+bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")
 
-# Prepare template variables
-pages_json = JSON.stringify(page_list)
-run_id = extract_run_id_from_base_path({base_path})
-
-# Inject variables into template
-injected_content = template_content
-    .replace("{{run_id}}", run_id)
-    .replace("{{style_variants}}", style_variants)
-    .replace("{{layout_variants}}", layout_variants)
-    .replace("{{pages_json}}", pages_json)
-
-# Write interactive matrix comparison
-Write({base_path}/prototypes/compare.html, injected_content)
-
-# Generate design-tokens.css (unified CSS custom properties for all styles)
-Write({base_path}/prototypes/design-tokens.css):
-/* Auto-generated from all style design systems */
-/* Note: Each prototype links to its specific style's tokens */
-
-:root {
-  /* Fallback tokens - each HTML file should link to its style-specific tokens */
-  /* See style-consolidation/style-{n}/design-tokens.json for actual values */
-}
-
-# Generate simple index.html for quick navigation
-Write({base_path}/prototypes/index.html):
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>UI Prototypes - Matrix View</title>
-  <style>
-    body {
-      font-family: system-ui, sans-serif;
-      max-width: 800px;
-      margin: 2rem auto;
-      padding: 0 1rem;
-    }
-    h1 { color: #2563eb; }
-    .info {
-      background: #f3f4f6;
-      padding: 1rem;
-      border-radius: 0.5rem;
-      margin: 1rem 0;
-    }
-    .cta {
-      display: inline-block;
-      background: #2563eb;
-      color: white;
-      padding: 0.75rem 1.5rem;
-      border-radius: 0.5rem;
-      text-decoration: none;
-      font-weight: 600;
-      margin-top: 1rem;
-    }
-    .cta:hover { background: #1d4ed8; }
-    .stats {
-      display: grid;
-      grid-template-columns: repeat(3, 1fr);
-      gap: 1rem;
-      margin: 1.5rem 0;
-    }
-    .stat {
-      background: white;
-      border: 1px solid #e5e7eb;
-      padding: 1rem;
-      border-radius: 0.5rem;
-      text-align: center;
-    }
-    .stat-value {
-      font-size: 2rem;
-      font-weight: bold;
-      color: #2563eb;
-    }
-    .stat-label {
-      color: #6b7280;
-      font-size: 0.875rem;
-      margin-top: 0.25rem;
-    }
-  </style>
-</head>
-<body>
-  <h1>🎨 UI Prototype Matrix</h1>
-
-  <div class="info">
-    <p><strong>Matrix Configuration:</strong> {style_variants} styles × {layout_variants} layouts × {len(page_list)} pages</p>
-    <p><strong>Total Prototypes:</strong> {style_variants * layout_variants * len(page_list)}</p>
-  </div>
-
-  <div class="stats">
-    <div class="stat">
-      <div class="stat-value">{style_variants}</div>
-      <div class="stat-label">Style Variants</div>
-    </div>
-    <div class="stat">
-      <div class="stat-value">{layout_variants}</div>
-      <div class="stat-label">Layout Options</div>
-    </div>
-    <div class="stat">
-      <div class="stat-value">{len(page_list)}</div>
-      <div class="stat-label">Pages</div>
-    </div>
-  </div>
-
-  <a href="compare.html" class="cta">🔍 Open Interactive Matrix Comparison →</a>
-
-  <h2>Features</h2>
-  <ul>
-    <li>3×3 matrix grid view with synchronized scrolling</li>
-    <li>Zoom controls (25%, 50%, 75%, 100%)</li>
-    <li>Fullscreen mode for individual prototypes</li>
-    <li>Selection system with export functionality</li>
-    <li>Page switcher for multi-page comparison</li>
-  </ul>
-
-  <h2>Generated Pages</h2>
-  <ul>
-    {FOR page IN page_list:
-      <li><strong>{page}</strong>: {style_variants × layout_variants} variants</li>
-    }
-  </ul>
-</body>
-</html>
-
-# Generate PREVIEW.md with instructions
-Write({base_path}/prototypes/PREVIEW.md):
-# UI Prototype Preview Guide
-
-## Quick Start
-1. Open `compare.html` in a modern browser
-2. Use the page selector to switch between pages
-3. Interact with prototypes in the 3×3 matrix
-
-## Matrix Configuration
-- **Style Variants:** {style_variants}
-- **Layout Options:** {layout_variants}
-- **Pages:** {page_list}
-- **Total Prototypes:** {style_variants * layout_variants * len(page_list)}
-
-## File Naming Convention
-`{page}-style-{s}-layout-{l}.html`
-
-Example: `dashboard-style-1-layout-2.html`
-- Page: dashboard
-- Style: Design system 1
-- Layout: Layout variant 2
-
-## Interactive Features
-- **Synchronized Scroll:** All prototypes scroll together
-- **Zoom Controls:** Adjust viewport scale (25%-100%)
-- **Fullscreen:** Click any prototype for detailed view
-- **Selection:** Mark favorites for implementation
-- **Export:** Save selections as JSON
-
-## Design System References
-Each prototype uses tokens from:
-`../style-consolidation/style-{s}/design-tokens.json`
-
-Refer to corresponding `style-guide.md` for design philosophy and usage guidelines.
-
-## Next Steps
-1. Review all variants in compare.html
-2. Select preferred style×layout combinations
-3. Export selections for implementation planning
-4. Run `/workflow:ui-design:update` to integrate chosen designs
+# For each style variant: Load design tokens
+Read({base_path}/style-consolidation/style-{id}/design-tokens.json)
 ```
 
-### Phase 4: TodoWrite & Completion
+**Output**: `design_tokens[]` for all style variants
 
+## Phase 2: Assembly (Agent)
+
+**Executor**: `Task(ui-design-agent)` × `T × S × L` tasks (can be batched)
+
+### Step 1: Launch Assembly Tasks
+```bash
+bash(mkdir -p {base_path}/prototypes)
+```
+
+For each `target × style_id × layout_id`:
 ```javascript
-TodoWrite({
-  todos: [
-    {content: "Resolve paths and load design systems", status: "completed", activeForm: "Loading design systems"},
-    {content: `Generate ${style_variants}×${layout_variants}×${page_list.length} prototypes`, status: "completed", activeForm: "Generating matrix prototypes"},
-    {content: "Generate interactive preview files", status: "completed", activeForm: "Generating preview"}
-  ]
-});
+Task(ui-design-agent): `
+  [LAYOUT_STYLE_ASSEMBLY]
+  🎯 Assembly task: {target} × Style-{style_id} × Layout-{layout_id}
+  Combine: Pre-extracted layout structure + design tokens → Final HTML/CSS
+
+  TARGET: {target} | STYLE: {style_id} | LAYOUT: {layout_id}
+  BASE_PATH: {base_path}
+
+  ## 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
+
+  2. Design Tokens:
+     Read("{base_path}/style-consolidation/style-{style_id}/design-tokens.json")
+     Extract: ALL token values (colors, typography, spacing, borders, shadows, breakpoints)
+
+  ## 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. 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
+
+  ## 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="...">
+`
 ```
 
-**Completion Message**:
+### Step 2: Verify Generated Files
+```bash
+# Count expected vs found
+bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
+
+# Validate samples
+Read({base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html)
+# Check: <!DOCTYPE html>, correct CSS href, sufficient CSS length
 ```
-✅ Matrix UI generation complete!
+
+**Output**: `S × L × T × 2` files verified
+
+## Phase 3: Generate Preview Files
+
+### Step 1: Run Preview Generation Script
+```bash
+bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
+```
+
+**Script generates**:
+- `compare.html` (interactive matrix)
+- `index.html` (navigation)
+- `PREVIEW.md` (instructions)
+
+### Step 2: Verify Preview Files
+```bash
+bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {base_path}/prototypes/PREVIEW.md)
+```
+
+**Output**: 3 preview files
+
+## Completion
+
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and validation", status: "completed", activeForm: "Loading design systems"},
+  {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"}
+]});
+```
+
+### Output Message
+```
+✅ UI prototype assembly complete!
 
 Configuration:
 - Style Variants: {style_variants}
-- Layout Options: {layout_variants}
-- Pages: {page_list}
-- Total Prototypes: {style_variants * layout_variants * len(page_list)}
+- Layout Variants: {layout_variants} (from layout-templates.json)
+- Device Type: {device_type}
+- Targets: {targets}
+- Total Prototypes: {S × L × T}
+
+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:
+- 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:
-{FOR style_id IN range(1, style_variants + 1):
-  {FOR layout_id IN range(1, layout_variants + 1):
-    {FOR page IN page_list:
-      - {page}-style-{style_id}-layout-{layout_id}.html
-    }
-  }
-}
+{base_path}/prototypes/
+├── _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)
+├── index.html (navigation)
+└── PREVIEW.md (instructions)
 
-📂 Location: {base_path}/prototypes/
+Preview:
+1. Open compare.html (recommended)
+2. Open index.html
+3. Read PREVIEW.md
 
-🌐 Interactive Preview:
-1. Matrix View: Open compare.html (recommended)
-2. Quick Index: Open index.html
-3. Instructions: See PREVIEW.md
+Next: /workflow:ui-design:update
+```
 
-Features:
-- 3×3 matrix grid with synchronized scrolling
-- Zoom controls and fullscreen mode
-- Selection export for implementation
-- Per-page comparison
+## Simple Bash Commands
 
-Next: /workflow:ui-design:update {--session flag if applicable}
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
 
-Note: When called from /workflow:ui-design:auto, design-update is triggered automatically.
+# Count style variants
+bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
+```
+
+### 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")
+
+# Count generated files
+bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
+
+# Verify preview
+bash(test -f {base_path}/prototypes/compare.html && echo "exists")
+```
+
+### File Operations
+```bash
+# Create directories
+bash(mkdir -p {base_path}/prototypes)
+
+# Run preview script
+bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
 ```
 
 ## Output Structure
 
 ```
-{base_path}/prototypes/
-├── compare.html                           # Interactive matrix visualization
-├── index.html                             # Simple navigation page
-├── PREVIEW.md                             # Preview instructions
-├── design-tokens.css                      # CSS custom properties fallback
-├── {page}-style-{s}-layout-{l}.html      # Matrix prototype files
-├── {page}-style-{s}-layout-{l}.css
-├── {page}-style-{s}-layout-{l}-notes.md
-└── ... (all style×layout×page combinations)
+{base_path}/
+├── 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
-- **No design systems found**: Run `/workflow:ui-design:consolidate --keep-separate` first
-- **Invalid page names**: Extract from synthesis-specification.md or error
-- **Agent execution errors**: Report details, suggest retry
-- **Missing template**: Provide fallback or error with template path
 
-## Quality Checks
-After generation, ensure:
-- [ ] All CSS values reference design token custom properties
-- [ ] No hardcoded colors, spacing, or typography
-- [ ] Semantic HTML structure
-- [ ] ARIA attributes present
-- [ ] Responsive design implemented
-- [ ] Mobile-first approach
-- [ ] File naming follows `{page}-style-{s}-layout-{l}` convention
-- [ ] compare.html loads correctly with all prototypes
+### Common Errors
+```
+ERROR: Layout templates not found
+→ Run /workflow:ui-design:layout-extract first
+
+ERROR: Design tokens not found
+→ Run /workflow:ui-design:consolidate first
+
+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 assembly combinations
+- **Invalid template structure**: Validate layout-templates.json
+- **Invalid tokens**: Validate design-tokens.json structure
+
+## Quality Checklist
+
+- [ ] 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
 
-1. **Matrix-Only Mode**: Simplified, focused workflow
-2. **Parallel Generation**: All style×layout combinations in parallel
-3. **Interactive Visualization**: Full-featured compare.html from template
-4. **Per-Style Tokens**: Each prototype references its style's design system
-5. **Systematic Exploration**: Consistent layout strategies across all styles
+- **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 Points
-- **Input**: Per-style design-tokens.json from `/workflow:ui-design:consolidate --keep-separate`
-- **Output**: Matrix HTML/CSS prototypes for `/workflow:ui-design:update`
-- **Template**: `~/.claude/workflows/_template-compare-matrix.html` (global)
-- **Context**: synthesis-specification.md for page requirements (optional)
+## Integration
+
+**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`

.claude/commands/workflow/ui-design/imitate-auto.md

@@ -0,0 +1,903 @@
+---
+name: imitate-auto
+description: High-speed multi-page UI replication with batch screenshot and optional token refinement
+usage: /workflow:ui-design:imitate-auto --url-map "<map>" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--refine-tokens] [--prompt "<desc>"]
+examples:
+  - /workflow:ui-design:imitate-auto --url-map "home:https://linear.app, features:https://linear.app/features"
+  - /workflow:ui-design:imitate-auto --session WFS-payment --url-map "pricing:https://stripe.com/pricing"
+  - /workflow:ui-design:imitate-auto --url-map "dashboard:https://app.com/dash" --refine-tokens
+  - /workflow:ui-design:imitate-auto --url-map "app:https://app.com" --capture-mode deep --depth 3
+  - /workflow:ui-design:imitate-auto --url-map "home:https://example.com, about:https://example.com/about" --prompt "Focus on minimalist design"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
+---
+
+# UI Design Imitate-Auto Workflow Command
+
+## Overview & Execution Model
+
+**Fully autonomous replication orchestrator**: Efficiently replicate multiple web pages through sequential execution from screenshot capture to design integration.
+
+**Dual Capture Strategy**: Supports two capture modes for different use cases:
+- **Batch Mode** (default): Fast multi-URL screenshot capture via `/workflow:ui-design:capture`
+- **Deep Mode**: Interactive layer exploration for single URL via `/workflow:ui-design:explore-layers`
+
+**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
+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: 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
+- Upon each phase completion: Automatically process output and execute next phase
+- No user interaction required after initial parameter parsing
+
+**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 5.
+
+## Core Rules
+
+1. **Start Immediately**: TodoWrite initialization → Phase 1 execution
+2. **No Preliminary Validation**: Sub-commands handle their own validation
+3. **Parse & Pass**: Extract data from each output for next phase
+4. **Track Progress**: Update TodoWrite after each phase
+5. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After each SlashCommand completes, you MUST wait for completion, then immediately execute the next phase. Workflow is NOT complete until Phase 5.
+
+## Parameter Requirements
+
+**Required Parameters**:
+- `--url-map "<map>"`: Target page mapping
+  - Format: `"target1:url1, target2:url2, ..."`
+  - Example: `"home:https://linear.app, pricing:https://linear.app/pricing"`
+  - First target serves as primary style source
+
+**Optional Parameters**:
+- `--capture-mode <batch|deep>` (Optional, default: batch): Screenshot capture strategy
+  - `batch` (default): Multi-URL fast batch capture via `/workflow:ui-design:capture`
+  - `deep`: Single-URL interactive depth exploration via `/workflow:ui-design:explore-layers`
+  - **Note**: `deep` mode only uses first URL from url-map
+
+- `--depth <1-5>` (Optional, default: 3): Capture depth for deep mode
+  - `1`: Page level (full-page screenshot)
+  - `2`: Element level (+ key components)
+  - `3`: Interaction level (+ modals, dropdowns)
+  - `4`: Embedded level (+ iframes)
+  - `5`: Shadow DOM (+ web components)
+  - **Only applies when** `--capture-mode deep`
+
+- `--session <id>` (Optional): Workflow session ID
+  - Integrate into existing session (`.workflow/WFS-{session}/`)
+  - Enable automatic design system integration (Phase 5)
+  - If not provided: standalone mode (`.workflow/.design/`)
+
+- `--refine-tokens` (Optional, default: false): Enable full token refinement
+  - `false` (default): Fast path, skip consolidate (~30-60s faster)
+  - `true`: Production quality, execute full consolidate (philosophy-driven refinement)
+
+- `--prompt "<desc>"` (Optional): Style extraction guidance
+  - Influences extract command analysis focus
+  - Example: `"Focus on dark mode"`, `"Emphasize minimalist design"`
+
+## Execution Modes
+
+**Capture Modes**:
+- **Batch Mode** (default): Multi-URL screenshot capture for fast replication
+  - Uses `/workflow:ui-design:capture` for parallel screenshot capture
+  - Optimized for replicating multiple pages efficiently
+- **Deep Mode**: Single-URL layer exploration for detailed analysis
+  - Uses `/workflow:ui-design:explore-layers` for interactive depth traversal
+  - Captures page layers at different depths (1-5)
+  - Only processes first URL from url-map
+
+**Token Processing Modes**:
+- **Fast-Track** (default): Skip consolidate, use proposed tokens directly (~2s)
+  - Best for rapid prototyping and testing
+  - Tokens may lack philosophy-driven refinement
+- **Production** (--refine-tokens): Full consolidate with WCAG validation (~60s)
+  - Philosophy-driven token refinement
+  - Complete accessibility validation
+  - Production-ready design system
+
+**Session Integration**:
+- `--session` flag determines session integration or standalone execution
+- Integrated: Design system automatically added to session artifacts
+- Standalone: Output in `.workflow/.design/{run_id}/`
+
+## 6-Phase Execution
+
+### Phase 0: Initialization and Target Parsing
+
+```bash
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 UI Design Imitate-Auto"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Constants
+DEPTH_NAMES = {
+    1: "Page level",
+    2: "Element level",
+    3: "Interaction level",
+    4: "Embedded level",
+    5: "Shadow DOM"
+}
+
+# Generate run ID
+run_id = "run-$(date +%Y%m%d-%H%M%S)"
+
+# Determine base path and session mode
+IF --session:
+    session_id = {provided_session}
+    base_path = ".workflow/WFS-{session_id}/design-{run_id}"
+    session_mode = "integrated"
+    REPORT: "Mode: Integrated (Session: {session_id})"
+ELSE:
+    session_id = null
+    base_path = ".workflow/.design/{run_id}"
+    session_mode = "standalone"
+    REPORT: "Mode: Standalone"
+
+# Create base directory
+Bash(mkdir -p "{base_path}")
+
+# Parse url-map
+url_map_string = {--url-map}
+VALIDATE: url_map_string is not empty, "--url-map parameter is required"
+
+# Parse target:url pairs
+url_map = {}  # {target_name: url}
+target_names = []
+
+FOR pair IN split(url_map_string, ","):
+    pair = pair.strip()
+
+    IF ":" NOT IN pair:
+        ERROR: "Invalid url-map format: '{pair}'"
+        ERROR: "Expected format: 'target:url'"
+        ERROR: "Example: 'home:https://example.com, pricing:https://example.com/pricing'"
+        EXIT 1
+
+    target, url = pair.split(":", 1)
+    target = target.strip().lower().replace(" ", "-")
+    url = url.strip()
+
+    url_map[target] = url
+    target_names.append(target)
+
+VALIDATE: len(target_names) > 0, "url-map must contain at least one target:url pair"
+
+primary_target = target_names[0]  # First target as primary style source
+refine_tokens_mode = --refine-tokens OR false
+
+# Parse capture mode
+capture_mode = --capture-mode OR "batch"
+depth = int(--depth OR 3)
+
+# Validate capture mode
+IF capture_mode NOT IN ["batch", "deep"]:
+    ERROR: "Invalid --capture-mode: {capture_mode}"
+    ERROR: "Valid options: batch, deep"
+    EXIT 1
+
+# Validate depth (only for deep mode)
+IF capture_mode == "deep":
+    IF depth NOT IN [1, 2, 3, 4, 5]:
+        ERROR: "Invalid --depth: {depth}"
+        ERROR: "Valid range: 1-5"
+        EXIT 1
+
+    # Warn if multiple URLs in deep mode
+    IF len(target_names) > 1:
+        WARN: "⚠️ Deep mode only uses first URL: '{primary_target}'"
+        WARN: "   Other URLs will be ignored: {', '.join(target_names[1:])}"
+        WARN: "   For multi-URL, use --capture-mode batch"
+
+# Write metadata
+metadata = {
+    "workflow": "imitate-auto",
+    "run_id": run_id,
+    "session_id": session_id,
+    "timestamp": current_timestamp(),
+    "parameters": {
+        "url_map": url_map,
+        "capture_mode": capture_mode,
+        "depth": depth IF capture_mode == "deep" ELSE null,
+        "refine_tokens": refine_tokens_mode,
+        "prompt": --prompt OR null
+    },
+    "targets": target_names,
+    "status": "in_progress"
+}
+
+Write("{base_path}/.run-metadata.json", JSON.stringify(metadata, null, 2))
+
+REPORT: ""
+REPORT: "Configuration:"
+REPORT: "  Capture mode: {capture_mode}"
+IF capture_mode == "deep":
+    REPORT: "    Depth level: {depth} ({DEPTH_NAMES[depth]})"
+    REPORT: "    Target: '{primary_target}' ({url_map[primary_target]})"
+ELSE:
+    REPORT: "    Targets: {len(target_names)} pages"
+    REPORT: "    Primary source: '{primary_target}' ({url_map[primary_target]})"
+    REPORT: "    All targets: {', '.join(target_names)}"
+REPORT: "  Token refinement: {refine_tokens_mode ? 'Enabled (production quality)' : 'Disabled (fast-track)'}"
+IF --prompt:
+    REPORT: "  Prompt guidance: \"{--prompt}\""
+REPORT: ""
+
+# Initialize TodoWrite
+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 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"Assemble UI for {len(target_names)} targets", status: "pending", activeForm: "Assembling UI"},
+  {content: session_id ? "Integrate design system" : "Standalone completion", status: "pending", activeForm: "Completing"}
+]})
+```
+
+### Phase 1: Screenshot Capture (Dual Mode)
+
+```bash
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: f"🚀 Phase 1: Screenshot Capture ({capture_mode} mode)"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+IF capture_mode == "batch":
+    # Mode A: Batch Multi-URL Capture
+    REPORT: "Using batch capture for multiple URLs..."
+
+    # Build url-map string for capture command
+    url_map_command_string = ",".join([f"{name}:{url}" for name, url in url_map.items()])
+
+    # Call capture command
+    capture_command = f"/workflow:ui-design:capture --base-path \"{base_path}\" --url-map \"{url_map_command_string}\""
+
+    REPORT: f"  Command: {capture_command}"
+    REPORT: f"  Targets: {len(target_names)}"
+
+    TRY:
+        SlashCommand(capture_command)
+    CATCH error:
+        ERROR: "Batch capture failed: {error}"
+        ERROR: "Cannot proceed without screenshots"
+        EXIT 1
+
+    # Verify batch capture results
+    screenshot_metadata_path = "{base_path}/screenshots/capture-metadata.json"
+
+    IF NOT exists(screenshot_metadata_path):
+        ERROR: "capture command did not generate metadata file"
+        ERROR: "Expected: {screenshot_metadata_path}"
+        EXIT 1
+
+    screenshot_metadata = Read(screenshot_metadata_path)
+    captured_count = screenshot_metadata.total_captured
+    total_requested = screenshot_metadata.total_requested
+    missing_count = total_requested - captured_count
+
+    REPORT: ""
+    REPORT: "✅ Batch capture complete:"
+    REPORT: "   Captured: {captured_count}/{total_requested} screenshots ({(captured_count/total_requested*100):.1f}%)"
+
+    IF missing_count > 0:
+        missing_targets = [s.target for s in screenshot_metadata.screenshots if not s.captured]
+        WARN: "   ⚠️ Missing {missing_count} screenshots: {', '.join(missing_targets)}"
+        WARN: "   Proceeding with available screenshots for extract phase"
+
+    # If all screenshots failed, terminate
+    IF captured_count == 0:
+        ERROR: "No screenshots captured - cannot proceed"
+        ERROR: "Please check URLs and tool availability"
+        EXIT 1
+
+ELSE:  # capture_mode == "deep"
+    # Mode B: Deep Interactive Layer Exploration
+    REPORT: "Using deep exploration for single URL..."
+
+    primary_url = url_map[primary_target]
+
+    # Call explore-layers command
+    explore_command = f"/workflow:ui-design:explore-layers --url \"{primary_url}\" --depth {depth} --base-path \"{base_path}\""
+
+    REPORT: f"  Command: {explore_command}"
+    REPORT: f"  URL: {primary_url}"
+    REPORT: f"  Depth: {depth} ({DEPTH_NAMES[depth]})"
+
+    TRY:
+        SlashCommand(explore_command)
+    CATCH error:
+        ERROR: "Deep exploration failed: {error}"
+        ERROR: "Cannot proceed without screenshots"
+        EXIT 1
+
+    # Verify deep exploration results
+    layer_map_path = "{base_path}/screenshots/layer-map.json"
+
+    IF NOT exists(layer_map_path):
+        ERROR: "explore-layers did not generate layer-map.json"
+        ERROR: "Expected: {layer_map_path}"
+        EXIT 1
+
+    layer_map = Read(layer_map_path)
+    total_layers = len(layer_map.layers)
+    captured_count = layer_map.summary.total_captures
+
+    REPORT: ""
+    REPORT: "✅ Deep exploration complete:"
+    REPORT: "   Layers: {total_layers} (depth 1-{depth})"
+    REPORT: "   Captures: {captured_count} screenshots"
+    REPORT: "   Total size: {layer_map.summary.total_size_kb:.1f} KB"
+
+    # Count actual images for extract phase
+    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 style (visual tokens)")
+```
+
+### Phase 2: Style Extraction (Visual Tokens)
+
+```bash
+REPORT: ""
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 Phase 2: Extract Style (Visual Tokens)"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Use all screenshots as input to extract single design system
+IF capture_mode == "batch":
+    images_glob = f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}"
+ELSE:  # deep mode
+    images_glob = f"{base_path}/screenshots/**/*.{{png,jpg,jpeg,webp}}"  # Include all depth directories
+
+# Build extraction prompt
+IF --prompt:
+    user_guidance = {--prompt}
+    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 visual style tokens (colors, typography, spacing) from the '{primary_target}' page. Use other screenshots for consistency across all pages."
+
+# 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 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}"
+
+TRY:
+    SlashCommand(extract_command)
+CATCH error:
+    ERROR: "Style extraction failed: {error}"
+    ERROR: "Cannot proceed without visual tokens"
+    EXIT 1
+
+# 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: "style-extract command did not generate style-cards.json"
+    ERROR: "Expected: {style_cards_path}"
+    EXIT 1
+
+style_cards = Read(style_cards_path)
+
+IF len(style_cards.style_cards) != 1:
+    ERROR: "Expected single variant in imitate mode, got {len(style_cards.style_cards)}"
+    EXIT 1
+
+extracted_style = style_cards.style_cards[0]
+
+REPORT: ""
+REPORT: "✅ Phase 2 complete:"
+REPORT: "   Style: '{extracted_style.name}'"
+REPORT: "   Philosophy: {extracted_style.design_philosophy}"
+REPORT: "   Tokens: {count_tokens(extracted_style.proposed_tokens)} visual tokens"
+
+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")
+```
+
+### Phase 3: Token Processing (Conditional Consolidate)
+
+```bash
+REPORT: ""
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 Phase 3: Token Processing"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+IF refine_tokens_mode:
+    # Path A: Full consolidate (production quality)
+    REPORT: "🔧 Using full consolidate for production-ready tokens"
+    REPORT: "   Benefits:"
+    REPORT: "   • Philosophy-driven token refinement"
+    REPORT: "   • WCAG AA accessibility validation"
+    REPORT: "   • Complete design system documentation"
+    REPORT: "   • Token gap filling and consistency checks"
+    REPORT: ""
+
+    consolidate_command = f"/workflow:ui-design:consolidate --base-path \"{base_path}\" --variants 1"
+
+    REPORT: f"Calling consolidate command..."
+
+    TRY:
+        SlashCommand(consolidate_command)
+    CATCH error:
+        ERROR: "Token consolidation failed: {error}"
+        ERROR: "Cannot proceed without refined tokens"
+        EXIT 1
+
+    # consolidate outputs to: {base_path}/style-consolidation/style-1/design-tokens.json
+    tokens_path = "{base_path}/style-consolidation/style-1/design-tokens.json"
+
+    IF NOT exists(tokens_path):
+        ERROR: "consolidate command did not generate design-tokens.json"
+        ERROR: "Expected: {tokens_path}"
+        EXIT 1
+
+    REPORT: ""
+    REPORT: "✅ Full consolidate complete"
+    REPORT: "   Output: style-consolidation/style-1/"
+    REPORT: "   Quality: Production-ready"
+    token_quality = "production-ready (consolidated)"
+    time_spent_estimate = "~60s"
+
+ELSE:
+    # Path B: Fast Token Adaptation
+    REPORT: "⚡ Fast token adaptation (skipping consolidate for speed)"
+    REPORT: "   Note: Using proposed tokens from extraction phase"
+    REPORT: "   For production quality, re-run with --refine-tokens flag"
+    REPORT: ""
+
+    # Directly copy proposed_tokens to consolidation directory
+    style_cards = Read("{base_path}/style-extraction/style-cards.json")
+    proposed_tokens = style_cards.style_cards[0].proposed_tokens
+
+    # Create directory and write tokens
+    consolidation_dir = "{base_path}/style-consolidation/style-1"
+    Bash(mkdir -p "{consolidation_dir}")
+
+    tokens_path = f"{consolidation_dir}/design-tokens.json"
+    Write(tokens_path, JSON.stringify(proposed_tokens, null, 2))
+
+    # Create simplified style guide
+    variant = style_cards.style_cards[0]
+    simple_guide = f"""# Design System: {variant.name}
+
+## Design Philosophy
+{variant.design_philosophy}
+
+## Description
+{variant.description}
+
+## Design Tokens
+All tokens in `design-tokens.json` follow OKLCH color space.
+
+**Note**: Generated in fast-track imitate mode using proposed tokens from extraction.
+For production-ready quality with philosophy-driven refinement, re-run with `--refine-tokens` flag.
+
+## Color Preview
+- Primary: {variant.preview.primary if variant.preview else "N/A"}
+- Background: {variant.preview.background if variant.preview else "N/A"}
+
+## Typography Preview
+- Heading Font: {variant.preview.font_heading if variant.preview else "N/A"}
+
+## Token Categories
+{list_token_categories(proposed_tokens)}
+"""
+
+    Write(f"{consolidation_dir}/style-guide.md", simple_guide)
+
+    REPORT: "✅ Fast adaptation complete (~2s vs ~60s with consolidate)"
+    REPORT: "   Output: style-consolidation/style-1/"
+    REPORT: "   Quality: Proposed (not refined)"
+    REPORT: "   Time saved: ~30-60s"
+    token_quality = "proposed (fast-track)"
+    time_spent_estimate = "~2s"
+
+REPORT: ""
+REPORT: "Token processing summary:"
+REPORT: "   Path: {refine_tokens_mode ? 'Full consolidate' : 'Fast adaptation'}"
+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"Assemble UI for {len(target_names)} targets")
+```
+
+### Phase 4: Batch UI Assembly
+
+```bash
+REPORT: ""
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 Phase 4: Batch UI Assembly"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Build targets string
+targets_string = ",".join(target_names)
+
+# 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 (pure assembler)..."
+REPORT: f"  Targets: {targets_string} (from layout templates)"
+REPORT: f"  Configuration: 1 style × 1 layout × {len(target_names)} pages"
+REPORT: f"  Inputs: layout-templates.json + design-tokens.json"
+
+TRY:
+    SlashCommand(generate_command)
+CATCH error:
+    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 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: "   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, assembled {generated_count}"
+    WARN: "   Some targets may have failed - check generate output"
+
+TodoWrite(mark_completed: f"Assemble UI for {len(target_names)} targets",
+          mark_in_progress: session_id ? "Integrate design system" : "Standalone completion")
+```
+
+### Phase 5: Design System Integration
+
+```bash
+REPORT: ""
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 Phase 5: Design System Integration"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+IF session_id:
+    REPORT: "Integrating design system into session {session_id}..."
+
+    update_command = f"/workflow:ui-design:update --session {session_id}"
+
+    TRY:
+        SlashCommand(update_command)
+    CATCH error:
+        WARN: "Design system integration failed: {error}"
+        WARN: "Prototypes are still available at {base_path}/prototypes/"
+        # Don't terminate, prototypes already generated
+
+    REPORT: "✅ Design system integrated into session {session_id}"
+ELSE:
+    REPORT: "ℹ️ Standalone mode: Skipping integration"
+    REPORT: "   Prototypes available at: {base_path}/prototypes/"
+    REPORT: "   To integrate later:"
+    REPORT: "   1. Create a workflow session"
+    REPORT: "   2. Copy design-tokens.json to session artifacts"
+
+# Update metadata
+metadata = Read("{base_path}/.run-metadata.json")
+metadata.status = "completed"
+metadata.completion_time = current_timestamp()
+metadata.outputs = {
+    "screenshots": f"{base_path}/screenshots/",
+    "style_system": f"{base_path}/style-consolidation/style-1/",
+    "prototypes": f"{base_path}/prototypes/",
+    "token_quality": token_quality,
+    "captured_count": captured_count,
+    "generated_count": generated_count
+}
+Write("{base_path}/.run-metadata.json", JSON.stringify(metadata, null, 2))
+
+TodoWrite(mark_completed: session_id ? "Integrate design system" : "Standalone completion")
+
+# Mark all phases complete
+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: "completed", activeForm: "Capturing"},
+  {content: "Extract unified design system", status: "completed", activeForm: "Extracting"},
+  {content: refine_tokens_mode ? "Refine design tokens via consolidate" : "Fast token adaptation", status: "completed", activeForm: "Processing"},
+  {content: f"Generate UI for {len(target_names)} targets", status: "completed", activeForm: "Generating"},
+  {content: session_id ? "Integrate design system" : "Standalone completion", status: "completed", activeForm: "Completing"}
+]})
+```
+
+### Phase 6: Completion Report
+
+**Completion Message**:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ UI Design Imitate-Auto Complete!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+━━━ 📊 Workflow Summary ━━━
+
+Mode: {capture_mode == "batch" ? "Batch Multi-Page Replication" : f"Deep Interactive Exploration (depth {depth})"}
+Session: {session_id or "standalone"}
+Run ID: {run_id}
+
+Phase 1 - Screenshot Capture: ✅ {IF capture_mode == "batch": f"{captured_count}/{total_requested} screenshots" ELSE: f"{captured_count} screenshots ({total_layers} layers)"}
+  {IF capture_mode == "batch" AND captured_count < total_requested: f"⚠️ {total_requested - captured_count} missing" ELSE: "All targets captured"}
+
+Phase 2 - Style Extraction: ✅ Single unified design system
+  Style: {extracted_style.name}
+  Philosophy: {extracted_style.design_philosophy[:80]}...
+
+Phase 3 - Token Processing: ✅ {token_quality}
+  {IF refine_tokens_mode:
+    "Full consolidate (~60s)"
+    "Quality: Production-ready with philosophy-driven refinement"
+  ELSE:
+    "Fast adaptation (~2s, saved ~30-60s)"
+    "Quality: Proposed tokens (for production, use --refine-tokens)"
+  }
+
+Phase 4 - UI Generation: ✅ {generated_count} pages generated
+  Targets: {', '.join(target_names)}
+  Configuration: 1 style × 1 layout × {generated_count} pages
+
+Phase 5 - Integration: {IF session_id: "✅ Integrated into session" ELSE: "⏭️ Standalone mode"}
+
+━━━ 📂 Output Structure ━━━
+
+{base_path}/
+├── screenshots/                    # {captured_count} screenshots
+{IF capture_mode == "batch":
+│   ├── {target1}.png
+│   ├── {target2}.png
+│   └── capture-metadata.json
+ELSE:
+│   ├── depth-1/
+│   │   └── full-page.png
+│   ├── depth-2/
+│   │   └── {elements}.png
+│   ├── depth-{depth}/
+│   │   └── {layers}.png
+│   └── layer-map.json
+}
+├── style-extraction/               # Design analysis
+│   └── style-cards.json
+├── style-consolidation/            # {token_quality}
+│   └── style-1/
+│       ├── design-tokens.json
+│       └── style-guide.md
+└── prototypes/                     # {generated_count} HTML/CSS files
+    ├── {target1}-style-1-layout-1.html + .css
+    ├── {target2}-style-1-layout-1.html + .css
+    ├── compare.html                # Interactive preview
+    └── index.html                  # Quick navigation
+
+━━━ ⚡ Performance ━━━
+
+Total workflow time: ~{estimate_total_time()} minutes
+  Screenshot capture: ~{capture_time}
+  Style extraction: ~{extract_time}
+  Token processing: ~{token_processing_time}
+  UI generation: ~{generate_time}
+
+━━━ 🌐 Next Steps ━━━
+
+1. Preview prototypes:
+   • Interactive matrix: Open {base_path}/prototypes/compare.html
+   • Quick navigation: Open {base_path}/prototypes/index.html
+
+{IF session_id:
+2. Create implementation tasks:
+   /workflow:plan --session {session_id}
+
+3. Generate tests (if needed):
+   /workflow:test-gen {session_id}
+ELSE:
+2. To integrate into a workflow session:
+   • Create session: /workflow:session:start
+   • Copy design-tokens.json to session artifacts
+
+3. Explore prototypes in {base_path}/prototypes/ directory
+}
+
+{IF NOT refine_tokens_mode:
+💡 Production Quality Tip:
+   Fast-track mode used proposed tokens for speed.
+   For production-ready quality with full token refinement:
+   /workflow:ui-design:imitate-auto --url-map "{url_map_command_string}" --refine-tokens {f"--session {session_id}" if session_id else ""}
+}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize IMMEDIATELY at start of Phase 0 to track multi-phase execution
+TodoWrite({todos: [
+  {content: "Initialize and parse url-map", status: "in_progress", activeForm: "Initializing"},
+  {content: "Batch screenshot capture", status: "pending", activeForm: "Capturing screenshots"},
+  {content: "Extract unified design system", status: "pending", activeForm: "Extracting style"},
+  {content: refine_tokens ? "Refine tokens via consolidate" : "Fast token adaptation", status: "pending", activeForm: "Processing tokens"},
+  {content: "Generate UI for all targets", status: "pending", activeForm: "Generating UI"},
+  {content: "Integrate design system", status: "pending", activeForm: "Integrating"}
+]})
+
+// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
+// 1. SlashCommand blocks and returns when phase is complete
+// 2. Update current phase: status → "completed"
+// 3. Update next phase: status → "in_progress"
+// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
+// This ensures continuous workflow tracking and prevents premature stopping
+```
+
+## Error Handling
+
+### Pre-execution Checks
+- **url-map format validation**: Clear error message with format example
+- **Empty url-map**: Error and exit
+- **Invalid target names**: Regex validation with suggestions
+
+### Phase-Specific Errors
+- **Screenshot capture failure (Phase 1)**:
+  - If total_captured == 0: Terminate workflow
+  - If partial failure: Warn but continue with available screenshots
+
+- **Style extraction failure (Phase 2)**:
+  - If extract fails: Terminate with clear error
+  - If style-cards.json missing: Terminate with debugging info
+
+- **Token processing failure (Phase 3)**:
+  - Consolidate mode: Terminate if consolidate fails
+  - Fast mode: Validate proposed_tokens exist before copying
+
+- **UI generation failure (Phase 4)**:
+  - If generate fails: Terminate with error
+  - If generated_count < target_count: Warn but proceed
+
+- **Integration failure (Phase 5)**:
+  - Non-blocking: Warn but don't terminate
+  - Prototypes already available
+
+### Recovery Strategies
+- **Partial screenshot failure**: Continue with available screenshots, list missing in warning
+- **Generate failure**: Report specific target failures, user can re-generate individually
+- **Integration failure**: Prototypes still usable, can integrate manually
+
+
+## Key Features
+
+- **🚀 Dual Capture**: Batch mode for speed, deep mode for detail
+- **⚡ Fast-Track Option**: Skip consolidate for 30-60s time savings
+- **🎨 High-Fidelity**: Single unified design system from primary target
+- **📦 Autonomous**: No user intervention required between phases
+- **🔄 Reproducible**: Deterministic flow with isolated run directories
+- **🎯 Flexible**: Standalone or session-integrated modes
+
+## Examples
+
+### 1. Basic Multi-Page Replication
+```bash
+/workflow:ui-design:imitate-auto --url-map "home:https://linear.app, features:https://linear.app/features"
+# Result: 2 prototypes with fast-track tokens
+```
+
+### 2. Production-Ready with Session
+```bash
+/workflow:ui-design:imitate-auto --session WFS-payment --url-map "pricing:https://stripe.com/pricing" --refine-tokens
+# Result: 1 prototype with production tokens, integrated into session
+```
+
+### 3. Deep Exploration Mode
+```bash
+/workflow:ui-design:imitate-auto --url-map "app:https://app.com" --capture-mode deep --depth 3
+# Result: Interactive layer capture + prototype
+```
+
+### 4. Guided Style Extraction
+```bash
+/workflow:ui-design:imitate-auto --url-map "home:https://example.com, about:https://example.com/about" --prompt "Focus on minimalist design"
+# Result: 2 prototypes with minimalist style focus
+```
+
+## Integration Points
+
+- **Input**: `--url-map` (multiple target:url pairs) + optional `--capture-mode`, `--depth`, `--session`, `--refine-tokens`, `--prompt`
+- **Output**: Complete design system in `{base_path}/` (screenshots, style-extraction, style-consolidation, prototypes)
+- **Sub-commands Called**:
+  1. Phase 1 (conditional):
+     - `--capture-mode batch`: `/workflow:ui-design:capture` (multi-URL batch)
+     - `--capture-mode deep`: `/workflow:ui-design:explore-layers` (single-URL depth exploration)
+  2. `/workflow:ui-design:extract` (Phase 2)
+  3. `/workflow:ui-design:consolidate` (Phase 3, conditional)
+  4. `/workflow:ui-design:generate` (Phase 4)
+  5. `/workflow:ui-design:update` (Phase 5, if --session)
+
+## Completion Output
+
+```
+✅ UI Design Imitate-Auto Workflow Complete!
+
+Mode: {capture_mode} | Session: {session_id or "standalone"}
+Run ID: {run_id}
+
+Phase 1 - Screenshot Capture: ✅ {captured_count} screenshots
+Phase 2 - Style Extraction: ✅ Single unified design system
+Phase 3 - Token Processing: ✅ {token_quality}
+Phase 4 - UI Generation: ✅ {generated_count} pages generated
+Phase 5 - Integration: {IF session_id: "✅ Integrated" ELSE: "⏭️ Standalone"}
+
+Design Quality:
+✅ High-Fidelity Replication: Accurate style from primary target
+✅ Token-Driven Styling: 100% var() usage
+✅ {IF refine_tokens: "Production-Ready: WCAG validated" ELSE: "Fast-Track: Proposed tokens"}
+
+📂 {base_path}/
+  ├── screenshots/                  # {captured_count} screenshots
+  ├── style-extraction/             # Design analysis
+  ├── style-consolidation/          # {token_quality}
+  └── prototypes/                   # {generated_count} HTML/CSS files
+
+🌐 Preview: {base_path}/prototypes/compare.html
+  - Interactive preview
+  - Side-by-side comparison
+  - {generated_count} replicated pages
+
+Next: [/workflow:execute] OR [Open compare.html → /workflow:plan]
+```

.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}`

.claude/commands/workflow/ui-design/style-extract.md

@@ -0,0 +1,277 @@
+---
+name: style-extract
+description: Extract design style from reference images or text prompts using Claude's analysis
+usage: /workflow:ui-design:style-extract [--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]
+examples:
+  - /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(*)
+---
+
+# Style Extraction Command
+
+## Overview
+Extract design style from reference images or text prompts using Claude's built-in analysis. Generates `style-cards.json` with multiple design variants containing token proposals for consolidation.
+
+**Strategy**: AI-Driven Design Space Exploration
+- **Claude-Native**: 100% Claude analysis, no external tools
+- **Single Output**: `style-cards.json` with embedded token proposals
+- **Flexible Input**: Images, text prompts, or both (hybrid mode)
+- **Maximum Contrast**: AI generates maximally divergent design directions
+
+## Phase 0: Setup & Input Validation
+
+### Step 1: Detect Input Mode, Extraction Mode & Base Path
+```bash
+# Detect input source
+# Priority: --images + --prompt → hybrid | --images → image | --prompt → text
+
+# Determine extraction mode
+# Priority: --mode parameter → default "imitate"
+extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
+
+# Set variants count based on mode
+IF extraction_mode == "imitate":
+    variants_count = 1  # Force single variant for imitate mode (ignore --variants)
+ELSE IF extraction_mode == "explore":
+    variants_count = --variants OR 3  # Default to 3 for explore mode
+    VALIDATE: 1 <= variants_count <= 5
+
+# Determine base path
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# OR use --base-path / --session parameters
+```
+
+### Step 2: Load Inputs
+```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}/style-extraction/)
+```
+
+### Step 3: Memory Check (Skip if Already Done)
+```bash
+# Check if already extracted
+bash(test -f {base_path}/style-extraction/style-cards.json && echo "exists")
+```
+
+**If exists**: Skip to completion message
+
+**Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `loaded_images[]` or `prompt_guidance`
+
+## Phase 1: Design Space Analysis (Explore Mode Only)
+
+### Step 1: Check Extraction Mode
+```bash
+# Check extraction mode
+# extraction_mode == "imitate" → skip this phase
+# extraction_mode == "explore" → execute this phase
+```
+
+**If imitate mode**: Skip to Phase 2
+
+### Step 2: Load Project Context (Explore Mode)
+```bash
+# Load brainstorming context if available
+bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it)
+```
+
+### Step 3: Generate Divergent Directions (Claude Native)
+AI analyzes requirements and generates `variants_count` maximally contrasting design directions:
+
+**Input**: User prompt + project context + image count
+**Analysis**: 6D attribute space (color saturation, visual weight, formality, organic/geometric, innovation, density)
+**Output**: JSON with divergent_directions, each having:
+- philosophy_name (2-3 words)
+- design_attributes (specific scores)
+- search_keywords (3-5 keywords)
+- anti_keywords (2-3 keywords)
+- rationale (contrast explanation)
+
+### Step 4: Write Design Space Analysis
+```bash
+bash(echo '{design_space_analysis}' > {base_path}/style-extraction/design-space-analysis.json)
+
+# Verify output
+bash(test -f design-space-analysis.json && echo "saved")
+```
+
+**Output**: `design-space-analysis.json` for consolidation phase
+
+## Phase 2: Style Synthesis & File Write
+
+### Step 1: Claude Native Analysis
+AI generates `variants_count` design style proposals:
+
+**Input**:
+- Input mode (image/text/hybrid)
+- Visual references or text guidance
+- Design space analysis (explore mode only)
+- Variant-specific directions (explore mode only)
+
+**Analysis Rules**:
+- **Explore mode**: Each variant follows pre-defined philosophy and attributes, maintains maximum contrast
+- **Imitate mode**: High-fidelity replication of reference design
+- OKLCH color format
+- Complete token proposals (colors, typography, spacing, border_radius, shadows, breakpoints)
+- WCAG AA accessibility (4.5:1 text, 3:1 UI)
+
+**Output Format**: `style-cards.json` with:
+- extraction_metadata (session_id, input_mode, extraction_mode, timestamp, variants_count)
+- style_cards[] (id, name, description, design_philosophy, preview, proposed_tokens)
+
+### Step 2: Write Style Cards
+```bash
+bash(echo '{style_cards_json}' > {base_path}/style-extraction/style-cards.json)
+```
+
+**Output**: `style-cards.json` with `variants_count` complete variants
+
+## Completion
+
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
+  {content: "Design space analysis (explore mode)", status: "completed", activeForm: "Analyzing design space"},
+  {content: "Style synthesis and file write", status: "completed", activeForm: "Generating style cards"}
+]});
+```
+
+### Output Message
+```
+✅ Style extraction complete!
+
+Configuration:
+- Session: {session_id}
+- Extraction Mode: {extraction_mode} (imitate/explore)
+- Input Mode: {input_mode} (image/text/hybrid)
+- Variants: {variants_count}
+
+{IF extraction_mode == "explore":
+Design Space Analysis:
+- {variants_count} maximally contrasting design directions
+- Min contrast distance: {design_space_analysis.contrast_verification.min_pairwise_distance}
+}
+
+Generated Variants:
+{FOR each card: - {card.name} - {card.design_philosophy}}
+
+Output Files:
+- {base_path}/style-extraction/style-cards.json
+{IF extraction_mode == "explore": - {base_path}/style-extraction/design-space-analysis.json}
+
+Next: /workflow:ui-design:consolidate --session {session_id} --variants {variants_count}
+```
+
+## Simple Bash Commands
+
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Expand image pattern
+bash(ls {images_pattern})
+
+# Create output directory
+bash(mkdir -p {base_path}/style-extraction/)
+```
+
+### Validation Commands
+```bash
+# Check if already extracted
+bash(test -f {base_path}/style-extraction/style-cards.json && echo "exists")
+
+# Count variants
+bash(cat style-cards.json | grep -c "\"id\": \"variant-")
+
+# Validate JSON
+bash(cat style-cards.json | grep -q "extraction_metadata" && echo "valid")
+```
+
+### File Operations
+```bash
+# Load brainstorming context
+bash(test -f .brainstorming/synthesis-specification.md && cat it)
+
+# Write output
+bash(echo '{json}' > {base_path}/style-extraction/style-cards.json)
+
+# Verify output
+bash(test -f design-space-analysis.json && echo "saved")
+```
+
+## Output Structure
+
+```
+{base_path}/style-extraction/
+├── style-cards.json              # Complete style variants with token proposals
+└── design-space-analysis.json    # Design directions (explore mode only)
+```
+
+## style-cards.json Format
+
+```json
+{
+  "extraction_metadata": {"session_id": "...", "input_mode": "image|text|hybrid", "extraction_mode": "imitate|explore", "timestamp": "...", "variants_count": N},
+  "style_cards": [
+    {
+      "id": "variant-1", "name": "Style Name", "description": "...",
+      "design_philosophy": "Core principles",
+      "preview": {"primary": "oklch(...)", "background": "oklch(...)", "font_heading": "...", "border_radius": "..."},
+      "proposed_tokens": {
+        "colors": {"brand": {...}, "surface": {...}, "semantic": {...}, "text": {...}, "border": {...}},
+        "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}},
+        "spacing": {"0": "0", ..., "24": "6rem"},
+        "border_radius": {"none": "0", ..., "full": "9999px"},
+        "shadows": {"sm": "...", ..., "xl": "..."},
+        "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
+      }
+    }
+    // Repeat for all variants
+  ]
+}
+```
+
+**Requirements**: All colors in OKLCH format, complete token proposals, semantic naming
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: No images found
+→ Check glob pattern
+
+ERROR: Invalid prompt
+→ Provide non-empty string
+
+ERROR: Claude JSON parsing error
+→ Retry with stricter format
+```
+
+## Key Features
+
+- **AI-Driven Design Space Exploration** - 6D attribute space analysis for maximum contrast
+- **Variant-Specific Directions** - Each variant has unique philosophy, keywords, anti-patterns
+- **Maximum Contrast Guarantee** - Variants maximally distant in attribute space
+- **Claude-Native** - No external tools, fast deterministic synthesis
+- **Flexible Input** - Images, text, or hybrid mode
+- **Production-Ready** - OKLCH colors, WCAG AA, semantic naming
+
+## Integration
+
+**Input**: Reference images or text prompts
+**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`.

.claude/commands/workflow/ui-design/update.md

@@ -1,96 +1,102 @@
 ---
 name: update
-description: Update brainstorming artifacts with finalized design system
+description: Update brainstorming artifacts with finalized design system references
 usage: /workflow:ui-design:update --session <session_id> [--selected-prototypes "<list>"]
-argument-hint: "--session WFS-session-id [--selected-prototypes \"dashboard-variant-1,auth-variant-2\"]"
 examples:
   - /workflow:ui-design:update --session WFS-auth
   - /workflow:ui-design:update --session WFS-dashboard --selected-prototypes "dashboard-variant-1"
-allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*), Bash(*)
+allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
 # Design Update Command
 
 ## Overview
-Synchronize finalized design system (tokens, style guide, selected prototypes) back to brainstorming artifacts, preparing for `/workflow:plan` phase consumption.
+
+Synchronize finalized design system references to brainstorming artifacts, preparing them for `/workflow:plan` consumption. This command updates **references only** (via @ notation), not content duplication.
 
 ## Core Philosophy
-- **Main Claude Execution**: Direct updates by main Claude (avoid Agent context loss, following synthesis pattern)
-- **Reference-Based Integration**: Use @ references, not content duplication
+
+- **Reference-Only Updates**: Use @ references, no content duplication
+- **Main Claude Execution**: Direct updates by main Claude (no Agent handoff)
 - **Synthesis Alignment**: Update synthesis-specification.md UI/UX Guidelines section
-- **UI Designer Sync**: Mirror design system to ui-designer/style-guide.md
 - **Plan-Ready Output**: Ensure design artifacts discoverable by task-generate
+- **Minimal Reading**: Verify file existence, don't read design content
 
 ## Execution Protocol
 
-### Phase 1: Session & Design System Validation
+### Phase 1: Session & Artifact Validation
+
 ```bash
-# Validate session and verify design system completeness
-CHECK: .workflow/.active-* marker files
-VALIDATE: session_id matches active session
+# Validate session
+CHECK: .workflow/.active-* marker files; VALIDATE: session_id matches active session
 
-VERIFY required artifacts:
-- .design/style-consolidation/design-tokens.json
-- .design/style-consolidation/style-guide.md
-- .design/style-consolidation/tailwind.config.js
-- .design/prototypes/*.html (at least one prototype)
+# Verify design artifacts in latest design run
+latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-*")
 
-IF --selected-prototypes provided:
-    VALIDATE: Specified prototypes exist
+# Detect design system structure (unified vs separate)
+IF exists({latest_design}/style-consolidation/design-tokens.json):
+    design_system_mode = "unified"; design_tokens_path = "style-consolidation/design-tokens.json"; style_guide_path = "style-consolidation/style-guide.md"
+ELSE IF exists({latest_design}/style-consolidation/style-1/design-tokens.json):
+    design_system_mode = "separate"; design_tokens_path = "style-consolidation/style-1/design-tokens.json"; style_guide_path = "style-consolidation/style-1/style-guide.md"
 ELSE:
-    AUTO-SELECT: Use all generated prototypes
+    ERROR: "No design tokens found. Run /workflow:ui-design:consolidate first"
+
+VERIFY: {latest_design}/{design_tokens_path}, {latest_design}/{style_guide_path}, {latest_design}/prototypes/*.html
+
+REPORT: "📋 Design system mode: {design_system_mode} | Tokens: {design_tokens_path}"
+
+# Prototype selection
+selected_list = --selected-prototypes ? parse_comma_separated(--selected-prototypes) : Glob({latest_design}/prototypes/*.html)
+VALIDATE: Specified prototypes exist IF --selected-prototypes
+
+REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
 ```
 
-### Phase 2: Load Design System Context
-**Direct Claude Code Execution** (no Agent invocation)
+### Phase 1.1: Memory Check (Skip if Already Updated)
 
 ```bash
-# Load all design system artifacts
-Read(.workflow/WFS-{session}/.design/style-consolidation/design-tokens.json)
-Read(.workflow/WFS-{session}/.design/style-consolidation/style-guide.md)
-Read(.workflow/WFS-{session}/.design/style-consolidation/tailwind.config.js)
-Read(.workflow/WFS-{session}/.design/style-consolidation/validation-report.json)
+# Check if synthesis-specification.md contains current design run reference
+synthesis_spec_path = ".workflow/WFS-{session}/.brainstorming/synthesis-specification.md"
+current_design_run = basename(latest_design)  # e.g., "design-run-20250109-143022"
 
-# Load selected prototype files
-FOR each selected_prototype IN selected_prototypes:
-    Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}.html)
-    Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}-notes.md)
+IF exists(synthesis_spec_path):
+    synthesis_content = Read(synthesis_spec_path)
+    IF "## UI/UX Guidelines" in synthesis_content AND current_design_run in synthesis_content:
+        REPORT: "✅ Design system references already updated (found in memory)"
+        REPORT: "   Skipping: Phase 2-5 (Load Target Artifacts, Update Synthesis, Update UI Designer Guide, Completion)"
+        EXIT 0
+```
 
-# Load target brainstorming artifacts
+### Phase 2: Load Target Artifacts Only
+
+**What to Load**: Only the files we need to **update**, not the design files we're referencing.
+
+```bash
+# Load target brainstorming artifacts (files to be updated)
 Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
-Read(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md) [if exists]
+IF exists(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md): Read(analysis.md)
+
+# Optional: Read prototype notes for descriptions (minimal context)
+FOR each selected_prototype IN selected_list:
+    Read({latest_design}/prototypes/{selected_prototype}-notes.md)  # Extract: layout_strategy, page_name only
+
+# Note: Do NOT read design-tokens.json, style-guide.md, or prototype HTML. Only verify existence and generate @ references.
 ```
 
 ### Phase 3: Update Synthesis Specification
-**Direct Write by Main Claude**
 
-Update `.brainstorming/synthesis-specification.md`:
+Update `.brainstorming/synthesis-specification.md` with design system references.
 
+**Target Section**: `## UI/UX Guidelines`
+
+**Content Template**:
 ```markdown
 ## UI/UX Guidelines
 
 ### Design System Reference
-**Finalized Design Tokens**: @../.design/style-consolidation/design-tokens.json
-**Style Guide**: @../.design/style-consolidation/style-guide.md
-**Tailwind Configuration**: @../.design/style-consolidation/tailwind.config.js
-
-### Design Philosophy
-[Extract philosophy section from style-guide.md]
-
-### Token System Overview
-**Colors**: OKLCH-based color system with semantic naming
-- Brand: primary, secondary, accent
-- Surface: background, elevated, sunken
-- Semantic: success, warning, error, info
-
-**Typography**: {font_family_count} font families, {scale_count}-step scale
-- Heading: {heading_font}
-- Body: {body_font}
-- Monospace: {mono_font}
-
-**Spacing**: {scale_count}-step scale ({min}rem to {max}rem)
-
-**Components**: Border radius, shadows, and component tokens defined
+**Finalized Design Tokens**: @../design-{run_id}/{design_tokens_path}
+**Style Guide**: @../design-{run_id}/{style_guide_path}
+**Design System Mode**: {design_system_mode}
 
 ### Implementation Requirements
 **Token Adherence**: All UI implementations MUST use design token CSS custom properties
@@ -99,68 +105,41 @@ Update `.brainstorming/synthesis-specification.md`:
 **Component Patterns**: Follow patterns documented in style-guide.md
 
 ### Reference Prototypes
-[For each selected prototype:]
-- **{page_name}**: @../.design/prototypes/{prototype}.html
-  - Layout: {layout_description from notes}
-  - Components: {component_list from notes}
-  - Token Usage: {token_usage_summary from notes}
-
-### Design System Assets (for task-generate consumption)
-```json
-{
-  "design_tokens": ".design/style-consolidation/design-tokens.json",
-  "style_guide": ".design/style-consolidation/style-guide.md",
-  "tailwind_config": ".design/style-consolidation/tailwind.config.js",
-  "prototypes": [
-    ".design/prototypes/{prototype-1}.html",
-    ".design/prototypes/{prototype-2}.html"
-  ]
+{FOR each selected_prototype:
+- **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html | Layout: {layout_strategy from notes}
 }
+
+### Design System Assets
+```json
+{"design_tokens": "design-{run_id}/{design_tokens_path}", "style_guide": "design-{run_id}/{style_guide_path}", "design_system_mode": "{design_system_mode}", "prototypes": [{FOR each: "design-{run_id}/prototypes/{prototype}.html"}]}
 ```
 ```
 
 **Implementation**:
 ```bash
-# Edit synthesis-specification.md
-Edit(
-  file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
-  old_string="## UI/UX Guidelines\n[existing content or empty]",
-  new_string="## UI/UX Guidelines\n\n[new design system content with @ references]"
-)
+# Option 1: Edit existing section
+Edit(file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
+     old_string="## UI/UX Guidelines\n[existing content]",
+     new_string="## UI/UX Guidelines\n\n[new design reference content]")
+
+# Option 2: Append if section doesn't exist
+IF section not found:
+    Edit(file_path="...", old_string="[end of document]", new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]")
 ```
 
-### Phase 4: Update UI Designer Analysis
-**Create or update** `.brainstorming/ui-designer/style-guide.md`:
+### Phase 4: Update UI Designer Style Guide
+
+Create or update `.brainstorming/ui-designer/style-guide.md`:
 
 ```markdown
 # UI Designer Style Guide
 
 ## Design System Integration
-This style guide integrates the finalized design system from the design refinement phase.
+This style guide references the finalized design system from the design refinement phase.
 
-**Source Design Tokens**: @../../.design/style-consolidation/design-tokens.json
-**Source Style Guide**: @../../.design/style-consolidation/style-guide.md
-
-## Design Philosophy
-[Extract philosophy section from source style-guide.md]
-
-## Design Tokens Reference
-For complete token definitions, see: @../../.design/style-consolidation/design-tokens.json
-
-### Color System
-[Summary of color tokens]
-
-### Typography System
-[Summary of typography tokens]
-
-### Spacing System
-[Summary of spacing tokens]
-
-### Component Tokens
-[Summary of component tokens: border-radius, shadows]
-
-## Component Patterns
-[Reference to style-guide.md component patterns]
+**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
+**Style Guide**: @../../design-{run_id}/{style_guide_path}
+**Design System Mode**: {design_system_mode}
 
 ## Implementation Guidelines
 1. **Use CSS Custom Properties**: All styles reference design tokens
@@ -169,62 +148,49 @@ For complete token definitions, see: @../../.design/style-consolidation/design-t
 4. **Responsive Design**: Mobile-first with token-based breakpoints
 
 ## Reference Prototypes
-[Links to selected prototypes with descriptions]
+{FOR each selected_prototype:
+- **{page_name}**: @../../design-{run_id}/prototypes/{prototype}.html
+}
+
+## Token System
+For complete token definitions and usage examples, see:
+- Design Tokens: @../../design-{run_id}/{design_tokens_path}
+- Style Guide: @../../design-{run_id}/{style_guide_path}
 
 ---
-*Auto-generated by /workflow:design:design-update*
-*Last updated: {timestamp}*
+*Auto-generated by /workflow:ui-design:update | Last updated: {timestamp}*
 ```
 
 **Implementation**:
 ```bash
-Write(
-  file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
-  content="[generated style guide content with @ references]"
-)
+Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
+      content="[generated content with @ references]")
 ```
 
-### Phase 5: Create Design System Symlinks (Optional)
-**For easier task-generate discovery**
+### Phase 5: Completion
 
-```bash
-# Create read-only mirror of key design files in brainstorming space
-bash(cd .workflow/WFS-{session}/.brainstorming && \
-     ln -s ../.design/style-consolidation/design-tokens.json design-tokens.json && \
-     ln -s ../.design/style-consolidation/style-guide.md design-style-guide.md)
-```
-
-### Phase 6: TodoWrite Integration
 ```javascript
-TodoWrite({
-  todos: [
-    {
-      content: "Validate session and design system completeness",
-      status: "completed",
-      activeForm: "Validating design system"
-    },
-    {
-      content: "Load design tokens, style guide, and selected prototypes",
-      status: "completed",
-      activeForm: "Loading design artifacts"
-    },
-    {
-      content: "Update synthesis-specification.md with design system references",
-      status: "completed",
-      activeForm: "Updating synthesis specification"
-    },
-    {
-      content: "Create or update ui-designer/style-guide.md",
-      status: "completed",
-      activeForm: "Updating UI designer style guide"
-    },
-    {
-      content: "Create design system symlinks for task-generate discovery",
-      status: "completed",
-      activeForm: "Creating artifact symlinks"
-    }
-  ]
-});
+TodoWrite({todos: [
+  {content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"},
+  {content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"},
+  {content: "Update synthesis-specification.md with design references", status: "completed", activeForm: "Updating synthesis spec"},
+  {content: "Create/update ui-designer/style-guide.md", status: "completed", activeForm: "Updating UI designer guide"}
+]});
+```
+
+**Completion Message**:
+```
+✅ Design system references updated for session: WFS-{session}
+
+Updated artifacts:
+✓ synthesis-specification.md - UI/UX Guidelines section with @ references
+✓ ui-designer/style-guide.md - Design system reference guide
+
+Design system assets ready for /workflow:plan:
+- design-tokens.json | style-guide.md | {prototype_count} reference prototypes
+
+Next: /workflow:plan [--agent] "<task description>"
+      The plan phase will automatically discover and utilize the design system.
 ```
 
 ## Output Structure
@@ -233,116 +199,89 @@ TodoWrite({
 ```
 .workflow/WFS-{session}/.brainstorming/
 ├── synthesis-specification.md       # Updated with UI/UX Guidelines section
-├── ui-designer/
-│   └── style-guide.md               # New or updated comprehensive style guide
-├── design-tokens.json               # Symlink to ../.design/style-consolidation/design-tokens.json
-└── design-style-guide.md            # Symlink to ../.design/style-consolidation/style-guide.md
+└── ui-designer/
+    └── style-guide.md               # New or updated design reference guide
 ```
 
-**Reference Structure** (@ references in synthesis-specification.md):
-- `@../.design/style-consolidation/design-tokens.json`
-- `@../.design/style-consolidation/style-guide.md`
-- `@../.design/style-consolidation/tailwind.config.js`
-- `@../.design/prototypes/{prototype}.html`
+**@ Reference Format** (synthesis-specification.md):
+```
+@../design-{run_id}/style-consolidation/design-tokens.json
+@../design-{run_id}/style-consolidation/style-guide.md
+@../design-{run_id}/prototypes/{prototype}.html
+```
 
-## Integration with task-generate
+**@ Reference Format** (ui-designer/style-guide.md):
+```
+@../../design-{run_id}/style-consolidation/design-tokens.json
+@../../design-{run_id}/style-consolidation/style-guide.md
+@../../design-{run_id}/prototypes/{prototype}.html
+```
 
-After this update, `/workflow:tools:task-generate` will discover:
+## Integration with /workflow:plan
 
-**In context.artifacts**:
+After this update, `/workflow:plan` will discover design assets through:
+
+**Phase 3: Intelligent Analysis** (`/workflow:tools:concept-enhanced`)
+- Reads synthesis-specification.md → Discovers @ references → Includes design system context in ANALYSIS_RESULTS.md
+
+**Phase 4: Task Generation** (`/workflow:tools:task-generate`)
+- Reads ANALYSIS_RESULTS.md → Discovers design assets → Includes design system paths in task JSON files
+
+**Example Task JSON** (generated by task-generate):
 ```json
 {
-  "artifacts": [
-    {
-      "type": "synthesis_specification",
-      "path": ".brainstorming/synthesis-specification.md"
-    },
-    {
-      "type": "design_tokens",
-      "path": ".design/style-consolidation/design-tokens.json"
-    },
-    {
-      "type": "style_guide",
-      "path": ".design/style-consolidation/style-guide.md"
-    },
-    {
-      "type": "tailwind_config",
-      "path": ".design/style-consolidation/tailwind.config.js"
-    },
-    {
-      "type": "ui_prototypes",
-      "paths": [
-        ".design/prototypes/dashboard-variant-1.html",
-        ".design/prototypes/auth-variant-2.html"
-      ]
+  "task_id": "IMPL-001",
+  "context": {
+    "design_system": {
+      "tokens": "design-{run_id}/style-consolidation/design-tokens.json",
+      "style_guide": "design-{run_id}/style-consolidation/style-guide.md",
+      "prototypes": ["design-{run_id}/prototypes/dashboard-variant-1.html"]
     }
-  ]
-}
-```
-
-**In flow_control.pre_analysis** (for UI tasks):
-```json
-{
-  "step": "load_design_tokens",
-  "action": "Load design system tokens and style guide",
-  "commands": [
-    "bash(cat .workflow/WFS-{session}/.design/style-consolidation/design-tokens.json)",
-    "bash(cat .workflow/WFS-{session}/.design/style-consolidation/style-guide.md)"
-  ],
-  "output_to": "design_system_context",
-  "on_error": "warn"
+  }
 }
 ```
 
 ## Error Handling
-- **Missing design tokens**: Error, run `/workflow:ui-design:consolidate` first
-- **Missing prototypes**: Error, run `/workflow:ui-design:generate` first
-- **synthesis-specification.md not found**: Warning, create minimal version
-- **Edit conflicts**: Preserve existing content, append design system section
-- **Symlink failures**: Warning only, continue with @ references
+
+- **Missing design artifacts**: Error with message "Run /workflow:ui-design:consolidate and /workflow:ui-design:generate first"
+- **synthesis-specification.md not found**: Warning, create minimal version with just UI/UX Guidelines
+- **ui-designer/ directory missing**: Create directory and file
+- **Edit conflicts**: Preserve existing content, append or replace only UI/UX Guidelines section
+- **Invalid prototype names**: Skip invalid entries, continue with valid ones
 
 ## Validation Checks
+
 After update, verify:
 - [ ] synthesis-specification.md contains UI/UX Guidelines section
-- [ ] UI/UX Guidelines include @ references to design system files
+- [ ] UI/UX Guidelines include @ references (not content duplication)
 - [ ] ui-designer/style-guide.md created or updated
-- [ ] design-tokens.json symlink created (if applicable)
-- [ ] All referenced files exist and are readable
+- [ ] All @ referenced files exist and are accessible
+- [ ] @ reference paths are relative and correct
+
+## Key Features
+
+1. **Reference-Only Updates**: Uses @ notation for file references, no content duplication, lightweight and maintainable
+2. **Main Claude Direct Execution**: No Agent handoff (preserves context), simple reference generation, reliable path resolution
+3. **Plan-Ready Output**: `/workflow:plan` Phase 3 can discover design system, task generation includes design asset paths, clear integration points
+4. **Minimal Reading**: Only reads target files to update, verifies design file existence (no content reading), optional prototype notes for descriptions
+5. **Flexible Prototype Selection**: Auto-select all prototypes (default), manual selection via --selected-prototypes parameter, validates existence
 
 ## Integration Points
-- **Input**: design-tokens.json, style-guide.md, prototypes from design phase
-- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md
-- **Next Phase**: `/workflow:plan` can now discover and utilize design system
 
-## Completion Message
+- **Input**: Design system artifacts from `/workflow:ui-design:consolidate` and `/workflow:ui-design:generate`
+- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md with @ references
+- **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references
+- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
 
-```
-Design system update complete for session: WFS-{session}
-
-Updated artifacts:
-✓ synthesis-specification.md - UI/UX Guidelines section added
-✓ ui-designer/style-guide.md - Comprehensive style guide created
-✓ Design system references: @ notation for all design files
-
-Design system assets ready for task generation:
-- design-tokens.json ({token_count} tokens)
-- style-guide.md (comprehensive component patterns)
-- tailwind.config.js (Tailwind theme extension)
-- {prototype_count} reference prototypes
-
-Next: /workflow:plan [--agent] "<task description>"
-      The plan phase will automatically discover and utilize the design system.
-```
-
-## Main Claude Direct Execution Rationale
+## Why Main Claude Execution?
 
 This command is executed directly by main Claude (not delegated to an Agent) because:
 
-1. **Context Preservation**: Main Claude has full session context and conversation memory
-2. **Integration Complexity**: Requires understanding multiple artifact relationships
-3. **Reference Accuracy**: @ reference generation needs precise path resolution
-4. **Synthesis Pattern**: Follows the same direct-execution pattern as `/workflow:brainstorm:synthesis`
-5. **Minimal Transformation**: Primarily reference integration, not generative analysis
-6. **Error Recovery**: Main Claude can better handle edit conflicts and missing files
+1. **Simple Reference Generation**: Only generating file paths, not complex synthesis
+2. **Context Preservation**: Main Claude has full session and conversation context
+3. **Minimal Transformation**: Primarily updating references, not analyzing content
+4. **Path Resolution**: Requires precise relative path calculation
+5. **Edit Operations**: Better error recovery for Edit conflicts
+6. **Synthesis Pattern**: Follows same direct-execution pattern as other reference updates
 
-This approach ensures reliable, context-aware integration without Agent handoff overhead.
+This ensures reliable, lightweight integration without Agent handoff overhead.

.claude/scripts/convert_tokens_to_css.sh

@@ -0,0 +1,225 @@
+#!/bin/bash
+# Convert design-tokens.json to tokens.css with Google Fonts import and global font rules
+# Usage: cat design-tokens.json | ./convert_tokens_to_css.sh > tokens.css
+# Or: ./convert_tokens_to_css.sh < design-tokens.json > tokens.css
+
+# Read JSON from stdin
+json_input=$(cat)
+
+# Extract metadata for header comment
+style_name=$(echo "$json_input" | jq -r '.meta.name // "Unknown Style"' 2>/dev/null || echo "Design Tokens")
+
+# Generate header
+cat <<EOF
+/* ========================================
+   Design Tokens: ${style_name}
+   Auto-generated from design-tokens.json
+   ======================================== */
+
+EOF
+
+# ========================================
+# Google Fonts Import Generation
+# ========================================
+# Extract font families and generate Google Fonts import URL
+fonts=$(echo "$json_input" | jq -r '
+  .typography.font_family | to_entries[] | .value
+' 2>/dev/null | sed "s/'//g" | cut -d',' -f1 | sort -u)
+
+# Build Google Fonts URL
+google_fonts_url="https://fonts.googleapis.com/css2?"
+font_params=""
+
+while IFS= read -r font; do
+  # Skip system fonts and empty lines
+  if [[ -z "$font" ]] || [[ "$font" =~ ^(system-ui|sans-serif|serif|monospace|cursive|fantasy)$ ]]; then
+    continue
+  fi
+
+  # Special handling for common web fonts with weights
+  case "$font" in
+    "Comic Neue")
+      font_params+="family=Comic+Neue:wght@300;400;700&"
+      ;;
+    "Patrick Hand"|"Caveat"|"Dancing Script"|"Architects Daughter"|"Indie Flower"|"Shadows Into Light"|"Permanent Marker")
+      # URL-encode font name and add common weights
+      encoded_font=$(echo "$font" | sed 's/ /+/g')
+      font_params+="family=${encoded_font}:wght@400;700&"
+      ;;
+    "Segoe Print"|"Bradley Hand"|"Chilanka")
+      # These are system fonts, skip
+      ;;
+    *)
+      # Generic font: add with default weights
+      encoded_font=$(echo "$font" | sed 's/ /+/g')
+      font_params+="family=${encoded_font}:wght@400;500;600;700&"
+      ;;
+  esac
+done <<< "$fonts"
+
+# Generate @import if we have fonts
+if [[ -n "$font_params" ]]; then
+  # Remove trailing &
+  font_params="${font_params%&}"
+  echo "/* Import Web Fonts */"
+  echo "@import url('${google_fonts_url}${font_params}&display=swap');"
+  echo ""
+fi
+
+# ========================================
+# CSS Custom Properties Generation
+# ========================================
+echo ":root {"
+
+# Colors - Brand
+echo "  /* Colors - Brand */"
+echo "$json_input" | jq -r '
+  .colors.brand | to_entries[] |
+  "  --color-brand-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Colors - Surface
+echo "  /* Colors - Surface */"
+echo "$json_input" | jq -r '
+  .colors.surface | to_entries[] |
+  "  --color-surface-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Colors - Semantic
+echo "  /* Colors - Semantic */"
+echo "$json_input" | jq -r '
+  .colors.semantic | to_entries[] |
+  "  --color-semantic-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Colors - Text
+echo "  /* Colors - Text */"
+echo "$json_input" | jq -r '
+  .colors.text | to_entries[] |
+  "  --color-text-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Colors - Border
+echo "  /* Colors - Border */"
+echo "$json_input" | jq -r '
+  .colors.border | to_entries[] |
+  "  --color-border-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Typography - Font Family
+echo "  /* Typography - Font Family */"
+echo "$json_input" | jq -r '
+  .typography.font_family | to_entries[] |
+  "  --font-family-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Typography - Font Size
+echo "  /* Typography - Font Size */"
+echo "$json_input" | jq -r '
+  .typography.font_size | to_entries[] |
+  "  --font-size-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Typography - Font Weight
+echo "  /* Typography - Font Weight */"
+echo "$json_input" | jq -r '
+  .typography.font_weight | to_entries[] |
+  "  --font-weight-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Typography - Line Height
+echo "  /* Typography - Line Height */"
+echo "$json_input" | jq -r '
+  .typography.line_height | to_entries[] |
+  "  --line-height-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Typography - Letter Spacing
+echo "  /* Typography - Letter Spacing */"
+echo "$json_input" | jq -r '
+  .typography.letter_spacing | to_entries[] |
+  "  --letter-spacing-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Spacing
+echo "  /* Spacing */"
+echo "$json_input" | jq -r '
+  .spacing | to_entries[] |
+  "  --spacing-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Border Radius
+echo "  /* Border Radius */"
+echo "$json_input" | jq -r '
+  .border_radius | to_entries[] |
+  "  --border-radius-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Shadows
+echo "  /* Shadows */"
+echo "$json_input" | jq -r '
+  .shadows | to_entries[] |
+  "  --shadow-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Breakpoints
+echo "  /* Breakpoints */"
+echo "$json_input" | jq -r '
+  .breakpoints | to_entries[] |
+  "  --breakpoint-\(.key): \(.value);"
+' 2>/dev/null
+
+echo "}"
+echo ""
+
+# ========================================
+# Global Font Application
+# ========================================
+echo "/* ========================================"
+echo "   Global Font Application"
+echo "   ======================================== */"
+echo ""
+echo "body {"
+echo "  font-family: var(--font-family-body);"
+echo "  font-size: var(--font-size-base);"
+echo "  line-height: var(--line-height-normal);"
+echo "  color: var(--color-text-primary);"
+echo "  background-color: var(--color-surface-background);"
+echo "}"
+echo ""
+echo "h1, h2, h3, h4, h5, h6, legend {"
+echo "  font-family: var(--font-family-heading);"
+echo "}"
+echo ""
+echo "/* Reset default margins for better control */"
+echo "* {"
+echo "  margin: 0;"
+echo "  padding: 0;"
+echo "  box-sizing: border-box;"
+echo "}"

.claude/scripts/ui-generate-preview.sh

@@ -0,0 +1,391 @@
+#!/bin/bash
+#
+# UI Generate Preview v2.0 - Template-Based Preview Generation
+# Purpose: Generate compare.html and index.html using template substitution
+# Template: ~/.claude/workflows/_template-compare-matrix.html
+#
+# Usage: ui-generate-preview.sh <prototypes_dir> [--template <path>]
+#
+
+set -e
+
+# Color output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Default template path
+TEMPLATE_PATH="$HOME/.claude/workflows/_template-compare-matrix.html"
+
+# Parse arguments
+prototypes_dir="${1:-.}"
+shift || true
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --template)
+            TEMPLATE_PATH="$2"
+            shift 2
+            ;;
+        *)
+            echo -e "${RED}Unknown option: $1${NC}"
+            exit 1
+            ;;
+    esac
+done
+
+if [[ ! -d "$prototypes_dir" ]]; then
+    echo -e "${RED}Error: Directory not found: $prototypes_dir${NC}"
+    exit 1
+fi
+
+cd "$prototypes_dir" || exit 1
+
+echo -e "${GREEN}📊 Auto-detecting matrix dimensions...${NC}"
+
+# Auto-detect styles, layouts, targets from file patterns
+# Pattern: {target}-style-{s}-layout-{l}.html
+styles=$(find . -maxdepth 1 -name "*-style-*-layout-*.html" | \
+         sed 's/.*-style-\([0-9]\+\)-.*/\1/' | sort -un)
+layouts=$(find . -maxdepth 1 -name "*-style-*-layout-*.html" | \
+          sed 's/.*-layout-\([0-9]\+\)\.html/\1/' | sort -un)
+targets=$(find . -maxdepth 1 -name "*-style-*-layout-*.html" | \
+          sed 's/\.\///; s/-style-.*//' | sort -u)
+
+S=$(echo "$styles" | wc -l)
+L=$(echo "$layouts" | wc -l)
+T=$(echo "$targets" | wc -l)
+
+echo -e "   Detected: ${GREEN}${S}${NC} styles × ${GREEN}${L}${NC} layouts × ${GREEN}${T}${NC} targets"
+
+if [[ $S -eq 0 ]] || [[ $L -eq 0 ]] || [[ $T -eq 0 ]]; then
+    echo -e "${RED}Error: No prototype files found matching pattern {target}-style-{s}-layout-{l}.html${NC}"
+    exit 1
+fi
+
+# ============================================================================
+# Generate compare.html from template
+# ============================================================================
+
+echo -e "${YELLOW}🎨 Generating compare.html from template...${NC}"
+
+if [[ ! -f "$TEMPLATE_PATH" ]]; then
+    echo -e "${RED}Error: Template not found: $TEMPLATE_PATH${NC}"
+    exit 1
+fi
+
+# Build pages/targets JSON array
+PAGES_JSON="["
+first=true
+for target in $targets; do
+    if [[ "$first" == true ]]; then
+        first=false
+    else
+        PAGES_JSON+=", "
+    fi
+    PAGES_JSON+="\"$target\""
+done
+PAGES_JSON+="]"
+
+# Generate metadata
+RUN_ID="run-$(date +%Y%m%d-%H%M%S)"
+SESSION_ID="standalone"
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u +"%Y-%m-%d")
+
+# Replace placeholders in template
+cat "$TEMPLATE_PATH" | \
+    sed "s|{{run_id}}|${RUN_ID}|g" | \
+    sed "s|{{session_id}}|${SESSION_ID}|g" | \
+    sed "s|{{timestamp}}|${TIMESTAMP}|g" | \
+    sed "s|{{style_variants}}|${S}|g" | \
+    sed "s|{{layout_variants}}|${L}|g" | \
+    sed "s|{{pages_json}}|${PAGES_JSON}|g" \
+    > compare.html
+
+echo -e "${GREEN}   ✓ Generated compare.html from template${NC}"
+
+# ============================================================================
+# Generate index.html
+# ============================================================================
+
+echo -e "${YELLOW}📋 Generating index.html...${NC}"
+
+cat > index.html << 'EOF'
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>UI Prototypes Index</title>
+    <style>
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            max-width: 1200px;
+            margin: 0 auto;
+            padding: 40px 20px;
+            background: #f5f5f5;
+        }
+        h1 { margin-bottom: 10px; color: #333; }
+        .subtitle { color: #666; margin-bottom: 30px; }
+        .cta {
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            padding: 20px;
+            border-radius: 8px;
+            margin-bottom: 30px;
+            box-shadow: 0 4px 6px rgba(0,0,0,0.1);
+        }
+        .cta h2 { margin-bottom: 10px; }
+        .cta a {
+            display: inline-block;
+            background: white;
+            color: #667eea;
+            padding: 10px 20px;
+            border-radius: 6px;
+            text-decoration: none;
+            font-weight: 600;
+            margin-top: 10px;
+        }
+        .cta a:hover { background: #f8f9fa; }
+        .style-section {
+            background: white;
+            padding: 20px;
+            border-radius: 8px;
+            margin-bottom: 20px;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }
+        .style-section h2 {
+            color: #495057;
+            margin-bottom: 15px;
+            padding-bottom: 10px;
+            border-bottom: 2px solid #e9ecef;
+        }
+        .target-group {
+            margin-bottom: 20px;
+        }
+        .target-group h3 {
+            color: #6c757d;
+            font-size: 16px;
+            margin-bottom: 10px;
+        }
+        .link-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+            gap: 10px;
+        }
+        .prototype-link {
+            padding: 12px 16px;
+            background: #f8f9fa;
+            border: 1px solid #dee2e6;
+            border-radius: 6px;
+            text-decoration: none;
+            color: #495057;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            transition: all 0.2s;
+        }
+        .prototype-link:hover {
+            background: #e9ecef;
+            border-color: #667eea;
+            transform: translateX(2px);
+        }
+        .prototype-link .label { font-weight: 500; }
+        .prototype-link .icon { color: #667eea; }
+    </style>
+</head>
+<body>
+    <h1>🎨 UI Prototypes Index</h1>
+    <p class="subtitle">Generated __S__×__L__×__T__ = __TOTAL__ prototypes</p>
+
+    <div class="cta">
+        <h2>📊 Interactive Comparison</h2>
+        <p>View all styles and layouts side-by-side in an interactive matrix</p>
+        <a href="compare.html">Open Matrix View →</a>
+    </div>
+
+    <h2>📂 All Prototypes</h2>
+__CONTENT__
+</body>
+</html>
+EOF
+
+# Build content HTML
+CONTENT=""
+for style in $styles; do
+    CONTENT+="<div class='style-section'>"$'\n'
+    CONTENT+="<h2>Style ${style}</h2>"$'\n'
+
+    for target in $targets; do
+        target_capitalized="$(echo ${target:0:1} | tr '[:lower:]' '[:upper:]')${target:1}"
+        CONTENT+="<div class='target-group'>"$'\n'
+        CONTENT+="<h3>${target_capitalized}</h3>"$'\n'
+        CONTENT+="<div class='link-grid'>"$'\n'
+
+        for layout in $layouts; do
+            html_file="${target}-style-${style}-layout-${layout}.html"
+            if [[ -f "$html_file" ]]; then
+                CONTENT+="<a href='${html_file}' class='prototype-link' target='_blank'>"$'\n'
+                CONTENT+="<span class='label'>Layout ${layout}</span>"$'\n'
+                CONTENT+="<span class='icon'>↗</span>"$'\n'
+                CONTENT+="</a>"$'\n'
+            fi
+        done
+
+        CONTENT+="</div></div>"$'\n'
+    done
+
+    CONTENT+="</div>"$'\n'
+done
+
+# Calculate total
+TOTAL_PROTOTYPES=$((S * L * T))
+
+# Replace placeholders (using a temp file for complex replacement)
+{
+    echo "$CONTENT" > /tmp/content_tmp.txt
+    sed "s|__S__|${S}|g" index.html | \
+        sed "s|__L__|${L}|g" | \
+        sed "s|__T__|${T}|g" | \
+        sed "s|__TOTAL__|${TOTAL_PROTOTYPES}|g" | \
+        sed -e "/__CONTENT__/r /tmp/content_tmp.txt" -e "/__CONTENT__/d" > /tmp/index_tmp.html
+    mv /tmp/index_tmp.html index.html
+    rm -f /tmp/content_tmp.txt
+}
+
+echo -e "${GREEN}   ✓ Generated index.html${NC}"
+
+# ============================================================================
+# Generate PREVIEW.md
+# ============================================================================
+
+echo -e "${YELLOW}📝 Generating PREVIEW.md...${NC}"
+
+cat > PREVIEW.md << EOF
+# UI Prototypes Preview Guide
+
+Generated: $(date +"%Y-%m-%d %H:%M:%S")
+
+## 📊 Matrix Dimensions
+
+- **Styles**: ${S}
+- **Layouts**: ${L}
+- **Targets**: ${T}
+- **Total Prototypes**: $((S*L*T))
+
+## 🌐 How to View
+
+### Option 1: Interactive Matrix (Recommended)
+
+Open \`compare.html\` in your browser to see all prototypes in an interactive matrix view.
+
+**Features**:
+- Side-by-side comparison of all styles and layouts
+- Switch between targets using the dropdown
+- Adjust grid columns for better viewing
+- Direct links to full-page views
+- Selection system with export to JSON
+- Fullscreen mode for detailed inspection
+
+### Option 2: Simple Index
+
+Open \`index.html\` for a simple list of all prototypes with direct links.
+
+### Option 3: Direct File Access
+
+Each prototype can be opened directly:
+- Pattern: \`{target}-style-{s}-layout-{l}.html\`
+- Example: \`dashboard-style-1-layout-1.html\`
+
+## 📁 File Structure
+
+\`\`\`
+prototypes/
+├── compare.html           # Interactive matrix view
+├── index.html             # Simple navigation index
+├── PREVIEW.md             # This file
+EOF
+
+for style in $styles; do
+    for target in $targets; do
+        for layout in $layouts; do
+            echo "├── ${target}-style-${style}-layout-${layout}.html" >> PREVIEW.md
+            echo "├── ${target}-style-${style}-layout-${layout}.css" >> PREVIEW.md
+        done
+    done
+done
+
+cat >> PREVIEW.md << 'EOF2'
+```
+
+## 🎨 Style Variants
+
+EOF2
+
+for style in $styles; do
+    cat >> PREVIEW.md << EOF3
+### Style ${style}
+
+EOF3
+    style_guide="../style-consolidation/style-${style}/style-guide.md"
+    if [[ -f "$style_guide" ]]; then
+        head -n 10 "$style_guide" | tail -n +2 >> PREVIEW.md 2>/dev/null || echo "Design philosophy and tokens" >> PREVIEW.md
+    else
+        echo "Design system ${style}" >> PREVIEW.md
+    fi
+    echo "" >> PREVIEW.md
+done
+
+cat >> PREVIEW.md << 'EOF4'
+
+## 🎯 Targets
+
+EOF4
+
+for target in $targets; do
+    target_capitalized="$(echo ${target:0:1} | tr '[:lower:]' '[:upper:]')${target:1}"
+    echo "- **${target_capitalized}**: ${L} layouts × ${S} styles = $((L*S)) variations" >> PREVIEW.md
+done
+
+cat >> PREVIEW.md << 'EOF5'
+
+## 💡 Tips
+
+1. **Comparison**: Use compare.html to see how different styles affect the same layout
+2. **Navigation**: Use index.html for quick access to specific prototypes
+3. **Selection**: Mark favorites in compare.html using star icons
+4. **Export**: Download selection JSON for implementation planning
+5. **Inspection**: Open browser DevTools to inspect HTML structure and CSS
+6. **Sharing**: All files are standalone - can be shared or deployed directly
+
+## 📝 Next Steps
+
+1. Review prototypes in compare.html
+2. Select preferred style × layout combinations
+3. Export selections as JSON
+4. Provide feedback for refinement
+5. Use selected designs for implementation
+
+---
+
+Generated by /workflow:ui-design:generate-v2 (Style-Centric Architecture)
+EOF5
+
+echo -e "${GREEN}   ✓ Generated PREVIEW.md${NC}"
+
+# ============================================================================
+# Completion Summary
+# ============================================================================
+
+echo ""
+echo -e "${GREEN}✅ Preview generation complete!${NC}"
+echo -e "   Files created: compare.html, index.html, PREVIEW.md"
+echo -e "   Matrix: ${S} styles × ${L} layouts × ${T} targets = $((S*L*T)) prototypes"
+echo ""
+echo -e "${YELLOW}🌐 Next Steps:${NC}"
+echo -e "   1. Open compare.html for interactive matrix view"
+echo -e "   2. Open index.html for simple navigation"
+echo -e "   3. Read PREVIEW.md for detailed usage guide"
+echo ""

.claude/scripts/ui-instantiate-prototypes.sh

@@ -0,0 +1,811 @@
+#!/bin/bash
+
+# UI Prototype Instantiation Script with Preview Generation (v3.0 - Auto-detect)
+# Purpose: Generate S × L × P final prototypes from templates + interactive preview files
+# Usage:
+#   Simple: ui-instantiate-prototypes.sh <prototypes_dir>
+#   Full:   ui-instantiate-prototypes.sh <base_path> <pages> <style_variants> <layout_variants> [options]
+
+# Use safer error handling
+set -o pipefail
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+log_info() {
+    echo "$1"
+}
+
+log_success() {
+    echo "✅ $1"
+}
+
+log_error() {
+    echo "❌ $1"
+}
+
+log_warning() {
+    echo "⚠️  $1"
+}
+
+# Auto-detect pages from templates directory
+auto_detect_pages() {
+    local templates_dir="$1/_templates"
+
+    if [ ! -d "$templates_dir" ]; then
+        log_error "Templates directory not found: $templates_dir"
+        return 1
+    fi
+
+    # Find unique page names from template files (e.g., login-layout-1.html -> login)
+    local pages=$(find "$templates_dir" -name "*-layout-*.html" -type f | \
+                  sed 's|.*/||' | \
+                  sed 's|-layout-[0-9]*\.html||' | \
+                  sort -u | \
+                  tr '\n' ',' | \
+                  sed 's/,$//')
+
+    echo "$pages"
+}
+
+# Auto-detect style variants count
+auto_detect_style_variants() {
+    local base_path="$1"
+    local style_dir="$base_path/../style-consolidation"
+
+    if [ ! -d "$style_dir" ]; then
+        log_warning "Style consolidation directory not found: $style_dir"
+        echo "3"  # Default
+        return
+    fi
+
+    # Count style-* directories
+    local count=$(find "$style_dir" -maxdepth 1 -type d -name "style-*" | wc -l)
+
+    if [ "$count" -eq 0 ]; then
+        echo "3"  # Default
+    else
+        echo "$count"
+    fi
+}
+
+# Auto-detect layout variants count
+auto_detect_layout_variants() {
+    local templates_dir="$1/_templates"
+
+    if [ ! -d "$templates_dir" ]; then
+        echo "3"  # Default
+        return
+    fi
+
+    # Find the first page and count its layouts
+    local first_page=$(find "$templates_dir" -name "*-layout-1.html" -type f | head -1 | sed 's|.*/||' | sed 's|-layout-1\.html||')
+
+    if [ -z "$first_page" ]; then
+        echo "3"  # Default
+        return
+    fi
+
+    # Count layout files for this page
+    local count=$(find "$templates_dir" -name "${first_page}-layout-*.html" -type f | wc -l)
+
+    if [ "$count" -eq 0 ]; then
+        echo "3"  # Default
+    else
+        echo "$count"
+    fi
+}
+
+# ============================================================================
+# Parse Arguments
+# ============================================================================
+
+show_usage() {
+    cat <<'EOF'
+Usage:
+  Simple (auto-detect): ui-instantiate-prototypes.sh <prototypes_dir> [options]
+  Full:                 ui-instantiate-prototypes.sh <base_path> <pages> <style_variants> <layout_variants> [options]
+
+Simple Mode (Recommended):
+  prototypes_dir    Path to prototypes directory (auto-detects everything)
+
+Full Mode:
+  base_path         Base path to prototypes directory
+  pages             Comma-separated list of pages/components
+  style_variants    Number of style variants (1-5)
+  layout_variants   Number of layout variants (1-5)
+
+Options:
+  --run-id <id>         Run ID (default: auto-generated)
+  --session-id <id>     Session ID (default: standalone)
+  --mode <page|component>  Exploration mode (default: page)
+  --template <path>     Path to compare.html template (default: ~/.claude/workflows/_template-compare-matrix.html)
+  --no-preview          Skip preview file generation
+  --help                Show this help message
+
+Examples:
+  # Simple usage (auto-detect everything)
+  ui-instantiate-prototypes.sh .design/prototypes
+
+  # With options
+  ui-instantiate-prototypes.sh .design/prototypes --session-id WFS-auth
+
+  # Full manual mode
+  ui-instantiate-prototypes.sh .design/prototypes "login,dashboard" 3 3 --session-id WFS-auth
+EOF
+}
+
+# Default values
+BASE_PATH=""
+PAGES=""
+STYLE_VARIANTS=""
+LAYOUT_VARIANTS=""
+RUN_ID="run-$(date +%Y%m%d-%H%M%S)"
+SESSION_ID="standalone"
+MODE="page"
+TEMPLATE_PATH="$HOME/.claude/workflows/_template-compare-matrix.html"
+GENERATE_PREVIEW=true
+AUTO_DETECT=false
+
+# Parse arguments
+if [ $# -lt 1 ]; then
+    log_error "Missing required arguments"
+    show_usage
+    exit 1
+fi
+
+# Check if using simple mode (only 1 positional arg before options)
+if [ $# -eq 1 ] || [[ "$2" == --* ]]; then
+    # Simple mode - auto-detect
+    AUTO_DETECT=true
+    BASE_PATH="$1"
+    shift 1
+else
+    # Full mode - manual parameters
+    if [ $# -lt 4 ]; then
+        log_error "Full mode requires 4 positional arguments"
+        show_usage
+        exit 1
+    fi
+
+    BASE_PATH="$1"
+    PAGES="$2"
+    STYLE_VARIANTS="$3"
+    LAYOUT_VARIANTS="$4"
+    shift 4
+fi
+
+# Parse optional arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --run-id)
+            RUN_ID="$2"
+            shift 2
+            ;;
+        --session-id)
+            SESSION_ID="$2"
+            shift 2
+            ;;
+        --mode)
+            MODE="$2"
+            shift 2
+            ;;
+        --template)
+            TEMPLATE_PATH="$2"
+            shift 2
+            ;;
+        --no-preview)
+            GENERATE_PREVIEW=false
+            shift
+            ;;
+        --help)
+            show_usage
+            exit 0
+            ;;
+        *)
+            log_error "Unknown option: $1"
+            show_usage
+            exit 1
+            ;;
+    esac
+done
+
+# ============================================================================
+# Auto-detection (if enabled)
+# ============================================================================
+
+if [ "$AUTO_DETECT" = true ]; then
+    log_info "🔍 Auto-detecting configuration from directory..."
+
+    # Detect pages
+    PAGES=$(auto_detect_pages "$BASE_PATH")
+    if [ -z "$PAGES" ]; then
+        log_error "Could not auto-detect pages from templates"
+        exit 1
+    fi
+    log_info "   Pages: $PAGES"
+
+    # Detect style variants
+    STYLE_VARIANTS=$(auto_detect_style_variants "$BASE_PATH")
+    log_info "   Style variants: $STYLE_VARIANTS"
+
+    # Detect layout variants
+    LAYOUT_VARIANTS=$(auto_detect_layout_variants "$BASE_PATH")
+    log_info "   Layout variants: $LAYOUT_VARIANTS"
+
+    echo ""
+fi
+
+# ============================================================================
+# Validation
+# ============================================================================
+
+# Validate base path
+if [ ! -d "$BASE_PATH" ]; then
+    log_error "Base path not found: $BASE_PATH"
+    exit 1
+fi
+
+# Validate style and layout variants
+if [ "$STYLE_VARIANTS" -lt 1 ] || [ "$STYLE_VARIANTS" -gt 5 ]; then
+    log_error "Style variants must be between 1 and 5 (got: $STYLE_VARIANTS)"
+    exit 1
+fi
+
+if [ "$LAYOUT_VARIANTS" -lt 1 ] || [ "$LAYOUT_VARIANTS" -gt 5 ]; then
+    log_error "Layout variants must be between 1 and 5 (got: $LAYOUT_VARIANTS)"
+    exit 1
+fi
+
+# Validate STYLE_VARIANTS against actual style directories
+if [ "$STYLE_VARIANTS" -gt 0 ]; then
+    style_dir="$BASE_PATH/../style-consolidation"
+
+    if [ ! -d "$style_dir" ]; then
+        log_error "Style consolidation directory not found: $style_dir"
+        log_info "Run /workflow:ui-design:consolidate first"
+        exit 1
+    fi
+
+    actual_styles=$(find "$style_dir" -maxdepth 1 -type d -name "style-*" 2>/dev/null | wc -l)
+
+    if [ "$actual_styles" -eq 0 ]; then
+        log_error "No style directories found in: $style_dir"
+        log_info "Run /workflow:ui-design:consolidate first to generate style design systems"
+        exit 1
+    fi
+
+    if [ "$STYLE_VARIANTS" -gt "$actual_styles" ]; then
+        log_warning "Requested $STYLE_VARIANTS style variants, but only found $actual_styles directories"
+        log_info "Available style directories:"
+        find "$style_dir" -maxdepth 1 -type d -name "style-*" 2>/dev/null | sed 's|.*/||' | sort
+        log_info "Auto-correcting to $actual_styles style variants"
+        STYLE_VARIANTS=$actual_styles
+    fi
+fi
+
+# Parse pages into array
+IFS=',' read -ra PAGE_ARRAY <<< "$PAGES"
+
+if [ ${#PAGE_ARRAY[@]} -eq 0 ]; then
+    log_error "No pages found"
+    exit 1
+fi
+
+# ============================================================================
+# Header Output
+# ============================================================================
+
+echo "========================================="
+echo "UI Prototype Instantiation & Preview"
+if [ "$AUTO_DETECT" = true ]; then
+    echo "(Auto-detected configuration)"
+fi
+echo "========================================="
+echo "Base Path: $BASE_PATH"
+echo "Mode: $MODE"
+echo "Pages/Components: $PAGES"
+echo "Style Variants: $STYLE_VARIANTS"
+echo "Layout Variants: $LAYOUT_VARIANTS"
+echo "Run ID: $RUN_ID"
+echo "Session ID: $SESSION_ID"
+echo "========================================="
+echo ""
+
+# Change to base path
+cd "$BASE_PATH" || exit 1
+
+# ============================================================================
+# Phase 1: Instantiate Prototypes
+# ============================================================================
+
+log_info "🚀 Phase 1: Instantiating prototypes from templates..."
+echo ""
+
+total_generated=0
+total_failed=0
+
+for page in "${PAGE_ARRAY[@]}"; do
+    # Trim whitespace
+    page=$(echo "$page" | xargs)
+
+    log_info "Processing page/component: $page"
+
+    for s in $(seq 1 "$STYLE_VARIANTS"); do
+        for l in $(seq 1 "$LAYOUT_VARIANTS"); do
+            # Define file paths
+            TEMPLATE_HTML="_templates/${page}-layout-${l}.html"
+            STRUCTURAL_CSS="_templates/${page}-layout-${l}.css"
+            TOKEN_CSS="../style-consolidation/style-${s}/tokens.css"
+            OUTPUT_HTML="${page}-style-${s}-layout-${l}.html"
+
+            # Copy template and replace placeholders
+            if [ -f "$TEMPLATE_HTML" ]; then
+                cp "$TEMPLATE_HTML" "$OUTPUT_HTML" || {
+                    log_error "Failed to copy template: $TEMPLATE_HTML"
+                    ((total_failed++))
+                    continue
+                }
+
+                # Replace CSS placeholders (Windows-compatible sed syntax)
+                sed -i "s|{{STRUCTURAL_CSS}}|${STRUCTURAL_CSS}|g" "$OUTPUT_HTML" || true
+                sed -i "s|{{TOKEN_CSS}}|${TOKEN_CSS}|g" "$OUTPUT_HTML" || true
+
+                log_success "Created: $OUTPUT_HTML"
+                ((total_generated++))
+
+                # Create implementation notes (simplified)
+                NOTES_FILE="${page}-style-${s}-layout-${l}-notes.md"
+
+                # Generate notes with simple heredoc
+                cat > "$NOTES_FILE" <<NOTESEOF
+# Implementation Notes: ${page}-style-${s}-layout-${l}
+
+## Generation Details
+- **Template**: ${TEMPLATE_HTML}
+- **Structural CSS**: ${STRUCTURAL_CSS}
+- **Style Tokens**: ${TOKEN_CSS}
+- **Layout Strategy**: Layout ${l}
+- **Style Variant**: Style ${s}
+- **Mode**: ${MODE}
+
+## Template Reuse
+This prototype was generated from a shared layout template to ensure consistency
+across all style variants. The HTML structure is identical for all ${page}-layout-${l}
+prototypes, with only the design tokens (colors, fonts, spacing) varying.
+
+## Design System Reference
+Refer to \`../style-consolidation/style-${s}/style-guide.md\` for:
+- Design philosophy
+- Token usage guidelines
+- Component patterns
+- Accessibility requirements
+
+## Customization
+To modify this prototype:
+1. Edit the layout template: \`${TEMPLATE_HTML}\` (affects all styles)
+2. Edit the structural CSS: \`${STRUCTURAL_CSS}\` (affects all styles)
+3. Edit design tokens: \`${TOKEN_CSS}\` (affects only this style variant)
+
+## Run Information
+- **Run ID**: ${RUN_ID}
+- **Session ID**: ${SESSION_ID}
+- **Generated**: $(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u +%Y-%m-%d)
+NOTESEOF
+
+            else
+                log_error "Template not found: $TEMPLATE_HTML"
+                ((total_failed++))
+            fi
+        done
+    done
+done
+
+echo ""
+log_success "Phase 1 complete: Generated ${total_generated} prototypes"
+if [ $total_failed -gt 0 ]; then
+    log_warning "Failed: ${total_failed} prototypes"
+fi
+echo ""
+
+# ============================================================================
+# Phase 2: Generate Preview Files (if enabled)
+# ============================================================================
+
+if [ "$GENERATE_PREVIEW" = false ]; then
+    log_info "⏭️  Skipping preview generation (--no-preview flag)"
+    exit 0
+fi
+
+log_info "🎨 Phase 2: Generating preview files..."
+echo ""
+
+# ============================================================================
+# 2a. Generate compare.html from template
+# ============================================================================
+
+if [ ! -f "$TEMPLATE_PATH" ]; then
+    log_warning "Template not found: $TEMPLATE_PATH"
+    log_info "   Skipping compare.html generation"
+else
+    log_info "📄 Generating compare.html from template..."
+
+    # Convert page array to JSON format
+    PAGES_JSON="["
+    for i in "${!PAGE_ARRAY[@]}"; do
+        page=$(echo "${PAGE_ARRAY[$i]}" | xargs)
+        PAGES_JSON+="\"$page\""
+        if [ $i -lt $((${#PAGE_ARRAY[@]} - 1)) ]; then
+            PAGES_JSON+=", "
+        fi
+    done
+    PAGES_JSON+="]"
+
+    TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u +%Y-%m-%d)
+
+    # Read template and replace placeholders
+    cat "$TEMPLATE_PATH" | \
+        sed "s|{{run_id}}|${RUN_ID}|g" | \
+        sed "s|{{session_id}}|${SESSION_ID}|g" | \
+        sed "s|{{timestamp}}|${TIMESTAMP}|g" | \
+        sed "s|{{style_variants}}|${STYLE_VARIANTS}|g" | \
+        sed "s|{{layout_variants}}|${LAYOUT_VARIANTS}|g" | \
+        sed "s|{{pages_json}}|${PAGES_JSON}|g" \
+        > compare.html
+
+    log_success "Generated: compare.html"
+fi
+
+# ============================================================================
+# 2b. Generate index.html
+# ============================================================================
+
+log_info "📄 Generating index.html..."
+
+# Calculate total prototypes
+TOTAL_PROTOTYPES=$((STYLE_VARIANTS * LAYOUT_VARIANTS * ${#PAGE_ARRAY[@]}))
+
+# Generate index.html with simple heredoc
+cat > index.html <<'INDEXEOF'
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>UI Prototypes - __MODE__ Mode - __RUN_ID__</title>
+  <style>
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      max-width: 900px;
+      margin: 2rem auto;
+      padding: 0 2rem;
+      background: #f9fafb;
+    }
+    .header {
+      background: white;
+      padding: 2rem;
+      border-radius: 0.75rem;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+      margin-bottom: 2rem;
+    }
+    h1 {
+      color: #2563eb;
+      margin-bottom: 0.5rem;
+      font-size: 2rem;
+    }
+    .meta {
+      color: #6b7280;
+      font-size: 0.875rem;
+      margin-top: 0.5rem;
+    }
+    .info {
+      background: #f3f4f6;
+      padding: 1.5rem;
+      border-radius: 0.5rem;
+      margin: 1.5rem 0;
+      border-left: 4px solid #2563eb;
+    }
+    .cta {
+      display: inline-block;
+      background: #2563eb;
+      color: white;
+      padding: 1rem 2rem;
+      border-radius: 0.5rem;
+      text-decoration: none;
+      font-weight: 600;
+      margin: 1rem 0;
+      transition: background 0.2s;
+    }
+    .cta:hover {
+      background: #1d4ed8;
+    }
+    .stats {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+      gap: 1rem;
+      margin: 1.5rem 0;
+    }
+    .stat {
+      background: white;
+      border: 1px solid #e5e7eb;
+      padding: 1.5rem;
+      border-radius: 0.5rem;
+      text-align: center;
+      box-shadow: 0 1px 2px rgba(0,0,0,0.05);
+    }
+    .stat-value {
+      font-size: 2.5rem;
+      font-weight: bold;
+      color: #2563eb;
+      margin-bottom: 0.25rem;
+    }
+    .stat-label {
+      color: #6b7280;
+      font-size: 0.875rem;
+    }
+    .section {
+      background: white;
+      padding: 2rem;
+      border-radius: 0.75rem;
+      margin-bottom: 2rem;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+    }
+    h2 {
+      color: #1f2937;
+      margin-bottom: 1rem;
+      font-size: 1.5rem;
+    }
+    ul {
+      line-height: 1.8;
+      color: #374151;
+    }
+    .pages-list {
+      list-style: none;
+      padding: 0;
+    }
+    .pages-list li {
+      background: #f9fafb;
+      padding: 0.75rem 1rem;
+      margin: 0.5rem 0;
+      border-radius: 0.375rem;
+      border-left: 3px solid #2563eb;
+    }
+    .badge {
+      display: inline-block;
+      background: #dbeafe;
+      color: #1e40af;
+      padding: 0.25rem 0.75rem;
+      border-radius: 0.25rem;
+      font-size: 0.75rem;
+      font-weight: 600;
+      margin-left: 0.5rem;
+    }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>🎨 UI Prototype __MODE__ Mode</h1>
+    <div class="meta">
+      <strong>Run ID:</strong> __RUN_ID__ |
+      <strong>Session:</strong> __SESSION_ID__ |
+      <strong>Generated:</strong> __TIMESTAMP__
+    </div>
+  </div>
+
+  <div class="info">
+    <p><strong>Matrix Configuration:</strong> __STYLE_VARIANTS__ styles × __LAYOUT_VARIANTS__ layouts × __PAGE_COUNT__ __MODE__s</p>
+    <p><strong>Total Prototypes:</strong> __TOTAL_PROTOTYPES__ interactive HTML files</p>
+  </div>
+
+  <a href="compare.html" class="cta">🔍 Open Interactive Matrix Comparison →</a>
+
+  <div class="stats">
+    <div class="stat">
+      <div class="stat-value">__STYLE_VARIANTS__</div>
+      <div class="stat-label">Style Variants</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value">__LAYOUT_VARIANTS__</div>
+      <div class="stat-label">Layout Options</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value">__PAGE_COUNT__</div>
+      <div class="stat-label">__MODE__s</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value">__TOTAL_PROTOTYPES__</div>
+      <div class="stat-label">Total Prototypes</div>
+    </div>
+  </div>
+
+  <div class="section">
+    <h2>🌟 Features</h2>
+    <ul>
+      <li><strong>Interactive Matrix View:</strong> __STYLE_VARIANTS__×__LAYOUT_VARIANTS__ grid with synchronized scrolling</li>
+      <li><strong>Flexible Zoom:</strong> 25%, 50%, 75%, 100% viewport scaling</li>
+      <li><strong>Fullscreen Mode:</strong> Detailed view for individual prototypes</li>
+      <li><strong>Selection System:</strong> Mark favorites with export to JSON</li>
+      <li><strong>__MODE__ Switcher:</strong> Compare different __MODE__s side-by-side</li>
+      <li><strong>Persistent State:</strong> Selections saved in localStorage</li>
+    </ul>
+  </div>
+
+  <div class="section">
+    <h2>📄 Generated __MODE__s</h2>
+    <ul class="pages-list">
+__PAGES_LIST__
+    </ul>
+  </div>
+
+  <div class="section">
+    <h2>📚 Next Steps</h2>
+    <ol>
+      <li>Open <code>compare.html</code> to explore all variants in matrix view</li>
+      <li>Use zoom and sync scroll controls to compare details</li>
+      <li>Select your preferred style×layout combinations</li>
+      <li>Export selections as JSON for implementation planning</li>
+      <li>Review implementation notes in <code>*-notes.md</code> files</li>
+    </ol>
+  </div>
+</body>
+</html>
+INDEXEOF
+
+# Build pages list HTML
+PAGES_LIST_HTML=""
+for page in "${PAGE_ARRAY[@]}"; do
+    page=$(echo "$page" | xargs)
+    VARIANT_COUNT=$((STYLE_VARIANTS * LAYOUT_VARIANTS))
+    PAGES_LIST_HTML+="      <li>\n"
+    PAGES_LIST_HTML+="        <strong>${page}</strong>\n"
+    PAGES_LIST_HTML+="        <span class=\"badge\">${STYLE_VARIANTS}×${LAYOUT_VARIANTS} = ${VARIANT_COUNT} variants</span>\n"
+    PAGES_LIST_HTML+="      </li>\n"
+done
+
+# Replace all placeholders in index.html
+MODE_UPPER=$(echo "$MODE" | awk '{print toupper(substr($0,1,1)) tolower(substr($0,2))}')
+sed -i "s|__RUN_ID__|${RUN_ID}|g" index.html
+sed -i "s|__SESSION_ID__|${SESSION_ID}|g" index.html
+sed -i "s|__TIMESTAMP__|${TIMESTAMP}|g" index.html
+sed -i "s|__MODE__|${MODE_UPPER}|g" index.html
+sed -i "s|__STYLE_VARIANTS__|${STYLE_VARIANTS}|g" index.html
+sed -i "s|__LAYOUT_VARIANTS__|${LAYOUT_VARIANTS}|g" index.html
+sed -i "s|__PAGE_COUNT__|${#PAGE_ARRAY[@]}|g" index.html
+sed -i "s|__TOTAL_PROTOTYPES__|${TOTAL_PROTOTYPES}|g" index.html
+sed -i "s|__PAGES_LIST__|${PAGES_LIST_HTML}|g" index.html
+
+log_success "Generated: index.html"
+
+# ============================================================================
+# 2c. Generate PREVIEW.md
+# ============================================================================
+
+log_info "📄 Generating PREVIEW.md..."
+
+cat > PREVIEW.md <<PREVIEWEOF
+# UI Prototype Preview Guide
+
+## Quick Start
+1. Open \`index.html\` for overview and navigation
+2. Open \`compare.html\` for interactive matrix comparison
+3. Use browser developer tools to inspect responsive behavior
+
+## Configuration
+
+- **Exploration Mode:** ${MODE_UPPER}
+- **Run ID:** ${RUN_ID}
+- **Session ID:** ${SESSION_ID}
+- **Style Variants:** ${STYLE_VARIANTS}
+- **Layout Options:** ${LAYOUT_VARIANTS}
+- **${MODE_UPPER}s:** ${PAGES}
+- **Total Prototypes:** ${TOTAL_PROTOTYPES}
+- **Generated:** ${TIMESTAMP}
+
+## File Naming Convention
+
+\`\`\`
+{${MODE}}-style-{s}-layout-{l}.html
+\`\`\`
+
+**Example:** \`dashboard-style-1-layout-2.html\`
+- ${MODE_UPPER}: dashboard
+- Style: Design system 1
+- Layout: Layout variant 2
+
+## Interactive Features (compare.html)
+
+### Matrix View
+- **Grid Layout:** ${STYLE_VARIANTS}×${LAYOUT_VARIANTS} table with all prototypes visible
+- **Synchronized Scroll:** All iframes scroll together (toggle with button)
+- **Zoom Controls:** Adjust viewport scale (25%, 50%, 75%, 100%)
+- **${MODE_UPPER} Selector:** Switch between different ${MODE}s instantly
+
+### Prototype Actions
+- **⭐ Selection:** Click star icon to mark favorites
+- **⛶ Fullscreen:** View prototype in fullscreen overlay
+- **↗ New Tab:** Open prototype in dedicated browser tab
+
+### Selection Export
+1. Select preferred prototypes using star icons
+2. Click "Export Selection" button
+3. Downloads JSON file: \`selection-${RUN_ID}.json\`
+4. Use exported file for implementation planning
+
+## Design System References
+
+Each prototype references a specific style design system:
+PREVIEWEOF
+
+# Add style references
+for s in $(seq 1 "$STYLE_VARIANTS"); do
+    cat >> PREVIEW.md <<STYLEEOF
+
+### Style ${s}
+- **Tokens:** \`../style-consolidation/style-${s}/design-tokens.json\`
+- **CSS Variables:** \`../style-consolidation/style-${s}/tokens.css\`
+- **Style Guide:** \`../style-consolidation/style-${s}/style-guide.md\`
+STYLEEOF
+done
+
+cat >> PREVIEW.md <<'FOOTEREOF'
+
+## Responsive Testing
+
+All prototypes are mobile-first responsive. Test at these breakpoints:
+
+- **Mobile:** 375px - 767px
+- **Tablet:** 768px - 1023px
+- **Desktop:** 1024px+
+
+Use browser DevTools responsive mode for testing.
+
+## Accessibility Features
+
+- Semantic HTML5 structure
+- ARIA attributes for screen readers
+- Keyboard navigation support
+- Proper heading hierarchy
+- Focus indicators
+
+## Next Steps
+
+1. **Review:** Open `compare.html` and explore all variants
+2. **Select:** Mark preferred prototypes using star icons
+3. **Export:** Download selection JSON for implementation
+4. **Implement:** Use `/workflow:ui-design:update` to integrate selected designs
+5. **Plan:** Run `/workflow:plan` to generate implementation tasks
+
+---
+
+**Generated by:** `ui-instantiate-prototypes.sh`
+**Version:** 3.0 (auto-detect mode)
+FOOTEREOF
+
+log_success "Generated: PREVIEW.md"
+
+# ============================================================================
+# Completion Summary
+# ============================================================================
+
+echo ""
+echo "========================================="
+echo "✅ Generation Complete!"
+echo "========================================="
+echo ""
+echo "📊 Summary:"
+echo "   Prototypes: ${total_generated} generated"
+if [ $total_failed -gt 0 ]; then
+    echo "   Failed: ${total_failed}"
+fi
+echo "   Preview Files: compare.html, index.html, PREVIEW.md"
+echo "   Matrix: ${STYLE_VARIANTS}×${LAYOUT_VARIANTS} (${#PAGE_ARRAY[@]} ${MODE}s)"
+echo "   Total Files: ${TOTAL_PROTOTYPES} prototypes + preview files"
+echo ""
+echo "🌐 Next Steps:"
+echo "   1. Open: ${BASE_PATH}/index.html"
+echo "   2. Explore: ${BASE_PATH}/compare.html"
+echo "   3. Review: ${BASE_PATH}/PREVIEW.md"
+echo ""
+echo "Performance: Template-based approach with ${STYLE_VARIANTS}× speedup"
+echo "========================================="

.claude/workflows/intelligent-tools-strategy.md

@@ -19,8 +19,8 @@ type: strategic-guideline
 ## ⚡ Core Framework
 
 ### Tool Overview
-- **Gemini**: Analysis, understanding, exploration & documentation
-- **Qwen**: Architecture analysis, code generation & implementation
+- **Gemini**: Analysis, understanding, exploration & documentation (primary)
+- **Qwen**: Analysis, understanding, exploration & documentation (fallback, same capabilities as Gemini)
 - **Codex**: Development, implementation & automation
 
 ### Decision Principles
@@ -32,8 +32,8 @@ type: strategic-guideline
 - **⚠️ Write operation protection** - For local codebase write/modify operations, require EXPLICIT user confirmation unless user provides clear instructions containing MODE=write or MODE=auto
 
 ### Quick Decision Rules
-1. **Exploring/Understanding?** → Start with Gemini
-2. **Architecture/Code generation?** → Start with Qwen
+1. **Exploring/Understanding?** → Start with Gemini (fallback to Qwen if needed)
+2. **Architecture/Analysis?** → Start with Gemini (fallback to Qwen if needed)
 3. **Building/Fixing?** → Start with Codex
 4. **Not sure?** → Use multiple tools in parallel
 5. **Small task?** → Still use tools - they're faster than manual work
@@ -56,15 +56,16 @@ type: strategic-guideline
 
 ### Qwen
 - **Command**: `~/.claude/scripts/qwen-wrapper`
-- **Strengths**: Architecture analysis, pattern recognition
-- **Best For**: System design analysis, architectural review
-- **Permissions**: Architecture analysis only, no automatic code generation
+- **Strengths**: Large context window, pattern recognition (same as Gemini)
+- **Best For**: Analysis, documentation generation, code exploration (fallback option when Gemini unavailable)
+- **Permissions**: Default read-only analysis, MODE=write requires explicit specification (auto-enables --approval-mode yolo)
 - **Default MODE**: `analysis` (read-only)
-- **⚠️ Write Trigger**: Explicitly prohibited from auto-calling write mode
+- **⚠️ Write Trigger**: Only when user explicitly requests "generate documentation", "modify code", or specifies MODE=write
+- **Priority**: Secondary to Gemini - use as fallback for same tasks
 
 #### MODE Options
-- `analysis` (default) - Architecture analysis only, no code generation/modification (read-only)
-- `write` - ⚠️ Code generation (requires explicit specification, disabled by default)
+- `analysis` (default) - Read-only analysis and documentation generation (same as Gemini)
+- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
 
 ### Codex
 - **Command**: `codex --full-auto exec`
@@ -149,13 +150,13 @@ RULES: [template reference and constraints]
 
 #### Qwen Commands
 ```bash
-# Qwen Architecture Analysis (read-only, default)
+# Qwen Analysis (read-only, default) - Same as Gemini, use as fallback
 cd [directory] && ~/.claude/scripts/qwen-wrapper -p "
-PURPOSE: [clear architecture goal]
+PURPOSE: [clear analysis goal]
 TASK: [specific analysis task]
 MODE: analysis
 CONTEXT: [file references and memory context]
-EXPECTED: [expected deliverables]
+EXPECTED: [expected output]
 RULES: [template reference and constraints]
 "
 
@@ -166,7 +167,7 @@ PURPOSE: [clear goal]
 TASK: [specific task]
 MODE: write
 CONTEXT: [file references and memory context]
-EXPECTED: [expected deliverables]
+EXPECTED: [expected output]
 RULES: [template reference and constraints]
 "
 ```
@@ -256,14 +257,13 @@ RULES: Focus on type safety and component composition
 
 | Task Type | Tool | Use Case | Template |
 |-----------|------|----------|-----------|
-| **Analysis** | Gemini | Code exploration, architecture review, patterns | `analysis/pattern.txt` |
-| **Architecture** | Qwen | System design, code generation, architectural analysis | `analysis/architecture.txt` |
-| **Code Generation** | Qwen | Implementation patterns, code scaffolding, component creation | `development/feature.txt` |
+| **Analysis** | Gemini (Qwen fallback) | Code exploration, architecture review, patterns | `analysis/pattern.txt` |
+| **Architecture** | Gemini (Qwen fallback) | System design, architectural analysis | `analysis/architecture.txt` |
+| **Documentation** | Gemini (Qwen fallback) | Code docs, API specs, guides | `analysis/quality.txt` |
 | **Development** | Codex | Feature implementation, bug fixes, testing | `development/feature.txt` |
-| **Planning** | Multiple | Task breakdown, migration planning | `planning/task-breakdown.txt` |
-| **Documentation** | Multiple | Code docs, API specs, guides | `analysis/quality.txt` |
+| **Planning** | Gemini/Qwen | Task breakdown, migration planning | `planning/task-breakdown.txt` |
 | **Security** | Codex | Vulnerability assessment, fixes | `analysis/security.txt` |
-| **Refactoring** | Multiple | Gemini for analysis, Qwen/Codex for execution | `development/refactor.txt` |
+| **Refactoring** | Multiple | Gemini/Qwen for analysis, Codex for execution | `development/refactor.txt` |
 
 ### Template System
 
@@ -302,9 +302,9 @@ tech-stacks/
 ### Workflow Integration (REQUIRED)
 When planning any coding task, **ALWAYS** integrate CLI tools:
 
-1. **Understanding Phase**: Use Gemini for analysis
-2. **Architecture Phase**: Use Qwen for design and code generation
-3. **Implementation Phase**: Use Qwen/Codex for development
+1. **Understanding Phase**: Use Gemini for analysis (Qwen as fallback)
+2. **Architecture Phase**: Use Gemini for design and analysis (Qwen as fallback)
+3. **Implementation Phase**: Use Codex for development
 4. **Quality Phase**: Use Codex for testing and validation
 
 ### Common Scenarios
@@ -333,8 +333,19 @@ RULES: Follow project documentation standards
 "
 ```
 
-#### Architecture Analysis
+#### Architecture Analysis (Qwen as Gemini fallback)
 ```bash
+# Prefer Gemini for architecture analysis
+cd src/auth && ~/.claude/scripts/gemini-wrapper -p "
+PURPOSE: Analyze authentication system architecture
+TASK: Review JWT-based auth system design
+MODE: analysis
+CONTEXT: @{src/auth/**/*} Existing patterns and requirements
+EXPECTED: Architecture analysis report with recommendations
+RULES: $(cat '~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt') | Focus on security
+"
+
+# Use Qwen only if Gemini unavailable
 cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
 PURPOSE: Analyze authentication system architecture
 TASK: Review JWT-based auth system design
@@ -419,7 +430,7 @@ EXPECTED: Pattern documentation
 RULES: Focus on security best practices
 "
 
-# Qwen - Architecture analysis
+# Qwen - Analysis (fallback option, same as Gemini)
 cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
 PURPOSE: Analyze auth architecture
 TASK: Review auth system design and patterns

.claude/workflows/workflow-architecture.md

@@ -276,6 +276,22 @@ All workflows use the same file structure definition regardless of complexity. *
 │   ├── execute-*-[timestamp].md        # Ad-hoc implementation logs
 │   └── codex-execute-*-[timestamp].md  # Multi-stage execution logs
 │
+├── [.design/]                  # Standalone UI design outputs (created when needed)
+│   └── run-[timestamp]/        # Timestamped design runs without session
+│       ├── style-extraction/   # Style analysis results
+│       ├── style-consolidation/ # Design system tokens (per-style)
+│       │   ├── style-1/        # design-tokens.json, style-guide.md
+│       │   └── style-N/
+│       ├── prototypes/         # Generated HTML/CSS prototypes
+│       │   ├── _templates/     # Target-specific layout plans and templates
+│       │   │   ├── {target}-layout-{n}.json  # Layout plan (target-specific)
+│       │   │   ├── {target}-layout-{n}.html  # HTML template
+│       │   │   └── {target}-layout-{n}.css   # CSS template
+│       │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
+│       │   ├── compare.html    # Interactive matrix view
+│       │   └── index.html      # Navigation page
+│       └── .run-metadata.json  # Run configuration
+│
 └── WFS-[topic-slug]/
     ├── workflow-session.json        # Session metadata and state (REQUIRED)
     ├── [.brainstorming/]           # Optional brainstorming phase (created when needed)
@@ -289,6 +305,20 @@ All workflows use the same file structure definition regardless of complexity. *
     ├── [.summaries/]               # Task completion summaries (created when tasks complete)
     │   ├── IMPL-*-summary.md      # Main task summaries
     │   └── IMPL-*.*-summary.md    # Subtask summaries
+    ├── [design-*/]                 # UI design outputs (created by ui-design workflows)
+    │   ├── style-extraction/       # Style analysis results
+    │   ├── style-consolidation/    # Design system tokens (per-style)
+    │   │   ├── style-1/            # design-tokens.json, style-guide.md
+    │   │   └── style-N/
+    │   ├── prototypes/             # Generated HTML/CSS prototypes
+    │   │   ├── _templates/         # Target-specific layout plans and templates
+    │   │   │   ├── {target}-layout-{n}.json  # Layout plan (target-specific)
+    │   │   │   ├── {target}-layout-{n}.html  # HTML template
+    │   │   │   └── {target}-layout-{n}.css   # CSS template
+    │   │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
+    │   │   ├── compare.html        # Interactive matrix view
+    │   │   └── index.html          # Navigation page
+    │   └── .run-metadata.json      # Run configuration
     └── .task/                      # Task definitions (REQUIRED)
         ├── IMPL-*.json             # Main task definitions
         └── IMPL-*.*.json           # Subtask definitions (created dynamically)
@@ -299,6 +329,8 @@ All workflows use the same file structure definition regardless of complexity. *
 - **On-Demand Creation**: Other directories created when first needed
 - **Dynamic Files**: Subtask JSON files created during task decomposition
 - **Scratchpad Usage**: `.scratchpad/` created when CLI commands run without active session
+- **Design Usage**: `design-{timestamp}/` created by UI design workflows, `.design/` for standalone design runs
+- **Layout Planning**: `prototypes/_templates/` contains target-specific layout plans (JSON) generated during UI generation phase
 
 #### Scratchpad Directory (.scratchpad/)
 **Purpose**: Centralized location for non-session-specific CLI outputs

.github/release-notes-v3.5.0.md

@@ -1,235 +0,0 @@
-# 🎨 UI Design Workflow with Triple Vision Analysis & Interactive Preview
-
-This release introduces a comprehensive UI design workflow system with triple vision analysis capabilities, interactive user checkpoints, zero agent overhead, and enhanced preview tools for real-time prototype comparison.
-
-## 🌟 Major Features
-
-### UI Design Workflow System
-- **`/workflow:design:auto`**: Semi-autonomous workflow orchestrator with interactive checkpoints
-- **`/workflow:design:style-extract`**: Triple vision analysis (Claude Code + Gemini + Codex)
-- **`/workflow:design:style-consolidate`**: Token validation and style guide generation
-- **`/workflow:design:ui-generate`**: Token-driven HTML/CSS prototype generation with preview tools
-- **`/workflow:design:design-update`**: Design system integration into brainstorming artifacts
-
-### 👁️ Triple Vision Analysis
-- **Claude Code**: Quick initial visual analysis using native Read tool
-- **Gemini Vision**: Deep semantic understanding of design intent
-- **Codex Vision**: Structured pattern recognition with -i parameter
-- **Consensus Synthesis**: Weighted combination strategy for robust results
-
-### ⏸️ Interactive Checkpoints
-- **Checkpoint 1**: User selects preferred style variants after extraction
-- **Checkpoint 2**: User confirms selected prototypes before design update
-- Pause-and-continue pattern for critical design decisions
-
-### 🌐 Preview Enhancement System (NEW!)
-- **`index.html`**: Master preview navigation with grid layout
-- **`compare.html`**: Side-by-side comparison with responsive viewport toggles
-- **`PREVIEW.md`**: Comprehensive preview instructions and server setup guide
-- Synchronized scrolling for layout comparison
-- Dynamic page switching and real-time responsive testing
-
-### 🎯 Zero Agent Overhead
-- Removed Task(conceptual-planning-agent) wrappers from design commands
-- Direct bash execution for gemini-wrapper and codex commands
-- Improved performance while preserving all functionality
-
-## 🚀 Quick Start
-
-### Complete Design Workflow
-```bash
-# Semi-autonomous workflow with user checkpoints
-/workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" --batch-plan
-```
-
-### Individual Commands
-```bash
-# Extract design styles (triple vision analysis)
-/workflow:design:style-extract --session WFS-auth --images "refs/*.png"
-
-# Consolidate selected variants
-/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
-
-# Generate prototypes with preview tools
-/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
-
-# Preview generated prototypes
-cd .workflow/WFS-auth/.design/prototypes
-python -m http.server 8080  # Visit http://localhost:8080
-
-# Integrate design system
-/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
-```
-
-## 🎨 Design System Features
-- **OKLCH Color Format**: Perceptually uniform color space
-- **W3C Design Tokens**: Standard-compliant token format
-- **WCAG 2.1 AA Compliance**: Automated accessibility validation
-- **Style Override Support**: Runtime token customization with --style-overrides
-- **Batch Task Generation**: Automatic task creation with --batch-plan
-
-## 📊 Preview Tools
-
-### Master Navigation (index.html)
-- Grid layout of all generated prototypes
-- Quick links to individual variants
-- Metadata display (session ID, timestamps, page info)
-- Direct access to implementation notes
-
-### Side-by-Side Comparison (compare.html)
-- Iframe-based comparison for multiple variants
-- Responsive viewport toggles:
-  - Desktop (100%)
-  - Tablet (768px)
-  - Mobile (375px)
-- Synchronized scrolling option
-- Dynamic page switching dropdown
-- Real-time variant comparison
-
-### Preview Options
-```bash
-# Option 1: Direct browser (simplest)
-cd .workflow/WFS-{session}/.design/prototypes
-open index.html  # or double-click
-
-# Option 2: Local server (recommended)
-python -m http.server 8080      # Python
-npx http-server -p 8080         # Node.js
-php -S localhost:8080           # PHP
-# Visit: http://localhost:8080
-```
-
-## 📦 What's Included
-
-### New Commands (5)
-- `/workflow:design:auto`
-- `/workflow:design:style-extract`
-- `/workflow:design:style-consolidate`
-- `/workflow:design:ui-generate`
-- `/workflow:design:design-update`
-
-### Generated Files
-```
-.workflow/WFS-{session}/.design/
-├── style-extraction/
-│   ├── claude_vision_analysis.json
-│   ├── gemini_vision_analysis.json
-│   ├── codex_vision_analysis.json
-│   ├── semantic_style_analysis.json
-│   ├── design-tokens.json
-│   └── style-cards.json
-├── style-consolidation/
-│   ├── design-tokens.json (validated)
-│   ├── style-guide.md
-│   ├── tailwind.config.js
-│   └── validation-report.json
-└── prototypes/
-    ├── index.html (NEW - preview navigation)
-    ├── compare.html (NEW - side-by-side comparison)
-    ├── PREVIEW.md (NEW - setup instructions)
-    ├── {page}-variant-{n}.html
-    ├── {page}-variant-{n}.css
-    └── design-tokens.css
-```
-
-## 🔄 Workflow Integration
-
-Design phase fits seamlessly between brainstorming and planning:
-
-```
-Brainstorming → UI Design → Planning → Execution
-     ↓              ↓           ↓          ↓
-synthesis-   design-tokens  tasks with  token-driven
-specification   + style     design       implementation
-                 guide      context
-```
-
-**Optional but recommended** for UI-heavy projects:
-- User-facing applications
-- Design system creation
-- Brand-critical interfaces
-- Accessibility compliance projects
-
-## 💡 Benefits
-
-### User Experience
-- 🎨 Visual validation before implementation
-- ⏸️ Interactive control at critical decision points
-- 👁️ Comprehensive analysis from three AI vision sources
-- 🌐 Real-time preview with comparison tools
-- 🎯 Zero waiting with direct bash execution
-
-### Code Quality
-- 🔒 100% CSS values use custom properties
-- ♿ WCAG AA validated at design phase
-- 🎨 Single source of truth for visual design
-- 🧪 Production-ready prototypes (semantic HTML5, responsive, accessible)
-
-### Development Workflow
-- 🔄 Seamless integration with existing workflow
-- 🚀 Backward compatible (design phase optional)
-- 📊 Better planning with design system context
-- 🎯 Focused implementation from validated prototypes
-
-## 📚 Documentation
-
-- **README.md**: Updated with UI Design Workflow section
-- **README_CN.md**: Chinese documentation for design workflow
-- **CHANGELOG.md**: Comprehensive release notes with examples
-- **Command Files**: Detailed implementation guides for all 5 commands
-
-## 🔧 Technical Details
-
-**Triple Vision Analysis Flow**:
-```
-Reference Images
-  ↓
-Claude Code (Read tool) → claude_vision_analysis.json
-Gemini Vision (wrapper) → gemini_vision_analysis.json
-Codex Vision (codex -i) → codex_vision_analysis.json
-  ↓
-Main Claude Synthesis → semantic_style_analysis.json
-  ↓
-Codex Token Generation → design-tokens.json, style-cards.json
-```
-
-**Checkpoint Workflow Pattern**:
-```
-User: /workflow:design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard"
-  ↓
-Phase 1: style-extract (automatic)
-  ↓ [CHECKPOINT 1: User selects variants]
-User: /workflow:design:style-consolidate --session WFS-xxx --variants "variant-1"
-  ↓
-Phase 3: ui-generate (automatic)
-  ↓ [CHECKPOINT 2: User confirms prototypes]
-User: /workflow:design:design-update --session WFS-xxx --selected-prototypes "dashboard-variant-1"
-  ↓
-Phase 5: batch-plan (optional, if --batch-plan flag)
-```
-
-## 🆙 Upgrade Instructions
-
-```bash
-# Windows (PowerShell)
-Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content
-
-# Linux/macOS (Bash/Zsh)
-bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
-```
-
-## 🐛 Bug Fixes & Improvements
-- Optimized agent architecture by removing unnecessary wrappers
-- Improved execution performance with direct bash commands
-- Enhanced documentation consistency across English and Chinese versions
-- Updated phase numbering to accommodate new design phase
-
-## 📝 Full Changelog
-See [CHANGELOG.md](https://github.com/catlog22/Claude-Code-Workflow/blob/main/CHANGELOG.md) for complete details.
-
----
-
-**Questions or Issues?**
-- 📖 [Documentation](https://github.com/catlog22/Claude-Code-Workflow)
-- 🐛 [Report Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
-- 💬 [Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions)

CHANGELOG-v4.1.0.md

@@ -1,302 +0,0 @@
-# UI Design Workflow v4.1.0 - 纯矩阵模式 + 路径修正
-
-## 📋 发布日期
-2025-10-09
-
-## 🎯 核心变更
-
-### 1. 矩阵模式成为唯一模式
-- ❌ 移除 standard/creative 模式选择
-- ✅ 3×3 矩阵生成为默认且唯一模式
-- ✅ 直接支持 `--style-variants` 和 `--layout-variants` 参数
-
-### 2. 路径符合workflow架构
-- ✅ 有session: `.workflow/WFS-{session_id}/runs/run-xxx/`
-- ✅ 无session: `.workflow/.scratchpad/{session_id}/runs/run-xxx/`
-- ✅ 模板移至全局: `~/.claude/workflows/_template-compare-matrix.html`
-
----
-
-## 📝 文件修改清单
-
-### 核心命令文件
-
-| 文件 | 主要变更 | 状态 |
-|------|---------|------|
-| **auto.md** | 删除模式选择，简化Phase 3，修正路径 | ✅ 已完成 |
-| **generate.md** | 完全重构为矩阵模式，集成模板 | ✅ 已完成 |
-| **consolidate.md** | 修正standalone路径 | ✅ 已完成 |
-| **extract.md** | 修正standalone路径 | ✅ 已完成 |
-| **update.md** | 仅session模式，无需修改 | ✅ 保持不变 |
-
-### 新增文件
-- ✅ `~/.claude/workflows/_template-compare-matrix.html` - 交互式矩阵可视化模板
-
----
-
-## 🔄 参数变更
-
-### 旧参数（废弃）
-```bash
---variants <count>           # 统一变种数
---creative-variants <count>  # 创意变种数
---matrix-mode                # 模式标志
-```
-
-### 新参数（v4.1.0）
-```bash
---style-variants <count>     # 风格变种数（默认3）
---layout-variants <count>    # 布局变种数（默认3）
-# 矩阵为默认模式，无需标志
-```
-
----
-
-## 🚀 工作流对比
-
-### v4.0.x（旧版）
-```bash
-/workflow:ui-design:auto --variants 3 --creative-variants 4
-
-# 问题:
-# - 参数混淆（variants vs creative-variants）
-# - 模式选择复杂
-# - standalone输出到项目根目录
-```
-
-### v4.1.0（新版）
-```bash
-/workflow:ui-design:auto --style-variants 3 --layout-variants 3
-
-# 优势:
-# - 参数语义清晰
-# - 唯一矩阵模式
-# - 输出到 .workflow/.scratchpad/
-# - 总计: 3×3×N 个原型
-```
-
----
-
-## 📊 路径架构
-
-### Standalone模式（无session）
-```
-.workflow/.scratchpad/
-└── design-session-20251009-101530/
-    └── runs/
-        ├── run-20251009-101530/
-        │   └── .design/
-        │       ├── style-extraction/style-cards.json
-        │       ├── style-consolidation/
-        │       │   ├── style-1/design-tokens.json
-        │       │   ├── style-2/design-tokens.json
-        │       │   └── style-3/design-tokens.json
-        │       └── prototypes/
-        │           ├── compare.html (交互式3×3矩阵)
-        │           ├── index.html
-        │           └── {page}-style-{s}-layout-{l}.html
-        └── latest -> run-20251009-101530/
-```
-
-### 集成模式（有session）
-```
-.workflow/WFS-auth-system/
-├── workflow-session.json
-├── IMPL_PLAN.md
-├── .brainstorming/synthesis-specification.md
-└── runs/
-    ├── run-20251009-101530/
-    │   └── .design/ (同上)
-    └── latest -> run-20251009-101530/
-```
-
----
-
-## 🔧 核心改进
-
-### 1. 简化架构
-- **auto.md Phase 3**: 从复杂并行Task循环简化为单一命令
-```bash
-# 旧方式（30+行）
-FOR style_id IN range(...):
-    Task(conceptual-planning-agent): "..."
-
-# 新方式（3行）
-command = "/workflow:ui-design:generate --style-variants {s} --layout-variants {l}"
-SlashCommand(command=command)
-```
-
-### 2. 路径规范化
-```bash
-# auto.md - Phase 0b
-IF --session:
-    base_path = ".workflow/WFS-{session_id}/runs/${run_id}"
-ELSE:
-    base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}"
-
-# generate/consolidate/extract
-base_path = find_latest_design_session(".workflow/.scratchpad/")
-```
-
-### 3. 可视化增强
-- 集成高级 `_template-compare-matrix.html` 模板
-- 3×3 网格矩阵视图
-- 同步滚动 + 缩放控制
-- 全屏模式 + 选择导出
-
----
-
-## ⚠️ 破坏性变更
-
-### 1. 参数废弃
-```bash
-# ❌ 不再支持
---variants <count>
---creative-variants <count>
-
-# ✅ 必须使用
---style-variants <count>
---layout-variants <count>
-```
-
-### 2. 文件命名强制统一
-```bash
-# ❌ 旧格式不再生成
-{page}-variant-{n}.html
-{page}-creative-variant-{n}.html
-
-# ✅ 强制新格式
-{page}-style-{s}-layout-{l}.html
-```
-
-### 3. Standalone路径变更
-```bash
-# ❌ v4.0.x
-./design-session-xxx/ (项目根目录)
-
-# ✅ v4.1.0
-.workflow/.scratchpad/design-session-xxx/
-```
-
----
-
-## 📖 迁移指南
-
-### 从 v4.0.x 迁移
-
-#### 1. 更新命令参数
-```bash
-# 旧方式
-/workflow:ui-design:auto --variants 3 --creative-variants 4
-
-# 新方式
-/workflow:ui-design:auto --style-variants 3 --layout-variants 4
-
-# 或依赖智能解析
-/workflow:ui-design:auto --prompt "Generate 3 styles with 4 layouts"
-```
-
-#### 2. 更新路径引用
-```bash
-# 旧standalone输出
-./design-session-xxx/
-
-# 新standalone输出
-.workflow/.scratchpad/design-session-xxx/
-
-# 迁移建议: 手动移动旧目录或保留为历史
-mv ./design-session-* .workflow/.scratchpad/
-```
-
-#### 3. 预览文件
-```bash
-# 保持不变
-{base_path}/.design/prototypes/compare.html
-{base_path}/.design/prototypes/index.html
-```
-
----
-
-## ✅ 向后兼容性
-
-### 完全兼容
-- ✅ `--session` 参数
-- ✅ `--pages` 参数
-- ✅ `--prompt` 参数
-- ✅ `--images` 参数
-- ✅ `--batch-plan` 标志
-- ✅ 智能prompt解析
-
-### 不兼容
-- ❌ standard/creative 模式选择
-- ❌ 旧参数 `--variants`, `--creative-variants`
-- ❌ 旧文件命名格式
-
----
-
-## 🧪 测试清单
-
-### 功能测试
-- [ ] 默认3×3矩阵生成
-- [ ] 自定义矩阵（2×2, 4×3等）
-- [ ] 智能prompt解析
-- [ ] 文件命名正确性
-- [ ] compare.html 可视化
-
-### 路径测试
-- [ ] Standalone输出到 `.scratchpad`
-- [ ] Session输出到 `WFS-{id}`
-- [ ] latest symlink正确
-- [ ] 跨命令路径传递
-
-### 集成测试
-- [ ] auto → extract → consolidate → generate → update
-- [ ] 模板正确加载
-- [ ] 设计token引用正确
-
----
-
-## 📚 相关文档
-
-- **workflow-architecture.md**: Workflow系统架构标准
-- **_run-manager.md**: Run-based文件管理文档（如果需要）
-- **~/.claude/workflows/_template-compare-matrix.html**: 可视化模板
-
----
-
-## 🔮 未来增强
-
-### 计划中
-- [ ] 自定义布局策略（覆盖默认 Classic/Modern/Minimal）
-- [ ] compare.html 运行历史对比
-- [ ] Scratchpad自动清理策略
-- [ ] Session升级工作流（scratchpad → WFS）
-
-### 待讨论
-- [ ] 非矩形矩阵支持（2×3）
-- [ ] 恢复 creative 模式（可选）
-- [ ] 更多布局变种（>5）
-
----
-
-## 📝 总结
-
-**v4.1.0 核心价值**:
-1. **极简哲学**: 移除模式选择，矩阵为唯一模式
-2. **清晰参数**: `--style-variants` 和 `--layout-variants` 语义明确
-3. **架构规范**: 严格遵循 workflow-architecture.md 标准
-4. **集中管理**: 所有输出在 `.workflow/` 下
-5. **可视化增强**: 高级交互式矩阵界面
-
-**升级理由**:
-- ✅ 系统化设计探索（风格×布局矩阵）
-- ✅ 简化工作流、减少参数困惑
-- ✅ 符合workflow架构标准
-- ✅ 避免项目根目录污染
-
----
-
-**发布者**: Claude Code
-**版本**: v4.1.0
-**类型**: Major Refactoring + Path Corrections
-**日期**: 2025-10-09

CHANGELOG-v4.1.1.md

@@ -1,219 +0,0 @@
-# UI Design Workflow v4.1.1 - Symlink Fix & Agent Optimization
-
-## 📋 发布日期
-2025-10-09
-
-## 🎯 核心修复与优化
-
-### 1. Windows 符号链接修复
-- **问题**：`latest` 被创建为实际目录而非符号链接，导致创建两套重复目录
-- **根本原因**：使用 `ln -s`（Unix 命令）在 Windows 环境下失败
-- **解决方案**：改用 Windows 原生命令 `mklink /D`
-- **影响范围**：auto.md Phase 0b
-
-### 2. Agent 任务分配优化
-- **旧策略**：按 style 分配（Agent-1 处理 style-1 的所有 layouts）
-- **新策略**：按 layout 分配（Agent-1 处理 layout-1 的所有 styles）
-- **批处理**：支持最多 8 个 styles per agent（超过 8 个 styles 时自动分批）
-- **优势**：
-  - 同一 agent 处理不同 styles（复用 layout 策略）
-  - 不同 agent 处理不同 layouts（并行优化）
-  - 扩展性提升：32 styles × 3 layouts = 12 agents（原方案需 32 agents）
-
----
-
-## 📝 文件修改清单
-
-| 文件 | 主要变更 | 状态 |
-|------|---------|------|
-| **auto.md** | 修复 Windows 符号链接创建逻辑 | ✅ 已完成 |
-| **generate.md** | 重构 agent 分配策略为 layout-based | ✅ 已完成 |
-
----
-
-## 🔄 技术细节
-
-### 修复 1: Symlink Creation (auto.md)
-
-#### 旧代码（错误）
-```bash
-# Phase 0b
-Bash(rm -f ".workflow/WFS-{session_id}/latest")
-Bash(ln -s "runs/${run_id}" ".workflow/WFS-{session_id}/latest")
-```
-
-**问题**：
-- `ln -s` 在 Windows 下失败时会创建实际目录
-- 导致 `latest/` 和 `runs/run-xxx/` 两套重复目录
-
-#### 新代码（修复）
-```bash
-# Phase 0b - Windows-compatible
-Bash(cd ".workflow/WFS-{session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}")
-```
-
-**改进**：
-- 使用 `mklink /D`（Windows 原生目录符号链接命令）
-- `cd` 到父目录确保相对路径正确
-- `rm -rf` 清理旧的目录/符号链接
-
----
-
-### 优化 2: Agent Allocation (generate.md)
-
-#### 旧策略（Style-Based）
-```bash
-FOR style_id IN range(1, style_variants + 1):
-    Task(agent): "Generate all layouts for style-{style_id}"
-```
-
-**问题**：
-- 16 styles → 16 agents
-- 32 styles → 32 agents（扩展性差）
-
-#### 新策略（Layout-Based with Batching）
-```bash
-# Calculate style batches (max 8 styles per agent)
-batch_size = 8
-all_style_ids = range(1, style_variants + 1)
-style_batches = split_into_chunks(all_style_ids, batch_size)
-
-FOR layout_id IN range(1, layout_variants + 1):
-    FOR style_batch IN style_batches:
-        Task(agent): "
-          Generate layout-{layout_id} for styles {style_batch}
-
-          Context:
-          - LAYOUT_ID: {layout_id}
-          - STYLE_IDS_BATCH: {style_batch}  # e.g., [1-8]
-
-          Strategy:
-          - Apply consistent layout-{layout_id} strategy to ALL styles in batch
-          - Load each style's design-tokens.json separately
-        "
-```
-
-**改进**：
-- 按 layout 分配，每个 agent 专注一种 layout 策略
-- 批处理支持：styles > 8 时自动分批
-- 示例：32 styles × 3 layouts
-  - 旧方案：32 agents
-  - 新方案：3 layouts × 4 batches = **12 agents**
-
----
-
-## 📊 性能对比
-
-### Agent 数量对比表
-
-| 配置 | 旧方案 (Style-Based) | 新方案 (Layout-Based) | 优化比例 |
-|------|---------------------|----------------------|---------|
-| 3×3 (默认) | 3 agents | 3 agents | 1:1 |
-| 8×3 | 8 agents | 3 agents | 2.7:1 |
-| 16×3 | 16 agents | 6 agents (3×2 batches) | 2.7:1 |
-| 32×3 | 32 agents | 12 agents (3×4 batches) | 2.7:1 |
-| 3×5 | 3 agents | 5 agents | 0.6:1 |
-| 16×5 | 16 agents | 10 agents (5×2 batches) | 1.6:1 |
-
-**结论**：layout 数量不变时，styles 增加不会线性增加 agent 数量
-
----
-
-## 🚀 工作流影响
-
-### 无影响的部分
-- ✅ 矩阵模式逻辑（仍然是 styles × layouts）
-- ✅ 文件命名格式（`{page}-style-{s}-layout-{l}.html`）
-- ✅ 设计 token 加载机制
-- ✅ 可视化模板（compare.html）
-- ✅ 所有参数（--style-variants, --layout-variants）
-
-### 改进的部分
-- ✅ **符号链接正确性**：不再创建重复目录
-- ✅ **Agent 扩展性**：高 variant 数场景下性能提升 2-3 倍
-- ✅ **Layout 一致性**：同一 agent 负责一种 layout 策略，确保跨 styles 的 layout 一致性
-
----
-
-## ⚠️ 破坏性变更
-
-**无破坏性变更**
-
-- 所有参数保持不变
-- 输出文件格式保持不变
-- API 接口保持不变
-- 向后兼容 v4.1.0
-
----
-
-## 🧪 测试建议
-
-### 符号链接测试
-```bash
-# Windows 环境测试
-/workflow:ui-design:auto --prompt "Test symlink" --style-variants 2
-
-# 验证
-cd .workflow/.scratchpad/design-session-*/
-ls -la  # 应看到 latest -> runs/run-xxx（符号链接，非目录）
-```
-
-### Agent 分配测试
-```bash
-# 小规模测试（3×3）
-/workflow:ui-design:auto --style-variants 3 --layout-variants 3
-# 预期：3 agents（每个 layout 1 个）
-
-# 中规模测试（16×3）
-/workflow:ui-design:auto --style-variants 16 --layout-variants 3
-# 预期：6 agents（3 layouts × 2 batches）
-
-# 大规模测试（32×3）
-/workflow:ui-design:auto --style-variants 32 --layout-variants 3
-# 预期：12 agents（3 layouts × 4 batches）
-```
-
----
-
-## 📚 相关文档
-
-- **workflow-architecture.md**: Workflow 系统架构标准（符号链接规范）
-- **CHANGELOG-v4.1.0.md**: 纯矩阵模式和路径修正
-- **auto.md**: Phase 0b 符号链接创建逻辑
-- **generate.md**: Phase 2 agent 分配策略
-
----
-
-## 🔮 未来优化方向
-
-### 计划中
-- [ ] 自适应批处理大小（根据 agent 性能动态调整）
-- [ ] Layout 策略配置化（允许自定义 layout 策略）
-- [ ] 跨 runs 的 agent 结果缓存
-
-### 待讨论
-- [ ] 是否需要 style-based 模式作为备选？
-- [ ] 批处理大小是否需要参数化（当前固定 8）？
-
----
-
-## 📝 总结
-
-**v4.1.1 核心价值**:
-1. **跨平台兼容性**: Windows 环境符号链接正常工作
-2. **扩展性提升**: 高 variant 数场景下 agent 数量减少 60%+
-3. **Layout 一致性**: 同一 layout 策略由单一 agent 负责
-4. **零破坏性**: 完全向后兼容 v4.1.0
-
-**升级理由**:
-- ✅ 修复 Windows 环境下的符号链接 bug
-- ✅ 大幅提升高 variant 数场景的性能
-- ✅ 改善 layout 策略的一致性
-- ✅ 为未来扩展奠定基础
-
----
-
-**发布者**: Claude Code
-**版本**: v4.1.1
-**类型**: Bugfix + Performance Optimization
-**日期**: 2025-10-09

CHANGELOG.md

@@ -5,6 +5,593 @@ All notable changes to Claude Code Workflow (CCW) will be documented in this fil
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.4.0] - 2025-10-11
+
+### 🏗️ UI Design Workflow V3 - Layout/Style Separation Architecture
+
+This release introduces a fundamental architectural refactoring that separates layout structure extraction from style token extraction, enabling the `generate` command to become a pure assembler.
+
+#### Breaking Changes
+
+**Command Renaming**:
+```bash
+# ❌ Old (v4.3.0 and earlier)
+/workflow:ui-design:extract
+
+# ✅ New (v4.4.0)
+/workflow:ui-design:style-extract
+```
+
+**New Required Command**:
+- **`/workflow:ui-design:layout-extract`**: Now mandatory for workflows using `generate`
+- Layout templates must be generated before prototype assembly
+- Both `imitate-auto` and `explore-auto` now include Phase 2.5 (layout extraction)
+
+**Workflow Changes**:
+```bash
+# ❌ Old Flow (v4.3.0)
+style-extract → consolidate → generate → update
+
+# ✅ New Flow (v4.4.0)
+style-extract → consolidate → layout-extract → generate (assembler) → update
+```
+
+#### Added
+
+**New Command: `/workflow:ui-design:layout-extract`**:
+- **Purpose**: Extract structural layout information separate from visual style
+- **Features**:
+  - Agent-powered structural analysis using `ui-design-agent`
+  - Dual-mode operation: `imitate` (high-fidelity replication) / `explore` (multiple variants)
+  - Device-aware layouts: desktop, mobile, tablet, responsive
+  - Generates `layout-templates.json` with DOM structure and CSS layout rules
+  - MCP-integrated layout pattern research (explore mode only)
+  - Token-based CSS using `var()` placeholders for spacing and breakpoints
+- **Output**: `layout-extraction/layout-templates.json` with:
+  - DOM structure (semantic HTML5 with ARIA)
+  - Component hierarchy (high-level layout regions)
+  - CSS layout rules (Grid/Flexbox, no visual styling)
+  - Device-specific structures and responsive breakpoints
+
+**Enhanced Layout Extraction Architecture**:
+```json
+{
+  "layout_templates": [
+    {
+      "target": "home",
+      "variant_id": "layout-1",
+      "device_type": "responsive",
+      "design_philosophy": "3-column holy grail with fixed header",
+      "dom_structure": { /* JSON object */ },
+      "component_hierarchy": ["header", "main", "sidebar", "footer"],
+      "css_layout_rules": "/* Grid/Flexbox only, uses var() */"
+    }
+  ]
+}
+```
+
+**Device-Aware Layout Generation**:
+- **Desktop**: 1920×1080px - Multi-column grids, spacious layouts
+- **Mobile**: 375×812px - Single column, stacked sections, touch targets ≥44px
+- **Tablet**: 768×1024px - Hybrid layouts, flexible columns
+- **Responsive**: Mobile-first breakpoint-driven adaptive layouts
+
+**MCP Integration (Explore Mode)**:
+- `mcp__exa__web_search_exa` for layout pattern inspiration
+- Pattern research: `{target} layout patterns {device_type}`
+- Inspiration files: `layout-extraction/_inspirations/{target}-layout-ideas.txt`
+
+#### Changed
+
+**`/workflow:ui-design:style-extract` (Renamed from `extract`)**:
+- **File Renamed**: `extract.md` → `style-extract.md`
+- **Scope Clarified**: Focus exclusively on visual style (colors, typography, spacing)
+- **Documentation Updated**: Added note about layout extraction separation
+- **No Functionality Change**: All style extraction features preserved
+- **Output**: Still generates `style-cards.json` with `proposed_tokens`
+
+**`/workflow:ui-design:generate` (Refactored to Pure Assembler)**:
+- **Before (v4.3.0)**: Layout design + style application agent
+  - Agent made layout decisions during generation
+  - Mixed structural and visual responsibilities
+  - CSS contained both layout and style rules
+
+- **After (v4.4.0)**: Pure assembly only
+  - **Reads**: `layout-templates.json` + `design-tokens.json`
+  - **Action**: Combines pre-extracted components:
+    1. Build HTML from `dom_structure`
+    2. Apply `css_layout_rules` (structure)
+    3. Link design tokens CSS (visual style)
+    4. Inject placeholder content
+  - **No Design Logic**: All layout and style decisions pre-made
+  - **Agent Prompt Updated**: Removed layout design instructions
+
+**Agent Instructions Simplification** (`generate.md`):
+```javascript
+// ❌ Old (v4.3.0): Agent designs layout + applies style
+Agent: "Design page layout based on requirements, then apply design tokens"
+
+// ✅ New (v4.4.0): Agent only assembles
+Agent: "
+  [LAYOUT_STYLE_ASSEMBLY]
+  Read layout-templates.json → Extract dom_structure, css_layout_rules
+  Read design-tokens.json → Extract ALL token values
+  Build HTML from dom_structure
+  Build CSS from css_layout_rules + token values
+  Write files IMMEDIATELY
+"
+```
+
+**Workflow Commands Updated**:
+- **`/workflow:ui-design:imitate-auto`**:
+  - Added Phase 2.5: Layout Extraction (imitate mode, single variant)
+  - Generates `layout-templates.json` before Phase 4 (UI Assembly)
+  - Uses `--mode imitate` for high-fidelity layout replication
+
+- **`/workflow:ui-design:explore-auto`**:
+  - Added Phase 2.5: Layout Extraction (explore mode, multiple variants)
+  - Generates `{targets × layout_variants}` layout templates
+  - Uses `--mode explore` for structural variety
+  - MCP-powered layout pattern research
+
+**Output Structure Changes**:
+```
+{base_path}/
+├── style-extraction/         # Visual tokens (unchanged)
+│   └── style-cards.json
+├── layout-extraction/        # NEW: Structural templates
+│   ├── layout-templates.json
+│   ├── layout-space-analysis.json (explore mode)
+│   └── _inspirations/ (explore mode)
+├── style-consolidation/      # Final design tokens (unchanged)
+│   └── style-1/
+│       └── design-tokens.json
+└── prototypes/               # Assembled output (unchanged)
+    └── {target}-style-{s}-layout-{l}.html
+```
+
+#### Improved
+
+**Separation of Concerns**:
+- 🎨 **Style (style-extract)**: Colors, typography, spacing → design-tokens.json
+- 🏗️ **Layout (layout-extract)**: DOM structure, CSS layout → layout-templates.json
+- 📦 **Assembly (generate)**: Combine structure + style → final prototypes
+- ✅ **Result**: Each phase has single, clear responsibility
+
+**Quality Improvements**:
+- 🎯 **Better Layout Variety**: Explore mode generates structurally distinct layouts
+- 🔄 **Reusability**: Layout templates can be combined with different styles
+- 📊 **Clarity**: All structural decisions in layout-templates.json
+- 🧪 **Testability**: Layout structure and visual style tested independently
+
+**Performance Benefits**:
+- ⚡ **Faster Generation**: Assembly is simpler than design + application
+- 🔄 **Better Caching**: Layout templates reused across style variants
+- 📉 **Reduced Complexity**: Generate agent has single responsibility
+
+#### Technical Details
+
+**Phase Flow Comparison**:
+
+**Old Flow (v4.3.0)**:
+```
+Phase 1: style-extract → style-cards.json
+Phase 2: consolidate → design-tokens.json
+Phase 3: generate (design+apply) → prototypes
+Phase 4: update
+```
+
+**New Flow (v4.4.0)**:
+```
+Phase 1: style-extract → style-cards.json
+Phase 2: consolidate → design-tokens.json
+Phase 2.5: layout-extract → layout-templates.json  [NEW]
+Phase 3: generate (pure assembly) → prototypes
+Phase 4: update
+```
+
+**Agent Task Changes**:
+
+**Before (Mixed Responsibility)**:
+```javascript
+Agent Task: "
+  Design page layout for {target}
+  Apply design tokens from design-tokens.json
+  Generate HTML + CSS
+"
+// Problems:
+// - Layout decisions made during generation
+// - Style application mixed with structure
+// - Agent has dual responsibility
+```
+
+**After (Pure Assembly)**:
+```javascript
+Agent Task: "
+  [LAYOUT_STYLE_ASSEMBLY]
+  INPUT 1: layout-templates.json → dom_structure, css_layout_rules
+  INPUT 2: design-tokens.json → token values
+
+  ASSEMBLY:
+  1. Build HTML from dom_structure
+  2. Build CSS from css_layout_rules (replace var())
+  3. Add visual styling using token values
+  4. Write files IMMEDIATELY
+
+  RULES:
+  ✅ Pure assembly only
+  ❌ NO layout design decisions
+  ❌ NO style design decisions
+"
+```
+
+**Layout Template Structure**:
+```json
+{
+  "target": "home",
+  "variant_id": "layout-1",
+  "device_type": "responsive",
+  "design_philosophy": "F-pattern with sticky nav",
+  "dom_structure": {
+    "tag": "body",
+    "children": [
+      {"tag": "header", "attributes": {"class": "layout-header"}},
+      {"tag": "main", "attributes": {"class": "layout-main"}},
+      {"tag": "footer", "attributes": {"class": "layout-footer"}}
+    ]
+  },
+  "component_hierarchy": ["header", "main", "footer"],
+  "css_layout_rules": ".layout-main { display: grid; grid-template-columns: 1fr 3fr; gap: var(--spacing-6); }"
+}
+```
+
+**Token-Based CSS Pattern**:
+```css
+/* Layout rules use var() for spacing/breakpoints */
+.layout-wrapper {
+  display: grid;
+  gap: var(--spacing-4);
+  padding: var(--spacing-8);
+}
+
+@media (max-width: var(--breakpoint-md)) {
+  .layout-wrapper {
+    grid-template-columns: 1fr;
+  }
+}
+```
+
+#### Migration Guide
+
+**For Existing Workflows**:
+1. **Update Command Names**:
+   ```bash
+   # Old: /workflow:ui-design:extract
+   # New: /workflow:ui-design:style-extract
+   ```
+
+2. **Add Layout Extraction Step**:
+   ```bash
+   # After consolidate, before generate:
+   /workflow:ui-design:layout-extract --session WFS-xxx --targets "dashboard,settings" --mode explore --variants 3
+   ```
+
+3. **Update Orchestrator Workflows**:
+   - `imitate-auto`: Automatically includes Phase 2.5
+   - `explore-auto`: Automatically includes Phase 2.5
+   - Manual workflows: Add `layout-extract` call
+
+**Backward Compatibility**:
+- ✅ Old `extract` command files archived (not deleted)
+- ✅ New `style-extract` command name explicit and clear
+- ✅ All output structures backward compatible
+- ⚠️ **Breaking**: `generate` now requires `layout-templates.json` input
+
+**For New Projects**:
+- Use new workflow: `style-extract → consolidate → layout-extract → generate → update`
+- Leverage layout variants: `--layout-variants` in explore-auto
+- Device-specific layouts: `--device-type` parameter
+
+#### Files Changed
+
+**Renamed**:
+- `.claude/commands/workflow/ui-design/extract.md` → `style-extract.md`
+
+**Added**:
+- `.claude/commands/workflow/ui-design/layout-extract.md` (new command, 370+ lines)
+
+**Modified**:
+- `.claude/commands/workflow/ui-design/generate.md`:
+  - Refactored to pure assembler (agent instructions simplified)
+  - Added Phase 2: Load Layout Templates
+  - Updated agent prompt to focus on assembly only
+  - Documentation updates for separation of concerns
+
+- `.claude/commands/workflow/ui-design/imitate-auto.md`:
+  - Added Phase 2.5: Layout Extraction (imitate mode)
+  - Updated workflow orchestration
+  - Phase numbering shifted (old Phase 3 → Phase 4)
+
+- `.claude/commands/workflow/ui-design/explore-auto.md`:
+  - Added Phase 2.5: Layout Extraction (explore mode)
+  - Updated workflow orchestration
+  - Matrix calculation updated: `style_variants × layout_variants × targets`
+  - Phase numbering shifted (old Phase 3 → Phase 4)
+
+- `.claude/commands/workflow/ui-design/consolidate.md`:
+  - Documentation updates
+  - Note added about layout-extract requirement
+
+**Removed**:
+- ❌ **V2 Commands Deprecated**: All `-v2` command variants removed
+  - `generate-v2.md` removed (merged into main `generate.md`)
+  - `explore-auto-v2.md` removed (merged into main `explore-auto.md`)
+  - Self-contained CSS architecture now standard in all commands
+  - No more v1/v2 split - unified workflow
+
+**Total Impact**:
+- 5 files changed
+- 1 file renamed
+- 1 new command (layout-extract, 370+ lines)
+- 2 deprecated commands removed (generate-v2, explore-auto-v2)
+- ~200 lines modified in existing commands
+- Net: +400 lines (improved separation of concerns)
+
+#### Benefits
+
+**Architectural Clarity**:
+- ✅ **Single Responsibility**: Each command has one job
+- ✅ **Clear Contracts**: Explicit input/output for each phase
+- ✅ **Better Testing**: Components testable independently
+- ✅ **Maintainability**: Changes localized to relevant phase
+
+**Developer Experience**:
+- 🎯 **Predictable**: Layout structure visible before assembly
+- 🔍 **Debuggable**: Easier to identify issues (layout vs style)
+- 🔄 **Flexible**: Reuse layouts with different styles
+- 📚 **Understandable**: Each phase has clear documentation
+
+**Design Quality**:
+- 🎨 **Style Independence**: Visual tokens separate from structure
+- 🏗️ **Layout Variety**: Explore mode generates structurally different layouts
+- 📐 **Device Optimization**: Layout templates device-specific
+- ♿ **Accessibility**: Semantic HTML5 structure with ARIA
+
+**Implementation Quality**:
+- 🧩 **Modular**: Components can be developed independently
+- 🔄 **Reusable**: Layout templates work with any style
+- 🧪 **Testable**: Structure and style tested separately
+- 📦 **Production-Ready**: Token-driven, semantic, accessible
+
+---
+
+## [4.3.0] - 2025-10-10
+
+### 🎨 UI Design Workflow V2 - Self-Contained CSS Architecture
+
+This release introduces a major architectural improvement to the UI Design Workflow, removing the placeholder mechanism and enabling agents to generate fully self-contained CSS files directly from design tokens.
+
+#### Changed
+
+**UI Design Workflow V2 Commands**:
+- **`/workflow:ui-design:generate-v2`**: Enhanced prototype generation with self-contained CSS
+  - Agents now read `design-tokens.json` and generate independent CSS files
+  - CSS contains direct token values (e.g., `#3b82f6`) instead of `var()` references
+  - HTML files reference CSS directly: `<link rel="stylesheet" href="page-style-1-layout-2.css">`
+  - No more placeholder mechanism or post-processing steps
+
+- **`/workflow:ui-design:explore-auto-v2`**: Updated to use new generation architecture
+  - Automatic coordination with `generate-v2` command
+  - Streamlined workflow without placeholder replacement
+
+**Removed Dependencies**:
+- ❌ **No more `tokens.css`**: Eliminated intermediate CSS variable files
+- ❌ **No more Phase 1.6**: Removed token-to-CSS conversion step
+- ❌ **No more placeholder replacement**: Scripts no longer process `{{STYLE_CSS}}` placeholders
+
+**Agent Instructions Enhanced**:
+- Agents receive `design-tokens.json` as primary design system reference
+- Direct CSS generation instructions with token value extraction guidance
+- Better adaptation to `design_attributes` (density, visual_weight, formality, etc.)
+- Example instruction: "Use color values for backgrounds, typography values for fonts"
+
+**Script Simplification** (`ui-generate-preview-v2.sh`):
+- Removed placeholder replacement logic (32 lines removed)
+- Focus solely on preview file generation (compare.html, index.html, PREVIEW.md)
+- Cleaner, more focused responsibility
+
+#### Improved
+
+**Style Differentiation**:
+- 🎨 **Better Style Diversity**: Agents can now freely adapt token values based on design philosophy
+- 🎯 **Stronger Visual Identity**: Each style variant can use different color spaces, typography scales
+- 💡 **Design-Aware Selection**: Agents intelligently select tokens matching design_attributes
+
+**Workflow Simplicity**:
+- 📉 **Reduced Complexity**: 346 lines of code removed (net reduction)
+- ⚡ **Fewer Steps**: Eliminated intermediate conversion and replacement phases
+- 🔧 **Easier Debugging**: All styling visible directly in generated CSS files
+- 📝 **Clearer Agent Tasks**: Agents have single, focused responsibility
+
+**CSS Generation Quality**:
+- 🎨 **Fully Embodies Design**: CSS directly reflects design token values
+- 🔄 **No External Dependencies**: Each CSS file is completely self-contained
+- 📊 **Better Adaptation**: Agents can adjust values based on layout context
+- 🎯 **Style-Specific Implementation**: Same layout + different style = truly different CSS
+
+#### Technical Details
+
+**Before (v4.2.x)**:
+```html
+<!-- Agent generates HTML with placeholders -->
+<link rel="stylesheet" href="{{TOKEN_CSS}}">
+<link rel="stylesheet" href="{{STRUCTURAL_CSS}}">
+
+<!-- Phase 1.6: Convert design-tokens.json → tokens.css -->
+<!-- Phase 3a: Replace placeholders with actual paths -->
+```
+
+**After (v4.3.0)**:
+```html
+<!-- Agent generates HTML with direct reference -->
+<link rel="stylesheet" href="dashboard-style-1-layout-2.css">
+
+<!-- CSS contains direct values from design-tokens.json -->
+.button { background: #3b82f6; font-size: 16px; }
+```
+
+**Workflow Comparison**:
+```
+Old Flow:
+Phase 1.5: Inspiration → Phase 1.6: Token Conversion → Phase 2: Agent Gen →
+Phase 3a: Replace Placeholders → Phase 3b: Preview
+
+New Flow:
+Phase 1.5: Inspiration → Phase 2: Agent Gen (reads tokens.json directly) →
+Phase 3: Preview
+```
+
+#### Benefits
+
+**Developer Experience**:
+- 🚀 **Faster Execution**: Removed 2 intermediate processing steps
+- 📁 **Simpler Output**: No more tokens.css files to manage
+- 🔍 **Easier Inspection**: All styling visible in prototype CSS files
+- 🎯 **Clearer Intent**: Direct mapping from design tokens to CSS
+
+**Design Quality**:
+- 🎨 **Richer Style Variations**: Agents can adapt token usage creatively
+- 💪 **Stronger Differentiation**: Each style truly looks different
+- 🎯 **Context-Aware Styling**: Agents adjust tokens based on layout needs
+- ✨ **Better Design Expression**: No constraints from CSS variable structure
+
+**Maintainability**:
+- 📉 **Less Code**: 346 lines removed (5 files modified)
+- 🔧 **Fewer Moving Parts**: Removed token conversion and placeholder systems
+- 📝 **Clearer Responsibilities**: Scripts focus on single purpose
+- 🧪 **Easier Testing**: Self-contained files easier to validate
+
+#### Files Changed
+
+**Commands Updated**:
+- `.claude/commands/workflow/ui-design/generate-v2.md`: Removed Phase 1.6 and Phase 3a, updated agent instructions
+- `.claude/commands/workflow/ui-design/explore-auto-v2.md`: Updated to work with new architecture
+- `.claude/commands/workflow/ui-design/generate.md`: Documentation updates
+- `.claude/commands/workflow/ui-design/extract.md`: Documentation updates
+
+**Scripts Modified**:
+- `.claude/scripts/ui-generate-preview-v2.sh`: Removed placeholder replacement (32 lines)
+
+**Total Impact**:
+- 5 files changed
+- 471 insertions, 817 deletions
+- Net: -346 lines (31% reduction in UI generation code)
+
+#### Migration Notes
+
+**No Breaking Changes** for users:
+- ✅ V2 commands are separate from V1 (`generate-v2` vs `generate`)
+- ✅ Existing workflows continue to work unchanged
+- ✅ New commands are opt-in
+
+**For New Projects**:
+- Use `/workflow:ui-design:generate-v2` for better style differentiation
+- Use `/workflow:ui-design:explore-auto-v2` for automatic workflow
+
+**Design Token Changes**:
+- `design-tokens.json` structure unchanged
+- `tokens.css` files no longer generated (V2 commands only)
+- Style guides (`style-guide.md`) unchanged
+
+## [4.2.1] - 2025-10-10
+
+### 📝 Command Renaming & Documentation Refactoring
+
+This release includes a command rename for better clarity and refactors UI design workflow documentation for improved maintainability.
+
+#### Changed
+
+**Command Renaming**:
+- **`/workflow:concept-verify` → `/workflow:concept-clarify`**: Renamed for clearer intent
+  - Better reflects the command's purpose of clarifying underspecified areas
+  - Updated all internal references and documentation
+  - Command functionality remains unchanged
+
+**explore-auto.md** (formerly `auto.md`):
+- **File Reorganization**: Reduced from 540 to 435 lines (19.4% reduction)
+- **Merged Duplicate Content**: Consolidated Overview, Coordinator Role, and Execution Model into single "Overview & Execution Model" section
+- **Simplified Core Rules**: From verbose descriptions to 5 concise rules
+- **Streamlined TodoWrite Pattern**: From detailed steps to concise mode with comments
+- **Preserved Functionality**: All 6-phase execution logic, intelligent parsing, interactive confirmation, and matrix mode intact
+
+**imitate-auto.md** (NEW command):
+- **File Reorganization**: Reduced from 566 to 475 lines (16.1% reduction)
+- **Merged Sections**: Combined Overview, Core Philosophy, Execution Model, and Workflow Position into unified structure
+- **Simplified Phase 0.5**: Screenshot capture logic complete but reduced redundant error handling
+- **Consolidated Performance**: Merged "Key Differences" and "Performance Benefits" into single comparison table
+- **Preserved Functionality**: All 5-phase execution, auto-screenshot mechanism, direct token extraction, and error handling intact
+
+#### Improved
+
+**Documentation Quality**:
+- 📚 Clearer structure with merged duplicate concepts
+- 🎯 Reduced redundancy across command documentation
+- ✨ Consistent formatting and organization patterns
+- 📖 Improved maintainability with better content separation
+- 🔍 All key functionality points preserved and highlighted
+
+**Total Impact**:
+- **explore-auto.md**: 105 lines removed (19.4% reduction)
+- **imitate-auto.md**: 91 lines removed (16.1% reduction)
+- **Combined**: 196 lines of documentation optimized
+- **Zero functionality loss**: All features, workflows, and technical details preserved
+
+## [4.2.0] - 2025-10-09
+
+### 🎯 Multi-Page Support Enhancement
+
+Based on Gemini's analysis of the UI Design Workflow, this version implements four key optimizations to improve the multi-page design experience.
+
+#### Added
+
+- **Cross-Page Consistency Validation**: New `Phase 3.5` in `generate` command automatically validates design consistency (shared components, tokens, accessibility) across multiple pages
+- **Side-by-Side Prototype Comparison**: `compare.html` preview tool now includes "Side-by-Side" tab to compare any two prototypes with intelligent consistency hints
+- **Batch Prototype Selection**: `compare.html` features "By Style" and "By Layout" buttons for quick bulk prototype selection
+
+#### Changed
+
+- **Enhanced Page Inference**: `auto` command's page detection uses multiple regex patterns with interactive user confirmation
+- **Improved Export**: Selection export from `compare.html` is now more structured with detailed metadata
+
+## [4.1.1] - 2025-10-09
+
+### 🔧 Symlink Fix & Agent Optimization
+
+#### Fixed
+
+- **Windows Symbolic Link Creation**: Corrected `auto.md` workflow to use `mklink /D` on Windows, preventing duplicate directories instead of symlinks
+
+#### Changed
+
+- **Agent Allocation Strategy**: `generate.md` now allocates tasks by layout (layout-based) instead of style, improving performance and consistency for high variant counts by having one agent handle one layout strategy across multiple styles
+
+## [4.1.0] - 2025-10-09
+
+### 🔄 Matrix-Only UI Design Workflow
+
+#### Changed
+
+- **Matrix Mode by Default**: UI Design workflow now exclusively uses `style × layout` matrix mode with `--style-variants` and `--layout-variants` as standard parameters
+- **Path Standardization**: Standalone design sessions saved to `.workflow/.scratchpad/` adhering to project architecture
+- **Simplified Orchestration**: `auto.md` command simplified to use single `SlashCommand` for generation phase, removing complex loop logic
+
+#### Removed
+
+- **Deprecated Parameters**: Removed `--variants` and `--creative-variants` in favor of explicit `--style-variants` and `--layout-variants`
+- **Standard/Creative Modes**: Distinction between these modes removed
+
+---
+
 ## [4.0.2] - 2025-10-09
 
 ### 🔄 UI Design Workflow - Complete Refactoring

README.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-v4.0.1-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[![Version](https://img.shields.io/badge/version-v4.4.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
 [![MCP Tools](https://img.shields.io/badge/🔧_MCP_Tools-Experimental-orange.svg)](https://github.com/modelcontextprotocol)
@@ -15,16 +15,13 @@
 
 **Claude Code Workflow (CCW)** is a next-generation multi-agent automation framework that orchestrates complex software development tasks through intelligent workflow management and autonomous execution.
 
-> **🎉 Latest: v4.0.1** - UI Design Workflow V2 with Intelligent Page Inference & Agent Mode. See [CHANGELOG.md](CHANGELOG.md) for details.
+> **🎉 Latest: v4.4.0** - UI Design Workflow V3 with Layout/Style Separation Architecture. See [CHANGELOG.md](CHANGELOG.md) for details.
 >
-> **What's New in v4.0.1**:
-> - 🧠 **Intelligent Page Inference**: Pages auto-extracted from prompt text - no need to specify `--pages` manually
-> - 🤖 **Agent Creative Mode**: `--use-agent` enables parallel exploration of diverse design directions
-> - 🎯 **Unified Variant Control**: Single `--variants` parameter controls both style cards and UI prototypes
-> - 🔀 **Dual Mode Support**: Standalone (quick prototyping) or Integrated (workflow enhancement)
-> - 💬 **Dual Input Sources**: Images, text prompts, or hybrid (text guides image analysis)
-> - ✨ **Extreme Simplification**: All parameters optional with smart defaults
-> - ⚡ **Parallel Execution**: Agent mode generates variants concurrently for speed
+> **What's New in v4.4.0**:
+> - 🏗️ **Layout/Style Separation**: New `layout-extract` command separates structure from visual tokens
+> - 📦 **Pure Assembler**: `generate` command now purely combines pre-extracted layouts + styles
+> - 🎯 **Better Variety**: Layout exploration generates structurally distinct designs
+> - ✅ **Single Responsibility**: Each phase (style, layout, assembly) has clear purpose
 
 ---
 
@@ -253,24 +250,28 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 
 **Phase 2: UI Design Refinement** *(Optional for UI-heavy projects)*
 ```bash
-# Simplest - pages inferred from prompt (v4.0.2+)
-/workflow:ui-design:auto --prompt "Modern blog with home, article and author pages, dark theme"
+# Matrix Exploration Mode - Multiple style/layout variants (v4.2.1+)
+/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" --style-variants 3 --layout-variants 2
+
+# Fast Imitation Mode - Single design replication (v4.2.1+)
+/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
 
 # With session integration
-/workflow:ui-design:auto --session WFS-auth --images "refs/*.png" --variants 3
+/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
 
-# Or run individual design phases
-/workflow:ui-design:extract --images "refs/*.png" --variants 3
+# Or run individual design phases (v4.4.0+)
+/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
 /workflow:ui-design:consolidate --variants "variant-1,variant-3"
-/workflow:ui-design:generate --variants 2
+/workflow:ui-design:layout-extract --targets "dashboard,auth" --mode explore --variants 2 --device-type responsive
+/workflow:ui-design:generate --style-variants 1 --layout-variants 2
 
-# Preview generated prototypes (NEW!)
-# Option 1: Open .workflow/WFS-auth/.design/prototypes/index.html in browser
+# Preview generated prototypes
+# Option 1: Open .workflow/WFS-auth/.design/prototypes/compare.html in browser
 # Option 2: Start local server
 cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 # Visit http://localhost:8080 for interactive preview with comparison tools
 
-/workflow:ui-design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
+/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
 ```
 
 **Phase 3: Action Planning**
@@ -364,11 +365,13 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 |---|---|
 | `/workflow:session:*` | Manage development sessions (`start`, `pause`, `resume`, `list`, `switch`, `complete`). |
 | `/workflow:brainstorm:*` | Use role-based agents for multi-perspective planning. |
-| `/workflow:ui-design:auto` | **v4.0.2** UI design workflow with pure Claude execution. All parameters optional, no external tools. |
-| `/workflow:ui-design:extract` | **v4.0.2** Extract design from images/text using Claude-native analysis. Single-pass variant generation. |
-| `/workflow:ui-design:consolidate` | **v4.0.2** Consolidate style variants into validated design tokens using Claude synthesis. |
-| `/workflow:ui-design:generate` | **v4.0.2** Generate token-driven HTML/CSS prototypes with agent-based execution. |
-| `/workflow:ui-design:update` | **v4.0.2** Integrate finalized design system into brainstorming artifacts. |
+| `/workflow:ui-design:explore-auto` | **v4.4.0** Matrix exploration mode - Generate multiple style × layout variants with layout/style separation. |
+| `/workflow:ui-design:imitate-auto` | **v4.4.0** Fast imitation mode - Rapid UI replication with auto-screenshot, layout extraction, and assembly. |
+| `/workflow:ui-design:style-extract` | **v4.4.0** Extract visual style (colors, typography, spacing) from images/text using Claude-native analysis. |
+| `/workflow:ui-design:layout-extract` | **v4.4.0** Extract structural layout (DOM, CSS layout rules) with device-aware templates. |
+| `/workflow:ui-design:consolidate` | **v4.4.0** Consolidate style variants into validated design tokens using Claude synthesis. |
+| `/workflow:ui-design:generate` | **v4.4.0** Pure assembler - Combine layout templates + design tokens → HTML/CSS prototypes. |
+| `/workflow:ui-design:update` | **v4.4.0** Integrate finalized design system into brainstorming artifacts. |
 | `/workflow:plan` | Create a detailed, executable plan from a description. |
 | `/workflow:tdd-plan` | Create TDD workflow (6 phases) with test coverage analysis and Red-Green-Refactor cycles. |
 | `/workflow:execute` | Execute the current workflow plan autonomously. |
@@ -380,47 +383,80 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 | `/workflow:tools:test-concept-enhanced` | Generate test strategy and requirements analysis using Gemini. |
 | `/workflow:tools:test-task-generate` | Generate test task JSON with test-fix-cycle specification. |
 
-### **UI Design Workflow Commands (`/workflow:ui-design:*`)** *(v4.0.2)*
+### **UI Design Workflow Commands (`/workflow:ui-design:*`)** *(v4.4.0)*
 
-The design workflow system provides complete UI design refinement with **pure Claude execution**, **intelligent page inference**, and **zero external dependencies**.
+The design workflow system provides complete UI design refinement with **layout/style separation architecture**, **pure Claude execution**, **intelligent target inference**, and **zero external dependencies**.
 
 #### Core Commands
 
-**`/workflow:ui-design:auto`** - Complete workflow orchestrator
+**`/workflow:ui-design:explore-auto`** - Matrix exploration mode
 ```bash
-# Simplest - pages auto-inferred from prompt (v4.0.2)
-/workflow:ui-design:auto --prompt "Modern blog with home, article and author pages, dark theme"
+# Comprehensive exploration - multiple style × layout variants
+/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" --style-variants 3 --layout-variants 2
 
-# Multiple style variants
-/workflow:ui-design:auto --prompt "SaaS dashboard and settings" --variants 3
+# With images and session integration
+/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
 
-# Hybrid: images + text prompt
-/workflow:ui-design:auto --images "refs/*.png" --prompt "E-commerce: home, product, cart"
-
-# Integrated with session + creative mode
-/workflow:ui-design:auto --session WFS-auth --images "refs/*.png" --variants 2 --creative-variants 3
+# Text-only mode with page inference
+/workflow:ui-design:explore-auto --prompt "E-commerce: home, product, cart" --style-variants 2 --layout-variants 2
 ```
-- **🆕 Pure Claude**: No external tools (gemini-wrapper, codex) required
-- **🆕 Zero Dependencies**: All analysis and generation done natively
-- **All Parameters Optional**: Smart defaults and inference for everything
-- **Page Inference**: Auto-extract pages from `--prompt` text
-- **Dual Mode**: Standalone (quick prototyping) or Integrated (workflow enhancement)
+- **🎯 Matrix Mode**: Generate all style × layout combinations
+- **📊 Comprehensive Exploration**: Compare multiple design directions
+- **🔍 Interactive Comparison**: Side-by-side comparison with viewport controls
+- **✅ Cross-page Validation**: Automatic consistency checks for multi-page designs
+- **⚡ Batch Selection**: Quick selection by style or layout
 
-**`/workflow:ui-design:extract`** - Style analysis with dual input sources
+**`/workflow:ui-design:imitate-auto`** - Fast imitation mode
+```bash
+# Rapid single-design replication
+/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
+
+# With session integration
+/workflow:ui-design:imitate-auto --session WFS-auth --images "refs/ui.png" --pages "home,product"
+
+# Auto-screenshot from URL (requires Playwright)
+/workflow:ui-design:imitate-auto --url "https://example.com" --pages "landing"
+```
+- **⚡ Speed Optimized**: 5-10x faster than explore-auto
+- **📸 Auto-Screenshot**: Automatic URL screenshot capture with Playwright/Chrome
+- **🎯 Direct Extraction**: Skip variant selection, go straight to implementation
+- **🔧 Single Design Focus**: Best for copying existing designs quickly
+
+**`/workflow:ui-design:style-extract`** - Visual style extraction (v4.4.0)
 ```bash
 # Pure text prompt
-/workflow:ui-design:extract --prompt "Modern minimalist, dark theme" --variants 3
+/workflow:ui-design:style-extract --prompt "Modern minimalist, dark theme" --mode explore --variants 3
 
 # Pure images
-/workflow:ui-design:extract --images "refs/*.png" --variants 3
+/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
 
 # Hybrid (text guides image analysis)
-/workflow:ui-design:extract --images "refs/*.png" --prompt "Linear.app style" --variants 2
+/workflow:ui-design:style-extract --images "refs/*.png" --prompt "Linear.app style" --mode imitate
+
+# High-fidelity single style
+/workflow:ui-design:style-extract --images "design.png" --mode imitate
 ```
+- **🎨 Visual Tokens Only**: Colors, typography, spacing (no layout structure)
+- **🔄 Dual Mode**: Imitate (single variant) / Explore (multiple variants)
 - **Claude-Native**: Single-pass analysis, no external tools
-- **Enhanced Output**: `style-cards.json` with embedded `proposed_tokens`
-- **Reproducible**: Deterministic structure, version-controlled logic
-- **Output**: 1 file (vs 4+ in previous versions)
+- **Output**: `style-cards.json` with embedded `proposed_tokens`
+
+**`/workflow:ui-design:layout-extract`** - Structural layout extraction (v4.4.0)
+```bash
+# Explore mode - multiple layout variants
+/workflow:ui-design:layout-extract --targets "home,dashboard" --mode explore --variants 3 --device-type responsive
+
+# Imitate mode - single layout replication
+/workflow:ui-design:layout-extract --images "refs/*.png" --targets "dashboard" --mode imitate --device-type desktop
+
+# With MCP research (explore mode)
+/workflow:ui-design:layout-extract --prompt "E-commerce checkout" --targets "cart,checkout" --mode explore --variants 2
+```
+- **🏗️ Structure Only**: DOM hierarchy, CSS layout rules (no visual style)
+- **📱 Device-Aware**: Desktop, mobile, tablet, responsive optimizations
+- **🧠 Agent-Powered**: Uses ui-design-agent for structural analysis
+- **🔍 MCP Research**: Layout pattern inspiration (explore mode)
+- **Output**: `layout-templates.json` with token-based CSS
 
 **`/workflow:ui-design:consolidate`** - Validate and merge tokens
 ```bash
@@ -431,18 +467,19 @@ The design workflow system provides complete UI design refinement with **pure Cl
 - **Features**: WCAG AA validation, OKLCH colors, W3C token format
 - **Output**: `design-tokens.json`, `style-guide.md`, `tailwind.config.js`, `validation-report.json`
 
-**`/workflow:ui-design:generate`** - Generate HTML/CSS prototypes
+**`/workflow:ui-design:generate`** - Pure assembler (v4.4.0)
 ```bash
-# Standard mode (consistent layouts)
-/workflow:ui-design:generate --pages "dashboard,auth" --variants 2
+# Combine layout templates + design tokens
+/workflow:ui-design:generate --style-variants 1 --layout-variants 2
 
-# Creative mode (diverse layout exploration)
-/workflow:ui-design:generate --pages "home,product,cart" --creative-variants 3
+# Multiple styles with multiple layouts
+/workflow:ui-design:generate --style-variants 2 --layout-variants 3
 ```
-- **Page Inference**: Auto-detect from session or default to `["home"]`
-- **Agent-Only**: Task(conceptual-planning-agent) execution
-- **Creative Mode**: Parallel agents for diverse layout strategies
-- **Preview Files**: `index.html`, `compare.html`, `PREVIEW.md`
+- **📦 Pure Assembly**: Combines pre-extracted layout-templates.json + design-tokens.json
+- **❌ No Design Logic**: All layout/style decisions made in previous phases
+- **✅ Token Resolution**: Replaces var() placeholders with actual token values
+- **🎯 Matrix Output**: Generates style × layout × targets prototypes
+- **🔍 Interactive Preview**: `compare.html` with side-by-side comparison
 
 **`/workflow:ui-design:update`** - Integrate design system
 ```bash

README_CN.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-v3.5.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[![Version](https://img.shields.io/badge/version-v4.3.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
 [![MCP工具](https://img.shields.io/badge/🔧_MCP工具-实验性-orange.svg)](https://github.com/modelcontextprotocol)
@@ -15,16 +15,13 @@
 
 **Claude Code Workflow (CCW)** 是一个新一代的多智能体自动化开发框架，通过智能工作流管理和自主执行来协调复杂的软件开发任务。
 
-> **🎉 最新版本: v3.5.0** - UI 设计工作流与三重视觉分析。详见 [CHANGELOG.md](CHANGELOG.md)。
+> **🎉 最新版本: v4.3.0** - UI 设计工作流 V2 自包含 CSS 架构。详见 [CHANGELOG.md](CHANGELOG.md)。
 >
-> **v3.5.0 版本新特性**:
-> - 🎨 **UI 设计工作流**: 从风格提取到原型生成的完整设计精炼工作流
-> - 👁️ **三重视觉分析**: 融合 Claude Code + Gemini + Codex 视觉能力进行综合风格提取
-> - ⏸️ **交互式检查点**: 用户选择风格变体和原型确认的决策点
-> - 🎯 **零智能体开销**: CLI 工具直接 bash 执行，移除不必要的智能体包装
-> - 🎨 **风格自定义**: 通过 `--style-overrides` 参数支持运行时样式覆盖
-> - 📦 **批量任务生成**: 使用 `--batch-plan` 为选定原型自动创建实现任务
-> - 🔄 **半自主工作流**: 在关键设计决策点由用户驱动继续
+> **v4.3.0 版本新特性**:
+> - 🎨 **自包含 CSS**: Agent 从 design-tokens.json 直接生成独立 CSS
+> - ⚡ **简化工作流**: 移除占位符机制和令牌转换步骤
+> - 💪 **更强风格差异**: CSS 使用直接令牌值，实现更强视觉区分
+> - 📉 **代码减少 31%**: 移除 346 行代码，职责更清晰
 
 ---
 
@@ -253,21 +250,27 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 
 **阶段 2：UI 设计精炼** *(UI 密集型项目可选)*
 ```bash
-# 从参考图像中提取设计风格并生成原型
-/workflow:ui-design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" --batch-plan
+# 矩阵探索模式 - 多个风格×布局变体（v4.2.1+）
+/workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2
+
+# 快速模仿模式 - 单一设计快速复制（v4.2.1+）
+/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
+
+# 与会话集成
+/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
 
 # 或者运行单独的设计阶段
-/workflow:ui-design:style-extract --session WFS-auth --images "refs/*.png"
-/workflow:ui-design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
-/workflow:ui-design:ui-generate --session WFS-auth --pages "login,register" --variants 2
+/workflow:ui-design:extract --images "refs/*.png" --variants 3
+/workflow:ui-design:consolidate --variants "variant-1,variant-3"
+/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 2
 
-# 预览生成的原型（新功能！）
-# 选项1：在浏览器中打开 .workflow/WFS-auth/.design/prototypes/index.html
+# 预览生成的原型
+# 选项1：在浏览器中打开 .workflow/WFS-auth/.design/prototypes/compare.html
 # 选项2：启动本地服务器
 cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 # 访问 http://localhost:8080 获取交互式预览和对比工具
 
-/workflow:ui-design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
+/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
 ```
 
 **阶段 3：行动规划**
@@ -361,11 +364,12 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 |---|---|
 | `/workflow:session:*` | 管理开发会话（`start`, `pause`, `resume`, `list`, `switch`, `complete`）。 |
 | `/workflow:brainstorm:*` | 使用基于角色的智能体进行多视角规划。 |
-| `/workflow:ui-design:auto` | **新增** 带交互式检查点的半自主 UI 设计工作流，用于风格和原型选择。 |
-| `/workflow:ui-design:style-extract` | **新增** 使用三重视觉分析（Claude + Gemini + Codex）从参考图像提取设计风格。 |
-| `/workflow:ui-design:style-consolidate` | **新增** 将选定的风格变体整合为经过验证的设计令牌和风格指南。 |
-| `/workflow:ui-design:ui-generate` | **新增** 生成基于令牌的 HTML/CSS 原型，支持可选的风格覆盖。 |
-| `/workflow:ui-design:design-update` | **新增** 将最终确定的设计系统集成到头脑风暴产物中。 |
+| `/workflow:ui-design:explore-auto` | **v4.2.1** 矩阵探索模式 - 生成多个风格×布局变体，全面探索设计方向。 |
+| `/workflow:ui-design:imitate-auto` | **v4.2.1** 快速模仿模式 - 单一设计快速复制，自动截图和直接令牌提取。 |
+| `/workflow:ui-design:extract` | **v4.2.1** 使用 Claude 原生分析从图像/文本提取设计。单次生成变体。 |
+| `/workflow:ui-design:consolidate` | **v4.2.1** 使用 Claude 合成将风格变体整合为经过验证的设计令牌。 |
+| `/workflow:ui-design:generate` | **v4.2.1** 生成矩阵模式（风格×布局组合）的令牌驱动 HTML/CSS 原型。 |
+| `/workflow:ui-design:update` | **v4.2.1** 将最终确定的设计系统集成到头脑风暴产物中。 |
 | `/workflow:plan` | 从描述创建详细、可执行的计划。 |
 | `/workflow:tdd-plan` | 创建 TDD 工作流（6 阶段），包含测试覆盖分析和 Red-Green-Refactor 循环。 |
 | `/workflow:execute` | 自主执行当前的工作流计划。 |
@@ -377,28 +381,44 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 | `/workflow:tools:test-concept-enhanced` | 使用 Gemini 生成测试策略和需求分析。 |
 | `/workflow:tools:test-task-generate` | 生成测试任务 JSON，包含 test-fix-cycle 规范。 |
 
-### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v3.5.0+)*
+### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v4.2.1)*
 
-设计工作流系统提供从风格提取到原型生成的完整 UI 设计精炼，配备交互式预览工具。
+设计工作流系统提供完整的 UI 设计精炼，具备**纯 Claude 执行**、**智能页面推断**和**零外部依赖**。
 
 #### 核心命令
 
-**`/workflow:ui-design:auto`** - 完整工作流编排器
+**`/workflow:ui-design:explore-auto`** - 矩阵探索模式
 ```bash
-# 带用户检查点的半自主工作流
-/workflow:ui-design:auto --session WFS-auth --images "refs/*.png" --pages "login,register"
-/workflow:ui-design:auto --session WFS-dash --images "refs/*.jpg" --pages "dashboard" --variants 3 --batch-plan
-```
-- **检查点**: 用户选择风格变体（阶段1）和确认原型（阶段3）
-- **可选**: `--batch-plan` 用于自动任务生成
+# 全面探索 - 多个风格×布局变体
+/workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2
 
-**`/workflow:ui-design:style-extract`** - 三重视觉风格分析
-```bash
-# 从参考图像提取设计
-/workflow:ui-design:style-extract --session WFS-auth --images "design-refs/*.png"
+# 与图像和会话集成
+/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
+
+# 纯文本模式，带页面推断
+/workflow:ui-design:explore-auto --prompt "电商：首页，产品，购物车" --style-variants 2 --layout-variants 2
 ```
-- **视觉来源**: Claude Code + Gemini + Codex
-- **输出**: 用于用户选择的风格变体卡片
+- **🎯 矩阵模式**: 生成所有风格×布局组合
+- **📊 全面探索**: 比较多个设计方向
+- **🔍 交互式对比**: 带视口控制的并排比较
+- **✅ 跨页面验证**: 多页面设计的自动一致性检查
+- **⚡ 批量选择**: 按风格或布局快速选择
+
+**`/workflow:ui-design:imitate-auto`** - 快速模仿模式
+```bash
+# 快速单一设计复制
+/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
+
+# 与会话集成
+/workflow:ui-design:imitate-auto --session WFS-auth --images "refs/ui.png" --pages "home,product"
+
+# 从 URL 自动截图（需要 Playwright）
+/workflow:ui-design:imitate-auto --url "https://example.com" --pages "landing"
+```
+- **⚡ 速度优化**: 比 explore-auto 快 5-10 倍
+- **📸 自动截图**: 使用 Playwright/Chrome 自动捕获 URL 截图
+- **🎯 直接提取**: 跳过变体选择，直接进入实现
+- **🔧 单一设计聚焦**: 最适合快速复制现有设计
 
 **`/workflow:ui-design:style-consolidate`** - 验证和合并令牌
 ```bash
@@ -408,19 +428,24 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 - **功能**: WCAG AA 验证、OKLCH 颜色、W3C 令牌格式
 - **输出**: `design-tokens.json`、`style-guide.md`、`tailwind.config.js`
 
-**`/workflow:ui-design:ui-generate`** - 生成 HTML/CSS 原型
+**`/workflow:ui-design:generate`** - 生成 HTML/CSS 原型
 ```bash
-# 生成带预览工具的原型
-/workflow:ui-design:ui-generate --session WFS-auth --pages "login,register" --variants 2
-/workflow:ui-design:ui-generate --session WFS-auth --pages "dashboard" --style-overrides "custom.json"
-```
-- **🆕 预览文件**: `index.html`（导航）、`compare.html`（并排对比）、`PREVIEW.md`（说明）
-- **功能**: 令牌驱动的 CSS、语义化 HTML5、ARIA 属性、响应式设计
+# 矩阵模式 - 风格×布局组合
+/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 3
 
-**`/workflow:ui-design:design-update`** - 集成设计系统
+# 单页面多变体
+/workflow:ui-design:generate --pages "home" --style-variants 3 --layout-variants 2
+```
+- **🎯 矩阵生成**: 创建所有风格×布局组合
+- **📊 多页面支持**: 跨页面一致的设计系统
+- **✅ 一致性验证**: 自动跨页面一致性报告（v4.2.0+）
+- **🔍 交互式预览**: `compare.html` 并排比较
+- **📋 批量选择**: 按风格或布局过滤器快速选择
+
+**`/workflow:ui-design:update`** - 集成设计系统
 ```bash
 # 使用设计系统更新头脑风暴产物
-/workflow:ui-design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
+/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
 ```
 - **更新**: `synthesis-specification.md`、`ui-designer/style-guide.md`
 - **使设计令牌可用于任务生成**

ui-instantiate-analysis.md

@@ -0,0 +1,231 @@
+# UI原型实例化脚本分析报告
+
+## 问题现象
+
+在执行 `ui-instantiate-prototypes.sh` 脚本时，生成了 `style-4` 的原型文件（如 `login-style-4-layout-1.html`），但实际上 `style-consolidation` 目录下只有3个样式目录（style-1, style-2, style-3）。
+
+## 调查结果
+
+### 1. 目录结构验证
+
+```bash
+# 实际存在的样式目录
+.workflow/.design/run-20251009-210559/style-consolidation/
+├── style-1/
+├── style-2/
+└── style-3/
+
+# 生成的原型文件包含
+prototypes/login-style-4-layout-1.html  ❌ 引用不存在的 ../style-consolidation/style-4/tokens.css
+prototypes/sidebar-style-4-layout-1.html  ❌ 引用不存在的 ../style-consolidation/style-4/tokens.css
+```
+
+### 2. consolidation-report.json 确认
+
+```json
+{
+  "variant_count": 3,  // 明确显示只有3个变体
+  "variants": [
+    {"id": "style-1"},
+    {"id": "style-2"},
+    {"id": "style-3"}
+  ]
+}
+```
+
+### 3. PREVIEW.md 显示异常
+
+```markdown
+- **Style Variants:** 4  ⚠️ 与实际不符
+- **Total Prototypes:** 24  (4 × 3 × 2 = 24)
+```
+
+### 4. 脚本auto_detect_style_variants()函数
+
+```bash
+# 位置：.claude/scripts/ui-instantiate-prototypes.sh 第52-71行
+auto_detect_style_variants() {
+    local base_path="$1"
+    local style_dir="$base_path/../style-consolidation"
+
+    # 统计style-*目录数量
+    local count=$(find "$style_dir" -maxdepth 1 -type d -name "style-*" | wc -l)
+    echo "$count"
+}
+```
+
+**验证测试**：
+```bash
+cd .workflow/.design/run-20251009-210559/style-consolidation
+find . -maxdepth 1 -type d -name "style-*" | wc -l
+# 输出：3 ✅ 函数逻辑正确
+```
+
+## 根本原因分析
+
+### ⚠️ 参数覆盖问题
+
+脚本虽然有自动检测功能，但**允许手动参数覆盖**：
+
+```bash
+# 自动检测模式（正确）
+ui-instantiate-prototypes.sh prototypes/  # 会自动检测到3个样式
+
+# 手动模式（错误来源）
+ui-instantiate-prototypes.sh prototypes/ "login,sidebar" 4 3  # 强制指定4个样式变体 ❌
+```
+
+### 🔍 实际调用场景
+
+根据工作流命令 `.claude/commands/workflow/ui-design/generate.md` 第79-82行：
+
+```bash
+# Phase 1: Path Resolution & Context Loading
+style_variants = --style-variants OR 3  # 默认为3
+```
+
+**推断的问题来源**：
+1. 工作流命令被手动调用时，传入了 `--style-variants 4`
+2. 这个参数被直接传递给 `ui-instantiate-prototypes.sh` 脚本
+3. 脚本没有验证参数值与实际目录数量是否匹配
+4. 导致生成了引用不存在的style-4目录的HTML文件
+
+## 问题影响
+
+### 生成的style-4文件问题
+
+所有 `*-style-4-*.html` 文件都会出现CSS加载失败：
+
+```html
+<!-- 文件中的CSS引用 -->
+<link rel="stylesheet" href="../style-consolidation/style-4/tokens.css">
+<!-- ❌ 该路径不存在，导致样式无法加载 -->
+```
+
+### 影响范围
+
+- `login-style-4-layout-{1,2,3}.html` - 3个文件 ❌
+- `sidebar-style-4-layout-{1,2,3}.html` - 3个文件 ❌
+- 对应的 `*-notes.md` 文件 - 6个说明文件（内容错误）
+
+## 解决方案
+
+### 方案1：重新生成（推荐）
+
+```bash
+cd .workflow/.design/run-20251009-210559/prototypes
+
+# 删除错误的style-4文件
+rm -f *-style-4-*
+
+# 重新运行脚本（使用自动检测）
+~/.claude/scripts/ui-instantiate-prototypes.sh . --session-id run-20251009-210559
+```
+
+### 方案2：脚本增强（预防）
+
+在 `ui-instantiate-prototypes.sh` 中添加参数验证：
+
+```bash
+# 在第239行之后添加
+# Validate STYLE_VARIANTS matches actual directories
+actual_styles=$(find "$BASE_PATH/../style-consolidation" -maxdepth 1 -type d -name "style-*" | wc -l)
+if [ "$STYLE_VARIANTS" -gt "$actual_styles" ]; then
+    log_warning "Requested $STYLE_VARIANTS style variants, but only found $actual_styles directories"
+    log_info "Auto-correcting to $actual_styles style variants"
+    STYLE_VARIANTS=$actual_styles
+fi
+```
+
+### 方案3：工作流命令修复
+
+在 `.claude/commands/workflow/ui-design/generate.md` 中添加验证：
+
+```bash
+# Phase 1: Path Resolution & Context Loading (第79-82行之后)
+style_variants = --style-variants OR 3  # Default to 3
+
+# 添加验证逻辑
+actual_styles = count_directories({base_path}/style-consolidation/style-*)
+IF style_variants > actual_styles:
+    WARN: "Requested {style_variants} styles, but only {actual_styles} exist"
+    REPORT: "Auto-correcting to {actual_styles} style variants"
+    style_variants = actual_styles
+
+VALIDATE: 1 <= style_variants <= 5
+```
+
+## 预防措施
+
+1. **优先使用自动检测**：
+   ```bash
+   # ✅ 推荐：让脚本自动检测
+   ui-instantiate-prototypes.sh prototypes/
+
+   # ⚠️ 谨慎：手动指定参数（需确保正确）
+   ui-instantiate-prototypes.sh prototypes/ "login,sidebar" 3 3
+   ```
+
+2. **验证consolidation输出**：
+   ```bash
+   # 生成原型前，先确认样式数量
+   jq '.variant_count' style-consolidation/consolidation-report.json
+   ```
+
+3. **使用工作流命令**：
+   ```bash
+   # 工作流命令会自动处理参数验证
+   /workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+   ```
+
+## 技术细节
+
+### 自动检测逻辑流程
+
+```mermaid
+graph TD
+    A[调用脚本] --> B{检查参数数量}
+    B -->|1个参数| C[自动检测模式]
+    B -->|4个参数| D[手动模式]
+    C --> E[检测style目录]
+    D --> F[使用传入参数]
+    E --> G[验证目录存在]
+    F --> G
+    G -->|不匹配| H[⚠️ 生成错误文件]
+    G -->|匹配| I[✅ 正常生成]
+```
+
+### find命令行为
+
+```bash
+# 正确的检测命令
+find style-consolidation -maxdepth 1 -type d -name "style-*"
+# 输出：
+# style-consolidation/style-1
+# style-consolidation/style-2
+# style-consolidation/style-3
+
+# wc -l 统计行数 = 3 ✅
+
+# 注意：style-extraction 不会被匹配（它在父目录）
+# find . -maxdepth 1 -type d -name "style-*"
+# 只会在当前目录搜索，不会递归到子目录
+```
+
+## 总结
+
+### 问题根源
+✅ **确认**：脚本被手动调用时传入了错误的 `--style-variants 4` 参数，但实际只有3个样式目录存在。
+
+### 脚本行为
+✅ **确认**：`auto_detect_style_variants()` 函数逻辑正确，能够正确检测到3个样式目录。
+
+### 修复优先级
+1. 🔴 **立即**：删除错误的style-4文件，重新生成
+2. 🟡 **短期**：在脚本中添加参数验证逻辑
+3. 🟢 **长期**：在工作流命令中添加防护验证
+
+### 最佳实践
+- 优先使用脚本的自动检测模式
+- 在手动指定参数前，先验证 `consolidation-report.json`
+- 使用工作流命令而非直接调用脚本

ui-workflow-parameter-clarity-report.md

@@ -0,0 +1,425 @@
+# UI设计工作流参数清晰度分析报告
+
+## 📋 执行摘要
+
+**问题来源**：用户手动调用 `/workflow:ui-design:generate` 时传入了 `--style-variants 4`，但实际只有3个样式目录存在，导致生成了引用不存在CSS文件的 `style-4` 原型。
+
+**根本原因**：工作流命令链中参数命名不一致、验证缺失、文档说明不清晰。
+
+## 🔍 关键发现
+
+### 1. 参数命名不一致
+
+| 命令 | 参数名称 | 默认值 | 说明 |
+|------|---------|--------|------|
+| `extract` | `--variants` | 1 | ⚠️ 未在文档中明确说明默认值 |
+| `consolidate` | `--variants` | 所有变体 | ⚠️ 与extract同名但语义不同 |
+| `generate` | `--style-variants` | 3 | ⚠️ 名称不一致，默认值说明不清晰 |
+
+**问题**：
+- `extract` 和 `consolidate` 使用 `--variants`，但 `generate` 使用 `--style-variants`
+- `--variants` 在两个命令中含义不同：
+  - `extract`：生成多少个变体
+  - `consolidate`：处理多少个变体
+
+### 2. 命名转换混淆
+
+```
+extract 输出        → consolidate 处理      → generate 使用
+variant-1           → style-1/              → login-style-1-layout-1.html
+variant-2           → style-2/              → login-style-2-layout-1.html
+variant-3           → style-3/              → login-style-3-layout-1.html
+```
+
+**问题**：
+- `variant-N` 到 `style-N` 的转换没有文档说明
+- 增加了用户的认知负担
+- 容易造成混淆和错误
+
+### 3. 验证缺失
+
+#### ❌ 当前状态（generate.md 第79-82行）
+
+```bash
+# Phase 1: Path Resolution & Context Loading
+style_variants = --style-variants OR 3  # Default to 3
+VALIDATE: 1 <= style_variants <= 5
+```
+
+**问题**：
+- ✅ 验证范围（1-5）
+- ❌ 不验证是否匹配实际目录数量
+- ❌ 允许传入 `4` 但实际只有 `3` 个目录
+
+#### ✅ 应有的验证
+
+```bash
+style_variants = --style-variants OR 3
+actual_styles = count_directories({base_path}/style-consolidation/style-*)
+
+IF style_variants > actual_styles:
+    WARN: "Requested {style_variants} styles, but only {actual_styles} exist"
+    REPORT: "Auto-correcting to {actual_styles} style variants"
+    style_variants = actual_styles
+
+VALIDATE: 1 <= style_variants <= actual_styles
+```
+
+### 4. 文档清晰度问题
+
+#### extract.md
+
+**问题点**：
+- ⚠️ 默认值 `1` 未在 `usage` 或 `argument-hint` 中说明
+- ⚠️ 输出的 `variant-N` 命名未解释后续转换为 `style-N`
+
+**当前文档**（第580行附近）：
+```
+"id": "variant-2"  # 缺少说明这会成为 style-2 目录
+```
+
+#### consolidate.md
+
+**问题点**：
+- ⚠️ `--variants` 与 `extract` 同名但语义不同
+- ⚠️ 默认行为（处理所有变体）不够突出
+- ⚠️ `variant-N` → `style-N` 转换未文档化
+
+#### generate.md
+
+**问题点**：
+- ⚠️ `--style-variants` 名称与前置命令不一致
+- ⚠️ 默认值 `3` 的来源和意义不清晰
+- ⚠️ 自动检测机制未说明
+- ❌ 手动覆盖无验证
+
+**当前文档**（第79-82行）：
+```bash
+style_variants = --style-variants OR 3  # Default to 3
+VALIDATE: 1 <= style_variants <= 5
+```
+
+## 💡 改进方案
+
+### 方案1：代码层面改进（推荐）
+
+#### 1.1 统一参数命名
+
+```diff
+# extract.md
+- usage: /workflow:ui-design:extract [--variants <count>]
++ usage: /workflow:ui-design:extract [--style-variants <count>]
+
+# consolidate.md
+- usage: /workflow:ui-design:consolidate [--variants <count>]
++ usage: /workflow:ui-design:consolidate [--style-variants <count>]
+
+# generate.md (保持不变)
+  usage: /workflow:ui-design:generate [--style-variants <count>]
+```
+
+**优点**：
+- ✅ 全链路参数名称统一
+- ✅ 语义清晰（style-variants）
+- ✅ 降低混淆风险
+
+#### 1.2 添加验证逻辑（关键）
+
+##### generate.md 改进
+
+```bash
+# Phase 1: Path Resolution & Context Loading
+style_variants = --style-variants OR 3  # Default to 3
+
+# 🆕 添加验证逻辑
+actual_styles = count_directories({base_path}/style-consolidation/style-*)
+
+IF actual_styles == 0:
+    ERROR: "No style directories found in {base_path}/style-consolidation/"
+    SUGGEST: "Run /workflow:ui-design:consolidate first"
+    EXIT 1
+
+IF style_variants > actual_styles:
+    WARN: "⚠️ Requested {style_variants} style variants, but only {actual_styles} directories exist"
+    REPORT: "   Auto-correcting to {actual_styles} style variants"
+    REPORT: "   Available styles: {list_directories(style-consolidation/style-*)}"
+    style_variants = actual_styles
+
+VALIDATE: 1 <= style_variants <= actual_styles
+```
+
+##### ui-instantiate-prototypes.sh 改进
+
+在脚本第239行之后添加：
+
+```bash
+# Validate STYLE_VARIANTS matches actual directories
+if [ "$STYLE_VARIANTS" -gt 0 ]; then
+    actual_styles=$(find "$BASE_PATH/../style-consolidation" -maxdepth 1 -type d -name "style-*" 2>/dev/null | wc -l)
+
+    if [ "$actual_styles" -eq 0 ]; then
+        log_error "No style directories found in style-consolidation/"
+        log_info "Run /workflow:ui-design:consolidate first"
+        exit 1
+    fi
+
+    if [ "$STYLE_VARIANTS" -gt "$actual_styles" ]; then
+        log_warning "Requested $STYLE_VARIANTS style variants, but only found $actual_styles directories"
+        log_info "Auto-correcting to $actual_styles style variants"
+        STYLE_VARIANTS=$actual_styles
+    fi
+fi
+```
+
+#### 1.3 统一命名约定
+
+##### extract.md 改进
+
+修改输出格式（第580行附近）：
+
+```diff
+# style-cards.json 格式
+{
+  "style_cards": [
+    {
+-     "id": "variant-1",
++     "id": "style-1",
+      "name": "Modern Minimalist",
+      ...
+    }
+  ]
+}
+```
+
+### 方案2：文档层面改进
+
+#### 2.1 extract.md 文档改进
+
+```markdown
+## Parameters
+
+- `--style-variants <count>`: Number of style variants to extract. **Default: 1**
+  - Range: 1-5
+  - Each variant will become an independent design system (style-1, style-2, etc.)
+  - Output IDs use `style-N` format for consistency across the workflow
+
+## Output Format
+
+style-cards.json uses `style-N` IDs that directly correspond to directory names
+created by the consolidate command:
+
+- `style-1` → `style-consolidation/style-1/`
+- `style-2` → `style-consolidation/style-2/`
+```
+
+#### 2.2 consolidate.md 文档改进
+
+```markdown
+## Parameters
+
+- `--style-variants <count>`: Number of style variants to process from style-cards.json.
+  **Default: all available variants**
+  - Processes the first N variants from the style-cards array
+  - Creates separate `style-{n}` directories for each variant
+  - Range: 1 to count available in style-cards.json
+
+## Naming Convention
+
+Variants from extraction are materialized into style directories:
+- Input: `style-cards.json` with `style-1`, `style-2`, `style-3`
+- Output: `style-consolidation/style-1/`, `style-2/`, `style-3/` directories
+```
+
+#### 2.3 generate.md 文档改进
+
+```markdown
+## Parameters
+
+- `--style-variants <count>`: Number of style variants to generate prototypes for.
+  **Default: 3** (can be overridden)
+  - Range: 1-5
+  - ⚠️ **IMPORTANT**: This value MUST match the number of style-* directories in style-consolidation/
+  - If mismatched, the command will auto-correct to the actual directory count
+  - Use auto-detection (omit parameter) for safety
+
+## Auto-Detection vs Manual Override
+
+The command uses intelligent auto-detection:
+
+1. **Auto-Detection** (Recommended):
+   ```bash
+   /workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+   # Automatically counts style-1/, style-2/, style-3/ → uses 3
+   ```
+
+2. **Manual Override** (Use with caution):
+   ```bash
+   /workflow:ui-design:generate --style-variants 4
+   # If only 3 styles exist, auto-corrects to 3 with warning
+   ```
+
+3. **Safety Check**:
+   - Command validates against actual `style-consolidation/style-*` directories
+   - Prevents generation of prototypes referencing non-existent styles
+   - Displays warning and auto-corrects if mismatch detected
+```
+
+### 方案3：用户指南改进
+
+创建 `.claude/commands/workflow/ui-design/README.md`：
+
+```markdown
+# UI Design Workflow Parameter Guide
+
+## Style Variant Count Flow
+
+### 1. Extract Phase
+```bash
+/workflow:ui-design:extract --style-variants 3
+# Generates: style-cards.json with 3 style variants (style-1, style-2, style-3)
+```
+
+### 2. Consolidate Phase
+```bash
+/workflow:ui-design:consolidate --style-variants 3
+# Creates: style-consolidation/style-1/, style-2/, style-3/
+```
+
+### 3. Generate Phase
+```bash
+# ✅ Recommended: Let it auto-detect
+/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+
+# ⚠️ Manual: Must match consolidation output
+/workflow:ui-design:generate --style-variants 3
+```
+
+## ⚠️ Common Mistakes
+
+### Mistake 1: Mismatched Counts
+```bash
+# ❌ Wrong: Request 4 styles when only 3 exist
+/workflow:ui-design:generate --style-variants 4
+# Only 3 directories in style-consolidation/ → ERROR
+
+# ✅ Correct: Omit parameter for auto-detection
+/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+```
+
+### Mistake 2: Naming Confusion
+```bash
+# ❌ Don't confuse variant-N with style-N
+# variant-N was old naming in style-cards.json
+# style-N is the current standard across all commands
+```
+
+## 🎯 Best Practices
+
+1. **Use auto-detection**: Omit `--style-variants` in generate command
+2. **Verify consolidation**: Check `consolidation-report.json` before generating
+3. **Use explore-auto**: Automated workflow prevents parameter mismatches
+4. **Check directories**: `ls .workflow/.design/run-xxx/style-consolidation/`
+```
+
+## 🎯 实施优先级
+
+### 🔴 高优先级（立即实施）
+
+1. **generate.md 添加验证逻辑**
+   - 防止参数不匹配问题再次发生
+   - 影响范围：所有手动调用 generate 命令的场景
+
+2. **ui-instantiate-prototypes.sh 添加验证**
+   - 脚本层面的最后防线
+   - 影响范围：所有原型生成操作
+
+3. **文档说明默认值和验证机制**
+   - 降低用户误用风险
+   - 影响范围：所有新用户和手动操作场景
+
+### 🟡 中优先级（短期改进）
+
+4. **统一参数命名为 --style-variants**
+   - 提高一致性，减少混淆
+   - 影响范围：需要更新多个命令文件
+
+5. **extract.md 统一使用 style-N 命名**
+   - 消除命名转换混淆
+   - 影响范围：需要更新 style-cards.json 格式
+
+### 🟢 低优先级（长期优化）
+
+6. **创建用户指南 README.md**
+   - 提供完整的参数使用指南
+   - 影响范围：文档层面，不影响功能
+
+## 📊 改进效果预测
+
+### 实施前
+
+```
+用户手动调用: /workflow:ui-design:generate --style-variants 4
+实际目录数: 3
+结果: ❌ 生成 login-style-4-layout-1.html 引用不存在的 CSS
+```
+
+### 实施后
+
+```
+用户手动调用: /workflow:ui-design:generate --style-variants 4
+实际目录数: 3
+
+验证检查:
+⚠️ Requested 4 style variants, but only 3 directories exist
+   Available: style-1, style-2, style-3
+   Auto-correcting to 3 style variants
+
+结果: ✅ 生成正确的 style-1, style-2, style-3 原型，避免错误
+```
+
+## 🔧 快速修复指南（针对当前问题）
+
+### 立即修复生成的错误文件
+
+```bash
+cd .workflow/.design/run-20251009-210559/prototypes
+
+# 删除错误的 style-4 文件
+rm -f *-style-4-*
+
+# 重新生成（使用自动检测）
+~/.claude/scripts/ui-instantiate-prototypes.sh . --session-id run-20251009-210559
+```
+
+### 预防未来错误
+
+```bash
+# ✅ 推荐：使用自动检测
+/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+
+# ⚠️ 如果必须手动指定，先验证
+jq '.variant_count' .workflow/.design/run-xxx/style-consolidation/consolidation-report.json
+# 输出: 3
+# 然后使用该数字
+/workflow:ui-design:generate --style-variants 3
+```
+
+## 📝 总结
+
+**核心问题**：
+- 参数命名不统一（`--variants` vs `--style-variants`）
+- 命名转换混淆（`variant-N` → `style-N`）
+- 验证缺失（不检查参数是否匹配实际目录）
+- 文档不清晰（默认值、自动检测机制说明不足）
+
+**关键改进**：
+1. ✅ 添加参数验证逻辑（防止不匹配）
+2. ✅ 统一参数命名（提高一致性）
+3. ✅ 完善文档说明（降低误用风险）
+4. ✅ 提供清晰的用户指南
+
+**预期效果**：
+- 🔒 杜绝参数不匹配问题
+- 📈 提高工作流鲁棒性
+- 🎓 降低用户学习成本
+- 🚀 提升整体用户体验