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

name, description, usage, examples, allowed-tools

name	description	usage	examples	allowed-tools
generate	Generate UI prototypes in matrix mode (style × layout combinations) for pages or components	/workflow:ui-design:generate [--targets "<list>"] [--target-type "page|component"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]	/workflow:ui-design:generate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --targets "dashboard,settings" /workflow:ui-design:generate --session WFS-auth --targets "home,pricing" --style-variants 2 --layout-variants 2 /workflow:ui-design:generate --targets "navbar,hero,card" --target-type "component"	TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)

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

Overview

Generate matrix of UI prototypes (style × layout × targets) with production-ready HTML/CSS. Optimized template-based architecture: S times faster than direct generation.

Strategy: Two-layer generation

• Layer 1: Generate L × T reusable templates (agent)
• Layer 2: Instantiate S × L × T final prototypes (script)

Supports: Pages (full layouts) and components (isolated elements)

Phase 1: Setup & Validation

Step 1: Resolve Base Path

# Determine working directory
bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
# OR use --base-path / --session parameters

Step 2: Parse Configuration

# Get style variant count (default: 3)
bash(ls {base_path}/style-consolidation/style-* -d | wc -l)

# Get layout variant count (default: 3, configurable via --layout-variants)

# Parse targets (pages/components)
# Priority: --targets → --pages (legacy) → synthesis-specification.md → default ["home"]

Step 3: Validate Inputs

# Check design systems exist
bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")

# Validate target names (lowercase, alphanumeric, hyphens only)
# Target type: "page" (default) or "component"

Output: base_path, style_variants, layout_variants, target_list[], target_type

Step 4: Check Existing Output

# Skip if already generated
bash(test -f {base_path}/prototypes/compare.html && echo "exists")

If exists: Skip to completion message

Phase 2: Layout Planning

Step 1: Research Layout Patterns (Agent)

bash(mkdir -p {base_path}/prototypes/_templates)

For each target × layout_id:

Task(ui-design-agent): `
  [TARGET_LAYOUT_PLANNING]
  TARGET: {target} | TYPE: {target_type} | LAYOUT: {layout_id}/{layout_variants}
  BASE_PATH: {base_path}
  ${--session ? "REQUIREMENTS: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md" : ""}

  ## 参考
  - Research via: mcp__exa__web_search_exa(query="{target} {target_type} layout patterns 2024", numResults=5)
  - Layout differentiation: Layout 1=common, Layout 2=alternative, Layout 3=innovative

  ## 生成
  Write("{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json")

  JSON schema:
  {
    "id": "layout-{layout_id}",
    "target": "{target}",
    "target_type": "{target_type}",
    "name": "2-4 words",
    "description": "2-3 sentences",
    "structure": {
      // Page: type, regions, grid, sidebar, responsive{mobile/tablet/desktop}
      // Component: arrangement, alignment, spacing, element_order, variants
    },
    "semantic_hints": ["<nav>", "<main role='main'>", ...],
    "accessibility_features": ["skip-link", "landmarks", ...],
    "research_references": ["source URLs/insights"]
  }

  ## 注意
  - Layout #{layout_id} must be STRUCTURALLY DIFFERENT from other IDs
  - Structure section must match target_type (page vs component)
  - Write file directly, no text output
`

Step 2: Verify Layout Plans

# Verify files created
bash(ls {base_path}/prototypes/_templates/*.json | wc -l)  # Should equal L×T

# Validate JSON structure
Read({base_path}/prototypes/_templates/{target}-layout-{layout_id}.json)

Output: L × T layout plan JSON files

Phase 3: Token Conversion

Step 1: Convert JSON to CSS Variables

# Check jq dependency
bash(command -v jq >/dev/null 2>&1 || echo "ERROR: jq not found")

# Convert each style's design-tokens.json to tokens.css
bash(cat {base_path}/style-consolidation/style-1/design-tokens.json | ~/.claude/scripts/convert_tokens_to_css.sh > tokens.css)

Step 2: Extract Variable Names

# Read generated tokens.css
Read({base_path}/style-consolidation/style-1/tokens.css)

# Extract CSS variable names (pattern: --variable-name:)
# Categorize: colors, typography, spacing, radius, shadows

Output: S × tokens.css files + extracted variable list

Phase 4: Template Generation (Agent)

Executor: Task(ui-design-agent) × L × T tasks in parallel

Step 1: Launch Agent Tasks

For each layout_id × target:

Task(ui-design-agent): `
  [UI_LAYOUT_TEMPLATE_GENERATION]
  🚨 ONE target only: '{target}' (standalone, reusable)

  LAYOUT: {layout_id} | TARGET: {target} | TYPE: {target_type}
  BASE_PATH: {base_path}
  ${--session ? "REQUIREMENTS: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md" : ""}

  ## 参考
  - Layout plan: Read("{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json")
  - Design tokens: Read("{base_path}/style-consolidation/style-1/tokens.css")
    Extract variables: --color-*, --font-*, --spacing-*, --border-radius-*, --shadow-*

  ## 生成
  1. HTML: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.html
     - Complete HTML5 doc with <link href="{{STRUCTURAL_CSS}}"> and <link href="{{TOKEN_CSS}}">
     - Body: Full structure (page) OR isolated element (component)
     - Semantic: <header>, <nav>, <main>, <footer>, proper heading hierarchy
     - A11y: ARIA landmarks, skip-link, alt/labels, focus styles

  2. CSS: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.css
     - Structure: Flexbox/Grid, positioning, dimensions, responsive
     - Mobile-first: base → @media(768px) → @media(1024px)
     - Optional: {target}-layout-{layout_id}-tokens.css for --layout-* vars

  ## 注意
  - ✅ ONLY var(--token-name) from tokens.css
  - ❌ NO hardcoded: colors (#333, rgb), spacing (16px), fonts ("Arial")
  - ❌ NO invented variable names
  - Body content matches target_type (page=full, component=isolated)
  - Write files directly, no text output
`

Step 2: Verify Templates Created

# Check file count
bash(ls {base_path}/prototypes/_templates/{target}-layout-*.html | wc -l)

# Validate structure
Read({base_path}/prototypes/_templates/{target}-layout-{layout_id}.html)
# Check: <!DOCTYPE html>, var(--, placeholders

Output: L × T template pairs (HTML + CSS)

Phase 5: Prototype Instantiation (Script)

Step 1: Execute Instantiation Script

# Verify tokens.css files exist
bash(ls {base_path}/style-consolidation/style-*/tokens.css | wc -l)

