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

Experiment in the playground

---

Installation

Caution

Note that you must have NodeJS (and NPM) installed before you can follow this guide.

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. Style Dictionary is a build tool, and you are most likely to use it as a dev dependency:

npm install -D style-dictionary

Note

When using as a dependency or dev dependency, prefix the style-dictionary commands with npx

Creating a New Project

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

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.


scss
✔︎  build/scss/_variables.scss

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

  • Directorycolor

    • base.json
    • font.json
  • Directorysize

    • font.json
• Directorybuild

  • Directoryandroid

    • font_dimens.xml
    • colors.xml
  • Directorycompose

    • StyleDictionaryColor.kt
    • StyleDictionarySize.kt
  • Directoryscss

    • _variables.scss
  • 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 3 platforms defined: scss, android, ios. 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="size_font_small">12.00sp</dimen>
  <dimen name="size_font_medium">16.00sp</dimen>
  <dimen name="size_font_large">32.00sp</dimen>
  <dimen name="size_font_base">16.00sp</dimen>
</resources>

colors.xml

<resources>
  <color name="color_base_gray_light">#ffcccccc</color>
  <color name="color_base_gray_medium">#ff999999</color>
  <color name="color_base_gray_dark">#ff111111</color>
  <color name="color_base_red">#ffff0000</color>
  <color name="color_base_green">#ff00ff00</color>
  <color name="color_font_base">#ff111111</color>
  <color name="color_font_secondary">#ff999999</color>
  <color name="color_font_tertiary">#ffcccccc</color>
</resources>

Compose

StyleDictionaryColor.kt

object StyleDictionaryColor {
  val colorBaseGrayDark = Color(0xff111111)
  val colorBaseGrayLight = Color(0xffcccccc)
  val colorBaseGrayMedium = Color(0xff999999)
  val colorBaseGreen = Color(0xff00ff00)
  val colorBaseRed = Color(0xffff0000)
  val colorFontBase = Color(0xffff0000)
  val colorFontSecondary = Color(0xff00ff00)
  val colorFontTertiary = Color(0xffcccccc)
}

StyleDictionarySize.kt

object StyleDictionarySize {
  /** the base size of the font */
  val sizeFontBase = 16.00.sp
  /** the large size of the font */
  val sizeFontLarge = 32.00.sp
  /** the medium size of the font */
  val sizeFontMedium = 16.00.sp
  /** the small size of the font */
  val sizeFontSmall = 12.00.sp
}

SCSS

_variables.scss

$color-base-gray-light: #cccccc;
$color-base-gray-medium: #999999;
$color-base-gray-dark: #111111;
$color-base-red: #ff0000;
$color-base-green: #00ff00;
$color-font-base: #ff0000;
$color-font-secondary: #00ff00;
$color-font-tertiary: #cccccc;
$size-font-small: 0.75rem;
$size-font-medium: 1rem;
$size-font-large: 2rem;
$size-font-base: 1rem;

iOS

StyleDictionaryColor.h

#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.800f green:0.800f blue:0.800f alpha:1.000f],
[UIColor colorWithRed:0.600f green:0.600f blue:0.600f alpha:1.000f],
[UIColor colorWithRed:0.067f green:0.067f blue:0.067f alpha:1.000f],
[UIColor colorWithRed:1.000f green:0.000f blue:0.000f alpha:1.000f],
[UIColor colorWithRed:0.000f green:1.000f blue:0.000f alpha:1.000f],
[UIColor colorWithRed:1.000f green:0.000f blue:0.000f alpha:1.000f],
[UIColor colorWithRed:0.000f green:1.000f blue:0.000f alpha:1.000f],
[UIColor colorWithRed:0.800f green:0.800f blue:0.800f 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. There are 2 JSON files with color as the top level key, but they get merged properly.
2. The build system resolves references to other design tokens. {size.font.medium.value} is resolved properly.
3. The build system handles references to design token values in other files as well (as you can see in tokens/color/font.json).
4. Values are transformed specifically for each platform.

Making a change

Now let’s make a change and see how that affects things. Open up tokens/color/base.json and change "#111111" to "#000000". 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="color_base_gray_light">#ffcccccc</color>
  <color name="color_base_gray_medium">#ff999999</color>
  <color name="color_base_gray_dark">#ff000000</color>
  <color name="color_base_red">#ffff0000</color>
  <color name="color_base_green">#ff00ff00</color>
  <color name="color_font_base">#ffff0000</color>
  <color name="color_font_secondary">#ff00ff00</color>
  <color name="color_font_tertiary">#ffcccccc</color>
</resources>

StyleDictionaryColor.kt

object StyleDictionaryColor {
  val colorBaseGrayDark = Color(0xff000000)
  val colorBaseGrayLight = Color(0xffcccccc)
  val colorBaseGrayMedium = Color(0xff999999)
  val colorBaseGreen = Color(0xff00ff00)
  val colorBaseRed = Color(0xffff0000)
  val colorFontBase = Color(0xffff0000)
  val colorFontSecondary = Color(0xff00ff00)
  val colorFontTertiary = Color(0xffcccccc)
}

_variables.scss

$color-base-gray-light: #cccccc;
$color-base-gray-medium: #999999;
$color-base-gray-dark: #000000;
$color-base-red: #ff0000;
$color-base-green: #00ff00;
$color-font-base: #ff0000;
$color-font-secondary: #00ff00;
$color-font-tertiary: #cccccc;

StyleDictionaryColor.h

[UIColor colorWithRed:0.800f green:0.800f blue:0.800f alpha:1.000f],
[UIColor colorWithRed:0.600f green:0.600f blue:0.600f alpha:1.000f],
[UIColor colorWithRed:0.000f green:0.000f blue:0.000f alpha:1.000f],
[UIColor colorWithRed:1.000f green:0.000f blue:0.000f alpha:1.000f],
[UIColor colorWithRed:0.000f green:1.000f blue:0.000f alpha:1.000f],
[UIColor colorWithRed:1.000f green:0.000f blue:0.000f alpha:1.000f],
[UIColor colorWithRed:0.000f green:1.000f blue:0.000f alpha:1.000f],
[UIColor colorWithRed:0.800f green:0.800f blue:0.800f 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, extending, or how the build process works.

Basic Usage

Command Line Interface (CLI)

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

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';

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

await sd.buildAllPlatforms();

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