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

feat: integrate Exa MCP for design trend research in UI workflow

Browse Source 
Enhance UI Design Workflow with intelligent design trend research capabilities:
- Add design trend analysis in extract phase using Exa MCP API
- Integrate layout strategy planning with current UI/UX patterns (2024-2025)
- Update consolidation command to include dynamic layout generation
- Add ui-instantiate-prototypes.sh script for prototype management
- Simplify path structure by removing nested .design directories
- Update workflow architecture documentation

This integration enables context-aware design decisions based on modern design trends
and improves the quality of generated UI prototypes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-10-09 18:04:37 +08:00
parent c7e2d6f82f
commit 20c75c0060
8 changed files with 1466 additions and 480 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,39 +1,46 @@
---
name: consolidate
description: Consolidate style variants into unified or separate design systems
usage: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--keep-separate]
argument-hint: "[--base-path \".workflow/WFS-xxx/runs/run-xxx/.design\"] [--variants 3] [--keep-separate]"
description: Consolidate style variants into unified or separate design systems and plan layout strategies
usage: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--keep-separate] [--layout-variants <count>]
argument-hint: "[--base-path \".workflow/WFS-xxx/design-run-xxx\"] [--variants 3] [--keep-separate] [--layout-variants 3]"
examples:
- /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/latest/.design" --variants 3 --keep-separate
- /workflow:ui-design:consolidate --session WFS-auth --variants 2
- /workflow:ui-design:consolidate --base-path "./design-session-xxx/.design"
- /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --variants 3 --keep-separate --layout-variants 3
- /workflow:ui-design:consolidate --session WFS-auth --variants 2 --layout-variants 2
- /workflow:ui-design:consolidate --base-path "./.workflow/.design/run-20250109-150533" --layout-variants 3
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*)
---
# Style Consolidation Command
# Design System Consolidation & Layout Planning Command
## Overview
Consolidate user-selected style variants into unified or separate production-ready design systems using Claude's native synthesis capabilities. Merges token proposals from multiple style cards into cohesive design language(s).
Consolidate user-selected style variants into unified or separate production-ready design systems AND plan layout strategies for UI generation. This command serves as the **Design Planning Phase**, producing all strategic decisions needed for the subsequent generation phase.
## Core Philosophy
- **Design Planning Hub**: Centralizes both style consolidation and layout strategy planning
- **Claude-Native**: 100% Claude-driven consolidation, no external tools
- **Token Merging**: Combines `proposed_tokens` from selected variants
- **Layout Strategy Definition**: Plans and documents layout variants for generation
- **Intelligent Synthesis**: Resolves conflicts, ensures consistency
- **Production-Ready**: Complete design system(s) with documentation
- **Dual Mode**: Unified (1 merged system) or Separate (N independent systems)
## Execution Protocol
### Phase 1: Path Resolution & Variant Loading
### 🔄 Common Phases (All Modes)
These phases are executed identically regardless of consolidation mode.
#### Phase 1: Path Resolution & Variant Loading
```bash
# Determine base path
IF --base-path provided:
base_path = {provided_base_path}
ELSE IF --session provided:
base_path = ".workflow/WFS-{session}/latest/.design"
# Find latest design run in session
base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*")
ELSE:
base_path = find_latest_design_session(".workflow/.scratchpad/")
base_path = find_latest_path_matching(".workflow/.design/*")
# Verify extraction output exists
style_cards_path = "{base_path}/style-extraction/style-cards.json"
@@ -44,7 +51,7 @@ style_cards = Read(style_cards_path)
total_variants = len(style_cards.style_cards)
```
### Phase 2: Variant Selection & Mode Determination
#### Phase 2: Variant Selection & Mode Determination
```bash
# Determine how many variants to consolidate
@@ -67,7 +74,86 @@ ELSE:
REPORT: "Mode: Unified - merging {variants_count} variants into one design system"
```
### Phase 3: Load Design Context (Optional)
#### Phase 2.5: Layout Strategy Planning (Dynamic Generation)
```bash
# Determine layout variants count
IF --layout-variants provided:
layout_variants = {provided_count}
VALIDATE: 1 <= layout_variants <= 5
ELSE:
layout_variants = 3 # Default to 3 layout strategies
REPORT: "📐 Planning {layout_variants} layout strategies (dynamic generation)"
# Step 1: Gather project context for layout planning
project_context = ""
IF exists({base_path}/.brainstorming/synthesis-specification.md):
project_context = Read({base_path}/.brainstorming/synthesis-specification.md)
ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md):
project_context = Read({base_path}/.brainstorming/ui-designer/analysis.md)
# Extract project type and requirements from context
project_hints = extract_project_type(project_context) # e.g., "dashboard", "marketing site", "SaaS platform"
# Step 2: Search for current UI/UX layout trends using Exa MCP
REPORT: "🔍 Searching for modern UI layout patterns..."
exa_query = "modern web UI layout patterns design systems {project_hints} 2024 2025"
layout_trends = mcp__exa__get_code_context_exa(
query=exa_query,
tokensNum="dynamic"
)
# Step 3: Generate layout strategies dynamically with Claude
REPORT: "🎨 Generating {layout_variants} custom layout strategies..."
layout_synthesis_prompt = """
Generate {layout_variants} distinct, modern UI layout strategies for this project.
PROJECT CONTEXT:
{project_context}
CURRENT LAYOUT TRENDS (from web research):
{layout_trends}
REQUIREMENTS:
1. Each layout must be unique and serve different use cases
2. Consider modern design trends from 2024-2025
3. Align with project type: {project_hints}
4. Balance innovation with usability
5. Cover diverse layout paradigms (grid-based, asymmetric, minimal, etc.)
OUTPUT FORMAT (JSON):
{
"layout_variants_count": {layout_variants},
"strategies": [
{
"id": "layout-1",
"name": "{Concise name, max 3 words}",
"description": "{Detailed description: layout structure, visual hierarchy, reading patterns, use cases. 2-3 sentences.}"
},
...
]
}
RESPONSE FORMAT:
Provide ONLY the JSON object, no additional text.
===== layout-strategies.json =====
{JSON content}
"""
# Execute synthesis
claude_response = synthesize_with_claude(layout_synthesis_prompt)
layout_strategies = parse_json_response(claude_response)
# Step 4: Write layout strategies to file
Write({base_path}/style-consolidation/layout-strategies.json, JSON.stringify(layout_strategies, null, 2))
REPORT: "✅ Layout strategies defined: {[s.name for s in layout_strategies.strategies]}"
```
#### Phase 3: Load Design Context (Optional)
```bash
# Load brainstorming context if available
@@ -78,15 +164,19 @@ ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md):
design_context = Read({base_path}/.brainstorming/ui-designer/analysis.md)
```
### Phase 4: Design System Synthesis (Claude)
---
**Route based on consolidation_mode**:
### 🔀 Mode-Specific Phases
#### Mode A: Unified Consolidation (Default)
**Execution branches based on `consolidation_mode`:**
Merges all style variants into a single, cohesive design system.
#### Branch A: Unified Mode
**Synthesis Prompt Template**:
**When**: `consolidation_mode == "unified"` (default)
**Goal**: Merge all selected variants into a single, cohesive design system.
**Phase 4A: Unified Design System Synthesis**
```
Create a unified, production-ready design system by consolidating the following style variants.
@@ -173,36 +263,29 @@ FILE 2: style-guide.md
- UI components meet WCAG AA (3:1 minimum)
- Focus indicators are clearly visible
FILE 3: tailwind.config.js
module.exports = {
theme: {
extend: {
colors: { brand: { primary: '{value}', ... }, ... },
fontFamily: { heading: [{fonts}], body: [{fonts}], mono: [{fonts}] },
fontSize: { ... },
spacing: { ... },
borderRadius: { ... },
boxShadow: { ... },
screens: { ... }
}
}
}
FILE 4: validation-report.json
FILE 3: consolidation-report.json
{
"session_id": "{session_id}",
"consolidated_variants": {variant_ids},
"consolidation_mode": "unified",
"timestamp": "{ISO timestamp}",
"validation_results": {
"colors": { "total": {count}, "wcag_aa_compliant": {count}, "warnings": [{issues}] },
"typography": { "font_families": {count}, "scale_sizes": {count} },
"spacing": { "scale_values": {count} },
"accessibility": { "status": "pass|warnings", "issues": [{list}] },
"completeness": {
"required_categories": ["colors", "typography", "spacing", "border_radius", "shadows", "breakpoints"],
"present_categories": [{list}],
"missing_categories": [{list if any}]
"style_systems": {
"consolidated_variants": {variant_ids},
"variant_count": {selected_variants.length},
"validation_results": {
"colors": { "total": {count}, "wcag_aa_compliant": {count}, "warnings": [{issues}] },
"typography": { "font_families": {count}, "scale_sizes": {count} },
"spacing": { "scale_values": {count} },
"accessibility": { "status": "pass|warnings", "issues": [{list}] },
"completeness": {
"required_categories": ["colors", "typography", "spacing", "border_radius", "shadows", "breakpoints"],
"present_categories": [{list}],
"missing_categories": [{list if any}]
}
}
},
"layout_strategies": {
"count": {layout_variants},
"strategies": {READ from layout-strategies.json}
}
}
@@ -215,22 +298,42 @@ Provide each file's content in clearly labeled sections:
===== style-guide.md =====
{Markdown content}
===== tailwind.config.js =====
{JavaScript content}
===== validation-report.json =====
===== consolidation-report.json =====
{JSON content}
```
**Output Location**: `{base_path}/style-consolidation/`
**Phase 5A: Unified Output**
```bash
# Parse Claude's response
CREATE: {base_path}/style-consolidation/
parsed_output = parse_claude_response(claude_response)
Write({base_path}/style-consolidation/design-tokens.json, parsed_output.design_tokens)
Write({base_path}/style-consolidation/style-guide.md, parsed_output.style_guide)
Write({base_path}/style-consolidation/consolidation-report.json, parsed_output.consolidation_report)
```
**Output Structure**:
```
{base_path}/style-consolidation/
├── design-tokens.json # Merged token definitions
├── style-guide.md # Comprehensive design documentation
├── layout-strategies.json # Layout variant definitions
└── consolidation-report.json # Unified validation & planning report
```
---
#### Mode B: Separate Consolidation (--keep-separate)
#### Branch B: Separate Mode
Generates N independent design systems, each refining one style variant into a complete production-ready system.
**When**: `consolidation_mode == "separate"` (--keep-separate flag)
**For each variant, use this Synthesis Prompt Template**:
**Goal**: Generate N independent design systems, each refining one style variant.
**Phase 4B: Separate Design System Synthesis**
For each variant, use this synthesis prompt:
```
Create a production-ready design system for the following style variant.
@@ -261,7 +364,7 @@ REFINEMENT RULES:
6. **OKLCH Format**: All colors must use oklch(L C H / A) format
7. **Design Philosophy**: Expand and articulate the variant's design philosophy
OUTPUT: Generate the same 4 files as unified mode (design-tokens.json, style-guide.md, tailwind.config.js, validation-report.json)
OUTPUT: Generate 2 files (design-tokens.json, style-guide.md) - validation will be aggregated later
RESPONSE FORMAT:
Provide each file's content in clearly labeled sections:
@@ -271,47 +374,9 @@ Provide each file's content in clearly labeled sections:
===== style-guide.md =====
{Markdown content}
===== tailwind.config.js =====
{JavaScript content}
===== validation-report.json =====
{JSON content}
```
**Output Location**: `{base_path}/style-consolidation/style-{n}/`
For N variants, generate N separate subdirectories:
```
{base_path}/style-consolidation/
├── style-1/
│ ├── design-tokens.json
│ ├── style-guide.md
│ ├── tailwind.config.js
│ └── validation-report.json
├── style-2/
│ └── ... (same structure)
└── style-N/
└── ... (same structure)
```
---
### Phase 5: Parse & Write Output Files
#### Unified Mode Output
```bash
# Parse Claude's response
CREATE: {base_path}/style-consolidation/
parsed_output = parse_claude_response(claude_response)
Write({base_path}/style-consolidation/design-tokens.json, parsed_output.design_tokens)
Write({base_path}/style-consolidation/style-guide.md, parsed_output.style_guide)
Write({base_path}/style-consolidation/tailwind.config.js, parsed_output.tailwind_config)
Write({base_path}/style-consolidation/validation-report.json, parsed_output.validation_report)
```
#### Separate Mode Output
**Phase 5B: Separate Output**
```bash
# Parse each variant's response
FOR variant_id IN range(1, variants_count + 1):
@@ -320,32 +385,76 @@ FOR variant_id IN range(1, variants_count + 1):
Write({base_path}/style-consolidation/style-{variant_id}/design-tokens.json, parsed_output.design_tokens)
Write({base_path}/style-consolidation/style-{variant_id}/style-guide.md, parsed_output.style_guide)
Write({base_path}/style-consolidation/style-{variant_id}/tailwind.config.js, parsed_output.tailwind_config)
Write({base_path}/style-consolidation/style-{variant_id}/validation-report.json, parsed_output.validation_report)
# Generate unified consolidation report for all variants
consolidation_report = {
"session_id": session_id,
"consolidation_mode": "separate",
"timestamp": ISO_timestamp,
"style_systems": {
"variant_count": variants_count,
"variants": []
},
"layout_strategies": Read({base_path}/style-consolidation/layout-strategies.json)
}
# Aggregate validation data from all style variants
FOR variant_id IN range(1, variants_count + 1):
design_tokens = Read({base_path}/style-consolidation/style-{variant_id}/design-tokens.json)
validation_data = validate_design_tokens(design_tokens)
consolidation_report.style_systems.variants.append({
"id": "style-{variant_id}",
"validation": validation_data
})
Write({base_path}/style-consolidation/consolidation-report.json, JSON.stringify(consolidation_report, null, 2))
```
### Phase 6: Completion
**Output Structure**:
```
{base_path}/style-consolidation/
├── style-1/
│ ├── design-tokens.json # Style 1 tokens
│ └── style-guide.md # Style 1 docs
├── style-2/
│ └── ... (same structure)
├── style-N/
│ └── ... (same structure)
├── layout-strategies.json # Layout variant definitions
└── consolidation-report.json # Unified validation for all styles + layout plan
```
---
### 🎯 Common Completion Phase
**Phase 6: Completion & Reporting** (executed after mode-specific phases)
```javascript
TodoWrite({
todos: [
{content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"},
{content: "Select variants and determine mode", status: "completed", activeForm: "Selecting variants"},
{content: "Plan layout strategies", status: "completed", activeForm: "Planning layout strategies"},
{content: "Load design context from brainstorming", status: "completed", activeForm: "Loading context"},
{content: "Synthesize design system(s) with Claude", status: "completed", activeForm: "Synthesizing design system"},
{content: "Write consolidated design system files", status: "completed", activeForm: "Writing output files"}
{content: "Write consolidated design system files", status: "completed", activeForm: "Writing output files"},
{content: "Generate unified consolidation report", status: "completed", activeForm: "Generating report"}
]
});
```
**Completion Message**:
```
✅ Style consolidation complete for session: {session_id}
✅ Design consolidation & layout planning complete for session: {session_id}
Mode: {consolidation_mode}
Consolidated {selected_variants.length} variant(s):
Consolidated {selected_variants.length} style variant(s):
{FOR each variant: - {variant.name} ({variant.id})}
Layout Strategies Planned: {layout_variants}
{FOR each strategy: - Layout {strategy.id}: {strategy.name}}
{IF unified mode:
Validation Summary:
- Colors: {total_colors} (WCAG AA: {compliant_count}/{total_colors})
@@ -356,47 +465,25 @@ Validation Summary:
📂 Output: {base_path}/style-consolidation/
├── design-tokens.json
├── style-guide.md
├── tailwind.config.js
└── validation-report.json
├── layout-strategies.json [NEW]
└── consolidation-report.json [NEW - replaces validation-report.json]
}
{IF separate mode:
Generated {variants_count} independent design systems:
📂 Output: {base_path}/style-consolidation/
├── style-1/ (design-tokens.json, style-guide.md, tailwind.config.js, validation-report.json)
├── style-1/ (design-tokens.json, style-guide.md)
├── style-2/ (same structure)
└── style-{variants_count}/ (same structure)
├── style-{variants_count}/ (same structure)
├── layout-strategies.json [NEW]
└── consolidation-report.json [NEW - unified report for all variants]
}
Next: /workflow:ui-design:generate --session {session_id} {IF separate: --style-variants {variants_count}} --pages "dashboard,auth"
Next: /workflow:ui-design:generate --session {session_id} {IF separate: --style-variants {variants_count} --layout-variants {layout_variants}} --pages "dashboard,auth"
Note: When called from /workflow:ui-design:auto, UI generation is triggered automatically.
```
## Output Structure
### Unified Mode
```
{base_path}/style-consolidation/
├── design-tokens.json # Merged token definitions
├── style-guide.md # Comprehensive design documentation
├── tailwind.config.js # Tailwind theme configuration
└── validation-report.json # Validation audit results
```
### Separate Mode (--keep-separate)
```
{base_path}/style-consolidation/
├── style-1/
│ ├── design-tokens.json # Style 1 token definitions
│ ├── style-guide.md # Style 1 documentation
│ ├── tailwind.config.js # Style 1 Tailwind config
│ └── validation-report.json # Style 1 validation
├── style-2/
│ └── ... (same structure)
└── style-N/
└── ... (same structure)
The generate command will now read layout strategies from layout-strategies.json.
```
## design-tokens.json Format
@@ -516,40 +603,53 @@ Complete token structure with OKLCH colors and semantic naming:
## Key Features
1. **Zero External Dependencies**
- No `gemini-wrapper`, no `codex` - pure Claude synthesis
1. **Zero External Dependencies for Style Consolidation**
- No `gemini-wrapper`, no `codex` for style synthesis - pure Claude
- Single-pass comprehensive prompt generates all outputs
2. **Dual Consolidation Modes**
- Unified: Merge N variants → 1 design system (default)
- Separate: Refine N variants → N independent systems (--keep-separate)
3. **Direct Token Merging**
3. **Dynamic Layout Strategy Generation** 🆕
- Uses Exa MCP to research current UI/UX layout trends (2024-2025)
- Generates layout strategies based on project context and modern patterns
- Adapts to project type (dashboard, marketing, SaaS, etc.)
- Balances innovation with usability
4. **Direct Token Merging**
- Reads `proposed_tokens` from style cards directly
- Intelligent conflict resolution with clear rules
4. **Complete Design System Output**
5. **Complete Design System Output**
- design-tokens.json (CSS tokens)
- style-guide.md (documentation)
- tailwind.config.js (framework integration)
- validation-report.json (quality audit)
- layout-strategies.json (dynamic layout plans)
- consolidation-report.json (quality audit & planning)
5. **Production-Ready Quality**
6. **Production-Ready Quality**
- WCAG AA accessibility validation
- OKLCH color format for perceptual uniformity
- Semantic token naming
- Complete token coverage
6. **Streamlined Workflow**
- `Load → Synthesize → Write` (3 core steps)
7. **Streamlined Workflow**
- Common phases (setup, context, completion) shared across modes
- Mode-specific synthesis clearly separated
- Reproducible with deterministic structure
- Context-aware (integrates brainstorming artifacts)
## Integration Points
- **Input**: `style-cards.json` from `/workflow:ui-design:extract` (with `proposed_tokens`)
- **Input**:
- `style-cards.json` from `/workflow:ui-design:extract` (with `proposed_tokens`)
- `--layout-variants` parameter (default: 3)
- **Output**:
- Unified: `style-consolidation/design-tokens.json` for `/workflow:ui-design:generate`
- Separate: `style-consolidation/style-{n}/design-tokens.json` for matrix mode generation
- Style Systems:
- Unified: `style-consolidation/design-tokens.json` for `/workflow:ui-design:generate`
- Separate: `style-consolidation/style-{n}/design-tokens.json` for matrix mode generation
- Layout Planning: `layout-strategies.json` consumed by `/workflow:ui-design:generate`
- Unified Reporting: `consolidation-report.json` for audit and validation
- **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md`
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
- **Next Command**: `/workflow:ui-design:generate` reads both design tokens and layout strategies

39
.claude/commands/workflow/ui-design/explore-auto.md
View File

@@ -112,13 +112,12 @@ STORE: style_variants, layout_variants
run_id = "run-$(date +%Y%m%d-%H%M%S)"
IF --session:
base_path = ".workflow/WFS-{session_id}/runs/${run_id}"
base_path = ".workflow/WFS-{session_id}/design-${run_id}"
ELSE:
session_id = "design-session-$(date +%Y%m%d-%H%M%S)"
base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}"
base_path = ".workflow/.design/${run_id}"
# Create directories
Bash(mkdir -p "${base_path}/.design/{style-extraction,style-consolidation,prototypes}")
Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
# Initialize metadata
Write({base_path}/.run-metadata.json): {
@@ -136,12 +135,6 @@ Write({base_path}/.run-metadata.json): {
"status": "in_progress"
}
# Update "latest" symlink (Windows-compatible)
IF --session:
Bash(cd ".workflow/WFS-{session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}")
ELSE:
Bash(cd ".workflow/.scratchpad/${session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}")
STORE: run_id, base_path
```
@@ -407,7 +400,7 @@ STORE: exploration_mode = exploration_mode # "page" or "component"
```bash
images_flag = --images present ? "--images \"{image_glob}\"" : ""
prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : ""
run_base_flag = "--base-path \"{base_path}/.design\""
run_base_flag = "--base-path \"{base_path}\""
command = "/workflow:ui-design:extract {run_base_flag} {images_flag} {prompt_flag} --variants {style_variants}"
SlashCommand(command)
@@ -419,15 +412,15 @@ SlashCommand(command)
### Phase 2: Style Consolidation with Separation
**Command**:
```bash
run_base_flag = "--base-path \"{base_path}/.design\""
run_base_flag = "--base-path \"{base_path}\""
# Use count-based parameter with --keep-separate for matrix mode
command = "/workflow:ui-design:consolidate {run_base_flag} --variants {style_variants} --keep-separate"
SlashCommand(command)
```
**Result**: Generates `style_variants` independent design systems:
- `.design/style-consolidation/style-1/design-tokens.json`
- `.design/style-consolidation/style-{N}/design-tokens.json`
- `style-consolidation/style-1/design-tokens.json`
- `style-consolidation/style-{N}/design-tokens.json`
**Auto-Continue**: On completion → Phase 3
@@ -436,7 +429,7 @@ SlashCommand(command)
### Phase 3: Matrix UI Generation (Mode-Aware)
**Command**:
```bash
run_base_flag = "--base-path \"{base_path}/.design\""
run_base_flag = "--base-path \"{base_path}\""
IF exploration_mode == "page":
# Page Mode: Generate full pages
@@ -620,11 +613,11 @@ Phase 4 - Design Update: Brainstorming artifacts updated
{IF batch-plan: Phase 5 - Task Generation: {task_count} implementation tasks created}
📂 Run Output: {base_path}/
├── .design/style-consolidation/ ({style_variants} design systems)
├── .design/prototypes/ ({total_prototypes} HTML/CSS files)
└── .run-metadata.json (run configuration)
├── style-consolidation/ ({style_variants} design systems)
├── prototypes/ ({total_prototypes} HTML/CSS files)
└── .run-metadata.json (run configuration)
🌐 Interactive Preview: {base_path}/.design/prototypes/compare.html
🌐 Interactive Preview: {base_path}/prototypes/compare.html
- {style_variants}×{layout_variants} matrix view with synchronized scrolling
- Zoom controls and fullscreen mode
- Selection export for implementation
@@ -659,11 +652,11 @@ Phase 3 - Matrix Generation: {style_variants}×{layout_variants}×{component_cou
Phase 4 - Design Update: Brainstorming artifacts updated
📂 Run Output: {base_path}/
├── .design/style-consolidation/ ({style_variants} design systems)
├── .design/prototypes/ ({total_prototypes} component HTML/CSS files)
└── .run-metadata.json (run configuration)
├── style-consolidation/ ({style_variants} design systems)
├── prototypes/ ({total_prototypes} component HTML/CSS files)
└── .run-metadata.json (run configuration)
🌐 Interactive Preview: {base_path}/.design/prototypes/compare.html
🌐 Interactive Preview: {base_path}/prototypes/compare.html
- {style_variants}×{layout_variants} component matrix view
- Isolated component rendering (minimal wrapper)
- Side-by-side comparison for design decisions

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

@@ -37,15 +37,16 @@ ELSE IF --prompt:
ELSE:
ERROR: "Must provide --images or --prompt"
# Detect session mode
# Detect session mode and generate run ID
run_id = "run-" + timestamp()
IF --session:
session_mode = "integrated"
session_id = {provided_session}
base_path = ".workflow/WFS-{session_id}/"
base_path = ".workflow/WFS-{session_id}/design-{run_id}/"
ELSE:
session_mode = "standalone"
session_id = "design-session-" + timestamp()
base_path = ".workflow/.scratchpad/{session_id}/"
base_path = ".workflow/.design/{run_id}/"
# Set variant count
variants_count = --variants provided ? {count} : 1
@@ -67,16 +68,55 @@ IF input_mode IN ["text", "hybrid"]:
prompt_guidance = {--prompt value}
# Create output directory
CREATE: {base_path}/.design/style-extraction/
CREATE: {base_path}/style-extraction/
```
### Phase 2: Unified Style Analysis (Claude)
### Phase 1.5: Design Trend Research (Exa MCP)
```bash
# Step 1: Load project context to inform search queries
project_context = ""
IF exists({base_path}/.brainstorming/synthesis-specification.md):
project_context = Read({base_path}/.brainstorming/synthesis-specification.md)
ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md):
project_context = Read({base_path}/.brainstorming/ui-designer/analysis.md)
# Extract hints from context and prompt
search_hints = []
IF prompt_guidance:
search_hints.append(extract_design_keywords(prompt_guidance)) # e.g., "minimalist", "dark theme", "Linear.app"
IF project_context:
search_hints.append(extract_project_type(project_context)) # e.g., "dashboard", "SaaS", "blog"
# Step 2: Search for design trends using Exa MCP
REPORT: "🔍 Researching modern design trends and color theory..."
# Build comprehensive search query
exa_queries = [
"modern UI design color palettes trends 2024 2025 {search_hints}",
"typography web design best practices system fonts {search_hints}",
"design system color theory accessibility WCAG {search_hints}",
"UI spacing rhythm layout patterns {search_hints}"
]
design_trends = {}
FOR query IN exa_queries:
category = identify_category(query) # "colors", "typography", "layout", "accessibility"
design_trends[category] = mcp__exa__get_code_context_exa(
query=query,
tokensNum="dynamic"
)
REPORT: "✅ Design research complete. Found trends for: colors, typography, layout, accessibility"
```
### Phase 2: Unified Style Analysis (Claude with Design Trends)
This is a single-pass analysis that replaces all external tool calls.
**Analysis Prompt Template**:
```
Analyze the following design references and generate {variants_count} distinct design style proposals.
Analyze the following design references and generate {variants_count} distinct design style proposals informed by current design trends.
INPUT MODE: {input_mode}
@@ -90,11 +130,28 @@ TEXT GUIDANCE: "{prompt_guidance}"
Use this to guide the aesthetic direction and feature requirements
{ENDIF}
DESIGN TRENDS RESEARCH (from web, 2024-2025):
COLOR TRENDS:
{design_trends.colors}
TYPOGRAPHY TRENDS:
{design_trends.typography}
LAYOUT PATTERNS:
{design_trends.layout}
ACCESSIBILITY GUIDELINES:
{design_trends.accessibility}
TASK: Generate {variants_count} design style variants that:
1. Each have a distinct visual identity and design philosophy
2. Use OKLCH color space for all color values
3. Include complete, production-ready design token proposals
4. Are semantically organized (brand, surface, semantic colors)
2. Incorporate modern design trends from the research above (2024-2025)
3. Balance trend awareness with timeless design principles
4. Use OKLCH color space for all color values
5. Include complete, production-ready design token proposals
6. Are semantically organized (brand, surface, semantic colors)
7. Apply current accessibility best practices from WCAG guidelines
OUTPUT FORMAT: JSON matching this exact structure:
{
@@ -143,11 +200,15 @@ OUTPUT FORMAT: JSON matching this exact structure:
RULES:
- Each variant must be distinct in visual character
- Incorporate insights from DESIGN TRENDS RESEARCH into color, typography, and spacing choices
- Balance modern trends with timeless design principles
- All colors MUST use OKLCH format: oklch(L C H / A)
- Token structures must be complete and production-ready
- Use semantic naming throughout (e.g., "brand-primary" not "color-1")
- Ensure accessibility (WCAG AA contrast ratios: 4.5:1 text, 3:1 UI)
- Ensure accessibility (WCAG AA contrast ratios: 4.5:1 text, 3:1 UI) using guidelines from research
- Apply modern typography trends (variable fonts, system font stacks, optical sizing)
- Include complete token categories for each variant
- Reference specific trends or patterns from the research when making design decisions
```
### Phase 3: Parse & Write Output
@@ -158,7 +219,7 @@ style_cards_data = parse_json(claude_response)
# Write single output file
Write({
file_path: "{base_path}/.design/style-extraction/style-cards.json",
file_path: "{base_path}/style-extraction/style-cards.json",
content: style_cards_data
})
```
@@ -169,6 +230,7 @@ Write({
TodoWrite({
todos: [
{content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"},
{content: "Research modern design trends with Exa MCP", status: "completed", activeForm: "Researching design trends"},
{content: "Analyze design references with Claude", status: "completed", activeForm: "Analyzing design"},
{content: `Generate ${variants_count} style cards with token proposals`, status: "completed", activeForm: "Generating style cards"}
]
@@ -186,7 +248,7 @@ Input mode: {input_mode}
Generated {variants_count} style variant(s):
{FOR each card: - {card.name} ({card.id})}
📂 Output: {base_path}/.design/style-extraction/style-cards.json
📂 Output: {base_path}/style-extraction/style-cards.json
Next: /workflow:ui-design:consolidate --session {session_id} --variants {variants_count}
@@ -196,7 +258,12 @@ Note: When called from /workflow:ui-design:auto, consolidation is triggered auto
## Output Structure
```
.workflow/WFS-{session}/.design/style-extraction/
.workflow/WFS-{session}/design-{run_id}/style-extraction/
└── style-cards.json # Single comprehensive output
OR (standalone mode):
.workflow/.design/{run_id}/style-extraction/
└── style-cards.json # Single comprehensive output
```
@@ -569,32 +636,45 @@ Complete structure with example values:
## Key Features
1. **Zero External Dependencies**
- No `gemini-wrapper`, no `codex` - pure Claude synthesis
- Single-pass comprehensive analysis
1. **Trend-Aware Style Generation** 🆕
- Uses Exa MCP to research current design trends (2024-2025)
- Searches for color theory, typography trends, layout patterns, and accessibility guidelines
- Generates style variants informed by modern best practices
- Balances innovation with timeless design principles
2. **Streamlined Output**
2. **Zero External Dependencies for Analysis**
- No `gemini-wrapper`, no `codex` for style synthesis - pure Claude
- Single-pass comprehensive analysis with trend integration
3. **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
3. **Flexible Input Modes**
4. **Flexible Input Modes**
- Image-only: Analyze visual references
- Text-only: Generate from descriptions
- Hybrid: Text guides image analysis
- All modes enhanced with web-based design research
4. **Reproducible Structure**
5. **Context-Aware Research**
- Extracts design keywords from user prompts (e.g., "minimalist", "Linear.app")
- Considers project type from brainstorming artifacts
- Customizes search queries based on project context
6. **Reproducible Structure**
- Same inputs = same output structure
- Deterministic JSON schema
- Content may vary based on Claude model version
- Content informed by current design trends
5. **Production-Ready Tokens**
7. **Production-Ready Tokens**
- Complete design system proposals per variant
- OKLCH color format for accessibility
- Semantic naming conventions
- WCAG AA accessibility considerations
- WCAG AA accessibility considerations from latest guidelines
- Modern typography trends (variable fonts, system stacks)
6. **Workflow Integration**
8. **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

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

@@ -2,11 +2,11 @@
name: generate
description: Generate UI prototypes in matrix mode (style × layout combinations)
usage: /workflow:ui-design:generate [--pages "<list>"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
argument-hint: "[--pages \"dashboard,auth\"] [--base-path \".workflow/WFS-xxx/runs/run-xxx/.design\"] [--style-variants 3] [--layout-variants 3]"
argument-hint: "[--pages \"dashboard,auth\"] [--base-path \".workflow/WFS-xxx/design-run-xxx\"] [--style-variants 3] [--layout-variants 3]"
examples:
- /workflow:ui-design:generate --base-path ".workflow/WFS-auth/runs/run-xxx/.design" --pages "dashboard,settings" --style-variants 3 --layout-variants 3
- /workflow:ui-design:generate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --pages "dashboard,settings" --style-variants 3 --layout-variants 3
- /workflow:ui-design:generate --session WFS-auth --pages "home,pricing" --style-variants 2 --layout-variants 2
- /workflow:ui-design:generate --base-path "./design-session-xxx/.design" --style-variants 3 --layout-variants 3
- /workflow:ui-design:generate --base-path "./.workflow/.design/run-20250109-150533" --style-variants 3 --layout-variants 3
allowed-tools: TodoWrite(*), Read(*), Write(*), Task(conceptual-planning-agent), Bash(*)
---
@@ -24,6 +24,38 @@ Generate production-ready UI prototypes (HTML/CSS) in `style × layout` matrix m
## Execution Protocol
### Phase 0: Load Layout Strategies
```bash
# Determine base path first (using same logic as Phase 1)
IF --base-path provided:
base_path = {provided_base_path}
ELSE IF --session provided:
# Find latest design run in session
base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*")
ELSE:
base_path = find_latest_path_matching(".workflow/.design/*")
# Load layout strategies from consolidation output
layout_strategies_path = "{base_path}/style-consolidation/layout-strategies.json"
VERIFY: exists(layout_strategies_path), "Layout strategies not found. Run /workflow:ui-design:consolidate first."
layout_strategies = Read(layout_strategies_path)
layout_variants = layout_strategies.layout_variants_count
REPORT: "📐 Loaded {layout_variants} layout strategies:"
FOR strategy IN layout_strategies.strategies:
REPORT: " - {strategy.name}: {strategy.description}"
# Override layout_variants if --layout-variants is provided (for manual runs)
IF --layout-variants provided:
WARN: "Overriding layout strategies count from {layout_variants} to {provided_count}"
layout_variants = {provided_count}
VALIDATE: 1 <= layout_variants <= len(layout_strategies.strategies)
# Trim strategies to match count
layout_strategies.strategies = layout_strategies.strategies[0:layout_variants]
```
### Phase 1: Path Resolution & Context Loading
```bash
@@ -35,12 +67,12 @@ ELSE IF --session provided:
ELSE:
base_path = find_latest_design_session(".workflow/.scratchpad/")
# 2. Determine variant counts
# 2. Determine style variant count (layout_variants already loaded in Phase 0)
style_variants = --style-variants OR 3 # Default to 3
layout_variants = --layout-variants OR 3 # Default to 3
VALIDATE: 1 <= style_variants <= 5
VALIDATE: 1 <= layout_variants <= 5
# Note: layout_variants is loaded from layout-strategies.json in Phase 0
# 3. Enhanced page list parsing
page_list = []
@@ -85,14 +117,62 @@ IF --session:
synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
```
### Phase 1.5: Implementation Pattern Research (Exa MCP)
```bash
# Step 1: Extract project context and technology preferences
project_context = ""
tech_stack_hints = []
IF --session:
# Load brainstorming artifacts to understand tech requirements
IF exists(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md):
project_context = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
tech_stack_hints = extract_tech_stack(project_context) # e.g., "React", "Vue", "vanilla JS"
IF exists(.workflow/WFS-{session}/.brainstorming/system-architect/analysis.md):
arch_context = Read(.workflow/WFS-{session}/.brainstorming/system-architect/analysis.md)
tech_stack_hints.extend(extract_tech_stack(arch_context))
# Step 2: Extract page types and requirements
page_types = classify_pages(page_list) # e.g., "dashboard", "auth", "settings"
layout_names = [s.name for s in layout_strategies.strategies]
REPORT: "🔍 Researching modern UI implementation patterns..."
# Step 3: Multi-dimensional implementation research using Exa MCP
exa_queries = {
"component_patterns": f"modern UI component implementation patterns {' '.join(tech_stack_hints)} 2024 2025",
"responsive_design": f"responsive web design best practices mobile-first {' '.join(page_types)} 2024",
"accessibility": f"web accessibility ARIA attributes implementation WCAG 2.2 {' '.join(page_types)}",
"html_semantics": f"semantic HTML5 structure best practices {' '.join(page_types)} modern",
"css_architecture": f"CSS architecture design tokens custom properties BEM {' '.join(tech_stack_hints)}"
}
implementation_research = {}
FOR category, query IN exa_queries.items():
REPORT: f" Searching {category}..."
implementation_research[category] = mcp__exa__get_code_context_exa(
query=query,
tokensNum="dynamic"
)
REPORT: "✅ Implementation research complete:"
REPORT: " - Component patterns and best practices"
REPORT: " - Responsive design strategies"
REPORT: " - Accessibility implementation guides"
REPORT: " - Semantic HTML structures"
REPORT: " - CSS architecture patterns"
```
### Phase 2: Optimized Matrix UI Generation
**Strategy**: Two-layer generation reduces complexity from `O(S×L×P)` to `O(L×P)`, achieving **`S` times faster** performance.
- **Layer 1**: Generate `L × P` layout templates (HTML structure + structural CSS)
- **Layer 1**: Generate `L × P` layout templates (HTML structure + structural CSS) with modern best practices
- **Layer 2**: Instantiate `S × L × P` final prototypes via fast file operations
#### Phase 2a: Layout Template Generation
#### Phase 2a: Layout Template Generation (Research-Informed)
Generate style-agnostic layout templates for each `{page} × {layout}` combination.
Total agent tasks: `layout_variants × len(page_list)`
@@ -108,7 +188,7 @@ FOR layout_id IN range(1, layout_variants + 1):
Task(conceptual-planning-agent): "
[UI_LAYOUT_TEMPLATE_GENERATION]
Generate a **style-agnostic** layout template for a specific page and layout strategy.
Generate a **style-agnostic** layout template for a specific page and layout strategy, informed by modern web development best practices.
## Context
LAYOUT_ID: {layout_id}
@@ -116,8 +196,25 @@ FOR layout_id IN range(1, layout_variants + 1):
BASE_PATH: {base_path}
{IF --session: - Requirements: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md}
## Implementation Research (from web, 2024-2025)
COMPONENT PATTERNS:
{implementation_research.component_patterns}
RESPONSIVE DESIGN:
{implementation_research.responsive_design}
ACCESSIBILITY GUIDELINES:
{implementation_research.accessibility}
HTML SEMANTICS:
{implementation_research.html_semantics}
CSS ARCHITECTURE:
{implementation_research.css_architecture}
## Task
Generate TWO files that work together as a reusable template:
Generate TWO files that work together as a reusable template, incorporating insights from the implementation research above:
**File 1**: `{page}-layout-{layout_id}.html`
- Semantic HTML5 structure WITHOUT any style-specific values
@@ -137,27 +234,13 @@ FOR layout_id IN range(1, layout_variants + 1):
- Mobile-first responsive design using token-based breakpoints
## Layout Diversity Strategy
Apply this strategy CONSISTENTLY to all styles:
Apply the following strategy from the planned layout strategies (loaded from layout-strategies.json):
{IF layout_id == 1}
**Layout 1: Classic Hierarchy**
- Traditional F-pattern reading flow
- Top navigation with sidebar
- Card-based content sections
{ELSE IF layout_id == 2}
**Layout 2: Modern Asymmetric**
- Z-pattern visual flow
- Split-screen hero sections
- Grid-based modular content
{ELSE IF layout_id == 3}
**Layout 3: Minimal Focus**
- Centered single-column content
- Floating navigation
- Generous whitespace and breathing room
{ELSE}
**Layout {layout_id}: Custom Variant**
- Develop a unique and consistent layout structure different from the standard three
{ENDIF}
**Layout ID**: {layout_id}
**Name**: {layout_strategies.strategies[layout_id - 1].name}
**Description**: {layout_strategies.strategies[layout_id - 1].description}
Apply this strategy CONSISTENTLY to all styles.
## Token Usage Requirements (STRICT)
- All colors: var(--color-brand-primary), var(--color-surface-background), etc.
@@ -165,17 +248,19 @@ FOR layout_id IN range(1, layout_variants + 1):
- All typography: var(--font-family-heading), var(--font-size-lg), etc.
- NO hardcoded values allowed
## HTML Requirements
## HTML Requirements (Apply Modern Best Practices from Research)
- Semantic HTML5 elements (<header>, <nav>, <main>, <section>, <article>)
- ARIA attributes for accessibility (role, aria-label, aria-labelledby)
- Proper heading hierarchy (h1 → h2 → h3)
- Mobile-first responsive design
- ARIA attributes for accessibility following WCAG 2.2 guidelines from research
- Proper heading hierarchy (h1 → h2 → h3) as recommended in HTML semantics research
- Mobile-first responsive design using patterns from responsive design research
- Component structure following modern patterns from component research
## CSS Requirements
## CSS Requirements (Apply Architecture Patterns from Research)
- Use CSS custom properties from design-tokens.json
- Mobile-first media queries using token breakpoints
- No inline styles
- BEM or semantic class naming
- BEM or semantic class naming following CSS architecture research
- Apply modern responsive patterns (grid, flexbox, container queries if applicable)
## Responsive Design
- Mobile: 375px+ (single column, stacked)
@@ -199,73 +284,60 @@ REPORT: "✅ Phase 2a complete: Generated {layout_variants * len(page_list)} lay
#### Phase 2b: Prototype Instantiation
Create final `S × L × P` prototypes by copying templates and injecting style-specific CSS links.
Uses **fast file operations** instead of expensive Agent calls.
Create final `S × L × P` prototypes using the optimized `ui-instantiate-prototypes.sh` script.
Uses **fast file operations** and **auto-detection** for efficient generation.
```bash
REPORT: "🚀 Phase 2b: Instantiating prototypes from templates..."
# Convert design tokens to CSS for each style
# Step 1: Convert design tokens to CSS for each style
REPORT: " Converting design tokens to CSS variables..."
FOR style_id IN range(1, style_variants + 1):
tokens_json = Read({base_path}/style-consolidation/style-{style_id}/design-tokens.json)
tokens_css = convert_json_to_css_variables(tokens_json)
Write({base_path}/style-consolidation/style-{style_id}/tokens.css, tokens_css)
REPORT: " ✓ Generated tokens.css for style-{style_id}"
# Instantiate S × L × P final prototypes
# Step 2: Use ui-instantiate-prototypes.sh script for instantiation
# The script handles:
# - Template copying with placeholder replacement
# - Implementation notes generation
# - Preview files (compare.html, index.html, PREVIEW.md)
# - Auto-detection of configuration from directory structure
# Prepare script parameters
prototypes_dir = "{base_path}/prototypes"
pages_csv = ','.join(page_list)
# Determine session ID
IF --session provided:
session_id = {session_id}
ELSE:
session_id = "standalone"
# Execute instantiation script
Bash(
cd {base_path}/prototypes/
for s in $(seq 1 {style_variants}); do
for l in $(seq 1 {layout_variants}); do
for p in {' '.join(page_list)}; do
# Define file paths
TEMPLATE_HTML="_templates/${p}-layout-${l}.html"
STRUCTURAL_CSS="./_templates/${p}-layout-${l}.css"
TOKEN_CSS="../../style-consolidation/style-${s}/tokens.css"
OUTPUT_HTML="${p}-style-${s}-layout-${l}.html"
# Copy template and replace placeholders
cp "${TEMPLATE_HTML}" "${OUTPUT_HTML}"
sed -i "s|{{STRUCTURAL_CSS}}|${STRUCTURAL_CSS}|g" "${OUTPUT_HTML}"
sed -i "s|{{TOKEN_CSS}}|${TOKEN_CSS}|g" "${OUTPUT_HTML}"
# Create implementation notes
cat > "${p}-style-${s}-layout-${l}-notes.md" <<EOF
# Implementation Notes: ${p}-style-${s}-layout-${l}
## Generation Details
- **Template**: ${TEMPLATE_HTML}
- **Structural CSS**: ${STRUCTURAL_CSS}
- **Style Tokens**: ${TOKEN_CSS}
- **Layout Strategy**: Layout ${l}
- **Style Variant**: Style ${s}
## Template Reuse
This prototype was generated from a shared layout template to ensure consistency
across all style variants. The HTML structure is identical for all ${p}-layout-${l}
prototypes, with only the design tokens (colors, fonts, spacing) varying.
## Design System Reference
Refer to \`../../style-consolidation/style-${s}/style-guide.md\` for:
- Design philosophy
- Token usage guidelines
- Component patterns
- Accessibility requirements
## Customization
To modify this prototype:
1. Edit the layout template: \`${TEMPLATE_HTML}\` (affects all styles)
2. Edit the structural CSS: \`${STRUCTURAL_CSS}\` (affects all styles)
3. Edit design tokens: \`${TOKEN_CSS}\` (affects only this style variant)
EOF
done
done
done
~/.claude/scripts/ui-instantiate-prototypes.sh \
"{prototypes_dir}" \
--session-id "{session_id}" \
--mode "page"
)
# The script auto-detects:
# - Pages from _templates/*.html files
# - Style variants from ../style-consolidation/style-* directories
# - Layout variants from _templates/*-layout-*.html pattern
# Script generates:
# 1. S × L × P 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(page_list)} final prototypes"
REPORT: " Performance: {style_variants}× faster than original approach"
REPORT: " Preview files generated: compare.html, index.html, PREVIEW.md"
```
**Performance Comparison**:
@@ -277,139 +349,48 @@ REPORT: " Performance: {style_variants}× faster than original approach"
| Speed Improvement | Baseline | **3× faster** (S times) |
| Resource Usage | High (creative generation for each combo) | Optimized (creative only for templates) |
### Phase 3: Generate Preview Files
### Phase 3: Verify Preview Files
```bash
# Read matrix visualization template
template_content = Read("~/.claude/workflows/_template-compare-matrix.html")
# Note: Preview files are now generated by ui-instantiate-prototypes.sh script
# This phase only verifies that all expected files were created
# Inject variables into template
pages_json = JSON.stringify(page_list)
run_id = extract_run_id_from_base_path({base_path})
REPORT: "🔍 Phase 3: Verifying preview files..."
injected_content = template_content
.replace("{{run_id}}", run_id)
.replace("{{style_variants}}", style_variants)
.replace("{{layout_variants}}", layout_variants)
.replace("{{pages_json}}", pages_json)
expected_files = [
"{base_path}/prototypes/compare.html",
"{base_path}/prototypes/index.html",
"{base_path}/prototypes/PREVIEW.md"
]
Write({base_path}/prototypes/compare.html, injected_content)
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
# Generate fallback design-tokens.css
Write({base_path}/prototypes/design-tokens.css):
/* Auto-generated from all style design systems */
/* Note: Each prototype links to its specific style's tokens */
IF all_present:
REPORT: "✅ Phase 3 complete: All preview files verified"
ELSE:
WARN: "⚠️ Some preview files missing - script may have failed"
REPORT: " Check Phase 2b output for errors"
# 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 */
/* Note: Each prototype links to its specific style's tokens.css */
/* See style-consolidation/style-{n}/tokens.css for actual values */
:root {
/* Fallback tokens - each HTML file should link to its style-specific tokens */
/* See style-consolidation/style-{n}/design-tokens.json for actual values */
/* This file serves as documentation only */
/* Individual prototypes use style-specific tokens */
}
# Generate simple index.html
Write({base_path}/prototypes/index.html):
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>UI Prototypes - Matrix View</title>
<style>
body { font-family: system-ui, sans-serif; max-width: 800px; margin: 2rem auto; padding: 0 1rem; }
h1 { color: #2563eb; }
.info { background: #f3f4f6; padding: 1rem; border-radius: 0.5rem; margin: 1rem 0; }
.cta { display: inline-block; background: #2563eb; color: white; padding: 0.75rem 1.5rem;
border-radius: 0.5rem; text-decoration: none; font-weight: 600; margin-top: 1rem; }
.cta:hover { background: #1d4ed8; }
.stats { display: grid; grid-template-columns: repeat(3, 1fr); gap: 1rem; margin: 1.5rem 0; }
.stat { background: white; border: 1px solid #e5e7eb; padding: 1rem; border-radius: 0.5rem; text-align: center; }
.stat-value { font-size: 2rem; font-weight: bold; color: #2563eb; }
.stat-label { color: #6b7280; font-size: 0.875rem; margin-top: 0.25rem; }
</style>
</head>
<body>
<h1>🎨 UI Prototype Matrix</h1>
<div class="info">
<p><strong>Matrix Configuration:</strong> {style_variants} styles × {layout_variants} layouts × {len(page_list)} pages</p>
<p><strong>Total Prototypes:</strong> {style_variants * layout_variants * len(page_list)}</p>
</div>
<div class="stats">
<div class="stat">
<div class="stat-value">{style_variants}</div>
<div class="stat-label">Style Variants</div>
</div>
<div class="stat">
<div class="stat-value">{layout_variants}</div>
<div class="stat-label">Layout Options</div>
</div>
<div class="stat">
<div class="stat-value">{len(page_list)}</div>
<div class="stat-label">Pages</div>
</div>
</div>
<a href="compare.html" class="cta">🔍 Open Interactive Matrix Comparison →</a>
<h2>Features</h2>
<ul>
<li>3×3 matrix grid view with synchronized scrolling</li>
<li>Zoom controls (25%, 50%, 75%, 100%)</li>
<li>Fullscreen mode for individual prototypes</li>
<li>Selection system with export functionality</li>
<li>Page switcher for multi-page comparison</li>
</ul>
<h2>Generated Pages</h2>
<ul>
{FOR page IN page_list:
<li><strong>{page}</strong>: {style_variants × layout_variants} variants</li>
}
</ul>
</body>
</html>
# Generate PREVIEW.md
Write({base_path}/prototypes/PREVIEW.md):
# UI Prototype Preview Guide
## Quick Start
1. Open `compare.html` in a modern browser
2. Use the page selector to switch between pages
3. Interact with prototypes in the 3×3 matrix
## Matrix Configuration
- **Style Variants:** {style_variants}
- **Layout Options:** {layout_variants}
- **Pages:** {page_list}
- **Total Prototypes:** {style_variants * layout_variants * len(page_list)}
## File Naming Convention
`{page}-style-{s}-layout-{l}.html`
Example: `dashboard-style-1-layout-2.html`
- Page: dashboard
- Style: Design system 1
- Layout: Layout variant 2
## Interactive Features
- **Synchronized Scroll:** All prototypes scroll together
- **Zoom Controls:** Adjust viewport scale (25%-100%)
- **Fullscreen:** Click any prototype for detailed view
- **Selection:** Mark favorites for implementation
- **Export:** Save selections as JSON
## Design System References
Each prototype uses tokens from:
`../style-consolidation/style-{s}/design-tokens.json`
Refer to corresponding `style-guide.md` for design philosophy and usage guidelines.
## Next Steps
1. Review all variants in compare.html
2. Select preferred style×layout combinations
3. Export selections for implementation planning
4. Run `/workflow:ui-design:update` to integrate chosen designs
""")
REPORT: " ✓ Generated fallback design-tokens.css"
```
### Phase 3.5: Cross-Page Consistency Validation
@@ -520,10 +501,13 @@ Run `/workflow:ui-design:update` once all issues are resolved.
```javascript
TodoWrite({
todos: [
{content: "Load layout strategies from consolidation", status: "completed", activeForm: "Loading layout strategies"},
{content: "Resolve paths and load design systems", status: "completed", activeForm: "Loading design systems"},
{content: `Generate ${layout_variants}×${page_list.length} layout templates`, status: "completed", activeForm: "Generating layout templates"},
{content: `Instantiate ${style_variants}×${layout_variants}×${page_list.length} final prototypes`, status: "completed", activeForm: "Instantiating prototypes"},
{content: "Generate interactive preview files", status: "completed", activeForm: "Generating preview"}
{content: "Research modern UI implementation patterns with Exa MCP", status: "completed", activeForm: "Researching implementation patterns"},
{content: `Generate ${layout_variants}×${page_list.length} layout templates using planned strategies`, status: "completed", activeForm: "Generating layout templates"},
{content: "Convert design tokens to CSS variables", status: "completed", activeForm: "Converting tokens"},
{content: `Instantiate ${style_variants}×${layout_variants}×${page_list.length} prototypes using script`, status: "completed", activeForm: "Running instantiation script"},
{content: "Verify preview files generation", status: "completed", activeForm: "Verifying preview files"}
]
});
```
@@ -534,15 +518,18 @@ TodoWrite({
Configuration:
- Style Variants: {style_variants}
- Layout Variants: {layout_variants}
- Layout Variants: {layout_variants} (from layout-strategies.json)
- Layout Strategies: {[s.name for s in layout_strategies.strategies]}
- Pages: {page_list}
- Total Prototypes: {style_variants * layout_variants * len(page_list)}
Performance Metrics:
- Layout Templates Generated: {layout_variants * len(page_list)} (Agent tasks)
- Prototypes Instantiated: {style_variants * layout_variants * len(page_list)} (file operations)
- Prototypes Instantiated: {style_variants * layout_variants * len(page_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
Generated Structure:
📂 {base_path}/prototypes/
@@ -595,10 +582,32 @@ Note: When called from /workflow:ui-design:auto, design-update is triggered auto
```
## Error Handling
- **No design systems found**: Run `/workflow:ui-design:consolidate --keep-separate` first
### Pre-execution Checks
- **Missing layout-strategies.json**: Error - Run `/workflow:ui-design:consolidate` first
- **No design systems found**: Error - Run `/workflow:ui-design:consolidate --keep-separate` first
- **Invalid page names**: Extract from synthesis-specification.md or error with validation message
- **Agent execution errors**: Report details, suggest retry with specific phase
- **Missing template**: Provide fallback or error with template path
- **Missing templates directory**: Verify Phase 2a completed successfully
### 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 `ui-instantiate-prototypes.sh` exists at `~/.claude/scripts/`
- Verify script has execute permissions (`chmod +x`)
- Review script output for specific error messages
- Check template files exist in `_templates/` directory
- Verify style-consolidation directory structure
- **Preview generation errors (Phase 3)**:
- Check script completed successfully
- Verify `_template-compare-matrix.html` exists
- Review Phase 2b output for warnings
### 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`
## Quality Checks
@@ -614,40 +623,67 @@ After generation, ensure:
## Key Features
1. **Optimized Template-Based Architecture**
1. **Research-Informed Implementation** 🆕
- Uses Exa MCP to research modern UI implementation patterns (2024-2025)
- Searches for component patterns, responsive design, accessibility, HTML semantics, CSS architecture
- Generates prototypes based on current web development best practices
- Context-aware: extracts tech stack hints from project brainstorming artifacts
- Multi-dimensional research: component, responsive, accessibility, semantic HTML, CSS patterns
2. **Optimized Template-Based Architecture**
- Decouples HTML structure from CSS styling
- Generates `L × P` reusable templates instead of `S × L × P` unique files
- **`S` times faster** than previous approach (typically 3× faster for S=3)
2. **Two-Layer Generation Strategy**
- Layer 1: Agent-driven creative generation of layout templates
- Layer 2: Fast file operations for prototype instantiation
3. **Two-Layer Generation Strategy**
- Layer 1: Agent-driven creative generation of layout templates (informed by research)
- Layer 2: Fast file operations for prototype instantiation (script-based)
- Reduces expensive Agent calls by ~67% (for S=3)
3. **Consistent Cross-Style Layouts**
4. **Script-Based Instantiation (v3.0)**
- Uses `ui-instantiate-prototypes.sh` for efficient file operations
- Auto-detection of configuration from directory structure
- Robust error handling with detailed reporting
- Generates implementation notes for each prototype
- Integrated preview file generation
5. **Modern Best Practices Integration**
- Component patterns from latest UI libraries and frameworks
- WCAG 2.2 accessibility implementation
- Modern responsive design (grid, flexbox, container queries)
- Semantic HTML5 structure following current standards
- CSS architecture patterns (BEM, design tokens, custom properties)
6. **Consistent Cross-Style Layouts**
- Same layout structure applied uniformly across all style variants
- Easier to compare styles directly (HTML structure is identical)
- Simplified maintenance (edit template once, affects all styles)
4. **Dynamic Style Injection**
7. **Dynamic Style Injection**
- CSS custom properties enable runtime style switching
- Each style variant has its own `tokens.css` file
- Clean separation of structure and aesthetics
5. **Interactive Visualization**
8. **Interactive Visualization**
- Full-featured compare.html from template
- Matrix grid view with synchronized scrolling
- Enhanced index.html with statistics
- Comprehensive PREVIEW.md documentation
- Per-style design system references
6. **Production-Ready Output**
- Semantic HTML5 and ARIA attributes
- Mobile-first responsive design
9. **Production-Ready Output**
- Semantic HTML5 and ARIA attributes (following latest guidelines)
- Mobile-first responsive design (modern patterns)
- Token-driven styling (no hardcoded values)
- Implementation notes for each prototype
## Integration Points
- **Input**: Per-style design-tokens.json from `/workflow:ui-design:consolidate --keep-separate`
- **Input**:
- Per-style `design-tokens.json` from `/workflow:ui-design:consolidate --keep-separate`
- **`layout-strategies.json`** from `/workflow:ui-design:consolidate` (defines layout variants)
- Optional: `synthesis-specification.md` for page requirements
- **Output**: Matrix HTML/CSS prototypes for `/workflow:ui-design:update`
- **Template**: `~/.claude/workflows/_template-compare-matrix.html` (global)
- **Context**: synthesis-specification.md for page requirements (optional)
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
- **Key Change**: Layout strategies are now externalized and planned by consolidate command

42
.claude/commands/workflow/ui-design/imitate-auto.md
View File

@@ -64,13 +64,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
run_id = "run-$(date +%Y%m%d-%H%M%S)"
IF --session:
base_path = ".workflow/WFS-{session_id}/runs/${run_id}"
base_path = ".workflow/WFS-{session_id}/design-${run_id}"
ELSE:
session_id = "imitate-session-$(date +%Y%m%d-%H%M%S)"
base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}"
base_path = ".workflow/.design/${run_id}"
# Create directories (simpler than explore-auto)
Bash(mkdir -p "${base_path}/.design/{style-extraction,style-consolidation/style-1,prototypes}")
Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation/style-1,prototypes}")
# Initialize metadata
Write({base_path}/.run-metadata.json): {
@@ -130,7 +129,7 @@ STORE: run_id, base_path, inferred_page_list = validated_pages
```bash
IF --url provided:
REPORT: "📸 Phase 0.5: Capturing screenshots..."
screenshot_dir = "{base_path}/.design/screenshots"
screenshot_dir = "{base_path}/screenshots"
Bash(mkdir -p "{screenshot_dir}")
screenshot_success = false
@@ -215,7 +214,7 @@ ELSE:
```bash
# Determine input based on screenshot capture
IF screenshot_mode == "with_screenshots":
screenshot_glob = "{base_path}/.design/screenshots/*.{png,jpg,jpeg}"
screenshot_glob = "{base_path}/screenshots/*.{png,jpg,jpeg}"
images_flag = "--images \"{screenshot_glob}\""
url_flag = ""
source_desc = "captured screenshots from {url_value}"
@@ -229,7 +228,7 @@ ELSE IF screenshot_mode == "manual_images":
source_desc = "user-provided images"
prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : ""
run_base_flag = "--base-path \"{base_path}/.design\""
run_base_flag = "--base-path \"{base_path}\""
# Construct optimized extraction prompt
enhanced_prompt = "Extract a single, high-fidelity design system that accurately imitates the visual style from {source_desc}. {prompt_text}"
@@ -256,7 +255,7 @@ SlashCommand(command)
REPORT: "🚀 Phase 2: Fast token adaptation (bypassing consolidate)"
# Read single style card
style_cards = Read({base_path}/.design/style-extraction/style-cards.json)
style_cards = Read({base_path}/style-extraction/style-cards.json)
style_card = style_cards.style_cards[0]
design_tokens = style_card.proposed_tokens
@@ -264,10 +263,10 @@ philosophy = style_card.design_philosophy
style_name = style_card.name
# Write design-tokens.json directly
Write({base_path}/.design/style-consolidation/style-1/design-tokens.json, JSON.stringify(design_tokens, null, 2))
Write({base_path}/style-consolidation/style-1/design-tokens.json, JSON.stringify(design_tokens, null, 2))
# Create minimal style-guide.md
Write({base_path}/.design/style-consolidation/style-1/style-guide.md):
Write({base_path}/style-consolidation/style-1/style-guide.md):
# Design System: {style_name}
## Design Philosophy
@@ -292,19 +291,6 @@ All tokens in `design-tokens.json` follow OKLCH color space.
*Note: Generated in imitate mode for fast replication.*
# Create minimal tailwind.config.js
Write({base_path}/.design/style-consolidation/style-1/tailwind.config.js):
module.exports = {
theme: {
extend: {
colors: ${JSON.stringify(design_tokens.colors, null, 6)},
fontFamily: ${JSON.stringify(design_tokens.typography.font_family, null, 6)},
spacing: ${JSON.stringify(design_tokens.spacing, null, 6)},
borderRadius: ${JSON.stringify(design_tokens.border_radius, null, 6)},
}
}
}
REPORT: "✅ Tokens extracted and formatted"
REPORT: " Style: {style_name}"
REPORT: " Bypassed consolidate for {performance_gain}× speed"
@@ -318,7 +304,7 @@ REPORT: " Bypassed consolidate for {performance_gain}× speed"
**Command**:
```bash
run_base_flag = "--base-path \"{base_path}/.design\""
run_base_flag = "--base-path \"{base_path}\""
pages_string = ",".join(inferred_page_list)
pages_flag = "--pages \"{pages_string}\""
@@ -349,7 +335,7 @@ IF --session:
SlashCommand(command)
ELSE:
REPORT: "ℹ️ Standalone mode: Skipping integration"
REPORT: " Prototypes at: {base_path}/.design/prototypes/"
REPORT: " Prototypes at: {base_path}/prototypes/"
```
**Completion**: Workflow complete
@@ -453,12 +439,12 @@ Phase 2 - Token Adaptation: Bypassed consolidate (⚡ {time_saved}s saved)
Phase 3 - Prototype Generation: {page_count} prototypes created
Phase 4 - Design Integration: {integrated OR "Standalone mode"}
📂 Output: {base_path}/.design/
📂 Output: {base_path}/
├── style-extraction/style-cards.json (1 style card)
├── style-consolidation/style-1/ (design tokens)
└── prototypes/ ({page_count} HTML/CSS files)
🌐 Preview: {base_path}/.design/prototypes/index.html
🌐 Preview: {base_path}/prototypes/index.html
Performance:
- Design system: ~{time}s (vs ~{consolidate_time}s with consolidate)
@@ -469,6 +455,6 @@ Performance:
Next: /workflow:plan to create implementation tasks
}
{ELSE:
Prototypes ready: {base_path}/.design/prototypes/
Prototypes ready: {base_path}/prototypes/
}
```

58
.claude/commands/workflow/ui-design/update.md
View File

@@ -30,12 +30,12 @@ Synchronize finalized design system references to brainstorming artifacts, prepa
CHECK: .workflow/.active-* marker files
VALIDATE: session_id matches active session
# Verify required design artifacts exist (file existence check only)
# Verify required design artifacts exist in latest design run
latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-*")
VERIFY:
- .design/style-consolidation/design-tokens.json
- .design/style-consolidation/style-guide.md
- .design/style-consolidation/tailwind.config.js
- .design/prototypes/*.html (at least one prototype)
- {latest_design}/style-consolidation/design-tokens.json
- {latest_design}/style-consolidation/style-guide.md
- {latest_design}/prototypes/*.html (at least one prototype)
# Prototype selection
IF --selected-prototypes provided:
@@ -43,7 +43,7 @@ IF --selected-prototypes provided:
selected_list = parse_comma_separated(--selected-prototypes)
ELSE:
AUTO-SELECT: Use all generated prototypes
selected_list = Glob(.design/prototypes/*.html)
selected_list = Glob({latest_design}/prototypes/*.html)
REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
```
@@ -76,9 +76,8 @@ Update `.brainstorming/synthesis-specification.md` with design system references
## UI/UX Guidelines
### Design System Reference
**Finalized Design Tokens**: @../.design/style-consolidation/design-tokens.json
**Style Guide**: @../.design/style-consolidation/style-guide.md
**Tailwind Configuration**: @../.design/style-consolidation/tailwind.config.js
**Finalized Design Tokens**: @../design-{run_id}/style-consolidation/design-tokens.json
**Style Guide**: @../design-{run_id}/style-consolidation/style-guide.md
### Implementation Requirements
**Token Adherence**: All UI implementations MUST use design token CSS custom properties
@@ -88,18 +87,17 @@ Update `.brainstorming/synthesis-specification.md` with design system references
### Reference Prototypes
{FOR each selected_prototype:
- **{page_name}**: @../.design/prototypes/{prototype}.html
- **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html
- Layout: {layout_strategy from notes}
}
### Design System Assets
```json
{
"design_tokens": ".design/style-consolidation/design-tokens.json",
"style_guide": ".design/style-consolidation/style-guide.md",
"tailwind_config": ".design/style-consolidation/tailwind.config.js",
"design_tokens": "design-{run_id}/style-consolidation/design-tokens.json",
"style_guide": "design-{run_id}/style-consolidation/style-guide.md",
"prototypes": [
{FOR each: ".design/prototypes/{prototype}.html"}
{FOR each: "design-{run_id}/prototypes/{prototype}.html"}
]
}
```
@@ -133,9 +131,8 @@ Create or update `.brainstorming/ui-designer/style-guide.md`:
## Design System Integration
This style guide references the finalized design system from the design refinement phase.
**Design Tokens**: @../../.design/style-consolidation/design-tokens.json
**Style Guide**: @../../.design/style-consolidation/style-guide.md
**Tailwind Config**: @../../.design/style-consolidation/tailwind.config.js
**Design Tokens**: @../../design-{run_id}/style-consolidation/design-tokens.json
**Style Guide**: @../../design-{run_id}/style-consolidation/style-guide.md
## Implementation Guidelines
1. **Use CSS Custom Properties**: All styles reference design tokens
@@ -145,13 +142,13 @@ This style guide references the finalized design system from the design refineme
## Reference Prototypes
{FOR each selected_prototype:
- **{page_name}**: @../../.design/prototypes/{prototype}.html
- **{page_name}**: @../../design-{run_id}/prototypes/{prototype}.html
}
## Token System
For complete token definitions and usage examples, see:
- Design Tokens: @../../.design/style-consolidation/design-tokens.json
- Style Guide: @../../.design/style-consolidation/style-guide.md
- Design Tokens: @../../design-{run_id}/style-consolidation/design-tokens.json
- Style Guide: @../../design-{run_id}/style-consolidation/style-guide.md
---
*Auto-generated by /workflow:ui-design:update*
@@ -190,7 +187,6 @@ Updated artifacts:
Design system assets ready for /workflow:plan:
- design-tokens.json
- style-guide.md
- tailwind.config.js
- {prototype_count} reference prototypes
Next: /workflow:plan [--agent] "<task description>"
@@ -209,18 +205,16 @@ Next: /workflow:plan [--agent] "<task description>"
**@ Reference Format** (used in synthesis-specification.md):
```
@../.design/style-consolidation/design-tokens.json
@../.design/style-consolidation/style-guide.md
@../.design/style-consolidation/tailwind.config.js
@../.design/prototypes/{prototype}.html
@../design-{run_id}/style-consolidation/design-tokens.json
@../design-{run_id}/style-consolidation/style-guide.md
@../design-{run_id}/prototypes/{prototype}.html
```
**@ Reference Format** (used in ui-designer/style-guide.md):
```
@../../.design/style-consolidation/design-tokens.json
@../../.design/style-consolidation/style-guide.md
@../../.design/style-consolidation/tailwind.config.js
@../../.design/prototypes/{prototype}.html
@../../design-{run_id}/style-consolidation/design-tokens.json
@../../design-{run_id}/style-consolidation/style-guide.md
@../../design-{run_id}/prototypes/{prototype}.html
```
## Integration with /workflow:plan
@@ -243,9 +237,9 @@ After this update, `/workflow:plan` will discover design assets through:
"task_id": "IMPL-001",
"context": {
"design_system": {
"tokens": ".design/style-consolidation/design-tokens.json",
"style_guide": ".design/style-consolidation/style-guide.md",
"prototypes": [".design/prototypes/dashboard-variant-1.html"]
"tokens": "design-{run_id}/style-consolidation/design-tokens.json",
"style_guide": "design-{run_id}/style-consolidation/style-guide.md",
"prototypes": ["design-{run_id}/prototypes/dashboard-variant-1.html"]
}
}
}

784
.claude/scripts/ui-instantiate-prototypes.sh Normal file
View File

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

13
.claude/workflows/workflow-architecture.md
View File

@@ -276,6 +276,13 @@ All workflows use the same file structure definition regardless of complexity. *
│ ├── execute-*-[timestamp].md # Ad-hoc implementation logs
│ └── codex-execute-*-[timestamp].md # Multi-stage execution logs
│
├── [.design/] # Standalone UI design outputs (created when needed)
│ └── run-[timestamp]/ # Timestamped design runs without session
│ ├── style-extraction/ # Style analysis results
│ ├── style-consolidation/ # Design system tokens
│ ├── prototypes/ # Generated HTML/CSS prototypes
│ └── .run-metadata.json # Run configuration
│
└── WFS-[topic-slug]/
├── workflow-session.json # Session metadata and state (REQUIRED)
├── [.brainstorming/] # Optional brainstorming phase (created when needed)
@@ -289,6 +296,11 @@ All workflows use the same file structure definition regardless of complexity. *
├── [.summaries/] # Task completion summaries (created when tasks complete)
│ ├── IMPL-*-summary.md # Main task summaries
│ └── IMPL-*.*-summary.md # Subtask summaries
├── [design-*/] # UI design outputs (created by ui-design workflows)
│ ├── style-extraction/ # Style analysis results
│ ├── style-consolidation/ # Design system tokens
│ ├── prototypes/ # Generated HTML/CSS prototypes
│ └── .run-metadata.json # Run configuration
└── .task/ # Task definitions (REQUIRED)
├── IMPL-*.json # Main task definitions
└── IMPL-*.*.json # Subtask definitions (created dynamically)
@@ -299,6 +311,7 @@ All workflows use the same file structure definition regardless of complexity. *
- **On-Demand Creation**: Other directories created when first needed
- **Dynamic Files**: Subtask JSON files created during task decomposition
- **Scratchpad Usage**: `.scratchpad/` created when CLI commands run without active session
- **Design Usage**: `design-{timestamp}/` created by UI design workflows, `.design/` for standalone design runs
#### Scratchpad Directory (.scratchpad/)
**Purpose**: Centralized location for non-session-specific CLI outputs