A design system is a set of decisions, not a set of components

Almost every team I join has a design system already. It is usually a Figma page of components with a colour palette above them, and by the time I arrive there are four button variants that look nearly identical and nobody can explain which to use where.

The components were never the hard part. The hard part is the decisions: which one, when, and why not the other.

Tokens first, and fewer than you think

Start with a small, semantic token set. Not 'green-500' but 'action-primary'. The moment a token carries meaning rather than a value, rebranding stops being a search-and-replace across four hundred layers, and engineers stop asking which blue.

Be ruthless about the size of the scale. Six spacing steps beats fourteen. A designer given fourteen options will use eleven of them, and the eleventh will be four pixels off the tenth.

• Colour: semantic roles, not hues, with contrast validated at creation.
• Type: five sizes, two weights, fixed line heights.
• Spacing: a 4pt scale with six steps and no exceptions.
• Radius and elevation: three values each, tied to meaning.

Document the 'when', not the 'what'

A component page that says 'this is a button, it has three variants' is worthless — anyone can see that. What it needs to say is: primary is the single most important action on the screen and there is never more than one; secondary is for the alternative path; ghost is for actions in a dense table where a filled button would create visual noise.

Write the anti-patterns too. 'Do not use a destructive button for a reversible action.' 'Do not put two primaries on one screen.' Rules with reasons get followed. Rules without reasons get worked around.

The real test

A system is working when a new designer builds their first screen without asking a question, and an engineer builds it without opening the design file to measure padding. If either of those is still happening, you have a component library, not a design system.