Versioning Design Tokens Like Code With Git and CI

Design tokens have carried the promise of a single source of truth for color, type, and spacing for years, but until recently that promise ran into a hard limit: no shared format existed to make tokens portable across tools. Teams had to build their own JSON schemas, write custom glue code for every integration, and re-solve the same translation problem each time a new platform joined the stack. The Design Tokens Community Group changed that on October 28, 2025, with the first stable version of its specification, known as 2025.10. The spec standardizes theming and multi-brand support, adds modern color spaces such as Display P3 and Oklch alongside the full CSS Color Module 4 range, and formalizes token relationships like inheritance and aliasing, so one token file can generate platform-specific code for iOS, Android, web, and Flutter. The organizations behind its development read like a cross-section of the industry that would need to agree for this to work at all: Adobe, Amazon, Google, Baidu, Sony, Microsoft, Meta, Sketch, Salesforce, Shopify, Figma, Framer, Cisco, Intuit, the New York Times, GM, and Disney, among others, with reference implementations in Tokens Studio, Style Dictionary, and Terrazzo backing its production readiness. More than ten tools and open-source projects, including Penpot, Sketch, Framer, Knapsack, Supernova, and zeroheight, already support it or are building toward it. What this unlocks is not a feature so much as a precondition: a token file exported from a design tool can now move into Style Dictionary, come out the other side as Tailwind config, and get read by a CI pipeline, with no custom glue code bridging the gaps. Every argument in this piece, about Git as source of truth, about three-tier token architecture, about CI gates and semantic versioning, depends on that precondition holding.

Git as the Source of Truth for Tokens

The most consequential decision a design system team makes is where the authoritative copy lives, not which tool renders the tokens. Keeping tokens as source files in a Git repository, rather than inside a design tool, is what makes versioning, auditability, and automated distribution possible. Design tools, however capable, are built for collaborative editing. They have no native concept of a changelog, a rollback, a branch, a pull request, or a review gate, because that was never the problem they were built to solve. A color value changed inside a design tool is a fact that exists in one place, at one moment, with no record of what it replaced or why.

The same change, committed to a token file in Git, becomes something else entirely: a diff. Because the stable W3C format structures token data with $value and $type keys in JSON, a change to a single color appears in a pull request as a one-line edit, legible to any team member who reviews it. That is the same property that makes a one-character fix to a line of application code reviewable, and it applies to brand decisions with the same force it applies to software.

The token file is the actual handoff boundary between design and engineering. Designers sync their work from tooling into the repository, and every downstream consumer, web, iOS, Android, Flutter, reads from that file. Tokens Studio syncs with GitHub, GitLab, Azure DevOps, and Bitbucket for exactly this reason: the Git repository becomes the stable intermediary between design-side editing and code-side consumption, the place both sides agree to trust. Once that boundary exists, every change that matters to the brand leaves a trail: who changed what, when, and why, recorded in commit messages and review comments.

How token files should be structured before automation

A flat list of token values does not scale past a handful of brands or platforms, and the pipeline described in the next section cannot automate safely against an unstructured file. The structural answer most mature design systems converge on is a three-tier architecture: option tokens, decision tokens, and component tokens, each layer answering a different question about a given value.

Option tokens are the raw palette: every color, every spacing step, every corner radius the system permits. They should generally stay private to the system, so consuming teams don't reference them directly. If you keep them private, file size stays down, and because nothing outside the system points at them directly, the values underneath can shift without breaking anyone's code. Decision tokens sit above that layer and alias into option tokens using the spec's alias syntax, encoding what a value means: a token named something like "color/surface/primary" references "color/palette/indigo-600", keeping the hex value itself out of the reference. This is the layer carrying brand identity, and it is the layer a rebrand actually touches. Component tokens are the top layer, referencing decision tokens and allowing component-level overrides without reaching back into the primitive layer. If you skip this top tier, every component-specific adjustment forces a change at the decision layer, and that then ripples into every other component relying on that same decision token. That is what makes multi-brand theming tractable at scale: a company running dozens of brands across many product teams needs the override to stay local to the component, not global to the system.

