- Revised TDD workflow to reduce phases from 7 to 6, integrating conflict resolution as an optional phase.
- Updated phase descriptions and execution logic to ensure automatic progression through phases based on TodoList status.
- Removed the concept-enhanced command and its associated documentation, streamlining the analysis process.
- Enhanced task generation to prioritize conflict resolution strategies and incorporate context package loading.
- Updated UI design documentation to reflect changes in role analysis and design system references.
- Improved error handling and validation checks across various commands to ensure robustness in execution.
- Updated references in various workflow commands to utilize role analysis documents instead of synthesis-specification.md.
- Modified CLI templates and command references to reflect the new architecture and document structure.
- Introduced conflict-resolution command to analyze and resolve conflicts between implementation plans and existing codebase.
- Deprecated synthesis role template and provided migration guidance for transitioning to the new role analysis approach.
Enhanced layout-extract and style-extract workflows with two-phase generation
process, allowing users to preview and select preferred options before full
generation.
Key changes:
- Split generation into two agent tasks:
* Task 1: Generate concept options with previews
* Task 2: Develop selected option into complete output
- Add Phase 1.5 interactive user selection:
* Present concept options with visual previews
* Capture user selection via AskUserQuestion tool
* Save selection to user-selection.json
- Layout workflow improvements:
* Generate layout concept options with ASCII wireframes
* User selects preferred structural approach
* Generate detailed templates only for selected concepts
- Style workflow improvements:
* Generate design direction options with color/typography previews
* User selects preferred design philosophy
* Generate complete design system only for selected direction
- Better user experience:
* Avoid generating unwanted variants
* Allow informed decisions before full generation
* Reduce wasted computation on unused variants
This change improves workflow efficiency and user control over design output.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes critical P0 issue where animation-tokens.json wasn't consumed by the
generate command, breaking the value chain. The animation extraction system
now properly flows through: animation-extract → tokens → generate → prototypes.
Changes:
- Added animation-extract command with hybrid CSS extraction + interactive
fallback strategy
- Updated generate.md to load and inject animation tokens into prototypes
- Added CSS animation support (custom properties, keyframes, interactions,
accessibility)
- Integrated animation extraction into explore-auto and imitate-auto workflows
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add --urls parameter support to style-extract and layout-extract
- Auto-trigger computed styles extraction when URLs provided (no manual flag)
- Auto-trigger DOM structure extraction for layout analysis
- Streamline imitate-auto workflow by removing redundant REPORT statements
- Maintain clear phase headers while reducing verbose output
- Enable graceful fallback to visual analysis if Chrome DevTools unavailable
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**Summary:**
Updated all 62 command files in `.claude/commands` directory to improve parameter documentation clarity by replacing `examples` field with descriptive `argument-hint` field.
**Changes:**
- Added/improved `argument-hint` for all commands based on usage patterns
- Removed `examples` field and all example items from YAML headers
- Maintained all other YAML fields (name, description, usage, allowed-tools)
- Deleted obsolete commands: workflow/issue/*, workflow/session/pause.md, workflow/session/switch.md
- Cleaned up temporary analysis files
**Rationale:**
The `argument-hint` field provides clearer, more concise parameter documentation than example lists, improving command discoverability and usability in the Claude Code interface.
**Files Modified:** 62 command files
**Lines Changed:** -1570 insertions, +192 deletions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Implemented the `/workflow:ui-design:explore-layers` command for depth-controlled UI capture.
- Defined depth levels from full-page screenshots to Shadow DOM exploration.
- Included setup, validation, and navigation phases with error handling.
- Captured screenshots at various depths and generated a comprehensive layer map.
- Added examples and usage instructions for ease of use.
- Introduced a new workflow named `imitate-auto-v3` that allows for batch screenshot capture and optional token refinement.
- Implemented a comprehensive 5-phase execution protocol to handle initialization, screenshot capture, style extraction, token processing, and UI generation.
- Added support for multiple target URLs through a `--url-map` parameter, enhancing flexibility in design replication.
- Included optional parameters for session management and token refinement, allowing users to customize their workflow experience.
- Enhanced error handling and reporting throughout the workflow to ensure clarity and ease of debugging.
- Deprecated the previous `imitate-auto.md` workflow in favor of this more robust version.
- Remove npx playwright to prevent auto-installation triggers
- Add explicit tool availability checks using 'which' command
- Check for playwright-cli, google-chrome, chrome, and chromium executables
- Only attempt screenshot capture if tools are already installed
- Provide clear tool availability reporting to users
- Gracefully fallback to manual mode when no tools available
- Support chromium browser on Linux systems
This ensures the workflow never triggers package installations and works
safely in environments without screenshot tools installed.
Add Phase 0.1/1.1 memory check to all UI design workflow commands to skip
execution when outputs already exist. This optimization dramatically reduces
redundant execution time from minutes to <1 second.
Changes:
- extract.md: Check for style-cards.json, skip Phase 0.5-3 if exists
- consolidate.md: Check for style-1/design-tokens.json, skip Phase 2-6
- generate.md: Check for compare.html, skip Phase 1.5-4
- update.md: Check for current design run in synthesis-spec, skip Phase 2-5
Benefits:
- >99% time reduction for repeated workflow execution
- Automatic cache detection without manual flags
- Clear reporting of skipped phases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Agent now directly generates HTML with final CSS references (no placeholders)
- Remove tokens.css dependency - agents create self-contained CSS from design-tokens.json
- Simplify ui-generate-preview-v2.sh (no placeholder replacement logic)
- Update Phase 2.5 validation to check actual href attributes
- Remove Phase 1.6 (token conversion step)
- Improve agent instructions with direct CSS value usage from design tokens
Benefits:
- Simpler workflow with fewer intermediate steps
- More flexible CSS generation - agents can adapt token values based on design_attributes
- Better style differentiation across variants
- Reduced dependencies and potential error points
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace exa-code with web-search for diverse layout inspiration
- Simplify from keyword pools to direct "common variations" search
- Add selection strategy for agents to pick different structural patterns
- Support unlimited layout variants with natural diversity
Impact: Prevents layout architecture convergence by leveraging web search
for real-world layout variations instead of code examples.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Implemented a new script to generate compare.html and index.html for UI prototypes.
- Auto-detects styles, layouts, and targets from HTML file patterns.
- Generates an interactive comparison matrix and a simple index of prototypes.
- Includes a detailed PREVIEW.md guide with usage instructions and file structure.
Clarified file writing patterns across UI design workflows to prevent confusion
between "generate content as output then save" vs "direct write to file" approaches.
Changes:
- extract.md: Merged Phase 2 & 3 to unify style synthesis and file write operations
* Updated phase title to emphasize direct file writing
* Added explicit note about internal processing without context output
* Consolidated parse-and-write step into single atomic operation
- imitate-auto.md: Added clarifying comments for orchestrator file transformation
* Documented that Phase 2 uses orchestrator-level read-process-write pattern
* Explained this as performance optimization to bypass consolidate phase
The entire UI design workflow now consistently follows clear file operation patterns
with no ambiguous intermediate output steps.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace mcp__exa__get_code_context_exa with mcp__exa__web_search_exa in consolidate.md
for trend research queries (colors, typography, layout, contrast, accessibility)
- Add Phase 0.75 URL Content Analysis in imitate-auto.md for screenshot fallback mode
- Use web_search_exa for design pattern extraction from URLs when screenshots unavailable
- Update workflow documentation to reflect new MCP tool usage
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix critical CSS loading issue where component templates were missing
style references due to contradictory instructions.
Changes:
- Require all templates (pages and components) to generate complete HTML5 documents
- Components now use full document structure with isolated body content
- Guarantees <head> tag presence for CSS placeholder injection
- Update validation to enforce <!DOCTYPE html> requirement
- Update documentation to reflect unified template approach
This ensures ui-instantiate-prototypes.sh can reliably inject STRUCTURAL_CSS
and TOKEN_CSS placeholders, fixing component styling issues.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**Extract Changes:**
- Remove Phase 1.5 MCP trend research (Exa queries)
- Save design-space-analysis.json with search keywords for consolidate
- Update to pure Claude-native analysis (aligns with philosophy)
- Simplify completion todos and output documentation
**Consolidate Changes:**
- Load design-space-analysis.json from extraction phase
- Add Step 1: Variant-Specific Trend Research (MCP) to agent prompt
- Agent performs 4 MCP queries per variant + shared accessibility research
- Refine tokens using trend insights while maintaining variant identity
- Update completion reporting and key features
**Generate Changes:**
- Enhance HTML placeholder documentation with critical warnings
- Add complete HTML template examples (page/component modes)
- Clarify {{STRUCTURAL_CSS}} and {{TOKEN_CSS}} placeholder rules
- Simplify agent completion requirements (remove detailed report format)
- Allow agent to self-report completion status
**Benefits:**
- Extract becomes truly Claude-native (no external tools)
- Consolidate agent handles all MCP research in one place
- Better separation of concerns between phases
- Clearer template generation instructions for agents
- More flexible agent reporting
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Added validation for --style-variants in generate command to ensure it matches actual style directories, preventing errors during prototype generation.
- Updated ui-instantiate-prototypes.sh script to validate style variants against existing directories, providing warnings and auto-correcting when necessary.
- Improved clarity in generate.md documentation regarding parameters, default values, and auto-detection mechanisms.
- Created a comprehensive UI Design Workflow Parameter Clarity Report to address inconsistencies in parameter naming and documentation across extract, consolidate, and generate commands.
- Unified parameter naming conventions to reduce confusion and improve user experience.
- Enhanced user guidance with a new README.md for the UI Design Workflow, outlining best practices and common mistakes.
- Removed the generation of a unified consolidation report in the consolidate.md file, streamlining the output structure.
- Updated the extract.md file to prioritize the --base-path argument for session management and improved error handling for style variant detection.
- Enhanced generate.md to enforce critical requirements for layout templates, ensuring independence from other targets.
- Added a comprehensive analysis report for the ui-instantiate-prototypes.sh script, detailing issues with style variant mismatches and proposing solutions for validation and prevention.
Changes agent task delegation from direct file writing to labeled output format, giving main command control over file paths. Fixes path inconsistency issues when called from explore-auto workflow.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Consolidate separate page/component modes into a unified target system to
reduce code duplication and simplify the workflow parameter model.
Changes:
- Merge --pages and --components into unified --targets parameter
- Add --target-type (auto|page|component) with intelligent detection
- Remove Phase 0d from explore-auto.md (131 lines of duplicate logic)
- Implement detect_target_type() helper for automatic classification
- Update generate.md to support adaptive wrapper generation
- Full HTML structure for pages
- Minimal wrapper for isolated components
- Update imitate-auto.md and update.md for parameter consistency
- Enhance ui-design-agent.md with adaptive design capabilities
- Maintain full backward compatibility with legacy syntax
Benefits:
- Code reduction: -35% in target inference logic (255 → 165 lines)
- Maintenance: Single unified logic path vs dual implementations
- Extensibility: Foundation for future mixed-mode support
- UX: Simpler parameter model with automatic type detection
Technical Details:
- explore-auto.md: 605 lines changed (unified Phase 0c)
- generate.md: 353 lines changed (targets + adaptive wrapper)
- Net change: +685 insertions, -504 deletions across 5 files
All existing workflows remain compatible via legacy parameter support.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix layout strategy generation issues across UI design commands:
- consolidate.md: Enhance layout synthesis prompt with explicit examples and requirements
* Add concrete 3-layout example to clarify expected output structure
* Emphasize requirement to generate EXACTLY N strategies (not more, not less)
* Add sequential ID validation (layout-1, layout-2, ..., layout-N)
- explore-auto.md: Add missing --layout-variants parameter to consolidate command call
* Phase 2 now passes layout_variants count to ensure correct strategy generation
* Prevents mismatch between requested layouts and generated strategies
- extract.md: Update next step suggestions to include --layout-variants parameter
* Users now see optional [--layout-variants <count>] in command examples
* Improves discoverability of layout customization option
Before: consolidate would only generate default 3 layouts even when user specified different count
After: consolidate receives and respects user-specified layout variant count
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Enhance UI Design Workflow with intelligent design trend research capabilities:
- Add design trend analysis in extract phase using Exa MCP API
- Integrate layout strategy planning with current UI/UX patterns (2024-2025)
- Update consolidation command to include dynamic layout generation
- Add ui-instantiate-prototypes.sh script for prototype management
- Simplify path structure by removing nested .design directories
- Update workflow architecture documentation
This integration enables context-aware design decisions based on modern design trends
and improves the quality of generated UI prototypes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Introduced a new command `/workflow:ui-design:imitate-auto` for imitating UI designs from URLs or images.
- Streamlined execution model with 5 phases: initialization, screenshot capture, style extraction, token adaptation, and prototype generation.
- Emphasized single style and layout generation, bypassing the consolidate step for improved speed.
- Implemented automated screenshot capture with fallback to manual input if necessary.
- Enhanced error handling for missing references and screenshot failures.
- Provided detailed documentation and examples for usage and execution flows.
