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.

2026-02-13 02:41:50 +08:00 · 2025-10-09 15:51:23 +08:00
parent 561a04c193
commit c7e2d6f82f
12 changed files with 1611 additions and 2103 deletions
--- a/.claude/commands/workflow/ui-design/consolidate.md
+++ b/.claude/commands/workflow/ui-design/consolidate.md
@@ -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