diff --git a/.claude/commands/workflow/ui-design/batch-generate.md b/.claude/commands/workflow/ui-design/batch-generate.md new file mode 100644 index 00000000..3dd312dc --- /dev/null +++ b/.claude/commands/workflow/ui-design/batch-generate.md @@ -0,0 +1,1073 @@ +--- +name: batch-generate +description: Batch generate UI prototypes based on prompt and style/layout information from other commands +usage: /workflow:ui-design:batch-generate --prompt "" [--base-path ] [--session ] [--targets ""] [--target-type "page|component"] [--style-variants ] [--layout-variants ] +examples: + - /workflow:ui-design:batch-generate --prompt "Create modern dashboard with cards and charts" --style-variants 3 --layout-variants 2 + - /workflow:ui-design:batch-generate --prompt "E-commerce product listing page" --base-path ".workflow/.design/run-20250110-120000" + - /workflow:ui-design:batch-generate --prompt "Generate auth pages: login, signup, reset password" --session WFS-auth + - /workflow:ui-design:batch-generate --prompt "Create navbar, hero, and footer components" --target-type "component" --targets "navbar,hero,footer" +allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*), Glob(*), mcp__exa__web_search_exa(*) +--- + +# Batch Generate UI Prototypes Command + +**Executor**: Main orchestrator → @ui-design-agent (T×S parallel tasks) + +## Overview + +Batch generate production-ready UI prototypes (HTML/CSS) based on user prompt and existing style/layout information. This command intelligently discovers available design tokens and generates prototypes using **Target-Style-Centric** architecture for optimal component isolation. + +## Core Philosophy + +- **Prompt-Driven Generation**: User describes what to build, command infers targets and requirements +- **Smart Token Discovery**: Auto-detects consolidated or proposed tokens from previous commands +- **Target-Style-Centric**: Each of T×S agents generates L layouts for one target × one style +- **Parallel Batch Execution**: Automatic task batching with max 6 concurrent agents for optimal throughput +- **Progress Tracking**: TodoWrite shows batch-by-batch progress with clear visibility +- **Component Isolation**: Tasks completely independent, preventing cross-component interference +- **Style-Aware Structure**: HTML DOM adapts based on design_attributes (if available) +- **Flexible Integration**: Works with consolidate, extract, or other workflow outputs +- **Production-Ready**: Semantic HTML5, ARIA attributes, responsive design +- **Scalable**: Handles 1-30+ tasks efficiently with automatic batching + +## Input Parameters + +### Required Parameters + +**--prompt** `""` +- User's description of what to generate +- Used to infer targets, understand requirements, and guide generation +- Examples: + - `"Create dashboard with metrics cards and charts"` + - `"Generate authentication pages: login and signup"` + - `"Build navbar, hero section, and footer components"` + +### Optional Parameters + +**--base-path** `` +- Path to design run directory containing style information +- If omitted: Auto-detects latest design run from `.workflow/.design/*` or session directory +- Example: `.workflow/WFS-auth/design-run-20250110-120000` + +**--session** `` +- Workflow session ID (e.g., `WFS-auth`) +- If provided: Searches for design runs in `.workflow/WFS-{session}/design-*` +- Enables integration with session brainstorming artifacts + +**--targets** `""` +- Comma-separated list of targets to generate +- If omitted: Extracted from prompt using intelligent parsing +- Examples: `"home,dashboard,settings"` or `"navbar,hero,card"` + +**--target-type** `"page|component"` +- Type of targets to generate +- `page`: Full-page layouts with complete structure +- `component`: Isolated UI elements with minimal wrapper +- If omitted: Auto-detected from target names + +**--style-variants** `` +- Number of style variants to generate (1-5) +- If omitted: Auto-detected from available style directories +- Default: All available styles in consolidation or extraction directory + +**--layout-variants** `` +- Number of layout variants per target × style (1-5) +- If omitted: Default = 3 +- Each layout should be structurally different + +## Execution Protocol + +### Phase 0: Initialization + +```javascript +TodoWrite({todos: [ + {content: "Initialize and parse user prompt", status: "in_progress", activeForm: "Initializing"}, + {content: "Load style information and validate token sources", status: "pending", activeForm: "Loading styles"}, + {content: "Gather layout inspiration via MCP search", status: "pending", activeForm: "Gathering inspiration"}, + {content: "Launch T×S target-style agents for batch generation", status: "pending", activeForm: "Generating prototypes"}, + {content: "Verify all generated files", status: "pending", activeForm: "Verifying files"}, + {content: "Generate comparison files (compare.html, index.html)", status: "pending", activeForm: "Generating previews"} +]}); +``` + +**Base Path Resolution**: +```bash +# Priority 1: Explicit --base-path +IF --base-path: + base_path = {provided_base_path} + VERIFY: exists(base_path), "Base path does not exist" + +# Priority 2: Session-based discovery +ELSE IF --session: + candidate_paths = Glob(".workflow/WFS-{session}/design-*") + candidate_paths.sort_by_modification_time(descending) + base_path = candidate_paths[0] + VERIFY: base_path, "No design runs found for session {session}" + REPORT: "📁 Auto-detected session design run: {base_path}" + +# Priority 3: Latest design run +ELSE: + candidate_paths = Glob(".workflow/.design/run-*") + candidate_paths.sort_by_modification_time(descending) + base_path = candidate_paths[0] + VERIFY: base_path, "No design runs found. Run extract or consolidate first." + REPORT: "📁 Auto-detected latest design run: {base_path}" + +STORE: base_path +``` + +**Target Extraction from Prompt**: +```bash +# Use intelligent parsing to extract targets from prompt +prompt_text = --prompt + +# Example patterns: +# "Create dashboard with cards" → ["dashboard"] +# "Generate login, signup, and reset password pages" → ["login", "signup", "reset-password"] +# "Build navbar, hero, footer components" → ["navbar", "hero", "footer"] + +# If --targets explicitly provided, use those instead +IF --targets: + target_list = split_and_clean(--targets, delimiters=[",", ";", "、"]) + REPORT: "🎯 Using explicit targets: {', '.join(target_list)}" +ELSE: + # Parse targets from prompt using pattern matching + target_list = extract_targets_from_prompt(prompt_text) + REPORT: "🎯 Extracted targets from prompt: {', '.join(target_list)}" + + # Fallback if extraction fails + IF NOT target_list: + target_list = ["home"] + REPORT: "⚠️ Could not extract targets, defaulting to: ['home']" + +# Validate target names +validated_targets = [t for t in target_list if regex_match(t, r"^[a-z0-9][a-z0-9_-]*$")] +invalid_targets = [t for t in target_list if t not in validated_targets] + +IF invalid_targets: + REPORT: "⚠️ Skipped invalid target names: {', '.join(invalid_targets)}" + +VALIDATE: validated_targets not empty, "No valid targets found" +target_list = validated_targets + +# Auto-detect target type if not provided +IF --target-type: + target_type = --target-type +ELSE: + target_type = detect_target_type(target_list) + REPORT: "🔍 Auto-detected target type: {target_type}" + +STORE: target_list, target_type +``` + +### Phase 1: Token Source Discovery & Context Loading + +```bash +REPORT: "📊 Phase 1: Discovering token sources..." + +# Determine style variant count +style_variants = --style-variants OR auto_detect_from_directories() +layout_variants = --layout-variants OR 3 + +VALIDATE: 1 <= style_variants <= 5, "Style variants must be between 1-5" +VALIDATE: 1 <= layout_variants <= 5, "Layout variants must be between 1-5" + +# Smart token source detection (same logic as generate-v2.md Phase 1.2) +token_sources = {} +consolidated_count = 0 +proposed_count = 0 + +FOR style_id IN range(1, style_variants + 1): + # Priority 1: Consolidated tokens + consolidated_path = "{base_path}/style-consolidation/style-{style_id}/design-tokens.json" + + IF exists(consolidated_path): + token_sources[style_id] = { + "path": consolidated_path, + "quality": "consolidated", + "source": "consolidate command" + } + consolidated_count += 1 + REPORT: " ✓ Style-{style_id}: Using consolidated tokens (production-ready)" + CONTINUE + + # Priority 2: Proposed tokens from style-cards.json + style_cards_path = "{base_path}/style-extraction/style-cards.json" + + IF exists(style_cards_path): + style_cards_data = Read(style_cards_path) + + IF style_id <= len(style_cards_data.style_cards): + variant_index = style_id - 1 + variant = style_cards_data.style_cards[variant_index] + proposed_tokens = variant.proposed_tokens + + # Create temp consolidation directory + temp_consolidation_dir = "{base_path}/style-consolidation/style-{style_id}" + Bash(mkdir -p "{temp_consolidation_dir}") + + # Write proposed tokens (Fast Token Adaptation) + temp_tokens_path = "{temp_consolidation_dir}/design-tokens.json" + Write(temp_tokens_path, JSON.stringify(proposed_tokens, null, 2)) + + # Create simplified style guide + simple_guide_content = f"""# Design System: {variant.name} + +## Design Philosophy +{variant.design_philosophy} + +## Description +{variant.description} + +## Design Tokens +Complete token specification in `design-tokens.json`. + +**Note**: Using proposed tokens from extraction phase (fast-track mode). +For production-ready refinement, run `/workflow:ui-design:consolidate` first. +""" + + Write("{temp_consolidation_dir}/style-guide.md", simple_guide_content) + + token_sources[style_id] = { + "path": temp_tokens_path, + "quality": "proposed", + "source": "extract command (fast adaptation)" + } + proposed_count += 1 + + REPORT: " ✓ Style-{style_id}: Using proposed tokens (fast-track)" + REPORT: " Source: {variant.name} from style-cards.json" + WARN: " ⚠️ Tokens not refined - for production quality, run consolidate first" + CONTINUE + ELSE: + ERROR: "style-cards.json exists but does not contain variant {style_id}" + SUGGEST: "Reduce --style-variants to {len(style_cards_data.style_cards)} or run extract with more variants" + EXIT 1 + + # Priority 3: Error - no token source found + ERROR: "No token source found for style-{style_id}" + ERROR: " Expected either:" + ERROR: " 1. {consolidated_path} (from /workflow:ui-design:consolidate)" + ERROR: " 2. {style_cards_path} (from /workflow:ui-design:extract)" + SUGGEST: "Run one of the following commands first:" + SUGGEST: " - /workflow:ui-design:extract --base-path \"{base_path}\" --images \"refs/*.png\" --variants {style_variants}" + SUGGEST: " - /workflow:ui-design:consolidate --base-path \"{base_path}\" --variants {style_variants}" + EXIT 1 + +# Summary report +REPORT: "" +REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +REPORT: "📊 Token Source Summary:" +REPORT: " Total style variants: {style_variants}" +REPORT: " Consolidated (production-ready): {consolidated_count}/{style_variants}" +REPORT: " Proposed (fast-track): {proposed_count}/{style_variants}" + +IF proposed_count > 0: + REPORT: "" + REPORT: "💡 Production Quality Tip:" + REPORT: " Fast-track mode is active for {proposed_count} style(s)." + REPORT: " For production-ready quality with philosophy-driven refinement:" + REPORT: " /workflow:ui-design:consolidate --base-path \"{base_path}\" --variants {style_variants}" + +REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + +# Load design space analysis (if available) +design_space_path = "{base_path}/style-extraction/design-space-analysis.json" +IF exists(design_space_path): + design_space_analysis = Read(design_space_path) + REPORT: "📊 Loaded design space analysis with style attributes" +ELSE: + design_space_analysis = null + REPORT: "ℹ️ No design space analysis found - will use basic style generation" + +STORE: token_sources, design_space_analysis, style_variants, layout_variants + +TodoWrite: Mark "Load style information" as completed, "Gather layout inspiration" as in_progress +``` + +### Phase 2: Layout Inspiration Gathering + +```bash +REPORT: "💡 Phase 2: Gathering layout inspiration for {len(target_list)} targets..." + +CREATE: {base_path}/prototypes/_inspirations/ + +# For each target, gather layout inspiration via MCP search +FOR target IN target_list: + REPORT: " Researching '{target}' ({target_type}) layout patterns..." + + # Construct search query based on prompt and target + search_query = f"common {target} {target_type} layout patterns variations best practices" + + # Use MCP web search for layout inspiration + search_results = mcp__exa__web_search_exa( + query=search_query, + numResults=5 + ) + + # Generate inspiration content + inspiration_content = f"""Layout Inspiration for '{target}' ({target_type}) +Generated: {current_timestamp()} +Search Query: {search_query} + +## User Requirements +{extract_relevant_context_from_prompt(prompt_text, target)} + +## Layout Patterns Identified + +From web research, {layout_variants} distinct layout approaches: + +Layout 1: [First structural pattern identified from search] +- Key characteristics: ... +- Structure approach: ... + +Layout 2: [Second structural pattern] +- Key characteristics: ... +- Structure approach: ... + +Layout 3: [Third structural pattern] +- Key characteristics: ... +- Structure approach: ... + +## Reference Links +{format_search_results_urls(search_results)} + +## Implementation Notes +- Each layout should be STRUCTURALLY DIFFERENT (not just CSS variations) +- Consider {target_type}-specific patterns (navigation, content areas, interactions) +- Adapt structure based on design_attributes in Phase 3 +- Follow user requirements from prompt: {extract_relevant_requirements(prompt_text, target)} +""" + + # Write inspiration file + inspiration_file = f"{base_path}/prototypes/_inspirations/{target}-layout-ideas.txt" + Write(inspiration_file, inspiration_content) + + REPORT: f" ✓ Created: {target}-layout-ideas.txt" + +REPORT: f"✅ Phase 2 complete: Gathered inspiration for {len(target_list)} targets" + +TodoWrite: Mark "Gather layout inspiration" as completed, "Launch agents" as in_progress +``` + +### Phase 3: Target-Style-Centric Batch Generation with Parallel Control + +```bash +REPORT: "🎨 Phase 3: Launching {len(target_list)}×{style_variants}={len(target_list) * style_variants} target-style agents..." +REPORT: " Each agent generates {layout_variants} layouts for one target × one style" + +CREATE: {base_path}/prototypes/ + +# ===== PARALLEL EXECUTION CONTROL ===== +# Maximum concurrent agents: 6 +MAX_PARALLEL_AGENTS = 6 + +# Build complete task list (T×S combinations) +all_tasks = [] +FOR target IN target_list: + FOR style_id IN range(1, style_variants + 1): + all_tasks.append({ + "target": target, + "style_id": style_id, + "task_id": f"{target}-style-{style_id}" + }) + +total_tasks = len(all_tasks) +total_batches = ceil(total_tasks / MAX_PARALLEL_AGENTS) + +REPORT: "" +REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +REPORT: "📊 Batch Execution Plan:" +REPORT: " Total tasks: {total_tasks} (T={len(target_list)} × S={style_variants})" +REPORT: " Max parallel: {MAX_PARALLEL_AGENTS} agents" +REPORT: " Total batches: {total_batches}" +REPORT: " Tasks per batch: ~{min(MAX_PARALLEL_AGENTS, total_tasks)}" +REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +REPORT: "" + +# Initialize TodoWrite with batch tracking +batch_todos = [] +FOR batch_num IN range(1, total_batches + 1): + start_idx = (batch_num - 1) * MAX_PARALLEL_AGENTS + end_idx = min(batch_num * MAX_PARALLEL_AGENTS, total_tasks) + batch_size = end_idx - start_idx + batch_tasks = all_tasks[start_idx:end_idx] + task_ids = [task["task_id"] for task in batch_tasks] + + batch_todos.append({ + "content": f"Batch {batch_num}/{total_batches}: Generate {batch_size} target-style combinations ({', '.join(task_ids[:3])}{'...' if batch_size > 3 else ''})", + "status": "pending" if batch_num > 1 else "in_progress", + "activeForm": f"Generating batch {batch_num}/{total_batches} ({batch_size} tasks)" + }) + +TodoWrite({todos: batch_todos}) + +# ===== BATCH EXECUTION LOOP ===== +FOR batch_num IN range(1, total_batches + 1): + start_idx = (batch_num - 1) * MAX_PARALLEL_AGENTS + end_idx = min(batch_num * MAX_PARALLEL_AGENTS, total_tasks) + batch_tasks = all_tasks[start_idx:end_idx] + batch_size = len(batch_tasks) + + REPORT: "" + REPORT: f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + REPORT: f"🚀 Starting Batch {batch_num}/{total_batches}" + REPORT: f" Tasks: {start_idx + 1}-{end_idx} of {total_tasks}" + REPORT: f" Parallel agents: {batch_size}" + REPORT: f"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + + # Launch all tasks in this batch in parallel (single message with multiple Task calls) + FOR task_info IN batch_tasks: + target = task_info["target"] + style_id = task_info["style_id"] + + # Load layout inspiration for this target + inspiration_path = f"{base_path}/prototypes/_inspirations/{target}-layout-ideas.txt" + + # Load style-specific context + style_tokens_path = token_sources[style_id]["path"] + style_guide_path = f"{base_path}/style-consolidation/style-{style_id}/style-guide.md" + + # Extract design attributes for this style (if available) + IF design_space_analysis AND style_id <= len(design_space_analysis.divergent_directions): + design_attributes = design_space_analysis.divergent_directions[style_id - 1] + philosophy_name = design_attributes.philosophy_name + attributes_summary = JSON.stringify({ + density: design_attributes.design_attributes.density, + visual_weight: design_attributes.design_attributes.visual_weight, + formality: design_attributes.design_attributes.formality, + organic_vs_geometric: design_attributes.design_attributes.organic_vs_geometric, + innovation: design_attributes.design_attributes.innovation + }) + ELSE: + design_attributes = null + philosophy_name = f"Style {style_id}" + attributes_summary = "No design attributes available" + + # Extract relevant requirements from prompt for this target + target_requirements = extract_relevant_context_from_prompt(prompt_text, target) + + REPORT: f" → Launching: {target} × Style-{style_id} ({philosophy_name})" + + Task(ui-design-agent): """ + [TARGET_STYLE_UI_GENERATION_FROM_PROMPT] + + ## 🎯 Mission + Generate {layout_variants} layout variants for: {target} × Style-{style_id} ({philosophy_name}) + Output: {layout_variants × 2} files ({layout_variants} HTML + {layout_variants} CSS) + + ## 📝 User Requirements (from prompt) + {target_requirements} + + **Original Prompt**: {prompt_text} + + ## 🎨 Style Context + PHILOSOPHY: {philosophy_name} + {IF design_attributes: + DESIGN_ATTRIBUTES: {attributes_summary} + Key impacts: + - density → DOM nesting depth, whitespace scale + - visual_weight → wrapper layers, border/shadow strength + - formality → semantic structure choices + - organic_vs_geometric → alignment, edge treatment + - innovation → layout adventurousness + } + + ## 📂 Input Resources + **Design System**: + - Design Tokens (JSON): {style_tokens_path} + - Style Guide: {style_guide_path} + + **Layout Inspiration**: {inspiration_path} + Contains {layout_variants} distinct structural patterns + + **Target**: {target} ({target_type}) + + ## 🔄 Generation Steps (for each layout 1..{layout_variants}) + + **1. Understand User Requirements** + - Review original prompt: {prompt_text} + - Focus on requirements for: {target} + - Understand functional and visual expectations + + **2. Read Inspiration** + - Load: {inspiration_path} + - Apply layout N pattern + - Adapt based on user requirements + + **3. Read Design Tokens** + - Load: {style_tokens_path} + - Parse JSON structure and extract all design token values + - Understand token categories: colors, typography, spacing, shadows, borders, etc. + + **4. Generate HTML Structure** + - Complete HTML5 document (, , , ) + - Semantic elements:
,