From f6292a6288ea8be960b00dc3b966efd00668b3ce Mon Sep 17 00:00:00 2001 From: catlog22 Date: Fri, 10 Oct 2025 09:41:49 +0800 Subject: [PATCH] refactor(ui-design): relocate MCP research from extract to consolidate agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Extract Changes:** - Remove Phase 1.5 MCP trend research (Exa queries) - Save design-space-analysis.json with search keywords for consolidate - Update to pure Claude-native analysis (aligns with philosophy) - Simplify completion todos and output documentation **Consolidate Changes:** - Load design-space-analysis.json from extraction phase - Add Step 1: Variant-Specific Trend Research (MCP) to agent prompt - Agent performs 4 MCP queries per variant + shared accessibility research - Refine tokens using trend insights while maintaining variant identity - Update completion reporting and key features **Generate Changes:** - Enhance HTML placeholder documentation with critical warnings - Add complete HTML template examples (page/component modes) - Clarify {{STRUCTURAL_CSS}} and {{TOKEN_CSS}} placeholder rules - Simplify agent completion requirements (remove detailed report format) - Allow agent to self-report completion status **Benefits:** - Extract becomes truly Claude-native (no external tools) - Consolidate agent handles all MCP research in one place - Better separation of concerns between phases - Clearer template generation instructions for agents - More flexible agent reporting 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../workflow/ui-design/consolidate.md | 494 ++++----- .../commands/workflow/ui-design/extract.md | 570 +++-------- .../commands/workflow/ui-design/generate.md | 969 ++++++++---------- 3 files changed, 769 insertions(+), 1264 deletions(-) diff --git a/.claude/commands/workflow/ui-design/consolidate.md b/.claude/commands/workflow/ui-design/consolidate.md index 270624fe..c3ef24e5 100644 --- a/.claude/commands/workflow/ui-design/consolidate.md +++ b/.claude/commands/workflow/ui-design/consolidate.md @@ -8,10 +8,6 @@ parameters: type: number default: all available variants from style-cards.json description: "Number of style variants to consolidate (1-N). Processes first N variants from style-cards.json. Creates style-N directories." - - name: --layout-variants - type: number - default: 3 - description: "Number of layout strategies to generate (1-5). Creates dynamic layout plans based on project context and modern trends." - name: --session type: string description: "Workflow session ID (e.g., WFS-auth). Finds latest design run in session directory." @@ -19,27 +15,26 @@ parameters: type: string description: "Custom base path for input/output. Overrides --session if provided." examples: - - /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --variants 3 --layout-variants 3 - - /workflow:ui-design:consolidate --session WFS-auth --variants 2 --layout-variants 2 - - /workflow:ui-design:consolidate --base-path "./.workflow/.design/run-20250109-150533" # Uses all variants, default 3 layouts - - /workflow:ui-design:consolidate --session WFS-auth --layout-variants 2 # Process all variants from extraction + - /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --variants 3 + - /workflow:ui-design:consolidate --session WFS-auth --variants 2 + - /workflow:ui-design:consolidate --base-path "./.workflow/.design/run-20250109-150533" # Uses all variants + - /workflow:ui-design:consolidate --session WFS-auth # Process all variants from extraction allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(*) --- -# Design System Consolidation & Layout Planning Command +# Design System Consolidation Command ## Overview -Consolidate user-selected style variants into **independent production-ready design systems** AND plan layout strategies for UI generation. This command serves as the **Design Planning Phase**, producing all strategic decisions needed for the subsequent generation phase. +Consolidate user-selected style variants into **independent production-ready design systems**. This command serves as the **Style Planning Phase**, focusing exclusively on design tokens and style guides for the subsequent generation phase. ## Core Philosophy -- **Design Planning Hub**: Centralizes both style consolidation and layout strategy planning +- **Style System Focus**: Exclusively handles design system consolidation - **Agent-Driven**: Uses ui-design-agent for multi-file generation efficiency - **Separate Design Systems**: Generates N independent design systems (one per variant) - **Token Refinement**: Refines `proposed_tokens` from each variant into complete systems -- **Layout Strategy Definition**: Plans and documents layout variants for generation - **Intelligent Synthesis**: Ensures completeness and consistency - **Production-Ready**: Complete design system(s) with documentation -- **Matrix-Ready**: Supports style × layout matrix exploration in generate phase +- **Matrix-Ready**: Provides style variants for style × layout matrix exploration in generate phase ## Execution Protocol @@ -47,13 +42,9 @@ Consolidate user-selected style variants into **independent production-ready des ```bash # Determine base path -IF --base-path provided: - base_path = {provided_base_path} -ELSE IF --session provided: - # Find latest design run in session - base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*") -ELSE: - base_path = find_latest_path_matching(".workflow/.design/*") +IF --base-path: base_path = {provided_base_path} +ELSE IF --session: base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*") +ELSE: base_path = find_latest_path_matching(".workflow/.design/*") # Verify extraction output exists style_cards_path = "{base_path}/style-extraction/style-cards.json" @@ -68,7 +59,7 @@ total_variants = len(style_cards.style_cards) ```bash # Determine how many variants to consolidate -IF --variants provided: +IF --variants: variants_count = {provided_count} VALIDATE: 1 <= variants_count <= total_variants ELSE: @@ -81,113 +72,24 @@ VERIFY: selected_variants.length > 0 REPORT: "📦 Generating {variants_count} independent design systems" ``` -### Phase 2.5: Layout Strategy Planning (Dynamic Generation) - -```bash -# Determine layout variants count -IF --layout-variants provided: - layout_variants = {provided_count} - VALIDATE: 1 <= layout_variants <= 5 -ELSE: - layout_variants = 3 # Default to 3 layout strategies - -REPORT: "📐 Planning {layout_variants} layout strategies (dynamic generation)" - -# Step 1: Gather project context for layout planning -project_context = "" -IF exists({base_path}/.brainstorming/synthesis-specification.md): - project_context = Read({base_path}/.brainstorming/synthesis-specification.md) -ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md): - project_context = Read({base_path}/.brainstorming/ui-designer/analysis.md) - -# Extract project type and requirements from context -project_hints = extract_project_type(project_context) # e.g., "dashboard", "marketing site", "SaaS platform" - -# Step 2: Search for current UI/UX layout trends using Exa MCP -REPORT: "🔍 Searching for modern UI layout patterns..." -exa_query = "modern web UI layout patterns design systems {project_hints} 2024 2025" -layout_trends = mcp__exa__get_code_context_exa( - query=exa_query, - tokensNum="dynamic" -) - -# Step 3: Generate layout strategies dynamically with Claude -REPORT: "🎨 Generating {layout_variants} custom layout strategies..." - -layout_synthesis_prompt = """ -Generate EXACTLY {layout_variants} distinct, modern UI layout strategies for this project. - -PROJECT CONTEXT: -{project_context} - -CURRENT LAYOUT TRENDS (from web research): -{layout_trends} - -REQUIREMENTS: -1. Generate EXACTLY {layout_variants} unique layout strategies (not more, not less) -2. Each layout must be unique and serve different use cases -3. Consider modern design trends from 2024-2025 -4. Align with project type: {project_hints} -5. Balance innovation with usability -6. Cover diverse layout paradigms (grid-based, asymmetric, minimal, single-column, sidebar-based, etc.) - -OUTPUT FORMAT (JSON): -You MUST generate {layout_variants} strategy objects in the "strategies" array. - -Example for layout_variants=3: -{ - "layout_variants_count": 3, - "strategies": [ - { - "id": "layout-1", - "name": "Grid Dashboard", - "description": "Traditional grid-based layout with sidebar navigation. Clear visual hierarchy with card-based content areas. Ideal for data-heavy dashboards." - }, - { - "id": "layout-2", - "name": "Asymmetric Flow", - "description": "Dynamic asymmetric layout with floating content blocks. Natural reading flow with varied content widths. Perfect for content-focused applications." - }, - { - "id": "layout-3", - "name": "Minimal Centered", - "description": "Clean centered layout with generous whitespace. Single-column focus with subtle hierarchy. Best for documentation or blog-style interfaces." - } - ] -} - -IMPORTANT: -- The "strategies" array MUST contain EXACTLY {layout_variants} objects -- Each strategy must have sequential IDs: "layout-1", "layout-2", ..., "layout-{layout_variants}" -- Each strategy name must be concise (max 3 words) -- Each description must be detailed (2-3 sentences covering structure, hierarchy, use cases) - -RESPONSE FORMAT: -Provide ONLY the JSON object, no additional text before or after. - -===== layout-strategies.json ===== -{JSON content} -""" - -# Execute synthesis -claude_response = synthesize_with_claude(layout_synthesis_prompt) -layout_strategies = parse_json_response(claude_response) - -# Step 4: Write layout strategies to file -Write({base_path}/style-consolidation/layout-strategies.json, JSON.stringify(layout_strategies, null, 2)) - -REPORT: "✅ Layout strategies defined: {[s.name for s in layout_strategies.strategies]}" -``` - ### Phase 3: Load Design Context (Optional) ```bash # Load brainstorming context if available design_context = "" IF exists({base_path}/.brainstorming/synthesis-specification.md): - design_context = Read({base_path}/.brainstorming/synthesis-specification.md) + design_context = Read(synthesis-specification.md) ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md): - design_context = Read({base_path}/.brainstorming/ui-designer/analysis.md) + design_context = Read(ui-designer/analysis.md) + +# Load design space analysis from extraction phase +design_space_analysis = {} +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 {len(design_space_analysis.divergent_directions)} variant directions" +ELSE: + REPORT: "⚠️ No design space analysis found - trend research will be skipped" ``` ### Phase 4: Design System Synthesis (Agent Execution) @@ -195,63 +97,128 @@ ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md): ```bash REPORT: "🤖 Using agent for separate design system generation..." +# Create output directories +Bash(mkdir -p "{base_path}/style-consolidation/style-{{1..{variants_count}}}") + # Prepare agent task prompt agent_task_prompt = """ -Generate {variants_count} independent production-ready design systems, one for each style variant. +Generate {variants_count} independent production-ready design systems with external trend research and WRITE them to the file system. +## Context SESSION: {session_id} -MODE: Separate design system generation - +MODE: Separate design system generation with MCP trend research +BASE_PATH: {base_path} VARIANTS TO PROCESS: {variants_count} -VARIANT DATA: +## Variant Data {FOR each variant IN selected_variants: --- - Variant ID: {variant.id} - Name: {variant.name} + Variant ID: {variant.id} | Name: {variant.name} Description: {variant.description} Design Philosophy: {variant.design_philosophy} - - Proposed Tokens: - {JSON.stringify(variant.proposed_tokens, null, 2)} + Proposed Tokens: {JSON.stringify(variant.proposed_tokens, null, 2)} --- } -{IF design_context: -DESIGN CONTEXT (from brainstorming): -{design_context} +{IF design_context: DESIGN CONTEXT (from brainstorming): {design_context}} + +{IF design_space_analysis: +## Design Space Analysis (for MCP Research) +{JSON.stringify(design_space_analysis, null, 2)} + +Note: Each variant has search_keywords and anti_keywords for trend research. } -TASK: For EACH variant, generate a complete, production-ready design system. +## Task +For EACH variant (1 to {variants_count}): +1. **Perform Variant-Specific Trend Research** (if design space analysis available) +2. **Refine design tokens** using research insights +3. **Generate and WRITE 2 files** to the file system -REFINEMENT RULES (apply to each variant): -1. **Complete Token Coverage**: Ensure all categories are present (colors, typography, spacing, etc.) -2. **Fill Gaps**: If any tokens are missing, generate appropriate values based on the variant's philosophy -3. **Maintain Style Identity**: Preserve the unique characteristics of this variant -4. **Semantic Naming**: Use clear, semantic names (e.g., "brand-primary" not "color-1") -5. **Accessibility**: Validate WCAG AA contrast ratios (4.5:1 text, 3:1 UI) -6. **OKLCH Format**: All colors must use oklch(L C H / A) format -7. **Design Philosophy**: Expand and articulate the variant's design philosophy +## Step 1: Variant-Specific Trend Research (MCP) -OUTPUT STRUCTURE: For each variant {variant_id} (1 to {variants_count}), generate 2 files: +IF design_space_analysis is provided, FOR EACH variant: -FILE 1: style-{variant_id}/design-tokens.json +1. **Extract Research Parameters** from design space analysis: + - philosophy_name: The variant's design philosophy + - search_keywords: Keywords for trend research + - anti_keywords: Patterns to avoid + +2. **Build Variant-Specific Queries**: + ```javascript + queries = [ + `{philosophy_name} UI design color palettes {search_keywords[:3]} 2024 2025`, + `{philosophy_name} typography trends {search_keywords[:3]} web design 2024`, + `{philosophy_name} layout patterns {search_keywords[:3]} design systems 2024`, + `design systems {philosophy_name} NOT {anti_keywords[:2]}` + ] + ``` + +3. **Execute MCP Searches**: + ```javascript + trend_research = { + colors: mcp__exa__get_code_context_exa(query=queries[0], tokensNum=2000), + typography: mcp__exa__get_code_context_exa(query=queries[1], tokensNum=2000), + layout: mcp__exa__get_code_context_exa(query=queries[2], tokensNum=2000), + contrast: mcp__exa__get_code_context_exa(query=queries[3], tokensNum=2000) + } + ``` + +4. **Shared Accessibility Research** (execute once, apply to all variants): + ```javascript + accessibility_guidelines = mcp__exa__get_code_context_exa( + query="WCAG 2.2 accessibility color contrast ARIA best practices 2024", + tokensNum=1500 + ) + ``` + +5. **Use Research Results** to inform token refinement: + - Color token refinement guided by `trend_research.colors` + - Typography refinement guided by `trend_research.typography` + - Layout spacing informed by `trend_research.layout` + - Contrast validation using `trend_research.contrast` and `accessibility_guidelines` + +IF design_space_analysis is NOT provided: +- Skip trend research +- Refine tokens based solely on variant's existing philosophy and proposed tokens + +## Step 2: Refinement Rules (apply to each variant) +1. **Complete Token Coverage**: Ensure all categories present (colors, typography, spacing, etc.) +2. **Fill Gaps**: Generate missing tokens based on variant's philosophy and trend research +3. **Maintain Style Identity**: Preserve unique characteristics from proposed tokens +4. **Semantic Naming**: Use clear names (e.g., "brand-primary" not "color-1") +5. **Accessibility**: Validate WCAG AA contrast using accessibility guidelines (4.5:1 text, 3:1 UI) +6. **OKLCH Format**: All colors use oklch(L C H / A) format +7. **Design Philosophy**: Expand variant's design philosophy using trend insights +8. **Trend Integration**: Incorporate modern trends from MCP research while maintaining variant identity + +## Step 3: File Write Instructions +For EACH variant {variant_id} (1 to {variants_count}), WRITE these 2 files: + +### File 1: Design Tokens +**Path**: {base_path}/style-consolidation/style-{variant_id}/design-tokens.json +**Content**: Complete design token JSON with structure: +```json { "colors": { - "brand": { "primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)" }, - "surface": { "background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)" }, - "semantic": { "success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)" }, - "text": { "primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)" }, - "border": { "default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)" } + "brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"}, + "surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"}, + "semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"}, + "text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"}, + "border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"} }, - "typography": { "font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...} }, - "spacing": { "0": "0", "1": "0.25rem", ..., "24": "6rem" }, - "border_radius": { "none": "0", "sm": "0.25rem", ..., "full": "9999px" }, - "shadows": { "sm": "...", "md": "...", "lg": "...", "xl": "..." }, - "breakpoints": { "sm": "640px", ..., "2xl": "1536px" } + "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}}, + "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"}, + "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"}, + "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."}, + "breakpoints": {"sm": "640px", ..., "2xl": "1536px"} } +``` -FILE 2: style-{variant_id}/style-guide.md +### File 2: Style Guide +**Path**: {base_path}/style-consolidation/style-{variant_id}/style-guide.md +**Content**: Markdown documentation with structure: +```markdown # Design System Style Guide - {variant.name} ## Design Philosophy @@ -272,112 +239,124 @@ FILE 2: style-{variant_id}/style-guide.md - All text meets WCAG AA (4.5:1 minimum) - UI components meet WCAG AA (3:1 minimum) - Focus indicators are clearly visible +``` -RESPONSE FORMAT: -For each variant, provide clearly labeled sections: +## Write Operation Instructions +- Use Write() tool for each file with the absolute paths provided above +- Verify each write operation succeeds +- Report completion with file paths and sizes +- DO NOT return file contents as text -===== style-1/design-tokens.json ===== -{JSON content} +## Example Write Operations +```javascript +// For variant 1 +Write("{base_path}/style-consolidation/style-1/design-tokens.json", JSON.stringify(tokens, null, 2)) +Write("{base_path}/style-consolidation/style-1/style-guide.md", guide_content) -===== style-1/style-guide.md ===== -{Markdown content} +// For variant 2 +Write("{base_path}/style-consolidation/style-2/design-tokens.json", JSON.stringify(tokens, null, 2)) +Write("{base_path}/style-consolidation/style-2/style-guide.md", guide_content) +``` -===== style-2/design-tokens.json ===== -{JSON content} +## Expected Final Report +Report which files were written and their sizes: +``` +✅ Written: {base_path}/style-consolidation/style-1/design-tokens.json (12.5 KB) +✅ Written: {base_path}/style-consolidation/style-1/style-guide.md (8.3 KB) +✅ Written: {base_path}/style-consolidation/style-2/design-tokens.json (11.8 KB) +✅ Written: {base_path}/style-consolidation/style-2/style-guide.md (7.9 KB) +... (for all {variants_count} variants) +``` -===== style-2/style-guide.md ===== -{Markdown content} - -... (repeat for all {variants_count} variants) - -IMPORTANT: +## Critical Requirements - Generate files for ALL {variants_count} variants - Use sequential IDs: style-1, style-2, ..., style-{variants_count} - Each variant must be complete and independent - Maintain consistent structure across all variants +- Write files directly using Write() tool - do NOT return contents as text """ # Execute agent task -Task( - subagent_type="ui-design-agent", - description="Generate {variants_count} separate design systems", - prompt=agent_task_prompt -) +Task(subagent_type="ui-design-agent", description="Generate {variants_count} separate design systems", prompt=agent_task_prompt) REPORT: "✅ Agent task dispatched for {variants_count} design systems" ``` -### Phase 5: Process Agent Results and Generate Report +### Phase 5: Verify Agent File Creation ```bash -REPORT: "📝 Processing agent output for {variants_count} design systems..." +REPORT: "📝 Verifying agent file creation for {variants_count} design systems..." -# Parse agent's response - agent returns all files in labeled sections -agent_output = get_agent_response() - -# Extract and write files for each variant +# Verify each variant's files were created by agent FOR variant_id IN range(1, variants_count + 1): - CREATE: {base_path}/style-consolidation/style-{variant_id}/ + tokens_path = "{base_path}/style-consolidation/style-{variant_id}/design-tokens.json" + guide_path = "{base_path}/style-consolidation/style-{variant_id}/style-guide.md" - # Extract design tokens - design_tokens_section = extract_section(agent_output, f"===== style-{variant_id}/design-tokens.json =====") - design_tokens = parse_json(design_tokens_section) - Write({base_path}/style-consolidation/style-{variant_id}/design-tokens.json, JSON.stringify(design_tokens, null, 2)) + # Verify files exist + VERIFY: exists(tokens_path), "Design tokens not created by agent for style-{variant_id}" + VERIFY: exists(guide_path), "Style guide not created by agent for style-{variant_id}" - # Extract style guide - style_guide_section = extract_section(agent_output, f"===== style-{variant_id}/style-guide.md =====") - Write({base_path}/style-consolidation/style-{variant_id}/style-guide.md, style_guide_section) + # Optional: Validate JSON structure + TRY: + tokens = Read(tokens_path) + tokens_json = parse_json(tokens) + VALIDATE: tokens_json.colors exists, "Missing colors in design-tokens.json" + VALIDATE: tokens_json.typography exists, "Missing typography in design-tokens.json" + VALIDATE: tokens_json.spacing exists, "Missing spacing in design-tokens.json" - REPORT: " ✅ style-{variant_id}/ written" + tokens_size = get_file_size(tokens_path) + guide_size = get_file_size(guide_path) + REPORT: " ✅ style-{variant_id}/ verified ({tokens_size} KB tokens, {guide_size} KB guide)" + CATCH error: + ERROR: "Validation failed for style-{variant_id}: {error}" + REPORT: " ⚠️ Files exist but validation failed - review agent output" + +REPORT: "✅ All {variants_count} design systems verified" ``` **Output Structure**: ``` {base_path}/style-consolidation/ -├── style-1/ -│ ├── design-tokens.json # Style 1 tokens -│ └── style-guide.md # Style 1 docs -├── style-2/ -│ └── ... (same structure) -├── style-N/ -│ └── ... (same structure) -└── layout-strategies.json # Layout variant definitions +├── style-1/ (design-tokens.json, style-guide.md) +├── style-2/ (same structure) +└── style-N/ (same structure) ``` ### Phase 6: Completion & Reporting ```javascript -TodoWrite({ - todos: [ - {content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"}, - {content: "Select variants for consolidation", status: "completed", activeForm: "Selecting variants"}, - {content: "Plan layout strategies", status: "completed", activeForm: "Planning layout strategies"}, - {content: "Load design context from brainstorming", status: "completed", activeForm: "Loading context"}, - {content: "Generate design systems via agent", status: "completed", activeForm: "Generating design systems"}, - {content: "Process agent results and write files", status: "completed", activeForm: "Writing output files"} - ] -}); +TodoWrite({todos: [ + {content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"}, + {content: "Select variants for consolidation", status: "completed", activeForm: "Selecting variants"}, + {content: "Load design context and space analysis", status: "completed", activeForm: "Loading context"}, + {content: "Perform variant-specific trend research", status: "completed", activeForm: "Researching design trends"}, + {content: "Generate design systems via agent", status: "completed", activeForm: "Generating design systems"}, + {content: "Process agent results and write files", status: "completed", activeForm: "Writing output files"} +]}); ``` **Completion Message**: ``` -✅ Design consolidation & layout planning complete for session: {session_id} +✅ Design system consolidation complete for session: {session_id} + +{IF design_space_analysis: +🔍 Trend Research Performed: +- {variants_count} × 4 variant-specific MCP queries ({variants_count * 4} total) +- 1 shared accessibility research query +- Each variant refined with independent trend guidance +} Generated {variants_count} independent design systems: {FOR each variant: - {variant.name} ({variant.id})} -Layout Strategies Planned: {layout_variants} -{FOR each strategy: - Layout {strategy.id}: {strategy.name}} - 📂 Output: {base_path}/style-consolidation/ ├── style-1/ (design-tokens.json, style-guide.md) ├── style-2/ (same structure) -├── style-{variants_count}/ (same structure) -└── layout-strategies.json +└── style-{variants_count}/ (same structure) -Next: /workflow:ui-design:generate --session {session_id} --style-variants {variants_count} --layout-variants {layout_variants} --pages "dashboard,auth" +Next: /workflow:ui-design:generate --session {session_id} --style-variants {variants_count} --targets "dashboard,auth" --layout-variants N -Note: When called from /workflow:ui-design:auto, UI generation is triggered automatically. -The generate command will read layout strategies from layout-strategies.json. +Note: When called from /workflow:ui-design:explore-auto, UI generation is triggered automatically. +Layout planning is now handled in the generate phase for each specific target. ``` ## design-tokens.json Format @@ -387,23 +366,23 @@ The generate command will read layout strategies from layout-strategies.json. ```json { "colors": { - "brand": { "primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)" }, - "surface": { "background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)" }, - "semantic": { "success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)" }, - "text": { "primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)" }, - "border": { "default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)" } + "brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"}, + "surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"}, + "semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"}, + "text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"}, + "border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"} }, "typography": { - "font_family": { "heading": "...", "body": "...", "mono": "..." }, - "font_size": { "xs": "...", "sm": "...", "base": "...", "lg": "...", "xl": "...", "2xl": "...", "3xl": "...", "4xl": "..." }, - "font_weight": { "normal": "400", "medium": "500", "semibold": "600", "bold": "700" }, - "line_height": { "tight": "1.25", "normal": "1.5", "relaxed": "1.75" }, - "letter_spacing": { "tight": "-0.025em", "normal": "0", "wide": "0.025em" } + "font_family": {"heading": "...", "body": "...", "mono": "..."}, + "font_size": {"xs": "...", "sm": "...", "base": "...", "lg": "...", "xl": "...", "2xl": "...", "3xl": "...", "4xl": "..."}, + "font_weight": {"normal": "400", "medium": "500", "semibold": "600", "bold": "700"}, + "line_height": {"tight": "1.25", "normal": "1.5", "relaxed": "1.75"}, + "letter_spacing": {"tight": "-0.025em", "normal": "0", "wide": "0.025em"} }, - "spacing": { "0": "0", "1": "0.25rem", ..., "24": "6rem" }, - "border_radius": { "none": "0", "sm": "0.25rem", ..., "full": "9999px" }, - "shadows": { "sm": "...", "md": "...", "lg": "...", "xl": "..." }, - "breakpoints": { "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" } + "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"}, + "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"}, + "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."}, + "breakpoints": {"sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px"} } ``` @@ -419,53 +398,22 @@ The generate command will read layout strategies from layout-strategies.json. ## Key Features -1. **Agent-Driven Architecture** - - Uses ui-design-agent for multi-file generation efficiency - - Parallel generation of N independent design systems - - Structured output parsing with labeled sections - -2. **Separate Design Systems (Matrix-Ready)** - - Generates N independent design systems (one per variant) - - Each variant maintains unique style identity - - Enables style × layout matrix exploration in generate phase - -3. **Dynamic Layout Strategy Generation** 🆕 - - Uses Exa MCP to research current UI/UX layout trends (2024-2025) - - Generates layout strategies based on project context and modern patterns - - Adapts to project type (dashboard, marketing, SaaS, etc.) - - Balances innovation with usability - -4. **Token Refinement** - - Reads `proposed_tokens` from style cards directly - - Agent refines each variant into complete design system - - Fills gaps while maintaining style identity - -5. **Complete Design System Output** - - design-tokens.json (CSS tokens per variant) - - style-guide.md (documentation per variant) - - layout-strategies.json (dynamic layout plans) - -6. **Production-Ready Quality** - - WCAG AA accessibility validation - - OKLCH color format for perceptual uniformity - - Semantic token naming - - Complete token coverage - -7. **Streamlined Workflow** - - Sequential phases with clear responsibilities - - Agent handles complex multi-file generation - - Reproducible with deterministic structure - - Context-aware (integrates brainstorming artifacts) +1. **Variant-Specific Trend Research** 🆕 - Agent performs independent MCP queries for each variant (4 queries per variant); Uses design space analysis keywords from extraction phase; Each variant researches its specific design philosophy; Shared accessibility research applied to all variants; Eliminates convergence by maintaining variant-specific research +2. **Agent-Driven Architecture** - Uses ui-design-agent for multi-file generation and MCP research; Parallel generation of N independent design systems with external trend integration; Structured output parsing with labeled sections; Agent handles both research and synthesis +3. **Separate Design Systems (Matrix-Ready)** - Generates N independent design systems (one per variant); Each variant maintains unique style identity enhanced by trend research; Provides style foundation for style × layout matrix exploration in generate phase +4. **Token Refinement with Trend Integration** 🆕 - Reads `proposed_tokens` from style cards; Loads design space analysis for research parameters; Agent performs MCP trend research per variant; Refines tokens using research insights while maintaining style identity +5. **Complete Design System Output** - design-tokens.json (CSS tokens per variant); style-guide.md (documentation per variant with trend insights) +6. **Production-Ready Quality** - WCAG AA accessibility validation with MCP research; OKLCH color format for perceptual uniformity; Semantic token naming; Complete token coverage; Modern trends integration +7. **Streamlined Workflow** - Sequential phases with clear responsibilities; Agent handles MCP research, token refinement, and file generation; Reproducible with deterministic structure; Context-aware (integrates brainstorming and design space analysis) +8. **Clear Separation of Concerns** - Consolidation focuses on style systems with trend research; Extraction focuses on Claude-native analysis; Layout planning delegated to generate phase for target-specific optimization ## Integration Points - **Input**: - `style-cards.json` from `/workflow:ui-design:extract` (with `proposed_tokens`) + - `design-space-analysis.json` from extraction phase (with search keywords for MCP research) - `--variants` parameter (default: all variants) - - `--layout-variants` parameter (default: 3) -- **Output**: - - Style Systems: `style-consolidation/style-{n}/design-tokens.json` for matrix mode generation - - Layout Planning: `layout-strategies.json` consumed by `/workflow:ui-design:generate` +- **Output**: Style Systems: `style-consolidation/style-{n}/design-tokens.json` and `style-guide.md` for each variant (enhanced with trend research) - **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md` -- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow -- **Next Command**: `/workflow:ui-design:generate --style-variants N --layout-variants M` reads design tokens and layout strategies +- **Auto Integration**: Automatically triggered by `/workflow:ui-design:explore-auto` workflow +- **Next Command**: `/workflow:ui-design:generate --style-variants N --targets "..." --layout-variants M` performs target-specific layout planning diff --git a/.claude/commands/workflow/ui-design/extract.md b/.claude/commands/workflow/ui-design/extract.md index 02dd57b7..ee2bd4a0 100644 --- a/.claude/commands/workflow/ui-design/extract.md +++ b/.claude/commands/workflow/ui-design/extract.md @@ -47,39 +47,25 @@ Extract design style elements from reference images or text prompts using Claude ```bash # Detect input source -IF --images AND --prompt: - input_mode = "hybrid" # Text guides image analysis -ELSE IF --images: - input_mode = "image" -ELSE IF --prompt: - input_mode = "text" -ELSE: - ERROR: "Must provide --images or --prompt" +IF --images AND --prompt: input_mode = "hybrid" # Text guides image analysis +ELSE IF --images: input_mode = "image" +ELSE IF --prompt: input_mode = "text" +ELSE: ERROR: "Must provide --images or --prompt" # Determine base path (PRIORITY: --base-path > --session > standalone) -IF --base-path provided: - base_path = {provided_base_path} - session_mode = "integrated" # Assume integrated if path is passed - # Extract session_id if possible from path pattern - IF base_path matches ".workflow/WFS-*/design-*": - session_id = extract_from_path(base_path, pattern="WFS-([^/]+)") - ELSE: - session_id = "standalone" +IF --base-path: + base_path = {provided_base_path}; session_mode = "integrated" + session_id = base_path matches ".workflow/WFS-*/design-*" ? extract_session_id(base_path) : "standalone" ELSE: - # Generate a new run_id and base_path only if not provided run_id = "run-" + timestamp() - IF --session: - session_mode = "integrated" - session_id = {provided_session} + session_mode = "integrated"; session_id = {provided_session} base_path = ".workflow/WFS-{session_id}/design-{run_id}/" ELSE: - session_mode = "standalone" - base_path = ".workflow/.design/{run_id}/" + session_mode = "standalone"; base_path = ".workflow/.design/{run_id}/" # Set variant count -variants_count = --variants provided ? {count} : 1 -VALIDATE: 1 <= variants_count <= 5 +variants_count = --variants OR 1; VALIDATE: 1 <= variants_count <= 5 ``` ### Phase 1: Input Loading & Validation @@ -87,50 +73,37 @@ VALIDATE: 1 <= variants_count <= 5 ```bash # Expand and validate inputs IF input_mode IN ["image", "hybrid"]: - expanded_images = Glob({--images pattern}) - VERIFY: expanded_images.length > 0 - FOR each image IN expanded_images: - image_data[i] = Read({image_path}) # Load for analysis + expanded_images = Glob({--images pattern}); VERIFY: expanded_images.length > 0 + FOR each image: image_data[i] = Read({image_path}) IF input_mode IN ["text", "hybrid"]: - VALIDATE: --prompt is non-empty string - prompt_guidance = {--prompt value} + VALIDATE: --prompt is non-empty; prompt_guidance = {--prompt value} -# Create output directory CREATE: {base_path}/style-extraction/ ``` ### Phase 0.5: AI-Driven Design Space Divergence ```bash -# Step 1: Load project context to inform design space analysis +# Step 1: Load project context project_context = "" IF exists({base_path}/.brainstorming/synthesis-specification.md): - project_context = Read({base_path}/.brainstorming/synthesis-specification.md) + project_context = Read(synthesis-specification.md) ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md): - project_context = Read({base_path}/.brainstorming/ui-designer/analysis.md) + project_context = Read(ui-designer/analysis.md) REPORT: "🎨 Analyzing design space to generate maximally contrasting directions..." # Step 2: AI-driven divergent direction generation divergence_prompt = """ -Analyze the user's design requirements and generate {variants_count} MAXIMALLY CONTRASTING design directions. +Analyze user requirements and generate {variants_count} MAXIMALLY CONTRASTING design directions. USER INPUT: -{IF prompt_guidance} -Prompt: "{prompt_guidance}" -{ENDIF} +{IF prompt_guidance: Prompt: "{prompt_guidance}"} +{IF project_context: Project Context Summary: {extract_key_points(project_context, max_lines=10)}} +{IF images: Reference Images: {image_count} images will be analyzed in next phase} -{IF project_context} -Project Context Summary: -{extract_key_points(project_context, max_lines=10)} -{ENDIF} - -{IF images} -Reference Images: {image_count} images will be analyzed in next phase -{ENDIF} - -DESIGN ATTRIBUTE SPACE (use to maximize contrast): +DESIGN ATTRIBUTE SPACE (maximize contrast): - Color Saturation: [monochrome, muted, moderate, vibrant, hypersaturated] - Visual Weight: [minimal, light, balanced, bold, heavy] - Formality: [playful, casual, professional, formal, luxury] @@ -139,279 +112,119 @@ DESIGN ATTRIBUTE SPACE (use to maximize contrast): - Density: [spacious, airy, balanced, compact, dense] TASK: -1. Identify the design space center point from user requirements -2. Generate {variants_count} design directions that: +1. Identify design space center point from user requirements +2. Generate {variants_count} directions that: - Are MAXIMALLY DISTANT from each other in attribute space - Each occupies a distinct region/quadrant of the design spectrum - - Together provide diverse aesthetic options for the user - - Are contextually appropriate for the project type + - Together provide diverse aesthetic options + - Are contextually appropriate for project type - Have clear, memorable philosophical differences - 3. For each direction, generate: - Specific search keywords for MCP research (3-5 keywords) - - Anti-keywords to avoid (2-3 keywords that would reduce contrast) - - Clear rationale explaining why this contrasts with other variants + - Anti-keywords to avoid (2-3 keywords) + - Clear rationale explaining contrast with other variants OUTPUT FORMAT: Valid JSON only, no markdown: -{ - "design_space_center": { - "color_saturation": "moderate", - "visual_weight": "balanced", - "formality": "professional", - "organic_geometric": "balanced", - "innovation": "contemporary", - "density": "balanced" - }, - "divergent_directions": [ - { - "id": "variant-1", - "philosophy_name": "Brief name 2-3 words (e.g., 'Minimal Brutalist')", - "design_attributes": { - "color_saturation": "monochrome", - "visual_weight": "minimal", - "formality": "professional", - "organic_geometric": "brutalist", - "innovation": "timeless", - "density": "spacious" - }, - "search_keywords": ["minimal", "brutalist", "monochrome", "geometric", "Swiss design"], - "anti_keywords": ["decorative", "colorful", "organic"], - "rationale": "Extreme minimalism with geometric rigor, contrasts with any ornamental or colorful approaches" - } - // ... {variants_count} total directions - ], - "contrast_verification": { - "min_pairwise_distance": "0.75", - "strategy": "Brief explanation of how maximum contrast was achieved" - } -} +{"design_space_center": {attributes}, "divergent_directions": [ + {"id": "variant-1", "philosophy_name": "Brief name 2-3 words", + "design_attributes": {attribute_scores}, "search_keywords": [...], + "anti_keywords": [...], "rationale": "..."} +], "contrast_verification": {"min_pairwise_distance": "0.75", "strategy": "..."}} -RULES: -- Output ONLY valid JSON, no markdown code blocks or explanations -- Maximize inter-variant distance in attribute space -- Ensure each variant occupies a distinct aesthetic region -- Avoid overlapping attribute combinations -- All directions must be contextually appropriate for: {project_context or "general web UI"} -- Philosophy names should be memorable and evocative -- Search keywords should be specific and actionable for web research +RULES: Output ONLY valid JSON, maximize inter-variant distance, ensure each variant +occupies distinct aesthetic region, avoid overlapping attributes """ # Execute AI analysis -divergence_response = Claude_Native_Analysis(divergence_prompt) -divergent_directions = parse_json(divergence_response) +divergent_directions = parse_json(Claude_Native_Analysis(divergence_prompt)) REPORT: "✅ Generated {variants_count} contrasting design directions:" FOR direction IN divergent_directions.divergent_directions: REPORT: " - {direction.philosophy_name}: {direction.rationale}" -# Store divergent directions for next phase design_space_analysis = divergent_directions + +# Step 3: Save design space analysis for consolidation phase +Write({file_path: "{base_path}/style-extraction/design-space-analysis.json", + content: JSON.stringify(design_space_analysis, null, 2)}) +REPORT: "💾 Saved design space analysis to design-space-analysis.json" ``` -### Phase 1.5: Variant-Specific Design Trend Research (Exa MCP) - -```bash -# Step 1: Execute independent MCP research for each variant -REPORT: "🔍 Researching design trends for each variant independently..." - -design_trends = {} - -FOR direction IN design_space_analysis.divergent_directions: - variant_id = direction.id - philosophy = direction.philosophy_name - keywords = direction.search_keywords - anti_keywords = direction.anti_keywords - - REPORT: " → Researching {philosophy} ({variant_id})..." - - # Build variant-specific search queries - variant_queries = [ - # Colors: philosophy-specific palette trends - f"{philosophy} UI design color palettes {' '.join(keywords[:3])} 2024 2025", - - # Typography: philosophy-specific font trends - f"{philosophy} typography trends {' '.join(keywords[:3])} web design 2024", - - # Layout: philosophy-specific patterns - f"{philosophy} layout patterns {' '.join(keywords[:3])} design systems 2024", - - # Contrast query: emphasize differentiation - f"design systems {philosophy} NOT {' NOT '.join(anti_keywords[:2])}" - ] - - # Execute MCP searches for this variant - design_trends[variant_id] = { - "philosophy": philosophy, - "attributes": direction.design_attributes, - "keywords": keywords, - "anti_keywords": anti_keywords, - "research": {} - } - - FOR query IN variant_queries: - category = identify_category(query) # "colors", "typography", "layout", "contrast" - design_trends[variant_id].research[category] = mcp__exa__get_code_context_exa( - query=query, - tokensNum=2000 # Increased for more detailed guidance - ) - - REPORT: " ✅ {philosophy} research complete" - -# Step 2: Gather shared accessibility guidelines (all variants) -REPORT: " → Researching universal accessibility guidelines..." -shared_accessibility = mcp__exa__get_code_context_exa( - query="WCAG 2.2 accessibility color contrast ARIA best practices 2024", - tokensNum=1500 -) - -REPORT: "✅ All variant-specific design research complete" -``` - -### Phase 2: Variant-Specific Style Synthesis (Claude with Divergent Research) - -This is a single-pass analysis that generates each variant based on its specific design direction and research. +### Phase 2: Variant-Specific Style Synthesis (Claude Native Analysis) **Analysis Prompt Template**: ``` -Generate {variants_count} design style proposals, each guided by its pre-analyzed design direction and independent trend research. +Generate {variants_count} design style proposals, each guided by its pre-analyzed design direction. INPUT MODE: {input_mode} +{IF input_mode IN ["image", "hybrid"]: VISUAL REFERENCES: {list of loaded images}} +{IF input_mode IN ["text", "hybrid"]: TEXT GUIDANCE: "{prompt_guidance}"} -{IF input_mode IN ["image", "hybrid"]} -VISUAL REFERENCES: {list of loaded images} -Analyze these images through the lens of each variant's design philosophy -{ENDIF} +DESIGN SPACE ANALYSIS: {design_space_analysis summary} -{IF input_mode IN ["text", "hybrid"]} -TEXT GUIDANCE: "{prompt_guidance}" -Apply this guidance while maintaining each variant's distinct aesthetic direction -{ENDIF} - -DESIGN SPACE ANALYSIS: -{design_space_analysis summary} - -VARIANT-SPECIFIC DESIGN DIRECTIONS AND RESEARCH: - -{FOR each variant_id IN design_trends.keys()} +VARIANT-SPECIFIC DESIGN DIRECTIONS: +{FOR each direction IN design_space_analysis.divergent_directions: --- -VARIANT: {variant_id} -PHILOSOPHY: {design_trends[variant_id].philosophy} -DESIGN ATTRIBUTES: - - Color Saturation: {design_trends[variant_id].attributes.color_saturation} - - Visual Weight: {design_trends[variant_id].attributes.visual_weight} - - Formality: {design_trends[variant_id].attributes.formality} - - Organic/Geometric: {design_trends[variant_id].attributes.organic_geometric} - - Innovation: {design_trends[variant_id].attributes.innovation} - - Density: {design_trends[variant_id].attributes.density} - -SEARCH KEYWORDS: {', '.join(design_trends[variant_id].keywords)} -ANTI-PATTERNS (avoid): {', '.join(design_trends[variant_id].anti_keywords)} - -TREND RESEARCH FOR THIS VARIANT: - -Color Trends ({variant_id}): -{design_trends[variant_id].research.colors} - -Typography Trends ({variant_id}): -{design_trends[variant_id].research.typography} - -Layout Patterns ({variant_id}): -{design_trends[variant_id].research.layout} - -Contrast Emphasis ({variant_id}): -{design_trends[variant_id].research.contrast} - ---- -{ENDFOR} - -SHARED ACCESSIBILITY GUIDELINES (apply to all variants): -{shared_accessibility} +VARIANT: {direction.id} | PHILOSOPHY: {direction.philosophy_name} +DESIGN ATTRIBUTES: {direction.design_attributes} +SEARCH KEYWORDS: {direction.search_keywords} +ANTI-PATTERNS (avoid): {direction.anti_keywords} +RATIONALE: {direction.rationale} +---} TASK: Generate {variants_count} design style variants where EACH variant: 1. Strictly follows its pre-defined design philosophy and attributes -2. Uses ONLY its variant-specific trend research for aesthetic decisions -3. Maintains maximum contrast with other variants' attributes -4. Incorporates its search keywords and avoids its anti-patterns -5. Uses OKLCH color space for all color values -6. Includes complete, production-ready design token proposals -7. Applies WCAG accessibility guidelines from shared research +2. Maintains maximum contrast with other variants' attributes +3. Incorporates its design direction and avoids its anti-patterns +4. Uses OKLCH color space for all color values +5. Includes complete, production-ready design token proposals +6. Applies WCAG AA accessibility guidelines (4.5:1 text, 3:1 UI) CRITICAL RULES FOR CONTRAST: -- Variant-1 should feel completely different from Variant-2 and Variant-3 +- Variant-1 should feel completely different from Variant-2/3 - Use each variant's specific attribute scores (e.g., "monochrome" vs "vibrant") -- Reference variant-specific research, NOT shared trends +- Each variant should embody its unique design direction - If Variant-1 is "minimal/geometric", Variant-2 must be "bold/organic" or similar contrast -- Each variant should be immediately distinguishable by visual inspection -OUTPUT FORMAT: JSON matching this structure (see full schema at end of prompt): -{ - "extraction_metadata": { "session_id": "...", "input_mode": "...", "timestamp": "...", "variants_count": N }, - "style_cards": [ - { - "id": "variant-1", - "name": "Concise Style Name (2-3 words)", - "description": "2-3 sentence description", - "design_philosophy": "Core design principles", - "preview": { "primary": "oklch(...)", "background": "oklch(...)", "font_heading": "...", "border_radius": "..." }, - "proposed_tokens": { - "colors": { - "brand": { "primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)" }, - "surface": { "background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)" }, - "semantic": { "success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)" }, - "text": { "primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)" }, - "border": { "default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)" } - }, - "typography": { "font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...} }, - "spacing": { "0": "0", ..., "24": "6rem" }, - "border_radius": { "none": "0", ..., "full": "9999px" }, - "shadows": { "sm": "...", ..., "xl": "..." }, - "breakpoints": { "sm": "640px", ..., "2xl": "1536px" } - } - } - // Repeat structure for ALL {variants_count} variants - ] -} +OUTPUT FORMAT: JSON matching this structure: +{"extraction_metadata": {"session_id": "...", "input_mode": "...", "timestamp": "...", "variants_count": N}, + "style_cards": [ + {"id": "variant-1", "name": "Concise Style Name (2-3 words)", "description": "2-3 sentences", + "design_philosophy": "Core design principles", + "preview": {"primary": "oklch(...)", "background": "oklch(...)", "font_heading": "...", "border_radius": "..."}, + "proposed_tokens": { + "colors": {"brand": {...}, "surface": {...}, "semantic": {...}, "text": {...}, "border": {...}}, + "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}}, + "spacing": {"0": "0", ..., "24": "6rem"}, + "border_radius": {"none": "0", ..., "full": "9999px"}, + "shadows": {"sm": "...", ..., "xl": "..."}, + "breakpoints": {"sm": "640px", ..., "2xl": "1536px"} + }} + // Repeat for ALL {variants_count} variants + ]} -RULES: -- Each variant must strictly adhere to its pre-defined design attributes -- Use ONLY variant-specific trend research (do NOT cross-pollinate research between variants) -- Maximize visual contrast between variants using their attribute differences -- All colors MUST use OKLCH format: oklch(L C H / A) -- Token structures must be complete and production-ready -- Use semantic naming throughout (e.g., "brand-primary" not "color-1") -- Ensure accessibility (WCAG AA contrast ratios: 4.5:1 text, 3:1 UI) using shared guidelines -- Apply typography trends from each variant's specific research -- Incorporate search keywords and actively avoid anti-patterns for each variant -- Each variant's philosophy_name should match the pre-analyzed name from design space analysis -- Reference specific trends from variant-specific research, not from other variants +RULES: Each variant must strictly adhere to pre-defined attributes; maximize visual contrast; +all colors in OKLCH format; complete token structures; semantic naming; +WCAG AA accessibility (4.5:1 text, 3:1 UI) ``` ### Phase 3: Parse & Write Output ```bash -# Parse Claude's JSON response style_cards_data = parse_json(claude_response) - -# Write single output file -Write({ - file_path: "{base_path}/style-extraction/style-cards.json", - content: style_cards_data -}) +Write({file_path: "{base_path}/style-extraction/style-cards.json", content: style_cards_data}) ``` ### Phase 4: Completion ```javascript -TodoWrite({ - todos: [ - {content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"}, - {content: "Analyze design space for maximum contrast", status: "completed", activeForm: "Analyzing design space"}, - {content: `Generate ${variants_count} divergent design directions`, status: "completed", activeForm: "Generating design directions"}, - {content: "Research variant-specific design trends with Exa MCP", status: "completed", activeForm: "Researching variant trends"}, - {content: "Synthesize style cards with independent research", status: "completed", activeForm: "Synthesizing style cards"}, - {content: `Generate ${variants_count} contrasting style variants`, status: "completed", activeForm: "Generating style variants"} - ] -}); +TodoWrite({todos: [ + {content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"}, + {content: "Analyze design space for maximum contrast", status: "completed", activeForm: "Analyzing design space"}, + {content: `Generate ${variants_count} divergent design directions`, status: "completed", activeForm: "Generating directions"}, + {content: "Save design space analysis for consolidation", status: "completed", activeForm: "Saving design space analysis"}, + {content: `Generate ${variants_count} contrasting style variants`, status: "completed", activeForm: "Generating variants"} +]}); ``` **Completion Message**: @@ -430,12 +243,9 @@ Input mode: {input_mode} Generated {variants_count} style variant(s): {FOR each card: - {card.name} ({card.id}) - {card.design_philosophy}} -🔍 Research performed: -- {variants_count} × 4 variant-specific MCP queries ({variants_count * 4} total) -- 1 shared accessibility research query -- Each variant has independent trend guidance - -📂 Output: {base_path}/style-extraction/style-cards.json +📂 Outputs: +- {base_path}/style-extraction/style-cards.json +- {base_path}/style-extraction/design-space-analysis.json Next: /workflow:ui-design:consolidate --session {session_id} --variants {variants_count} [--layout-variants ] @@ -446,12 +256,14 @@ Note: When called from /workflow:ui-design:auto, consolidation is triggered auto ``` .workflow/WFS-{session}/design-{run_id}/style-extraction/ -└── style-cards.json # Single comprehensive output +├── style-cards.json # Complete style variants with token proposals +└── design-space-analysis.json # Design directions for consolidation phase OR (standalone mode): .workflow/.design/{run_id}/style-extraction/ -└── style-cards.json # Single comprehensive output +├── style-cards.json +└── design-space-analysis.json ``` ### style-cards.json Format @@ -460,43 +272,40 @@ OR (standalone mode): ```json { - "extraction_metadata": { - "session_id": "string", - "input_mode": "image|text|hybrid", - "timestamp": "ISO 8601 string", - "variants_count": "number" - }, + "extraction_metadata": {"session_id": "string", "input_mode": "image|text|hybrid", + "timestamp": "ISO 8601", "variants_count": "number"}, "style_cards": [ { - "id": "variant-{n}", - "name": "Concise Style Name (2-3 words)", + "id": "variant-{n}", "name": "Concise Style Name (2-3 words)", "description": "2-3 sentence description of visual language and UX", "design_philosophy": "Core design principles for this variant", - "preview": { - "primary": "oklch(...)", - "background": "oklch(...)", - "font_heading": "Font family, fallbacks", - "border_radius": "value" - }, + "preview": {"primary": "oklch(...)", "background": "oklch(...)", + "font_heading": "Font family, fallbacks", "border_radius": "value"}, "proposed_tokens": { "colors": { - "brand": { "primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)" }, - "surface": { "background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)" }, - "semantic": { "success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)" }, - "text": { "primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)" }, - "border": { "default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)" } + "brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"}, + "surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"}, + "semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"}, + "text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"}, + "border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"} }, "typography": { - "font_family": { "heading": "...", "body": "...", "mono": "..." }, - "font_size": { "xs": "...", "sm": "...", "base": "...", "lg": "...", "xl": "...", "2xl": "...", "3xl": "...", "4xl": "..." }, - "font_weight": { "normal": "400", "medium": "500", "semibold": "600", "bold": "700" }, - "line_height": { "tight": "1.25", "normal": "1.5", "relaxed": "1.75" }, - "letter_spacing": { "tight": "-0.025em", "normal": "0", "wide": "0.025em" } + "font_family": {"heading": "...", "body": "...", "mono": "..."}, + "font_size": {"xs": "...", "sm": "...", "base": "...", "lg": "...", "xl": "...", "2xl": "...", "3xl": "...", "4xl": "..."}, + "font_weight": {"normal": "400", "medium": "500", "semibold": "600", "bold": "700"}, + "line_height": {"tight": "1.25", "normal": "1.5", "relaxed": "1.75"}, + "letter_spacing": {"tight": "-0.025em", "normal": "0", "wide": "0.025em"} }, - "spacing": { "0": "0", "1": "0.25rem", "2": "0.5rem", ..., "24": "6rem" }, - "border_radius": { "none": "0", "sm": "0.25rem", "md": "0.5rem", "lg": "0.75rem", "xl": "1rem", "full": "9999px" }, - "shadows": { "sm": "...", "md": "...", "lg": "...", "xl": "..." }, - "breakpoints": { "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" } + "spacing": {"0": "0", "1": "0.25rem", "2": "0.5rem", "3": "0.75rem", "4": "1rem", + "5": "1.25rem", "6": "1.5rem", "8": "2rem", "10": "2.5rem", "12": "3rem", + "16": "4rem", "20": "5rem", "24": "6rem"}, + "border_radius": {"none": "0", "sm": "0.25rem", "md": "0.5rem", "lg": "0.75rem", + "xl": "1rem", "full": "9999px"}, + "shadows": {"sm": "0 1px 2px oklch(0.00 0.00 0 / 0.05)", + "md": "0 4px 6px oklch(0.00 0.00 0 / 0.07)", + "lg": "0 10px 15px oklch(0.00 0.00 0 / 0.10)", + "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.15)"}, + "breakpoints": {"sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px"} } } // Repeat structure for variants_count total (variant-1, variant-2, ..., variant-n) @@ -504,111 +313,6 @@ OR (standalone mode): } ``` -**Concrete Example (variant-1 only, others follow same structure)**: - -```json -{ - "extraction_metadata": { - "session_id": "WFS-auth", - "input_mode": "hybrid", - "timestamp": "2025-01-15T10:30:00Z", - "variants_count": 3 - }, - "style_cards": [ - { - "id": "variant-1", - "name": "Minimal Brutalist", - "description": "Stark geometric design with monochrome palette and sharp edges. Prioritizes function over decoration with extreme clarity.", - "design_philosophy": "Form follows function - eliminate all non-essential visual elements", - "preview": { - "primary": "oklch(0.20 0.01 270 / 1)", - "background": "oklch(0.98 0.00 0 / 1)", - "font_heading": "Inter, system-ui, sans-serif", - "border_radius": "0" - }, - "proposed_tokens": { - "colors": { - "brand": { - "primary": "oklch(0.20 0.01 270 / 1)", - "secondary": "oklch(0.40 0.01 270 / 1)", - "accent": "oklch(0.60 0.01 270 / 1)" - }, - "surface": { - "background": "oklch(0.98 0.00 0 / 1)", - "elevated": "oklch(0.95 0.00 0 / 1)", - "overlay": "oklch(0.90 0.00 0 / 1)" - }, - "semantic": { - "success": "oklch(0.30 0.01 270 / 1)", - "warning": "oklch(0.30 0.01 270 / 1)", - "error": "oklch(0.30 0.01 270 / 1)", - "info": "oklch(0.30 0.01 270 / 1)" - }, - "text": { - "primary": "oklch(0.10 0.00 0 / 1)", - "secondary": "oklch(0.40 0.00 0 / 1)", - "tertiary": "oklch(0.60 0.00 0 / 1)", - "inverse": "oklch(0.98 0.00 0 / 1)" - }, - "border": { - "default": "oklch(0.20 0.00 0 / 1)", - "strong": "oklch(0.10 0.00 0 / 1)", - "subtle": "oklch(0.85 0.00 0 / 1)" - } - }, - "typography": { - "font_family": { - "heading": "Inter, system-ui, sans-serif", - "body": "Inter, system-ui, sans-serif", - "mono": "JetBrains Mono, monospace" - }, - "font_size": { - "xs": "0.75rem", "sm": "0.875rem", "base": "1rem", "lg": "1.125rem", - "xl": "1.25rem", "2xl": "1.5rem", "3xl": "1.875rem", "4xl": "2.25rem" - }, - "font_weight": { "normal": "400", "medium": "500", "semibold": "600", "bold": "700" }, - "line_height": { "tight": "1.25", "normal": "1.5", "relaxed": "1.75" }, - "letter_spacing": { "tight": "-0.025em", "normal": "0", "wide": "0.025em" } - }, - "spacing": { - "0": "0", "1": "0.25rem", "2": "0.5rem", "3": "0.75rem", "4": "1rem", - "5": "1.25rem", "6": "1.5rem", "8": "2rem", "10": "2.5rem", "12": "3rem", - "16": "4rem", "20": "5rem", "24": "6rem" - }, - "border_radius": { - "none": "0", "sm": "0.25rem", "md": "0.5rem", "lg": "0.75rem", "xl": "1rem", "full": "9999px" - }, - "shadows": { - "sm": "0 1px 2px oklch(0.00 0.00 0 / 0.05)", - "md": "0 4px 6px oklch(0.00 0.00 0 / 0.07)", - "lg": "0 10px 15px oklch(0.00 0.00 0 / 0.10)", - "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.15)" - }, - "breakpoints": { - "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" - } - } - }, - { - "id": "variant-2", - "name": "Bold Vibrant", - "description": "High-energy design with saturated colors, dynamic typography, and strong contrast. (Full token structure same as variant-1)", - "design_philosophy": "Make a statement - use color and energy to create memorable experiences", - "preview": { "primary": "oklch(0.50 0.25 330 / 1)", "background": "oklch(0.15 0.02 270 / 1)", "..." }, - "proposed_tokens": { "...same structure as variant-1 with different values..." } - }, - { - "id": "variant-3", - "name": "Organic Natural", - "description": "Soft, rounded design with warm earth tones and fluid layouts. (Full token structure same as variant-1)", - "design_philosophy": "Nature-inspired - embrace curves, warmth, and organic flow", - "preview": { "primary": "oklch(0.55 0.15 60 / 1)", "background": "oklch(0.96 0.03 80 / 1)", "..." }, - "proposed_tokens": { "...same structure as variant-1 with different values..." } - } - ] -} -``` - **Key Structural Requirements**: - Each variant MUST have complete, independent token proposals (all categories present) - All colors MUST use OKLCH format: `oklch(L C H / A)` @@ -618,27 +322,27 @@ OR (standalone mode): ## Error Handling -- **No images found**: Report glob pattern and suggest corrections (e.g., "Pattern '*.png' matched 0 files in current directory") +- **No images found**: Report glob pattern and suggest corrections - **Invalid prompt**: Require non-empty string for text mode -- **Claude JSON parsing error**: Retry with stricter format instructions and explicit structure requirements +- **Claude JSON parsing error**: Retry with stricter format instructions - **Invalid session**: Create standalone session automatically in `.workflow/.scratchpad/` - **Invalid variant count**: Clamp to 1-5 range and warn user ## Key Features -1. **🚀 AI-Driven Design Space Exploration (Strategy A)** 🆕 - - **Phase 0.5**: AI analyzes requirements and generates MAXIMALLY CONTRASTING design directions +1. **🚀 AI-Driven Design Space Exploration** 🆕 + - Phase 0.5: AI analyzes requirements and generates MAXIMALLY CONTRASTING design directions - Uses 6-dimensional design attribute space (color saturation, visual weight, formality, organic/geometric, innovation, density) - Ensures each variant occupies a distinct region of the design spectrum - Generates search keywords and anti-patterns for each variant - Provides contrast verification with minimum pairwise distance metrics -2. **🎯 Variant-Specific Trend Research** 🆕 - - **Independent MCP queries** for each variant (4 queries per variant) - - Each variant researches its specific design philosophy (e.g., "minimal brutalist" vs "bold vibrant") - - Uses philosophy-specific keywords and avoids cross-contamination - - Eliminates趋同性 (convergence) by preventing shared trend influence - - Shared accessibility research applied to all variants +2. **🎯 Variant-Specific Design Directions** 🆕 + - AI generates search keywords and anti-patterns for each variant + - Each variant has distinct design philosophy (e.g., "minimal brutalist" vs "bold vibrant") + - Philosophy-specific keywords guide synthesis + - Design space analysis saved for consolidation phase + - Trend research deferred to consolidation for better integration 3. **🔒 Maximum Contrast Guarantee** - AI-driven divergence ensures variants are maximally distant in attribute space @@ -646,10 +350,10 @@ OR (standalone mode): - Explicit anti-patterns prevent variants from borrowing each other's characteristics - Contrast verification built into design space analysis -4. **Zero External Dependencies for Core Analysis** - - No `gemini-wrapper`, no `codex` for style synthesis - pure Claude - - Single-pass comprehensive analysis with variant-specific trend integration - - Only uses Exa MCP for external trend research (not for synthesis) +4. **100% Claude-Native Analysis** + - No external tools (gemini-wrapper, codex, or MCP) - pure Claude + - Single-pass comprehensive analysis guided by design space analysis + - Fast, deterministic style synthesis without external dependencies 5. **Streamlined Output** - Single file (`style-cards.json`) vs. multiple scattered files @@ -660,7 +364,7 @@ OR (standalone mode): - Image-only: Analyze visual references through each variant's philosophical lens - Text-only: Generate from descriptions with maximum divergence - Hybrid: Text guides image analysis while maintaining variant independence - - All modes enhanced with variant-specific web research + - All modes enhanced with AI-driven design space analysis 7. **Context-Aware & Dynamic** - Extracts design keywords from user prompts (e.g., "minimalist", "Linear.app") @@ -668,12 +372,12 @@ OR (standalone mode): - Dynamically generates design directions based on project context - No hardcoded design philosophies - fully adaptive -8. **Production-Ready Tokens** +8. **Production-Ready Token Proposals** - Complete design system proposals per variant - OKLCH color format for perceptual uniformity and accessibility - Semantic naming conventions - - WCAG AA accessibility considerations from shared research - - Variant-specific typography trends (not generic) + - WCAG AA accessibility considerations built-in + - Variant-specific token sets (not generic) 9. **Workflow Integration** - Integrated mode: Works within existing workflow sessions diff --git a/.claude/commands/workflow/ui-design/generate.md b/.claude/commands/workflow/ui-design/generate.md index 41a9892b..01df46fe 100644 --- a/.claude/commands/workflow/ui-design/generate.md +++ b/.claude/commands/workflow/ui-design/generate.md @@ -48,97 +48,44 @@ Generate production-ready UI prototypes (HTML/CSS) in `style × layout` matrix m ## Execution Protocol -### Phase 0: Load Layout Strategies - -```bash -# Determine base path first (using same logic as Phase 1) -IF --base-path provided: - base_path = {provided_base_path} -ELSE IF --session provided: - # Find latest design run in session - base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*") -ELSE: - base_path = find_latest_path_matching(".workflow/.design/*") - -# Load layout strategies from consolidation output -layout_strategies_path = "{base_path}/style-consolidation/layout-strategies.json" -VERIFY: exists(layout_strategies_path), "Layout strategies not found. Run /workflow:ui-design:consolidate first." - -layout_strategies = Read(layout_strategies_path) -layout_variants = layout_strategies.layout_variants_count - -REPORT: "📐 Loaded {layout_variants} layout strategies:" -FOR strategy IN layout_strategies.strategies: - REPORT: " - {strategy.name}: {strategy.description}" - -# Override layout_variants if --layout-variants is provided (for manual runs) -IF --layout-variants provided: - WARN: "Overriding layout strategies count from {layout_variants} to {provided_count}" - layout_variants = {provided_count} - VALIDATE: 1 <= layout_variants <= len(layout_strategies.strategies) - # Trim strategies to match count - layout_strategies.strategies = layout_strategies.strategies[0:layout_variants] -``` - ### Phase 1: Path Resolution & Context Loading ```bash # 1. Determine base path -IF --base-path provided: - base_path = {provided_base_path} -ELSE IF --session provided: - # Find latest design run in session - base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*") -ELSE: - base_path = find_latest_design_session(".workflow/.scratchpad/") +IF --base-path: base_path = {provided_base_path} +ELSE IF --session: base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*") +ELSE: base_path = find_latest_path_matching(".workflow/.design/*") -# 2. Determine style variant count (layout_variants already loaded in Phase 0) -style_variants = --style-variants OR 3 # Default to 3 +# 2. Determine style variant count and layout variant count +style_variants = --style-variants OR 3; VALIDATE: 1 <= style_variants <= 5 +layout_variants = --layout-variants OR 3; VALIDATE: 1 <= layout_variants <= 5 -# Validate range -VALIDATE: 1 <= style_variants <= 5 - -# Validate against actual style directories (prevent style-N file generation for non-existent directories) +# Validate against actual style directories actual_style_count = count_directories({base_path}/style-consolidation/style-*) IF actual_style_count == 0: - ERROR: "No style directories found in {base_path}/style-consolidation/" - SUGGEST: "Run /workflow:ui-design:consolidate first to generate style design systems" - EXIT 1 + ERROR: "No style directories found"; SUGGEST: "Run /workflow:ui-design:consolidate first"; EXIT 1 IF style_variants > actual_style_count: - WARN: "⚠️ Requested {style_variants} style variants, but only {actual_style_count} directories exist" - REPORT: " Available styles: {list_directories({base_path}/style-consolidation/style-*)}" - REPORT: " Auto-correcting to {actual_style_count} style variants" - style_variants = actual_style_count + WARN: "⚠️ Requested {style_variants}, but only {actual_style_count} exist" + REPORT: " Available styles: {list_directories}"; style_variants = actual_style_count -REPORT: "✅ Validated style variants: {style_variants} (matching actual directory count)" - -# Note: layout_variants is loaded from layout-strategies.json in Phase 0 +REPORT: "✅ Validated style variants: {style_variants}" # 3. Enhanced target list parsing with type detection -target_list = [] -target_type = "page" # Default to page for backward compatibility +target_list = []; target_type = "page" # Default # Priority 1: Unified --targets parameter -IF --targets provided: +IF --targets: raw_targets = {--targets value} - # Split by comma, semicolon, or Chinese comma target_list = split_and_clean(raw_targets, delimiters=[",", ";", "、"]) - # Clean: strip whitespace, lowercase, replace spaces with hyphens target_list = [t.strip().lower().replace(" ", "-") for t in target_list if t.strip()] - # Get target type - IF --target-type provided: - target_type = {--target-type value} - ELSE: - # Auto-detect from target names (use same logic as explore-auto) - target_type = detect_target_type(target_list) - + target_type = --target-type provided ? {--target-type} : detect_target_type(target_list) REPORT: "🎯 Using provided targets ({target_type}): {', '.join(target_list)}" -# Priority 2: Legacy --pages parameter (backward compatibility) -ELSE IF --pages provided: +# Priority 2: Legacy --pages parameter +ELSE IF --pages: raw_targets = {--pages value} target_list = split_and_clean(raw_targets, delimiters=[",", ";", "、"]) target_list = [t.strip().lower().replace(" ", "-") for t in target_list if t.strip()] @@ -148,47 +95,203 @@ ELSE IF --pages provided: # Priority 3: Extract from synthesis-specification.md ELSE IF --session: synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) - target_list = extract_targets_from_synthesis(synthesis_spec) - target_type = "page" # Synthesis typically defines pages + target_list = extract_targets_from_synthesis(synthesis_spec); target_type = "page" REPORT: "📋 Extracted from synthesis: {', '.join(target_list)}" # Priority 4: Detect from existing prototypes or default ELSE: - target_list = detect_from_prototypes({base_path}/prototypes/) OR ["home"] - target_type = "page" + target_list = detect_from_prototypes({base_path}/prototypes/) OR ["home"]; target_type = "page" REPORT: "📋 Detected/default targets: {', '.join(target_list)}" # 4. 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)}" - +IF invalid_targets: REPORT: "⚠️ Skipped invalid target names: {', '.join(invalid_targets)}" VALIDATE: validated_targets not empty, "No valid targets found" target_list = validated_targets -# Store for later use -STORE: target_list = target_list -STORE: target_type = target_type +STORE: target_list, target_type # 5. Verify design systems exist FOR style_id IN range(1, style_variants + 1): - VERIFY: {base_path}/style-consolidation/style-{style_id}/design-tokens.json exists - VERIFY: {base_path}/style-consolidation/style-{style_id}/style-guide.md exists + VERIFY: exists({base_path}/style-consolidation/style-{style_id}/design-tokens.json) + VERIFY: exists({base_path}/style-consolidation/style-{style_id}/style-guide.md) # 6. Load requirements (if integrated mode) -IF --session: - synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) +IF --session: synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) ``` -### Phase 1.5: Token Variable Name Extraction +### Phase 1.5: Target-Specific Layout Planning ```bash -# Load design-tokens.json from style-1 to extract exact variable names -# This ensures template generation uses correct token names -REPORT: "📋 Extracting design token variable names..." +REPORT: "📐 Planning {layout_variants} layout strategies for each target..." +CREATE: {base_path}/prototypes/_templates/ + +# For each target, plan its specific layouts +FOR target IN target_list: + REPORT: " Planning layouts for '{target}' ({target_type})..." + + FOR layout_id IN range(1, layout_variants + 1): + Task(ui-design-agent): " + [TARGET_LAYOUT_PLANNING] + + Generate a concrete, actionable layout plan for a specific target and WRITE it to the file system. + + ## Context + TARGET: {target} + TARGET_TYPE: {target_type} + LAYOUT_ID: {layout_id} + BASE_PATH: {base_path} + {IF --session: PROJECT_REQUIREMENTS: Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)} + + ## Task + Research, design, and WRITE a modern, innovative layout plan specifically for '{target}'. + + ## Research Phase (Use MCP Tools) + 1. Search for modern {target_type} layout patterns: + mcp__exa__get_code_context_exa( + query=\"modern {target} {target_type} layout design patterns 2024 2025\", + tokensNum=\"dynamic\" + ) + 2. Search for {target}-specific UI best practices + + ## Layout Planning Rules + + **For PAGES (target_type='page')**: + - Define macro-layout: main regions (header, sidebar, main, footer) + - Specify grid/flexbox structure for content organization + - Define responsive breakpoints and behavior + - Include navigation and page-level components + + **For COMPONENTS (target_type='component')**: + - Define micro-layout: internal element arrangement + - Specify alignment, spacing, and element sizing + - Focus on component-specific structure (no header/footer) + - Optimize for reusability and composition + + ## File Write Instructions + Generate layout plan JSON and WRITE it using Write() tool: + + **Path**: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.json + + **Content** - JSON with this EXACT structure: + ```json + { + \"id\": \"layout-{layout_id}\", + \"target\": \"{target}\", + \"target_type\": \"{target_type}\", + \"name\": \"Descriptive name (2-4 words)\", + \"description\": \"Detailed description (2-3 sentences explaining structure, use cases, and unique aspects)\", + \"structure\": { + // For pages, include: + \"type\": \"sidebar-main\" | \"centered\" | \"asymmetric\" | \"grid-dashboard\", + \"regions\": [\"header\", \"sidebar\", \"main\", \"footer\"], + \"grid\": { + \"columns\": 12, + \"rows\": \"auto\", + \"gap\": \"var(--spacing-6)\" + }, + \"sidebar\": { + \"position\": \"left\" | \"right\", + \"width\": \"250px\", + \"fixed\": true, + \"collapsible\": true + }, + \"responsive\": { + \"mobile\": {\"columns\": 1, \"sidebar\": \"hidden\"}, + \"tablet\": {\"columns\": 6, \"sidebar\": \"overlay\"}, + \"desktop\": {\"columns\": 12, \"sidebar\": \"fixed\"} + }, + + // For components, include: + \"arrangement\": \"flex-column\" | \"flex-row\" | \"grid\", + \"alignment\": \"center\" | \"start\" | \"end\" | \"stretch\", + \"spacing\": \"compact\" | \"normal\" | \"relaxed\", + \"element_order\": [\"icon\", \"title\", \"description\", \"action\"] + }, + \"semantic_hints\": [ + \"dashboard\", + \"data-visualization\", + \"navigation-sidebar\", + \"card-based\" + ], + \"accessibility_features\": [ + \"skip-navigation\", + \"landmark-regions\", + \"keyboard-navigation\", + \"screen-reader-optimized\" + ], + \"research_references\": [ + \"URL or description of research source 1\", + \"URL or description of research source 2\" + ] + } + ``` + + ## Write Operation Instructions + - Use Write() tool with the absolute path provided above + - Create directory if needed: Bash('mkdir -p {base_path}/prototypes/_templates') + - Verify write operation succeeds + + ## Example Write Operation + ```javascript + Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json\", JSON.stringify(layout_plan, null, 2)) + ``` + + ## Completion + Report successful file creation with path confirmation. + + ## Critical Requirements + - ✅ Layout plan is ONLY for '{target}' - tailor to this specific target's needs + - ✅ Consider {target_type} type (page vs component) when designing structure + - ✅ Research modern patterns using MCP tools before designing + - ✅ Provide concrete, implementable structure (not abstract descriptions) + - ✅ Different layout IDs should explore meaningfully different approaches + - ✅ Use semantic naming and clear documentation + - ✅ Write file directly using Write() tool - do NOT return contents as text + " + +# Wait for all agent tasks to complete +REPORT: "⏳ Waiting for layout planning agents to complete..." + +# Verify agent created layout JSON files +REPORT: "📝 Verifying agent file creation..." + +FOR target IN target_list: + FOR layout_id IN range(1, layout_variants + 1): + layout_json_label = f"{target}-layout-{layout_id}.json" + json_path = f"{base_path}/prototypes/_templates/{layout_json_label}" + + # Verify file exists + VERIFY: exists(json_path), f"Layout JSON not created by agent: {layout_json_label}" + + # Validate JSON structure + TRY: + layout_json_content = Read(json_path) + layout_plan = JSON.parse(layout_json_content) + + # Validate required fields + VALIDATE: layout_plan.id == f"layout-{layout_id}", f"Invalid layout ID in {layout_json_label}" + VALIDATE: layout_plan.target == target, f"Invalid target in {layout_json_label}" + VALIDATE: layout_plan.target_type == target_type, f"Invalid target_type in {layout_json_label}" + VALIDATE: layout_plan.name exists, f"Missing 'name' field in {layout_json_label}" + VALIDATE: layout_plan.structure exists, f"Missing 'structure' field in {layout_json_label}" + + file_size = get_file_size(json_path) + REPORT: f" ✓ Verified: {layout_json_label} - {layout_plan.name} ({file_size} KB)" + CATCH error: + ERROR: f"Validation failed for {layout_json_label}: {error}" + REPORT: f" ⚠️ File exists but validation failed - review agent output" + +REPORT: f"✅ Phase 1.5 complete: Verified {len(target_list) × layout_variants} target-specific layout files" +``` + +### Phase 1.6: Token Variable Name Extraction + +```bash +REPORT: "📋 Extracting design token variable names..." tokens_json_path = "{base_path}/style-consolidation/style-1/design-tokens.json" VERIFY: exists(tokens_json_path), "Design tokens not found. Run /workflow:ui-design:consolidate first." @@ -196,38 +299,14 @@ design_tokens = Read(tokens_json_path) # Extract all available token categories and variable names token_reference = { - "colors": { - "brand": list(design_tokens.colors.brand.keys()), # e.g., ["primary", "secondary", "accent"] - "surface": list(design_tokens.colors.surface.keys()), # e.g., ["background", "elevated", "overlay"] - "semantic": list(design_tokens.colors.semantic.keys()), # e.g., ["success", "warning", "error", "info"] - "text": list(design_tokens.colors.text.keys()), # e.g., ["primary", "secondary", "tertiary", "inverse"] - "border": list(design_tokens.colors.border.keys()) # e.g., ["default", "strong", "subtle"] - }, - "typography": { - "font_family": list(design_tokens.typography.font_family.keys()), # e.g., ["heading", "body", "mono"] - "font_size": list(design_tokens.typography.font_size.keys()), # e.g., ["xs", "sm", "base", "lg", "xl", "2xl", "3xl", "4xl"] - "font_weight": list(design_tokens.typography.font_weight.keys()), # e.g., ["normal", "medium", "semibold", "bold"] - "line_height": list(design_tokens.typography.line_height.keys()), # e.g., ["tight", "normal", "relaxed"] - "letter_spacing": list(design_tokens.typography.letter_spacing.keys()) # e.g., ["tight", "normal", "wide"] - }, - "spacing": list(design_tokens.spacing.keys()), # e.g., ["0", "1", "2", ..., "24"] - "border_radius": list(design_tokens.border_radius.keys()), # e.g., ["none", "sm", "md", "lg", "xl", "full"] - "shadows": list(design_tokens.shadows.keys()), # e.g., ["sm", "md", "lg", "xl"] - "breakpoints": list(design_tokens.breakpoints.keys()) # e.g., ["sm", "md", "lg", "xl", "2xl"] + "colors": {"brand": list(keys), "surface": list(keys), "semantic": list(keys), "text": list(keys), "border": list(keys)}, + "typography": {"font_family": list(keys), "font_size": list(keys), "font_weight": list(keys), "line_height": list(keys), "letter_spacing": list(keys)}, + "spacing": list(keys), "border_radius": list(keys), "shadows": list(keys), "breakpoints": list(keys) } # Generate complete variable name lists for Agent prompt -color_vars = [] -FOR category IN ["brand", "surface", "semantic", "text", "border"]: - FOR key IN token_reference.colors[category]: - color_vars.append(f"--color-{category}-{key}") - -typography_vars = [] -FOR category IN ["font_family", "font_size", "font_weight", "line_height", "letter_spacing"]: - prefix = "--" + category.replace("_", "-") - FOR key IN token_reference.typography[category]: - typography_vars.append(f"{prefix}-{key}") - +color_vars = []; FOR category, keys: FOR key: color_vars.append(f"--color-{category}-{key}") +typography_vars = []; FOR category, keys: FOR key: typography_vars.append(f"--{category.replace('_', '-')}-{key}") spacing_vars = [f"--spacing-{key}" for key in token_reference.spacing] radius_vars = [f"--border-radius-{key}" for key in token_reference.border_radius] shadow_vars = [f"--shadow-{key}" for key in token_reference.shadows] @@ -236,36 +315,31 @@ breakpoint_vars = [f"--breakpoint-{key}" for key in token_reference.breakpoints] all_token_vars = color_vars + typography_vars + spacing_vars + radius_vars + shadow_vars + breakpoint_vars REPORT: f"✅ Extracted {len(all_token_vars)} design token variables from design-tokens.json" -REPORT: f" - Color variables: {len(color_vars)}" -REPORT: f" - Typography variables: {len(typography_vars)}" -REPORT: f" - Spacing variables: {len(spacing_vars)}" -REPORT: f" - Other variables: {len(radius_vars) + len(shadow_vars) + len(breakpoint_vars)}" ``` ### Phase 2: Optimized Matrix UI Generation -**Strategy**: Two-layer generation reduces complexity from `O(S×L×P)` to `O(L×P)`, achieving **`S` times faster** performance. +**Strategy**: Two-layer generation reduces complexity from `O(S×L×T)` to `O(L×T)`, achieving **`S` times faster** performance. - **Layer 1**: Generate `L × T` layout templates (HTML structure + structural CSS) by agent - **Layer 2**: Instantiate `S × L × T` final prototypes via fast file operations -*T = targets (pages or components), P = pages (legacy notation)* - #### Phase 2a: Layout Template Generation **Parallel Executor**: → @ui-design-agent -Generate style-agnostic layout templates for each `{target} × {layout}` combination. -Total agent tasks: `layout_variants × len(target_list)` - ```bash -# Create directories CREATE: {base_path}/prototypes/_templates/ CREATE: {base_path}/prototypes/ # Launch parallel template generation tasks → @ui-design-agent +# Total agent tasks: layout_variants × len(target_list) FOR layout_id IN range(1, layout_variants + 1): FOR target IN target_list: + # Read the target-specific layout plan + layout_json_path = f"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json" + layout_plan = Read(layout_json_path) + Task(ui-design-agent): " [UI_LAYOUT_TEMPLATE_GENERATION] @@ -286,97 +360,126 @@ FOR layout_id IN range(1, layout_variants + 1): ✅ **RESEARCH-INFORMED**: Use MCP tools to research modern UI patterns as needed ## Context - LAYOUT_ID: {layout_id} - TARGET: {target} - TARGET_TYPE: {target_type} + LAYOUT_ID: {layout_id} | TARGET: {target} | TARGET_TYPE: {target_type} BASE_PATH: {base_path} - {IF --session: - Requirements: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md} + {IF --session: Requirements: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md} **Target Type Details**: {IF target_type == "page": - - Type: Full-page layout - - Wrapper: Complete HTML document structure with , , - - Navigation: Include header/navigation elements - - Footer: Include page footer + - Type: Full-page layout | Wrapper: Complete HTML document (, , ) + - Navigation: Include header/navigation | Footer: Include page footer - Content: Complete page content structure } {ELSE IF target_type == "component": - - Type: Isolated UI component - - Wrapper: Minimal container for component demonstration - - Navigation: Exclude header/footer (component-only) - - Container: Simple wrapper (e.g.,
) - - Content: Focus solely on the component design + - Type: Isolated UI component | Wrapper: Minimal container for demonstration + - Navigation: Exclude header/footer | Container: Simple wrapper (e.g.,
) + - Content: Focus solely on component design } ## Task - Generate TWO files that work together as a reusable template: + Generate TWO files that work together as a reusable template. - **File 1**: `{target}-layout-{layout_id}.html` - - 🏗️ **SEMANTIC STRUCTURE**: HTML5 structure WITHOUT any style-specific values - - {IF target_type == "page": "Complete HTML document with , , " ELSE: "Minimal wrapper with component container only"} - - 🔗 **DYNAMIC STYLING**: Use placeholder links for runtime style switching: - ```html + ### File 1: HTML Template (`{target}-layout-{layout_id}.html`) + + **Structure Requirements**: + - Semantic HTML5 elements with ARIA attributes + - Complete {target_type} wrapper (full document for pages, minimal for components) + - Zero hardcoded styles, colors, or spacing + - Responsive structure ready for mobile/tablet/desktop + + **⚠️ CRITICAL: CSS Placeholder Links** + + You MUST include these EXACT placeholder links in the `` section: + + ```html + + + ``` + + **Placeholder Rules**: + 1. Use EXACTLY `{{STRUCTURAL_CSS}}` and `{{TOKEN_CSS}}` with double curly braces + 2. Place in `` AFTER `` tags, BEFORE `` closing tag + 3. DO NOT substitute with actual paths - the script handles this + 4. DO NOT add any other CSS `` tags + 5. These enable runtime style switching for all variants + + **Complete HTML Template Examples**: + + {IF target_type == \"page\": + ```html + + + + + + {target} - Layout {layout_id} - ``` - - ♿ **ACCESSIBILITY**: All semantic elements, ARIA attributes, responsive structure - - 🚫 **ZERO HARDCODING**: NO inline styles, NO hardcoded colors/fonts/spacing - - 🎨 **STYLE-AGNOSTIC**: HTML structure must work with ANY design token set + + +
+
+
+ + + ``` + } - **File 2**: `{target}-layout-{layout_id}.css` + {ELSE IF target_type == \"component\": + ```html + + + + + + {target} Component - Layout {layout_id} + + + + +
+ +
+ + + ``` + } + + ### File 2: CSS Template (`{target}-layout-{layout_id}.css`) - 🎨 **TOKEN-DRIVEN STYLING**: ALL values use `var()` for dynamic theme switching - 🔄 **RUNTIME SWITCHABLE**: `background-color: var(--color-surface-background);` - 🚫 **ZERO LITERALS**: NO hardcoded values (#4F46E5, 16px, Arial) - 📐 **SEMANTIC NAMING**: BEM or descriptive class naming - 📱 **MOBILE-FIRST**: Responsive design using token-based breakpoints - - 💡 **VARIABLE REFERENCES**: Every visual property must use var(--token-name) - {IF target_type == "component": "Focus styles on component only, minimal global styles"} - ## Layout Diversity Strategy - Apply the following strategy from the planned layout strategies (loaded from layout-strategies.json): + ## Layout Plan (Target-Specific) + Implement the following pre-defined layout plan for this target: - **Layout ID**: {layout_id} - **Name**: {layout_strategies.strategies[layout_id - 1].name} - **Description**: {layout_strategies.strategies[layout_id - 1].description} + **Layout JSON Path**: {layout_json_path} + **Layout Plan**: + ```json + {JSON.stringify(layout_plan, null, 2)} + ``` - Apply this strategy CONSISTENTLY to all styles. + **Critical**: Your job is to IMPLEMENT this exact layout plan, not to redesign it. + - Follow the structure defined in the 'structure' field + - Use semantic hints for appropriate HTML elements + - Respect the target_type (page vs component) wrapper requirements + - Apply the specified responsive behavior ## Token Usage Requirements (STRICT - USE EXACT NAMES) - **CRITICAL**: You MUST use ONLY the variable names listed below. These are extracted from design-tokens.json. + **CRITICAL**: You MUST use ONLY the variable names listed below. DO NOT invent variable names like --color-background-base, --radius-md, --transition-base, etc. - **Available Color Variables** ({len(color_vars)} total): - {', '.join(color_vars[:10])}... ({len(color_vars) - 10} more) - - **Key Color Variables**: - - Brand: --color-brand-primary, --color-brand-secondary, --color-brand-accent - - Surface: --color-surface-background, --color-surface-elevated, --color-surface-overlay - - Text: --color-text-primary, --color-text-secondary, --color-text-tertiary, --color-text-inverse - - Border: --color-border-default, --color-border-strong, --color-border-subtle - - Semantic: --color-semantic-success, --color-semantic-warning, --color-semantic-error, --color-semantic-info - - **Available Typography Variables** ({len(typography_vars)} total): - {', '.join(typography_vars[:10])}... ({len(typography_vars) - 10} more) - - **Key Typography Variables**: - - Families: --font-family-heading, --font-family-body, --font-family-mono - - Sizes: --font-size-xs, --font-size-sm, --font-size-base, --font-size-lg, --font-size-xl, --font-size-2xl, --font-size-3xl, --font-size-4xl - - Weights: --font-weight-normal, --font-weight-medium, --font-weight-semibold, --font-weight-bold - - Line heights: --line-height-tight, --line-height-normal, --line-height-relaxed - - Letter spacing: --letter-spacing-tight, --letter-spacing-normal, --letter-spacing-wide - - **Available Spacing Variables** ({len(spacing_vars)} total): - {', '.join(spacing_vars)} - - **Available Border Radius Variables** ({len(radius_vars)} total): - {', '.join(radius_vars)} - - **Available Shadow Variables** ({len(shadow_vars)} total): - {', '.join(shadow_vars)} - - **Available Breakpoint Variables** ({len(breakpoint_vars)} total): - {', '.join(breakpoint_vars)} + **Available Variables** ({len(all_token_vars)} total): + - Color variables ({len(color_vars)}): --color-brand-primary, --color-surface-background, --color-text-primary, etc. + - Typography variables ({len(typography_vars)}): --font-family-heading, --font-size-base, --font-weight-bold, etc. + - Spacing variables ({len(spacing_vars)}): --spacing-0, --spacing-1, ..., --spacing-24 + - Border radius ({len(radius_vars)}): --border-radius-none, --border-radius-sm, ..., --border-radius-full + - Shadows ({len(shadow_vars)}): --shadow-sm, --shadow-md, --shadow-lg, --shadow-xl + - Breakpoints ({len(breakpoint_vars)}): --breakpoint-sm, --breakpoint-md, --breakpoint-lg, etc. **STRICT RULES**: 1. Use ONLY the variables listed above - NO custom variable names @@ -385,172 +488,99 @@ FOR layout_id IN range(1, layout_variants + 1): 4. NO hardcoded colors, fonts, or spacing (e.g., #4F46E5, 16px, Arial) 5. All `var()` references must match exact variable names above - ## HTML Requirements - - 🏗️ **SEMANTIC STRUCTURE**: HTML5 elements (
,