Your design system has a drift problem, not a documentation problem
When Figma and code disagree, teams write more docs. But a doc is just another copy of the truth — and copies drift. The fix isn't informational. It's architectural.
Siarhei Tarasenka
Product Designer
I’ve sat through this meeting enough times to know the script. Someone — usually a designer, usually tired — puts Figma on one monitor and production on the other, and starts a spreadsheet: the project’s design review. One row per mismatch — the button that’s the wrong shade, the gap that grew four pixels, the radius nobody remembers changing. By row forty the room has a plan: fix the mismatches, update the documentation, remind everyone to check the library before shipping. Maybe a recurring design–engineering sync, so this never happens again.
Everyone nods. It feels like closure.
Six months later: same meeting, new spreadsheet, new forty rows.
The ritual repeats because the plan quietly assumes drift is an information problem — people didn’t know, so let’s tell them better. But I’ve been on both sides of those forty rows, and knowledge was never the thing that was missing. The people who shipped those mismatches knew the system; most of them helped build it. What actually happened is smaller and more boring: they edited one copy of a value while three other copies sat elsewhere, unchanged, with nothing in the world responsible for keeping them equal.
That’s not a knowledge gap. That’s architecture.
The misdiagnosis
When design and code disagree, the reflex is to document harder: write the guidelines page, pin the spec, build the wiki that finally explains the way we do things. I understand the reflex, because I’ve followed it — twice. Both times the result was a genuinely nice docs page I was proud of for about a month. Both times it changed nothing, and it took me longer than I’d like to admit to see why:
Documentation is another copy of the same facts.
A docs page that says the brand blue is #1072EA is one more place that value now lives — next to Figma, the CSS, and the brand deck that marketing keeps asking about. And copies don’t just sit there. Every copy pairs with every other copy, and every pair is a seam where the system can quietly split. Two copies, one seam. Add a docs site — three. Add the deck — six.
So the team that “finally documented the design system” usually didn’t reduce drift. They grew its surface — and gave it one more place to hide, because now a mismatch between Figma and code can be settled by a docs page that’s wrong in a third way.
Drift is physics, not morals
Here’s the definition I’d write on the whiteboard: drift is what happens when the same fact is stored in more than one place with no mechanism keeping the stores equal. Given edits and time, the copies diverge. Not because anyone is careless — because divergence is the default state of duplicated data. The only variable is when.
It’s the same law that governs a single file, just scaled up: the first heuristic I use for tokens says a value that appears twice must be extracted, because two inline copies will split. A design system’s Figma library, its CSS, and its docs are that situation at organizational scale. Same law, bigger blast radius, slower clock.
And there’s a human side to this that teams are strangely reluctant to say out loud. A huge share of drift is born in one specific moment: a developer translating a Figma mockup into code by eye. Things get lost in that translation — a 12px gap becomes 16, a tertiary grey becomes the secondary one, a radius quietly rounds itself off — and the tempting conclusion is that the developer was sloppy. They weren’t. Telling two greys a shade apart is trained vision: designers spend years calibrating that eye, and developers spend those same years calibrating a different one — the one that catches a race condition or an off-by-one you’d walk right past. Asking someone to hand-copy a design pixel-for-pixel is asking them to be a rendering engine, and humans are not rendering engines. That’s not a flaw in the developer. That’s the species.
A process that only works if every developer sees like a designer isn’t a process. It’s a bet against human nature, renewed every sprint.
Which is why treating drift as a discipline problem never sticks. Discipline is real, but it’s a force applied against a gradient: relax it for one sprint — a deadline, a handoff, a reorg — and the copies resume doing what copies do. Blaming the team for drift is blaming them for gravity. The audit doesn’t find the people who failed. It finds the places where the architecture asked humans to be a sync mechanism — or a rendering engine — and humans, being humans, weren’t.
The doc is a copy too — and the slowest one
There’s a second, quieter problem with documentation as the fix: of all the copies, the doc drifts fastest, because it’s the only copy nothing depends on.
Code that’s wrong breaks something; someone notices. A Figma library that’s wrong produces wrong mockups; a designer notices. A docs page that’s wrong produces… nothing. No build fails. No review flags it. The nicest docs page I ever wrote died exactly this way — a rebrand nudged the blue, the page kept its old hex, and for months it politely told everyone the wrong color. Nobody noticed. Including me.
#0A57BD current #0E63D0 a true answer — then #1072EA a true answer — then Every one of those answers was true when it was written. That’s what makes stale documentation so durable — it doesn’t lie, it just keeps telling the truth about a system that has moved on. A document is a snapshot pretending to be a source. And asking the team to “keep the docs updated” is asking them to solve duplication with more diligence — the exact resource whose scarcity caused the drift in the first place.
What actually removes drift
You can’t reliably synchronize copies. You can stop having them.
The fix is derivation: one machine-readable source, with every other surface generated from it. The Figma variables are rendered from the theme file. The CSS is compiled from the theme file. The reference tables in the docs are built from the theme file. Change the source, and every surface moves together — not because everyone was careful, but because there was never a second value to forget.
Where a surface derives, drift isn’t discouraged. It’s impossible — for the same reason a spreadsheet cell computed by a formula can’t disagree with its inputs. No audit, no sync meeting, no reminder. The whole category of error is just gone, though only across the surfaces that derive; everywhere authoring still happens in two places, the clock keeps ticking.
Notice what this does to the developer’s-eye problem from earlier: it deletes it. When the CSS is generated from the same file Figma renders, nobody translates anything by eye. The 12px gap arrives in code as the same token it was in the mockup — not as a guess about what the mockup meant. The developer’s vision stops being a load-bearing part of your visual quality. That’s good news for the developers too; nobody enjoys being blamed for a shade of grey.
This is most of why I build Veritheme the way I do — one theme.json generating the Figma side, the CSS side, and the machine-readable side. But the principle is bigger than any one system, and it’s getting more urgent, not less: there’s a third consumer now, and models multiply copies faster than humans ever did. Every AI tool that gets handed a screenshot of your system instead of its source is one more place your blue is about to be approximately right.
What documentation is actually for
None of this makes documentation worthless. It makes documentation misassigned.
The docs were failing at a job they should never have had: storing facts. What is the brand blue, what is the spacing scale, which radius does a card use — those are values, and values belong in the source, rendered into the docs, never typed into them. The rule of thumb I’ve settled on: anything a document states that a machine also states will eventually be stated differently by the two of them.
What no other surface stores is reasoning. Why the scale sits on a 4px grid. Why there’s one primary button per view. Why spacing stays primitive while color goes semantic. Judgment, constraints, tradeoffs, the decisions behind the values — that content can’t drift, because it isn’t duplicated anywhere; the source stores the what, the doc stores the why. Document the reasoning. Derive the facts.
The honest limits of derivation are the mirror image of its strength, and they’re worth naming. A generated system centralizes the blast radius — a careless edit to the source propagates everywhere, instantly, so the source needs the governance of a shared dependency: review, versioning, rollback. And a half-finished migration creates its own seams: a partially derived system is a source plus the surviving legacy copies, which is more stores than you started with until you finish. Derivation is a debt worth taking on. It isn’t free.
The diagnostic
If you’re not sure which problem your team actually has, there’s a clean test, and it costs one quarter of patience.
Fix the mismatches. Update everything. Then change nothing about how the system works — and wait.
If the fixes hold, it really was an information problem, and the documentation did its job. If the spreadsheet refills — same seams, new rows — you’ve learned something no amount of writing will change: the drift is structural, and its recurrence is the system pointing at exactly where the copies live. Recurring drift isn’t a failure of the last audit. It’s the schedule for the next one.
Everything on that list works, briefly. Audits work — for a day. Docs work — until the next edit. Meetings work — while everyone’s in the room. They all correct the copies without touching the reason copies diverge, which is why they recur on a calendar. Only removing the copies changes what next quarter looks like.
The tax and the invoice
Drift is a tax, and every team pays it one way or another. The audit day, the “why doesn’t this match?” threads, the hour a designer spends working out whether Figma or production is right, the developer quietly taking the blame for a grey they had no realistic way to catch — that’s the quarterly invoice for storing one truth in four places.
Documentation doesn’t cancel the tax. It adds a page to the invoice.
The way out is the boring, structural one: one source, generated surfaces, docs that explain decisions instead of restating values. Stop paying quarterly for the copies to be corrected. Delete the copies — and let the audit die of natural causes.
I haven’t opened one of those spreadsheets in a while now. I don’t miss them.
P.S. Full disclosure: derivation is the reason Veritheme exists — an open-source system where one theme.json generates the Figma variables, the CSS, and a machine-readable bundle for AI tools, so there are no copies left to drift. If your team is paying the drift tax, it might save you an audit or two. And if you’ve beaten drift some other way, I genuinely want to hear how — tell me.
Siarhei Tarasenka
Product Designer
Product designer, manager, and team lead with 18+ years of experience. Ex-principal designer of a top-charting AI assistant with 100M+ downloads. Creator of the Veritheme design system; IADAS member and judge at the Webby and Lovie Awards.
Follow