Style Dictionary V4 release plans

Style-Dictionary v4.0.0 full release is planned for Q2 2024. Together with the full release we will also release @tokens-studio/sd-transforms v1.0.0, meaning it will be out of alpha state and be stable from API perspective. And then there's the style-dictionary configurator project, which will be updated to Style-Dictionary v4 and sd-transforms v1.

What does this mean for you?

The Configurator will no longer support style-dictionary v3 when v4.0.0 is released. It already uses v4 under the hood anyways, but still accepts v3 configurations, transforms, formats etc. The public API of those will break slightly in the last v4 prerelease and at that point it will be tough for me to support both v3 and v4. You can still use sd-transforms v0.x.x and style-dictionary v3 if you're not ready to migrate just yet, but your transforms, formats, etc. might no longer work inside the configurator due to the breaking changes, so you'll have to address the gap in those specific API changes when trying to run it in the configurator.

What does migration from v3 to v4 look like?

see changelog

Not all breaking changes have been done just yet, but this is a rough overview of what will be needed on your end:

• Convert your JavaScript code that's importing from or configuring style-dictionary to modern ESM format (instead of CJS). Some JS build/dev tools allow using mixed formats but this is not my personal recommendation. Another alternatively is using dynamic imports in your CJS files, which allows importing ESM files that way.

• Use new StyleDictionary(cfg) instead of StyleDictionary.extend(cfg) when initializing style-dictionary instance

• Methods like buildAllPlatforms, extend, cleanAllPlatforms, exportPlatform etc. are now async methods returning Promises, and the methods are tied to your StyleDictionary instance.

• All deprecated properties and methods such as sd.properties/sd.allProperties/sd.registerTemplate() have been removed, use the alternatives sd.tokens/sd.allTokens/sd.registerFormat()

• You cannot import from Style-Dictionary's internal files anymore e.g. import createDictionary from 'style-dictionary/lib/utils/createDictionary.js';. We use Package Entrypoints which locks down the public API. This is safer for our consumers, as we make explicit what is considered publicly exposed. Importing a private utility is unsafe as it could break at any time, as we do not take into account that someone might be using it. Utilities that are publicly exposed can be imported from import { ... } from 'style-dictionary/utils';.

• Type safety is much better in v4, standalone type interfaces can now be imported from the types entrypoint e.g. import type { DesignTokens } from 'style-dictionary/types'; rather than from 'style-dictionary';.

• StyleDictionary.Core type no longer needs to be separately imported, this type is now available as import type { StyleDictionary } from 'style-dictionary';.

• Not quite done yet, but basically some of the registers will get slight changes to its properties to make them consistently named across the board.

What goodies do I get for migrating to v4?

see projects board

• Much better type safety and auto completion

• Style-Dictionary is much more reliable, as type safety is strictly enforced throughout the entire repository. All tests (98% coverage) are running in Node v18, Node LTS (v21 atm), Chromium, and both in Linux and Windows environments for every pull request.

• We explicitly expose some cool utilities and consider them public API, see utils docs

• Browser-compatible out of the box

TO DO or IN PROGRESS

• Forward compatibility with the W3C Design Token Community Group draft specification for design tokens

• Transitive transforms can defer themselves

• transformGroup & transforms can be combined

We know migration can be scary or feel like it will be a lot of work, but just know that I'm available to help you with this. If you've got any questions or you'd like us to take a look at your project to help estimate the cost of migrating, let us know! Join our slack

Once we're in v4.0.0, we will also start going through all of the open pull requests and issues and see what's still relevant, we'll be much more responsive to contributions at that point as well, which we acknowledge has been subpar since the v3 release.

If you have any contributions that you'd like to revive or start right now, best is to do this using the v4 branch on GitHub, we'll be prioritizing those, feel free to DM Joren on Slack or tag @jorenbroekema on GitHub if you've got one that you want eyes on!