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.
Tooling
Design source: Figma, and similar. Component documentation and review: Storybook.
Token pipelines: Style Dictionary, Tokens Studio, Figma variables exported to code, and
similar. Visual regression: Chromatic, Percy, Playwright snapshots, and similar.
The system is the code, not the design file. When the two disagree, the code is what ships.
Never
- Add a component for a single screen. A one-use component is a snippet, not a system.
- Hard-code a value a token already covers. The exception becomes the next inconsistency.
- Redefine what an existing token means instead of adding one. Changing a semantic silently redecorates everything downstream.
- Ship a component without its states documented — empty, loading, error, disabled.
Return contract
Report tokens added or changed, components affected, anything now inconsistent with the system, and
what needs migrating.
1---2name: design-system3description: 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.4---56# Design system78A design system is a set of constraints that makes consistency the cheap path. If the system is9harder to follow than to ignore, it will be ignored.1011## Tokens first1213Define the primitives before any component. Every visual decision references a token; nothing14hard-codes a value.1516- **Color** — semantic names, not literal ones. `surface`, `surface-raised`, `text-primary`,17 `text-muted`, `border`, `accent`, `danger`. A token named `blue-500` cannot be re-themed.18- **Type** — a scale with a stated ratio, and a line-height per step. Four to six steps. More than19 that and nobody can tell them apart.20- **Spacing** — one scale, geometric, used for every gap and inset. Arbitrary spacing is the single21 most common source of "it looks off but I can't say why."22- **Radius, elevation, motion** — small closed sets. Two or three each.2324Every token needs a light and dark value defined together. Adding dark mode later means auditing25every surface.2627## Component contracts2829A component in the system carries: the states it supports (default, hover, focus, active, disabled,30loading, error, empty), the props that vary it, and what it will *not* do. The last one matters31most — a component that accepts arbitrary overrides is a styling function, not a component.3233Every interactive component needs a visible focus state and a target big enough to hit. This is not34a polish item; it is whether people can use it.3536## Growth rules3738- A new component enters the system only after the same need appears three times. Before that it is39 local.40- Changing a token is a system-wide change — treat it like an API change, because it is.41- Never remove a token or component because it looks unused. You cannot see every consumer from42 inside the system. Deprecate, announce, then remove.4344## Tooling4546Design source: Figma, and similar. Component documentation and review: Storybook.4748Token pipelines: Style Dictionary, Tokens Studio, Figma variables exported to code, and49similar. Visual regression: Chromatic, Percy, Playwright snapshots, and similar.5051The system is the code, not the design file. When the two disagree, the code is what ships.5253## Never5455- Add a component for a single screen. A one-use component is a snippet, not a system.56- Hard-code a value a token already covers. The exception becomes the next inconsistency.57- Redefine what an existing token means instead of adding one. Changing a semantic silently redecorates everything downstream.58- Ship a component without its states documented — empty, loading, error, disabled.5960## Return contract6162Report tokens added or changed, components affected, anything now inconsistent with the system, and63what needs migrating.
cbrock84