Design System Audit

---
name: design-system-audit
description: Audit an existing brand / design system for consistency, completeness, token coverage, dark-mode readiness. Used by `visual-designer` (primary) + `frontend-implementer` (token-to-code wiring).
---

# Skill: design-system-audit

**Purpose:** Audit an existing brand / design system for consistency, completeness, token coverage, dark-mode readiness. Used by `visual-designer` (primary) and `frontend-implementer` (token-to-code wiring).

## When to use

- Site / app has visible drift (different blues, different button styles, different spacing)
- Pre-redesign assessment ("what's our actual current system?")
- Dark-mode rollout planning
- Component-library audit
- Onboarding a new brand or sub-brand

## The audit dimensions

For each dimension, score: ✅ consistent / ⚠️ partial / 🔴 inconsistent.

### 1. Color

- Brand color used consistently across surfaces
- Functional colors (success / warning / danger / info) clearly distinct
- Neutral scale: continuous progression (9-step or 11-step), no gaps
- Color used semantically (`color.text.primary`) not raw (`color.gray.500`)
- Contrast ratios ≥ 4.5:1 for body, ≥ 3:1 for UI components
- Dark-mode pair exists for every light-mode color (or documented exception)

### 2. Typography

- Type scale (8-step typical): `display`, `h1`, `h2`, `h3`, `body`, `body-small`, `caption`, `label`
- One font for display, one for body (max two display)
- Weight palette: usually 400 / 600 / 700; never every weight loaded
- Line-height system: tight for headings, comfortable for body
- Font-loading strategy: subsets, `font-display`, preloads on critical fonts

### 3. Spacing

- Geometric scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 (or `8pt` system)
- No off-scale values in production
- Negative space respected in layouts

### 4. Layout

- Grid system documented (12-column desktop standard; 4 mobile typical)
- Breakpoints documented (sm / md / lg / xl with definitions)
- Max content widths defined
- Container queries used where supported (or media-query fallback)

### 5. Radius & elevation

- Radius scale (none / sm / md / lg / full) documented
- Elevation / shadow scale documented (0 / 1 / 2 / 3 / overlay)
- Consistent application (cards at `sm`, modals at `lg`, etc.)

### 6. Motion

- Timing functions: ease-out (entries) / ease-in (exits) / ease-in-out (through-states)
- Duration scale (100 / 200 / 300 / 500ms)
- **Tap-feedback latency: 80–150ms** for a tactile/visual response to a touch/click — distinct from the transition duration scale above; a control with no acknowledgment inside that window reads as unresponsive even if the eventual transition timing is correct.
- `prefers-reduced-motion` fallbacks present

### 7. Iconography

- Icon set documented (single source, single visual style)
- Sizing scale (16 / 20 / 24 / 32)
- Color treatment consistent (currentColor preferred)
- **Emoji used as a structural icon** (nav item, button, status indicator) is a named anti-pattern — flag it, don't wave it through as "quick and cheap." Reserve emoji for genuinely decorative/informal contexts, never a UI affordance.
- **Meaningful (non-decorative) icons carry their own ≥3:1 contrast minimum** against their background — called out separately from body-text contrast (WCAG 1.4.11, non-text contrast), because an icon audit that only checks text contrast misses this.

### 8. Components

- Button: variants × states × sizes documented + implemented consistently
- Input: variants × states × sizes
- Card, navigation, modal, tabs, accordion — each has a spec + an implementation

### 9. Tokens layer

- Primitive tokens defined (raw values)
- Semantic tokens defined (use-cases consuming primitives)
- Components consume **semantic** tokens, not primitives
- Token build pipeline (JSON → CSS variables / framework consumption)
- Dark-mode token swaps via semantic re-pointing, not component overrides

### 10. Documentation

- Living style guide (Storybook / dedicated docs site)
- Component docs include: anatomy, states, accessibility notes, usage do's-and-don'ts
- Decision log for non-obvious choices

## Output

| Dimension | Score | Findings | Severity (P0 / P1 / P2) |
|---|---|---|---|

Plus:
- **Top 5 fixes** by leverage (fixing N components vs. fixing token layer once)
- **Token-rationalization opportunities** (drop unused, consolidate redundant)
- **Dark-mode readiness gap** (if applicable)
- **Recommendation:** keep / refresh / rebuild

## Severity

- **P0** — system fails consistency at the consumer-visible level (different greens on same page); fix before next launch
- **P1** — token layer drifts from components; fix before next major feature
- **P2** — improvable; not a current visible problem

## Anti-patterns the audit catches

- Components consuming primitive tokens directly
- "Brand blue" with 4 different hex values across the codebase
- Spacing values outside the scale
- A "design system" that's actually a screenshot library
- Dark mode added by global `filter: invert()`
- Storybook stories that don't reflect production reality

## See also

- Template: [`../../templates/design-system-spec.md`](../../templates/design-system-spec.md)
- Agent: [`../../agents/visual-designer.md`](../../agents/visual-designer.md)
- Agent: [`../../agents/frontend-implementer.md`](../../agents/frontend-implementer.md)