Skip to content
Style-Dictionary logo, Pascal the chameleon.Style Dictionary

Overview

Style Dictionary is a build-system that runs in both NodeJS and browsers (natively), to parse and transform your design tokens to then export them to any platform: iOS, Android, CSS, JS, HTML, sketch files, style documentation, or anything you can think of.

It’s also forward-compatible with Design Token Community Group spec.

Watch the Demo on Youtube

Section titled “Watch the Demo on Youtube”

Watch the video

Experiment in the playground

Section titled “Experiment in the playground”

Installation

Section titled “Installation”

If you want to use the CLI, you can install it globally via npm:

Terminal window
npm install -g style-dictionary

Or you can install it like a normal npm dependency. Style Dictionary is a build tool, and you are most likely to use it as a dev dependency:

Terminal window
npm install -D style-dictionary

Creating a New Project

Section titled “Creating a New Project”

The CLI comes with some starter code to get a new project started easily.

Terminal window
mkdir MyStyleD
cd MyStyleD
style-dictionary init basic

This command will copy over the example files found in the basic example in this repo and then run the style-dictionary build command to generate the build artifacts. You should see something like this output:

Copying starter files...


Source style dictionary starter files created!


Running `style-dictionary build` for the first time to generate build artifacts.




css
✔︎  build/css/_variables.css


android
✔︎  build/android/font_dimens.xml
✔︎  build/android/colors.xml


compose
✔︎ build/compose/StyleDictionaryColor.kt
✔︎ build/compose/StyleDictionarySize.kt


ios
✔︎  build/ios/StyleDictionaryColor.h
✔︎  build/ios/StyleDictionaryColor.m
✔︎  build/ios/StyleDictionarySize.h
✔︎  build/ios/StyleDictionarySize.m


ios-swift
✔︎  build/ios-swift/StyleDictionary.swift


ios-swift-separate-enums
✔︎  build/ios-swift/StyleDictionaryColor.swift
✔︎  build/ios-swift/StyleDictionarySize.swift

Pat yourself on the back, you built your first style dictionary! Take a look at what you built. This should have created a build directory and it should look like this:

  • README.md
  • config.json
  • Directorytokens
    • colors.json
    • dimensions.json
    • object-values.json
    • text.json
  • Directorybuild
    • Directoryandroid
      • font_dimens.xml
      • colors.xml
    • Directorycompose
      • StyleDictionaryColor.kt
      • StyleDictionarySize.kt
    • Directorycss
      • _variables.css
    • Directoryios
      • StyleDictionaryColor.h
      • StyleDictionaryColor.m
      • StyleDictionarySize.h
      • StyleDictionarySize.m
    • Directoryios-swift
      • StyleDictionary.swift
      • StyleDictionaryColor.swift
      • StyleDictionarySize.swift

If you open config.json you will see there are 6 platforms defined: css, android, compose, ios, ios-swift, and ios-swift-separate-enums. Each platform has a transformGroup, buildPath, and files defined. The buildPath and files of the platform should match up to the files what were built. Those files should look like these:

Android

font_dimens.xml
<resources>
  <dimen name="text_sizes_heading">448.00dp</dimen>
  <dimen name="text_sizes_body">256.00dp</dimen>
</resources>
colors.xml
<resources>
  <color name="colors_black">#ff000000</color>
  <color name="colors_white">#ffffffff</color>
  <color name="colors_orange_100">#fffffaf0</color>
  <color name="colors_orange_200">#fffeebc8</color>
  <color name="colors_orange_300">#fffbd38d</color>
  <color name="colors_orange_400">#fff6ad55</color>
  <color name="colors_orange_500">#ffed8936</color>
  <color name="colors_orange_600">#ffdd6b20</color>
  <color name="colors_orange_700">#ffc05621</color>
  <color name="colors_orange_800">#ff9c4221</color>
  <color name="colors_orange_900">#ff7b341e</color>
</resources>

Compose

