design-system git:20260828.f80dcb5A

Immutable. This exact content is served forever at /api/v1/blob/5104191c50bc11c3.

---
name: design-system
description: Builds and maintains the design system a product is assembled from — tokens for color, type, spacing and elevation, component contracts, and the rules that keep them coherent as the product grows. Use this when starting a new interface, when screens have drifted apart visually, when the same component exists three times in slightly different forms, or when a token or component needs adding without breaking what exists.
---

# Design system

A design system is a set of constraints that makes consistency the cheap path. If the system is
harder to follow than to ignore, it will be ignored.

## Tokens first

Define the primitives before any component. Every visual decision references a token; nothing
hard-codes a value.

- **Color** — semantic names, not literal ones. `surface`, `surface-raised`, `text-primary`,
  `text-muted`, `border`, `accent`, `danger`. A token named `blue-500` cannot be re-themed.
- **Type** — a scale with a stated ratio, and a line-height per step. Four to six steps. More than
  that and nobody can tell them apart.
- **Spacing** — one scale, geometric, used for every gap and inset. Arbitrary spacing is the single
  most common source of "it looks off but I can't say why."
- **Radius, elevation, motion** — small closed sets. Two or three each.

Every token needs a light and dark value defined together. Adding dark mode later means auditing
every surface.

## Component contracts

A component in the system carries: the states it supports (default, hover, focus, active, disabled,
loading, error, empty), the props that vary it, and what it will *not* do. The last one matters
most — a component that accepts arbitrary overrides is a styling function, not a component.

Every interactive component needs a visible focus state and a target big enough to hit. This is not
a polish item; it is whether people can use it.

## Growth rules

- A new component enters the system only after the same need appears three times. Before that it is
  local.
- Changing a token is a system-wide change — treat it like an API change, because it is.
- Never remove a token or component because it looks unused. You cannot see every consumer from
  inside the system. Deprecate, announce, then remove.

## Return contract

Report tokens added or changed, components affected, anything now inconsistent with the system, and
what needs migrating.