Outputting to Different Formats with Style Dictionary

1. Getting Started With Style Dictionary
2. Outputting to Different Formats with Style Dictionary – You are here
3. Beyond JSON: Exploring File Formats for Design Tokens
4. Converting Tokens with Style Dictionary
5. Organising Outputs with Style Dictionary
6. Layers, referencing tokens in Style Dictionary

In the first article in this series I walked us through creating up a simple Style Dictionary setup that can transform your Design Tokens (in .json) to different formats (a .css file of CSS Custom Properties and Sass variables in a .scss file). In this article we will go through the other 'built-in' formats that are available, how to set them up, what they are for, and what they would look like.

Defining Design Tokens

Let's look again at the Design Tokens from the first part in this series. We have a couple of colours, some spacing units, and some typography decisions.

{
  "color": {
    "$type": "color",
    "primary": {
      "$value": "#007bff"
    },
    "secondary": {
      "$value": "#6c757d"
    }
  },
  "spacing": {
    "$type": "spacing",
    "none": {
      "$value": "0"
    },
    "small": {
      "$value": "0.5rem"
    },
    "medium": {
      "$value": "1rem"
    }
  },
  "typography": {
    "font": {
      "family": {
        "$type": "fontFamily",
        "body": {
          "$value": "Roboto, sans-serif"
        }
      },
      "size": {
        "$type": "fontSize",
        "base": {
          "$value": "1rem"
        },
        "lg": {
          "$value": "1.25rem"
        }
      }
    }
  }
}

Built In Formats

Out of the box Style Dictionary comes with several built-in formats you can use to convert your Design Tokens from .json to a file format that can be used with various platforms and codebases.

There are formats for CSS, Sass, LESS, Stylus, JavaScript, TypeScript, Android, iOS, Swift, and JSON. With all these possibilities we can truly keep design decisions in sync across the various platforms we need to. This also allows you to scale to new codebases more easily because the Design Token .json stays the same but can output to what you need, as needed.

Let's go through a couple of them to see what how we can turn our Design Tokens into useable code for our projects. You can follow along and see the results in the fresh branch of the git repository.

CSS

We've already seen this in the first article. The format css/variables takes the .json and creates a .css with the Design Tokens generated as CSS Custom Properties.

CSS Preprocessors

Sass

Variables

Again, from the first article. The format scss/variables can create a file of Sass variables based on the Design Tokens in the .scss format.

Map (flat)

Using the format scss/map-flat provides a Sass map of the Design Tokens. To incorporate this into the example git repository we need to add some additional code to the build.js file.

We can add this to the existing scss platform in build.js. Platforms in Style Dictionary define the different output formats where you want your Design Tokens to be used. Each platform has unique configurations for how the tokens are to be transformed, formmated, and written to files.

To add a flat Sass Map to our project we need to add a new destination for where the file is created and tell Style Dictionary what format to use. We can do this by adding:

{
  destination: 'tokens-map.scss',
  format: 'scss/map-flat',
},

After the existing destination and format for scss/variabkes. The complete file would look like this:

const myStyleDictionary = new StyleDictionary({
  source: [`src/tokens/**/*.json`],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'build/css/',
      files: [
        {
          destination: 'variables.css',
          format: 'css/variables',
        },
      ],
    },
    scss: {
      transformGroup: 'scss',
      buildPath: 'build/scss/',
      files: [
        {
          destination: '_variables.scss',
          format: 'scss/variables',
        },
        {
          destination: 'tokens-map.scss',
          format: 'scss/map-flat',
        },
      ],
    },
  },
});

Once we build the tokens again we will get a new tokens-map.scss file withe the following content:

$tokens: (
  'color-primary': #007bff,
  'color-secondary': #6c757d,
  'spacing-none': 0,
  'spacing-small': 0.5rem,
  'spacing-medium': 1rem,
  'typography-font-family-body': Roboto, sans-serif,
  'typography-font-size-base': 1rem,
  'typography-font-size-lg': 1.25rem
);

Map (deep)

We can use the Style Dictionary format scss/map-deep to generate a list of Sass variables and then a nested Sass map that references them.

Again, we can add the new format and destination to our build.js file to then have Style Dictionary create a new .scss file with variables and map.