The Province of British Columbia's design token package shows this working in a public, production setting. At version 4.0.0 as of March 11, 2026, it publishes tokens in CSS, SCSS, and JavaScript, in both ESM and CommonJS formats, with TypeScript declarations included for both JavaScript builds, and it ships prefixed and non-prefixed variants so the tokens don't collide with whatever styles already exist in a consuming project.

What the CI Pipeline Does at Each Stage

None of the structure described above holds on its own. A CI/CD pipeline for tokens is the mechanism that enforces the guarantees the file structure promises, and removing any single stage collapses a specific one of those guarantees.

The pipeline starts with validation. A linting step checks that token files conform to the stable W3C format, correct $type values, valid aliases, no circular references, before any transformation runs against them. Skip this gate and a malformed token doesn't get caught at the source. It ships straight through to whatever platform consumes it next.

From there the pipeline builds and transforms. Style Dictionary, one of several reference implementations alongside Tokens Studio and Terrazzo, reads the source JSON and compiles it into platform-specific outputs: CSS custom properties for web, XML for Android, Swift constants for iOS, all generated from the same source file. Without this step, every platform ends up maintaining its own copy of the same values by hand, and drift between them starts immediately, not eventually.

Testing follows the build. Automated contrast-ratio checks, snapshot comparisons against the previous build, and coverage tests confirm that every decision token resolves to a valid option token, so they catch regressions before they reach a shipped product, not after a user reports them.

Publishing is where the compiled artifacts get released, to npm or to a private registry, under semantic versioning driven by Conventional Commits: patch bumps for non-visual fixes, minor bumps for additive tokens, major bumps for anything breaking. It is the same contract software libraries have run on for decades, now applied to decisions about brand. The B.C. government package makes the stakes of that major-version boundary explicit in its own documentation, instructing consuming developers to install major updates manually and review the release notes first, the same discipline any team already applies when upgrading a dependency it doesn't fully control.

The last stage is notification. A release note, whether posted to Slack, written into GitHub release notes, or logged in a changelog, tells every consuming team what changed and at what version, replacing the informal message that someone updated the colors with a structured, timestamped record anyone can check later.

Rockwell Automation ran this pipeline in its Flourish design system to deliver fast token updates across its Angular and Web Components libraries, and it shows how ordinary this kind of automation can make that speed. GitLab's Pajamas design system shows the governance side of the same idea: a Core layer maintained centrally by the Design System team, and an Extended layer where product teams own and build their own contributions on top of core patterns. That separation is what lets many teams contribute to a shared system without any one of them breaking the standard everyone else depends on.

Semantic versioning as the contract between brand decisions and consuming systems

Semantic versioning is the mechanism that makes a brand change safe to propagate automatically across every platform that depends on it. Applying semver to a token package reframes every brand decision as a typed change with a known blast radius: additive changes get a minor bump, safe fixes get a patch, breaking changes get a major bump. That classification decides whether a consuming system can update on its own or needs a human to hold the change for review.

A color rename and a color value tweak look the same to any automated system reading the package, but one breaks every consumer still referencing the old token name, and the other breaks nothing. Semantic versioning forces that distinction into the release process itself, so it doesn't just depend on whoever happens to notice. Conventional Commits, a structured commit message format using prefixes like feat:, fix:, and BREAKING CHANGE:, automates the version-bump decision through tools like semantic-release, taking the judgment call out of human hands under deadline pressure, which is exactly when that judgment tends to go wrong.

The changelog that semantic-release generates becomes the audit trail for brand decisions themselves: every token change carries a commit, a version number, a date, and a human-readable description, the same artifact a legal or compliance team would ask for if a brand standard were ever challenged. The B.C. token package makes this contract explicit in its own documentation: it tells developers to install major updates manually and review release notes first. That instruction only works because the versioning signal it relies on is reliable and machine-readable, not because anyone is trusting goodwill.

