design-system

# Design System

Build, evolve, or audit a design system. Stack-agnostic in principle. Implementation is stack-specific (Figma, Storybook, code library, etc.) but the structure and governance principles transfer.

This skill is for building the system. For applying a system to specific pages or components, use `design-standards`. For brand visual identity, use `brand-identity`.

---

## When to use

- Building a design system from scratch
- Auditing an existing system for gaps or fragmentation
- Defining design tokens at the system level
- Structuring a component library
- Establishing contribution and governance models
- Migrating from ad-hoc components to a documented system

## When NOT to use

- Designing a single page or component (use `design-standards`)
- Brand identity work (use `brand-identity`)
- Component-level frontend implementation (use `frontend-component-build`)
- Pure design documentation for marketing (use `brand-style-guide`)

---

## Required inputs

- The brand identity (tokens, voice, imagery direction)
- The product surfaces the system needs to support (web, mobile, marketing, app, internal tools)
- The team and its working tools (Figma, code framework, doc platform)
- Existing components, even if undocumented
- Constraints (accessibility requirements, performance targets, browser support)

If brand identity is undefined, run `brand-identity` first.

---

## The framework: 5 layers

A complete design system has five layers, stacked. Each layer feeds the layer above.

### 1. Foundations (tokens)

The atomic decisions. Color, type, spacing, radius, shadow, motion, breakpoints.

**Why this layer matters:**
- Tokens are the source of truth for everything above
- Token changes propagate everywhere automatically
- Without tokens, the system has no foundation

**Output:**
- A documented token set (see `design-standards/references/design-tokens-template.md`)
- Token implementation in code (CSS variables, JS objects, Style Dictionary, etc.)
- Token implementation in Figma (variables and styles)
- A primer doc explaining what tokens to use when

**Common patterns:**
- Two-tier tokens: base tokens (raw values) + semantic tokens (named uses). Example: `color-blue-600` (base) + `color-text-link` (semantic). Components reference semantic tokens. Theme changes update semantic tokens, not base.

### 2. Elements (atoms)

The smallest functional building blocks. Buttons, inputs, labels, badges, icons, links, dividers.

**Per element, document:**
- Visual variants (primary, secondary, ghost, etc.)
- Size variants (small, medium, large)
- States (default, hover, focus, active, disabled, error, loading)
- Anatomy (the parts that make up the element)
- Spacing and proportions
- Accessibility (keyboard support, screen reader behavior, ARIA)
- Code usage (props, examples)

**Output:**
- Element library in Figma
- Element components in code
- Per-element documentation

### 3. Components (molecules + organisms)

Combinations of elements that form recognizable UI patterns. Cards, alerts, modals, navigation, forms, data tables, headers, footers.

**Per component:**
- Composition (which elements it uses)
- Variants and configurations
- Use cases (when to reach for this vs. an alternative)
- Layout behavior (responsive, contained, full-bleed)
- Anti-patterns (when NOT to use it)

**Output:**
- Component library
- Per-component documentation with usage guidance

### 4. Patterns (templates)

Larger structures that combine components. Sign-in flow, settings page, dashboard layout, marketing page sections.

**Per pattern:**
- The structure and components used
- The user journey it supports
- Layout grid and spacing
- Responsive behavior
- Variants (e.g., "with sidebar," "fullscreen," "modal")

**Output:**
- Pattern library or page templates
- Documentation showing complete examples

### 5. Documentation and governance

How the system gets used, contributed to, and maintained.

**Documentation includes:**
- Getting started guide for new team members
- How to use vs. how to extend
- Contribution model
- Versioning policy
- Migration paths when breaking changes happen
- Decision log for major system choices

**Governance includes:**
- Who owns the system (a team or rotation)
- How new components get proposed and approved
- How conflicts get resolved
- How the system evolves vs. stays stable
- Cadence of review and updates

---

## Workflow

### For a new design system

1. **Inventory the existing UI.** Screenshot every component, button, form, modal across the product. The list of distinct UI patterns is your starting scope.
2. **Identify the duplicates.** Same component built 5 different ways across the product. These are your high-value consolidation targets.
3. **Define foundations.** Token set, with both base and semantic layers. Document each.
4. **Audit elements.** From the inventory, identify the actual elements (buttons, inputs, etc.) and reduce variants to a managed set.
5. **Build the element library.** Figma + code. Document each element.
6. **Identify priority components.** The 10 to 15 components that appear most often. Build those first.
7. **Document patterns.** Page-level templates that show the system in use.
8. **Establish governance.** Owner, contribution model, review cadence.
9. **Roll out.** Migrate existing surfaces to the system progressively.

### For an existing design system audit

1. **Inventory what exists.** What's documented, what's in Figma, what's in code, what's actually used in production.
2. **Map gaps.** Where the system is incomplete. Where teams build outside the system because the system can't serve their need.
3. **Map fragmentation.** Where the system has divergent implementations (Figma vs. code, web vs. mobile, multiple teams).
4. **Identify decay.** Components that have drifted from the documented standard.
5. **Prioritize fixes.** Foundation gaps first. High-use component drift second. Rarely-used component cleanup last.
6. **Plan rollout.** Major changes