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

refactor(ui-design): remove placeholder mechanism and simplify CSS generation workflow

Browse Source 
- Agent now directly generates HTML with final CSS references (no placeholders)
- Remove tokens.css dependency - agents create self-contained CSS from design-tokens.json
- Simplify ui-generate-preview-v2.sh (no placeholder replacement logic)
- Update Phase 2.5 validation to check actual href attributes
- Remove Phase 1.6 (token conversion step)
- Improve agent instructions with direct CSS value usage from design tokens

Benefits:
- Simpler workflow with fewer intermediate steps
- More flexible CSS generation - agents can adapt token values based on design_attributes
- Better style differentiation across variants
- Reduced dependencies and potential error points

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-10-10 19:29:38 +08:00
parent 043a3f05ba
commit 6e37881588
5 changed files with 457 additions and 803 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -24,11 +24,18 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
1. User triggers: `/workflow:ui-design:explore-auto-v2 [params]`
2. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues
3. Phase 2 (style-consolidate) → **WAIT for completion** → Auto-continues
4. **Phase 3 (ui-generate-v2)** → **WAIT for completion** → Auto-continues
5. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
6. Phase 5 (batch-plan, optional) → Reports completion
2. Phase 0c: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 1**
3. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues
4. Phase 2 (style-consolidate) → **WAIT for completion** → Auto-continues
5. **Phase 3 (ui-generate-v2)** → **WAIT for completion** → Auto-continues
6. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
7. Phase 5 (batch-plan, optional) → Reports completion
**Phase Transition Mechanism**:
- **Phase 0c (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 1
- **Phase 1-5 (Autonomous)**: `SlashCommand` is BLOCKING - execution pauses until completion
- Upon each phase completion: Automatically process output and execute next phase
- No additional user interaction after Phase 0c confirmation
**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 4 (or Phase 5 if --batch-plan).
@@ -186,6 +193,10 @@ MATCH user_input:
default → proceed with current list
STORE: inferred_target_list, target_type, target_inference_source
# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 1
# This is the only user interaction point in the workflow
# After this point, all subsequent phases execute automatically without user intervention
```
**Helper Function: detect_target_type()**
@@ -209,8 +220,8 @@ command = "/workflow:ui-design:extract --base-path \"{base_path}\" " +
SlashCommand(command)
# Output: {style_variants} style cards with design_attributes
# WAIT for extract command to complete, then IMMEDIATELY continue to Phase 2
# DO NOT STOP - Phase 2 must execute automatically
# SlashCommand blocks until phase complete
# Upon completion, IMMEDIATELY execute Phase 2 (auto-continue)
```
### Phase 2: Style Consolidation
@@ -220,8 +231,8 @@ command = "/workflow:ui-design:consolidate --base-path \"{base_path}\" " +
SlashCommand(command)
# Output: {style_variants} independent design systems with tokens.css
# WAIT for consolidate command to complete, then IMMEDIATELY continue to Phase 3
# DO NOT STOP - Phase 3 must execute automatically
# SlashCommand blocks until phase complete
# Upon completion, IMMEDIATELY execute Phase 3 (auto-continue)
```
### Phase 3: Style-Centric Matrix UI Generation
@@ -241,8 +252,8 @@ REPORT: " → Style-centric generation: Each of {style_variants} agents handle
SlashCommand(command)
# WAIT for generate-v2 command to complete, then IMMEDIATELY continue to Phase 4
# DO NOT STOP - Phase 4 must execute automatically
# SlashCommand blocks until phase complete
# Upon completion, IMMEDIATELY execute Phase 4 (auto-continue)
# Output:
# - {target}-layout-{l}.json (target-specific layout plans)
# - {target}-style-{s}-layout-{l}.html (final prototypes with style-aware structure)
@@ -255,9 +266,10 @@ SlashCommand(command)
command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
SlashCommand(command)
# WAIT for update command to complete
# If --batch-plan flag present: IMMEDIATELY continue to Phase 5
# If no --batch-plan: Workflow complete, display final report
# SlashCommand blocks until phase complete
# Upon completion:
# - If --batch-plan flag present: IMMEDIATELY execute Phase 5 (auto-continue)
# - If no --batch-plan: Workflow complete, display final report
```
### Phase 5: Batch Task Generation (Optional)
@@ -270,7 +282,7 @@ IF --batch-plan:
## TodoWrite Pattern
```javascript
// Initialize at workflow start to track multi-phase execution
// Initialize IMMEDIATELY after Phase 0c user confirmation to track multi-phase execution
TodoWrite({todos: [
{"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
{"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing..."},
@@ -278,10 +290,11 @@ TodoWrite({todos: [
{"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."}
]})
// ⚠️ CRITICAL: After EACH phase completion, you MUST:
// 1. Update current phase: status → "completed"
// 2. Update next phase: status → "in_progress"
// 3. Continue to execute next phase immediately
// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
// 1. SlashCommand blocks and returns when phase is complete
// 2. Update current phase: status → "completed"
// 3. Update next phase: status → "in_progress"
// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
// This ensures continuous workflow tracking and prevents premature stopping
```

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

@@ -73,7 +73,7 @@ IF extraction_mode == "auto":
extraction_mode = (variants_count == 1) ? "imitate" : "explore"
REPORT: "🔍 Auto-detected mode: {extraction_mode} (variants_count={variants_count})"
# Skip divergence analysis for imitate mode
# Branch: Skip or Execute divergence analysis
IF extraction_mode == "imitate":
REPORT: "🎯 IMITATE MODE: High-fidelity single style extraction"
REPORT: " → Skipping design space divergence analysis"
@@ -82,6 +82,8 @@ IF extraction_mode == "imitate":
# Skip to Phase 2
GOTO Phase 2
# ELSE: REQUIRED execution path for explore mode
# ⚠️ CRITICAL: The following steps (Step 1-3) MUST be executed when extraction_mode == "explore"
# Step 1: Load project context (explore mode only)
project_context = ""
IF exists({base_path}/.brainstorming/synthesis-specification.md):
@@ -89,9 +91,12 @@ IF exists({base_path}/.brainstorming/synthesis-specification.md):
ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md):
project_context = Read(ui-designer/analysis.md)
REPORT: "🎨 EXPLORE MODE: Analyzing design space to generate maximally contrasting directions..."
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "🎨 EXPLORE MODE: Analyzing design space (REQUIRED)"
REPORT: " → Generating {variants_count} maximally contrasting directions"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
# Step 2: AI-driven divergent direction generation
# Step 2: AI-driven divergent direction generation (REQUIRED)
divergence_prompt = """
Analyze user requirements and generate {variants_count} MAXIMALLY CONTRASTING design directions.
@@ -132,7 +137,7 @@ RULES: Output ONLY valid JSON, maximize inter-variant distance, ensure each vari
occupies distinct aesthetic region, avoid overlapping attributes
"""
# Execute AI analysis
# Execute AI analysis (REQUIRED in explore mode)
divergent_directions = parse_json(Claude_Native_Analysis(divergence_prompt))
REPORT: "✅ Generated {variants_count} contrasting design directions:"
@@ -141,10 +146,17 @@ FOR direction IN divergent_directions.divergent_directions:
design_space_analysis = divergent_directions
# Step 3: Save design space analysis for consolidation phase
Write({file_path: "{base_path}/style-extraction/design-space-analysis.json",
# Step 3: Save design space analysis for consolidation phase (REQUIRED)
# ⚠️ CRITICAL: This file MUST be generated in explore mode for downstream consolidation
output_file_path = "{base_path}/style-extraction/design-space-analysis.json"
Write({file_path: output_file_path,
content: JSON.stringify(design_space_analysis, null, 2)})
REPORT: "💾 Saved design space analysis to design-space-analysis.json"
# Verification step (REQUIRED)
VERIFY: file_exists(output_file_path) == true
REPORT: "✅ Verified: design-space-analysis.json exists ({file_size(output_file_path)} bytes)"
```
### Phase 2: Variant-Specific Style Synthesis & Direct File Write
@@ -232,8 +244,8 @@ REPORT: "💾 Saved {variants_count} style variants to style-cards.json"
TodoWrite({todos: [
{content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"},
{content: extraction_mode == "explore" ? "Analyze design space for maximum contrast" : "Skip design space analysis (imitate mode)", status: "completed", activeForm: extraction_mode == "explore" ? "Analyzing design space" : "Skipping analysis"},
{content: extraction_mode == "explore" ? `Generate ${variants_count} divergent design directions` : "Prepare for high-fidelity extraction", status: "completed", activeForm: extraction_mode == "explore" ? "Generating directions" : "Preparing extraction"},
{content: extraction_mode == "explore" ? "Save design space analysis for consolidation" : "Skip design space output", status: "completed", activeForm: extraction_mode == "explore" ? "Saving design space analysis" : "Skipping output"},
{content: extraction_mode == "explore" ? `Generate ${variants_count} divergent design directions (REQUIRED)` : "Prepare for high-fidelity extraction", status: "completed", activeForm: extraction_mode == "explore" ? "Generating directions" : "Preparing extraction"},
{content: extraction_mode == "explore" ? `Write and verify design-space-analysis.json (REQUIRED)` : "Skip design space output", status: "completed", activeForm: extraction_mode == "explore" ? "Writing and verifying file" : "Skipping output"},
{content: `Generate and write ${variants_count} ${extraction_mode == "explore" ? "contrasting" : "high-fidelity"} style variant${variants_count > 1 ? "s" : ""} to file`, status: "completed", activeForm: "Generating and writing variants"}
]});
```

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

@@ -1,6 +1,6 @@
---
name: generate-v2
description: Generate UI prototypes using style-centric batch generation
description: Generate UI prototypes using target-style-centric batch generation
usage: /workflow:ui-design:generate-v2 [--targets "<list>"] [--target-type "page|component"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
examples:
- /workflow:ui-design:generate-v2 --session WFS-auth --targets "dashboard,settings" --style-variants 3 --layout-variants 3
@@ -9,20 +9,21 @@ examples:
allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
---
# UI Generation Command (Style-Centric Architecture)
# UI Generation Command (Target-Style-Centric Architecture)
**Executor**: → @ui-design-agent
**Parallel Generation**: Phase 2 → @ui-design-agent (S tasks, each handling L×T combinations)
**Parallel Generation**: Phase 2 → @ui-design-agent (T×S tasks, each handling L layouts)
## Overview
Generate production-ready UI prototypes (HTML/CSS) using **style-centric batch generation**. Each agent handles all layout × target combinations for one style, ensuring maximum style consistency and optimal performance.
Generate production-ready UI prototypes (HTML/CSS) using **target-style-centric batch generation**. Each agent handles all layout variants for one target × one style combination, ensuring component isolation and focused generation.
## Core Philosophy
- **Style-Centric Batching**: Each of S agents generates ALL L×T prototypes for one style
- **Target-Style-Centric**: Each of T×S agents generates L layouts for one target × one style
- **Component Isolation**: Tasks completely independent, preventing cross-component interference
- **Style-Aware Structure**: HTML DOM adapts based on design_attributes (density, visual_weight, etc.)
- **Performance Optimized**: S agent calls for efficient generation
- **Perfect Style Consistency**: All layouts for a style generated by single agent with full context
- **Token-Driven Styling**: All styles reference design-tokens.json via tokens.css
- **Performance Optimized**: T×S agent calls with highly focused scope per agent
- **Layout Inspiration**: Simple text-based research replaces complex JSON planning
- **Self-Contained CSS**: Agent reads design-tokens.json and creates independent CSS (no token.css reference)
- **Production-Ready**: Semantic HTML5, ARIA attributes, responsive design
## Execution Protocol
@@ -96,7 +97,6 @@ STORE: target_list, target_type
# 5. Verify design systems exist
FOR style_id IN range(1, style_variants + 1):
VERIFY: exists({base_path}/style-consolidation/style-{style_id}/design-tokens.json)
VERIFY: exists({base_path}/style-consolidation/style-{style_id}/tokens.css)
# 6. Load design space analysis (for style-aware generation)
design_space_path = "{base_path}/style-extraction/design-space-analysis.json"
@@ -114,400 +114,222 @@ ELSE:
synthesis_spec = null
```
### Phase 1.5: Target-Specific Layout Planning
### Phase 1.5: Target Layout Inspiration
```bash
REPORT: "📐 Planning {layout_variants} layout strategies for each target..."
REPORT: "💡 Gathering layout inspiration for {len(target_list)} targets..."
CREATE: {base_path}/prototypes/_templates/
CREATE: {base_path}/prototypes/_inspirations/
# For each target, plan its specific layouts
# For each target, gather layout inspiration via MCP search
FOR target IN target_list:
REPORT: " Planning layouts for '{target}' ({target_type})..."
REPORT: " Researching '{target}' ({target_type}) layout patterns..."
FOR layout_id IN range(1, layout_variants + 1):
Task(ui-design-agent): "
[TARGET_LAYOUT_PLANNING]
# MCP search for layout patterns
search_query = f"common {target} {target_type} layout patterns variations best practices"
search_results = mcp__exa__web_search_exa(
query=search_query,
numResults=5
)
TARGET: {target} | TARGET_TYPE: {target_type} | LAYOUT_ID: {layout_id}/{layout_variants}
BASE_PATH: {base_path}
{IF synthesis_spec: PROJECT_REQUIREMENTS: {synthesis_spec}}
# Extract key layout patterns from search results
inspiration_content = f"""Layout Inspiration for '{target}' ({target_type})
Generated: {current_timestamp()}
Search Query: {search_query}
## Task
Research common {target} {target_type} layout variations and select the #{layout_id} approach.
Generate layout plan JSON that is STRUCTURALLY DIFFERENT from other layout IDs.
## Layout Patterns Identified
## Research (MCP Required)
mcp__exa__web_search_exa(
query=\"common {target} {target_type} layout patterns variations best practices 2024\",
numResults=5
)
From web research, {layout_variants} distinct layout approaches:
## Selection Strategy
From search results, identify multiple layout variations and select approach #{layout_id}.
Ensure each layout_id uses a DIFFERENT structural pattern (not just styling differences).
Layout 1: [First structural pattern identified from search]
- Key characteristics: ...
- Structure approach: ...
## Output File
Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json\", layout_plan_json)
Layout 2: [Second structural pattern]
- Key characteristics: ...
- Structure approach: ...
## JSON Structure (Required Fields)
```json
{{
\"id\": \"layout-{layout_id}\",
\"target\": \"{target}\",
\"target_type\": \"{target_type}\",
\"name\": \"Descriptive name (2-4 words)\",
\"description\": \"2-3 sentences\",
\"structure\": {{
// IF page: type, regions, grid, sidebar, responsive
// IF component: arrangement, alignment, spacing, element_order
}},
\"semantic_hints\": [...],
\"accessibility_features\": [...],
\"research_references\": [...]
}}
```
Layout 3: [Third structural pattern]
- Key characteristics: ...
- Structure approach: ...
## Requirements
- Research-informed, target-specific, meaningfully different from other layout IDs
- Write file directly (not text output)
"
## Reference Links
{format_search_results_urls(search_results)}
# Wait for all agent tasks to complete
REPORT: "⏳ Waiting for layout planning agents to complete..."
## Implementation Notes
- Each layout should be STRUCTURALLY DIFFERENT (not just CSS variations)
- Consider {target_type}-specific patterns (navigation, content areas, interactions)
- Adapt structure based on design_attributes in Phase 2
"""
# Verify agent created layout JSON files
REPORT: "📝 Verifying agent file creation..."
# Write simple inspiration file
inspiration_file = f"{base_path}/prototypes/_inspirations/{target}-layout-ideas.txt"
Write(inspiration_file, inspiration_content)
FOR target IN target_list:
FOR layout_id IN range(1, layout_variants + 1):
layout_json_label = f"{target}-layout-{layout_id}.json"
json_path = f"{base_path}/prototypes/_templates/{layout_json_label}"
REPORT: f" ✓ Created: {target}-layout-ideas.txt"
# Verify file exists
VERIFY: exists(json_path), f"Layout JSON not created by agent: {layout_json_label}"
# Validate JSON structure
TRY:
layout_json_content = Read(json_path)
layout_plan = JSON.parse(layout_json_content)
# Validate required fields
VALIDATE: layout_plan.id == f"layout-{layout_id}", f"Invalid layout ID in {layout_json_label}"
VALIDATE: layout_plan.target == target, f"Invalid target in {layout_json_label}"
VALIDATE: layout_plan.target_type == target_type, f"Invalid target_type in {layout_json_label}"
VALIDATE: layout_plan.name exists, f"Missing 'name' field in {layout_json_label}"
VALIDATE: layout_plan.structure exists, f"Missing 'structure' field in {layout_json_label}"
file_size = get_file_size(json_path)
REPORT: f" ✓ Verified: {layout_json_label} - {layout_plan.name} ({file_size} KB)"
CATCH error:
ERROR: f"Validation failed for {layout_json_label}: {error}"
REPORT: f" ⚠️ File exists but validation failed - review agent output"
REPORT: f"✅ Phase 1.5 complete: Verified {len(target_list) × layout_variants} target-specific layout files"
REPORT: f"✅ Phase 1.5 complete: Gathered inspiration for {len(target_list)} targets"
```
### Phase 1.6: Convert Design Tokens to CSS
```bash
REPORT: "🎨 Converting design tokens to CSS variables..."
### Phase 2: Target-Style-Centric Batch Generation
# Check for jq dependency
IF NOT command_exists("jq"):
ERROR: "jq is not installed or not in PATH. The conversion script requires jq."
REPORT: "Please install jq: macOS: brew install jq | Linux: apt-get install jq | Windows: https://stedolan.github.io/jq/download/"
EXIT 1
# Convert design tokens to CSS for each style variant
FOR style_id IN range(1, style_variants + 1):
tokens_json_path = "{base_path}/style-consolidation/style-${style_id}/design-tokens.json"
tokens_css_path = "{base_path}/style-consolidation/style-${style_id}/tokens.css"
script_path = "~/.claude/scripts/convert_tokens_to_css.sh"
# Verify input file exists
VERIFY: exists(tokens_json_path), f"Design tokens not found for style-{style_id}"
# Execute conversion: cat input.json | script.sh > output.css
Bash(cat "${tokens_json_path}" | "${script_path}" > "${tokens_css_path}")
# Verify output was generated
IF exit_code == 0 AND exists(tokens_css_path):
file_size = get_file_size(tokens_css_path)
REPORT: f" ✓ Generated tokens.css for style-{style_id} ({file_size} KB)"
ELSE:
ERROR: f"Failed to generate tokens.css for style-{style_id}"
EXIT 1
REPORT: f"✅ Phase 1.6 complete: Converted {style_variants} design token files to CSS"
```
### Phase 1.7: Extract Token Variable Names from CSS
```bash
REPORT: "📋 Extracting actual CSS variable names from tokens.css..."
tokens_css_path = "{base_path}/style-consolidation/style-1/tokens.css"
VERIFY: exists(tokens_css_path), "tokens.css not found. Phase 1.6 may have failed."
tokens_css_content = Read(tokens_css_path)
# Extract all CSS variable names from the generated file
# Pattern: --variable-name: value;
all_token_vars = extract_css_variables(tokens_css_content) # Regex: r'--([a-z0-9-_]+):'
# Categorize variables for better Agent understanding
color_vars = [v for v in all_token_vars if v.startswith('--color-')]
typography_vars = [v for v in all_token_vars if v.startswith(('--font-', '--line-height-', '--letter-spacing-'))]
spacing_vars = [v for v in all_token_vars if v.startswith('--spacing-')]
radius_vars = [v for v in all_token_vars if v.startswith('--border-radius-')]
shadow_vars = [v for v in all_token_vars if v.startswith('--shadow-')]
breakpoint_vars = [v for v in all_token_vars if v.startswith('--breakpoint-')]
REPORT: f"✅ Extracted {len(all_token_vars)} actual CSS variables from tokens.css"
REPORT: f" Colors: {len(color_vars)} | Typography: {len(typography_vars)} | Spacing: {len(spacing_vars)}"
```
### Phase 2: Style-Centric Batch Generation
**Strategy**: S style-centric agents, each generating L×T prototypes for one style.
**Performance**: S agent calls for parallel execution
**Strategy**: T×S target-style-centric agents, each generating L layouts for one target × one style.
**Performance**: T×S agent calls with component isolation
```bash
REPORT: "🎨 Phase 2: Launching {style_variants} style-centric agents..."
REPORT: " Each agent generates {layout_variants}×{len(target_list)}={layout_variants * len(target_list)} prototypes"
REPORT: "🎨 Phase 2: Launching {len(target_list)}×{style_variants}={len(target_list) * style_variants} target-style agents..."
REPORT: " Each agent generates {layout_variants} layouts for one component"
CREATE: {base_path}/prototypes/
# Launch ONE agent task PER STYLE (parallel execution)
FOR style_id IN range(1, style_variants + 1):
# Load style-specific context
style_tokens_path = "{base_path}/style-consolidation/style-{style_id}/design-tokens.json"
style_css_path = "{base_path}/style-consolidation/style-{style_id}/tokens.css"
style_guide_path = "{base_path}/style-consolidation/style-{style_id}/style-guide.md"
# Launch ONE agent task PER TARGET × STYLE combination (parallel execution)
FOR target IN target_list:
# Load layout inspiration for this target
inspiration_path = f"{base_path}/prototypes/_inspirations/{target}-layout-ideas.txt"
# Extract design attributes for this style (if available)
IF design_space_analysis AND style_id <= len(design_space_analysis.divergent_directions):
design_attributes = design_space_analysis.divergent_directions[style_id - 1]
philosophy_name = design_attributes.philosophy_name
attributes_summary = JSON.stringify({
density: design_attributes.design_attributes.density,
visual_weight: design_attributes.design_attributes.visual_weight,
formality: design_attributes.design_attributes.formality,
organic_vs_geometric: design_attributes.design_attributes.organic_vs_geometric,
innovation: design_attributes.design_attributes.innovation
})
ELSE:
design_attributes = null
philosophy_name = f"Style {style_id}"
attributes_summary = "No design attributes available"
FOR style_id IN range(1, style_variants + 1):
# Load style-specific context
style_tokens_path = f"{base_path}/style-consolidation/style-{style_id}/design-tokens.json"
style_guide_path = f"{base_path}/style-consolidation/style-{style_id}/style-guide.md"
Task(ui-design-agent): """
[STYLE_CENTRIC_UI_BATCH_GENERATION]
# Extract design attributes for this style (if available)
IF design_space_analysis AND style_id <= len(design_space_analysis.divergent_directions):
design_attributes = design_space_analysis.divergent_directions[style_id - 1]
philosophy_name = design_attributes.philosophy_name
attributes_summary = JSON.stringify({
density: design_attributes.design_attributes.density,
visual_weight: design_attributes.design_attributes.visual_weight,
formality: design_attributes.design_attributes.formality,
organic_vs_geometric: design_attributes.design_attributes.organic_vs_geometric,
innovation: design_attributes.design_attributes.innovation
})
ELSE:
design_attributes = null
philosophy_name = f"Style {style_id}"
attributes_summary = "No design attributes available"
## 🎯 Mission
Generate COMPLETE set of UI prototypes for Style-{style_id} across ALL targets and layouts.
Total files to create: {layout_variants × len(target_list) × 2} (HTML + CSS pairs)
Task(ui-design-agent): """
[TARGET_STYLE_UI_GENERATION]
## 🎨 Style Context (Your Design Identity)
STYLE_ID: {style_id}
PHILOSOPHY: {philosophy_name}
## 🎯 Mission
Generate {layout_variants} layout variants for: {target} × Style-{style_id} ({philosophy_name})
Output: {layout_variants × 2} files ({layout_variants} HTML + {layout_variants} CSS)
{IF design_attributes:
DESIGN_ATTRIBUTES: {attributes_summary}
- density: {design_attributes.design_attributes.density} → Affects spacing, container usage
- visual_weight: {design_attributes.design_attributes.visual_weight} → Affects borders, shadows, nesting
- formality: {design_attributes.design_attributes.formality} → Affects font choices, structure formality
- organic_vs_geometric: {design_attributes.design_attributes.organic_vs_geometric} → Affects border-radius, alignment
- innovation: {design_attributes.design_attributes.innovation} → Affects layout adventurousness
}
## 🎨 Style Context
PHILOSOPHY: {philosophy_name}
{IF design_attributes:
DESIGN_ATTRIBUTES: {attributes_summary}
Key impacts:
- density → DOM nesting depth, whitespace scale
- visual_weight → wrapper layers, border/shadow strength
- formality → semantic structure choices
- organic_vs_geometric → alignment, edge treatment
- innovation → layout adventurousness
}
STYLE_FILES:
- Design Tokens: {style_tokens_path}
- CSS Variables: {style_css_path}
- Style Guide: {style_guide_path}
## 📂 Input Resources
**Design System**:
- Design Tokens (JSON): {style_tokens_path}
- Style Guide: {style_guide_path}
## 📋 Batch Generation Matrix
TARGETS: {target_list} # Example: [dashboard, settings]
LAYOUTS: 1 to {layout_variants} # Example: [1, 2, 3]
TOTAL_COMBINATIONS: {layout_variants × len(target_list)}
TARGET_TYPE: {target_type}
**Layout Inspiration**: {inspiration_path}
Contains {layout_variants} distinct structural patterns
## 🔄 Required Execution Loop
**Target**: {target} ({target_type})
You MUST implement this nested loop to generate all combinations:
## 🔄 Generation Steps (for each layout 1..{layout_variants})
```pseudocode
FOR target IN {target_list}:
FOR layout_id IN [1..{layout_variants}]:
# Step 1: Load layout plan
layout_plan_path = "{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json"
layout_plan = Read(layout_plan_path)
**1. Read Inspiration**
- Load: {inspiration_path}
- Apply layout N pattern
# Step 2: Load CSS variables (to know what tokens exist)
tokens_css = Read("{style_css_path}")
available_vars = extract_all_css_variables(tokens_css) # Pattern: --variable-name:
**2. Read Design Tokens**
- Load: {style_tokens_path}
- Parse JSON structure and extract all design token values
- Understand token categories: colors, typography, spacing, shadows, borders, etc.
# Step 3: Generate STYLE-AWARE HTML structure
# ⚠️ CRITICAL: Structure must adapt based on design_attributes!
**3. Generate HTML Structure**
- Complete HTML5 document (<!DOCTYPE>, <html>, <head>, <body>)
- Semantic elements: <header>, <nav>, <main>, <section>, <article>, <footer>
- ARIA attributes: aria-label, role, aria-labelledby
- Responsive meta: <meta name="viewport" content="width=device-width, initial-scale=1">
- Include CSS reference: <link rel="stylesheet" href="{target}-style-{style_id}-layout-N.css">
- Example: For dashboard-style-1-layout-2.html, use <link rel="stylesheet" href="dashboard-style-1-layout-2.css">
html_structure = generate_html_with_style_awareness(
target=target,
layout_plan=layout_plan,
target_type="{target_type}",
design_attributes={design_attributes if design_attributes else "null"}
)
{IF design_attributes:
**⚠️ Adapt DOM based on design_attributes:**
- density='spacious' → Flatter hierarchy
Example: <main><section class="card"></section></main>
- density='compact' → Deeper nesting
Example: <main><div class="grid"><div class="card-wrapper"><section></section></div></div></main>
- visual_weight='heavy' → Extra wrapper divs for layered effects
Example: <div class="border-container"><div class="content-wrapper">...</div></div>
- visual_weight='minimal' → Direct structure, minimal wrappers
Example: <section class="card">...</section>
- organic_vs_geometric → Affects alignment patterns and edge structure
}
## Style-Aware Structure Rules:
{IF design_attributes:
# Apply design_attributes to HTML structure:
IF density == 'spacious':
→ Use FEWER containers, flatter DOM hierarchy
→ Example: <main><section class="card"></section></main>
IF density == 'compact':
→ Use MORE containers, allow nesting
→ Example: <main><div class="grid"><div class="card-wrapper"><section></section></div></div></main>
**4. Generate Self-Contained CSS**
⚠️ Use design token values DIRECTLY from step 2 - create complete, independent CSS
IF visual_weight == 'heavy':
→ Add extra wrapper divs for border effects
→ Example: <div class="border-container"><div class="content-wrapper">...</div></div>
IF visual_weight == 'minimal' or 'light':
→ Minimal wrappers, direct structure
→ Example: <section class="card">...</section>
**Required Token Usage** (from design-tokens.json):
- Colors: Use color values for backgrounds, text, borders
- Typography: Use font-family, font-size, font-weight, line-height values
- Spacing: Use spacing scale for margins, padding, gaps
- Borders: Use border-radius, border-width values
- Shadows: Use box-shadow values
- Breakpoints: Use breakpoint values for @media queries
IF organic_vs_geometric == 'brutalist':
→ Hard edges, overlapping allowed, structural honesty
IF organic_vs_geometric == 'organic':
→ Flowing, natural hierarchy
}
{IF design_attributes:
**Apply design_attributes to token selection:**
- density='spacious' → Select larger spacing tokens
- density='compact' → Select smaller spacing tokens
- visual_weight='heavy' → Use stronger shadows, add borders
- visual_weight='minimal' → Use subtle/no shadows
- formality → Affects typography choices and structure
- organic_vs_geometric → Affects border-radius and alignment
}
# Step 4: Generate structural CSS using ONLY extracted variables
# ⚠️ CRITICAL: Use var() for ALL styling, NO hardcoded values
**CSS Structure**:
- Complete styling: colors, typography, layout, spacing, effects
- Responsive design: Mobile-first with breakpoint-based @media
- Self-contained: No external dependencies or var() references
css_content = generate_structural_css(
layout_plan=layout_plan,
available_vars=available_vars, # ⚠️ Only use these!
design_attributes={design_attributes if design_attributes else "null"}
)
**5. Write Files IMMEDIATELY**
- Output paths:
- HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-N.html
- CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-N.css
- Write after generating each layout (do NOT accumulate)
- Do NOT return content as text
## CSS Requirements:
- ALL colors use: var(--color-*)
- ALL fonts use: var(--font-*)
- ALL spacing use: var(--spacing-*)
- ALL radius use: var(--border-radius-*)
- ALL shadows use: var(--shadow-*)
- Responsive: Use var(--breakpoint-*) for media queries
## ✅ Success Criteria
- [ ] Generated exactly {layout_variants × 2} files
- [ ] All HTML includes correct CSS file reference (matching filename pattern)
- [ ] All CSS uses design token values directly (self-contained, no var() references)
- [ ] CSS fully embodies the style's design tokens (colors, typography, spacing, effects)
- [ ] {IF design_attributes: 'HTML structure adapts to design_attributes' ELSE: 'HTML follows layout inspiration'}
- [ ] Layouts are structurally distinct (different grids/regions, not just CSS tweaks)
- [ ] Files written to filesystem (not returned as text)
{IF design_attributes:
# Apply design_attributes to CSS properties:
IF density == 'spacious':
→ Use larger spacing values: var(--spacing-8) instead of var(--spacing-4)
IF density == 'compact':
→ Use smaller spacing values: var(--spacing-2) instead of var(--spacing-4)
## 📋 Completion
Report: "✅ {target} × Style-{style_id} ({philosophy_name}): {layout_variants × 2} files created"
"""
IF visual_weight == 'heavy':
→ Use stronger shadows: var(--shadow-lg) instead of var(--shadow-md)
→ Add border declarations
IF visual_weight == 'minimal':
→ Use subtle shadows: var(--shadow-sm) or none
→ Minimal borders
}
# Step 5: HTML must include CSS placeholders
html_content = html_structure.replace("</head>", \"\"\"
<link rel="stylesheet" href="{{STRUCTURAL_CSS}}">
<link rel="stylesheet" href="{{TOKEN_CSS}}">
</head>
\"\"\")
# Step 6: Write files IMMEDIATELY (don't accumulate)
output_html = "{base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html"
output_css = "{base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.css"
Write(output_html, html_content)
Write(output_css, css_content)
REPORT: f" ✓ Generated: {target}-style-{style_id}-layout-{layout_id}"
```
## ⚠️ Critical Requirements
### 1. HTML Generation Rules
- **Complete HTML5 document**: <!DOCTYPE html>, <html>, <head>, <body>
- **Semantic elements**: Use <header>, <nav>, <main>, <section>, <article>, <aside>, <footer>
- **ARIA attributes**: aria-label, role, aria-labelledby for accessibility
- **Responsive meta**: <meta name="viewport" content="width=device-width, initial-scale=1">
- **CSS placeholders**: MUST include {{STRUCTURAL_CSS}} and {{TOKEN_CSS}} placeholders
### 2. Style-Aware Structure Adaptation
{IF design_attributes:
**You have design_attributes - USE THEM to vary DOM structure:**
- Same target+layout with different styles = DIFFERENT HTML structures
- Example: Minimalist dashboard (density=spacious) has fewer divs than Brutalist dashboard (visual_weight=heavy)
- This is NOT just CSS differences - the HTML tree itself must adapt!
}
{ELSE:
**No design_attributes available - generate clean, semantic structure**
- Focus on layout_plan requirements
- Use best practices for {target_type} structure
}
### 3. CSS Generation Rules
- **Token-driven**: 100% var() usage, ZERO hardcoded values
- **Structural only**: Layout, positioning, spacing, structure
- **NO styling**: No colors, fonts in structural CSS (handled by tokens.css)
- **Responsive**: Mobile-first, use var(--breakpoint-*) for media queries
### 4. Layout Differentiation
- layout-1 vs layout-2 vs layout-3 must be STRUCTURALLY DIFFERENT
- Not just CSS tweaks - different grid systems, different regions
- Refer to layout_plan.structure for each layout's unique requirements
### 5. Write Operations (MANDATORY)
- Write() IMMEDIATELY after generating each prototype
- Do NOT accumulate all content and write at end
- Do NOT return file contents as text output
- Each Write() creates one HTML or CSS file
## ✅ Completion Report
After generating ALL {layout_variants × len(target_list)} combinations, report:
```
✅ Style-{style_id} ({philosophy_name}) Batch Generation Complete
Files Created: {layout_variants × len(target_list) × 2} ({layout_variants × len(target_list)} HTML + {layout_variants × len(target_list)} CSS)
{FOR target IN target_list:
{target.capitalize()}:
{FOR layout_id IN range(1, layout_variants + 1):
- {target}-style-{style_id}-layout-{layout_id}.html/css ({file_size_kb} KB each)
}
}
Summary: All prototypes generated with {IF design_attributes: 'style-aware structure' ELSE: 'semantic structure'}
```
## 🔑 Key Success Criteria
- [ ] Generated exactly {layout_variants × len(target_list) × 2} files
- [ ] All HTML files include CSS placeholders
- [ ] All CSS files use var() exclusively (no hardcoded values)
- [ ] {IF design_attributes: '[ ] HTML structure varies based on design_attributes' ELSE: '[ ] HTML structure follows layout_plan'}
- [ ] Layout-1, Layout-2, Layout-3 are structurally distinct
- [ ] All files written directly to filesystem (not returned as text)
"""
REPORT: "⏳ Phase 2: Waiting for {style_variants} style-centric agents to complete..."
REPORT: "⏳ Phase 2: Waiting for {len(target_list) * style_variants} target-style agents to complete..."
REPORT: " Expected total files: {style_variants × layout_variants × len(target_list) × 2}"
```
### Phase 2.5: Verify Agent File Creation
```bash
REPORT: "📝 Phase 2.5: Verifying style-centric generation..."
REPORT: "📝 Phase 2.5: Verifying target-style generation..."
total_expected = style_variants × layout_variants × len(target_list) × 2
total_found = 0
FOR style_id IN range(1, style_variants + 1):
style_files_found = 0
FOR target IN target_list:
FOR style_id IN range(1, style_variants + 1):
agent_files_found = 0
FOR layout_id IN range(1, layout_variants + 1):
FOR target IN target_list:
FOR layout_id IN range(1, layout_variants + 1):
html_file = f"{target}-style-{style_id}-layout-{layout_id}.html"
css_file = f"{target}-style-{style_id}-layout-{layout_id}.css"
@@ -522,20 +344,20 @@ FOR style_id IN range(1, style_variants + 1):
# Basic validation
VALIDATE: "<!DOCTYPE html>" in html_content, f"Invalid HTML: {html_file}"
VALIDATE: "{{STRUCTURAL_CSS}}" in html_content, f"Missing CSS placeholder: {html_file}"
VALIDATE: "var(--" in css_content, f"Missing CSS variables: {css_file}"
VALIDATE: f'href="{css_file}"' in html_content, f"Missing or incorrect CSS reference in: {html_file}"
VALIDATE: len(css_content) > 100, f"CSS file too small (likely incomplete): {css_file}"
html_size = get_file_size(html_path)
css_size = get_file_size(css_path)
style_files_found += 2
agent_files_found += 2
total_found += 2
REPORT: f" ✓ {html_file} ({html_size} KB) + {css_file} ({css_size} KB)"
ELSE:
ERROR: f" ✗ Missing files: {target}-style-{style_id}-layout-{layout_id}.*"
REPORT: f" Style-{style_id}: {style_files_found}/{layout_variants * len(target_list) * 2} files verified"
REPORT: f" {target} × style-{style_id}: {agent_files_found}/{layout_variants * 2} files verified"
IF total_found == total_expected:
REPORT: f"✅ Phase 2.5 complete: Verified all {total_expected} files"
@@ -548,36 +370,14 @@ ELSE:
```bash
REPORT: "🌐 Phase 3: Generating preview files..."
# Phase 3a: Replace CSS placeholders in HTML files
FOR style_id IN range(1, style_variants + 1):
tokens_css_rel_path = f"../style-consolidation/style-{style_id}/tokens.css"
FOR layout_id IN range(1, layout_variants + 1):
FOR target IN target_list:
html_path = f"{base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html"
css_path = f"{target}-style-{style_id}-layout-{layout_id}.css" # Relative path
IF exists(html_path):
html_content = Read(html_path)
# Replace placeholders
html_content = html_content.replace("{{STRUCTURAL_CSS}}", css_path)
html_content = html_content.replace("{{TOKEN_CSS}}", tokens_css_rel_path)
# Write updated HTML
Write(html_path, html_content)
REPORT: " ✓ Updated CSS links in all HTML files"
# Phase 3b: Generate compare.html and index.html using simplified preview script
prototypes_dir = f"{base_path}/prototypes"
# Simple preview generation (no template substitution)
# Template-based preview generation script
# - Uses: ~/.claude/workflows/_template-compare-matrix.html
# - Auto-detects: S, L, T from file patterns
# - Generates: compare.html, index.html, PREVIEW.md
Bash(~/.claude/scripts/ui-generate-preview-v2.sh "{prototypes_dir}")
# The script auto-detects: S, L, T from file patterns
# The script generates: compare.html, index.html, PREVIEW.md
# Verify preview files generated
preview_files = [
f"{base_path}/prototypes/compare.html",
@@ -604,10 +404,8 @@ ELSE:
```javascript
TodoWrite({todos: [
{content: "Resolve paths and load design systems", status: "completed", activeForm: "Loading design systems"},
{content: `Plan ${target_list.length}×${layout_variants} target-specific layouts`, status: "completed", activeForm: "Planning layouts"},
{content: `Convert ${style_variants} design token files to CSS`, status: "completed", activeForm: "Converting tokens to CSS"},
{content: "Extract CSS variable names from tokens.css", status: "completed", activeForm: "Extracting variable names"},
{content: `Launch ${style_variants} style-centric agents (each handling ${layout_variants}×${target_list.length} combinations)`, status: "completed", activeForm: "Running style-centric generation"},
{content: `Gather layout inspiration for ${target_list.length} targets`, status: "completed", activeForm: "Gathering inspiration"},
{content: `Launch ${target_list.length}×${style_variants}=${target_list.length * style_variants} target-style agents (each handling ${layout_variants} layouts)`, status: "completed", activeForm: "Running target-style generation"},
{content: `Verify ${style_variants * layout_variants * target_list.length * 2} generated files`, status: "completed", activeForm: "Verifying files"},
{content: "Generate preview files (compare.html, index.html)", status: "completed", activeForm: "Generating previews"}
]});
@@ -615,36 +413,37 @@ TodoWrite({todos: [
**Completion Message**:
```
✅ Style-Centric UI Generation Complete!
✅ Target-Style-Centric UI Generation Complete!
Architecture: Style-Centric Batch Generation
Architecture: Target-Style-Centric Batch Generation
Configuration:
- Style Variants: {style_variants}
- Layout Variants: {layout_variants} (target-specific planning)
- Layout Variants: {layout_variants} (inspiration-based)
- Target Type: {target_type_icon} {target_type}
- Targets: {target_list}
- Total Prototypes: {style_variants * layout_variants * len(target_list)}
Agent Execution:
✅ Style-centric agents: S = {style_variants} agents
✅ Each agent handles: L×T = {layout_variants}×{len(target_list)} combinations
✅ Target-style agents: T×S = {len(target_list)}×{style_variants} = {len(target_list) * style_variants} agents
✅ Each agent handles: L = {layout_variants} layouts for one component
✅ Component isolation: Tasks completely independent
Design Quality:
✅ Style-Aware Structure: {IF design_space_analysis: 'YES - HTML adapts to design_attributes' ELSE: 'Standard semantic structure'}
✅ Style Consistency: PERFECT (each style by single agent)
✅ Token-Driven Styling: 100% var() usage
✅ Focused generation: Each agent handles single target × single style
✅ Self-Contained CSS: Direct design token usage (no var() dependencies)
Output Files:
- Layout Plans: {len(target_list) × layout_variants} JSON files
- Layout Inspirations: {len(target_list)} simple text files
- HTML Prototypes: {style_variants * layout_variants * len(target_list)} files
- CSS Files: {style_variants * layout_variants * len(target_list)} files
- Preview Files: compare.html, index.html, PREVIEW.md
Generated Structure:
📂 {base_path}/prototypes/
├── _templates/
│ └── {target}-layout-{l}.json ({len(target_list) × layout_variants} layout plans)
├── _inspirations/
│ └── {target}-layout-ideas.txt ({len(target_list)} inspiration files)
├── {target}-style-{s}-layout-{l}.html ({style_variants * layout_variants * len(target_list)} prototypes)
├── {target}-style-{s}-layout-{l}.css
├── compare.html (interactive S×L×T matrix)
@@ -675,8 +474,8 @@ Note: When called from /workflow:ui-design:explore-auto, design-update is trigge
```
{base_path}/prototypes/
├── _templates/ # Layout planning only
│ └── {target}-layout-1.json # Layout plan JSON
├── _inspirations/ # Layout inspiration only
│ └── {target}-layout-ideas.txt # Simple inspiration text
├── {target}-style-{s}-layout-{l}.html # Final prototypes (S×L×T)
├── {target}-style-{s}-layout-{l}.css
├── compare.html # Interactive matrix
@@ -684,7 +483,7 @@ Note: When called from /workflow:ui-design:explore-auto, design-update is trigge
└── PREVIEW.md # Instructions
{base_path}/style-consolidation/
├── style-1/ (design-tokens.json, tokens.css, style-guide.md)
├── style-1/ (design-tokens.json, style-guide.md)
├── style-2/ (same structure)
└── style-{S}/ (same structure)
```
@@ -698,39 +497,40 @@ Note: When called from /workflow:ui-design:explore-auto, design-update is trigge
- **Unsupported target type**: Error if target_type not in ["page", "component"]
### Phase-Specific Errors
- **Agent execution errors (Phase 2)**: Report details, identify which style agent failed
- **Token conversion errors (Phase 1.6)**: Check design-tokens.json format
- **Agent execution errors (Phase 2)**: Report details, identify which target × style agent failed
- **Invalid design-tokens.json**: Check JSON format and structure
- **Missing files (Phase 2.5)**: Indicates agent failed to write - review agent output logs
- **MCP search errors (Phase 1.5)**: Check network connectivity, retry search
- **Preview generation errors (Phase 3)**: Check script exists, permissions
### Recovery Strategies
- **Partial generation**: If some style agents succeed, you still have those prototypes
- **Retry single style**: Can re-run targeting failed style directory
- **Partial generation**: If some target-style agents succeed, you still have those prototypes
- **Retry single combination**: Can re-run targeting failed target × style combination
- **Missing design_attributes**: Generation works without them - just less style-aware
- **Permission errors**: Run `chmod +x ~/.claude/scripts/ui-generate-preview-v2.sh`
## Key Features
1. **🚀 Style-Centric Batch Generation**
Each agent handles ALL L×T combinations for one style with efficient parallel execution
1. **🚀 Target-Style-Centric Batch Generation**
Each agent handles L layouts for one target × one style with component isolation
2. **🎨 Style-Aware Structure Adaptation**
2. **🎯 Component Isolation**
Tasks completely independent, preventing cross-component interference
3. **🎨 Style-Aware Structure Adaptation**
HTML DOM adapts based on design_attributes (density, visual_weight, organic_vs_geometric)
3. **📦 Intelligent Context Batching**
Each agent receives full style context + all layout plans + all targets
4. **⚡ Performance Optimized**
Parallel execution of S agents for efficient generation
Parallel execution of T×S agents with highly focused scope per agent
5. **🔒 Guaranteed Style Consistency**
All layouts for a style by single agent; Maintains philosophy throughout
5. **💡 Simplified Layout Inspiration**
Simple text-based research replaces complex JSON planning
6. **📐 Target-Specific Layout Planning**
Each target gets custom-designed layouts via MCP research
6. **🔧 Focused Agent Scope**
Each agent generates only L layouts, reducing complexity and improving quality
7. **🎯 Token-Driven Styling**
100% var() usage; Each style has own tokens.css
7. **🎯 Self-Contained CSS Generation**
Agents read design-tokens.json and create independent CSS with direct token values (no var() references)
8. **🌐 Interactive Visualization**
Full-featured compare.html with matrix grid
@@ -740,7 +540,7 @@ Note: When called from /workflow:ui-design:explore-auto, design-update is trigge
## Integration Points
- **Input**: Per-style design-tokens.json + tokens.css; design-space-analysis.json (optional); targets + layout-variants
- **Output**: S×L×T HTML/CSS prototypes for `/workflow:ui-design:update`
- **Input**: Per-style design-tokens.json; design-space-analysis.json (optional); targets + layout-variants
- **Output**: S×L×T HTML/CSS prototypes with self-contained styling for `/workflow:ui-design:update`
- **Auto Integration**: Triggered by `/workflow:ui-design:explore-auto`
- **Backward Compatibility**: Works without design-space-analysis.json

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

@@ -124,23 +124,19 @@ FOR target IN target_list:
{IF --session: PROJECT_REQUIREMENTS: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md}
## Task
Research common {target} {target_type} layout variations and select the #{layout_id} approach.
Generate layout plan JSON that is STRUCTURALLY DIFFERENT from other layout IDs.
Research {target} {target_type} layout variations → Select approach #{layout_id} → Generate layout plan JSON
## Research (MCP Required)
## Research
mcp__exa__web_search_exa(
query=\"common {target} {target_type} layout patterns variations best practices 2024\",
numResults=5
)
Identify multiple structural patterns → Select DISTINCT approach #{layout_id}
## Selection Strategy
From search results, identify multiple layout variations and select approach #{layout_id}.
Ensure each layout_id uses a DIFFERENT structural pattern (not just styling differences).
## Output File
## Output
Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json\", layout_plan_json)
## JSON Structure (Required Fields)
## JSON Structure
```json
{
"id": "layout-{layout_id}",
@@ -159,7 +155,7 @@ FOR target IN target_list:
```
## Requirements
- Research-informed, target-specific, meaningfully different from other layout IDs
- Research-informed, structurally DIFFERENT from other layout IDs
- Write file directly (not text output)
"
@@ -294,53 +290,45 @@ FOR layout_id IN range(1, layout_variants + 1):
**Plan**: {JSON.stringify(layout_plan, null, 2)}
## Task
Generate TWO template files implementing the layout plan above:
1. HTML: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.html
2. CSS: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.css
Generate TWO template files implementing the layout plan:
- HTML: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.html
- CSS: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.css
## HTML Requirements
- Semantic HTML5 + ARIA attributes
- Wrapper: Always generate a complete HTML5 document (<!DOCTYPE html>, <html>, <head>, <body>)
* IF page: <body> contains full page structure (header, nav, main, footer)
* IF component: <body> contains only the component in a simple presentation wrapper
- ⚠️ CRITICAL: Include CSS placeholders in <head>:
- Complete HTML5 document (<!DOCTYPE>, <html>, <head>, <body>)
- Semantic elements + ARIA attributes
- Body content:
* IF page → Full structure (header, nav, main, footer)
* IF component → Isolated element in presentation wrapper
- ⚠️ CRITICAL CSS placeholders in <head>:
<link rel=\"stylesheet\" href=\"{{STRUCTURAL_CSS}}\">
<link rel=\"stylesheet\" href=\"{{TOKEN_CSS}}\">
## CSS Requirements - TOKEN REFERENCE (CRITICAL)
## CSS Requirements - Token Reference
**STEP 1: Read the actual tokens.css file FIRST**
**1. Read tokens.css**
Read(\"{base_path}/style-consolidation/style-1/tokens.css\")
Extract all CSS variable names (pattern: lines with \" --\" in \":root {}\")
**STEP 2: Extract ALL CSS variable names**
- Pattern: Lines starting with \" --\" inside \":root {}\"
- Example: \" --color-brand-primary: oklch(...)\" → use \"--color-brand-primary\"
**STEP 3: Use ONLY variables that exist in tokens.css**
- ✅ DO: Copy exact variable names from tokens.css
- ✅ DO: Use var(--exact-name-from-file)
- ❌ DON'T: Invent or guess variable names
- ❌ DON'T: Use hardcoded values (colors, fonts, spacing)
**Available Token Categories** (extracted from actual file):
**2. Available Tokens**
- Colors: {', '.join(color_vars[:5])}... ({len(color_vars)} total)
- Typography: {', '.join(typography_vars[:5])}... ({len(typography_vars)} total)
- Spacing: {', '.join(spacing_vars[:5])}... ({len(spacing_vars)} total)
- Radius: {', '.join(radius_vars[:3])}... ({len(radius_vars)} total)
- Shadows: {', '.join(shadow_vars)}
**OPTIONAL: Layout-Specific Token Extension**
If core tokens are insufficient, create `{target}-layout-{layout_id}-tokens.css` with `--layout-*` prefix.
Example: `--layout-spacing-navbar-height`, `--layout-size-sidebar-width`
**3. Variable Usage Rules**
- ✅ Use ONLY variables from tokens.css (exact names)
- ✅ Format: var(--exact-name-from-file)
- ❌ NO invented/guessed variable names
- ❌ NO hardcoded values (colors, fonts, spacing)
**Example Workflow**:
1. Read tokens.css → find \"--color-brand-primary: oklch(0.55 0.12 45);\"
2. Use in CSS → \"background: var(--color-brand-primary);\"
**4. Optional Extension**
If core tokens insufficient → Create `{target}-layout-{layout_id}-tokens.css` with `--layout-*` prefix
Examples: `--layout-spacing-navbar-height`, `--layout-size-sidebar-width`
**CSS Rules**:
- Token-driven: ALL stylistic values use var() (zero hardcoded values)
- Mobile-first responsive design
- Structural layout only (Flexbox, Grid, positioning)
**CSS Scope**: Structural layout only (Flexbox, Grid, positioning)
**Responsive**: Mobile-first approach
## Write Operations
Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.html\", html_content)
@@ -459,22 +447,22 @@ FOR style_id IN range(1, style_variants + 1):
Task(@ui-design-agent): "
[CROSS_PAGE_CONSISTENCY_VALIDATION]
STYLE_ID: {style_id} | LAYOUT_ID: {layout_id} | TARGETS: {target_list} | TARGET_TYPE: {target_type}
STYLE: {style_id} | LAYOUT: {layout_id} | TARGETS: {target_list} | TYPE: {target_type}
BASE_PATH: {base_path}
## Input
{base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html/css (all targets)
## Validate
1. Shared component structure (header/nav/footer)
2. Token usage consistency (no hardcoded values)
3. Accessibility compliance (ARIA, headings, landmarks)
4. Layout strategy adherence
1. Shared components (header/nav/footer)
2. Token usage (no hardcoded values)
3. Accessibility (ARIA, headings, landmarks)
4. Layout strategy consistency
## Output
Write({base_path}/prototypes/consistency-report-s{style_id}-l{layout_id}.md, validation_report)
Focus on shared elements. Page-specific variations are acceptable.
Focus on shared elements. Page-specific variations acceptable.
"
# Aggregate consistency reports

471
.claude/scripts/ui-generate-preview-v2.sh
View File

@@ -1,10 +1,10 @@
#!/bin/bash
#
# UI Generate Preview v2.0 - Simplified Preview Generation
# Purpose: Generate compare.html and index.html for style-centric prototypes
# No template substitution - just preview generation
# UI Generate Preview v2.0 - Template-Based Preview Generation
# Purpose: Generate compare.html and index.html using template substitution
# Template: ~/.claude/workflows/_template-compare-matrix.html
#
# Usage: ui-generate-preview-v2.sh <prototypes_dir>
# Usage: ui-generate-preview-v2.sh <prototypes_dir> [--template <path>]
#
set -e
@@ -15,7 +15,25 @@ GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# Default template path
TEMPLATE_PATH="$HOME/.claude/workflows/_template-compare-matrix.html"
# Parse arguments
prototypes_dir="${1:-.}"
shift || true
while [[ $# -gt 0 ]]; do
case $1 in
--template)
TEMPLATE_PATH="$2"
shift 2
;;
*)
echo -e "${RED}Unknown option: $1${NC}"
exit 1
;;
esac
done
if [[ ! -d "$prototypes_dir" ]]; then
echo -e "${RED}Error: Directory not found: $prototypes_dir${NC}"
@@ -42,264 +60,58 @@ T=$(echo "$targets" | wc -l)
echo -e " Detected: ${GREEN}${S}${NC} styles × ${GREEN}${L}${NC} layouts × ${GREEN}${T}${NC} targets"
if [[ $S -eq 0 ]] || [[ $L -eq 0 ]] || [[ $T -eq 0 ]]; then
echo -e "${RED}Error: No prototype files found matching pattern{target}-style-{s}-layout-{l}.html${NC}"
echo -e "${RED}Error: No prototype files found matching pattern {target}-style-{s}-layout-{l}.html${NC}"
exit 1
fi
# Generate compare.html
echo -e "${YELLOW}🎨 Generating compare.html...${NC}"
# ============================================================================
# Generate compare.html from template
# ============================================================================
cat > compare.html << 'EOF'
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>UI Design Matrix - Style × Layout Comparison</title>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
background: #f5f5f5;
padding: 20px;
}
.header {
background: white;
padding: 20px;
border-radius: 8px;
margin-bottom: 20px;
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
.header h1 { margin-bottom: 10px; color: #333; }
.header .stats { color: #666; font-size: 14px; }
.controls {
background: white;
padding: 15px;
border-radius: 8px;
margin-bottom: 20px;
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
.controls label { margin-right: 10px; font-weight: 500; }
.controls select {
padding: 5px 10px;
border: 1px solid #ddd;
border-radius: 4px;
margin-right: 20px;
}
.matrix-container { margin-bottom: 40px; }
.matrix-title {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
padding: 15px 20px;
border-radius: 8px 8px 0 0;
font-size: 18px;
font-weight: 600;
}
.matrix {
display: grid;
gap: 20px;
padding: 20px;
background: white;
border-radius: 0 0 8px 8px;
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
.cell {
border: 2px solid #e0e0e0;
border-radius: 8px;
overflow: hidden;
background: #fafafa;
transition: all 0.3s ease;
}
.cell:hover {
border-color: #667eea;
box-shadow: 0 4px 12px rgba(102, 126, 234, 0.15);
transform: translateY(-2px);
}
.cell-header {
padding: 12px 15px;
background: #f8f9fa;
border-bottom: 1px solid #e0e0e0;
font-weight: 600;
color: #495057;
display: flex;
justify-content: space-between;
align-items: center;
}
.cell-header .badge {
background: #667eea;
color: white;
padding: 2px 8px;
border-radius: 12px;
font-size: 11px;
font-weight: 500;
}
.iframe-wrapper {
position: relative;
width: 100%;
padding-top: 75%; /* 4:3 aspect ratio */
background: white;
}
iframe {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
border: none;
}
.cell-footer {
padding: 10px 15px;
background: #f8f9fa;
border-top: 1px solid #e0e0e0;
font-size: 12px;
color: #6c757d;
text-align: center;
}
.cell-footer a {
color: #667eea;
text-decoration: none;
margin: 0 5px;
}
.cell-footer a:hover {
text-decoration: underline;
}
</style>
</head>
<body>
<div class="header">
<h1>🎨 UI Design Matrix Comparison</h1>
<div class="stats">
<span id="matrix-stats"></span>
</div>
</div>
echo -e "${YELLOW}🎨 Generating compare.html from template...${NC}"
<div class="controls">
<label for="target-selector">Target:</label>
<select id="target-selector"></select>
if [[ ! -f "$TEMPLATE_PATH" ]]; then
echo -e "${RED}Error: Template not found: $TEMPLATE_PATH${NC}"
exit 1
fi
<label for="layout-cols">Columns:</label>
<select id="layout-cols">
<option value="1">1</option>
<option value="2">2</option>
<option value="3" selected>3</option>
<option value="4">4</option>
</select>
</div>
# Build pages/targets JSON array
PAGES_JSON="["
first=true
for target in $targets; do
if [[ "$first" == true ]]; then
first=false
else
PAGES_JSON+=", "
fi
PAGES_JSON+="\"$target\""
done
PAGES_JSON+="]"
<div id="matrices-container"></div>
# Generate metadata
RUN_ID="run-$(date +%Y%m%d-%H%M%S)"
SESSION_ID="standalone"
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u +"%Y-%m-%d")
<script>
// Data from script
const styles = STYLES_PLACEHOLDER;
const layouts = LAYOUTS_PLACEHOLDER;
const targets = TARGETS_PLACEHOLDER;
# Replace placeholders in template
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}}|${S}|g" | \
sed "s|{{layout_variants}}|${L}|g" | \
sed "s|{{pages_json}}|${PAGES_JSON}|g" \
> compare.html
// Update stats
document.getElementById('matrix-stats').textContent =
`${styles.length} styles × ${layouts.length} layouts × ${targets.length} targets = ${styles.length * layouts.length * targets.length} prototypes`;
// Populate target selector
const targetSelector = document.getElementById('target-selector');
targets.forEach((target, index) => {
const option = document.createElement('option');
option.value = target;
option.textContent = target.charAt(0).toUpperCase() + target.slice(1);
if (index === 0) option.selected = true;
targetSelector.appendChild(option);
});
// Generate matrices
function renderMatrices(target) {
const container = document.getElementById('matrices-container');
container.innerHTML = '';
styles.forEach(styleId => {
const matrixContainer = document.createElement('div');
matrixContainer.className = 'matrix-container';
const title = document.createElement('div');
title.className = 'matrix-title';
title.textContent = `Style ${styleId} - ${target.charAt(0).toUpperCase() + target.slice(1)}`;
const matrix = document.createElement('div');
matrix.className = 'matrix';
matrix.id = `matrix-style-${styleId}`;
layouts.forEach(layoutId => {
const cell = document.createElement('div');
cell.className = 'cell';
const header = document.createElement('div');
header.className = 'cell-header';
header.innerHTML = `
<span>Layout ${layoutId}</span>
<span class="badge">S${styleId}L${layoutId}</span>
`;
const iframeWrapper = document.createElement('div');
iframeWrapper.className = 'iframe-wrapper';
const iframe = document.createElement('iframe');
iframe.src = `./${target}-style-${styleId}-layout-${layoutId}.html`;
iframe.loading = 'lazy';
const footer = document.createElement('div');
footer.className = 'cell-footer';
footer.innerHTML = `
<a href="./${target}-style-${styleId}-layout-${layoutId}.html" target="_blank">Open ↗</a>
<a href="./${target}-style-${styleId}-layout-${layoutId}.css" target="_blank">CSS</a>
`;
iframeWrapper.appendChild(iframe);
cell.appendChild(header);
cell.appendChild(iframeWrapper);
cell.appendChild(footer);
matrix.appendChild(cell);
});
matrixContainer.appendChild(title);
matrixContainer.appendChild(matrix);
container.appendChild(matrixContainer);
});
updateGridColumns();
}
function updateGridColumns() {
const cols = document.getElementById('layout-cols').value;
styles.forEach(styleId => {
const matrix = document.getElementById(`matrix-style-${styleId}`);
if (matrix) {
matrix.style.gridTemplateColumns = `repeat(${cols}, 1fr)`;
}
});
}
// Event listeners
targetSelector.addEventListener('change', (e) => {
renderMatrices(e.target.value);
});
document.getElementById('layout-cols').addEventListener('change', updateGridColumns);
// Initial render
renderMatrices(targets[0]);
</script>
</body>
</html>
EOF
# Replace placeholders with actual data
sed -i "s/STYLES_PLACEHOLDER/[$(echo "$styles" | tr '\n' ',' | sed 's/,$//' | sed 's/\([0-9]\+\)/"\1"/g')]/" compare.html
sed -i "s/LAYOUTS_PLACEHOLDER/[$(echo "$layouts" | tr '\n' ',' | sed 's/,$//' | sed 's/\([0-9]\+\)/"\1"/g')]/" compare.html
sed -i "s/TARGETS_PLACEHOLDER/[$(echo "$targets" | tr '\n' ',' | sed 's/,$//' | sed 's/\(.*\)/"\1"/g')]/" compare.html
echo -e "${GREEN} ✓ Generated compare.html${NC}"
echo -e "${GREEN} ✓ Generated compare.html from template${NC}"
# ============================================================================
# Generate index.html
# ============================================================================
echo -e "${YELLOW}📋 Generating index.html...${NC}"
cat > index.html << EOF
cat > index.html << 'EOF'
<!DOCTYPE html>
<html lang="en">
<head>
@@ -386,7 +198,7 @@ cat > index.html << EOF
</head>
<body>
<h1>🎨 UI Prototypes Index</h1>
<p class="subtitle">Generated ${S}×${L}×${T} = $((S*L*T)) prototypes</p>
<p class="subtitle">Generated __S__×__L__×__T__ = __TOTAL__ prototypes</p>
<div class="cta">
<h2>📊 Interactive Comparison</h2>
@@ -395,43 +207,60 @@ cat > index.html << EOF
</div>
<h2>📂 All Prototypes</h2>
EOF
# Generate index content
for style in $styles; do
echo "<div class='style-section'>" >> index.html
echo "<h2>Style ${style}</h2>" >> index.html
for target in $targets; do
target_capitalized="$(echo ${target:0:1} | tr '[:lower:]' '[:upper:]')${target:1}"
echo "<div class='target-group'>" >> index.html
echo "<h3>${target_capitalized}</h3>" >> index.html
echo "<div class='link-grid'>" >> index.html
for layout in $layouts; do
html_file="${target}-style-${style}-layout-${layout}.html"
if [[ -f "$html_file" ]]; then
echo "<a href='${html_file}' class='prototype-link' target='_blank'>" >> index.html
echo "<span class='label'>Layout ${layout}</span>" >> index.html
echo "<span class='icon'>↗</span>" >> index.html
echo "</a>" >> index.html
fi
done
echo "</div></div>" >> index.html
done
echo "</div>" >> index.html
done
cat >> index.html << EOF
__CONTENT__
</body>
</html>
EOF
# Build content HTML
CONTENT=""
for style in $styles; do
CONTENT+="<div class='style-section'>"$'\n'
CONTENT+="<h2>Style ${style}</h2>"$'\n'
for target in $targets; do
target_capitalized="$(echo ${target:0:1} | tr '[:lower:]' '[:upper:]')${target:1}"
CONTENT+="<div class='target-group'>"$'\n'
CONTENT+="<h3>${target_capitalized}</h3>"$'\n'
CONTENT+="<div class='link-grid'>"$'\n'
for layout in $layouts; do
html_file="${target}-style-${style}-layout-${layout}.html"
if [[ -f "$html_file" ]]; then
CONTENT+="<a href='${html_file}' class='prototype-link' target='_blank'>"$'\n'
CONTENT+="<span class='label'>Layout ${layout}</span>"$'\n'
CONTENT+="<span class='icon'>↗</span>"$'\n'
CONTENT+="</a>"$'\n'
fi
done
CONTENT+="</div></div>"$'\n'
done
CONTENT+="</div>"$'\n'
done
# Calculate total
TOTAL_PROTOTYPES=$((S * L * T))
# Replace placeholders (using a temp file for complex replacement)
{
echo "$CONTENT" > /tmp/content_tmp.txt
sed "s|__S__|${S}|g" index.html | \
sed "s|__L__|${L}|g" | \
sed "s|__T__|${T}|g" | \
sed "s|__TOTAL__|${TOTAL_PROTOTYPES}|g" | \
sed -e "/__CONTENT__/r /tmp/content_tmp.txt" -e "/__CONTENT__/d" > /tmp/index_tmp.html
mv /tmp/index_tmp.html index.html
rm -f /tmp/content_tmp.txt
}
echo -e "${GREEN} ✓ Generated index.html${NC}"
# ============================================================================
# Generate PREVIEW.md
# ============================================================================
echo -e "${YELLOW}📝 Generating PREVIEW.md...${NC}"
cat > PREVIEW.md << EOF
@@ -457,6 +286,8 @@ Open \`compare.html\` in your browser to see all prototypes in an interactive ma
- Switch between targets using the dropdown
- Adjust grid columns for better viewing
- Direct links to full-page views
- Selection system with export to JSON
- Fullscreen mode for detailed inspection
### Option 2: Simple Index
@@ -475,76 +306,86 @@ prototypes/
├── compare.html # Interactive matrix view
├── index.html # Simple navigation index
├── PREVIEW.md # This file
$(for style in $styles; do
EOF
for style in $styles; do
for target in $targets; do
for layout in $layouts; do
echo "├── ${target}-style-${style}-layout-${layout}.html"
echo "├── ${target}-style-${style}-layout-${layout}.css"
echo "├── ${target}-style-${style}-layout-${layout}.html" >> PREVIEW.md
echo "├── ${target}-style-${style}-layout-${layout}.css" >> PREVIEW.md
done
done
done)
\`\`\`
done
cat >> PREVIEW.md << 'EOF2'
```
## 🎨 Style Variants
$(for style in $styles; do
echo "### Style ${style}"
echo ""
EOF2
for style in $styles; do
cat >> PREVIEW.md << EOF3
### Style ${style}
EOF3
style_guide="../style-consolidation/style-${style}/style-guide.md"
if [[ -f "$style_guide" ]]; then
head -n 10 "$style_guide" | tail -n +2 || echo "Design philosophy and tokens"
head -n 10 "$style_guide" | tail -n +2 >> PREVIEW.md 2>/dev/null || echo "Design philosophy and tokens" >> PREVIEW.md
else
echo "Design system ${style}"
echo "Design system ${style}" >> PREVIEW.md
fi
echo ""
done)
echo "" >> PREVIEW.md
done
## 📐 Layout Variants
$(for layout in $layouts; do
echo "### Layout ${layout}"
echo ""
for target in $targets; do
layout_plan="_templates/${target}-layout-${layout}.json"
if [[ -f "$layout_plan" ]]; then
name=$(grep -o '"name":[[:space:]]*"[^"]*"' "$layout_plan" | head -1 | cut -d'"' -f4 || echo "Layout ${layout}")
echo "- **${target}**: ${name}"
fi
done
echo ""
done)
cat >> PREVIEW.md << 'EOF4'
## 🎯 Targets
$(for target in $targets; do
EOF4
for target in $targets; do
target_capitalized="$(echo ${target:0:1} | tr '[:lower:]' '[:upper:]')${target:1}"
echo "- **${target_capitalized}**: ${L} layouts × ${S} styles = $((L*S)) variations"
done)
echo "- **${target_capitalized}**: ${L} layouts × ${S} styles = $((L*S)) variations" >> PREVIEW.md
done
cat >> PREVIEW.md << 'EOF5'
## 💡 Tips
1. **Comparison**: Use compare.html to see how different styles affect the same layout
2. **Navigation**: Use index.html for quick access to specific prototypes
3. **Inspection**: Open browser DevTools to inspect HTML structure and CSS
4. **Sharing**: All files are standalone - can be shared or deployed directly
3. **Selection**: Mark favorites in compare.html using star icons
4. **Export**: Download selection JSON for implementation planning
5. **Inspection**: Open browser DevTools to inspect HTML structure and CSS
6. **Sharing**: All files are standalone - can be shared or deployed directly
## 📝 Next Steps
1. Review prototypes in compare.html
2. Select preferred style × layout combinations
3. Provide feedback for refinement
4. Use selected designs for implementation
3. Export selections as JSON
4. Provide feedback for refinement
5. Use selected designs for implementation
---
Generated by /workflow:ui-design:generate-v2 (Style-Centric Architecture)
EOF
EOF5
echo -e "${GREEN} ✓ Generated PREVIEW.md${NC}"
# ============================================================================
# Completion Summary
# ============================================================================
echo ""
echo -e "${GREEN}✅ Preview generation complete!${NC}"
echo -e " Files created: compare.html, index.html, PREVIEW.md"
echo -e " Matrix: ${S} styles × ${L} layouts × ${T} targets = $((S*L*T)) prototypes"
echo ""
echo -e "${YELLOW}🌐 Open compare.html to view interactive matrix${NC}"
echo -e "${YELLOW}🌐 Next Steps:${NC}"
echo -e " 1. Open compare.html for interactive matrix view"
echo -e " 2. Open index.html for simple navigation"
echo -e " 3. Read PREVIEW.md for detailed usage guide"
echo ""