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): update workflow commands and agent configuration

Browse Source 
**Agent Changes:**
- Update ui-design-agent.md with refined task definitions
- Improve agent prompt structure and guidelines

**Workflow Command Updates:**
- Simplify explore-auto.md workflow orchestration (-589 lines)
- Streamline imitate-auto.md for faster execution (-378 lines)
- Optimize update.md command flow and documentation (-136 lines)

**Architecture Updates:**
- Update workflow-architecture.md with current patterns
- Refine command parameter documentation

**Cleanup:**
- Remove outdated release-notes-v3.5.0.md

**Summary:**
- Net reduction: 729 lines removed
- Improved clarity and maintainability
- Better alignment with agent-driven execution model

🤖 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 09:46:27 +08:00
parent f6292a6288
commit 4cf66b41a4
6 changed files with 326 additions and 1055 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
.claude/agents/ui-design-agent.md
View File

@@ -365,8 +365,30 @@ summary = mcp__code-index__get_file_summary(file_path="path/to/component.tsx")
**File Operations**:
- **Read**: Load design tokens, layout strategies, project artifacts
- **Write**: Generate design-tokens.json, tokens.css, HTML/CSS prototypes, documentation
- **Edit**: Update token definitions, refine layout strategies
- **Write**: **PRIMARY RESPONSIBILITY** - Generate and write files directly to the file system
- Agent MUST use Write() tool to create all output files
- Agent receives ABSOLUTE file paths from orchestrator (e.g., `{base_path}/style-consolidation/style-1/design-tokens.json`)
- Agent MUST create directories if they don't exist (use Bash `mkdir -p` if needed)
- Agent MUST verify each file write operation succeeds
- Agent does NOT return file contents as text with labeled sections
- **Edit**: Update token definitions, refine layout strategies when files already exist
**Path Handling**:
- Orchestrator provides complete absolute paths in prompts
- Agent uses provided paths exactly as given without modification
- If path contains variables (e.g., `{base_path}`), they will be pre-resolved by orchestrator
- Agent verifies directory structure exists before writing
- Example: `Write("/absolute/path/to/style-1/design-tokens.json", content)`
**File Write Verification**:
- After writing each file, agent should verify file creation
- Report file path and size in completion message
- If write fails, report error immediately with details
- Example completion report:
```
✅ Written: style-1/design-tokens.json (12.5 KB)
✅ Written: style-1/style-guide.md (8.3 KB)
```
**Script Execution**:
```bash
@@ -379,7 +401,7 @@ cat design-tokens.json | ~/.claude/scripts/convert_tokens_to_css.sh > tokens.css
--mode {page|component}
```
**Agent Delegation**:
**Agent Delegation Pattern**:
```javascript
Task(ui-design-agent): "
[TASK_TYPE_IDENTIFIER]
@@ -389,10 +411,30 @@ Task(ui-design-agent): "
## Context
- Key parameters and input files
- Quality standards and constraints
- BASE_PATH: {absolute_path_to_output_directory}
## Output Format
- Expected deliverables
- File format specifications
## File Write Instructions
Generate and WRITE files directly using Write() tool:
1. File 1:
Path: {absolute_path}/file1.json
Content: [specification]
2. File 2:
Path: {absolute_path}/file2.md
Content: [specification]
## Instructions
- Use Write() tool for each file with provided absolute paths
- Create directories if needed: Bash('mkdir -p {directory}')
- Verify each write operation succeeds
- Report completion with file paths and sizes
## Expected Final Report
✅ Written: file1.json (12.5 KB)
✅ Written: file2.md (8.3 KB)
DO NOT return file contents as text - write them directly to the file system.
"
```

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

