catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

Refactor documentation for UI Design Workflow (v4.2.1): Optimize explore-auto and imitate-auto commands, enhance clarity and maintainability, and reduce file sizes while preserving functionality. Remove CHANGELOG-v4.2.0.md as it is no longer needed. Update README and README_CN to reflect new version and features.

Browse Source
This commit is contained in:
catlog22
2025-10-09 15:51:23 +08:00
parent 561a04c193
commit c7e2d6f82f
12 changed files with 1611 additions and 2103 deletions
Download Patch File Download Diff File Expand all files Collapse all files

382
.claude/commands/workflow/ui-design/consolidate.md
View File

@@ -13,26 +13,26 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*)
# Style Consolidation Command
## Overview
Consolidate user-selected style variants into a unified, production-ready design system using Claude's native synthesis capabilities. Merges token proposals from multiple style cards into a cohesive design language.
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).
## Core Philosophy
- **Claude-Native**: 100% Claude-driven consolidation, no external tools
- **Token Merging**: Combines `proposed_tokens` from selected variants
- **Intelligent Synthesis**: Resolves conflicts, ensures consistency
- **Production-Ready**: Complete design system with documentation
- **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
```bash
# Determine base path
IF --base-path provided:
base_path = {provided_base_path} # e.g., ".workflow/WFS-xxx/runs/run-xxx/.design"
base_path = {provided_base_path}
ELSE IF --session provided:
session_id = {provided_session}
base_path = ".workflow/WFS-{session_id}/latest/.design" # Use latest run
base_path = ".workflow/WFS-{session}/latest/.design"
ELSE:
# Standalone mode: search for most recent design-session in scratchpad
base_path = find_latest_design_session(".workflow/.scratchpad/")
# Verify extraction output exists
@@ -44,14 +44,14 @@ style_cards = Read(style_cards_path)
total_variants = len(style_cards.style_cards)
```
### Phase 2: Variant Selection (Count-Based)
### Phase 2: Variant Selection & Mode Determination
```bash
# Determine how many variants to consolidate
IF --variants provided:
variants_count = {provided_count}
VALIDATE: 1 <= variants_count <= total_variants
ELSE:
# Default to all variants
variants_count = total_variants
# Select first N variants
@@ -61,11 +61,14 @@ VERIFY: selected_variants.length > 0
# Determine consolidation mode
IF --keep-separate provided:
consolidation_mode = "separate" # Generate N independent design systems
REPORT: "Mode: Separate - generating {variants_count} independent design systems"
ELSE:
consolidation_mode = "unified" # Merge into 1 design system
consolidation_mode = "unified" # Merge into 1 design system
REPORT: "Mode: Unified - merging {variants_count} variants into one design system"
```
### Phase 3: Load Design Context (Optional)
```bash
# Load brainstorming context if available
design_context = ""
@@ -80,6 +83,7 @@ ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md):
**Route based on consolidation_mode**:
#### Mode A: Unified Consolidation (Default)
Merges all style variants into a single, cohesive design system.
**Synthesis Prompt Template**:
@@ -111,54 +115,32 @@ TASK: Consolidate these {selected_variants.length} style variant(s) into a singl
CONSOLIDATION RULES:
1. **Merge Token Proposals**: Combine all `proposed_tokens` into one unified system
2. **Resolve Conflicts**: When variants disagree (e.g., different primary colors), choose the most appropriate value or create a balanced compromise
2. **Resolve Conflicts**: When variants disagree, choose the most appropriate value or create a balanced compromise
3. **Maintain Completeness**: Ensure all token categories are present (colors, typography, spacing, etc.)
4. **Semantic Naming**: Use clear, semantic names (e.g., "brand-primary" not "color-1")
5. **Accessibility**: Validate WCAG AA contrast ratios (4.5:1 text, 3:1 UI)
6. **OKLCH Format**: All colors must use oklch(L C H / A) format
7. **Design Philosophy**: Synthesize a unified philosophy statement from variant descriptions
OUTPUT: Generate the following files as JSON/Markdown:
OUTPUT: Generate the following files:
FILE 1: design-tokens.json
{
"colors": {
"brand": {
"primary": "oklch(...)",
"secondary": "oklch(...)",
"accent": "oklch(...)"
},
"surface": {
"background": "oklch(...)",
"elevated": "oklch(...)",
"overlay": "oklch(...)"
},
"semantic": {
"success": "oklch(...)",
"warning": "oklch(...)",
"error": "oklch(...)",
"info": "oklch(...)"
},
"text": {
"primary": "oklch(...)",
"secondary": "oklch(...)",
"tertiary": "oklch(...)",
"inverse": "oklch(...)"
},
"border": {
"default": "oklch(...)",
"strong": "oklch(...)",
"subtle": "oklch(...)"
}
"brand": { "primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)" },
"surface": { "background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)" },
"semantic": { "success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)" },
"text": { "primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)" },
"border": { "default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)" }
},
"typography": {
"font_family": { "heading": "...", "body": "...", "mono": "..." },
"font_size": { "xs": "...", ..., "4xl": "..." },
"font_weight": { "normal": "...", "medium": "...", "semibold": "...", "bold": "..." },
"line_height": { "tight": "...", "normal": "...", "relaxed": "..." },
"letter_spacing": { "tight": "...", "normal": "...", "wide": "..." }
"font_size": { "xs": "...", "sm": "...", "base": "...", "lg": "...", "xl": "...", "2xl": "...", "3xl": "...", "4xl": "..." },
"font_weight": { "normal": "400", "medium": "500", "semibold": "600", "bold": "700" },
"line_height": { "tight": "1.25", "normal": "1.5", "relaxed": "1.75" },
"letter_spacing": { "tight": "-0.025em", "normal": "0", "wide": "0.025em" }
},
"spacing": { "0": "0", "1": "0.25rem", ..., "24": "6rem" },
"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" }
@@ -176,43 +158,15 @@ FILE 2: style-guide.md
- **Secondary**: {value} - {usage description}
- **Accent**: {value} - {usage description}
### Surface Colors
{List all surface colors with usage}
### Semantic Colors
{List semantic colors with accessibility notes}
### Text Colors
{List text colors with contrast ratios}
### Surface Colors, Semantic Colors, Text Colors, Border Colors
{List all with usage and accessibility notes}
## Typography
### Font Families
{List font families with fallbacks}
### Font Families, Type Scale, Usage Examples
{Complete typography documentation}
### Type Scale
{Show scale with examples}
### Usage Examples
```css
.heading-primary {
font-family: var(--font-family-heading);
font-size: var(--font-size-3xl);
font-weight: var(--font-weight-bold);
}
```
## Spacing System
{Describe spacing scale and usage patterns}
## Component Guidelines
### Buttons
{Token-based button styling examples}
### Cards
{Token-based card styling examples}
### Forms
{Token-based form styling examples}
## Spacing System, Component Guidelines
{Spacing patterns and component token examples}
## Accessibility
- All text meets WCAG AA (4.5:1 minimum)
@@ -223,34 +177,13 @@ FILE 3: tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
brand: {
primary: '{value}',
secondary: '{value}',
accent: '{value}'
},
// ... all color tokens
},
fontFamily: {
heading: [{fonts}],
body: [{fonts}],
mono: [{fonts}]
},
fontSize: {
// ... all size tokens
},
spacing: {
// ... all spacing tokens
},
borderRadius: {
// ... all radius tokens
},
boxShadow: {
// ... all shadow tokens
},
screens: {
// ... all breakpoint tokens
}
colors: { brand: { primary: '{value}', ... }, ... },
fontFamily: { heading: [{fonts}], body: [{fonts}], mono: [{fonts}] },
fontSize: { ... },
spacing: { ... },
borderRadius: { ... },
boxShadow: { ... },
screens: { ... }
}
}
}
@@ -261,22 +194,10 @@ FILE 4: validation-report.json
"consolidated_variants": {variant_ids},
"timestamp": "{ISO timestamp}",
"validation_results": {
"colors": {
"total": {count},
"wcag_aa_compliant": {count},
"warnings": [{any contrast issues}]
},
"typography": {
"font_families": {count},
"scale_sizes": {count}
},
"spacing": {
"scale_values": {count}
},
"accessibility": {
"status": "pass|warnings",
"issues": [{list any issues}]
},
"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}],
@@ -301,43 +222,117 @@ Provide each file's content in clearly labeled sections:
{JSON content}
```
### Phase 5: Parse & Write Output Files
```bash
# Parse Claude's response into separate files
CREATE: {base_path}/.design/style-consolidation/
**Output Location**: `{base_path}/style-consolidation/`
# Extract and write each file
parsed_output = parse_claude_response(claude_response)
---
Write({
file_path: "{base_path}/.design/style-consolidation/design-tokens.json",
content: parsed_output.design_tokens
})
#### Mode B: Separate Consolidation (--keep-separate)
Write({
file_path: "{base_path}/.design/style-consolidation/style-guide.md",
content: parsed_output.style_guide
})
Generates N independent design systems, each refining one style variant into a complete production-ready system.
Write({
file_path: "{base_path}/.design/style-consolidation/tailwind.config.js",
content: parsed_output.tailwind_config
})
**For each variant, use this Synthesis Prompt Template**:
```
Create a production-ready design system for the following style variant.
Write({
file_path: "{base_path}/.design/style-consolidation/validation-report.json",
content: parsed_output.validation_report
})
SESSION: {session_id}
VARIANT: {variant.id}
VARIANT DATA:
Name: {variant.name}
Description: {variant.description}
Design Philosophy: {variant.design_philosophy}
Proposed Tokens:
{JSON.stringify(variant.proposed_tokens, null, 2)}
{IF design_context:
DESIGN CONTEXT (from brainstorming):
{design_context}
}
TASK: Refine this style variant into a complete, production-ready design system.
REFINEMENT RULES:
1. **Complete Token Coverage**: Ensure all categories are present (colors, typography, spacing, etc.)
2. **Fill Gaps**: If any tokens are missing, generate appropriate values based on the variant's philosophy
3. **Maintain Style Identity**: Preserve the unique characteristics of this variant
4. **Semantic Naming**: Use clear, semantic names (e.g., "brand-primary" not "color-1")
5. **Accessibility**: Validate WCAG AA contrast ratios (4.5:1 text, 3:1 UI)
6. **OKLCH Format**: All colors must use oklch(L C H / A) format
7. **Design Philosophy**: Expand and articulate the variant's design philosophy
OUTPUT: Generate the same 4 files as unified mode (design-tokens.json, style-guide.md, tailwind.config.js, validation-report.json)
RESPONSE FORMAT:
Provide each file's content in clearly labeled sections:
===== design-tokens.json =====
{JSON content}
===== style-guide.md =====
{Markdown content}
===== tailwind.config.js =====
{JavaScript content}
===== validation-report.json =====
{JSON content}
```
### Phase 6: TodoWrite & Completion
**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
```bash
# Parse each variant's response
FOR variant_id IN range(1, variants_count + 1):
CREATE: {base_path}/style-consolidation/style-{variant_id}/
parsed_output = parse_claude_response(claude_responses[variant_id - 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)
```
### Phase 6: Completion
```javascript
TodoWrite({
todos: [
{content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"},
{content: "Select and validate variant IDs", status: "completed", activeForm: "Selecting variants"},
{content: "Select variants and determine mode", status: "completed", activeForm: "Selecting variants"},
{content: "Load design context from brainstorming", status: "completed", activeForm: "Loading context"},
{content: "Synthesize unified design system with Claude", status: "completed", activeForm: "Synthesizing design system"},
{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"}
]
});
@@ -347,37 +342,67 @@ TodoWrite({
```
✅ Style consolidation complete for session: {session_id}
Mode: {consolidation_mode}
Consolidated {selected_variants.length} variant(s):
{FOR each variant: - {variant.name} ({variant.id})}
{IF unified mode:
Validation Summary:
- Colors: {total_colors} (WCAG AA: {compliant_count}/{total_colors})
- Typography: {scale_count} sizes
- Spacing: {scale_count} values
- Accessibility: {status}
📂 Output: {base_path}/.design/style-consolidation/
├── design-tokens.json (Final token definitions)
├── style-guide.md (Design system documentation)
├── tailwind.config.js (Tailwind configuration)
└── validation-report.json (Validation audit)
📂 Output: {base_path}/style-consolidation/
├── design-tokens.json
├── style-guide.md
├── tailwind.config.js
└── validation-report.json
}
Next: /workflow:ui-design:generate --session {session_id} --pages "dashboard,auth"
{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-2/ (same structure)
└── style-{variants_count}/ (same structure)
}
Next: /workflow:ui-design:generate --session {session_id} {IF separate: --style-variants {variants_count}} --pages "dashboard,auth"
Note: When called from /workflow:ui-design:auto, UI generation is triggered automatically.
```
## Output Structure
### Unified Mode
```
.workflow/WFS-{session}/.design/style-consolidation/
├── design-tokens.json # Final validated CSS tokens
├── style-guide.md # Comprehensive design system documentation
{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
```
### design-tokens.json Format
### 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)
```
## design-tokens.json Format
Complete token structure with OKLCH colors and semantic naming:
```json
{
"colors": {
@@ -482,20 +507,49 @@ Note: When called from /workflow:ui-design:auto, UI generation is triggered auto
```
## Error Handling
- **No style cards found**: Report error, suggest running `/workflow:ui-design:extract` first
- **Invalid variant IDs**: List available IDs, auto-select all if called from auto workflow
- **Invalid variant count**: List available count, auto-select all if called from auto workflow
- **Parsing errors**: Retry with stricter format instructions
- **Validation warnings**: Report but continue (non-blocking)
- **Missing categories**: Claude will fill gaps based on design philosophy
## Key Improvements Over Previous Version
## Key Features
1. **Zero External Dependencies**: No `gemini-wrapper`, no `codex` - pure Claude
2. **Direct Token Merging**: Reads `proposed_tokens` from style cards directly
3. **Single-Pass Synthesis**: One comprehensive prompt generates all outputs
4. **Reproducible**: Deterministic structure with clear consolidation rules
5. **Streamlined**: `Load → Synthesize → Write` (3 steps vs 7+ previously)
1. **Zero External Dependencies**
- No `gemini-wrapper`, no `codex` - pure Claude synthesis
- 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**
- Reads `proposed_tokens` from style cards directly
- Intelligent conflict resolution with clear rules
4. **Complete Design System Output**
- design-tokens.json (CSS tokens)
- style-guide.md (documentation)
- tailwind.config.js (framework integration)
- validation-report.json (quality audit)
5. **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)
- Reproducible with deterministic structure
- Context-aware (integrates brainstorming artifacts)
## Integration Points
- **Input**: `style-cards.json` from `/workflow:ui-design:extract` (with `proposed_tokens`)
- **Output**: `design-tokens.json` for `/workflow:ui-design:generate`
- **Output**:
- Unified: `style-consolidation/design-tokens.json` for `/workflow:ui-design:generate`
- Separate: `style-consolidation/style-{n}/design-tokens.json` for matrix mode generation
- **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md`
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow

682
.claude/commands/workflow/ui-design/explore-auto.md
View File

@@ -1,66 +1,75 @@
---
name: explore-auto
description: Exploratory UI design workflow - Generate and compare multiple style × layout combinations (3×3 matrix exploration)
usage: /workflow:ui-design:explore-auto [--prompt "<desc>"] [--images "<glob>"] [--pages "<list>"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]
argument-hint: "[--prompt \"Modern SaaS with 3 styles\"] [--images \"refs/*.png\"] [--pages \"dashboard,auth\"] [--session WFS-xxx] [--style-variants 3] [--layout-variants 3]"
description: Exploratory UI design workflow - Generate and compare multiple style × layout combinations for pages OR components (3×3 matrix exploration)
usage: /workflow:ui-design:explore-auto [--prompt "<desc>"] [--images "<glob>"] [--pages "<list>" | --components "<list>"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]
argument-hint: "[--prompt \"Modern SaaS with 3 styles\"] [--images \"refs/*.png\"] [--pages \"dashboard,auth\" | --components \"navbar,hero,card\"] [--session WFS-xxx] [--style-variants 3] [--layout-variants 3]"
examples:
- /workflow:ui-design:explore-auto --prompt "Generate 3 style variants for modern blog: home, article, author"
- /workflow:ui-design:explore-auto --prompt "SaaS dashboard and settings with 2 layout options"
- /workflow:ui-design:explore-auto --images "refs/*.png" --prompt "E-commerce: home, product, cart" --style-variants 3 --layout-variants 3
- /workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png"
- /workflow:ui-design:explore-auto --components "navbar,hero" --prompt "Compare 3 navigation bar designs" --style-variants 3 --layout-variants 2
- /workflow:ui-design:explore-auto --components "card,form" --images "refs/*.png" --style-variants 2 --layout-variants 3
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
---
# UI Design Auto Workflow Command
## Overview
Fully autonomous UI design workflow: style extraction → consolidation → UI generation → design update → optional batch planning. This command orchestrates the entire design process without user intervention.
## Overview & Execution Model
## Coordinator Role
**Fully autonomous orchestrator**: Executes all phases sequentially, parsing outputs from one phase to construct the inputs for the next. Supports both standard sequential mode and parallel creative mode for generating diverse design variants.
**Fully autonomous orchestrator**: Executes all design phases sequentially from style extraction to design integration, with optional batch planning. Supports two exploration modes:
## Execution Model - Autonomous Workflow
**Exploration Modes**:
- **Page Mode** (default): Generates `style_variants × layout_variants × pages` full-page prototypes
- **Component Mode**: Generates `style_variants × layout_variants × components` isolated component prototypes
This workflow runs **fully autonomously** from start to finish:
**Autonomous Flow**:
1. User triggers: `/workflow:ui-design:explore-auto [params]`
2. Phase 1 (style-extract) → Auto-continues
3. Phase 2 (style-consolidate) → Auto-continues
4. Phase 3 (ui-generate) → Auto-continues with appropriate mode
5. Phase 4 (design-update) → Auto-continues
6. Phase 5 (batch-plan, optional) → Reports completion
1. **User triggers**: `/workflow:ui-design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard,auth" [--batch-plan]`
2. **Phase 1 executes** (style-extract) → Auto-continues
3. **Phase 2 executes** (style-consolidate) → Auto-continues
4. **Phase 3 executes** (ui-generate) → Auto-continues
5. **Phase 4 executes** (design-update) → Auto-continues
6. **Phase 5 executes** (batch-plan, optional) → Reports task files
**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon completion, coordinator constructs next command and executes immediately. No user intervention required.
**Auto-Continue Mechanism**:
- The workflow uses `TodoWrite` to track the state of each phase
- Upon successful completion of a phase, the coordinator immediately constructs and executes the command for the next phase
- This pattern ensures a seamless flow
**Mode Selection**: Determined by `--pages` vs `--components` parameter (mutually exclusive).
## Core Rules
1. **Start Immediately**: First action is `TodoWrite` initialization, second action is Phase 1 command execution
2. **No Preliminary Analysis**: Do not read files or validate before Phase 1 (sub-commands handle their own validation)
3. **Parse Every Output**: Extract required data from each command's output for the next phase
4. **Auto-Continue**: After each phase, automatically proceed to the next without pausing
5. **Track Progress**: Update `TodoWrite` after every phase completion
6. **Default to All**: When selecting variants or prototypes for the next phase, the autonomous workflow defaults to using **all** generated items
1. **Start Immediately**: TodoWrite initialization → Phase 1 execution
2. **No Preliminary Validation**: Sub-commands handle their own validation
3. **Parse & Pass**: Extract data from each output for next phase
4. **Default to All**: When selecting variants/prototypes, use ALL generated items
5. **Track Progress**: Update TodoWrite after each phase
## Parameter Requirements
**Optional Parameters** (all have smart defaults):
- `--pages "<page_list>"`: Pages to generate (if omitted, inferred from prompt/session)
- `--session <session_id>`: Workflow session ID (if omitted, runs in standalone mode)
- `--images "<glob_pattern>"`: Reference image paths (default: `design-refs/*`)
- `--prompt "<description>"`: Text description of design style and pages (supports intelligent parsing)
- `--style-variants <count>`: Number of style variants to generate (default: inferred from prompt or 3, range: 1-5)
- `--layout-variants <count>`: Number of layout variants per style (default: inferred from prompt or 3, range: 1-5)
- `--batch-plan`: Auto-generate implementation tasks after design-update (integrated mode only)
- `--pages "<list>"`: Pages to generate (inferred from prompt/session if omitted) - **Page Mode**
- `--components "<list>"`: Components to generate (inferred from prompt if omitted) - **Component Mode**
- `--session <id>`: Workflow session ID (standalone mode if omitted)
- `--images "<glob>"`: Reference image paths (default: `design-refs/*`)
- `--prompt "<description>"`: Design style and pages/components description
- `--style-variants <count>`: Style variants (default: inferred from prompt or 3, range: 1-5)
- `--layout-variants <count>`: Layout variants per style (default: inferred or 3, range: 1-5)
- `--batch-plan`: Auto-generate implementation tasks after design-update
**Input Source Rules**:
- Must provide at least one of: `--images` or `--prompt`
- Both can be combined for guided style analysis
**Input Rules**:
- Must provide at least one: `--images` or `--prompt`
- Both can be combined for guided analysis
- `--pages` and `--components` are **mutually exclusive**
- Default mode: **Page Mode** if neither specified
**Intelligent Prompt Parsing**:
The workflow extracts variant counts from natural language:
**Supported Component Types**:
- **Navigation**: navbar, header, menu, breadcrumb, tabs, sidebar
- **Content**: hero, card, list, table, grid, timeline
- **Input**: form, search, filter, input-group
- **Feedback**: modal, alert, toast, badge, progress
- **Media**: gallery, carousel, video-player, image-card
- **Other**: footer, pagination, dropdown, tooltip, avatar
**Intelligent Prompt Parsing**: Extracts variant counts from natural language:
- "Generate **3 style variants**" → `--style-variants 3`
- "**2 layout options**" → `--layout-variants 2`
- "Create **4 styles** with **2 layouts each**" → `--style-variants 4 --layout-variants 2`
@@ -68,15 +77,14 @@ The workflow extracts variant counts from natural language:
## Execution Modes
### Matrix Mode (Default and Only)
- Generates `style_variants × layout_variants × pages` prototypes in 3×3 matrix pattern
- **Phase 1 (Style Extraction)**: Generates `style_variants` style options
- **Phase 2 (Style Consolidation)**: Creates `style_variants` independent design systems
- **Phase 3 (Matrix Generation)**: Generates `style_variants × layout_variants` prototypes per page
- This is the only supported mode - focused on systematic design exploration
**Matrix Mode** (default and only):
- Generates `style_variants × layout_variants × pages` prototypes
- **Phase 1**: `style_variants` style options
- **Phase 2**: `style_variants` independent design systems
- **Phase 3**: `style_variants × layout_variants` prototypes per page
### Integrated vs. Standalone Mode
- `--session` flag determines if the workflow is integrated with a larger session or runs standalone
**Integrated vs. Standalone**:
- `--session` flag determines session integration or standalone execution
## 6-Phase Execution
@@ -84,53 +92,36 @@ The workflow extracts variant counts from natural language:
```bash
# Extract variant counts from prompt if not explicitly provided
IF --prompt provided AND (NOT --style-variants OR NOT --layout-variants):
prompt_text = {--prompt value}
# Parse style variants: "3 style variants", "generate 4 styles", etc.
# Parse: "3 style variants", "4 styles", "2 layout options", "3 layouts each"
style_match = regex_search(prompt_text, r"(\d+)\s*(style\s*variants?|styles?)")
IF style_match AND NOT --style-variants:
style_variants = int(style_match.group(1))
ELSE:
style_variants = --style-variants OR 3 # Default to 3
# Parse layout variants: "2 layout options", "3 layouts each", etc.
layout_match = regex_search(prompt_text, r"(\d+)\s*(layout\s*(variants?|options?)|layouts?)")
IF layout_match AND NOT --layout-variants:
layout_variants = int(layout_match.group(1))
ELSE:
layout_variants = --layout-variants OR 3 # Default to 3
style_variants = style_match ? int(match[1]) : (--style-variants OR 3)
layout_variants = layout_match ? int(match[1]) : (--layout-variants OR 3)
ELSE:
style_variants = --style-variants OR 3
layout_variants = --layout-variants OR 3
VALIDATE: 1 <= style_variants <= 5
VALIDATE: 1 <= layout_variants <= 5
STORE: style_variants, layout_variants # For Phase 1 and Phase 3
VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
STORE: style_variants, layout_variants
```
### Phase 0b: Run Initialization & Directory Setup
```bash
# Generate run ID with timestamp
# Generate run ID and determine base path
run_id = "run-$(date +%Y%m%d-%H%M%S)"
# Determine base path
IF --session:
session_id = {provided_session}
base_path = ".workflow/WFS-{session_id}/runs/${run_id}"
ELSE:
# Standalone mode: use scratchpad
session_id = "design-session-$(date +%Y%m%d-%H%M%S)"
base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}"
# Create run directory structure
Bash(mkdir -p "${base_path}/.design/style-extraction")
Bash(mkdir -p "${base_path}/.design/style-consolidation")
Bash(mkdir -p "${base_path}/.design/prototypes")
# Create directories
Bash(mkdir -p "${base_path}/.design/{style-extraction,style-consolidation,prototypes}")
# Initialize run metadata
Write({base_path}/.run-metadata.json):
{
# Initialize metadata
Write({base_path}/.run-metadata.json): {
"run_id": "${run_id}",
"session_id": "${session_id}",
"timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
@@ -149,273 +140,374 @@ Write({base_path}/.run-metadata.json):
IF --session:
Bash(cd ".workflow/WFS-{session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}")
ELSE:
# Standalone mode: create symlink in scratchpad session dir
Bash(cd ".workflow/.scratchpad/${session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}")
STORE: run_id, base_path # Use throughout workflow
STORE: run_id, base_path
```
### Phase 0c: Enhanced Page Inference with Dynamic Analysis
```bash
# Initialize
page_list = []
page_source = "none"
page_structure = null # Store structured analysis results
# Priority 1: Explicit --pages parameter (with enhanced cleaning)
# Priority 1: Explicit --pages parameter
IF --pages provided:
# Enhanced cleaning: tolerate spaces, multiple delimiters
raw_pages = {--pages value}
# Split by comma, semicolon, or Chinese comma, then clean each
# Split by comma/semicolon/Chinese comma, clean and normalize
page_list = split_and_clean(raw_pages, delimiters=[",", ";", "、"])
# Strip whitespace, convert to lowercase, replace spaces with hyphens
page_list = [p.strip().lower().replace(" ", "-") for p in page_list if p.strip()]
page_source = "explicit"
REPORT: "📋 Using explicitly provided pages: {', '.join(page_list)}"
# Priority 2: Dynamic prompt decomposition (using Claude's analysis)
# Priority 2: Dynamic prompt decomposition (Claude analysis)
ELSE IF --prompt provided:
REPORT: "🔍 Analyzing prompt to identify pages..."
# Use main Claude to analyze prompt structure
# Internal Claude analysis
analysis_prompt = """
Analyze the following UI design request and identify all distinct pages/screens needed.
Analyze the UI design request and identify all distinct pages/screens.
User Request: "{prompt_text}"
Request: "{prompt_text}"
Output a JSON object with this structure:
Output JSON:
{
"pages": [
{"name": "page-name", "purpose": "brief description", "priority": "high|medium|low"}
],
"shared_components": ["header", "footer", "sidebar"],
"navigation_structure": {
"primary": ["home", "dashboard"],
"secondary": ["settings", "profile"]
}
"pages": [{"name": "page-name", "purpose": "description", "priority": "high|medium|low"}],
"shared_components": ["header", "footer"],
"navigation_structure": {"primary": ["home"], "secondary": ["settings"]}
}
Rules:
- Normalize page names to be URL-friendly (lowercase, use hyphens, no spaces)
- Consolidate synonyms (e.g., "homepage" → "home", "user-profile" → "profile")
- Identify hierarchical relationships if mentioned
- Prioritize pages based on user intent
- Common page patterns: home, dashboard, settings, profile, login, signup, about, contact
- Normalize to URL-friendly (lowercase, hyphens, no spaces)
- Consolidate synonyms (homepage → home, user-profile → profile)
- Identify hierarchical relationships
- Prioritize by user intent
- Common patterns: home, dashboard, settings, profile, login, signup
"""
# Execute analysis (internal to main Claude, no external tool needed)
page_structure = analyze_prompt_structure(analysis_prompt, prompt_text)
page_list = extract_page_names_from_structure(page_structure)
page_source = "prompt_analysis"
# Display analysis results
IF page_list:
REPORT: "📋 Identified pages from prompt:"
FOR each page IN page_structure.pages:
FOR page IN page_structure.pages:
REPORT: " • {page.name}: {page.purpose} [{page.priority}]"
IF page_structure.shared_components:
REPORT: "🔧 Shared components: {', '.join(page_structure.shared_components)}"
ELSE:
REPORT: "⚠️ No pages could be extracted from the prompt."
REPORT: "🔧 Shared components: {', '.join(shared_components)}"
# Priority 3: Extract from synthesis-specification.md
ELSE IF --session AND exists(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md):
synthesis = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
page_list = extract_pages_from_synthesis(synthesis)
page_source = "synthesis"
REPORT: "📋 Extracted pages from synthesis: {', '.join(page_list)}"
REPORT: "📋 Extracted from synthesis: {', '.join(page_list)}"
# Priority 4: Final fallback - default page
# Priority 4: Fallback default
IF NOT page_list:
page_list = ["home"]
page_source = "default"
REPORT: "⚠️ No pages identified, using default: 'home'"
# Enhanced validation
# Validate page names
validated_pages = []
invalid_pages = []
FOR page IN page_list:
# Clean: strip, lowercase, replace spaces with hyphens
cleaned_page = page.strip().lower().replace(" ", "-")
# Validate: must start with letter/number, can contain letters, numbers, hyphens, underscores
IF regex_match(cleaned_page, r"^[a-z0-9][a-z0-9_-]*$"):
validated_pages.append(cleaned_page)
cleaned = page.strip().lower().replace(" ", "-")
IF regex_match(cleaned, r"^[a-z0-9][a-z0-9_-]*$"):
validated_pages.append(cleaned)
ELSE:
invalid_pages.append(page)
IF invalid_pages:
REPORT: "⚠️ Skipped invalid page names: {', '.join(invalid_pages)}"
REPORT: " Valid format: lowercase, alphanumeric, hyphens, underscores (e.g., 'user-profile', 'dashboard')"
REPORT: "⚠️ Skipped invalid: {', '.join(invalid_pages)}"
IF NOT validated_pages:
validated_pages = ["home"]
REPORT: "⚠️ All page names invalid, using default: 'home'"
REPORT: "⚠️ All invalid, using default: 'home'"
# Interactive confirmation step
# Interactive confirmation
REPORT: ""
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "📌 PAGE LIST CONFIRMATION"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "Source: {page_source}"
REPORT: "Pages to generate ({len(validated_pages)}): {', '.join(validated_pages)}"
REPORT: ""
REPORT: "⏸️ Please confirm or modify the page list:"
REPORT: "Pages ({len(validated_pages)}): {', '.join(validated_pages)}"
REPORT: ""
REPORT: "Options:"
REPORT: " • Type 'continue' or 'yes' to proceed with these pages"
REPORT: " • Type 'pages: page1, page2, page3' to replace the entire list"
REPORT: " • Type 'skip: page-name' to remove specific pages"
REPORT: " • Type 'add: page-name' to add specific pages"
REPORT: ""
REPORT: " • 'continue/yes' - proceed"
REPORT: " • 'pages: page1,page2' - replace list"
REPORT: " • 'skip: page-name' - remove pages"
REPORT: " • 'add: page-name' - add pages"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
# Wait for user input
user_confirmation = WAIT_FOR_USER_INPUT()
user_input = WAIT_FOR_USER_INPUT()
# Process user input
IF user_confirmation MATCHES r"^(continue|yes|ok|proceed)$":
# Process input
IF user_input MATCHES r"^(continue|yes|ok|proceed)$":
REPORT: "✅ Proceeding with: {', '.join(validated_pages)}"
ELSE IF user_confirmation MATCHES r"^pages:\s*(.+)$":
# User provided new page list
new_pages_raw = extract_after_prefix(user_confirmation, "pages:")
new_pages = split_and_clean(new_pages_raw, delimiters=[",", ";", "、"])
ELSE IF user_input MATCHES r"^pages:\s*(.+)$":
new_pages = split_and_clean(extract_after("pages:"), [",", ";"])
validated_pages = [p.strip().lower().replace(" ", "-") for p in new_pages if p.strip()]
REPORT: "✅ Updated page list: {', '.join(validated_pages)}"
ELSE IF user_confirmation MATCHES r"^skip:\s*(.+)$":
# Remove specified pages
pages_to_skip_raw = extract_after_prefix(user_confirmation, "skip:")
pages_to_skip = [p.strip().lower() for p in pages_to_skip_raw.split(",")]
validated_pages = [p for p in validated_pages if p not in pages_to_skip]
REPORT: "✅ Removed pages: {', '.join(pages_to_skip)}"
REPORT: " Final list: {', '.join(validated_pages)}"
ELSE IF user_confirmation MATCHES r"^add:\s*(.+)$":
# Add specified pages
pages_to_add_raw = extract_after_prefix(user_confirmation, "add:")
pages_to_add = [p.strip().lower().replace(" ", "-") for p in pages_to_add_raw.split(",") if p.strip()]
validated_pages.extend(pages_to_add)
# Remove duplicates while preserving order
validated_pages = list(dict.fromkeys(validated_pages))
REPORT: "✅ Added pages: {', '.join(pages_to_add)}"
REPORT: " Final list: {', '.join(validated_pages)}"
REPORT: "✅ Updated: {', '.join(validated_pages)}"
ELSE IF user_input MATCHES r"^skip:\s*(.+)$":
to_skip = [p.strip().lower() for p in extract_after("skip:").split(",")]
validated_pages = [p for p in validated_pages if p not in to_skip]
REPORT: "✅ Removed: {', '.join(to_skip)}, Final: {', '.join(validated_pages)}"
ELSE IF user_input MATCHES r"^add:\s*(.+)$":
to_add = [p.strip().lower().replace(" ", "-") for p in extract_after("add:").split(",") if p.strip()]
validated_pages.extend(to_add)
validated_pages = list(dict.fromkeys(validated_pages)) # Remove duplicates
REPORT: "✅ Added: {', '.join(to_add)}, Final: {', '.join(validated_pages)}"
ELSE:
REPORT: "⚠️ Invalid input format, proceeding with original list: {', '.join(validated_pages)}"
REPORT: "⚠️ Invalid input, proceeding with: {', '.join(validated_pages)}"
# Final verification
IF NOT validated_pages:
validated_pages = ["home"]
REPORT: "⚠️ Empty page list detected, using default: 'home'"
# Store results for subsequent phases
STORE: inferred_page_list = validated_pages # For Phase 3
STORE: page_inference_source = page_source # Track source for metadata
STORE: page_structure_data = page_structure # Save structured data for future use
STORE: inferred_page_list = validated_pages
STORE: page_inference_source = page_source
STORE: page_structure_data = page_structure
STORE: exploration_mode = "page"
```
### Phase 0d: Component Inference (Component Mode Only)
```bash
component_list = []
component_source = "none"
exploration_mode = "page" # Default
# Determine exploration mode
IF --components provided:
exploration_mode = "component"
raw_components = {--components value}
# Split and clean
component_list = split_and_clean(raw_components, delimiters=[",", ";", "、"])
component_list = [c.strip().lower().replace(" ", "-") for c in component_list if c.strip()]
component_source = "explicit"
REPORT: "🧩 Using explicitly provided components: {', '.join(component_list)}"
# Component inference from prompt (if no --pages and no --components)
ELSE IF --prompt provided AND NOT --pages:
REPORT: "🔍 Analyzing prompt to identify components..."
# Internal Claude analysis for components
analysis_prompt = """
Analyze the UI design request and identify component-level design elements.
Request: "{prompt_text}"
Output JSON:
{
"components": [
{"name": "component-type", "purpose": "description", "variants": ["variant1", "variant2"]}
],
"component_context": "page or section where components appear",
"interaction_patterns": ["hover", "click", "scroll"]
}
Component Categories:
- Navigation: navbar, header, menu, breadcrumb, tabs, sidebar
- Content: hero, card, list, table, grid, timeline
- Input: form, search, filter, input-group
- Feedback: modal, alert, toast, badge, progress
- Media: gallery, carousel, video-player, image-card
- Other: footer, pagination, dropdown, tooltip, avatar
Rules:
- Normalize to lowercase with hyphens
- Be specific (e.g., "navbar" not "navigation")
- Include interaction context
"""
component_structure = analyze_prompt_structure(analysis_prompt, prompt_text)
# Check if prompt is component-focused
IF component_structure.components AND len(component_structure.components) > 0:
component_list = extract_component_names_from_structure(component_structure)
component_source = "prompt_analysis"
exploration_mode = "component"
REPORT: "🧩 Identified components from prompt:"
FOR comp IN component_structure.components:
REPORT: " • {comp.name}: {comp.purpose}"
IF component_structure.interaction_patterns:
REPORT: "🎯 Interaction patterns: {', '.join(interaction_patterns)}"
# Validate component names
IF exploration_mode == "component":
validated_components = []
invalid_components = []
FOR comp IN component_list:
cleaned = comp.strip().lower().replace(" ", "-")
IF regex_match(cleaned, r"^[a-z0-9][a-z0-9_-]*$"):
validated_components.append(cleaned)
ELSE:
invalid_components.append(comp)
IF invalid_components:
REPORT: "⚠️ Skipped invalid: {', '.join(invalid_components)}"
IF NOT validated_components:
# Fallback to page mode with default page
exploration_mode = "page"
inferred_page_list = ["home"]
REPORT: "⚠️ No valid components, switching to page mode: 'home'"
ELSE:
# Interactive confirmation for components
REPORT: ""
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "🧩 COMPONENT LIST CONFIRMATION"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "Mode: Component Exploration"
REPORT: "Source: {component_source}"
REPORT: "Components ({len(validated_components)}): {', '.join(validated_components)}"
REPORT: ""
REPORT: "Options:"
REPORT: " • 'continue/yes' - proceed"
REPORT: " • 'components: comp1,comp2' - replace list"
REPORT: " • 'skip: comp-name' - remove components"
REPORT: " • 'add: comp-name' - add components"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
user_input = WAIT_FOR_USER_INPUT()
# Process input
IF user_input MATCHES r"^(continue|yes|ok|proceed)$":
REPORT: "✅ Proceeding with: {', '.join(validated_components)}"
ELSE IF user_input MATCHES r"^components:\s*(.+)$":
new_comps = split_and_clean(extract_after("components:"), [",", ";"])
validated_components = [c.strip().lower().replace(" ", "-") for c in new_comps if c.strip()]
REPORT: "✅ Updated: {', '.join(validated_components)}"
ELSE IF user_input MATCHES r"^skip:\s*(.+)$":
to_skip = [c.strip().lower() for c in extract_after("skip:").split(",")]
validated_components = [c for c in validated_components if c not in to_skip]
REPORT: "✅ Removed: {', '.join(to_skip)}, Final: {', '.join(validated_components)}"
ELSE IF user_input MATCHES r"^add:\s*(.+)$":
to_add = [c.strip().lower().replace(" ", "-") for c in extract_after("add:").split(",") if c.strip()]
validated_components.extend(to_add)
validated_components = list(dict.fromkeys(validated_components)) # Remove duplicates
REPORT: "✅ Added: {', '.join(to_add)}, Final: {', '.join(validated_components)}"
ELSE:
REPORT: "⚠️ Invalid input, proceeding with: {', '.join(validated_components)}"
IF NOT validated_components:
# Fallback to page mode
exploration_mode = "page"
inferred_page_list = ["home"]
REPORT: "⚠️ No components, switching to page mode: 'home'"
STORE: inferred_component_list = validated_components IF exploration_mode == "component" ELSE []
STORE: component_inference_source = component_source
STORE: component_structure_data = component_structure IF exploration_mode == "component" ELSE {}
STORE: exploration_mode = exploration_mode # "page" or "component"
```
### Phase 1: Style Extraction
**Command Construction**:
**Command**:
```bash
images_flag = --images present ? "--images \"{image_glob}\"" : ""
prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : ""
# Use run-scoped base path
run_base_flag = "--base-path \"{base_path}/.design\""
# Use style_variants from Phase 0a
command = "/workflow:ui-design:extract {run_base_flag} {images_flag} {prompt_flag} --variants {style_variants}"
SlashCommand(command=command)
SlashCommand(command)
```
**Auto-Continue**: On completion, proceeds to Phase 2
**Auto-Continue**: On completion → Phase 2
---
### Phase 2: Style Consolidation with Separation (Auto-Triggered)
**Action**: Consolidates each style variant into separate design systems for matrix generation
**Command Construction**:
### Phase 2: Style Consolidation with Separation
**Command**:
```bash
# Use run-scoped base path and keep styles separate
run_base_flag = "--base-path \"{base_path}/.design\""
# Use count-based parameter (automatically uses all style_variants)
# 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)
```
**Command**: `SlashCommand(command=command)`
**Result**: Generates `style_variants` independent design systems:
- `.design/style-consolidation/style-1/design-tokens.json`
- `.design/style-consolidation/style-2/design-tokens.json`
- `.design/style-consolidation/style-3/design-tokens.json`
- `.design/style-consolidation/style-{N}/design-tokens.json`
**Auto-Continue**: On completion, proceeds to Phase 3
**Auto-Continue**: On completion → Phase 3
---
### Phase 3: Matrix UI Generation (Auto-Triggered)
**Action**: Generates `style_variants × layout_variants × pages` prototypes using matrix mode
**Command Construction**:
### Phase 3: Matrix UI Generation (Mode-Aware)
**Command**:
```bash
run_base_flag = "--base-path \"{base_path}/.design\""
# Ensure inferred_page_list is serialized correctly as comma-separated string
# Convert list to string: ['dashboard', 'settings'] → "dashboard,settings"
pages_string = ",".join(inferred_page_list)
IF exploration_mode == "page":
# Page Mode: Generate full pages
pages_string = ",".join(inferred_page_list)
VERIFY: pages_string matches r"^[a-z0-9_-]+(,[a-z0-9_-]+)*$"
# Validate the serialized string format
VERIFY: pages_string matches r"^[a-z0-9_-]+(,[a-z0-9_-]+)*$"
pages_flag = "--pages \"{pages_string}\""
command = "/workflow:ui-design:generate {run_base_flag} {pages_flag} --style-variants {style_variants} --layout-variants {layout_variants}"
pages_flag = "--pages \"{pages_string}\""
total_prototypes = style_variants * layout_variants * len(inferred_page_list)
REPORT: "🚀 Phase 3: Matrix UI Generation (Page Mode)"
REPORT: " Pages: {pages_string}"
REPORT: " Matrix: {style_variants}×{layout_variants}"
REPORT: " Total: {total_prototypes} full-page prototypes"
# Matrix mode is default in generate.md, no mode flag needed
command = "/workflow:ui-design:generate {run_base_flag} {pages_flag} --style-variants {style_variants} --layout-variants {layout_variants}"
ELSE IF exploration_mode == "component":
# Component Mode: Generate isolated components
components_string = ",".join(inferred_component_list)
VERIFY: components_string matches r"^[a-z0-9_-]+(,[a-z0-9_-]+)*$"
# Log command for debugging
REPORT: "🚀 Executing Phase 3: Matrix UI Generation"
REPORT: " Pages: {pages_string}"
REPORT: " Style variants: {style_variants}"
REPORT: " Layout variants: {layout_variants}"
REPORT: " Total prototypes: {style_variants * layout_variants * len(inferred_page_list)}"
components_flag = "--components \"{components_string}\""
command = "/workflow:ui-design:generate {run_base_flag} {components_flag} --style-variants {style_variants} --layout-variants {layout_variants}"
SlashCommand(command=command)
total_prototypes = style_variants * layout_variants * len(inferred_component_list)
REPORT: "🚀 Phase 3: Matrix UI Generation (Component Mode)"
REPORT: " Components: {components_string}"
REPORT: " Matrix: {style_variants}×{layout_variants}"
REPORT: " Total: {total_prototypes} component prototypes"
REPORT: " Context: Components displayed in minimal page wrapper"
SlashCommand(command)
```
**Result**: Generates `style_variants × layout_variants × pages` prototypes:
- File naming: `{page}-style-{s}-layout-{l}.html`
- Total prototypes: `style_variants * layout_variants * len(inferred_page_list)`
- Matrix visualization: `compare.html` with interactive 3×3 grid
**Result**:
- **Page Mode**: `{page}-style-{s}-layout-{l}.html`
- **Component Mode**: `{component}-style-{s}-layout-{l}.html`
- Total: `style_variants × layout_variants × (pages|components)`
- Matrix view: `compare.html` with interactive grid
- Component isolation: Minimal wrapper for focus on component design
**Auto-Continue**: On completion, proceeds to Phase 4
**Auto-Continue**: On completion → Phase 4
---
### Phase 4: Design System Integration (Auto-Triggered)
**Action**: Integrates all generated prototypes and the design system into the brainstorming artifacts
**Command Construction**:
### Phase 4: Design System Integration
**Command**:
```bash
session_flag = --session present ? "--session {session_id}" : ""
# --selected-prototypes is omitted to default to ALL generated prototypes
# Omit --selected-prototypes to use ALL generated prototypes
command = "/workflow:ui-design:update {session_flag}"
SlashCommand(command)
```
**Command**: `SlashCommand(command=command)`
**Auto-Continue**: If `--batch-plan` is present, proceeds to Phase 5. Otherwise, the workflow completes
**Auto-Continue**: If `--batch-plan` present → Phase 5, else complete
---
### Phase 5: Batch Task Generation (Optional, Auto-Triggered)
**Condition**: Only executes if `--batch-plan` flag is present
### Phase 5: Batch Task Generation (Optional)
**Condition**: Only if `--batch-plan` flag present
**Execution**:
```bash
FOR each page IN inferred_page_list:
SlashCommand(command="/workflow:plan --agent \"Implement {page} page based on design system\"")
FOR page IN inferred_page_list:
SlashCommand("/workflow:plan --agent \"Implement {page} page based on design system\"")
```
**Completion**: The workflow is now complete
**Completion**: Workflow complete
## TodoWrite Pattern (Autonomous)
## TodoWrite Pattern
```javascript
// Initialize (before Phase 1)
// Initialize
TodoWrite({todos: [
{"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing style extraction"},
{"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing style consolidation"},
@@ -423,96 +515,107 @@ TodoWrite({todos: [
{"content": "Execute design system integration", "status": "pending", "activeForm": "Executing design system integration"}
]})
// After Phase 1 completes, before Phase 2 starts
TodoWrite({todos: [
{"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
{"content": "Execute style consolidation", "status": "in_progress", "activeForm": "Executing style consolidation"},
// ... rest are pending
]})
// After Phase 2 completes, before Phase 3 starts
TodoWrite({todos: [
{"content": "Execute style extraction", "status": "completed"},
{"content": "Execute style consolidation", "status": "completed", "activeForm": "Executing style consolidation"},
{"content": "Execute UI prototype generation", "status": "in_progress", "activeForm": "Executing UI generation"},
// ... rest are pending
]})
// This pattern continues until all phases are complete
// After each phase: Mark current completed, next in_progress, rest pending
// Phase 1 done → Phase 2 in_progress
// Phase 2 done → Phase 3 in_progress
// ... continues until all completed
```
## Error Handling
- **Phase Execution Failures**: The workflow will halt, keeping the failed phase `in_progress`. It will report the error and provide recovery instructions, suggesting a manual command execution with corrected parameters
- **Default Behavior**: In case of ambiguity (e.g., which variants to select), the system defaults to selecting ALL available items to ensure the workflow can proceed autonomously
- **Phase Failures**: Workflow halts, keeps failed phase `in_progress`, reports error with recovery instructions
- **Ambiguity**: Defaults to ALL available items (variants/prototypes) to ensure autonomous continuation
## Key Improvements Over Previous Version
## Key Features & Workflow Position
1. **Zero External Dependencies**: Pure Claude + agents, no CLI tools
2. **Streamlined Commands**: Removed `--tool` parameter and all CLI tool flags
3. **Consistent Execution**: All sub-commands use unified patterns
4. **Reproducible**: Deterministic flow with clear phase dependencies
5. **Simpler**: Fewer moving parts, easier to understand and debug
**Core Improvements**:
- **Zero External Dependencies**: Pure Claude + agents, no CLI tools
- **Streamlined Commands**: Unified patterns, no tool-specific flags
- **Reproducible Flow**: Deterministic phase dependencies
- **Intelligent Parsing**: Natural language → variant counts, pages
- **Run Isolation**: Each execution in timestamped run directory
## Workflow Position
The workflow acts as the bridge between brainstorming (`synthesis-specification.md`) and planning (`/workflow:plan`), providing this connection in a fully automated fashion with options for deep creative exploration through parallel agents.
**Workflow Bridge**: Connects brainstorming (`synthesis-specification.md`) → design phase → planning (`/workflow:plan`) in fully automated fashion with matrix-based design exploration.
## Example Execution Flows
### Example 1: Default 3×3 Matrix (Prompt Inference)
### Example 1: Default 3×3 Matrix (Page Mode - Prompt Inference)
```bash
/workflow:ui-design:auto --prompt "Modern minimalist blog with home, article, and author pages"
/workflow:ui-design:explore-auto --prompt "Modern minimalist blog with home, article, and author pages"
# Mode: Page
# Inferred: 3 style variants, 3 layout variants (default)
# Executes:
# 1. /workflow:ui-design:extract --base-path ".../run-xxx/.design" --prompt "..." --variants 3
# 2. /workflow:ui-design:consolidate --base-path ".../run-xxx/.design" --variants 3 --keep-separate
# 3. /workflow:ui-design:generate --base-path ".../run-xxx/.design" --pages "home,article,author" --style-variants 3 --layout-variants 3
# 4. /workflow:ui-design:update
# Total: 27 prototypes (3 styles × 3 layouts × 3 pages)
# Pages: home, article, author
# Total: 27 full-page prototypes (3×3×3)
```
### Example 2: Custom 2×2 Matrix with Explicit Parameters
### Example 2: Custom 2×2 Matrix with Session (Page Mode)
```bash
/workflow:ui-design:auto --session WFS-ecommerce --images "refs/*.png" --prompt "E-commerce" --style-variants 2 --layout-variants 2
/workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
# Executes:
# 1. /workflow:ui-design:extract --base-path ".workflow/WFS-ecommerce/runs/run-xxx/.design" --images "refs/*.png" --variants 2
# 2. /workflow:ui-design:consolidate --base-path "..." --variants 2 --keep-separate
# 3. /workflow:ui-design:generate --base-path "..." --pages "{inferred}" --style-variants 2 --layout-variants 2
# 4. /workflow:ui-design:update --session WFS-ecommerce
# Total: 2×2×N prototypes
# Mode: Page
# Executes with session integration
# Total: 2×2×N prototypes (N from inference)
```
### Example 3: Intelligent Parsing with Batch Planning
### Example 3: Component Mode - Navbar Design Comparison
```bash
/workflow:ui-design:auto --session WFS-saas --prompt "Create 4 styles with 2 layouts for SaaS dashboard and settings" --batch-plan
/workflow:ui-design:explore-auto --components "navbar,hero" --prompt "Compare 3 navigation bar designs for SaaS product" --style-variants 3 --layout-variants 2
# Parsed: --style-variants 4, --layout-variants 2
# Executes:
# 1. /workflow:ui-design:extract --variants 4
# 2. /workflow:ui-design:consolidate --variants 4 --keep-separate
# 3. /workflow:ui-design:generate --pages "dashboard,settings" --style-variants 4 --layout-variants 2
# (generates 16 prototypes: 4 styles × 2 layouts × 2 pages)
# 4. /workflow:ui-design:update --session WFS-saas
# 5. /workflow:plan --agent "Implement dashboard page..."
# /workflow:plan --agent "Implement settings page..."
# Mode: Component
# Components: navbar, hero
# Matrix: 3 styles × 2 layouts
# Total: 12 component prototypes (3×2×2)
# Output: navbar-style-1-layout-1.html, navbar-style-1-layout-2.html, ...
```
### Example 4: Component Mode - Card & Form Exploration
```bash
/workflow:ui-design:explore-auto --components "card,form,button" --images "refs/*.png" --style-variants 2 --layout-variants 3
# Mode: Component
# Components: card, form, button
# Matrix: 2 styles × 3 layouts
# Total: 18 component prototypes (2×3×3)
# Context: Each component in minimal wrapper for isolated comparison
```
### Example 5: Intelligent Parsing + Batch Planning (Page Mode)
```bash
/workflow:ui-design:explore-auto --session WFS-saas --prompt "Create 4 styles with 2 layouts for SaaS dashboard and settings" --batch-plan
# Mode: Page
# Parsed: 4 styles, 2 layouts
# Pages: dashboard, settings
# Total: 16 full-page prototypes (4×2×2)
# Auto-generates implementation tasks for each page
```
### Example 6: Component Mode - Prompt-Inferred Components
```bash
/workflow:ui-design:explore-auto --prompt "Design exploration for pricing table and testimonial card components" --style-variants 3 --layout-variants 2
# Mode: Component (auto-detected from prompt)
# Inferred components: pricing-table, testimonial-card
# Matrix: 3 styles × 2 layouts
# Total: 12 component prototypes (3×2×2)
```
## Final Completion Message
**Page Mode**:
```
✅ UI Design Auto Workflow Complete!
✅ UI Design Explore-Auto Workflow Complete! (Page Mode)
Run ID: {run_id}
Session: {session_id or "standalone"}
Mode: Full-Page Exploration
Matrix: {style_variants}×{layout_variants} ({total_prototypes} total prototypes)
Input: {images and/or prompt summary}
Phase 1 - Style Extraction: {style_variants} style variants
Phase 2 - Style Consolidation: {style_variants} independent design systems
Phase 3 - Matrix Generation: {style_variants}×{layout_variants}×{pages_count} = {total_prototypes} prototypes
Phase 3 - Matrix Generation: {style_variants}×{layout_variants}×{pages_count} = {total_prototypes} page prototypes
Phase 4 - Design Update: Brainstorming artifacts updated
{IF batch-plan: Phase 5 - Task Generation: {task_count} implementation tasks created}
@@ -522,18 +625,55 @@ Phase 4 - Design Update: Brainstorming artifacts updated
└── .run-metadata.json (run configuration)
🌐 Interactive Preview: {base_path}/.design/prototypes/compare.html
- 3×3 matrix view with synchronized scrolling
- {style_variants}×{layout_variants} matrix view with synchronized scrolling
- Zoom controls and fullscreen mode
- Selection export for implementation
📄 Pages Explored: {', '.join(inferred_page_list)}
{IF batch-plan:
📋 Implementation Tasks: .workflow/WFS-{session}/.task/
Next: /workflow:execute to begin implementation
}
{ELSE:
Next Steps:
1. Open compare.html to preview all variants
2. Select preferred style×layout combinations
1. Open compare.html to preview all page variants
2. Select preferred style×layout combinations per page
3. Run /workflow:plan to create implementation tasks
}
```
**Component Mode**:
```
✅ UI Design Explore-Auto Workflow Complete! (Component Mode)
Run ID: {run_id}
Session: {session_id or "standalone"}
Mode: Component Exploration
Matrix: {style_variants}×{layout_variants} ({total_prototypes} total component prototypes)
Input: {images and/or prompt summary}
Phase 1 - Style Extraction: {style_variants} style variants
Phase 2 - Style Consolidation: {style_variants} independent design systems
Phase 3 - Matrix Generation: {style_variants}×{layout_variants}×{component_count} = {total_prototypes} component prototypes
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)
🌐 Interactive Preview: {base_path}/.design/prototypes/compare.html
- {style_variants}×{layout_variants} component matrix view
- Isolated component rendering (minimal wrapper)
- Side-by-side comparison for design decisions
- Selection export for implementation
🧩 Components Explored: {', '.join(inferred_component_list)}
Next Steps:
1. Open compare.html to preview all component variants
2. Select preferred style×layout combinations per component
3. Extract selected components for integration into pages
4. Run /workflow:plan with component integration context
```

473
.claude/commands/workflow/ui-design/extract.md
View File

@@ -19,12 +19,13 @@ Extract design style elements from reference images or text prompts using Claude
- **Claude-Native**: 100% Claude-driven analysis, no external tools
- **Single Output**: Only `style-cards.json` with embedded token proposals
- **Sequential Execution**: Generate multiple style variants in one pass
- **Flexible Input**: Images, text prompts, or both
- **Flexible Input**: Images, text prompts, or both (hybrid mode)
- **Reproducible**: Deterministic output structure
## Execution Protocol
### Phase 0: Parameter Detection & Validation
```bash
# Detect input source
IF --images AND --prompt:
@@ -52,6 +53,7 @@ VALIDATE: 1 <= variants_count <= 5
```
### Phase 1: Input Loading & Validation
```bash
# Expand and validate inputs
IF input_mode IN ["image", "hybrid"]:
@@ -69,6 +71,7 @@ CREATE: {base_path}/.design/style-extraction/
```
### Phase 2: Unified Style Analysis (Claude)
This is a single-pass analysis that replaces all external tool calls.
**Analysis Prompt Template**:
@@ -107,6 +110,114 @@ OUTPUT FORMAT: JSON matching this exact structure:
"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"
},
"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", ..., "full": "9999px" },
"shadows": { "sm": "...", "md": "...", "lg": "...", "xl": "..." },
"breakpoints": { "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" }
}
},
// Repeat for variants_count total
]
}
RULES:
- Each variant must be distinct in visual character
- 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)
- Include complete token categories for each variant
```
### Phase 3: Parse & Write Output
```bash
# Parse Claude's JSON response
style_cards_data = parse_json(claude_response)
# Write single output file
Write({
file_path: "{base_path}/.design/style-extraction/style-cards.json",
content: style_cards_data
})
```
### Phase 4: Completion
```javascript
TodoWrite({
todos: [
{content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"},
{content: "Analyze design references with Claude", status: "completed", activeForm: "Analyzing design"},
{content: `Generate ${variants_count} style cards with token proposals`, status: "completed", activeForm: "Generating style cards"}
]
});
```
**Completion Message**:
```
✅ Style extraction complete for session: {session_id}
Input mode: {input_mode}
{IF image mode: Images analyzed: {count}}
{IF prompt mode: Prompt: "{truncated_prompt}"}
Generated {variants_count} style variant(s):
{FOR each card: - {card.name} ({card.id})}
📂 Output: {base_path}/.design/style-extraction/style-cards.json
Next: /workflow:ui-design:consolidate --session {session_id} --variants {variants_count}
Note: When called from /workflow:ui-design:auto, consolidation is triggered automatically.
```
## Output Structure
```
.workflow/WFS-{session}/.design/style-extraction/
└── style-cards.json # Single comprehensive output
```
### style-cards.json Format
Complete structure with example values:
```json
{
"extraction_metadata": {
"session_id": "WFS-xxx or design-session-xxx",
"input_mode": "image|text|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",
"preview": {
"primary": "oklch(0.45 0.20 270 / 1)",
"background": "oklch(0.98 0.01 270 / 1)",
@@ -213,115 +324,285 @@ OUTPUT FORMAT: JSON matching this exact structure:
"2xl": "1536px"
}
}
}
]
}
RULES:
- Each variant must be distinct in visual character
- All colors MUST use OKLCH format: oklch(L C H / A)
- Token structures must be complete and production-ready
- Use semantic naming throughout
- Ensure accessibility (contrast ratios, readable font sizes)
```
### Phase 3: Generate & Write Output
```bash
# Parse Claude's JSON response
style_cards_data = parse_json(claude_response)
# Write single output file
Write({
file_path: "{base_path}/.design/style-extraction/style-cards.json",
content: style_cards_data
})
```
### Phase 4: TodoWrite & Completion
```javascript
TodoWrite({
todos: [
{content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"},
{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"}
]
});
```
**Completion Message**:
```
✅ Style extraction complete for session: {session_id}
Input mode: {input_mode}
{IF image mode: Images analyzed: {count}}
{IF prompt mode: Prompt: "{truncated_prompt}"}
Generated {variants_count} style variant(s):
{FOR each card: - {card.name} ({card.id})}
📂 Output: {base_path}/.design/style-extraction/style-cards.json
Next: /workflow:ui-design:consolidate --session {session_id} --variants "{all_variant_ids}"
Note: When called from /workflow:ui-design:auto, consolidation is triggered automatically.
```
## Output Structure
```
.workflow/WFS-{session}/.design/style-extraction/
└── style-cards.json # Single comprehensive output
```
### style-cards.json Format (Enhanced)
```json
{
"extraction_metadata": {
"session_id": "WFS-xxx or design-session-xxx",
"input_mode": "image|text|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",
"design_philosophy": "Less is more - focus on content clarity and visual breathing room",
"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.45 0.20 270 / 1)",
"background": "oklch(0.98 0.01 270 / 1)",
"font_heading": "Inter, system-ui, sans-serif",
"border_radius": "0.5rem"
"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": { /* complete color system */ },
"typography": { /* complete typography system */ },
"spacing": { /* complete spacing scale */ },
"border_radius": { /* border radius scale */ },
"shadows": { /* shadow system */ },
"breakpoints": { /* responsive breakpoints */ }
"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"
}
}
},
{
"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"
}
}
}
]
}
```
**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
## Error Handling
- **No images found**: Report glob pattern and suggest corrections
- **No images found**: Report glob pattern and suggest corrections (e.g., "Pattern '*.png' matched 0 files in current directory")
- **Invalid prompt**: Require non-empty string for text mode
- **Claude JSON parsing error**: Retry with stricter format instructions
- **Invalid session**: Create standalone session automatically
- **Claude JSON parsing error**: Retry with stricter format instructions and explicit structure requirements
- **Invalid session**: Create standalone session automatically in `.workflow/.scratchpad/`
- **Invalid variant count**: Clamp to 1-5 range and warn user
## Key Improvements Over Previous Version
## Key Features
1. **Zero External Dependencies**: No `gemini-wrapper`, no `codex` - pure Claude
2. **Single Output File**: Eliminates `semantic_style_analysis.json`, `design-tokens.json`, `tailwind-tokens.js` clutter
3. **Complete Token Proposals**: Each style card contains a full design system proposal
4. **Reproducible**: Same inputs = same output structure (content may vary based on Claude model)
5. **Streamlined Flow**: `Input → Analysis → style-cards.json` (3 steps vs 7+ previously)
1. **Zero External Dependencies**
- No `gemini-wrapper`, no `codex` - pure Claude synthesis
- Single-pass comprehensive analysis
2. **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**
- Image-only: Analyze visual references
- Text-only: Generate from descriptions
- Hybrid: Text guides image analysis
4. **Reproducible Structure**
- Same inputs = same output structure
- Deterministic JSON schema
- Content may vary based on Claude model version
5. **Production-Ready Tokens**
- Complete design system proposals per variant
- OKLCH color format for accessibility
- Semantic naming conventions
- WCAG AA accessibility considerations
6. **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
## Integration Points
- **Input**: Reference images (PNG, JPG, WebP) or text prompts
- **Input**: Reference images (PNG, JPG, WebP) via glob patterns, or text prompts
- **Output**: `style-cards.json` for `/workflow:ui-design:consolidate`
- **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md` can guide prompts
- **Context**: Optional brainstorming artifacts (`synthesis-specification.md`, `ui-designer/analysis.md`)
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
- **Next Step**: `/workflow:ui-design:consolidate --session {session_id} --variants {count}` (or `--keep-separate` for matrix mode)

