Importing via Tokens Studio

With the Tokens Studio integration, you can synchronize Tokens Studio tokens and themes with your Supernova design system. When you push token changes from the Tokens Studio plugin, they'll be immediately updated across Supernova. This includes any tokens mentioned in your documentation, which will be available in the next documentation publish.

There are two options for integrating with Tokens Studio: through a combination of the Supernova interface and Tokens Studio plugin, or with the Supernova CLI.

This documentation is about using the Supernova interface and Tokens Studio plugin.

Getting started

There are a few important things to note when using Tokens Studio to import styles and themes:

• You cannot import tokens from connected Figma files when Tokens Studio is enabled. You can still import components, assets or documentation images from them.
• If you are already importing tokens and themes from Figma when Tokens Studio is enabled, any previously imported tokens with matching names will be overwritten, and all other tokens (from Figma, CLI or created manually) will be removed from the design system.
• Only 1 Tokens Studio source can be used per design system.
• Token changes must be made in Tokens Studio, then pushed to Supernova. You can also pull the tokens from Supernova to your Tokens Studio.

Set up the Tokens Studio integration

We're assuming you're already using the Tokens Studio plugin, and would like to integrate it with Supernova.

If you're not using Tokens Studio to manage your tokens yet, and you'd like to get started, please refer to the Tokens Studio documentation instead.

Head to Design data -> Tokens Studio to get started.

1. Generate an authentication token

In Supernova, you’ll need to generate an authentication token which you will use to give permission to access Supernova from the plugin.

You can do this in the Authentication section. Learn how to generate an authentication token in Authentication tokens.

2. Set up Supernova Sync in Tokens Studio

• In the Tokens Studio plugin, go to the Settings tab.
• Under Sync Providers, select Supernova from the dropdown.

3. Provide your personal access token

• Enter a name for the connection. This can be anything you want, used just for reference.
• Paste in your personal access token from your clipboard.

4. Copy/paste the design system URL

• Navigate to design system you'd like to synchronize with.
• Copy a URL from the design system. The URL must contain your design system name as part of the slug, but once that's there, any URL will do.
• Paste the URL into Design System URL field.

At this point, you have everything prepared to start syncing data with Supernova. However, there is one more step to take: Tell the plugin how exactly should be data used within Supernova.

5. Setting up mapping

The most important part of the entire integration is the mapping between Supernova and Tokens Studio data. Because both your token structures within Tokens Studio and your Supernova setup can be very complex, you must clearly describe how to map the data from one place to another.

You can do this by providing mapping configuration.

As you can see, the mapping describes what to take from Tokens Studio and where to write it in Supernova. Specifically:

• tokenSets describes which token sets should be taken from Tokens Studio and imported into Supernova. Each token set is name of one of your Tokens Studio sets.
• supernovaBrand describes which brand the tokens should be written to. If you have multiple brands, you can use this to synchronize different token sets with different brands (more on that later). Unless you have renamed your default brand, Default will work for your setup.

Your default brand is set to whichever brand you first set up your design system with.

Change the brand and token sets to your liking, copy paste the configuration to the mapping and save the integration!

Mapping example

Here is a simple example of how your mapping can look — you can copy this to use if you wish:

                                                        
                                                        
                                                            [
                                                            {
                                                              "tokenSets": ["global", "light"],
                                                              "supernovaBrand": "Default"
                                                            }
                                                        ]
                                                        
                                                            

The structure of the mapping is important. Copy/paste the mapping precisely, including [ ] (signifying that there can be multiple mappings at the same time).

6. Saving and syncing data

Finally, hit Save to store your integration. On the screen that shows up, hit Cancel if you don't want to sync your data just yet, or Push to immediately upload your data to Supernova. After all was done correctly, you'll see Supernova as your new persistent provider.

Remove the Tokens Studio integration

1. To remove the Tokens Studio integration, in Data sources → Tokens Studio, click ••• and then Remove integration.
2. Click Confirm in the dialog.
3. The integration will be removed and the authentication token will also be invalidated.
4. Because the authentication token was not invalidated, it will still be possible to push from Tokens Studio, or pull from Supernova.

The integration can be set up again at any type by generating a new personal authentication token and following the same setup steps as previously.