Token Drift: The Silent System Killer

Season 1 · Episode 5 · 8 min read

I want to tell you about the day I discovered my tokens were lying to me.

Not dramatically. Not all at once. Quietly. The way all system failures begin.

I was building a design system for a kiosk. Not a web product. Not a native mobile app. A kiosk — with its own rendering environment, its own color profile handling, its own pixel density behavior, and a coding language so rigorous and restricted that half the assumptions I had built into my token architecture had no valid translation on the other side.

I brought my existing tokens with me. Color values, spacing scale, typography decisions. All of it. Because the tokens were defined. The work was done. That was the point.

What I didn't account for was that "defined" and "portable" are not the same thing. And a kiosk does not care about your Figma variables.

The colors rendered differently. Not dramatically — just enough to be wrong. The spacing felt off in ways that were hard to articulate and harder to explain to an engineer working inside a coding environment that didn't recognize the token references the way a browser would. What I had built was a token architecture that was fluent in one language and expected to be understood by a platform that spoke a completely different one.

This is where most token drift stories begin. Not with bad design — with reasonable assumptions applied to the wrong context.

The Promise Tokens Make

Here is what every design system practitioner believes about tokens: define the values once, reference them everywhere, change them in one place, everything updates.

Clean. Elegant. Scalable.

That promise is true. Inside the context you designed for. The moment you step outside that context — the promise starts to fray.

Tokens don't create consistency. They expose whether your assumptions were consistent to begin with.

My color tokens assumed a screen with a specific color profile. My spacing tokens assumed a viewport with a specific density. My typography tokens assumed a rendering engine that handled font weights a particular way.

None of those assumptions were wrong. For the context I had designed them in. But in the new medium — the colors rendered differently. The spacing felt wrong. The typography looked like it belonged to a different product entirely.

They didn't. Because tokens don't translate. They reflect. And what they reflected back at me was an architecture built entirely around assumptions I had never made explicit.

The Three Layers Most Token Architectures Collapse

A token architecture has three distinct layers. Most teams treat them as one.

Layer 1 — The Values

Raw numbers. #1A1A2E. 16px. 400. These are not decisions. These are facts.

Layer 2 — The Decisions

Primary color. Body size. Regular weight. This is where meaning is assigned.

Layer 3 — The Context

Where does this decision apply? On what surface? In what rendering environment? Under what accessibility requirements?

Most token architectures name a hex value a primary color and assume the context will take care of itself. The brand changes one shade of blue and somehow that becomes twelve decisions nobody was prepared to trace. The context never takes care of itself. It just waits for the moment when it can't be ignored.

Three Rules for Tokens That Survive

Rule 1 — Separate Values From Decisions From Contexts

Primitive tokens hold raw values: blue-500: #457B9D.
Semantic tokens assign meaning: color-interactive: {blue-500}.
Component tokens assign context: button-background-default: {color-interactive}.

Three layers. Three separate files. Never collapsed. When a new medium arrives — you add a new context layer. The values and decisions underneath don't move.

Rule 2 — Use Style Dictionary as the Contract

Style Dictionary is the industry standard for cross-platform token delivery. It reads your token definitions and transforms them into whatever format any platform needs — CSS custom properties for web, Swift variables for iOS, Kotlin constants for Android.

One source. Multiple outputs. The contract holds because Style Dictionary enforces it. Without it, each platform maintains its own version. And versions drift.

Versions drift in the same way all unsupervised systems drift: gradually, then all at once, and always at the worst possible moment.

Rule 3 — Automate the Pipeline or the Drift Is Inevitable

Token Studio inside Figma is where designers work. Style Dictionary is where engineers consume. GitHub Actions is what keeps them synchronized. The moment that pipeline becomes manual — someone skips a step. The drift begins. Not because anyone was careless. Because manual processes fail under pressure. And design systems always operate under pressure.

The Quick Win: One Audit Question

Look at your current token architecture and ask one question:

"Do our tokens separate values from decisions from contexts?"

If no — you don't have a token architecture. You have a list of variables waiting to become someone else's drift problem.

Start with the semantic layer. Name your decisions explicitly. color-interactive not blue. space-component-padding not 16. Names that survive translation into any medium.

The Argument

Tokens are not the foundation. They are the mirror. And what they reflect back at you is an honest picture of every assumption you made explicit — and every one you didn't.

Disagree loudly. Inspire boldly.

And remind me — falsely if needed — that somewhere a token called blue-500 means the same thing in Figma, in code, and in production.

Do your tokens separate values from decisions from contexts?