Built-in formats

These are the formats included in Style Dictionary by default, pulled from lib/common/formats.js

You created a format and think it should be included? Send us a PR.

css/variables

Creates a CSS file with variable definitions based on the style dictionary

Param	Type	Description
`options`	`Object`
`options.showFileHeader`	`boolean`	Whether or not to include a comment that has the build date. Defaults to `true`
`options.outputReferences`	`boolean \| OutputReferencesFunction`	Whether or not to keep references (a -> b -> c) in the output. Defaults to `false`. Also allows passing a function to conditionally output references on a per token basis.
`options.outputReferenceFallbacks`	`boolean`	Whether or not to output css variable fallback values when using output references. You will want to pass this from the `options` object sent to the format function.
`options.selector`	`string \| string[]`	Override the root CSS selector. When a string array is provided, the styles will be nested within the specified selectors in order - the first selector in the array acts as the outermost layer.
`options.formatting`	`FormattingOverrides`	Custom formatting properties that define parts of a declaration line in code. The configurable strings are: `indentation`, `commentStyle` and `commentPosition`. The `fileHeaderTimestamp`, `header`, and `footer` formatting options are used for the fileHeader helper.

Example:

:root {
  --color-background-base: #f0f0f0;
  --color-background-alt: #eeeeee;
}

scss/map-flat

Creates a SCSS file with a flat map based on the style dictionary

Name the map by adding a mapName property on the options object property on the file object property in your config.

Example:

$tokens: (
  'color-background-base': #f0f0f0; 'color-background-alt': #eeeeee;,
);

scss/map-deep

Creates a SCSS file with a deep map based on the style dictionary.

Name the map by adding a mapName property on the options object property on the file object property in your config.

Param	Type	Description
`options`	`Object`
`options.outputReferences`	`boolean \| OutputReferencesFunction`	Whether or not to keep references (a -> b -> c) in the output. Defaults to `false`. Also allows passing a function to conditionally output references on a per token basis.
`options.outputReferenceFallbacks`	`boolean`	Whether or not to output css variable fallback values when using output references. You will want to pass this from the `options` object sent to the format function.
`options.themeable`	`boolean`	Whether or not tokens should default to being themeable, if not otherwise specified per token. Defaults to `false`.
`options.mapName`	`string`	Name of your SCSS map.
`options.formatting`	`FormattingOverrides`	Custom formatting properties that define parts of a declaration line in code. The configurable strings are: `indentation`, `commentStyle` and `commentPosition`. The `fileHeaderTimestamp`, `header`, and `footer` formatting options are used for the fileHeader helper.

Example:

$color-background-base: #f0f0f0 !default;
$color-background-alt: #eeeeee !default;

$tokens: (
  'color': (
    'background': (
      'base': $color-background-base,
      'alt': $color-background-alt,
    ),
  ),
);

scss/variables

Creates a SCSS file with variable definitions based on the style dictionary.

Add !default to any variable by setting a themeable: true attribute in the token’s definition.

Param	Type	Description
`options`	`Object`
`options.showFileHeader`	`boolean`	Whether or not to include a comment that has the build date. Defaults to `true`
`options.outputReferences`	`boolean \| OutputReferencesFunction`	Whether or not to keep references (a -> b -> c) in the output. Defaults to `false`. Also allows passing a function to conditionally output references on a per token basis.
`options.outputReferenceFallbacks`	`boolean`	Whether or not to output css variable fallback values when using output references. You will want to pass this from the `options` object sent to the format function.
`options.themeable`	`boolean`	Whether or not tokens should default to being themeable, if not otherwise specified per token. Defaults to `false`.
`options.formatting`	`FormattingOverrides`	Custom formatting properties that define parts of a declaration line in code. The configurable strings are: `indentation`, `commentStyle` and `commentPosition`. The `fileHeaderTimestamp`, `header`, and `footer` formatting options are used for the fileHeader helper.

Example:

$color-background-base: #f0f0f0;
$color-background-alt: #eeeeee !default;

scss/icons

Creates a SCSS file with variable definitions and helper classes for icons

Example:

$content-icon-email: '\E001';
.icon.email:before {
  content: $content-icon-email;
}

less/variables

Creates a LESS file with variable definitions based on the style dictionary

Param	Type	Description
`options`	`Object`
`options.showFileHeader`	`boolean`	Whether or not to include a comment that has the build date. Defaults to `true`
`options.outputReferences`	`boolean \| OutputReferencesFunction`	Whether or not to keep references (a -> b -> c) in the output. Defaults to `false`. Also allows passing a function to conditionally output references on a per token basis.
`options.outputReferenceFallbacks`	`boolean`	Whether or not to output css variable fallback values when using output references. You will want to pass this from the `options` object sent to the format function.
`options.formatting`	`FormattingOverrides`	Custom formatting properties that define parts of a declaration line in code. The configurable strings are: `indentation`, `commentStyle` and `commentPosition`. The `fileHeaderTimestamp`, `header`, and `footer` formatting options are used for the fileHeader helper.

Example:

@color-background-base: #f0f0f0;
@color-background-alt: #eeeeee;

less/icons

Creates a LESS file with variable definitions and helper classes for icons

Example:

@content-icon-email: '\E001';
.icon.email:before {
  content: @content-icon-email;
}

stylus/variables

Creates a Stylus file with variable definitions based on the style dictionary

Example:

$color-background-base= #f0f0f0;
$color-background-alt= #eeeeee;

javascript/module

Creates a CommonJS module with the whole style dictionary

Example:

module.exports = {
  color: {
    base: {
      red: {
        value: '#ff0000',
      },
    },
  },
};