{
  destination: 'tokens-map-deep.scss',
  format: 'scss/map-deep',  // Deep map format
},

Getting Style Dictionary to generate the various files will now create this new Sass file which would look like this:

$color-primary: #007bff !default;
$color-secondary: #6c757d !default;
$spacing-none: 0 !default;
$spacing-small: 0.5rem !default;
$spacing-medium: 1rem !default;
$typography-font-family-body: Roboto, sans-serif !default;
$typography-font-size-base: 1rem !default;
$typography-font-size-lg: 1.25rem !default;
$tokens: (
  'color': (
    'primary': $color-primary,
    'secondary': $color-secondary
  ),
  'spacing': (
    'none': $spacing-none,
    'small': $spacing-small,
    'medium': $spacing-medium
  ),
  'typography': (
    'font': (
      'family': (
        'body': $typography-font-family-body
      ),
      'size': (
        'base': $typography-font-size-base,
        'lg': $typography-font-size-lg
      )
    )
  )
);

JavaScript and TypeScript

Style Dictionary has 3 JavaScript and 1 TypeScript built-in formats that can be used to generate various forms of JavaScript for various needs and projects.

JavaScript (Object)

Using the format javascript/object will export the tokens as a structured JavaScript object using the hierarchy defined in the Design Tokens. These can be used in your Vue or React projects that make use of direct JavaScript imports. In React, for example, you can import the tokens and apply them directly within a CSS-in-JS solution (like styled-components).

To add a JavaScript format to our existing build.js file we will als need to include a new platform (js) so Style Dictionary knows what to do when generating the code.

js: {
  transformGroup: 'js',
  buildPath: 'build/js/',
  files: [
 {
   destination: 'tokens.js',
   format: 'javascript/object',
 },
  ],
},

