Token governance workflows in zeroheight
Learn

Token governance workflows in zeroheight

Author Avatar
Written by
Jun 23, 2026

Article 13 — Design token governance covers the process side of governance: ownership models, contribution workflows, deprecation, semantic versioning, and audits. This article covers the tooling side — specifically, what zeroheight adds to a governance workflow and how to configure it.

zeroheight functions as the governance layer between your token source and the teams consuming it. It's where adoption is measured, changes are communicated, and access is controlled. Used well, it reduces the manual overhead of keeping a token system healthy.

Measuring token adoption with analytics

A governance process is only as good as the information that drives it. Without visibility into how tokens are actually being used (which ones appear in designs, which ones don't, which ones have been replaced by hardcoded values) governance decisions are based on assumption rather than evidence.

zeroheight's analytics give you a view of how your styleguide is being used: which pages are visited, how often, and by whom. For token governance specifically, this surfaces a few useful signals:

Which token documentation pages are getting traffic. High-traffic token pages indicate either active use or active confusion, and both are worth investigating. A color token page with high traffic and frequent support questions suggests the documentation isn't answering the questions people actually have.

Which pages are rarely visited. Token documentation that nobody reads is a signal either that those tokens aren't being used, or that teams are finding the information they need elsewhere (which may mean the documentation and the actual usage are drifting apart).

Engagement patterns over time. A spike in visits to a token page after a release or rebrand indicates teams are actively checking the documentation, which is what good governance looks like. A sustained absence of traffic after a major token update may mean the update wasn't communicated effectively.

Analytics won't tell you directly which specific tokens are referenced in code. That requires tooling on the engineering side. But they give you a proxy for documentation health and can prompt the right investigations at audit time.

Tracking documented, used, and deprecated tokens

A key governance task is keeping three lists current: tokens that are documented, tokens that are in active use, and tokens that have been deprecated. In a well-run system these lists are closely aligned. In practice, they diverge, and the divergence is where technical debt accumulates.

zeroheight helps with the documented side of this picture. The Tokens Manager shows every token in your connected token sets, giving you a complete inventory of what's been synced from your source. Tokens that exist in the source but haven't been surfaced on any documentation page are visible in the Tokens Manager even if they're not yet part of the styleguide, making it easier to spot documentation gaps during an audit.

For deprecated tokens, the workflow in zeroheight mirrors the code-side deprecation practice from Article 13:

  1. Mark the token as deprecated in the source. In Figma, this might mean renaming it with a deprecated/ prefix or adding a description note. In code, it means the @deprecated JSDoc tag.
  2. Update the documentation page. Add a clear deprecation notice to the token's entry in the styleguide: what it's being replaced with, and when it will be removed.
  3. Sync the change. The updated token state propagates to zeroheight on the next sync.
  4. Remove after the migration window. Once consuming teams have migrated, remove the token from the source, sync, and update the documentation to reflect the removal.

This process keeps the Tokens Manager accurate and ensures teams who rely on styleguide documentation for token discovery aren't led to deprecated values without warning.

Token changelog setup

One of the most underused governance tools in any design system is the changelog. A changelog that records what changed, when, and why gives consuming teams the context they need to absorb updates confidently, and gives the system team an audit trail for decisions.

In zeroheight, a changelog can be as simple as a dedicated styleguide page updated on each token release. A minimal changelog entry for a token update includes the version, the tokens affected, what changed, and the rationale:

v2.3.0, April 2026
color/action/primary updated from #3B82F6 to #2563EB
Reason: brand refresh. Primary blue shifted to improve contrast against white surfaces.
Migration: replace all uses of color/action/primary. No alias changes required.

For teams using the automated PR workflow covered in Article 18, pull request descriptions are a natural home for this information — the PR is automatically created when a sync triggers, and the description can be populated with the diff of what changed. A governance habit of writing meaningful PR descriptions produces a changelog almost for free.

A few additional practices that make changelogs useful:

  • Version your token package before documenting. The changelog entry and the package version should correspond. A "v2.3.0" changelog entry is only meaningful if there's actually a v2.3.0 package that teams can point to.
  • Include migration guidance for breaking changes. A changelog that notes a token was renamed is only half the information consuming teams need. The other half is "here's the token that replaces it and here's how to find uses of the old one in your codebase."
  • Keep a separate changelog for major releases. Minor token updates can be batched in a running changelog page. Major releases (ones that involve token removals, renames, or significant value changes) warrant their own announcement page with more detail.

Access controls for contribution workflows

Not everyone who uses the styleguide should be able to edit it. And not everyone who can edit the styleguide should be able to change token documentation. zeroheight's permission model lets you configure access at the styleguide and page level.

For a token governance workflow, the useful permission levels are:

Admin: Full access to the styleguide and its settings, including the Tokens Manager and automation configuration. Reserve this for the design system team and anyone responsible for the token pipeline.

Editor: Can create and edit pages, embed token documentation, and update content. Appropriate for brand designers and design system contributors who are responsible for keeping documentation current.

Commenter: Can read pages and leave comments, but can't edit. Useful for reviewers in a contribution workflow. A product designer proposing a new token can be given commenter access to the governance section to participate in the review discussion.

Viewer: Read-only access. The default for most styleguide consumers: developers, stakeholders, partner teams.

For multi-brand setups, separate styleguide permissions per brand (covered in Article 19) let you give each brand team editorial control over their own documentation without cross-brand access.

A useful governance practice: audit styleguide permissions quarterly alongside the token audit. Teams change, people leave, and permission lists drift. An editor who left the organization six months ago still having active access is a risk worth catching before it becomes a problem.

Integrating zeroheight into the token release pipeline

The final governance function is pipeline integration: making zeroheight a node in the release process rather than a documentation afterthought that gets updated manually, if at all.

The automation setup from Article 18 handles the inbound side: when a designer syncs from Figma, zeroheight creates a pull request in the connected repository. For the outbound side — ensuring documentation is updated when a token package is released — the pattern is to treat the zeroheight sync as part of the release checklist.

A token release checklist that includes zeroheight:

  1. Update token values in Figma
  2. Sync to zeroheight via plugin
  3. Review the generated pull request; add changelog notes to the PR description
  4. Merge the PR. CI/CD runs the transformation pipeline and publishes updated packages.
  5. Update the changelog page in the styleguide
  6. Communicate the release to consuming teams

Steps 2 and 5 are the zeroheight-specific steps. Everything else is standard token release process. Adding them to an existing checklist rather than treating them as separate documentation overhead keeps the two in sync.

For teams using zeroheight's GitHub markdown sync, the changelog can be maintained as a markdown file in the repository and synced to the styleguide automatically, removing step 5 as a manual action entirely.

Closing the loop

This article closes the guide. The twenty articles in this series have covered design tokens from first principles through to the governance and documentation workflows that keep a token system healthy at scale.

The most important thread running through all of it: a token system that isn't used isn't a system. Governance, documentation, and pipeline integration aren't overhead on top of the "real" work of building tokens. They're what turns a token structure into a system that teams actually rely on.

For everything covered here in the context of zeroheight's specific features, the zeroheight Help Center has detailed product documentation. For the token governance principles that sit behind the tooling, Article 13 — Design token governance: maintaining tokens at scale covers them in full.

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