Versioning and distributing token updates safely

WHAT THIS TESTS: This checks that you treat a token library as a versioned API with consumers and that you understand the blast radius of breaking changes.

A GOOD ANSWER COVERS: Publish tokens as a versioned package, for example to a registry, and follow semantic versioning: patch for fixes, minor for additive new tokens, and major for removals, renames, or value changes that alter meaning. Consumers pin a version and upgrade on their own schedule, which prevents surprise breakage. For breaking changes, do not delete outright; first deprecate the old token, keep it as an alias to the new one for a transition window, mark it deprecated in metadata, and announce the timeline. Ship a clear changelog, a migration guide, and where possible a codemod or find-and-replace mapping. The main risks are silent visual regressions when a value changes, build failures when a token is removed, and inconsistent adoption across teams. Mitigations are deprecation windows, automated usage detection or lint rules, visual regression tests, and communication through release notes and team channels.

COMMON WRONG ANSWERS: Renaming or deleting a token in a minor or patch release. Force-pushing changes to consumers without versioning so everyone updates at once. Skipping deprecation aliases. Changing a value's meaning while keeping the name, causing silent design drift. No changelog or migration path.

LIKELY FOLLOW-UPS: How do you detect which consumers use a deprecated token. What belongs in a major versus minor bump for value-only changes. How do visual regression tests fit the release process.

ONE CONCRETE EXAMPLE: To rename color-accent to color-brand-primary, ship a minor release adding the new token aliased from the old, mark color-accent deprecated with a removal version, publish a migration guide, then remove it only in the next major release after the window closes.