Components are decisions wrapped around foundations. If you build the Button before you've defined what 'primary' means in your color system, you've baked an arbitrary choice into a thing the rest of the system will inherit from. Every component you build after will either match the arbitrary choice or rebel against it.
Foundations first means: agree on the visual primitives the entire system will compose from, before the component layer exists. Four foundations cover most of what matters — color, typography, spacing, motion — and getting them right takes a week, not a quarter.
Color: scales before semantics
Build an eleven-step scale (50–950) for each color family you ship — primary, neutral, plus a small set of semantic accents (success, warning, danger, info). The scale should be perceptually uniform, which OKLCH gives you for free. Don't ship raw hex values as UI tokens; ship the scale and reference it.
Semantic aliases come next: text-default, surface-page, border-subtle, brand-primary. Components use the semantic names. Themes (light, dark, high-contrast) swap the underlying scale references. The semantic layer is what makes the system themeable.
Typography: a ratio, a stack, a small set
Pick a modular ratio (minor third, major third, perfect fourth) and a base size. The ratio generates the scale — xs through 6xl. Eight steps is enough for most product UI; an editorial system can have more.
Pair two families: a body sans for everything, a display family if your brand calls for one. Do not pair Inter with Inter at five different weights and call it typography.
Spacing: one base unit, no exceptions
Pick a base unit — 4px or 8px. Build a scale by multiplication: 4, 8, 12, 16, 24, 32, 48, 64, 96. That's it. If a spacing value isn't on the scale, you're inventing a new one and creating a new exception future you will have to maintain.
Above the primitive scale, semantic tokens describe roles: card-padding, section-gap, control-padding-x. Components reference the semantic names so the scale can shift without rewriting components.
Motion: durations and easings, not animations
Define a small set of duration tokens (instant, fast, base, slow) and easing tokens (ease-out, ease-in-out, spring). That's the system's motion vocabulary. Animations themselves — the choreography of a modal opening or a row reordering — are component-level decisions.
Apple's HIG and Material Design both treat motion as a first-class foundation. Carbon publishes its motion tokens with documented durations down to the millisecond. Borrow that discipline.
- 01Foundations are color, typography, spacing, motion — and they ship before the first component.
- 02Color: 11-step OKLCH scales, semantic aliases on top, themes swap the references.
- 03Type: one modular ratio, two families max, eight sizes is plenty.
- 04Spacing: one base unit, no off-scale values.
- 05Motion: duration and easing tokens; animations are component decisions on top.
Token Generator
Generate the four foundations end-to-end — OKLCH color scales, type scale, spacing ladder, shape, and shadow — with W3C-spec exports.
Color
How modern systems structure color — primitive scales, semantic layers, theme references.
Typography
Modular type scales, line-height tokens, and the discipline of restraint.