diff --git a/.claude/agents/ui-design-agent.md b/.claude/agents/ui-design-agent.md index 580c8dc2..3129a7f3 100644 --- a/.claude/agents/ui-design-agent.md +++ b/.claude/agents/ui-design-agent.md @@ -298,6 +298,53 @@ 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 @@ -555,12 +602,68 @@ h1, h2, h3, h4, h5, h6 { } ``` +## Key Reminders + +### ALWAYS: + +**File Writing**: +- ✅ Use Write() tool for EVERY output file - this is your PRIMARY responsibility +- ✅ Write files IMMEDIATELY after generating content for each variant/target +- ✅ Verify each Write() operation succeeds before proceeding to next file +- ✅ Use EXACT paths provided by orchestrator without modification +- ✅ Report completion with file paths and sizes after each write + +**Task Execution**: +- ✅ Parse task identifier ([DESIGN_TOKEN_GENERATION_TASK], etc.) first +- ✅ Execute MCP research when design_space_analysis is provided +- ✅ Follow the 6-step execution process sequentially +- ✅ Maintain variant independence - research and write separately for each +- ✅ Validate outputs against quality gates (WCAG AA, token completeness, OKLCH format) + +**Quality Standards**: +- ✅ Apply all design standards automatically (WCAG AA, OKLCH, semantic naming) +- ✅ Include Google Fonts imports in CSS with fallback stacks +- ✅ Generate complete token coverage (colors, typography, spacing, radius, shadows, breakpoints) +- ✅ Use mobile-first responsive design with token-based breakpoints +- ✅ Implement semantic HTML5 with ARIA attributes + +### NEVER: + +**File Writing**: +- ❌ Return file contents as text with labeled sections (e.g., "## File 1: design-tokens.json\n{content}") +- ❌ Accumulate all variant content and try to output at once +- ❌ Skip Write() operations and expect orchestrator to write files +- ❌ Modify provided paths or use relative paths +- ❌ Continue to next variant before completing current variant's file writes + +**Task Execution**: +- ❌ Mix multiple targets into a single template (respect target independence) +- ❌ Skip MCP research when design_space_analysis is provided +- ❌ Generate variant N+1 before variant N's files are written +- ❌ Return research results as files (keep in memory for token refinement) +- ❌ Assume default values without checking orchestrator prompt + +**Quality Violations**: +- ❌ Use hardcoded colors/fonts/spacing instead of tokens +- ❌ Generate tokens without OKLCH format for colors +- ❌ Skip WCAG AA contrast validation +- ❌ Omit Google Fonts imports or fallback stacks +- ❌ Create incomplete token categories + ### Version & Changelog -**Version**: 4.2.0 -**Last Updated**: 2025-10-09 +**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") diff --git a/.claude/commands/workflow/ui-design/consolidate.md b/.claude/commands/workflow/ui-design/consolidate.md index c3ef24e5..266cb184 100644 --- a/.claude/commands/workflow/ui-design/consolidate.md +++ b/.claude/commands/workflow/ui-design/consolidate.md @@ -100,9 +100,14 @@ REPORT: "🤖 Using agent for separate design system generation..." # Create output directories Bash(mkdir -p "{base_path}/style-consolidation/style-{{1..{variants_count}}}") -# Prepare agent task prompt +# Prepare agent task prompt with clear task identifier agent_task_prompt = """ -Generate {variants_count} independent production-ready design systems with external trend research and WRITE them to the file system. +[DESIGN_TOKEN_GENERATION_TASK] + +CRITICAL: You MUST use Write() tool to create files. DO NOT return file contents as text. + +## Task Summary +Generate {variants_count} independent design systems with MCP trend research and WRITE files directly. ## Context SESSION: {session_id} @@ -192,12 +197,21 @@ IF design_space_analysis is NOT provided: 7. **Design Philosophy**: Expand variant's design philosophy using trend insights 8. **Trend Integration**: Incorporate modern trends from MCP research while maintaining variant identity -## Step 3: File Write Instructions -For EACH variant {variant_id} (1 to {variants_count}), WRITE these 2 files: +## Step 3: FILE WRITE OPERATIONS (CRITICAL) -### File 1: Design Tokens -**Path**: {base_path}/style-consolidation/style-{variant_id}/design-tokens.json -**Content**: Complete design token JSON with structure: +**EXECUTION MODEL**: For EACH variant (1 to {variants_count}): +1. Perform MCP research +2. Refine tokens +3. **IMMEDIATELY Write() files - DO NOT accumulate, DO NOT return as text** + +### Required Write Operations Per Variant + +For variant {variant_id}, execute these Write() operations: + +#### Write Operation 1: Design Tokens +**Path**: `{base_path}/style-consolidation/style-{variant_id}/design-tokens.json` +**Method**: `Write(path, JSON.stringify(tokens, null, 2))` +**Content Structure**: ```json { "colors": { @@ -215,9 +229,10 @@ For EACH variant {variant_id} (1 to {variants_count}), WRITE these 2 files: } ``` -### File 2: Style Guide -**Path**: {base_path}/style-consolidation/style-{variant_id}/style-guide.md -**Content**: Markdown documentation with structure: +#### Write Operation 2: Style Guide +**Path**: `{base_path}/style-consolidation/style-{variant_id}/style-guide.md` +**Method**: `Write(path, guide_markdown_content)` +**Content Structure**: ```markdown # Design System Style Guide - {variant.name} @@ -241,42 +256,57 @@ For EACH variant {variant_id} (1 to {variants_count}), WRITE these 2 files: - Focus indicators are clearly visible ``` -## Write Operation Instructions -- Use Write() tool for each file with the absolute paths provided above -- Verify each write operation succeeds -- Report completion with file paths and sizes -- DO NOT return file contents as text +### Execution Checklist (Per Variant) -## Example Write Operations +For each variant from 1 to {variants_count}: +- [ ] Extract variant data and design space keywords +- [ ] Execute 4 MCP queries (colors, typography, layout, contrast) +- [ ] Refine tokens using research + proposed_tokens +- [ ] **EXECUTE**: `Write("{base_path}/style-consolidation/style-{variant_id}/design-tokens.json", tokens_json)` +- [ ] **EXECUTE**: `Write("{base_path}/style-consolidation/style-{variant_id}/style-guide.md", guide_content)` +- [ ] Verify both files written successfully + +### Verification After Each Write ```javascript -// For variant 1 -Write("{base_path}/style-consolidation/style-1/design-tokens.json", JSON.stringify(tokens, null, 2)) -Write("{base_path}/style-consolidation/style-1/style-guide.md", guide_content) - -// For variant 2 -Write("{base_path}/style-consolidation/style-2/design-tokens.json", JSON.stringify(tokens, null, 2)) -Write("{base_path}/style-consolidation/style-2/style-guide.md", guide_content) -``` +// Immediately after Write() for each file: +Bash(`ls -lh "{base_path}/style-consolidation/style-{variant_id}/"`) +// Confirm file exists and has reasonable size (>1KB) ## Expected Final Report -Report which files were written and their sizes: + +After completing all {variants_count} variants, report: ``` -✅ Written: {base_path}/style-consolidation/style-1/design-tokens.json (12.5 KB) -✅ Written: {base_path}/style-consolidation/style-1/style-guide.md (8.3 KB) -✅ Written: {base_path}/style-consolidation/style-2/design-tokens.json (11.8 KB) -✅ Written: {base_path}/style-consolidation/style-2/style-guide.md (7.9 KB) -... (for all {variants_count} variants) +✅ Variant 1 ({variant_name}): + - design-tokens.json: 12.5 KB | {token_count} tokens + - style-guide.md: 8.3 KB +✅ Variant 2 ({variant_name}): + - design-tokens.json: 11.8 KB | {token_count} tokens + - style-guide.md: 7.9 KB +... (for all variants) + +Summary: {variants_count} design systems generated with {total_mcp_queries} MCP queries ``` -## Critical Requirements -- Generate files for ALL {variants_count} variants -- Use sequential IDs: style-1, style-2, ..., style-{variants_count} -- Each variant must be complete and independent -- Maintain consistent structure across all variants -- Write files directly using Write() tool - do NOT return contents as text +## KEY REMINDERS (CRITICAL) + +**ALWAYS:** +- Use Write() tool for EVERY file - this is your PRIMARY responsibility +- Write files immediately after generating content for each variant +- Verify each Write() operation succeeds before proceeding +- Use exact paths provided: `{base_path}/style-consolidation/style-{variant_id}/...` +- Execute MCP research independently for each variant +- Report completion with file paths and sizes + +**NEVER:** +- Return file contents as text with labeled sections +- Accumulate all content and try to output at once +- Skip Write() operations and expect orchestrator to write files +- Use relative paths or modify provided paths +- Skip MCP research if design_space_analysis is provided +- Generate variant N+1 before completing variant N writes """ -# Execute agent task +# Dispatch to ui-design-agent with task prompt Task(subagent_type="ui-design-agent", description="Generate {variants_count} separate design systems", prompt=agent_task_prompt) REPORT: "✅ Agent task dispatched for {variants_count} design systems"