Skip to content

API

new StyleDictionary()

Create a new StyleDictionary instance.

ParamTypeDescription
configConfigConfiguration options to build your style dictionary. If you pass a string, it will be used as a path to a JSON config file. You can also pass an object with the configuration.
optionsObjectOptions object when creating a new StyleDictionary instance.
options.initbooleantrue by default but can be disabled to delay initializing the dictionary. You can then call sdInstance.init() yourself, e.g. for testing or error handling purposes.
options.verbosity'silent'|'default'|'verbose'Verbosity of logs, overrides log.verbosity set in SD config or platform config.
options.warnings'error'|'warn'|'disabled'Whether to throw warnings as errors, warn or disable warnings, overrides log.verbosity set in SD config or platform config.
options.volumeimport('memfs').IFs | typeof import('node:fs')FileSystem Volume to use as an alternative to the default FileSystem, handy if you need to isolate or “containerise” StyleDictionary files

Example:

build-tokens.js
import StyleDictionary from 'style-dictionary';
const sd = new StyleDictionary('config.json');
const sdTwo = new StyleDictionary({
source: ['tokens/*.json'],
platforms: {
scss: {
transformGroup: 'scss',
buildPath: 'build/',
files: [
{
destination: 'variables.scss',
format: 'scss/variables',
},
],
},
// ...
},
});

Using volume option:

build-tokens.js
import { Volume } from 'memfs';
// You will need a bundler like webpack/rollup for memfs in browser...
// Or use as a prebundled fork:
import memfs from '@bundled-es-modules/memfs';
const { Volume } = memfs;
const vol = new Volume();
const sd = new StyleDictionary(
{
tokens: {
colors: {
red: {
value: '#FF0000',
type: 'color',
},
},
},
platforms: {
css: {
transformGroup: 'css',
files: [
{
destination: 'variables.css',
format: 'css/variables',
},
],
},
},
},
{ volume: vol },
);
await sd.buildAllPlatforms();
vol.readFileSync('/variables.css');
/**
* :root {
* --colors-red: #FF0000;
* }
*/

Instance methods

init

type init = (config: Config)Promise<SDInstance>

Called automatically when doing new StyleDictionary(config) unless passing a second argument with init property set to false. In this scenario, you can call .init() manually, e.g. for testing or error handling purposes.

ParamTypeDescription
initConfigObjectInit configuration options.
initConfig.verbosity'silent'|'default'|'verbose'Verbosity of logs, overrides log.verbosity set in SD config or platform config.
initConfig.warnings'error'|'warn'|'disabled'Whether to throw warnings as errors, warn or disable warnings, overrides log.verbosity set in SD config or platform config.

extend

type extend = (config: Config | string, options: Options)Promise<SDInstance>

Extend a Style Dictionary instance with a config object, to create an extension instance.

ParamTypeDescription
configConfigConfiguration options to build your style dictionary. If you pass a string, it will be used as a path to a JSON config file. You can also pass an object with the configuration.
optionsObject
options.verbosity'silent'|'default'|'verbose'Verbosity of logs, overrides log.verbosity set in SD config or platform config.
options.warnings'error'|'warn'|'disabled'Whether to throw warnings as errors, warn or disable warnings, overrides log.verbosity set in SD config or platform config.
options.volumeimport('memfs').IFs | typeof import('node:fs')Pass a custom Volume to use instead of filesystem shim itself. Only possible in browser or in Node if you’re explicitly using memfs as filesystem shim (by calling setFs() function and setting it to the memfs module)
options.mutateOriginalbooleanPrivate option, do not use

Example:

build-tokens.js
import StyleDictionary from 'style-dictionary';
const sd = new StyleDictionary('config.json');
const sdExtended = await sd.extend({
source: ['tokens/*.json'],
platforms: {
scss: {
transformGroup: 'scss',
buildPath: 'build/',
files: [
{
destination: 'variables.scss',
format: 'scss/variables',
},
],
},
// ...
},
});

Volume option also works when using extend:

