Style Dictionary v5 shipped. Three things quietly broke your tokens
By The WAALEE Team · · 5 min read
Style Dictionary v5 is out, and if you maintain a token pipeline that feeds Claude, Lovable, v0, Cursor, or Bolt, it's worth a slower look than a changelog skim. The headline is that it aligns with DTCG 2025.10, the design tokens spec that went stable last October. The part that actually breaks builds is three smaller, specific changes buried in the migration guide, and a fourth one that just hit a token management tool you might already be using.
References can only point to a token now, not a group
In earlier versions, a reference like `{foo}` could resolve to a whole group of tokens, or `{foo.nested.attributes}` could reach into a sub-property partway down the tree. The v5 migration guide closes both doors: a reference now has to point at an actual token, meaning its `$value`, full stop. If your tokens.json ever aliased a category instead of a specific value, expecting Style Dictionary to figure out which leaf you meant, that file no longer builds. It has to be rewritten to reference the leaf token directly.
The reference syntax itself is no longer yours to configure
v4 and earlier let you customize the brackets and separator used in references, so a team could run `$foo.bar` instead of `{foo.bar}` if that fit their existing files better. v5 removes that option. The opening brace, closing brace, and dot separator are fixed to match the DTCG spec exactly. That's a reasonable trade for interoperability, one less way for a tool to silently disagree with another tool about what a reference looks like, but it means any pipeline that leaned on a custom syntax needs a find-and-replace pass before it builds again.
Node 22 is now the floor
Style Dictionary v5 requires Node.js 22 or newer, because it uses `Set.prototype.union` internally to speed up how references get resolved. That's a small technical detail with a real operational consequence: a CI pipeline still pinned to Node 18 or 20 for a token build step will fail outright, not silently. Worth checking before you bump the package version and walk away.
zeroheight just retired its legacy export, this month
Separately from the library itself, zeroheight's token manager upgraded its export pipeline to run on Style Dictionary v5, and as part of that, it retired the older DTCG JSON (legacy) and Style Dictionary export formats starting this September. Existing exports in the old format keep working, but you can no longer create a new token set output or a new URL export in it. If your AI builder's setup script points at a saved zeroheight export URL from a year ago, this is worth checking now rather than after a build quietly stops resolving colors.
- A reference to a token group, not a leaf value, stops building under v5.
- A custom reference syntax (anything other than `{}` and `.`) stops building under v5.
- A CI runner on Node 18 or 20 fails the build step outright, not silently.
- A zeroheight export URL created before this month may be sitting on a format that new token sets can no longer be exported to.
Why this matters more than a normal dependency bump
A version bump in most tools breaks a build loudly, you see the error, you fix the syntax, you move on. Token pipelines are sneakier, because a broken reference doesn't always fail the build, sometimes it resolves to nothing and your CSS custom property comes out empty. The agent building your UI still runs. It just quietly gets no color instead of your color, and you find out when the page looks unstyled instead of wrong. That failure mode is exactly why it's worth testing your token build against v5 deliberately, rather than finding out from a broken deploy.
Where this actually lands depending on how you get your tokens:
- Style Dictionary v5: The transform engine itself. Real breaking changes: leaf-only references, fixed syntax, Node 22 floor. Worth testing before you upgrade in place.
- zeroheight tokens: Legacy export formats retired for new token sets starting September 2026. Old export URLs still resolve, but nothing new can be created in the old shape.
- WAALEE: Extracts tokens fresh from a live URL in current DTCG 2025.10 shape, so there's no legacy export or old reference syntax to migrate in the first place.
None of this means skip the upgrade. DTCG alignment is the right direction, and a stricter reference model catches real mistakes that used to fail silently. It just means treat a token pipeline upgrade like a schema migration, not a patch bump: rebuild your tokens against v5 in a branch, diff the output, and check that every color your app depends on actually still resolves before you ship it.