Tokens Studio Style Dictionary Transforms

If you are using the PRO version of Tokens Studio, you can integrate its theme data with Style Dictionary using sd-transforms.

To implement this, you must:

1. Register sd-transforms with Style Dictionary using register(StyleDictionary, { ... }).
2. Parse your $themes.json file.
3. Map through the themes to create individual Style Dictionary configurations.
4. Crucial: Since version 0.16.0, you must explicitly set preprocessors: ['tokens-studio'] in your configuration object.
5. For each theme, define a platform (e.g., css) using the tokens-studio transformGroup and specify your desired transforms and files destination.

import { register } from '@tokens-studio/sd-transforms';
import StyleDictionary from 'style-dictionary';
import { promises } from 'fs';

register(StyleDictionary, {
  /* options here if needed */
});

async function run() {
  const $themes = JSON.parse(await promises.readFile('$themes.json', 'utf-8'));
  const configs = $themes.map(theme => ({
    source: Object.entries(theme.selectedTokenSets)
      .filter(([, val]) => val !== 'disabled')
      .map(([tokenset]) => `${tokenset}.json`),
    preprocessors: ['tokens-studio'], // <-- since 0.16.0 this must be explicit
    platforms: {
      css: {
        transformGroup: 'tokens-studio',
        transforms: ['name/kebab'],
        files: [
          {
            destination: `vars-${theme.name}.css`,
            format: 'css/variables',
          },
        ],
      },
    },
  }));

  async function cleanAndBuild(cfg) {
    const sd = new StyleDictionary(cfg);
    await sd.cleanAllPlatforms();
    await sd.buildAllPlatforms();
  }
  await Promise.all(configs.map(cleanAndBuild));
}

run();

The register function accepts an options object to customize the behavior of the tokens-studio transform group.

Color Modifier Options:

• format: ColorModifierFormat (e.g., 'hex', 'hsl', 'lch', 'p3', 'srgb'). Overrides the output format.

register(StyleDictionary, {
  excludeParentKeys: true,
  platform: 'css',
  name: 'tokens-studio',
  'ts/color/modifiers': {
    format: 'hex',
  },
});

This complete workflow demonstrates how to use permutateThemes to generate separate CSS variable files for every possible theme combination produced by multi-dimensional theming.

import { register, permutateThemes } from '@tokens-studio/sd-transforms';
import StyleDictionary from 'style-dictionary';
import { promises as fsPromises } from 'fs';

register(StyleDictionary, {});

async function run() {
  const $themes = JSON.parse(await fsPromises.readFile('$themes.json', 'utf-8'));
  const themes = permutateThemes($themes, { separator: '_' });
  
  const configs = Object.entries(themes).map(([name, tokensets]) => ({
    source: tokensets.map(tokenset => `${tokenset}.json`),
    preprocessors: ['tokens-studio'],
    platforms: {
      css: {
        transformGroup: 'tokens-studio',
        transforms: ['name/kebab'],
        files: [
          {
            destination: `vars-${name}.css`,
            format: 'css/variables',
          },
        ],
      },
    },
  }));

  async function cleanAndBuild(cfg) {
    const sd = new StyleDictionary(cfg);
    await sd.cleanAllPlatforms();
    await sd.buildAllPlatforms();
  }
  await Promise.all(configs.map(cleanAndBuild));
}

run();

To use the transforms, import register from @tokens-studio/sd-transforms and pass your StyleDictionary instance to it. This registers the generic and CSS transforms as a transform group named tokens-studio.

Note: This library is only available in ESM.

import { register } from '@tokens-studio/sd-transforms';
import StyleDictionary from 'style-dictionary';

// will register them on StyleDictionary object
register(StyleDictionary);

const sd = new StyleDictionary({
  source: ['tokens/**/*.json'],
  preprocessors: ['tokens-studio'], // must be explicit since 0.16.0
  platforms: {
    css: {
      transformGroup: 'tokens-studio', // applies all transforms in the group
      transforms: ['name/kebab'],
      buildPath: 'build/css/',
      files: [
        {
          destination: 'variables.css',
          format: 'css/variables',
        },
      ],
    },
  },
});

await sd.cleanAllPlatforms();
await sd.buildAllPlatforms();