From 29dfd49c90ff99fc83fde69469deaf9955ddaaa3 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Thu, 9 Oct 2025 22:37:20 +0800 Subject: [PATCH] Enhance UI Design Workflow: Parameter Validation and Documentation Improvements - Added validation for --style-variants in generate command to ensure it matches actual style directories, preventing errors during prototype generation. - Updated ui-instantiate-prototypes.sh script to validate style variants against existing directories, providing warnings and auto-correcting when necessary. - Improved clarity in generate.md documentation regarding parameters, default values, and auto-detection mechanisms. - Created a comprehensive UI Design Workflow Parameter Clarity Report to address inconsistencies in parameter naming and documentation across extract, consolidate, and generate commands. - Unified parameter naming conventions to reduce confusion and improve user experience. - Enhanced user guidance with a new README.md for the UI Design Workflow, outlining best practices and common mistakes. --- .../workflow/ui-design/consolidate.md | 142 +-- .../commands/workflow/ui-design/extract.md | 807 +++++++++--------- .../commands/workflow/ui-design/generate.md | 168 ++-- .claude/scripts/ui-instantiate-prototypes.sh | 27 + ui-workflow-parameter-clarity-report.md | 425 +++++++++ 5 files changed, 951 insertions(+), 618 deletions(-) create mode 100644 ui-workflow-parameter-clarity-report.md diff --git a/.claude/commands/workflow/ui-design/consolidate.md b/.claude/commands/workflow/ui-design/consolidate.md index 8392f9eb..270624fe 100644 --- a/.claude/commands/workflow/ui-design/consolidate.md +++ b/.claude/commands/workflow/ui-design/consolidate.md @@ -3,10 +3,26 @@ name: consolidate description: Consolidate style variants into independent design systems and plan layout strategies usage: /workflow:ui-design:consolidate [--base-path ] [--session ] [--variants ] [--layout-variants ] argument-hint: "[--base-path \".workflow/WFS-xxx/design-run-xxx\"] [--variants 3] [--layout-variants 3]" +parameters: + - name: --variants + 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." + - name: --base-path + 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" --layout-variants 3 + - /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 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(*) --- @@ -228,17 +244,11 @@ FILE 1: style-{variant_id}/design-tokens.json "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" } - }, - "spacing": { "0": "0", "1": "0.25rem", "2": "0.5rem", ..., "24": "6rem" }, + "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", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" } + "breakpoints": { "sm": "640px", ..., "2xl": "1536px" } } FILE 2: style-{variant_id}/style-guide.md @@ -372,111 +382,33 @@ The generate command will read layout strategies from layout-strategies.json. ## design-tokens.json Format -Complete token structure with OKLCH colors and semantic naming: +**Token structure** (all variants follow identical structure with different values): ```json { "colors": { - "brand": { - "primary": "oklch(0.45 0.20 270 / 1)", - "secondary": "oklch(0.60 0.15 320 / 1)", - "accent": "oklch(0.70 0.18 150 / 1)" - }, - "surface": { - "background": "oklch(0.98 0.01 270 / 1)", - "elevated": "oklch(1.00 0.00 0 / 1)", - "overlay": "oklch(0.95 0.01 270 / 1)" - }, - "semantic": { - "success": "oklch(0.60 0.15 142 / 1)", - "warning": "oklch(0.75 0.12 85 / 1)", - "error": "oklch(0.55 0.22 27 / 1)", - "info": "oklch(0.55 0.18 252 / 1)" - }, - "text": { - "primary": "oklch(0.20 0.01 270 / 1)", - "secondary": "oklch(0.45 0.01 270 / 1)", - "tertiary": "oklch(0.60 0.01 270 / 1)", - "inverse": "oklch(0.95 0.01 270 / 1)" - }, - "border": { - "default": "oklch(0.85 0.01 270 / 1)", - "strong": "oklch(0.70 0.01 270 / 1)", - "subtle": "oklch(0.92 0.01 270 / 1)" - } + "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": "Inter, system-ui, sans-serif", - "body": "Inter, system-ui, sans-serif", - "mono": "JetBrains Mono, Consolas, 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" - } + "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", - "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" - } + "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" } } ``` +**Requirements**: All colors in OKLCH format, complete token coverage, semantic naming + ## Error Handling - **No style cards found**: Report error, suggest running `/workflow:ui-design:extract` first diff --git a/.claude/commands/workflow/ui-design/extract.md b/.claude/commands/workflow/ui-design/extract.md index f67af825..02dd57b7 100644 --- a/.claude/commands/workflow/ui-design/extract.md +++ b/.claude/commands/workflow/ui-design/extract.md @@ -3,11 +3,29 @@ name: extract description: Extract design style from reference images or text prompts using Claude's analysis usage: /workflow:ui-design:extract [--base-path ] [--session ] [--images ""] [--prompt ""] [--variants ] argument-hint: "[--base-path \".workflow/WFS-xxx/design-run-xxx\"] [--session WFS-xxx] [--images \"refs/*.png\"] [--prompt \"Modern minimalist\"] [--variants 3]" +parameters: + - name: --variants + type: number + default: 1 + description: "Number of design variants to extract (1-5). Each variant will be maximally contrasting. Generates style-cards.json with variant-N IDs." + - name: --images + type: string + description: "Glob pattern for reference images (e.g., 'refs/*.png'). Supports PNG, JPG, WebP." + - name: --prompt + type: string + description: "Text description of desired style (e.g., 'Modern minimalist blog'). Can be combined with --images." + - name: --session + type: string + description: "Workflow session ID (e.g., WFS-auth). Creates design run in session directory." + - name: --base-path + type: string + description: "Custom base path for output. Overrides --session if provided." examples: - /workflow:ui-design:extract --images "design-refs/*.png" --variants 3 - /workflow:ui-design:extract --prompt "Modern minimalist blog, dark theme" --variants 3 - /workflow:ui-design:extract --session WFS-auth --images "refs/*.png" --prompt "Linear.app style" --variants 2 - /workflow:ui-design:extract --base-path ".workflow/WFS-auth/design-run-20250109-143022" --images "refs/*.png" --variants 3 + - /workflow:ui-design:extract --prompt "Bold vibrant" --variants 1 # Single variant (default) allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*) --- @@ -82,108 +100,259 @@ IF input_mode IN ["text", "hybrid"]: CREATE: {base_path}/style-extraction/ ``` -### Phase 1.5: Design Trend Research (Exa MCP) +### Phase 0.5: AI-Driven Design Space Divergence ```bash -# Step 1: Load project context to inform search queries +# Step 1: Load project context to inform design space analysis 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 hints from context and prompt -search_hints = [] -IF prompt_guidance: - search_hints.append(extract_design_keywords(prompt_guidance)) # e.g., "minimalist", "dark theme", "Linear.app" -IF project_context: - search_hints.append(extract_project_type(project_context)) # e.g., "dashboard", "SaaS", "blog" +REPORT: "🎨 Analyzing design space to generate maximally contrasting directions..." -# Step 2: Search for design trends using Exa MCP -REPORT: "🔍 Researching modern design trends and color theory..." +# Step 2: AI-driven divergent direction generation +divergence_prompt = """ +Analyze the user's design requirements and generate {variants_count} MAXIMALLY CONTRASTING design directions. -# Build comprehensive search query -exa_queries = [ - "modern UI design color palettes trends 2024 2025 {search_hints}", - "typography web design best practices system fonts {search_hints}", - "design system color theory accessibility WCAG {search_hints}", - "UI spacing rhythm layout patterns {search_hints}" -] +USER INPUT: +{IF prompt_guidance} +Prompt: "{prompt_guidance}" +{ENDIF} -design_trends = {} -FOR query IN exa_queries: - category = identify_category(query) # "colors", "typography", "layout", "accessibility" - design_trends[category] = mcp__exa__get_code_context_exa( - query=query, - tokensNum="dynamic" - ) +{IF project_context} +Project Context Summary: +{extract_key_points(project_context, max_lines=10)} +{ENDIF} -REPORT: "✅ Design research complete. Found trends for: colors, typography, layout, accessibility" +{IF images} +Reference Images: {image_count} images will be analyzed in next phase +{ENDIF} + +DESIGN ATTRIBUTE SPACE (use to maximize contrast): +- Color Saturation: [monochrome, muted, moderate, vibrant, hypersaturated] +- Visual Weight: [minimal, light, balanced, bold, heavy] +- Formality: [playful, casual, professional, formal, luxury] +- Organic vs Geometric: [organic/fluid, soft, balanced, geometric, brutalist] +- Innovation: [timeless, modern, contemporary, trendy, experimental] +- Density: [spacious, airy, balanced, compact, dense] + +TASK: +1. Identify the design space center point from user requirements +2. Generate {variants_count} design 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 + - 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 + +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" + } +} + +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 +""" + +# Execute AI analysis +divergence_response = Claude_Native_Analysis(divergence_prompt) +divergent_directions = parse_json(divergence_response) + +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 ``` -### Phase 2: Unified Style Analysis (Claude with Design Trends) +### Phase 1.5: Variant-Specific Design Trend Research (Exa MCP) -This is a single-pass analysis that replaces all external tool calls. +```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. **Analysis Prompt Template**: ``` -Analyze the following design references and generate {variants_count} distinct design style proposals informed by current design trends. +Generate {variants_count} design style proposals, each guided by its pre-analyzed design direction and independent trend research. INPUT MODE: {input_mode} {IF input_mode IN ["image", "hybrid"]} VISUAL REFERENCES: {list of loaded images} -Identify: color palettes, typography patterns, spacing rhythms, visual hierarchy, component styles +Analyze these images through the lens of each variant's design philosophy {ENDIF} {IF input_mode IN ["text", "hybrid"]} TEXT GUIDANCE: "{prompt_guidance}" -Use this to guide the aesthetic direction and feature requirements +Apply this guidance while maintaining each variant's distinct aesthetic direction {ENDIF} -DESIGN TRENDS RESEARCH (from web, 2024-2025): +DESIGN SPACE ANALYSIS: +{design_space_analysis summary} -COLOR TRENDS: -{design_trends.colors} +VARIANT-SPECIFIC DESIGN DIRECTIONS AND RESEARCH: -TYPOGRAPHY TRENDS: -{design_trends.typography} +{FOR each variant_id IN design_trends.keys()} +--- +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} -LAYOUT PATTERNS: -{design_trends.layout} +SEARCH KEYWORDS: {', '.join(design_trends[variant_id].keywords)} +ANTI-PATTERNS (avoid): {', '.join(design_trends[variant_id].anti_keywords)} -ACCESSIBILITY GUIDELINES: -{design_trends.accessibility} +TREND RESEARCH FOR THIS VARIANT: -TASK: Generate {variants_count} design style variants that: -1. Each have a distinct visual identity and design philosophy -2. Incorporate modern design trends from the research above (2024-2025) -3. Balance trend awareness with timeless design principles -4. Use OKLCH color space for all color values -5. Include complete, production-ready design token proposals -6. Are semantically organized (brand, surface, semantic colors) -7. Apply current accessibility best practices from WCAG guidelines +Color Trends ({variant_id}): +{design_trends[variant_id].research.colors} -OUTPUT FORMAT: JSON matching this exact structure: +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} + +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 + +CRITICAL RULES FOR CONTRAST: +- Variant-1 should feel completely different from Variant-2 and Variant-3 +- Use each variant's specific attribute scores (e.g., "monochrome" vs "vibrant") +- Reference variant-specific research, NOT shared trends +- 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": "{session_id}", - "input_mode": "{input_mode}", - "timestamp": "{ISO timestamp}", - "variants_count": {variants_count} - }, + "extraction_metadata": { "session_id": "...", "input_mode": "...", "timestamp": "...", "variants_count": N }, "style_cards": [ { "id": "variant-1", - "name": "Concise Style Name (e.g., Modern Minimalist)", - "description": "2-3 sentence description of this style's visual language and user experience", - "design_philosophy": "Core design principles for this variant", - "preview": { - "primary": "oklch(...)", - "background": "oklch(...)", - "font_heading": "Font name, fallbacks", - "border_radius": "value" - }, + "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(...)" }, @@ -192,34 +361,29 @@ OUTPUT FORMAT: JSON matching this exact structure: "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" } - }, - "spacing": { "0": "0", "1": "0.25rem", "2": "0.5rem", ..., "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" } + "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 variants_count total + } + // Repeat structure for ALL {variants_count} variants ] } RULES: -- Each variant must be distinct in visual character -- Incorporate insights from DESIGN TRENDS RESEARCH into color, typography, and spacing choices -- Balance modern trends with timeless design principles +- 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 guidelines from research -- Apply modern typography trends (variable fonts, system font stacks, optical sizing) -- Include complete token categories for each variant -- Reference specific trends or patterns from the research when making design decisions +- 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 ``` ### Phase 3: Parse & Write Output @@ -241,9 +405,11 @@ Write({ TodoWrite({ todos: [ {content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"}, - {content: "Research modern design trends with Exa MCP", status: "completed", activeForm: "Researching design trends"}, - {content: "Analyze design references with Claude", status: "completed", activeForm: "Analyzing design"}, - {content: `Generate ${variants_count} style cards with token proposals`, status: "completed", activeForm: "Generating style cards"} + {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"} ] }); ``` @@ -256,8 +422,18 @@ Input mode: {input_mode} {IF image mode: Images analyzed: {count}} {IF prompt mode: Prompt: "{truncated_prompt}"} +🎨 Design Space Analysis: +- Generated {variants_count} MAXIMALLY CONTRASTING design directions +- Min pairwise contrast distance: {design_space_analysis.contrast_verification.min_pairwise_distance} +- Strategy: {design_space_analysis.contrast_verification.strategy} + Generated {variants_count} style variant(s): -{FOR each card: - {card.name} ({card.id})} +{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 @@ -280,113 +456,127 @@ OR (standalone mode): ### style-cards.json Format -Complete structure with example values: +**Schema Structure**: ```json { "extraction_metadata": { - "session_id": "WFS-xxx or design-session-xxx", + "session_id": "string", "input_mode": "image|text|hybrid", + "timestamp": "ISO 8601 string", + "variants_count": "number" + }, + "style_cards": [ + { + "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" + }, + "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": { "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" } + } + } + // Repeat structure for variants_count total (variant-1, variant-2, ..., variant-n) + ] +} +``` + +**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": "Modern Minimalist", - "description": "Clean, high-contrast design with bold typography and ample whitespace. Focuses on content clarity with minimal visual noise.", - "design_philosophy": "Less is more - prioritize content clarity and visual breathing room over decorative elements", + "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.45 0.20 270 / 1)", - "background": "oklch(0.98 0.01 270 / 1)", + "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.5rem" + "border_radius": "0" }, "proposed_tokens": { "colors": { "brand": { - "primary": "oklch(0.45 0.20 270 / 1)", - "secondary": "oklch(0.60 0.15 320 / 1)", - "accent": "oklch(0.70 0.18 150 / 1)" + "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.01 270 / 1)", - "elevated": "oklch(1.00 0.00 0 / 1)", - "overlay": "oklch(0.95 0.01 270 / 1)" + "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.60 0.15 142 / 1)", - "warning": "oklch(0.75 0.12 85 / 1)", - "error": "oklch(0.55 0.22 27 / 1)", - "info": "oklch(0.55 0.18 252 / 1)" + "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.20 0.01 270 / 1)", - "secondary": "oklch(0.45 0.01 270 / 1)", - "tertiary": "oklch(0.60 0.01 270 / 1)", - "inverse": "oklch(0.95 0.01 270 / 1)" + "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.85 0.01 270 / 1)", - "strong": "oklch(0.70 0.01 270 / 1)", - "subtle": "oklch(0.92 0.01 270 / 1)" + "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, Consolas, monospace" + "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" + "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" - } + "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" + "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" + "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)", @@ -395,247 +585,36 @@ Complete structure with example values: "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.15)" }, "breakpoints": { - "sm": "640px", - "md": "768px", - "lg": "1024px", - "xl": "1280px", - "2xl": "1536px" + "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" } } }, { "id": "variant-2", "name": "Bold Vibrant", - "description": "High-energy design with saturated colors and strong visual hierarchy. Creates excitement and demands attention.", - "design_philosophy": "Make a statement - use color and contrast to create memorable, energetic experiences", - "preview": { - "primary": "oklch(0.50 0.25 330 / 1)", - "background": "oklch(0.15 0.02 270 / 1)", - "font_heading": "Poppins, system-ui, sans-serif", - "border_radius": "0.75rem" - }, - "proposed_tokens": { - "colors": { - "brand": { - "primary": "oklch(0.50 0.25 330 / 1)", - "secondary": "oklch(0.65 0.22 60 / 1)", - "accent": "oklch(0.70 0.20 180 / 1)" - }, - "surface": { - "background": "oklch(0.15 0.02 270 / 1)", - "elevated": "oklch(0.20 0.02 270 / 1)", - "overlay": "oklch(0.25 0.02 270 / 1)" - }, - "semantic": { - "success": "oklch(0.65 0.18 140 / 1)", - "warning": "oklch(0.70 0.15 80 / 1)", - "error": "oklch(0.60 0.25 25 / 1)", - "info": "oklch(0.60 0.20 250 / 1)" - }, - "text": { - "primary": "oklch(0.95 0.01 270 / 1)", - "secondary": "oklch(0.75 0.01 270 / 1)", - "tertiary": "oklch(0.60 0.01 270 / 1)", - "inverse": "oklch(0.20 0.01 270 / 1)" - }, - "border": { - "default": "oklch(0.35 0.02 270 / 1)", - "strong": "oklch(0.50 0.02 270 / 1)", - "subtle": "oklch(0.25 0.02 270 / 1)" - } - }, - "typography": { - "font_family": { - "heading": "Poppins, system-ui, sans-serif", - "body": "Open Sans, system-ui, sans-serif", - "mono": "Fira Code, Consolas, 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.10)", - "md": "0 4px 6px oklch(0.00 0.00 0 / 0.15)", - "lg": "0 10px 15px oklch(0.00 0.00 0 / 0.20)", - "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.25)" - }, - "breakpoints": { - "sm": "640px", - "md": "768px", - "lg": "1024px", - "xl": "1280px", - "2xl": "1536px" - } - } + "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": "Elegant Serif", - "description": "Sophisticated design with serif typography and refined color palette. Conveys professionalism and timeless quality.", - "design_philosophy": "Timeless elegance - combine classical typography with modern layout principles", - "preview": { - "primary": "oklch(0.35 0.08 280 / 1)", - "background": "oklch(0.96 0.01 60 / 1)", - "font_heading": "Playfair Display, Georgia, serif", - "border_radius": "0.25rem" - }, - "proposed_tokens": { - "colors": { - "brand": { - "primary": "oklch(0.35 0.08 280 / 1)", - "secondary": "oklch(0.50 0.10 320 / 1)", - "accent": "oklch(0.65 0.12 40 / 1)" - }, - "surface": { - "background": "oklch(0.96 0.01 60 / 1)", - "elevated": "oklch(1.00 0.00 0 / 1)", - "overlay": "oklch(0.94 0.01 60 / 1)" - }, - "semantic": { - "success": "oklch(0.55 0.12 145 / 1)", - "warning": "oklch(0.70 0.10 85 / 1)", - "error": "oklch(0.50 0.18 30 / 1)", - "info": "oklch(0.50 0.15 255 / 1)" - }, - "text": { - "primary": "oklch(0.25 0.01 280 / 1)", - "secondary": "oklch(0.50 0.01 280 / 1)", - "tertiary": "oklch(0.65 0.01 280 / 1)", - "inverse": "oklch(0.95 0.01 60 / 1)" - }, - "border": { - "default": "oklch(0.82 0.01 60 / 1)", - "strong": "oklch(0.65 0.01 60 / 1)", - "subtle": "oklch(0.90 0.01 60 / 1)" - } - }, - "typography": { - "font_family": { - "heading": "Playfair Display, Georgia, serif", - "body": "Source Sans Pro, system-ui, sans-serif", - "mono": "Source Code Pro, Consolas, 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.03)", - "md": "0 4px 6px oklch(0.00 0.00 0 / 0.05)", - "lg": "0 10px 15px oklch(0.00 0.00 0 / 0.08)", - "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.12)" - }, - "breakpoints": { - "sm": "640px", - "md": "768px", - "lg": "1024px", - "xl": "1280px", - "2xl": "1536px" - } - } + "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 Points**: -- Each variant has complete, independent token proposals -- All colors use OKLCH format for perceptual uniformity -- Token structures are production-ready (no placeholders) -- Variants have distinct visual identities and philosophies +**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)` +- Token keys MUST match exactly across all variants for consistency +- Variants differ in VALUES, not structure +- Production-ready: no placeholders or incomplete sections ## Error Handling @@ -647,48 +626,60 @@ Complete structure with example values: ## Key Features -1. **Trend-Aware Style Generation** 🆕 - - Uses Exa MCP to research current design trends (2024-2025) - - Searches for color theory, typography trends, layout patterns, and accessibility guidelines - - Generates style variants informed by modern best practices - - Balances innovation with timeless design principles +1. **🚀 AI-Driven Design Space Exploration (Strategy A)** 🆕 + - **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. **Zero External Dependencies for Analysis** +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 + +3. **🔒 Maximum Contrast Guarantee** + - AI-driven divergence ensures variants are maximally distant in attribute space + - Each variant has distinct: philosophy, color saturation, visual weight, formality, etc. + - 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 trend integration + - Single-pass comprehensive analysis with variant-specific trend integration + - Only uses Exa MCP for external trend research (not for synthesis) -3. **Streamlined Output** +5. **Streamlined Output** - Single file (`style-cards.json`) vs. multiple scattered files - Eliminates `semantic_style_analysis.json`, `design-tokens.json`, `tailwind-tokens.js` clutter - Each variant contains complete token proposals embedded -4. **Flexible Input Modes** - - Image-only: Analyze visual references - - Text-only: Generate from descriptions - - Hybrid: Text guides image analysis - - All modes enhanced with web-based design research +6. **Flexible Input Modes** + - 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 -5. **Context-Aware Research** +7. **Context-Aware & Dynamic** - Extracts design keywords from user prompts (e.g., "minimalist", "Linear.app") - Considers project type from brainstorming artifacts - - Customizes search queries based on project context + - Dynamically generates design directions based on project context + - No hardcoded design philosophies - fully adaptive -6. **Reproducible Structure** - - Same inputs = same output structure - - Deterministic JSON schema - - Content informed by current design trends - -7. **Production-Ready Tokens** +8. **Production-Ready Tokens** - Complete design system proposals per variant - - OKLCH color format for accessibility + - OKLCH color format for perceptual uniformity and accessibility - Semantic naming conventions - - WCAG AA accessibility considerations from latest guidelines - - Modern typography trends (variable fonts, system stacks) + - WCAG AA accessibility considerations from shared research + - Variant-specific typography trends (not generic) -8. **Workflow Integration** +9. **Workflow Integration** - Integrated mode: Works within existing workflow sessions - Standalone mode: Auto-creates session in scratchpad - Context-aware: Can reference synthesis-specification.md or ui-designer/analysis.md + - Contrast metrics included in completion report ## Integration Points diff --git a/.claude/commands/workflow/ui-design/generate.md b/.claude/commands/workflow/ui-design/generate.md index a200dc45..41a9892b 100644 --- a/.claude/commands/workflow/ui-design/generate.md +++ b/.claude/commands/workflow/ui-design/generate.md @@ -3,11 +3,27 @@ name: generate description: Generate UI prototypes in matrix mode (style × layout combinations) for pages or components usage: /workflow:ui-design:generate [--targets ""] [--target-type "page|component"] [--base-path ] [--session ] [--style-variants ] [--layout-variants ] argument-hint: "[--targets \"dashboard,auth,navbar,hero\"] [--target-type \"page\"] [--base-path \".workflow/WFS-xxx/design-run-xxx\"] [--style-variants 3] [--layout-variants 3]" +parameters: + - name: --style-variants + type: number + default: 3 + description: "Number of style variants to generate prototypes for (1-5). Auto-validates against actual style-* directories. ⚠️ Recommend omitting to use auto-detection." + - name: --layout-variants + type: number + default: auto-detected from layout-strategies.json + description: "Number of layout variants. Default: loaded from consolidation output. Can override for manual testing." + - name: --targets + type: string + description: "Comma-separated list of targets (pages or components) to generate" + - name: --target-type + type: string + default: page + description: "Type of targets: 'page' (full layout) or 'component' (isolated element)" examples: - /workflow:ui-design:generate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --targets "dashboard,settings" --target-type "page" --style-variants 3 --layout-variants 3 - /workflow:ui-design:generate --session WFS-auth --targets "home,pricing" --target-type "page" --style-variants 2 --layout-variants 2 + - /workflow:ui-design:generate --base-path "./.workflow/.design/run-20250109-150533" # ✅ Recommended: auto-detect variants - /workflow:ui-design:generate --targets "navbar,hero,card" --target-type "component" --style-variants 3 --layout-variants 2 - - /workflow:ui-design:generate --base-path "./.workflow/.design/run-20250109-150533" --style-variants 3 --layout-variants 3 - /workflow:ui-design:generate --pages "home,dashboard" --style-variants 2 --layout-variants 2 # Legacy syntax executor: → @ui-design-agent allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*) @@ -79,8 +95,25 @@ ELSE: # 2. Determine style variant count (layout_variants already loaded in Phase 0) style_variants = --style-variants OR 3 # Default to 3 +# Validate range VALIDATE: 1 <= style_variants <= 5 +# Validate against actual style directories (prevent style-N file generation for non-existent 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 + +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 + +REPORT: "✅ Validated style variants: {style_variants} (matching actual directory count)" + # Note: layout_variants is loaded from layout-strategies.json in Phase 0 # 3. Enhanced target list parsing with type detection @@ -149,55 +182,7 @@ IF --session: synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) ``` -### Phase 1.5: Implementation Pattern Research (Exa MCP) - -```bash -# Step 1: Extract project context and technology preferences -project_context = "" -tech_stack_hints = [] - -IF --session: - # Load brainstorming artifacts to understand tech requirements - IF exists(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md): - project_context = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) - tech_stack_hints = extract_tech_stack(project_context) # e.g., "React", "Vue", "vanilla JS" - - IF exists(.workflow/WFS-{session}/.brainstorming/system-architect/analysis.md): - arch_context = Read(.workflow/WFS-{session}/.brainstorming/system-architect/analysis.md) - tech_stack_hints.extend(extract_tech_stack(arch_context)) - -# Step 2: Extract page types and requirements -page_types = classify_pages(page_list) # e.g., "dashboard", "auth", "settings" -layout_names = [s.name for s in layout_strategies.strategies] - -REPORT: "🔍 Researching modern UI implementation patterns..." - -# Step 3: Multi-dimensional implementation research using Exa MCP -exa_queries = { - "component_patterns": f"modern UI component implementation patterns {' '.join(tech_stack_hints)} 2024 2025", - "responsive_design": f"responsive web design best practices mobile-first {' '.join(page_types)} 2024", - "accessibility": f"web accessibility ARIA attributes implementation WCAG 2.2 {' '.join(page_types)}", - "html_semantics": f"semantic HTML5 structure best practices {' '.join(page_types)} modern", - "css_architecture": f"CSS architecture design tokens custom properties BEM {' '.join(tech_stack_hints)}" -} - -implementation_research = {} -FOR category, query IN exa_queries.items(): - REPORT: f" Searching {category}..." - implementation_research[category] = mcp__exa__get_code_context_exa( - query=query, - tokensNum="dynamic" - ) - -REPORT: "✅ Implementation research complete:" -REPORT: " - Component patterns and best practices" -REPORT: " - Responsive design strategies" -REPORT: " - Accessibility implementation guides" -REPORT: " - Semantic HTML structures" -REPORT: " - CSS architecture patterns" -``` - -### Phase 1.8: Token Variable Name Extraction +### Phase 1.5: Token Variable Name Extraction ```bash # Load design-tokens.json from style-1 to extract exact variable names @@ -261,15 +246,17 @@ REPORT: f" - Other variables: {len(radius_vars) + len(shadow_vars) + len(break **Strategy**: Two-layer generation reduces complexity from `O(S×L×P)` to `O(L×P)`, achieving **`S` times faster** performance. -- **Layer 1**: Generate `L × P` layout templates (HTML structure + structural CSS) with modern best practices -- **Layer 2**: Instantiate `S × L × P` final prototypes via fast file operations +- **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 -#### Phase 2a: Layout Template Generation (Research-Informed) +*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 `{page} × {layout}` combination. -Total agent tasks: `layout_variants × len(page_list)` +Generate style-agnostic layout templates for each `{target} × {layout}` combination. +Total agent tasks: `layout_variants × len(target_list)` ```bash # Create directories @@ -289,13 +276,14 @@ FOR layout_id IN range(1, layout_variants + 1): - Even if '{target}' might coexist with other targets in a final application, your task is to create an INDEPENDENT, REUSABLE template for '{target}' alone - Generate a **style-agnostic** layout template for a specific {target_type} and layout strategy, informed by modern web development best practices. + Generate a **style-agnostic** layout template for a specific {target_type} and layout strategy. 🎯 **CRITICAL REQUIREMENTS**: ✅ **ADAPTIVE**: Multi-device responsive design (mobile, tablet, desktop) ✅ **STYLE-SWITCHABLE**: Support runtime theme/style switching via CSS variables ✅ **TOKEN-DRIVEN**: 100% CSS variable usage, zero hardcoded values ✅ **INDEPENDENT**: Template for '{target}' only, no other targets included + ✅ **RESEARCH-INFORMED**: Use MCP tools to research modern UI patterns as needed ## Context LAYOUT_ID: {layout_id} @@ -320,25 +308,8 @@ FOR layout_id IN range(1, layout_variants + 1): - Content: Focus solely on the component design } - ## Implementation Research (from web, 2024-2025) - - COMPONENT PATTERNS: - {implementation_research.component_patterns} - - RESPONSIVE DESIGN: - {implementation_research.responsive_design} - - ACCESSIBILITY GUIDELINES: - {implementation_research.accessibility} - - HTML SEMANTICS: - {implementation_research.html_semantics} - - CSS ARCHITECTURE: - {implementation_research.css_architecture} - ## Task - Generate TWO files that work together as a reusable template, incorporating insights from the implementation research above: + 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 @@ -414,20 +385,20 @@ 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 (Apply Modern Best Practices from Research) + ## HTML Requirements - 🏗️ **SEMANTIC STRUCTURE**: HTML5 elements (
,