diff --git a/.claude/commands/workflow/design/auto.md b/.claude/commands/workflow/design/auto.md index d49438cc..7b761974 100644 --- a/.claude/commands/workflow/design/auto.md +++ b/.claude/commands/workflow/design/auto.md @@ -1,45 +1,47 @@ --- name: auto -description: Orchestrate complete UI design refinement workflow from style extraction to brainstorming integration -usage: /workflow:design:auto --session --images "" --pages "" [--interactive] [--variants ] -argument-hint: "--session WFS-session-id --images \"refs/*.png\" --pages \"dashboard,auth\" [--interactive] [--variants 2]" +description: Orchestrate UI design refinement workflow with interactive checkpoints for user selection +usage: /workflow:design:auto --session --images "" --pages "" [--variants ] [--batch-plan] +argument-hint: "--session WFS-session-id --images \"refs/*.png\" --pages \"dashboard,auth\" [--variants 2] [--batch-plan]" examples: - - /workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" --interactive - - /workflow:design:auto --session WFS-dashboard --images "refs/*.jpg" --pages "dashboard" --variants 3 -allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*) + - /workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" + - /workflow:design:auto --session WFS-dashboard --images "refs/*.jpg" --pages "dashboard" --variants 3 --batch-plan +allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*) --- # UI Design Auto Workflow Command ## Overview -Complete autonomous orchestration of UI design refinement workflow: style extraction → consolidation → UI generation → brainstorming integration. +Semi-autonomous UI design workflow with interactive checkpoints: style extraction → **user selection** → consolidation → UI generation → **user confirmation** → design update → optional batch planning. ## Coordinator Role -**Pure orchestrator following /workflow:plan pattern**: Execute 4 design commands in sequence with TodoWrite-driven auto-continuation, no user intervention required. +**Checkpoint-based orchestrator**: Execute Phase 1 automatically, pause for user style selection, execute Phase 3, pause for user prototype confirmation, complete with optional batch task generation. -## Execution Model - Auto-Continue Workflow +## Execution Model - Checkpoint Workflow -This workflow runs **fully autonomously** once triggered: +This workflow runs **semi-autonomously** with user checkpoints: -1. **User triggers**: `/workflow:design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard,auth"` -2. **Phase 1 executes** (style-extract) → Reports output → Auto-continues -3. **Phase 2 executes** (style-consolidate) → Reports output → Auto-continues -4. **Phase 3 executes** (ui-generate) → Reports output → Auto-continues -5. **Phase 4 executes** (design-update) → Reports final summary +1. **User triggers**: `/workflow:design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard,auth" [--batch-plan]` +2. **Phase 1 executes** (style-extract) → Reports style cards → **⏸️ PAUSE FOR USER SELECTION** +3. **User selects variants** → Runs `style-consolidate --variants "..."` → Auto-continues +4. **Phase 3 executes** (ui-generate) → Reports prototypes → **⏸️ PAUSE FOR USER CONFIRMATION** +5. **User confirms prototypes** → Runs `design-update --selected-prototypes "..."` → Auto-continues +6. **Phase 5 executes** (batch-plan, optional) → Reports task files -**Auto-Continue Mechanism**: -- TodoWrite tracks current phase status -- After each phase completion, automatically executes next pending phase -- **No user action required** - workflow runs end-to-end autonomously -- Progress updates shown at each phase for visibility +**Checkpoint Mechanism**: +- TodoWrite tracks current phase with "awaiting_user_confirmation" status +- System reports output location and exact command for next step +- User runs provided command to continue workflow +- Workflow resumes automatically after user input ## 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 (commands handle their own validation) 3. **Parse Every Output**: Extract required data from each command's output for next phase -4. **Auto-Continue via TodoWrite**: Check TodoWrite status to execute next pending phase automatically -5. **Track Progress**: Update TodoWrite after every phase completion +4. **Pause at Checkpoints**: After Phase 1 and Phase 3, pause and prompt user with exact command to continue +5. **User-Driven Continuation**: Workflow resumes when user runs style-consolidate or design-update commands +6. **Track Progress**: Update TodoWrite after every phase completion and checkpoint ## Parameter Requirements @@ -49,10 +51,10 @@ This workflow runs **fully autonomously** once triggered: - `--pages ""`: Comma-separated list of pages to generate **Optional Parameters**: -- `--interactive`: Enable interactive style variant selection (default: auto-select first variant) - `--variants `: Number of UI variants per page (default: 1) +- `--batch-plan`: Auto-generate implementation tasks for selected prototypes after design-update -## 4-Phase Execution +## 5-Phase Execution ### Phase 1: Style Extraction **Command**: `SlashCommand(command="/workflow:design:style-extract --session {session_id} --images \"{image_glob}\"")` @@ -60,50 +62,43 @@ This workflow runs **fully autonomously** once triggered: **Parse Output**: - Verify: `.design/style-extraction/style-cards.json` created - Extract: `style_cards_count` from output message +- List available style variant IDs **Validation**: - Style cards successfully generated - At least one style variant available -**TodoWrite**: Mark phase 1 completed, phase 2 in_progress +**TodoWrite**: Mark phase 1 completed, mark checkpoint "awaiting_user_confirmation" -**After Phase 1**: Report to user, auto-continue to Phase 2 +**⏸️ CHECKPOINT 1: Pause for User Style Selection** ``` Phase 1 Complete: Style Extraction Style cards generated: {count} +Available variants: {variant_ids} Location: .workflow/WFS-{session}/.design/style-extraction/ -Continuing to Phase 2: Style Consolidation... +⏸️ USER SELECTION REQUIRED +Review style cards and select your preferred variants. +Then run: + +/workflow:design:style-consolidate --session WFS-{session} --variants "{variant_ids}" + +Example: /workflow:design:style-consolidate --session WFS-{session} --variants "variant-1,variant-3" ``` --- -### Phase 2: Style Consolidation -**Command Construction**: +### Phase 2: Style Consolidation (User-Triggered) +**User Command**: `/workflow:design:style-consolidate --session {session_id} --variants "{selected_variants}"` -```bash -IF --interactive flag present: - command = "/workflow:design:style-consolidate --session {session_id} --interactive" -ELSE: - # Auto-select first variant - command = "/workflow:design:style-consolidate --session {session_id} --variants \"variant-1\"" -``` - -**Command**: `SlashCommand(command="{constructed_command}")` - -**Parse Output**: -- Verify: `.design/style-consolidation/design-tokens.json` created -- Extract: `token_count`, `validation_status` from output message - -**Validation**: -- Design tokens finalized -- Validation report shows no critical errors +**After user runs command**: +- Workflow automatically continues to Phase 3 +- Parse output: token_count, validation_status **TodoWrite**: Mark phase 2 completed, phase 3 in_progress -**After Phase 2**: Report to user, auto-continue to Phase 3 - +**Output**: ``` Phase 2 Complete: Style Consolidation Design tokens: {count} @@ -115,7 +110,7 @@ Continuing to Phase 3: UI Generation... --- -### Phase 3: UI Generation +### Phase 3: UI Generation (Auto-Triggered after Phase 2) **Command Construction**: ```bash @@ -127,41 +122,50 @@ command = "/workflow:design:ui-generate --session {session_id} --pages \"{page_l **Parse Output**: - Verify: `.design/prototypes/*.html` files created -- Extract: `prototype_count`, `page_list` from output message +- Extract: `prototype_count`, `page_list`, `generated_files` list **Validation**: - All requested pages generated - HTML and CSS files present for each variant -**TodoWrite**: Mark phase 3 completed, phase 4 in_progress +**TodoWrite**: Mark phase 3 completed, mark checkpoint "awaiting_user_confirmation" -**After Phase 3**: Report to user, auto-continue to Phase 4 +**⏸️ CHECKPOINT 2: Pause for User Prototype Confirmation** ``` Phase 3 Complete: UI Generation -Prototypes generated: {count} -Pages: {page_list} +Prototypes generated: {count} ({page_list}) +Generated files: {file_list} Location: .workflow/WFS-{session}/.design/prototypes/ -Continuing to Phase 4: Design System Integration... +⏸️ USER CONFIRMATION REQUIRED +Review the generated prototypes and select your preferred variants. +Then run: + +/workflow:design:design-update --session WFS-{session} --selected-prototypes "{prototype_ids}" + +Example: /workflow:design:design-update --session WFS-{session} --selected-prototypes "dashboard-variant-1,auth-variant-2" + +Or to use all generated prototypes: +/workflow:design:design-update --session WFS-{session} ``` --- -### Phase 4: Design System Integration -**Command**: `SlashCommand(command="/workflow:design:design-update --session {session_id}")` +### Phase 4: Design System Integration (User-Triggered) +**User Command**: `/workflow:design:design-update --session {session_id} [--selected-prototypes "{selected_prototypes}"]` + +**After user runs command**: +- Workflow updates brainstorming artifacts +- If --batch-plan flag present, automatically continues to Phase 5 **Parse Output**: - Verify: `synthesis-specification.md` updated - Verify: `ui-designer/style-guide.md` created/updated -**Validation**: -- Brainstorming artifacts successfully updated -- Design system references integrated - **TodoWrite**: Mark phase 4 completed -**Return to User**: +**Output** (if --batch-plan NOT present): ``` UI Design Refinement Complete for session: WFS-{session} @@ -183,6 +187,45 @@ Next Steps: (The plan phase will automatically discover and utilize the design system) ``` +**Output** (if --batch-plan present): +``` +Phase 4 Complete: Design System Integration +Updated Artifacts: +✓ synthesis-specification.md +✓ ui-designer/style-guide.md + +Continuing to Phase 5: Batch Task Generation... +``` + +--- + +### Phase 5: Batch Task Generation (Optional, Auto-Triggered if --batch-plan) +**Condition**: Only executes if `--batch-plan` flag present + +**Execution**: +```bash +FOR each page IN selected_prototypes_pages: + SlashCommand(command="/workflow:plan --agent \"Implement {page} page based on design system\"") + + # Parse output task file location + task_files.add(output_location) +``` + +**TodoWrite**: Mark phase 5 completed + +**Return to User**: +``` +Phase 5 Complete: Batch Task Generation +Tasks generated for: {page_count} pages + +Generated task files: +{task_file_list} + +Design workflow complete for session: WFS-{session} + +Next: /workflow:execute +``` + ## TodoWrite Pattern ```javascript diff --git a/.claude/commands/workflow/design/style-extract.md b/.claude/commands/workflow/design/style-extract.md index c0171ea6..94047d2e 100644 --- a/.claude/commands/workflow/design/style-extract.md +++ b/.claude/commands/workflow/design/style-extract.md @@ -1,22 +1,23 @@ --- name: style-extract -description: Extract design style from reference images using Gemini Vision and Codex +description: Extract design style from reference images using triple vision analysis (Claude Code + Gemini + Codex) usage: /workflow:design:style-extract --session --images "" argument-hint: "--session WFS-session-id --images \"path/to/*.png\"" examples: - /workflow:design:style-extract --session WFS-auth --images "design-refs/*.png" - /workflow:design:style-extract --session WFS-dashboard --images "refs/dashboard-*.jpg" -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*) +allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*) --- # Style Extraction Command ## Overview -Extract design style elements from reference images using a hybrid approach: Gemini Vision for semantic understanding and Codex for structured CSS token generation. +Extract design style elements from reference images using triple vision analysis: Claude Code's native vision, Gemini Vision for semantic understanding, and Codex for structured token generation. ## Core Philosophy -- **Visual Semantic Understanding**: Gemini Vision analyzes design style, typography, and composition -- **Structured Token Generation**: Codex converts semantic analysis to OKLCH + CSS variables + Tailwind config +- **Triple Vision Analysis**: Combine Claude Code, Gemini Vision, and Codex vision capabilities +- **Comprehensive Coverage**: Claude Code for quick analysis, Gemini for deep semantic understanding, Codex for structured output +- **Consensus-Based Extraction**: Synthesize results from all three sources - **Style Card System**: Generate reusable style cards for consolidation phase - **Multi-Image Support**: Process multiple reference images and extract common patterns @@ -31,73 +32,102 @@ EXPAND: glob pattern to concrete image paths VERIFY: at least one image file exists ``` -### Phase 2: Gemini Vision Analysis -**Agent Invocation**: Task(conceptual-planning-agent) with Gemini Vision capability +### Phase 2: Claude Code Vision Analysis (Quick Initial Pass) +**Direct Execution**: Use Read tool with image paths ```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] +# Claude Code's native vision capability for quick initial analysis +FOR each image IN expanded_image_paths: + Read({image_path}) + # Claude Code analyzes image and extracts basic patterns -Extract visual design semantics from reference images - -## Context Loading -ASSIGNED_TASK: style-extraction -OUTPUT_LOCATION: .workflow/WFS-{session}/.design/style-extraction/ -IMAGE_INPUTS: {expanded_image_paths} - -## Flow Control Steps -1. **load_images_gemini** - - Action: Analyze reference images using Gemini Vision - - Command: bash(cd .workflow/WFS-{session} && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p \" - PURPOSE: Extract design style semantics from reference images - TASK: Analyze color palettes, typography, spacing, layout principles, component styles - MODE: write - CONTEXT: @{../../{image_paths}} - EXPECTED: JSON with semantic style description (colors with names, font characteristics, spacing scale, design philosophy) - RULES: Focus on extracting semantic meaning, not exact pixel values - \") - - Output: semantic_style_analysis.json - -2. **load_session_context** - - Action: Load brainstorming context for style alignment - - Command: Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) || Read(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md) - - Output: design_context - - Optional: true - -## Analysis Requirements -**Semantic Extraction**: Identify design philosophy (minimalist, brutalist, neumorphic, etc.) -**Color System**: Extract primary, secondary, accent colors with semantic names -**Typography**: Font families, weights, scale (headings, body, small) -**Spacing**: Identify spacing scale patterns -**Components**: Border radius, shadows, button styles, card styles - -## Expected Deliverables -1. **semantic_style_analysis.json**: Gemini Vision analysis results -" +# Write preliminary analysis +Write(.workflow/WFS-{session}/.design/style-extraction/claude_vision_analysis.json) ``` -### Phase 3: Codex Structured Token Generation -**Agent Invocation**: Task(conceptual-planning-agent) with Codex capabilities +**Output**: `claude_vision_analysis.json` with Claude Code's initial observations + +### Phase 3: Gemini Vision Analysis (Deep Semantic Understanding) +**Direct Bash Execution**: No agent wrapper ```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] +bash(cd .workflow/WFS-{session}/.design/style-extraction && \ + ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p " + PURPOSE: Extract deep design semantics from reference images + TASK: Analyze color palettes, typography, spacing, layout principles, component styles, design philosophy + MODE: write + CONTEXT: @{../../{image_paths}} + EXPECTED: JSON with comprehensive semantic style description (colors with names, font characteristics, spacing scale, design philosophy, UI patterns) + RULES: Focus on extracting semantic meaning and design intent, not exact pixel values. Identify design system patterns. + ") -Convert semantic style analysis to structured CSS tokens +# Output: gemini_vision_analysis.json +``` -## Context Loading -INPUT_ANALYSIS: .workflow/WFS-{session}/.design/style-extraction/semantic_style_analysis.json -OUTPUT_LOCATION: .workflow/WFS-{session}/.design/style-extraction/ -TECH_STACK_CONTEXT: CLAUDE.md, .claude/workflows/cli-templates/tech-stacks/*.md +**Output**: `gemini_vision_analysis.json` with Gemini's deep semantic analysis -## Flow Control Steps -1. **load_semantic_analysis** - - Action: Read Gemini Vision analysis - - Command: Read(.workflow/WFS-{session}/.design/style-extraction/semantic_style_analysis.json) - - Output: semantic_analysis +### Phase 4: Codex Vision Analysis (Structured Pattern Recognition) +**Direct Bash Execution**: Codex with -i parameter -2. **generate_css_tokens_codex** - - Action: Convert semantic analysis to structured CSS tokens +```bash +bash(codex -C .workflow/WFS-{session}/.design/style-extraction --full-auto -i {image_paths} exec " + PURPOSE: Analyze reference images for structured design patterns + TASK: Extract color values, typography specs, spacing measurements, component patterns + MODE: auto + CONTEXT: Reference images provided via -i parameter + EXPECTED: Structured JSON with precise design specifications + RULES: Focus on measurable design attributes and component patterns +" --skip-git-repo-check -s danger-full-access) + +# Output: codex_vision_analysis.json +``` + +**Output**: `codex_vision_analysis.json` with Codex's structured analysis + +### Phase 5: Synthesis of Triple Vision Analysis +**Direct Execution**: Main Claude synthesizes all three analyses + +```bash +# Read all three vision analysis results +Read(.workflow/WFS-{session}/.design/style-extraction/claude_vision_analysis.json) +Read(.workflow/WFS-{session}/.design/style-extraction/gemini_vision_analysis.json) +Read(.workflow/WFS-{session}/.design/style-extraction/codex_vision_analysis.json) + +# Load optional session context +Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) [optional] + +# Synthesize consensus analysis +# Main Claude identifies common patterns, resolves conflicts, creates unified semantic analysis +Write(.workflow/WFS-{session}/.design/style-extraction/semantic_style_analysis.json) +``` + +**Synthesis Strategy**: +- **Color system**: Consensus from all three sources, prefer Codex for precise values +- **Typography**: Gemini for semantic understanding, Codex for measurements +- **Spacing**: Cross-validate across all three,identify consistent patterns +- **Design philosophy**: Weighted combination with Gemini having highest weight +- **Conflict resolution**: Majority vote or use context from synthesis-specification.md + +**Output**: `semantic_style_analysis.json` - unified analysis synthesizing all three sources + +### Phase 6: Structured Token Generation +**Direct Bash Execution**: Codex generates CSS tokens + +```bash +bash(codex -C .workflow/WFS-{session}/.design/style-extraction --full-auto exec " + PURPOSE: Convert synthesized semantic analysis to structured CSS design tokens + TASK: Generate W3C-compliant design tokens, Tailwind config, and style card variants + MODE: auto + CONTEXT: @{semantic_style_analysis.json,../../../../CLAUDE.md} + EXPECTED: design-tokens.json (OKLCH format), tailwind-tokens.js, style-cards.json (3 variants) + RULES: $(cat ~/.claude/workflows/design-tokens-schema.md) | OKLCH colors, rem spacing, semantic naming +" --skip-git-repo-check -s danger-full-access) +``` + +**Output**: +- `design-tokens.json`: W3C-compliant tokens in OKLCH format +- `tailwind-tokens.js`: Tailwind theme extension +- `style-cards.json`: 3 style variant cards for user selection - Command: bash(codex -C .workflow/WFS-{session}/.design/style-extraction --full-auto exec \" PURPOSE: Generate structured CSS design tokens from semantic analysis TASK: Convert semantic color/typography/spacing to OKLCH CSS variables and Tailwind config diff --git a/.claude/commands/workflow/design/ui-generate.md b/.claude/commands/workflow/design/ui-generate.md index 059db179..f99d792e 100644 --- a/.claude/commands/workflow/design/ui-generate.md +++ b/.claude/commands/workflow/design/ui-generate.md @@ -1,12 +1,12 @@ --- name: ui-generate -description: Generate UI prototypes using consolidated design tokens and synthesis specification -usage: /workflow:design:ui-generate --session --pages "" [--variants ] -argument-hint: "--session WFS-session-id --pages \"dashboard,auth,settings\" [--variants 2]" +description: Generate UI prototypes using consolidated design tokens with optional style overrides +usage: /workflow:design:ui-generate --session --pages "" [--variants ] [--style-overrides ""] +argument-hint: "--session WFS-session-id --pages \"dashboard,auth\" [--variants 2] [--style-overrides \"overrides.json\"]" examples: - /workflow:design:ui-generate --session WFS-auth --pages "login,register" - - /workflow:design:ui-generate --session WFS-dashboard --pages "dashboard" --variants 3 -allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Bash(*) + - /workflow:design:ui-generate --session WFS-dashboard --pages "dashboard" --variants 3 --style-overrides "overrides.json" +allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*) --- # UI Generation Command diff --git a/CHANGELOG.md b/CHANGELOG.md index 8af85acf..5d606f50 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,201 @@ 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). +## [3.5.0] - 2025-10-06 + +### 🎨 UI Design Workflow with Triple Vision Analysis + +This release introduces a comprehensive UI design workflow system with triple vision analysis capabilities, interactive user checkpoints, and zero agent overhead for improved performance. + +#### Added + +**New UI Design Workflow System**: +- **`/workflow:design:auto`**: Semi-autonomous UI design workflow orchestrator + - Interactive checkpoints for user style selection and prototype confirmation + - Optional batch task generation with `--batch-plan` flag + - Pause-and-continue pattern at critical decision points + - Automatic progression between phases after user input + - Support for multiple UI variants per page (`--variants` parameter) + +**Triple Vision Analysis Architecture**: +- **Phase 1: Claude Code Vision Analysis**: Quick initial visual analysis using native Read tool +- **Phase 2: Gemini Vision Analysis**: Deep semantic understanding of design intent +- **Phase 3: Codex Vision Analysis**: Structured pattern recognition with `-i` parameter +- **Phase 4: Consensus Synthesis**: Weighted combination by main Claude agent +- **Synthesis Strategy**: + - Color system: Consensus with Codex precision preference + - Typography: Gemini semantic + Codex measurements + - Spacing: Cross-validation across all three sources + - Design philosophy: Weighted with Gemini highest priority + - Conflict resolution: Majority vote or synthesis-specification.md context + +**Individual Design Commands**: +- **`/workflow:design:style-extract`**: Extract design styles from reference images + - Triple vision analysis (Claude Code + Gemini + Codex) + - Generates `semantic_style_analysis.json`, `design-tokens.json`, `style-cards.json` + - Outputs multiple style variant cards for user selection + - Direct bash execution (no agent wrappers) + +- **`/workflow:design:style-consolidate`**: Consolidate selected style variants + - Validates and merges design tokens + - Generates finalized `design-tokens.json`, `style-guide.md`, `tailwind.config.js` + - WCAG AA compliance validation + - Token coverage ≥90% requirement + +- **`/workflow:design:ui-generate`**: Generate production-ready UI prototypes + - Token-driven HTML/CSS generation with Codex + - Support for `--style-overrides` parameter for runtime customization + - Generates `{page}-variant-{n}.html`, `{page}-variant-{n}.css` per page + - Semantic HTML5 with ARIA attributes + - Responsive design with token-based breakpoints + +- **`/workflow:design:design-update`**: Integrate design system into brainstorming + - Updates `synthesis-specification.md` with UI/UX guidelines section + - Creates/updates `ui-designer/style-guide.md` + - Makes design tokens available for task generation phase + +**Interactive Checkpoint System**: +- **Checkpoint 1 (After style-extract)**: User selects preferred style variants + - Command: `/workflow:design:style-consolidate --session WFS-xxx --variants "variant-1,variant-3"` + - Workflow pauses until user runs consolidation command + +- **Checkpoint 2 (After ui-generate)**: User confirms selected prototypes + - Command: `/workflow:design:design-update --session WFS-xxx --selected-prototypes "page-variant-1,page-variant-2"` + - Workflow pauses until user runs design-update command + +**Design System Features**: +- **OKLCH Color Format**: Perceptually uniform color space for design tokens +- **W3C Design Tokens Compatibility**: Standard-compliant token format +- **Style Override Mechanism**: Runtime token merging using jq +- **Batch Task Generation**: Automatic `/workflow:plan` invocation for each page +- **Accessibility Validation**: WCAG 2.1 AA compliance checks + +#### Changed + +**Agent Architecture Simplification**: +- **Removed agent wrappers** from `style-extract` and `ui-generate` commands + - Previously used `Task(conceptual-planning-agent)` for simple bash execution + - Now executes `gemini-wrapper` and `codex` commands directly via Bash tool + - Reduced execution overhead and complexity + - Preserved all functionality while improving performance + +**Command Execution Pattern**: +- **Direct Bash Execution**: All CLI tools now use direct bash commands + - Gemini Vision: `bash(gemini-wrapper --approval-mode yolo -p "...")` + - Codex Vision: `bash(codex -i {images} --full-auto exec "..." -s danger-full-access)` + - Codex Token Generation: `bash(codex --full-auto exec "..." -s danger-full-access)` + - No intermediate agent layers + +**Workflow Integration**: +- Design phase now optional but recommended for UI-heavy projects +- Seamless integration with existing brainstorming → planning → execution flow +- Design artifacts automatically discovered by `task-generate` if present +- UI tasks automatically include `load_design_tokens` in flow_control + +**Updated Documentation**: +- **README.md**: Added UI Design Workflow section in Getting Started +- **README_CN.md**: Chinese documentation updated with design workflow +- **Command Reference**: Added 5 new `/workflow:design:*` commands +- **Phase Renumbering**: Shifted phases to accommodate new Phase 2 (UI Design) + +#### Benefits + +**User Experience**: +- 🎨 **Visual Validation**: Users confirm design before implementation starts +- ⏸️ **Interactive Control**: Critical design decisions require explicit user approval +- 👁️ **Comprehensive Analysis**: Three AI vision sources provide robust style extraction +- 🎯 **Zero Waiting**: Direct bash execution eliminates agent overhead +- 📦 **Automation Ready**: Optional batch task generation accelerates workflow + +**Code Quality**: +- 🔒 **Token Enforcement**: 100% CSS values use custom properties (verified) +- ♿ **Accessibility**: WCAG AA validated at design phase +- 🎨 **Consistency**: Single source of truth for visual design (design-tokens.json) +- 🧪 **Production Ready**: Semantic HTML5, responsive, accessible prototypes + +**Development Workflow**: +- 🔄 **Seamless Integration**: Optional design phase fits between brainstorming and planning +- 🚀 **Backward Compatible**: Existing workflows unaffected if design phase skipped +- 📊 **Better Planning**: Design system context improves task generation quality +- 🎯 **Focused Implementation**: Developers work from validated prototypes and tokens + +#### Technical Details + +**Triple Vision Analysis Flow**: +``` +Reference Images + ↓ +Phase 2: Claude Code (Read tool) → claude_vision_analysis.json +Phase 3: Gemini Vision (gemini-wrapper) → gemini_vision_analysis.json +Phase 4: Codex Vision (codex -i) → codex_vision_analysis.json + ↓ +Phase 5: Main Claude Synthesis → semantic_style_analysis.json + ↓ +Phase 6: Codex Token Generation → design-tokens.json, style-cards.json +``` + +**Checkpoint Workflow Pattern**: +``` +User: /workflow:design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard,auth" + ↓ +Phase 1: style-extract (automatic) + ↓ [CHECKPOINT 1: User selects style variants] +User: /workflow:design:style-consolidate --session WFS-xxx --variants "variant-1,variant-3" + ↓ +Phase 3: ui-generate (automatic after Phase 2) + ↓ [CHECKPOINT 2: User confirms prototypes] +User: /workflow:design:design-update --session WFS-xxx --selected-prototypes "dashboard-variant-1,auth-variant-2" + ↓ +Phase 5: batch-plan (optional, automatic if --batch-plan flag) +``` + +**Output Structure**: +``` +.workflow/WFS-{session}/.design/ +├── style-extraction/ +│ ├── claude_vision_analysis.json +│ ├── gemini_vision_analysis.json +│ ├── codex_vision_analysis.json +│ ├── semantic_style_analysis.json (synthesis) +│ ├── design-tokens.json (preliminary) +│ └── style-cards.json (variants for selection) +├── style-consolidation/ +│ ├── style-philosophy.md +│ ├── design-tokens.json (final, validated) +│ ├── style-guide.md +│ ├── tailwind.config.js +│ └── validation-report.json +└── prototypes/ + ├── {page}-variant-{n}.html (per page, per variant) + ├── {page}-variant-{n}.css (token-driven styles) + ├── {page}-variant-{n}-notes.md (implementation notes) + └── design-tokens.css (CSS custom properties) +``` + +**New Agent Documentation**: +- **`ui-design-agent.md`**: Specialized agent for UI/UX design workflows + - Vision analysis, token generation, prototype creation capabilities + - Multi-modal vision provider strategy (Gemini primary, Codex fallback) + - Quality gates: WCAG AA, token coverage ≥90%, component mapping ≥95% + - Flow control specification for 3 design phases + +#### Use Cases + +**When to Use Design Workflow**: +- User-facing applications with visual design requirements +- Design system creation and maintenance +- Brand-critical user interfaces +- Projects requiring accessibility compliance +- Multi-page applications with consistent styling + +**When to Skip Design Workflow**: +- Backend APIs without UI components +- CLI tools and command-line applications +- Quick prototypes and MVPs +- Projects with existing design systems + +--- + ## [3.4.2] - 2025-10-05 ### 📚 CLI Documentation Refactoring diff --git a/README.md b/README.md index 77e1ace7..56392e41 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@
-[![Version](https://img.shields.io/badge/version-v3.4.2-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases) +[![Version](https://img.shields.io/badge/version-v3.5.0-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,15 +15,16 @@ **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: v3.4.2** - CLI documentation refactoring & single source of truth. See [CHANGELOG.md](CHANGELOG.md) for details. +> **🎉 Latest: v3.5.0** - UI Design Workflow with Triple Vision Analysis. See [CHANGELOG.md](CHANGELOG.md) for details. > -> **What's New in v3.4.2**: -> - 📚 **CLI Documentation Refactoring**: Eliminated 681 lines of duplicate content across 7 command files -> - 🎯 **Single Source of Truth**: Established implicit reference pattern to `intelligent-tools-strategy.md` -> - 🔍 **Documentation Consistency**: All CLI commands now reference centralized strategy guide -> - 💡 **Maintenance Optimization**: Reduced maintenance overhead while preserving unique command features -> - ✨ **Enhanced Clarity**: Streamlined documentation focuses on command-specific capabilities -> - 📖 **Better Organization**: File patterns, templates, and MODE definitions centralized +> **What's New in v3.5.0**: +> - 🎨 **UI Design Workflow**: Complete design refinement workflow from style extraction to prototype generation +> - 👁️ **Triple Vision Analysis**: Combines Claude Code + Gemini + Codex vision capabilities for comprehensive style extraction +> - ⏸️ **Interactive Checkpoints**: User selection points for style variants and prototype confirmation +> - 🎯 **Zero Agent Overhead**: Direct bash execution for CLI tools, removing unnecessary agent wrappers +> - 🎨 **Style Customization**: Runtime override support with `--style-overrides` parameter +> - 📦 **Batch Task Generation**: Optional automatic task creation for selected prototypes with `--batch-plan` +> - 🔄 **Semi-Autonomous Workflow**: User-driven continuation at critical design decision points --- @@ -250,7 +251,19 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme /workflow:brainstorm:synthesis # Generate consolidated specification ``` -**Phase 2: Action Planning** +**Phase 2: UI Design Refinement** *(Optional for UI-heavy projects)* +```bash +# Extract design styles from reference images and generate prototypes +/workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" --batch-plan + +# Or run individual design phases +/workflow:design:style-extract --session WFS-auth --images "refs/*.png" +/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3" +/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2 +/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2" +``` + +**Phase 3: Action Planning** ```bash # Create executable implementation plan /workflow:plan "Implement JWT-based authentication system" @@ -259,7 +272,7 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme /workflow:tdd-plan "Implement authentication with test-first development" ``` -**Phase 3: Execution** +**Phase 4: Execution** ```bash # Execute tasks with AI agents /workflow:execute @@ -268,7 +281,7 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme /workflow:status ``` -**Phase 4: Testing & Quality Assurance** +**Phase 5: Testing & Quality Assurance** ```bash # Generate independent test-fix workflow (v3.2.2+) /workflow:test-gen WFS-auth # Creates WFS-test-auth session @@ -341,6 +354,11 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme |---|---| | `/workflow:session:*` | Manage development sessions (`start`, `pause`, `resume`, `list`, `switch`, `complete`). | | `/workflow:brainstorm:*` | Use role-based agents for multi-perspective planning. | +| `/workflow:design:auto` | **NEW** Semi-autonomous UI design workflow with interactive checkpoints for style and prototype selection. | +| `/workflow:design:style-extract` | **NEW** Extract design styles from reference images using triple vision analysis (Claude + Gemini + Codex). | +| `/workflow:design:style-consolidate` | **NEW** Consolidate selected style variants into validated design tokens and style guide. | +| `/workflow:design:ui-generate` | **NEW** Generate token-driven HTML/CSS prototypes with optional style overrides. | +| `/workflow:design:design-update` | **NEW** 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. | diff --git a/README_CN.md b/README_CN.md index bffc131c..dc5a629a 100644 --- a/README_CN.md +++ b/README_CN.md @@ -2,7 +2,7 @@
-[![Version](https://img.shields.io/badge/version-v3.4.2-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases) +[![Version](https://img.shields.io/badge/version-v3.5.0-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,15 +15,16 @@ **Claude Code Workflow (CCW)** 是一个新一代的多智能体自动化开发框架，通过智能工作流管理和自主执行来协调复杂的软件开发任务。 -> **🎉 最新版本: v3.4.2** - CLI 文档重构与单一信息源。详见 [CHANGELOG.md](CHANGELOG.md)。 +> **🎉 最新版本: v3.5.0** - UI 设计工作流与三重视觉分析。详见 [CHANGELOG.md](CHANGELOG.md)。 > -> **v3.4.2 版本新特性**: -> - 📚 **CLI 文档重构**: 消除 7 个命令文件中的 681 行重复内容 -> - 🎯 **单一信息源**: 建立对 `intelligent-tools-strategy.md` 的隐式引用模式 -> - 🔍 **文档一致性**: 所有 CLI 命令现在引用集中的策略指南 -> - 💡 **维护优化**: 降低维护开销，同时保留独特的命令功能 -> - ✨ **增强清晰度**: 精简的文档专注于命令特定功能 -> - 📖 **更好的组织**: 文件模式、模板和 MODE 定义集中化 +> **v3.5.0 版本新特性**: +> - 🎨 **UI 设计工作流**: 从风格提取到原型生成的完整设计精炼工作流 +> - 👁️ **三重视觉分析**: 融合 Claude Code + Gemini + Codex 视觉能力进行综合风格提取 +> - ⏸️ **交互式检查点**: 用户选择风格变体和原型确认的决策点 +> - 🎯 **零智能体开销**: CLI 工具直接 bash 执行，移除不必要的智能体包装 +> - 🎨 **风格自定义**: 通过 `--style-overrides` 参数支持运行时样式覆盖 +> - 📦 **批量任务生成**: 使用 `--batch-plan` 为选定原型自动创建实现任务 +> - 🔄 **半自主工作流**: 在关键设计决策点由用户驱动继续 --- @@ -250,7 +251,19 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装** /workflow:brainstorm:synthesis # 生成综合规范 ``` -**阶段 2：行动规划** +**阶段 2：UI 设计精炼** *(UI 密集型项目可选)* +```bash +# 从参考图像中提取设计风格并生成原型 +/workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" --batch-plan + +# 或者运行单独的设计阶段 +/workflow:design:style-extract --session WFS-auth --images "refs/*.png" +/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3" +/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2 +/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2" +``` + +**阶段 3：行动规划** ```bash # 创建可执行的实现计划 /workflow:plan "实现基于 JWT 的认证系统" @@ -259,7 +272,7 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装** /workflow:tdd-plan "使用测试优先开发实现认证" ``` -**阶段 3：执行** +**阶段 4：执行** ```bash # 使用 AI 智能体执行任务 /workflow:execute @@ -268,7 +281,7 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装** /workflow:status ``` -**阶段 4：测试与质量保证** +**阶段 5：测试与质量保证** ```bash # 生成独立测试修复工作流（v3.2.2+） /workflow:test-gen WFS-auth # 创建 WFS-test-auth 会话 @@ -341,6 +354,11 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装** |---|---| | `/workflow:session:*` | 管理开发会话（`start`, `pause`, `resume`, `list`, `switch`, `complete`）。 | | `/workflow:brainstorm:*` | 使用基于角色的智能体进行多视角规划。 | +| `/workflow:design:auto` | **新增** 带交互式检查点的半自主 UI 设计工作流，用于风格和原型选择。 | +| `/workflow:design:style-extract` | **新增** 使用三重视觉分析（Claude + Gemini + Codex）从参考图像提取设计风格。 | +| `/workflow:design:style-consolidate` | **新增** 将选定的风格变体整合为经过验证的设计令牌和风格指南。 | +| `/workflow:design:ui-generate` | **新增** 生成基于令牌的 HTML/CSS 原型，支持可选的风格覆盖。 | +| `/workflow:design:design-update` | **新增** 将最终确定的设计系统集成到头脑风暴产物中。 | | `/workflow:plan` | 从描述创建详细、可执行的计划。 | | `/workflow:tdd-plan` | 创建 TDD 工作流（6 阶段），包含测试覆盖分析和 Red-Green-Refactor 循环。 | | `/workflow:execute` | 自主执行当前的工作流计划。 |