---
name: design-system
description: Create a cohesive design system with tokens and component patterns for frontend
summary: "Creates a visual language — color palette (WCAG-compliant), typography scale, spacing system, component patterns — and generates working theme config files for your frontend framework."
phase: "environment"
order: 320
dependencies: [dev-env-setup]
outputs: [docs/design-system.md, docs/coding-standards.md]
reads: [create-prd]
conditional: "if-needed"
knowledge-base: [design-system-tokens]
---

## Purpose
Define a complete visual language (colors, typography, spacing, borders, shadows)
and configure the frontend framework's theme with these design tokens. Document
reusable component patterns so all AI agents build consistent, accessible,
professional UI without requiring design expertise from the user.

## Inputs
- docs/tech-stack.md (required) — frontend framework and UI library choices
- docs/plan.md (required) — application purpose and target users inform design direction
- User preferences (gathered via questions) — overall feel, color preferences,
  reference apps, dark mode requirement

## Expected Outputs
- docs/design-system.md — color palette, typography scale, spacing scale, border
  radius, shadows, component patterns (buttons, forms, cards, feedback, navigation,
  data display), layout system, and do's/don'ts
- Theme configuration files (tailwind.config.js, theme.ts, CSS custom properties, etc.)
- Example implementation page demonstrating the design system
- docs/coding-standards.md updated with Styling / Design System section
- CLAUDE.md updated with Design System section and quick reference

## Quality Criteria
- (mvp) All colors meet WCAG AA contrast requirements
- (mvp) Typography scale uses a consistent modular ratio; body text >= 16px; line height >= 1.5 for body text
- (mvp) Spacing uses a consistent system with a defined base unit (e.g., 4px for custom systems, Tailwind spacing scale, or Material Design grid)
- (deep) Component patterns cover buttons, forms, cards, feedback, navigation, data display
- (mvp) Theme configuration files actually work (verified by running dev server)
- (deep) Both light and dark mode token values provided (if dark mode requested)
- (deep) Responsive breakpoints defined (mobile, tablet, desktop)
- (mvp) No arbitrary hex values or pixel values in component examples (all use tokens)

## Methodology Scaling
- **deep**: Full design system with all component categories, dark mode support,
  responsive breakpoints, animation guidelines, accessibility audit, and example
  page demonstrating all patterns. 15-20 pages.
- **mvp**: Color palette, typography, spacing scale, and button/form/card patterns.
  No dark mode. Basic theme config. 3-5 pages.
- **custom:depth(1-5)**:
  - Depth 1: color palette and typography scale only.
  - Depth 2: colors, typography, and button patterns.
  - Depth 3: add forms, cards, and spacing scale.
  - Depth 4: add navigation, data display, layout system, and responsive breakpoints.
  - Depth 5: full suite with dark mode, accessibility audit, and animation guidelines.

## Conditional Evaluation
Enable when: tech-stack.md includes a frontend framework (React, Vue, Angular, Svelte,
etc.), plan.md describes a UI-based application, or project targets web/mobile
platforms. Skip when: project is backend-only, a CLI tool, or a library with no UI.

## Mode Detection
Update mode if docs/design-system.md exists. In update mode: never change color
values, font families, or spacing scales without user approval. Preserve all
theme config file customizations.

## Update Mode Specifics
- **Detect prior artifact**: docs/design-system.md exists
- **Preserve**: color palette, typography scale, spacing scale, existing
  component patterns, theme configuration files, dark mode token values,
  responsive breakpoint definitions
- **Triggers for update**: new UI features need new component patterns, UX spec
  requires additional interaction states, accessibility audit identified contrast
  issues, user requests design direction change
- **Conflict resolution**: if a new component pattern conflicts with existing
  token usage, extend the token set rather than modifying existing values;
  always verify WCAG AA compliance after any color changes

## Adoption Mode Specifics
- **Codify from repo evidence**: the visual language already shipped —
  existing token sources (tailwind.config, CSS custom properties, theme
  files), the fonts and color values in actual use, and recurring component
  patterns in the UI code. The document names what exists before proposing
  anything.
- **Interview only for**: which current visuals are intentional brand
  decisions versus accidents — this is the one step where the user may want
  change, but every change is opt-in per token, never assumed.
- **Ingest with provenance**: fold incumbent token definitions into the
  design-system doc with provenance annotations; record WCAG contrast
  measurements of the existing palette as findings, not as automatic
  changes.
- **Do not**: restyle working UI; introduce a parallel token system when one
  exists (extend the incumbent scale); swap fonts or palette values without
  explicit approval.