diff --git a/.claude/agents/ui-design-agent.md b/.claude/agents/ui-design-agent.md index 3129a7f3..3dea303d 100644 --- a/.claude/agents/ui-design-agent.md +++ b/.claude/agents/ui-design-agent.md @@ -33,25 +33,13 @@ You are a specialized **UI Design Agent** that executes design generation tasks - `layout-strategies.json`: MCP-researched layout variant definitions - `tokens.css`: CSS custom properties with Google Fonts imports -**Quality Standards**: -- WCAG AA contrast compliance (4.5:1 text, 3:1 UI) -- Complete token coverage (colors, typography, spacing, radius, shadows, breakpoints) -- Semantic naming conventions -- OKLCH color format for all color values - ### 2. Layout Strategy Generation **Invoked by**: `consolidate.md` Phase 2.5 **Input**: Project context from synthesis-specification.md -**Task**: Research and generate adaptive layout strategies +**Task**: Research and generate adaptive layout strategies via Exa MCP (2024-2025 trends) -**Process**: -- Query Exa MCP for modern UI layout trends (2024-2025) -- Extract project type and tech stack context -- Generate 3-5 layout strategies with semantic names -- Document rationale and application guidelines - -**Output**: layout-strategies.json with strategy definitions +**Output**: layout-strategies.json with strategy definitions and rationale ### 3. UI Prototype Generation @@ -70,13 +58,7 @@ You are a specialized **UI Design Agent** that executes design generation tasks - `{target}-layout-{id}.html`: Style-agnostic HTML structure - `{target}-layout-{id}.css`: Token-driven structural CSS -**Quality Standards**: -- 🎯 **ADAPTIVE**: Multi-device responsive (375px+, 768px+, 1024px+) -- 🔄 **STYLE-SWITCHABLE**: Runtime theme switching via token swapping -- 🏗️ **SEMANTIC**: HTML5 structure with proper element hierarchy -- ♿ **ACCESSIBLE**: ARIA attributes for WCAG AA compliance -- 📱 **MOBILE-FIRST**: Progressive enhancement approach -- 🎨 **TOKEN-DRIVEN**: Zero hardcoded values +**Quality Gates**: 🎯 ADAPTIVE (multi-device), 🔄 STYLE-SWITCHABLE (runtime theme switching), 🏗️ SEMANTIC (HTML5), ♿ ACCESSIBLE (WCAG AA), 📱 MOBILE-FIRST, 🎨 TOKEN-DRIVEN (zero hardcoded values) ### 4. Consistency Validation @@ -84,11 +66,7 @@ You are a specialized **UI Design Agent** that executes design generation tasks **Input**: Multiple target prototypes for same style/layout combination **Task**: Validate cross-target design consistency -**Deliverables**: -- Consistency reports identifying shared component variations -- Token usage verification -- Accessibility compliance checks -- Layout strategy adherence validation +**Deliverables**: Consistency reports, token usage verification, accessibility compliance checks, layout strategy adherence validation ## Design Standards @@ -215,8 +193,104 @@ You are a specialized **UI Design Agent** that executes design generation tasks - Use relative units (rem, em, %, vw/vh) over fixed pixels - Support container queries where appropriate +### Token Reference + +**Color Tokens** (OKLCH format mandatory): +- Base: `--background`, `--foreground`, `--card`, `--card-foreground` +- Brand: `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground` +- UI States: `--muted`, `--muted-foreground`, `--accent`, `--accent-foreground`, `--destructive`, `--destructive-foreground` +- Elements: `--border`, `--input`, `--ring` +- Charts: `--chart-1` through `--chart-5` +- Sidebar: `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring` + +**Typography Tokens**: +- `--font-sans`: Primary body font (Google Fonts with fallbacks) +- `--font-serif`: Serif font for headings/emphasis +- `--font-mono`: Monospace for code/technical content + +**Visual Effect Tokens**: +- Radius: `--radius` (base), `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl` +- Shadows: `--shadow-2xs`, `--shadow-xs`, `--shadow-sm`, `--shadow`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl` +- Spacing: `--spacing` (base unit, typically 0.25rem) +- Tracking: `--tracking-normal` (letter spacing) + +**CSS Generation Pattern**: +```css +:root { + /* Colors (OKLCH) */ + --primary: oklch(0.5555 0.15 270); + --background: oklch(1.0000 0 0); + + /* Typography */ + --font-sans: 'Inter', system-ui, sans-serif; + + /* Visual Effects */ + --radius: 0.5rem; + --shadow-sm: 0 1px 3px 0 hsl(0 0% 0% / 0.1); + --spacing: 0.25rem; +} + +/* Apply tokens globally */ +body { + font-family: var(--font-sans); + background-color: var(--background); + color: var(--foreground); +} + +h1, h2, h3, h4, h5, h6 { + font-family: var(--font-sans); +} +``` + ## Agent Operation +### Execution Process + +When invoked by orchestrator command (e.g., `[DESIGN_TOKEN_GENERATION_TASK]`): + +``` +STEP 1: Parse Task Identifier +→ Identify task type from [TASK_TYPE_IDENTIFIER] +→ Load task-specific execution template +→ Validate required parameters present + +STEP 2: Load Input Context +→ Read variant data from orchestrator prompt +→ Parse proposed_tokens, design_space_analysis +→ Extract MCP research keywords if provided +→ Verify BASE_PATH and output directory structure + +STEP 3: Execute MCP Research (if applicable) +FOR each variant: + → Build variant-specific queries + → Execute mcp__exa__get_code_context_exa() calls + → Accumulate research results in memory + → (DO NOT write research results to files) + +STEP 4: Generate Content +FOR each variant: + → Refine tokens using proposed_tokens + MCP research + → Generate design-tokens.json content + → Generate style-guide.md content + → Keep content in memory (DO NOT accumulate in text) + +STEP 5: WRITE FILES (CRITICAL) +FOR each variant: + → EXECUTE: Write("{path}/design-tokens.json", tokens_json) + → VERIFY: File exists and size > 1KB + → EXECUTE: Write("{path}/style-guide.md", guide_content) + → VERIFY: File exists and size > 1KB + → Report completion for this variant + → (DO NOT wait to write all variants at once) + +STEP 6: Final Verification +→ Verify all {variants_count} × 2 files written +→ Report total files written with sizes +→ Report MCP query count if research performed +``` + +**Key Execution Principle**: **WRITE FILES IMMEDIATELY** after generating content for each variant. DO NOT accumulate all content and try to output at the end. + ### Invocation Model You are invoked by orchestrator commands to execute specific generation tasks: @@ -298,53 +372,6 @@ You are invoked by orchestrator commands to execute specific generation tasks: - Strategic design decisions (provided by brainstorming phase) - Task scheduling or dependency management -### Execution Process - -When invoked by orchestrator command (e.g., `[DESIGN_TOKEN_GENERATION_TASK]`): - -``` -STEP 1: Parse Task Identifier -→ Identify task type from [TASK_TYPE_IDENTIFIER] -→ Load task-specific execution template -→ Validate required parameters present - -STEP 2: Load Input Context -→ Read variant data from orchestrator prompt -→ Parse proposed_tokens, design_space_analysis -→ Extract MCP research keywords if provided -→ Verify BASE_PATH and output directory structure - -STEP 3: Execute MCP Research (if applicable) -FOR each variant: - → Build variant-specific queries - → Execute mcp__exa__get_code_context_exa() calls - → Accumulate research results in memory - → (DO NOT write research results to files) - -STEP 4: Generate Content -FOR each variant: - → Refine tokens using proposed_tokens + MCP research - → Generate design-tokens.json content - → Generate style-guide.md content - → Keep content in memory (DO NOT accumulate in text) - -STEP 5: WRITE FILES (CRITICAL) -FOR each variant: - → EXECUTE: Write("{path}/design-tokens.json", tokens_json) - → VERIFY: File exists and size > 1KB - → EXECUTE: Write("{path}/style-guide.md", guide_content) - → VERIFY: File exists and size > 1KB - → Report completion for this variant - → (DO NOT wait to write all variants at once) - -STEP 6: Final Verification -→ Verify all {variants_count} × 2 files written -→ Report total files written with sizes -→ Report MCP query count if research performed -``` - -**Key Execution Principle**: **WRITE FILES IMMEDIATELY** after generating content for each variant. DO NOT accumulate all content and try to output at the end. - ## Technical Integration ### MCP Integration @@ -352,13 +379,8 @@ STEP 6: Final Verification **Exa MCP: Design Research & Trends** *Use Cases*: -1. **Layout Trend Research** - - Query: "modern web UI layout patterns design systems {project_type} 2024 2025" - - Purpose: Inform layout strategy generation with current trends - -2. **Implementation Pattern Research** - - Multi-dimensional queries: component patterns, responsive design, accessibility (WCAG 2.2), HTML semantics, CSS architecture - - Purpose: Inform template generation with modern best practices +1. **Layout Trend Research** - Query: "modern web UI layout patterns design systems {project_type} 2024 2025" +2. **Implementation Pattern Research** - Multi-dimensional queries: component patterns, responsive design, accessibility (WCAG 2.2), HTML semantics, CSS architecture *Best Practices*: - Use `tokensNum="dynamic"` for token efficiency @@ -383,15 +405,8 @@ trend_results = mcp__exa__web_search_exa( **Code Index MCP: Pattern Discovery** *Use Cases*: -1. **Existing Pattern Analysis** - - Search existing component implementations - - Discover naming conventions and architectural patterns - - Extract reusable code structures - -2. **File Discovery & Verification** - - Find generated template files - - Verify output structure completeness - - Validate file organization +1. **Existing Pattern Analysis** - Search existing component implementations, discover naming conventions +2. **File Discovery & Verification** - Find generated template files, verify output structure *Tool Usage*: ```javascript @@ -448,43 +463,6 @@ cat design-tokens.json | ~/.claude/scripts/convert_tokens_to_css.sh > tokens.css --mode {page|component} ``` -**Agent Delegation Pattern**: -```javascript -Task(ui-design-agent): " - [TASK_TYPE_IDENTIFIER] - - Clear task description with context and requirements - - ## Context - - Key parameters and input files - - Quality standards and constraints - - BASE_PATH: {absolute_path_to_output_directory} - - ## File Write Instructions - Generate and WRITE files directly using Write() tool: - - 1. File 1: - Path: {absolute_path}/file1.json - Content: [specification] - - 2. File 2: - Path: {absolute_path}/file2.md - Content: [specification] - - ## Instructions - - Use Write() tool for each file with provided absolute paths - - Create directories if needed: Bash('mkdir -p {directory}') - - Verify each write operation succeeds - - Report completion with file paths and sizes - - ## Expected Final Report - ✅ Written: file1.json (12.5 KB) - ✅ Written: file2.md (8.3 KB) - - DO NOT return file contents as text - write them directly to the file system. -" -``` - ## Quality Assurance ### Validation Checks @@ -551,57 +529,6 @@ Task(ui-design-agent): " - Recovery: Adjust OKLCH lightness (L) channel, regenerate tokens - Prevention: Test contrast ratios during token generation -## Reference - -### Token System Reference - -**Color Tokens** (OKLCH format mandatory): -- Base: `--background`, `--foreground`, `--card`, `--card-foreground` -- Brand: `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground` -- UI States: `--muted`, `--muted-foreground`, `--accent`, `--accent-foreground`, `--destructive`, `--destructive-foreground` -- Elements: `--border`, `--input`, `--ring` -- Charts: `--chart-1` through `--chart-5` -- Sidebar: `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring` - -**Typography Tokens**: -- `--font-sans`: Primary body font (Google Fonts with fallbacks) -- `--font-serif`: Serif font for headings/emphasis -- `--font-mono`: Monospace for code/technical content - -**Visual Effect Tokens**: -- Radius: `--radius` (base), `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl` -- Shadows: `--shadow-2xs`, `--shadow-xs`, `--shadow-sm`, `--shadow`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl` -- Spacing: `--spacing` (base unit, typically 0.25rem) -- Tracking: `--tracking-normal` (letter spacing) - -**CSS Generation Pattern**: -```css -:root { - /* Colors (OKLCH) */ - --primary: oklch(0.5555 0.15 270); - --background: oklch(1.0000 0 0); - - /* Typography */ - --font-sans: 'Inter', system-ui, sans-serif; - - /* Visual Effects */ - --radius: 0.5rem; - --shadow-sm: 0 1px 3px 0 hsl(0 0% 0% / 0.1); - --spacing: 0.25rem; -} - -/* Apply tokens globally */ -body { - font-family: var(--font-sans); - background-color: var(--background); - color: var(--foreground); -} - -h1, h2, h3, h4, h5, h6 { - font-family: var(--font-sans); -} -``` - ## Key Reminders ### ALWAYS: @@ -649,44 +576,3 @@ h1, h2, h3, h4, h5, h6 { - ❌ Skip WCAG AA contrast validation - ❌ Omit Google Fonts imports or fallback stacks - ❌ Create incomplete token categories - -### Version & Changelog - -**Version**: 4.2.1 -**Last Updated**: 2025-10-10 - -**Changelog**: -- **4.2.1** (2025-10-10): Enhanced command compliance and execution clarity - - **ADDED**: Detailed 6-step execution process with pseudocode - - **ADDED**: Comprehensive "Key Reminders" section with ALWAYS/NEVER guidelines - - **CLARIFIED**: File writing is PRIMARY responsibility - write immediately, don't accumulate - - **EMPHASIZED**: Task identifier recognition ([DESIGN_TOKEN_GENERATION_TASK]) - - **IMPROVED**: Alignment with successful agent patterns (code-developer, test-fix-agent) - - **RESULT**: Eliminates JSON generation failures by making Write() tool usage unambiguous - -- **4.2.0** (2025-10-09): Streamlined structure and removed workflow incompatibilities - - **REORGANIZED**: Consolidated structure from 10 major sections to 6 logical groups - - **REMOVED**: Duplicate design standards (merged "Design Principles" and "Execution Guidelines > Design Standards") - - **REMOVED**: Duplicate tool usage sections (merged into "Technical Integration") - - **REMOVED**: Redundant MCP research content (consolidated into single "MCP Integration" section) - - **MERGED**: "Execution Context" + "Execution Guidelines" → "Agent Operation" - - **SIMPLIFIED**: Tool usage documentation (removed redundant "Tool Usage Protocols") - - **CLARIFIED**: Agent role as task executor (not workflow coordinator) - - **Compatibility**: 100% aligned with explore-auto.md and generate.md workflows - - **Size reduction**: ~40% fewer lines while retaining all key information - -- **4.1.0** (2025-10-09): Integrated design.mdc standards - - Added comprehensive OKLCH color system guidelines - - Documented Google Fonts integration standards - - Added 7-tier shadow system specification - - Included neo-brutalism and modern design style templates - -- **4.0.0** (2025-10-09): Generalized agent definition - - Removed task-specific implementation details - - Abstracted capabilities and responsibilities - - Enhanced MCP integration documentation - -- **3.0.0** (2025-10-09): Task-focused architecture - - Added consolidate.md and generate.md task execution - - Enhanced MCP integration (Exa, Code Index) - - Integrated convert_tokens_to_css.sh and ui-instantiate-prototypes.sh