Why your design tokens aren't working
Spoiler: it's not the tooling. It's the lack of a shared mental model between design and engineering — and no amount of Style Dictionary config will fix that.
Most token implementations I’ve inherited or audited are a mess. Not because the tooling is wrong — Style Dictionary, Tokens Studio, Figma Variables — these are all perfectly capable. The problem is almost always conceptual.
Teams adopt tokens without agreeing on what a token actually represents. Is color-primary-500 a token? Sure, in a technical sense. But does it encode any design intent? Does it tell an engineer when to use it versus color-primary-600? No. It’s a value with a name. That’s not a system — that’s a lookup table.
Mental models matter more than tooling
The most successful token systems I’ve built share one trait: the team had a shared mental model before anyone opened a config file. They could articulate the difference between a reference token and a system token. They understood why color.bg.surface.primary exists and blue-500 shouldn’t be used directly.
This mental model doesn’t come from documentation — though documentation helps. It comes from sitting in a room (or a call) with designers and engineers and working through real decisions together. When should we create a new token? When should we alias? When is a one-off value acceptable?
Without this shared understanding, you end up with one of two failure modes: an explosion of tokens that nobody can navigate, or so few tokens that engineers bypass the system entirely. Both are symptoms of the same root cause.
The three-tier architecture
The pattern I keep coming back to is a three-tier token architecture. Tier 1 is reference tokens — raw values that describe what something is, not where it’s used. Tier 2 is system tokens — these encode design decisions and describe intent. Tier 3 is component tokens — scoped to specific components, allowing local overrides without breaking the global system.
It’s not revolutionary. Plenty of mature systems use something similar. But the clarity it provides is worth spelling out explicitly before you start naming things.
Naming is the hardest part
I’ve spent more hours debating token names than I’d care to admit. But naming isn’t bikeshedding — it’s API design. A token name is a contract between the system and its consumers.
My rules: use a consistent grammatical structure, avoid abbreviations that aren’t universally understood, and never encode a specific value in the name. color.bg.surface.primary tells you what it’s for. background-white tells you what colour it was when someone named it. Those are very different things.
Closing thoughts
Design tokens are deceptively simple. A name, a value, maybe some metadata. But the decisions encoded in that simplicity are what separate a design system that scales from one that collapses under its own weight.
If your tokens aren’t working, don’t reach for a new tool. Reach for a whiteboard.