StyleDictionaryColor.kt
object StyleDictionaryColor {
  val colorsBlack = Color(0xff000000)
  val colorsOrange100 = Color(0xfffffaf0)
  val colorsOrange200 = Color(0xfffeebc8)
  val colorsOrange300 = Color(0xfffbd38d)
  val colorsOrange400 = Color(0xfff6ad55)
  val colorsOrange500 = Color(0xffed8936)
  val colorsOrange600 = Color(0xffdd6b20)
  val colorsOrange700 = Color(0xffc05621)
  val colorsOrange800 = Color(0xff9c4221)
  val colorsOrange900 = Color(0xff7b341e)
  val colorsWhite = Color(0xffffffff)
}
StyleDictionarySize.kt
object StyleDictionarySize {
  val dimensions0 = 0.00.dp
  val dimensions1 = 64.00.dp
  val dimensions2 = 128.00.dp
  val dimensions3 = 192.00.dp
  val dimensions4 = 256.00.dp
  val dimensions5 = 320.00.dp
  val dimensions6 = 384.00.dp
  val dimensions7 = 448.00.dp
  val dimensions8 = 512.00.dp
  val dimensions9 = 576.00.dp
  val dimensions10 = 640.00.dp
  val dimensions11 = 704.00.dp
  val dimensions12 = 768.00.dp
  val dimensions13 = 832.00.dp
  val dimensions14 = 896.00.dp
  val dimensions15 = 960.00.dp
  val dimensionsMax = 159984.00.dp
}

CSS

_variables.css
:root {
  --colors-black: #000000;
  --colors-white: #ffffff;
  --colors-orange-100: #fffaf0;
  --colors-orange-200: #feebc8;
  --colors-orange-300: #fbd38d;
  --colors-orange-400: #f6ad55;
  --colors-orange-500: #ed8936;
  --colors-orange-600: #dd6b20;
  --colors-orange-700: #c05621;
  --colors-orange-800: #9c4221;
  --colors-orange-900: #7b341e;
  --dimensions-0: 0px;
  --dimensions-1: 4px;
  /* ...additional dimension, typography, transition, border, shadow, and text tokens... */
}

iOS

StyleDictionaryColor.h
typedef NS_ENUM(NSInteger, StyleDictionaryColorName) {
ColorsBlack,
ColorsWhite,
ColorsOrange100,
ColorsOrange200,
ColorsOrange300,
ColorsOrange400,
ColorsOrange500,
ColorsOrange600,
ColorsOrange700,
ColorsOrange800,
ColorsOrange900
};


@interface StyleDictionaryColor : NSObject
+ (NSArray *)values;
+ (UIColor *)color:(StyleDictionaryColorName)color;
@end
StyleDictionaryColor.m
#import "StyleDictionaryColor.h"


@implementation StyleDictionaryColor


+ (UIColor *)color:(StyleDictionaryColorName)colorEnum{
  return [[self values] objectAtIndex:colorEnum];
}


+ (NSArray *)values {
  static NSArray* colorArray;
  static dispatch_once_t onceToken;


  dispatch_once(&onceToken, ^{
    colorArray = @[
[UIColor colorWithRed:0.000f green:0.000f blue:0.000f alpha:1.000f],
[UIColor colorWithRed:1.000f green:1.000f blue:1.000f alpha:1.000f],
[UIColor colorWithRed:1.000f green:0.980f blue:0.941f alpha:1.000f],
[UIColor colorWithRed:0.996f green:0.922f blue:0.784f alpha:1.000f],
[UIColor colorWithRed:0.984f green:0.827f blue:0.553f alpha:1.000f],
[UIColor colorWithRed:0.965f green:0.678f blue:0.333f alpha:1.000f],
[UIColor colorWithRed:0.929f green:0.537f blue:0.212f alpha:1.000f],
[UIColor colorWithRed:0.867f green:0.420f blue:0.125f alpha:1.000f],
[UIColor colorWithRed:0.753f green:0.337f blue:0.129f alpha:1.000f],
[UIColor colorWithRed:0.612f green:0.259f blue:0.129f alpha:1.000f],
[UIColor colorWithRed:0.482f green:0.204f blue:0.118f alpha:1.000f]
    ];
  });


  return colorArray;
}


@end

Pretty nifty! This shows a few things happening:

  1. The build system does a deep merge of all the design token files defined in the source attribute of config.json. This allows you to split up the design token files however you want.
  2. The build system resolves references to other design tokens. {dimensions.4} is resolved properly.
  3. The build system handles references to design token values in other files as well (as you can see in tokens/object-values.json, which references tokens from tokens/colors.json and tokens/dimensions.json).
  4. Values are transformed specifically for each platform.

Making a change

Section titled “Making a change”

