diff --git a/.claude/commands/workflow/design/auto.md b/.claude/commands/workflow/design/auto.md index 7b761974..560ad3b0 100644 --- a/.claude/commands/workflow/design/auto.md +++ b/.claude/commands/workflow/design/auto.md @@ -1,11 +1,12 @@ --- name: auto 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]" +usage: /workflow:design:auto --pages "" [--session ] [--images ""] [--prompt ""] [--variants ] [--use-agent] [--batch-plan] +argument-hint: "--pages \"dashboard,auth\" [--session WFS-xxx] [--images \"refs/*.png\"] [--prompt \"Modern SaaS\"] [--variants 3] [--use-agent] [--batch-plan]" examples: - - /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 + - /workflow:design:auto --pages "login,register" --images "design-refs/*.png" + - /workflow:design:auto --pages "dashboard" --prompt "Modern minimalist, dark theme" --variants 3 --use-agent + - /workflow:design:auto --session WFS-auth --images "refs/*.png" --pages "login" --variants 2 --batch-plan allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*) --- @@ -46,27 +47,69 @@ This workflow runs **semi-autonomously** with user checkpoints: ## Parameter Requirements **Required Parameters**: -- `--session `: Active workflow session ID -- `--images ""`: Reference image paths for style extraction - `--pages ""`: Comma-separated list of pages to generate **Optional Parameters**: -- `--variants `: Number of UI variants per page (default: 1) -- `--batch-plan`: Auto-generate implementation tasks for selected prototypes after design-update +- `--session `: Workflow session ID (if omitted, runs in standalone mode) +- `--images ""`: Reference image paths (default: `design-refs/*`) +- `--prompt ""`: Text description of design style +- `--variants `: Number of style/UI variants to generate (default: 3, range: 1-5) +- `--use-agent`: Enable agent-driven creative exploration mode +- `--batch-plan`: Auto-generate implementation tasks after design-update (integrated mode only) + +**Input Source Rules**: +- Must provide at least one of: `--images` or `--prompt` +- Both can be combined for guided style analysis + +## Execution Modes + +### Integrated Mode (with `--session`) +- Works within existing workflow session: `.workflow/WFS-{session}/` +- Reads from `.brainstorming/` artifacts +- Phase 4 (design-update) updates synthesis-specification.md +- Enables `--batch-plan` for task generation + +### Standalone Mode (without `--session`) +- Creates new session: `design-session-YYYYMMDD-HHMMSS/` +- Independent of brainstorming phase +- Phase 4 (design-update) is **skipped** +- Outputs final summary instead of artifact updates + +### Mode Detection +```bash +IF --session provided: + mode = "integrated" + base_path = ".workflow/WFS-{session}/" +ELSE: + mode = "standalone" + session_id = "design-session-" + timestamp() + base_path = "./{session_id}/" +``` ## 5-Phase Execution ### Phase 1: Style Extraction -**Command**: `SlashCommand(command="/workflow:design:style-extract --session {session_id} --images \"{image_glob}\"")` +**Command Construction**: +```bash +variants_flag = --variants present ? "--variants {variants_count}" : "" +agent_flag = --use-agent present ? "--use-agent" : "" +images_flag = --images present ? "--images \"{image_glob}\"" : "" +prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : "" +session_flag = --session present ? "--session {session_id}" : "" + +command = "/workflow:design:style-extract {session_flag} {images_flag} {prompt_flag} {variants_flag} {agent_flag}" +``` + +**Command**: `SlashCommand(command="{constructed_command}")` **Parse Output**: - Verify: `.design/style-extraction/style-cards.json` created -- Extract: `style_cards_count` from output message +- Extract: `style_cards_count` (should match `variants_count`) - List available style variant IDs **Validation**: - Style cards successfully generated -- At least one style variant available +- Variant count matches requested count **TodoWrite**: Mark phase 1 completed, mark checkpoint "awaiting_user_confirmation" @@ -115,7 +158,9 @@ Continuing to Phase 3: UI Generation... ```bash variants_flag = --variants present ? "--variants {variants_count}" : "" -command = "/workflow:design:ui-generate --session {session_id} --pages \"{page_list}\" {variants_flag}" +agent_flag = --use-agent present ? "--use-agent" : "" +session_flag = --session present ? "--session {session_id}" : "" +command = "/workflow:design:ui-generate {session_flag} --pages \"{page_list}\" {variants_flag} {agent_flag}" ``` **Command**: `SlashCommand(command="{constructed_command}")` diff --git a/.claude/commands/workflow/design/style-extract.md b/.claude/commands/workflow/design/style-extract.md index 94047d2e..1c0c5d78 100644 --- a/.claude/commands/workflow/design/style-extract.md +++ b/.claude/commands/workflow/design/style-extract.md @@ -1,12 +1,13 @@ --- name: style-extract -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\"" +description: Extract design style from reference images or text prompts using triple vision analysis or agent mode +usage: /workflow:design:style-extract [--session ] [--images ""] [--prompt ""] [--variants ] [--use-agent] +argument-hint: "[--session WFS-xxx] [--images \"refs/*.png\"] [--prompt \"Modern minimalist\"] [--variants 3] [--use-agent]" 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: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*) + - /workflow:design:style-extract --images "design-refs/*.png" --variants 3 + - /workflow:design:style-extract --prompt "Modern minimalist blog, dark theme" --variants 3 --use-agent + - /workflow:design:style-extract --session WFS-auth --images "refs/*.png" --prompt "Linear.app style" --variants 2 +allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), Task(conceptual-planning-agent) --- # Style Extraction Command @@ -15,174 +16,197 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*) 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 -- **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 +- **Dual Mode Support**: Conventional triple vision OR agent-driven creative exploration +- **Flexible Input**: Images, text prompts, or both combined +- **Variant Control**: Generate N style cards based on `--variants` parameter (default: 3) +- **Consensus Synthesis**: Multi-source analysis for quality assurance +- **Style Card Output**: Reusable design direction cards for consolidation phase ## Execution Protocol -### Phase 1: Session & Input Validation +### Phase 0: Mode & Parameter Detection ```bash -# Validate session and locate images -CHECK: .workflow/.active-* marker files -VALIDATE: session_id matches active session -EXPAND: glob pattern to concrete image paths -VERIFY: at least one image file exists +# Detect execution mode +IF --use-agent: + mode = "agent" # Agent-driven creative exploration +ELSE: + mode = "conventional" # Triple vision analysis + +# Detect input source +IF --images AND --prompt: + input_mode = "hybrid" # Text guides image analysis +ELSE IF --images: + input_mode = "image" +ELSE IF --prompt: + input_mode = "text" +ELSE: + ERROR: "Must provide --images or --prompt" + +# Detect session mode +IF --session: + session_mode = "integrated" + session_id = {provided_session} + base_path = ".workflow/WFS-{session_id}/" +ELSE: + session_mode = "standalone" + session_id = "design-session-" + timestamp() + base_path = "./{session_id}/" + +# Set variant count +variants_count = --variants provided ? {count} : 3 +VALIDATE: 1 <= variants_count <= 5 ``` -### Phase 2: Claude Code Vision Analysis (Quick Initial Pass) -**Direct Execution**: Use Read tool with image paths - +### Phase 1: Input Validation & Preparation ```bash -# 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 +# Validate and prepare inputs based on input_mode +IF input_mode IN ["image", "hybrid"]: + EXPAND: --images glob pattern to concrete paths + VERIFY: at least one image file exists -# Write preliminary analysis -Write(.workflow/WFS-{session}/.design/style-extraction/claude_vision_analysis.json) +IF input_mode IN ["text", "hybrid"]: + VALIDATE: --prompt is non-empty string + +# Create session directory structure +CREATE: {base_path}/.design/style-extraction/ ``` -**Output**: `claude_vision_analysis.json` with Claude Code's initial observations +### Phase 2: Style Extraction Execution -### Phase 3: Gemini Vision Analysis (Deep Semantic Understanding) -**Direct Bash Execution**: No agent wrapper +**Route based on mode**: +#### A. Conventional Mode (Triple Vision) +Execute if `mode == "conventional"` + +**Step 1**: Claude Code initial analysis ```bash -bash(cd .workflow/WFS-{session}/.design/style-extraction && \ +IF input_mode IN ["image", "hybrid"]: + FOR each image IN expanded_image_paths: + Read({image_path}) # Claude analyzes visuals +ELSE IF input_mode == "text": + # Analyze text prompt for design keywords + keywords = extract_design_keywords({prompt_text}) + +Write({base_path}/.design/style-extraction/claude_analysis.json) +``` + +**Step 2**: Gemini deep semantic analysis +```bash +context_arg = "" +IF input_mode IN ["image", "hybrid"]: + context_arg += "@{image_paths}" +IF input_mode IN ["text", "hybrid"]: + guidance = "GUIDED BY PROMPT: '{prompt_text}'" + +bash(cd {base_path}/.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 + PURPOSE: Extract design semantics {guidance} + TASK: Generate {variants_count} distinct style directions 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. + CONTEXT: {context_arg} + EXPECTED: {variants_count} style analysis variants in JSON + RULES: OKLCH colors, semantic naming, explore diverse themes ") - -# Output: gemini_vision_analysis.json ``` -**Output**: `gemini_vision_analysis.json` with Gemini's deep semantic analysis - -### Phase 4: Codex Vision Analysis (Structured Pattern Recognition) -**Direct Bash Execution**: Codex with -i parameter - +**Step 3**: Codex structured token generation ```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 +bash(codex -C {base_path}/.design/style-extraction --full-auto exec " + PURPOSE: Convert semantic analysis to structured tokens + TASK: Generate design-tokens.json and {variants_count} style-cards 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 + CONTEXT: @{claude_analysis.json,gemini output} + EXPECTED: design-tokens.json, style-cards.json with {variants_count} variants + RULES: OKLCH format, rem spacing, semantic names " --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 - MODE: auto - CONTEXT: @{semantic_style_analysis.json,../../../../CLAUDE.md} - EXPECTED: - 1. design-tokens.json with OKLCH color values, font stacks, spacing scale - 2. tailwind-tokens.js with Tailwind config extension - 3. style-cards.json with named style variants for user selection - RULES: Use OKLCH for colors, rem for spacing, maintain semantic naming, generate 2-3 style card variants - \" --skip-git-repo-check -s danger-full-access) - - Output: design-tokens.json, tailwind-tokens.js, style-cards.json +#### B. Agent Mode (Creative Exploration) +Execute if `mode == "agent"` -## Token Requirements -**Color Format**: OKLCH with fallback (e.g., \"oklch(0.65 0.15 270 / 1)\") -**Spacing Scale**: rem-based (0.25rem, 0.5rem, 1rem, 1.5rem, 2rem, 3rem, 4rem, 6rem) -**Typography Scale**: rem-based with line-height (xs, sm, base, lg, xl, 2xl, 3xl, 4xl) -**Border Radius**: rem-based (none, sm, md, lg, xl, 2xl, full) -**Shadows**: Layered shadows with OKLCH colors +**Agent-Driven Parallel Generation**: +```bash +# Prepare base context +context_files = "" +IF input_mode IN ["image", "hybrid"]: + context_files += "@{image_paths}" +IF session_mode == "integrated": + context_files += "@{../../.brainstorming/synthesis-specification.md}" -## Expected Deliverables -1. **design-tokens.json**: Structured CSS token definitions -2. **tailwind-tokens.js**: Tailwind configuration extension -3. **style-cards.json**: Multiple style variants for user selection -" +# Define creative themes for diversity +themes = generate_creative_themes(variants_count) +# Example: ["Modern Minimalist", "Brutalist Tech", "Organic Warmth"] + +# Launch parallel agent tasks +FOR i IN range(variants_count): + Task(conceptual-planning-agent): " + [FLOW_CONTROL] + + Generate unique design style variant: '{themes[i]}' + + ## Context + INPUT_SOURCE: {input_mode} + PROMPT_GUIDANCE: {prompt_text if present else 'derive from images'} + THEME_FOCUS: {themes[i]} + OUTPUT_LOCATION: {base_path}/.design/style-extraction/ + + ## Flow Steps + 1. **analyze_input** + IF input_mode IN ['image', 'hybrid']: + Use Gemini Vision to analyze images with theme focus + IF input_mode IN ['text', 'hybrid']: + Use Gemini to expand prompt into detailed design philosophy + + 2. **generate_tokens** + Use Codex to create design-tokens subset for this variant + Output: variant-{i}-tokens.json + + 3. **create_style_card** + Synthesize into style card with: + - id: 'variant-{i}' + - name: '{themes[i]}' + - preview: key design token values + Output: variant-{i}-card.json + + ## Rules + - Focus on '{themes[i]}' aesthetic + - OKLCH colors, rem spacing, semantic naming + - Must be distinct from other variants + " + +# Consolidate parallel results +Wait for all {variants_count} tasks to complete +Consolidate variant-*-card.json → style-cards.json +Merge variant-*-tokens.json → design-tokens.json (include all variants) ``` -### Phase 4: TodoWrite Integration +**Output**: `style-cards.json` with {variants_count} creatively distinct variants + +### Phase 3: TodoWrite & Completion + ```javascript TodoWrite({ todos: [ - { - content: "Validate session and locate reference images", - status: "completed", - activeForm: "Validating session and images" - }, - { - content: "Extract visual semantics using Gemini Vision", - status: "completed", - activeForm: "Extracting visual semantics" - }, - { - content: "Generate structured CSS tokens using Codex", - status: "completed", - activeForm: "Generating CSS tokens" - }, - { - content: "Create style cards for consolidation phase", - status: "completed", - activeForm: "Creating style cards" - } + {content: "Detect mode and validate inputs", status: "completed", activeForm: "Detecting mode"}, + {content: "Execute style extraction (conventional/agent mode)", status: "completed", activeForm: "Extracting styles"}, + {content: "Generate {variants_count} style cards", status: "completed", activeForm: "Generating style cards"} ] }); ``` +**Completion Message**: +``` +Style extraction complete for session: {session_id} +Mode: {mode} | Input: {input_mode} | Variants: {variants_count} + +Generated {variants_count} style cards: +{list_variant_names} + +Location: {base_path}/.design/style-extraction/ + +Next: /workflow:design:style-consolidate --session {session_id} --variants "{selected_ids}" +``` + ## Output Structure ``` diff --git a/.claude/commands/workflow/design/ui-generate.md b/.claude/commands/workflow/design/ui-generate.md index 02fba33a..da8c7634 100644 --- a/.claude/commands/workflow/design/ui-generate.md +++ b/.claude/commands/workflow/design/ui-generate.md @@ -1,12 +1,13 @@ --- name: ui-generate -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\"]" +description: Generate UI prototypes using consolidated design tokens with conventional or agent mode +usage: /workflow:design:ui-generate --pages "" [--session ] [--variants ] [--use-agent] +argument-hint: "--pages \"dashboard,auth\" [--session WFS-xxx] [--variants 3] [--use-agent]" examples: - - /workflow:design:ui-generate --session WFS-auth --pages "login,register" - - /workflow:design:ui-generate --session WFS-dashboard --pages "dashboard" --variants 3 --style-overrides "overrides.json" -allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*) + - /workflow:design:ui-generate --pages "login,register" --variants 2 + - /workflow:design:ui-generate --session WFS-auth --pages "dashboard" --variants 3 --use-agent + - /workflow:design:ui-generate --pages "home,pricing" --variants 2 +allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(conceptual-planning-agent) --- # UI Generation Command @@ -15,228 +16,158 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*) Generate production-ready UI prototypes (HTML/CSS) strictly adhering to consolidated design tokens and synthesis specification requirements. ## Core Philosophy +- **Dual Mode**: Conventional (Codex primary) OR agent-driven (creative layouts) - **Token-Driven**: All styles reference design-tokens.json, no hardcoded values -- **Specification-Aligned**: UI structure follows synthesis-specification.md requirements -- **Codex Primary**: Code generation with strict token enforcement -- **Gemini Variants**: Optional semantic layout variations -- **Production-Ready**: Clean HTML5, semantic markup, accessibility attributes +- **Variant Control**: Generate N prototypes per page based on `--variants` (default: 1) +- **Layout Diversity**: Agent mode explores structural variations (F-pattern, grid, asymmetric) +- **Production-Ready**: Semantic HTML5, ARIA attributes, responsive design ## Execution Protocol -### Phase 1: Session & Requirements Loading +### Phase 1: Mode Detection & Context Loading ```bash -# Validate session and load design system -CHECK: .workflow/.active-* marker files -VALIDATE: session_id matches active session -VERIFY: .design/style-consolidation/design-tokens.json exists -PARSE: --pages parameter to page list -SET: variants_count = --variants || 1 +# Detect execution mode +IF --use-agent: + mode = "agent" # Agent-driven creative layouts +ELSE: + mode = "conventional" # Codex primary generation + +# Detect session mode +IF --session: + session_mode = "integrated" + session_id = {provided_session} + base_path = ".workflow/WFS-{session_id}/" +ELSE: + session_mode = "standalone" + # Infer session_id from existing design-session-* directory + base_path = "./{detected_design_session}/" + +# Set parameters +PARSE: --pages to page_list[] +variants_count = --variants provided ? {count} : 1 +VALIDATE: 1 <= variants_count <= 5 + +# Load design system +VERIFY: {base_path}/.design/style-consolidation/design-tokens.json exists +LOAD: design-tokens.json, style-guide.md, tailwind.config.js + +# Load requirements (if integrated mode) +IF session_mode == "integrated": + LOAD: {base_path}/.brainstorming/synthesis-specification.md ``` -### Phase 2: Context Gathering -**Load comprehensive context for UI generation** +### Phase 2: UI Generation Execution + +**Route based on mode**: + +#### A. Conventional Mode (Codex Primary) +Execute if `mode == "conventional"` ```bash -LOAD: design-tokens.json (style system) -LOAD: style-guide.md (usage guidelines) -LOAD: synthesis-specification.md (functional requirements) -LOAD: ui-designer/analysis.md (UX guidelines, optional) -PARSE: page_requirements for each page in --pages list +# Single Codex call generates all variants for all pages +bash(codex -C {base_path}/.design/prototypes --full-auto exec " + PURPOSE: Generate UI prototypes adhering to design tokens + TASK: Create HTML/CSS for pages: {page_list} with {variants_count} variant(s) each + MODE: auto + CONTEXT: @{../style-consolidation/design-tokens.json,../style-consolidation/style-guide.md} + EXPECTED: + For each page, generate {variants_count} variant(s): + - {page}-variant-{n}.html (semantic HTML5) + - {page}-variant-{n}.css (token-driven, no hardcoded values) + - {page}-variant-{n}-notes.md (implementation notes) + + RULES: + - STRICT token adherence: var(--color-brand-primary), var(--spacing-4) + - Semantic HTML5 + ARIA attributes + - Responsive: mobile-first, token-based breakpoints + - Variants differ in minor layout details +" --skip-git-repo-check -s danger-full-access) ``` -### Phase 3: Codex UI Generation (Primary) -**Agent Invocation**: Task(conceptual-planning-agent) with Codex capabilities +#### B. Agent Mode (Creative Layouts) +Execute if `mode == "agent"` + +**Agent-Driven Parallel Generation**: +```bash +# Define layout strategies for diversity +layouts = generate_layout_strategies(variants_count) +# Example: ["F-Pattern", "Asymmetric Grid", "Card-Based Modular"] + +# Launch parallel agent tasks for each page-variant combination +FOR page IN page_list: + FOR i IN range(variants_count): + Task(conceptual-planning-agent): " + [FLOW_CONTROL] + + Generate UI prototype: {page} using '{layouts[i]}' layout + + ## Context + PAGE: {page} + LAYOUT_STRATEGY: {layouts[i]} + OUTPUT: {base_path}/.design/prototypes/ + + ## Flow Steps + 1. **load_design_system** + Read design-tokens.json and style-guide.md + + 2. **load_requirements** + IF session_mode == 'integrated': + Read synthesis-specification.md for {page} requirements + + 3. **generate_prototype_codex** + Use Codex to generate HTML/CSS with layout focus: + Layout: {layouts[i]} + Token adherence: STRICT (all values from design-tokens) + Output: {page}-variant-{i}.html/css/notes.md + + ## Rules + - Layout must follow '{layouts[i]}' strategy + - Examples: + * F-Pattern: Content flows top→left→middle→bottom + * Asymmetric Grid: Strong visual hierarchy, off-center + * Card-Based: Modular components, flexible grid + - STRICT token usage, semantic HTML, ARIA attributes + " + +Wait for all {len(page_list) * variants_count} tasks to complete +``` + +### Phase 3: Generate Preview Files ```bash -Task(conceptual-planning-agent): " -[FLOW_CONTROL] - -Generate production-ready UI prototypes with strict design token adherence - -## Context Loading -ASSIGNED_TASK: ui-prototype-generation -OUTPUT_LOCATION: .workflow/WFS-{session}/.design/prototypes/ -TARGET_PAGES: {page_list} -VARIANTS_PER_PAGE: {variants_count} - -## Flow Control Steps -1. **load_design_system** - - Action: Load finalized design tokens and style guide - - Commands: - - 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) - - Output: design_system - -2. **load_requirements** - - Action: Load functional and UX requirements - - Commands: - - Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) - - Read(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md) [optional] - - Output: requirements_context - -3. **generate_ui_prototypes_codex** - - Action: Generate HTML/CSS prototypes with strict token enforcement - - Command: bash(codex -C .workflow/WFS-{session}/.design/prototypes --full-auto exec \" - PURPOSE: Generate production-ready UI prototypes adhering to design tokens - TASK: Create HTML/CSS prototypes for pages: {page_list} with {variants_count} variant(s) each - MODE: auto - CONTEXT: @{../style-consolidation/design-tokens.json,../style-consolidation/style-guide.md,../../.brainstorming/synthesis-specification.md,../../../../CLAUDE.md} - EXPECTED: - For each page, generate {variants_count} variant(s): - 1. {page}-variant-{n}.html - Complete HTML structure - 2. {page}-variant-{n}.css - CSS using design token custom properties - 3. {page}-variant-{n}-notes.md - Implementation notes and token usage - - RULES: - - ALL styles MUST reference design token CSS custom properties (--color-brand-primary, --spacing-4, etc.) - - NO hardcoded colors, spacing, or typography values - - Use semantic HTML5 elements (header, nav, main, section, article, footer) - - Include ARIA labels and accessibility attributes (role, aria-label, aria-describedby) - - Implement responsive design using token-based breakpoints - - Follow component patterns from style-guide.md - - Include placeholder content matching page purpose - - Variants explore different layouts while maintaining token consistency - - Generate CSS custom properties mapping in each CSS file - \" --skip-git-repo-check -s danger-full-access) - - Output: {page}-variant-{n}.html, {page}-variant-{n}.css, {page}-variant-{n}-notes.md - -## Generation Requirements - -**Token Adherence**: -- Use CSS custom properties for all design values -- Reference design-tokens.json for property definitions -- Example: `color: var(--color-brand-primary);` -- Example: `padding: var(--spacing-4) var(--spacing-6);` -- Example: `font-size: var(--font-size-lg);` - -**Semantic HTML**: -```html -
- -
-
-
-

