Style Dictionary: one config, many generated stylesheets
A build system for creating cross-platform styles.
At a glance
- What is it?
- Style Dictionary reads JSON design tokens, deep merges them, and writes SCSS, Android and other platform files from a single config.json. Here is what its config keys, four CLI flags and Node entry points actually cover, and where they stop.
- Who is it for?
- Adopt Style Dictionary when your tokens already live in JSON or JavaScript files and the same values have to reach more than one platform, choosing transforms per platform through transformGroup. Pass on it if you need a watcher, a validator, or a merge report from the command line, because none of those sit in the documented surface, or if the tool that produces your tokens writes a shape the source globs cannot pick up.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 12 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- style-dictionary/style-dictionary4,884 ★ · +60
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| style-dictionary/style-dictionary | 4.8k | 4.9k |
60 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Source globs are deep merged before any transform runs
Everything starts in `config.json`. Its `source` property is an array of file path globs such as `tokens/**/*.json`, and Style Dictionary does a deep merge of every token file those patterns match, which lets you organize the files however you want. A second property, `include`, takes globs pointing at files that contain default styles, and the build uses that as the base collection. Tokens found through `source` overwrite tokens found through `include`.
The package layout that feeds those globs looks like this:
├── config.json
├── tokens/
│ ├── size/
│ ├── font.json
│ ├── color/
│ ├── font.json
│ ...
├── assets/
│ ├── fonts/
│ ├── images/Four flags, one subcommand, and a config.json in the root
Node and npm have to be installed before anything else, and package.json pins `>=22.0.0` under engines. Then pick one of the three install shapes:
$ npm install -g style-dictionary$ npm install -D style-dictionary$ yarn add style-dictionary --devBecause this is a build tool, the README suggests saving it as a dev dependency rather than a global. The build itself is one subcommand, called from the root directory of the project, where `config.json` or `config.js` is expected:
$ style-dictionary build| Flag | Short Flag | Description | | --- | --- | --- | | --config [path] | -c | Set the config file to use. Must be a .json file | | --platform [platform] | -p | Only build a specific platform defined in the config file. | | --help | -h | Display help content | | --version | -v | Display the version |
There is no watch flag, no output override, and no clean step in that list. Regenerating on every save means running the command again, or calling the Node entry point from another build system such as Grunt or Gulp.
Engines demand Node 22 while the examples mix require and import
The `>=22.0.0` floor means a project pinned to an older Node has to move before the install step, not after it. The exports map in package.json publishes five entry points: the package root at `./lib/StyleDictionary.js`, `./fs`, which resolves to `./lib/fs-node.js` under node and `./lib/fs.js` by default, plus `./utils`, `./enums`, and `./types`. The bin field points the CLI at `./bin/style-dictionary.js`.
The Node examples do not settle which module system your own script should use. The first one calls `require`, and the second imports from `style-dictionary/enums` while still calling `require('style-dictionary').extend`, inside a package whose `"type"` is `module`:
import { formats, transformGroups } from 'style-dictionary/enums';
const StyleDictionary = require('style-dictionary').extend({
source: ['tokens/**/*.json'],
platforms: {
scss: {
transformGroup: transformGroups.scss,
buildPath: 'build/',
files: [
{
destination: 'variables.scss',
format: formats.scssVariables,
},
],
},
// ...
},
});
StyleDictionary.buildAllPlatforms();The shorter Node form reads the same config from disk, which is the path to take when you want to extend the functionality rather than hand write platform entries:
const StyleDictionary = require('style-dictionary').extend('config.json');
StyleDictionary.buildAllPlatforms();A platform entry is a transformGroup, a buildPath, and a file list
Output shape is decided per platform. `transformGroup` selects the transforms, `buildPath` sets the directory, and every item in `files` pairs a `destination` with a `format` name:
{
"source": ["tokens/**/*.json"],
"platforms": {
"scss": {
"transformGroup": "scss",
"buildPath": "build/",
"files": [
{
"destination": "scss/_variables.scss",
"format": "scss/variables"
}
]
},
"android": {
"transformGroup": "android",
"buildPath": "build/android/",
"files": [
{
"destination": "font_dimens.xml",
"format": "android/fontDimens"
}
]
}
}
}Those format values are opaque strings in a JSON config. Working from Node, you can skip the strings and use the exported enum values instead, `formats.scssVariables` and `transformGroups.scss` for the scss platform above.
The npm package ships examples and leaves the docs site behind
The published tarball is described by the `files` array in package.json: `bin`, `lib`, `types/**/*.d.ts`, `examples`, `LICENSE`, and `NOTICE`. Inside `examples` there are four entry points, `examples/README.md`, `examples/basic/`, `examples/advanced/`, and `examples/complete/`.
The documentation site is not on that list. The repository serves it with `astro dev --root ./docs` through the `docs:start` script, and builds it with `astro check --root ./docs && astro build --root ./docs`, but `docs/` never lands in an install. Anything you need to know about a transform, a format, or a version jump has to come from styledictionary.com, from CHANGELOG.md, or from the source in `lib/`. A browser playground also exists at https://www.style-dictionary-play.dev/, built by the folks at <div>RIOTS.
A fast moving 5.x line with no 5.x migration file in the tree
package.json reports version 5.7.1. Three releases landed inside three weeks: v5.6.1 on 2026-10-10, v5.7.0 on 2026-10-16, and v5.7.1 on 2026-10-24, and the last push to main is dated 2026-10-28. Release notes are assembled from a `.changeset/` directory that sits next to CHANGELOG.md, and the README opens with a link to the Style Dictionary 5 migration guide at https://styledictionary.com/versions/v5/migration/.
The test wiring is visible in package.json too: `test` runs `web-test-runner --coverage`. Patching a lockstep upgrade is cheap in a repository this size, but for consumers the generated files are a contract shared by several platforms, so pin an exact version in your own package.json and read CHANGELOG.md on each bump rather than tracking the latest tag.
The default config name accepts .js while --config is documented as .json
Without a flag, the build looks for `config.json` or `config.js` in the root of the project. The `--config` row in the flag table states that the path must be a .json file. Those two statements do not agree, so a project that keeps its config as JavaScript works under the default name and sits outside the documented path when you pass `-c` to point somewhere else. Confirm which of the two your installed version honors before you rename anything.
Beyond that, the extension surface is the Node API. `.extend()` is overloaded and takes either a file path or an object in the same format as a config.json file, and `StyleDictionary.buildAllPlatforms()` runs every platform at once, while the CLI's `--platform` narrows a run to one entry in the config file. Anything the built in transforms and formats do not cover, such as a custom output shape, means writing that code yourself against the Node module.
Editorial conclusion
Adopt Style Dictionary when your tokens already live in JSON or JavaScript files and the same values have to reach more than one platform, choosing transforms per platform through transformGroup. Pass on it if you need a watcher, a validator, or a merge report from the command line, because none of those sit in the documented surface, or if the tool that produces your tokens writes a shape the source globs cannot pick up. Before you let other teams consume the output, open the destinations under your buildPath and confirm the token names survived, then pin an exact version in package.json.
Frequently asked questions
What is a style dictionary?
Style Dictionary is a build system for creating cross platform styles. You define design tokens as key and value pairs describing colors, sizes, icons, and motion in JSON or JavaScript files, then the build exports them to iOS, Android, CSS, JS, HTML, sketch files, and style documentation. It runs as a CLI through npm or as a normal node module.
How do you use Style Dictionary from the command line?
Install it with `npm install -g style-dictionary` or `npm install -D style-dictionary`, put a config.json in the project root, and run `style-dictionary build` there. The CLI takes `--config [path]`, `--platform [platform]`, `--help`, and `--version`, so a single platform can be rebuilt with `--platform`.
What is the difference between Style Dictionary and Tokens Studio?
What it states about Style Dictionary is its scope: one token source that exports to iOS, Android, CSS, JS, HTML, sketch files, and style documentation, used either as a CLI through npm or as a node module you can extend.
How does Style Dictionary compare with Terrazzo?
Style Dictionary's own mechanism is a config file whose source globs are deep merged, with one platform entry per output, each picking a transformGroup, a buildPath, and a destination file with a format name.
How does Style Dictionary compare with Storybook?
Its documented outputs are generated files per platform, for example scss/_variables.scss for the scss transformGroup and font_dimens.xml under build/android/ for the android transformGroup.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/style-dictionary-style-dictionary)Star history chart for your README
[](https://hysenlabs.com/projects/style-dictionary-style-dictionary)Was this useful?