Why our design tokens are boring on purpose
Every interesting token is a token someone has to remember. We cut ours to four layers and the design review got shorter.
The first version of our token set had thirty-one categories. It was, by any reasonable measure, expressive: you could describe a hover state on a destructive button in a disabled card without writing a single hard-coded value. Nobody used it.
What we learned is that a token is a shared vocabulary, and vocabularies fail the moment they get bigger than the people using them. Every extra layer was another thing a new engineer had to hold in their head before they could confidently change a colour.
The four that survived
Colour, radius, space and type. Everything else became a recipe — a named combination of those four — which meant it could live next to the component instead of in the global vocabulary.
// Four layers, and nothing else gets to be a token.export const tokens = { color: { brand: "var(--brand-600)" }, radius: { md: "0.5rem" }, space: { 4: "1rem" }, type: { body: "0.875rem/1.25rem" },};A design system is not measured by what it can express. It is measured by what a tired engineer gets right on a Friday afternoon.
The review cost dropped immediately. Not because the tokens were better, but because there were few enough of them that a reviewer could hold the whole set in mind and notice when something was off.