Shipping Less JavaScript Without Rewriting Everything

There is no shortage of articles about React. Most of them cover the happy path. This one is about what happened after the happy path ended.

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 problem

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 setup was ordinary: React at the edges, Vue doing most of the heavy lifting, and a handful of scripts nobody wanted to own. It worked well until usage roughly doubled over a single quarter.

How it works

The key insight was to treat design tokens as part of the interface rather than an implementation detail. Once we did that, most of the other decisions followed naturally.

Stripped of the project-specific bits, it looks like this:

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);
  };
}

This alone let us delete a surprising amount of code elsewhere in the project.

A few things that helped along the way:

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.
Keep the old path around until the new one has survived a real incident.

Caveats

None of this is free. The new approach is a bit more verbose, and newcomers occasionally ask why we don't just use Vue for everything. That's a fair question with a boring answer: we tried, and it made design tokens harder to reason about.

We still haven't solved form validation. That's a post for another day, and honestly, I'm not sure we'll get it right the first time either.

Closing thoughts

If you take one thing away from this, let it be this: design tokens is a design decision, not a cleanup task. Make it early and make it on purpose.