Now let’s make a change and see how that affects things. Open up tokens/colors.json and change "#000000" to "#111111". After you make that change, save the file and re-run the build command style-dictionary build. Open up the build files and take a look. Now:

Android

colors.xml
<resources>
  <color name="colors_black">#ff111111</color>
  <color name="colors_white">#ffffffff</color>
  <color name="colors_orange_100">#fffffaf0</color>
  <color name="colors_orange_200">#fffeebc8</color>
  <color name="colors_orange_300">#fffbd38d</color>
  <color name="colors_orange_400">#fff6ad55</color>
  <color name="colors_orange_500">#ffed8936</color>
  <color name="colors_orange_600">#ffdd6b20</color>
  <color name="colors_orange_700">#ffc05621</color>
  <color name="colors_orange_800">#ff9c4221</color>
  <color name="colors_orange_900">#ff7b341e</color>
</resources>
StyleDictionaryColor.kt
object StyleDictionaryColor {
  val colorsBlack = Color(0xff111111)
  val colorsOrange100 = Color(0xfffffaf0)
  val colorsOrange200 = Color(0xfffeebc8)
  val colorsOrange300 = Color(0xfffbd38d)
  val colorsOrange400 = Color(0xfff6ad55)
  val colorsOrange500 = Color(0xffed8936)
  val colorsOrange600 = Color(0xffdd6b20)
  val colorsOrange700 = Color(0xffc05621)
  val colorsOrange800 = Color(0xff9c4221)
  val colorsOrange900 = Color(0xff7b341e)
  val colorsWhite = Color(0xffffffff)
}
_variables.css
:root {
  --colors-black: #111111;
  --colors-white: #ffffff;
  --colors-orange-100: #fffaf0;
  --colors-orange-200: #feebc8;
  --colors-orange-300: #fbd38d;
  --colors-orange-400: #f6ad55;
  --colors-orange-500: #ed8936;
  --colors-orange-600: #dd6b20;
  --colors-orange-700: #c05621;
  --colors-orange-800: #9c4221;
  --colors-orange-900: #7b341e;
}
StyleDictionaryColor.m
    colorArray = @[
[UIColor colorWithRed:0.067f green:0.067f blue:0.067f alpha:1.000f],
[UIColor colorWithRed:1.000f green:1.000f blue:1.000f alpha:1.000f],
[UIColor colorWithRed:1.000f green:0.980f blue:0.941f alpha:1.000f],
[UIColor colorWithRed:0.996f green:0.922f blue:0.784f alpha:1.000f],
[UIColor colorWithRed:0.984f green:0.827f blue:0.553f alpha:1.000f],
[UIColor colorWithRed:0.965f green:0.678f blue:0.333f alpha:1.000f],
[UIColor colorWithRed:0.929f green:0.537f blue:0.212f alpha:1.000f],
[UIColor colorWithRed:0.867f green:0.420f blue:0.125f alpha:1.000f],
[UIColor colorWithRed:0.753f green:0.337f blue:0.129f alpha:1.000f],
[UIColor colorWithRed:0.612f green:0.259f blue:0.129f alpha:1.000f],
[UIColor colorWithRed:0.482f green:0.204f blue:0.118f alpha:1.000f]
    ];

That’s it! There is a lot more you can do with your style dictionary than generating files with color values. Take a look at some examples or take a deeper dive into package structure or how the build process works.

Basic Usage

Section titled “Basic Usage”

Command Line Interface (CLI)

Section titled “Command Line Interface (CLI)”
Terminal window
style-dictionary build

Call this in the root directory of your project, which must include a configuration file.

More detailed information about using the Style Dictionary CLI is available here.

NodeJS

Section titled “NodeJS”

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.

build-tokens.js
import StyleDictionary from 'style-dictionary';


const sd = new StyleDictionary('config.json');
await sd.buildAllPlatforms();

The StyleDictionary constructor can also take a configuration object.

build-tokens.js
import StyleDictionary from 'style-dictionary';
import { formats, transformGroups } from 'style-dictionary/enums';


const sd = new StyleDictionary({
  source: ['tokens/**/*.json'],
  platforms: {
    scss: {
      transformGroup: transformGroups.scss,
      buildPath: 'build/',
      files: [
        {
          destination: 'variables.scss',
          format: formats.scssVariables,
        },
      ],
    },
    // ...
  },
});


await sd.buildAllPlatforms();

More detailed information about using the Style Dictionary npm module is available here.