Design token governance: maintaining tokens at scale
Learn

Design token governance: maintaining tokens at scale

Author Avatar
Written by
Jun 22, 2026

A design token system without governance is a design token system in slow decay.

It starts small: a one-off color added directly to a component because the right semantic token didn't exist. A spacing value duplicated under a slightly different name. A deprecated token that nobody removed because it was easier to leave it. Over time these accumulate: redundant tokens, inconsistent naming, values that exist in the system but aren't used anywhere, values used everywhere but not in the system.

Governance is the set of processes that prevents this. It defines who can change the token system, how changes get proposed and approved, when tokens are retired, and how the health of the system gets measured. None of it is glamorous, but all of it is what separates a token system that holds its value over years from one that becomes technical debt.

This article covers the practical governance structures that work for token systems at different scales: ownership models, contribution processes, deprecation workflows, semantic versioning, and the quarterly audit.

Governance is two-fold

Before getting into ownership models and processes, it's worth naming something that often gets missed: token system governance has two distinct dimensions.

The first is governance around the tokens themselves: how new tokens are proposed, reviewed, named, and retired. This is what most teams think of when they hear "token governance."

The second is governance around how the team operates: how decisions get made, who has authority over what, how disagreements get resolved, and how often the system gets reviewed. Both matter. A well-defined contribution process breaks down quickly if there's no shared understanding of who has final say.

The sections below address both dimensions.

Ownership models

The first governance question is accountability: who owns the token system? The answer varies by organization, but three models appear consistently in mature design systems.

Centralized ownership

A single team (usually the design system team) owns the token system end to end. They define the naming conventions, approve all additions and changes, and are responsible for the health of the system.

This model produces the most consistent output. Decisions go through people who understand the full system, so naming stays coherent and the alias layer stays clean. The trade-off is a bottleneck: every token request routes through one team, which creates latency for consuming teams and workload for the system owners.

Centralized ownership works well when the token system is relatively small and the design system team has the capacity to handle requests. It tends to break down as the number of consuming teams grows.

Federated ownership

Consuming teams can contribute to the token system, with the design system team acting as reviewers rather than sole authors. A product team can propose a new token, open a PR, and have it reviewed and merged by the token system owners, much like open-source contribution models.

This distributes the authoring work and reduces the bottleneck, but it requires more process: contribution guidelines, naming conventions that are explicit enough to be followed without direct oversight, and a review process that's lightweight enough that teams will actually use it.

Federated ownership works well for larger organizations with multiple product teams and a mature enough token system that the conventions are well documented.

Embedded ownership

A specific person within each team (a design technologist, a lead designer, or a senior engineer) is designated as the token steward for that team. Stewards can make token decisions within their domain and are responsible for keeping their team's usage consistent with the broader system. The design system team sets global conventions and arbitrates cross-team decisions.

This is the most scalable model for large organizations, but it requires investment in documentation and alignment: stewards need to know the system well enough to make good local decisions, and there needs to be a forum for cross-team coordination when decisions affect the shared layer.

Contribution process

Regardless of ownership model, every token system needs a defined process for how new tokens get added and how existing ones get changed. Without it, tokens accumulate through informal decisions that nobody else knows about.

A workable contribution process has four stages:

1. Request and rationale. Before a new token is created, the requester documents why the existing system can't cover the need. This is the most important step. Most token requests turn out to be alias token gaps rather than genuine missing tokens. A form or PR template that asks "what existing token did you consider first, and why doesn't it work?" surfaces this quickly.

2. Naming proposal. The requester proposes a name following the system's naming conventions, with the role-based structure and modifier pattern from the existing vocabulary. The review step should confirm the name doesn't duplicate an existing token and would remain accurate if the underlying value changed. As design educator Dan Mall has put it: "It doesn't matter what you agree on, it just matters that you agree." The goal isn't a perfect name. It's a consistent one that the whole team can predict and trust.

3. Review and approval. The system owners (or token stewards, in a federated model) review the proposal. For global and alias tokens, this is typically a design and engineering review. For component tokens, the review can often be lighter: a check that the token is genuinely component-specific and not a re-implementation of an existing alias.

4. Documentation. New tokens don't ship without documentation. The minimum: what the token is for, when to use it, and what it resolves to in each active mode. Undocumented tokens are effectively invisible. They exist in the system but consuming teams can't discover or trust them.

The whole process should be fast enough that teams don't route around it. If requesting a token takes two weeks, developers will hardcode values instead.

Token deprecation

Tokens have lifecycles. Values change, component structures evolve, naming conventions improve, and over time, tokens that made sense when they were created become obsolete or incorrect. Deprecation is the process of retiring those tokens without breaking the teams that depend on them.

A robust deprecation workflow has three phases:

Phase 1: Mark as deprecated

Before removing a token, mark it as deprecated in the system. This signals to consuming teams that the token will be removed in a future version and gives them time to migrate. In code, the @deprecated JSDoc tag is the standard mechanism:

js

/**
 * @deprecated Use `color-action-primary` instead. Will be removed in v3.0.0.
 */
export const colorBrandBlue = Tokens.color.brand.blue;

This produces a visual warning in most editors (a strikethrough or highlighted reference) wherever the deprecated token is used. Developers encounter the migration prompt naturally, without needing to be told separately.

