@divriots/style-dictionary-to-figma

Brought to you by

Style Dictionary To Figma

A utility that transforms a style-dictionary object into something Figma Tokens plugin understands.

Used by Design Systems in Backlight using design tokens in style-dictionary that can be synced into Figma via the Figma Tokens plugin.

The tool, at the moment, assumes usage of the Sync feature of Figma Tokens Plugin. The JSON output is catered to this as it is a single file containing the tokensets information.

Features

• Supports marking a token group as a custom tokenset so that it will appear as a separate tokenset in Figma. By default, "global" is used as the tokenset, and your tokens will be placed inside of this, but you can override it. This is useful if you want to combine many base tokens into a "global" set but theme-specific token groups into a "theme-dark" set for example. You can configure it like so:

  {
    "color": {
      "tokenset": "custom",
      "primary": {
        "base": {
          "type": "color",
          "value": "#14b8a6"
        }
      }
    }
  }
  

  color.primary.base token will appear under custom tokenset now in the plugin. You can also configure or turn off this automatic tokenset mapping by passing defaultTokenset: false or configuring a string for it defaultTokenset: 'default'

• Trims .value from reference values as Figma Tokens plugin does not use this suffix.

• Trims the name properties from tokens since Figma Tokens plugin uses this property to name its tokens, however, without a name property it creates its own naming/nesting by the object structure which is way nicer.

• Use the reference values rather than its resolved values. Put ignoreUseRefValue: true as a sibling property to the value prop if you want to make an exception and keep it as a resolved value.

• Allow passing some optional options to adjust the object conversion:

  • cleanMeta, if true, will clean up some of the meta info that style-dictionary creates, which Figma Tokens plugin doesn't care about. Can also pass a string[] if you want to configure a blacklist of meta props that you want to filter out yourself

  transform(obj, { cleanMeta: ['foo', 'bar'] });
  

Usage

npm i @divriots/style-dictionary-to-figma

import { transform } from '@divriots/style-dictionary-to-figma';

const sdObject = { ... };
const figmaObj = transform(sdObject);

In case you want its separate counterparts, you can import them separately.

import {
  trimValue,
  trimName,
  useRefValue,
  markTokenset,
  cleanMeta,
} from '@divriots/style-dictionary-to-figma';

Once you transformed the object to Figma, a recommendation is to push this to GitHub and use the Figma Tokens plugin to sync with it to use the tokens in Figma.

Use in Backlight / Style-dictionary

Import the transform utility and create a style-dictionary formatter:

const { transform } = require('@divriots/style-dictionary-to-figma');
const StyleDictionary = require('style-dictionary');

StyleDictionary.registerFormat({
  name: 'figmaTokensPlugin',
  formatter: ({ dictionary }) => {
    const transformedTokens = transform(dictionary.tokens);
    return JSON.stringify(transformedTokens, null, 2);
  },
});

Or you can also put the formatter directly into the config without registering it imperatively:

const { transform } = require('@divriots/style-dictionary-to-figma');

module.exports = {
  source: ['**/*.tokens.json'],
  format: {
    figmaTokensPlugin: ({ dictionary }) => {
      const transformedTokens = transform(dictionary.tokens);
      return JSON.stringify(transformedTokens, null, 2);
    },
  },
  platforms: {
    json: {
      transformGroup: 'js',
      buildPath: '/tokens/',
      files: [
        {
          destination: 'tokens.json',
          format: 'figmaTokensPlugin',
        },
      ],
    },
  },
};

This spits out a file /tokens/tokens.json which Figma Tokens plugin can import (e.g. through GitHub).

Since Backlight has GitHub and Style-Dictionary integration out of the box, this process is very simple.

Create a JSON for each tokenset

Perhaps you'd like to use this tool to generate a separate JSON file for each tokenset, which you can then manually paste into the Figma Tokens Plugin JSON view. For example, when you're not using the Figma Tokens Plugin Sync feature.

For this, refer to this code snippet from this issue.

Changelog

0.4.0

Minor Changes

• ab01a1e: BREAKING: if an upper token group does not have a tokenset property, it will get placed in a "global" tokenset by default. This means that no action is required by the user of the transformer to get a working JSON for Figma Tokens Plugin, but this change is potentially breaking because of how it changes the JSON output.

  Before

  {
    "core": {
      "color": {
        "primary": {
          "base": {
            "type": "color",
            "value": "#14b8a6"
          },
          "secondary": {
            "type": "color",
            "value": "#ff0000"
          }
        }
      }
    }
  }
  

  Nothing is changed in the output. However, if you have references, they might be broken because the plugin will interpret this as "color" being the upper property in a tokenset called "core".

  After

  {
    "core": {
      "color": {
        "primary": {
          "base": {
            "type": "color",
            "value": "#14b8a6"
          },
          "secondary": {
            "type": "color",
            "value": "#ff0000"
          }
        }
      }
    }
  }
  

  turns into

  {
    "global": {
      "core": {
        "color": {
          "primary": {
            "base": {
              "type": "color",
              "value": "#14b8a6"
            },
            "secondary": {
              "type": "color",
              "value": "#ff0000"
            }
          }
        }
      }
    }
  }
  

  Your reference, for example {core.color.primary.base} will now work properly because "core" is not interpreted as the tokenset, "global" is.

Patch Changes

• ab01a1e: Fix clean-meta utility by using a proper isObject check which excludes arrays (values can be arrays).