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

---
name: generate-v2
description: Generate UI prototypes using target-style-centric batch generation
usage: /workflow:ui-design:generate-v2 [--targets "<list>"] [--target-type "page|component"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
examples:
  - /workflow:ui-design:generate-v2 --session WFS-auth --targets "dashboard,settings"
  - /workflow:ui-design:generate-v2 --targets "home,pricing" --style-variants 2 --layout-variants 2
allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
---

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

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

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

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

## Phase 1: Setup & Validation

### Step 1: Resolve Base Path & Parse Configuration
```bash
# Determine working directory
bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect

# Get counts (defaults: style=auto, layout=3)
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"
```

### Step 2: Validate Inputs
```bash
# 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)
# Load design-space-analysis.json (optional, for style-aware generation)
```

**Output**: `base_path`, `style_variants`, `layout_variants`, `target_list[]`, `target_type`, `design_space_analysis` (optional)

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

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 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
```bash
bash(mkdir -p {base_path}/prototypes)
```

For each `target × style_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)

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

  ## 参考
  - 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" : ""}

  ## 生成
  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
     ${design_attributes ? `
     - DOM adaptation:
       * density='spacious' → flatter hierarchy
       * density='compact' → deeper nesting
       * visual_weight='heavy' → extra wrappers
       * visual_weight='minimal' → direct 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
     - Responsive: Mobile-first @media(breakpoints)
     ${design_attributes ? `
     - Token selection:
       * density → spacing scale
       * visual_weight → shadow strength
       * organic_vs_geometric → border-radius` : ""}

  ## 注意
  - ✅ Use token VALUES directly from design-tokens.json
  - ❌ NO var() references, NO external dependencies
  - Layouts structurally DISTINCT (different grids/regions)
  - Write files IMMEDIATELY (per layout, no accumulation)
  - CSS filename MUST match HTML <link href="...">
  - No text output, write to filesystem only
`
```

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

**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-v2.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: "Gather layout inspiration", status: "completed", activeForm: "Researching layouts"},
  {content: "Target-style generation (agent)", status: "completed", activeForm: "Generating prototypes"},
  {content: "Verify files", status: "completed", activeForm: "Validating output"},
  {content: "Generate previews", status: "completed", activeForm: "Creating preview files"}
]});
```

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

Configuration:
- Style Variants: {style_variants}
- Layout Variants: {layout_variants} (inspiration-based)
- Target Type: {target_type}
- Targets: {target_list}
- 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

Quality:
- Style-aware: {design_space_analysis ? 'HTML adapts to design_attributes' : 'Standard structure'}
- CSS: Self-contained (direct token values, no var())
- 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-*" | 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 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/_inspirations)

# Run preview script
bash(~/.claude/scripts/ui-generate-preview-v2.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: MCP search failed
→ Check network, retry

ERROR: Agent task failed
→ Check agent output, retry specific target×style

ERROR: Script permission denied
→ chmod +x ~/.claude/scripts/ui-generate-preview-v2.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

## 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
- [ ] 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

## Integration

**Input**: design-tokens.json, design-space-analysis.json (optional), targets
**Output**: S×L×T prototypes for `/workflow:ui-design:update`
**Called by**: `/workflow:ui-design:explore-auto-v2`, `/workflow:ui-design:imitate-auto`