What a design system is actually for

Most teams describe a design system as a palette, a type scale and a component library. That description is accurate and not very useful — it tells you what is in the box, not what the box is for.

Here is the more useful framing, which came out of consolidating one across about twenty pages this month.

A design system is a list of decisions you have stopped making

Every card on a site involves the same handful of choices. What is the corner radius? Is there a border, a shadow, or both? What is the padding? What happens on hover?

Without a system, those questions get answered again on every page, by whoever is building it, under whatever time pressure they are under that day. The answers are all defensible in isolation. Collectively they are noise — and the noise is what people mean when they say a site "feels inconsistent" without being able to point at anything specific.

The system's job is to answer those questions once, in a place with a name, so nobody spends attention on them again.

The value is not that the answer is optimal. It is that the answer is settled.

The audit that tells you the truth

Before consolidating anything, count. Grep the codebase for each competing idiom and see how many of each you have.

Ours came back roughly like this:

Five ways to be bold, three radii for the same kind of surface, and italics scattered across headings with no rule about when. Nobody decided this. It accumulated — the way these things always do, one reasonable local choice at a time.

That table is the actual state of the design, and it is more honest than any style guide document, because it is measured from what ships rather than from what was intended.

Ratchets, not guidelines

The failure mode of design systems is that they are advisory. A document nobody reads describes what should happen, the code does something else, and the gap widens quietly.

What works better is making the system the path of least resistance:

• Name the pattern. If a card is .panel, people reach for .panel. If it is eleven utility classes, people copy the nearest eleven utility classes they can find — including whatever drift is in them.
• Delete the alternatives. We had CSS redefining text-primary and bg-primary as fixed shades, shadowing the framework's own token-backed versions. Both looked right. Only one tracked the theme. Removing the duplicate meant there was no longer a wrong one to pick.
• Let structure carry the repetition. Sixteen of our pages had a near-identical hero. They are now one component with props. The consistency is no longer maintained by discipline; it is maintained by there only being one implementation.

That last one matters most. Anything held together by everyone remembering to do it will drift the moment someone is in a hurry.

What we would do differently

We restyled first and documented second, which meant the design document described the old system while the code had moved on — for about a day, but still. The doc should change in the same commit as the code, or it becomes another artifact that quietly disagrees with reality.

We also found the audit more valuable than expected and would run it earlier next time. Ten minutes of grepping told us more about the real state of the design than reading the pages did.

What we shipped this week

• Consolidated the token layer: one radius scale, one weight for headings, one source of truth for the brand colour.
• Extracted the repeated page hero, section header and closing call-to-action into shared components.
• Rewrote the design system document to describe what the code now does, rather than what it used to.

If you are about to start a design system: begin by counting what you already have. The number of ways your team currently writes "bold" is the most informative metric you will collect all week.