How do you version design tokens shared by an app and a marketing site on different release cadences?
Tokens are published as an npm package. The product app upgrades roughly monthly with a full visual QA pass. The marketing site upgrades whenever someone runs npm update, which is to say continuously and without QA.
Result: a token rename that was a clean minor for us was a broken hero section for them, and I found out from a screenshot in a group chat.
Options I can see:
- Strict semver with deprecation aliases. Old name keeps working for two minors, build warns. Safe, but the alias layer accumulates and nobody ever deletes it.
- Two packages —
tokens-coreandtokens-brand— so marketing only tracks the half that changes slowly. More release surface for a two-person team. - Pin marketing to a tag and upgrade deliberately. Works until someone needs a fix and takes eight months of drift with it.
For teams who have run this longer than a year: which of these survived, and what did the alias graveyard actually cost you? I suspect the answer is "less than the broken hero section" but I would like evidence.
Written by
Lena Fischer
Front-end engineer on a design systems team. I maintain the token pipeline and the component library four product teams build on. Strong opinions about focus rings, colour contrast, and the fact that most "theming" problems are really naming problems. CSS is a real language and I will keep saying so.
3 Comments
Sign in to join the discussion
'Delete on a calendar, not on a feeling' is going straight into the RFC.
Third option with a twist: pin marketing to a tag, but have CI open the upgrade PR every week automatically. It stays deliberate because a human reviews it, and the drift never reaches eight months because the PR is always sitting there being annoying.
We ran the deprecation-alias version on a database schema for two years, which is the same problem with worse ergonomics. The alias graveyard cost maybe a day a year of confusion. The broken hero section cost you an afternoon and your credibility with marketing, which is the more expensive currency. Keep the aliases, put an expiry date in the deprecation warning, and delete on a calendar rather than on a feeling.