Style Dictionary

While not required, organizing tokens in a hierarchical tree structure (Category $\rightarrow$ Type $\rightarrow$ Item) provides consistent naming and enables powerful helpers.

For example, a structure like size.font.base implicitly defines:

• Category: size
• Type: font
• Item: base

Using this structure allows you to use the 'attribute/cti' transform to automatically add attributes to tokens based on their object path, which can then be used for filtering or further transformations.

{
  "size": {
    "font": {
      "base": { "value": "16" },
      "large": { "value": "20" }
    }
  }
}

You can register a preprocessor using one of two methods:

1. Using .registerPreprocessor: Call this method on the StyleDictionary class to make the preprocessor available globally.
2. Inline in configuration: Define the preprocessor directly within the hooks.preprocessors property of your configuration object.

// Method 1: .registerPreprocessor
import StyleDictionary from 'style-dictionary';
StyleDictionary.registerPreprocessor(myPreprocessor);

// Method 2: Inline in config
export default {
  hooks: {
    preprocessors: {
      'strip-props': myPreprocessor,
    },
  },
  // ... the rest of the configuration
};

Style Dictionary is configuration-driven. A complete package must include a configuration file and a reference to a path containing design token files. You may optionally include an assets directory to maintain a single source of truth for files like images, vectors, or fonts.

Required components:

• Configuration file: Typically config.json, where you define the execution logic.
• Design token files: A collection of JSON or JS module files. The location of these files must be specified in the source attribute of your configuration file.

Optional components:

• Assets: A directory for managing non-token files (e.g., fonts, images) within the same package.

- config.json
- tokens
  - size
    - font.json
  - color
    - font.json
- assets
  - fonts
  - images

Version 4 removes the heavy reliance on CTI (Category/Type/Item) structure. Instead of relying on attributes.category (often set via the attribute/cti transform), Style Dictionary now looks for a token.type property to determine token types. This aligns with the Design Tokens Community Group specification.

Example Token Structure:

{
  "color": {
    "red": {
      "value": "#FF0000",
      "type": "color"
    }
  }
}

Transform Changes:

• Built-in name transforms are now reliant only on the token path and have been renamed from name/cti/[casing] to name/[casing]. (e.g., name/cti/kebab becomes name/kebab).
• content/icon is renamed to html/icon.
• font/[platform]/literal transforms are replaced by content/[platform]/literal (e.g., content/objC/literal).

Inside a transitive transform's transform function, you can defer the transformation to a later cycle of reference resolution by returning undefined. This is useful when the transformation depends on a property that is itself a reference and hasn't been resolved yet. Use the usesReferences utility from style-dictionary/utils to check if a property contains a reference.

import { StyleDictionary } from 'style-dictionary';
import { usesReferences } from 'style-dictionary/utils';

StyleDictionary.registerTransform({
  name: 'my-deferred-transform',
  type: 'value',
  transitive: true,
  transform: (token) => {
    const darkenModifier = token.darken;
    if (usesReferences(darkenModifier)) {
      // defer this transform, because our darken value is a reference
      return undefined;
    }
    return darken(token.value, darkenModifier);
  },
});

From version 4 onwards, Style Dictionary determines a token's type using the token.type property or the $type property (for DTCG spec format). This replaces the version 3 CTI structure where type was determined via token.attributes.category.

If you use a custom token structure that does not follow the standard CTI (Category, Type, Item) or DTCG formats, you must write custom transforms or ensure the proper attributes are present on your tokens.

Install style-dictionary as a development dependency since it is a build tool.

npm install -D style-dictionary

Design tokens are the primary input for Style Dictionary. You can define them using the original Style Dictionary format or the Design Token Community Group (DTCG) spec.

Important: In version 4 and later, you can use either format, but you cannot combine them within a single Style Dictionary instance.

• Style Dictionary format: Uses value, type, and comment.
• DTCG format: Uses $value, $type, and $description.

A design token is identified as any node in your JSON object that contains a value (or $value) attribute.

// Style Dictionary format
{
  "colors": {
    "font": {
      "base": { "value": "#111111", "type": "color" }
    }
  }
}

// DTCG format
{
  "colors": {
    "$type": "color",
    "font": {
      "base": { "$value": "#111111" }
    }
  }
}

You can use both transformGroup and transforms within the same platform configuration. When doing so, the standalone transforms are applied after the transforms contained within the transformGroup.

If you require a specific execution order that differs from this (where standalone transforms always follow the group), you should register a custom transform group instead of combining them.

{
  "source": ["tokens/**/*.json"],
  "platforms": {
    "android": {
      "transformGroup": "android",
      "transforms": ["name/snake"]
    }
  }
}