Versioning and shipping design tokens via NPM

WHAT THIS TESTS This probes whether you understand that design tokens shipped as a package are a public API contract. Many teams depend on them, so changes must follow versioning rules and provide migration paths, not just overwrite values.

A GOOD ANSWER COVERS Use strict semantic versioning. Adding a token is a minor release, fixing a wrong value is a patch, and renaming or deleting a token is a major release. Generate platform outputs (CSS variables, JS objects, iOS, Android) from a single source of truth using a tool like Style Dictionary. For breaking changes, deprecate before deleting: keep the old token name as an alias that points to the new one, emit a build-time or lint warning, and remove it only in the next major. Ship a changelog, a migration guide, and where possible a codemod so consumers can run an automated find-and-replace.

COMMON WRONG ANSWERS Claiming any token change is safe under a minor bump. Renaming tokens in place with no alias. Hand-editing per-platform files instead of generating them, which causes drift. Forgetting that color value changes can be visually breaking even when the token name is stable.

LIKELY FOLLOW-UPS How do you let two major versions coexist during migration? How do you test that token output is valid across platforms? How do you communicate the change and track who is still on the old version?

ONE CONCRETE EXAMPLE You rename color-brand-primary to color-action-primary. In version 2.0.0 you publish both names, with the old one aliased and marked deprecated in the build log. You publish a codemod that rewrites references in consumer code, plus a migration doc. Three months later, version 3.0.0 removes the alias entirely. Teams that ran the codemod see zero breakage.