const extendedSd = await sd.extend(cfg, { volume: vol });

getPlatformTokens

Replaces the deprecated exportPlatform method, with a slightly different (expanded) return value

type getPlatformTokens = (platform: string, opts: { cache?: boolean }) => Promise<Dictionary>;

Exports a dictionary object containing the tokens as object or flat array, after platform specific transformations and reference resolutions.

ParamTypeDescription
platformstringThe platform to be exported. Must be defined on the style dictionary.
opts{ cache?: boolean }cache prop determines whether or not it should return the cached tokens if they’ve already been transformed/resolved earlier for this platform. false by default

getPlatformConfig

Replaces the deprecated getPlatform method, returns just the PlatformConfig, use getPlatformTokens if you need the Dictionary

type getPlatformConfig = (platform: string, opts: { cache?: boolean }) => Promise<PlatformConfig>;

Returns a processed version of the user config for the platform.

ParamTypeDescription
platformstringThe platform to be exported. Must be defined on the style dictionary.
opts{ cache?: boolean }cache prop determines whether or not it should return the cached tokens if they’ve already been transformed/resolved earlier for this platform. false by default

formatPlatform

type formatPlatform = (
platform: string,
opts: { cache?: boolean },
) => Promise<Array<{ output: unknown; destination?: string }>>;
ParamTypeDescription
platformstringName of the platform you want to build.
opts{ cache?: boolean }cache prop determines whether or not it should reuse the cached tokens/config if they’ve already been processed earlier for this platform. false by default

Runs getPlatform under the hood, and then loops over the files, and formats the dictionary for each file, returning an array of file objects:

  • output property, which is usually a string but depending on the format, it could also be any other data type. This is useful if you don’t intend to write to a file, but want to do something else with the formatted tokens.
  • destination property, this one is optional, if you don’t intend on writing to a file you don’t need this, but it can still be useful to name your outputs if you’ve got multiple files.

formatAllPlatforms

type formatAllPlatforms = (opts: {
cache?: boolean;
}) => Promise<Record<string, Array<{ output: unknown; destination?: string }>>>;
ParamTypeDescription
opts{ cache?: boolean }cache prop determines whether or not it should reuse the cached tokens/config if they’ve already been processed earlier for this platform. false by default

Runs formatPlatform under the hood but for each platform.

The resulting object is similar, but an Object with key-value pairs where they key is the platform key, and the value is the same data from the formatPlatform method.

This is useful if you don’t want to write to the filesystem but want to do something custom with the data instead.


buildPlatform

type buildPlatform = (platform: string, opts: { cache?: boolean }) => Promise<SDInstance>;

Takes a platform and performs all transforms to the tokens object (non-mutative) then builds all the files and performs any actions. This is useful if you only want to build the artifacts of one platform to speed up the build process.

This method is also used internally in buildAllPlatforms to build each platform defined in the config.

ParamTypeDescription
platformstringName of the platform you want to build.
opts{ cache?: boolean }cache prop determines whether or not it should reuse the cached tokens/config if they’ve already been processed earlier for this platform. false by default

Example:

build-web.js
// Async, so you can do `await` or .then() if you
// want to execute code after buildAllPlatforms has completed
await sd.buildPlatform('web');
Terminal window
style-dictionary build --platform web

buildAllPlatforms

type buildAllPlatforms = (opts: { cache?: boolean }) => Promise<SDInstance>;

Uses buildPlatform under the hood for each platform.

ParamTypeDescription
opts{ cache?: boolean }cache prop determines whether or not it should reuse the cached tokens/config if they’ve already been processed earlier for this platform. false by default

Example:

import StyleDictionary from 'style-dictionary';
const sd = new StyleDictionary('config.json');
// Async, so you can do `await` or .then() if you
// want to execute code after buildAllPlatforms has completed
await sd.buildAllPlatforms();
Terminal window
style-dictionary build

cleanPlatform

type cleanPlatform = (platform: string, opts: { cache?: boolean }) => Promise<SDInstance>;