@@ -86,9 +86,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
**Matrix Mode** (unified):
- Generates `style_variants × layout_variants × targets` prototypes
- **Phase 1**: `style_variants` style options
- **Phase 2**: `style_variants` independent design systems
- **Phase 3**: `style_variants × layout_variants × targets` prototypes
- **Phase 1**: `style_variants` style options (extract)
- **Phase 2**: `style_variants` independent design systems (consolidate)
- **Phase 3**: Layout planning + UI generation (generate)
- Sub-phase 1: `targets × layout_variants` target-specific layout plans
- Sub-phase 2: `layout_variants × targets` HTML/CSS templates
- Sub-phase 3: `style_variants × layout_variants × targets` final prototypes
- Pages: Full-page layouts with complete structure
- Components: Isolated elements with minimal wrapper
- Mixed: Combination based on intelligent detection
@@ -100,527 +103,229 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
### Phase 0a: Intelligent Prompt Parsing
```bash
# Extract variant counts from prompt if not explicitly provided
IF --prompt provided AND (NOT --style-variants OR NOT --layout-variants):
# Parse: "3 style variants", "4 styles", "2 layout options", "3 layouts each"
style_match = regex_search(prompt_text, r"(\d+)\s*(style\s*variants?|styles?)")
layout_match = regex_search(prompt_text, r"(\d+)\s*(layout\s*(variants?|options?)|layouts?)")
style_variants = style_match ? int(match[1]) : (--style-variants OR 3)
layout_variants = layout_match ? int(match[1]) : (--layout-variants OR 3)
# Parse variant counts from prompt or use explicit/default values
IF --prompt AND (NOT --style-variants OR NOT --layout-variants):
style_variants = regex_extract(prompt, r"(\d+)\s*style") OR --style-variants OR 3
layout_variants = regex_extract(prompt, r"(\d+)\s*layout") OR --layout-variants OR 3
ELSE:
style_variants = --style-variants OR 3
layout_variants = --layout-variants OR 3
VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
STORE: style_variants, layout_variants
```
### Phase 0b: Run Initialization & Directory Setup
```bash
# Generate run ID and determine base path
run_id = "run-$(date +%Y%m%d-%H%M%S)"
base_path = --session ? ".workflow/WFS-{session}/design-${run_id}" : ".workflow/.design/${run_id}"
IF --session:
base_path = ".workflow/WFS-{session_id}/design-${run_id}"
ELSE:
base_path = ".workflow/.design/${run_id}"
# Create directories
Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
# Initialize metadata
Write({base_path}/.run-metadata.json): {
"run_id": "${run_id}",
"session_id": "${session_id}",
"timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "...",
"workflow": "ui-design:auto",
"parameters": {
"style_variants": ${style_variants},
"layout_variants": ${layout_variants},
"pages": "${inferred_page_list}",
"prompt": "${prompt_text}",
"images": "${images_pattern}"
},
"parameters": { "style_variants": ${style_variants}, "layout_variants": ${layout_variants},
"targets": "${inferred_target_list}", "target_type": "${target_type}",
"prompt": "${prompt_text}", "images": "${images_pattern}" },
"status": "in_progress"
}
STORE: run_id, base_path
```
### Phase 0c: Unified Target Inference with Intelligent Type Detection
```bash
target_list = []
target_type = "auto" # auto, page, component
target_source = "none"
# Priority: --pages/--components (legacy) → --targets → --prompt analysis → synthesis → default
target_list = []; target_type = "auto"; target_source = "none"
# Step 1: Handle legacy parameters (backward compatibility)
IF --pages provided:
target_list = split_and_clean(--pages, delimiters=[",", ";", "、"])
target_type = "page"
target_source = "explicit_legacy"
REPORT: "📋 Using explicitly provided pages (legacy): {', '.join(target_list)}"
ELSE IF --components provided:
target_list = split_and_clean(--components, delimiters=[",", ";", "、"])
target_type = "component"
target_source = "explicit_legacy"
REPORT: "🧩 Using explicitly provided components (legacy): {', '.join(target_list)}"
# Step 1-2: Explicit parameters (legacy or unified)
IF --pages: target_list = split(--pages); target_type = "page"; target_source = "explicit_legacy"
ELSE IF --components: target_list = split(--components); target_type = "component"; target_source = "explicit_legacy"
ELSE IF --targets:
target_list = split(--targets); target_source = "explicit"
target_type = --target-type != "auto" ? --target-type : detect_target_type(target_list)
# Step 2: Handle unified --targets parameter
ELSE IF --targets provided:
target_list = split_and_clean(--targets, delimiters=[",", ";", "、"])
target_source = "explicit"
# Override type if explicitly set
IF --target-type provided AND --target-type != "auto":
target_type = --target-type
REPORT: "🎯 Using explicitly provided targets with type '{target_type}': {', '.join(target_list)}"
ELSE:
# Intelligent type detection
target_type = detect_target_type(target_list)
REPORT: "🎯 Using explicitly provided targets (detected type: {target_type}): {', '.join(target_list)}"
# Step 3: Dynamic prompt analysis
ELSE IF --prompt provided:
REPORT: "🔍 Analyzing prompt to identify targets..."
# Internal Claude analysis
analysis_prompt = """
Analyze the UI design request and identify targets (pages or components) with their types.
Request: "{prompt_text}"
Output JSON:
{
"targets": [
{"name": "normalized-name", "type": "page|component", "purpose": "description", "priority": "high|medium|low"}
],
"primary_type": "page|component|mixed",
"shared_elements": ["header", "footer"],
"context": "application context description"
}
Rules:
- Normalize to URL-friendly (lowercase, hyphens, no spaces)
- Detect type: page (full layouts like home, dashboard) vs component (UI elements like navbar, card)
- Consolidate synonyms (homepage → home, navigation → navbar)
- Common pages: home, dashboard, settings, profile, login, signup
- Common components: navbar, header, hero, card, form, button, modal, footer
- If prompt mentions "page", "screen", "view" → type: page
- If prompt mentions "component", "element", "widget" → type: component
"""
target_structure = analyze_prompt_structure(analysis_prompt, prompt_text)
target_list = extract_target_names_from_structure(target_structure)
target_type = target_structure.primary_type OR detect_target_type(target_list)
# Step 3: Prompt analysis (Claude internal analysis)
ELSE IF --prompt:
analysis_result = analyze_prompt("{prompt_text}") # Extract targets, types, purpose
target_list = analysis_result.targets
target_type = analysis_result.primary_type OR detect_target_type(target_list)
target_source = "prompt_analysis"
IF target_list:
REPORT: "🎯 Identified targets from prompt (type: {target_type}):"
FOR target IN target_structure.targets:
icon = "📄" IF target.type == "page" ELSE "🧩"
REPORT: " {icon} {target.name}: {target.purpose} [{target.priority}]"
IF target_structure.shared_elements:
REPORT: "🔧 Shared elements: {', '.join(shared_elements)}"
# Step 4: Session synthesis
ELSE IF --session AND exists(synthesis-specification.md):
target_list = extract_targets_from_synthesis(); target_type = "page"; target_source = "synthesis"
# Step 4: Extract from synthesis-specification.md (for session mode)
ELSE IF --session AND exists(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md):
synthesis = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
target_list = extract_targets_from_synthesis(synthesis) # Returns pages by default
target_type = "page"
target_source = "synthesis"
REPORT: "📋 Extracted from synthesis: {', '.join(target_list)}"
# Step 5: Fallback
IF NOT target_list: target_list = ["home"]; target_type = "page"; target_source = "default"
# Step 5: Fallback default
IF NOT target_list:
target_list = ["home"]
target_type = "page"
target_source = "default"
REPORT: "⚠️ No targets identified, using default: 'home' (page)"
# Validate and clean target names
validated_targets = []
invalid_targets = []
FOR target IN target_list:
cleaned = target.strip().lower().replace(" ", "-")
IF regex_match(cleaned, r"^[a-z0-9][a-z0-9_-]*$"):
validated_targets.append(cleaned)
ELSE:
invalid_targets.append(target)
IF invalid_targets:
REPORT: "⚠️ Skipped invalid: {', '.join(invalid_targets)}"
IF NOT validated_targets:
validated_targets = ["home"]
target_type = "page"
REPORT: "⚠️ All invalid, using default: 'home'"
# Override target type if explicitly set
IF --target-type provided AND --target-type != "auto":
target_type = --target-type
REPORT: "🔧 Target type overridden to: {target_type}"
# Validate and clean
validated_targets = [normalize(t) for t in target_list if is_valid(t)]
IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
IF --target-type != "auto": target_type = --target-type
# Interactive confirmation
type_emoji = "📄" IF target_type == "page" ELSE ("🧩" IF target_type == "component" ELSE "🎯")
type_label = "PAGES" IF target_type == "page" ELSE ("COMPONENTS" IF target_type == "component" ELSE "TARGETS")
REPORT: ""
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "{type_emoji} {type_label} CONFIRMATION"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "Type: {target_type}"
REPORT: "Source: {target_source}"
REPORT: "Targets ({len(validated_targets)}): {', '.join(validated_targets)}"
REPORT: ""
REPORT: "Options:"
REPORT: " • 'continue/yes' - proceed"
REPORT: " • 'targets: item1,item2' - replace list"
REPORT: " • 'skip: item-name' - remove targets"
REPORT: " • 'add: item-name' - add targets"
REPORT: " • 'type: page|component' - change type"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
DISPLAY_CONFIRMATION(target_type, target_source, validated_targets):
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
"{emoji} {LABEL} CONFIRMATION"
"Type: {target_type} | Source: {target_source}"
"Targets ({count}): {', '.join(validated_targets)}"
"Options: 'continue/yes' | 'targets: a,b' | 'skip: x' | 'add: y' | 'type: page|component'"
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
user_input = WAIT_FOR_USER_INPUT()
# Process input
IF user_input MATCHES r"^(continue|yes|ok|proceed)$":
REPORT: "✅ Proceeding with {len(validated_targets)} {target_type}(s): {', '.join(validated_targets)}"
ELSE IF user_input MATCHES r"^targets:\s*(.+)$":
new_targets = split_and_clean(extract_after("targets:"), [",", ";"])
validated_targets = [t.strip().lower().replace(" ", "-") for t in new_targets if t.strip()]
REPORT: "✅ Updated: {', '.join(validated_targets)}"
ELSE IF user_input MATCHES r"^skip:\s*(.+)$":
to_skip = [t.strip().lower() for t in extract_after("skip:").split(",")]
validated_targets = [t for t in validated_targets if t not in to_skip]
REPORT: "✅ Removed: {', '.join(to_skip)}, Final: {', '.join(validated_targets)}"
ELSE IF user_input MATCHES r"^add:\s*(.+)$":
to_add = [t.strip().lower().replace(" ", "-") for t in extract_after("add:").split(",") if t.strip()]
validated_targets.extend(to_add)
validated_targets = list(dict.fromkeys(validated_targets)) # Remove duplicates
REPORT: "✅ Added: {', '.join(to_add)}, Final: {', '.join(validated_targets)}"
ELSE IF user_input MATCHES r"^type:\s*(page|component)$":
target_type = extract_after("type:").strip()
REPORT: "✅ Type changed to: {target_type}"
ELSE:
REPORT: "⚠️ Invalid input, proceeding with: {', '.join(validated_targets)}"
# Process user modifications
MATCH user_input:
"continue|yes|ok" → proceed
"targets: ..." → validated_targets = parse_new_list()
"skip: ..." → validated_targets = remove_items()
"add: ..." → validated_targets = add_items()
"type: ..." → target_type = extract_type()
default → proceed with current list
IF NOT validated_targets:
validated_targets = ["home"]
target_type = "page"
STORE: inferred_target_list = validated_targets
STORE: target_type = target_type
STORE: target_inference_source = target_source
STORE: target_structure_data = target_structure IF exists(target_structure) ELSE {}
STORE: inferred_target_list, target_type, target_inference_source
```
**Helper Function: detect_target_type()**
```bash
detect_target_type(target_list):
# Common page keywords
page_keywords = ["home", "dashboard", "settings", "profile", "login", "signup", "auth",
"landing", "about", "contact", "pricing", "account", "admin"]
page_keywords = ["home", "dashboard", "settings", "profile", "login", "signup", "auth", ...]
component_keywords = ["navbar", "header", "footer", "hero", "card", "button", "form", ...]
# Common component keywords
component_keywords = ["navbar", "header", "footer", "hero", "card", "button", "form",
"modal", "alert", "toast", "menu", "sidebar", "breadcrumb", "tabs",
"table", "list", "grid", "carousel", "gallery", "search", "filter"]
page_matches = count_matches(target_list, page_keywords + ["page", "screen", "view"])
component_matches = count_matches(target_list, component_keywords + ["component", "widget"])
page_matches = 0
component_matches = 0
FOR target IN target_list:
IF target IN page_keywords:
page_matches += 1
ELSE IF target IN component_keywords:
component_matches += 1
ELSE IF contains_keyword(target, ["page", "screen", "view"]):
page_matches += 1
ELSE IF contains_keyword(target, ["component", "widget", "element"]):
component_matches += 1
# Decision logic
IF component_matches > page_matches:
RETURN "component"
ELSE IF page_matches > 0 OR len(target_list) == 0:
RETURN "page"
ELSE:
# Ambiguous - default to page
RETURN "page"
RETURN "component" IF component_matches > page_matches ELSE "page"
```
### Phase 1: Style Extraction
**Command**:
```bash
images_flag = --images present ? "--images \"{image_glob}\"" : ""
prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : ""
run_base_flag = "--base-path \"{base_path}\""
command = "/workflow:ui-design:extract {run_base_flag} {images_flag} {prompt_flag} --variants {style_variants}"
SlashCommand(command)
command = "/workflow:ui-design:extract --base-path \"{base_path}\" " +
(--images ? "--images \"{images}\" " : "") +
(--prompt ? "--prompt \"{prompt}\" " : "") +
"--variants {style_variants}"
SlashCommand(command) # → Phase 2
```
**Auto-Continue**: On completion → Phase 2
---
### Phase 2: Style Consolidation (Separate Design Systems)
**Command**:
### Phase 2: Style Consolidation
```bash
run_base_flag = "--base-path \"{base_path}\""
# Consolidate generates independent design systems by default
# IMPORTANT: Pass --layout-variants to ensure correct number of layout strategies are generated
command = "/workflow:ui-design:consolidate {run_base_flag} --variants {style_variants} --layout-variants {layout_variants}"
SlashCommand(command)
command = "/workflow:ui-design:consolidate --base-path \"{base_path}\" " +
"--variants {style_variants}"
SlashCommand(command) # → Phase 3
# Output: style_variants independent design systems (design tokens and style guides)
```
**Result**: Generates `style_variants` independent design systems:
- `style-consolidation/style-1/design-tokens.json`
- `style-consolidation/style-{N}/design-tokens.json`
**Auto-Continue**: On completion → Phase 3
---
### Phase 3: Matrix UI Generation (Unified)
**Command**:
### Phase 3: Matrix UI Generation (with Layout Planning)
```bash
run_base_flag = "--base-path \"{base_path}\""
# Build unified targets string
targets_string = ",".join(inferred_target_list)
VERIFY: targets_string matches r"^[a-z0-9_-]+(,[a-z0-9_-]+)*$"
command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
"--targets \"{targets_string}\" --target-type \"{target_type}\" " +
"--style-variants {style_variants} --layout-variants {layout_variants}"
# Prepare command with unified parameters
targets_flag = "--targets \"{targets_string}\""
type_flag = "--target-type \"{target_type}\""
total = style_variants × layout_variants × len(inferred_target_list)
REPORT: "🚀 Phase 3: {type_icon} {targets_string} | Matrix: {s}×{l} | Total: {total} prototypes"
REPORT: " → Layout planning: {len(inferred_target_list)}×{layout_variants} target-specific layouts"
command = "/workflow:ui-design:generate {run_base_flag} {targets_flag} {type_flag} --style-variants {style_variants} --layout-variants {layout_variants}"
total_prototypes = style_variants * layout_variants * len(inferred_target_list)
# Report based on type
IF target_type == "page":
type_icon = "📄"
type_label = "Pages"
context_note = "Full-page layouts"
ELSE IF target_type == "component":
type_icon = "🧩"
type_label = "Components"
context_note = "Isolated elements with minimal wrapper"
ELSE:
type_icon = "🎯"
type_label = "Targets"
context_note = "Mixed pages and components"
REPORT: "🚀 Phase 3: Matrix UI Generation"
REPORT: " {type_icon} {type_label}: {targets_string}"
REPORT: " Matrix: {style_variants}×{layout_variants}"
REPORT: " Total: {total_prototypes} prototypes"
REPORT: " Context: {context_note}"
SlashCommand(command)
SlashCommand(command) # → Phase 4
# Output:
# - {target}-layout-{l}.json (target-specific layout plans)
# - {target}-style-{s}-layout-{l}.html (final prototypes)
# - compare.html (matrix view)
```
**Result**:
- File naming: `{target}-style-{s}-layout-{l}.html`
- Total: `style_variants × layout_variants × targets`
- Matrix view: `compare.html` with interactive grid
- Rendering: Full-page for pages, minimal wrapper for components
**Auto-Continue**: On completion → Phase 4
---
### Phase 4: Design System Integration
**Command**:
```bash
session_flag = --session present ? "--session {session_id}" : ""
# Omit --selected-prototypes to use ALL generated prototypes
command = "/workflow:ui-design:update {session_flag}"
SlashCommand(command)
command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
SlashCommand(command) # → Phase 5 if --batch-plan, else complete
```
**Auto-Continue**: If `--batch-plan` present → Phase 5, else complete
---
### Phase 5: Batch Task Generation (Optional)
**Condition**: Only if `--batch-plan` flag present
**Execution**:
```bash
FOR target IN inferred_target_list:
IF target_type == "page":
SlashCommand("/workflow:plan --agent \"Implement {target} page based on design system\"")
ELSE IF target_type == "component":
SlashCommand("/workflow:plan --agent \"Implement {target} component based on design system\"")
ELSE:
SlashCommand("/workflow:plan --agent \"Implement {target} based on design system\"")
IF --batch-plan:
FOR target IN inferred_target_list:
task_desc = "Implement {target} {target_type} based on design system"
SlashCommand("/workflow:plan --agent \"{task_desc}\"")
```
**Completion**: Workflow complete
## TodoWrite Pattern
```javascript
// Initialize
TodoWrite({todos: [
{"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing style extraction"},
{"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing style consolidation"},
{"content": "Execute UI prototype generation", "status": "pending", "activeForm": "Executing UI generation"},
{"content": "Execute design system integration", "status": "pending", "activeForm": "Executing design system integration"}
{"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
{"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing..."},
{"content": "Execute UI generation", "status": "pending", "activeForm": "Executing..."},
{"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."}
]})
// After each phase: Mark current completed, next in_progress, rest pending
// Phase 1 done → Phase 2 in_progress
// Phase 2 done → Phase 3 in_progress
// ... continues until all completed
// Update after each phase: current → completed, next → in_progress
```
## Error Handling
## Key Features
- **Autonomous**: No user intervention required between phases
- **Intelligent**: Parses natural language, infers targets/types
- **Reproducible**: Deterministic flow with isolated run directories
- **Flexible**: Supports pages, components, or mixed targets
- **Phase Failures**: Workflow halts, keeps failed phase `in_progress`, reports error with recovery instructions
- **Ambiguity**: Defaults to ALL available items (variants/prototypes) to ensure autonomous continuation
## Examples
## Key Features & Workflow Position
**Core Improvements**:
- **Zero External Dependencies**: Pure Claude + agents, no CLI tools
- **Streamlined Commands**: Unified patterns, no tool-specific flags
- **Reproducible Flow**: Deterministic phase dependencies
- **Intelligent Parsing**: Natural language → variant counts, pages
- **Run Isolation**: Each execution in timestamped run directory
**Workflow Bridge**: Connects brainstorming (`synthesis-specification.md`) → design phase → planning (`/workflow:plan`) in fully automated fashion with matrix-based design exploration.
## Example Execution Flows
### Example 1: Default 3×3 Matrix (Page Mode - Prompt Inference)
### 1. Page Mode (Prompt Inference)
```bash
/workflow:ui-design:explore-auto --prompt "Modern minimalist blog with home, article, and author pages"
# Auto-detected type: page
# Inferred: 3 style variants, 3 layout variants (default)
# Targets: home, article, author
# Total: 27 full-page prototypes (3×3×3)
/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author"
# Result: 27 prototypes (3×3×3 - inferred defaults)
```
### Example 2: Custom 2×2 Matrix with Session
### 2. Custom Matrix with Session
```bash
/workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
# Auto-detected from session synthesis
# Total: 2×2×N prototypes (N from inference)
# Result: 2×2×N prototypes (targets from synthesis)
```
### Example 3: Unified - Navbar Design Comparison
### 3. Component Mode
```bash
/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --prompt "Compare 3 navigation bar designs for SaaS product" --style-variants 3 --layout-variants 2
# Explicit type: component
# Targets: navbar, hero
# Matrix: 3 styles × 2 layouts
# Total: 12 component prototypes (3×2×2)
# Output: navbar-style-1-layout-1.html, navbar-style-1-layout-2.html, ...
/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --style-variants 3 --layout-variants 2
# Result: 12 prototypes (3×2×2 components with minimal wrapper)
```
### Example 4: Unified - Card & Form Exploration
### 4. Intelligent Parsing + Batch Planning
```bash
/workflow:ui-design:explore-auto --targets "card,form,button" --images "refs/*.png" --style-variants 2 --layout-variants 3
# Auto-detected type: component (based on keywords)
# Targets: card, form, button
# Matrix: 2 styles × 3 layouts
# Total: 18 component prototypes (2×3×3)
# Context: Each component in minimal wrapper for isolated comparison
/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for dashboard and settings" --batch-plan
# Result: 16 prototypes (4×2×2) + auto-generated implementation tasks
```
### Example 5: Intelligent Parsing + Batch Planning
### 5. Legacy Support
```bash
/workflow:ui-design:explore-auto --session WFS-saas --prompt "Create 4 styles with 2 layouts for SaaS dashboard and settings" --batch-plan
# Auto-detected type: page
# Parsed: 4 styles, 2 layouts
# Targets: dashboard, settings
# Total: 16 full-page prototypes (4×2×2)
# Auto-generates implementation tasks for each target
```
### Example 6: Auto-Detected Components from Prompt
```bash
/workflow:ui-design:explore-auto --prompt "Design exploration for pricing table and testimonial card components" --style-variants 3 --layout-variants 2
# Auto-detected type: component (keyword: "components")
# Inferred targets: pricing-table, testimonial-card
# Matrix: 3 styles × 2 layouts
# Total: 12 component prototypes (3×2×2)
```
### Example 7: Legacy Parameter Support
```bash
# Using legacy --pages parameter (backward compatible)
/workflow:ui-design:explore-auto --pages "home,dashboard,settings"
# Equivalent to: --targets "home,dashboard,settings" --target-type "page"
```
### Example 8: Mixed Mode (Future Enhancement)
```bash
/workflow:ui-design:explore-auto --targets "home,dashboard,navbar,hero,card" --target-type "auto"
# Auto-detection: home, dashboard → page; navbar, hero, card → component
# Generates appropriate wrapper for each target type
# Future: Support per-target type specification
```
## Final Completion Message
**Unified Template**:
## Completion Output
```
✅ UI Design Explore-Auto Workflow Complete!
Run ID: {run_id}
Session: {session_id or "standalone"}
Type: {target_type_icon} {target_type_label}
Matrix: {style_variants}×{layout_variants} ({total_prototypes} total prototypes)
Input: {images and/or prompt summary}
Run ID: {run_id} | Session: {session_id or "standalone"}
Type: {icon} {target_type} | Matrix: {s}×{l} ({total} prototypes)
Phase 1 - Style Extraction: {style_variants} style variants
Phase 2 - Style Consolidation: {style_variants} independent design systems
Phase 3 - Matrix Generation: {style_variants}×{layout_variants}×{target_count} = {total_prototypes} prototypes
Phase 4 - Design Update: Brainstorming artifacts updated
{IF batch-plan: Phase 5 - Task Generation: {task_count} implementation tasks created}
Phase 1: {s} style variants (extract)
Phase 2: {s} design systems (consolidate)
Phase 3: Layout planning + generation (generate)
- {n}×{l} target-specific layout plans
- {l}×{n} HTML/CSS templates
- {s}×{l}×{n} = {total} final prototypes
Phase 4: Brainstorming artifacts updated
[Phase 5: {n} implementation tasks created] # if --batch-plan
📂 Run Output: {base_path}/
├── style-consolidation/ ({style_variants} design systems)
├── prototypes/ ({total_prototypes} HTML/CSS files)
└── .run-metadata.json (run configuration)
📂 {base_path}/
├── style-consolidation/ ({s} design systems)
├── prototypes/
│ ├── _templates/ ({n}×{l} layout JSON + {l}×{n} HTML/CSS)
│ └── ... ({total} final prototypes)
└── .run-metadata.json
🌐 Interactive Preview: {base_path}/prototypes/compare.html
- {style_variants}×{layout_variants} matrix view with synchronized scrolling
- {IF target_type == "component": "Isolated rendering with minimal wrapper" ELSE: "Full-page layouts"}
- Side-by-side comparison for design decisions
- Selection export for implementation
🌐 Preview: {base_path}/prototypes/compare.html
- Interactive {s}×{l} matrix view
- Side-by-side comparison
- Target-specific layouts per prototype
{target_type_icon} Targets Explored: {', '.join(inferred_target_list)}
Type: {target_type}
Context: {IF target_type == "page": "Full-page layouts" ELSE IF target_type == "component": "Isolated UI elements" ELSE: "Mixed targets"}
{icon} Targets: {', '.join(targets)} (type: {target_type})
- Each target has {l} custom-designed layouts
- Layout plans stored as structured JSON
{IF batch-plan:
📋 Implementation Tasks: .workflow/WFS-{session}/.task/
Next: /workflow:execute to begin implementation
}
{ELSE:
Next Steps:
1. Open compare.html to preview all variants
2. Select preferred style×layout combinations per target
3. Run /workflow:plan to create implementation tasks
{IF target_type == "component": "4. Integrate selected components into pages"}
}
Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
```
**Dynamic Values**:
- `target_type_icon`: "📄" for page, "🧩" for component, "🎯" for mixed/auto
- `target_type_label`: "Pages" for page, "Components" for component, "Targets" for mixed/auto
- `target_count`: `len(inferred_target_list)`
- All other placeholders are resolved from stored phase data

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

