How to keep design tokens in sync with code

I keep design tokens in sync with code by choosing one authoritative token source, generating platform values from it, and reviewing design and code changes together. Stable semantic names, automated validation, and versioned releases prevent the design library and the shipped product from developing separate definitions.

Choose a single source of truth for design tokens

I start by deciding where a token becomes official. A design library, a repository and a spreadsheet cannot all hold that authority. For a team shipping a web product, my default is a version-controlled token file in the product repository or a dedicated package. Designers can propose changes elsewhere, but approved values enter through that file.

That choice has a cost. Designers need a practical way to inspect and propose edits without becoming build engineers. I would provide a generated token reference and a small proposal template containing the name, intended use, current value and proposed value. A design-tool extension can help, but it must write proposals rather than silently replace approved data.

A design-tool-first setup can work too. I only accept it when exports are repeatable, reviewable and tied to identifiable releases. The key decision is authority, not file location. If someone edits an exported platform file, the next generation step should replace that edit, not absorb it as another source.

Name design tokens by purpose, not appearance

I separate raw values from decisions about their use. A reference token might be `color.blue.600`. A semantic token such as `color.action.primary.background` points to that reference. Components consume the semantic name because their job is to express an action, not to remain blue forever. That distinction makes a palette change manageable.

Material Design describes reference, system and component tokens. I use that separation as a useful model, not a requirement to create three layers everywhere. A small product might need reference and semantic tokens only. I add component tokens when a component has a genuine exception or needs an independently controlled styling contract.

My naming convention identifies the property, role and state in a predictable order. For example, `color.action.primary.background.hover` sits beside its default and disabled equivalents. I avoid names tied to a page, temporary campaign or visual judgement such as `nice.grey`. Before approving a name, I check whether its meaning would survive a new theme and a redesigned component.

Define token types, aliases and theme behaviour

I use the Design Tokens Community Group format as the reference for a portable token structure, then check what the actual tools support. Its format defines typed values and references between tokens. The community group's work should not be described as a formal web standards recommendation simply because the group is hosted by the standards organisation.

In a compatible file, `$type` identifies the value's kind and `$value` holds the value or an alias. I preserve aliases instead of replacing every semantic token with a copied raw value. If five roles share one reference token, that relationship needs to remain visible during review. Otherwise, a palette correction becomes five unrelated edits.

For themes, I keep the semantic contract stable and change its mappings. `color.text.primary` should still mean primary text in both light and dark themes. I document theme selection separately and test the resolver used by the pipeline. I don't assume that one exporter understands another tool's modes, collections or inheritance rules.

Build a one-way design tokens handoff pipeline

My preferred pipeline has a clear direction: proposed edit, reviewed source change, validation, generated outputs, then a versioned release. The build produces the formats each platform needs. For a web product, that might mean style variables and a typed token-name map. I generate the token reference from the same input so documentation cannot quietly retain old values.

The design library is another consumer of the approved source. I check whether its import path preserves aliases, modes and supported types before committing to automation. If importing requires a manual step, I assign an owner and record the imported release. A documented manual update is safer than a background sync that drops relationships without reporting them.

I don't rely on both sides changing simultaneously. Instead, the product and design library record which token release they use. A mismatch becomes an explicit update task. I also include a generated difference report in each proposal so reviewers can see changed values and mappings without reading every platform output.

Validate token changes before they reach components

I start automated checks with failures that are cheap to detect: missing references, circular aliases, invalid types and absent required theme mappings. I also check for name collisions after conversion. Two distinct source paths can produce the same platform identifier if the naming transform removes punctuation or normalises names carelessly.

Next, I verify the generation step. Running it twice against the same source should produce identical output. If generated files are committed, the build checks that regeneration leaves no unexplained differences. If outputs are published as a package, the release process builds them from the reviewed revision rather than a developer's local working copy.

Visual review comes after those checks, not instead of them. I inspect representative components across supported themes and interaction states. A valid colour token can still create unreadable text when paired with the wrong surface. I test actual foreground and background combinations, including hover and disabled treatments, rather than treating token validity as proof that the interface is accessible.

Version design tokens and deprecate names safely

I treat token names as a contract with consuming components. Removing or renaming a token can break that contract even when the screen is supposed to look identical. A value change is different: it may compile successfully but alter hundreds of screens. Both need review, with the expected compatibility and visual impact stated separately.

For a rename, I introduce the replacement, retain the old name as a temporary alias and document the migration. I agree the removal window with the teams consuming it. Two releases might be reasonable for one application; a shared package with slower consumers may need longer. The useful deadline is one consumers can actually meet.

I keep release notes specific: changed tokens, affected themes, expected visual differences and required action. Before release, I verify that the previous package remains available for rollback. For an independent client project, I'd name one design reviewer and one engineering reviewer, with explicit agreement on who publishes and who updates the library.

Measure token drift and skip unnecessary automation

I measure drift in three places: the token release used by the product, the release imported into the design library, and hard-coded values in components intended to use tokens. Those signals expose different problems. A library can be current while application code still contains copied colours from six months earlier.

I would also track the time from an approved token change to its adoption in both places, plus token-related build failures and visual regressions. These are proposed operating measures, not universal benchmarks. I establish a baseline first, then investigate delays. A week spent waiting for a library update is usually an ownership issue before it is a tooling issue.

I skip bidirectional editing until there is a defined conflict policy and a demonstrated need. I also avoid tokenising every isolated measurement just to increase coverage. My first implementation would cover shared colours, typography and spacing, prove one complete release cycle, and only then add more categories. The pipeline should earn its maintenance cost.

Questions people ask

Should design tokens live in Figma or in code?

I usually choose a version-controlled repository when tokens feed production code. A design-tool source can work if its exports are repeatable, reviewed and linked to releases.

What is the difference between primitive and semantic tokens?

A primitive token names a raw value, such as a palette colour. I use semantic tokens to describe intended use, such as primary text, without tying components to that colour.

Can I sync design tokens automatically?

I automate validation, generation and supported library imports. I still require review for changes in meaning or appearance, and I verify that imports preserve aliases and theme mappings.

Do I need a token management tool?

I don't require a dedicated tool for a small system. A versioned source file, generation script and clear review process can work until permissions or publishing needs justify more tooling.

Where I checked my thinking

• Design Tokens Community Group
• Design Tokens Community Group format specification, editor's draft
• Material Design: Design tokens overview