catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-11 02:33:51 +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 name: consolidate
description: Consolidate style variants into unified or separate design systems 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] usage: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--keep-separate] [--layout-variants <count>]
argument-hint: "[--base-path \".workflow/WFS-xxx/runs/run-xxx/.design\"] [--variants 3] [--keep-separate]" argument-hint: "[--base-path \".workflow/WFS-xxx/design-run-xxx\"] [--variants 3] [--keep-separate] [--layout-variants 3]"
examples: examples:
- /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/latest/.design" --variants 3 --keep-separate - /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 - /workflow:ui-design:consolidate --session WFS-auth --variants 2 --layout-variants 2
- /workflow:ui-design:consolidate --base-path "./design-session-xxx/.design" - /workflow:ui-design:consolidate --base-path "./.workflow/.design/run-20250109-150533" --layout-variants 3
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*) allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*)
--- ---
# Style Consolidation Command # Design System Consolidation & Layout Planning Command
## Overview ## 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 ## Core Philosophy
- **Design Planning Hub**: Centralizes both style consolidation and layout strategy planning
- **Claude-Native**: 100% Claude-driven consolidation, no external tools - **Claude-Native**: 100% Claude-driven consolidation, no external tools
- **Token Merging**: Combines `proposed_tokens` from selected variants - **Token Merging**: Combines `proposed_tokens` from selected variants
- **Layout Strategy Definition**: Plans and documents layout variants for generation
- **Intelligent Synthesis**: Resolves conflicts, ensures consistency - **Intelligent Synthesis**: Resolves conflicts, ensures consistency
- **Production-Ready**: Complete design system(s) with documentation - **Production-Ready**: Complete design system(s) with documentation
- **Dual Mode**: Unified (1 merged system) or Separate (N independent systems) - **Dual Mode**: Unified (1 merged system) or Separate (N independent systems)
## Execution Protocol ## 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 ```bash
# Determine base path # Determine base path
IF --base-path provided: IF --base-path provided:
base_path = {provided_base_path} base_path = {provided_base_path}
ELSE IF --session provided: 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: ELSE:
base_path = find_latest_design_session(".workflow/.scratchpad/") base_path = find_latest_path_matching(".workflow/.design/*")
# Verify extraction output exists # Verify extraction output exists
style_cards_path = "{base_path}/style-extraction/style-cards.json" 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) total_variants = len(style_cards.style_cards)
``` ```
### Phase 2: Variant Selection & Mode Determination #### Phase 2: Variant Selection & Mode Determination
```bash ```bash
# Determine how many variants to consolidate # Determine how many variants to consolidate
@@ -67,7 +74,86 @@ ELSE:
REPORT: "Mode: Unified - merging {variants_count} variants into one design system" 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 ```bash
# Load brainstorming context if available # 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) 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. 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) - UI components meet WCAG AA (3:1 minimum)
- Focus indicators are clearly visible - Focus indicators are clearly visible
FILE 3: tailwind.config.js FILE 3: consolidation-report.json
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
{ {
"session_id": "{session_id}", "session_id": "{session_id}",
"consolidated_variants": {variant_ids}, "consolidation_mode": "unified",
"timestamp": "{ISO timestamp}", "timestamp": "{ISO timestamp}",
"validation_results": { "style_systems": {
"colors": { "total": {count}, "wcag_aa_compliant": {count}, "warnings": [{issues}] }, "consolidated_variants": {variant_ids},
"typography": { "font_families": {count}, "scale_sizes": {count} }, "variant_count": {selected_variants.length},
"spacing": { "scale_values": {count} }, "validation_results": {
"accessibility": { "status": "pass|warnings", "issues": [{list}] }, "colors": { "total": {count}, "wcag_aa_compliant": {count}, "warnings": [{issues}] },
"completeness": { "typography": { "font_families": {count}, "scale_sizes": {count} },
"required_categories": ["colors", "typography", "spacing", "border_radius", "shadows", "breakpoints"], "spacing": { "scale_values": {count} },
"present_categories": [{list}], "accessibility": { "status": "pass|warnings", "issues": [{list}] },
"missing_categories": [{list if any}] "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 ===== ===== style-guide.md =====
{Markdown content} {Markdown content}
===== tailwind.config.js ===== ===== consolidation-report.json =====
{JavaScript content}
===== validation-report.json =====
{JSON content} {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. 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 6. **OKLCH Format**: All colors must use oklch(L C H / A) format
7. **Design Philosophy**: Expand and articulate the variant's design philosophy 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: RESPONSE FORMAT:
Provide each file's content in clearly labeled sections: 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 ===== ===== style-guide.md =====
{Markdown content} {Markdown content}
===== tailwind.config.js =====
{JavaScript content}
===== validation-report.json =====
{JSON content}
``` ```
**Output Location**: `{base_path}/style-consolidation/style-{n}/` **Phase 5B: Separate Output**
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
```bash ```bash
# Parse each variant's response # Parse each variant's response
FOR variant_id IN range(1, variants_count + 1): 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}/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}/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 ```javascript
TodoWrite({ TodoWrite({
todos: [ todos: [
{content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"}, {content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"},
{content: "Select variants and determine mode", status: "completed", activeForm: "Selecting variants"}, {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: "Load design context from brainstorming", status: "completed", activeForm: "Loading context"},
{content: "Synthesize design system(s) with Claude", status: "completed", activeForm: "Synthesizing design system"}, {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**: **Completion Message**:
``` ```
✅ Style consolidation complete for session: {session_id} ✅ Design consolidation & layout planning complete for session: {session_id}
Mode: {consolidation_mode} Mode: {consolidation_mode}
Consolidated {selected_variants.length} variant(s): Consolidated {selected_variants.length} style variant(s):
{FOR each variant: - {variant.name} ({variant.id})} {FOR each variant: - {variant.name} ({variant.id})}
Layout Strategies Planned: {layout_variants}
{FOR each strategy: - Layout {strategy.id}: {strategy.name}}
{IF unified mode: {IF unified mode:
Validation Summary: Validation Summary:
- Colors: {total_colors} (WCAG AA: {compliant_count}/{total_colors}) - Colors: {total_colors} (WCAG AA: {compliant_count}/{total_colors})
@@ -356,47 +465,25 @@ Validation Summary:
📂 Output: {base_path}/style-consolidation/ 📂 Output: {base_path}/style-consolidation/
├── design-tokens.json ├── design-tokens.json
├── style-guide.md ├── style-guide.md
├── tailwind.config.js ├── layout-strategies.json [NEW]
└── validation-report.json └── consolidation-report.json [NEW - replaces validation-report.json]
} }
{IF separate mode: {IF separate mode:
Generated {variants_count} independent design systems: Generated {variants_count} independent design systems:
📂 Output: {base_path}/style-consolidation/ 📂 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-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. Note: When called from /workflow:ui-design:auto, UI generation is triggered automatically.
``` The generate command will now read layout strategies from layout-strategies.json.
## 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)
``` ```
## design-tokens.json Format ## design-tokens.json Format
@@ -516,40 +603,53 @@ Complete token structure with OKLCH colors and semantic naming:
## Key Features ## Key Features
1. **Zero External Dependencies** 1. **Zero External Dependencies for Style Consolidation**
- No `gemini-wrapper`, no `codex` - pure Claude synthesis - No `gemini-wrapper`, no `codex` for style synthesis - pure Claude
- Single-pass comprehensive prompt generates all outputs - Single-pass comprehensive prompt generates all outputs
2. **Dual Consolidation Modes** 2. **Dual Consolidation Modes**
- Unified: Merge N variants → 1 design system (default) - Unified: Merge N variants → 1 design system (default)
- Separate: Refine N variants → N independent systems (--keep-separate) - 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 - Reads `proposed_tokens` from style cards directly
- Intelligent conflict resolution with clear rules - Intelligent conflict resolution with clear rules
4. **Complete Design System Output** 5. **Complete Design System Output**
- design-tokens.json (CSS tokens) - design-tokens.json (CSS tokens)
- style-guide.md (documentation) - style-guide.md (documentation)
- tailwind.config.js (framework integration) - layout-strategies.json (dynamic layout plans)
- validation-report.json (quality audit) - consolidation-report.json (quality audit & planning)
5. **Production-Ready Quality** 6. **Production-Ready Quality**
- WCAG AA accessibility validation - WCAG AA accessibility validation
- OKLCH color format for perceptual uniformity - OKLCH color format for perceptual uniformity
- Semantic token naming - Semantic token naming
- Complete token coverage - Complete token coverage
6. **Streamlined Workflow** 7. **Streamlined Workflow**
- `Load → Synthesize → Write` (3 core steps) - Common phases (setup, context, completion) shared across modes
- Mode-specific synthesis clearly separated
- Reproducible with deterministic structure - Reproducible with deterministic structure
- Context-aware (integrates brainstorming artifacts) - Context-aware (integrates brainstorming artifacts)
## Integration Points ## 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**: - **Output**:
- Unified: `style-consolidation/design-tokens.json` for `/workflow:ui-design:generate` - Style Systems:
- Separate: `style-consolidation/style-{n}/design-tokens.json` for matrix mode generation - 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` - **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md`
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow - **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)" run_id = "run-$(date +%Y%m%d-%H%M%S)"
IF --session: IF --session:
base_path = ".workflow/WFS-{session_id}/runs/${run_id}" base_path = ".workflow/WFS-{session_id}/design-${run_id}"
ELSE: ELSE:
session_id = "design-session-$(date +%Y%m%d-%H%M%S)" base_path = ".workflow/.design/${run_id}"
base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}"
# Create directories # 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 # Initialize metadata
Write({base_path}/.run-metadata.json): { Write({base_path}/.run-metadata.json): {
@@ -136,12 +135,6 @@ Write({base_path}/.run-metadata.json): {
"status": "in_progress" "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 STORE: run_id, base_path
``` ```
@@ -407,7 +400,7 @@ STORE: exploration_mode = exploration_mode # "page" or "component"
```bash ```bash
images_flag = --images present ? "--images \"{image_glob}\"" : "" images_flag = --images present ? "--images \"{image_glob}\"" : ""
prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : "" 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}" command = "/workflow:ui-design:extract {run_base_flag} {images_flag} {prompt_flag} --variants {style_variants}"
SlashCommand(command) SlashCommand(command)
@@ -419,15 +412,15 @@ SlashCommand(command)
### Phase 2: Style Consolidation with Separation ### Phase 2: Style Consolidation with Separation
**Command**: **Command**:
```bash ```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 # Use count-based parameter with --keep-separate for matrix mode
command = "/workflow:ui-design:consolidate {run_base_flag} --variants {style_variants} --keep-separate" command = "/workflow:ui-design:consolidate {run_base_flag} --variants {style_variants} --keep-separate"
SlashCommand(command) SlashCommand(command)
``` ```
**Result**: Generates `style_variants` independent design systems: **Result**: Generates `style_variants` independent design systems:
- `.design/style-consolidation/style-1/design-tokens.json` - `style-consolidation/style-1/design-tokens.json`
- `.design/style-consolidation/style-{N}/design-tokens.json` - `style-consolidation/style-{N}/design-tokens.json`
**Auto-Continue**: On completion → Phase 3 **Auto-Continue**: On completion → Phase 3
@@ -436,7 +429,7 @@ SlashCommand(command)
### Phase 3: Matrix UI Generation (Mode-Aware) ### Phase 3: Matrix UI Generation (Mode-Aware)
**Command**: **Command**:
```bash ```bash
run_base_flag = "--base-path \"{base_path}/.design\"" run_base_flag = "--base-path \"{base_path}\""
IF exploration_mode == "page": IF exploration_mode == "page":
# Page Mode: Generate full pages # 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} {IF batch-plan: Phase 5 - Task Generation: {task_count} implementation tasks created}
📂 Run Output: {base_path}/ 📂 Run Output: {base_path}/
├── .design/style-consolidation/ ({style_variants} design systems) ├── style-consolidation/ ({style_variants} design systems)
├── .design/prototypes/ ({total_prototypes} HTML/CSS files) ├── prototypes/ ({total_prototypes} HTML/CSS files)
└── .run-metadata.json (run configuration) └── .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 - {style_variants}×{layout_variants} matrix view with synchronized scrolling
- Zoom controls and fullscreen mode - Zoom controls and fullscreen mode
- Selection export for implementation - 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 Phase 4 - Design Update: Brainstorming artifacts updated
📂 Run Output: {base_path}/ 📂 Run Output: {base_path}/
├── .design/style-consolidation/ ({style_variants} design systems) ├── style-consolidation/ ({style_variants} design systems)
├── .design/prototypes/ ({total_prototypes} component HTML/CSS files) ├── prototypes/ ({total_prototypes} component HTML/CSS files)
└── .run-metadata.json (run configuration) └── .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 - {style_variants}×{layout_variants} component matrix view
- Isolated component rendering (minimal wrapper) - Isolated component rendering (minimal wrapper)
- Side-by-side comparison for design decisions - 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: ELSE:
ERROR: "Must provide --images or --prompt" ERROR: "Must provide --images or --prompt"
# Detect session mode # Detect session mode and generate run ID
run_id = "run-" + timestamp()
IF --session: IF --session:
session_mode = "integrated" session_mode = "integrated"
session_id = {provided_session} session_id = {provided_session}
base_path = ".workflow/WFS-{session_id}/" base_path = ".workflow/WFS-{session_id}/design-{run_id}/"
ELSE: ELSE:
session_mode = "standalone" session_mode = "standalone"
session_id = "design-session-" + timestamp() base_path = ".workflow/.design/{run_id}/"
base_path = ".workflow/.scratchpad/{session_id}/"
# Set variant count # Set variant count
variants_count = --variants provided ? {count} : 1 variants_count = --variants provided ? {count} : 1
@@ -67,16 +68,55 @@ IF input_mode IN ["text", "hybrid"]:
prompt_guidance = {--prompt value} prompt_guidance = {--prompt value}
# Create output directory # 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. This is a single-pass analysis that replaces all external tool calls.
**Analysis Prompt Template**: **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} INPUT MODE: {input_mode}
@@ -90,11 +130,28 @@ TEXT GUIDANCE: "{prompt_guidance}"
Use this to guide the aesthetic direction and feature requirements Use this to guide the aesthetic direction and feature requirements
{ENDIF} {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: TASK: Generate {variants_count} design style variants that:
1. Each have a distinct visual identity and design philosophy 1. Each have a distinct visual identity and design philosophy
2. Use OKLCH color space for all color values 2. Incorporate modern design trends from the research above (2024-2025)
3. Include complete, production-ready design token proposals 3. Balance trend awareness with timeless design principles
4. Are semantically organized (brand, surface, semantic colors) 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: OUTPUT FORMAT: JSON matching this exact structure:
{ {
@@ -143,11 +200,15 @@ OUTPUT FORMAT: JSON matching this exact structure:
RULES: RULES:
- Each variant must be distinct in visual character - 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) - All colors MUST use OKLCH format: oklch(L C H / A)
- Token structures must be complete and production-ready - Token structures must be complete and production-ready
- Use semantic naming throughout (e.g., "brand-primary" not "color-1") - 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 - Include complete token categories for each variant
- Reference specific trends or patterns from the research when making design decisions
``` ```
### Phase 3: Parse & Write Output ### Phase 3: Parse & Write Output
@@ -158,7 +219,7 @@ style_cards_data = parse_json(claude_response)
# Write single output file # Write single output file
Write({ Write({
file_path: "{base_path}/.design/style-extraction/style-cards.json", file_path: "{base_path}/style-extraction/style-cards.json",
content: style_cards_data content: style_cards_data
}) })
``` ```
@@ -169,6 +230,7 @@ Write({
TodoWrite({ TodoWrite({
todos: [ todos: [
{content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"}, {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: "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"} {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): Generated {variants_count} style variant(s):
{FOR each card: - {card.name} ({card.id})} {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} 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 ## 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 └── style-cards.json # Single comprehensive output
``` ```
@@ -569,32 +636,45 @@ Complete structure with example values:
## Key Features ## Key Features
1. **Zero External Dependencies** 1. **Trend-Aware Style Generation** 🆕
- No `gemini-wrapper`, no `codex` - pure Claude synthesis - Uses Exa MCP to research current design trends (2024-2025)
- Single-pass comprehensive analysis - 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 - Single file (`style-cards.json`) vs. multiple scattered files
- Eliminates `semantic_style_analysis.json`, `design-tokens.json`, `tailwind-tokens.js` clutter - Eliminates `semantic_style_analysis.json`, `design-tokens.json`, `tailwind-tokens.js` clutter
- Each variant contains complete token proposals embedded - Each variant contains complete token proposals embedded
3. **Flexible Input Modes** 4. **Flexible Input Modes**
- Image-only: Analyze visual references - Image-only: Analyze visual references
- Text-only: Generate from descriptions - Text-only: Generate from descriptions
- Hybrid: Text guides image analysis - 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 - Same inputs = same output structure
- Deterministic JSON schema - 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 - Complete design system proposals per variant
- OKLCH color format for accessibility - OKLCH color format for accessibility
- Semantic naming conventions - 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 - Integrated mode: Works within existing workflow sessions
- Standalone mode: Auto-creates session in scratchpad - Standalone mode: Auto-creates session in scratchpad
- Context-aware: Can reference synthesis-specification.md or ui-designer/analysis.md - 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 name: generate
description: Generate UI prototypes in matrix mode (style × layout combinations) 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>] 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: 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 --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(*) 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 ## 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 ### Phase 1: Path Resolution & Context Loading
```bash ```bash
@@ -35,12 +67,12 @@ ELSE IF --session provided:
ELSE: ELSE:
base_path = find_latest_design_session(".workflow/.scratchpad/") 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 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 <= 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 # 3. Enhanced page list parsing
page_list = [] page_list = []
@@ -85,14 +117,62 @@ IF --session:
synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) 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 ### 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. **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 - **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. Generate style-agnostic layout templates for each `{page} × {layout}` combination.
Total agent tasks: `layout_variants × len(page_list)` 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): " Task(conceptual-planning-agent): "
[UI_LAYOUT_TEMPLATE_GENERATION] [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 ## Context
LAYOUT_ID: {layout_id} LAYOUT_ID: {layout_id}
@@ -116,8 +196,25 @@ FOR layout_id IN range(1, layout_variants + 1):
BASE_PATH: {base_path} BASE_PATH: {base_path}
{IF --session: - Requirements: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md} {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 ## 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` **File 1**: `{page}-layout-{layout_id}.html`
- Semantic HTML5 structure WITHOUT any style-specific values - 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 - Mobile-first responsive design using token-based breakpoints
## Layout Diversity Strategy ## 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 ID**: {layout_id}
**Layout 1: Classic Hierarchy** **Name**: {layout_strategies.strategies[layout_id - 1].name}
- Traditional F-pattern reading flow **Description**: {layout_strategies.strategies[layout_id - 1].description}
- Top navigation with sidebar
- Card-based content sections Apply this strategy CONSISTENTLY to all styles.
{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}
## Token Usage Requirements (STRICT) ## Token Usage Requirements (STRICT)
- All colors: var(--color-brand-primary), var(--color-surface-background), etc. - 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. - All typography: var(--font-family-heading), var(--font-size-lg), etc.
- NO hardcoded values allowed - NO hardcoded values allowed
## HTML Requirements ## HTML Requirements (Apply Modern Best Practices from Research)
- Semantic HTML5 elements (<header>, <nav>, <main>, <section>, <article>) - Semantic HTML5 elements (<header>, <nav>, <main>, <section>, <article>)
- ARIA attributes for accessibility (role, aria-label, aria-labelledby) - ARIA attributes for accessibility following WCAG 2.2 guidelines from research
- Proper heading hierarchy (h1 → h2 → h3) - Proper heading hierarchy (h1 → h2 → h3) as recommended in HTML semantics research
- Mobile-first responsive design - 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 - Use CSS custom properties from design-tokens.json
- Mobile-first media queries using token breakpoints - Mobile-first media queries using token breakpoints
- No inline styles - 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 ## Responsive Design
- Mobile: 375px+ (single column, stacked) - Mobile: 375px+ (single column, stacked)
@@ -199,73 +284,60 @@ REPORT: "✅ Phase 2a complete: Generated {layout_variants * len(page_list)} lay
#### Phase 2b: Prototype Instantiation #### Phase 2b: Prototype Instantiation
Create final `S × L × P` prototypes by copying templates and injecting style-specific CSS links. Create final `S × L × P` prototypes using the optimized `ui-instantiate-prototypes.sh` script.
Uses **fast file operations** instead of expensive Agent calls. Uses **fast file operations** and **auto-detection** for efficient generation.
```bash ```bash
REPORT: "🚀 Phase 2b: Instantiating prototypes from templates..." 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): FOR style_id IN range(1, style_variants + 1):
tokens_json = Read({base_path}/style-consolidation/style-{style_id}/design-tokens.json) tokens_json = Read({base_path}/style-consolidation/style-{style_id}/design-tokens.json)
tokens_css = convert_json_to_css_variables(tokens_json) tokens_css = convert_json_to_css_variables(tokens_json)
Write({base_path}/style-consolidation/style-{style_id}/tokens.css, tokens_css) 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( Bash(
cd {base_path}/prototypes/ ~/.claude/scripts/ui-instantiate-prototypes.sh \
"{prototypes_dir}" \
for s in $(seq 1 {style_variants}); do --session-id "{session_id}" \
for l in $(seq 1 {layout_variants}); do --mode "page"
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
) )
# 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: "✅ Phase 2b complete: Instantiated {style_variants * layout_variants * len(page_list)} final prototypes"
REPORT: " Performance: {style_variants}× faster than original approach" REPORT: " Performance: {style_variants}× faster than original approach"
REPORT: " Preview files generated: compare.html, index.html, PREVIEW.md"
``` ```
**Performance Comparison**: **Performance Comparison**:
@@ -277,139 +349,48 @@ REPORT: " Performance: {style_variants}× faster than original approach"
| Speed Improvement | Baseline | **3× faster** (S times) | | Speed Improvement | Baseline | **3× faster** (S times) |
| Resource Usage | High (creative generation for each combo) | Optimized (creative only for templates) | | Resource Usage | High (creative generation for each combo) | Optimized (creative only for templates) |
### Phase 3: Generate Preview Files ### Phase 3: Verify Preview Files
```bash ```bash
# Read matrix visualization template # Note: Preview files are now generated by ui-instantiate-prototypes.sh script
template_content = Read("~/.claude/workflows/_template-compare-matrix.html") # This phase only verifies that all expected files were created
# Inject variables into template REPORT: "🔍 Phase 3: Verifying preview files..."
pages_json = JSON.stringify(page_list)
run_id = extract_run_id_from_base_path({base_path})
injected_content = template_content expected_files = [
.replace("{{run_id}}", run_id) "{base_path}/prototypes/compare.html",
.replace("{{style_variants}}", style_variants) "{base_path}/prototypes/index.html",
.replace("{{layout_variants}}", layout_variants) "{base_path}/prototypes/PREVIEW.md"
.replace("{{pages_json}}", pages_json) ]
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 IF all_present:
Write({base_path}/prototypes/design-tokens.css): REPORT: "✅ Phase 3 complete: All preview files verified"
/* Auto-generated from all style design systems */ ELSE:
/* Note: Each prototype links to its specific style's tokens */ 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 { :root {
/* Fallback tokens - each HTML file should link to its style-specific tokens */ /* This file serves as documentation only */
/* See style-consolidation/style-{n}/design-tokens.json for actual values */ /* Individual prototypes use style-specific tokens */
} }
""")
# Generate simple index.html REPORT: " ✓ Generated fallback design-tokens.css"
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
``` ```
### Phase 3.5: Cross-Page Consistency Validation ### Phase 3.5: Cross-Page Consistency Validation
@@ -520,10 +501,13 @@ Run `/workflow:ui-design:update` once all issues are resolved.
```javascript ```javascript
TodoWrite({ TodoWrite({
todos: [ 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: "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: "Research modern UI implementation patterns with Exa MCP", status: "completed", activeForm: "Researching implementation patterns"},
{content: `Instantiate ${style_variants}×${layout_variants}×${page_list.length} final prototypes`, status: "completed", activeForm: "Instantiating prototypes"}, {content: `Generate ${layout_variants}×${page_list.length} layout templates using planned strategies`, status: "completed", activeForm: "Generating layout templates"},
{content: "Generate interactive preview files", status: "completed", activeForm: "Generating preview"} {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: Configuration:
- Style Variants: {style_variants} - 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} - Pages: {page_list}
- Total Prototypes: {style_variants * layout_variants * len(page_list)} - Total Prototypes: {style_variants * layout_variants * len(page_list)}
Performance Metrics: Performance Metrics:
- Layout Templates Generated: {layout_variants * len(page_list)} (Agent tasks) - 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 - Speed Improvement: {style_variants}× faster than previous approach
- Resource Efficiency: {100 * (1 - 1/style_variants)}% reduction in Agent calls - Resource Efficiency: {100 * (1 - 1/style_variants)}% reduction in Agent calls
- Script: ui-instantiate-prototypes.sh v3.0 with auto-detection
Generated Structure: Generated Structure:
📂 {base_path}/prototypes/ 📂 {base_path}/prototypes/
@@ -595,10 +582,32 @@ Note: When called from /workflow:ui-design:auto, design-update is triggered auto
``` ```
## Error Handling ## 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 - **Invalid page names**: Extract from synthesis-specification.md or error with validation message
- **Agent execution errors**: Report details, suggest retry with specific phase - **Missing templates directory**: Verify Phase 2a completed successfully
- **Missing template**: Provide fallback or error with template path
### 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 ## Quality Checks
@@ -614,40 +623,67 @@ After generation, ensure:
## Key Features ## 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 - Decouples HTML structure from CSS styling
- Generates `L × P` reusable templates instead of `S × L × P` unique files - Generates `L × P` reusable templates instead of `S × L × P` unique files
- **`S` times faster** than previous approach (typically 3× faster for S=3) - **`S` times faster** than previous approach (typically 3× faster for S=3)
2. **Two-Layer Generation Strategy** 3. **Two-Layer Generation Strategy**
- Layer 1: Agent-driven creative generation of layout templates - Layer 1: Agent-driven creative generation of layout templates (informed by research)
- Layer 2: Fast file operations for prototype instantiation - Layer 2: Fast file operations for prototype instantiation (script-based)
- Reduces expensive Agent calls by ~67% (for S=3) - 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 - Same layout structure applied uniformly across all style variants
- Easier to compare styles directly (HTML structure is identical) - Easier to compare styles directly (HTML structure is identical)
- Simplified maintenance (edit template once, affects all styles) - Simplified maintenance (edit template once, affects all styles)
4. **Dynamic Style Injection** 7. **Dynamic Style Injection**
- CSS custom properties enable runtime style switching - CSS custom properties enable runtime style switching
- Each style variant has its own `tokens.css` file - Each style variant has its own `tokens.css` file
- Clean separation of structure and aesthetics - Clean separation of structure and aesthetics
5. **Interactive Visualization** 8. **Interactive Visualization**
- Full-featured compare.html from template - Full-featured compare.html from template
- Matrix grid view with synchronized scrolling - Matrix grid view with synchronized scrolling
- Enhanced index.html with statistics
- Comprehensive PREVIEW.md documentation
- Per-style design system references - Per-style design system references
6. **Production-Ready Output** 9. **Production-Ready Output**
- Semantic HTML5 and ARIA attributes - Semantic HTML5 and ARIA attributes (following latest guidelines)
- Mobile-first responsive design - Mobile-first responsive design (modern patterns)
- Token-driven styling (no hardcoded values) - Token-driven styling (no hardcoded values)
- Implementation notes for each prototype
## Integration Points ## 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` - **Output**: Matrix HTML/CSS prototypes for `/workflow:ui-design:update`
- **Template**: `~/.claude/workflows/_template-compare-matrix.html` (global) - **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 - **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)" run_id = "run-$(date +%Y%m%d-%H%M%S)"
IF --session: IF --session:
base_path = ".workflow/WFS-{session_id}/runs/${run_id}" base_path = ".workflow/WFS-{session_id}/design-${run_id}"
ELSE: ELSE:
session_id = "imitate-session-$(date +%Y%m%d-%H%M%S)" base_path = ".workflow/.design/${run_id}"
base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}"
# Create directories (simpler than explore-auto) # 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 # Initialize metadata
Write({base_path}/.run-metadata.json): { Write({base_path}/.run-metadata.json): {
@@ -130,7 +129,7 @@ STORE: run_id, base_path, inferred_page_list = validated_pages
```bash ```bash
IF --url provided: IF --url provided:
REPORT: "📸 Phase 0.5: Capturing screenshots..." REPORT: "📸 Phase 0.5: Capturing screenshots..."
screenshot_dir = "{base_path}/.design/screenshots" screenshot_dir = "{base_path}/screenshots"
Bash(mkdir -p "{screenshot_dir}") Bash(mkdir -p "{screenshot_dir}")
screenshot_success = false screenshot_success = false
@@ -215,7 +214,7 @@ ELSE:
```bash ```bash
# Determine input based on screenshot capture # Determine input based on screenshot capture
IF screenshot_mode == "with_screenshots": 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}\"" images_flag = "--images \"{screenshot_glob}\""
url_flag = "" url_flag = ""
source_desc = "captured screenshots from {url_value}" source_desc = "captured screenshots from {url_value}"
@@ -229,7 +228,7 @@ ELSE IF screenshot_mode == "manual_images":
source_desc = "user-provided images" source_desc = "user-provided images"
prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : "" 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 # Construct optimized extraction prompt
enhanced_prompt = "Extract a single, high-fidelity design system that accurately imitates the visual style from {source_desc}. {prompt_text}" 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)" REPORT: "🚀 Phase 2: Fast token adaptation (bypassing consolidate)"
# Read single style card # 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] style_card = style_cards.style_cards[0]
design_tokens = style_card.proposed_tokens design_tokens = style_card.proposed_tokens
@@ -264,10 +263,10 @@ philosophy = style_card.design_philosophy
style_name = style_card.name style_name = style_card.name
# Write design-tokens.json directly # 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 # 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 System: {style_name}
## Design Philosophy ## Design Philosophy
@@ -292,19 +291,6 @@ All tokens in `design-tokens.json` follow OKLCH color space.
*Note: Generated in imitate mode for fast replication.* *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: "✅ Tokens extracted and formatted"
REPORT: " Style: {style_name}" REPORT: " Style: {style_name}"
REPORT: " Bypassed consolidate for {performance_gain}× speed" REPORT: " Bypassed consolidate for {performance_gain}× speed"
@@ -318,7 +304,7 @@ REPORT: " Bypassed consolidate for {performance_gain}× speed"
**Command**: **Command**:
```bash ```bash
run_base_flag = "--base-path \"{base_path}/.design\"" run_base_flag = "--base-path \"{base_path}\""
pages_string = ",".join(inferred_page_list) pages_string = ",".join(inferred_page_list)
pages_flag = "--pages \"{pages_string}\"" pages_flag = "--pages \"{pages_string}\""
@@ -349,7 +335,7 @@ IF --session:
SlashCommand(command) SlashCommand(command)
ELSE: ELSE:
REPORT: "ℹ️ Standalone mode: Skipping integration" REPORT: "ℹ️ Standalone mode: Skipping integration"
REPORT: " Prototypes at: {base_path}/.design/prototypes/" REPORT: " Prototypes at: {base_path}/prototypes/"
``` ```
**Completion**: Workflow complete **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 3 - Prototype Generation: {page_count} prototypes created
Phase 4 - Design Integration: {integrated OR "Standalone mode"} Phase 4 - Design Integration: {integrated OR "Standalone mode"}
📂 Output: {base_path}/.design/ 📂 Output: {base_path}/
├── style-extraction/style-cards.json (1 style card) ├── style-extraction/style-cards.json (1 style card)
├── style-consolidation/style-1/ (design tokens) ├── style-consolidation/style-1/ (design tokens)
└── prototypes/ ({page_count} HTML/CSS files) └── prototypes/ ({page_count} HTML/CSS files)
🌐 Preview: {base_path}/.design/prototypes/index.html 🌐 Preview: {base_path}/prototypes/index.html
Performance: Performance:
- Design system: ~{time}s (vs ~{consolidate_time}s with consolidate) - Design system: ~{time}s (vs ~{consolidate_time}s with consolidate)
@@ -469,6 +455,6 @@ Performance:
Next: /workflow:plan to create implementation tasks Next: /workflow:plan to create implementation tasks
} }
{ELSE: {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 CHECK: .workflow/.active-* marker files
VALIDATE: session_id matches active session 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: VERIFY:
- .design/style-consolidation/design-tokens.json - {latest_design}/style-consolidation/design-tokens.json
- .design/style-consolidation/style-guide.md - {latest_design}/style-consolidation/style-guide.md
- .design/style-consolidation/tailwind.config.js - {latest_design}/prototypes/*.html (at least one prototype)
- .design/prototypes/*.html (at least one prototype)
# Prototype selection # Prototype selection
IF --selected-prototypes provided: IF --selected-prototypes provided:
@@ -43,7 +43,7 @@ IF --selected-prototypes provided:
selected_list = parse_comma_separated(--selected-prototypes) selected_list = parse_comma_separated(--selected-prototypes)
ELSE: ELSE:
AUTO-SELECT: Use all generated prototypes 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" REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
``` ```
@@ -76,9 +76,8 @@ Update `.brainstorming/synthesis-specification.md` with design system references
## UI/UX Guidelines ## UI/UX Guidelines
### Design System Reference ### Design System Reference
**Finalized Design Tokens**: @../.design/style-consolidation/design-tokens.json **Finalized Design Tokens**: @../design-{run_id}/style-consolidation/design-tokens.json
**Style Guide**: @../.design/style-consolidation/style-guide.md **Style Guide**: @../design-{run_id}/style-consolidation/style-guide.md
**Tailwind Configuration**: @../.design/style-consolidation/tailwind.config.js
### Implementation Requirements ### Implementation Requirements
**Token Adherence**: All UI implementations MUST use design token CSS custom properties **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 ### Reference Prototypes
{FOR each selected_prototype: {FOR each selected_prototype:
- **{page_name}**: @../.design/prototypes/{prototype}.html - **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html
- Layout: {layout_strategy from notes} - Layout: {layout_strategy from notes}
} }
### Design System Assets ### Design System Assets
```json ```json
{ {
"design_tokens": ".design/style-consolidation/design-tokens.json", "design_tokens": "design-{run_id}/style-consolidation/design-tokens.json",
"style_guide": ".design/style-consolidation/style-guide.md", "style_guide": "design-{run_id}/style-consolidation/style-guide.md",
"tailwind_config": ".design/style-consolidation/tailwind.config.js",
"prototypes": [ "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 ## Design System Integration
This style guide references the finalized design system from the design refinement phase. This style guide references the finalized design system from the design refinement phase.
**Design Tokens**: @../../.design/style-consolidation/design-tokens.json **Design Tokens**: @../../design-{run_id}/style-consolidation/design-tokens.json
**Style Guide**: @../../.design/style-consolidation/style-guide.md **Style Guide**: @../../design-{run_id}/style-consolidation/style-guide.md
**Tailwind Config**: @../../.design/style-consolidation/tailwind.config.js
## Implementation Guidelines ## Implementation Guidelines
1. **Use CSS Custom Properties**: All styles reference design tokens 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 ## Reference Prototypes
{FOR each selected_prototype: {FOR each selected_prototype:
- **{page_name}**: @../../.design/prototypes/{prototype}.html - **{page_name}**: @../../design-{run_id}/prototypes/{prototype}.html
} }
## Token System ## Token System
For complete token definitions and usage examples, see: For complete token definitions and usage examples, see:
- Design Tokens: @../../.design/style-consolidation/design-tokens.json - Design Tokens: @../../design-{run_id}/style-consolidation/design-tokens.json
- Style Guide: @../../.design/style-consolidation/style-guide.md - Style Guide: @../../design-{run_id}/style-consolidation/style-guide.md
--- ---
*Auto-generated by /workflow:ui-design:update* *Auto-generated by /workflow:ui-design:update*
@@ -190,7 +187,6 @@ Updated artifacts:
Design system assets ready for /workflow:plan: Design system assets ready for /workflow:plan:
- design-tokens.json - design-tokens.json
- style-guide.md - style-guide.md
- tailwind.config.js
- {prototype_count} reference prototypes - {prototype_count} reference prototypes
Next: /workflow:plan [--agent] "<task description>" Next: /workflow:plan [--agent] "<task description>"
@@ -209,18 +205,16 @@ Next: /workflow:plan [--agent] "<task description>"
**@ Reference Format** (used in synthesis-specification.md): **@ Reference Format** (used in synthesis-specification.md):
``` ```
@../.design/style-consolidation/design-tokens.json @../design-{run_id}/style-consolidation/design-tokens.json
@../.design/style-consolidation/style-guide.md @../design-{run_id}/style-consolidation/style-guide.md
@../.design/style-consolidation/tailwind.config.js @../design-{run_id}/prototypes/{prototype}.html
@../.design/prototypes/{prototype}.html
``` ```
**@ Reference Format** (used in ui-designer/style-guide.md): **@ Reference Format** (used in ui-designer/style-guide.md):
``` ```
@../../.design/style-consolidation/design-tokens.json @../../design-{run_id}/style-consolidation/design-tokens.json
@../../.design/style-consolidation/style-guide.md @../../design-{run_id}/style-consolidation/style-guide.md
@../../.design/style-consolidation/tailwind.config.js @../../design-{run_id}/prototypes/{prototype}.html
@../../.design/prototypes/{prototype}.html
``` ```
## Integration with /workflow:plan ## Integration with /workflow:plan
@@ -243,9 +237,9 @@ After this update, `/workflow:plan` will discover design assets through:
"task_id": "IMPL-001", "task_id": "IMPL-001",
"context": { "context": {
"design_system": { "design_system": {
"tokens": ".design/style-consolidation/design-tokens.json", "tokens": "design-{run_id}/style-consolidation/design-tokens.json",
"style_guide": ".design/style-consolidation/style-guide.md", "style_guide": "design-{run_id}/style-consolidation/style-guide.md",
"prototypes": [".design/prototypes/dashboard-variant-1.html"] "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 │ ├── execute-*-[timestamp].md # Ad-hoc implementation logs
│ └── codex-execute-*-[timestamp].md # Multi-stage execution 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]/ └── WFS-[topic-slug]/
├── workflow-session.json # Session metadata and state (REQUIRED) ├── workflow-session.json # Session metadata and state (REQUIRED)
├── [.brainstorming/] # Optional brainstorming phase (created when needed) ├── [.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) ├── [.summaries/] # Task completion summaries (created when tasks complete)
│ ├── IMPL-*-summary.md # Main task summaries │ ├── IMPL-*-summary.md # Main task summaries
│ └── IMPL-*.*-summary.md # Subtask 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) └── .task/ # Task definitions (REQUIRED)
├── IMPL-*.json # Main task definitions ├── IMPL-*.json # Main task definitions
└── IMPL-*.*.json # Subtask definitions (created dynamically) └── 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 - **On-Demand Creation**: Other directories created when first needed
- **Dynamic Files**: Subtask JSON files created during task decomposition - **Dynamic Files**: Subtask JSON files created during task decomposition
- **Scratchpad Usage**: `.scratchpad/` created when CLI commands run without active session - **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/) #### Scratchpad Directory (.scratchpad/)
**Purpose**: Centralized location for non-session-specific CLI outputs **Purpose**: Centralized location for non-session-specific CLI outputs