Takes a platform and performs all transforms to the tokens object (non-mutative) then cleans all the files and performs the undo method of any actions.

ParamTypeDescription
platformstringName of the platform you want to clean.
opts{ cache?: boolean }cache prop determines whether or not it should reuse the cached tokens/config if they’ve already been processed earlier for this platform. false by default

cleanAllPlatforms

type cleanAllPlatforms = (opts: { cache?: boolean }) => Promise<SDInstance>;

Uses cleanPlatform under the hood for each platform.

Does the reverse of buildAllPlatforms by performing a clean on each platform. This removes all the files defined in the platform and calls the undo method on any actions.

ParamTypeDescription
opts{ cache?: boolean }cache prop determines whether or not it should reuse the cached tokens/config if they’ve already been processed earlier for this platform. false by default

Deprecated instance methods

  • For exportPlatform, use getPlatformTokens instead, turning off the cache option if needed.
  • For getPlatform, use getPlatformConfig insetad, turning off the cache option if needed.

exportPlatform

type exportPlatform = (platform: string, opts: { cache?: boolean }) => Promise<DesignTokens>;

Exports a tokens object with applied platform transforms.

This is useful if you want to use a Style Dictionary in JS build tools like Webpack.

ParamTypeDescription
platformstringName of the platform you want to build.
opts{ cache?: boolean }cache prop determines whether or not it should reuse the cached tokens/config if they’ve already been processed earlier for this platform. false by default

getPlatform

type getPlatform = (
platform: string,
opts: { cache?: boolean },
) => Promise<{
platformConfig: PlatformConfig;
dictionary: {
tokens: DesignTokens;
allTokens: DesignToken[];
};
}>;

SDInstance.getPlatform(platform) ⇒ Promise<Object>

Wrapper around exportPlatform, returns a bit more data.

Returns an object with platformConfig and dictionary properties:

  • platformConfig a processed version of the user config for the platform
  • dictionary an object with tokens after transformations and reference resolutions, and an allTokens property which is a flattened (Array) version of that.

This is useful if you want to use a Style Dictionary in JS build tools like Webpack.

ParamTypeDescription
platformstringName of the platform you want to build.
opts{ cache?: boolean }cache prop determines whether or not it should reuse the cached tokens/config if they’ve already been processed earlier for this platform. false by default

Class methods

registerAction

StyleDictionary.registerAction(action) ⇒ StyleDictionary

Adds a custom action to Style Dictionary. Custom actions can do whatever you need, such as: copying files, base64’ing files, running other build scripts, etc. After you register a custom action, you then use that action in a platform your config.json

You can perform operations on files generated by the style dictionary as actions run after these files are generated. Actions are run sequentially, if you write synchronous code then it will block other actions, or if you use asynchronous code like Promises it will not block.

ParamTypeDescription
actionObject
action.namestringThe name of the action
action.dofunctionThe action in the form of a function. Can be async
action.undofunctionA function that undoes the action. Can be async

Example:

StyleDictionary.registerAction({
name: 'copy_assets',
do: async function (dictionary, config) {
console.log('Copying assets directory');
await fs.promises.copy('assets', config.buildPath + 'assets');
},
undo: async function (dictionary, config) {
console.log('Cleaning assets directory');
await fs.promises.remove(config.buildPath + 'assets');
},
});

registerFileHeader

StyleDictionary.registerFileHeader(fileHeader) ⇒ StyleDictionary

Add a custom fileHeader to the Style Dictionary. File headers are used in formats to display some information about how the file was built in a comment.

ParamTypeDescription
optionsObject
options.namestringName of the format to be referenced in your config.json
options.fileHeaderfunctionFunction that returns an array of strings, which will be mapped to comment lines. It takes a single argument which is the default message array. See file headers for more information. Can be async.

Example:

StyleDictionary.registerFileHeader({
name: 'myCustomHeader',
fileHeader: function (defaultMessage) {
return [...defaultMessage, `hello, world!`];
},
});

registerFilter

StyleDictionary.registerFilter(filter) ⇒ StyleDictionary