231
.claude/commands/workflow/ui-design/generate.md
View File

@@ -20,117 +20,89 @@ Generate production-ready UI prototypes (HTML/CSS) in `style × layout` matrix m
- **Agent-Driven**: Uses `Task(conceptual-planning-agent)` for parallel generation
- **Token-Driven**: All styles reference per-style design-tokens.json; no hardcoded values
- **Production-Ready**: Semantic HTML5, ARIA attributes, responsive design
- **Template-Based**: Decouples HTML structure from CSS styling for optimal performance
## Execution Protocol
### Phase 1: Path Resolution & Context Loading (Enhanced)
### Phase 1: Path Resolution & Context Loading
```bash
# Determine base path
# 1. Determine base path
IF --base-path provided:
base_path = {provided_base_path} # e.g., ".workflow/WFS-xxx/runs/run-xxx/.design"
base_path = {provided_base_path}
ELSE IF --session provided:
session_id = {provided_session}
base_path = ".workflow/WFS-{session_id}/latest/.design" # Use latest run
base_path = ".workflow/WFS-{session}/latest/.design"
ELSE:
# Standalone mode: search for most recent design-session in scratchpad
base_path = find_latest_design_session(".workflow/.scratchpad/")
# Determine style and layout variant counts
# 2. Determine variant counts
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
# Enhanced page list parsing
# 3. Enhanced page list parsing
page_list = []
page_source = "none"
# Priority 1: Explicit --pages parameter (with robust parsing)
# Priority 1: Explicit --pages parameter
IF --pages provided:
# Enhanced parsing: handle spaces, multiple delimiters
raw_pages = {--pages value}
# Split by comma, semicolon, or Chinese comma, then clean
# Split by comma, semicolon, or Chinese comma
page_list = split_and_clean(raw_pages, delimiters=[",", ";", "、"])
# Clean each page name: strip whitespace, convert to lowercase
# Clean: strip whitespace, lowercase, replace spaces with hyphens
page_list = [p.strip().lower().replace(" ", "-") for p in page_list if p.strip()]
page_source = "explicit_parameter"
REPORT: "📋 Using provided pages: {', '.join(page_list)}"
# Priority 2: Extract from synthesis-specification.md
ELSE IF --session:
# Read synthesis-specification.md to extract page requirements
synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
page_list = extract_pages_from_synthesis(synthesis_spec)
page_source = "synthesis_specification"
REPORT: "📋 Extracted pages from synthesis: {', '.join(page_list)}"
# Priority 3: Detect from existing prototypes
# Priority 3: Detect from existing prototypes or default
ELSE:
# Infer from existing prototypes or default
page_list = detect_from_prototypes({base_path}/prototypes/)
IF page_list:
page_source = "existing_prototypes"
REPORT: "📋 Detected pages from existing prototypes: {', '.join(page_list)}"
ELSE:
page_list = ["home"]
page_source = "default"
REPORT: "⚠️ No pages found, using default: 'home'"
page_list = detect_from_prototypes({base_path}/prototypes/) OR ["home"]
REPORT: "📋 Detected/default pages: {', '.join(page_list)}"
# Validation: ensure page names are valid
validated_pages = []
invalid_pages = []
FOR page IN page_list:
# Validate format: must start with letter/number, can contain alphanumeric, hyphens, underscores
IF regex_match(page, r"^[a-z0-9][a-z0-9_-]*$"):
validated_pages.append(page)
ELSE:
invalid_pages.append(page)
# 4. Validate page names
validated_pages = [p for p in page_list if regex_match(p, r"^[a-z0-9][a-z0-9_-]*$")]
invalid_pages = [p for p in page_list if p not in validated_pages]
IF invalid_pages:
REPORT: "⚠️ Skipped invalid page names: {', '.join(invalid_pages)}"
REPORT: " Valid format: lowercase, alphanumeric, hyphens, underscores"
VALIDATE: validated_pages not empty, "No valid pages found"
# Use validated list
page_list = validated_pages
REPORT: "✅ Final page list ({len(page_list)}): {', '.join(page_list)}"
# Verify design systems exist for all styles
# 5. Verify design systems exist
FOR style_id IN range(1, style_variants + 1):
VERIFY: {base_path}/style-consolidation/style-{style_id}/design-tokens.json exists
VERIFY: {base_path}/style-consolidation/style-{style_id}/style-guide.md exists
# Load requirements (if integrated mode)
# 6. Load requirements (if integrated mode)
IF --session:
synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
```
### Phase 2: Optimized Matrix UI Generation (Layered, Template-Based)
### Phase 2: Optimized Matrix UI Generation
**Strategy**: Two-layer generation reduces complexity from `O(S×L×P)` to `O(L×P)`, achieving **`S` times faster** performance.
**Strategy**: Decouple HTML structure from CSS styling to eliminate redundancy.
- **Layer 1**: Generate `L × P` layout templates (HTML structure + structural CSS)
- **Layer 2**: Instantiate `S × L × P` final prototypes via fast file operations
**Performance**: Reduces core generation tasks from `O(S×L×P)` to `O(L×P)` — **`S` times faster**
---
#### Phase 2a: Layout Template Generation (Parallel Agent Execution)
#### Phase 2a: Layout Template Generation
Generate style-agnostic layout templates for each `{page} × {layout}` combination.
Total agent tasks: `layout_variants × len(page_list)`
```bash
# Create template directory
# Create directories
CREATE: {base_path}/prototypes/_templates/
CREATE: {base_path}/prototypes/
# Launch layout_variants × page_list parallel tasks
# Launch parallel template generation tasks
FOR layout_id IN range(1, layout_variants + 1):
FOR page IN page_list:
Task(conceptual-planning-agent): "
@@ -165,7 +137,7 @@ FOR layout_id IN range(1, layout_variants + 1):
- Mobile-first responsive design using token-based breakpoints
## Layout Diversity Strategy
You are responsible for Layout {layout_id}. Apply this strategy CONSISTENTLY to all styles in your batch.
Apply this strategy CONSISTENTLY to all styles:
{IF layout_id == 1}
**Layout 1: Classic Hierarchy**
@@ -187,14 +159,11 @@ FOR layout_id IN range(1, layout_variants + 1):
- Develop a unique and consistent layout structure different from the standard three
{ENDIF}
Adapt this strategy to each page's purpose while maintaining layout consistency.
## Token Usage Requirements (STRICT)
- For each style, load design tokens from its specific file: {base_path}/style-consolidation/style-{style_id}/design-tokens.json
- All colors: var(--color-brand-primary), var(--color-surface-background), etc.
- All spacing: var(--spacing-4), var(--spacing-6), etc.
- All typography: var(--font-family-heading), var(--font-size-lg), etc.
- NO hardcoded values (e.g., #4F46E5, 16px) allowed
- NO hardcoded values allowed
## HTML Requirements
- Semantic HTML5 elements (<header>, <nav>, <main>, <section>, <article>)
@@ -203,7 +172,6 @@ FOR layout_id IN range(1, layout_variants + 1):
- Mobile-first responsive design
## CSS Requirements
- Link to design-tokens.css: <link rel=\"stylesheet\" href=\"../../design-tokens.css\">
- Use CSS custom properties from design-tokens.json
- Mobile-first media queries using token breakpoints
- No inline styles
@@ -226,53 +194,43 @@ FOR layout_id IN range(1, layout_variants + 1):
completely style-agnostic (no hardcoded colors, fonts, or spacing).
"
# Wait for all {layout_variants × len(page_list)} parallel tasks to complete
# Generated templates: L × P (significantly fewer than the old S × L × P approach)
REPORT: "✅ Phase 2a complete: Generated {layout_variants * len(page_list)} layout templates"
```
---
#### Phase 2b: Prototype Instantiation (Fast File Operations)
#### Phase 2b: Prototype Instantiation
Create final `S × L × P` prototypes by copying templates and injecting style-specific CSS links.
This phase uses **fast file operations** instead of expensive Agent calls.
Uses **fast file operations** instead of expensive Agent calls.
```bash
REPORT: "🚀 Phase 2b: Instantiating prototypes from templates..."
# Ensure design tokens are converted to CSS for each style
# Convert design tokens to CSS for each style
FOR style_id IN range(1, style_variants + 1):
tokens_json = Read({base_path}/style-consolidation/style-{style_id}/design-tokens.json)
tokens_css = convert_json_to_css_variables(tokens_json)
# Write tokens.css for this style
Write({base_path}/style-consolidation/style-{style_id}/tokens.css, tokens_css)
# Instantiate S × L × P final prototypes via file copying and placeholder replacement
# Instantiate S × L × P final prototypes
Bash(
cd {base_path}/prototypes/
# For each style, layout, and page combination...
for s in $(seq 1 {style_variants}); do
for l in $(seq 1 {layout_variants}); do
for p in {' '.join(page_list)}; do
# Define file names
# Define file paths
TEMPLATE_HTML="_templates/${p}-layout-${l}.html"
STRUCTURAL_CSS="./_templates/${p}-layout-${l}.css"
TOKEN_CSS="../../style-consolidation/style-${s}/tokens.css"
OUTPUT_HTML="${p}-style-${s}-layout-${l}.html"
# 1. Copy the HTML template
# Copy template and replace placeholders
cp "${TEMPLATE_HTML}" "${OUTPUT_HTML}"
# 2. Replace CSS placeholders with actual paths
# Using | delimiter for sed to handle paths with slashes
sed -i "s|{{STRUCTURAL_CSS}}|${STRUCTURAL_CSS}|g" "${OUTPUT_HTML}"
sed -i "s|{{TOKEN_CSS}}|${TOKEN_CSS}|g" "${OUTPUT_HTML}"
# 3. Create implementation notes file
# Create implementation notes
cat > "${p}-style-${s}-layout-${l}-notes.md" <<EOF
# Implementation Notes: ${p}-style-${s}-layout-${l}
@@ -300,7 +258,6 @@ To modify this prototype:
1. Edit the layout template: \`${TEMPLATE_HTML}\` (affects all styles)
2. Edit the structural CSS: \`${STRUCTURAL_CSS}\` (affects all styles)
3. Edit design tokens: \`${TOKEN_CSS}\` (affects only this style variant)
EOF
done
done
@@ -319,7 +276,6 @@ REPORT: " Performance: {style_variants}× faster than original approach"
| Example (3×3×3) | 27 Agent calls | 9 Agent calls |
| Speed Improvement | Baseline | **3× faster** (S times) |
| Resource Usage | High (creative generation for each combo) | Optimized (creative only for templates) |
```
### Phase 3: Generate Preview Files
@@ -327,21 +283,19 @@ REPORT: " Performance: {style_variants}× faster than original approach"
# Read matrix visualization template
template_content = Read("~/.claude/workflows/_template-compare-matrix.html")
# Prepare template variables
# Inject variables into template
pages_json = JSON.stringify(page_list)
run_id = extract_run_id_from_base_path({base_path})
# Inject variables into template
injected_content = template_content
.replace("{{run_id}}", run_id)
.replace("{{style_variants}}", style_variants)
.replace("{{layout_variants}}", layout_variants)
.replace("{{pages_json}}", pages_json)
# Write interactive matrix comparison
Write({base_path}/prototypes/compare.html, injected_content)
# Generate design-tokens.css (unified CSS custom properties for all styles)
# Generate fallback design-tokens.css
Write({base_path}/prototypes/design-tokens.css):
/* Auto-generated from all style design systems */
/* Note: Each prototype links to its specific style's tokens */
@@ -351,7 +305,7 @@ Write({base_path}/prototypes/design-tokens.css):
/* See style-consolidation/style-{n}/design-tokens.json for actual values */
}
# Generate simple index.html for quick navigation
# Generate simple index.html
Write({base_path}/prototypes/index.html):
<!DOCTYPE html>
<html lang="en">
@@ -360,53 +314,16 @@ Write({base_path}/prototypes/index.html):
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>UI Prototypes - Matrix View</title>
<style>
body {
font-family: system-ui, sans-serif;
max-width: 800px;
margin: 2rem auto;
padding: 0 1rem;
}
body { font-family: system-ui, sans-serif; max-width: 800px; margin: 2rem auto; padding: 0 1rem; }
h1 { color: #2563eb; }
.info {
background: #f3f4f6;
padding: 1rem;
border-radius: 0.5rem;
margin: 1rem 0;
}
.cta {
display: inline-block;
background: #2563eb;
color: white;
padding: 0.75rem 1.5rem;
border-radius: 0.5rem;
text-decoration: none;
font-weight: 600;
margin-top: 1rem;
}
.info { background: #f3f4f6; padding: 1rem; border-radius: 0.5rem; margin: 1rem 0; }
.cta { display: inline-block; background: #2563eb; color: white; padding: 0.75rem 1.5rem;
border-radius: 0.5rem; text-decoration: none; font-weight: 600; margin-top: 1rem; }
.cta:hover { background: #1d4ed8; }
.stats {
display: grid;
grid-template-columns: repeat(3, 1fr);
gap: 1rem;
margin: 1.5rem 0;
}
.stat {
background: white;
border: 1px solid #e5e7eb;
padding: 1rem;
border-radius: 0.5rem;
text-align: center;
}
.stat-value {
font-size: 2rem;
font-weight: bold;
color: #2563eb;
}
.stat-label {
color: #6b7280;
font-size: 0.875rem;
margin-top: 0.25rem;
}
.stats { display: grid; grid-template-columns: repeat(3, 1fr); gap: 1rem; margin: 1.5rem 0; }
.stat { background: white; border: 1px solid #e5e7eb; padding: 1rem; border-radius: 0.5rem; text-align: center; }
.stat-value { font-size: 2rem; font-weight: bold; color: #2563eb; }
.stat-label { color: #6b7280; font-size: 0.875rem; margin-top: 0.25rem; }
</style>
</head>
<body>
@@ -452,7 +369,7 @@ Write({base_path}/prototypes/index.html):
</body>
</html>
# Generate PREVIEW.md with instructions
# Generate PREVIEW.md
Write({base_path}/prototypes/PREVIEW.md):
# UI Prototype Preview Guide
@@ -495,7 +412,8 @@ Refer to corresponding `style-guide.md` for design philosophy and usage guidelin
4. Run `/workflow:ui-design:update` to integrate chosen designs
```
### Phase 3.5: Cross-Page Consistency Validation (Optional, Multi-Page Only)
### Phase 3.5: Cross-Page Consistency Validation
**Condition**: Only executes if `len(page_list) > 1`
```bash
@@ -506,7 +424,6 @@ IF len(page_list) <= 1:
# For multi-page workflows, validate cross-page consistency
FOR style_id IN range(1, style_variants + 1):
FOR layout_id IN range(1, layout_variants + 1):
# Generate consistency report for this style-layout combo across all pages
Task(conceptual-planning-agent): "
[CROSS_PAGE_CONSISTENCY_VALIDATION]
@@ -572,7 +489,7 @@ FOR style_id IN range(1, style_variants + 1):
IMPORTANT: Focus on truly shared elements (header, nav, footer). Page-specific content variations are expected and acceptable.
"
# Aggregate all consistency reports
# Aggregate consistency reports
Write({base_path}/prototypes/CONSISTENCY_SUMMARY.md):
# Multi-Page Consistency Summary
@@ -598,13 +515,13 @@ This report summarizes consistency validation across all {len(page_list)} pages.
Run `/workflow:ui-design:update` once all issues are resolved.
```
### Phase 4: TodoWrite & Completion
### Phase 4: Completion
```javascript
TodoWrite({
todos: [
{content: "Resolve paths and load design systems", status: "completed", activeForm: "Loading design systems"},
{content: `Generate ${layout_variants}×${page_list.length} layout templates (optimized)`, status: "completed", activeForm: "Generating layout templates"},
{content: `Generate ${layout_variants}×${page_list.length} layout templates`, status: "completed", activeForm: "Generating layout templates"},
{content: `Instantiate ${style_variants}×${layout_variants}×${page_list.length} final prototypes`, status: "completed", activeForm: "Instantiating prototypes"},
{content: "Generate interactive preview files", status: "completed", activeForm: "Generating preview"}
]
@@ -642,29 +559,16 @@ Generated Structure:
2. Quick Index: Open index.html
3. Instructions: See PREVIEW.md
Features:
- 3×3 matrix grid with synchronized scrolling
- Zoom controls and fullscreen mode
- Selection export for implementation
- Per-page comparison
- Template-based consistency across style variants
Technical Highlights:
- ✅ Decoupled HTML structure from CSS styling
- ✅ Reusable layout templates (affects all styles uniformly)
- ✅ Dynamic style injection via CSS custom properties
- ✅ Significantly reduced generation time
Next: /workflow:ui-design:update {--session flag if applicable}
Note: When called from /workflow:ui-design:auto, design-update is triggered automatically.
```
## Output Structure (Optimized, Template-Based)
## Output Structure
```
{base_path}/prototypes/
├── _templates/ # Reusable layout templates (NEW)
├── _templates/ # Reusable layout templates
│ ├── {page}-layout-1.html # Style-agnostic HTML structure
│ ├── {page}-layout-1.css # Structural CSS with var() references
│ ├── {page}-layout-2.html
@@ -675,48 +579,49 @@ Note: When called from /workflow:ui-design:auto, design-update is triggered auto
├── PREVIEW.md # Preview instructions
├── design-tokens.css # CSS custom properties fallback
├── {page}-style-{s}-layout-{l}.html # Final prototypes (copied from templates)
├── {page}-style-{s}-layout-{l}-notes.md # Implementation notes (auto-generated)
├── {page}-style-{s}-layout-{l}-notes.md # Implementation notes
└── ... (S × L × P total final files)
{base_path}/style-consolidation/
├── style-1/
│ ├── design-tokens.json
│ ├── tokens.css # NEW: CSS variables for style-1
│ ├── tokens.css # CSS variables for style-1
│ └── style-guide.md
├── style-2/
│ ├── design-tokens.json
│ ├── tokens.css # NEW: CSS variables for style-2
│ ├── tokens.css # CSS variables for style-2
│ └── style-guide.md
└── ...
```
## Error Handling
- **No design systems found**: Run `/workflow:ui-design:consolidate --keep-separate` first
- **Invalid page names**: Extract from synthesis-specification.md or error
- **Agent execution errors**: Report details, suggest retry
- **Invalid page names**: Extract from synthesis-specification.md or error with validation message
- **Agent execution errors**: Report details, suggest retry with specific phase
- **Missing template**: Provide fallback or error with template path
## Quality Checks
After generation, ensure:
- [ ] All CSS values reference design token custom properties
- [ ] No hardcoded colors, spacing, or typography
- [ ] Semantic HTML structure
- [ ] ARIA attributes present
- [ ] Responsive design implemented
- [ ] Mobile-first approach
- [ ] Semantic HTML structure with proper element hierarchy
- [ ] ARIA attributes present for accessibility
- [ ] Responsive design implemented with mobile-first approach
- [ ] File naming follows `{page}-style-{s}-layout-{l}` convention
- [ ] compare.html loads correctly with all prototypes
- [ ] Template files are reusable and style-agnostic
## Key Features
1. **Optimized Template-Based Architecture** (NEW)
1. **Optimized Template-Based Architecture**
- Decouples HTML structure from CSS styling
- Generates `L × P` reusable templates instead of `S × L × P` unique files
- **`S` times faster** than previous approach (typically 3× faster)
- **`S` times faster** than previous approach (typically 3× faster for S=3)
2. **Two-Layer Generation Strategy**
- **Layer 1**: Agent-driven creative generation of layout templates
- **Layer 2**: Fast file operations for prototype instantiation
- Layer 1: Agent-driven creative generation of layout templates
- Layer 2: Fast file operations for prototype instantiation
- Reduces expensive Agent calls by ~67% (for S=3)
3. **Consistent Cross-Style Layouts**
@@ -740,7 +645,9 @@ After generation, ensure:
- Token-driven styling (no hardcoded values)
## Integration Points
- **Input**: Per-style design-tokens.json from `/workflow:ui-design:consolidate --keep-separate`
- **Output**: Matrix HTML/CSS prototypes for `/workflow:ui-design:update`
- **Template**: `~/.claude/workflows/_template-compare-matrix.html` (global)
- **Context**: synthesis-specification.md for page requirements (optional)
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow

385
.claude/commands/workflow/ui-design/imitate-auto.md
View File

@@ -13,80 +13,67 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
# UI Design Imitate-Auto Workflow Command
## Overview
Fast-track UI design workflow optimized for **imitating a single design style** from a reference source (URL or images). This command skips the exploration and consolidation phases, directly generating production-ready prototypes based on the provided reference.
## Overview & Philosophy
## Core Philosophy
- **Imitation over Exploration**: Focus on replicating a specific design, not generating variants
- **Single Style**: Always generates one design system (no style matrix)
- **Single Layout**: Generates one layout per page (no layout exploration)
- **Speed Optimized**: Skips `consolidate` step, uses direct token extraction
- **Reference-Driven**: Requires URL or images as primary input source
**Fast-track UI imitation workflow**: Replicates a single design style from reference source (URL or images), bypassing exploration and consolidation phases for maximum speed (~2-3× faster than explore-auto).
## Execution Model - Streamlined Workflow
**Core Philosophy**:
- **Imitation over Exploration**: Focus on replicating specific design, not generating variants
- **Single Mode**: Always 1 style × 1 layout × N pages
- **Speed Optimized**: Bypasses `consolidate` step via direct token extraction
- **Reference-Driven**: Requires URL or images as primary input
- **Auto-Screenshot**: Supports Playwright/Chrome with manual upload fallback
This workflow is optimized for speed and simplicity:
**Streamlined Flow**:
1. User triggers → Phase 0 (initialization) → Phase 0.5 (screenshot capture) → Phase 1 (style extraction) → Phase 2 (token adaptation) → Phase 3 (prototype generation) → Phase 4 (integration) → Complete
1. **User triggers**: `/workflow:ui-design:imitate-auto --url "..." --pages "..."`
2. **Phase 0 executes** (simplified initialization) → Auto-continues
3. **Phase 0.5 executes** (URL screenshot capture with auto-fallback) → Auto-continues
4. **Phase 1 executes** (single style extraction, forced --variants 1) → Auto-continues
5. **Phase 2 executes** (fast token adaptation, bypasses consolidate) → Auto-continues
6. **Phase 3 executes** (single prototype generation, forced 1×1 mode) → Auto-continues
7. **Phase 4 executes** (design integration) → Complete
**Performance**: ~2-3× faster than explore-auto for single-style scenarios
**Performance**: ~2-3× faster than `explore-auto` for single-style scenarios
**Screenshot Automation**: Supports Playwright and Chrome DevTools with manual upload fallback
**Ideal For**: MVP development, high-fidelity prototyping, design replication, studying successful patterns
**Not For**: Design exploration, generating multiple alternatives, novel design creation
## Core Rules
1. **Start Immediately**: First action is `TodoWrite` initialization, second action is Phase 0 execution
2. **No Multi-Variant**: Always generates exactly 1 style × 1 layout × N pages
3. **Reference Required**: Must provide `--url` OR `--images` (at least one)
4. **Auto-Continue**: After each phase, automatically proceed to the next without pausing
5. **Track Progress**: Update `TodoWrite` after every phase completion
1. **Start Immediately**: TodoWrite initialization → Phase 0 execution
2. **No Multi-Variant**: Always 1 style × 1 layout × N pages
3. **Reference Required**: Must provide `--url` OR `--images`
4. **Auto-Continue**: Automatic phase progression without pausing
5. **Track Progress**: Update TodoWrite after each phase
## Parameter Requirements
**Required Parameters** (at least one):
**Required** (at least one):
- `--url "<url>"`: Website URL to imitate (e.g., "https://linear.app")
- `--images "<glob_pattern>"`: Local reference images (e.g., "refs/*.png")
- `--images "<glob>"`: Local reference images (e.g., "refs/*.png")
**Optional Parameters**:
- `--pages "<page_list>"`: Pages to generate (default: "home")
- `--session <session_id>"`: Workflow session ID for integration (optional, standalone if omitted)
- `--prompt "<description>"`: Additional design guidance (e.g., "Focus on dark mode", "Imitate card-based layout")
**Optional**:
- `--pages "<list>"`: Pages to generate (default: "home")
- `--session <id>"`: Workflow session ID (standalone if omitted)
- `--prompt "<desc>"`: Additional design guidance (e.g., "Focus on dark mode")
**Removed Parameters** (not supported):
- `--style-variants`: Always 1 (single style focus)
- `--layout-variants`: Always 1 (single layout focus)
**Not Supported**:
- `--style-variants`: Always 1 (single style)
- `--layout-variants`: Always 1 (single layout)
- `--batch-plan`: Not supported in imitate mode
## 5-Phase Execution
### Phase 0: Simplified Initialization
```bash
# Generate run ID with timestamp
# Generate run ID and determine base path
run_id = "run-$(date +%Y%m%d-%H%M%S)"
# Determine base path
IF --session:
session_id = {provided_session}
base_path = ".workflow/WFS-{session_id}/runs/${run_id}"
ELSE:
# Standalone mode: use scratchpad
session_id = "imitate-session-$(date +%Y%m%d-%H%M%S)"
base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}"
# Create run directory structure (simpler than explore-auto)
Bash(mkdir -p "${base_path}/.design/style-extraction")
Bash(mkdir -p "${base_path}/.design/style-consolidation/style-1")
Bash(mkdir -p "${base_path}/.design/prototypes")
# Create directories (simpler than explore-auto)
Bash(mkdir -p "${base_path}/.design/{style-extraction,style-consolidation/style-1,prototypes}")
# Initialize run metadata
Write({base_path}/.run-metadata.json):
{
# Initialize metadata
Write({base_path}/.run-metadata.json): {
"run_id": "${run_id}",
"session_id": "${session_id}",
"timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
@@ -103,17 +90,15 @@ Write({base_path}/.run-metadata.json):
# Page inference (simplified, no interactive confirmation)
IF --pages provided:
page_list = split_and_clean({--pages value}, delimiters=[",", ";", "、"])
page_list = split_and_clean({--pages value}, [",", ";", "、"])
page_list = [p.strip().lower().replace(" ", "-") for p in page_list if p.strip()]
page_source = "explicit"
ELSE IF --prompt provided:
# Simple extraction from prompt
# Look for patterns like "for dashboard and settings" or "pages: home, about"
# Extract from prompt: "for dashboard and settings" or "pages: home, about"
page_list = extract_pages_from_prompt(prompt_text)
page_source = "prompt_inferred"
IF NOT page_list:
page_list = ["home"]
page_source = "default"
ELSE:
page_list = ["home"]
page_source = "default"
@@ -121,14 +106,14 @@ ELSE:
# Validate page names
validated_pages = []
FOR page IN page_list:
cleaned_page = page.strip().lower().replace(" ", "-")
IF regex_match(cleaned_page, r"^[a-z0-9][a-z0-9_-]*$"):
validated_pages.append(cleaned_page)
cleaned = page.strip().lower().replace(" ", "-")
IF regex_match(cleaned, r"^[a-z0-9][a-z0-9_-]*$"):
validated_pages.append(cleaned)
IF NOT validated_pages:
validated_pages = ["home"]
REPORT: "📋 Imitate mode: Generating {len(validated_pages)} pages with single style"
REPORT: "📋 Imitate mode: {len(validated_pages)} pages with single style"
REPORT: " Pages: {', '.join(validated_pages)}"
REPORT: " Reference: {url_value OR images_pattern}"
@@ -139,181 +124,149 @@ STORE: run_id, base_path, inferred_page_list = validated_pages
### Phase 0.5: URL Screenshot Capture (Auto-Fallback)
**Condition**: Only executes if `--url` is provided
**Purpose**: Automatically capture screenshots from the URL to ensure visual reference is available for style extraction. If automated capture fails, prompts user to provide manual screenshots.
**Condition**: Only if `--url` provided
**Execution**:
```bash
IF --url provided:
REPORT: "📸 Phase 0.5: Capturing screenshots from URL..."
# Create screenshots directory
REPORT: "📸 Phase 0.5: Capturing screenshots..."
screenshot_dir = "{base_path}/.design/screenshots"
Bash(mkdir -p "{screenshot_dir}")
# Try automated screenshot methods
screenshot_success = false
screenshot_files = []
# Method 1: Playwright CLI (preferred, if available)
# Method 1: Playwright CLI (preferred)
TRY:
REPORT: " Attempting Playwright screenshot..."
Bash(
npx playwright screenshot "{url_value}" "{screenshot_dir}/full-page.png" --full-page --timeout 30000
)
REPORT: " Attempting Playwright..."
Bash(npx playwright screenshot "{url_value}" "{screenshot_dir}/full-page.png" --full-page --timeout 30000)
screenshot_files.append("{screenshot_dir}/full-page.png")
screenshot_success = true
REPORT: " ✅ Playwright screenshot captured"
CATCH:
REPORT: " ⚠️ Playwright not available or failed"
REPORT: " ⚠️ Playwright failed"
# Method 2: Chrome DevTools Protocol (fallback)
# Method 2: Chrome DevTools (fallback)
IF NOT screenshot_success:
TRY:
REPORT: " Attempting Chrome headless screenshot..."
Bash(
google-chrome --headless --disable-gpu --screenshot="{screenshot_dir}/full-page.png" --window-size=1920,1080 "{url_value}"
)
REPORT: " Attempting Chrome headless..."
Bash(google-chrome --headless --disable-gpu --screenshot="{screenshot_dir}/full-page.png" --window-size=1920,1080 "{url_value}")
screenshot_files.append("{screenshot_dir}/full-page.png")
screenshot_success = true
REPORT: " ✅ Chrome headless screenshot captured"
REPORT: " ✅ Chrome screenshot captured"
CATCH:
REPORT: " ⚠️ Chrome headless not available or failed"
REPORT: " ⚠️ Chrome failed"
# If both automated methods fail, prompt user for manual screenshot
# Manual upload fallback
IF NOT screenshot_success:
REPORT: ""
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "⚠️ AUTOMATED SCREENSHOT FAILED"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "Unable to automatically capture screenshot from: {url_value}"
REPORT: "Unable to capture: {url_value}"
REPORT: ""
REPORT: "Please provide a manual screenshot:"
REPORT: " 1. Visit the URL in your browser: {url_value}"
REPORT: " 2. Take a full-page screenshot"
REPORT: " 3. Save it to: {screenshot_dir}/"
REPORT: "Manual screenshot required:"
REPORT: " 1. Visit: {url_value}"
REPORT: " 2. Take full-page screenshot"
REPORT: " 3. Save to: {screenshot_dir}/"
REPORT: ""
REPORT: "Options:"
REPORT: " • Type 'ready' when screenshot is saved"
REPORT: " • Type 'skip' to use URL analysis only (lower quality)"
REPORT: " • Type 'abort' to cancel the workflow"
REPORT: ""
REPORT: " • 'ready' - screenshot saved"
REPORT: " • 'skip' - use URL analysis only"
REPORT: " • 'abort' - cancel workflow"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
# Wait for user input
user_response = WAIT_FOR_USER_INPUT()
IF user_response MATCHES r"^(ready|done|ok)$":
# Check if user provided screenshot
screenshot_files = Glob("{screenshot_dir}/*.{png,jpg,jpeg}")
IF screenshot_files:
screenshot_success = true
REPORT: "✅ Manual screenshot detected: {', '.join(screenshot_files)}"
REPORT: "✅ Manual screenshot detected"
ELSE:
REPORT: "❌ No screenshot found in {screenshot_dir}/"
REPORT: " Workflow will use URL analysis only (may result in lower quality)"
REPORT: "❌ No screenshot found, using URL analysis only"
ELSE IF user_response MATCHES r"^skip$":
REPORT: "⏭️ Skipping screenshot, using URL analysis only"
screenshot_success = false
REPORT: "⏭️ Skipping screenshot, using URL analysis"
ELSE IF user_response MATCHES r"^abort$":
ERROR: "Workflow aborted by user"
EXIT
ELSE:
REPORT: "⚠️ Invalid input, proceeding with URL analysis only"
screenshot_success = false
REPORT: "⚠️ Invalid input, proceeding with URL analysis"
# Store screenshot info for Phase 1
# Store results
IF screenshot_success:
STORE: screenshot_mode = "with_screenshots"
STORE: screenshot_paths = screenshot_files
STORE: screenshot_mode = "with_screenshots", screenshot_paths = screenshot_files
REPORT: "✅ Screenshot capture complete: {len(screenshot_files)} image(s)"
ELSE:
STORE: screenshot_mode = "url_only"
STORE: screenshot_paths = []
REPORT: "ℹ️ Proceeding with URL analysis only (no screenshots)"
STORE: screenshot_mode = "url_only", screenshot_paths = []
REPORT: "ℹ️ Proceeding with URL analysis only"
ELSE:
# No URL provided, must use --images
STORE: screenshot_mode = "manual_images"
STORE: screenshot_paths = []
STORE: screenshot_mode = "manual_images", screenshot_paths = []
REPORT: "ℹ️ Using provided images (--images parameter)"
```
**Auto-Continue**: On completion, proceeds to Phase 1
**Auto-Continue**: On completion → Phase 1
---
### Phase 1: Single Style Extraction
**Command Construction**:
**Command**:
```bash
# Determine input flags based on screenshot capture results
# Determine input based on screenshot capture
IF screenshot_mode == "with_screenshots":
# Use captured screenshots instead of URL
screenshot_glob = "{base_path}/.design/screenshots/*.{png,jpg,jpeg}"
images_flag = "--images \"{screenshot_glob}\""
url_flag = ""
source_desc = "captured screenshots from {url_value}"
ELSE IF screenshot_mode == "url_only":
# Use URL directly (Claude can analyze URLs)
url_flag = "--url \"{url_value}\""
images_flag = ""
source_desc = "URL analysis of {url_value}"
ELSE IF screenshot_mode == "manual_images":
# Use user-provided images
images_flag = --images present ? "--images \"{image_glob}\"" : ""
url_flag = ""
source_desc = "user-provided images"
ELSE:
# Fallback
url_flag = --url present ? "--url \"{url_value}\"" : ""
images_flag = --images present ? "--images \"{image_glob}\"" : ""
source_desc = "provided references"
# Add user prompt if provided
prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : ""
# Use run-scoped base path and FORCE --variants 1
run_base_flag = "--base-path \"{base_path}/.design\""
# Construct optimized extraction prompt for imitation
# Construct optimized extraction prompt
enhanced_prompt = "Extract a single, high-fidelity design system that accurately imitates the visual style from {source_desc}. {prompt_text}"
# Force single variant extraction
# Force single variant
command = "/workflow:ui-design:extract {run_base_flag} {url_flag} {images_flag} --prompt \"{enhanced_prompt}\" --variants 1"
REPORT: "🚀 Executing Phase 1: Style Extraction"
REPORT: "🚀 Phase 1: Style Extraction"
REPORT: " Source: {source_desc}"
REPORT: " Mode: Single style (imitation-optimized)"
SlashCommand(command=command)
SlashCommand(command)
```
**Auto-Continue**: On completion, proceeds to Phase 2
**Auto-Continue**: On completion → Phase 2
---
### Phase 2: Fast Token Adaptation (Bypass Consolidate)
**Action**: Direct extraction of design tokens from the single style card, bypassing the heavy `consolidate` step
**Action**: Direct extraction of design tokens, bypassing heavy `consolidate` step
**Execution**:
```bash
REPORT: "🚀 Phase 2: Fast token adaptation (bypassing consolidate for speed)"
REPORT: "🚀 Phase 2: Fast token adaptation (bypassing consolidate)"
# Read the single style card from extraction output
# Read single style card
style_cards = Read({base_path}/.design/style-extraction/style-cards.json)
style_card = style_cards.style_cards[0] # Only one card in imitate mode
style_card = style_cards.style_cards[0]
# Extract components
design_tokens = style_card.proposed_tokens
philosophy = style_card.design_philosophy
style_name = style_card.name
# Create minimal design system structure (generate needs this)
# Write design-tokens.json directly from proposed_tokens
# Write design-tokens.json directly
Write({base_path}/.design/style-consolidation/style-1/design-tokens.json, JSON.stringify(design_tokens, null, 2))
# Create minimal style-guide.md (simpler than consolidate output)
# Create minimal style-guide.md
Write({base_path}/.design/style-consolidation/style-1/style-guide.md):
# Design System: {style_name}
@@ -324,7 +277,7 @@ Write({base_path}/.design/style-consolidation/style-1/style-guide.md):
{style_card.description}
## Design Tokens
All design tokens are defined in `design-tokens.json` and follow the OKLCH color space standard.
All tokens in `design-tokens.json` follow OKLCH color space.
**Key Colors**:
- Primary: {design_tokens.colors.brand.primary}
@@ -332,14 +285,14 @@ All design tokens are defined in `design-tokens.json` and follow the OKLCH color
- Text: {design_tokens.colors.text.primary}
**Typography**:
- Heading Font: {design_tokens.typography.font_family.heading}
- Body Font: {design_tokens.typography.font_family.body}
- Heading: {design_tokens.typography.font_family.heading}
- Body: {design_tokens.typography.font_family.body}
**Spacing Scale**: {design_tokens.spacing.keys().length} values
**Note**: This design system was generated in imitate mode, optimized for fast replication of the reference source.
*Note: Generated in imitate mode for fast replication.*
# Create minimal tailwind.config.js (optional, for convenience)
# Create minimal tailwind.config.js
Write({base_path}/.design/style-consolidation/style-1/tailwind.config.js):
module.exports = {
theme: {
@@ -352,59 +305,59 @@ module.exports = {
}
}
REPORT: "✅ Design tokens extracted and formatted"
REPORT: "✅ Tokens extracted and formatted"
REPORT: " Style: {style_name}"
REPORT: " Bypassed consolidate step for {performance_gain}× speed improvement"
REPORT: " Bypassed consolidate for {performance_gain}× speed"
```
**Auto-Continue**: On completion, proceeds to Phase 3
**Auto-Continue**: On completion → Phase 3
---
### Phase 3: Single Prototype Generation
**Command Construction**:
**Command**:
```bash
run_base_flag = "--base-path \"{base_path}/.design\""
pages_string = ",".join(inferred_page_list)
pages_flag = "--pages \"{pages_string}\""
# Force single style and single layout
# Force 1×1 mode
command = "/workflow:ui-design:generate {run_base_flag} {pages_flag} --style-variants 1 --layout-variants 1"
REPORT: "🚀 Executing Phase 3: Generating {len(inferred_page_list)} prototype(s)"
REPORT: " Mode: Single style × Single layout (optimized for imitation)"
REPORT: "🚀 Phase 3: Generating {len(inferred_page_list)} prototype(s)"
REPORT: " Mode: 1×1 (imitation-optimized)"
SlashCommand(command=command)
SlashCommand(command)
```
**Result**: Generates `1 × 1 × N` prototypes (where N = number of pages)
- File naming: `{page}-style-1-layout-1.html`
- Total prototypes: `len(inferred_page_list)`
**Result**:
- Prototypes: `{page}-style-1-layout-1.html`
- Total: `len(inferred_page_list)`
**Auto-Continue**: On completion, proceeds to Phase 4
**Auto-Continue**: On completion → Phase 4
---
### Phase 4: Design System Integration
**Command Construction**:
**Command**:
```bash
IF --session:
session_flag = "--session {session_id}"
command = "/workflow:ui-design:update {session_flag}"
SlashCommand(command=command)
SlashCommand(command)
ELSE:
REPORT: "ℹ️ Standalone mode: Skipping design system integration (no session provided)"
REPORT: " Prototypes available at: {base_path}/.design/prototypes/"
REPORT: "ℹ️ Standalone mode: Skipping integration"
REPORT: " Prototypes at: {base_path}/.design/prototypes/"
```
**Completion**: Workflow is now complete
**Completion**: Workflow complete
## TodoWrite Pattern
```javascript
// Initialize (before Phase 0)
// Initialize
TodoWrite({todos: [
{"content": "Initialize run directory and infer pages", "status": "in_progress", "activeForm": "Initializing"},
{"content": "Capture screenshots from URL (if provided)", "status": "pending", "activeForm": "Capturing screenshots"},
@@ -414,115 +367,71 @@ TodoWrite({todos: [
{"content": "Integrate design system", "status": "pending", "activeForm": "Integrating design"}
]})
// Update after each phase...
// Update after each phase: Mark current completed, next in_progress
```
## Error Handling
- **No reference source**: Error if neither `--url` nor `--images` provided
- **Screenshot capture failure**:
- Tries 2 automated methods in sequence: Playwright → Chrome DevTools
- Falls back to manual screenshot upload if both fail
- User can choose: upload manual screenshot, skip screenshots, or abort
- **Invalid URL**: Report URL fetch failure, suggest using `--images` instead
- **Missing images**: Report glob pattern error, suggest checking file paths
- **Token extraction failure**: Fallback to a minimal default design system
- **Playwright/Chrome not installed**: Gracefully prompts user to upload manual screenshot
- Tries 2 methods: Playwright → Chrome DevTools
- Falls back to manual upload: user uploads screenshot, skips, or aborts
- Gracefully handles missing Playwright/Chrome
- **Invalid URL/images**: Report error, suggest alternative input
- **Token extraction failure**: Fallback to minimal default design system
## Key Differences from explore-auto
## Performance Comparison
| Aspect | explore-auto | imitate-auto |
|--------|--------------|--------------|
| **Purpose** | Explore multiple design options | Replicate specific design |
| **Purpose** | Design exploration | Design replication |
| **Input** | Optional URL/images | **Required** URL or images |
| **Variants** | 1-5 styles × 1-5 layouts | Always 1 × 1 (single) |
| **Consolidate** | Full consolidation with validation | **Bypassed** (direct token extraction) |
| **Variants** | 1-5 styles × 1-5 layouts | Always 1 × 1 |
| **Consolidate** | Full consolidation | **Bypassed** (direct tokens) |
| **Speed** | Baseline | **~2-3× faster** |
| **Output** | Design matrix (S×L×P prototypes) | Direct prototypes (1×1×P) |
| **Use Case** | Design exploration, need options | Fast prototyping, have reference |
| **Output** | Matrix (S×L×P) | Direct (1×1×P) |
| **Phases** | 6 phases | 5 phases |
## Performance Benefits
1. **Skipped consolidate**: Saves ~30-60s per run (most expensive phase)
**Performance Benefits**:
1. **Skipped consolidate**: Saves ~30-60s (most expensive phase)
2. **Single variant**: Reduces extraction complexity
3. **Direct token mapping**: Simple file operations vs AI synthesis
4. **Streamlined decisions**: No variant selection or confirmation needed
## Workflow Position
This workflow is ideal for:
- **MVP Development**: Quickly create UI based on a competitor or design reference
- **High-Fidelity Prototyping**: Convert designs to code rapidly
- **Design Replication**: Imitate specific visual styles from existing sites
- **Learning**: Study and recreate successful design patterns
**NOT ideal for**:
- Generating multiple design alternatives
- Design exploration without clear reference
- Creating completely novel designs
3. **Direct token mapping**: Simple file ops vs AI synthesis
4. **Streamlined decisions**: No variant selection/confirmation
## Example Execution Flows
### Example 1: Imitate from URL (with Auto-Screenshot)
### Example 1: URL with Auto-Screenshot
```bash
/workflow:ui-design:imitate-auto --url "https://linear.app" --pages "home,features,pricing"
# Execution:
# 0. Initialize: 3 pages identified
# 0.5. Screenshot: Playwright captures full-page screenshot of linear.app
# 1. Extract: Single style from captured screenshot
# 2. Adapt: Direct token extraction (~2s vs consolidate's ~45s)
# 3. Generate: 3 prototypes (home, features, pricing)
# Flow:
# 0. Init: 3 pages identified
# 0.5. Screenshot: Playwright captures linear.app
# 1. Extract: Single style from screenshot
# 2. Adapt: Direct tokens (~2s vs consolidate's ~45s)
# 3. Generate: 3 prototypes
# 4. Complete
# Total time: ~2-3 minutes (vs 5-7 minutes with explore-auto)
# Screenshot: Automatically saved to .design/screenshots/
# Time: ~2-3 min (vs 5-7 min with explore-auto)
```
### Example 2: Imitate from Images with Guidance
### Example 2: Images with Guidance
```bash
/workflow:ui-design:imitate-auto --images "refs/dark-theme.png" --prompt "Focus on dark mode color palette" --pages "dashboard"
/workflow:ui-design:imitate-auto --images "refs/dark-theme.png" --prompt "Focus on dark mode" --pages "dashboard"
# Execution:
# 0. Initialize: 1 page (dashboard)
# 0.5. Screenshot: Skipped (using provided images)
# 1. Extract: Single style from image, dark mode emphasis
# 2. Adapt: Direct token extraction
# 3. Generate: 1 prototype (dashboard-style-1-layout-1.html)
# 4. Complete (standalone mode, no integration)
# Flow: 0 → 0.5 (skip) → 1 → 2 → 3 → 4
# Output: dashboard-style-1-layout-1.html
```
### Example 3: URL with Manual Screenshot Upload
### Example 3: URL with Manual Screenshot
```bash
/workflow:ui-design:imitate-auto --url "https://stripe.com/pricing" --pages "pricing"
# Execution:
# 0. Initialize: 1 page (pricing)
# 0.5. Screenshot:
# ⚠️ Playwright not available
# ⚠️ Chrome headless not available
# 📸 Prompting user to upload manual screenshot...
#
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# ⚠️ AUTOMATED SCREENSHOT FAILED
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Please provide a manual screenshot:
# 1. Visit: https://stripe.com/pricing
# 2. Take a full-page screenshot
# 3. Save to: .design/screenshots/
#
# Options:
# • Type 'ready' when screenshot is saved
# • Type 'skip' to use URL analysis only
# • Type 'abort' to cancel
#
# User saves screenshot and types 'ready' → ✅ Workflow continues
# OR
# User types 'skip' → ⚠️ Uses URL analysis only
# 1. Extract: Single style from screenshot or URL
# 2. Adapt: Direct token extraction
# 3. Generate: 1 prototype
# 4. Complete
# ⚠️ Playwright failed → Chrome failed
# 📸 User prompted for manual upload
# User saves screenshot → types 'ready' → ✅ continues
# OR types 'skip' → ⚠️ uses URL analysis only
# Continues: 1 → 2 → 3 → 4
```
## Final Completion Message
@@ -537,29 +446,29 @@ Reference: {url OR images}
Phase 0 - Initialization: {page_count} pages prepared
Phase 0.5 - Screenshot Capture: {screenshot_status}
{IF screenshot_success: ✅ Screenshot captured via {method} (Playwright/Chrome/Manual)}
{ELSE: ⚠️ Using URL analysis only}
Phase 1 - Style Extraction: Single design style extracted
{IF success: ✅ Captured via {method}}
{ELSE: ⚠️ URL analysis only}
Phase 1 - Style Extraction: Single style extracted
Phase 2 - Token Adaptation: Bypassed consolidate (⚡ {time_saved}s saved)
Phase 3 - Prototype Generation: {page_count} prototypes created
Phase 4 - Design Integration: {integrated OR "Standalone mode - No integration"}
Phase 4 - Design Integration: {integrated OR "Standalone mode"}
📂 Output: {base_path}/.design/
├── style-extraction/style-cards.json (1 style card)
├── style-consolidation/style-1/ (design tokens)
└── prototypes/ ({page_count} HTML/CSS files)
🌐 Preview: Open {base_path}/.design/prototypes/index.html
🌐 Preview: {base_path}/.design/prototypes/index.html
Performance:
- Design system creation: ~{time}s (vs ~{consolidate_time}s with consolidate)
- Total workflow time: ~{total_time}s
- Design system: ~{time}s (vs ~{consolidate_time}s with consolidate)
- Total workflow: ~{total_time}s
- Speed improvement: ~{improvement}× faster than explore-auto
{IF session mode:
{IF session:
Next: /workflow:plan to create implementation tasks
}
{ELSE:
Prototypes ready for direct use at: {base_path}/.design/prototypes/
Prototypes ready: {base_path}/.design/prototypes/
}
```

378
.claude/commands/workflow/ui-design/update.md
View File

@@ -1,71 +1,77 @@
---
name: update
description: Update brainstorming artifacts with finalized design system
description: Update brainstorming artifacts with finalized design system references
usage: /workflow:ui-design:update --session <session_id> [--selected-prototypes "<list>"]
argument-hint: "--session WFS-session-id [--selected-prototypes \"dashboard-variant-1,auth-variant-2\"]"
examples:
- /workflow:ui-design:update --session WFS-auth
- /workflow:ui-design:update --session WFS-dashboard --selected-prototypes "dashboard-variant-1"
allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*), Bash(*)
allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
---
# Design Update Command
## Overview
Synchronize finalized design system (tokens, style guide, selected prototypes) back to brainstorming artifacts, preparing for `/workflow:plan` phase consumption.
Synchronize finalized design system references to brainstorming artifacts, preparing them for `/workflow:plan` consumption. This command updates **references only** (via @ notation), not content duplication.
## Core Philosophy
- **Main Claude Execution**: Direct updates by main Claude (avoid Agent context loss, following synthesis pattern)
- **Reference-Based Integration**: Use @ references, not content duplication
- **Reference-Only Updates**: Use @ references, no content duplication
- **Main Claude Execution**: Direct updates by main Claude (no Agent handoff)
- **Synthesis Alignment**: Update synthesis-specification.md UI/UX Guidelines section
- **UI Designer Sync**: Mirror design system to ui-designer/style-guide.md
- **Plan-Ready Output**: Ensure design artifacts discoverable by task-generate
- **Minimal Reading**: Verify file existence, don't read design content
## Execution Protocol
### Phase 1: Session & Design System Validation
### Phase 1: Session & Artifact Validation
```bash
# Validate session and verify design system completeness
# Validate session
CHECK: .workflow/.active-* marker files
VALIDATE: session_id matches active session
VERIFY required artifacts:
# Verify required design artifacts exist (file existence check only)
VERIFY:
- .design/style-consolidation/design-tokens.json
- .design/style-consolidation/style-guide.md
- .design/style-consolidation/tailwind.config.js
- .design/prototypes/*.html (at least one prototype)
# Prototype selection
IF --selected-prototypes provided:
VALIDATE: Specified prototypes exist
selected_list = parse_comma_separated(--selected-prototypes)
ELSE:
AUTO-SELECT: Use all generated prototypes
selected_list = Glob(.design/prototypes/*.html)
REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
```
### Phase 2: Load Design System Context
**Direct Claude Code Execution** (no Agent invocation)
### Phase 2: Load Target Artifacts Only
**What to Load**: Only the files we need to **update**, not the design files we're referencing.
```bash
# Load all design system artifacts
Read(.workflow/WFS-{session}/.design/style-consolidation/design-tokens.json)
Read(.workflow/WFS-{session}/.design/style-consolidation/style-guide.md)
Read(.workflow/WFS-{session}/.design/style-consolidation/tailwind.config.js)
Read(.workflow/WFS-{session}/.design/style-consolidation/validation-report.json)
# Load selected prototype files
FOR each selected_prototype IN selected_prototypes:
Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}.html)
Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}-notes.md)
# Load target brainstorming artifacts
# Load target brainstorming artifacts (files to be updated)
Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
Read(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md) [if exists]
# Optional: Read prototype notes for descriptions (minimal context)
FOR each selected_prototype IN selected_list:
Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}-notes.md)
# Extract: layout_strategy, page_name only
```
**Note**: We do **NOT** read design-tokens.json, style-guide.md, or prototype HTML. We only verify they exist and generate @ references to them.
### Phase 3: Update Synthesis Specification
**Direct Write by Main Claude**
Update `.brainstorming/synthesis-specification.md`:
Update `.brainstorming/synthesis-specification.md` with design system references.
**Target Section**: `## UI/UX Guidelines`
**Content Template**:
```markdown
## UI/UX Guidelines
@@ -74,24 +80,6 @@ Update `.brainstorming/synthesis-specification.md`:
**Style Guide**: @../.design/style-consolidation/style-guide.md
**Tailwind Configuration**: @../.design/style-consolidation/tailwind.config.js
### Design Philosophy
[Extract philosophy section from style-guide.md]
### Token System Overview
**Colors**: OKLCH-based color system with semantic naming
- Brand: primary, secondary, accent
- Surface: background, elevated, sunken
- Semantic: success, warning, error, info
**Typography**: {font_family_count} font families, {scale_count}-step scale
- Heading: {heading_font}
- Body: {body_font}
- Monospace: {mono_font}
**Spacing**: {scale_count}-step scale ({min}rem to {max}rem)
**Components**: Border radius, shadows, and component tokens defined
### Implementation Requirements
**Token Adherence**: All UI implementations MUST use design token CSS custom properties
**Accessibility**: WCAG AA compliance validated in design-tokens.json
@@ -99,21 +87,19 @@ Update `.brainstorming/synthesis-specification.md`:
**Component Patterns**: Follow patterns documented in style-guide.md
### Reference Prototypes
[For each selected prototype:]
{FOR each selected_prototype:
- **{page_name}**: @../.design/prototypes/{prototype}.html
- Layout: {layout_description from notes}
- Components: {component_list from notes}
- Token Usage: {token_usage_summary from notes}
- Layout: {layout_strategy from notes}
}
### Design System Assets (for task-generate consumption)
### Design System Assets
```json
{
"design_tokens": ".design/style-consolidation/design-tokens.json",
"style_guide": ".design/style-consolidation/style-guide.md",
"tailwind_config": ".design/style-consolidation/tailwind.config.js",
"prototypes": [
".design/prototypes/{prototype-1}.html",
".design/prototypes/{prototype-2}.html"
{FOR each: ".design/prototypes/{prototype}.html"}
]
}
```
@@ -121,46 +107,35 @@ Update `.brainstorming/synthesis-specification.md`:
**Implementation**:
```bash
# Edit synthesis-specification.md
# Option 1: Edit existing section
Edit(
file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
old_string="## UI/UX Guidelines\n[existing content or empty]",
new_string="## UI/UX Guidelines\n\n[new design system content with @ references]"
old_string="## UI/UX Guidelines\n[existing content]",
new_string="## UI/UX Guidelines\n\n[new design reference content]"
)
# Option 2: Append if section doesn't exist
IF section not found:
Edit(
file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
old_string="[end of document]",
new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]"
)
```
### Phase 4: Update UI Designer Analysis
**Create or update** `.brainstorming/ui-designer/style-guide.md`:
### Phase 4: Update UI Designer Style Guide
Create or update `.brainstorming/ui-designer/style-guide.md`:
```markdown
# UI Designer Style Guide
## Design System Integration
This style guide integrates the finalized design system from the design refinement phase.
This style guide references the finalized design system from the design refinement phase.
**Source Design Tokens**: @../../.design/style-consolidation/design-tokens.json
**Source Style Guide**: @../../.design/style-consolidation/style-guide.md
## Design Philosophy
[Extract philosophy section from source style-guide.md]
## Design Tokens Reference
For complete token definitions, see: @../../.design/style-consolidation/design-tokens.json
### Color System
[Summary of color tokens]
### Typography System
[Summary of typography tokens]
### Spacing System
[Summary of spacing tokens]
### Component Tokens
[Summary of component tokens: border-radius, shadows]
## Component Patterns
[Reference to style-guide.md component patterns]
**Design Tokens**: @../../.design/style-consolidation/design-tokens.json
**Style Guide**: @../../.design/style-consolidation/style-guide.md
**Tailwind Config**: @../../.design/style-consolidation/tailwind.config.js
## Implementation Guidelines
1. **Use CSS Custom Properties**: All styles reference design tokens
@@ -169,10 +144,17 @@ For complete token definitions, see: @../../.design/style-consolidation/design-t
4. **Responsive Design**: Mobile-first with token-based breakpoints
## Reference Prototypes
[Links to selected prototypes with descriptions]
{FOR each selected_prototype:
- **{page_name}**: @../../.design/prototypes/{prototype}.html
}
## Token System
For complete token definitions and usage examples, see:
- Design Tokens: @../../.design/style-consolidation/design-tokens.json
- Style Guide: @../../.design/style-consolidation/style-guide.md
---
*Auto-generated by /workflow:design:design-update*
*Auto-generated by /workflow:ui-design:update*
*Last updated: {timestamp}*
```
@@ -180,169 +162,155 @@ For complete token definitions, see: @../../.design/style-consolidation/design-t
```bash
Write(
file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
content="[generated style guide content with @ references]"
content="[generated content with @ references]"
)
```
### Phase 5: Create Design System Symlinks (Optional)
**For easier task-generate discovery**
### Phase 5: Completion
```bash
# Create read-only mirror of key design files in brainstorming space
bash(cd .workflow/WFS-{session}/.brainstorming && \
ln -s ../.design/style-consolidation/design-tokens.json design-tokens.json && \
ln -s ../.design/style-consolidation/style-guide.md design-style-guide.md)
```
### Phase 6: TodoWrite Integration
```javascript
TodoWrite({
todos: [
{
content: "Validate session and design system completeness",
status: "completed",
activeForm: "Validating design system"
},
{
content: "Load design tokens, style guide, and selected prototypes",
status: "completed",
activeForm: "Loading design artifacts"
},
{
content: "Update synthesis-specification.md with design system references",
status: "completed",
activeForm: "Updating synthesis specification"
},
{
content: "Create or update ui-designer/style-guide.md",
status: "completed",
activeForm: "Updating UI designer style guide"
},
{
content: "Create design system symlinks for task-generate discovery",
status: "completed",
activeForm: "Creating artifact symlinks"
}
{content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"},
{content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"},
{content: "Update synthesis-specification.md with design references", status: "completed", activeForm: "Updating synthesis spec"},
{content: "Create/update ui-designer/style-guide.md", status: "completed", activeForm: "Updating UI designer guide"}
]
});
```
**Completion Message**:
```
✅ Design system references updated for session: WFS-{session}
Updated artifacts:
✓ synthesis-specification.md - UI/UX Guidelines section with @ references
✓ ui-designer/style-guide.md - Design system reference guide
Design system assets ready for /workflow:plan:
- design-tokens.json
- style-guide.md
- tailwind.config.js
- {prototype_count} reference prototypes
Next: /workflow:plan [--agent] "<task description>"
The plan phase will automatically discover and utilize the design system.
```
## Output Structure
**Updated Files**:
```
.workflow/WFS-{session}/.brainstorming/
├── synthesis-specification.md # Updated with UI/UX Guidelines section
├── ui-designer/
│ └── style-guide.md # New or updated comprehensive style guide
├── design-tokens.json # Symlink to ../.design/style-consolidation/design-tokens.json
└── design-style-guide.md # Symlink to ../.design/style-consolidation/style-guide.md
└── ui-designer/
└── style-guide.md # New or updated design reference guide
```
**Reference Structure** (@ references in synthesis-specification.md):
- `@../.design/style-consolidation/design-tokens.json`
- `@../.design/style-consolidation/style-guide.md`
- `@../.design/style-consolidation/tailwind.config.js`
- `@../.design/prototypes/{prototype}.html`
**@ Reference Format** (used in synthesis-specification.md):
```
@../.design/style-consolidation/design-tokens.json
@../.design/style-consolidation/style-guide.md
@../.design/style-consolidation/tailwind.config.js
@../.design/prototypes/{prototype}.html
```
## Integration with task-generate
**@ Reference Format** (used in ui-designer/style-guide.md):
```
@../../.design/style-consolidation/design-tokens.json
@../../.design/style-consolidation/style-guide.md
@../../.design/style-consolidation/tailwind.config.js
@../../.design/prototypes/{prototype}.html
```
After this update, `/workflow:tools:task-generate` will discover:
## Integration with /workflow:plan
**In context.artifacts**:
After this update, `/workflow:plan` will discover design assets through:
**Phase 3: Intelligent Analysis** (`/workflow:tools:concept-enhanced`)
- Reads synthesis-specification.md
- Discovers @ references to design system files
- Includes design system context in ANALYSIS_RESULTS.md
**Phase 4: Task Generation** (`/workflow:tools:task-generate`)
- Reads ANALYSIS_RESULTS.md
- Discovers design assets from synthesis-specification.md
- Includes design system paths in task JSON files
**Example Task JSON** (generated by task-generate):
```json
{
"artifacts": [
{
"type": "synthesis_specification",
"path": ".brainstorming/synthesis-specification.md"
},
{
"type": "design_tokens",
"path": ".design/style-consolidation/design-tokens.json"
},
{
"type": "style_guide",
"path": ".design/style-consolidation/style-guide.md"
},
{
"type": "tailwind_config",
"path": ".design/style-consolidation/tailwind.config.js"
},
{
"type": "ui_prototypes",
"paths": [
".design/prototypes/dashboard-variant-1.html",
".design/prototypes/auth-variant-2.html"
]
"task_id": "IMPL-001",
"context": {
"design_system": {
"tokens": ".design/style-consolidation/design-tokens.json",
"style_guide": ".design/style-consolidation/style-guide.md",
"prototypes": [".design/prototypes/dashboard-variant-1.html"]
}
]
}
```
**In flow_control.pre_analysis** (for UI tasks):
```json
{
"step": "load_design_tokens",
"action": "Load design system tokens and style guide",
"commands": [
"bash(cat .workflow/WFS-{session}/.design/style-consolidation/design-tokens.json)",
"bash(cat .workflow/WFS-{session}/.design/style-consolidation/style-guide.md)"
],
"output_to": "design_system_context",
"on_error": "warn"
}
}
```
## Error Handling
- **Missing design tokens**: Error, run `/workflow:ui-design:consolidate` first
- **Missing prototypes**: Error, run `/workflow:ui-design:generate` first
- **synthesis-specification.md not found**: Warning, create minimal version
- **Edit conflicts**: Preserve existing content, append design system section
- **Symlink failures**: Warning only, continue with @ references
- **Missing design artifacts**: Error with message "Run /workflow:ui-design:consolidate and /workflow:ui-design:generate first"
- **synthesis-specification.md not found**: Warning, create minimal version with just UI/UX Guidelines
- **ui-designer/ directory missing**: Create directory and file
- **Edit conflicts**: Preserve existing content, append or replace only UI/UX Guidelines section
- **Invalid prototype names**: Skip invalid entries, continue with valid ones
## Validation Checks
After update, verify:
- [ ] synthesis-specification.md contains UI/UX Guidelines section
- [ ] UI/UX Guidelines include @ references to design system files
- [ ] UI/UX Guidelines include @ references (not content duplication)
- [ ] ui-designer/style-guide.md created or updated
- [ ] design-tokens.json symlink created (if applicable)
- [ ] All referenced files exist and are readable
- [ ] All @ referenced files exist and are accessible
- [ ] @ reference paths are relative and correct
## Key Features
1. **Reference-Only Updates**
- Uses @ notation for file references
- No content duplication between design and brainstorming spaces
- Lightweight, maintainable approach
2. **Main Claude Direct Execution**
- No Agent handoff (preserves context)
- Simple reference generation (no complex synthesis)
- Reliable path resolution
3. **Plan-Ready Output**
- `/workflow:plan` Phase 3 can discover design system
- Task generation includes design asset paths
- Clear integration points for implementation tasks
4. **Minimal Reading**
- Only reads target files to update (synthesis-specification.md, ui-designer/analysis.md)
- Verifies design file existence (no content reading)
- Optional: reads prototype notes for descriptions
5. **Flexible Prototype Selection**
- Auto-select all prototypes (default)
- Manual selection via --selected-prototypes parameter
- Validates prototype existence before referencing
## Integration Points
- **Input**: design-tokens.json, style-guide.md, prototypes from design phase
- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md
- **Next Phase**: `/workflow:plan` can now discover and utilize design system
## Completion Message
- **Input**: Design system artifacts from `/workflow:ui-design:consolidate` and `/workflow:ui-design:generate`
- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md with @ references
- **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
```
Design system update complete for session: WFS-{session}
Updated artifacts:
✓ synthesis-specification.md - UI/UX Guidelines section added
✓ ui-designer/style-guide.md - Comprehensive style guide created
✓ Design system references: @ notation for all design files
Design system assets ready for task generation:
- design-tokens.json ({token_count} tokens)
- style-guide.md (comprehensive component patterns)
- tailwind.config.js (Tailwind theme extension)
- {prototype_count} reference prototypes
Next: /workflow:plan [--agent] "<task description>"
The plan phase will automatically discover and utilize the design system.
```
## Main Claude Direct Execution Rationale
## Why Main Claude Execution?
This command is executed directly by main Claude (not delegated to an Agent) because:
1. **Context Preservation**: Main Claude has full session context and conversation memory
2. **Integration Complexity**: Requires understanding multiple artifact relationships
3. **Reference Accuracy**: @ reference generation needs precise path resolution
4. **Synthesis Pattern**: Follows the same direct-execution pattern as `/workflow:brainstorm:synthesis`
5. **Minimal Transformation**: Primarily reference integration, not generative analysis
6. **Error Recovery**: Main Claude can better handle edit conflicts and missing files
1. **Simple Reference Generation**: Only generating file paths, not complex synthesis
2. **Context Preservation**: Main Claude has full session and conversation context
3. **Minimal Transformation**: Primarily updating references, not analyzing content
4. **Path Resolution**: Requires precise relative path calculation
5. **Edit Operations**: Better error recovery for Edit conflicts
6. **Synthesis Pattern**: Follows same direct-execution pattern as other reference updates
This approach ensures reliable, context-aware integration without Agent handoff overhead.
This ensures reliable, lightweight integration without Agent handoff overhead.

302
CHANGELOG-v4.1.0.md
View File

@@ -1,302 +0,0 @@
# UI Design Workflow v4.1.0 - 纯矩阵模式 + 路径修正
## 📋 发布日期
2025-10-09
## 🎯 核心变更
### 1. 矩阵模式成为唯一模式
- ❌ 移除 standard/creative 模式选择
- ✅ 3×3 矩阵生成为默认且唯一模式
- ✅ 直接支持 `--style-variants` 和 `--layout-variants` 参数
### 2. 路径符合workflow架构
- ✅ 有session: `.workflow/WFS-{session_id}/runs/run-xxx/`
- ✅ 无session: `.workflow/.scratchpad/{session_id}/runs/run-xxx/`
- ✅ 模板移至全局: `~/.claude/workflows/_template-compare-matrix.html`
---
## 📝 文件修改清单
### 核心命令文件
| 文件 | 主要变更 | 状态 |
|------|---------|------|
| **auto.md** | 删除模式选择，简化Phase 3，修正路径 | ✅ 已完成 |
| **generate.md** | 完全重构为矩阵模式，集成模板 | ✅ 已完成 |
| **consolidate.md** | 修正standalone路径 | ✅ 已完成 |
| **extract.md** | 修正standalone路径 | ✅ 已完成 |
| **update.md** | 仅session模式，无需修改 | ✅ 保持不变 |
### 新增文件
- ✅ `~/.claude/workflows/_template-compare-matrix.html` - 交互式矩阵可视化模板
---
## 🔄 参数变更
### 旧参数（废弃）
```bash
--variants <count> # 统一变种数
--creative-variants <count> # 创意变种数
--matrix-mode # 模式标志
```
### 新参数（v4.1.0）
```bash
--style-variants <count> # 风格变种数（默认3）
--layout-variants <count> # 布局变种数（默认3）
# 矩阵为默认模式，无需标志
```
---
## 🚀 工作流对比
### v4.0.x（旧版）
```bash
/workflow:ui-design:auto --variants 3 --creative-variants 4
# 问题:
# - 参数混淆（variants vs creative-variants）
# - 模式选择复杂
# - standalone输出到项目根目录
```
### v4.1.0（新版）
```bash
/workflow:ui-design:auto --style-variants 3 --layout-variants 3
# 优势:
# - 参数语义清晰
# - 唯一矩阵模式
# - 输出到 .workflow/.scratchpad/
# - 总计: 3×3×N 个原型
```
---
## 📊 路径架构
### Standalone模式（无session）
```
.workflow/.scratchpad/
└── design-session-20251009-101530/
└── runs/
├── run-20251009-101530/
│ └── .design/
│ ├── style-extraction/style-cards.json
│ ├── style-consolidation/
│ │ ├── style-1/design-tokens.json
│ │ ├── style-2/design-tokens.json
│ │ └── style-3/design-tokens.json
│ └── prototypes/
│ ├── compare.html (交互式3×3矩阵)
│ ├── index.html
│ └── {page}-style-{s}-layout-{l}.html
└── latest -> run-20251009-101530/
```
### 集成模式（有session）
```
.workflow/WFS-auth-system/
├── workflow-session.json
├── IMPL_PLAN.md
├── .brainstorming/synthesis-specification.md
└── runs/
├── run-20251009-101530/
│ └── .design/ (同上)
└── latest -> run-20251009-101530/
```
---
## 🔧 核心改进
### 1. 简化架构
- **auto.md Phase 3**: 从复杂并行Task循环简化为单一命令
```bash
# 旧方式（30+行）
FOR style_id IN range(...):
Task(conceptual-planning-agent): "..."
# 新方式（3行）
command = "/workflow:ui-design:generate --style-variants {s} --layout-variants {l}"
SlashCommand(command=command)
```
### 2. 路径规范化
```bash
# auto.md - Phase 0b
IF --session:
base_path = ".workflow/WFS-{session_id}/runs/${run_id}"
ELSE:
base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}"
# generate/consolidate/extract
base_path = find_latest_design_session(".workflow/.scratchpad/")
```
### 3. 可视化增强
- 集成高级 `_template-compare-matrix.html` 模板
- 3×3 网格矩阵视图
- 同步滚动 + 缩放控制
- 全屏模式 + 选择导出
---
## ⚠️ 破坏性变更
### 1. 参数废弃
```bash
# ❌ 不再支持
--variants <count>
--creative-variants <count>
# ✅ 必须使用
--style-variants <count>
--layout-variants <count>
```
### 2. 文件命名强制统一
```bash
# ❌ 旧格式不再生成
{page}-variant-{n}.html
{page}-creative-variant-{n}.html
# ✅ 强制新格式
{page}-style-{s}-layout-{l}.html
```
### 3. Standalone路径变更
```bash
# ❌ v4.0.x
./design-session-xxx/ (项目根目录)
# ✅ v4.1.0
.workflow/.scratchpad/design-session-xxx/
```
---
## 📖 迁移指南
### 从 v4.0.x 迁移
#### 1. 更新命令参数
```bash
# 旧方式
/workflow:ui-design:auto --variants 3 --creative-variants 4
# 新方式
/workflow:ui-design:auto --style-variants 3 --layout-variants 4
# 或依赖智能解析
/workflow:ui-design:auto --prompt "Generate 3 styles with 4 layouts"
```
#### 2. 更新路径引用
```bash
# 旧standalone输出
./design-session-xxx/
# 新standalone输出
.workflow/.scratchpad/design-session-xxx/
# 迁移建议: 手动移动旧目录或保留为历史
mv ./design-session-* .workflow/.scratchpad/
```
#### 3. 预览文件
```bash
# 保持不变
{base_path}/.design/prototypes/compare.html
{base_path}/.design/prototypes/index.html
```
---
## ✅ 向后兼容性
### 完全兼容
- ✅ `--session` 参数
- ✅ `--pages` 参数
- ✅ `--prompt` 参数
- ✅ `--images` 参数
- ✅ `--batch-plan` 标志
- ✅ 智能prompt解析
### 不兼容
- ❌ standard/creative 模式选择
- ❌ 旧参数 `--variants`, `--creative-variants`
- ❌ 旧文件命名格式
---
## 🧪 测试清单
### 功能测试
- [ ] 默认3×3矩阵生成
- [ ] 自定义矩阵（2×2, 4×3等）
- [ ] 智能prompt解析
- [ ] 文件命名正确性
- [ ] compare.html 可视化
### 路径测试
- [ ] Standalone输出到 `.scratchpad`
- [ ] Session输出到 `WFS-{id}`
- [ ] latest symlink正确
- [ ] 跨命令路径传递
### 集成测试
- [ ] auto → extract → consolidate → generate → update
- [ ] 模板正确加载
- [ ] 设计token引用正确
---
## 📚 相关文档
- **workflow-architecture.md**: Workflow系统架构标准
- **_run-manager.md**: Run-based文件管理文档（如果需要）
- **~/.claude/workflows/_template-compare-matrix.html**: 可视化模板
---
## 🔮 未来增强
### 计划中
- [ ] 自定义布局策略（覆盖默认 Classic/Modern/Minimal）
- [ ] compare.html 运行历史对比
- [ ] Scratchpad自动清理策略
- [ ] Session升级工作流（scratchpad → WFS）
### 待讨论
- [ ] 非矩形矩阵支持（2×3）
- [ ] 恢复 creative 模式（可选）
- [ ] 更多布局变种（>5）
---
## 📝 总结
**v4.1.0 核心价值**:
1. **极简哲学**: 移除模式选择，矩阵为唯一模式
2. **清晰参数**: `--style-variants` 和 `--layout-variants` 语义明确
3. **架构规范**: 严格遵循 workflow-architecture.md 标准
4. **集中管理**: 所有输出在 `.workflow/` 下
5. **可视化增强**: 高级交互式矩阵界面
**升级理由**:
- ✅ 系统化设计探索（风格×布局矩阵）
- ✅ 简化工作流、减少参数困惑
- ✅ 符合workflow架构标准
- ✅ 避免项目根目录污染
---
**发布者**: Claude Code
**版本**: v4.1.0
**类型**: Major Refactoring + Path Corrections
**日期**: 2025-10-09

219
CHANGELOG-v4.1.1.md
View File

@@ -1,219 +0,0 @@
# UI Design Workflow v4.1.1 - Symlink Fix & Agent Optimization
## 📋 发布日期
2025-10-09
## 🎯 核心修复与优化
### 1. Windows 符号链接修复
- **问题**：`latest` 被创建为实际目录而非符号链接，导致创建两套重复目录
- **根本原因**：使用 `ln -s`（Unix 命令）在 Windows 环境下失败
- **解决方案**：改用 Windows 原生命令 `mklink /D`
- **影响范围**：auto.md Phase 0b
### 2. Agent 任务分配优化
- **旧策略**：按 style 分配（Agent-1 处理 style-1 的所有 layouts）
- **新策略**：按 layout 分配（Agent-1 处理 layout-1 的所有 styles）
- **批处理**：支持最多 8 个 styles per agent（超过 8 个 styles 时自动分批）
- **优势**：
- 同一 agent 处理不同 styles（复用 layout 策略）
- 不同 agent 处理不同 layouts（并行优化）
- 扩展性提升：32 styles × 3 layouts = 12 agents（原方案需 32 agents）
---
## 📝 文件修改清单
| 文件 | 主要变更 | 状态 |
|------|---------|------|
| **auto.md** | 修复 Windows 符号链接创建逻辑 | ✅ 已完成 |
| **generate.md** | 重构 agent 分配策略为 layout-based | ✅ 已完成 |
---
## 🔄 技术细节
### 修复 1: Symlink Creation (auto.md)
#### 旧代码（错误）
```bash
# Phase 0b
Bash(rm -f ".workflow/WFS-{session_id}/latest")
Bash(ln -s "runs/${run_id}" ".workflow/WFS-{session_id}/latest")
```
**问题**：
- `ln -s` 在 Windows 下失败时会创建实际目录
- 导致 `latest/` 和 `runs/run-xxx/` 两套重复目录
#### 新代码（修复）
```bash
# Phase 0b - Windows-compatible
Bash(cd ".workflow/WFS-{session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}")
```
**改进**：
- 使用 `mklink /D`（Windows 原生目录符号链接命令）
- `cd` 到父目录确保相对路径正确
- `rm -rf` 清理旧的目录/符号链接
---
### 优化 2: Agent Allocation (generate.md)
#### 旧策略（Style-Based）
```bash
FOR style_id IN range(1, style_variants + 1):
Task(agent): "Generate all layouts for style-{style_id}"
```
**问题**：
- 16 styles → 16 agents
- 32 styles → 32 agents（扩展性差）
#### 新策略（Layout-Based with Batching）
```bash
# Calculate style batches (max 8 styles per agent)
batch_size = 8
all_style_ids = range(1, style_variants + 1)
style_batches = split_into_chunks(all_style_ids, batch_size)
FOR layout_id IN range(1, layout_variants + 1):
FOR style_batch IN style_batches:
Task(agent): "
Generate layout-{layout_id} for styles {style_batch}
Context:
- LAYOUT_ID: {layout_id}
- STYLE_IDS_BATCH: {style_batch} # e.g., [1-8]
Strategy:
- Apply consistent layout-{layout_id} strategy to ALL styles in batch
- Load each style's design-tokens.json separately
"
```
**改进**：
- 按 layout 分配，每个 agent 专注一种 layout 策略
- 批处理支持：styles > 8 时自动分批
- 示例：32 styles × 3 layouts
- 旧方案：32 agents
- 新方案：3 layouts × 4 batches = **12 agents**
---
## 📊 性能对比
### Agent 数量对比表
| 配置 | 旧方案 (Style-Based) | 新方案 (Layout-Based) | 优化比例 |
|------|---------------------|----------------------|---------|
| 3×3 (默认) | 3 agents | 3 agents | 1:1 |
| 8×3 | 8 agents | 3 agents | 2.7:1 |
| 16×3 | 16 agents | 6 agents (3×2 batches) | 2.7:1 |
| 32×3 | 32 agents | 12 agents (3×4 batches) | 2.7:1 |
| 3×5 | 3 agents | 5 agents | 0.6:1 |
| 16×5 | 16 agents | 10 agents (5×2 batches) | 1.6:1 |
**结论**：layout 数量不变时，styles 增加不会线性增加 agent 数量
---
## 🚀 工作流影响
### 无影响的部分
- ✅ 矩阵模式逻辑（仍然是 styles × layouts）
- ✅ 文件命名格式（`{page}-style-{s}-layout-{l}.html`）
- ✅ 设计 token 加载机制
- ✅ 可视化模板（compare.html）
- ✅ 所有参数（--style-variants, --layout-variants）
### 改进的部分
- ✅ **符号链接正确性**：不再创建重复目录
- ✅ **Agent 扩展性**：高 variant 数场景下性能提升 2-3 倍
- ✅ **Layout 一致性**：同一 agent 负责一种 layout 策略，确保跨 styles 的 layout 一致性
---
## ⚠️ 破坏性变更
**无破坏性变更**
- 所有参数保持不变
- 输出文件格式保持不变
- API 接口保持不变
- 向后兼容 v4.1.0
---
## 🧪 测试建议
### 符号链接测试
```bash
# Windows 环境测试
/workflow:ui-design:auto --prompt "Test symlink" --style-variants 2
# 验证
cd .workflow/.scratchpad/design-session-*/
ls -la # 应看到 latest -> runs/run-xxx（符号链接，非目录）
```
### Agent 分配测试
```bash
# 小规模测试（3×3）
/workflow:ui-design:auto --style-variants 3 --layout-variants 3
# 预期：3 agents（每个 layout 1 个）
# 中规模测试（16×3）
/workflow:ui-design:auto --style-variants 16 --layout-variants 3
# 预期：6 agents（3 layouts × 2 batches）
# 大规模测试（32×3）
/workflow:ui-design:auto --style-variants 32 --layout-variants 3
# 预期：12 agents（3 layouts × 4 batches）
```
---
## 📚 相关文档
- **workflow-architecture.md**: Workflow 系统架构标准（符号链接规范）
- **CHANGELOG-v4.1.0.md**: 纯矩阵模式和路径修正
- **auto.md**: Phase 0b 符号链接创建逻辑
- **generate.md**: Phase 2 agent 分配策略
---
## 🔮 未来优化方向
### 计划中
- [ ] 自适应批处理大小（根据 agent 性能动态调整）
- [ ] Layout 策略配置化（允许自定义 layout 策略）
- [ ] 跨 runs 的 agent 结果缓存
### 待讨论
- [ ] 是否需要 style-based 模式作为备选？
- [ ] 批处理大小是否需要参数化（当前固定 8）？
---
## 📝 总结
**v4.1.1 核心价值**:
1. **跨平台兼容性**: Windows 环境符号链接正常工作
2. **扩展性提升**: 高 variant 数场景下 agent 数量减少 60%+
3. **Layout 一致性**: 同一 layout 策略由单一 agent 负责
4. **零破坏性**: 完全向后兼容 v4.1.0
**升级理由**:
- ✅ 修复 Windows 环境下的符号链接 bug
- ✅ 大幅提升高 variant 数场景的性能
- ✅ 改善 layout 策略的一致性
- ✅ 为未来扩展奠定基础
---
**发布者**: Claude Code
**版本**: v4.1.1
**类型**: Bugfix + Performance Optimization
**日期**: 2025-10-09

353
CHANGELOG-v4.2.0.md
View File

@@ -1,353 +0,0 @@
# UI Design Workflow v4.2.0 - Multi-Page Support Enhancement
## 📋 发布日期
2025-10-09
## 🎯 核心增强
### 多页面支持优化（基于 Gemini 分析）
本版本专注于改进多页面工作流的用户体验，基于 Gemini 对现有工作流的深入分析，实施了四项关键优化：
1. **改进 Prompt 解析可靠性** ✅
2. **增强跨页面对比可视化** ✅
3. **添加跨页面一致性验证** ✅
4. **改进原型选择粒度** ✅
---
## 📝 详细变更
### 1. 改进 Prompt 解析可靠性（auto.md）
#### 问题
- 基于自然语言的页面提取不可靠
- 没有用户确认机制
- 缺少页面名称验证
#### 解决方案
**增强的页面推断逻辑**（Phase 0c）：
```bash
# 多种解析模式
page_patterns = [
r"pages?:\s*([a-zA-Z,\s]+)", # "pages: home, about"
r"build:\s*([a-zA-Z,\s]+)", # "build: home, product"
r"create\s+([a-zA-Z,\s]+?)\s+pages?", # "create home and settings pages"
r"for\s+([a-zA-Z,\s]+?)\s+pages?", # "for dashboard and auth pages"
r":\s*([a-zA-Z,\s]+)$" # "Modern blog: home, article, author"
]
# 用户确认
REPORT: "📋 Extracted pages from prompt: {', '.join(page_list)}"
# 页面名称验证
IF regex_match(page, r"^[a-zA-Z0-9_-]+$"):
validated_pages.append(page)
ELSE:
REPORT: "⚠️ Skipping invalid page name: '{page}'"
```
**改进**：
- ✅ 5种不同的解析模式
- ✅ 实时用户确认（REPORT输出）
- ✅ 页面名称验证（仅允许字母、数字、连字符、下划线）
- ✅ 追踪页面来源（explicit/prompt_parsed/synthesis/default）
---
### 2. 增强跨页面对比可视化（compare.html）
#### 问题
- 只能查看单页面矩阵
- 无法并排对比不同页面
- 难以评估跨页面一致性
#### 解决方案
**新增 "Side-by-Side" 标签页**：
**功能特性**：
- 📊 独立选择器（页面、Style、Layout）
- 🔍 并排对比任意两个原型
- 📋 智能一致性提示
- ✅ 支持跨页面对比
**一致性提示示例**：
```javascript
if (pageA !== pageB && styleA === styleB) {
notes.push('✅ Same Style: Both prototypes use the same design system');
notes.push('📋 Shared Components: Verify header, navigation, footer consistency');
notes.push('🔗 User Journey: Assess transition flow between pages');
}
```
**用户体验**：
1. 选择 Prototype A（如：dashboard-s1-l2）
2. 选择 Prototype B（如：settings-s1-l2）
3. 点击 "🔍 Compare Selected Prototypes"
4. 并排查看 + 一致性建议
---
### 3. 添加跨页面一致性验证（generate.md）
#### 问题
- 并行生成各页面，无一致性保证
- 共享组件可能不一致
- 缺少验证机制
#### 解决方案
**新增 Phase 3.5: Cross-Page Consistency Validation**
**条件**: 仅在 `len(page_list) > 1` 时执行
**验证内容**：
1. **共享组件一致性**
- Header/Navigation 结构
- Footer 内容和样式
- 通用 UI 元素（buttons, forms, cards）
2. **Token 使用一致性**
- Design tokens 文件引用
- CSS 变量使用
- 间距、排版、颜色应用
3. **无障碍一致性**
- ARIA 属性
- Heading 层级（h1 unique, h2-h6 consistent）
- Landmark roles
4. **Layout 策略遵循**
- 跨页面 layout 一致性
- 响应式断点
- Grid/Flex 系统
**输出文件**：
```
.design/prototypes/
├── consistency-report-s1-l1.md # Style 1 Layout 1 跨页面报告
├── consistency-report-s1-l2.md
├── ...
└── CONSISTENCY_SUMMARY.md # 汇总报告
```
**报告格式**：
```markdown
# Cross-Page Consistency Report
**Style**: 1 | **Layout**: 2 | **Pages**: dashboard, settings, profile
## ✅ Passed Checks
- Header structure identical across all pages
- Footer styling matches
- Same design-tokens.json referenced
## ⚠️ Warnings
- Minor spacing variation in navigation (dashboard: 2rem, settings: 1.5rem)
## ❌ Issues
- Button classes inconsistent (dashboard: .btn-primary, settings: .button-primary)
## Recommendations
- Standardize button class names
- Create shared header/footer components
```
---
### 4. 改进原型选择粒度（compare.html）
#### 问题
- 只能逐个选择原型
- 无法批量选择某个 style/layout
- 选择大量原型效率低
#### 解决方案
**新增快速选择功能**：
**按钮**：
- 🎨 **By Style**: 选择某个 style 的所有 layouts
- 📐 **By Layout**: 选择某个 layout 的所有 styles
- 🗑️ **Clear All**: 清除所有选择
**交互流程**：
```javascript
// 按 Style 选择
User clicks "By Style" → Prompt: "Select style (1-3)?" → Input: 2
→ Selects: dashboard-s2-l1, dashboard-s2-l2, dashboard-s2-l3
// 按 Layout 选择
User clicks "By Layout" → Prompt: "Select layout (1-3)?" → Input: 1
→ Selects: dashboard-s1-l1, dashboard-s2-l1, dashboard-s3-l1
```
**导出增强**：
```json
{
"runId": "run-20251009-143000",
"sessionId": "design-session-xxx",
"timestamp": "2025-10-09T14:30:00Z",
"selections": [
{"id": "dashboard-s2-l1", "file": "dashboard-style-2-layout-1.html"},
{"id": "dashboard-s2-l2", "file": "dashboard-style-2-layout-2.html"},
{"id": "settings-s1-l3", "file": "settings-style-1-layout-3.html"}
]
}
```
---
## 📊 文件修改清单
| 文件 | 主要变更 | 状态 |
|------|---------|------|
| **auto.md** | Phase 0c 页面推断逻辑增强 | ✅ 已完成 |
| **generate.md** | 新增 Phase 3.5 跨页面一致性验证 | ✅ 已完成 |
| **_template-compare-matrix.html** | 跨页面对比 + 快速选择 | ✅ 已完成 |
---
## 🚀 工作流对比
### v4.1.x（旧版）
```bash
/workflow:ui-design:auto --prompt "Modern blog with home, article, author"
问题:
- Prompt 解析可能失败
- 只能逐页查看矩阵
- 无一致性验证
- 逐个选择原型
```
### v4.2.0（新版）
```bash
/workflow:ui-design:auto --prompt "Modern blog: home, article, author"
# Phase 0c - 智能解析 + 确认
📋 Extracted pages from prompt: home, article, author
# Phase 3.5 - 一致性验证（自动）
生成: consistency-report-s1-l1.md, consistency-report-s1-l2.md, ...
CONSISTENCY_SUMMARY.md
# compare.html - 增强功能
✅ 并排对比: home-s1-l2 vs article-s1-l2
✅ 快速选择: "By Style 1" → 选择所有 Style 1 原型
✅ 导出: selection-run-xxx.json
```
---
## ⚠️ 破坏性变更
**无破坏性变更** - 完全向后兼容 v4.1.1
所有新功能都是**增强**而非替换：
- Phase 0c 保留原有逻辑，仅增强解析
- Phase 3.5 为可选步骤（仅多页面时执行）
- compare.html 保留原有 Matrix View，增加新标签页
---
## 🧪 测试建议
### 1. Prompt 解析测试
```bash
# 测试各种 prompt 格式
/workflow:ui-design:auto --prompt "pages: home, about, contact"
/workflow:ui-design:auto --prompt "build: dashboard, settings, profile"
/workflow:ui-design:auto --prompt "create home and pricing pages"
/workflow:ui-design:auto --prompt "Modern SaaS: dashboard, analytics"
# 验证
- 检查提取的页面是否正确
- 查看确认消息
- 验证无效页面名是否被过滤
```
### 2. 跨页面对比测试
```bash
# 生成多页面原型
/workflow:ui-design:auto --pages "home,about,contact" --style-variants 2 --layout-variants 2
# 测试对比功能
1. 打开 compare.html
2. 切换到 "Side-by-Side" 标签
3. 选择: Prototype A = home-s1-l1, Prototype B = about-s1-l1
4. 查看一致性提示
```
### 3. 一致性验证测试
```bash
# 多页面工作流
/workflow:ui-design:auto --pages "dashboard,settings" --style-variants 2 --layout-variants 2
# 验证
- 检查是否生成 consistency-report-*.md
- 检查 CONSISTENCY_SUMMARY.md
- 验证报告内容准确性
```
### 4. 快速选择测试
```bash
1. 打开 compare.html
2. 点击 "By Style" → 输入 "1"
3. 验证是否选择了所有 Style 1 的原型
4. 点击 "By Layout" → 输入 "2"
5. 验证是否选择了所有 Layout 2 的原型
6. 点击 "Clear All" → 验证是否清除所有选择
7. 导出选择 → 验证 JSON 格式正确
```
---
## 📚 相关文档
- **Gemini 分析报告**: 识别了 4 个关键问题
- **workflow-architecture.md**: Workflow 系统架构标准
- **CHANGELOG-v4.1.1.md**: Agent 优化和符号链接修复
- **auto.md**: Phase 0c 页面推断逻辑
- **generate.md**: Phase 3.5 跨页面一致性验证
- **_template-compare-matrix.html**: 跨页面对比 UI
---
## 🔮 未来增强
### 计划中
- [ ] 页面模板系统（预定义页面类型：home, dashboard, auth, etc.）
- [ ] 跨 runs 对比功能（对比不同运行的同一原型）
- [ ] AI 驱动的一致性自动修复
### 待讨论
- [ ] 是否需要页面依赖关系定义（如：dashboard 依赖 auth）
- [ ] 是否需要页面分组功能（如：public pages vs. admin pages）
---
## 📝 总结
**v4.2.0 核心价值**:
1. **智能解析**: 多模式 prompt 解析 + 实时确认
2. **可视化增强**: 跨页面并排对比 + 一致性提示
3. **质量保证**: 自动一致性验证报告
4. **效率提升**: 批量选择 + 快速导出
**升级理由**:
- ✅ 解决 Gemini 分析识别的 4 个关键问题
- ✅ 大幅改善多页面工作流用户体验
- ✅ 提供一致性保证机制
- ✅ 零破坏性，完全向后兼容
**适用场景**:
- 多页面应用设计（SaaS, 电商, 博客等）
- 需要跨页面一致性验证的项目
- 大量原型快速筛选和对比
---
**发布者**: Claude Code
**版本**: v4.2.0
**类型**: Feature Enhancement (Multi-Page Support)
**日期**: 2025-10-09
**基于**: Gemini 深度分析报告

83
CHANGELOG.md
View File

@@ -5,6 +5,89 @@ All notable changes to Claude Code Workflow (CCW) will be documented in this fil
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [4.2.1] - 2025-10-09
### 📝 Documentation Refactoring: UI Design Workflow Commands
This release refactors UI design workflow documentation for improved clarity and maintainability, with significant size reductions while preserving all functionality.
#### Changed
**explore-auto.md** (formerly `auto.md`):
- **File Reorganization**: Reduced from 540 to 435 lines (19.4% reduction)
- **Merged Duplicate Content**: Consolidated Overview, Coordinator Role, and Execution Model into single "Overview & Execution Model" section
- **Simplified Core Rules**: From verbose descriptions to 5 concise rules
- **Streamlined TodoWrite Pattern**: From detailed steps to concise mode with comments
- **Preserved Functionality**: All 6-phase execution logic, intelligent parsing, interactive confirmation, and matrix mode intact
**imitate-auto.md** (NEW command):
- **File Reorganization**: Reduced from 566 to 475 lines (16.1% reduction)
- **Merged Sections**: Combined Overview, Core Philosophy, Execution Model, and Workflow Position into unified structure
- **Simplified Phase 0.5**: Screenshot capture logic complete but reduced redundant error handling
- **Consolidated Performance**: Merged "Key Differences" and "Performance Benefits" into single comparison table
- **Preserved Functionality**: All 5-phase execution, auto-screenshot mechanism, direct token extraction, and error handling intact
#### Improved
**Documentation Quality**:
- 📚 Clearer structure with merged duplicate concepts
- 🎯 Reduced redundancy across command documentation
- ✨ Consistent formatting and organization patterns
- 📖 Improved maintainability with better content separation
- 🔍 All key functionality points preserved and highlighted
**Total Impact**:
- **explore-auto.md**: 105 lines removed (19.4% reduction)
- **imitate-auto.md**: 91 lines removed (16.1% reduction)
- **Combined**: 196 lines of documentation optimized
- **Zero functionality loss**: All features, workflows, and technical details preserved
## [4.2.0] - 2025-10-09
### 🎯 Multi-Page Support Enhancement
Based on Gemini's analysis of the UI Design Workflow, this version implements four key optimizations to improve the multi-page design experience.
#### Added
- **Cross-Page Consistency Validation**: New `Phase 3.5` in `generate` command automatically validates design consistency (shared components, tokens, accessibility) across multiple pages
- **Side-by-Side Prototype Comparison**: `compare.html` preview tool now includes "Side-by-Side" tab to compare any two prototypes with intelligent consistency hints
- **Batch Prototype Selection**: `compare.html` features "By Style" and "By Layout" buttons for quick bulk prototype selection
#### Changed
- **Enhanced Page Inference**: `auto` command's page detection uses multiple regex patterns with interactive user confirmation
- **Improved Export**: Selection export from `compare.html` is now more structured with detailed metadata
## [4.1.1] - 2025-10-09
### 🔧 Symlink Fix & Agent Optimization
#### Fixed
- **Windows Symbolic Link Creation**: Corrected `auto.md` workflow to use `mklink /D` on Windows, preventing duplicate directories instead of symlinks
#### Changed
- **Agent Allocation Strategy**: `generate.md` now allocates tasks by layout (layout-based) instead of style, improving performance and consistency for high variant counts by having one agent handle one layout strategy across multiple styles
## [4.1.0] - 2025-10-09
### 🔄 Matrix-Only UI Design Workflow
#### Changed
- **Matrix Mode by Default**: UI Design workflow now exclusively uses `style × layout` matrix mode with `--style-variants` and `--layout-variants` as standard parameters
- **Path Standardization**: Standalone design sessions saved to `.workflow/.scratchpad/` adhering to project architecture
- **Simplified Orchestration**: `auto.md` command simplified to use single `SlashCommand` for generation phase, removing complex loop logic
#### Removed
- **Deprecated Parameters**: Removed `--variants` and `--creative-variants` in favor of explicit `--style-variants` and `--layout-variants`
- **Standard/Creative Modes**: Distinction between these modes removed
---
## [4.0.2] - 2025-10-09
### 🔄 UI Design Workflow - Complete Refactoring

107
README.md
View File

@@ -2,7 +2,7 @@
<div align="center">
[![Version](https://img.shields.io/badge/version-v4.0.1-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
[![Version](https://img.shields.io/badge/version-v4.2.1-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
[![MCP Tools](https://img.shields.io/badge/🔧_MCP_Tools-Experimental-orange.svg)](https://github.com/modelcontextprotocol)
@@ -15,16 +15,13 @@
**Claude Code Workflow (CCW)** is a next-generation multi-agent automation framework that orchestrates complex software development tasks through intelligent workflow management and autonomous execution.
> **🎉 Latest: v4.0.1** - UI Design Workflow V2 with Intelligent Page Inference & Agent Mode. See [CHANGELOG.md](CHANGELOG.md) for details.
> **🎉 Latest: v4.2.1** - Documentation Refactoring for UI Design Workflow. See [CHANGELOG.md](CHANGELOG.md) for details.
>
> **What's New in v4.0.1**:
> - 🧠 **Intelligent Page Inference**: Pages auto-extracted from prompt text - no need to specify `--pages` manually
> - 🤖 **Agent Creative Mode**: `--use-agent` enables parallel exploration of diverse design directions
> - 🎯 **Unified Variant Control**: Single `--variants` parameter controls both style cards and UI prototypes
> - 🔀 **Dual Mode Support**: Standalone (quick prototyping) or Integrated (workflow enhancement)
> - 💬 **Dual Input Sources**: Images, text prompts, or hybrid (text guides image analysis)
> - ✨ **Extreme Simplification**: All parameters optional with smart defaults
> - ⚡ **Parallel Execution**: Agent mode generates variants concurrently for speed
> **What's New in v4.2.1**:
> - 📚 **Documentation Optimization**: Reduced file sizes by 15-20% while preserving all functionality
> - 🎯 **Clearer Structure**: Merged duplicate concepts and streamlined content organization
> - ✨ **Improved Maintainability**: Better content separation and consistent formatting patterns
> - 📖 **Zero Functionality Loss**: All features, workflows, and technical details preserved
---
@@ -253,24 +250,27 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
**Phase 2: UI Design Refinement** *(Optional for UI-heavy projects)*
```bash
# Simplest - pages inferred from prompt (v4.0.2+)
/workflow:ui-design:auto --prompt "Modern blog with home, article and author pages, dark theme"
# Matrix Exploration Mode - Multiple style/layout variants (v4.2.1+)
/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" --style-variants 3 --layout-variants 2
# Fast Imitation Mode - Single design replication (v4.2.1+)
/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
# With session integration
/workflow:ui-design:auto --session WFS-auth --images "refs/*.png" --variants 3
/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
# Or run individual design phases
/workflow:ui-design:extract --images "refs/*.png" --variants 3
/workflow:ui-design:consolidate --variants "variant-1,variant-3"
/workflow:ui-design:generate --variants 2
/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 2
# Preview generated prototypes (NEW!)
# Option 1: Open .workflow/WFS-auth/.design/prototypes/index.html in browser
# Preview generated prototypes
# Option 1: Open .workflow/WFS-auth/.design/prototypes/compare.html in browser
# Option 2: Start local server
cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
# Visit http://localhost:8080 for interactive preview with comparison tools
/workflow:ui-design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
```
**Phase 3: Action Planning**
@@ -364,11 +364,12 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|---|---|
| `/workflow:session:*` | Manage development sessions (`start`, `pause`, `resume`, `list`, `switch`, `complete`). |
| `/workflow:brainstorm:*` | Use role-based agents for multi-perspective planning. |
| `/workflow:ui-design:auto` | **v4.0.2** UI design workflow with pure Claude execution. All parameters optional, no external tools. |
| `/workflow:ui-design:extract` | **v4.0.2** Extract design from images/text using Claude-native analysis. Single-pass variant generation. |
| `/workflow:ui-design:consolidate` | **v4.0.2** Consolidate style variants into validated design tokens using Claude synthesis. |
| `/workflow:ui-design:generate` | **v4.0.2** Generate token-driven HTML/CSS prototypes with agent-based execution. |
| `/workflow:ui-design:update` | **v4.0.2** Integrate finalized design system into brainstorming artifacts. |
| `/workflow:ui-design:explore-auto` | **v4.2.1** Matrix exploration mode - Generate multiple style × layout variants for comprehensive design exploration. |
| `/workflow:ui-design:imitate-auto` | **v4.2.1** Fast imitation mode - Rapid single-design replication with auto-screenshot and direct token extraction. |
| `/workflow:ui-design:extract` | **v4.2.1** Extract design from images/text using Claude-native analysis. Single-pass variant generation. |
| `/workflow:ui-design:consolidate` | **v4.2.1** Consolidate style variants into validated design tokens using Claude synthesis. |
| `/workflow:ui-design:generate` | **v4.2.1** Generate token-driven HTML/CSS prototypes in matrix mode (style × layout combinations). |
| `/workflow:ui-design:update` | **v4.2.1** Integrate finalized design system into brainstorming artifacts. |
| `/workflow:plan` | Create a detailed, executable plan from a description. |
| `/workflow:tdd-plan` | Create TDD workflow (6 phases) with test coverage analysis and Red-Green-Refactor cycles. |
| `/workflow:execute` | Execute the current workflow plan autonomously. |
@@ -380,31 +381,44 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
| `/workflow:tools:test-concept-enhanced` | Generate test strategy and requirements analysis using Gemini. |
| `/workflow:tools:test-task-generate` | Generate test task JSON with test-fix-cycle specification. |
### **UI Design Workflow Commands (`/workflow:ui-design:*`)** *(v4.0.2)*
### **UI Design Workflow Commands (`/workflow:ui-design:*`)** *(v4.2.1)*
The design workflow system provides complete UI design refinement with **pure Claude execution**, **intelligent page inference**, and **zero external dependencies**.
#### Core Commands
**`/workflow:ui-design:auto`** - Complete workflow orchestrator
**`/workflow:ui-design:explore-auto`** - Matrix exploration mode
```bash
# Simplest - pages auto-inferred from prompt (v4.0.2)
/workflow:ui-design:auto --prompt "Modern blog with home, article and author pages, dark theme"
# Comprehensive exploration - multiple style × layout variants
/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" --style-variants 3 --layout-variants 2
# Multiple style variants
/workflow:ui-design:auto --prompt "SaaS dashboard and settings" --variants 3
# With images and session integration
/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
# Hybrid: images + text prompt
/workflow:ui-design:auto --images "refs/*.png" --prompt "E-commerce: home, product, cart"
# Integrated with session + creative mode
/workflow:ui-design:auto --session WFS-auth --images "refs/*.png" --variants 2 --creative-variants 3
# Text-only mode with page inference
/workflow:ui-design:explore-auto --prompt "E-commerce: home, product, cart" --style-variants 2 --layout-variants 2
```
- **🆕 Pure Claude**: No external tools (gemini-wrapper, codex) required
- **🆕 Zero Dependencies**: All analysis and generation done natively
- **All Parameters Optional**: Smart defaults and inference for everything
- **Page Inference**: Auto-extract pages from `--prompt` text
- **Dual Mode**: Standalone (quick prototyping) or Integrated (workflow enhancement)
- **🎯 Matrix Mode**: Generate all style × layout combinations
- **📊 Comprehensive Exploration**: Compare multiple design directions
- **🔍 Interactive Comparison**: Side-by-side comparison with viewport controls
- **✅ Cross-page Validation**: Automatic consistency checks for multi-page designs
- **⚡ Batch Selection**: Quick selection by style or layout
**`/workflow:ui-design:imitate-auto`** - Fast imitation mode
```bash
# Rapid single-design replication
/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
# With session integration
/workflow:ui-design:imitate-auto --session WFS-auth --images "refs/ui.png" --pages "home,product"
# Auto-screenshot from URL (requires Playwright)
/workflow:ui-design:imitate-auto --url "https://example.com" --pages "landing"
```
- **⚡ Speed Optimized**: 5-10x faster than explore-auto
- **📸 Auto-Screenshot**: Automatic URL screenshot capture with Playwright/Chrome
- **🎯 Direct Extraction**: Skip variant selection, go straight to implementation
- **🔧 Single Design Focus**: Best for copying existing designs quickly
**`/workflow:ui-design:extract`** - Style analysis with dual input sources
```bash
@@ -433,16 +447,17 @@ The design workflow system provides complete UI design refinement with **pure Cl
**`/workflow:ui-design:generate`** - Generate HTML/CSS prototypes
```bash
# Standard mode (consistent layouts)
/workflow:ui-design:generate --pages "dashboard,auth" --variants 2
# Matrix mode - style × layout combinations
/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 3
# Creative mode (diverse layout exploration)
/workflow:ui-design:generate --pages "home,product,cart" --creative-variants 3
# Single page with multiple variants
/workflow:ui-design:generate --pages "home" --style-variants 3 --layout-variants 2
```
- **Page Inference**: Auto-detect from session or default to `["home"]`
- **Agent-Only**: Task(conceptual-planning-agent) execution
- **Creative Mode**: Parallel agents for diverse layout strategies
- **Preview Files**: `index.html`, `compare.html`, `PREVIEW.md`
- **🎯 Matrix Generation**: Creates all style × layout combinations
- **📊 Multi-page Support**: Consistent design system across pages
- **✅ Consistency Validation**: Automatic cross-page consistency reports (v4.2.0+)
- **🔍 Interactive Preview**: `compare.html` with side-by-side comparison
- **📋 Batch Selection**: Quick selection by style or layout filters
**`/workflow:ui-design:update`** - Integrate design system
```bash

119
README_CN.md
View File

@@ -2,7 +2,7 @@
<div align="center">
[![Version](https://img.shields.io/badge/version-v3.5.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
[![Version](https://img.shields.io/badge/version-v4.2.1-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
[![MCP工具](https://img.shields.io/badge/🔧_MCP工具-实验性-orange.svg)](https://github.com/modelcontextprotocol)
@@ -15,16 +15,13 @@
**Claude Code Workflow (CCW)** 是一个新一代的多智能体自动化开发框架，通过智能工作流管理和自主执行来协调复杂的软件开发任务。
> **🎉 最新版本: v3.5.0** - UI 设计工作流与三重视觉分析。详见 [CHANGELOG.md](CHANGELOG.md)。
> **🎉 最新版本: v4.2.1** - UI 设计工作流文档重构。详见 [CHANGELOG.md](CHANGELOG.md)。
>
> **v3.5.0 版本新特性**:
> - 🎨 **UI 设计工作流**: 从风格提取到原型生成的完整设计精炼工作流
> - 👁️ **三重视觉分析**: 融合 Claude Code + Gemini + Codex 视觉能力进行综合风格提取
> - ⏸️ **交互式检查点**: 用户选择风格变体和原型确认的决策点
> - 🎯 **零智能体开销**: CLI 工具直接 bash 执行，移除不必要的智能体包装
> - 🎨 **风格自定义**: 通过 `--style-overrides` 参数支持运行时样式覆盖
> - 📦 **批量任务生成**: 使用 `--batch-plan` 为选定原型自动创建实现任务
> - 🔄 **半自主工作流**: 在关键设计决策点由用户驱动继续
> **v4.2.1 版本新特性**:
> - 📚 **文档优化**: 文件大小减少 15-20%，同时保留所有功能
> - 🎯 **更清晰的结构**: 合并重复概念，优化内容组织
> - ✨ **改进的可维护性**: 更好的内容分离和一致的格式模式
> - 📖 **零功能损失**: 保留所有特性、工作流和技术细节
---
@@ -253,21 +250,27 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
**阶段 2：UI 设计精炼** *(UI 密集型项目可选)*
```bash
# 从参考图像中提取设计风格并生成原型
/workflow:ui-design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" --batch-plan
# 矩阵探索模式 - 多个风格×布局变体（v4.2.1+）
/workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2
# 快速模仿模式 - 单一设计快速复制（v4.2.1+）
/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
# 与会话集成
/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
# 或者运行单独的设计阶段
/workflow:ui-design:style-extract --session WFS-auth --images "refs/*.png"
/workflow:ui-design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
/workflow:ui-design:ui-generate --session WFS-auth --pages "login,register" --variants 2
/workflow:ui-design:extract --images "refs/*.png" --variants 3
/workflow:ui-design:consolidate --variants "variant-1,variant-3"
/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 2
# 预览生成的原型（新功能！）
# 选项1：在浏览器中打开 .workflow/WFS-auth/.design/prototypes/index.html
# 预览生成的原型
# 选项1：在浏览器中打开 .workflow/WFS-auth/.design/prototypes/compare.html
# 选项2：启动本地服务器
cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
# 访问 http://localhost:8080 获取交互式预览和对比工具
/workflow:ui-design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
```
**阶段 3：行动规划**
@@ -361,11 +364,12 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|---|---|
| `/workflow:session:*` | 管理开发会话（`start`, `pause`, `resume`, `list`, `switch`, `complete`）。 |
| `/workflow:brainstorm:*` | 使用基于角色的智能体进行多视角规划。 |
| `/workflow:ui-design:auto` | **新增** 带交互式检查点的半自主 UI 设计工作流，用于风格和原型选择。 |
| `/workflow:ui-design:style-extract` | **新增** 使用三重视觉分析（Claude + Gemini + Codex）从参考图像提取设计风格。 |
| `/workflow:ui-design:style-consolidate` | **新增** 将选定的风格变体整合为经过验证的设计令牌和风格指南。 |
| `/workflow:ui-design:ui-generate` | **新增** 生成基于令牌的 HTML/CSS 原型，支持可选的风格覆盖。 |
| `/workflow:ui-design:design-update` | **新增** 将最终确定的设计系统集成到头脑风暴产物中。 |
| `/workflow:ui-design:explore-auto` | **v4.2.1** 矩阵探索模式 - 生成多个风格×布局变体，全面探索设计方向。 |
| `/workflow:ui-design:imitate-auto` | **v4.2.1** 快速模仿模式 - 单一设计快速复制，自动截图和直接令牌提取。 |
| `/workflow:ui-design:extract` | **v4.2.1** 使用 Claude 原生分析从图像/文本提取设计。单次生成变体。 |
| `/workflow:ui-design:consolidate` | **v4.2.1** 使用 Claude 合成将风格变体整合为经过验证的设计令牌。 |
| `/workflow:ui-design:generate` | **v4.2.1** 生成矩阵模式（风格×布局组合）的令牌驱动 HTML/CSS 原型。 |
| `/workflow:ui-design:update` | **v4.2.1** 将最终确定的设计系统集成到头脑风暴产物中。 |
| `/workflow:plan` | 从描述创建详细、可执行的计划。 |
| `/workflow:tdd-plan` | 创建 TDD 工作流（6 阶段），包含测试覆盖分析和 Red-Green-Refactor 循环。 |
| `/workflow:execute` | 自主执行当前的工作流计划。 |
@@ -377,28 +381,44 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
| `/workflow:tools:test-concept-enhanced` | 使用 Gemini 生成测试策略和需求分析。 |
| `/workflow:tools:test-task-generate` | 生成测试任务 JSON，包含 test-fix-cycle 规范。 |
### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v3.5.0+)*
### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v4.2.1)*
设计工作流系统提供从风格提取到原型生成的完整 UI 设计精炼，配备交互式预览工具。
设计工作流系统提供完整的 UI 设计精炼，具备**纯 Claude 执行**、**智能页面推断**和**零外部依赖**。
#### 核心命令
**`/workflow:ui-design:auto`** - 完整工作流编排器
**`/workflow:ui-design:explore-auto`** - 矩阵探索模式
```bash
# 带用户检查点的半自主工作流
/workflow:ui-design:auto --session WFS-auth --images "refs/*.png" --pages "login,register"
/workflow:ui-design:auto --session WFS-dash --images "refs/*.jpg" --pages "dashboard" --variants 3 --batch-plan
```
- **检查点**: 用户选择风格变体（阶段1）和确认原型（阶段3）
- **可选**: `--batch-plan` 用于自动任务生成
# 全面探索 - 多个风格×布局变体
/workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2
**`/workflow:ui-design:style-extract`** - 三重视觉风格分析
```bash
# 从参考图像提取设计
/workflow:ui-design:style-extract --session WFS-auth --images "design-refs/*.png"
# 与图像和会话集成
/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
# 纯文本模式，带页面推断
/workflow:ui-design:explore-auto --prompt "电商：首页，产品，购物车" --style-variants 2 --layout-variants 2
```
- **视觉来源**: Claude Code + Gemini + Codex
- **输出**: 用于用户选择的风格变体卡片
- **🎯 矩阵模式**: 生成所有风格×布局组合
- **📊 全面探索**: 比较多个设计方向
- **🔍 交互式对比**: 带视口控制的并排比较
- **✅ 跨页面验证**: 多页面设计的自动一致性检查
- **⚡ 批量选择**: 按风格或布局快速选择
**`/workflow:ui-design:imitate-auto`** - 快速模仿模式
```bash
# 快速单一设计复制
/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
# 与会话集成
/workflow:ui-design:imitate-auto --session WFS-auth --images "refs/ui.png" --pages "home,product"
# 从 URL 自动截图（需要 Playwright）
/workflow:ui-design:imitate-auto --url "https://example.com" --pages "landing"
```
- **⚡ 速度优化**: 比 explore-auto 快 5-10 倍
- **📸 自动截图**: 使用 Playwright/Chrome 自动捕获 URL 截图
- **🎯 直接提取**: 跳过变体选择，直接进入实现
- **🔧 单一设计聚焦**: 最适合快速复制现有设计
**`/workflow:ui-design:style-consolidate`** - 验证和合并令牌
```bash
@@ -408,19 +428,24 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
- **功能**: WCAG AA 验证、OKLCH 颜色、W3C 令牌格式
- **输出**: `design-tokens.json`、`style-guide.md`、`tailwind.config.js`
**`/workflow:ui-design:ui-generate`** - 生成 HTML/CSS 原型
**`/workflow:ui-design:generate`** - 生成 HTML/CSS 原型
```bash
# 生成带预览工具的原型
/workflow:ui-design:ui-generate --session WFS-auth --pages "login,register" --variants 2
/workflow:ui-design:ui-generate --session WFS-auth --pages "dashboard" --style-overrides "custom.json"
```
- **🆕 预览文件**: `index.html`（导航）、`compare.html`（并排对比）、`PREVIEW.md`（说明）
- **功能**: 令牌驱动的 CSS、语义化 HTML5、ARIA 属性、响应式设计
# 矩阵模式 - 风格×布局组合
/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 3
**`/workflow:ui-design:design-update`** - 集成设计系统
# 单页面多变体
/workflow:ui-design:generate --pages "home" --style-variants 3 --layout-variants 2
```
- **🎯 矩阵生成**: 创建所有风格×布局组合
- **📊 多页面支持**: 跨页面一致的设计系统
- **✅ 一致性验证**: 自动跨页面一致性报告（v4.2.0+）
- **🔍 交互式预览**: `compare.html` 并排比较
- **📋 批量选择**: 按风格或布局过滤器快速选择
**`/workflow:ui-design:update`** - 集成设计系统
```bash
# 使用设计系统更新头脑风暴产物
/workflow:ui-design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
```
- **更新**: `synthesis-specification.md`、`ui-designer/style-guide.md`
- **使设计令牌可用于任务生成**