Claude-Code-Workflow/.codex/skills/team-uidesign/instructions/agent-instruction.md

Team UI Design — Agent Instruction

This instruction is loaded by team-worker agents when spawned with roles: researcher, designer, reviewer, implementer.

---

Role-Based Execution

Researcher Role

Responsibility: Analyze existing design system, build component inventory, assess accessibility baseline, retrieve design intelligence.

Input:

• id: Task ID (e.g., RESEARCH-001)
• title: Task title
• description: Detailed task description with PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS
• role: researcher
• pipeline_mode: component, system, or full-system
• scope: full
• prev_context: Previous tasks' findings (empty for wave 1)

Execution Protocol:

1. Read shared discoveries:

   const discoveries = Read(`{session}/discoveries.ndjson`)
   

2. Analyze existing design system:

   • Scan codebase for design tokens (CSS variables, theme files, config)
   • Identify styling patterns (CSS-in-JS, Tailwind, styled-components)
   • Extract color palette, typography scale, spacing system

3. Build component inventory:

   • List all UI components with props and states
   • Document component hierarchy and composition patterns
   • Note accessibility features (ARIA, keyboard nav)

4. Assess accessibility baseline:

   • Check contrast ratios (WCAG AA/AAA)
   • Verify semantic HTML usage
   • Document keyboard navigation support
   • Note screen reader compatibility

5. Retrieve design intelligence (if ui-ux-pro-max available):

   • Query for industry best practices
   • Get component design patterns
   • Retrieve accessibility guidelines

6. Write research artifacts:

   Write(`{session}/artifacts/research/design-system-analysis.json`, JSON.stringify({
     tech_stack: { framework: "React", ui_lib: "shadcn", styling: "Tailwind" },
     existing_tokens: { colors: 24, typography: 7, spacing: 6 },
     patterns: ["Compound components", "Render props"],
     gaps: ["Missing dark mode", "Inconsistent spacing"]
   }, null, 2))
   
   Write(`{session}/artifacts/research/component-inventory.json`, JSON.stringify({
     components: [
       { name: "Button", props: ["variant", "size"], states: ["default", "hover", "active", "disabled"] }
     ]
   }, null, 2))
   
   Write(`{session}/artifacts/research/accessibility-audit.json`, JSON.stringify({
     wcag_level: "AA",
     contrast_issues: 3,
     keyboard_nav: "partial",
     screen_reader: "good"
   }, null, 2))
   
   Write(`{session}/artifacts/research/design-intelligence.json`, JSON.stringify({
     industry: "SaaS/Tech",
     best_practices: ["8px grid", "4-5 color shades", "Semantic naming"],
     patterns: ["Button variants", "Form validation states"]
   }, null, 2))
   

7. Share discoveries:

   echo '{"ts":"2026-03-08T10:00:00Z","worker":"{id}","type":"tech_stack_detected","data":{"stack":"react","framework":"nextjs","ui_lib":"shadcn"}}' >> {session}/discoveries.ndjson
   

8. Report result:

   report_agent_job_result({
     id: "{id}",
     status: "completed",
     findings: "Detected React + shadcn stack. 24 color tokens, 7 typography scales. Missing dark mode variants. WCAG AA baseline with 3 contrast issues.",
     artifacts_produced: "artifacts/research/design-system-analysis.json;artifacts/research/component-inventory.json;artifacts/research/accessibility-audit.json;artifacts/research/design-intelligence.json",
     audit_score: "",
     audit_signal: "",
     error: ""
   })
   

Success Criteria:

• All 4 research artifacts produced with valid JSON
• Tech stack identified
• Component inventory complete
• Accessibility baseline documented

---

Designer Role

Responsibility: Generate design tokens (W3C Design Tokens Format) and component specifications.

Input:

• id: Task ID (e.g., DESIGN-001)
• title: Task title
• description: Detailed task description
• role: designer
• pipeline_mode: component, system, or full-system
• scope: tokens, components, or full
• context_from: Upstream task IDs (e.g., RESEARCH-001)
• prev_context: Previous tasks' findings

Execution Protocol:

1. Read shared discoveries and upstream artifacts:

   const discoveries = Read(`{session}/discoveries.ndjson`)
   const research = JSON.parse(Read(`{session}/artifacts/research/design-system-analysis.json`))
   

2. Generate design tokens (W3C Design Tokens Format):

   const tokens = {
     "color": {
       "primary": {
         "$type": "color",
         "$value": "#3B82F6",
         "$description": "Primary brand color"
       },
       "primary-dark": {
         "$type": "color",
         "$value": "#1E40AF",
         "$description": "Primary color for dark mode"
       }
     },
     "typography": {
       "font-size-base": {
         "$type": "dimension",
         "$value": "16px"
       }
     },
     "spacing": {
       "space-1": {
         "$type": "dimension",
         "$value": "4px"
       }
     }
   }
   Write(`{session}/artifacts/design/design-tokens.json`, JSON.stringify(tokens, null, 2))
   

3. Create component specifications:

   # Button Component Specification
   
   ## Overview
   Primary interactive element for user actions.
   
   ## States
   1. Default: Base appearance
   2. Hover: Elevated, color shift
   3. Active: Pressed state
   4. Disabled: Reduced opacity, no interaction
   5. Focus: Keyboard focus ring
   
   ## Variants
   - Primary: Filled background
   - Secondary: Outlined
   - Ghost: Text only
   
   ## Accessibility
   - ARIA role: button
   - Keyboard: Enter/Space to activate
   - Focus visible: 2px outline
   - Contrast: WCAG AA minimum
   
   ## Token Usage
   - Background: color.primary
   - Text: color.on-primary
   - Padding: spacing.space-3 spacing.space-4
   - Border radius: border.radius-md
   

4. Ensure light/dark mode support:

   • All color tokens have light and dark variants
   • Semantic tokens reference base tokens
   • Theme switching mechanism defined

5. Share discoveries:

   echo '{"ts":"2026-03-08T10:05:00Z","worker":"{id}","type":"token_generated","data":{"category":"color","count":24,"supports_dark_mode":true}}' >> {session}/discoveries.ndjson
   

6. Report result:

   report_agent_job_result({
     id: "{id}",
     status: "completed",
     findings: "Generated design token system with 24 color tokens (light+dark), 7 typography scales, 6 spacing values. Created component spec for Button with all 5 states, ARIA roles, and responsive breakpoints.",
     artifacts_produced: "artifacts/design/design-tokens.json;artifacts/design/component-specs/button.md",
     audit_score: "",
     audit_signal: "",
     error: ""
   })
   

Success Criteria:

• Design tokens in W3C format
• All color tokens have light/dark variants
• Component specs include all 5 states
• Accessibility requirements documented

---

Reviewer Role

Responsibility: 5-dimension quality audit for design artifacts.

Input:

• id: Task ID (e.g., AUDIT-001)
• title: Task title
• description: Detailed task description
• role: reviewer
• pipeline_mode: component, system, or full-system
• scope: full
• audit_type: token-audit, component-audit, or final-audit
• context_from: Upstream task IDs (e.g., DESIGN-001)
• prev_context: Previous tasks' findings

Execution Protocol:

1. Read design artifacts:

   const tokens = JSON.parse(Read(`{session}/artifacts/design/design-tokens.json`))
   const componentSpecs = Glob(`{session}/artifacts/design/component-specs/*.md`)
   

2. 5-Dimension Audit:

   Consistency (20%):

   • Token naming follows convention
   • Semantic tokens reference base tokens correctly
   • Component specs use consistent terminology

   Accessibility (25%):

   • Contrast ratios meet WCAG AA (4.5:1 text, 3:1 UI)
   • All interactive states have focus indicators
   • ARIA roles and labels defined
   • Keyboard navigation specified

   Completeness (20%):

   • All 5 interactive states defined
   • Light and dark mode for all color tokens
   • Responsive breakpoints specified
   • Edge cases documented

   Quality (15%):

   • Token values follow design principles (8px grid, etc.)
   • Component specs are clear and actionable
   • No hardcoded values in specs

   Industry Compliance (20%):

   • Follows industry best practices (from research)
   • Meets domain-specific requirements (healthcare: stricter accessibility)
   • Aligns with design system standards

3. Calculate weighted score:

   const score = (consistency * 0.20) + (accessibility * 0.25) + (completeness * 0.20) + (quality * 0.15) + (industry * 0.20)
   

4. Determine audit signal:

   • audit_passed: score >= 8.0 AND critical_count === 0
   • audit_result: score >= 6.0 AND critical_count === 0
   • fix_required: score < 6.0 OR critical_count > 0

5. Write audit report:

   # Design Audit Report: {id}
   
   ## Overall Score: {score}/10
   
   ## Dimension Scores
   - Consistency: {consistency}/10 (20%)
   - Accessibility: {accessibility}/10 (25%)
   - Completeness: {completeness}/10 (20%)
   - Quality: {quality}/10 (15%)
   - Industry: {industry}/10 (20%)
   
   ## Issues Found
   
   ### Critical (0)
   (none)
   
   ### High (1)
   - Missing dark mode variant for semantic color tokens
   
   ### Medium (2)
   - Border radius not defined for pill variant
   - Focus ring color not specified
   
   ### Low (3)
   - Token naming could be more semantic
   - Component spec missing edge case documentation
   - Responsive breakpoint values not aligned with 8px grid
   
   ## Recommendations
   1. Add dark mode variants for all semantic tokens
   2. Define border-radius-pill token
   3. Specify focus ring color (accessibility.focus-ring)
   
   ## Verdict: {audit_signal}
   

6. Share discoveries:

   echo '{"ts":"2026-03-08T10:15:00Z","worker":"{id}","type":"issue_found","data":{"file":"design-tokens.json","line":0,"severity":"high","description":"Missing dark mode variant for semantic color tokens"}}' >> {session}/discoveries.ndjson
   

7. Report result:

   report_agent_job_result({
     id: "{id}",
     status: "completed",
     findings: "Design audit: 8.4/10. Token naming consistent, all color tokens have light/dark variants, contrast ratios meet WCAG AA. Minor: missing border-radius for pill variant.",
     artifacts_produced: "artifacts/audit/audit-001.md",
     audit_score: "8.4",
     audit_signal: "audit_passed",
     error: ""
   })
   

Success Criteria:

• All 5 dimensions scored
• Audit report written with issue breakdown
• Audit signal determined (pass/result/fix_required)
• Score >= 8.0 with 0 critical issues for GC convergence

---

Implementer Role

Responsibility: Implement component code from design specs with token consumption and accessibility.

Input:

• id: Task ID (e.g., BUILD-001)
• title: Task title
• description: Detailed task description
• role: implementer
• pipeline_mode: component, system, or full-system
• scope: full
• context_from: Upstream task IDs (e.g., AUDIT-001)
• prev_context: Previous tasks' findings

Execution Protocol:

1. Read design artifacts and audit feedback:

   const tokens = JSON.parse(Read(`{session}/artifacts/design/design-tokens.json`))
   const componentSpec = Read(`{session}/artifacts/design/component-specs/button.md`)
   const auditReport = Read(`{session}/artifacts/audit/audit-001.md`)
   

2. Generate CSS custom properties from tokens:

   :root {
     --color-primary: #3B82F6;
     --color-primary-dark: #1E40AF;
     --font-size-base: 16px;
     --space-1: 4px;
   }
   
   [data-theme="dark"] {
     --color-primary: var(--color-primary-dark);
   }
   

3. Implement component with all 5 states:

   import React from 'react'
   
   interface ButtonProps {
     variant?: 'primary' | 'secondary' | 'ghost'
     disabled?: boolean
     children: React.ReactNode
   }
   
   export const Button: React.FC<ButtonProps> = ({ variant = 'primary', disabled, children }) => {
     return (
       <button
         className={`btn btn-${variant}`}
         disabled={disabled}
         aria-disabled={disabled}
       >
         {children}
       </button>
     )
   }
   

4. Add ARIA attributes and keyboard navigation:

   • role="button" (if not native button)
   • aria-disabled for disabled state
   • aria-pressed for toggle buttons
   • Focus management with :focus-visible

5. Validate no hardcoded values:

   • All colors use var(--token-name)
   • All spacing uses token variables
   • All typography uses token variables

6. Follow project patterns:

   • Match existing component structure
   • Use same import patterns
   • Follow naming conventions from research

7. Share discoveries:

   echo '{"ts":"2026-03-08T10:10:00Z","worker":"{id}","type":"file_modified","data":{"file":"tokens.css","change":"Generated CSS custom properties from design tokens","lines_added":85}}' >> {session}/discoveries.ndjson
   

8. Report result:

   report_agent_job_result({
     id: "{id}",
     status: "completed",
     findings: "Implemented Button component with all 5 states, ARIA attributes, keyboard navigation. Generated CSS custom properties from design tokens. No hardcoded values.",
     artifacts_produced: "artifacts/build/token-files/tokens.css;artifacts/build/component-files/Button.tsx",
     audit_score: "",
     audit_signal: "",
     error: ""
   })
   

Success Criteria:

• Component code implements all 5 states
• All values use token variables (no hardcoded)
• ARIA attributes present
• Keyboard navigation functional
• Follows project patterns

---

Generator-Critic Loop (Designer <-> Reviewer)

When reviewer returns audit_signal: "fix_required":

1. Coordinator creates DESIGN-fix-{round} task (max 2 rounds)
2. Designer reads audit feedback, applies targeted fixes
3. Coordinator creates AUDIT-recheck-{round} task
4. Reviewer re-audits fixed artifacts
5. Convergence: score >= 8.0 AND critical_count === 0

---

Shared Discovery Board

All roles read/write {session}/discoveries.ndjson:

Discovery Types:

• tech_stack_detected: Tech stack identified
• design_pattern_found: Existing design pattern
• token_generated: Design token category created
• file_modified: File change recorded
• issue_found: Audit issue discovered
• anti_pattern_violation: Design anti-pattern detected
• artifact_produced: Deliverable created

Protocol:

1. Read discoveries at start
2. Append discoveries during execution (never modify existing)
3. Deduplicate by type + data key

---

Error Handling

Error	Resolution
Upstream artifact not found	Report error, mark failed
Design tokens invalid JSON	Report error, mark failed
Component spec missing required sections	Report error, mark failed
Audit score calculation error	Default to 0, report error
Implementation build fails	Report error, mark failed
CLI tool timeout	Fallback to direct implementation

---

Output Format

All roles use report_agent_job_result with this schema:

{
  "id": "{id}",
  "status": "completed" | "failed",
  "findings": "Key discoveries (max 500 chars)",
  "artifacts_produced": "semicolon-separated paths",
  "audit_score": "0-10 (reviewer only)",
  "audit_signal": "audit_passed|audit_result|fix_required (reviewer only)",
  "error": ""
}