feat: integrate Exa MCP for design trend research in UI workflow

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 <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-10-09 18:04:37 +08:00
parent c7e2d6f82f
commit 20c75c0060
8 changed files with 1466 additions and 480 deletions

View File

@@ -1,39 +1,46 @@
---
name: consolidate
description: Consolidate style variants into unified or separate design systems
usage: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--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 <path>] [--session <id>] [--variants <count>] [--keep-separate] [--layout-variants <count>]
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