catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

Refactor UI Generation Workflow: Optimize matrix generation process, enhance layout planning, and improve error handling. Consolidate steps for better performance and clarity, ensuring production-ready output with semantic HTML and responsive design. Update examples and documentation for clarity and usability.

Browse Source
This commit is contained in:
catlog22
2025-10-11 12:54:55 +08:00
parent 2fcd44e856
commit 980f554b27
4 changed files with 878 additions and 1844 deletions
Download Patch File Download Diff File Expand all files Collapse all files

553
.claude/commands/workflow/ui-design/consolidate.md
View File

@@ -13,209 +13,215 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(*)
# Design System Consolidation Command
## Overview
Consolidate user-selected style variants into **independent production-ready design systems**. This command serves as the **Style Refinement Phase**, transforming raw token proposals from `extract` into finalized, production-ready design tokens and style guides for the subsequent generation phase.
Consolidate style variants into independent production-ready design systems. Refines raw token proposals from `extract` into finalized design tokens and style guides.
## Core Philosophy
- **Style System Focus**: Exclusively handles design system consolidation
- **System Refinement, Not Generation**: Consumes proposed tokens from `extract` to create finalized design systems; does NOT generate UI prototypes or CSS stylesheets (that's generate's job)
- **Agent-Driven**: Uses ui-design-agent for multi-file generation efficiency
- **Separate Design Systems**: Generates N independent design systems (one per variant)
- **Token Refinement**: Refines `proposed_tokens` from each variant into complete, production-ready systems
- **Intelligent Synthesis**: Ensures completeness and consistency
- **Production-Ready**: Complete design system(s) with documentation
- **Matrix-Ready**: Provides style variants for style × layout matrix exploration in generate phase
**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: Path Resolution & Variant Loading
## Phase 1: Setup & Validation
### Step 1: Resolve Base Path & Load Style Cards
```bash
# Determine base path
IF --base-path: base_path = {provided_base_path}
ELSE IF --session: base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*")
ELSE: base_path = find_latest_path_matching(".workflow/.design/*")
# 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 1.1: Memory Check (Skip if Already Consolidated)
### Step 2: Memory Check (Skip if Already Done)
```bash
# Check if style-1/design-tokens.json exists in memory
IF exists("{base_path}/style-consolidation/style-1/design-tokens.json"):
REPORT: "✅ Design system consolidation already complete (found in memory)"
REPORT: " Skipping: Phase 2-6 (Variant Selection, Design Context Loading, Design System Synthesis, Agent Verification, Completion)"
EXIT 0
# Check if already consolidated
bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "exists")
```
### Phase 2: Variant Selection
**If exists**: Skip to completion message
### Step 3: Select Variants
```bash
# Determine how many variants to consolidate
IF --variants:
variants_count = {provided_count}
VALIDATE: 1 <= variants_count <= total_variants
ELSE:
variants_count = total_variants
# Determine variant count (default: all from style-cards.json)
bash(cat style-cards.json | grep -c "\"id\": \"variant-")
# Select first N variants
selected_variants = style_cards.style_cards[0:variants_count]
VERIFY: selected_variants.length > 0
REPORT: "📦 Generating {variants_count} independent design systems"
# Validate variant count
# Priority: --variants parameter → total_variants from style-cards.json
```
### Phase 3: Load Design Context (Optional)
**Output**: `variants_count`, `selected_variants[]`
### Step 4: Load Design Context (Optional)
```bash
# Load brainstorming context if available
design_context = ""
IF exists({base_path}/.brainstorming/synthesis-specification.md):
design_context = Read(synthesis-specification.md)
ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md):
design_context = Read(ui-designer/analysis.md)
# Load brainstorming context
bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it)
# Load design space analysis from extraction phase
design_space_analysis = {}
design_space_path = "{base_path}/style-extraction/design-space-analysis.json"
IF exists(design_space_path):
design_space_analysis = Read(design_space_path)
REPORT: "📊 Loaded design space analysis with {len(design_space_analysis.divergent_directions)} variant directions"
ELSE:
REPORT: "⚠️ No design space analysis found - will refine tokens from proposed_tokens only"
# Load design space analysis
bash(test -f {base_path}/style-extraction/design-space-analysis.json && cat it)
```
### Phase 4: Design System Synthesis (Agent Execution)
**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
REPORT: "🤖 Using agent for separate design system generation..."
bash(mkdir -p {base_path}/style-consolidation/style-{{1..{variants_count}}})
```
# Create output directories
Bash(mkdir -p "{base_path}/style-consolidation/style-{{1..{variants_count}}}")
### Step 2: Launch Agent Task
For all variants (1 to {variants_count}):
```javascript
Task(ui-design-agent): `
[DESIGN_TOKEN_GENERATION_TASK]
Generate {variants_count} independent design systems using philosophy-driven refinement
# Prepare agent task prompt with clear task identifier
agent_task_prompt = """
[DESIGN_TOKEN_GENERATION_TASK]
SESSION: {session_id} | MODE: Philosophy-driven refinement | BASE_PATH: {base_path}
CRITICAL: You MUST use Write() tool to create files. DO NOT return file contents as text.
CRITICAL PATH: Use loop index (N) for directories: style-1/, style-2/, ..., style-N/
## Task Summary
Generate {variants_count} independent design systems using philosophy-driven refinement and WRITE files directly (NO MCP calls).
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}}
}
## Context
SESSION: {session_id}
MODE: Separate design system generation with philosophy-driven refinement (NO MCP)
BASE_PATH: {base_path}
VARIANTS TO PROCESS: {variants_count}
## 参考
- 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)
## Variant Data
## 生成
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.)
CRITICAL PATH MAPPING:
- Variant 1 (id: {variant.id}) → Output directory: style-1/
- Variant 2 (id: {variant.id}) → Output directory: style-2/
- Variant N (id: {variant.id}) → Output directory: style-N/
2. {base_path}/style-consolidation/style-{N}/style-guide.md
- Expanded design philosophy
- Complete color system with accessibility notes
- Typography documentation
- Usage guidelines
Use loop index (1-based) for directory names, NOT variant.id.
## 注意
- ✅ 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
`
```
{FOR each variant IN selected_variants with index N (1-based):
---
VARIANT INDEX: {N} (use this for directory: style-{N}/)
Variant ID: {variant.id} (metadata only, DO NOT use in paths)
Name: {variant.name}
Description: {variant.description}
Design Philosophy: {variant.design_philosophy}
Proposed Tokens: {JSON.stringify(variant.proposed_tokens, null, 2)}
---
}
**Output**: Agent generates `variants_count × 2` files
{IF design_context: DESIGN CONTEXT (from brainstorming): {design_context}}
## Phase 3: Verify Output
{IF design_space_analysis:
## Design Space Analysis (for Philosophy-Driven Refinement)
{JSON.stringify(design_space_analysis, null, 2)}
### Step 1: Check Files Created
```bash
# Verify all design systems created
bash(ls {base_path}/style-consolidation/style-*/design-tokens.json | wc -l)
Note: Each variant has design_attributes and anti_keywords for token refinement.
Use philosophy_name and design_attributes to guide token generation WITHOUT external research.
}
# Validate structure
bash(cat {base_path}/style-consolidation/style-1/design-tokens.json | grep -q "colors" && echo "valid")
```
## Task
For EACH variant (1 to {variants_count}):
1. **Load variant's design philosophy and attributes** (from design_space_analysis)
2. **Refine design tokens** using philosophy-driven strategy (NO external research)
3. **Generate and WRITE 2 files** to the file system
### Step 2: Verify File Sizes
```bash
bash(ls -lh {base_path}/style-consolidation/style-1/)
```
## Step 1: Load Design Philosophy (No MCP Calls)
**Output**: `variants_count × 2` files verified
IF design_space_analysis is provided:
FOR EACH variant:
1. **Extract Design Direction**: Load philosophy_name, design_attributes, search_keywords, anti_keywords
2. **Use as Refinement Guide**: Apply philosophy and attributes to token generation
3. **Enforce Constraints**: Avoid characteristics listed in anti_keywords
4. **Maintain Divergence**: Ensure tokens differ from other variants based on attributes
## Completion
ELSE:
Refine tokens based solely on variant's proposed_tokens and design_philosophy from style-cards.json
### 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"}
]});
```
## Philosophy-Driven Refinement Strategy
### Output Message
```
✅ Design system consolidation complete!
**Core Principles**:
- Use variant's design_attributes as primary guide (color saturation, visual weight, formality, organic/geometric, innovation, density)
- Apply anti_keywords as explicit constraints during token selection
- Ensure WCAG AA accessibility using built-in AI knowledge (4.5:1 text, 3:1 UI)
- Preserve maximum contrast between variants from extraction phase
Configuration:
- Session: {session_id}
- Variants: {variants_count}
- Philosophy-driven refinement (zero MCP calls)
**Refinement Process** (Apply to each variant):
1. **Colors**: Generate palette based on saturation attribute
- "monochrome" → low chroma values (oklch L 0.00-0.02 H)
- "vibrant" → high chroma values (oklch L 0.20-0.30 H)
2. **Typography**: Select font families matching formality level
- "playful" → rounded, friendly fonts
- "luxury" → serif, elegant fonts
3. **Spacing**: Apply density attribute
- "spacious" → larger spacing scale (e.g., "4": "1.5rem")
- "compact" → smaller spacing scale (e.g., "4": "0.75rem")
4. **Shadows**: Match visual weight
- "minimal" → subtle shadows with low opacity
- "bold" → strong shadows with higher spread
5. **Border Radius**: Align with organic/geometric attribute
- "organic" → larger radius values (xl: "1.5rem")
- "brutalist" → minimal radius (xl: "0.125rem")
6. **Innovation**: Influence overall token adventurousness
- "timeless" → conservative, proven values
- "experimental" → unconventional token combinations
Generated Files:
{base_path}/style-consolidation/
├── style-1/ (design-tokens.json, style-guide.md)
├── style-2/ (same structure)
└── style-{variants_count}/ (same structure)
## Step 2: Refinement Rules (apply to each variant)
1. **Complete Token Coverage**: Ensure all categories present (colors, typography, spacing, etc.)
2. **Fill Gaps**: Generate missing tokens based on variant's philosophy and design_attributes
3. **Maintain Style Identity**: Preserve unique characteristics from proposed tokens
4. **Semantic Naming**: Use clear names (e.g., "brand-primary" not "color-1")
5. **Accessibility**: Validate WCAG AA contrast using built-in AI knowledge (4.5:1 text, 3:1 UI)
6. **OKLCH Format**: All colors use oklch(L C H / A) format
7. **Design Philosophy**: Expand variant's design philosophy based on its attributes
8. **Divergence Preservation**: Apply anti_keywords to prevent convergence with other variants
Next: /workflow:ui-design:generate --session {session_id} --style-variants {variants_count} --targets "dashboard,auth"
```
## Step 3: FILE WRITE OPERATIONS (CRITICAL)
## Simple Bash Commands
**EXECUTION MODEL**: For EACH variant (1 to {variants_count}):
1. Load design philosophy and attributes
2. Refine tokens using philosophy-driven strategy
3. **IMMEDIATELY Write() files - DO NOT accumulate, DO NOT return as text**
### Path Operations
```bash
# Find design directory
bash(find .workflow -type d -name "design-*" | head -1)
### Required Write Operations Per Variant
# Load style cards
bash(cat {base_path}/style-extraction/style-cards.json)
For variant with loop index {N} (e.g., 1st variant = N=1, 2nd variant = N=2), execute these Write() operations:
# 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
```
{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
#### Write Operation 1: Design Tokens
**Path**: `{base_path}/style-consolidation/style-{N}/design-tokens.json`
**Method**: `Write(path, JSON.stringify(tokens, null, 2))`
**Example**: For 1st variant → `{base_path}/style-consolidation/style-1/design-tokens.json`
**Content Structure**:
```json
{
"colors": {
@@ -233,229 +239,32 @@ For variant with loop index {N} (e.g., 1st variant = N=1, 2nd variant = N=2), ex
}
```
#### Write Operation 2: Style Guide
**Path**: `{base_path}/style-consolidation/style-{N}/style-guide.md`
**Method**: `Write(path, guide_markdown_content)`
**Example**: For 2nd variant → `{base_path}/style-consolidation/style-2/style-guide.md`
**Content Structure**:
```markdown
# Design System Style Guide - {variant.name}
## Design Philosophy
{Expanded variant philosophy}
## Color System
### Brand Colors, Surface Colors, Semantic Colors, Text Colors, Border Colors
{List all with usage and accessibility notes}
## Typography
### Font Families, Type Scale, Usage Examples
{Complete typography documentation}
## Spacing System, Component Guidelines
{Spacing patterns and component token examples}
## Accessibility
- All text meets WCAG AA (4.5:1 minimum)
- UI components meet WCAG AA (3:1 minimum)
- Focus indicators are clearly visible
```
### Execution Checklist (Per Variant)
For each variant from 1 to {variants_count} (use loop index N):
- [ ] Extract variant's philosophy, design_attributes, and anti_keywords
- [ ] Apply philosophy-driven refinement strategy to proposed_tokens
- [ ] Generate complete token set following refinement rules
- [ ] **EXECUTE**: `Write("{base_path}/style-consolidation/style-{N}/design-tokens.json", tokens_json)`
- Example: 1st variant → `style-1/design-tokens.json`
- [ ] **EXECUTE**: `Write("{base_path}/style-consolidation/style-{N}/style-guide.md", guide_content)`
- Example: 1st variant → `style-1/style-guide.md`
- [ ] Verify both files written successfully
### Verification After Each Write
```javascript
// Immediately after Write() for each file (use loop index N):
Bash(`ls -lh "{base_path}/style-consolidation/style-{N}/"`)
// Example: For 1st variant → ls -lh ".../style-1/"
// Confirm file exists and has reasonable size (>1KB)
## Expected Final Report
After completing all {variants_count} variants, report:
```
✅ Variant 1 ({variant_name}):
- design-tokens.json: 12.5 KB | {token_count} tokens
- style-guide.md: 8.3 KB
✅ Variant 2 ({variant_name}):
- design-tokens.json: 11.8 KB | {token_count} tokens
- style-guide.md: 7.9 KB
... (for all variants)
Summary: {variants_count} design systems generated with philosophy-driven refinement (zero MCP calls)
```
## KEY REMINDERS (CRITICAL)
**ALWAYS:**
- Use Write() tool for EVERY file - this is your PRIMARY responsibility
- Write files immediately after generating content for each variant
- Verify each Write() operation succeeds before proceeding
- Use loop index (N) for directory names: `{base_path}/style-consolidation/style-{N}/...`
- 1st variant → `style-1/`, 2nd variant → `style-2/`, etc.
- DO NOT use variant.id in paths (metadata only)
- Apply philosophy-driven refinement strategy for each variant
- Maintain variant divergence using design_attributes and anti_keywords
- Report completion with file paths and sizes
**NEVER:**
- Return file contents as text with labeled sections
- Accumulate all content and try to output at once
- Skip Write() operations and expect orchestrator to write files
- Use relative paths or modify provided paths
- Use external research or MCP calls (pure AI refinement only)
- Generate variant N+1 before completing variant N writes
"""
# Dispatch to ui-design-agent with task prompt
Task(subagent_type="ui-design-agent", description="Generate {variants_count} separate design systems", prompt=agent_task_prompt)
REPORT: "✅ Agent task dispatched for {variants_count} design systems"
```
### Phase 5: Verify Agent File Creation
```bash
REPORT: "📝 Verifying agent file creation for {variants_count} design systems..."
# Verify each variant's files were created by agent (use numeric index)
FOR N IN range(1, variants_count + 1):
tokens_path = "{base_path}/style-consolidation/style-{N}/design-tokens.json"
guide_path = "{base_path}/style-consolidation/style-{N}/style-guide.md"
# Verify files exist
VERIFY: exists(tokens_path), "Design tokens not created by agent for style-{N}"
VERIFY: exists(guide_path), "Style guide not created by agent for style-{N}"
# Optional: Validate JSON structure
TRY:
tokens = Read(tokens_path)
tokens_json = parse_json(tokens)
VALIDATE: tokens_json.colors exists, "Missing colors in design-tokens.json"
VALIDATE: tokens_json.typography exists, "Missing typography in design-tokens.json"
VALIDATE: tokens_json.spacing exists, "Missing spacing in design-tokens.json"
tokens_size = get_file_size(tokens_path)
guide_size = get_file_size(guide_path)
REPORT: " ✅ style-{N}/ verified ({tokens_size} KB tokens, {guide_size} KB guide)"
CATCH error:
ERROR: "Validation failed for style-{N}: {error}"
REPORT: " ⚠️ Files exist but validation failed - review agent output"
REPORT: "✅ All {variants_count} design systems verified"
```
**Output Structure**:
```
{base_path}/style-consolidation/
├── style-1/ (design-tokens.json, style-guide.md)
├── style-2/ (same structure)
└── style-N/ (same structure)
```
### Phase 6: Completion & Reporting
```javascript
TodoWrite({todos: [
{content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"},
{content: "Select variants for consolidation", status: "completed", activeForm: "Selecting variants"},
{content: "Load design context and space analysis", status: "completed", activeForm: "Loading context"},
{content: "Apply philosophy-driven refinement", status: "completed", activeForm: "Refining design tokens"},
{content: "Generate design systems via agent", status: "completed", activeForm: "Generating design systems"},
{content: "Process agent results and write files", status: "completed", activeForm: "Writing output files"}
]});
```
**Completion Message**:
```
✅ Design system consolidation complete for session: {session_id}
{IF design_space_analysis:
🎨 Philosophy-Driven Refinement:
- {variants_count} design systems generated from AI-analyzed philosophies
- Zero MCP calls (pure AI token refinement)
- Divergence preserved from extraction phase design_attributes
- Each variant maintains unique style identity via anti_keywords
}
Generated {variants_count} independent design systems:
{FOR each variant: - {variant.name} ({variant.id})}
📂 Output: {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" --layout-variants N
Note: When called from /workflow:ui-design:explore-auto, UI generation is triggered automatically.
Layout planning is now handled in the generate phase for each specific target.
```
## design-tokens.json Format
**Token structure** (all variants follow identical structure with different values):
```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": "...", "sm": "...", "base": "...", "lg": "...", "xl": "...", "2xl": "...", "3xl": "...", "4xl": "..."},
"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", ..., "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"}
}
```
**Requirements**: All colors in OKLCH format, complete token coverage, semantic naming
**Requirements**: OKLCH colors, complete coverage, semantic naming
## Error Handling
- **No style cards found**: Report error, suggest running `/workflow:ui-design:extract` first
- **Invalid variant count**: List available count, auto-select all if called from auto workflow
- **Parsing errors**: Retry with stricter format instructions
- **Validation warnings**: Report but continue (non-blocking)
- **Missing categories**: Claude will fill gaps based on design philosophy
### Common Errors
```
ERROR: No style cards found
→ Run /workflow:ui-design:extract first
ERROR: Invalid variant count
→ List available count, auto-select all
ERROR: Agent file creation failed
→ Check agent output, verify Write() operations
```
## Key Features
1. **Philosophy-Driven Refinement** - Pure AI token refinement based on design_space_analysis from extraction phase; Uses variant-specific philosophies and design_attributes as refinement rules; Preserves maximum contrast without external trend pollution; Zero MCP calls = faster execution + better divergence preservation
2. **Agent-Driven Architecture** - Uses ui-design-agent for multi-file generation; Processes N variants with philosophy-guided synthesis; Structured output with deterministic token generation; Agent applies design attributes directly to token values
3. **Separate Design Systems (Matrix-Ready)** - Generates N independent design systems (one per variant); Each variant maintains unique style identity from extraction phase; Provides style foundation for style × layout matrix exploration in generate phase
4. **Token Refinement with AI Guidance** - Reads `proposed_tokens` from style cards; Loads design_space_analysis for philosophy and attributes; Applies attributes to token generation (saturation → chroma, density → spacing, etc.); Refines tokens while maintaining variant divergence through anti_keywords
5. **Complete Design System Output** - design-tokens.json (CSS tokens per variant); style-guide.md (documentation per variant with philosophy explanation)
6. **Production-Ready Quality** - WCAG AA accessibility validation using built-in AI knowledge (4.5:1 text, 3:1 UI); OKLCH color format for perceptual uniformity; Semantic token naming; Complete token coverage
7. **Streamlined Workflow** - Sequential phases with clear responsibilities; Agent handles philosophy-driven token refinement and file generation; Reproducible with deterministic structure; Context-aware (integrates brainstorming and design space analysis); ~30-60s faster without MCP overhead
8. **Divergence Preservation** - Strictly follows design_space_analysis constraints from extraction; Applies anti_keywords to prevent variant convergence; Maintains maximum variant contrast through attribute-driven generation; No external research = pure philosophical consistency
- **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 Points
## Integration
- **Input**:
- `style-cards.json` from `/workflow:ui-design:extract` (with `proposed_tokens`)
- `design-space-analysis.json` from extraction phase (with philosophy and design_attributes)
- `--variants` parameter (default: all variants)
- **Output**: Style Systems: `style-consolidation/style-{N}/design-tokens.json` and `style-guide.md` for each variant (refined with philosophy-driven approach), where N is the variant index (1, 2, 3...)
- **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md`
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:explore-auto` workflow
- **Next Command**: `/workflow:ui-design:generate --style-variants N --targets "..." --layout-variants M` performs target-specific layout planning
**Input**: `style-cards.json` from `/workflow:ui-design:extract`
**Output**: `style-consolidation/style-{N}/` for each variant
**Next**: `/workflow:ui-design:generate --style-variants N --targets "..."`

532
.claude/commands/workflow/ui-design/extract.md
View File

@@ -14,423 +14,255 @@ 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** (raw, unrefined data for consolidation phase).
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.
## Core Philosophy
- **Claude-Native**: 100% Claude-driven analysis, no external tools
- **Single Output**: Only `style-cards.json` with embedded token proposals
- **Token Proposals, Not Final Systems**: Outputs raw token data proposals; does NOT create final CSS or separate design systems (that's consolidate's job)
- **Sequential Execution**: Generate multiple style variants in one pass
**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)
- **Reproducible**: Deterministic output structure
- **Maximum Contrast**: AI generates maximally divergent design directions
## Execution Protocol
### Phase 0: Parameter Detection & Validation
## Phase 0: Setup & Input Validation
### Step 1: Detect Input Mode & Base Path
```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"
# Priority: --images + --prompt → hybrid | --images → image | --prompt → text
# Determine base path (PRIORITY: --base-path > --session > standalone)
IF --base-path:
base_path = {provided_base_path}; session_mode = "integrated"
session_id = base_path matches ".workflow/WFS-*/design-*" ? extract_session_id(base_path) : "standalone"
ELSE:
run_id = "run-" + timestamp()
IF --session:
session_mode = "integrated"; session_id = {provided_session}
base_path = ".workflow/WFS-{session_id}/design-{run_id}/"
ELSE:
session_mode = "standalone"; base_path = ".workflow/.design/{run_id}/"
# Determine base path
bash(find .workflow -type d -name "design-*" | head -1) # Auto-detect
# OR use --base-path / --session parameters
# Set variant count
variants_count = --variants OR 1; VALIDATE: 1 <= variants_count <= 5
# Set variant count (default: 1)
# Priority: --variants parameter → default 1
# Validate: 1 <= variants_count <= 5
```
### Phase 1: Input Loading & Validation
### Step 2: Load Inputs
```bash
# Expand and validate inputs
IF input_mode IN ["image", "hybrid"]:
expanded_images = Glob({--images pattern}); VERIFY: expanded_images.length > 0
FOR each image: image_data[i] = Read({image_path})
# For image mode
bash(ls {images_pattern}) # Expand glob pattern
Read({image_path}) # Load each image
IF input_mode IN ["text", "hybrid"]:
VALIDATE: --prompt is non-empty; prompt_guidance = {--prompt value}
# For text mode
# Validate --prompt is non-empty
CREATE: {base_path}/style-extraction/
# Create output directory
bash(mkdir -p {base_path}/style-extraction/)
```
### Phase 0.1: Memory Check (Skip if Already Extracted)
### Step 3: Memory Check (Skip if Already Done)
```bash
# Check if output already exists in memory/cache
IF exists("{base_path}/style-extraction/style-cards.json"):
REPORT: "✅ Style extraction already complete (found in memory)"
REPORT: " Skipping: Phase 0.5-3 (Design Space Divergence, Variant-Specific Style Synthesis, Completion)"
EXIT 0
# Check if already extracted
bash(test -f {base_path}/style-extraction/style-cards.json && echo "exists")
```
### Phase 0.5: AI-Driven Design Space Divergence
**If exists**: Skip to completion message
**Output**: `input_mode`, `base_path`, `variants_count`, `loaded_images[]` or `prompt_guidance`
## Phase 1: Design Space Analysis (Explore Mode Only)
### Step 1: Determine Extraction Mode
```bash
# Determine extraction mode
extraction_mode = --mode OR "auto"
IF extraction_mode == "auto":
extraction_mode = (variants_count == 1) ? "imitate" : "explore"
REPORT: "🔍 Auto-detected mode: {extraction_mode} (variants_count={variants_count})"
# Branch: Skip or Execute divergence analysis
IF extraction_mode == "imitate":
REPORT: "🎯 IMITATE MODE: High-fidelity single style extraction"
REPORT: " → Skipping design space divergence analysis"
REPORT: " → Proceeding to Phase 2 for direct style synthesis"
design_space_analysis = null
# Skip to Phase 2
GOTO Phase 2
# ELSE: REQUIRED execution path for explore mode
# ⚠️ CRITICAL: The following steps (Step 1-3) MUST be executed when extraction_mode == "explore"
# Step 1: Load project context (explore mode only)
project_context = ""
IF exists({base_path}/.brainstorming/synthesis-specification.md):
project_context = Read(synthesis-specification.md)
ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md):
project_context = Read(ui-designer/analysis.md)
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "🎨 EXPLORE MODE: Analyzing design space (REQUIRED)"
REPORT: " → Generating {variants_count} maximally contrasting directions"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
# Step 2: AI-driven divergent direction generation (REQUIRED)
divergence_prompt = """
Analyze user requirements and generate {variants_count} MAXIMALLY CONTRASTING design directions.
USER INPUT:
{IF prompt_guidance: Prompt: "{prompt_guidance}"}
{IF project_context: Project Context Summary: {extract_key_points(project_context, max_lines=10)}}
{IF images: Reference Images: {image_count} images will be analyzed in next phase}
DESIGN ATTRIBUTE SPACE (maximize contrast):
- Color Saturation: [monochrome, muted, moderate, vibrant, hypersaturated]
- Visual Weight: [minimal, light, balanced, bold, heavy]
- Formality: [playful, casual, professional, formal, luxury]
- Organic vs Geometric: [organic/fluid, soft, balanced, geometric, brutalist]
- Innovation: [timeless, modern, contemporary, trendy, experimental]
- Density: [spacious, airy, balanced, compact, dense]
TASK:
1. Identify design space center point from user requirements
2. Generate {variants_count} directions that:
- Are MAXIMALLY DISTANT from each other in attribute space
- Each occupies a distinct region/quadrant of the design spectrum
- Together provide diverse aesthetic options
- Are contextually appropriate for project type
- Have clear, memorable philosophical differences
3. For each direction, generate:
- Specific search keywords for MCP research (3-5 keywords)
- Anti-keywords to avoid (2-3 keywords)
- Clear rationale explaining contrast with other variants
OUTPUT FORMAT: Valid JSON only, no markdown:
{"design_space_center": {attributes}, "divergent_directions": [
{"id": "variant-1", "philosophy_name": "Brief name 2-3 words",
"design_attributes": {attribute_scores}, "search_keywords": [...],
"anti_keywords": [...], "rationale": "..."}
], "contrast_verification": {"min_pairwise_distance": "0.75", "strategy": "..."}}
RULES: Output ONLY valid JSON, maximize inter-variant distance, ensure each variant
occupies distinct aesthetic region, avoid overlapping attributes
"""
# Execute AI analysis (REQUIRED in explore mode)
divergent_directions = parse_json(Claude_Native_Analysis(divergence_prompt))
REPORT: "✅ Generated {variants_count} contrasting design directions:"
FOR direction IN divergent_directions.divergent_directions:
REPORT: " - {direction.philosophy_name}: {direction.rationale}"
design_space_analysis = divergent_directions
# Step 3: Save design space analysis for consolidation phase (REQUIRED)
# ⚠️ CRITICAL: This file MUST be generated in explore mode for downstream consolidation
output_file_path = "{base_path}/style-extraction/design-space-analysis.json"
Write({file_path: output_file_path,
content: JSON.stringify(design_space_analysis, null, 2)})
REPORT: "💾 Saved design space analysis to design-space-analysis.json"
# Verification step (REQUIRED)
VERIFY: file_exists(output_file_path) == true
REPORT: "✅ Verified: design-space-analysis.json exists ({file_size(output_file_path)} bytes)"
# Auto-detect mode
# variants_count == 1 → imitate mode (skip this phase)
# variants_count > 1 → explore mode (execute this phase)
```
### Phase 2: Variant-Specific Style Synthesis & Direct File Write
**If imitate mode**: Skip to Phase 2
**Analysis Prompt Template**:
```
Generate {variants_count} design style proposals{IF extraction_mode == "explore": , each guided by its pre-analyzed design direction}.
INPUT MODE: {input_mode}
{IF input_mode IN ["image", "hybrid"]: VISUAL REFERENCES: {list of loaded images}}
{IF input_mode IN ["text", "hybrid"]: TEXT GUIDANCE: "{prompt_guidance}"}
{IF extraction_mode == "explore":
DESIGN SPACE ANALYSIS: {design_space_analysis summary}
VARIANT-SPECIFIC DESIGN DIRECTIONS:
{FOR each direction IN design_space_analysis.divergent_directions:
---
VARIANT: {direction.id} | PHILOSOPHY: {direction.philosophy_name}
DESIGN ATTRIBUTES: {direction.design_attributes}
SEARCH KEYWORDS: {direction.search_keywords}
ANTI-PATTERNS (avoid): {direction.anti_keywords}
RATIONALE: {direction.rationale}
---}
}
TASK: Generate {variants_count} design style variant{IF variants_count > 1: s} where {IF extraction_mode == "explore": EACH variant}:
{IF extraction_mode == "explore":
1. Strictly follows its pre-defined design philosophy and attributes
2. Maintains maximum contrast with other variants' attributes
3. Incorporates its design direction and avoids its anti-patterns
}
{IF extraction_mode == "imitate":
1. Provides high-fidelity replication of reference design
2. Focuses on accurate extraction of visual characteristics
}
4. Uses OKLCH color space for all color values
5. Includes complete, production-ready design token proposals
6. Applies WCAG AA accessibility guidelines (4.5:1 text, 3:1 UI)
{IF extraction_mode == "explore":
CRITICAL RULES FOR CONTRAST:
- Variant-1 should feel completely different from Variant-2/3
- Use each variant's specific attribute scores (e.g., "monochrome" vs "vibrant")
- Each variant should embody its unique design direction
- If Variant-1 is "minimal/geometric", Variant-2 must be "bold/organic" or similar contrast
}
OUTPUT FORMAT: JSON matching this structure:
{"extraction_metadata": {"session_id": "...", "input_mode": "...", "timestamp": "...", "variants_count": N},
"style_cards": [
{"id": "variant-1", "name": "Concise Style Name (2-3 words)", "description": "2-3 sentences",
"design_philosophy": "Core design 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_count} variants
]}
RULES: {IF extraction_mode == "explore": Each variant must strictly adhere to pre-defined attributes; maximize visual contrast;}
{IF extraction_mode == "imitate": Focus on high-fidelity replication;}
all colors in OKLCH format; complete token structures; semantic naming;
WCAG AA accessibility (4.5:1 text, 3:1 UI)
```
**Execution & File Write**:
### Step 2: Load Project Context (Explore Mode)
```bash
# Execute Claude Native Analysis (internal processing, no context output)
style_cards_json = Claude_Native_Analysis(synthesis_prompt)
# Write directly to file
Write({file_path: "{base_path}/style-extraction/style-cards.json", content: style_cards_json})
REPORT: "💾 Saved {variants_count} style variants to style-cards.json"
# Load brainstorming context if available
bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it)
```
### Phase 3: Completion
### 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, 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: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"},
{content: extraction_mode == "explore" ? "Analyze design space for maximum contrast" : "Skip design space analysis (imitate mode)", status: "completed", activeForm: extraction_mode == "explore" ? "Analyzing design space" : "Skipping analysis"},
{content: extraction_mode == "explore" ? `Generate ${variants_count} divergent design directions (REQUIRED)` : "Prepare for high-fidelity extraction", status: "completed", activeForm: extraction_mode == "explore" ? "Generating directions" : "Preparing extraction"},
{content: extraction_mode == "explore" ? `Write and verify design-space-analysis.json (REQUIRED)` : "Skip design space output", status: "completed", activeForm: extraction_mode == "explore" ? "Writing and verifying file" : "Skipping output"},
{content: `Generate and write ${variants_count} ${extraction_mode == "explore" ? "contrasting" : "high-fidelity"} style variant${variants_count > 1 ? "s" : ""} to file`, status: "completed", activeForm: "Generating and writing variants"}
{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"}
]});
```
**Completion Message**:
### Output Message
```
✅ Style extraction complete for session: {session_id}
✅ Style extraction complete!
Mode: {extraction_mode == "imitate" ? "🎯 IMITATE (high-fidelity)" : "🎨 EXPLORE (contrast analysis)"}
Input mode: {input_mode}
{IF image mode: Images analyzed: {count}}
{IF prompt mode: Prompt: "{truncated_prompt}"}
Configuration:
- Session: {session_id}
- Mode: {extraction_mode} (imitate/explore)
- Input: {input_mode} (image/text/hybrid)
- Variants: {variants_count}
{IF extraction_mode == "explore":
🎨 Design Space Analysis:
- Generated {variants_count} MAXIMALLY CONTRASTING design directions
- Min pairwise contrast distance: {design_space_analysis.contrast_verification.min_pairwise_distance}
- Strategy: {design_space_analysis.contrast_verification.strategy}
}
{IF extraction_mode == "imitate":
🎯 Imitation Mode:
- High-fidelity single style extraction
- Design space divergence skipped for faster execution
{IF explore mode:
Design Space Analysis:
- {variants_count} maximally contrasting design directions
- Min contrast distance: {design_space_analysis.contrast_verification.min_pairwise_distance}
}
Generated {variants_count} style variant{variants_count > 1 ? "s" : ""}:
{FOR each card: - {card.name} ({card.id}) - {card.design_philosophy}}
Generated Variants:
{FOR each card: - {card.name} - {card.design_philosophy}}
📂 Outputs:
Output Files:
- {base_path}/style-extraction/style-cards.json
{IF extraction_mode == "explore": - {base_path}/style-extraction/design-space-analysis.json}
{IF explore mode: - {base_path}/style-extraction/design-space-analysis.json}
Next: /workflow:ui-design:consolidate --session {session_id} --variants {variants_count} [--layout-variants <count>]
Next: /workflow:ui-design:consolidate --session {session_id} --variants {variants_count}
```
Note: When called from /workflow:ui-design:{extraction_mode == "imitate" ? "imitate" : "explore"}-auto, consolidation is triggered automatically.
## 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
```
.workflow/WFS-{session}/design-{run_id}/style-extraction/
{base_path}/style-extraction/
├── style-cards.json # Complete style variants with token proposals
└── design-space-analysis.json # Design directions (explore mode only)
OR (standalone mode):
.workflow/.design/{run_id}/style-extraction/
├── style-cards.json
└── design-space-analysis.json # Only in explore mode
```
### style-cards.json Format
**Schema Structure**:
## style-cards.json Format
```json
{
"extraction_metadata": {"session_id": "string", "input_mode": "image|text|hybrid",
"timestamp": "ISO 8601", "variants_count": "number"},
"extraction_metadata": {"session_id": "...", "input_mode": "image|text|hybrid", "timestamp": "...", "variants_count": N},
"style_cards": [
{
"id": "variant-{n}", "name": "Concise Style Name (2-3 words)",
"description": "2-3 sentence description of visual language and UX",
"design_philosophy": "Core design principles for this variant",
"preview": {"primary": "oklch(...)", "background": "oklch(...)",
"font_heading": "Font family, fallbacks", "border_radius": "value"},
"id": "variant-1", "name": "Style Name", "description": "...",
"design_philosophy": "Core principles",
"preview": {"primary": "oklch(...)", "background": "oklch(...)", "font_heading": "...", "border_radius": "..."},
"proposed_tokens": {
"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": "...", "sm": "...", "base": "...", "lg": "...", "xl": "...", "2xl": "...", "3xl": "...", "4xl": "..."},
"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"}
"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 structure for variants_count total (variant-1, variant-2, ..., variant-n)
// Repeat for all variants
]
}
```
**Key Structural Requirements**:
- Each variant MUST have complete, independent token proposals (all categories present)
- All colors MUST use OKLCH format: `oklch(L C H / A)`
- Token keys MUST match exactly across all variants for consistency
- Variants differ in VALUES, not structure
- Production-ready: no placeholders or incomplete sections
**Requirements**: All colors in OKLCH format, complete token proposals, semantic naming
## 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 in `.workflow/.scratchpad/`
- **Invalid variant count**: Clamp to 1-5 range and warn user
### 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
1. **🚀 AI-Driven Design Space Exploration** 🆕
- Phase 0.5: AI analyzes requirements and generates MAXIMALLY CONTRASTING design directions
- Uses 6-dimensional design attribute space (color saturation, visual weight, formality, organic/geometric, innovation, density)
- Ensures each variant occupies a distinct region of the design spectrum
- Generates search keywords and anti-patterns for each variant
- Provides contrast verification with minimum pairwise distance metrics
- **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
2. **🎯 Variant-Specific Design Directions** 🆕
- AI generates search keywords and anti-patterns for each variant
- Each variant has distinct design philosophy (e.g., "minimal brutalist" vs "bold vibrant")
- Philosophy-specific keywords guide synthesis
- Design space analysis saved for consolidation phase
- Trend research deferred to consolidation for better integration
## Integration
3. **🔒 Maximum Contrast Guarantee**
- AI-driven divergence ensures variants are maximally distant in attribute space
- Each variant has distinct: philosophy, color saturation, visual weight, formality, etc.
- Explicit anti-patterns prevent variants from borrowing each other's characteristics
- Contrast verification built into design space analysis
4. **100% Claude-Native Analysis**
- No external tools (gemini-wrapper, codex, or MCP) - pure Claude
- Single-pass comprehensive analysis guided by design space analysis
- Fast, deterministic style synthesis without external dependencies
5. **Streamlined Output**
- Single file (`style-cards.json`) vs. multiple scattered files
- Eliminates `semantic_style_analysis.json`, `design-tokens.json`, `tailwind-tokens.js` clutter
- Each variant contains complete token proposals embedded
6. **Flexible Input Modes**
- Image-only: Analyze visual references through each variant's philosophical lens
- Text-only: Generate from descriptions with maximum divergence
- Hybrid: Text guides image analysis while maintaining variant independence
- All modes enhanced with AI-driven design space analysis
7. **Context-Aware & Dynamic**
- Extracts design keywords from user prompts (e.g., "minimalist", "Linear.app")
- Considers project type from brainstorming artifacts
- Dynamically generates design directions based on project context
- No hardcoded design philosophies - fully adaptive
8. **Production-Ready Token Proposals**
- Complete design system proposals per variant
- OKLCH color format for perceptual uniformity and accessibility
- Semantic naming conventions
- WCAG AA accessibility considerations built-in
- Variant-specific token sets (not generic)
9. **Workflow Integration**
- Integrated mode: Works within existing workflow sessions
- Standalone mode: Auto-creates session in scratchpad
- Context-aware: Can reference synthesis-specification.md or ui-designer/analysis.md
- Contrast metrics included in completion report
## Integration Points
- **Input**: Reference images (PNG, JPG, WebP) via glob patterns, or text prompts
- **Output**: `style-cards.json` for `/workflow:ui-design:consolidate`
- **Context**: Optional brainstorming artifacts (`synthesis-specification.md`, `ui-designer/analysis.md`)
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
- **Next Step**: `/workflow:ui-design:consolidate --session {session_id} --variants {count} [--layout-variants <count>]` (add `--keep-separate` for matrix mode)
**Input**: Reference images or text prompts
**Output**: `style-cards.json` for `/workflow:ui-design:consolidate`
**Next**: `/workflow:ui-design:consolidate --session {session_id} --variants {count}`

