diff --git a/.claude/commands/workflow/ui-design/consolidate.md b/.claude/commands/workflow/ui-design/consolidate.md index 85dce886..4f781150 100644 --- a/.claude/commands/workflow/ui-design/consolidate.md +++ b/.claude/commands/workflow/ui-design/consolidate.md @@ -13,26 +13,26 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*) # Style Consolidation Command ## Overview -Consolidate user-selected style variants into a unified, production-ready design system using Claude's native synthesis capabilities. Merges token proposals from multiple style cards into a cohesive design language. +Consolidate user-selected style variants into unified or separate production-ready design systems using Claude's native synthesis capabilities. Merges token proposals from multiple style cards into cohesive design language(s). ## Core Philosophy - **Claude-Native**: 100% Claude-driven consolidation, no external tools - **Token Merging**: Combines `proposed_tokens` from selected variants - **Intelligent Synthesis**: Resolves conflicts, ensures consistency -- **Production-Ready**: Complete design system with documentation +- **Production-Ready**: Complete design system(s) with documentation +- **Dual Mode**: Unified (1 merged system) or Separate (N independent systems) ## Execution Protocol ### Phase 1: Path Resolution & Variant Loading + ```bash # Determine base path IF --base-path provided: - base_path = {provided_base_path} # e.g., ".workflow/WFS-xxx/runs/run-xxx/.design" + base_path = {provided_base_path} ELSE IF --session provided: - session_id = {provided_session} - base_path = ".workflow/WFS-{session_id}/latest/.design" # Use latest run + base_path = ".workflow/WFS-{session}/latest/.design" ELSE: - # Standalone mode: search for most recent design-session in scratchpad base_path = find_latest_design_session(".workflow/.scratchpad/") # Verify extraction output exists @@ -44,14 +44,14 @@ style_cards = Read(style_cards_path) total_variants = len(style_cards.style_cards) ``` -### Phase 2: Variant Selection (Count-Based) +### Phase 2: Variant Selection & Mode Determination + ```bash # Determine how many variants to consolidate IF --variants provided: variants_count = {provided_count} VALIDATE: 1 <= variants_count <= total_variants ELSE: - # Default to all variants variants_count = total_variants # Select first N variants @@ -61,11 +61,14 @@ VERIFY: selected_variants.length > 0 # Determine consolidation mode IF --keep-separate provided: consolidation_mode = "separate" # Generate N independent design systems + REPORT: "Mode: Separate - generating {variants_count} independent design systems" ELSE: - consolidation_mode = "unified" # Merge into 1 design system + consolidation_mode = "unified" # Merge into 1 design system + REPORT: "Mode: Unified - merging {variants_count} variants into one design system" ``` ### Phase 3: Load Design Context (Optional) + ```bash # Load brainstorming context if available design_context = "" @@ -80,6 +83,7 @@ ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md): **Route based on consolidation_mode**: #### Mode A: Unified Consolidation (Default) + Merges all style variants into a single, cohesive design system. **Synthesis Prompt Template**: @@ -111,54 +115,32 @@ TASK: Consolidate these {selected_variants.length} style variant(s) into a singl CONSOLIDATION RULES: 1. **Merge Token Proposals**: Combine all `proposed_tokens` into one unified system -2. **Resolve Conflicts**: When variants disagree (e.g., different primary colors), choose the most appropriate value or create a balanced compromise +2. **Resolve Conflicts**: When variants disagree, choose the most appropriate value or create a balanced compromise 3. **Maintain Completeness**: Ensure all token categories are present (colors, typography, spacing, etc.) 4. **Semantic Naming**: Use clear, semantic names (e.g., "brand-primary" not "color-1") 5. **Accessibility**: Validate WCAG AA contrast ratios (4.5:1 text, 3:1 UI) 6. **OKLCH Format**: All colors must use oklch(L C H / A) format 7. **Design Philosophy**: Synthesize a unified philosophy statement from variant descriptions -OUTPUT: Generate the following files as JSON/Markdown: +OUTPUT: Generate the following files: FILE 1: design-tokens.json { "colors": { - "brand": { - "primary": "oklch(...)", - "secondary": "oklch(...)", - "accent": "oklch(...)" - }, - "surface": { - "background": "oklch(...)", - "elevated": "oklch(...)", - "overlay": "oklch(...)" - }, - "semantic": { - "success": "oklch(...)", - "warning": "oklch(...)", - "error": "oklch(...)", - "info": "oklch(...)" - }, - "text": { - "primary": "oklch(...)", - "secondary": "oklch(...)", - "tertiary": "oklch(...)", - "inverse": "oklch(...)" - }, - "border": { - "default": "oklch(...)", - "strong": "oklch(...)", - "subtle": "oklch(...)" - } + "brand": { "primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)" }, + "surface": { "background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)" }, + "semantic": { "success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)" }, + "text": { "primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)" }, + "border": { "default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)" } }, "typography": { "font_family": { "heading": "...", "body": "...", "mono": "..." }, - "font_size": { "xs": "...", ..., "4xl": "..." }, - "font_weight": { "normal": "...", "medium": "...", "semibold": "...", "bold": "..." }, - "line_height": { "tight": "...", "normal": "...", "relaxed": "..." }, - "letter_spacing": { "tight": "...", "normal": "...", "wide": "..." } + "font_size": { "xs": "...", "sm": "...", "base": "...", "lg": "...", "xl": "...", "2xl": "...", "3xl": "...", "4xl": "..." }, + "font_weight": { "normal": "400", "medium": "500", "semibold": "600", "bold": "700" }, + "line_height": { "tight": "1.25", "normal": "1.5", "relaxed": "1.75" }, + "letter_spacing": { "tight": "-0.025em", "normal": "0", "wide": "0.025em" } }, - "spacing": { "0": "0", "1": "0.25rem", ..., "24": "6rem" }, + "spacing": { "0": "0", "1": "0.25rem", "2": "0.5rem", ..., "24": "6rem" }, "border_radius": { "none": "0", "sm": "0.25rem", ..., "full": "9999px" }, "shadows": { "sm": "...", "md": "...", "lg": "...", "xl": "..." }, "breakpoints": { "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" } @@ -176,43 +158,15 @@ FILE 2: style-guide.md - **Secondary**: {value} - {usage description} - **Accent**: {value} - {usage description} -### Surface Colors -{List all surface colors with usage} - -### Semantic Colors -{List semantic colors with accessibility notes} - -### Text Colors -{List text colors with contrast ratios} +### Surface Colors, Semantic Colors, Text Colors, Border Colors +{List all with usage and accessibility notes} ## Typography -### Font Families -{List font families with fallbacks} +### Font Families, Type Scale, Usage Examples +{Complete typography documentation} -### Type Scale -{Show scale with examples} - -### Usage Examples -```css -.heading-primary { - font-family: var(--font-family-heading); - font-size: var(--font-size-3xl); - font-weight: var(--font-weight-bold); -} -``` - -## Spacing System -{Describe spacing scale and usage patterns} - -## Component Guidelines -### Buttons -{Token-based button styling examples} - -### Cards -{Token-based card styling examples} - -### Forms -{Token-based form styling examples} +## Spacing System, Component Guidelines +{Spacing patterns and component token examples} ## Accessibility - All text meets WCAG AA (4.5:1 minimum) @@ -223,34 +177,13 @@ FILE 3: tailwind.config.js module.exports = { theme: { extend: { - colors: { - brand: { - primary: '{value}', - secondary: '{value}', - accent: '{value}' - }, - // ... all color tokens - }, - fontFamily: { - heading: [{fonts}], - body: [{fonts}], - mono: [{fonts}] - }, - fontSize: { - // ... all size tokens - }, - spacing: { - // ... all spacing tokens - }, - borderRadius: { - // ... all radius tokens - }, - boxShadow: { - // ... all shadow tokens - }, - screens: { - // ... all breakpoint tokens - } + colors: { brand: { primary: '{value}', ... }, ... }, + fontFamily: { heading: [{fonts}], body: [{fonts}], mono: [{fonts}] }, + fontSize: { ... }, + spacing: { ... }, + borderRadius: { ... }, + boxShadow: { ... }, + screens: { ... } } } } @@ -261,22 +194,10 @@ FILE 4: validation-report.json "consolidated_variants": {variant_ids}, "timestamp": "{ISO timestamp}", "validation_results": { - "colors": { - "total": {count}, - "wcag_aa_compliant": {count}, - "warnings": [{any contrast issues}] - }, - "typography": { - "font_families": {count}, - "scale_sizes": {count} - }, - "spacing": { - "scale_values": {count} - }, - "accessibility": { - "status": "pass|warnings", - "issues": [{list any issues}] - }, + "colors": { "total": {count}, "wcag_aa_compliant": {count}, "warnings": [{issues}] }, + "typography": { "font_families": {count}, "scale_sizes": {count} }, + "spacing": { "scale_values": {count} }, + "accessibility": { "status": "pass|warnings", "issues": [{list}] }, "completeness": { "required_categories": ["colors", "typography", "spacing", "border_radius", "shadows", "breakpoints"], "present_categories": [{list}], @@ -301,43 +222,117 @@ Provide each file's content in clearly labeled sections: {JSON content} ``` -### Phase 5: Parse & Write Output Files -```bash -# Parse Claude's response into separate files -CREATE: {base_path}/.design/style-consolidation/ +**Output Location**: `{base_path}/style-consolidation/` -# Extract and write each file -parsed_output = parse_claude_response(claude_response) +--- -Write({ - file_path: "{base_path}/.design/style-consolidation/design-tokens.json", - content: parsed_output.design_tokens -}) +#### Mode B: Separate Consolidation (--keep-separate) -Write({ - file_path: "{base_path}/.design/style-consolidation/style-guide.md", - content: parsed_output.style_guide -}) +Generates N independent design systems, each refining one style variant into a complete production-ready system. -Write({ - file_path: "{base_path}/.design/style-consolidation/tailwind.config.js", - content: parsed_output.tailwind_config -}) +**For each variant, use this Synthesis Prompt Template**: +``` +Create a production-ready design system for the following style variant. -Write({ - file_path: "{base_path}/.design/style-consolidation/validation-report.json", - content: parsed_output.validation_report -}) +SESSION: {session_id} +VARIANT: {variant.id} + +VARIANT DATA: + Name: {variant.name} + Description: {variant.description} + Design Philosophy: {variant.design_philosophy} + + Proposed Tokens: + {JSON.stringify(variant.proposed_tokens, null, 2)} + +{IF design_context: +DESIGN CONTEXT (from brainstorming): +{design_context} +} + +TASK: Refine this style variant into a complete, production-ready design system. + +REFINEMENT RULES: +1. **Complete Token Coverage**: Ensure all categories are present (colors, typography, spacing, etc.) +2. **Fill Gaps**: If any tokens are missing, generate appropriate values based on the variant's philosophy +3. **Maintain Style Identity**: Preserve the unique characteristics of this variant +4. **Semantic Naming**: Use clear, semantic names (e.g., "brand-primary" not "color-1") +5. **Accessibility**: Validate WCAG AA contrast ratios (4.5:1 text, 3:1 UI) +6. **OKLCH Format**: All colors must use oklch(L C H / A) format +7. **Design Philosophy**: Expand and articulate the variant's design philosophy + +OUTPUT: Generate the same 4 files as unified mode (design-tokens.json, style-guide.md, tailwind.config.js, validation-report.json) + +RESPONSE FORMAT: +Provide each file's content in clearly labeled sections: + +===== design-tokens.json ===== +{JSON content} + +===== style-guide.md ===== +{Markdown content} + +===== tailwind.config.js ===== +{JavaScript content} + +===== validation-report.json ===== +{JSON content} ``` -### Phase 6: TodoWrite & Completion +**Output Location**: `{base_path}/style-consolidation/style-{n}/` + +For N variants, generate N separate subdirectories: +``` +{base_path}/style-consolidation/ +├── style-1/ +│ ├── design-tokens.json +│ ├── style-guide.md +│ ├── tailwind.config.js +│ └── validation-report.json +├── style-2/ +│ └── ... (same structure) +└── style-N/ + └── ... (same structure) +``` + +--- + +### Phase 5: Parse & Write Output Files + +#### Unified Mode Output +```bash +# Parse Claude's response +CREATE: {base_path}/style-consolidation/ +parsed_output = parse_claude_response(claude_response) + +Write({base_path}/style-consolidation/design-tokens.json, parsed_output.design_tokens) +Write({base_path}/style-consolidation/style-guide.md, parsed_output.style_guide) +Write({base_path}/style-consolidation/tailwind.config.js, parsed_output.tailwind_config) +Write({base_path}/style-consolidation/validation-report.json, parsed_output.validation_report) +``` + +#### Separate Mode Output +```bash +# Parse each variant's response +FOR variant_id IN range(1, variants_count + 1): + CREATE: {base_path}/style-consolidation/style-{variant_id}/ + parsed_output = parse_claude_response(claude_responses[variant_id - 1]) + + Write({base_path}/style-consolidation/style-{variant_id}/design-tokens.json, parsed_output.design_tokens) + Write({base_path}/style-consolidation/style-{variant_id}/style-guide.md, parsed_output.style_guide) + Write({base_path}/style-consolidation/style-{variant_id}/tailwind.config.js, parsed_output.tailwind_config) + Write({base_path}/style-consolidation/style-{variant_id}/validation-report.json, parsed_output.validation_report) +``` + +### Phase 6: Completion + ```javascript TodoWrite({ todos: [ {content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"}, - {content: "Select and validate variant IDs", status: "completed", activeForm: "Selecting variants"}, + {content: "Select variants and determine mode", status: "completed", activeForm: "Selecting variants"}, {content: "Load design context from brainstorming", status: "completed", activeForm: "Loading context"}, - {content: "Synthesize unified design system with Claude", status: "completed", activeForm: "Synthesizing design system"}, + {content: "Synthesize design system(s) with Claude", status: "completed", activeForm: "Synthesizing design system"}, {content: "Write consolidated design system files", status: "completed", activeForm: "Writing output files"} ] }); @@ -347,37 +342,67 @@ TodoWrite({ ``` ✅ Style consolidation complete for session: {session_id} +Mode: {consolidation_mode} Consolidated {selected_variants.length} variant(s): {FOR each variant: - {variant.name} ({variant.id})} +{IF unified mode: Validation Summary: - Colors: {total_colors} (WCAG AA: {compliant_count}/{total_colors}) - Typography: {scale_count} sizes - Spacing: {scale_count} values - Accessibility: {status} -📂 Output: {base_path}/.design/style-consolidation/ - ├── design-tokens.json (Final token definitions) - ├── style-guide.md (Design system documentation) - ├── tailwind.config.js (Tailwind configuration) - └── validation-report.json (Validation audit) +📂 Output: {base_path}/style-consolidation/ + ├── design-tokens.json + ├── style-guide.md + ├── tailwind.config.js + └── validation-report.json +} -Next: /workflow:ui-design:generate --session {session_id} --pages "dashboard,auth" +{IF separate mode: +Generated {variants_count} independent design systems: + +📂 Output: {base_path}/style-consolidation/ +├── style-1/ (design-tokens.json, style-guide.md, tailwind.config.js, validation-report.json) +├── style-2/ (same structure) +└── style-{variants_count}/ (same structure) +} + +Next: /workflow:ui-design:generate --session {session_id} {IF separate: --style-variants {variants_count}} --pages "dashboard,auth" Note: When called from /workflow:ui-design:auto, UI generation is triggered automatically. ``` ## Output Structure +### Unified Mode ``` -.workflow/WFS-{session}/.design/style-consolidation/ -├── design-tokens.json # Final validated CSS tokens -├── style-guide.md # Comprehensive design system documentation +{base_path}/style-consolidation/ +├── design-tokens.json # Merged token definitions +├── style-guide.md # Comprehensive design documentation ├── tailwind.config.js # Tailwind theme configuration └── validation-report.json # Validation audit results ``` -### design-tokens.json Format +### Separate Mode (--keep-separate) +``` +{base_path}/style-consolidation/ +├── style-1/ +│ ├── design-tokens.json # Style 1 token definitions +│ ├── style-guide.md # Style 1 documentation +│ ├── tailwind.config.js # Style 1 Tailwind config +│ └── validation-report.json # Style 1 validation +├── style-2/ +│ └── ... (same structure) +└── style-N/ + └── ... (same structure) +``` + +## design-tokens.json Format + +Complete token structure with OKLCH colors and semantic naming: + ```json { "colors": { @@ -482,20 +507,49 @@ Note: When called from /workflow:ui-design:auto, UI generation is triggered auto ``` ## Error Handling + - **No style cards found**: Report error, suggest running `/workflow:ui-design:extract` first -- **Invalid variant IDs**: List available IDs, auto-select all if called from auto workflow +- **Invalid variant count**: List available count, auto-select all if called from auto workflow - **Parsing errors**: Retry with stricter format instructions - **Validation warnings**: Report but continue (non-blocking) +- **Missing categories**: Claude will fill gaps based on design philosophy -## Key Improvements Over Previous Version +## Key Features -1. **Zero External Dependencies**: No `gemini-wrapper`, no `codex` - pure Claude -2. **Direct Token Merging**: Reads `proposed_tokens` from style cards directly -3. **Single-Pass Synthesis**: One comprehensive prompt generates all outputs -4. **Reproducible**: Deterministic structure with clear consolidation rules -5. **Streamlined**: `Load → Synthesize → Write` (3 steps vs 7+ previously) +1. **Zero External Dependencies** + - No `gemini-wrapper`, no `codex` - pure Claude synthesis + - Single-pass comprehensive prompt generates all outputs + +2. **Dual Consolidation Modes** + - Unified: Merge N variants → 1 design system (default) + - Separate: Refine N variants → N independent systems (--keep-separate) + +3. **Direct Token Merging** + - Reads `proposed_tokens` from style cards directly + - Intelligent conflict resolution with clear rules + +4. **Complete Design System Output** + - design-tokens.json (CSS tokens) + - style-guide.md (documentation) + - tailwind.config.js (framework integration) + - validation-report.json (quality audit) + +5. **Production-Ready Quality** + - WCAG AA accessibility validation + - OKLCH color format for perceptual uniformity + - Semantic token naming + - Complete token coverage + +6. **Streamlined Workflow** + - `Load → Synthesize → Write` (3 core steps) + - Reproducible with deterministic structure + - Context-aware (integrates brainstorming artifacts) ## Integration Points + - **Input**: `style-cards.json` from `/workflow:ui-design:extract` (with `proposed_tokens`) -- **Output**: `design-tokens.json` for `/workflow:ui-design:generate` +- **Output**: + - Unified: `style-consolidation/design-tokens.json` for `/workflow:ui-design:generate` + - Separate: `style-consolidation/style-{n}/design-tokens.json` for matrix mode generation - **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md` +- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow diff --git a/.claude/commands/workflow/ui-design/explore-auto.md b/.claude/commands/workflow/ui-design/explore-auto.md index f539b4ff..c274aac3 100644 --- a/.claude/commands/workflow/ui-design/explore-auto.md +++ b/.claude/commands/workflow/ui-design/explore-auto.md @@ -1,66 +1,75 @@ --- name: explore-auto -description: Exploratory UI design workflow - Generate and compare multiple style × layout combinations (3×3 matrix exploration) -usage: /workflow:ui-design:explore-auto [--prompt ""] [--images ""] [--pages ""] [--session ] [--style-variants ] [--layout-variants ] [--batch-plan] -argument-hint: "[--prompt \"Modern SaaS with 3 styles\"] [--images \"refs/*.png\"] [--pages \"dashboard,auth\"] [--session WFS-xxx] [--style-variants 3] [--layout-variants 3]" +description: Exploratory UI design workflow - Generate and compare multiple style × layout combinations for pages OR components (3×3 matrix exploration) +usage: /workflow:ui-design:explore-auto [--prompt ""] [--images ""] [--pages "" | --components ""] [--session ] [--style-variants ] [--layout-variants ] [--batch-plan] +argument-hint: "[--prompt \"Modern SaaS with 3 styles\"] [--images \"refs/*.png\"] [--pages \"dashboard,auth\" | --components \"navbar,hero,card\"] [--session WFS-xxx] [--style-variants 3] [--layout-variants 3]" examples: - /workflow:ui-design:explore-auto --prompt "Generate 3 style variants for modern blog: home, article, author" - /workflow:ui-design:explore-auto --prompt "SaaS dashboard and settings with 2 layout options" - /workflow:ui-design:explore-auto --images "refs/*.png" --prompt "E-commerce: home, product, cart" --style-variants 3 --layout-variants 3 - /workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" + - /workflow:ui-design:explore-auto --components "navbar,hero" --prompt "Compare 3 navigation bar designs" --style-variants 3 --layout-variants 2 + - /workflow:ui-design:explore-auto --components "card,form" --images "refs/*.png" --style-variants 2 --layout-variants 3 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent) --- # UI Design Auto Workflow Command -## Overview -Fully autonomous UI design workflow: style extraction → consolidation → UI generation → design update → optional batch planning. This command orchestrates the entire design process without user intervention. +## Overview & Execution Model -## Coordinator Role -**Fully autonomous orchestrator**: Executes all phases sequentially, parsing outputs from one phase to construct the inputs for the next. Supports both standard sequential mode and parallel creative mode for generating diverse design variants. +**Fully autonomous orchestrator**: Executes all design phases sequentially from style extraction to design integration, with optional batch planning. Supports two exploration modes: -## Execution Model - Autonomous Workflow +**Exploration Modes**: +- **Page Mode** (default): Generates `style_variants × layout_variants × pages` full-page prototypes +- **Component Mode**: Generates `style_variants × layout_variants × components` isolated component prototypes -This workflow runs **fully autonomously** from start to finish: +**Autonomous Flow**: +1. User triggers: `/workflow:ui-design:explore-auto [params]` +2. Phase 1 (style-extract) → Auto-continues +3. Phase 2 (style-consolidate) → Auto-continues +4. Phase 3 (ui-generate) → Auto-continues with appropriate mode +5. Phase 4 (design-update) → Auto-continues +6. Phase 5 (batch-plan, optional) → Reports completion -1. **User triggers**: `/workflow:ui-design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard,auth" [--batch-plan]` -2. **Phase 1 executes** (style-extract) → Auto-continues -3. **Phase 2 executes** (style-consolidate) → Auto-continues -4. **Phase 3 executes** (ui-generate) → Auto-continues -5. **Phase 4 executes** (design-update) → Auto-continues -6. **Phase 5 executes** (batch-plan, optional) → Reports task files +**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon completion, coordinator constructs next command and executes immediately. No user intervention required. -**Auto-Continue Mechanism**: -- The workflow uses `TodoWrite` to track the state of each phase -- Upon successful completion of a phase, the coordinator immediately constructs and executes the command for the next phase -- This pattern ensures a seamless flow +**Mode Selection**: Determined by `--pages` vs `--components` parameter (mutually exclusive). ## Core Rules -1. **Start Immediately**: First action is `TodoWrite` initialization, second action is Phase 1 command execution -2. **No Preliminary Analysis**: Do not read files or validate before Phase 1 (sub-commands handle their own validation) -3. **Parse Every Output**: Extract required data from each command's output for the next phase -4. **Auto-Continue**: After each phase, automatically proceed to the next without pausing -5. **Track Progress**: Update `TodoWrite` after every phase completion -6. **Default to All**: When selecting variants or prototypes for the next phase, the autonomous workflow defaults to using **all** generated items +1. **Start Immediately**: TodoWrite initialization → Phase 1 execution +2. **No Preliminary Validation**: Sub-commands handle their own validation +3. **Parse & Pass**: Extract data from each output for next phase +4. **Default to All**: When selecting variants/prototypes, use ALL generated items +5. **Track Progress**: Update TodoWrite after each phase ## Parameter Requirements **Optional Parameters** (all have smart defaults): -- `--pages ""`: Pages to generate (if omitted, inferred from prompt/session) -- `--session `: Workflow session ID (if omitted, runs in standalone mode) -- `--images ""`: Reference image paths (default: `design-refs/*`) -- `--prompt ""`: Text description of design style and pages (supports intelligent parsing) -- `--style-variants `: Number of style variants to generate (default: inferred from prompt or 3, range: 1-5) -- `--layout-variants `: Number of layout variants per style (default: inferred from prompt or 3, range: 1-5) -- `--batch-plan`: Auto-generate implementation tasks after design-update (integrated mode only) +- `--pages ""`: Pages to generate (inferred from prompt/session if omitted) - **Page Mode** +- `--components ""`: Components to generate (inferred from prompt if omitted) - **Component Mode** +- `--session `: Workflow session ID (standalone mode if omitted) +- `--images ""`: Reference image paths (default: `design-refs/*`) +- `--prompt ""`: Design style and pages/components description +- `--style-variants `: Style variants (default: inferred from prompt or 3, range: 1-5) +- `--layout-variants `: Layout variants per style (default: inferred or 3, range: 1-5) +- `--batch-plan`: Auto-generate implementation tasks after design-update -**Input Source Rules**: -- Must provide at least one of: `--images` or `--prompt` -- Both can be combined for guided style analysis +**Input Rules**: +- Must provide at least one: `--images` or `--prompt` +- Both can be combined for guided analysis +- `--pages` and `--components` are **mutually exclusive** +- Default mode: **Page Mode** if neither specified -**Intelligent Prompt Parsing**: -The workflow extracts variant counts from natural language: +**Supported Component Types**: +- **Navigation**: navbar, header, menu, breadcrumb, tabs, sidebar +- **Content**: hero, card, list, table, grid, timeline +- **Input**: form, search, filter, input-group +- **Feedback**: modal, alert, toast, badge, progress +- **Media**: gallery, carousel, video-player, image-card +- **Other**: footer, pagination, dropdown, tooltip, avatar + +**Intelligent Prompt Parsing**: Extracts variant counts from natural language: - "Generate **3 style variants**" → `--style-variants 3` - "**2 layout options**" → `--layout-variants 2` - "Create **4 styles** with **2 layouts each**" → `--style-variants 4 --layout-variants 2` @@ -68,15 +77,14 @@ The workflow extracts variant counts from natural language: ## Execution Modes -### Matrix Mode (Default and Only) -- Generates `style_variants × layout_variants × pages` prototypes in 3×3 matrix pattern -- **Phase 1 (Style Extraction)**: Generates `style_variants` style options -- **Phase 2 (Style Consolidation)**: Creates `style_variants` independent design systems -- **Phase 3 (Matrix Generation)**: Generates `style_variants × layout_variants` prototypes per page -- This is the only supported mode - focused on systematic design exploration +**Matrix Mode** (default and only): +- Generates `style_variants × layout_variants × pages` prototypes +- **Phase 1**: `style_variants` style options +- **Phase 2**: `style_variants` independent design systems +- **Phase 3**: `style_variants × layout_variants` prototypes per page -### Integrated vs. Standalone Mode -- `--session` flag determines if the workflow is integrated with a larger session or runs standalone +**Integrated vs. Standalone**: +- `--session` flag determines session integration or standalone execution ## 6-Phase Execution @@ -84,53 +92,36 @@ The workflow extracts variant counts from natural language: ```bash # Extract variant counts from prompt if not explicitly provided IF --prompt provided AND (NOT --style-variants OR NOT --layout-variants): - prompt_text = {--prompt value} - - # Parse style variants: "3 style variants", "generate 4 styles", etc. + # Parse: "3 style variants", "4 styles", "2 layout options", "3 layouts each" style_match = regex_search(prompt_text, r"(\d+)\s*(style\s*variants?|styles?)") - IF style_match AND NOT --style-variants: - style_variants = int(style_match.group(1)) - ELSE: - style_variants = --style-variants OR 3 # Default to 3 - - # Parse layout variants: "2 layout options", "3 layouts each", etc. layout_match = regex_search(prompt_text, r"(\d+)\s*(layout\s*(variants?|options?)|layouts?)") - IF layout_match AND NOT --layout-variants: - layout_variants = int(layout_match.group(1)) - ELSE: - layout_variants = --layout-variants OR 3 # Default to 3 + + style_variants = style_match ? int(match[1]) : (--style-variants OR 3) + layout_variants = layout_match ? int(match[1]) : (--layout-variants OR 3) ELSE: style_variants = --style-variants OR 3 layout_variants = --layout-variants OR 3 -VALIDATE: 1 <= style_variants <= 5 -VALIDATE: 1 <= layout_variants <= 5 - -STORE: style_variants, layout_variants # For Phase 1 and Phase 3 +VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5 +STORE: style_variants, layout_variants ``` ### Phase 0b: Run Initialization & Directory Setup ```bash -# Generate run ID with timestamp +# Generate run ID and determine base path run_id = "run-$(date +%Y%m%d-%H%M%S)" -# Determine base path IF --session: - session_id = {provided_session} base_path = ".workflow/WFS-{session_id}/runs/${run_id}" ELSE: - # Standalone mode: use scratchpad session_id = "design-session-$(date +%Y%m%d-%H%M%S)" base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}" -# Create run directory structure -Bash(mkdir -p "${base_path}/.design/style-extraction") -Bash(mkdir -p "${base_path}/.design/style-consolidation") -Bash(mkdir -p "${base_path}/.design/prototypes") +# Create directories +Bash(mkdir -p "${base_path}/.design/{style-extraction,style-consolidation,prototypes}") -# Initialize run metadata -Write({base_path}/.run-metadata.json): -{ +# Initialize metadata +Write({base_path}/.run-metadata.json): { "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)", @@ -149,273 +140,374 @@ Write({base_path}/.run-metadata.json): IF --session: Bash(cd ".workflow/WFS-{session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}") ELSE: - # Standalone mode: create symlink in scratchpad session dir Bash(cd ".workflow/.scratchpad/${session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}") -STORE: run_id, base_path # Use throughout workflow +STORE: run_id, base_path ``` ### Phase 0c: Enhanced Page Inference with Dynamic Analysis ```bash -# Initialize page_list = [] page_source = "none" -page_structure = null # Store structured analysis results -# Priority 1: Explicit --pages parameter (with enhanced cleaning) +# Priority 1: Explicit --pages parameter IF --pages provided: - # Enhanced cleaning: tolerate spaces, multiple delimiters raw_pages = {--pages value} - # Split by comma, semicolon, or Chinese comma, then clean each + # Split by comma/semicolon/Chinese comma, clean and normalize page_list = split_and_clean(raw_pages, delimiters=[",", ";", "、"]) - # Strip whitespace, convert to lowercase, replace spaces with hyphens page_list = [p.strip().lower().replace(" ", "-") for p in page_list if p.strip()] page_source = "explicit" REPORT: "📋 Using explicitly provided pages: {', '.join(page_list)}" -# Priority 2: Dynamic prompt decomposition (using Claude's analysis) +# Priority 2: Dynamic prompt decomposition (Claude analysis) ELSE IF --prompt provided: REPORT: "🔍 Analyzing prompt to identify pages..." - # Use main Claude to analyze prompt structure + # Internal Claude analysis analysis_prompt = """ - Analyze the following UI design request and identify all distinct pages/screens needed. + Analyze the UI design request and identify all distinct pages/screens. - User Request: "{prompt_text}" + Request: "{prompt_text}" - Output a JSON object with this structure: + Output JSON: { - "pages": [ - {"name": "page-name", "purpose": "brief description", "priority": "high|medium|low"} - ], - "shared_components": ["header", "footer", "sidebar"], - "navigation_structure": { - "primary": ["home", "dashboard"], - "secondary": ["settings", "profile"] - } + "pages": [{"name": "page-name", "purpose": "description", "priority": "high|medium|low"}], + "shared_components": ["header", "footer"], + "navigation_structure": {"primary": ["home"], "secondary": ["settings"]} } Rules: - - Normalize page names to be URL-friendly (lowercase, use hyphens, no spaces) - - Consolidate synonyms (e.g., "homepage" → "home", "user-profile" → "profile") - - Identify hierarchical relationships if mentioned - - Prioritize pages based on user intent - - Common page patterns: home, dashboard, settings, profile, login, signup, about, contact + - Normalize to URL-friendly (lowercase, hyphens, no spaces) + - Consolidate synonyms (homepage → home, user-profile → profile) + - Identify hierarchical relationships + - Prioritize by user intent + - Common patterns: home, dashboard, settings, profile, login, signup """ - # Execute analysis (internal to main Claude, no external tool needed) page_structure = analyze_prompt_structure(analysis_prompt, prompt_text) page_list = extract_page_names_from_structure(page_structure) page_source = "prompt_analysis" - # Display analysis results IF page_list: REPORT: "📋 Identified pages from prompt:" - FOR each page IN page_structure.pages: + FOR page IN page_structure.pages: REPORT: " • {page.name}: {page.purpose} [{page.priority}]" - IF page_structure.shared_components: - REPORT: "🔧 Shared components: {', '.join(page_structure.shared_components)}" - ELSE: - REPORT: "⚠️ No pages could be extracted from the prompt." + REPORT: "🔧 Shared components: {', '.join(shared_components)}" # Priority 3: Extract from synthesis-specification.md ELSE IF --session AND exists(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md): synthesis = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) page_list = extract_pages_from_synthesis(synthesis) page_source = "synthesis" - REPORT: "📋 Extracted pages from synthesis: {', '.join(page_list)}" + REPORT: "📋 Extracted from synthesis: {', '.join(page_list)}" -# Priority 4: Final fallback - default page +# Priority 4: Fallback default IF NOT page_list: page_list = ["home"] page_source = "default" REPORT: "⚠️ No pages identified, using default: 'home'" -# Enhanced validation +# Validate page names validated_pages = [] invalid_pages = [] FOR page IN page_list: - # Clean: strip, lowercase, replace spaces with hyphens - cleaned_page = page.strip().lower().replace(" ", "-") - # Validate: must start with letter/number, can contain letters, numbers, hyphens, underscores - IF regex_match(cleaned_page, r"^[a-z0-9][a-z0-9_-]*$"): - validated_pages.append(cleaned_page) + cleaned = page.strip().lower().replace(" ", "-") + IF regex_match(cleaned, r"^[a-z0-9][a-z0-9_-]*$"): + validated_pages.append(cleaned) ELSE: invalid_pages.append(page) IF invalid_pages: - REPORT: "⚠️ Skipped invalid page names: {', '.join(invalid_pages)}" - REPORT: " Valid format: lowercase, alphanumeric, hyphens, underscores (e.g., 'user-profile', 'dashboard')" + REPORT: "⚠️ Skipped invalid: {', '.join(invalid_pages)}" IF NOT validated_pages: validated_pages = ["home"] - REPORT: "⚠️ All page names invalid, using default: 'home'" + REPORT: "⚠️ All invalid, using default: 'home'" -# Interactive confirmation step +# Interactive confirmation REPORT: "" REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" REPORT: "📌 PAGE LIST CONFIRMATION" REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" REPORT: "Source: {page_source}" -REPORT: "Pages to generate ({len(validated_pages)}): {', '.join(validated_pages)}" -REPORT: "" -REPORT: "⏸️ Please confirm or modify the page list:" +REPORT: "Pages ({len(validated_pages)}): {', '.join(validated_pages)}" REPORT: "" REPORT: "Options:" -REPORT: " • Type 'continue' or 'yes' to proceed with these pages" -REPORT: " • Type 'pages: page1, page2, page3' to replace the entire list" -REPORT: " • Type 'skip: page-name' to remove specific pages" -REPORT: " • Type 'add: page-name' to add specific pages" -REPORT: "" +REPORT: " • 'continue/yes' - proceed" +REPORT: " • 'pages: page1,page2' - replace list" +REPORT: " • 'skip: page-name' - remove pages" +REPORT: " • 'add: page-name' - add pages" REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -# Wait for user input -user_confirmation = WAIT_FOR_USER_INPUT() +user_input = WAIT_FOR_USER_INPUT() -# Process user input -IF user_confirmation MATCHES r"^(continue|yes|ok|proceed)$": +# Process input +IF user_input MATCHES r"^(continue|yes|ok|proceed)$": REPORT: "✅ Proceeding with: {', '.join(validated_pages)}" -ELSE IF user_confirmation MATCHES r"^pages:\s*(.+)$": - # User provided new page list - new_pages_raw = extract_after_prefix(user_confirmation, "pages:") - new_pages = split_and_clean(new_pages_raw, delimiters=[",", ";", "、"]) +ELSE IF user_input MATCHES r"^pages:\s*(.+)$": + new_pages = split_and_clean(extract_after("pages:"), [",", ";"]) validated_pages = [p.strip().lower().replace(" ", "-") for p in new_pages if p.strip()] - REPORT: "✅ Updated page list: {', '.join(validated_pages)}" -ELSE IF user_confirmation MATCHES r"^skip:\s*(.+)$": - # Remove specified pages - pages_to_skip_raw = extract_after_prefix(user_confirmation, "skip:") - pages_to_skip = [p.strip().lower() for p in pages_to_skip_raw.split(",")] - validated_pages = [p for p in validated_pages if p not in pages_to_skip] - REPORT: "✅ Removed pages: {', '.join(pages_to_skip)}" - REPORT: " Final list: {', '.join(validated_pages)}" -ELSE IF user_confirmation MATCHES r"^add:\s*(.+)$": - # Add specified pages - pages_to_add_raw = extract_after_prefix(user_confirmation, "add:") - pages_to_add = [p.strip().lower().replace(" ", "-") for p in pages_to_add_raw.split(",") if p.strip()] - validated_pages.extend(pages_to_add) - # Remove duplicates while preserving order - validated_pages = list(dict.fromkeys(validated_pages)) - REPORT: "✅ Added pages: {', '.join(pages_to_add)}" - REPORT: " Final list: {', '.join(validated_pages)}" + REPORT: "✅ Updated: {', '.join(validated_pages)}" +ELSE IF user_input MATCHES r"^skip:\s*(.+)$": + to_skip = [p.strip().lower() for p in extract_after("skip:").split(",")] + validated_pages = [p for p in validated_pages if p not in to_skip] + REPORT: "✅ Removed: {', '.join(to_skip)}, Final: {', '.join(validated_pages)}" +ELSE IF user_input MATCHES r"^add:\s*(.+)$": + to_add = [p.strip().lower().replace(" ", "-") for p in extract_after("add:").split(",") if p.strip()] + validated_pages.extend(to_add) + validated_pages = list(dict.fromkeys(validated_pages)) # Remove duplicates + REPORT: "✅ Added: {', '.join(to_add)}, Final: {', '.join(validated_pages)}" ELSE: - REPORT: "⚠️ Invalid input format, proceeding with original list: {', '.join(validated_pages)}" + REPORT: "⚠️ Invalid input, proceeding with: {', '.join(validated_pages)}" -# Final verification IF NOT validated_pages: validated_pages = ["home"] - REPORT: "⚠️ Empty page list detected, using default: 'home'" -# Store results for subsequent phases -STORE: inferred_page_list = validated_pages # For Phase 3 -STORE: page_inference_source = page_source # Track source for metadata -STORE: page_structure_data = page_structure # Save structured data for future use +STORE: inferred_page_list = validated_pages +STORE: page_inference_source = page_source +STORE: page_structure_data = page_structure +STORE: exploration_mode = "page" +``` + +### Phase 0d: Component Inference (Component Mode Only) +```bash +component_list = [] +component_source = "none" +exploration_mode = "page" # Default + +# Determine exploration mode +IF --components provided: + exploration_mode = "component" + raw_components = {--components value} + # Split and clean + component_list = split_and_clean(raw_components, delimiters=[",", ";", "、"]) + component_list = [c.strip().lower().replace(" ", "-") for c in component_list if c.strip()] + component_source = "explicit" + REPORT: "🧩 Using explicitly provided components: {', '.join(component_list)}" + +# Component inference from prompt (if no --pages and no --components) +ELSE IF --prompt provided AND NOT --pages: + REPORT: "🔍 Analyzing prompt to identify components..." + + # Internal Claude analysis for components + analysis_prompt = """ + Analyze the UI design request and identify component-level design elements. + + Request: "{prompt_text}" + + Output JSON: + { + "components": [ + {"name": "component-type", "purpose": "description", "variants": ["variant1", "variant2"]} + ], + "component_context": "page or section where components appear", + "interaction_patterns": ["hover", "click", "scroll"] + } + + Component Categories: + - Navigation: navbar, header, menu, breadcrumb, tabs, sidebar + - Content: hero, card, list, table, grid, timeline + - Input: form, search, filter, input-group + - Feedback: modal, alert, toast, badge, progress + - Media: gallery, carousel, video-player, image-card + - Other: footer, pagination, dropdown, tooltip, avatar + + Rules: + - Normalize to lowercase with hyphens + - Be specific (e.g., "navbar" not "navigation") + - Include interaction context + """ + + component_structure = analyze_prompt_structure(analysis_prompt, prompt_text) + + # Check if prompt is component-focused + IF component_structure.components AND len(component_structure.components) > 0: + component_list = extract_component_names_from_structure(component_structure) + component_source = "prompt_analysis" + exploration_mode = "component" + + REPORT: "🧩 Identified components from prompt:" + FOR comp IN component_structure.components: + REPORT: " • {comp.name}: {comp.purpose}" + IF component_structure.interaction_patterns: + REPORT: "🎯 Interaction patterns: {', '.join(interaction_patterns)}" + +# Validate component names +IF exploration_mode == "component": + validated_components = [] + invalid_components = [] + FOR comp IN component_list: + cleaned = comp.strip().lower().replace(" ", "-") + IF regex_match(cleaned, r"^[a-z0-9][a-z0-9_-]*$"): + validated_components.append(cleaned) + ELSE: + invalid_components.append(comp) + + IF invalid_components: + REPORT: "⚠️ Skipped invalid: {', '.join(invalid_components)}" + + IF NOT validated_components: + # Fallback to page mode with default page + exploration_mode = "page" + inferred_page_list = ["home"] + REPORT: "⚠️ No valid components, switching to page mode: 'home'" + ELSE: + # Interactive confirmation for components + REPORT: "" + REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + REPORT: "🧩 COMPONENT LIST CONFIRMATION" + REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + REPORT: "Mode: Component Exploration" + REPORT: "Source: {component_source}" + REPORT: "Components ({len(validated_components)}): {', '.join(validated_components)}" + REPORT: "" + REPORT: "Options:" + REPORT: " • 'continue/yes' - proceed" + REPORT: " • 'components: comp1,comp2' - replace list" + REPORT: " • 'skip: comp-name' - remove components" + REPORT: " • 'add: comp-name' - add components" + REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + + user_input = WAIT_FOR_USER_INPUT() + + # Process input + IF user_input MATCHES r"^(continue|yes|ok|proceed)$": + REPORT: "✅ Proceeding with: {', '.join(validated_components)}" + ELSE IF user_input MATCHES r"^components:\s*(.+)$": + new_comps = split_and_clean(extract_after("components:"), [",", ";"]) + validated_components = [c.strip().lower().replace(" ", "-") for c in new_comps if c.strip()] + REPORT: "✅ Updated: {', '.join(validated_components)}" + ELSE IF user_input MATCHES r"^skip:\s*(.+)$": + to_skip = [c.strip().lower() for c in extract_after("skip:").split(",")] + validated_components = [c for c in validated_components if c not in to_skip] + REPORT: "✅ Removed: {', '.join(to_skip)}, Final: {', '.join(validated_components)}" + ELSE IF user_input MATCHES r"^add:\s*(.+)$": + to_add = [c.strip().lower().replace(" ", "-") for c in extract_after("add:").split(",") if c.strip()] + validated_components.extend(to_add) + validated_components = list(dict.fromkeys(validated_components)) # Remove duplicates + REPORT: "✅ Added: {', '.join(to_add)}, Final: {', '.join(validated_components)}" + ELSE: + REPORT: "⚠️ Invalid input, proceeding with: {', '.join(validated_components)}" + + IF NOT validated_components: + # Fallback to page mode + exploration_mode = "page" + inferred_page_list = ["home"] + REPORT: "⚠️ No components, switching to page mode: 'home'" + +STORE: inferred_component_list = validated_components IF exploration_mode == "component" ELSE [] +STORE: component_inference_source = component_source +STORE: component_structure_data = component_structure IF exploration_mode == "component" ELSE {} +STORE: exploration_mode = exploration_mode # "page" or "component" ``` ### Phase 1: Style Extraction -**Command Construction**: +**Command**: ```bash images_flag = --images present ? "--images \"{image_glob}\"" : "" prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : "" - -# Use run-scoped base path run_base_flag = "--base-path \"{base_path}/.design\"" -# Use style_variants from Phase 0a command = "/workflow:ui-design:extract {run_base_flag} {images_flag} {prompt_flag} --variants {style_variants}" -SlashCommand(command=command) +SlashCommand(command) ``` -**Auto-Continue**: On completion, proceeds to Phase 2 +**Auto-Continue**: On completion → Phase 2 --- -### Phase 2: Style Consolidation with Separation (Auto-Triggered) -**Action**: Consolidates each style variant into separate design systems for matrix generation - -**Command Construction**: +### Phase 2: Style Consolidation with Separation +**Command**: ```bash -# Use run-scoped base path and keep styles separate run_base_flag = "--base-path \"{base_path}/.design\"" -# Use count-based parameter (automatically uses all style_variants) +# Use count-based parameter with --keep-separate for matrix mode command = "/workflow:ui-design:consolidate {run_base_flag} --variants {style_variants} --keep-separate" +SlashCommand(command) ``` -**Command**: `SlashCommand(command=command)` **Result**: Generates `style_variants` independent design systems: - `.design/style-consolidation/style-1/design-tokens.json` -- `.design/style-consolidation/style-2/design-tokens.json` -- `.design/style-consolidation/style-3/design-tokens.json` +- `.design/style-consolidation/style-{N}/design-tokens.json` -**Auto-Continue**: On completion, proceeds to Phase 3 +**Auto-Continue**: On completion → Phase 3 --- -### Phase 3: Matrix UI Generation (Auto-Triggered) -**Action**: Generates `style_variants × layout_variants × pages` prototypes using matrix mode - -**Command Construction**: +### Phase 3: Matrix UI Generation (Mode-Aware) +**Command**: ```bash run_base_flag = "--base-path \"{base_path}/.design\"" -# Ensure inferred_page_list is serialized correctly as comma-separated string -# Convert list to string: ['dashboard', 'settings'] → "dashboard,settings" -pages_string = ",".join(inferred_page_list) +IF exploration_mode == "page": + # Page Mode: Generate full pages + pages_string = ",".join(inferred_page_list) + VERIFY: pages_string matches r"^[a-z0-9_-]+(,[a-z0-9_-]+)*$" -# Validate the serialized string format -VERIFY: pages_string matches r"^[a-z0-9_-]+(,[a-z0-9_-]+)*$" + pages_flag = "--pages \"{pages_string}\"" + command = "/workflow:ui-design:generate {run_base_flag} {pages_flag} --style-variants {style_variants} --layout-variants {layout_variants}" -pages_flag = "--pages \"{pages_string}\"" + total_prototypes = style_variants * layout_variants * len(inferred_page_list) + REPORT: "🚀 Phase 3: Matrix UI Generation (Page Mode)" + REPORT: " Pages: {pages_string}" + REPORT: " Matrix: {style_variants}×{layout_variants}" + REPORT: " Total: {total_prototypes} full-page prototypes" -# Matrix mode is default in generate.md, no mode flag needed -command = "/workflow:ui-design:generate {run_base_flag} {pages_flag} --style-variants {style_variants} --layout-variants {layout_variants}" +ELSE IF exploration_mode == "component": + # Component Mode: Generate isolated components + components_string = ",".join(inferred_component_list) + VERIFY: components_string matches r"^[a-z0-9_-]+(,[a-z0-9_-]+)*$" -# Log command for debugging -REPORT: "🚀 Executing Phase 3: Matrix UI Generation" -REPORT: " Pages: {pages_string}" -REPORT: " Style variants: {style_variants}" -REPORT: " Layout variants: {layout_variants}" -REPORT: " Total prototypes: {style_variants * layout_variants * len(inferred_page_list)}" + components_flag = "--components \"{components_string}\"" + command = "/workflow:ui-design:generate {run_base_flag} {components_flag} --style-variants {style_variants} --layout-variants {layout_variants}" -SlashCommand(command=command) + total_prototypes = style_variants * layout_variants * len(inferred_component_list) + REPORT: "🚀 Phase 3: Matrix UI Generation (Component Mode)" + REPORT: " Components: {components_string}" + REPORT: " Matrix: {style_variants}×{layout_variants}" + REPORT: " Total: {total_prototypes} component prototypes" + REPORT: " Context: Components displayed in minimal page wrapper" + +SlashCommand(command) ``` -**Result**: Generates `style_variants × layout_variants × pages` prototypes: -- File naming: `{page}-style-{s}-layout-{l}.html` -- Total prototypes: `style_variants * layout_variants * len(inferred_page_list)` -- Matrix visualization: `compare.html` with interactive 3×3 grid +**Result**: +- **Page Mode**: `{page}-style-{s}-layout-{l}.html` +- **Component Mode**: `{component}-style-{s}-layout-{l}.html` +- Total: `style_variants × layout_variants × (pages|components)` +- Matrix view: `compare.html` with interactive grid +- Component isolation: Minimal wrapper for focus on component design -**Auto-Continue**: On completion, proceeds to Phase 4 +**Auto-Continue**: On completion → Phase 4 --- -### Phase 4: Design System Integration (Auto-Triggered) -**Action**: Integrates all generated prototypes and the design system into the brainstorming artifacts - -**Command Construction**: +### Phase 4: Design System Integration +**Command**: ```bash session_flag = --session present ? "--session {session_id}" : "" -# --selected-prototypes is omitted to default to ALL generated prototypes + +# Omit --selected-prototypes to use ALL generated prototypes command = "/workflow:ui-design:update {session_flag}" +SlashCommand(command) ``` -**Command**: `SlashCommand(command=command)` -**Auto-Continue**: If `--batch-plan` is present, proceeds to Phase 5. Otherwise, the workflow completes +**Auto-Continue**: If `--batch-plan` present → Phase 5, else complete --- -### Phase 5: Batch Task Generation (Optional, Auto-Triggered) -**Condition**: Only executes if `--batch-plan` flag is present +### Phase 5: Batch Task Generation (Optional) +**Condition**: Only if `--batch-plan` flag present **Execution**: ```bash -FOR each page IN inferred_page_list: - SlashCommand(command="/workflow:plan --agent \"Implement {page} page based on design system\"") +FOR page IN inferred_page_list: + SlashCommand("/workflow:plan --agent \"Implement {page} page based on design system\"") ``` -**Completion**: The workflow is now complete +**Completion**: Workflow complete -## TodoWrite Pattern (Autonomous) +## TodoWrite Pattern ```javascript -// Initialize (before Phase 1) +// Initialize TodoWrite({todos: [ {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing style extraction"}, {"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing style consolidation"}, @@ -423,96 +515,107 @@ TodoWrite({todos: [ {"content": "Execute design system integration", "status": "pending", "activeForm": "Executing design system integration"} ]}) -// After Phase 1 completes, before Phase 2 starts -TodoWrite({todos: [ - {"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"}, - {"content": "Execute style consolidation", "status": "in_progress", "activeForm": "Executing style consolidation"}, - // ... rest are pending -]}) - -// After Phase 2 completes, before Phase 3 starts -TodoWrite({todos: [ - {"content": "Execute style extraction", "status": "completed"}, - {"content": "Execute style consolidation", "status": "completed", "activeForm": "Executing style consolidation"}, - {"content": "Execute UI prototype generation", "status": "in_progress", "activeForm": "Executing UI generation"}, - // ... rest are pending -]}) - -// This pattern continues until all phases are complete +// After each phase: Mark current completed, next in_progress, rest pending +// Phase 1 done → Phase 2 in_progress +// Phase 2 done → Phase 3 in_progress +// ... continues until all completed ``` ## Error Handling -- **Phase Execution Failures**: The workflow will halt, keeping the failed phase `in_progress`. It will report the error and provide recovery instructions, suggesting a manual command execution with corrected parameters -- **Default Behavior**: In case of ambiguity (e.g., which variants to select), the system defaults to selecting ALL available items to ensure the workflow can proceed autonomously +- **Phase Failures**: Workflow halts, keeps failed phase `in_progress`, reports error with recovery instructions +- **Ambiguity**: Defaults to ALL available items (variants/prototypes) to ensure autonomous continuation -## Key Improvements Over Previous Version +## Key Features & Workflow Position -1. **Zero External Dependencies**: Pure Claude + agents, no CLI tools -2. **Streamlined Commands**: Removed `--tool` parameter and all CLI tool flags -3. **Consistent Execution**: All sub-commands use unified patterns -4. **Reproducible**: Deterministic flow with clear phase dependencies -5. **Simpler**: Fewer moving parts, easier to understand and debug +**Core Improvements**: +- **Zero External Dependencies**: Pure Claude + agents, no CLI tools +- **Streamlined Commands**: Unified patterns, no tool-specific flags +- **Reproducible Flow**: Deterministic phase dependencies +- **Intelligent Parsing**: Natural language → variant counts, pages +- **Run Isolation**: Each execution in timestamped run directory -## Workflow Position - -The workflow acts as the bridge between brainstorming (`synthesis-specification.md`) and planning (`/workflow:plan`), providing this connection in a fully automated fashion with options for deep creative exploration through parallel agents. +**Workflow Bridge**: Connects brainstorming (`synthesis-specification.md`) → design phase → planning (`/workflow:plan`) in fully automated fashion with matrix-based design exploration. ## Example Execution Flows -### Example 1: Default 3×3 Matrix (Prompt Inference) +### Example 1: Default 3×3 Matrix (Page Mode - Prompt Inference) ```bash -/workflow:ui-design:auto --prompt "Modern minimalist blog with home, article, and author pages" +/workflow:ui-design:explore-auto --prompt "Modern minimalist blog with home, article, and author pages" +# Mode: Page # Inferred: 3 style variants, 3 layout variants (default) -# Executes: -# 1. /workflow:ui-design:extract --base-path ".../run-xxx/.design" --prompt "..." --variants 3 -# 2. /workflow:ui-design:consolidate --base-path ".../run-xxx/.design" --variants 3 --keep-separate -# 3. /workflow:ui-design:generate --base-path ".../run-xxx/.design" --pages "home,article,author" --style-variants 3 --layout-variants 3 -# 4. /workflow:ui-design:update -# Total: 27 prototypes (3 styles × 3 layouts × 3 pages) +# Pages: home, article, author +# Total: 27 full-page prototypes (3×3×3) ``` -### Example 2: Custom 2×2 Matrix with Explicit Parameters +### Example 2: Custom 2×2 Matrix with Session (Page Mode) ```bash -/workflow:ui-design:auto --session WFS-ecommerce --images "refs/*.png" --prompt "E-commerce" --style-variants 2 --layout-variants 2 +/workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2 -# Executes: -# 1. /workflow:ui-design:extract --base-path ".workflow/WFS-ecommerce/runs/run-xxx/.design" --images "refs/*.png" --variants 2 -# 2. /workflow:ui-design:consolidate --base-path "..." --variants 2 --keep-separate -# 3. /workflow:ui-design:generate --base-path "..." --pages "{inferred}" --style-variants 2 --layout-variants 2 -# 4. /workflow:ui-design:update --session WFS-ecommerce -# Total: 2×2×N prototypes +# Mode: Page +# Executes with session integration +# Total: 2×2×N prototypes (N from inference) ``` -### Example 3: Intelligent Parsing with Batch Planning +### Example 3: Component Mode - Navbar Design Comparison ```bash -/workflow:ui-design:auto --session WFS-saas --prompt "Create 4 styles with 2 layouts for SaaS dashboard and settings" --batch-plan +/workflow:ui-design:explore-auto --components "navbar,hero" --prompt "Compare 3 navigation bar designs for SaaS product" --style-variants 3 --layout-variants 2 -# Parsed: --style-variants 4, --layout-variants 2 -# Executes: -# 1. /workflow:ui-design:extract --variants 4 -# 2. /workflow:ui-design:consolidate --variants 4 --keep-separate -# 3. /workflow:ui-design:generate --pages "dashboard,settings" --style-variants 4 --layout-variants 2 -# (generates 16 prototypes: 4 styles × 2 layouts × 2 pages) -# 4. /workflow:ui-design:update --session WFS-saas -# 5. /workflow:plan --agent "Implement dashboard page..." -# /workflow:plan --agent "Implement settings page..." +# Mode: Component +# Components: navbar, hero +# Matrix: 3 styles × 2 layouts +# Total: 12 component prototypes (3×2×2) +# Output: navbar-style-1-layout-1.html, navbar-style-1-layout-2.html, ... +``` + +### Example 4: Component Mode - Card & Form Exploration +```bash +/workflow:ui-design:explore-auto --components "card,form,button" --images "refs/*.png" --style-variants 2 --layout-variants 3 + +# Mode: Component +# Components: card, form, button +# Matrix: 2 styles × 3 layouts +# Total: 18 component prototypes (2×3×3) +# Context: Each component in minimal wrapper for isolated comparison +``` + +### Example 5: Intelligent Parsing + Batch Planning (Page Mode) +```bash +/workflow:ui-design:explore-auto --session WFS-saas --prompt "Create 4 styles with 2 layouts for SaaS dashboard and settings" --batch-plan + +# Mode: Page +# Parsed: 4 styles, 2 layouts +# Pages: dashboard, settings +# Total: 16 full-page prototypes (4×2×2) +# Auto-generates implementation tasks for each page +``` + +### Example 6: Component Mode - Prompt-Inferred Components +```bash +/workflow:ui-design:explore-auto --prompt "Design exploration for pricing table and testimonial card components" --style-variants 3 --layout-variants 2 + +# Mode: Component (auto-detected from prompt) +# Inferred components: pricing-table, testimonial-card +# Matrix: 3 styles × 2 layouts +# Total: 12 component prototypes (3×2×2) ``` ## Final Completion Message +**Page Mode**: ``` -✅ UI Design Auto Workflow Complete! +✅ UI Design Explore-Auto Workflow Complete! (Page Mode) Run ID: {run_id} Session: {session_id or "standalone"} +Mode: Full-Page Exploration Matrix: {style_variants}×{layout_variants} ({total_prototypes} total prototypes) Input: {images and/or prompt summary} Phase 1 - Style Extraction: {style_variants} style variants Phase 2 - Style Consolidation: {style_variants} independent design systems -Phase 3 - Matrix Generation: {style_variants}×{layout_variants}×{pages_count} = {total_prototypes} prototypes +Phase 3 - Matrix Generation: {style_variants}×{layout_variants}×{pages_count} = {total_prototypes} page prototypes Phase 4 - Design Update: Brainstorming artifacts updated {IF batch-plan: Phase 5 - Task Generation: {task_count} implementation tasks created} @@ -522,18 +625,55 @@ Phase 4 - Design Update: Brainstorming artifacts updated └── .run-metadata.json (run configuration) 🌐 Interactive Preview: {base_path}/.design/prototypes/compare.html - - 3×3 matrix view with synchronized scrolling + - {style_variants}×{layout_variants} matrix view with synchronized scrolling - Zoom controls and fullscreen mode - Selection export for implementation +📄 Pages Explored: {', '.join(inferred_page_list)} + {IF batch-plan: 📋 Implementation Tasks: .workflow/WFS-{session}/.task/ Next: /workflow:execute to begin implementation } {ELSE: Next Steps: -1. Open compare.html to preview all variants -2. Select preferred style×layout combinations +1. Open compare.html to preview all page variants +2. Select preferred style×layout combinations per page 3. Run /workflow:plan to create implementation tasks } ``` + +**Component Mode**: +``` +✅ UI Design Explore-Auto Workflow Complete! (Component Mode) + +Run ID: {run_id} +Session: {session_id or "standalone"} +Mode: Component Exploration +Matrix: {style_variants}×{layout_variants} ({total_prototypes} total component prototypes) +Input: {images and/or prompt summary} + +Phase 1 - Style Extraction: {style_variants} style variants +Phase 2 - Style Consolidation: {style_variants} independent design systems +Phase 3 - Matrix Generation: {style_variants}×{layout_variants}×{component_count} = {total_prototypes} component prototypes +Phase 4 - Design Update: Brainstorming artifacts updated + +📂 Run Output: {base_path}/ + ├── .design/style-consolidation/ ({style_variants} design systems) + ├── .design/prototypes/ ({total_prototypes} component HTML/CSS files) + └── .run-metadata.json (run configuration) + +🌐 Interactive Preview: {base_path}/.design/prototypes/compare.html + - {style_variants}×{layout_variants} component matrix view + - Isolated component rendering (minimal wrapper) + - Side-by-side comparison for design decisions + - Selection export for implementation + +🧩 Components Explored: {', '.join(inferred_component_list)} + +Next Steps: +1. Open compare.html to preview all component variants +2. Select preferred style×layout combinations per component +3. Extract selected components for integration into pages +4. Run /workflow:plan with component integration context +``` diff --git a/.claude/commands/workflow/ui-design/extract.md b/.claude/commands/workflow/ui-design/extract.md index 92a2e104..3caf5593 100644 --- a/.claude/commands/workflow/ui-design/extract.md +++ b/.claude/commands/workflow/ui-design/extract.md @@ -19,12 +19,13 @@ Extract design style elements from reference images or text prompts using Claude - **Claude-Native**: 100% Claude-driven analysis, no external tools - **Single Output**: Only `style-cards.json` with embedded token proposals - **Sequential Execution**: Generate multiple style variants in one pass -- **Flexible Input**: Images, text prompts, or both +- **Flexible Input**: Images, text prompts, or both (hybrid mode) - **Reproducible**: Deterministic output structure ## Execution Protocol ### Phase 0: Parameter Detection & Validation + ```bash # Detect input source IF --images AND --prompt: @@ -52,6 +53,7 @@ VALIDATE: 1 <= variants_count <= 5 ``` ### Phase 1: Input Loading & Validation + ```bash # Expand and validate inputs IF input_mode IN ["image", "hybrid"]: @@ -69,6 +71,7 @@ CREATE: {base_path}/.design/style-extraction/ ``` ### Phase 2: Unified Style Analysis (Claude) + This is a single-pass analysis that replaces all external tool calls. **Analysis Prompt Template**: @@ -107,6 +110,114 @@ OUTPUT FORMAT: JSON matching this exact structure: "name": "Concise Style Name (e.g., Modern Minimalist)", "description": "2-3 sentence description of this style's visual language and user experience", "design_philosophy": "Core design principles for this variant", + "preview": { + "primary": "oklch(...)", + "background": "oklch(...)", + "font_heading": "Font name, fallbacks", + "border_radius": "value" + }, + "proposed_tokens": { + "colors": { + "brand": { "primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)" }, + "surface": { "background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)" }, + "semantic": { "success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)" }, + "text": { "primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)" }, + "border": { "default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)" } + }, + "typography": { + "font_family": { "heading": "...", "body": "...", "mono": "..." }, + "font_size": { "xs": "...", "sm": "...", "base": "...", "lg": "...", "xl": "...", "2xl": "...", "3xl": "...", "4xl": "..." }, + "font_weight": { "normal": "400", "medium": "500", "semibold": "600", "bold": "700" }, + "line_height": { "tight": "1.25", "normal": "1.5", "relaxed": "1.75" }, + "letter_spacing": { "tight": "-0.025em", "normal": "0", "wide": "0.025em" } + }, + "spacing": { "0": "0", "1": "0.25rem", "2": "0.5rem", ..., "24": "6rem" }, + "border_radius": { "none": "0", "sm": "0.25rem", ..., "full": "9999px" }, + "shadows": { "sm": "...", "md": "...", "lg": "...", "xl": "..." }, + "breakpoints": { "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" } + } + }, + // Repeat for variants_count total + ] +} + +RULES: +- Each variant must be distinct in visual character +- All colors MUST use OKLCH format: oklch(L C H / A) +- Token structures must be complete and production-ready +- Use semantic naming throughout (e.g., "brand-primary" not "color-1") +- Ensure accessibility (WCAG AA contrast ratios: 4.5:1 text, 3:1 UI) +- Include complete token categories for each variant +``` + +### Phase 3: Parse & Write Output + +```bash +# Parse Claude's JSON response +style_cards_data = parse_json(claude_response) + +# Write single output file +Write({ + file_path: "{base_path}/.design/style-extraction/style-cards.json", + content: style_cards_data +}) +``` + +### Phase 4: Completion + +```javascript +TodoWrite({ + todos: [ + {content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"}, + {content: "Analyze design references with Claude", status: "completed", activeForm: "Analyzing design"}, + {content: `Generate ${variants_count} style cards with token proposals`, status: "completed", activeForm: "Generating style cards"} + ] +}); +``` + +**Completion Message**: +``` +✅ Style extraction complete for session: {session_id} + +Input mode: {input_mode} +{IF image mode: Images analyzed: {count}} +{IF prompt mode: Prompt: "{truncated_prompt}"} + +Generated {variants_count} style variant(s): +{FOR each card: - {card.name} ({card.id})} + +📂 Output: {base_path}/.design/style-extraction/style-cards.json + +Next: /workflow:ui-design:consolidate --session {session_id} --variants {variants_count} + +Note: When called from /workflow:ui-design:auto, consolidation is triggered automatically. +``` + +## Output Structure + +``` +.workflow/WFS-{session}/.design/style-extraction/ +└── style-cards.json # Single comprehensive output +``` + +### style-cards.json Format + +Complete structure with example values: + +```json +{ + "extraction_metadata": { + "session_id": "WFS-xxx or design-session-xxx", + "input_mode": "image|text|hybrid", + "timestamp": "2025-01-15T10:30:00Z", + "variants_count": 3 + }, + "style_cards": [ + { + "id": "variant-1", + "name": "Modern Minimalist", + "description": "Clean, high-contrast design with bold typography and ample whitespace. Focuses on content clarity with minimal visual noise.", + "design_philosophy": "Less is more - prioritize content clarity and visual breathing room over decorative elements", "preview": { "primary": "oklch(0.45 0.20 270 / 1)", "background": "oklch(0.98 0.01 270 / 1)", @@ -213,115 +324,285 @@ OUTPUT FORMAT: JSON matching this exact structure: "2xl": "1536px" } } - } - ] -} - -RULES: -- Each variant must be distinct in visual character -- All colors MUST use OKLCH format: oklch(L C H / A) -- Token structures must be complete and production-ready -- Use semantic naming throughout -- Ensure accessibility (contrast ratios, readable font sizes) -``` - -### Phase 3: Generate & Write Output -```bash -# Parse Claude's JSON response -style_cards_data = parse_json(claude_response) - -# Write single output file -Write({ - file_path: "{base_path}/.design/style-extraction/style-cards.json", - content: style_cards_data -}) -``` - -### Phase 4: TodoWrite & Completion -```javascript -TodoWrite({ - todos: [ - {content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"}, - {content: "Analyze design references with Claude", status: "completed", activeForm: "Analyzing design"}, - {content: "Generate {variants_count} style cards with token proposals", status: "completed", activeForm: "Generating style cards"} - ] -}); -``` - -**Completion Message**: -``` -✅ Style extraction complete for session: {session_id} - -Input mode: {input_mode} -{IF image mode: Images analyzed: {count}} -{IF prompt mode: Prompt: "{truncated_prompt}"} - -Generated {variants_count} style variant(s): -{FOR each card: - {card.name} ({card.id})} - -📂 Output: {base_path}/.design/style-extraction/style-cards.json - -Next: /workflow:ui-design:consolidate --session {session_id} --variants "{all_variant_ids}" - -Note: When called from /workflow:ui-design:auto, consolidation is triggered automatically. -``` - -## Output Structure - -``` -.workflow/WFS-{session}/.design/style-extraction/ -└── style-cards.json # Single comprehensive output -``` - -### style-cards.json Format (Enhanced) -```json -{ - "extraction_metadata": { - "session_id": "WFS-xxx or design-session-xxx", - "input_mode": "image|text|hybrid", - "timestamp": "2025-01-15T10:30:00Z", - "variants_count": 3 - }, - "style_cards": [ + }, { - "id": "variant-1", - "name": "Modern Minimalist", - "description": "Clean, high-contrast design with bold typography and ample whitespace", - "design_philosophy": "Less is more - focus on content clarity and visual breathing room", + "id": "variant-2", + "name": "Bold Vibrant", + "description": "High-energy design with saturated colors and strong visual hierarchy. Creates excitement and demands attention.", + "design_philosophy": "Make a statement - use color and contrast to create memorable, energetic experiences", "preview": { - "primary": "oklch(0.45 0.20 270 / 1)", - "background": "oklch(0.98 0.01 270 / 1)", - "font_heading": "Inter, system-ui, sans-serif", - "border_radius": "0.5rem" + "primary": "oklch(0.50 0.25 330 / 1)", + "background": "oklch(0.15 0.02 270 / 1)", + "font_heading": "Poppins, system-ui, sans-serif", + "border_radius": "0.75rem" }, "proposed_tokens": { - "colors": { /* complete color system */ }, - "typography": { /* complete typography system */ }, - "spacing": { /* complete spacing scale */ }, - "border_radius": { /* border radius scale */ }, - "shadows": { /* shadow system */ }, - "breakpoints": { /* responsive breakpoints */ } + "colors": { + "brand": { + "primary": "oklch(0.50 0.25 330 / 1)", + "secondary": "oklch(0.65 0.22 60 / 1)", + "accent": "oklch(0.70 0.20 180 / 1)" + }, + "surface": { + "background": "oklch(0.15 0.02 270 / 1)", + "elevated": "oklch(0.20 0.02 270 / 1)", + "overlay": "oklch(0.25 0.02 270 / 1)" + }, + "semantic": { + "success": "oklch(0.65 0.18 140 / 1)", + "warning": "oklch(0.70 0.15 80 / 1)", + "error": "oklch(0.60 0.25 25 / 1)", + "info": "oklch(0.60 0.20 250 / 1)" + }, + "text": { + "primary": "oklch(0.95 0.01 270 / 1)", + "secondary": "oklch(0.75 0.01 270 / 1)", + "tertiary": "oklch(0.60 0.01 270 / 1)", + "inverse": "oklch(0.20 0.01 270 / 1)" + }, + "border": { + "default": "oklch(0.35 0.02 270 / 1)", + "strong": "oklch(0.50 0.02 270 / 1)", + "subtle": "oklch(0.25 0.02 270 / 1)" + } + }, + "typography": { + "font_family": { + "heading": "Poppins, system-ui, sans-serif", + "body": "Open Sans, system-ui, sans-serif", + "mono": "Fira Code, Consolas, monospace" + }, + "font_size": { + "xs": "0.75rem", + "sm": "0.875rem", + "base": "1rem", + "lg": "1.125rem", + "xl": "1.25rem", + "2xl": "1.5rem", + "3xl": "1.875rem", + "4xl": "2.25rem" + }, + "font_weight": { + "normal": "400", + "medium": "500", + "semibold": "600", + "bold": "700" + }, + "line_height": { + "tight": "1.25", + "normal": "1.5", + "relaxed": "1.75" + }, + "letter_spacing": { + "tight": "-0.025em", + "normal": "0", + "wide": "0.025em" + } + }, + "spacing": { + "0": "0", + "1": "0.25rem", + "2": "0.5rem", + "3": "0.75rem", + "4": "1rem", + "5": "1.25rem", + "6": "1.5rem", + "8": "2rem", + "10": "2.5rem", + "12": "3rem", + "16": "4rem", + "20": "5rem", + "24": "6rem" + }, + "border_radius": { + "none": "0", + "sm": "0.25rem", + "md": "0.5rem", + "lg": "0.75rem", + "xl": "1rem", + "full": "9999px" + }, + "shadows": { + "sm": "0 1px 2px oklch(0.00 0.00 0 / 0.10)", + "md": "0 4px 6px oklch(0.00 0.00 0 / 0.15)", + "lg": "0 10px 15px oklch(0.00 0.00 0 / 0.20)", + "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.25)" + }, + "breakpoints": { + "sm": "640px", + "md": "768px", + "lg": "1024px", + "xl": "1280px", + "2xl": "1536px" + } + } + }, + { + "id": "variant-3", + "name": "Elegant Serif", + "description": "Sophisticated design with serif typography and refined color palette. Conveys professionalism and timeless quality.", + "design_philosophy": "Timeless elegance - combine classical typography with modern layout principles", + "preview": { + "primary": "oklch(0.35 0.08 280 / 1)", + "background": "oklch(0.96 0.01 60 / 1)", + "font_heading": "Playfair Display, Georgia, serif", + "border_radius": "0.25rem" + }, + "proposed_tokens": { + "colors": { + "brand": { + "primary": "oklch(0.35 0.08 280 / 1)", + "secondary": "oklch(0.50 0.10 320 / 1)", + "accent": "oklch(0.65 0.12 40 / 1)" + }, + "surface": { + "background": "oklch(0.96 0.01 60 / 1)", + "elevated": "oklch(1.00 0.00 0 / 1)", + "overlay": "oklch(0.94 0.01 60 / 1)" + }, + "semantic": { + "success": "oklch(0.55 0.12 145 / 1)", + "warning": "oklch(0.70 0.10 85 / 1)", + "error": "oklch(0.50 0.18 30 / 1)", + "info": "oklch(0.50 0.15 255 / 1)" + }, + "text": { + "primary": "oklch(0.25 0.01 280 / 1)", + "secondary": "oklch(0.50 0.01 280 / 1)", + "tertiary": "oklch(0.65 0.01 280 / 1)", + "inverse": "oklch(0.95 0.01 60 / 1)" + }, + "border": { + "default": "oklch(0.82 0.01 60 / 1)", + "strong": "oklch(0.65 0.01 60 / 1)", + "subtle": "oklch(0.90 0.01 60 / 1)" + } + }, + "typography": { + "font_family": { + "heading": "Playfair Display, Georgia, serif", + "body": "Source Sans Pro, system-ui, sans-serif", + "mono": "Source Code Pro, Consolas, monospace" + }, + "font_size": { + "xs": "0.75rem", + "sm": "0.875rem", + "base": "1rem", + "lg": "1.125rem", + "xl": "1.25rem", + "2xl": "1.5rem", + "3xl": "1.875rem", + "4xl": "2.25rem" + }, + "font_weight": { + "normal": "400", + "medium": "500", + "semibold": "600", + "bold": "700" + }, + "line_height": { + "tight": "1.25", + "normal": "1.5", + "relaxed": "1.75" + }, + "letter_spacing": { + "tight": "-0.025em", + "normal": "0", + "wide": "0.025em" + } + }, + "spacing": { + "0": "0", + "1": "0.25rem", + "2": "0.5rem", + "3": "0.75rem", + "4": "1rem", + "5": "1.25rem", + "6": "1.5rem", + "8": "2rem", + "10": "2.5rem", + "12": "3rem", + "16": "4rem", + "20": "5rem", + "24": "6rem" + }, + "border_radius": { + "none": "0", + "sm": "0.25rem", + "md": "0.5rem", + "lg": "0.75rem", + "xl": "1rem", + "full": "9999px" + }, + "shadows": { + "sm": "0 1px 2px oklch(0.00 0.00 0 / 0.03)", + "md": "0 4px 6px oklch(0.00 0.00 0 / 0.05)", + "lg": "0 10px 15px oklch(0.00 0.00 0 / 0.08)", + "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.12)" + }, + "breakpoints": { + "sm": "640px", + "md": "768px", + "lg": "1024px", + "xl": "1280px", + "2xl": "1536px" + } } } ] } ``` +**Key Points**: +- Each variant has complete, independent token proposals +- All colors use OKLCH format for perceptual uniformity +- Token structures are production-ready (no placeholders) +- Variants have distinct visual identities and philosophies + ## Error Handling -- **No images found**: Report glob pattern and suggest corrections + +- **No images found**: Report glob pattern and suggest corrections (e.g., "Pattern '*.png' matched 0 files in current directory") - **Invalid prompt**: Require non-empty string for text mode -- **Claude JSON parsing error**: Retry with stricter format instructions -- **Invalid session**: Create standalone session automatically +- **Claude JSON parsing error**: Retry with stricter format instructions and explicit structure requirements +- **Invalid session**: Create standalone session automatically in `.workflow/.scratchpad/` +- **Invalid variant count**: Clamp to 1-5 range and warn user -## Key Improvements Over Previous Version +## Key Features -1. **Zero External Dependencies**: No `gemini-wrapper`, no `codex` - pure Claude -2. **Single Output File**: Eliminates `semantic_style_analysis.json`, `design-tokens.json`, `tailwind-tokens.js` clutter -3. **Complete Token Proposals**: Each style card contains a full design system proposal -4. **Reproducible**: Same inputs = same output structure (content may vary based on Claude model) -5. **Streamlined Flow**: `Input → Analysis → style-cards.json` (3 steps vs 7+ previously) +1. **Zero External Dependencies** + - No `gemini-wrapper`, no `codex` - pure Claude synthesis + - Single-pass comprehensive analysis + +2. **Streamlined Output** + - Single file (`style-cards.json`) vs. multiple scattered files + - Eliminates `semantic_style_analysis.json`, `design-tokens.json`, `tailwind-tokens.js` clutter + - Each variant contains complete token proposals embedded + +3. **Flexible Input Modes** + - Image-only: Analyze visual references + - Text-only: Generate from descriptions + - Hybrid: Text guides image analysis + +4. **Reproducible Structure** + - Same inputs = same output structure + - Deterministic JSON schema + - Content may vary based on Claude model version + +5. **Production-Ready Tokens** + - Complete design system proposals per variant + - OKLCH color format for accessibility + - Semantic naming conventions + - WCAG AA accessibility considerations + +6. **Workflow Integration** + - Integrated mode: Works within existing workflow sessions + - Standalone mode: Auto-creates session in scratchpad + - Context-aware: Can reference synthesis-specification.md or ui-designer/analysis.md ## Integration Points -- **Input**: Reference images (PNG, JPG, WebP) or text prompts + +- **Input**: Reference images (PNG, JPG, WebP) via glob patterns, or text prompts - **Output**: `style-cards.json` for `/workflow:ui-design:consolidate` -- **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md` can guide prompts +- **Context**: Optional brainstorming artifacts (`synthesis-specification.md`, `ui-designer/analysis.md`) +- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow +- **Next Step**: `/workflow:ui-design:consolidate --session {session_id} --variants {count}` (or `--keep-separate` for matrix mode) diff --git a/.claude/commands/workflow/ui-design/generate.md b/.claude/commands/workflow/ui-design/generate.md index 709595df..eb7cbade 100644 --- a/.claude/commands/workflow/ui-design/generate.md +++ b/.claude/commands/workflow/ui-design/generate.md @@ -20,117 +20,89 @@ Generate production-ready UI prototypes (HTML/CSS) in `style × layout` matrix m - **Agent-Driven**: Uses `Task(conceptual-planning-agent)` for parallel generation - **Token-Driven**: All styles reference per-style design-tokens.json; no hardcoded values - **Production-Ready**: Semantic HTML5, ARIA attributes, responsive design +- **Template-Based**: Decouples HTML structure from CSS styling for optimal performance ## Execution Protocol -### Phase 1: Path Resolution & Context Loading (Enhanced) +### Phase 1: Path Resolution & Context Loading + ```bash -# Determine base path +# 1. Determine base path IF --base-path provided: - base_path = {provided_base_path} # e.g., ".workflow/WFS-xxx/runs/run-xxx/.design" + base_path = {provided_base_path} ELSE IF --session provided: - session_id = {provided_session} - base_path = ".workflow/WFS-{session_id}/latest/.design" # Use latest run + base_path = ".workflow/WFS-{session}/latest/.design" ELSE: - # Standalone mode: search for most recent design-session in scratchpad base_path = find_latest_design_session(".workflow/.scratchpad/") -# Determine style and layout variant counts +# 2. Determine variant counts style_variants = --style-variants OR 3 # Default to 3 layout_variants = --layout-variants OR 3 # Default to 3 VALIDATE: 1 <= style_variants <= 5 VALIDATE: 1 <= layout_variants <= 5 -# Enhanced page list parsing +# 3. Enhanced page list parsing page_list = [] -page_source = "none" -# Priority 1: Explicit --pages parameter (with robust parsing) +# Priority 1: Explicit --pages parameter IF --pages provided: - # Enhanced parsing: handle spaces, multiple delimiters raw_pages = {--pages value} - - # Split by comma, semicolon, or Chinese comma, then clean + # Split by comma, semicolon, or Chinese comma page_list = split_and_clean(raw_pages, delimiters=[",", ";", "、"]) - - # Clean each page name: strip whitespace, convert to lowercase + # Clean: strip whitespace, lowercase, replace spaces with hyphens page_list = [p.strip().lower().replace(" ", "-") for p in page_list if p.strip()] - - page_source = "explicit_parameter" REPORT: "📋 Using provided pages: {', '.join(page_list)}" # Priority 2: Extract from synthesis-specification.md ELSE IF --session: - # Read synthesis-specification.md to extract page requirements synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) page_list = extract_pages_from_synthesis(synthesis_spec) - page_source = "synthesis_specification" REPORT: "📋 Extracted pages from synthesis: {', '.join(page_list)}" -# Priority 3: Detect from existing prototypes +# Priority 3: Detect from existing prototypes or default ELSE: - # Infer from existing prototypes or default - page_list = detect_from_prototypes({base_path}/prototypes/) - IF page_list: - page_source = "existing_prototypes" - REPORT: "📋 Detected pages from existing prototypes: {', '.join(page_list)}" - ELSE: - page_list = ["home"] - page_source = "default" - REPORT: "⚠️ No pages found, using default: 'home'" + page_list = detect_from_prototypes({base_path}/prototypes/) OR ["home"] + REPORT: "📋 Detected/default pages: {', '.join(page_list)}" -# Validation: ensure page names are valid -validated_pages = [] -invalid_pages = [] -FOR page IN page_list: - # Validate format: must start with letter/number, can contain alphanumeric, hyphens, underscores - IF regex_match(page, r"^[a-z0-9][a-z0-9_-]*$"): - validated_pages.append(page) - ELSE: - invalid_pages.append(page) +# 4. Validate page names +validated_pages = [p for p in page_list if regex_match(p, r"^[a-z0-9][a-z0-9_-]*$")] +invalid_pages = [p for p in page_list if p not in validated_pages] IF invalid_pages: REPORT: "⚠️ Skipped invalid page names: {', '.join(invalid_pages)}" - REPORT: " Valid format: lowercase, alphanumeric, hyphens, underscores" VALIDATE: validated_pages not empty, "No valid pages found" - -# Use validated list page_list = validated_pages -REPORT: "✅ Final page list ({len(page_list)}): {', '.join(page_list)}" -# Verify design systems exist for all styles +# 5. Verify design systems exist FOR style_id IN range(1, style_variants + 1): VERIFY: {base_path}/style-consolidation/style-{style_id}/design-tokens.json exists VERIFY: {base_path}/style-consolidation/style-{style_id}/style-guide.md exists -# Load requirements (if integrated mode) +# 6. Load requirements (if integrated mode) IF --session: synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) ``` -### Phase 2: Optimized Matrix UI Generation (Layered, Template-Based) +### Phase 2: Optimized Matrix UI Generation + +**Strategy**: Two-layer generation reduces complexity from `O(S×L×P)` to `O(L×P)`, achieving **`S` times faster** performance. -**Strategy**: Decouple HTML structure from CSS styling to eliminate redundancy. - **Layer 1**: Generate `L × P` layout templates (HTML structure + structural CSS) - **Layer 2**: Instantiate `S × L × P` final prototypes via fast file operations -**Performance**: Reduces core generation tasks from `O(S×L×P)` to `O(L×P)` — **`S` times faster** - ---- - -#### Phase 2a: Layout Template Generation (Parallel Agent Execution) +#### Phase 2a: Layout Template Generation Generate style-agnostic layout templates for each `{page} × {layout}` combination. Total agent tasks: `layout_variants × len(page_list)` ```bash -# Create template directory +# Create directories CREATE: {base_path}/prototypes/_templates/ CREATE: {base_path}/prototypes/ -# Launch layout_variants × page_list parallel tasks +# Launch parallel template generation tasks FOR layout_id IN range(1, layout_variants + 1): FOR page IN page_list: Task(conceptual-planning-agent): " @@ -165,7 +137,7 @@ FOR layout_id IN range(1, layout_variants + 1): - Mobile-first responsive design using token-based breakpoints ## Layout Diversity Strategy - You are responsible for Layout {layout_id}. Apply this strategy CONSISTENTLY to all styles in your batch. + Apply this strategy CONSISTENTLY to all styles: {IF layout_id == 1} **Layout 1: Classic Hierarchy** @@ -187,14 +159,11 @@ FOR layout_id IN range(1, layout_variants + 1): - Develop a unique and consistent layout structure different from the standard three {ENDIF} - Adapt this strategy to each page's purpose while maintaining layout consistency. - ## Token Usage Requirements (STRICT) - - For each style, load design tokens from its specific file: {base_path}/style-consolidation/style-{style_id}/design-tokens.json - All colors: var(--color-brand-primary), var(--color-surface-background), etc. - All spacing: var(--spacing-4), var(--spacing-6), etc. - All typography: var(--font-family-heading), var(--font-size-lg), etc. - - NO hardcoded values (e.g., #4F46E5, 16px) allowed + - NO hardcoded values allowed ## HTML Requirements - Semantic HTML5 elements (
,