Last updated
Was this helpful?
Last updated
Was this helpful?
You can now split up your Tokens across several Figma files connected to styles and variables and maintain the connected references!
For example, you can have your primitive Tokens published as variables or styles in a separate file from other Tokens which reference them.
This enables you to use Figma's native library publishing features to manage permissions of who has access to your Tokens without loosing any of the connected references.
To set up non-local variables, you will need:
A Tokens Studio Pro licence.
A Paid Figma account to support the use of Variable collections and modes.
A Git Sync Provider account used to access the same Tokens Studio files across multiple Figma files.
Ensure your storage provider is setup in folder pathway for multi-file sync option (pro)
→
To follow along this guide, you can duplicate a copy of the Figma playground file used in the images and videos below.
Here are some terms you'll see in our docs about this feature.
Local styles and variables are attached to Tokens in the current Figma file in which you are working.
Non-local styles and variables are attached to Tokens in a different Figma file than the one you are currently working in.
If you edit Tokens connected to non-local styles/variables in this file, the updates will not impact the styles and variables. You need to navigate to the Local File where the styles/variables are published and Export to Figma.
The image below shows an example of both Primitive (left) and Decision Tokens (right) in the Plugin.
A Theme is one or more Token Sets (containing design Tokens) grouped to apply a styling effect to design elements.
The Theme Name is Exported to Figma Variables as a Mode with the same name.
Each Token living in the Token Sets within the Theme is exported to Figma as an individual variable with the same name.
A Theme Group is a collection of 1+ related themes identified by a unique name using the Tokens Studio Themes feature.
The Theme Group Name is exported to Figma Variables as a Collection with the same name.
The image below shows how Theme Groups and Themes map to Figma's Variable collections and modes.
Before you Export your Tokens to your first Figma File as Variables, you'll want to ensure your Themes are set up properly. As a reminder:
Each Theme Group will create a Variable Collection
Each Theme in the Theme Group will be created as a mode within Variable Collection
Each Theme Group can only be synced to a single Figma File.
If you want a separate Figma File for brandA and brandB, they would need to be in separate Theme Groups.
In this guide, we will assume Primitive Tokens are referenced inside Decision Tokens for a single brand, with a light and dark color mode.
Create a Theme Group for your Decision Tokens, for example primitives
Create at least one Theme within the Theme Group, for example all
Ensure all primitive Token Sets required for the theme have the enabled status (checkmark visible).
Create a Theme Group for your Decision Tokens, for example brands
Create at least one Theme within the Theme Group, for example Apple and Berry
Ensure all Token Sets within the Theme are configured as enabled (checkmark visible)
Create a Theme Group for your Decision Tokens, for example themes
Create at least one Theme within the Theme Group, for example light and dark
Ensure all Token Sets within the Theme are configured as enabled (checkmark visible)
Once your Themes are setup, push your Themes configuration to your Sync Provider.
Now that Themes are ready, we will start Exporting them to our Figma Files. Each file you setup requires the same basic steps:
Pull Tokens into the Figma file from your remote Token storage provider.
Export the desired Theme Group to Figma as Variables.
Sync your updates to your remote Token storage provider.
Publish the Figma library.
Navigate to the next Figma file and enable all related published Figma libraries in the new file and repeat the process.
In Figma file 1, the Primitive Theme Tokens where all the hard-coded values in your system are located will be exported as their own variable collection.
First, you have to set up your Figma file:
Ensure your file is located in a Figma project (drafts have limited variables support).
Ensure you are syncing your Token project to an external storage provider.
Open the Tokens Studio plugin and navigate to the Styles and Variables Menu and select Export Styles and Variables
Option menu configuration
Select the Variable types to export based on what is in your Tokens.
Ensure "Create styles from variables" is not selected.
Configure other options as desired
Confirm your changes.
Once you've confirmed your options, you'll be brought to the Export to Figma from Themes part of the Plugin.
Ensure only the all theme under the primitives group is selected (checkmark visible).
Select Export to Figma to confirm your changes.
Open up the Variables featue in Figma to check your your work.
Sync your changes to your Token storage provider before closing the Plugin.
This ensures when you work in a new Figma file to publish additional themes, the Plugin can share the data with the new Figma file and keep your references connected.
Use Figma's native library publishing feature to publish your library.
Navigate to the Assets tab in your Figma file and
Select the book icon to manage your libraries.
Select the Publish button.
Figma will show you the new variables collection (primitives in the this example) created as something to publish.
Ensure you've selected the Variable collection (checkmark visible)
Select the Publish button to finish.
You are now finished the work in File 1, where in this example, the primitive theme has been published as a variable collection.
Next is File 2. In this example, a theme of brand decisions has Tokens with values that reference Tokens included in the Primitives theme which have been published as a variable collection in File 1.
In Figma file 2, the Brand Theme Tokens will be exported as their own variable collection.
First, you have to set up your Figma file:
Ensure your file is located in a Figma project (drafts have limited variables support).
Use Figma's native library feature to enable the previously published Primitives library (File 1).
Reload the Figma file, this updates the plugin API with the newly connected library information.
Figma desktop app - right click on the file fab and select reload tab
Web browser - refresh the page.
Open the Tokens Studio plugin and navigate to the Styles and Variables Menu and select Export Styles and Variables
Option menu configuration
Select the Variable types to export based on what is in your Tokens.
Configure other options as desired
Confirm your changes.
Once you've confirmed your options, you'll be brought to the Export to Figma from Themes part of the Plugin.
Ensure only the apple berry cherry and tangerine themes under the brands group are selected (checkmark visible).
Select Export to Figma to confirm your changes.
Open up the Variables feature in Figma to check your your work.
You should see the values of the variables created in this file referencing the Tokens that were published in a different file.
In this example, its primitive decisions living in Figma file 1.
Sync your changes to your Token storage provider before closing the Plugin.
This ensures when you work in a new Figma file to publish additional themes, the Plugin can share the data with the new Figma file and keep your references connected.
Use Figma's native library publishing feature to publish the new Variables Collection (brand) as a shared library.
Navigate to the Assets tab in your Figma file and
Select the book icon to manage your libraries.
Select the Publish button.
Figma will show you the new variables collection (brands in the this example) created as something to publish.
Ensure you've selected the Variable collection (checkmark visible)
Select the Publish button to finish.
You are now finished the work in File 2, where in this example, the brand theme has been published as a variable collection.
Next is File 3. In this example, a theme of color-mode decisions has Tokens with values that reference Tokens included in the brand theme which have been published as a variable collection in File 2.
In Figma file 3, the Color Mode Theme Tokens will be exported as their own variable collection.
First, you have to set up your Figma file:
Ensure your file is located in a Figma project (drafts have limited variables support).
Use Figma's native library feature to enable the previously published Primitives library (File 1) and Brands library (File 2)
Reload the Figma file, to update the plugin API with the newly connected library information.
Figma desktop app - right click on the file fab and select reload tab
Web browser - refresh the page.
Open the Tokens Studio plugin and navigate to the Styles and Variables Menu and select Export Styles and Variables
Option menu configuration
Select the Variable types to export based on what is in your Tokens.
Configure other options as desired
Confirm your changes.
Once you've confirmed your options, you'll be brought to the Export to Figma from Themes part of the Plugin.
Ensure only the light-mode and dark-mode themes are selected (checkmark visible).
Select Export to Figma to confirm your changes.
Open up the Variables featue in Figma to check your your work.
You should see the values of the variables created in this file referencing the Tokens that were published in a different file.
In this example, its brand decisions living in Figma file 2.
Once you've confirmed your options, you'll be brought to the Export to Figma from Themes part of the Plugin.
Sync your changes to your Token storage provider before closing the Plugin.
This ensures when you work in a new Figma file to publish additional themes, the Plugin can share the data with the new Figma file and keep your references connected.
Use Figma's native library publishing feature to publish the new Variables Collection (theme) as a shared library.
Navigate to the Assets tab in your Figma file and
Select the book icon to manage your libraries.
Select the Publish button.
Figma will show you the new variables collection (themes in the this example) created as something to publish.
Ensure you've selected the Variable collection (checkmark visible)
Select the Publish button to finish.
You are now finished the work in all 3 files in this example.
There are some known limitations when working with non-local variables in Figma using Tokens Studio.
When working in a Figma file, the information in the file is passed through their plugin API to Tokens Studio.
Unfortunately, when you enable a new library in your Figma file, this addition of the library data isn't automatically added to the plugin API data shared with Tokens Studio. The fastest way to 'refresh' the data Tokens Studio has available from Figma, is to reload the Figma file.
Reload the file using Figma desktop app
Right click on the file tab and select reload tab.
Close and reopen the file.
Reload the file using a Web browser
Refresh the page.
Close and reopen the file.
When you need to update your Tokens, you need to navigate to the local Figma file where they are published to update the styles and variables.
Once changes are made in the Plugin, repeat the Export to Figma steps with the same configurations to update the attached Variables.
Sync your changes (updating a connect variable is a change) to your remote Token Storage provider.
Use Figma's native library publishing feature to publish your library changes.
Navigate to any consuming Library files and perform updates to Tokens, Libraries, and Components as needed.
In our example, a change to our brand Tokens would need to be Exported, synced, and published in File 2, then we would head to File 3 and:
Accept Figma's library updates from File 2.
Open the plugin and pull in changes from our sync provider.
Export to Figma with the same configuration as above to update any Variables/Styles which reference the new brand Tokens we updated in File 2
Sync the changes (updated variables/styles) to our remote storage provider.
Use Figma's native library publishing feature to publish the library changes.
If your Token structure is more complex, including multi-dimensional theming, color modifiers, or values calculated by math equations, your theme configuration may need to be adjusted to export correctly to Figma.
Recall that Token Sets within Themes have a status of Enabled, Reference only or Disabled.
When splitting your Variable collections across multiple Figma files, you may have to remind the plugin to 'look at' Token Sets, which pass their value to the Tokens in the current theme, by using the Reference only status.
In the example above, our brand themes have Tokens that inherit values from our primitive Token Sets. Let's say our primitive Color Tokens are created using color modifiers, and our Dimension Tokens are created using math equations to produce size and spacing scales.
In our apple theme configuration, we would want to ensure that all the Token Sets containing our primitive Tokens have the status of Reference only.
This tells the plugin to 'look' at the Variable collection we published from Figma file 1 (Primitive library), pass any calculated values from our primitive colors and dimensions to Figma file 2 (Brand library) and attach referenced Tokens between the two files.
Without the status of Reference only on the primitive Token Sets, the plugin might miss the calculated values needed to populate the brand Token Sets.
With a simple Token structure, this doesn't appear to be as much of a challenge.
Figma resources:
🔗
→
We refer to Tokens with as Primitive Tokens
We refer to Tokens with as a Decision Token as the new name, or alias, describes how the design decision is intended to be used in the system.
→
→
→
→
→
Design in Figma -
Playground file for non-local variables by Tokens Studio -
The Tokens Studio collection of Variable videos -
Our friends at have free learning resources on Variables -
Tokens Studio Plugin GitHub - Open issues for
Tokens Studio Plugin GitHub -
Tokens Studio Plugin GitHub -
Tokens Studio Plugin GitHub -
Add support for scoping and publishing variables and styles -
Ignore parts of the token name for variables and styles -
Theme Switcher for non-DS designers so I don't need variables anymore -
Tokens applied with Figma UI as Styles or Variables are Fragile -
Create Variable Collections With The Plugin's Order of Themes -
Show updated number of Variables (or styles) when exporting to Figma with updated values -
💡 Something to share?
🐞 If you are experiencing an issue not listed here, please reach out to us on the Troubleshooting channel of our , , or send us an email support@tokens.studio
💌 Visit to contribute or subscribe to updates.
