Cover Image
Tokens drift because nobody owns the pipeline. One team edits Figma styles, another hardcodes hex values in CSS, and within weeks the two no longer match. The fix is not stricter naming conventions. It is treating tokens as versioned data with a single source of truth, automated sync into Figma and code, and written rules for who can add, change, or retire a token.
Why tokens drift: two sources of truth and no owner
Most drift starts innocently. A designer tweaks a shade in Figma to make a mock look right. A developer ships a one-off hex value to meet a deadline. Neither change flows back to a shared definition, so the next person copies whichever value they find first. Multiply that by a year and you get a product with fourteen grays and nobody who can explain where any of them came from.
Tools like TokenDrift exist precisely because this problem is so common: they scan CSS for hardcoded colors and spacing hiding outside the token system. If drift detection is a product category, drift is the default state of an ungoverned system.
The root cause is structural. Figma and code each hold their own copy of the truth, and no person or process owns the sync between them. Governance starts by naming one source of truth and one owner. A joint design engineering guild works well: designers define intent, engineers define transform outputs, and the guild reviews changes the way a team reviews API changes. Tokens are an interface between design and code, so govern them like one.
The three-tier naming system that survives scaling
Naming breaks down the moment a second brand or theme enters the picture. Flat names like blue-500 or primary cannot express intent across contexts, so the tiered system has become the standard answer: primitive, semantic, component.
Start with primitives, raw values with no meaning attached: color.blue.500 = #2563eb. Nobody uses these directly in a product. They exist so a rebrand touches values in one place.
Then add a semantic layer mapping primitives to intent: color.background.primary, color.text.muted, space.stack.md. Components consume these. When dark mode or a new brand arrives, you remap semantics, not every component.
Reserve a third tier for component exceptions: button.primary.background.hover for states too specific to live at the semantic layer. Keep this tier small. Every component token is a promise to maintain it, and a tier with hundreds of entries is a second codebase wearing a naming convention as a disguise.
The rule that makes tiers work: primitives never ship to components, and component tokens need a written justification in the change request. Without that gate, all three tiers collapse into one flat list within a year.
Single source of truth: repo-owned JSON, Figma as consumer
Here is the opinionated part. The token source of truth should live in a git repository as JSON, and Figma should consume it, not author it.
Why the repo wins: JSON diffs cleanly, versions with the product, gates changes behind pull request review, and feeds every platform transform. Figma Variables are an excellent delivery surface but a weak system of record. No blame history, no review workflow, no branch strategy. When Figma authors tokens, engineering inherits values they cannot audit, and designers inherit a sync plugin as a single point of failure.
The practical setup uses Tokens Studio for Figma as the bridge. Token sets and themes in Tokens Studio map naturally onto a governance model: sets hold the tiers, themes hold brand and mode variants, and the plugin syncs both directions with the repo. Designers keep working in Figma. The repo keeps the record. The sync keeps them honest.
This also inoculates you against vendor churn. Specify built a well loved token pipeline, then sunset the product in October 2024. Teams whose governance lived inside a single vendor had to rebuild. Teams whose tokens lived in versioned JSON swapped the sync layer and carried on. Own the data, rent the tooling.
The sync pipeline: standard format to platform outputs
A governed pipeline has three stages: author in a standard format, transform per platform, verify in CI.
First, author in the community format. The W3C Design Tokens Community Group draft defines an interchange format for token JSON. It is a draft, not a finished standard, but writing tokens in a compatible shape keeps you portable across Tokens Studio, Style Dictionary, and whatever replaces both. Avoid proprietary schemas that lock your tokens to one tool.
Second, transform with Style Dictionary. Style Dictionary takes token JSON and emits platform outputs: CSS custom properties for web, Swift or XML resources for native, whatever each target needs. Each brand and theme becomes a build configuration, not a fork. The transform layer is also where you enforce rules mechanically: reject tokens missing descriptions, reject component tokens without a linked review, fail the build on duplicate names.
Third, verify in CI. Every token pull request should run checks: schema validation against the format, contrast checks on color pairs, a diff report showing which components consume changed tokens. Figma's own design systems coverage of Variables and Code Connect points in this direction: the handoff between design and code is healthiest when it runs through versioned artifacts rather than screenshots and hope. If your token change cannot show its blast radius before merge, your pipeline is a delivery hose, not governance.
For the handoff side of this workflow, how designers package tokens for AI assisted builds matters too. Our guide to design tokens for AI handoff walks through structuring tokens so codegen tools consume them instead of inventing values.
Contribution and review rules: who can add, change, deprecate
Governance without written contribution rules is a suggestion box. Publish a short RFC style process and enforce it in review:
New tokens require a use case, a tier justification, and a name following the three-tier scheme. The requester shows the design and the code that will consume it. No speculative tokens. A token with one consumer is a variable with ambitions.
Value changes require a visual diff and a consumer list. Because semantic tokens fan out to many components, even a small value change deserves a screenshot review. Automate the consumer list from the transform output so the author cannot skip it.
Deprecation is a lifecycle, not a deletion. Mark deprecated with a removal version, alias to the replacement, warn in CI for one release cycle, then remove. Deletions without a deprecation window break downstream teams silently and teach everyone to stop trusting the system.
Ownership stays with the guild, but day to day review can rotate. Two reviewers per change: one designer checking intent and naming, one engineer checking transform output and blast radius. Small surface, fast reviews, no single gatekeeper who becomes a bottleneck.
Tooling choices feed back into these rules. Native Figma Variables versus the Tokens Studio plugin is the question every team asks, and our breakdown of AI coding tools for designers covers how designer tooling decisions ripple into engineering workflows. The governance answer: pick whichever surface your designers will actually use, but keep the repo as the record either way. Adoption beats purity; the JSON is what makes either choice reversible.
Multi-brand theming without forking the system
Multi-brand is where ungoverned systems fork. One team copies the token file, renames a few values, and now two systems evolve independently until a rebrand costs quarters instead of weeks.
The tiered model prevents the fork. Primitives stay shared. Each brand gets a theme: a complete remapping of semantic tokens onto brand owned primitives. Brand A maps color.background.primary to its white; Brand B maps the same semantic to its cream. Components never know the difference because they only read semantics.
Three guardrails keep themes honest. First, every theme must implement the full semantic set. A theme missing tokens forces components into fallback logic, which is a fork wearing a theme costume. Second, themes add mappings, never new semantics. A brand specific semantic like color.brandA.only belongs in that brand's component tier with a justification, not in shared semantics. Third, CI builds every theme on every change and screenshots the differences. A primitive change that looks fine in Brand A and breaks contrast in Brand B should fail the build, not ship to users.
Done right, a new brand launch becomes a theming exercise measured in days: define brand primitives, map semantics, review visual diffs, ship. That is the payoff governance buys. Tokens stop being a style inventory and start being infrastructure.
Start with the repo, not the rename
You do not need a rebrand or a reorganization to start. Pick the smallest slice that hurts: export current Figma values to JSON, check them into a repo, wire one sync to Figma and one Style Dictionary build to CSS. Write the three contribution rules on one page. Review the next five token changes through the new process.
Expect the first month to surface every hidden one-off in the codebase. That inventory is the point. Each hardcoded value you pull into the system is drift converted back into governance. Keep the pipeline small, the rules written, and the data owned, and the system compounds from there.
