From 20c75c0060ea66b0ea51869ba7fe896e19871c0b Mon Sep 17 00:00:00 2001 From: catlog22 Date: Thu, 9 Oct 2025 18:04:37 +0800 Subject: [PATCH] feat: integrate Exa MCP for design trend research in UI workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enhance UI Design Workflow with intelligent design trend research capabilities: - Add design trend analysis in extract phase using Exa MCP API - Integrate layout strategy planning with current UI/UX patterns (2024-2025) - Update consolidation command to include dynamic layout generation - Add ui-instantiate-prototypes.sh script for prototype management - Simplify path structure by removing nested .design directories - Update workflow architecture documentation This integration enables context-aware design decisions based on modern design trends and improves the quality of generated UI prototypes. πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../workflow/ui-design/consolidate.md | 380 +++++---- .../workflow/ui-design/explore-auto.md | 39 +- .../commands/workflow/ui-design/extract.md | 128 ++- .../commands/workflow/ui-design/generate.md | 502 +++++------ .../workflow/ui-design/imitate-auto.md | 42 +- .claude/commands/workflow/ui-design/update.md | 58 +- .claude/scripts/ui-instantiate-prototypes.sh | 784 ++++++++++++++++++ .claude/workflows/workflow-architecture.md | 13 + 8 files changed, 1466 insertions(+), 480 deletions(-) create mode 100644 .claude/scripts/ui-instantiate-prototypes.sh diff --git a/.claude/commands/workflow/ui-design/consolidate.md b/.claude/commands/workflow/ui-design/consolidate.md index 4f781150..684089ce 100644 --- a/.claude/commands/workflow/ui-design/consolidate.md +++ b/.claude/commands/workflow/ui-design/consolidate.md @@ -1,39 +1,46 @@ --- name: consolidate -description: Consolidate style variants into unified or separate design systems -usage: /workflow:ui-design:consolidate [--base-path ] [--session ] [--variants ] [--keep-separate] -argument-hint: "[--base-path \".workflow/WFS-xxx/runs/run-xxx/.design\"] [--variants 3] [--keep-separate]" +description: Consolidate style variants into unified or separate design systems and plan layout strategies +usage: /workflow:ui-design:consolidate [--base-path ] [--session ] [--variants ] [--keep-separate] [--layout-variants ] +argument-hint: "[--base-path \".workflow/WFS-xxx/design-run-xxx\"] [--variants 3] [--keep-separate] [--layout-variants 3]" examples: - - /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/latest/.design" --variants 3 --keep-separate - - /workflow:ui-design:consolidate --session WFS-auth --variants 2 - - /workflow:ui-design:consolidate --base-path "./design-session-xxx/.design" + - /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --variants 3 --keep-separate --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 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*) --- -# Style Consolidation Command +# Design System Consolidation & Layout Planning Command ## Overview -Consolidate user-selected style variants into unified or separate production-ready design systems using Claude's native synthesis capabilities. Merges token proposals from multiple style cards into cohesive design language(s). +Consolidate user-selected style variants into unified or separate 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. ## Core Philosophy +- **Design Planning Hub**: Centralizes both style consolidation and layout strategy planning - **Claude-Native**: 100% Claude-driven consolidation, no external tools - **Token Merging**: Combines `proposed_tokens` from selected variants +- **Layout Strategy Definition**: Plans and documents layout variants for generation - **Intelligent Synthesis**: Resolves conflicts, ensures consistency - **Production-Ready**: Complete design system(s) with documentation - **Dual Mode**: Unified (1 merged system) or Separate (N independent systems) ## Execution Protocol -### Phase 1: Path Resolution & Variant Loading +### πŸ”„ Common Phases (All Modes) + +These phases are executed identically regardless of consolidation mode. + +#### Phase 1: Path Resolution & Variant Loading ```bash # Determine base path IF --base-path provided: base_path = {provided_base_path} ELSE IF --session provided: - base_path = ".workflow/WFS-{session}/latest/.design" + # 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/") + base_path = find_latest_path_matching(".workflow/.design/*") # Verify extraction output exists style_cards_path = "{base_path}/style-extraction/style-cards.json" @@ -44,7 +51,7 @@ style_cards = Read(style_cards_path) total_variants = len(style_cards.style_cards) ``` -### Phase 2: Variant Selection & Mode Determination +#### Phase 2: Variant Selection & Mode Determination ```bash # Determine how many variants to consolidate @@ -67,7 +74,86 @@ ELSE: REPORT: "Mode: Unified - merging {variants_count} variants into one design system" ``` -### Phase 3: Load Design Context (Optional) +#### 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 {layout_variants} distinct, modern UI layout strategies for this project. + +PROJECT CONTEXT: +{project_context} + +CURRENT LAYOUT TRENDS (from web research): +{layout_trends} + +REQUIREMENTS: +1. Each layout must be unique and serve different use cases +2. Consider modern design trends from 2024-2025 +3. Align with project type: {project_hints} +4. Balance innovation with usability +5. Cover diverse layout paradigms (grid-based, asymmetric, minimal, etc.) + +OUTPUT FORMAT (JSON): +{ + "layout_variants_count": {layout_variants}, + "strategies": [ + { + "id": "layout-1", + "name": "{Concise name, max 3 words}", + "description": "{Detailed description: layout structure, visual hierarchy, reading patterns, use cases. 2-3 sentences.}" + }, + ... + ] +} + +RESPONSE FORMAT: +Provide ONLY the JSON object, no additional text. + +===== 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 @@ -78,15 +164,19 @@ ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md): design_context = Read({base_path}/.brainstorming/ui-designer/analysis.md) ``` -### Phase 4: Design System Synthesis (Claude) +--- -**Route based on consolidation_mode**: +### πŸ”€ Mode-Specific Phases -#### Mode A: Unified Consolidation (Default) +**Execution branches based on `consolidation_mode`:** -Merges all style variants into a single, cohesive design system. +#### Branch A: Unified Mode -**Synthesis Prompt Template**: +**When**: `consolidation_mode == "unified"` (default) + +**Goal**: Merge all selected variants into a single, cohesive design system. + +**Phase 4A: Unified Design System Synthesis** ``` Create a unified, production-ready design system by consolidating the following style variants. @@ -173,36 +263,29 @@ FILE 2: style-guide.md - UI components meet WCAG AA (3:1 minimum) - Focus indicators are clearly visible -FILE 3: tailwind.config.js -module.exports = { - theme: { - extend: { - colors: { brand: { primary: '{value}', ... }, ... }, - fontFamily: { heading: [{fonts}], body: [{fonts}], mono: [{fonts}] }, - fontSize: { ... }, - spacing: { ... }, - borderRadius: { ... }, - boxShadow: { ... }, - screens: { ... } - } - } -} - -FILE 4: validation-report.json +FILE 3: consolidation-report.json { "session_id": "{session_id}", - "consolidated_variants": {variant_ids}, + "consolidation_mode": "unified", "timestamp": "{ISO timestamp}", - "validation_results": { - "colors": { "total": {count}, "wcag_aa_compliant": {count}, "warnings": [{issues}] }, - "typography": { "font_families": {count}, "scale_sizes": {count} }, - "spacing": { "scale_values": {count} }, - "accessibility": { "status": "pass|warnings", "issues": [{list}] }, - "completeness": { - "required_categories": ["colors", "typography", "spacing", "border_radius", "shadows", "breakpoints"], - "present_categories": [{list}], - "missing_categories": [{list if any}] + "style_systems": { + "consolidated_variants": {variant_ids}, + "variant_count": {selected_variants.length}, + "validation_results": { + "colors": { "total": {count}, "wcag_aa_compliant": {count}, "warnings": [{issues}] }, + "typography": { "font_families": {count}, "scale_sizes": {count} }, + "spacing": { "scale_values": {count} }, + "accessibility": { "status": "pass|warnings", "issues": [{list}] }, + "completeness": { + "required_categories": ["colors", "typography", "spacing", "border_radius", "shadows", "breakpoints"], + "present_categories": [{list}], + "missing_categories": [{list if any}] + } } + }, + "layout_strategies": { + "count": {layout_variants}, + "strategies": {READ from layout-strategies.json} } } @@ -215,22 +298,42 @@ Provide each file's content in clearly labeled sections: ===== style-guide.md ===== {Markdown content} -===== tailwind.config.js ===== -{JavaScript content} - -===== validation-report.json ===== +===== consolidation-report.json ===== {JSON content} ``` -**Output Location**: `{base_path}/style-consolidation/` +**Phase 5A: Unified Output** + +```bash +# Parse Claude's response +CREATE: {base_path}/style-consolidation/ +parsed_output = parse_claude_response(claude_response) + +Write({base_path}/style-consolidation/design-tokens.json, parsed_output.design_tokens) +Write({base_path}/style-consolidation/style-guide.md, parsed_output.style_guide) +Write({base_path}/style-consolidation/consolidation-report.json, parsed_output.consolidation_report) +``` + +**Output Structure**: +``` +{base_path}/style-consolidation/ +β”œβ”€β”€ design-tokens.json # Merged token definitions +β”œβ”€β”€ style-guide.md # Comprehensive design documentation +β”œβ”€β”€ layout-strategies.json # Layout variant definitions +└── consolidation-report.json # Unified validation & planning report +``` --- -#### Mode B: Separate Consolidation (--keep-separate) +#### Branch B: Separate Mode -Generates N independent design systems, each refining one style variant into a complete production-ready system. +**When**: `consolidation_mode == "separate"` (--keep-separate flag) -**For each variant, use this Synthesis Prompt Template**: +**Goal**: Generate N independent design systems, each refining one style variant. + +**Phase 4B: Separate Design System Synthesis** + +For each variant, use this synthesis prompt: ``` Create a production-ready design system for the following style variant. @@ -261,7 +364,7 @@ REFINEMENT RULES: 6. **OKLCH Format**: All colors must use oklch(L C H / A) format 7. **Design Philosophy**: Expand and articulate the variant's design philosophy -OUTPUT: Generate the same 4 files as unified mode (design-tokens.json, style-guide.md, tailwind.config.js, validation-report.json) +OUTPUT: Generate 2 files (design-tokens.json, style-guide.md) - validation will be aggregated later RESPONSE FORMAT: Provide each file's content in clearly labeled sections: @@ -271,47 +374,9 @@ Provide each file's content in clearly labeled sections: ===== style-guide.md ===== {Markdown content} - -===== tailwind.config.js ===== -{JavaScript content} - -===== validation-report.json ===== -{JSON content} ``` -**Output Location**: `{base_path}/style-consolidation/style-{n}/` - -For N variants, generate N separate subdirectories: -``` -{base_path}/style-consolidation/ -β”œβ”€β”€ style-1/ -β”‚ β”œβ”€β”€ design-tokens.json -β”‚ β”œβ”€β”€ style-guide.md -β”‚ β”œβ”€β”€ tailwind.config.js -β”‚ └── validation-report.json -β”œβ”€β”€ style-2/ -β”‚ └── ... (same structure) -└── style-N/ - └── ... (same structure) -``` - ---- - -### Phase 5: Parse & Write Output Files - -#### Unified Mode Output -```bash -# Parse Claude's response -CREATE: {base_path}/style-consolidation/ -parsed_output = parse_claude_response(claude_response) - -Write({base_path}/style-consolidation/design-tokens.json, parsed_output.design_tokens) -Write({base_path}/style-consolidation/style-guide.md, parsed_output.style_guide) -Write({base_path}/style-consolidation/tailwind.config.js, parsed_output.tailwind_config) -Write({base_path}/style-consolidation/validation-report.json, parsed_output.validation_report) -``` - -#### Separate Mode Output +**Phase 5B: Separate Output** ```bash # Parse each variant's response FOR variant_id IN range(1, variants_count + 1): @@ -320,32 +385,76 @@ FOR variant_id IN range(1, variants_count + 1): Write({base_path}/style-consolidation/style-{variant_id}/design-tokens.json, parsed_output.design_tokens) Write({base_path}/style-consolidation/style-{variant_id}/style-guide.md, parsed_output.style_guide) - Write({base_path}/style-consolidation/style-{variant_id}/tailwind.config.js, parsed_output.tailwind_config) - Write({base_path}/style-consolidation/style-{variant_id}/validation-report.json, parsed_output.validation_report) + +# Generate unified consolidation report for all variants +consolidation_report = { + "session_id": session_id, + "consolidation_mode": "separate", + "timestamp": ISO_timestamp, + "style_systems": { + "variant_count": variants_count, + "variants": [] + }, + "layout_strategies": Read({base_path}/style-consolidation/layout-strategies.json) +} + +# Aggregate validation data from all style variants +FOR variant_id IN range(1, variants_count + 1): + design_tokens = Read({base_path}/style-consolidation/style-{variant_id}/design-tokens.json) + validation_data = validate_design_tokens(design_tokens) + consolidation_report.style_systems.variants.append({ + "id": "style-{variant_id}", + "validation": validation_data + }) + +Write({base_path}/style-consolidation/consolidation-report.json, JSON.stringify(consolidation_report, null, 2)) ``` -### Phase 6: Completion +**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 +└── consolidation-report.json # Unified validation for all styles + layout plan +``` + +--- + +### 🎯 Common Completion Phase + +**Phase 6: Completion & Reporting** (executed after mode-specific phases) ```javascript TodoWrite({ todos: [ {content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"}, {content: "Select variants and determine mode", 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: "Synthesize design system(s) with Claude", status: "completed", activeForm: "Synthesizing design system"}, - {content: "Write consolidated design system files", status: "completed", activeForm: "Writing output files"} + {content: "Write consolidated design system files", status: "completed", activeForm: "Writing output files"}, + {content: "Generate unified consolidation report", status: "completed", activeForm: "Generating report"} ] }); ``` **Completion Message**: ``` -βœ… Style consolidation complete for session: {session_id} +βœ… Design consolidation & layout planning complete for session: {session_id} Mode: {consolidation_mode} -Consolidated {selected_variants.length} variant(s): +Consolidated {selected_variants.length} style variant(s): {FOR each variant: - {variant.name} ({variant.id})} +Layout Strategies Planned: {layout_variants} +{FOR each strategy: - Layout {strategy.id}: {strategy.name}} + {IF unified mode: Validation Summary: - Colors: {total_colors} (WCAG AA: {compliant_count}/{total_colors}) @@ -356,47 +465,25 @@ Validation Summary: πŸ“‚ Output: {base_path}/style-consolidation/ β”œβ”€β”€ design-tokens.json β”œβ”€β”€ style-guide.md - β”œβ”€β”€ tailwind.config.js - └── validation-report.json + β”œβ”€β”€ layout-strategies.json [NEW] + └── consolidation-report.json [NEW - replaces validation-report.json] } {IF separate mode: Generated {variants_count} independent design systems: πŸ“‚ Output: {base_path}/style-consolidation/ -β”œβ”€β”€ style-1/ (design-tokens.json, style-guide.md, tailwind.config.js, validation-report.json) +β”œβ”€β”€ style-1/ (design-tokens.json, style-guide.md) β”œβ”€β”€ style-2/ (same structure) -└── style-{variants_count}/ (same structure) +β”œβ”€β”€ style-{variants_count}/ (same structure) +β”œβ”€β”€ layout-strategies.json [NEW] +└── consolidation-report.json [NEW - unified report for all variants] } -Next: /workflow:ui-design:generate --session {session_id} {IF separate: --style-variants {variants_count}} --pages "dashboard,auth" +Next: /workflow:ui-design:generate --session {session_id} {IF separate: --style-variants {variants_count} --layout-variants {layout_variants}} --pages "dashboard,auth" Note: When called from /workflow:ui-design:auto, UI generation is triggered automatically. -``` - -## Output Structure - -### Unified Mode -``` -{base_path}/style-consolidation/ -β”œβ”€β”€ design-tokens.json # Merged token definitions -β”œβ”€β”€ style-guide.md # Comprehensive design documentation -β”œβ”€β”€ tailwind.config.js # Tailwind theme configuration -└── validation-report.json # Validation audit results -``` - -### Separate Mode (--keep-separate) -``` -{base_path}/style-consolidation/ -β”œβ”€β”€ style-1/ -β”‚ β”œβ”€β”€ design-tokens.json # Style 1 token definitions -β”‚ β”œβ”€β”€ style-guide.md # Style 1 documentation -β”‚ β”œβ”€β”€ tailwind.config.js # Style 1 Tailwind config -β”‚ └── validation-report.json # Style 1 validation -β”œβ”€β”€ style-2/ -β”‚ └── ... (same structure) -└── style-N/ - └── ... (same structure) +The generate command will now read layout strategies from layout-strategies.json. ``` ## design-tokens.json Format @@ -516,40 +603,53 @@ Complete token structure with OKLCH colors and semantic naming: ## Key Features -1. **Zero External Dependencies** - - No `gemini-wrapper`, no `codex` - pure Claude synthesis +1. **Zero External Dependencies for Style Consolidation** + - No `gemini-wrapper`, no `codex` for style synthesis - pure Claude - Single-pass comprehensive prompt generates all outputs 2. **Dual Consolidation Modes** - Unified: Merge N variants β†’ 1 design system (default) - Separate: Refine N variants β†’ N independent systems (--keep-separate) -3. **Direct Token Merging** +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. **Direct Token Merging** - Reads `proposed_tokens` from style cards directly - Intelligent conflict resolution with clear rules -4. **Complete Design System Output** +5. **Complete Design System Output** - design-tokens.json (CSS tokens) - style-guide.md (documentation) - - tailwind.config.js (framework integration) - - validation-report.json (quality audit) + - layout-strategies.json (dynamic layout plans) + - consolidation-report.json (quality audit & planning) -5. **Production-Ready Quality** +6. **Production-Ready Quality** - WCAG AA accessibility validation - OKLCH color format for perceptual uniformity - Semantic token naming - Complete token coverage -6. **Streamlined Workflow** - - `Load β†’ Synthesize β†’ Write` (3 core steps) +7. **Streamlined Workflow** + - Common phases (setup, context, completion) shared across modes + - Mode-specific synthesis clearly separated - Reproducible with deterministic structure - Context-aware (integrates brainstorming artifacts) ## Integration Points -- **Input**: `style-cards.json` from `/workflow:ui-design:extract` (with `proposed_tokens`) +- **Input**: + - `style-cards.json` from `/workflow:ui-design:extract` (with `proposed_tokens`) + - `--layout-variants` parameter (default: 3) - **Output**: - - Unified: `style-consolidation/design-tokens.json` for `/workflow:ui-design:generate` - - Separate: `style-consolidation/style-{n}/design-tokens.json` for matrix mode generation + - Style Systems: + - Unified: `style-consolidation/design-tokens.json` for `/workflow:ui-design:generate` + - Separate: `style-consolidation/style-{n}/design-tokens.json` for matrix mode generation + - Layout Planning: `layout-strategies.json` consumed by `/workflow:ui-design:generate` + - Unified Reporting: `consolidation-report.json` for audit and validation - **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` reads both design tokens and layout strategies diff --git a/.claude/commands/workflow/ui-design/explore-auto.md b/.claude/commands/workflow/ui-design/explore-auto.md index c274aac3..98e0d6f6 100644 --- a/.claude/commands/workflow/ui-design/explore-auto.md +++ b/.claude/commands/workflow/ui-design/explore-auto.md @@ -112,13 +112,12 @@ STORE: style_variants, layout_variants run_id = "run-$(date +%Y%m%d-%H%M%S)" IF --session: - base_path = ".workflow/WFS-{session_id}/runs/${run_id}" + base_path = ".workflow/WFS-{session_id}/design-${run_id}" ELSE: - session_id = "design-session-$(date +%Y%m%d-%H%M%S)" - base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}" + base_path = ".workflow/.design/${run_id}" # Create directories -Bash(mkdir -p "${base_path}/.design/{style-extraction,style-consolidation,prototypes}") +Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}") # Initialize metadata Write({base_path}/.run-metadata.json): { @@ -136,12 +135,6 @@ Write({base_path}/.run-metadata.json): { "status": "in_progress" } -# Update "latest" symlink (Windows-compatible) -IF --session: - Bash(cd ".workflow/WFS-{session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}") -ELSE: - Bash(cd ".workflow/.scratchpad/${session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}") - STORE: run_id, base_path ``` @@ -407,7 +400,7 @@ STORE: exploration_mode = exploration_mode # "page" or "component" ```bash images_flag = --images present ? "--images \"{image_glob}\"" : "" prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : "" -run_base_flag = "--base-path \"{base_path}/.design\"" +run_base_flag = "--base-path \"{base_path}\"" command = "/workflow:ui-design:extract {run_base_flag} {images_flag} {prompt_flag} --variants {style_variants}" SlashCommand(command) @@ -419,15 +412,15 @@ SlashCommand(command) ### Phase 2: Style Consolidation with Separation **Command**: ```bash -run_base_flag = "--base-path \"{base_path}/.design\"" +run_base_flag = "--base-path \"{base_path}\"" # Use count-based parameter with --keep-separate for matrix mode command = "/workflow:ui-design:consolidate {run_base_flag} --variants {style_variants} --keep-separate" SlashCommand(command) ``` **Result**: Generates `style_variants` independent design systems: -- `.design/style-consolidation/style-1/design-tokens.json` -- `.design/style-consolidation/style-{N}/design-tokens.json` +- `style-consolidation/style-1/design-tokens.json` +- `style-consolidation/style-{N}/design-tokens.json` **Auto-Continue**: On completion β†’ Phase 3 @@ -436,7 +429,7 @@ SlashCommand(command) ### Phase 3: Matrix UI Generation (Mode-Aware) **Command**: ```bash -run_base_flag = "--base-path \"{base_path}/.design\"" +run_base_flag = "--base-path \"{base_path}\"" IF exploration_mode == "page": # Page Mode: Generate full pages @@ -620,11 +613,11 @@ Phase 4 - Design Update: Brainstorming artifacts updated {IF batch-plan: Phase 5 - Task Generation: {task_count} implementation tasks created} πŸ“‚ Run Output: {base_path}/ - β”œβ”€β”€ .design/style-consolidation/ ({style_variants} design systems) - β”œβ”€β”€ .design/prototypes/ ({total_prototypes} HTML/CSS files) - └── .run-metadata.json (run configuration) + β”œβ”€β”€ style-consolidation/ ({style_variants} design systems) + β”œβ”€β”€ prototypes/ ({total_prototypes} HTML/CSS files) + └── .run-metadata.json (run configuration) -🌐 Interactive Preview: {base_path}/.design/prototypes/compare.html +🌐 Interactive Preview: {base_path}/prototypes/compare.html - {style_variants}Γ—{layout_variants} matrix view with synchronized scrolling - Zoom controls and fullscreen mode - Selection export for implementation @@ -659,11 +652,11 @@ Phase 3 - Matrix Generation: {style_variants}Γ—{layout_variants}Γ—{component_cou Phase 4 - Design Update: Brainstorming artifacts updated πŸ“‚ Run Output: {base_path}/ - β”œβ”€β”€ .design/style-consolidation/ ({style_variants} design systems) - β”œβ”€β”€ .design/prototypes/ ({total_prototypes} component HTML/CSS files) - └── .run-metadata.json (run configuration) + β”œβ”€β”€ style-consolidation/ ({style_variants} design systems) + β”œβ”€β”€ prototypes/ ({total_prototypes} component HTML/CSS files) + └── .run-metadata.json (run configuration) -🌐 Interactive Preview: {base_path}/.design/prototypes/compare.html +🌐 Interactive Preview: {base_path}/prototypes/compare.html - {style_variants}Γ—{layout_variants} component matrix view - Isolated component rendering (minimal wrapper) - Side-by-side comparison for design decisions diff --git a/.claude/commands/workflow/ui-design/extract.md b/.claude/commands/workflow/ui-design/extract.md index 3caf5593..f8427024 100644 --- a/.claude/commands/workflow/ui-design/extract.md +++ b/.claude/commands/workflow/ui-design/extract.md @@ -37,15 +37,16 @@ ELSE IF --prompt: ELSE: ERROR: "Must provide --images or --prompt" -# Detect session mode +# Detect session mode and generate run ID +run_id = "run-" + timestamp() + IF --session: session_mode = "integrated" session_id = {provided_session} - base_path = ".workflow/WFS-{session_id}/" + base_path = ".workflow/WFS-{session_id}/design-{run_id}/" ELSE: session_mode = "standalone" - session_id = "design-session-" + timestamp() - base_path = ".workflow/.scratchpad/{session_id}/" + base_path = ".workflow/.design/{run_id}/" # Set variant count variants_count = --variants provided ? {count} : 1 @@ -67,16 +68,55 @@ IF input_mode IN ["text", "hybrid"]: prompt_guidance = {--prompt value} # Create output directory -CREATE: {base_path}/.design/style-extraction/ +CREATE: {base_path}/style-extraction/ ``` -### Phase 2: Unified Style Analysis (Claude) +### Phase 1.5: Design Trend Research (Exa MCP) + +```bash +# Step 1: Load project context to inform search queries +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" + +# Step 2: Search for design trends using Exa MCP +REPORT: "πŸ” Researching modern design trends and color theory..." + +# 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}" +] + +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" + ) + +REPORT: "βœ… Design research complete. Found trends for: colors, typography, layout, accessibility" +``` + +### Phase 2: Unified Style Analysis (Claude with Design Trends) This is a single-pass analysis that replaces all external tool calls. **Analysis Prompt Template**: ``` -Analyze the following design references and generate {variants_count} distinct design style proposals. +Analyze the following design references and generate {variants_count} distinct design style proposals informed by current design trends. INPUT MODE: {input_mode} @@ -90,11 +130,28 @@ TEXT GUIDANCE: "{prompt_guidance}" Use this to guide the aesthetic direction and feature requirements {ENDIF} +DESIGN TRENDS RESEARCH (from web, 2024-2025): + +COLOR TRENDS: +{design_trends.colors} + +TYPOGRAPHY TRENDS: +{design_trends.typography} + +LAYOUT PATTERNS: +{design_trends.layout} + +ACCESSIBILITY GUIDELINES: +{design_trends.accessibility} + TASK: Generate {variants_count} design style variants that: 1. Each have a distinct visual identity and design philosophy -2. Use OKLCH color space for all color values -3. Include complete, production-ready design token proposals -4. Are semantically organized (brand, surface, semantic colors) +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 OUTPUT FORMAT: JSON matching this exact structure: { @@ -143,11 +200,15 @@ OUTPUT FORMAT: JSON matching this exact structure: 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 - 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) +- 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 ``` ### Phase 3: Parse & Write Output @@ -158,7 +219,7 @@ style_cards_data = parse_json(claude_response) # Write single output file Write({ - file_path: "{base_path}/.design/style-extraction/style-cards.json", + file_path: "{base_path}/style-extraction/style-cards.json", content: style_cards_data }) ``` @@ -169,6 +230,7 @@ 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"} ] @@ -186,7 +248,7 @@ Input mode: {input_mode} Generated {variants_count} style variant(s): {FOR each card: - {card.name} ({card.id})} -πŸ“‚ Output: {base_path}/.design/style-extraction/style-cards.json +πŸ“‚ Output: {base_path}/style-extraction/style-cards.json Next: /workflow:ui-design:consolidate --session {session_id} --variants {variants_count} @@ -196,7 +258,12 @@ Note: When called from /workflow:ui-design:auto, consolidation is triggered auto ## Output Structure ``` -.workflow/WFS-{session}/.design/style-extraction/ +.workflow/WFS-{session}/design-{run_id}/style-extraction/ +└── style-cards.json # Single comprehensive output + +OR (standalone mode): + +.workflow/.design/{run_id}/style-extraction/ └── style-cards.json # Single comprehensive output ``` @@ -569,32 +636,45 @@ Complete structure with example values: ## Key Features -1. **Zero External Dependencies** - - No `gemini-wrapper`, no `codex` - pure Claude synthesis - - Single-pass comprehensive analysis +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 -2. **Streamlined Output** +2. **Zero External Dependencies for Analysis** + - No `gemini-wrapper`, no `codex` for style synthesis - pure Claude + - Single-pass comprehensive analysis with trend integration + +3. **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 -3. **Flexible Input Modes** +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 -4. **Reproducible Structure** +5. **Context-Aware Research** + - Extracts design keywords from user prompts (e.g., "minimalist", "Linear.app") + - Considers project type from brainstorming artifacts + - Customizes search queries based on project context + +6. **Reproducible Structure** - Same inputs = same output structure - Deterministic JSON schema - - Content may vary based on Claude model version + - Content informed by current design trends -5. **Production-Ready Tokens** +7. **Production-Ready Tokens** - Complete design system proposals per variant - OKLCH color format for accessibility - Semantic naming conventions - - WCAG AA accessibility considerations + - WCAG AA accessibility considerations from latest guidelines + - Modern typography trends (variable fonts, system stacks) -6. **Workflow Integration** +8. **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 diff --git a/.claude/commands/workflow/ui-design/generate.md b/.claude/commands/workflow/ui-design/generate.md index eb7cbade..ee3cc6c2 100644 --- a/.claude/commands/workflow/ui-design/generate.md +++ b/.claude/commands/workflow/ui-design/generate.md @@ -2,11 +2,11 @@ name: generate description: Generate UI prototypes in matrix mode (style Γ— layout combinations) usage: /workflow:ui-design:generate [--pages ""] [--base-path ] [--session ] [--style-variants ] [--layout-variants ] -argument-hint: "[--pages \"dashboard,auth\"] [--base-path \".workflow/WFS-xxx/runs/run-xxx/.design\"] [--style-variants 3] [--layout-variants 3]" +argument-hint: "[--pages \"dashboard,auth\"] [--base-path \".workflow/WFS-xxx/design-run-xxx\"] [--style-variants 3] [--layout-variants 3]" examples: - - /workflow:ui-design:generate --base-path ".workflow/WFS-auth/runs/run-xxx/.design" --pages "dashboard,settings" --style-variants 3 --layout-variants 3 + - /workflow:ui-design:generate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --pages "dashboard,settings" --style-variants 3 --layout-variants 3 - /workflow:ui-design:generate --session WFS-auth --pages "home,pricing" --style-variants 2 --layout-variants 2 - - /workflow:ui-design:generate --base-path "./design-session-xxx/.design" --style-variants 3 --layout-variants 3 + - /workflow:ui-design:generate --base-path "./.workflow/.design/run-20250109-150533" --style-variants 3 --layout-variants 3 allowed-tools: TodoWrite(*), Read(*), Write(*), Task(conceptual-planning-agent), Bash(*) --- @@ -24,6 +24,38 @@ 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 @@ -35,12 +67,12 @@ ELSE IF --session provided: ELSE: base_path = find_latest_design_session(".workflow/.scratchpad/") -# 2. Determine variant counts +# 2. Determine style variant count (layout_variants already loaded in Phase 0) style_variants = --style-variants OR 3 # Default to 3 -layout_variants = --layout-variants OR 3 # Default to 3 VALIDATE: 1 <= style_variants <= 5 -VALIDATE: 1 <= layout_variants <= 5 + +# Note: layout_variants is loaded from layout-strategies.json in Phase 0 # 3. Enhanced page list parsing page_list = [] @@ -85,14 +117,62 @@ 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 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. -- **Layer 1**: Generate `L Γ— P` layout templates (HTML structure + structural CSS) +- **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 -#### Phase 2a: Layout Template Generation +#### Phase 2a: Layout Template Generation (Research-Informed) Generate style-agnostic layout templates for each `{page} Γ— {layout}` combination. Total agent tasks: `layout_variants Γ— len(page_list)` @@ -108,7 +188,7 @@ FOR layout_id IN range(1, layout_variants + 1): Task(conceptual-planning-agent): " [UI_LAYOUT_TEMPLATE_GENERATION] - Generate a **style-agnostic** layout template for a specific page and layout strategy. + Generate a **style-agnostic** layout template for a specific page and layout strategy, informed by modern web development best practices. ## Context LAYOUT_ID: {layout_id} @@ -116,8 +196,25 @@ FOR layout_id IN range(1, layout_variants + 1): BASE_PATH: {base_path} {IF --session: - Requirements: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md} + ## 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: + Generate TWO files that work together as a reusable template, incorporating insights from the implementation research above: **File 1**: `{page}-layout-{layout_id}.html` - Semantic HTML5 structure WITHOUT any style-specific values @@ -137,27 +234,13 @@ FOR layout_id IN range(1, layout_variants + 1): - Mobile-first responsive design using token-based breakpoints ## Layout Diversity Strategy - Apply this strategy CONSISTENTLY to all styles: + Apply the following strategy from the planned layout strategies (loaded from layout-strategies.json): - {IF layout_id == 1} - **Layout 1: Classic Hierarchy** - - Traditional F-pattern reading flow - - Top navigation with sidebar - - Card-based content sections - {ELSE IF layout_id == 2} - **Layout 2: Modern Asymmetric** - - Z-pattern visual flow - - Split-screen hero sections - - Grid-based modular content - {ELSE IF layout_id == 3} - **Layout 3: Minimal Focus** - - Centered single-column content - - Floating navigation - - Generous whitespace and breathing room - {ELSE} - **Layout {layout_id}: Custom Variant** - - Develop a unique and consistent layout structure different from the standard three - {ENDIF} + **Layout ID**: {layout_id} + **Name**: {layout_strategies.strategies[layout_id - 1].name} + **Description**: {layout_strategies.strategies[layout_id - 1].description} + + Apply this strategy CONSISTENTLY to all styles. ## Token Usage Requirements (STRICT) - All colors: var(--color-brand-primary), var(--color-surface-background), etc. @@ -165,17 +248,19 @@ FOR layout_id IN range(1, layout_variants + 1): - All typography: var(--font-family-heading), var(--font-size-lg), etc. - NO hardcoded values allowed - ## HTML Requirements + ## HTML Requirements (Apply Modern Best Practices from Research) - Semantic HTML5 elements (
,