Most teams' first attempt at design tokens is a JSON file nobody consumes automatically. Someone writes { "color-brand-primary": "#2F5FDB" }, a developer manually copies the value into a CSS file, and the JSON file becomes documentation rather than infrastructure within a month. Style Dictionary exists specifically to close that gap: it reads a single token source and generates the platform-specific output every consuming codebase actually needs, on a build step instead of a manual transcription.
This is a walkthrough of setting it up from an empty token file to a working multi-platform build.
Photo by Anna Shvets on Pexels
Before any of the setup below, it's worth being honest about when Style Dictionary earns its keep. A single web app with no design tool integration and no second platform to target can often get by with a hand-written CSS variables file. Style Dictionary becomes clearly worth the setup once you have more than one platform consuming the same values, or once a designer is expected to be able to change a value without filing a ticket for an engineer to update a stylesheet by hand.
Step 1: Structure the token source file
Start with a JSON structure that mirrors the tiered approach: core values, semantic references, and component-level overrides. A minimal starting file looks something like this:
{
"color": {
"blue": { "500": { "value": "#2F5FDB" } }
},
"semantic": {
"color": {
"brand": { "primary": { "value": "{color.blue.500}" } }
}
}
}
The curly-brace reference syntax is Style Dictionary's way of letting semantic tokens point at core tokens, so a change to the core value propagates automatically to every semantic token that references it. This structure closely tracks the format the W3C Design Tokens Community Group has been standardizing, which is worth aligning with even if you're not using their exact schema, since it keeps you close to whatever tooling converges on the shared standard.
Step 2: Install and configure the build
npm install style-dictionary --save-dev
A configuration file tells Style Dictionary which token source files to read and which platforms to generate output for:
module.exports = {
source: ["tokens/**/*.json"],
platforms: {
css: {
transformGroup: "css",
buildPath: "build/css/",
files: [{ destination: "variables.css", format: "css/variables" }]
},
ios: {
transformGroup: "ios-swift",
buildPath: "build/ios/",
files: [{ destination: "Tokens.swift", format: "ios-swift/class.swift" }]
}
}
};
Running the build generates a variables.css file with CSS custom properties and a Tokens.swift file with native constants, both derived from the exact same source values. The MDN documentation on CSS custom properties covers the syntax the generated CSS output follows and how components should consume it once it lands in the codebase.
Step 3: Wire the build into CI, not a developer's memory
The build command above needs to run automatically whenever the token source changes, not whenever someone remembers to run it locally. A CI step that runs the Style Dictionary build on every push to the token source directory, then either commits the generated output or publishes it as a package consumed by other repositories, is what actually closes the loop between "someone changed a token" and "every platform has the updated value."
Teams that skip this step end up with generated output that is stale relative to the source file, which recreates the exact problem tokens were supposed to solve, just one layer removed from where it used to live.
Step 4: Add custom transforms for anything platform-specific
Style Dictionary's default transforms cover the common cases (hex to rgba, pixel to rem, naming case conversion) but real design systems usually need at least one custom transform. A common example is converting a shadow token, which might be structured as an object with x, y, blur, and color properties in the source file, into the single string format CSS box-shadow expects. Custom transforms are plain JavaScript functions registered with the build config, which is one of the reasons Style Dictionary has become a common choice over hand-rolled build scripts: the transform layer is extensible without forking the tool itself.
Step 5: Validate the output before it ships
A build that completes without errors is not the same as a build that produced correct output. Adding a lightweight visual check, rendering a small set of representative components against the freshly generated CSS and comparing snapshots, catches the case where a transform quietly mangled a value in a way that still produces syntactically valid CSS. Storybook paired with a visual regression tool is the most common way teams add this check without building custom tooling from scratch.
Step 6: Version the generated output deliberately
A decision worth making early is whether the generated CSS and platform files get committed to the repository or published as a versioned package consumed by other codebases. Committing works fine for a single-repo product. Publishing as a package (an npm package for the CSS and JS outputs, a CocoaPod or similar for iOS) is the better choice once more than one repository consumes the tokens, since it gives every consumer an explicit version to pin against rather than silently picking up whatever the token repository's main branch currently contains. Treat a breaking token change, removing or renaming a semantic token consumers depend on, the same way you'd treat a breaking API change: a major version bump, not a silent update.
What a broken build actually looks like in practice
The most common Style Dictionary failure isn't a build that crashes, it's a build that completes and produces subtly wrong output. A misconfigured transform can silently convert a spacing value to the wrong unit, or a reference cycle between two tokens can resolve to an unexpected fallback rather than throwing an error. Adding a small assertion step after the build, checking a handful of known token values against the generated output, catches this class of regression far more reliably than a visual review of the generated CSS file, which is easy to skim past when nothing looks obviously broken.
Common setup mistakes worth avoiding
A few mistakes show up repeatedly in Style Dictionary setups. Nesting the source JSON too deeply before establishing clear naming conventions makes the generated variable names unreadable, since Style Dictionary's default naming transform concatenates the full path. Mixing raw values and references inconsistently within the same file (some semantic tokens pointing at core tokens, others hardcoding a duplicate value instead of referencing) reintroduces drift risk inside the very file meant to prevent it. And skipping the CI wiring described in step three is the single most common reason a Style Dictionary setup that looked complete in a demo quietly stops reflecting reality within a few months.
What this setup buys you
Once the pipeline is running in CI, a designer changing a core color value in the token source, and a developer never touching a stylesheet by hand, is the actual day-to-day workflow instead of an aspirational one. The generated output for web, iOS, Android, or whatever other platform the config targets stays in sync because it is derived from the same file on every build, not maintained as separate hand-edited copies that happen to agree today.
We cover the tiering strategy and governance model this build step should sit on top of in our longer guide to a design token pipeline both designers and developers trust. 137Foundry has set up this exact pipeline on production design systems moving off hand-maintained token files, and it's usually a smaller lift than teams expect once the token source is structured correctly.
Top comments (1)
I completely agree that having a single JSON file with design tokens is not enough, and that's where Style Dictionary comes in to fill the gap by generating platform-specific output. I've had experience with setting up Style Dictionary in a multi-platform project, and I can attest that it's worth the setup once you have more than one platform consuming the same values. One thing I'd like to add is that it's also important to consider how to handle versioning of the design tokens, so that changes to the tokens can be properly tracked and managed across different platforms. Have you considered how to integrate versioning into the Style Dictionary workflow, or are there any best practices you've found for managing token updates across multiple platforms?