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.