A design system is mostly a deletion project

What a year of decisions looks like

Styling on the platform had been decided screen by screen for about a year, by several people, all of them reasonable. The result was the usual: a greenish teal and a slightly different greenish teal, four spacing scales, a card that had been reimplemented five times because finding the existing one was slower than writing a new one.

None of that is a failure of discipline. It is what happens when every screen is shipped under its own deadline and there is nowhere for a shared decision to live.

Two files, one direction of travel

The source of truth is two JSON files. Primitives hold the raw values — the actual colours, the actual steps on the type scale. Semantics map intent onto those primitives: what a surface is, what a border is, what a danger state is. Nothing else may invent a value.

A build step generates two things from them: the CSS custom properties the application consumes, and typed token objects the engineers import. That second output is what makes the system hold. An invented value is now a type error rather than a code-review conversation, and type errors do not depend on the reviewer being awake.

Light and dark stopped being two stylesheets and became one switch on a data attribute, because the semantic layer is the only thing that differs between them.

Where we got it wrong first

We seeded the token files with provisional values before the design file had been reconciled, so that the pipeline could be built and tested against something. That was the right call for the pipeline and the wrong one for everybody else, because provisional values that render correctly are indistinguishable from final ones.

For a few weeks the system looked finished and was not, and work got built on top of numbers we intended to change. The fix was procedural rather than technical: mark the provisional values as provisional in a place the build can see, and reconcile against the design file before anything downstream consumes them.

The general version of this lesson: a placeholder that looks like the real thing is worse than no placeholder at all. It removes the one signal that would have told somebody to wait.

Sixteen components, documented

The component library is deliberately small. Sixteen documented components, each built strictly on the token layer, each with its states rendered in a catalogue an engineer can open rather than guess at.

A small library used everywhere beats a large one used occasionally. Every component we added had to earn its place by replacing at least two existing implementations, which is a rule that keeps a design system from quietly becoming another thing to maintain.

The part nobody budgets for

Building the pipeline was about a fortnight. Migrating the product onto it, and deleting what it replaced, took considerably longer and was most of the actual value.

A design system that exists alongside the old styling has not reduced anything; it has added a second way to do everything. The work that matters is the removal, and it is the work that is easiest to defer because nothing visibly breaks when you skip it. If you are scoping one of these, scope the deletion. That is the project.