diff --git a/.claude/agents/ui-design-agent.md b/.claude/agents/ui-design-agent.md index 9c0c8386..580c8dc2 100644 --- a/.claude/agents/ui-design-agent.md +++ b/.claude/agents/ui-design-agent.md @@ -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. " ``` diff --git a/.claude/commands/workflow/ui-design/explore-auto.md b/.claude/commands/workflow/ui-design/explore-auto.md index 4fce3621..8d64cf60 100644 --- a/.claude/commands/workflow/ui-design/explore-auto.md +++ b/.claude/commands/workflow/ui-design/explore-auto.md @@ -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 diff --git a/.claude/commands/workflow/ui-design/imitate-auto.md b/.claude/commands/workflow/ui-design/imitate-auto.md index 1063fe19..0aba2224 100644 --- a/.claude/commands/workflow/ui-design/imitate-auto.md +++ b/.claude/commands/workflow/ui-design/imitate-auto.md @@ -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 ""`: Website URL to imitate (e.g., "https://linear.app") -- `--images ""`: Local reference images (e.g., "refs/*.png") +**Required** (at least one): `--url ""` OR `--images ""` -**Optional**: -- `--targets ""`: Comma-separated targets (pages/components) to generate (inferred from prompt if omitted) -- `--target-type "page|component"`: Explicitly set target type (default: intelligent detection) -- `--session "`: Workflow session ID (standalone if omitted) -- `--prompt ""`: Additional design guidance (e.g., "Focus on dark mode") +**Optional**: `--targets ""`, `--target-type "page|component"`, `--session `, `--prompt ""` -**Legacy Parameters** (maintained for backward compatibility): -- `--pages ""`: Alias for `--targets` with `--target-type page` +**Legacy**: `--pages ""` (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/} ``` diff --git a/.claude/commands/workflow/ui-design/update.md b/.claude/commands/workflow/ui-design/update.md index 22bd6e48..52344cb6 100644 --- a/.claude/commands/workflow/ui-design/update.md +++ b/.claude/commands/workflow/ui-design/update.md @@ -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] "" The plan phase will automatically discover and utilize the design system. @@ -224,14 +189,14 @@ Next: /workflow:plan [--agent] "" └── 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] "" 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 diff --git a/.claude/workflows/workflow-architecture.md b/.claude/workflows/workflow-architecture.md index 905c929f..0ed7f85c 100644 --- a/.claude/workflows/workflow-architecture.md +++ b/.claude/workflows/workflow-architecture.md @@ -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 diff --git a/.github/release-notes-v3.5.0.md b/.github/release-notes-v3.5.0.md deleted file mode 100644 index 23dfd34b..00000000 --- a/.github/release-notes-v3.5.0.md +++ /dev/null @@ -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)