A design token package for a veterinary booking system shipped 25% wider spacing values as a minor release, and the reception kiosk's appointment grid now overflows. Was it breaking, and how should token releases be versioned?
answer
- what the package promises consumers
- names, types, units, output files
- letter versus effect of a change
- fix forward with a new minor
- big restyles: major or opt-in
basics
~20 sNo name broke, but a sweeping value change that predictably breaks consumer layouts is breaking in effect. Fix forward with a minor that restores the old values, then reship the change as a major or as opt-in tokens.
solid answer
~40 sBy the letter of semantic versioning, nothing in the token package's API changed: every name, type and output file still exists. But a token package also promises the **values consumers built layouts against**, and widening every spacing step by a quarter predictably breaks dense screens like the kiosk's appointment grid — semantic versioning exists to convey meaning, so that change deserved a **major** or an **opt-in** path. To recover, follow the semantic versioning FAQ: never modify the published release; ship a **new minor that restores the old values**, note the offending version, then reship the scale as a major or as new tokens teams adopt deliberately. Going forward, classify token changes explicitly: additions and deprecations are minor, fixes to wrong values are patch, and renames without aliases, removals, type or unit changes are major.
go deeper
Recall the three semantic versioning bumps and which token changes map to each: additions and deprecations are minor, removals and renames without aliases are major.
Explain what a token package's public API includes beyond names — types, units, output files and value meaning — and why a type or unit change is breaking.
Diagnose a compatible-by-the-letter release that broke consumers, fix forward without editing the published version, and reship the change as a major or an opt-in path.
Decide where the team draws the line between a refinement and a restyle, write that classification down, and weigh opt-in migrations against the cost of frequent majors.
## What a token package promises Semantic versioning classifies releases by their effect on a **public API**: MAJOR for backward incompatible changes, MINOR for backward compatible additions — and whenever something is marked deprecated — and PATCH for backward compatible bug fixes. For a design token package the public API is wider than the list of names: - **Token names**, in every platform's output form. - **Token types and units** — a spacing token that was a dimension on every platform must stay one. - **The output files and entry points** consumers import on each platform. - **The documented meaning and rough magnitude of values** — softer than the rest, but consumers lay out screens, pick text sizes and check contrast against them. ## Classifying token changes | Change | Usual bump | Reason | |---|---|---| | Add a token | MINOR | New backward compatible functionality | | Deprecate a token, keeping it as an alias | MINOR | Semantic versioning requires a minor bump for a deprecation | | Correct a value that did not match the approved spec | PATCH | A bug fix: the name always promised the right value | | Small deliberate refinement within the token's meaning | MINOR, by most teams' convention | Compatible, but worth a release note | | Sweeping change consumers laid out against | MAJOR, or ship as opt-in | Predictable breakage of consumer screens | | Rename without an alias, or remove a token | MAJOR | References dangle | | Change a token's type, unit or output location | MAJOR | Existing references resolve to the wrong kind of value, or not at all | The fourth row is a convention, not a rule the standard dictates; what matters is that the team writes its classification down and applies it consistently. ## Was the spacing change breaking? By the letter, no: the kiosk still compiled and every reference still resolved. In effect, yes. Widening every spacing step at once is not a refinement of one decision — it changes the scale that every dense layout was fitted to. The appointment grid on a small kiosk screen, the week view in the staff dashboard, the pet profile header on a small phone: all were sized with the old steps in mind. The semantic versioning FAQ's own guidance fits: it is about conveying meaning by how the version number changes, and when a change matters to users, the version number should tell them. A useful test before any value release: **would a consumer need to look at their screens again after upgrading?** If the honest answer is yes for many consumers, the release is breaking in practice. ## How to recover 1. **Do not modify or silently replace the published release.** The FAQ is explicit that versioned releases are not edited. 2. **Ship a new minor that restores the old values**, which is the FAQ's remedy for an accidentally incompatible minor release. 3. **Document the offending version** so teams that already upgraded know why their grid overflowed and what to take next. 4. **Reship the new spacing deliberately**, either as a major with a migration note, or as new tokens (or a new scale) that teams adopt when they have checked their screens, before the old ones are deprecated. ## Preventing the next one - Add a release-readiness question for value changes: which tokens moved, by how much, and which reference screens changed. - Compare a small set of dense reference screens on each platform before publishing, not just the documentation examples. - Flag layout-critical tokens — spacing, type size, line height — so their changes get design review, not only code review. - Keep value changes and renames in separate releases so each one's effect is readable. The org-wide release cadence and who approves a major belong to governance; the classification itself is part of owning the token package.
- A token's value was a typo that never matched the approved design. Is fixing it a patch even though screens will change?Usually yes: the name always promised the approved value, so correcting it is a bug fix, and semantic versioning puts backward compatible bug fixes in a patch. Still judge the blast radius — if many consumers had tuned layouts around the wrong value, the FAQ's advice applies: when a change matters to users, let the version number and the release note tell them.
- Why are type or unit changes in a token's output treated as breaking even when the name stays?Consumers use the output as a value of a particular kind. If a spacing token that was a dimension becomes a unitless number, or a platform output switches units, references still resolve but now produce wrong sizes or invalid values. The token format itself treats a referenced value incompatible with the expected type as an error, which shows how fundamental the type is to the contract.
- What does shipping a sweeping value change as opt-in look like?Publish the new values under new names or as a new scale alongside the old one in a minor release. Teams switch deliberately after checking their screens; once adoption is high, the old names are deprecated with aliases, and a later major removes them. It turns one risky restyle into many small, reviewed ones.
saying these in an interview costs you the question
- Only name changes can ever justify a major release of a token package.
- Fix a bad release by republishing the same version number with corrected values.
- Every value change should be a major release, to be safe.
- Changing a token's unit is compatible because the name is unchanged.
- Consumers should read the token diff themselves; version numbers need not signal restyles.