Style Dictionary Configuration

Style Dictionary configuration controls how design tokens transform from source definitions into platform-specific outputs. As the most widely adopted token transformation tool, Style Dictionary provides extensive configuration options for platforms, transforms, formats, and file generation. Understanding configuration enables teams to generate exactly the outputs their applications require.

What Is Style Dictionary Configuration

Style Dictionary configuration specifies how the tool should process token source files to produce outputs. Configuration defines which token files to read, what transformations to apply, which platforms to generate, and how output files should be formatted and organized.

Configuration typically lives in a config.json or config.js file at the root of a token project, though JavaScript configuration offers additional flexibility through dynamic values and custom logic.

How Style Dictionary Configuration Works

A basic configuration file specifies source files and platform outputs:

module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{
        destination: 'tokens.css',
        format: 'css/variables'
      }]
    },
    js: {
      transformGroup: 'js',
      buildPath: 'dist/js/',
      files: [{
        destination: 'tokens.js',
        format: 'javascript/es6'
      }]
    }
  }
};

The source array uses glob patterns to specify which token files to process. Style Dictionary reads all matching files and combines them into a single token dictionary.

The platforms object defines outputs. Each platform has its own configuration including transform groups, build paths, and file specifications.

Transform groups bundle related transforms. The css transform group applies transforms appropriate for CSS output: converting colors to hex, dimensions to pixels with units, and names to kebab-case.

Files within each platform specify output destinations and formats. Multiple files can be generated per platform, enabling separation of different token categories or theme variants.

Key Considerations

• JavaScript configuration files offer more flexibility than JSON
• Transform groups provide sensible defaults but can be customized
• Custom transforms extend capabilities for organization-specific needs
• Filter functions control which tokens appear in each output file
• Platform configuration order does not affect output
• Build path directories are created automatically if they do not exist
• Configuration changes require rebuilding to take effect
• Version control should track configuration alongside tokens

Common Questions

How should multiple themes be configured?

Multiple themes require generating separate outputs where the same token names resolve to different values. Several configuration approaches support this.

Separate source files with filtering process different token files for different themes:

module.exports = {
  source: ['tokens/core/**/*.json'],
  platforms: {
    'css-light': {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{
        destination: 'light.css',
        format: 'css/variables',
        filter: (token) => token.filePath.includes('light')
      }]
    },
    'css-dark': {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{
        destination: 'dark.css',
        format: 'css/variables',
        filter: (token) => token.filePath.includes('dark')
      }]
    }
  }
};

Dynamic configuration generates platform configs programmatically:

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

const platforms = {};
themes.forEach(theme => {
  platforms[`css-${theme}`] = {
    transformGroup: 'css',
    buildPath: `dist/css/${theme}/`,
    files: [{
      destination: 'tokens.css',
      format: 'css/variables'
    }]
  };
});

module.exports = {
  source: ['tokens/**/*.json'],
  platforms
};

This pattern scales to many themes without configuration duplication.

How are custom transforms created?

Custom transforms handle value conversions that built-in transforms do not support. Each transform specifies a name, type, matcher, and transformer function.

const StyleDictionary = require('style-dictionary');

StyleDictionary.registerTransform({
  name: 'shadow/css',
  type: 'value',
  matcher: (token) => token.type === 'shadow',
  transformer: (token) => {
    const { offsetX, offsetY, blur, spread, color } = token.value;
    return `${offsetX} ${offsetY} ${blur} ${spread} ${color}`;
  }
});

module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transforms: ['attribute/cti', 'name/cti/kebab', 'shadow/css'],
      buildPath: 'dist/css/',
      files: [{
        destination: 'tokens.css',
        format: 'css/variables'
      }]
    }
  }
};

Custom transforms integrate with built-in transforms by including both in the transforms array. Transform order matters when transforms depend on each other’s output.

What format options exist?

Formats determine how transformed tokens are assembled into output files. Built-in formats cover common needs.

CSS formats include css/variables for custom properties and scss/variables for Sass variables. JavaScript formats include javascript/es6 for ES module exports and javascript/module-flat for CommonJS.

Custom formats enable organization-specific output structures:

StyleDictionary.registerFormat({
  name: 'typescript/declarations',
  formatter: ({ dictionary }) => {
    return dictionary.allTokens.map(token => {
      return `export const ${token.name}: string = '${token.value}';`;
    }).join('\n');
  }
});

Format functions receive the processed dictionary and return string content for the output file. This enables any output format including documentation, native mobile resources, or custom data structures.

Summary

Style Dictionary configuration controls the transformation of design tokens into platform-specific outputs. Source patterns specify input files, platform configurations define outputs, and transform groups handle value and name conversions. Custom transforms and formats extend capabilities for specialized needs. Understanding configuration options enables teams to generate precisely the token outputs their applications require.