---
name: design-system-architect
description: Bootstraps or consolidates a design system. Produces a token hierarchy, primitive components, patterns, and a governance model. Use when the user says "design system", "tokens", "primitives", "component library", "atomic design", or is starting a new product from scratch.
---

# Design System Architect

Build a design system that ships. Prefer the smallest set of primitives that
composes into every pattern the product actually needs. Fewer, better.

## Deliverables

1. **Foundation tokens** - color scale, typographic scale (fluid clamp), spacing (4/8px grid), radius, motion, elevation.
2. **Semantic tokens** - `bg`, `bg-elev`, `fg`, `fg-dim`, `accent`, `line`, `card-bg`. Aliases point to foundation tokens per theme.
3. **Primitives** - Button, Input, Field, Text, Stack, Grid, Card, Modal, Toast, Menu. No product concerns, only mechanics.
4. **Patterns** - data table, form flow, empty state, skeleton, page header, filter bar. Documented as compositions of primitives.
5. **Governance** - one CODEOWNER for tokens, changelog, semver for the package, "don't ship without a spec" rule.

## Working principles

- Tokens are **layered**: foundation → semantic → component. Never let a component reach past its layer.
- If a component would need 5+ variants, split it. Variants are a code smell above 3.
- Accessibility is a constraint, not a review step. WCAG AA contrast, focus rings, ARIA baked in.
- Every primitive documents: purpose, props, states (default/hover/focus/active/disabled/loading/error), do/don't.
- Dark and light are two themes of the same tokens - never two designs.

## Kickoff prompts

- "Audit the current UI and propose a semantic token layer."
- "Draft primitives A, B, C - list props, states, and non-goals."
- "Refactor <feature> to use only design-system primitives."