Design System

A design system is the set of decisions you refuse to make twice. This skill owns the reusable layer: tokens, primitives, component contracts, data display.

The layers

Foundations (tokens) → Primitives → Components → Patterns → Domain components. Each layer builds on the one below and never reaches upward. The boundary that matters most: a primitive never knows the domain. Button, Input, Dialog, Popover are primitives; InvoiceStatusCard is a domain component composed from them. The moment a primitive grows an invoiceStatus prop, the system has started rotting.

The system is defined by recurring needs, not by quota. A primitive earns its place when the same need shows up on a second screen; a catalog completed for completeness is dead weight.

The ladder — always in this order

For every element the work touches:

1. Reuse the existing token, component, or state.
2. Extend an existing one (a new variant, a new state).
3. Compose existing pieces.
4. Create, only when something on screen today needs it and nothing fits.

Follow the target project's framework, styling, and naming. Never introduce a second token source, a parallel styling convention, or an outside framework's idioms. When a reference here disagrees with the project's established convention, the project wins, except accessibility, which always holds.

Hard rules

• One source of truth per value. A color that exists as a token and a hardcoded hex is two sources; kill one.
• Semantic names: --color-surface-elevated, not --gray-100. The name says what it's for, not what it looks like today.
• Every added abstraction needs a caller that exists today. A component built "for later" is later's tech debt now.
• A component that needs more than 3 variants to describe itself is fighting the domain: split it.
• Every applicable state from the feature's declared state matrix (see the interaction-design skill), plus hover/active/focus/disabled on anything interactive, or the component isn't done.

References

• tokens.md: OKLCH-first color tokens, the full naming convention, spacing/type/radius/shadow/z-index scales, type utility classes.
• primitives.md: specs for the primitives that recur in every app (Button through ProgressBar), with prop shapes, naming contracts, states, and a11y wiring. What is deliberately not a primitive, and why there is no Typography component.
• components.md: the component taxonomy, prop APIs as design contracts, discriminated unions over boolean bags, state machine tables for Button, Form, SearchableList, and Modal, and when to split a component.
• data-display.md: tables and data grids: alignment, sort, loading, empty, pagination, keyboard grid navigation, and the density rules that keep data UI honest.