@@ -9,7 +9,6 @@ examples:
- /workflow:ui-design:imitate-auto --url "https://stripe.com" --session WFS-payment
- /workflow:ui-design:imitate-auto --images "refs/*.png" --targets "home"
- /workflow:ui-design:imitate-auto --url "https://example.com" --targets "navbar,hero" --target-type "component"
- /workflow:ui-design:imitate-auto --images "refs/*.png" --pages "home" # Legacy syntax
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*)
---
@@ -21,282 +20,157 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
**Core Philosophy**:
- **Imitation over Exploration**: Focus on replicating specific design, not generating variants
- **Single Mode**: Always 1 style × 1 layout × N pages
- **Single Mode**: Always 1 style × 1 layout × N targets
- **Speed Optimized**: Bypasses `consolidate` step via direct token extraction
- **Reference-Driven**: Requires URL or images as primary input
- **Auto-Screenshot**: Supports Playwright/Chrome with manual upload fallback
**Streamlined Flow**:
1. User triggers → Phase 0 (initialization) → Phase 0.5 (screenshot capture) → Phase 1 (style extraction) → Phase 2 (token adaptation) → Phase 3 (prototype generation) → Phase 4 (integration) → Complete
**Streamlined Flow**: Phase 0 (init) → 0.5 (screenshot) → 1 (extraction) → 2 (token adapt) → 3 (generate) → 4 (integrate)
**Performance**: ~2-3× faster than explore-auto for single-style scenarios
**Ideal For**: MVP development, high-fidelity prototyping, design replication, studying successful patterns
**Not For**: Design exploration, generating multiple alternatives, novel design creation
## Core Rules
1. **Start Immediately**: TodoWrite initialization → Phase 0 execution
2. **No Multi-Variant**: Always 1 style × 1 layout × N pages
2. **No Multi-Variant**: Always 1 style × 1 layout × N targets
3. **Reference Required**: Must provide `--url` OR `--images`
4. **Auto-Continue**: Automatic phase progression without pausing
5. **Track Progress**: Update TodoWrite after each phase
## Parameter Requirements
**Required** (at least one):
- `--url "<url>"`: Website URL to imitate (e.g., "https://linear.app")
- `--images "<glob>"`: Local reference images (e.g., "refs/*.png")
**Required** (at least one): `--url "<url>"` OR `--images "<glob>"`
**Optional**:
- `--targets "<list>"`: Comma-separated targets (pages/components) to generate (inferred from prompt if omitted)
- `--target-type "page|component"`: Explicitly set target type (default: intelligent detection)
- `--session <id>"`: Workflow session ID (standalone if omitted)
- `--prompt "<desc>"`: Additional design guidance (e.g., "Focus on dark mode")
**Optional**: `--targets "<list>"`, `--target-type "page|component"`, `--session <id>`, `--prompt "<desc>"`
**Legacy Parameters** (maintained for backward compatibility):
- `--pages "<list>"`: Alias for `--targets` with `--target-type page`
**Legacy**: `--pages "<list>"` (alias for `--targets` with type=page)
**Not Supported**:
- `--style-variants`: Always 1 (single style)
- `--layout-variants`: Always 1 (single layout)
- `--batch-plan`: Not supported in imitate mode
**Not Supported**: `--style-variants`, `--layout-variants`, `--batch-plan`
## 5-Phase Execution
### Phase 0: Simplified Initialization
```bash
# Generate run ID and determine base path
run_id = "run-$(date +%Y%m%d-%H%M%S)"
base_path = --session ? ".workflow/WFS-{session}/design-${run_id}" : ".workflow/.design/${run_id}"
IF --session:
base_path = ".workflow/WFS-{session_id}/design-${run_id}"
ELSE:
base_path = ".workflow/.design/${run_id}"
# Create directories (simpler than explore-auto)
Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation/style-1,prototypes}")
# Initialize metadata
# Metadata
Write({base_path}/.run-metadata.json): {
"run_id": "${run_id}",
"session_id": "${session_id}",
"timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"workflow": "ui-design:imitate-auto",
"mode": "single_style_imitation",
"parameters": {
"url": "${url_value}",
"images": "${images_pattern}",
"pages": "${inferred_page_list}",
"prompt": "${prompt_text}"
},
"run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"workflow": "ui-design:imitate-auto", "mode": "single_style_imitation",
"parameters": {"url": "${url_value}", "images": "${images_pattern}", "targets": "${target_list}", "prompt": "${prompt_text}"},
"status": "in_progress"
}
# Unified target inference (simplified for imitate mode, no interactive confirmation)
target_list = []
target_type = "page" # Default to page for imitate mode
target_source = "none"
# Unified target inference (no interactive confirmation)
target_list = []; target_type = "page"; target_source = "none"
# Step 1: Handle legacy --pages parameter (backward compatibility)
IF --pages provided:
target_list = split_and_clean({--pages value}, [",", ";", "、"])
target_type = "page"
target_source = "explicit_legacy"
REPORT: "📋 Using explicitly provided pages (legacy): {', '.join(target_list)}"
# Step 2: Handle unified --targets parameter
ELSE IF --targets provided:
target_list = split_and_clean({--targets value}, [",", ";", "、"])
# Priority: --pages (legacy) → --targets → --prompt → default
IF --pages: target_list = split(--pages); target_type = "page"; target_source = "explicit_legacy"
ELSE IF --targets:
target_list = split(--targets)
target_type = --target-type ? --target-type : detect_target_type(target_list)
target_source = "explicit"
# Override type if explicitly set
IF --target-type provided:
target_type = --target-type
REPORT: "🎯 Using explicitly provided targets with type '{target_type}': {', '.join(target_list)}"
ELSE:
# Intelligent type detection (same logic as explore-auto)
target_type = detect_target_type(target_list)
REPORT: "🎯 Using explicitly provided targets (detected type: {target_type}): {', '.join(target_list)}"
# Step 3: Extract from prompt
ELSE IF --prompt provided:
# Extract from prompt: "for dashboard and settings" or "pages: home, about"
target_list = extract_targets_from_prompt(prompt_text)
ELSE IF --prompt:
target_list = extract_targets_from_prompt(prompt_text) OR ["home"]
target_type = --target-type ? --target-type : detect_target_type(target_list)
target_source = "prompt_inferred"
IF NOT target_list:
target_list = ["home"]
# Detect type from prompt or targets
IF --target-type provided:
target_type = --target-type
ELSE:
target_type = detect_target_type(target_list)
# Step 4: Fallback default
ELSE:
target_list = ["home"]
target_type = "page"
target_source = "default"
target_list = ["home"]; target_type = "page"; target_source = "default"
# Validate and clean target names
validated_targets = []
FOR target IN target_list:
cleaned = target.strip().lower().replace(" ", "-")
IF regex_match(cleaned, r"^[a-z0-9][a-z0-9_-]*$"):
validated_targets.append(cleaned)
IF NOT validated_targets:
validated_targets = ["home"]
target_type = "page"
# Validate and clean
validated_targets = [t.strip().lower().replace(" ", "-") for t in target_list if regex_match(t, r"^[a-z0-9][a-z0-9_-]*$")]
IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
type_emoji = "📄" IF target_type == "page" ELSE "🧩"
type_label = "pages" IF target_type == "page" ELSE "components"
REPORT: "📋 Imitate mode: {len(validated_targets)} {type_label} with single style"
REPORT: " {type_emoji} Targets: {', '.join(validated_targets)}"
REPORT: " Type: {target_type}"
REPORT: " Reference: {url_value OR images_pattern}"
REPORT: " {type_emoji} Targets: {', '.join(validated_targets)} | Type: {target_type} | Reference: {url_value OR images_pattern}"
STORE: run_id, base_path, inferred_target_list = validated_targets, target_type = target_type
STORE: run_id, base_path, inferred_target_list = validated_targets, target_type
```
---
### Phase 0.5: URL Screenshot Capture (Auto-Fallback)
**Condition**: Only if `--url` provided
**Execution**:
```bash
IF --url provided:
REPORT: "📸 Phase 0.5: Capturing screenshots..."
screenshot_dir = "{base_path}/screenshots"
Bash(mkdir -p "{screenshot_dir}")
IF --url:
screenshot_dir = "{base_path}/screenshots"; Bash(mkdir -p "{screenshot_dir}")
screenshot_success = false; screenshot_files = []
screenshot_success = false
screenshot_files = []
# Try Playwright → Chrome → Manual fallback
TRY: Bash(npx playwright screenshot "{url_value}" "{screenshot_dir}/full-page.png" --full-page --timeout 30000)
screenshot_files.append("{screenshot_dir}/full-page.png"); screenshot_success = true
REPORT: " ✅ Playwright screenshot captured"
CATCH: REPORT: " ⚠️ Playwright failed"
# Method 1: Playwright CLI (preferred)
TRY:
REPORT: " Attempting Playwright..."
Bash(npx playwright screenshot "{url_value}" "{screenshot_dir}/full-page.png" --full-page --timeout 30000)
screenshot_files.append("{screenshot_dir}/full-page.png")
screenshot_success = true
REPORT: " ✅ Playwright screenshot captured"
CATCH:
REPORT: " ⚠️ Playwright failed"
# Method 2: Chrome DevTools (fallback)
IF NOT screenshot_success:
TRY:
REPORT: " Attempting Chrome headless..."
Bash(google-chrome --headless --disable-gpu --screenshot="{screenshot_dir}/full-page.png" --window-size=1920,1080 "{url_value}")
screenshot_files.append("{screenshot_dir}/full-page.png")
screenshot_success = true
REPORT: " ✅ Chrome screenshot captured"
CATCH:
REPORT: " ⚠️ Chrome failed"
TRY: Bash(google-chrome --headless --disable-gpu --screenshot="{screenshot_dir}/full-page.png" --window-size=1920,1080 "{url_value}")
screenshot_files.append("{screenshot_dir}/full-page.png"); screenshot_success = true
REPORT: " ✅ Chrome screenshot captured"
CATCH: REPORT: " ⚠️ Chrome failed"
# Manual upload fallback
IF NOT screenshot_success:
REPORT: ""
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "⚠️ AUTOMATED SCREENSHOT FAILED"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "━━━ ⚠️ AUTOMATED SCREENSHOT FAILED ━━━"
REPORT: "Unable to capture: {url_value}"
REPORT: ""
REPORT: "Manual screenshot required:"
REPORT: " 1. Visit: {url_value}"
REPORT: " 2. Take full-page screenshot"
REPORT: " 3. Save to: {screenshot_dir}/"
REPORT: ""
REPORT: "Options:"
REPORT: " • 'ready' - screenshot saved"
REPORT: " • 'skip' - use URL analysis only"
REPORT: " • 'abort' - cancel workflow"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: " 1. Visit: {url_value} | 2. Take full-page screenshot | 3. Save to: {screenshot_dir}/"
REPORT: "Options: 'ready' (screenshot saved) | 'skip' (URL only) | 'abort' (cancel)"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
user_response = WAIT_FOR_USER_INPUT()
IF user_response MATCHES r"^(ready|done|ok)$":
screenshot_files = Glob("{screenshot_dir}/*.{png,jpg,jpeg}")
IF screenshot_files:
screenshot_success = true
REPORT: "✅ Manual screenshot detected"
ELSE:
REPORT: "❌ No screenshot found, using URL analysis only"
ELSE IF user_response MATCHES r"^skip$":
REPORT: "⏭️ Skipping screenshot, using URL analysis"
ELSE IF user_response MATCHES r"^abort$":
ERROR: "Workflow aborted by user"
EXIT
ELSE:
REPORT: "⚠️ Invalid input, proceeding with URL analysis"
MATCH user_response:
"ready|done|ok" → screenshot_files = Glob("{screenshot_dir}/*.{png,jpg,jpeg}");
IF screenshot_files: screenshot_success = true; REPORT: "✅ Manual screenshot detected"
ELSE: REPORT: "❌ No screenshot found, using URL analysis only"
"skip" → REPORT: "⏭️ Skipping screenshot, using URL analysis"
"abort" → ERROR: "Workflow aborted by user"; EXIT
_ → REPORT: "⚠️ Invalid input, proceeding with URL analysis"
# Store results
IF screenshot_success:
STORE: screenshot_mode = "with_screenshots", screenshot_paths = screenshot_files
REPORT: "✅ Screenshot capture complete: {len(screenshot_files)} image(s)"
ELSE:
STORE: screenshot_mode = "url_only", screenshot_paths = []
REPORT: "ℹ️ Proceeding with URL analysis only"
STORE: screenshot_mode = screenshot_success ? "with_screenshots" : "url_only", screenshot_paths = screenshot_files
REPORT: screenshot_success ? "✅ Screenshot capture complete: {len(screenshot_files)} image(s)" : "ℹ️ Proceeding with URL analysis only"
ELSE:
STORE: screenshot_mode = "manual_images", screenshot_paths = []
REPORT: "ℹ️ Using provided images (--images parameter)"
REPORT: "ℹ️ Using provided images (--images parameter)"
```
**Auto-Continue**: On completion → Phase 1
---
### Phase 1: Single Style Extraction
**Command**:
```bash
# Determine input based on screenshot capture
IF screenshot_mode == "with_screenshots":
screenshot_glob = "{base_path}/screenshots/*.{png,jpg,jpeg}"
images_flag = "--images \"{screenshot_glob}\""
url_flag = ""
source_desc = "captured screenshots from {url_value}"
ELSE IF screenshot_mode == "url_only":
url_flag = "--url \"{url_value}\""
images_flag = ""
source_desc = "URL analysis of {url_value}"
ELSE IF screenshot_mode == "manual_images":
images_flag = --images present ? "--images \"{image_glob}\"" : ""
url_flag = ""
source_desc = "user-provided images"
source_desc = screenshot_mode == "with_screenshots" ? "captured screenshots from {url_value}" :
screenshot_mode == "url_only" ? "URL analysis of {url_value}" : "user-provided images"
prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : ""
run_base_flag = "--base-path \"{base_path}\""
images_flag = screenshot_mode == "with_screenshots" ? "--images \"{base_path}/screenshots/*.{png,jpg,jpeg}\"" :
screenshot_mode == "manual_images" AND --images ? "--images \"{image_glob}\"" : ""
url_flag = screenshot_mode == "url_only" ? "--url \"{url_value}\"" : ""
# Construct optimized extraction prompt
enhanced_prompt = "Extract a single, high-fidelity design system that accurately imitates the visual style from {source_desc}. {prompt_text}"
# Force single variant
command = "/workflow:ui-design:extract {run_base_flag} {url_flag} {images_flag} --prompt \"{enhanced_prompt}\" --variants 1"
command = "/workflow:ui-design:extract --base-path \"{base_path}\" {url_flag} {images_flag} --prompt \"{enhanced_prompt}\" --variants 1"
REPORT: "🚀 Phase 1: Style Extraction"
REPORT: " Source: {source_desc}"
REPORT: " Mode: Single style (imitation-optimized)"
REPORT: "🚀 Phase 1: Style Extraction | Source: {source_desc} | Mode: Single style (imitation-optimized)"
SlashCommand(command)
```
**Auto-Continue**: On completion → Phase 2
---
### Phase 2: Fast Token Adaptation (Bypass Consolidate)
**Action**: Direct extraction of design tokens, bypassing heavy `consolidate` step
**Execution**:
```bash
REPORT: "🚀 Phase 2: Fast token adaptation (bypassing consolidate)"
# Read single style card
style_cards = Read({base_path}/style-extraction/style-cards.json)
style_card = style_cards.style_cards[0]
@@ -320,74 +194,43 @@ Write({base_path}/style-consolidation/style-1/style-guide.md):
## Design Tokens
All tokens in `design-tokens.json` follow OKLCH color space.
**Key Colors**:
- Primary: {design_tokens.colors.brand.primary}
- Background: {design_tokens.colors.surface.background}
- Text: {design_tokens.colors.text.primary}
**Key Colors**: Primary: {design_tokens.colors.brand.primary} | Background: {design_tokens.colors.surface.background} | Text: {design_tokens.colors.text.primary}
**Typography**:
- Heading: {design_tokens.typography.font_family.heading}
- Body: {design_tokens.typography.font_family.body}
**Typography**: Heading: {design_tokens.typography.font_family.heading} | Body: {design_tokens.typography.font_family.body}
**Spacing Scale**: {design_tokens.spacing.keys().length} values
*Note: Generated in imitate mode for fast replication.*
REPORT: "✅ Tokens extracted and formatted"
REPORT: " Style: {style_name}"
REPORT: " Bypassed consolidate for {performance_gain}× speed"
REPORT: "✅ Tokens extracted and formatted | Style: {style_name} | Bypassed consolidate for {performance_gain}× speed"
```
**Auto-Continue**: On completion → Phase 3
---
### Phase 3: Single Prototype Generation
**Command**:
```bash
run_base_flag = "--base-path \"{base_path}\""
targets_string = ",".join(inferred_target_list)
targets_flag = "--targets \"{targets_string}\""
type_flag = "--target-type \"{target_type}\""
# Force 1×1 mode
command = "/workflow:ui-design:generate {run_base_flag} {targets_flag} {type_flag} --style-variants 1 --layout-variants 1"
type_emoji = "📄" IF target_type == "page" ELSE "🧩"
type_label = "page(s)" IF target_type == "page" ELSE "component(s)"
command = "/workflow:ui-design:generate --base-path \"{base_path}\" --targets \"{targets_string}\" --target-type \"{target_type}\" --style-variants 1 --layout-variants 1"
REPORT: "🚀 Phase 3: Generating {len(inferred_target_list)} {type_label}"
REPORT: " {type_emoji} Targets: {targets_string}"
REPORT: " Mode: 1×1 (imitation-optimized)"
REPORT: " {type_emoji} Targets: {targets_string} | Mode: 1×1 (imitation-optimized)"
SlashCommand(command)
# Result: Prototypes: {target}-style-1-layout-1.html, Total: len(inferred_target_list), Type: {target_type}
```
**Result**:
- Prototypes: `{target}-style-1-layout-1.html`
- Total: `len(inferred_target_list)`
- Type: {target_type} (full-page for pages, minimal wrapper for components)
**Auto-Continue**: On completion → Phase 4
---
### Phase 4: Design System Integration
**Command**:
```bash
IF --session:
session_flag = "--session {session_id}"
command = "/workflow:ui-design:update {session_flag}"
SlashCommand(command)
SlashCommand("/workflow:ui-design:update --session {session_id}")
ELSE:
REPORT: "ℹ️ Standalone mode: Skipping integration"
REPORT: " Prototypes at: {base_path}/prototypes/"
REPORT: "ℹ️ Standalone mode: Skipping integration | Prototypes at: {base_path}/prototypes/"
```
**Completion**: Workflow complete
## TodoWrite Pattern
```javascript
@@ -407,10 +250,7 @@ TodoWrite({todos: [
## Error Handling
- **No reference source**: Error if neither `--url` nor `--images` provided
- **Screenshot capture failure**:
- Tries 2 methods: Playwright → Chrome DevTools
- Falls back to manual upload: user uploads screenshot, skips, or aborts
- Gracefully handles missing Playwright/Chrome
- **Screenshot capture failure**: Tries Playwright → Chrome → Manual upload (user uploads, skips, or aborts); gracefully handles missing tools
- **Invalid URL/images**: Report error, suggest alternative input
- **Token extraction failure**: Fallback to minimal default design system
@@ -423,14 +263,9 @@ TodoWrite({todos: [
| **Variants** | 1-5 styles × 1-5 layouts | Always 1 × 1 |
| **Consolidate** | Full consolidation | **Bypassed** (direct tokens) |
| **Speed** | Baseline | **~2-3× faster** |
| **Output** | Matrix (S×L×P) | Direct (1×1×P) |
| **Phases** | 6 phases | 5 phases |
| **Output** | Matrix (S×L×T) | Direct (1×1×T) |
**Performance Benefits**:
1. **Skipped consolidate**: Saves ~30-60s (most expensive phase)
2. **Single variant**: Reduces extraction complexity
3. **Direct token mapping**: Simple file ops vs AI synthesis
4. **Streamlined decisions**: No variant selection/confirmation
**Performance Benefits**: Skipped consolidate (~30-60s saved), single variant, direct token mapping, streamlined decisions
## Example Execution Flows
@@ -438,13 +273,7 @@ TodoWrite({todos: [
```bash
/workflow:ui-design:imitate-auto --url "https://linear.app" --targets "home,features,pricing"
# Flow:
# 0. Init: 3 pages identified
# 0.5. Screenshot: Playwright captures linear.app
# 1. Extract: Single style from screenshot
# 2. Adapt: Direct tokens (~2s vs consolidate's ~45s)
# 3. Generate: 3 page prototypes
# 4. Complete
# Flow: 0 (3 pages) → 0.5 (Playwright captures) → 1 (single style) → 2 (direct tokens ~2s vs ~45s) → 3 (3 prototypes) → 4
# Time: ~2-3 min (vs 5-7 min with explore-auto)
```
@@ -453,8 +282,7 @@ TodoWrite({todos: [
/workflow:ui-design:imitate-auto --images "refs/dark-theme.png" --prompt "Focus on dark mode" --targets "dashboard"
# Flow: 0 → 0.5 (skip) → 1 → 2 → 3 → 4
# Output: dashboard-style-1-layout-1.html
# Type: page (full-page layout)
# Output: dashboard-style-1-layout-1.html | Type: page (full-page layout)
```
### Example 3: Component Mode
@@ -462,45 +290,27 @@ TodoWrite({todos: [
/workflow:ui-design:imitate-auto --url "https://example.com" --targets "navbar,hero,card" --target-type "component"
# Flow: 0 → 0.5 → 1 → 2 → 3 → 4
# Output: navbar-style-1-layout-1.html, hero-style-1-layout-1.html, card-style-1-layout-1.html
# Type: component (minimal wrapper for isolated comparison)
# Output: navbar/hero/card-style-1-layout-1.html | Type: component (minimal wrapper)
```
### Example 4: URL with Manual Screenshot
```bash
/workflow:ui-design:imitate-auto --url "https://stripe.com/pricing" --targets "pricing"
# 0.5. Screenshot:
# ⚠️ Playwright failed → Chrome failed
# 📸 User prompted for manual upload
# User saves screenshot → types 'ready' → ✅ continues
# OR types 'skip' → ⚠️ uses URL analysis only
# 0.5: Playwright failed → Chrome failed → User prompted → types 'ready' → ✅ continues OR 'skip' → ⚠️ URL only
# Continues: 1 → 2 → 3 → 4
```
### Example 5: Legacy Parameter Support
```bash
# Using legacy --pages parameter (backward compatible)
/workflow:ui-design:imitate-auto --url "https://example.com" --pages "home,dashboard"
# Equivalent to: --targets "home,dashboard" --target-type "page"
```
## Final Completion Message
```
✅ UI Design Imitation Complete!
Mode: Single Style Replication
Run ID: {run_id}
Session: {session_id or "standalone"}
Reference: {url OR images}
Type: {target_type_icon} {target_type_label}
Mode: Single Style Replication | Run ID: {run_id} | Session: {session_id or "standalone"} | Reference: {url OR images} | Type: {type_emoji} {type_label}
Phase 0 - Initialization: {target_count} {target_type}(s) prepared
Phase 0.5 - Screenshot Capture: {screenshot_status}
{IF success: ✅ Captured via {method}}
{ELSE: ⚠️ URL analysis only}
{IF success: ✅ Captured via {method} | ELSE: ⚠️ URL analysis only}
Phase 1 - Style Extraction: Single style extracted
Phase 2 - Token Adaptation: Bypassed consolidate (⚡ {time_saved}s saved)
Phase 3 - Prototype Generation: {target_count} {target_type} prototypes created
@@ -513,8 +323,7 @@ Phase 4 - Design Integration: {integrated OR "Standalone mode"}
🌐 Preview: {base_path}/prototypes/index.html
{target_type_icon} Targets: {', '.join(inferred_target_list)}
Type: {target_type}
{type_emoji} Targets: {', '.join(inferred_target_list)} | Type: {target_type}
Context: {IF target_type == "page": "Full-page layouts" ELSE: "Isolated components with minimal wrapper"}
Performance:
@@ -522,16 +331,5 @@ Performance:
- Total workflow: ~{total_time}s
- Speed improvement: ~{improvement}× faster than explore-auto
{IF session:
Next: /workflow:plan to create implementation tasks
}
{ELSE:
Prototypes ready: {base_path}/prototypes/
}
```
**Dynamic Values**:
- `target_type_icon`: "📄" for page, "🧩" for component
- `target_type_label`: "Pages" for page, "Components" for component
- `target_count`: `len(inferred_target_list)`
{IF session: Next: /workflow:plan to create implementation tasks | ELSE: Prototypes ready: {base_path}/prototypes/}
```

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

@@ -12,9 +12,11 @@ allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
# Design Update Command
## Overview
Synchronize finalized design system references to brainstorming artifacts, preparing them for `/workflow:plan` consumption. This command updates **references only** (via @ notation), not content duplication.
## Core Philosophy
- **Reference-Only Updates**: Use @ references, no content duplication
- **Main Claude Execution**: Direct updates by main Claude (no Agent handoff)
- **Synthesis Alignment**: Update synthesis-specification.md UI/UX Guidelines section
@@ -27,41 +29,26 @@ Synchronize finalized design system references to brainstorming artifacts, prepa
```bash
# Validate session
CHECK: .workflow/.active-* marker files
VALIDATE: session_id matches active session
CHECK: .workflow/.active-* marker files; VALIDATE: session_id matches active session
# Verify required design artifacts exist in latest design run
# Verify design artifacts in latest design run
latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-*")
# Detect design system structure (unified vs separate)
IF exists({latest_design}/style-consolidation/design-tokens.json):
# Unified mode (single design system)
design_system_mode = "unified"
design_tokens_path = "style-consolidation/design-tokens.json"
style_guide_path = "style-consolidation/style-guide.md"
design_system_mode = "unified"; design_tokens_path = "style-consolidation/design-tokens.json"; style_guide_path = "style-consolidation/style-guide.md"
ELSE IF exists({latest_design}/style-consolidation/style-1/design-tokens.json):
# Separate mode (per-style design systems)
design_system_mode = "separate"
design_tokens_path = "style-consolidation/style-1/design-tokens.json"
style_guide_path = "style-consolidation/style-1/style-guide.md"
design_system_mode = "separate"; design_tokens_path = "style-consolidation/style-1/design-tokens.json"; style_guide_path = "style-consolidation/style-1/style-guide.md"
ELSE:
ERROR: "No design tokens found. Run /workflow:ui-design:consolidate first"
VERIFY:
- {latest_design}/{design_tokens_path}
- {latest_design}/{style_guide_path}
- {latest_design}/prototypes/*.html (at least one prototype)
VERIFY: {latest_design}/{design_tokens_path}, {latest_design}/{style_guide_path}, {latest_design}/prototypes/*.html
REPORT: "📋 Design system mode: {design_system_mode}"
REPORT: " Tokens: {design_tokens_path}"
REPORT: "📋 Design system mode: {design_system_mode} | Tokens: {design_tokens_path}"
# Prototype selection
IF --selected-prototypes provided:
VALIDATE: Specified prototypes exist
selected_list = parse_comma_separated(--selected-prototypes)
ELSE:
AUTO-SELECT: Use all generated prototypes
selected_list = Glob({latest_design}/prototypes/*.html)
selected_list = --selected-prototypes ? parse_comma_separated(--selected-prototypes) : Glob({latest_design}/prototypes/*.html)
VALIDATE: Specified prototypes exist IF --selected-prototypes
REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
```
@@ -73,15 +60,14 @@ REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
```bash
# Load target brainstorming artifacts (files to be updated)
Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
Read(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md) [if exists]
IF exists(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md): Read(analysis.md)
# Optional: Read prototype notes for descriptions (minimal context)
FOR each selected_prototype IN selected_list:
Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}-notes.md)
# Extract: layout_strategy, page_name only
```
Read({latest_design}/prototypes/{selected_prototype}-notes.md) # Extract: layout_strategy, page_name only
**Note**: We do **NOT** read design-tokens.json, style-guide.md, or prototype HTML. We only verify they exist and generate @ references to them.
# Note: Do NOT read design-tokens.json, style-guide.md, or prototype HTML. Only verify existence and generate @ references.
```
### Phase 3: Update Synthesis Specification
@@ -106,39 +92,25 @@ Update `.brainstorming/synthesis-specification.md` with design system references
### Reference Prototypes
{FOR each selected_prototype:
- **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html
- Layout: {layout_strategy from notes}
- **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html | Layout: {layout_strategy from notes}
}
### Design System Assets
```json
{
"design_tokens": "design-{run_id}/{design_tokens_path}",
"style_guide": "design-{run_id}/{style_guide_path}",
"design_system_mode": "{design_system_mode}",
"prototypes": [
{FOR each: "design-{run_id}/prototypes/{prototype}.html"}
]
}
{"design_tokens": "design-{run_id}/{design_tokens_path}", "style_guide": "design-{run_id}/{style_guide_path}", "design_system_mode": "{design_system_mode}", "prototypes": [{FOR each: "design-{run_id}/prototypes/{prototype}.html"}]}
```
```
**Implementation**:
```bash
# Option 1: Edit existing section
Edit(
file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
old_string="## UI/UX Guidelines\n[existing content]",
new_string="## UI/UX Guidelines\n\n[new design reference content]"
)
Edit(file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
old_string="## UI/UX Guidelines\n[existing content]",
new_string="## UI/UX Guidelines\n\n[new design reference content]")
# Option 2: Append if section doesn't exist
IF section not found:
Edit(
file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
old_string="[end of document]",
new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]"
)
Edit(file_path="...", old_string="[end of document]", new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]")
```
### Phase 4: Update UI Designer Style Guide
@@ -172,29 +144,24 @@ For complete token definitions and usage examples, see:
- Style Guide: @../../design-{run_id}/{style_guide_path}
---
*Auto-generated by /workflow:ui-design:update*
*Last updated: {timestamp}*
*Auto-generated by /workflow:ui-design:update | Last updated: {timestamp}*
```
**Implementation**:
```bash
Write(
file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
content="[generated content with @ references]"
)
Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
content="[generated content with @ references]")
```
### Phase 5: Completion
```javascript
TodoWrite({
todos: [
{content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"},
{content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"},
{content: "Update synthesis-specification.md with design references", status: "completed", activeForm: "Updating synthesis spec"},
{content: "Create/update ui-designer/style-guide.md", status: "completed", activeForm: "Updating UI designer guide"}
]
});
TodoWrite({todos: [
{content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"},
{content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"},
{content: "Update synthesis-specification.md with design references", status: "completed", activeForm: "Updating synthesis spec"},
{content: "Create/update ui-designer/style-guide.md", status: "completed", activeForm: "Updating UI designer guide"}
]});
```
**Completion Message**:
@@ -206,9 +173,7 @@ Updated artifacts:
✓ ui-designer/style-guide.md - Design system reference guide
Design system assets ready for /workflow:plan:
- design-tokens.json
- style-guide.md
- {prototype_count} reference prototypes
- design-tokens.json | style-guide.md | {prototype_count} reference prototypes
Next: /workflow:plan [--agent] "<task description>"
The plan phase will automatically discover and utilize the design system.
@@ -224,14 +189,14 @@ Next: /workflow:plan [--agent] "<task description>"
└── style-guide.md # New or updated design reference guide
```
**@ Reference Format** (used in synthesis-specification.md):
**@ Reference Format** (synthesis-specification.md):
```
@../design-{run_id}/style-consolidation/design-tokens.json
@../design-{run_id}/style-consolidation/style-guide.md
@../design-{run_id}/prototypes/{prototype}.html
```
**@ Reference Format** (used in ui-designer/style-guide.md):
**@ Reference Format** (ui-designer/style-guide.md):
```
@../../design-{run_id}/style-consolidation/design-tokens.json
@../../design-{run_id}/style-consolidation/style-guide.md
@@ -243,14 +208,10 @@ Next: /workflow:plan [--agent] "<task description>"
After this update, `/workflow:plan` will discover design assets through:
**Phase 3: Intelligent Analysis** (`/workflow:tools:concept-enhanced`)
- Reads synthesis-specification.md
- Discovers @ references to design system files
- Includes design system context in ANALYSIS_RESULTS.md
- Reads synthesis-specification.md → Discovers @ references → Includes design system context in ANALYSIS_RESULTS.md
**Phase 4: Task Generation** (`/workflow:tools:task-generate`)
- Reads ANALYSIS_RESULTS.md
- Discovers design assets from synthesis-specification.md
- Includes design system paths in task JSON files
- Reads ANALYSIS_RESULTS.md → Discovers design assets → Includes design system paths in task JSON files
**Example Task JSON** (generated by task-generate):
```json
@@ -285,30 +246,11 @@ After update, verify:
## Key Features
1. **Reference-Only Updates**
- Uses @ notation for file references
- No content duplication between design and brainstorming spaces
- Lightweight, maintainable approach
2. **Main Claude Direct Execution**
- No Agent handoff (preserves context)
- Simple reference generation (no complex synthesis)
- Reliable path resolution
3. **Plan-Ready Output**
- `/workflow:plan` Phase 3 can discover design system
- Task generation includes design asset paths
- Clear integration points for implementation tasks
4. **Minimal Reading**
- Only reads target files to update (synthesis-specification.md, ui-designer/analysis.md)
- Verifies design file existence (no content reading)
- Optional: reads prototype notes for descriptions
5. **Flexible Prototype Selection**
- Auto-select all prototypes (default)
- Manual selection via --selected-prototypes parameter
- Validates prototype existence before referencing
1. **Reference-Only Updates**: Uses @ notation for file references, no content duplication, lightweight and maintainable
2. **Main Claude Direct Execution**: No Agent handoff (preserves context), simple reference generation, reliable path resolution
3. **Plan-Ready Output**: `/workflow:plan` Phase 3 can discover design system, task generation includes design asset paths, clear integration points
4. **Minimal Reading**: Only reads target files to update, verifies design file existence (no content reading), optional prototype notes for descriptions
5. **Flexible Prototype Selection**: Auto-select all prototypes (default), manual selection via --selected-prototypes parameter, validates existence
## Integration Points

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

@@ -279,8 +279,17 @@ All workflows use the same file structure definition regardless of complexity. *
├── [.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
│ ├── style-consolidation/ # Design system tokens (per-style)
│ │ ├── style-1/ # design-tokens.json, style-guide.md
│ │ └── style-N/
│ ├── prototypes/ # Generated HTML/CSS prototypes
│ │ ├── _templates/ # Target-specific layout plans and templates
│ │ │ ├── {target}-layout-{n}.json # Layout plan (target-specific)
│ │ │ ├── {target}-layout-{n}.html # HTML template
│ │ │ └── {target}-layout-{n}.css # CSS template
│ │ ├── {target}-style-{s}-layout-{l}.html # Final prototypes
│ │ ├── compare.html # Interactive matrix view
│ │ └── index.html # Navigation page
│ └── .run-metadata.json # Run configuration
│
└── WFS-[topic-slug]/
@@ -298,8 +307,17 @@ All workflows use the same file structure definition regardless of complexity. *
│ └── IMPL-*.*-summary.md # Subtask summaries
├── [design-*/] # UI design outputs (created by ui-design workflows)
│ ├── style-extraction/ # Style analysis results
│ ├── style-consolidation/ # Design system tokens
│ ├── style-consolidation/ # Design system tokens (per-style)
│ │ ├── style-1/ # design-tokens.json, style-guide.md
│ │ └── style-N/
│ ├── prototypes/ # Generated HTML/CSS prototypes
│ │ ├── _templates/ # Target-specific layout plans and templates
│ │ │ ├── {target}-layout-{n}.json # Layout plan (target-specific)
│ │ │ ├── {target}-layout-{n}.html # HTML template
│ │ │ └── {target}-layout-{n}.css # CSS template
│ │ ├── {target}-style-{s}-layout-{l}.html # Final prototypes
│ │ ├── compare.html # Interactive matrix view
│ │ └── index.html # Navigation page
│ └── .run-metadata.json # Run configuration
└── .task/ # Task definitions (REQUIRED)
├── IMPL-*.json # Main task definitions
@@ -312,6 +330,7 @@ All workflows use the same file structure definition regardless of complexity. *
- **Dynamic Files**: Subtask JSON files created during task decomposition
- **Scratchpad Usage**: `.scratchpad/` created when CLI commands run without active session
- **Design Usage**: `design-{timestamp}/` created by UI design workflows, `.design/` for standalone design runs
- **Layout Planning**: `prototypes/_templates/` contains target-specific layout plans (JSON) generated during UI generation phase
#### Scratchpad Directory (.scratchpad/)
**Purpose**: Centralized location for non-session-specific CLI outputs

235
.github/release-notes-v3.5.0.md vendored
View File

@@ -1,235 +0,0 @@
# 🎨 UI Design Workflow with Triple Vision Analysis & Interactive Preview
This release introduces a comprehensive UI design workflow system with triple vision analysis capabilities, interactive user checkpoints, zero agent overhead, and enhanced preview tools for real-time prototype comparison.
## 🌟 Major Features
### UI Design Workflow System
- **`/workflow:design:auto`**: Semi-autonomous workflow orchestrator with interactive checkpoints
- **`/workflow:design:style-extract`**: Triple vision analysis (Claude Code + Gemini + Codex)
- **`/workflow:design:style-consolidate`**: Token validation and style guide generation
- **`/workflow:design:ui-generate`**: Token-driven HTML/CSS prototype generation with preview tools
- **`/workflow:design:design-update`**: Design system integration into brainstorming artifacts
### 👁️ Triple Vision Analysis
- **Claude Code**: Quick initial visual analysis using native Read tool
- **Gemini Vision**: Deep semantic understanding of design intent
- **Codex Vision**: Structured pattern recognition with -i parameter
- **Consensus Synthesis**: Weighted combination strategy for robust results
### ⏸️ Interactive Checkpoints
- **Checkpoint 1**: User selects preferred style variants after extraction
- **Checkpoint 2**: User confirms selected prototypes before design update
- Pause-and-continue pattern for critical design decisions
### 🌐 Preview Enhancement System (NEW!)
- **`index.html`**: Master preview navigation with grid layout
- **`compare.html`**: Side-by-side comparison with responsive viewport toggles
- **`PREVIEW.md`**: Comprehensive preview instructions and server setup guide
- Synchronized scrolling for layout comparison
- Dynamic page switching and real-time responsive testing
### 🎯 Zero Agent Overhead
- Removed Task(conceptual-planning-agent) wrappers from design commands
- Direct bash execution for gemini-wrapper and codex commands
- Improved performance while preserving all functionality
## 🚀 Quick Start
### Complete Design Workflow
```bash
# Semi-autonomous workflow with user checkpoints
/workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" --batch-plan
```
### Individual Commands
```bash
# Extract design styles (triple vision analysis)
/workflow:design:style-extract --session WFS-auth --images "refs/*.png"
# Consolidate selected variants
/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
# Generate prototypes with preview tools
/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
# Preview generated prototypes
cd .workflow/WFS-auth/.design/prototypes
python -m http.server 8080 # Visit http://localhost:8080
# Integrate design system
/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
```
## 🎨 Design System Features
- **OKLCH Color Format**: Perceptually uniform color space
- **W3C Design Tokens**: Standard-compliant token format
- **WCAG 2.1 AA Compliance**: Automated accessibility validation
- **Style Override Support**: Runtime token customization with --style-overrides
- **Batch Task Generation**: Automatic task creation with --batch-plan
## 📊 Preview Tools
### Master Navigation (index.html)
- Grid layout of all generated prototypes
- Quick links to individual variants
- Metadata display (session ID, timestamps, page info)
- Direct access to implementation notes
### Side-by-Side Comparison (compare.html)
- Iframe-based comparison for multiple variants
- Responsive viewport toggles:
- Desktop (100%)
- Tablet (768px)
- Mobile (375px)
- Synchronized scrolling option
- Dynamic page switching dropdown
- Real-time variant comparison
### Preview Options
```bash
# Option 1: Direct browser (simplest)
cd .workflow/WFS-{session}/.design/prototypes
open index.html # or double-click
# Option 2: Local server (recommended)
python -m http.server 8080 # Python
npx http-server -p 8080 # Node.js
php -S localhost:8080 # PHP
# Visit: http://localhost:8080
```
## 📦 What's Included
### New Commands (5)
- `/workflow:design:auto`
- `/workflow:design:style-extract`
- `/workflow:design:style-consolidate`
- `/workflow:design:ui-generate`
- `/workflow:design:design-update`
### Generated Files
```
.workflow/WFS-{session}/.design/
├── style-extraction/
│ ├── claude_vision_analysis.json
│ ├── gemini_vision_analysis.json
│ ├── codex_vision_analysis.json
│ ├── semantic_style_analysis.json
│ ├── design-tokens.json
│ └── style-cards.json
├── style-consolidation/
│ ├── design-tokens.json (validated)
│ ├── style-guide.md
│ ├── tailwind.config.js
│ └── validation-report.json
└── prototypes/
├── index.html (NEW - preview navigation)
├── compare.html (NEW - side-by-side comparison)
├── PREVIEW.md (NEW - setup instructions)
├── {page}-variant-{n}.html
├── {page}-variant-{n}.css
└── design-tokens.css
```
## 🔄 Workflow Integration
Design phase fits seamlessly between brainstorming and planning:
```
Brainstorming → UI Design → Planning → Execution
↓ ↓ ↓ ↓
synthesis- design-tokens tasks with token-driven
specification + style design implementation
guide context
```
**Optional but recommended** for UI-heavy projects:
- User-facing applications
- Design system creation
- Brand-critical interfaces
- Accessibility compliance projects
## 💡 Benefits
### User Experience
- 🎨 Visual validation before implementation
- ⏸️ Interactive control at critical decision points
- 👁️ Comprehensive analysis from three AI vision sources
- 🌐 Real-time preview with comparison tools
- 🎯 Zero waiting with direct bash execution
### Code Quality
- 🔒 100% CSS values use custom properties
- ♿ WCAG AA validated at design phase
- 🎨 Single source of truth for visual design
- 🧪 Production-ready prototypes (semantic HTML5, responsive, accessible)
### Development Workflow
- 🔄 Seamless integration with existing workflow
- 🚀 Backward compatible (design phase optional)
- 📊 Better planning with design system context
- 🎯 Focused implementation from validated prototypes
## 📚 Documentation
- **README.md**: Updated with UI Design Workflow section
- **README_CN.md**: Chinese documentation for design workflow
- **CHANGELOG.md**: Comprehensive release notes with examples
- **Command Files**: Detailed implementation guides for all 5 commands
## 🔧 Technical Details
**Triple Vision Analysis Flow**:
```
Reference Images
↓
Claude Code (Read tool) → claude_vision_analysis.json
Gemini Vision (wrapper) → gemini_vision_analysis.json
Codex Vision (codex -i) → codex_vision_analysis.json
↓
Main Claude Synthesis → semantic_style_analysis.json
↓
Codex Token Generation → design-tokens.json, style-cards.json
```
**Checkpoint Workflow Pattern**:
```
User: /workflow:design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard"
↓
Phase 1: style-extract (automatic)
↓ [CHECKPOINT 1: User selects variants]
User: /workflow:design:style-consolidate --session WFS-xxx --variants "variant-1"
↓
Phase 3: ui-generate (automatic)
↓ [CHECKPOINT 2: User confirms prototypes]
User: /workflow:design:design-update --session WFS-xxx --selected-prototypes "dashboard-variant-1"
↓
Phase 5: batch-plan (optional, if --batch-plan flag)
```
## 🆙 Upgrade Instructions
```bash
# Windows (PowerShell)
Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content
# Linux/macOS (Bash/Zsh)
bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
```
## 🐛 Bug Fixes & Improvements
- Optimized agent architecture by removing unnecessary wrappers
- Improved execution performance with direct bash commands
- Enhanced documentation consistency across English and Chinese versions
- Updated phase numbering to accommodate new design phase
## 📝 Full Changelog
See [CHANGELOG.md](https://github.com/catlog22/Claude-Code-Workflow/blob/main/CHANGELOG.md) for complete details.
---
**Questions or Issues?**
- 📖 [Documentation](https://github.com/catlog22/Claude-Code-Workflow)
- 🐛 [Report Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
- 💬 [Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions)