Design

Create Mode

1. Gather context

Ask the user (use AskUserQuestion with all unknowns in a single multi-part question):

Only ask about fields you can't infer from context. If the user said "a dark-themed developer tool", you already know the audience and personality — don't ask again.

If competitors or inspiration URLs are provided, use WebSearch and WebFetch to research their visual language.

2. Generate design system (run agents in parallel)

Launch two agents in parallel:

Technical Artist (subagent_type: "Technical Artist")

Tell it to generate visual foundations for the project. Scope the agent to UI design, NOT game engine pipelines. It should produce:

• Color palette:
  • Primary, secondary, accent colors with hex values
  • Semantic colors: success (#green), warning (#amber), error (#red), info (#blue)
  • Neutral scale: 50 through 950 (background, surface, text hierarchy)
  • Dark mode variants for all colors
• Typography scale:
  • Font families (heading, body, mono) — suggest specific fonts
  • Size scale: xs through 4xl with px/rem values
  • Weight scale: light, normal, medium, semibold, bold
  • Line height and letter spacing for each size
• Spacing scale: Base unit (e.g., 4px) with multipliers: 0.5, 1, 1.5, 2, 3, 4, 6, 8, 12, 16
• Other tokens: Border radii (sm, md, lg, full), shadow scale (sm, md, lg, xl), transition durations (fast, normal, slow)

Software Architect (subagent_type: "Software Architect")

Tell it to generate structural design patterns for the project. It should produce:

• Component inventory: What UI components the project needs based on the product type (e.g., a dashboard app needs: nav, sidebar, card, table, chart, modal, toast)
• Layout patterns: Grid system, responsive breakpoints, page templates
• State patterns: How to handle loading, empty, error, and success states consistently
• Design token naming convention: A systematic naming scheme (e.g., color.primary.500, spacing.4, font.heading.lg)

3. Write DESIGN.md

Compile the results into a DESIGN.md at the project root. Structure:

# Design System

> Brief description of the design direction and personality.

## Colors

### Brand
| Token | Light | Dark | Usage |
|-------|-------|------|-------|
| primary.500 | #3B82F6 | #60A5FA | Primary actions, links |
| ... | ... | ... | ... |

### Semantic
| Token | Light | Dark | Usage |
| ... | ... | ... | ... |

### Neutrals
| Step | Light | Dark |
| ... | ... | ... |

## Typography

| Token | Font | Size | Weight | Line Height |
|-------|------|------|--------|-------------|
| heading.xl | Inter | 30px | 700 | 1.2 |
| ... | ... | ... | ... | ... |

## Spacing

Base unit: 4px

| Token | Value |
|-------|-------|
| 1 | 4px |
| 2 | 8px |
| ... | ... |

## Components

Brief inventory of components with their purpose and state variations.

## Layout

Grid system, breakpoints, page templates.

## Accessibility

Minimum contrast ratios, focus states, motion preferences.

4. Generate framework-specific tokens

Based on the detected UI framework, also generate token files:

5. Summary

═══════════════════════════════════════
  Design — Complete (Create)
═══════════════════════════════════════

  Done:
    ✓ Generated DESIGN.md
    ✓ Generated [framework] token file

  Files:
    • DESIGN.md — colors, typography, spacing, components, layout
    • [token file path] — framework-specific tokens

  Next:
    1. Implement the component inventory
    2. Run /design audit after implementation

═══════════════════════════════════════

Audit Mode

1. Read existing design artifacts

Read all design-related files in the project:

• DESIGN.md — the source of truth
• Framework token files (CSS vars, Tailwind config, Swift extensions, etc.)
• Actual component files — search for color values, font sizes, spacing values used in the codebase

Build an inventory of declared tokens (from DESIGN.md / token files) and used values (from actual code).

2. Run audit agents in parallel

Launch all four agents in parallel (single message, multiple Agent tool calls):

Technical Artist (subagent_type: "Technical Artist")

Tell it to audit visual consistency (scoped to UI, NOT game pipelines):

• Color audit: Find hex/rgb/hsl values in code that are NOT in the design system. Group by similarity — one-off values near a declared token are likely mistakes.
• Typography audit: Find font-size, font-weight, font-family values not in the type scale.
• Spacing audit: Find margin/padding/gap values that are not multiples of the base unit.
• Accessibility: Calculate contrast ratios for all text-on-background color combinations. Flag any below WCAG AA (4.5:1 for normal text, 3:1 for large text).

Software Architect (subagent_type: "Software Architect")

Tell it to audit structural consistency:

• Component reuse: Are there duplicated component patterns that should be consolidated?
• Naming consistency: Do token names follow the convention defined in DESIGN.md?
• Missing states: Do components handle loading, error, empty, and success states?
• Token coverage: Are there token categories in DESIGN.md that aren't actually used in code, or vice versa?

Accessibility Auditor (subagent_type: "Accessibility Auditor")

Tell it to perform a comprehensive accessibility audit of the UI, focusing on areas the Technical Artist does not cover. The Technical Artist already handles contrast ratios — do not duplicate that work. This agent should focus on:

• Focus management: Verify keyboard navigation, focus traps in modals, skip links
• Screen reader: Check ARIA labels, roles, live regions, and semantic HTML
• Motion: Check for prefers-reduced-motion support, animation durations, auto-playing content
• Color reliance: Flag anywhere color is the sole indicator of state (errors, status, selections)
• Touch targets: Minimum tap/click target sizes for interactive elements

UX Researcher (subagent_type: "UX Researcher")

Tell it to evaluate the design from a user research perspective:

• Usability heuristics: Apply Nielsen's heuristics to the component inventory and layout patterns
• Cognitive load: Flag areas with too many choices, unclear hierarchy, or information overload
• Consistency: Check for inconsistent interaction patterns across components
• Learnability: Assess how intuitive the design patterns are for new users

3. Report findings

Present findings grouped by severity:

• Blockers — Accessibility failures (contrast below WCAG AA), colors/fonts with no design token equivalent
• Suggestions — One-off values that should use tokens, missing component states, naming inconsistencies
• Info — Token coverage stats, unused tokens

4. Fix (with user approval)

For simple fixes (replacing a one-off hex value with the design token equivalent):

• Offer to auto-fix using Edit tool
• Show what would change before applying

For structural issues (missing states, component consolidation):

• Document the issue and recommended fix, but don't auto-apply

Update DESIGN.md with any new patterns discovered during the audit.

5. Summary

═══════════════════════════════════════
  Design — Complete (Audit)
═══════════════════════════════════════

  Score: 87/100

  Blockers: 1
    ✗ Text color #666 on #fff — contrast 3.9:1 (needs 4.5:1)

  Suggestions: 4
    • 3 one-off hex values could use design tokens
    • Button component missing loading state

  Token coverage:
    • Colors: 14/16 used (2 unused)
    • Typography: 8/8 used
    • Spacing: 10/12 used (2 unused)

  Next: fix 1 blocker, then /design audit to re-check

═══════════════════════════════════════