Design tokens won't save your product

After two years of maintaining a token system across three platforms, I learned that naming things is only half the battle.

Last winter I inherited a design token file with 612 entries across three platforms. What began as a tidy hierarchy had become a map no single engineer could trace end to end. The same token produced different colors on different pages, and nobody could explain why.

The token explosion

By spring, our token-to-Canvas sync broke whenever a designer renamed a layer. The linter rejected overrides that product had already signed off. Each tool solved a real problem and quietly created a new one.

Automation and its discontents

I traced a single surface color through five layers of aliasing and found it would silently affect seventeen components. Four of those had no visual regression tests. None of us knew the full dependency graph anymore, and the CI pipeline took eleven extra minutes to tell us things we already suspected.

The most reliable part of our system was not the token file. It was the two engineers who could tell you, from memory, which components shared which values.

A design system is a social contract, not a software artifact. The real system lives in the conversations between the people who maintain it — the design critiques, the code reviews, the Loomline threads where someone asks whether a component should use the surface or elevated background token.