What's new in Style Dictionary 4.0!
Style Dictionary
Style once, use everywhere.
A Style Dictionary uses design tokens to define styles once and use those styles on any platform or language. It provides a single place to create and edit your styles, and exports these tokens to all the places you need - iOS, Android, CSS, JS, HTML, sketch files, style documentation, etc. It is available as a CLI through npm, but can also be used like any normal node module if you want to extend its functionality.
When you are managing user experiences, it can be quite challenging to keep styles consistent and synchronized across multiple development platforms and devices. At the same time, designers, developers, PMs and others must be able to have consistent and up-to-date style documentation to enable effective work and communication. Even then, mistakes inevitably happen and the design may not be implemented accurately. Style Dictionary solves this by automatically generating style definitions across all platforms from a single source - removing roadblocks, errors, and inefficiencies across your workflow.
Watch the Demo on YouTube
Experiment in the playground
Try the browser-based Style Dictionary playground: https://www.style-dictionary-play.dev/, built by the folks at \RIOTS.
Contents
Installation
Note that you must have node (and npm) installed.
If you want to use the CLI, you can install it globally via npm:
$ npm install -g style-dictionary
Or you can install it like a normal npm dependency. This is a build tool and you are most likely going to want to save it as a dev dependency:
$ npm install -D style-dictionary
If you want to install it with yarn:
$ yarn add style-dictionary --dev
Usage
CLI
$ style-dictionary build
Call this in the root directory of your project. The only thing needed is a config.json file. There are also arguments:
| 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 |
Node
You can also use the style dictionary build system in node if you want to extend the functionality or use it in another build system like Grunt or Gulp.
const StyleDictionary = require('style-dictionary').extend('config.json');
StyleDictionary.buildAllPlatforms();
The .extend() method is an overloaded method that can also take an object with the configuration in the same format as a config.json file.
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();
Example
Take a look at some of our examples
A style dictionary is a collection of design tokens, key/value pairs that describe stylistic attributes like colors, sizes, icons, motion, etc. A style dictionary defines these design tokens in JSON or Javascript files, and can also include static assets like images and fonts. Here is a basic example of what the package structure can look like:
├── config.json
├── tokens/
│ ├── size/
│ ├── font.json
│ ├── color/
│ ├── font.json
│ ...
├── assets/
│ ├── fonts/
│ ├── images/
config.json
This tells the style dictionary build system how and what to build. The default file path is config.json or config.js in the root of the project, but you can name it whatever you want by passing in the --config flag to the CLI.
{
"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"
}
]
}
}
}
| Property | Type | Description |
|---|---|---|
| source | Array | An array of file path globs to design token files. Style Dictionary will do a deep merge of all of the token files, allowing you to organize your files files however you want. |
| include | Array | An array of file path globs to design token files that contain default styles. The Style Dictionary uses this as a base collection of tokens. The tokens found using the "source" attribute will overwrite tokens found using include. |
| platforms | Object | Sets of platform files to be built. |
| platform.transformGroup | String (optional) | Apply a group of transforms to the tokens, must either define this or transforms. |
| platform.transforms | Array (optional) | Transforms to apply sequentially to all tokens. Can be a built-in one or you can create your own. |
| platform.buildPath | String (optional) | Base path to build the files, must end with a trailing slash. |
| platform.files |