Style Dictionary

5.4.0 · active · verified Tue Apr 21

Style Dictionary is a powerful build system for creating and managing design tokens across multiple platforms and technologies. It allows developers and designers to define styles once using a single source of truth, typically JSON-based design tokens, and then automatically generate platform-specific assets such as CSS variables, Sass maps, iOS `.h`/`.m` files, Android XML resources, and JavaScript objects. The current stable version is 5.4.0, with frequent patch and minor releases, often adding support for the latest Design Token Community Group (DTCG) specification drafts. Its key differentiator is its highly configurable transformation and formatting pipeline, enabling extensive customization for diverse output requirements across web, iOS, and Android ecosystems. It's designed to streamline design system implementation by ensuring consistency and reducing manual synchronization efforts, thereby solving errors, roadblocks, and workflow inefficiencies.

Common errors

Warnings

Install

Imports

Quickstart

This quickstart demonstrates how to programmatically define design tokens, configure Style Dictionary, and build platform-specific output files like CSS variables and ES Modules JavaScript. It highlights the asynchronous nature of `extend` and `build` methods introduced in v4.

import StyleDictionary from 'style-dictionary';
import fs from 'fs';
import path from 'path';

// 1. Define your design tokens (e.g., in tokens/colors.json)
const tokens = {
  "color": {
    "brand": {
      "primary": { "value": "#007bff" },
      "secondary": { "value": "#6c757d" }
    }
  },
  "size": {
    "font": {
      "base": { "value": "16px" },
      "large": { "value": "24px" }
    }
  }
};

// Create a tokens directory and write the tokens file if it doesn't exist
const tokensDir = path.resolve(process.cwd(), 'tokens');
const tokensFilePath = path.join(tokensDir, 'colors.json');
if (!fs.existsSync(tokensDir)) {
  fs.mkdirSync(tokensDir, { recursive: true });
}
fs.writeFileSync(tokensFilePath, JSON.stringify(tokens, null, 2));

// 2. Define your Style Dictionary configuration
const config = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'build/',
      files: [
        {
          destination: '_variables.css',
          format: 'css/variables'
        }
      ]
    },
    js: {
      transformGroup: 'js/es6',
      buildPath: 'build/',
      files: [
        {
          destination: 'tokens.js',
          format: 'javascript/es6'
        }
      ]
    }
  }
};

// Create a build directory if it doesn't exist
const outputDir = path.resolve(process.cwd(), 'build');
if (!fs.existsSync(outputDir)) {
  fs.mkdirSync(outputDir, { recursive: true });
}

// 3. Extend Style Dictionary and build all platforms
async function buildTokens() {
  // StyleDictionary.extend is now asynchronous since v4
  const sd = await StyleDictionary.extend(config);
  sd.buildAllPlatforms();
  console.log('Style Dictionary build completed successfully!');

  // To clean generated files:
  // sd.cleanAllPlatforms();
}

buildTokens().catch(err => {
  console.error('Style Dictionary build failed:', err);
  process.exit(1);
});

view raw JSON →