Tokens Studio for Figma
  • Getting Started
    • Tokens Studio Plugin for Figma
    • Install the Figma Plugin
    • Pro Licence for the Figma Plugin
    • Join the Slack Community
    • Feature Requests - Featurebase
    • Changelog - Featurebase
  • Design Token Fundamentals
    • Intro to Design Tokens
      • Token Anatomy - Type
      • Token Anatomy - Value
      • Token Anatomy - Description
      • Token Anatomy - Name
  • Token Management
    • Token Types
      • Asset
      • Boolean
      • Border - Composite
      • Box Shadow - Composite
      • Color
        • Modified Colors (pro)
        • Gradient Colors
      • Dimension
        • Border Radius
        • Border Width
        • Sizing
        • Spacing
      • Number
      • Opacity
      • Other
      • Text (string)
      • Typography - Composite
        • Font Family
        • Font Weight
        • Font Fallbacks
        • Font Size
        • Line Height
        • Letter Spacing
        • Paragraph Indent
        • Paragraph Spacing
        • Text Case
        • Text Decoration
      • Composition (legacy)
    • Token Values
      • Token Values with References
      • Using Math in Token Values
    • Token Names
      • Token Name Technical Specs
      • Token Groups
      • Edit Token Names
    • Token Description
    • Token Sets
      • JSON View
  • Themes management
    • Themes (pro)
    • Themes that switch
  • Working in Figma
    • Variables and Tokens Studio
    • Styles and Tokens Studio
    • Export to Figma Guide
      • Export Options
      • Export Using Themes (pro)
      • Export Using Token Sets
      • Variables Skipped on Export
      • Styles with Variable References
    • Import from Figma Guide
      • Import Styles from Figma
      • Import Variables from Figma
        • Connect Themes to Imported Variables
        • Imported Variable Types and Token Types
    • Non-local Variables and Styles (pro)
    • Remove Tokens from Figma elements
    • Dev Mode in Figma
  • Settings Management
    • Plugin Settings
    • Base Font Size Setting
    • Token Format - W3C DTCG vs Legacy
  • Token Storage and Sync Integrations
    • Local Document - Figma File Token Storage
      • Figma Data Limits
    • Remote Token Storage Integrations
      • GitHub - Git Sync Provider
      • GitLab - Git Sync Provider
      • Bitbucket - Git Sync Provider
      • Azure DevOps - Git Sync Provider
      • JSONBin - Cloud Sync Provider
      • Supernova - Cloud Sync Provider
      • Tokens Studio Platform - Cloud Sync Provider
      • URL - Server Sync Provider
      • Generic Versioned Storage - Server Sync Provider
    • Multi-file Sync to Remote Storage (pro)
    • Manage Sync Providers
      • Edit Sync Provider
      • Change Active Sync Provider
      • Remove Sync Provider
    • Sync Changes to Remote Storage - Push and Pull
    • Branch Switching (pro) - Version Control
  • Inspect and Debug Tokens
    • Inspect Tokens
    • Remap Tokens
  • Transform Tokens for Development
    • Style Dictionary + SD Transforms
    • Official docs for Style Dictionary
  • Style Dictionary Playground
  • Troubleshooting
    • Reset Tokens from Dev Console
    • Tokens Studio Status
  • Open Source
    • Contribute
    • Shared Plugin Data
Powered by GitBook
On this page
  • Themes that switch
  • How it works
  • In the Plugin
  • 1. Token Sets with identical Tokens
  • 2. Create a Theme Group
  • 3. Create First Theme
  • 4. Create Additional Themes
  • 5. Theme Switching
  • Theme Switching and Variables
  • Transforming Themes for use in Code
  • Resources

Was this helpful?

Edit on GitHub
Export as PDF
PreviousThemes (pro)NextVariables and Tokens Studio

Last updated 22 days ago

Was this helpful?

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.

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

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

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

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.

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.

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.

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.

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.


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.

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.

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:


Resources

Mentioned in this Guide

  • SD-Transforms Read-Me - Theming

Community resources:

  • None yet!

Known issues and bugs

Tokens Studio Plugin GitHub - Open issues for Themes

Requests, roadmap and changelog

  • None

→

Jump to the guide on Token Sets - Status for more details on reference only aka set-as-source.
Page cover image
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".
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.
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.
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.
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.
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.
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.
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.
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.
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.
Cover

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

Cover

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

💡 Something to share?

Submit it here!

🐞 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

community Slack
submit it on our feedback tool

💌 Visit to contribute or subscribe to updates.

https://feedback.tokens.studio/

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.

Style Dictionary
@Tokens-studio/sd-transforms