\n\n# Style Dictionary To Figma\n\nA utility that transforms a [style-dictionary](https://amzn.github.io/style-dictionary/#/) object into something [Figma Tokens plugin](https://www.figma.com/community/plugin/843461159747178978) understands.\n\nUsed by Design Systems in [Backlight](https://backlight.dev) using design tokens in [style-dictionary](https://amzn.github.io/style-dictionary/) that can be synced into Figma via the [Figma Tokens plugin](https://www.figma.com/community/plugin/843461159747178978).\n\n> The tool, at the moment, assumes usage of the Sync feature of Figma Tokens Plugin.\n> The JSON output is catered to this as it is a single file containing the tokensets information.\n\n## Features\n\n- 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:\n\n ```json\n {\n \"color\": {\n \"tokenset\": \"custom\",\n \"primary\": {\n \"base\": {\n \"type\": \"color\",\n \"value\": \"#14b8a6\"\n }\n }\n }\n }\n ```\n\n `color.primary.base` token will appear under `custom` tokenset now in the plugin.\n You can also configure or turn off this automatic tokenset mapping by passing `defaultTokenset: false` or configuring a string for it `defaultTokenset: 'default'`\n\n- Trims `.value` from reference values as Figma Tokens plugin does not use this suffix.\n- 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.\n- 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.\n- Allow passing some optional options to adjust the object conversion:\n\n - 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\n\n ```js\n transform(obj, { cleanMeta: ['foo', 'bar'] });\n ```\n\n## Usage\n\n```sh\nnpm i @divriots/style-dictionary-to-figma\n```\n\n```js\nimport { transform } from '@divriots/style-dictionary-to-figma';\n\nconst sdObject = { ... };\nconst figmaObj = transform(sdObject);\n```\n\nIn case you want its separate counterparts, you can import them separately.\n\n```js\nimport {\n trimValue,\n trimName,\n useRefValue,\n markTokenset,\n cleanMeta,\n} from '@divriots/style-dictionary-to-figma';\n```\n\nOnce you transformed the object to Figma, a recommendation is to push this to GitHub and use the [Figma Tokens plugin](https://www.figma.com/community/plugin/843461159747178978) to sync with it to use the tokens in Figma.\n\n## Use in [Backlight](https://backlight.dev/) / [Style-dictionary](https://amzn.github.io/style-dictionary/#/)\n\nImport the `transform` utility and create a style-dictionary formatter:\n\n```js\nconst { transform } = require('@divriots/style-dictionary-to-figma');\nconst StyleDictionary = require('style-dictionary');\n\nStyleDictionary.registerFormat({\n name: 'figmaTokensPlugin',\n formatter: ({ dictionary }) => {\n const transformedTokens = transform(dictionary.tokens);\n return JSON.stringify(transformedTokens, null, 2);\n },\n});\n```\n\nOr you can also put the formatter directly into the config without registering it imperatively:\n\n```js\nconst { transform } = require('@divriots/style-dictionary-to-figma');\n\nmodule.exports = {\n source: ['**/*.tokens.json'],\n format: {\n figmaTokensPlugin: ({ dictionary }) => {\n const transformedTokens = transform(dictionary.tokens);\n return JSON.stringify(transformedTokens, null, 2);\n },\n },\n platforms: {\n json: {\n transformGroup: 'js',\n buildPath: '/tokens/',\n files: [\n {\n destination: 'tokens.json',\n format: 'figmaTokensPlugin',\n },\n ],\n },\n },\n};\n```\n\nThis spits out a file `/tokens/tokens.json` which Figma Tokens plugin can import (e.g. through GitHub).\n\nSince [Backlight](https://backlight.dev/) has [GitHub](https://github.com/) and [Style-Dictionary](https://amzn.github.io/style-dictionary/#/) integration out of the box, this process is very simple.\n\n## Create a JSON for each tokenset\n\nPerhaps you'd like to use this tool to generate a separate JSON file for each tokenset,\nwhich you can then manually paste into the Figma Tokens Plugin JSON view.\nFor example, when you're not using the Figma Tokens Plugin Sync feature.\n\nFor this, [refer to this code snippet from this issue](https://github.com/divriots/style-dictionary-to-figma/issues/15#issuecomment-1127797022).\n","readmeFilename":"README.md"}
![\"style](\"https://raw.githubusercontent.com/divriots/style-dictionary-to-figma/main/.github/logo.png\"){kind=logo}
\n![\"‹div›RIOTS\"](\"https://divRIOTS.com/divriots.svg\")
\n \n \n ![\"‹div›RIOTS\"](\"https://divRIOTS.com/divriots-dark.svg\")
\n \n