Section Title

- -
-
-
- -
+# Generate preview utilities +Write({base_path}/.design/prototypes/index.html) # Master navigation +Write({base_path}/.design/prototypes/compare.html) # Side-by-side comparison +Write({base_path}/.design/prototypes/PREVIEW.md) # Setup instructions ``` -**Accessibility Requirements**: -- Proper heading hierarchy (h1 → h2 → h3) -- Alt text for images -- ARIA labels for interactive elements -- Keyboard navigation support -- Focus indicators using token colors -- Sufficient color contrast (validated against tokens) +### Phase 4: TodoWrite & Completion -**Responsive Design**: -- Mobile-first approach -- Token-based breakpoints (e.g., --breakpoint-md: 768px) -- Flexible layouts using CSS Grid or Flexbox -- Responsive typography using clamp() with token values - -## Expected Deliverables -For each page in {page_list}: -1. **{page}-variant-{n}.html**: Complete HTML prototype -2. **{page}-variant-{n}.css**: Token-driven CSS -3. **{page}-variant-{n}-notes.md**: Implementation notes -" -``` - -### Phase 4: Generate Preview Enhancement Files -**Direct Execution**: Create preview index and comparison view - -```bash -# Generate preview index page -Write(.workflow/WFS-{session}/.design/prototypes/index.html): - - List all generated prototypes with thumbnails - - Quick navigation to individual variants - - Metadata: page name, variant count, generation timestamp - - Direct links to HTML files - -# Generate side-by-side comparison view -Write(.workflow/WFS-{session}/.design/prototypes/compare.html): - - Iframe-based comparison for all variants of same page - - Responsive viewport toggles (mobile, tablet, desktop) - - Synchronized scrolling option - - Variant labels and quick switching - -# Generate preview server instructions -Write(.workflow/WFS-{session}/.design/prototypes/PREVIEW.md): - - How to open files directly in browser - - Local server setup commands (Python, Node.js, PHP) - - Port and access instructions - - Browser compatibility notes -``` - -**Output**: -- `index.html`: Master index page for all prototypes -- `compare.html`: Side-by-side comparison view -- `PREVIEW.md`: Preview instructions and server setup guide - -### Phase 5: Gemini Variant Suggestions (Optional) -**Conditional Execution**: Only if --variants > 1 - -```bash -IF variants_count > 1: - bash(cd .workflow/WFS-{session}/.design/prototypes && \ - ~/.claude/scripts/gemini-wrapper -p " - PURPOSE: Generate semantic layout variation rationale - TASK: Analyze synthesis-specification.md and explain {variants_count} layout approaches - MODE: analysis - CONTEXT: @{../../.brainstorming/synthesis-specification.md,../../.brainstorming/ui-designer/analysis.md} - EXPECTED: variant-suggestions.md with layout rationale for each variant - RULES: Focus on information hierarchy, component composition, user flow emphasis, layout patterns - ") -``` - -**Output**: `variant-suggestions.md` with Gemini's layout rationale - -### Phase 6: TodoWrite Integration ```javascript TodoWrite({ todos: [ - { - content: "Validate session and load design system", - status: "completed", - activeForm: "Loading design system" - }, - { - content: "Load functional requirements and UX guidelines", - status: "completed", - activeForm: "Loading requirements" - }, - { - content: "Generate UI prototypes using Codex with token enforcement", - status: "completed", - activeForm: "Generating UI prototypes" - }, - { - content: "Generate preview enhancement files (index, compare, instructions)", - status: "completed", - activeForm: "Generating preview files" - }, - { - content: "Generate layout variant suggestions using Gemini (optional)", - status: "completed", - activeForm: "Generating variant suggestions" - }, - { - content: "Create implementation notes for each prototype", - status: "completed", - activeForm: "Creating implementation notes" - } + {content: "Detect mode and load design system", status: "completed", activeForm: "Loading design system"}, + {content: "Generate {len(page_list) * variants_count} UI prototypes", status: "completed", activeForm: "Generating prototypes"}, + {content: "Generate preview files", status: "completed", activeForm: "Generating preview"} ] }); ``` +**Completion Message**: +``` +UI generation complete for session: {session_id} +Mode: {mode} | Pages: {page_list} | Variants: {variants_count} + +Generated {len(page_list) * variants_count} prototypes: +{list_generated_files} + +Location: {base_path}/.design/prototypes/ + +Preview: Open index.html or run: python -m http.server 8080 + +Next: /workflow:design:design-update --session {session_id} --selected-prototypes "{selected_ids}" +``` + ## Output Structure ``` diff --git a/CHANGELOG.md b/CHANGELOG.md index b747231e..169ca374 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,126 @@ 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.1] - 2025-10-07 + +### 🚀 Enhanced UI Design Workflow with Agent Mode & Flexible Inputs + +This release significantly enhances the UI design workflow with agent-driven creative exploration, unified variant control, dual-mode support (standalone/integrated), and flexible input sources (images + text prompts). + +#### Added + +**Unified Variant Control**: +- **`--variants `**: Single parameter controls both style cards AND UI prototypes generation + - Default: 3 | Range: 1-5 + - Data flow: `auto.md` → `style-extract` → `ui-generate` + - Example: `--variants 3` generates 3 style cards and 3 UI variants per page + +**Agent Creative Exploration Mode** (`--use-agent`): +- **style-extract**: Parallel generation of distinctly different design directions + - Conventional mode: Subtle variations within same core style + - Agent mode: Dramatically different aesthetics (e.g., "Modern Minimalist" vs "Brutalist Tech" vs "Organic Warmth") + - Uses `conceptual-planning-agent` for creative exploration +- **ui-generate**: Diverse layout strategies exploration + - Conventional mode: Minor layout differences + - Agent mode: Structural variations (F-Pattern, Asymmetric Grid, Card-Based Modular) + - Parallel execution for efficiency + +**Dual Mode Support**: +- **Integrated Mode** (with `--session`): Works within existing workflow session + - Location: `.workflow/WFS-{session}/` + - Reads from `.brainstorming/` artifacts + - Phase 4 (design-update) updates synthesis-specification.md +- **Standalone Mode** (without `--session`): Independent quick prototyping + - Auto-creates: `design-session-YYYYMMDD-HHMMSS/` + - No dependency on brainstorming phase + - Phase 4 (design-update) is skipped + - Outputs final summary instead + +**Dual Input Source Support**: +- **`--images`**: Reference image paths (optional, default: `design-refs/*`) +- **`--prompt`**: Text description of design style (NEW) +- **Hybrid Mode**: Both combined - text guides image analysis +- Input modes: + - Pure image: Existing triple vision analysis + - Pure text: Claude keywords → Gemini philosophy → Codex tokens + - Hybrid: Text as context for visual analysis + +#### Changed + +**Command Interface Simplification**: +- **`/workflow:design:auto`**: + - `--session` now optional (enables standalone mode when omitted) + - `--images` now optional (defaults to `design-refs/*`) + - Added `--prompt` for text-based design input + - Added `--use-agent` for creative exploration + - **Before**: `/workflow:design:auto --session WFS-auth --images "refs/*.png" --pages "login"` + - **After**: `/workflow:design:auto --pages "login"` (all defaults) + - **Agent Mode**: `/workflow:design:auto --prompt "Modern SaaS" --pages "home" --variants 3 --use-agent` + +- **`/workflow:design:style-extract`**: + - Added `--variants ` parameter + - Added `--use-agent` flag + - Added `--prompt ` parameter + - `--session` now optional + - Supports image-only, text-only, or hybrid inputs + +- **`/workflow:design:ui-generate`**: + - Added `--use-agent` flag + - `--session` now optional + - Removed `--style-overrides` (simplified) + - Agent mode enables parallel layout exploration + +#### Usage Examples + +**Standalone Quick Prototyping**: +```bash +# Pure text, agent exploration +/workflow:design:auto --prompt "Modern minimalist blog, dark theme" --pages "home,article" --variants 3 --use-agent + +# Pure image, conventional mode +/workflow:design:auto --images "refs/*.png" --pages "dashboard" --variants 2 + +# Hybrid input +/workflow:design:auto --images "current-app.png" --prompt "Modernize with Linear.app style" --pages "tasks,settings" --use-agent +``` + +**Integrated Workflow Enhancement**: +```bash +# Within existing workflow session +/workflow:design:auto --session WFS-app-refresh --images "refs/*.png" --pages "dashboard" --variants 3 --use-agent +``` + +#### Technical Details + +**Agent Mode Architecture**: +- Uses `conceptual-planning-agent` for both style-extract and ui-generate phases +- Parallel task execution: N variants × M pages run concurrently +- Theme diversity strategies: + - style-extract: Creative theme generation (Minimalist, Brutalist, Organic) + - ui-generate: Layout strategy assignment (F-Pattern, Grid, Asymmetric) +- Quality assurance: All variants maintain strict token adherence and WCAG AA compliance + +**Mode Detection Logic**: +```bash +# Session mode +IF --session provided: mode = "integrated" +ELSE: mode = "standalone", auto-create design-session-YYYYMMDD-HHMMSS/ + +# Execution mode +IF --use-agent: mode = "agent" (creative exploration) +ELSE: mode = "conventional" (triple vision) + +# Input mode +IF --images AND --prompt: mode = "hybrid" +ELSE IF --images: mode = "image" +ELSE IF --prompt: mode = "text" +``` + +**Backward Compatibility**: +- All existing commands continue to work unchanged +- New parameters are optional with sensible defaults +- No breaking changes to command interfaces + ## [3.5.0] - 2025-10-06 ### 🎨 UI Design Workflow with Triple Vision Analysis & Interactive Preview