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.

@divriots/style-dictionary-to-figma

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).

0.3.3

Patch Changes

• 2c9be59: Allow tokensets to be the same name as the upper most keys in the tokens object, e.g.:

  {
    "core": {
      "tokenset": "core",
      "color": {
        "value": "#ff0000",
        "type": "color"
      }
    }
  }

  will become

  {
    "core": {
      "core": {
        "color": {
          "value": "#ff0000",
          "type": "color"
        }
      }
    }
  }

  so that Figma Tokens plugin picks it up properly.

0.3.2

Patch Changes

• f9cf466: Allow passing an options object, for example cleanMeta, to clean unwanted meta props from the style-dictionary object.

0.3.1

Patch Changes

• 1c0ee01: Do proper isObject check (typeof null and Array are also 'object') where needed. Fixes bug with metadata props with type Array getting altered by trimValue to become Objects.

0.3.0

Minor Changes

• b6cb742: BREAKING: do not restore original value if it was not a reference value. Before, it used to always restore, which unintentionally also restored style-dictionary transforms. For nested values, restore fully if any reference is found inside the nested value (object or array). If undesired, you can always use ignoreUseRefValue (see README) to fall back to keeping the fully resolved value. Currently, a hybrid solution that restores only the subparts of a value that is partially using references, is not available. Feel free to raise an issue if needed to explain your use case.

0.2.1

Patch Changes

• c30d4c1: Allow passing ignoreUseRefValue boolean metadata as a sibling to the token value property. It will use the resolved value rather than using the original reference value after conversion when this is set to true.

0.2.0

Minor Changes

• 00c39e3: BREAKING: no longer using default export, this is considered an anti-pattern for JS libraries. Re-export wildstars with default exports in ESM is one example quirk, another example is CommonJS not supporting default exports next to named exports in a single file. Now, the main export is a named export called "transform" and you have to import it as such.

  Before:

  // ESM
  import styleDictionaryToFigma from '@divriots/style-dictionary-to-figma';
  // CommonJS
  const styleDictionaryToFigma = require('@divriots/style-dictionary-to-figma');
  
  styleDictionaryToFigma({...}) // figma object

  After:

  // ESM
  import { transform } from '@divriots/style-dictionary-to-figma';
  // CommonJS
  const { transform } = require('@divriots/style-dictionary-to-figma');
  
  transform({...}) // figma object

0.1.3

Patch Changes

• ff5d591: Keeps an array-type value as an array. This is useful with boxShadows that can have multiple stacked shadows in a single token.

0.1.2

Patch Changes

• 31493c5: Fixes trimValue when used on values that are objects.

0.1.1

Patch Changes

• 52117f8: Add CommonJS entrypoint, allowing importing with const sdToFigma = require('@divriots/style-dictionary-to-figma').default.

0.1.0

Minor Changes

• 092a7fb: Initial release: A utility that transforms a style-dictionary object into something Figma Tokens plugin understands.