This repository serves as an example to illustrate how you can locally transform your tokens stored on Figma Tokens so they are up and ready for Style Dictionary to compile.

1. Why the need for Token Transformer?
2. Tokens Structure
3. How to use this project in 3 steps
4. Other considerations

First of all, let me begin with why we need Token Transformer in the first place.

The short answer is: The way tokens are referenced across Token Sets in the Figma Plugin is not reflected in the Token Keys after tokens are exported. This results in Style Dictionary not being able to retrieve the token references.

For more information, please read this thread on Github and the suggested workflow by @jam-awake.

In the end, Token Transformer helps us remove any aliases that would result in errors during the Style Dictionary build. Token Transformer prepares a file that only output raw values that Style Dictionary can process.

At Apart, our tokens follow a multi-layers approach.

for more information read our Design Tokens Guide.

To replicate this layers structure in the Figma Tokens Plugin we use Token Sets. A feature that allows us to semantically separate tokens and keep having the ability to make references (aliases) between them.

In a basic setup, we usually end up with two main Token Sets:

• core (all the private tokens)
• public (all the semantic and component tokens that reference core tokens)

A third Token Set can also co-exist but is not useful for developers: mobile-overrides. This Token Set can be ignored. This is for design purposes only.

Figma Tokens generates for you a single file with all your tokens organised by Token Set. The exported file should look something like this:

// ./tokens/tokens.json
{
    "core": {...},
    "public": {...}
    // mobile-overrides if it exists
    // ... Plus any other Token Sets you might have created
}

With this file, references between public tokens and core tokens do not work out of the box with Style Dictionary. That is where Token Transformer comes into play.

Token Transformer generates a tokens file that get rid off any math operations or aliases only resulting in raw values. Your transformed tokens file should look something like this:

// ./transformed-tokens/tokens.json
{
    "core": {...},
    // List of all the basic public tokens you make use of organized by family:
    "font": {...},
    "color": {...},
    "space": {...},
    "size": {...},
    "opacity": {...},
    "borderWidth": {...},
    "borderRadius": {...},
    "boxShadow": {...},
    // ... Plus any component tokens
}

From there, you can use this file for your Style Dictionary build.

Do not forget to run npm i to install all dependencies first.

If your tokens are not sync anywhere:

1. Open your Figma Project
2. Open the Figma Tokens Plugin
3. Click Export at the bottom of the window
4. Check "All token sets"
5. Check "Expand Typography" and "Expand Shadows"
6. Click download and name your file tokens.json

If your tokens are sync and stored somewhere, maybe you can automate a flow and query this file at build time (this workflow is not documented here).

With your tokens.json file available locally in your project you can run the transform-tokens command. This command expect your tokens.json file to be under a tokens directory at the root of your project: tokens/tokens.json.

This command will generate a transformed-tokens directory with a tokens.json file inside.

Define whatever you want Style Dictionary to do with your tokens in the sd.config.json file. Then, you can run the style-dictionary command. This command expect your transformed tokens to be in the transformed-tokens directory: transformed-tokens/tokens.json.

This command will generate a build directory with the output results configured in your Style Dictionary config file: sd.config.json.

For example, the default configuration integrated to this project will generate a _variables.sass file and a variables.js file.

For more information, see Style Dictionary configuration options.

By using this project without any additional Style Dictionary configuration you might end up with font, size or shadows properties without unit formats like %, em, px, ... You can use transformers to do that at build time. Read this github thread for more information.