How AI Agents Consume Versioned Tokens and the Version Contract

AI coding tools such as Cursor, Claude Code, and GitHub Copilot generate interface code from whatever context sits in front of them at that moment. Without a structured, versioned token source feeding that context, they default to values that look plausible but aren't actually correct for the brand, and every new session starts over with no memory of the decisions the product was built on. A human developer who has read the design system docs carries that context from one task to the next. An agent without a token source to read from does not.

The fix is to make the token file itself the agent's brand context: you can point it at the token package through a reference file like CLAUDE.md, or expose the current token set directly through an MCP server. Either approach gives an AI-assisted coding session the same grounding a human developer gets from reading the documentation, with the agent getting it fresh every time regardless of what it happened to retain. Versioning is what makes this dependable at scale: when the token package moves to a new version, every agent reading from it inherits the updated values automatically, so one update to the source propagates everywhere instead of requiring someone to manually revise prompts across every tool and workflow in use.

Tokens Studio positions its platform explicitly as a CI/CD-integrated output layer, and tokens flow directly from it into pipelines for web, iOS, and Android. The same pipeline that serves human developers also serves agent workflows once the token package is the shared source both sides read from. The Model Context Protocol is becoming the interface for this kind of connection, and it enables structured, two-way links between data sources and AI tools. Figma's native MCP server integration, announced at Schema 2025, pulls design system context, component names, spacing values, color palettes, usage guidelines, directly into developer agents working in VS Code with GitHub Copilot or Cursor, with no manual reinterpretation required at each handoff.

Bloom's Brand Skill model follows the same pattern to its logical endpoint: a versioned, retrievable representation of brand context, covering aesthetics, voice, references, and assets, accessible through an API or MCP connection, so any connected agent or product pulls the current version directly rather than depending on someone to paste guidelines into a prompt by hand. It is one realization of a principle this entire pipeline has been building toward: brand context that updates once and reaches every consumer, human or automated, from that single update.

What a Team Needs for the Pipeline's Guarantees

None of what this pipeline promises arrives automatically just because a team adopts the tooling. The guarantees hold only when three things are true at once: the source files are structured correctly, the consuming teams have actually agreed to the version contract, and the CI gates are enforced. A gap anywhere in that chain reverts the system to the same drift and inconsistency the pipeline exists to eliminate.

Token file discipline comes first. Tokens need to follow the stable W3C format, with proper $value and $type keys and correctly structured aliases, so a pipeline can validate or transform them with confidence. If a team is migrating off an ad-hoc JSON schema built before the spec existed, it needs an explicit migration step, because the pipeline won't sort the old structure out on its own.

Consuming-team buy-in comes second, and it is easy to undercut by accident. If product teams can still import tokens straight from the design tool instead of from the versioned package, the version contract gets bypassed entirely, no matter how well the pipeline behind it is built. The governance model only holds if the published package is the one sanctioned way to bring tokens into a project. Tokens Studio's own split between its Figma plugin, built for managing and applying tokens inside Figma, and its Studio platform, which handles branching, versioning, and CI/CD delivery, illustrates where teams tend to stop short: many start with the plugin and mistake it for the full infrastructure, when the governance and distribution the pipeline depends on live in the platform layer.

The three-tier architecture has a cost that earns its keep only in certain conditions. It earns its cost when you run a large-scale, multi-platform system, or one that changes often enough that manual coordination becomes its own source of risk. A small team running one platform with a design that rarely changes may find the setup costs more than the structure gives back. The pipeline scales the value of structure, and structure has a cost to build before it pays that value out.

For the teams where it fits, the payoff is concrete: same-day token releases, brand changes that reach every platform without anyone coordinating the rollout by hand, AI agents that inherit updated brand context the moment the source updates, and a changelog that doubles as the compliance record a legal or audit team would otherwise have to reconstruct from memory. The infrastructure takes on coordination work that used to fall to people, one pull request, one version bump, one release note at a time.