Building Forms That Don't Fight the Browser

A colleague asked me last week why our team cares so much about design tokens. I gave a rambling answer, so here is the longer, more organized version.

The setup was ordinary: Playwright at the edges, Storybook 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.

What was going wrong

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.

When we finally measured, the numbers were worse than anyone guessed. Around 33% of the time spent on a typical change went into working around design tokens rather than building anything.

A simpler approach

Rather than a big-bang rewrite, we migrated one module at a time over about 6 weeks, keeping both paths alive behind a flag.

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

Nothing about this is clever, and that's the point. Anyone on the team can read it in a minute and know exactly what it does.

A few things that helped along the way:

• Delete dead code aggressively; it's the cheapest refactor there is.
• Write the migration guide before writing the migration.
• Agree on what "done" means before the first pull request.

What it cost us

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

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

I don't think there's a universal answer here, but I hope this gives you a few ideas to try on your own project. If you do, I'd love to hear how it goes.