lukasoppermann / design-token-transformer

Base repo to transform json design tokens from the figma design token plugin via amazon style dictionary.

Design Token Transformer

This package is supposed to be used together with the Design Tokens plugin for Figma. It transforms the exported design tokens using Amazon style dictionary.

Installation

1. Download or clone the repo to your computer

You can download this package or clone it via the terminal.

git clone https://github.com/lukasoppermann/design-token-transformer.git

2. Install dependencies

1. From within the terminal cd (navigate) this folder.
2. Run npm i to install the dependencies.

Usage

Option 1: Local transformation

To use an exported json file and transform it locally on your machine, follow the 3 steps below:

1. Save the .json file you exported using the Design Token plugin to the tokens folder (and remove the example files).
2. In the terminal cd (navigate) to this folder.
3. Run npm run transform-tokens.
4. 🎉 Your converted tokens should be in the build folder.

Option 2: Transformation in github repository (or on server)

1. Fork this repository.

It is recommended to create a fork of this repository and adapt it to your needs.
Should you decide to instead create a new repo, make sure to set up a .github/workflows file that handles the data.

2. Enable github actions in the actions tab

Go to the actions tab in your fork of this repository and enable the github actions by clicking the enable actions button.

3. Create a personal access token.

4. Add repo url & access token to plugin settings

In the plugin settings you need to add two items:

1. Add the url to your repository in the format https://api.github.com/repos/:username/:repo/dispatches to the server-url field (See server-url for details)
2. Add the personal access token to the access token field.

5. Run the Send Design Tokens to Url command from the plugin.

6. 🎉 You are done.

You should be able to see the action running in your GitHub repo and have all the converted files in the build folder once it is done.

7. Optional: Adapt the transform-tokens script in the package.json.

If you want to you can do something else when the tokens are pushed to the server you can change the transform-tokens script in the package.json. However note that the name of the script transform-tokens should not be changed.

8. Optional: Adapt the github workflow

You can adapt the workflow file if you need to. Just make sure the keep the current setup working.

Personal access token

The access token should be specifically for this plugin and only have the minimal permissions needed:

• only public_repo is needed for a public repository.

The token is not stored with the Figma file but only locally on your machine.

Here you can find more information about creating personal access tokens in the docs.

Custom dev server

If you want to set up a custom server that responds to a push from this plugin, check out the setup for GitHub and adapt it to your needs. If you run into problems, please create an issues in the main Design Tokens plugin for Figma repository.

Customization

To customize the output please view the Amazon style dictionary documentation.

FAQ

Sending tokens to the server

I don't see the tokens in the github repositiory

1. Make sure you have a .github/workflows
2. Make sure you enabled github actions in the actions tab of your repositiory.
3. Verify that you specified the correct server url in the plugin settings: https://api.github.com/repos/{username}/{reponame}/dispatches (replace {username} with your username e.g. lukasoppermann and {reponame} with the name of your repo e.g. design-token-transformer)
4. Verify that the action runs without any error

I can't enable github actions

If you only see the Get started with GitHub Actions page without an option to enable actions you either deleted the .github/workflows file from your forked repository, or you created a new repositiory without adding a .github/workflows file. See step 1.

Bugs, issues & feature requests

If you have issues concerning the Design Tokens plugin for Figma please create an issue in the plugin repo.

Only create an issue in this repository if you have an issue with this transformation package.

design-token-transformer's Issues

Unit transforms don't seem to apply

Hi!

It seems units aren't being added as expected. As an example, the build/scss file uses the transformGroup SCSS https://amzn.github.io/style-dictionary/#/transform_groups?id=scss, which includes size/rem, which in turn should append the unit rem to relevant variables, but it doesn't seem to be doing that.

Unable to receive the commit message in GitHub's pull request.

I have forked this repository for my use.
I want to receive the commit message in GitHub's pull request.

Although I have commit messages, the commit message in GitHub's pull request always appears as "Tokens updated."
I understand the cause. refer: https://github.com/lukasoppermann/design-token-transformer/blob/main/.github/workflows/transform-tokens.yml#L46

I would like to set the commit message in the following section if a commit message is received through the request body.
Like this.

commit-message: ${{ github.event.client_payload.commitMessage || 'Tokens updated' }}

The setting

Transform-tokens workflow always creates the file design-tokens-example.tokens.json

The transform-tokens workflow has a hardcoded value for the file name:

design-token-transformer/.github/workflows/transform-tokens.yml

Line 28 in 5db78c7