javascript/module-flat

Creates a CommonJS module with the whole style dictionary flattened to a single level.

Example:

module.exports = {
  ColorBaseRed: '#ff0000',
};

javascript/object

Creates a JS file a global var that is a plain javascript object of the style dictionary. Name the variable by adding a name property on the options object property of the file object property in your config.

Example:

var StyleDictionary = {
  color: {
    base: {
      red: {
        value: '#ff0000',
      },
    },
  },
};

javascript/umd

Creates a UMD module of the style dictionary. Name the module by adding a name property on the options object property of the file object property in your config.

Example

(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: {
      red: {
        value: '#FF0000',
      },
    },
  };
});

javascript/es6

Creates a ES6 module of the style dictionary.

{
  "platforms": {
    "js": {
      "transformGroup": "js",
      "files": [
        {
          "format": "javascript/es6",
          "destination": "colors.js",
          "filter": {
            "type": "color"
          }
        }
      ]
    }
  }
}

Example:

export const ColorBackgroundBase = '#ffffff';
export const ColorBackgroundAlt = '#fcfcfcfc';

javascript/esm

Creates an ES6 module object of the style dictionary.

{
  "platforms": {
    "js": {
      "transformGroup": "js",
      "files": [
        {
          "format": "javascript/esm",
          "destination": "colors.js",
          "options": {
            "minify": true
          }
        }
      ]
    }
  }
}

Param	Type	Description
`options`	`Object`
`options.minify`	`boolean`	Whether or not to minify the output. Defaults to `false`. Has no effect when `options.flat` is `true`.
`options.flat`	`boolean`	Whether or not to flatten the output. Defaults to `false`. If `true`, renders only the token value, which means it is minified.
`options.stripMeta`	`Object \| boolean`	Control whether meta data is stripped from the output tokens. `false` by default. If set to `true`, will strip known Style Dictionary meta props: `['attributes', 'filePath', 'name', 'path', 'comment']`. Note that using minify means that meta is stripped as a side effect of this already, so using both is unnecessary.
`options.stripMeta.keep`	`string[]`	Array of property keys to keep in the output.
`options.stripMeta.strip`	`string[]`	Array of property keys to strip from the output.

Example:

export default {
  colors: {
    black: {
      $value: '#000000',
      filePath: 'src/tokens/color.json',
      isSource: true,
      $type: 'color',
      original: {
        $value: '#000000',
        $type: 'color',
      },
      name: 'ColorsBlack',
      attributes: {
        category: 'colors',
        type: 'black',
      },
      path: ['colors', 'black'],
    },
  },
};

Example with minify flag:

export default {
  colors: {
    black: '#000000',
  },
};

Example with stripMeta flag:

export default {
  colors: {
    black: {
      $value: '#000000',
      $type: 'color',
    },
  },
};

typescript/es6-declarations

Creates TypeScript declarations for ES6 modules

{
  "platforms": {
    "ts": {
      "transformGroup": "js",
      "files": [
        {
          "format": "javascript/es6",
          "destination": "colors.js"
        },
        {
          "format": "typescript/es6-declarations",
          "destination": "colors.d.ts"
        }
      ]
    }
  }
}

Param	Type	Description
`options`	`Object`
`options.outputStringLiterals`	`boolean`	Whether or not to output literal types for string values. Defaults to `false`.

Example:

export const ColorBackgroundBase: string;
export const ColorBackgroundAlt: string;

typescript/module-declarations

Creates TypeScript declarations for module

{
  "platforms": {
    "ts": {
      "transformGroup": "js",
      "files": [
        {
          "format": "javascript/module",
          "destination": "colors.js"
        },
        {
          "format": "typescript/module-declarations",
          "destination": "colors.d.ts"
        }
      ]
    }
  }
}

Example:

export default tokens;
declare interface DesignToken {
  value?: any;
  type?: string;
  name?: string;
  comment?: string;
  themeable?: boolean;
  attributes?: Record<string, unknown>;
  [key: string]: any;
}
declare const tokens: {
  color: {
    red: DesignToken;
  };
};

As you can see above example output this does not generate 100% accurate d.ts. This is a compromise between of what style-dictionary can do to help and not bloating the library with rarely used dependencies.

Thankfully you can extend style-dictionary very easily:

import JsonToTS from 'json-to-ts';

StyleDictionaryPackage.registerFormat({
  name: 'typescript/accurate-module-declarations',
  format: function ({ dictionary }) {
    return (
      'declare const root: RootObject\n' +
      'export default root\n' +
      JsonToTS(dictionary.tokens).join('\n')
    );
  },
});

android/resources

Creates a resource xml file. It is recommended to use a filter with this format as it is generally best practice in Android development to have resource files organized by type (color, dimension, string, etc.). However, a resource file with mixed resources will still work.

This format will try to use the proper resource type for each token based on the category (color => color, size => dimen, etc.). However if you want to force a particular resource type you can provide a resourceType property on the options object property on the file object property configuration. You can also provide a resourceMap if you don’t use Style Dictionary’s built-in CTI structure.

Param	Type	Description
`options`	`Object`
`options.showFileHeader`	`boolean`	Whether or not to include a comment that has the build date. Defaults to `true`
`options.outputReferences`	`boolean \| OutputReferencesFunction`	Whether or not to keep references (a -> b -> c) in the output. Defaults to `false`. Also allows passing a function to conditionally output references on a per token basis.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<resources>
 <color name="color_base_red_5">#fffaf3f2</color>
 <color name="color_base_red_30">#fff0cccc</color>
 <dimen name="size_font_base">14sp</color>