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

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

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

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

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

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

 ## Phase 1: Setup & Validation

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

 ## Error Handling

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

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

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

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

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

 ## Quality Checklist

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

 ## Key Features

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

 ## Integration

-**Input**: design-tokens.json, design-space-analysis.json (optional), targets
+**Prerequisites**:
+- `/workflow:ui-design:style-extract` → `style-cards.json`
+- `/workflow:ui-design:consolidate` → `design-tokens.json`
+- `/workflow:ui-design:layout-extract` → `layout-templates.json`
+
+**Input**: `layout-templates.json` + `design-tokens.json`
 **Output**: S×L×T prototypes for `/workflow:ui-design:update`
 **Called by**: `/workflow:ui-design:explore-auto`, `/workflow:ui-design:imitate-auto`