Designing a design system, end to end

A system does not start with a palette. It starts with an inventory, because you cannot fix drift you have not measured. I wrote a shell script that greps the codebase for every colour, type size and radius, and ran it against my own site.

I had declared eight colour tokens. The script found fourteen colours in use, sixty nine distinct type sizes and nineteen radii. The tokens existed. Nothing referenced them.

A design system nobody references is a style guide. The difference is enforcement, not documentation.

The reason my first eight tokens failed is that they were named after what they looked like. --accent tells you nothing about when to use it, so people guess, and guessing produces fourteen colours. Three tiers fixes that.

The payoff is concrete. Changing the pressed state of every button in the product is one line in tier three. Rebranding is one ramp in tier one. Neither touches a component file.

Four ramps, five stops each. Hover and pressed states are steps on the accent ramp rather than colours someone eyeballed, which is why the interface stays coherent when a new component appears.

Support colours carry status and nothing else. The moment green means both success and a brand accent, it stops meaning success.

Sixty nine sizes became eleven. I did not invent a modular scale, I derived the steps from what the site already used and collapsed neighbours closer than a pixel. A scale taken from the code describes the product that exists. An invented one describes a product you wish you had built.

Each step is fluid, so a single token covers phone through desktop and there are no breakpoint overrides for text anywhere in the codebase.

Most systems stop at colour and type, which is why their products still feel loose. Rhythm, corner language and easing are the three things people read as quality without being able to name them.

Three curves is a system. Eleven curves is eleven people each picking a favourite.

This is where systems are won or lost. A component is not the resting state, it is the full matrix. Hover, pressed, focus, disabled, loading, error. If the designer does not draw them, an engineer invents them at 6pm on a Friday.

Hover and press the row above. The transitions use dur-fast and ease-out-expo from step five.

Error is a state of the field, not a red line underneath it. The border, the ring and the helper text all change together, which is why the error is legible without colour alone carrying the message.

A component is only shared if its API is small enough to remember. I write the prop signature at the same time as the Figma variants, and they use the same words, so the conversation between design and engineering stops being a translation.

type ButtonProps = {
  intent?:   "primary" | "secondary" | "ghost" | "danger"
  size?:     "sm" | "md" | "lg"
  loading?:  boolean
  disabled?: boolean
}

<Button>Save changes</Button>

Variants over booleans. Four intents in one prop cannot contradict each other; four booleans can produce sixteen combinations, twelve of which are nonsense.

The audit script from step one is the system's immune response. It runs on every commit and prints the same numbers, so drift shows up as a diff instead of as a feeling six months later.

It also separates two surfaces, which took me two wrong runs to get right: system chrome must use tokens, while a case study recreating a client's interface must keep that client's literal colours. Counting those as debt would have pushed me to tokenise someone else's brand into mine.

The number I care about is the first one. Adoption is the only metric that separates a design system from a folder of opinions.

Every button, input, toggle and badge on this page is the live system, running in production, not an image of one.