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.
1---2name: design-system-23description: 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---5
6# Design system
7
8A design system is a set of constraints that makes consistency the cheap path. If the system is
9harder to follow than to ignore, it will be ignored.
10
11## Tokens first
12
13Define the primitives before any component. Every visual decision references a token; nothing
14hard-codes a value.
15
16- **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 than
19 that and nobody can tell them apart.
20- **Spacing** — one scale, geometric, used for every gap and inset. Arbitrary spacing is the single
21 most common source of "it looks off but I can't say why."
22- **Radius, elevation, motion** — small closed sets. Two or three each.
23
24Every token needs a light and dark value defined together. Adding dark mode later means auditing
25every surface.
26
27## Component contracts
28
29A 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 matters
31most — a component that accepts arbitrary overrides is a styling function, not a component.
32
33Every interactive component needs a visible focus state and a target big enough to hit. This is not
34a polish item; it is whether people can use it.
35
36## Growth rules
37
38- A new component enters the system only after the same need appears three times. Before that it is
39 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 from
42 inside the system. Deprecate, announce, then remove.
43
44## Return contract
45
46Report tokens added or changed, components affected, anything now inconsistent with the system, and
47what needs migrating.
majiayu000