In documentation, deprecated tokens should be clearly labeled with the replacement token and the planned removal version.

Phase 2: Migration window

Give consuming teams a defined window to migrate off the deprecated token before it's removed. The length depends on how widely the token is used and how disruptive the migration is. For a token used in a handful of components, a patch cycle might be sufficient. For a token referenced across dozens of teams and codebases, a minor version window is more appropriate.

During this window, communicate the deprecation through whatever channels consuming teams actually read: changelog entries, design system office hours, Slack announcements. Don't assume that marking the token as deprecated in code is enough.

Phase 3: Removal

Once the migration window closes, the token is removed in a major version release. This is a breaking change by definition. Any consumer that hasn't migrated will see an error or a missing value. Semantic versioning makes this predictable (see below), and a clear changelog entry ensures teams know what changed and why.

Semantic versioning for token libraries

Token libraries distributed as packages should follow semantic versioning. The rules map naturally onto token changes:

Patch release (1.0.x): Bug fixes that don't affect consuming code. A value corrected by a few pixels, a typo in a token name fixed, a documentation update. Consuming teams can absorb patch releases automatically.

Minor release (1.x.0): New tokens added to the system. Consuming teams get new capabilities without any breaking changes. Additive changes only: existing tokens are unchanged, no tokens are removed.

Major release (x.0.0): Breaking changes. This includes: removing a token, renaming a token, or changing a token's value in a way that affects visual output across consuming products. Major releases require active migration from consuming teams.

The most important discipline here is being honest about what constitutes a breaking change. A color shift that "only affects one component" is a breaking change if consuming teams rely on that value being stable. Major releases should be infrequent and deliberate. A system that releases major versions every other month creates constant migration overhead for consuming teams and erodes trust in the system's stability.

A changelog entry for every release (not just major ones) is what makes the versioning meaningful. Without it, consuming teams can't evaluate whether a minor update is safe to absorb.

Token audits: the quarterly health check

A token audit is a systematic review of the token system's health, an opportunity to catch drift, redundancy, and decay before it compounds. Running one quarterly is a reasonable cadence for most systems; for very active systems, monthly may make more sense.

Before running a formal audit, it's worth checking for early warning signs that the system is drifting into debt. The early signs fall into two categories. On the technical side, watch for developers hardcoding values instead of using tokens, simple changes requiring updates across multiple unrelated files, or a growing number of tokens that nobody can explain. On the team side, watch for frustration whenever someone mentions the token process, workarounds quietly becoming the de facto approach, or reluctance to make changes because nobody knows what might break. If changing a single brand color requires a spreadsheet to track the downstream impact, the system has already crossed the line.

A useful audit covers four questions:

Are there duplicate or near-duplicate tokens? Tokens that resolve to the same or nearly the same value, with different names, are a signal of either gaps in the contribution process or undocumented intent. Each duplicate is a decision: consolidate them, document why they differ, or remove one.

Are there orphaned tokens? Tokens that exist in the system but aren't referenced by any component or consuming codebase are candidates for deprecation. They add documentation weight without delivering value, and over time they accumulate into a long tail of mystery values that nobody wants to touch.

Are the naming conventions holding? As systems grow and new contributors join, naming discipline tends to erode. An audit is a chance to catch tokens that don't follow conventions (appearance-based names that should be role-based, inconsistent modifier naming, tokens at the wrong tier) before they become the pattern that newer tokens follow.

Are deprecated tokens making progress toward removal? A deprecated token that's been in the system for three quarters without migration progress is a signal that either the migration is harder than anticipated or consuming teams don't know about it. Both are worth investigating.

The output of an audit should be a prioritized backlog of improvements, with owners and timelines. A document nobody acts on doesn't improve the system.

Governance and tooling

Good governance process reduces reliance on individuals remembering the rules. The more you can encode governance into tooling (naming linters, contrast validators, automated deprecation warnings, usage analytics) the more consistently it gets applied.

Token documentation platforms can surface which tokens are documented, which are in use, and which have been deprecated, giving system owners a live view of system health rather than a snapshot they have to reconstruct manually. Keeping documentation in sync with the token source, rather than maintained separately, removes one of the most common points of drift.

For how these workflows look specifically in zeroheight — analytics, token changelogs, access controls, and pipeline integration — Article 20 — Token governance workflows in zeroheight covers the product-specific setup.

For a deeper look at how token systems accumulate technical debt, and the patterns that signal a system is tipping from helpful to harmful, When design tokens become technical debt covers the warning signs and recovery path in detail.

For the organizational side of governance (how to structure the team, set expectations with stakeholders, and iterate on the governance model itself), Governance is a design system's friend covers those patterns in depth, including a useful framework from Lisa Welchman's work on digital governance.

What comes next

Section 4 covers the technical implementation of the token pipeline. Section 5 moves to Figma, the design tool side of the token system.

Article 14 — Setting up design tokens in Figma: variables, collections and modes is the entry point to that section, covering how Figma's variable system maps to the token hierarchy you've built in the articles so far.

Author Avatar
Try zeroheight
The design systems platform that keeps teams and agents in sync
Start for free
Share this post