This will then generate a JavaScript file of the tokens like this (I've also popped this into a js folder to try to keep the build folder a little cleaner):

var _styleDictionary = {
  "color": {
    "primary": {
      "$value": "#007bff",
      "filePath": "src/tokens/tokens.json",
      "isSource": true,
      "$type": "color",
      "original": {
        "$value": "#007bff",
        "$type": "color"
      },
      "name": "ColorPrimary",
      "attributes": {
        "category": "color",
        "type": "primary"
      },
      "path": [
        "color",
        "primary"
      ]
    },
  // more code followed

JavaScript (Module Flat)

This built-in format creates a file of flat JavaScript objects. This could be great for projects that need to access tokens frequently and directly, without needing to navigate the structure of the Design Tokens to get to it. This flat output may also be better for projects that use a JavaScript bundler. A flat object also aligns more closely with how Design Tokens can be 'directly' in CSS or Sass as Custom Properties and Variables.

Adding the below to the files within our js platform in the build.js file:

{
  destination: 'tokens-flat.js',
  format: 'javascript/module-flat',
}

Will give us the flat JavaScript objects:

module.exports = {
  "ColorPrimary": "#007bff",
  "ColorSecondary": "#6c757d",
  "SpacingNone": "0",
  "SpacingSmall": "0.5rem",
  "SpacingMedium": "1rem",
  "TypographyFontFamilyBody": "Roboto, sans-serif",
  "TypographyFontSizeBase": "1rem",
  "TypographyFontSizeLg": "1.25rem"
};

JavaScript (UMD)

Generating a .js file using this format could allow tokens to be accessed as global variables when CommonJS or AMD imports are not available. This could work well for older or mixed environments where some flexibility is key. This format can be particularly handy in environments that cannot guarantee ES module support.

Adding the new destionation and format:

{ 
  destination: 'tokens-umd.js',
  format: 'javascript/umd',
},

Will generate a JavaScript file that looks like this which includes the Universal Module Definition wrapper to make sure the code inside can be used in multiple environments:

(function(root, factory) {
  if (typeof module === "object" && module.exports) {
    module.exports = factory();
  } else if (typeof exports === "object") {
    exports["_styleDictionary"] = factory();
  } else if (typeof define === "function" && define.amd) {
    define([], factory);
  } else {
    root["_styleDictionary"] = factory();
  }
}(this, function() {
  return {
  "color": {
    "primary": {
      "$value": "#007bff",
      "filePath": "src/tokens/tokens.json",
      "isSource": true,
      "$type": "color",
      "original": {
        "$value": "#007bff",
        "$type": "color"
      },
      "name": "ColorPrimary",
      "attributes": {
        "category": "color",
        "type": "primary"
      },
      "path": [
        "color",
        "primary"
      ]
    },

TypeScript (ES6 Declarations)

This format creates a .d.ts file of your Design Tokens to provide TypeScript definitions so that TypeScript projects can use the tokens with type safety and autocomplete support. This does not output the actual token values but instead provides types, ensuring that TypeScript can recognise and check token names and types within code.

Let's add a new platform for TypeScript to our build.js file to generate the .d.ts file:

ts: {
  transformGroup: 'js',
  buildPath: 'build/types/',
  files: [
 {
   destination: 'tokens.d.ts',
   format: 'typescript/es6-declarations',
 },
  ],
},

This will generate:

export const ColorPrimary : string;
export const ColorSecondary : string;
export const SpacingNone : string;
export const SpacingSmall : string;
export const SpacingMedium : string;
export const TypographyFontFamilyBody : string;
export const TypographyFontSizeBase : string;
export const TypographyFontSizeLg : string;

Android

Using android/resources will generate an XML resource file containing the Design Tokens that follows Android's resource naming conventions.

We will need to define a new platform in our build.js file and add the relevant destination and format so Style Dictionary can generate the XML file correctly:

android: {
  transformGroup: 'android',
  buildPath: 'build/android/',
  files: [
 {
   destination: 'values/tokens.xml',
   format: 'android/resources',
 },
  ],
},

This will generate a file of mixed types within a single <resources> tag for Android development:

<?xml version="1.0" encoding="UTF-8"?>

<resources>
  <color name="color_primary">#ff007bff</color>
  <color name="color_secondary">#ff6c757d</color>
  <string name="spacing_none">0</string>
  <string name="spacing_small">0.5rem</string>
  <string name="spacing_medium">1rem</string>
  <string name="typography_font_family_body">Roboto, sans-serif</string>
  <dimen name="typography_font_size_base">16.00sp</dimen>
  <dimen name="typography_font_size_lg">20.00sp</dimen>
</resources>

iOS / Swift

iOS Swift (class)

This format will create a Swift class file that defines the Design Tokens as static properties which can be directly accessed within iOS code ideal when you need to use Design Tokens as constants throughout the codebase.

Again, we will need to define a new platform in our build.js file for this format:

ios: {
  transformGroup: 'ios-swift',
  buildPath: 'build/ios/',
  files: [
 {
   destination: 'Tokens.swift',
   format: 'ios-swift/class.swift',
   className: 'Tokens', // Name of the Swift class
 },
  ],
},

When run the build.js file will then create a new file in build/ios/ called Tokens.swift with the following:

import UIKit

public class {
    public static let colorPrimary = UIColor(red: 0.000, green: 0.482, blue: 1.000, alpha: 1)
    public static let colorSecondary = UIColor(red: 0.424, green: 0.459, blue: 0.490, alpha: 1)
    public static let spacingMedium = 1rem
    public static let spacingNone = 0
    public static let spacingSmall = 0.5rem
    public static let typographyFontFamilyBody = Roboto, sans-serif
    public static let typographyFontSizeBase = CGFloat(16.00)
    public static let typographyFontSizeLg = CGFloat(20.00)
}

Going through the above built-in formats only shows an example of what is possible 'out of the box'. There are also built-in formats for the Less and Stylus CSS preprocessors, for various outputs of JSON, and a few more options for iOS and Swift.

Having all these options means you have the ability to push your Design Tokens across teams, projects, and platforms and create consistency and trust in your products. Using Design Tokens as a source of truth for your design decisions can also help streamline development and updates.

These are 'built-in' formats which means we can also create our own custom formats, for example, with scss/map-deep I would want a separate .scss file for my Sass variables and then have the map in a different file rather than a single file with both.

While Style Dictionary’s built-in formats cover a wide range, customisation is often essential.

In a future article, we’ll look into how to create custom formats tailored to your unique needs. Whether you need to separate variables from maps in Sass or define specialised token structures, custom formats will allow you to adapt Style Dictionary even further to fit your project.

• #Css
• #Sass
• #Designsystems
• #Designtokens
• #Styledictionary