Add a custom filter to the Style Dictionary.

ParamTypeDescription
FilterObject
Filter.namestringName of the filter to be referenced in your config.json
Filter.filterfunctionFilter function, return boolean if the token should be included. Can be async

Example:

StyleDictionary.registerFilter({
name: 'isColor',
filter: function (token) {
return token.type === 'color';
},
});

registerFormat

StyleDictionary.registerFormat(format) ⇒ StyleDictionary

Add a custom format to the Style Dictionary.

ParamTypeDescription
formatObject
format.namestringName of the format to be referenced in your config.json
format.formatfunctionFunction to perform the format. Takes a single argument. See creating custom formats Must return a string, which is then written to a file. Can be async

Example:

StyleDictionary.registerFormat({
name: 'json',
format: function ({ dictionary, platform, options, file }) {
return JSON.stringify(dictionary.tokens, null, 2);
},
});

registerParser

StyleDictionary.registerParser(parser) ⇒ StyleDictionary

Adds a custom parser to parse style dictionary files.

ParamTypeDescription
Parser.namestringName of the parser to be referenced in your config.json
Parser.patternRegexA file path regular expression to match which files this parser should be be used on. This is similar to how webpack loaders work. /\.json$/ will match any file ending in ‘.json’, for example.
Parser.parserfunctionFunction to parse the file contents. Takes 1 argument, which is an object with 2 properties: contents wich is the string of the file contents and filePath. The function should return a plain JavaScript object. Can be async.

Example:

StyleDictionary.registerParser({
name: 'json-parser',
pattern: /\.json$/,
parser: ({ contents, filePath }) => {
return JSON.parse(contents);
},
});

registerPreprocessor

StyleDictionary.registerPreprocessor({ name, preprocessor }) => StyleDictionary

Adds a custom preprocessor to preprocess already parsed Style Dictionary objects.

ParamTypeDescription
PreprocessorObject
Preprocessor.namestringName of the format to be referenced in your config.json
Preprocessor.preprocessorfunctionFunction to preprocess the dictionary. The function should return a plain Javascript object. Can be async

Example:

StyleDictionary.registerPreprocessor({
name: 'strip-third-party-meta',
preprocessor: (dictionary) => {
delete dictionary.thirdPartyMetadata;
return dictionary;
},
});

registerTransform

StyleDictionary.registerTransform(transform) ⇒ StyleDictionary

Add a custom transform to the Style Dictionary. Transforms can manipulate a token’s name, value, or attributes.

ParamTypeDescription
transformObjectTransform object
transform.typestringType of transform, can be: name, attribute, or value
transform.namestringName of the transform (used by transformGroup to call a list of transforms).
transform.transitivebooleanIf the value transform should be applied transitively, i.e. should be applied to referenced values as well as absolute values.
transform.filterfunctionFilter function, return boolean if transform should be applied. If you omit the filter function, it will match all tokens.
transform.transformfunctionModifies a design token object. The transform function will receive the token and the platform configuration as its arguments. The transform function should return a string for name transforms, an object for attribute transforms, and same type of value for a value transform. Can be async.

Example:

StyleDictionary.registerTransform({
name: 'time/seconds',
type: 'value',
filter: function (token) {
return token.type === 'time';
},
transform: function (token) {
// Note the use of prop.original.value,
// before any transforms are performed, the build system
// clones the original token to the 'original' attribute.
return (parseInt(token.original.value) / 1000).tostring() + 's';
},
});

registerTransformGroup

StyleDictionary.registerTransformGroup(transformGroup) ⇒ StyleDictionary

Add a custom transformGroup to the Style Dictionary, which is a group of transforms.

ParamTypeDescription
transformGroupObject
transformGroup.namestringName of the transform group that will be referenced in config.json
transformGroup.transformsstring[]Array of strings that reference the name of transforms to be applied in order. Transforms must be defined and match the name or there will be an error at build time.

Example:

StyleDictionary.registerTransformGroup({
name: 'Swift',
transforms: ['attribute/cti', 'size/pt', 'name'],
});