Design Tokens Are a Contract, Not a Color Palette

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

The setup was ordinary: Playwright 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.

The problem

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

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.

What we changed

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

The core of it looks like this:

.card-list {
  container-type: inline-size;
}

@container (min-width: 36rem) {
  .card {
    display: grid;
    grid-template-columns: 12rem 1fr;
    gap: 1.5rem;
  }
}

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:

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

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.

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.