Last updated
Was this helpful?
Last updated
Was this helpful?
When thinking about Themes, most people focus on the parts of a Token Structure that support switching between options controlled by the users of an interface, such as a light or dark mode preference.
However, not all themes switch.
For example, this documentation website has a switch for light and dark color preferences, but regardless of what option you have active, the typography and dimension design decisions remain the same.
Themes that switch are intended to always have one of the themes active, you can think of this as an 'either this or that' logic in the system.
For example, this documentation website always has either light or dark theme active.
This guide covers how to create Themes that switch using the Tokens Studio Plugin for Figma using a very simple example.
Once you've got the basics down, you can start to think strategically about your Token Structure to take advantage of multi-dimensional theming.
You might recall from the Token Name Techincal Specs guide that when the system has more than one Token with the same name located in different Token Sets, we have to tell the system which Token Value it should pay attention to.
Without the use of the Themes feature, the Plugin looks for any Token Set which is currently active (checkmark visible). If there is more than one Token Set with an active status, the Plugin favors the Token Set at the bottom of the list. You can think about this as the 'last set wins' logic of the plugin.
However, this can get confusing to manage as your system scales.
With the Themes feature, we set up a logic that allows you to toggle which Tokens Sets are active in the 'either this or that' logic with a single click.
Ensure Token Sets to be included in either theme have identical Tokens (names and types)
Using the Themes Manager, create a Theme Group with a unique name.
Create a Theme within that group with a unique name.
Select the Tokens Sets included in the Theme.
Create at least 1 additional Theme within that group with a unique name.
Select the Token Sets indluded in the Theme.
The themes manager will show all themes created within the group with a toggle switch next to them. Turning on a toggle for a theme will switch off all other themes within the group.
In two or more Token Sets, ensure you have at least one Token with the same name and type. The value can be different.
In this very simple example, both Token Sets mode-colors/light and mode-colors/dark have two Color Tokens named:
mode-colors.neutral.container.standard
mode-colors.neutral.foreground.standard
From the Tokens Page of the Plugin, open the Themes dropdown (it doesn't matter what Token Set is showing on the page):
Select Manage Themes
Select New Theme
From the create new theme modal, select the left input for Theme Group and enter a unique name.
In this example, the Theme Group name is mode-colors
Once you've added the Theme Group name:
Enter a unique name for the Theme in the input on the right.
Adjust the Token Set status below to ensure the checkmark is toggled on only for Sets to be included.
At least one Token Set must be enabled. There is no limit to how mant Token Sets can be included in a Theme.
Token Sets that belong to any additional Themes should be disabled (X icon toggled on, checkmark icon toggled off.
If you have a sophisticated Token Structure and you know the status of some Tokens Sets need to be reference only, ensure those are configured as needed.
Press the Save theme button when you are finished. You'll return to the Themes Manager where your new Theme will be visible.
In our simple example, the Theme name is light , and the Token Set named mode-colors/light is enabled (checkmark toggled on). The other Token Set in this project named mode-colors/dark is disabled.
The steps to create additional Themes within the same Theme Group are similar to above.
From the Themes Manager, select the New Theme button
From the New Theme modal, select the Add Group dropdown to open it.
You'll see a list of any Theme Groups that already exist in your project.
Select the Theme Group you created in the previous step.
In this example, the previous Theme Group called mode-colors appears in the dropdown.
Enter a unique name for the Theme in the input on the right.
Adjust the Token Set status below to ensure the checkmark is toggled on only for Sets to be included.
At least one Token Set must be enabled. There is no limit to how mant Token Sets can be included in a Theme.
Token Sets that belong to any additional Themes should be disabled (X icon toggled on, checkmark icon toggled off.
If you have a sophisticated Token Structure and you know the status of some Tokens Sets need to be reference only, ensure those are configured as needed.
Press the Save theme button when you are finished. You'll return to the Themes Manager where your new Theme will be visible.
In our simple example, the Theme name is dark , and the Token Set named mode-colors/dark is enabled (checkmark toggled on). The other Token Set in this project named mode-colors/light is disabled.
You can repeat this process as many times as needed to support all the themes you'd like to switch between in the same Theme Group.
Now that you've created a Theme Group with more than one Theme, it will appear in the Themes dropdown from the Tokens Page of the Plugin.
Selecting any Theme from the group will enable the Token Sets in the Theme and disable the status of Sets in the other Themes in the group.
In this example, selecting the light Theme changes the status of the color-modes/light Token Set and disables the color-modes/dark Token Set. Selecting the dark Theme does the inverse.
Once you export your Themes that switch as a Variable Collection in Figma
The Theme Group is mapped to a Variable Collection with the same name.
Each Theme within the Group is mapped to a Variable Mode with the same name.
If you have more Themes in a Theme Group than you Figma plan will allow, the Plugin will prioritize them in order from top to bottom.
→ Jump to the Guide on Exporting to Figma from Themes for more details.
As soon as your Token project includes Themes, there are JSON files created by the plugin to save your configuration data so it can be shared with developers. Once developers have the new Themes files in your external storage provider, they can use that data in their transformation process to turn the themes file into usable code.
SD-Transforms generic package includes a specific transforms to convert Tokens Studio themes into individual theme files for all possible permutations
→ SD-Transforms Read-Me Doc, Theming
If this is the first time you are working with Themes in your project, theres a couple things you'll want to do in the Plugin Settings make the transformation process as simple as possible:
Mentioned in this Guide
SD-Transforms Read-Me - Theming
Community resources:
None yet!
Tokens Studio Plugin GitHub - Open issues for Themes
None
→
💡 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.
Engineers typically transform Tokens used in code with , which is tool-agnostic. Tokens coming from Tokens Studio require an additional step: , an npm package that prepares Tokens for Style Dictionary.
