Two years ago I shipped a token rename on a Friday afternoon. color-brand-primary became color-surface-brand in our system, a five-minute find-and-replace in our own repo. Monday morning, three product teams had failing builds, and not one of them had seen it coming, because there wasn't a changelog entry to see.
TL;DR: Design token adoption hit 84 percent of teams in 2026, up from 56 percent a year earlier (zeroheight - Design Systems Report 2026, 2026), but only 40 percent run any real token pipeline. Most still hand-sync tokens between design, docs, and code, which is exactly where breaking changes slip through unannounced.
How Do You Decide What Counts as a Breaking Change?
Start with the consumer's code, not your own diff. If a product team upgrades and their existing implementation, unchanged, now renders or behaves differently, that's major. Renaming a token, removing a component export, flipping a default, or changing what a prop does all qualify, even when the change looks trivial in your own PR. Adding a new token, a new variant, or an optional prop with a backward-compatible default is minor. Bug fixes that don't touch the API are patch.
Visual changes deserve their own scrutiny here. A spacing token that shifts by 2px feels like a patch to the person who made it and a layout bug to the six teams whose padding just moved. I'd argue visual drift inside a shared token is major far more often than teams admit, because it fails silently instead of throwing a build error.
| Bump | Test | Example |
|---|---|---|
| Major | Consumer's unchanged code now behaves or renders differently | Renaming a token, removing a component export, flipping a default |
| Minor | Adds something new without touching what exists | A new button variant, an optional prop with a safe default |
| Patch | Fixes a bug without changing the API surface | Bug fix, no API change |
Should Tokens and Components Version Separately?
Yes, once your system serves more than one or two consuming teams. A design system isn't really one package. It's a graph: primitives, semantic tokens, components, and framework adapters, all moving at different speeds. Forcing them onto a single version number means an unrelated token tweak drags a major bump through every component, and consumers stop trusting your major releases because half of them weren't really breaking anything they used.
Changesets handles this well in a monorepo: each package gets its own version, and a single pull request can declare "patch for tokens, major for button" in one changeset file. Independent versioning means the changelog for @yourds/tokens only lists what actually changed in tokens, which is what your token-only consumers should read. Nobody wants to scroll through forty component entries to find the one line that affects them.
What Belongs in a Design System Changelog?
Four things, in every entry: what changed, why, who's affected, and what to do next. "Removed Button size='xl'" is a fact nobody can act on. "Removed Button size='xl', use size='large'; grep for size= props on Button" is a fact someone can paste into a terminal. Group entries by Major, Minor, and Patch under each dated version, and resist the urge to write clever release notes. Isn't the whole point of a changelog to save someone a debugging session at the worst possible hour?
Communicating a breaking change well is its own skill, not that different from the discipline behind a clean designer to developer handoff: name the intent, not just the diff, and don't make the reader reconstruct your reasoning from a Git log.
How Long Should a Deprecation Window Last?
Long enough for your slowest team to actually schedule the work, which in practice means at least one full quarter for anything widely used. My rule: a deprecated piece stays functional, with a warning, for two minor releases minimum before a major release removes it. Announce the deprecation the day you decide it, not the day you ship the removal. Give people a migration path in the same message, a codemod if you can manage one, a find-and-replace pattern if you can't.
I've watched a team announce and remove a component in the same release, and it produced exactly the fire drill you'd expect. A short deprecation window doesn't save you time. It just moves the pain onto someone else's sprint, usually the team least equipped to absorb it that week.
Which Tools Actually Automate This So You Don't Forget?
Changesets and semantic-release both solve the same core problem: humans forget to bump versions and write changelogs consistently, so let a tool enforce it from the commit or the PR. Changesets asks contributors to describe intent in a small file alongside their PR; a bot then computes the version bump and drafts the changelog entry from that description. Semantic-release goes further and infers the bump from commit message conventions, no manual file required, which works well if your team already writes disciplined conventional commits.
Neither tool fixes a team that doesn't think about breaking changes in the first place. The zeroheight data on token pipelines backs this up: with only 40 percent of teams running any pipeline at all, most breaking changes are still caught by a human noticing a broken build, not by tooling. Automate the mechanical part, version numbers and changelog formatting, but the judgment call of what's breaking still belongs to a person who understands the consumers.
Governance isn't a document you write once. It's the muscle of treating every token or component change as something a stranger on another team will read about before their build breaks, not after.