name: 'design-tokens-example.json'

The action should use the filename from the client_payload object:

name: ${{ github.event.client_payload.filename }}

I'd open a PR to fix this myself, but I don't have permissions.

missing android platform

design-token-transformer/config.json missing android support

npm run transform-tokens cant find "global" form figma plugin export

"Reference doesn't exist: global.color.primary-base.value tries to reference brand.accenture.primary-base, which is not defined"

Once the figma Plugin creates this "Global" key, the token-transformer can't find it, I'm including it manually

to this:

{
  "global": {
    "brand": {
      "accenture": {
        "primary-base": {
          "value": "#A100FF",
          "type": "color",
          "description": "Base Accenture Color"
        },
        "secondary": {
          "value": "#0041F0",
          "type": "color"
        }
      }
    },
    "color": {
      "primary-base": {
        "value": "{brand.accenture.primary-base}",
        "type": "color"
      }
    },
    "black": {
      "12": {
        "value": "rgba(0,0,0,0.12)",
        "type": "color"
      },
      "25": {
        "value": "rgba(0,0,0,0.25)",
        "type": "color"
      },
      "50": {
        "value": "rgba(0,0,0,0.5)",
        "type": "color"
      },
      "85": {
        "value": "rgba(0,0,0,0.85)",
        "type": "color"
      },
      "100": {
        "value": "#000",
        "type": "color"
      }
    }
  },
  "font": {},
  "$themes": [],
  "$metadata": {
    "tokenSetOrder": [
      "global",
      "font"
    ]
  }
}

422 Error sending tokens to url

I want to use the "Send design tokens to url" feature to export the variables, color, text styles and effects from my figma file. When I check "variables" I get a 422 error:


If I uncheck the "variables (beta)" option everything works fine. The JSON file download works fine too, only issue is when I try to export it. I have recreated a separate figma file with similar variable config and to my surprise the "Send design tokens to url" feature works fine. I suspect there is some issue with my file or variables that I have in this file.
design-tokensjson.txt

I am attaching the downloaded json.

Any idea how I can begin to debug this ? "the console doesn't provide any useful info to begin debugging this" failed to load resource: the server responded with a status of 422 ()

rgba values becomes #0000000

When I run with values like the image:

The output json becomes like this:

Is this a known issue? Any ideas on how to fix?

No android output for this file

Using this file as input, I expect to see an Android build output with colors for Android, like there is for ios and ios-swift.
Ideally I would like Android Jetpack Compose compatible files, but xml is fine, too.

But no android folder is created when following the readme.

• Export my colors from figma
• place the file in ./token/, overwriting the sample file
• npm run transform-tokens

When I then run the android task, it says it cannot find inputs for colors

 node ./examples/android/build.js

android
No properties for values/font_styles.xml. File not created.
No properties for values/dimens.xml. File not created.
No properties for values/colors.xml. File not created.
No properties for values-night/colors.xml. File not created.
Copying ./examples/android/filesToCopy/font_family.xml to ./examples/build/android/font/font_family.xml

Now the android folder is created, but as the cli output hints at, its only the template font file that gets created

File used:

design-tokens.tokens.json

build directory less and scss builds contain multiple [object object] lines

I'm new to Design Token and Amazon Style Dictionary so I may be pointing out something known but the less and scss builds in the build directory contains multiple [object object] entries, for example:

$spacing-10: [object Object];
$spacing-mixed: [object Object];
$spacing-top: [object Object];
$borders-single: [object Object];
$borders-dashed-outside: [object Object];
$borders-single-style: [object Object];

I have seen this issue mentioned over the last couple of days while reading documentation, I think it relates to Style Dictionary. There is an issue here in which the post by jam-awake appears to identify the cause and solution in case it helps.

Need correction in documentation

Doc says https://api.github.com/repo/:username/:repo/dispatches

this has to be repos

Some units are called "pixel" while others are called "pixels"

Suggested to either keep consistent naming, or modify transformTokens.js line 9 to read return (token.unit === 'pixel' || token.unit === 'pixels') && token.value !== 0

Flutter support

Hi,

First, thanks a lot for these great tools!

I just wanted to share a set of custom transformers I did for my own needs with Flutter, which could be interesting to improve your official transformer package.

Everything is available here : style-dictionary-figma-flutter.

It basically outputs tokens as a Flutter theme widget with a few helpers.

I also added a custom-icon type to export vector paths from Figma too (I made a custom plugin that clones my icon frames, flattens them as a single path, and then exports it as json).

