Immutable semver releases for design-token packages with alias resolution, compatibility gates, and rollback-safe distribution so consumers never bind to unvalidated draft token sets across surfaces.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Publish design tokens as immutable semver packages in a single registry, expose only vetted aliases such as stable and previous-stable, and require compatibility gates before any alias moves. Consumers may pin an exact version or follow an alias deliberately; draft token sets never ship to production aliases.
Scope
- Version numbering, changelog requirements, alias maps, and publish immutability for token packages.
- Cross-surface distribution to web and native consumers that share a registry.
- Rollback of alias pointers within a bounded operator window after a bad release.
- Deprecation lifecycle for renamed or removed tokens.
Outside this block
- Authoring token semantics, color science, or component styling rules.
- Runtime theme switching mechanics (see the dark-mode theme contract block).
- General package registry administration unrelated to design tokens.
Contract
- A published token release at version
X.Y.Zis immutable; republishing the same version with different content is rejected. - Breaking token renames or removals require a major semver bump; minor and patch releases must remain backward compatible for all non-deprecated public aliases.
- Production aliases (
stable,previous-stable) reference only releases that passed the profile compatibility gates; draft or local builds cannot satisfy an alias. - Consumers that pin an exact version continue to resolve that version after alias repointing unless they explicitly upgrade.
- Deprecated tokens remain readable for the configured grace period and emit a build-time or CI-visible warning before hard failure.
- Rollback repoints
stabletoprevious-stable(or a named safe version) within the profile rollback window and records actor, reason, and affected digest. - Adoption metrics expose which surfaces consume which token version so cross-surface drift is observable within one reporting interval.
Implementation guidance
- Store tokens in a format your toolchain can diff (JSON, Style Dictionary, or CSS custom properties export) and attach a release manifest similar to
token-release.yaml. - Run visual or contrast diff gates on representative screens before alias promotion; block publish when required tokens are missing from the export.
- Treat alias updates as infrastructure changes: require two-person approval or automated canary on a staging consumer before repointing
stable. - Document supported version combinations when web and native release on different cadences.
Failure handling and safeguards
- If a publish succeeds but downstream gates fail afterward, leave aliases unchanged and mark the release as
withdrawnrather than deleting the immutable artifact. - If rollback is invoked outside the window, require an explicit break-glass ticket and retain both versions until consumers confirm migration.
- If a consumer requests a withdrawn version, return the artifact with a prominent deprecation header rather than silently substituting tokens.
- If registry replication lag causes mixed versions across regions, halt alias movement until all replicas serve the same digest.
Verification and operations
- Track alias repoint events, rollback count, deprecated-token references in CI, and per-surface version adoption ratio.
- Alert when any production surface remains on a version older than the minimum support window for longer than the profile threshold.
- Rehearse rollback quarterly on a staging alias to verify manifests and consumer pins behave as expected.
Adoption assumptions
- Names and numeric values in
example.yamlandtoken-release.yamlare an adoption profile, not universal defaults. - The adopting team owns registry credentials, visual diff tooling, and the definition of breaking change for its token schema.