Tokens Studio and Supernova integration
With the Tokens Studio (previously Figma Tokens plugin) 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.
Getting started
Using Tokens Studio as a data source
Things to note when using Tokens Studio as a data source:
- The Tokens Studio integration is a replacement for Figma data sources, which means Figma source files cannot be used for styles or themes when Tokens Studio is enabled. They can, however, still be used for components, assets or frames.
- If you are already using Supernova with another data source when Tokens Studio is enabled, any previously imported Figma 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 download the tokens from Supernova to your Token Studio.
Set up the integration
Head to Data Sources -> Tokens Studio to get started
1. Generate a personal access token
Generate a personal access token
In Supernova, you’ll need to generate a personal access token which you will use to give permission to access Supernova from the plugin.
- In the Data Sources section of Supernova, click Tokens Studio.
- Then click + Set up integration to open the setup dialog, and click Next to reach the setup steps, which here are explained in more detail.
- Click Generate Token to generate a new token, and click the copy icon to copy it to your clipboard.
2. Set up Supernova Sync in Tokens Studio
- In the Tokens Studio plugin, go to the Settings tab.
- Under Sync Providers, Add new provider called Supernova.
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 Figma Tokens data. Because both your token structures within Token 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 Token Studio and where to write it in Supernova. Specifically:
- tokenSets describes which token sets should be taken from Token Studio and imported into Supernova. Each token set is name of one of your Token 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.
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"
}
]
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.
7. Push and pull from Supernova
With integration setup, you can use the push and pull functionality in Tokens Studio:
- Use Push to write any new changes to Supernova.
- The small blue dot signifies that there are changes that you haven't yet pushed to Supernova.
- Use Pull to download any tokens from Supernova that someone else pushed for you. Note that Tokens Studio tokens can't be edited in Supernova yet, and you or anyone from the team must edit them through the plugin interface, then push to Supernova to see the changes.
To check that everything went right, navigate to token section of our design system. When you Push your tokens, they'll show up there (refresh browser to see the changes)!
Keep data up to date
When token definitions are updated in Tokens Studio, they can then be synced to Supernova from the plugin.
- In Tokens Studio, click Push to push token information into Supernova. This requires integration setup, as described in the steps above.
- The tokens will then update in Supernova, and changes will be shown in Data sources in the Latest updates column.
Working with themes
If you’d like to use Tokens Studio as the data source for your theme, select ‘No source’ and finish creating the theme. Then, edit the theme to add Tokens Studio as the source. Learn more.
- Make sure you've created a theme in Supernova
2. Update mapping in Tokens Studio integration to update to theme
To update the mapping to write to a theme instead of base values for tokens, include a new key to your Tokens Studio provider settings called supernovaTheme:
[
{
"tokenSets": ["global", "light"],
"supernovaBrand": "Default",
"supernovaTheme": "Light"
}
]
In the example above, tokens from global and light sets will be written into Supernova brand called Default, theme called Light.
Handling base values and themes together
To write both base values of tokens and themes together, simply add another mapping combining everything we learned so far:
[
{
"tokenSets": ["global"],
"supernovaBrand": "Default",
"supernovaTheme": null
},
{
"tokenSets": ["global", "light"],
"supernovaBrand": "Default",
"supernovaTheme": "Light"
},
{
"tokenSets": ["global", "dark"],
"supernovaBrand": "Default",
"supernovaTheme": "Dark"
}
]
In the example above, we are defining multiple mappings at once.
- The first mapping will synchronize our base tokens from set global, without any themed overrides, and write them to brand Default.
- The second mapping will synchronize our base tokens from set global, apply any overrides from light set and write it into Supernova brand Default, under Light theme.
- The third mapping will synchronize our base tokens from set global, apply any overrides from light set and write it into Supernova brand Default, under Light theme.
Click Save to save the mapping in your settings and click Push to reflect changes to Supernova.
Handling multiple brands
To write tokens to multiple brands, once again add a new mapping to your Supernova provider settings:
[
{
"tokenSets": ["global", "my-brand-a"],
"supernovaBrand": "Brand A"
},
{
"tokenSets": ["global", "my-brand-b"],
"supernovaBrand": "Brand B"
}
]
In the example above, we are synchronizing tokens with multiple Supernova brands at once:
- The first mapping will synchronize our base tokens from set global, apply any overrides from my-brand-a, and write them to brand Brand A. This assumes you have Brand A created in your design system.
- The second mapping will synchronize our base tokens from set global, apply any overrides from my-brand-b set and write them to Brand B. This assumes you have Brand B created in your design system.
Click Save to save the mapping in your settings and click Push to reflect changes to Supernova.
Working with Token Studio themes
If you are on the pro plan of Token Studio, you have access to themes. Themes are token sets combined together for easier manipulation. Supernova sync supports Token Studio out of the box. To make use of themes, modify your mapping with a new property called tokensTheme:
[
{
"tokensTheme": "My Theme",
"supernovaBrand": "Default"
}
]
You can either use tokenSets or tokensTheme, but you can't use both of them together. Internally, tokensTheme will get converted to tokenSets, so tokensTheme is effectively just a shortcut and you can achieve the same mapping with both approaches:
[
{
"tokensTheme": "My Theme",
"supernovaBrand": "Default"
}
]
[
{
"tokenSets": ["global", "light"],
"supernovaBrand": "Default"
}
]
Assuming My Theme is defined containing 2 sets, global and light, the result published into Supernova will be the same.
Remove the Tokens Studio integration
- To remove the Tokens Studio integration, in Data sources → Tokens Studio, click ••• and then Remove integration.
- Type DELETE into the dialog to confirm.
- The integration will be removed and the authentication token will also be invalidated.
- Because the authentication token was invalidated, it will no longer be possible to push or pull from Supernova.