831
.claude/commands/workflow/ui-design/generate-v2.md
View File

@@ -3,674 +3,319 @@ 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" --style-variants 3 --layout-variants 3
- /workflow:ui-design:generate-v2 --base-path ".workflow/WFS-auth/design-run-20250109-143022" --targets "home,pricing"
- /workflow:ui-design:generate-v2 --targets "navbar,hero,card" --target-type "component" --style-variants 2 --layout-variants 2
- /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(*)
---
# UI Generation Command (Target-Style-Centric Architecture)
**Executor**: → @ui-design-agent
**Parallel Generation**: Phase 2 → @ui-design-agent (T×S tasks, each handling L layouts)
# Generate UI Prototypes V2 (/workflow:ui-design:generate-v2)
## Overview
Generate production-ready UI prototypes (HTML/CSS) using **target-style-centric batch generation**. Each agent handles all layout variants for one target × one style combination, ensuring component isolation and focused generation.
Generate matrix of UI prototypes (`style × layout × targets`) using **target-style-centric batch generation**. Each agent handles all layouts for one target × style combination.
## Core Philosophy
- **Target-Style-Centric**: Each of T×S agents generates L layouts for one target × one style
- **Component Isolation**: Tasks completely independent, preventing cross-component interference
- **Style-Aware Structure**: HTML DOM adapts based on design_attributes (density, visual_weight, etc.)
- **Performance Optimized**: T×S agent calls with highly focused scope per agent
- **Layout Inspiration**: Simple text-based research replaces complex JSON planning
- **Self-Contained CSS**: Agent reads design-tokens.json and creates independent CSS (no token.css reference)
- **Production-Ready**: Semantic HTML5, ARIA attributes, responsive design
**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)
## Execution Protocol
**Supports**: Pages (full layouts) and components (isolated elements)
### Phase 1: Path Resolution & Context Loading
## Phase 1: Setup & Validation
### Step 1: Resolve Base Path & Parse Configuration
```bash
# 1. Determine base path
IF --base-path: base_path = {provided_base_path}
ELSE IF --session: base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*")
ELSE: base_path = find_latest_path_matching(".workflow/.design/*")
# Determine working directory
bash(find .workflow -type d -name "design-*" | head -1) # Auto-detect
# 2. Determine style variant count and layout variant count
style_variants = --style-variants OR auto_detect_from_consolidation()
layout_variants = --layout-variants OR 3
VALIDATE: 1 <= style_variants <= 5
VALIDATE: 1 <= layout_variants <= 5
# Get counts (defaults: style=auto, layout=3)
bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
# Validate against actual style directories
actual_style_count = count_directories({base_path}/style-consolidation/style-*)
IF actual_style_count == 0:
ERROR: "No style directories found"; SUGGEST: "Run /workflow:ui-design:consolidate first"; EXIT 1
IF style_variants > actual_style_count:
WARN: "⚠️ Requested {style_variants}, but only {actual_style_count} exist"
REPORT: " Available styles: {list_directories}"; style_variants = actual_style_count
REPORT: "✅ Validated style variants: {style_variants}"
# 3. Enhanced target list parsing with type detection
target_list = []; target_type = "page" # Default
# Priority 1: Unified --targets parameter
IF --targets:
raw_targets = {--targets value}
target_list = split_and_clean(raw_targets, delimiters=[",", ";", "、"])
target_list = [t.strip().lower().replace(" ", "-") for t in target_list if t.strip()]
target_type = --target-type provided ? {--target-type} : detect_target_type(target_list)
REPORT: "🎯 Using provided targets ({target_type}): {', '.join(target_list)}"
# Priority 2: Legacy --pages parameter
ELSE IF --pages:
raw_targets = {--pages value}
target_list = split_and_clean(raw_targets, delimiters=[",", ";", "、"])
target_list = [t.strip().lower().replace(" ", "-") for t in target_list if t.strip()]
target_type = "page"
REPORT: "📋 Using provided pages (legacy): {', '.join(target_list)}"
# Priority 3: Extract from synthesis-specification.md
ELSE IF --session:
synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
target_list = extract_targets_from_synthesis(synthesis_spec); target_type = "page"
REPORT: "📋 Extracted from synthesis: {', '.join(target_list)}"
# Priority 4: Detect from existing prototypes or default
ELSE:
target_list = detect_from_prototypes({base_path}/prototypes/) OR ["home"]; target_type = "page"
REPORT: "📋 Detected/default targets: {', '.join(target_list)}"
# 4. Validate target names
validated_targets = [t for t in target_list if regex_match(t, r"^[a-z0-9][a-z0-9_-]*$")]
invalid_targets = [t for t in target_list if t not in validated_targets]
IF invalid_targets: REPORT: "⚠️ Skipped invalid target names: {', '.join(invalid_targets)}"
VALIDATE: validated_targets not empty, "No valid targets found"
target_list = validated_targets
STORE: target_list, target_type
# 5. Verify design systems exist
FOR style_id IN range(1, style_variants + 1):
VERIFY: exists({base_path}/style-consolidation/style-{style_id}/design-tokens.json)
# 6. Load design space analysis (for style-aware generation)
design_space_path = "{base_path}/style-extraction/design-space-analysis.json"
IF exists(design_space_path):
design_space_analysis = Read(design_space_path)
REPORT: "📊 Loaded design space analysis with style attributes"
ELSE:
WARN: "⚠️ No design space analysis found - will use basic style generation"
design_space_analysis = null
# 7. Load requirements (if integrated mode)
IF --session:
synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
ELSE:
synthesis_spec = null
# Parse targets (Priority: --targets → --pages → synthesis-specification.md → default ["home"])
# Target type: "page" (default) or "component"
```
### Phase 1.2: Token源智能检测
### Step 2: Validate Inputs
```bash
REPORT: "🔍 Phase 1.2: Detecting token sources for {style_variants} style(s)..."
# Check design systems exist
bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")
token_sources = {} # {style_id: {path: str, quality: str, source: str}}
consolidated_count = 0
proposed_count = 0
FOR style_id IN range(1, style_variants + 1):
# 优先级1：Consolidated tokens（完整refinement from consolidate command）
consolidated_path = "{base_path}/style-consolidation/style-{style_id}/design-tokens.json"
IF exists(consolidated_path):
token_sources[style_id] = {
"path": consolidated_path,
"quality": "consolidated",
"source": "consolidate command"
}
consolidated_count += 1
REPORT: " ✓ Style-{style_id}: Using consolidated tokens (production-ready)"
CONTINUE
# 优先级2：Proposed tokens from style-cards.json（fast-track from extract command）
style_cards_path = "{base_path}/style-extraction/style-cards.json"
IF exists(style_cards_path):
# 读取style-cards.json
style_cards_data = Read(style_cards_path)
# 验证variant index有效
IF style_id <= len(style_cards_data.style_cards):
variant_index = style_id - 1
variant = style_cards_data.style_cards[variant_index]
proposed_tokens = variant.proposed_tokens
# 创建临时consolidation目录（兼容现有逻辑）
temp_consolidation_dir = "{base_path}/style-consolidation/style-{style_id}"
Bash(mkdir -p "{temp_consolidation_dir}")
# 写入proposed tokens（Fast Token Adaptation）
temp_tokens_path = "{temp_consolidation_dir}/design-tokens.json"
Write(temp_tokens_path, JSON.stringify(proposed_tokens, null, 2))
# 创建简化style guide（可选but recommended）
simple_guide_content = f"""# Design System: {variant.name}
## Design Philosophy
{variant.design_philosophy}
## Description
{variant.description}
## Design Tokens
Complete token specification in `design-tokens.json`.
**Note**: Using proposed tokens from extraction phase (fast-track mode).
For production-ready refinement with philosophy-driven token generation, run `/workflow:ui-design:consolidate` first.
## 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"}
- Border Radius: {variant.preview.border_radius if variant.preview else "N/A"}
"""
Write("{temp_consolidation_dir}/style-guide.md", simple_guide_content)
token_sources[style_id] = {
"path": temp_tokens_path,
"quality": "proposed",
"source": "extract command (fast adaptation)"
}
proposed_count += 1
REPORT: " ✓ Style-{style_id}: Using proposed tokens (fast-track)"
REPORT: " Source: {variant.name} from style-cards.json"
WARN: " ⚠️ Tokens not refined - for production quality, run consolidate first"
CONTINUE
ELSE:
ERROR: "style-cards.json exists but does not contain variant {style_id}"
ERROR: " style-cards.json has {len(style_cards_data.style_cards)} variants, but requested style-{style_id}"
SUGGEST: " Reduce --style-variants to {len(style_cards_data.style_cards)} or run extract with more variants"
EXIT 1
# 优先级3：错误处理（无可用token源）
ERROR: "No token source found for style-{style_id}"
ERROR: " Expected either:"
ERROR: " 1. {consolidated_path} (from /workflow:ui-design:consolidate)"
ERROR: " 2. {style_cards_path} (from /workflow:ui-design:extract)"
ERROR: ""
SUGGEST: "Run one of the following commands first:"
SUGGEST: " - /workflow:ui-design:extract --base-path \"{base_path}\" --images \"refs/*.png\" --variants {style_variants}"
SUGGEST: " - /workflow:ui-design:consolidate --base-path \"{base_path}\" --variants {style_variants}"
EXIT 1
# 汇总报告Token sources
REPORT: ""
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "📊 Token Source Summary:"
REPORT: " Total style variants: {style_variants}"
REPORT: " Consolidated (production-ready): {consolidated_count}/{style_variants}"
REPORT: " Proposed (fast-track): {proposed_count}/{style_variants}"
IF proposed_count > 0:
REPORT: ""
REPORT: "💡 Production Quality Tip:"
REPORT: " Fast-track mode is active for {proposed_count} style(s) using proposed tokens."
REPORT: " For production-ready quality with philosophy-driven refinement:"
REPORT: " /workflow:ui-design:consolidate --base-path \"{base_path}\" --variants {style_variants}"
REPORT: ""
REPORT: " Benefits of consolidate:"
REPORT: " • Philosophy-driven token refinement"
REPORT: " • WCAG AA accessibility validation"
REPORT: " • Complete design system documentation"
REPORT: " • Token gap filling and consistency checks"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
# Store token_sources for use in Phase 2
STORE: token_sources, consolidated_count, proposed_count
# Validate target names (lowercase, alphanumeric, hyphens only)
# Load design-space-analysis.json (optional, for style-aware generation)
```
### Phase 1.5: Target Layout Inspiration
**Output**: `base_path`, `style_variants`, `layout_variants`, `target_list[]`, `target_type`, `design_space_analysis` (optional)
### Step 3: Detect Token Sources
```bash
REPORT: "💡 Gathering layout inspiration for {len(target_list)} targets..."
# 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)
CREATE: {base_path}/prototypes/_inspirations/
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")
# For each target, gather layout inspiration via MCP search
FOR target IN target_list:
REPORT: " Researching '{target}' ({target_type}) layout patterns..."
# MCP search for layout patterns
search_query = f"common {target} {target_type} layout patterns variations best practices"
search_results = mcp__exa__web_search_exa(
query=search_query,
numResults=5
)
# Extract key layout patterns from search results
inspiration_content = f"""Layout Inspiration for '{target}' ({target_type})
Generated: {current_timestamp()}
Search Query: {search_query}
## Layout Patterns Identified
From web research, {layout_variants} distinct layout approaches:
Layout 1: [First structural pattern identified from search]
- Key characteristics: ...
- Structure approach: ...
Layout 2: [Second structural pattern]
- Key characteristics: ...
- Structure approach: ...
Layout 3: [Third structural pattern]
- Key characteristics: ...
- Structure approach: ...
## Reference Links
{format_search_results_urls(search_results)}
## Implementation Notes
- Each layout should be STRUCTURALLY DIFFERENT (not just CSS variations)
- Consider {target_type}-specific patterns (navigation, content areas, interactions)
- Adapt structure based on design_attributes in Phase 2
"""
# Write simple inspiration file
inspiration_file = f"{base_path}/prototypes/_inspirations/{target}-layout-ideas.txt"
Write(inspiration_file, inspiration_content)
REPORT: f" ✓ Created: {target}-layout-ideas.txt"
REPORT: f"✅ Phase 1.5 complete: Gathered inspiration for {len(target_list)} targets"
# 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)
```
### Phase 2: Target-Style-Centric Batch Generation
**Strategy**: T×S target-style-centric agents, each generating L layouts for one target × one style.
**Performance**: T×S agent calls with component isolation
**Output**: `token_sources{}`, `consolidated_count`, `proposed_count`
### Step 4: Gather Layout Inspiration
```bash
REPORT: "🎨 Phase 2: Launching {len(target_list)}×{style_variants}={len(target_list) * style_variants} target-style agents..."
REPORT: " Each agent generates {layout_variants} layouts for one component"
bash(mkdir -p {base_path}/prototypes/_inspirations)
CREATE: {base_path}/prototypes/
# For each target: Research via MCP
# mcp__exa__web_search_exa(query="{target} {target_type} layout patterns", numResults=5)
# Launch ONE agent task PER TARGET × STYLE combination (parallel execution)
FOR target IN target_list:
# Load layout inspiration for this target
inspiration_path = f"{base_path}/prototypes/_inspirations/{target}-layout-ideas.txt"
FOR style_id IN range(1, style_variants + 1):
# Load style-specific context
style_tokens_path = f"{base_path}/style-consolidation/style-{style_id}/design-tokens.json"
style_guide_path = f"{base_path}/style-consolidation/style-{style_id}/style-guide.md"
# Extract design attributes for this style (if available)
IF design_space_analysis AND style_id <= len(design_space_analysis.divergent_directions):
design_attributes = design_space_analysis.divergent_directions[style_id - 1]
philosophy_name = design_attributes.philosophy_name
attributes_summary = JSON.stringify({
density: design_attributes.design_attributes.density,
visual_weight: design_attributes.design_attributes.visual_weight,
formality: design_attributes.design_attributes.formality,
organic_vs_geometric: design_attributes.design_attributes.organic_vs_geometric,
innovation: design_attributes.design_attributes.innovation
})
ELSE:
design_attributes = null
philosophy_name = f"Style {style_id}"
attributes_summary = "No design attributes available"
Task(ui-design-agent): """
[TARGET_STYLE_UI_GENERATION]
## 🎯 Mission
Generate {layout_variants} layout variants for: {target} × Style-{style_id} ({philosophy_name})
Output: {layout_variants × 2} files ({layout_variants} HTML + {layout_variants} CSS)
## 🎨 Style Context
PHILOSOPHY: {philosophy_name}
{IF design_attributes:
DESIGN_ATTRIBUTES: {attributes_summary}
Key impacts:
- density → DOM nesting depth, whitespace scale
- visual_weight → wrapper layers, border/shadow strength
- formality → semantic structure choices
- organic_vs_geometric → alignment, edge treatment
- innovation → layout adventurousness
}
## 📂 Input Resources
**Design System**:
- Design Tokens (JSON): {style_tokens_path}
- Style Guide: {style_guide_path}
**Layout Inspiration**: {inspiration_path}
Contains {layout_variants} distinct structural patterns
**Target**: {target} ({target_type})
## 🔄 Generation Steps (for each layout 1..{layout_variants})
**1. Read Inspiration**
- Load: {inspiration_path}
- Apply layout N pattern
**2. Read Design Tokens**
- Load: {style_tokens_path}
- Parse JSON structure and extract all design token values
- Understand token categories: colors, typography, spacing, shadows, borders, etc.
**3. Generate HTML Structure**
- Complete HTML5 document (<!DOCTYPE>, <html>, <head>, <body>)
- Semantic elements: <header>, <nav>, <main>, <section>, <article>, <footer>
- ARIA attributes: aria-label, role, aria-labelledby
- Responsive meta: <meta name="viewport" content="width=device-width, initial-scale=1">
- Include CSS reference: <link rel="stylesheet" href="{target}-style-{style_id}-layout-N.css">
- Example: For dashboard-style-1-layout-2.html, use <link rel="stylesheet" href="dashboard-style-1-layout-2.css">
{IF design_attributes:
**⚠️ Adapt DOM based on design_attributes:**
- density='spacious' → Flatter hierarchy
Example: <main><section class="card"></section></main>
- density='compact' → Deeper nesting
Example: <main><div class="grid"><div class="card-wrapper"><section></section></div></div></main>
- visual_weight='heavy' → Extra wrapper divs for layered effects
Example: <div class="border-container"><div class="content-wrapper">...</div></div>
- visual_weight='minimal' → Direct structure, minimal wrappers
Example: <section class="card">...</section>
- organic_vs_geometric → Affects alignment patterns and edge structure
}
**4. Generate Self-Contained CSS**
⚠️ Use design token values DIRECTLY from step 2 - create complete, independent CSS
**Required Token Usage** (from design-tokens.json):
- Colors: Use color values for backgrounds, text, borders
- Typography: Use font-family, font-size, font-weight, line-height values
- Spacing: Use spacing scale for margins, padding, gaps
- Borders: Use border-radius, border-width values
- Shadows: Use box-shadow values
- Breakpoints: Use breakpoint values for @media queries
{IF design_attributes:
**Apply design_attributes to token selection:**
- density='spacious' → Select larger spacing tokens
- density='compact' → Select smaller spacing tokens
- visual_weight='heavy' → Use stronger shadows, add borders
- visual_weight='minimal' → Use subtle/no shadows
- formality → Affects typography choices and structure
- organic_vs_geometric → Affects border-radius and alignment
}
**CSS Structure**:
- Complete styling: colors, typography, layout, spacing, effects
- Responsive design: Mobile-first with breakpoint-based @media
- Self-contained: No external dependencies or var() references
**5. Write Files IMMEDIATELY**
- Output paths:
- HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-N.html
- CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-N.css
- Write after generating each layout (do NOT accumulate)
- Do NOT return content as text
## ✅ Success Criteria
- [ ] Generated exactly {layout_variants × 2} files
- [ ] All HTML includes correct CSS file reference (matching filename pattern)
- [ ] All CSS uses design token values directly (self-contained, no var() references)
- [ ] CSS fully embodies the style's design tokens (colors, typography, spacing, effects)
- [ ] {IF design_attributes: 'HTML structure adapts to design_attributes' ELSE: 'HTML follows layout inspiration'}
- [ ] Layouts are structurally distinct (different grids/regions, not just CSS tweaks)
- [ ] Files written to filesystem (not returned as text)
## 📋 Completion
Report: "✅ {target} × Style-{style_id} ({philosophy_name}): {layout_variants × 2} files created"
"""
REPORT: "⏳ Phase 2: Waiting for {len(target_list) * style_variants} target-style agents to complete..."
REPORT: " Expected total files: {style_variants × layout_variants × len(target_list) × 2}"
# Write simple inspiration file
Write({base_path}/prototypes/_inspirations/{target}-layout-ideas.txt, inspiration_content)
```
### Phase 2.5: Verify Agent File Creation
**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
REPORT: "📝 Phase 2.5: Verifying target-style generation..."
total_expected = style_variants × layout_variants × len(target_list) × 2
total_found = 0
FOR target IN target_list:
FOR style_id IN range(1, style_variants + 1):
agent_files_found = 0
FOR layout_id IN range(1, layout_variants + 1):
html_file = f"{target}-style-{style_id}-layout-{layout_id}.html"
css_file = f"{target}-style-{style_id}-layout-{layout_id}.css"
html_path = f"{base_path}/prototypes/{html_file}"
css_path = f"{base_path}/prototypes/{css_file}"
# Verify files exist
IF exists(html_path) AND exists(css_path):
# Validate content
html_content = Read(html_path)
css_content = Read(css_path)
# Basic validation
VALIDATE: "<!DOCTYPE html>" in html_content, f"Invalid HTML: {html_file}"
VALIDATE: f'href="{css_file}"' in html_content, f"Missing or incorrect CSS reference in: {html_file}"
VALIDATE: len(css_content) > 100, f"CSS file too small (likely incomplete): {css_file}"
html_size = get_file_size(html_path)
css_size = get_file_size(css_path)
agent_files_found += 2
total_found += 2
REPORT: f" ✓ {html_file} ({html_size} KB) + {css_file} ({css_size} KB)"
ELSE:
ERROR: f" ✗ Missing files: {target}-style-{style_id}-layout-{layout_id}.*"
REPORT: f" {target} × style-{style_id}: {agent_files_found}/{layout_variants * 2} files verified"
IF total_found == total_expected:
REPORT: f"✅ Phase 2.5 complete: Verified all {total_expected} files"
ELSE:
ERROR: f"⚠️ Only {total_found}/{total_expected} files found - some agents may have failed"
bash(mkdir -p {base_path}/prototypes)
```
### Phase 3: Generate Preview Files
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)
```bash
REPORT: "🌐 Phase 3: Generating preview files..."
TARGET: {target} | TYPE: {target_type} | STYLE: {style_id}/{style_variants}
BASE_PATH: {base_path}
${design_attributes ? "DESIGN_ATTRIBUTES: " + JSON.stringify(design_attributes) : ""}
prototypes_dir = f"{base_path}/prototypes"
## 参考
- 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" : ""}
# Template-based preview generation script
# - Uses: ~/.claude/workflows/_template-compare-matrix.html
# - Auto-detects: S, L, T from file patterns
# - Generates: compare.html, index.html, PREVIEW.md
Bash(~/.claude/scripts/ui-generate-preview-v2.sh "{prototypes_dir}")
## 生成
For EACH layout (1 to {layout_variants}):
# Verify preview files generated
preview_files = [
f"{base_path}/prototypes/compare.html",
f"{base_path}/prototypes/index.html",
f"{base_path}/prototypes/PREVIEW.md"
]
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` : ""}
all_present = True
FOR file_path IN preview_files:
IF exists(file_path):
REPORT: f" ✓ Generated: {basename(file_path)}"
ELSE:
WARN: f" ✗ Missing: {basename(file_path)}"
all_present = False
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` : ""}
IF all_present:
REPORT: "✅ Phase 3 complete: All preview files generated"
ELSE:
WARN: "⚠️ Some preview files missing - script may need attention"
## 注意
- ✅ 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
`
```
### Phase 4: Completion
### 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: "Resolve paths and load design systems", status: "completed", activeForm: "Loading design systems"},
{content: `Gather layout inspiration for ${target_list.length} targets`, status: "completed", activeForm: "Gathering inspiration"},
{content: `Launch ${target_list.length}×${style_variants}=${target_list.length * style_variants} target-style agents (each handling ${layout_variants} layouts)`, status: "completed", activeForm: "Running target-style generation"},
{content: `Verify ${style_variants * layout_variants * target_list.length * 2} generated files`, status: "completed", activeForm: "Verifying files"},
{content: "Generate preview files (compare.html, index.html)", status: "completed", activeForm: "Generating previews"}
{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"}
]});
```
**Completion Message**:
### Output Message
```
✅ Target-Style-Centric UI Generation Complete!
Architecture: Target-Style-Centric Batch Generation
✅ Target-Style-Centric UI generation complete!
Configuration:
- Style Variants: {style_variants}
- Layout Variants: {layout_variants} (inspiration-based)
- Target Type: {target_type_icon} {target_type}
- Target Type: {target_type}
- Targets: {target_list}
- Total Prototypes: {style_variants * layout_variants * len(target_list)}
- Total Prototypes: {S × L × T}
Agent Execution:
✅ Target-style agents: T×S = {len(target_list)}×{style_variants} = {len(target_list) * style_variants} agents
✅ Each agent handles: L = {layout_variants} layouts for one component
✅ Component isolation: Tasks completely independent
- Target-style agents: T×S = {T}×{S} = {T×S} agents
- Each agent scope: {L} layouts for one component
- Component isolation: Complete task independence
Design Quality:
✅ Style-Aware Structure: {IF design_space_analysis: 'YES - HTML adapts to design_attributes' ELSE: 'Standard semantic structure'}
✅ Focused generation: Each agent handles single target × single style
✅ Self-Contained CSS: Direct design token usage (no var() dependencies)
✅ Token Quality: {consolidated_count} consolidated, {proposed_count} proposed
{IF proposed_count > 0:
ℹ️ Fast-track mode active: {proposed_count} style(s) using proposed tokens
💡 For production quality: /workflow:ui-design:consolidate --base-path "{base_path}" --variants {style_variants}
}
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'}
Output Files:
- Layout Inspirations: {len(target_list)} simple text files
- HTML Prototypes: {style_variants * layout_variants * len(target_list)} files
- CSS Files: {style_variants * layout_variants * len(target_list)} files
- Preview Files: compare.html, index.html, PREVIEW.md
Generated Structure:
📂 {base_path}/prototypes/
├── _inspirations/
│ └── {target}-layout-ideas.txt ({len(target_list)} inspiration files)
├── {target}-style-{s}-layout-{l}.html ({style_variants * layout_variants * len(target_list)} prototypes)
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 S×L×T matrix)
├── index.html (quick navigation)
└── PREVIEW.md (usage instructions)
├── compare.html (interactive matrix)
├── index.html (navigation)
└── PREVIEW.md (instructions)
🌐 Interactive Preview:
1. Matrix View: Open compare.html (recommended)
2. Quick Index: Open index.html
3. Instructions: See PREVIEW.md
Preview:
1. Open compare.html (recommended)
2. Open index.html
3. Read PREVIEW.md
{IF design_space_analysis:
🎨 Style-Aware Generation Active:
Each style's prototypes use structure adapted to design_attributes:
- Density affects container nesting and whitespace
- Visual weight affects wrapper layers and border structure
- Same layout × same target × different style = DIFFERENT HTML trees!
}
Next: /workflow:ui-design:update
```
Next: /workflow:ui-design:update {--session flag if applicable}
## Simple Bash Commands
Note: When called from /workflow:ui-design:explore-auto, design-update is triggered automatically.
### Path Operations
```bash
# Find design directory
bash(find .workflow -type d -name "design-*" | head -1)
**Dynamic Values**: target_type_icon: "📄" for page, "🧩" for component
# 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/ # Layout inspiration only
│ └── {target}-layout-ideas.txt # Simple inspiration text
├── {target}-style-{s}-layout-{l}.html # Final prototypes (S×L×T)
├── {target}-style-{s}-layout-{l}.css
├── compare.html # Interactive matrix
├── index.html # Navigation page
└── PREVIEW.md # Instructions
{base_path}/style-consolidation/
├── style-1/ (design-tokens.json, style-guide.md)
├── style-2/ (same structure)
└── style-{S}/ (same 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
### Pre-execution Checks
- **No design systems found**: Error - Run `/workflow:ui-design:consolidate` first
- **Invalid target names**: Extract from synthesis-specification.md or error with validation message
- **Missing design-space-analysis.json**: WARN only - generation continues with basic structure
- **Unsupported target type**: Error if target_type not in ["page", "component"]
### Common Errors
```
ERROR: No token sources found
→ Run /workflow:ui-design:extract or /workflow:ui-design:consolidate
### Phase-Specific Errors
- **Agent execution errors (Phase 2)**: Report details, identify which target × style agent failed
- **Invalid design-tokens.json**: Check JSON format and structure
- **Missing files (Phase 2.5)**: Indicates agent failed to write - review agent output logs
- **MCP search errors (Phase 1.5)**: Check network connectivity, retry search
- **Preview generation errors (Phase 3)**: Check script exists, permissions
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 generation**: If some target-style agents succeed, you still have those prototypes
- **Retry single combination**: Can re-run targeting failed target × style combination
- **Missing design_attributes**: Generation works without them - just less style-aware
- **Permission errors**: Run `chmod +x ~/.claude/scripts/ui-generate-preview-v2.sh`
- **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
1. **🚀 Target-Style-Centric Batch Generation**
Each agent handles L layouts for one target × one style with component isolation
- **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
2. **🎯 Component Isolation**
Tasks completely independent, preventing cross-component interference
## Integration
3. **🎨 Style-Aware Structure Adaptation**
HTML DOM adapts based on design_attributes (density, visual_weight, organic_vs_geometric)
4. **⚡ Performance Optimized**
Parallel execution of T×S agents with highly focused scope per agent
5. **💡 Simplified Layout Inspiration**
Simple text-based research replaces complex JSON planning
6. **🔧 Focused Agent Scope**
Each agent generates only L layouts, reducing complexity and improving quality
7. **🎯 Self-Contained CSS Generation**
Agents read design-tokens.json and create independent CSS with direct token values (no var() references)
8. **🌐 Interactive Visualization**
Full-featured compare.html with matrix grid
9. **✅ Production-Ready Output**
Semantic HTML5, ARIA attributes, WCAG 2.2 compliant
## Integration Points
- **Input**: Per-style design-tokens.json; design-space-analysis.json (optional); targets + layout-variants
- **Output**: S×L×T HTML/CSS prototypes with self-contained styling for `/workflow:ui-design:update`
- **Auto Integration**: Triggered by `/workflow:ui-design:explore-auto`
- **Backward Compatibility**: Works without design-space-analysis.json
**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`

806
.claude/commands/workflow/ui-design/generate.md
View File

@@ -3,625 +3,373 @@ name: generate
description: Generate UI prototypes in matrix mode (style × layout combinations) for pages or components
usage: /workflow:ui-design:generate [--targets "<list>"] [--target-type "page|component"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
examples:
- /workflow:ui-design:generate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --targets "dashboard,settings" --target-type "page" --style-variants 3 --layout-variants 3
- /workflow:ui-design:generate --session WFS-auth --targets "home,pricing" --target-type "page" --style-variants 2 --layout-variants 2
- /workflow:ui-design:generate --base-path "./.workflow/.design/run-20250109-150533" # ✅ Recommended: auto-detect variants
- /workflow:ui-design:generate --targets "navbar,hero,card" --target-type "component" --style-variants 3 --layout-variants 2
- /workflow:ui-design:generate --pages "home,dashboard" --style-variants 2 --layout-variants 2 # Legacy syntax
- /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"
allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
---
# UI Generation Command (Matrix Mode)
**Executor**: → @ui-design-agent
**Parallel Generation**: Phase 2a → @ui-design-agent (L×T tasks)
# 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. Supports both full-page layouts and isolated component generation.
Generate matrix of UI prototypes (`style × layout × targets`) with production-ready HTML/CSS. Optimized template-based architecture: **`S` times faster** than direct generation.
## Core Philosophy
- **Unified Generation**: Single mode generating `style_variants × layout_variants × targets` prototypes
- **Target Types**: Supports pages (full layouts) and components (isolated UI elements)
- **Agent-Driven**: Uses `Task(ui-design-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
- **Template-Based**: Decouples HTML structure from CSS styling for optimal performance
- **Adaptive Wrapper**: All templates use complete HTML5 documents; body content adapts (full page structure for pages, isolated component for components)
**Strategy**: Two-layer generation
- **Layer 1**: Generate `L × T` reusable templates (agent)
- **Layer 2**: Instantiate `S × L × T` final prototypes (script)
## Execution Protocol
**Supports**: Pages (full layouts) and components (isolated elements)
### Phase 1: Path Resolution & Context Loading
## Phase 1: Setup & Validation
### Step 1: Resolve Base Path
```bash
# 1. Determine base path
IF --base-path: base_path = {provided_base_path}
ELSE IF --session: base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*")
ELSE: base_path = find_latest_path_matching(".workflow/.design/*")
# 2. Determine style variant count and layout variant count
style_variants = --style-variants OR 3; VALIDATE: 1 <= style_variants <= 5
layout_variants = --layout-variants OR 3; VALIDATE: 1 <= layout_variants <= 5
# Validate against actual style directories
actual_style_count = count_directories({base_path}/style-consolidation/style-*)
IF actual_style_count == 0:
ERROR: "No style directories found"; SUGGEST: "Run /workflow:ui-design:consolidate first"; EXIT 1
IF style_variants > actual_style_count:
WARN: "⚠️ Requested {style_variants}, but only {actual_style_count} exist"
REPORT: " Available styles: {list_directories}"; style_variants = actual_style_count
REPORT: "✅ Validated style variants: {style_variants}"
# 3. Enhanced target list parsing with type detection
target_list = []; target_type = "page" # Default
# Priority 1: Unified --targets parameter
IF --targets:
raw_targets = {--targets value}
target_list = split_and_clean(raw_targets, delimiters=[",", ";", "、"])
target_list = [t.strip().lower().replace(" ", "-") for t in target_list if t.strip()]
target_type = --target-type provided ? {--target-type} : detect_target_type(target_list)
REPORT: "🎯 Using provided targets ({target_type}): {', '.join(target_list)}"
# Priority 2: Legacy --pages parameter
ELSE IF --pages:
raw_targets = {--pages value}
target_list = split_and_clean(raw_targets, delimiters=[",", ";", "、"])
target_list = [t.strip().lower().replace(" ", "-") for t in target_list if t.strip()]
target_type = "page"
REPORT: "📋 Using provided pages (legacy): {', '.join(target_list)}"
# Priority 3: Extract from synthesis-specification.md
ELSE IF --session:
synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
target_list = extract_targets_from_synthesis(synthesis_spec); target_type = "page"
REPORT: "📋 Extracted from synthesis: {', '.join(target_list)}"
# Priority 4: Detect from existing prototypes or default
ELSE:
target_list = detect_from_prototypes({base_path}/prototypes/) OR ["home"]; target_type = "page"
REPORT: "📋 Detected/default targets: {', '.join(target_list)}"
# 4. Validate target names
validated_targets = [t for t in target_list if regex_match(t, r"^[a-z0-9][a-z0-9_-]*$")]
invalid_targets = [t for t in target_list if t not in validated_targets]
IF invalid_targets: REPORT: "⚠️ Skipped invalid target names: {', '.join(invalid_targets)}"
VALIDATE: validated_targets not empty, "No valid targets found"
target_list = validated_targets
STORE: target_list, target_type
# 5. Verify design systems exist
FOR style_id IN range(1, style_variants + 1):
VERIFY: exists({base_path}/style-consolidation/style-{style_id}/design-tokens.json)
VERIFY: exists({base_path}/style-consolidation/style-{style_id}/style-guide.md)
# 6. Load requirements (if integrated mode)
IF --session: synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
# Determine working directory
bash(find .workflow -type d -name "design-*" | head -1) # Auto-detect
# OR use --base-path / --session parameters
```
### Phase 1.1: Memory Check (Skip if Already Generated)
### Step 2: Parse Configuration
```bash
# Check if compare.html exists in memory
IF exists("{base_path}/prototypes/compare.html"):
REPORT: "✅ UI generation already complete (found in memory)"
REPORT: " Skipping: Phase 1.5-4 (Layout Planning, Token Conversion, Template Generation, Prototype Instantiation, Preview Verification, Completion)"
EXIT 0
# 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"]
```
### Phase 1.5: Target-Specific Layout Planning
### Step 3: Validate Inputs
```bash
REPORT: "📐 Planning {layout_variants} layout strategies for each target..."
# Check design systems exist
bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")
CREATE: {base_path}/prototypes/_templates/
# For each target, plan its specific layouts
FOR target IN target_list:
REPORT: " Planning layouts for '{target}' ({target_type})..."
FOR layout_id IN range(1, layout_variants + 1):
Task(ui-design-agent): "
[TARGET_LAYOUT_PLANNING]
TARGET: {target} | TARGET_TYPE: {target_type} | LAYOUT_ID: {layout_id}/{layout_variants}
BASE_PATH: {base_path}
{IF --session: PROJECT_REQUIREMENTS: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md}
## Task
Research {target} {target_type} layout variations → Select approach #{layout_id} → Generate layout plan JSON
## Research
mcp__exa__web_search_exa(
query=\"common {target} {target_type} layout patterns variations best practices 2024\",
numResults=5
)
Identify multiple structural patterns → Select DISTINCT approach #{layout_id}
## Output
Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json\", layout_plan_json)
## JSON Structure
```json
{
"id": "layout-{layout_id}",
"target": "{target}",
"target_type": "{target_type}",
"name": "Descriptive name (2-4 words)",
"description": "2-3 sentences",
"structure": {
// IF page: type, regions, grid, sidebar, responsive
// IF component: arrangement, alignment, spacing, element_order
},
"semantic_hints": [...],
"accessibility_features": [...],
"research_references": [...]
}
```
## Requirements
- Research-informed, structurally DIFFERENT from other layout IDs
- Write file directly (not text output)
"
# Wait for all agent tasks to complete
REPORT: "⏳ Waiting for layout planning agents to complete..."
# Verify agent created layout JSON files
REPORT: "📝 Verifying agent file creation..."
FOR target IN target_list:
FOR layout_id IN range(1, layout_variants + 1):
layout_json_label = f"{target}-layout-{layout_id}.json"
json_path = f"{base_path}/prototypes/_templates/{layout_json_label}"
# Verify file exists
VERIFY: exists(json_path), f"Layout JSON not created by agent: {layout_json_label}"
# Validate JSON structure
TRY:
layout_json_content = Read(json_path)
layout_plan = JSON.parse(layout_json_content)
# Validate required fields
VALIDATE: layout_plan.id == f"layout-{layout_id}", f"Invalid layout ID in {layout_json_label}"
VALIDATE: layout_plan.target == target, f"Invalid target in {layout_json_label}"
VALIDATE: layout_plan.target_type == target_type, f"Invalid target_type in {layout_json_label}"
VALIDATE: layout_plan.name exists, f"Missing 'name' field in {layout_json_label}"
VALIDATE: layout_plan.structure exists, f"Missing 'structure' field in {layout_json_label}"
file_size = get_file_size(json_path)
REPORT: f" ✓ Verified: {layout_json_label} - {layout_plan.name} ({file_size} KB)"
CATCH error:
ERROR: f"Validation failed for {layout_json_label}: {error}"
REPORT: f" ⚠️ File exists but validation failed - review agent output"
REPORT: f"✅ Phase 1.5 complete: Verified {len(target_list) × layout_variants} target-specific layout files"
# Validate target names (lowercase, alphanumeric, hyphens only)
# Target type: "page" (default) or "component"
```
### Phase 1.6: Convert Design Tokens to CSS
**Output**: `base_path`, `style_variants`, `layout_variants`, `target_list[]`, `target_type`
### Step 4: Check Existing Output
```bash
REPORT: "🎨 Converting design tokens to CSS variables..."
# Check for jq dependency
IF NOT command_exists("jq"):
ERROR: "jq is not installed or not in PATH. The conversion script requires jq."
REPORT: "Please install jq: macOS: brew install jq | Linux: apt-get install jq | Windows: https://stedolan.github.io/jq/download/"
EXIT 1
# Convert design tokens to CSS for each style variant
FOR style_id IN range(1, style_variants + 1):
tokens_json_path = "{base_path}/style-consolidation/style-${style_id}/design-tokens.json"
tokens_css_path = "{base_path}/style-consolidation/style-${style_id}/tokens.css"
script_path = "~/.claude/scripts/convert_tokens_to_css.sh"
# Verify input file exists
VERIFY: exists(tokens_json_path), f"Design tokens not found for style-{style_id}"
# Execute conversion: cat input.json | script.sh > output.css
Bash(cat "${tokens_json_path}" | "${script_path}" > "${tokens_css_path}")
# Verify output was generated
IF exit_code == 0 AND exists(tokens_css_path):
file_size = get_file_size(tokens_css_path)
REPORT: f" ✓ Generated tokens.css for style-{style_id} ({file_size} KB)"
ELSE:
ERROR: f"Failed to generate tokens.css for style-{style_id}"
EXIT 1
REPORT: f"✅ Phase 1.6 complete: Converted {style_variants} design token files to CSS"
# Skip if already generated
bash(test -f {base_path}/prototypes/compare.html && echo "exists")
```
### Phase 1.7: Extract Token Variable Names from CSS
**If exists**: Skip to completion message
## Phase 2: Layout Planning
### Step 1: Research Layout Patterns (Agent)
```bash
REPORT: "📋 Extracting actual CSS variable names from tokens.css..."
tokens_css_path = "{base_path}/style-consolidation/style-1/tokens.css"
VERIFY: exists(tokens_css_path), "tokens.css not found. Phase 1.6 may have failed."
tokens_css_content = Read(tokens_css_path)
# Extract all CSS variable names from the generated file
# Pattern: --variable-name: value;
all_token_vars = extract_css_variables(tokens_css_content) # Regex: r'--([a-z0-9-_]+):'
# Categorize variables for better Agent understanding
color_vars = [v for v in all_token_vars if v.startswith('--color-')]
typography_vars = [v for v in all_token_vars if v.startswith(('--font-', '--line-height-', '--letter-spacing-'))]
spacing_vars = [v for v in all_token_vars if v.startswith('--spacing-')]
radius_vars = [v for v in all_token_vars if v.startswith('--border-radius-')]
shadow_vars = [v for v in all_token_vars if v.startswith('--shadow-')]
breakpoint_vars = [v for v in all_token_vars if v.startswith('--breakpoint-')]
REPORT: f"✅ Extracted {len(all_token_vars)} actual CSS variables from tokens.css"
REPORT: f" Colors: {len(color_vars)} | Typography: {len(typography_vars)} | Spacing: {len(spacing_vars)}"
bash(mkdir -p {base_path}/prototypes/_templates)
```
### Phase 2: Optimized Matrix UI Generation
For each `target × layout_id`:
```javascript
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" : ""}
**Strategy**: Two-layer generation reduces complexity from `O(S×L×T)` to `O(L×T)`, achieving **`S` times faster** performance.
## 参考
- 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
- **Layer 1**: Generate `L × T` layout templates (HTML structure + structural CSS) by agent
- **Layer 2**: Instantiate `S × L × T` final prototypes via fast file operations
## 生成
Write("{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json")
#### Phase 2a: Layout Template Generation
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"]
}
**Parallel Executor**: → @ui-design-agent
```bash
CREATE: {base_path}/prototypes/_templates/
CREATE: {base_path}/prototypes/
# Launch parallel template generation tasks → @ui-design-agent
# Total agent tasks: layout_variants × len(target_list)
FOR layout_id IN range(1, layout_variants + 1):
FOR target IN target_list:
# Read the target-specific layout plan
layout_json_path = f"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json"
layout_plan = Read(layout_json_path)
Task(ui-design-agent): "
[UI_LAYOUT_TEMPLATE_GENERATION]
🚨 TARGET INDEPENDENCE: Generate template for EXACTLY ONE target: '{target}' (standalone, reusable)
LAYOUT_ID: {layout_id} | TARGET: {target} | TARGET_TYPE: {target_type}
BASE_PATH: {base_path}
{IF --session: REQUIREMENTS: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md}
## Layout Plan to Implement
**Path**: {layout_json_path}
**Plan**: {JSON.stringify(layout_plan, null, 2)}
## Task
Generate TWO template files implementing the layout plan:
- HTML: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.html
- CSS: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.css
## HTML Requirements
- Complete HTML5 document (<!DOCTYPE>, <html>, <head>, <body>)
- Semantic elements + ARIA attributes
- Body content:
* IF page → Full structure (header, nav, main, footer)
* IF component → Isolated element in presentation wrapper
- ⚠️ CRITICAL CSS placeholders in <head>:
<link rel=\"stylesheet\" href=\"{{STRUCTURAL_CSS}}\">
<link rel=\"stylesheet\" href=\"{{TOKEN_CSS}}\">
## CSS Requirements - Token Reference
**1. Read tokens.css**
Read(\"{base_path}/style-consolidation/style-1/tokens.css\")
Extract all CSS variable names (pattern: lines with \" --\" in \":root {}\")
**2. Available Tokens**
- Colors: {', '.join(color_vars[:5])}... ({len(color_vars)} total)
- Typography: {', '.join(typography_vars[:5])}... ({len(typography_vars)} total)
- Spacing: {', '.join(spacing_vars[:5])}... ({len(spacing_vars)} total)
- Radius: {', '.join(radius_vars[:3])}... ({len(radius_vars)} total)
- Shadows: {', '.join(shadow_vars)}
**3. Variable Usage Rules**
- ✅ Use ONLY variables from tokens.css (exact names)
- ✅ Format: var(--exact-name-from-file)
- ❌ NO invented/guessed variable names
- ❌ NO hardcoded values (colors, fonts, spacing)
**4. Optional Extension**
If core tokens insufficient → Create `{target}-layout-{layout_id}-tokens.css` with `--layout-*` prefix
Examples: `--layout-spacing-navbar-height`, `--layout-size-sidebar-width`
**CSS Scope**: Structural layout only (Flexbox, Grid, positioning)
**Responsive**: Mobile-first approach
## Write Operations
Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.html\", html_content)
Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.css\", css_content)
Report completion with file paths. Write files directly (not text output).
"
REPORT: "⏳ Phase 2a: Waiting for agents to complete template generation..."
## 注意
- 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
`
```
#### Phase 2a.5: Verify Agent Template File Creation
### Step 2: Verify Layout Plans
```bash
REPORT: "📝 Phase 2a.5: Verifying agent template file creation..."
# Verify files created
bash(ls {base_path}/prototypes/_templates/*.json | wc -l) # Should equal L×T
# Verify each agent created template files
FOR layout_id IN range(1, layout_variants + 1):
FOR target IN target_list:
html_label = f"{target}-layout-{layout_id}.html"
css_label = f"{target}-layout-{layout_id}.css"
html_path = f"{base_path}/prototypes/_templates/{html_label}"
css_path = f"{base_path}/prototypes/_templates/{css_label}"
# Verify files exist
VERIFY: exists(html_path), f"HTML template not created by agent: {html_label}"
VERIFY: exists(css_path), f"CSS template not created by agent: {css_label}"
# Validate content
TRY:
html_content = Read(html_path)
css_content = Read(css_path)
# Basic validation checks
VALIDATE: len(html_content) > 100, f"HTML template too short: {html_label}"
VALIDATE: len(css_content) > 50, f"CSS template too short: {css_label}"
VALIDATE: "<!DOCTYPE html>" in html_content, f"Invalid HTML structure: {html_label}"
VALIDATE: "var(--" in css_content, f"Missing CSS variables: {css_label}"
html_size = get_file_size(html_path)
css_size = get_file_size(css_path)
REPORT: f" ✓ Verified: {html_label} ({html_size} KB) + {css_label} ({css_size} KB)"
CATCH error:
ERROR: f"Validation failed for {target}-layout-{layout_id}: {error}"
REPORT: f" ⚠️ Files exist but validation failed - review agent output"
REPORT: "✅ Phase 2a.5 complete: Verified {layout_variants * len(target_list) * 2} template files"
# Validate JSON structure
Read({base_path}/prototypes/_templates/{target}-layout-{layout_id}.json)
```
#### Phase 2b: Prototype Instantiation
**Output**: `L × T` layout plan JSON files
## Phase 3: Token Conversion
### Step 1: Convert JSON to CSS Variables
```bash
REPORT: "🚀 Phase 2b: Instantiating prototypes from templates..."
# Check jq dependency
bash(command -v jq >/dev/null 2>&1 || echo "ERROR: jq not found")
# Verify tokens.css files exist (should be created in Phase 1.6)
FOR style_id IN range(1, style_variants + 1):
tokens_css_path = "{base_path}/style-consolidation/style-${style_id}/tokens.css"
VERIFY: exists(tokens_css_path), f"tokens.css missing for style-{style_id}. Phase 1.6 may have failed."
REPORT: " ✓ Verified {style_variants} tokens.css files exist"
# Use ui-instantiate-prototypes.sh script for instantiation
prototypes_dir = "{base_path}/prototypes"
targets_csv = ','.join(target_list)
session_id = --session provided ? {session_id} : "standalone"
# Execute instantiation script with target type
Bash(~/.claude/scripts/ui-instantiate-prototypes.sh "{prototypes_dir}" --session-id "{session_id}" --mode "{target_type}")
# The script auto-detects: Targets, Style variants, Layout variants
# The script generates:
# 1. S × L × T HTML prototypes with CSS links
# 2. Implementation notes for each prototype
# 3. compare.html (interactive matrix)
# 4. index.html (navigation page)
# 5. PREVIEW.md (documentation)
REPORT: "✅ Phase 2b complete: Instantiated {style_variants * layout_variants * len(target_list)} final prototypes"
REPORT: " Mode: {target_type} | Performance: {style_variants}× faster than original approach"
# 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)
```
### Phase 3: Verify Preview Files
### Step 2: Extract Variable Names
```bash
REPORT: "🔍 Phase 3: Verifying preview files..."
# Read generated tokens.css
Read({base_path}/style-consolidation/style-1/tokens.css)
expected_files = ["{base_path}/prototypes/compare.html", "{base_path}/prototypes/index.html", "{base_path}/prototypes/PREVIEW.md"]
all_present = true
FOR file_path IN expected_files:
IF exists(file_path): REPORT: " ✓ Found: {basename(file_path)}"
ELSE: REPORT: " ✗ Missing: {basename(file_path)}"; all_present = false
IF all_present: REPORT: "✅ Phase 3 complete: All preview files verified"
ELSE: WARN: "⚠️ Some preview files missing - script may have failed"
# Optional: Generate fallback design-tokens.css for reference
fallback_css_path = "{base_path}/prototypes/design-tokens.css"
IF NOT exists(fallback_css_path):
Write(fallback_css_path, "/* Auto-generated fallback CSS custom properties */\n/* See style-consolidation/style-{n}/tokens.css for actual values */")
REPORT: " ✓ Generated fallback design-tokens.css"
# Extract CSS variable names (pattern: --variable-name:)
# Categorize: colors, typography, spacing, radius, shadows
```
### Phase 3.5: Cross-Target Consistency Validation
**Output**: `S × tokens.css` files + extracted variable list
**Condition**: Only executes if `len(target_list) > 1 AND target_type == "page"`
## Phase 4: Template Generation (Agent)
```bash
# Skip if single target or component mode
IF len(target_list) <= 1 OR target_type == "component": SKIP to Phase 4
**Executor**: `Task(ui-design-agent)` × `L × T` tasks in parallel
# For multi-page workflows, validate cross-page consistency → @ui-design-agent
FOR style_id IN range(1, style_variants + 1):
FOR layout_id IN range(1, layout_variants + 1):
Task(@ui-design-agent): "
[CROSS_PAGE_CONSISTENCY_VALIDATION]
### Step 1: Launch Agent Tasks
For each `layout_id × target`:
```javascript
Task(ui-design-agent): `
[UI_LAYOUT_TEMPLATE_GENERATION]
🚨 ONE target only: '{target}' (standalone, reusable)
STYLE: {style_id} | LAYOUT: {layout_id} | TARGETS: {target_list} | TYPE: {target_type}
BASE_PATH: {base_path}
LAYOUT: {layout_id} | TARGET: {target} | TYPE: {target_type}
BASE_PATH: {base_path}
${--session ? "REQUIREMENTS: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md" : ""}
## Input
{base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html/css (all targets)
## 参考
- 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-*
## Validate
1. Shared components (header/nav/footer)
2. Token usage (no hardcoded values)
3. Accessibility (ARIA, headings, landmarks)
4. Layout strategy consistency
## 生成
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
## Output
Write({base_path}/prototypes/consistency-report-s{style_id}-l{layout_id}.md, validation_report)
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
Focus on shared elements. Page-specific variations acceptable.
"
# Aggregate consistency reports
Write({base_path}/prototypes/CONSISTENCY_SUMMARY.md):
# Multi-{target_type.capitalize()} Consistency Summary
## Validated Combinations
- Style Variants: {style_variants} | Layout Variants: {layout_variants}
- Total Reports: {style_variants * layout_variants}
## Report Files
{FOR s, l: - [Style {s} Layout {l}](./consistency-report-s{s}-l{l}.md)}
Run `/workflow:ui-design:update` once all issues are resolved.
## 注意
- ✅ 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
`
```
### Phase 4: Completion
### Step 2: Verify Templates Created
```bash
# 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
```bash
# 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
```bash
# 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
```javascript
TodoWrite({todos: [
{content: "Resolve paths and load design systems", status: "completed", activeForm: "Loading design systems"},
{content: `Plan ${target_list.length}×${layout_variants} target-specific layouts`, status: "completed", activeForm: "Planning layouts"},
{content: `Convert ${style_variants} design token files to CSS`, status: "completed", activeForm: "Converting tokens to CSS"},
{content: "Extract CSS variable names from tokens.css", status: "completed", activeForm: "Extracting variable names"},
{content: `Generate ${layout_variants}×${target_list.length} layout templates (agent reads tokens.css)`, status: "completed", activeForm: "Generating templates"},
{content: `Instantiate ${style_variants}×${layout_variants}×${target_list.length} prototypes using script`, status: "completed", activeForm: "Running script"},
{content: "Verify preview files generation", status: "completed", activeForm: "Verifying files"}
{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"}
]});
```
**Completion Message**:
### Output Message
```
✅ Optimized Matrix UI generation complete!
✅ Matrix UI generation complete!
Configuration:
- Style Variants: {style_variants}
- Layout Variants: {layout_variants} (target-specific planning)
- Target Type: {target_type_icon} {target_type}
- Layout Variants: {layout_variants}
- Target Type: {target_type}
- Targets: {target_list}
- Total Prototypes: {style_variants * layout_variants * len(target_list)}
- Layout Plans: {len(target_list) × layout_variants} target-specific JSON files generated
- Total Prototypes: {S × L × T}
Performance Metrics:
- Layout Templates Generated: {layout_variants * len(target_list)} (Agent tasks)
- Prototypes Instantiated: {style_variants * layout_variants * len(target_list)} (script-based)
- Preview Files: compare.html, index.html, PREVIEW.md (auto-generated)
- Speed Improvement: {style_variants}× faster than previous approach
- Resource Efficiency: {100 * (1 - 1/style_variants)}% reduction in Agent calls
- Script: ui-instantiate-prototypes.sh v3.0 with auto-detection
Performance:
- Templates: {L × T} (agent)
- Prototypes: {S × L × T} (script)
- Speed: {S}× faster
- Script: ui-instantiate-prototypes.sh v3.0
Generated Structure:
📂 {base_path}/prototypes/
├── _templates/
│ ├── {target}-layout-{l}.json ({len(target_list) × layout_variants} layout plans)
│ ├── {target}-layout-{l}.html ({layout_variants * len(target_list)} HTML templates)
│ └── {target}-layout-{l}.css ({layout_variants * len(target_list)} CSS templates)
├── {target}-style-{s}-layout-{l}.html ({style_variants * layout_variants * len(target_list)} final prototypes)
├── {target}-style-{s}-layout-{l}-notes.md
├── compare.html (interactive matrix visualization)
└── index.html (quick navigation)
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)
🌐 Interactive Preview:
1. Matrix View: Open compare.html (recommended)
2. Quick Index: Open index.html
3. Instructions: See PREVIEW.md
Preview:
1. Open compare.html (recommended)
2. Open index.html
3. Read PREVIEW.md
{IF target_type == "component": Note: Components use complete HTML5 documents with isolated body content for better comparison and styling.}
Next: /workflow:ui-design:update
```
Next: /workflow:ui-design:update {--session flag if applicable}
## Simple Bash Commands
Note: When called from /workflow:ui-design:auto, design-update is triggered automatically.
### Path Operations
```bash
# Find design directory
bash(find .workflow -type d -name "design-*" | head -1)
**Dynamic Values**: target_type_icon: "📄" for page, "🧩" for component
# 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
```bash
# 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
```bash
# 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-specific layout plans and templates
│ ├── {target}-layout-1.json # Layout plan JSON (target-specific)
│ ├── {target}-layout-1.html # Style-agnostic HTML structure
│ ├── {target}-layout-1.css # Structural CSS with var() references
│ └── ... (T × L layout plans + templates)
├── compare.html # Interactive matrix visualization
├── index.html # Simple navigation page
├── PREVIEW.md # Preview instructions
├── design-tokens.css # CSS custom properties fallback
├── {target}-style-{s}-layout-{l}.html # Final prototypes (copied from templates)
├── {target}-style-{s}-layout-{l}-notes.md # Implementation notes
└── ... (S × L × T total final files)
{base_path}/style-consolidation/
├── style-1/ (design-tokens.json, tokens.css, style-guide.md)
├── style-2/ (same 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
### Pre-execution Checks
- **No design systems found**: Error - Run `/workflow:ui-design:consolidate` first
- **Invalid target names**: Extract from synthesis-specification.md or error with validation message
- **Missing templates directory**: Auto-created in Phase 1.5
- **Unsupported target type**: Error if target_type not in ["page", "component"]
- **Layout planning failures**: Check Phase 1.5 agent outputs for errors
### Common Errors
```
ERROR: No design systems found
→ Run /workflow:ui-design:consolidate first
### Phase-Specific Errors
- **Agent execution errors (Phase 2a)**: Report details, suggest retry with specific phase
- **Token conversion errors (Phase 2b)**: Check design-tokens.json format, validate JSON schema
- **Script execution errors (Phase 2b)**: Check script exists, permissions, output for specific errors
- **Preview generation errors (Phase 3)**: Check script completed, verify template exists, review Phase 2b output
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**: Script reports generated vs failed counts - review logs
- **Missing templates**: Indicates Phase 2a issue - regenerate templates
- **Auto-detection failures**: Use manual mode with explicit parameters
- **Permission errors**: Run `chmod +x ~/.claude/scripts/ui-instantiate-prototypes.sh`
- **Partial failure**: Check script logs for counts
- **Missing templates**: Regenerate Phase 4
- **Invalid tokens**: Validate design-tokens.json
## Quality Checks
## Quality Checklist
After generation, ensure:
- [ ] All CSS values reference design token custom properties
- [ ] No hardcoded colors, spacing, or typography
- [ ] Semantic HTML structure with proper element hierarchy
- [ ] ARIA attributes present for accessibility
- [ ] Responsive design implemented with mobile-first approach
- [ ] File naming follows `{target}-style-{s}-layout-{l}` convention
- [ ] compare.html loads correctly with all prototypes
- [ ] Template files are reusable and style-agnostic
- [ ] All templates use complete HTML5 documents with appropriate body content (full structure for pages, isolated component for components)
- [ ] 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
1. **Target-Specific Layout Planning** 🆕 - Each target gets custom-designed layouts; Agent researches modern patterns using MCP tools; Layout plans saved as structured JSON
2. **Unified Target Generation** - Supports both pages (full layouts) and components (isolated elements); Backward compatible with legacy `--pages` parameter
3. **Optimized Template-Based Architecture** - Generates `L × T` reusable templates plus `L × T` layout plans; **`S` times faster**
4. **Three-Layer Generation Strategy** - Layer 1: Layout planning (target-specific); Layer 2: Template generation (implements plans); Layer 3: Fast instantiation; Agent autonomously uses MCP tools
5. **Script-Based Instantiation (v3.0)** - Uses `ui-instantiate-prototypes.sh` for efficient file operations; Auto-detection; Robust error handling; Integrated preview generation; Supports both page and component modes
6. **Consistent Cross-Style Layouts** - Same layout structure applied uniformly; Easier to compare styles; Simplified maintenance
7. **Dynamic Style Injection** - CSS custom properties enable runtime style switching; Each style variant has its own `tokens.css` file
8. **Interactive Visualization** - Full-featured compare.html; Matrix grid view with synchronized scrolling; Enhanced index.html with statistics; Comprehensive PREVIEW.md
9. **Production-Ready Output** - Semantic HTML5 and ARIA attributes (WCAG 2.2); Mobile-first responsive design; Token-driven styling; Implementation notes
- **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 Points
## Integration
- **Input**: Per-style `design-tokens.json` from `/workflow:ui-design:consolidate`; `--targets` and `--layout-variants` parameters; Optional: `synthesis-specification.md` for target requirements; Target type specification
- **Output**: Target-specific `layout-{n}.json` files; Matrix HTML/CSS prototypes for `/workflow:ui-design:update`
- **Template**: `~/.claude/workflows/_template-compare-matrix.html` (global)
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:explore-auto` workflow
- **Key Change**: Layout planning moved from consolidate to generate phase; Each target gets custom-designed layouts
- **Backward Compatibility**: Legacy `--pages` parameter continues to work
**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`