Themes that switch

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.

Keep in mind, there is no limit to how many themes in a group that can switch.

For example, a multi-brand design system may have four or fourty brands to switch between.

The Tokens page of the Plugin is shown with the Themes dropdown open. The first theme group, named primitives, has a single theme below it called all. There is an annotation pointing to it labelled with "theme does not switch". The second theme group, called brands, has four theme groups below it: apple, berry, cherry, and tangerine. There is an annotation with a bracket pointing to all four themes labelled with "themes that switch".

This guide covers how to create Themes that switch using the Tokens Studio Plugin for Figma using a very simple example.

You'll need a Pro licence for the Tokens Studio Plugin to use the Themes feature to follow along with the guide.

Once you've got the basics down, you can start to think strategically about your Token Structure to take advantage of multi-dimensional theming.

---

How it works

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.

In the Plugin

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.

1. Ensure Token Sets to be included in either theme have identical Tokens (names and types)

2. Using the Themes Manager, create a Theme Group with a unique name.

3. Create a Theme within that group with a unique name.

   1. Select the Tokens Sets included in the Theme.

4. Create at least 1 additional Theme within that group with a unique name.

   1. Select the Token Sets indluded in the Theme.

5. 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.

1. Token Sets with identical Tokens

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

On the Tokens Page of the Plugin the mode-colors/light token set is pictured on the left, the mode-colors/dark token set on the right. Both are annotated to highlight the current Token Set, and the two tokens mentioned above. In the color preview next to each Token Name, the values are different between the two images.

2. Create a Theme Group

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

On the left, the Tokens page of the Plugin has the Themes dropdown open. It shows no themes exist in the Token Project. The Manage Themes action is annotated with a line connecting to the right side image, a screenshot of the themes manager showing that no themes have been created. The new theme button is highlighted.

From the create new theme modal, select the left input for Theme Group and enter a unique name.

On the left, the Themes Manager is shown without any Themes created. The new theme button is annotated with a line pointing to the Create New Theme modal on the right.

In this example, the Theme Group name is mode-colors

On the left, the create new theme modal is open with the add group button highlighted with a line pointing to the screenshot on the right. The image on the right shows the add group button has been converted to a text input that has mode-colors entered into it.

3. Create First Theme

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.

→ Jump to the guide on Token Sets - Status for more details on reference only aka set-as-source.

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.

On the left, the Create New Theme modal is open with labelled annotations pointing to the theme group input on the top left, the theme name input beside it to the right, and the token set status below. The save theme button is highlighted with a line pointing to the screenshot on the right. The image on the right shows the themes manager is shown with a mode-colors theme group containing a theme called light.

4. Create Additional Themes

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.

On the left, the Themes Manager is shown with a mode-colors theme group containing a theme called light. The new theme button is annotated with a line pointing to the Create New Theme modal on the right. The add group dropdown is open and the previously created theme group named mode-colors is highlighted.

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.

On the left, the Create New Theme modal is open with labelled annotations pointing to the theme group input on the top left, the theme name input beside it to the right, and the token set status below. The save theme button is highlighted with a line pointing to the screenshot on the right. The image on the right shows the themes manager is shown with a mode-colors theme group containing a theme named light and a second theme named dark.

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.

5. Theme Switching

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.

The Tokens page of the Plugin is shown with the Themes dropdown open. The example on the left has a theme named light with a checkmark next to it, and a Token Set on the far left named light with a checkmark next to it. The example on the right has a theme named dark with a checkmark next to it, and a Token Set on the far left named dark with a checkmark next to it.

---

Theme Switching and Variables

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.

Figma Variable Collection beside the Themes Manager in the Plugin. The numbered annotations show the Theme Group to Collection names. The lettered annotations show the Theme to Mode names for the current Variable collection named brands.

Theme switching in the Plugin does not work once Variables are attached to the Themes that Switch.

You must use Figma's native mode switching.

→ Jump to the Guide on Exporting to Figma from Themes for more details.

---

Transforming Themes for use in Code

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.

Engineers typically transform Tokens used in code with Style Dictionary, which is tool-agnostic. Tokens coming from Tokens Studio require an additional step: @Tokens-studio/sd-transforms, an npm package that prepares Tokens for Style Dictionary.

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

Plugin Sync Settings

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:

Sync to a remote storage provider, like GitHub, GitLab, Bitbucket or Azure DevOps.

Configure your sync settings to save to a folder in your repository with multiple files.

---

Resources

Mentioned in this Guide

• SD-Transforms Read-Me - Theming

Community resources:

• None yet!

💡 Something to share? Submit it here!

Known issues and bugs

Tokens Studio Plugin GitHub - Open issues for Themes

🐞 If you are experiencing an issue not listed here, please reach out to us on the Troubleshooting channel of our community Slack, submit it on our feedback tool, or send us an email [e-mail]

Requests, roadmap and changelog

• None

💌 Visit https://feedback.tokens.studio/ to contribute or subscribe to updates.