Style Dictionary 4

Hi Lukas, just wondering if you aware that the folks from Figma have seemed to join forces with Danny Banks to work on v4. Looks like some good progress is being made. Anyway, if you are not involved, thought you might be interested. It seems to me that some of your work with your transformer could be used in the W3C compatibility aspects that they plan to bake in. Here are some links:

• https://tokens-studio.slack.com/archives/C0622L9CKDM
• https://github.com/orgs/amzn/projects/4/views/1?layout=board

Support nested variable transformation ([object Object])

First and foremost, thanks for building this great tool!

I recognized that with the the exported text and effect styles as objects, the css variable generation is kinda broken or doesn't resolve properly wit nested key-value pairs because the nested properties aren't recognized and transformed to it's own value.

For example:

--font-headline-2x-large: [object Object];
--font-headline-x-large: [object Object];
--font-headline-large: [object Object];
--font-headline-medium: [object Object];
--font-headline-small: [object Object];
--font-headline-x-small: [object Object];
--font-copy-large: [object Object];
--font-copy-medium: [object Object];
--font-copy-x-small: [object Object];
--font-copy-small: [object Object];
--font-label-medium: [object Object];
--font-label-small: [object Object];
--font-button-medium: [object Object];
--font-button-small: [object Object];
--effect-focus-inner-default-0: [object Object];
--effect-focus-inner-default-1: [object Object];
--effect-focus-outside-default-0: [object Object];
--effect-focus-outside-default-1: [object Object];
--effect-focus-outside-input: [object Object];
--effect-shadow-bottom-400: [object Object];
--effect-shadow-bottom-800: [object Object];
--effect-shadow-right-400: [object Object];

The solution:
Having the text style for example --font-headline-2x-large as prefix and add the nested property fontSize as font-size or something similar to generate also the nested key value pairs as variables as --font-headline-2x-large-font-size. Same would work for the other generated tokens such as less and scss.

What do you think bout this improvement? Is this possible to implement as the standard configuration?
Thanks for your effort! :)

Question - How to produce fontFamilies?

Hi, just a question:
Seeing that the webFont.js file seems to recognized that there could be plural fontFamilies. But how does one get this out of figma and the Design Tokens plugin? I can only get the singular form.

Thanks!

[Question]: Figma local variables

Hey,
I'm playing with your plugin and realised that there is no output for local variables from transformer.
Do you have such support? Maybe I'm doing something wrong

JSON file from plugin:

  "color": {
    "u-p1": {
      "263238": {
        "description": "\"Black\"",
        "type": "color",
        "value": "#263238ff",
        "blendMode": "normal",
        "extensions": {
          "org.lukasoppermann.figmaDesignTokens": {
            "styleId": "S:8534522e8bed2ead25c21d3ac971217b6e92c40b,",
            "exportKey": "color"
          }
        }
      }
    }
  },
  "primitives": {
    "color": {
      "type": "color",
      "value": "#ffffff"
      "grayscale-01": {
        "type": "color",
        "value": "#fafafaff",
        "blendMode": "normal",
        "extensions": {
          "org.lukasoppermann.figmaDesignTokens": {
            "mode": "Mode 1",
            "collection": "Primitives",
            "scopes": ["ALL_SCOPES"],
            "variableId": "VariableID:15:146",
            "exportKey": "variables"
          }
        }
      },
      "type": "color",
      "value": "#ffffffff",
      "blendMode": "normal",
      "extensions": {
        "org.lukasoppermann.figmaDesignTokens": {
          "mode": "Mode 1",
          "collection": "Primitives",
          "scopes": ["ALL_SCOPES"],
          "variableId": "VariableID:2024:149",
          "exportKey": "variables"
        }
      }
    }
  }
}

Output from transformer:

:root {
  --color-u-p1-263238: rgb(38, 50, 56);
}

Plugin is great! Any help is welcomed.
Thanks!

Resolve References using Style Dictionary

Hello there, Thanks for this Great Library

Please any idea of how to resolve references ?

{
    "global": {
      "hello-pink": {
        "50": {
          "value": "#fge7ee",
          "type": "color"
        },
      },
      "white": {
        "value": "#ffffff",
        "type": "color"
      }
    },
    "Light": {
      "bg": {
        "default": {
          "value": "{white}",
          "type": "color",
          "description": "Default background color for the whole app."
        },
      },
      }
    }
  }

Here is the error i get

scss

Property Reference Errors:
Reference doesn't exist: Light.bg.default.value tries to reference white, which is not defined