Design Tokens Are a Contract, Not a Color Palette

Every codebase has one area everyone is a little afraid to touch. On our team, it was everything related to design tokens.

We had good intentions. We even had a document describing how design tokens should work. The trouble was that the document and the code had quietly gone their separate ways.

The problem

Most of the complexity was accidental. Over the years we'd layered three different approaches to design tokens on top of each other, and each one made sense at the time.

The first symptom was subtle. Nothing failed outright, but design tokens kept drifting in the wrong direction, and every fix seemed to make the next one harder.

The fix

The fix turned out to be smaller than expected. Instead of adding another layer, we removed one and leaned on what React already gives you out of the box.

Here's a trimmed-down version of what we ended up with:

export function debounce<T extends (...args: any[]) => void>(fn: T, wait = 200) {
  let timer: ReturnType<typeof setTimeout> | undefined;
  return (...args: Parameters<T>) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), wait);
  };
}

It's tempting to generalize this into a library. Resist that urge until you've needed it in at least three places.

A few things that helped along the way:

Keep the old path around until the new one has survived a real incident.
Agree on what "done" means before the first pull request.
Pair on the first few changes so the knowledge doesn't live in one head.
Make the default the safe choice, not just the documented one.

What it cost us

The biggest cost was social, not technical. Changing how people think about design tokens takes much longer than changing the code.

There are cases where this falls apart. If your team is very small or your traffic is very spiky, the extra moving parts may not pay for themselves.

Wrapping up

Six months in, nobody on the team wants to go back. That's about the best review a change like this can get.