From 7c8e75f3637b44900b5da31c722f69dda4455051 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 11 Oct 2025 16:21:28 +0800 Subject: [PATCH] Release v4.4.0: UI Design Workflow V3 - Layout/Style Separation Architecture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Breaking Changes - **Command Renamed**: `extract` → `style-extract` - **New Required Phase**: `layout-extract` now mandatory before `generate` - **Workflow Changed**: Old flow (extract → consolidate → generate) → New flow (style-extract → consolidate → layout-extract → generate) ## Added **New Command: layout-extract** - Extract structural layout separate from visual style - Agent-powered with ui-design-agent - Dual-mode: imitate (high-fidelity) / explore (multiple variants) - Device-aware: desktop, mobile, tablet, responsive - MCP-integrated layout pattern research (explore mode) - Output: layout-templates.json with DOM structure + CSS layout rules **Enhanced Architecture** - Layout/Style Separation: Clear responsibility boundaries - Pure Assembler: generate command combines pre-extracted components - Device-Aware Layouts: Optimized structures for different devices - Token-Based CSS: var() placeholders for spacing/breakpoints ## Changed **style-extract (Renamed from extract)** - File renamed: extract.md → style-extract.md - Scope clarified: Visual style only (colors, typography, spacing) - No functionality change, all features preserved **generate (Refactored to Pure Assembler)** - Before: Agent designed layout + applied style - After: Pure assembly - combines layout-templates.json + design-tokens.json - No design logic: All decisions made in previous phases - Simplified agent instructions: Focus on assembly only **Workflow Commands Updated** - imitate-auto: Added Phase 2.5 (layout extraction) - explore-auto: Added Phase 2.5 (layout extraction) - Both workflows now include layout-extract step ## Removed - ❌ V2 Commands: generate-v2, explore-auto-v2 (merged into main commands) - ❌ Old extract command (renamed to style-extract) - ❌ ui-generate-preview-v2.sh (merged into ui-generate-preview.sh) ## Files Changed - Renamed: extract.md → style-extract.md - Added: layout-extract.md (370+ lines) - Modified: generate.md, imitate-auto.md, explore-auto.md, consolidate.md - Removed: 2 deprecated v2 command files - Updated: CHANGELOG.md, README.md ## Benefits - ✅ Single Responsibility: Each phase has one clear job - ✅ Better Layout Variety: Explore mode generates structurally distinct layouts - ✅ Reusability: Layout templates work with any style - ✅ Clarity: All structural decisions visible in layout-templates.json - ✅ Testability: Layout structure and visual style tested independently 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../workflow/ui-design/consolidate.md | 10 +- .../workflow/ui-design/explore-auto.md | 84 ++-- .../commands/workflow/ui-design/generate.md | 303 +++++++------- .../workflow/ui-design/imitate-auto.md | 117 ++++-- .../workflow/ui-design/layout-extract.md | 371 ++++++++++++++++++ .../{extract.md => style-extract.md} | 18 +- ...e-preview-v2.sh => ui-generate-preview.sh} | 2 +- CHANGELOG.md | 360 +++++++++++++++++ README.md | 90 +++-- 9 files changed, 1071 insertions(+), 284 deletions(-) create mode 100644 .claude/commands/workflow/ui-design/layout-extract.md rename .claude/commands/workflow/ui-design/{extract.md => style-extract.md} (89%) rename .claude/scripts/{ui-generate-preview-v2.sh => ui-generate-preview.sh} (99%) diff --git a/.claude/commands/workflow/ui-design/consolidate.md b/.claude/commands/workflow/ui-design/consolidate.md index 426249b8..98b73815 100644 --- a/.claude/commands/workflow/ui-design/consolidate.md +++ b/.claude/commands/workflow/ui-design/consolidate.md @@ -13,7 +13,7 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(*) # Design System Consolidation Command ## Overview -Consolidate style variants into independent production-ready design systems. Refines raw token proposals from `extract` into finalized design tokens and style guides. +Consolidate style variants into independent production-ready design systems. Refines raw token proposals from `style-extract` into finalized design tokens and style guides. **Strategy**: Philosophy-Driven Refinement - **Agent-Driven**: Uses ui-design-agent for N variant generation @@ -246,7 +246,7 @@ bash(ls -lh {base_path}/style-consolidation/style-1/) ### Common Errors ``` ERROR: No style cards found -→ Run /workflow:ui-design:extract first +→ Run /workflow:ui-design:style-extract first ERROR: Invalid variant count → List available count, auto-select all @@ -265,6 +265,8 @@ ERROR: Agent file creation failed ## Integration -**Input**: `style-cards.json` from `/workflow:ui-design:extract` +**Input**: `style-cards.json` from `/workflow:ui-design:style-extract` **Output**: `style-consolidation/style-{N}/` for each variant -**Next**: `/workflow:ui-design:generate --style-variants N --targets "..."` +**Next**: `/workflow:ui-design:generate --style-variants N` + +**Note**: After consolidate, use `/workflow:ui-design:layout-extract` to generate layout templates before running generate. diff --git a/.claude/commands/workflow/ui-design/explore-auto.md b/.claude/commands/workflow/ui-design/explore-auto.md index d145a239..350c16cf 100644 --- a/.claude/commands/workflow/ui-design/explore-auto.md +++ b/.claude/commands/workflow/ui-design/explore-auto.md @@ -27,9 +27,10 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(* 2. Phase 0c: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 1** 3. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues 4. Phase 2 (style-consolidate) → **WAIT for completion** → Auto-continues -5. **Phase 3 (ui-generate)** → **WAIT for completion** → Auto-continues -6. Phase 4 (design-update) → **WAIT for completion** → Auto-continues -7. Phase 5 (batch-plan, optional) → Reports completion +5. Phase 2.5 (layout-extract) → **WAIT for completion** → Auto-continues +6. **Phase 3 (ui-assembly)** → **WAIT for completion** → Auto-continues +7. Phase 4 (design-update) → **WAIT for completion** → Auto-continues +8. Phase 5 (batch-plan, optional) → Reports completion **Phase Transition Mechanism**: - **Phase 0c (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 1 @@ -274,7 +275,7 @@ detect_target_type(target_list): ### Phase 1: Style Extraction ```bash -command = "/workflow:ui-design:extract --base-path \"{base_path}\" " + +command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " + (--images ? "--images \"{images}\" " : "") + (--prompt ? "--prompt \"{prompt}\" " : "") + "--mode explore --variants {style_variants}" @@ -293,33 +294,50 @@ SlashCommand(command) # Output: {style_variants} independent design systems with tokens.css # SlashCommand blocks until phase complete +# Upon completion, IMMEDIATELY execute Phase 2.5 (auto-continue) +``` + +### Phase 2.5: Layout Extraction +```bash +targets_string = ",".join(inferred_target_list) +command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " + + (--images ? "--images \"{images}\" " : "") + + (--prompt ? "--prompt \"{prompt}\" " : "") + + "--targets \"{targets_string}\" " + + "--mode explore --variants {layout_variants} " + + "--device-type \"{device_type}\"" + +REPORT: "🚀 Phase 2.5: Layout Extraction (explore mode)" +REPORT: " → Targets: {targets_string}" +REPORT: " → Layout variants: {layout_variants}" +REPORT: " → Device: {device_type}" + +SlashCommand(command) + +# Output: layout-templates.json with {targets × layout_variants} layout structures +# SlashCommand blocks until phase complete # Upon completion, IMMEDIATELY execute Phase 3 (auto-continue) ``` -### Phase 3: Style-Centric Matrix UI Generation +### Phase 3: UI Assembly ```bash -targets_string = ",".join(inferred_target_list) command = "/workflow:ui-design:generate --base-path \"{base_path}\" " + - "--targets \"{targets_string}\" --target-type \"{target_type}\" " + - "--style-variants {style_variants} --layout-variants {layout_variants} " + - "--device-type \"{device_type}\"" + "--style-variants {style_variants} --layout-variants {layout_variants}" total = style_variants × layout_variants × len(inferred_target_list) -agent_calls = style_variants -REPORT: "🚀 Phase 3: {type_icon} {targets_string} | Matrix: {s}×{l}×{n} = {total} prototypes" -REPORT: " → Device: {device_type}" -REPORT: " → Agent calls: {agent_calls} style-centric agents" -REPORT: " → Layout planning: {len(inferred_target_list)}×{layout_variants} target-specific layouts" -REPORT: " → Style-centric generation: Each of {style_variants} agents handles {layout_variants}×{len(inferred_target_list)} combinations" +REPORT: "🚀 Phase 3: UI Assembly | Matrix: {s}×{l}×{n} = {total} prototypes" +REPORT: " → Pure assembly: Combining layout templates + design tokens" +REPORT: " → Device: {device_type} (from layout templates)" +REPORT: " → Assembly tasks: {total} combinations" SlashCommand(command) # SlashCommand blocks until phase complete # Upon completion, IMMEDIATELY execute Phase 4 (auto-continue) # Output: -# - {target}-layout-{l}.json (target-specific layout plans) -# - {target}-style-{s}-layout-{l}.html (final prototypes with style-aware structure) +# - {target}-style-{s}-layout-{l}.html (assembled prototypes) +# - {target}-style-{s}-layout-{l}.css # - compare.html (interactive matrix view) # - PREVIEW.md (usage instructions) ``` @@ -349,7 +367,8 @@ IF --batch-plan: TodoWrite({todos: [ {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."}, {"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing..."}, - {"content": "Execute style-centric UI generation", "status": "pending", "activeForm": "Executing..."}, + {"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing..."}, + {"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing..."}, {"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."} ]}) @@ -429,33 +448,34 @@ Architecture: Style-Centric Batch Generation Run ID: {run_id} | Session: {session_id or "standalone"} Type: {icon} {target_type} | Device: {device_type} | Matrix: {s}×{l}×{n} = {total} prototypes -Phase 1: {s} style variants with design_attributes (extract) +Phase 1: {s} style variants with design_attributes (style-extract) Phase 2: {s} design systems with tokens.css (consolidate) -Phase 3: Style-centric batch generation (generate) +Phase 2.5: {n×l} layout templates (layout-extract explore mode) - Device: {device_type} layouts - - {n}×{l} target-specific layout plans - - {s} style-centric agents (each handled {l}×{n} combinations) - - {s}×{l}×{n} = {total} final prototypes with style-aware structure + - {n} targets × {l} layout variants = {n×l} structural templates +Phase 3: UI Assembly (generate) + - Pure assembly: layout templates + design tokens + - {s}×{l}×{n} = {total} final prototypes Phase 4: Brainstorming artifacts updated [Phase 5: {n} implementation tasks created] # if --batch-plan -Agent Execution: -✅ Style-centric agents: {s} agents total -✅ Each agent handles: {l}×{n} combinations -✅ Device-optimized: {device_type} layouts +Assembly Process: +✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate +✅ Layout Extraction: {n×l} reusable structural templates +✅ Pure Assembly: No design decisions in generate phase +✅ Device-Optimized: Layouts designed for {device_type} Design Quality: -✅ Style-Aware Structure: HTML adapts to design_attributes -✅ Style Consistency: PERFECT (each style by single agent) ✅ Token-Driven Styling: 100% var() usage +✅ Structural Variety: {l} distinct layouts per target +✅ Style Variety: {s} independent design systems ✅ Device-Optimized: Layouts designed for {device_type} 📂 {base_path}/ ├── style-extraction/ ({s} style cards + design-space-analysis.json) ├── style-consolidation/ ({s} design systems with tokens.css) - ├── prototypes/ - │ ├── _templates/ ({n}×{l} layout JSON files) - │ └── ... ({total} final prototypes) + ├── layout-extraction/ ({n×l} layout templates + layout-space-analysis.json) + ├── prototypes/ ({total} assembled prototypes) └── .run-metadata.json (includes device type) 🌐 Preview: {base_path}/prototypes/compare.html diff --git a/.claude/commands/workflow/ui-design/generate.md b/.claude/commands/workflow/ui-design/generate.md index 6941903a..8d9700d8 100644 --- a/.claude/commands/workflow/ui-design/generate.md +++ b/.claude/commands/workflow/ui-design/generate.md @@ -1,27 +1,29 @@ --- name: generate -description: Generate UI prototypes using target-style-centric batch generation -usage: /workflow:ui-design:generate [--targets ""] [--target-type "page|component"] [--device-type "desktop|mobile|tablet|responsive"] [--base-path ] [--session ] [--style-variants ] [--layout-variants ] +description: Assemble UI prototypes by combining layout templates with design tokens (pure assembler) +usage: /workflow:ui-design:generate [--base-path ] [--session ] [--style-variants ] [--layout-variants ] examples: - - /workflow:ui-design:generate --session WFS-auth --targets "dashboard,settings" - - /workflow:ui-design:generate --targets "home,pricing" --style-variants 2 --layout-variants 2 - - /workflow:ui-design:generate --targets "app" --device-type mobile - - /workflow:ui-design:generate --targets "dashboard" --device-type desktop + - /workflow:ui-design:generate --session WFS-auth + - /workflow:ui-design:generate --style-variants 2 --layout-variants 2 + - /workflow:ui-design:generate --base-path ".workflow/WFS-auth/design-run-20250109-143022" allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*) --- # Generate UI Prototypes (/workflow:ui-design:generate) ## Overview -Generate matrix of UI prototypes (`style × layout × targets`) using **target-style-centric batch generation**. Each agent handles all layouts for one target × style combination. +Pure assembler that combines pre-extracted layout templates with design tokens to generate UI prototypes (`style × layout × targets`). No layout design logic - purely combines existing components. -**Strategy**: Target-Style-Centric -- **Agent scope**: Each of `T × S` agents generates `L` layouts -- **Component isolation**: Complete task independence -- **Style-aware**: HTML adapts to design_attributes -- **Self-contained CSS**: Direct token values (no var() refs) +**Strategy**: Pure Assembly +- **Input**: `layout-templates.json` + `design-tokens.json` +- **Process**: Combine structure (DOM) with style (tokens) +- **Output**: Complete HTML/CSS prototypes +- **No Design Logic**: All layout and style decisions already made -**Supports**: Pages (full layouts) and components (isolated elements) +**Prerequisite Commands**: +- `/workflow:ui-design:style-extract` → Style tokens +- `/workflow:ui-design:consolidate` → Final design tokens +- `/workflow:ui-design:layout-extract` → Layout structure ## Phase 1: Setup & Validation @@ -30,135 +32,90 @@ Generate matrix of UI prototypes (`style × layout × targets`) using **target-s # Determine working directory bash(find .workflow -type d -name "design-*" | head -1) # Auto-detect -# Get counts (defaults: style=auto, layout=3) +# Get style count bash(ls {base_path}/style-consolidation/style-* -d | wc -l) - -# Parse targets (Priority: --targets → --pages → synthesis-specification.md → default ["home"]) -# Target type: "page" (default) or "component" - -# Parse device type -device_type = --device-type OR "responsive" # Default: responsive - -# Try to load from .run-metadata.json if exists -IF exists({base_path}/.run-metadata.json): - metadata = Read({base_path}/.run-metadata.json) - IF metadata.parameters.device_type: - device_type = metadata.parameters.device_type ``` -### Step 2: Validate Inputs +### Step 2: Load Layout Templates ```bash -# Check design systems exist +# Check layout templates exist +bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists") + +# Load layout templates +Read({base_path}/layout-extraction/layout-templates.json) +# Extract: targets, layout_variants count, device_type, template structures +``` + +**Output**: `base_path`, `style_variants`, `layout_templates[]`, `targets[]`, `device_type` + +### Step 3: Validate Design Tokens +```bash +# Check design tokens exist for all styles bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid") -# Validate target names (lowercase, alphanumeric, hyphens only) -# Load design-space-analysis.json (optional, for style-aware generation) +# For each style variant: Load design tokens +Read({base_path}/style-consolidation/style-{id}/design-tokens.json) ``` -**Output**: `base_path`, `style_variants`, `layout_variants`, `target_list[]`, `target_type`, `design_space_analysis` (optional), `device_type` +**Output**: `design_tokens[]` for all style variants -### Step 3: Detect Token Sources -```bash -# Priority 1: consolidated tokens (production-ready from /workflow:ui-design:consolidate) -# Priority 2: proposed tokens from style-cards.json (fast-track from /workflow:ui-design:extract) +## Phase 2: Assembly (Agent) -bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "consolidated") -# OR -bash(test -f {base_path}/style-extraction/style-cards.json && echo "proposed") +**Executor**: `Task(ui-design-agent)` × `T × S × L` tasks (can be batched) -# If proposed: Create temp consolidation dir + write proposed tokens -bash(mkdir -p {base_path}/style-consolidation/style-{id}) -Write({base_path}/style-consolidation/style-{id}/design-tokens.json, proposed_tokens) -``` - -**Output**: `token_sources{}`, `consolidated_count`, `proposed_count` - -### Step 4: Gather Layout Inspiration -```bash -bash(mkdir -p {base_path}/prototypes/_inspirations) - -# For each target: Research via MCP -# mcp__exa__web_search_exa(query="{target} {target_type} layout patterns", numResults=5) - -# Write simple inspiration file -Write({base_path}/prototypes/_inspirations/{target}-layout-ideas.txt, inspiration_content) -``` - -**Output**: `L` inspiration text files - -## Phase 2: Target-Style-Centric Generation (Agent) - -**Executor**: `Task(ui-design-agent)` × `T × S` tasks in parallel - -### Step 1: Launch Agent Tasks +### Step 1: Launch Assembly Tasks ```bash bash(mkdir -p {base_path}/prototypes) ``` -For each `target × style_id`: +For each `target × style_id × layout_id`: ```javascript Task(ui-design-agent): ` - [TARGET_STYLE_UI_GENERATION] - 🎯 ONE component: {target} × Style-{style_id} ({philosophy_name}) - Generate: {layout_variants} × 2 files (HTML + CSS per layout) + [LAYOUT_STYLE_ASSEMBLY] + 🎯 Assembly task: {target} × Style-{style_id} × Layout-{layout_id} + Combine: Pre-extracted layout structure + design tokens → Final HTML/CSS - TARGET: {target} | TYPE: {target_type} | STYLE: {style_id}/{style_variants} + TARGET: {target} | STYLE: {style_id} | LAYOUT: {layout_id} BASE_PATH: {base_path} - DEVICE: {device_type} - ${design_attributes ? "DESIGN_ATTRIBUTES: " + JSON.stringify(design_attributes) : ""} - ## Reference - - Layout inspiration: Read("{base_path}/prototypes/_inspirations/{target}-layout-ideas.txt") - - Design tokens: Read("{base_path}/style-consolidation/style-{style_id}/design-tokens.json") - Parse ALL token values (colors, typography, spacing, borders, shadows, breakpoints) - ${design_attributes ? "- Adapt DOM structure to: density, visual_weight, formality, organic_vs_geometric" : ""} + ## Inputs (READ ONLY - NO DESIGN DECISIONS) + 1. Layout Template: + Read("{base_path}/layout-extraction/layout-templates.json") + Find template where: target={target} AND variant_id="layout-{layout_id}" + Extract: dom_structure, css_layout_rules, device_type - ## Generation - For EACH layout (1 to {layout_variants}): + 2. Design Tokens: + Read("{base_path}/style-consolidation/style-{style_id}/design-tokens.json") + Extract: ALL token values (colors, typography, spacing, borders, shadows, breakpoints) - 1. HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-N.html - - Complete HTML5: , , - - CSS ref: - - Semantic:
,