A design ledger stops the drift

Design drift is what happens when the fortieth component doesn't look like the first. Nobody decides on it. It arrives one reasonable exception at a time.

The fix I settled on is a single markdown file per project — a design ledger — plus a check in CI that fails the build when a component contradicts it.

What goes in it

Not a style guide. A style guide describes intentions. A ledger records decisions, and each entry is specific enough to check:

• Every surface colour, by role. Not #FFFFFF — surface, which happens to be white today.
• The radius scale, and which size is used where.
• The type scale, and the two or three weights that exist.
• Status colours, kept separate from the accent, because they mean something.

If a value isn't in the ledger, it doesn't exist. That's the entire rule.

Naming the role, never the colour

The thing that makes this work is one habit borrowed from daisyUI: components reference a role, never a value. You don't write bg-white, you write bg-surface. You don't write text-slate-500, you write text-ink-2.

The payoff shows up the first time you ship a dark theme. If every component names roles, the second theme is a block of variable overrides and nothing else changes. If any component hardcoded a colour, you find out immediately, because it's the one that looks broken.

Making it fail loudly

A ledger nobody enforces is documentation, and documentation rots. So there's a script in the pre-commit chain that walks the component tree and fails on any hex literal, any radius outside the scale, any font size that isn't on the ramp.

It takes about a second to run and it has caught me more times than I'd like to admit — almost always at 11pm, when adding one exception felt completely reasonable.

What it costs

An afternoon to write, and a small amount of friction every time you genuinely do need a new value. That friction is the point. Adding to the ledger is a deliberate act, which means the system grows on purpose instead of by accident.

It's the cheapest consistency I've ever bought.