# Run instantiation script
bash(~/.claude/scripts/ui-instantiate-prototypes.sh "{base_path}/prototypes" --session-id "{session_id}" --mode "{target_type}")

Script generates:

• S × L × T HTML prototypes with CSS links
• Implementation notes for each prototype
• compare.html (interactive matrix)
• index.html (navigation)
• PREVIEW.md (documentation)

Step 2: Verify Output Files

# Check preview files
bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {base_path}/prototypes/PREVIEW.md)

# Count final prototypes
bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)

Output: S × L × T final prototypes + preview files

Completion

Todo Update

TodoWrite({todos: [
  {content: "Setup and validation", status: "completed", activeForm: "Loading design systems"},
  {content: "Layout planning (agent)", status: "completed", activeForm: "Planning layouts"},
  {content: "Token conversion", status: "completed", activeForm: "Converting tokens"},
  {content: "Template generation (agent)", status: "completed", activeForm: "Generating templates"},
  {content: "Prototype instantiation (script)", status: "completed", activeForm: "Running script"},
  {content: "Verify output", status: "completed", activeForm: "Verifying files"}
]});

Output Message

✅ Matrix UI generation complete!

Configuration:
- Style Variants: {style_variants}
- Layout Variants: {layout_variants}
- Target Type: {target_type}
- Targets: {target_list}
- Total Prototypes: {S × L × T}

Performance:
- Templates: {L × T} (agent)
- Prototypes: {S × L × T} (script)
- Speed: {S}× faster
- Script: ui-instantiate-prototypes.sh v3.0

Generated Files:
{base_path}/prototypes/
├── _templates/ ({T×L} JSON + HTML + CSS)
├── {target}-style-{s}-layout-{l}.html ({S×L×T} prototypes)
├── compare.html (interactive matrix)
├── index.html (navigation)
└── PREVIEW.md (documentation)

Preview:
1. Open compare.html (recommended)
2. Open index.html
3. Read PREVIEW.md

Next: /workflow:ui-design:update

Simple Bash Commands

Path Operations

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

# Count style variants
bash(ls {base_path}/style-consolidation/style-* -d | wc -l)

# List targets from templates
bash(ls {base_path}/prototypes/_templates/*-layout-1.json | sed 's/-layout-1.json//')

Validation Commands

# Check design tokens exist
bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")

# Count template files
bash(ls {base_path}/prototypes/_templates/*.html | wc -l)

# Verify output complete
bash(test -f {base_path}/prototypes/compare.html && echo "exists")

File Operations

# Create directories
bash(mkdir -p {base_path}/prototypes/_templates)

# Convert tokens to CSS
bash(cat design-tokens.json | ~/.claude/scripts/convert_tokens_to_css.sh > tokens.css)

# Run instantiation script
bash(~/.claude/scripts/ui-instantiate-prototypes.sh "{base_path}/prototypes" --mode "page")

Output Structure

{base_path}/
├── prototypes/
│   ├── _templates/
│   │   ├── {target}-layout-{l}.json  # Layout plans
│   │   ├── {target}-layout-{l}.html  # HTML templates
│   │   └── {target}-layout-{l}.css   # CSS templates
│   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
│   ├── {target}-style-{s}-layout-{l}-notes.md
│   ├── compare.html
│   ├── index.html
│   └── PREVIEW.md
└── style-consolidation/
    └── style-{s}/
        ├── design-tokens.json
        ├── tokens.css
        └── style-guide.md

Error Handling

Common Errors

ERROR: No design systems found
→ Run /workflow:ui-design:consolidate first

ERROR: jq not found
→ Install jq: brew install jq

ERROR: Agent task failed
→ Check agent output, retry phase

ERROR: Script permission denied
→ chmod +x ~/.claude/scripts/ui-instantiate-prototypes.sh

Recovery Strategies

• Partial failure: Check script logs for counts
• Missing templates: Regenerate Phase 4
• Invalid tokens: Validate design-tokens.json

Quality Checklist

• CSS uses var(--token-name) only
• No hardcoded colors/spacing
• Semantic HTML5 structure
• ARIA attributes present
• Mobile-first responsive
• Naming: {target}-style-{s}-layout-{l}
• compare.html works

Key Features

• Template-Based: S times faster generation
• Target Types: Pages and components
• Agent-Driven: Parallel task execution
• Token-Driven: No hardcoded values
• Production-Ready: Semantic, accessible, responsive
• Interactive Preview: Matrix comparison view

Integration

Input: design-tokens.json from /workflow:ui-design:consolidate Output: Prototypes for /workflow:ui-design:update Called by: /workflow:ui-design:explore-auto, /workflow:ui-design:imitate-auto