Style Dictionary

Style Dictionary

Overview

Style Dictionary is the standard build system for transforming design tokens into platform-specific outputs — CSS custom properties, SCSS variables, iOS/Android constants, Kotlin Compose themes, and more. Version 4 adds native W3C DTCG support, ESM configuration, async transforms, and browser compatibility.

How It Works

Token source files (.tokens.json)
        │
        ▼
  ┌──────────┐
  │  Parse    │  Deep-merge all source files
  └────┬─────┘
       ▼
  ┌──────────┐
  │ Transform │  Name, value, and attribute transforms per platform
  └────┬─────┘
       ▼
  ┌──────────┐
  │  Format   │  Serialize into platform file format
  └────┬─────┘
       ▼
  Platform outputs (CSS, SCSS, JSON, Swift, Kotlin, etc.)

Configuration

// style-dictionary.config.mjs
import StyleDictionary from "style-dictionary";

const sd = new StyleDictionary({
  source: ["tokens/**/*.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",
        },
      ],
    },
    ios: {
      transformGroup: "ios-swift",
      buildPath: "build/ios/",
      files: [
        {
          destination: "DesignTokens.swift",
          format: "ios-swift/class.swift",
          className: "DesignTokens",
        },
      ],
    },
    android: {
      transformGroup: "android",
      buildPath: "build/android/",
      files: [
        {
          destination: "tokens.xml",
          format: "android/resources",
        },
      ],
    },
  },
});

await sd.buildAllPlatforms();

Build Commands

# Build all platforms
npx style-dictionary build --config style-dictionary.config.mjs

# Build a single platform
npx style-dictionary build --config style-dictionary.config.mjs --platform css

Transforms

Transforms modify tokens for a specific platform. Three types:

Transform Groups

Built-in groups bundle common transforms:

Formats

Formats serialize transformed tokens into output files:

Custom Transform

import StyleDictionary from "style-dictionary";

StyleDictionary.registerTransform({
  name: "size/pxToRem",
  type: "value",
  filter: (token) => token.$type === "dimension",
  transform: (token) => {
    const val = parseFloat(token.value);
    return `${val / 16}rem`;
  },
});

Custom Format

StyleDictionary.registerFormat({
  name: "css/tailwind",
  format: ({ dictionary }) => {
    const tokens = dictionary.allTokens
      .map((t) => `  "${t.name}": "${t.value}"`)
      .join(",\n");
    return `module.exports = {\n${tokens}\n};\n`;
  },
});

Filtering Tokens

Filter which tokens appear in a specific output file:

{
  destination: "colors.css",
  format: "css/variables",
  filter: (token) => token.$type === "color",
}

DTCG Support (v4)

Style Dictionary v4 natively reads W3C DTCG tokens ($value, $type, $description):

{
  "color": {
    "$type": "color",
    "primary": { "$value": "#3b82f6" },
    "secondary": { "$value": "{color.primary}" }
  }
}

SD resolves $type inheritance from parent groups and resolves {alias} references automatically.

Token References in Output

// Preserve references in CSS output
{
  destination: "variables.css",
  format: "css/variables",
  options: {
    outputReferences: true,  // --color-secondary: var(--color-primary)
  },
}

Multi-Theme Builds

Build separate files per theme by pointing to different source sets:

const themes = ["light", "dark"];

const configs = themes.map((theme) => ({
  source: [`tokens/global/**/*.tokens.json`, `tokens/themes/${theme}/**/*.tokens.json`],
  platforms: {
    css: {
      transformGroup: "css",
      buildPath: `build/css/${theme}/`,
      files: [{ destination: "variables.css", format: "css/variables" }],
    },
  },
}));

for (const config of configs) {
  const sd = new StyleDictionary(config);
  await sd.buildAllPlatforms();
}

Best Practices

• Use DTCG-format tokens ($value, $type) as input — Style Dictionary v4 supports them natively.
• Use outputReferences: true in CSS/SCSS to preserve the alias chain as var() references — this enables runtime theming.
• Use filter on files to split outputs by token type (colors, typography, spacing) for tree-shaking.
• Register custom transforms for project-specific needs (px → rem, color space conversions).
• Run Style Dictionary in CI to ensure token → platform output is always in sync.
• Use the CTI naming convention (color.brand.primary) for predictable transform behavior.
• Pin to Style Dictionary v4+ for ESM, async transforms, and DTCG support.