Tokens Studio 101

Learn how to push your Token Studio data to Supernova using CLI.



Tokens Studio is a Figma plugin that allows you to integrate tokens into your Figma designs. It is also the most advanced in-editor solution to manage your Figma tokens, and works amazingly well when combined with Supernova's design system management, advanced automation and documentation.

Using the Supernova CLI, you can push tokens from Figma Tokens plugin to Supernova workspaces using data defined in a JSON format. Make sure that you have the Supernova CLI installed as a global or local dependency before continuing with this tutorial. If you have any questions, don't hesitate to ask us on our community Slack!

Configuring the Supernova <> Tokens Studio integration

The Supernova CLI allows you to read Figma tokens declaration files in JSON format in both single-file and multi-file mode (either a file or an entire directory of token definitions) and push it to the design system of your choosing. There are few main steps you must take to setup integration properly:

  1. Choose the appropriate sync command.
  2. Obtain your apiKey.
  3. Obtain the designSystemId for the design system you want to push data to.
  4. Get a path to tokens.json or a full directory with token definitions.
  5. Configure the mapping between Supernova and Tokens Studio.
  6. Run the sync!
  7. (optional) Set up an automated sync.

Here is the entire process described step by step. Generally, the entire set up will not take more than few minutes.

Choose the appropriate sync command template

Select one of the following templates as a base for your Tokens Studio sync command:

For single-file mode:

Use the following command if you are syncing a single file containing all definitions:

                                                            $ supernova sync-tokens \
                                                            --apiKey="xxx-xxx-xxx" \
                                                            --designSystemId="1234" \
                                                            --tokenFilePath "/path/to/tokens.json" \
                                                            --configFilePath "/path/to/supernova.settings.json"

For multi-file mode:

Use the following command if you are syncing an entire directory containing the definitions:

                                                            $ supernova sync-tokens \
                                                            --apiKey="xxx-xxx-xxx" \
                                                            --designSystemId="1234" \
                                                            --tokenDirPath "/path/to/tokens/" \
                                                            --configFilePath "/path/to/supernova.settings.json"

Obtain your API Key and design system ID

You'll need an API key, and the ID for the design system you are targeting for your sync. Learn how to get them here.

Get a path to the token file or directory

Depending on your choice in step 1, fill --tokenFilePath or --tokenDirPath with the path (relative or absolute) to your Figma Token definitions. For single-file mode, you must point to a file path of JSON definition containing all tokens. For multi-file mode, you must point to a directory with JSON file definition. You can only provide one option at time.

Configure mapping between Supernova and Tokens Studio

Finally, you must provide a JSON file describing how the sync should work and handle your data. Because the configuration can get complex, we have a dedicated section just for that. Once you are done with the mapping, write a file called supernova.settings.json next to your token definitions.

Run the sync!

You now have everything you need to properly push data from Tokens Studio into Supernova. Since you installed the Supernova CLI, you can use the supernova [command] as a global terminal command. Run the sync using all the attributes you have obtained, for example:

                                                            $ supernova sync-tokens \
                                                            --apiKey="sn.generated-api-token-copied-from-your-profile" \
                                                            --designSystemId="420" \
                                                            --tokenFilePath "/data/tokens.js" \
                                                            --configFilePath "/data/supernova.settings.json"

If everything went well, you'll see a success message:

                                                            $ supernova sync-tokens ...
                                                        > Tokens synchronized

If there was a problem of any kind, you'll get a detailed error message stating what happened and how to fix it. If you are still unable to run the sync, feel free to join and ask us at our community Slack!

(optional) Setup automated sync

After you have successfully synced your tokens, you might also want to automate the sync to run every time you push your tokens to a remote repository. We have prepared tutorials to walk you through the setup for most common scenarios:

  • Automated sync with GitHub using Github Actions

Examples in action

We have prepared a repository so you can see all of this in action! This repository takes tokens being pushed through a GitHub provider in Tokens Studio and runs a GitHub action invoking the CLI.

See it for yourself.