Page cover image

Remap Tokens

When you apply a Design Token to a node in Figma using the Tokens Studio Plugin, there is an invisible connection created that maps the Token data to the design element in Figma.

The way Figma identifies an individual design decision mapped to a node is by the Name of the Token.

A node in Figma refers to a design element, layer, style or variable. Each node can have several different types of Tokens applied depending on the type of node.

In Tokens Studio, to Remap a Token is to tell Figma to change the ID of that connection to a different Token Name. Once the connection has been remapped to the new Token, the plugin can send updated data about your design decision to your Figma design elements.

You'll find the Remap Tokens feature handy when you are:

The rename options are shown on the left with an annotation highlighting the option which takes the longest time to execute. On the right side, the Tokens Page shows the progress of the renaming process at the top of the plugin.

If you don't remap the connection between the Figma node and the Token to the new name, Figma won't be able to find the right Token because it's looking for the old name which no longer exists, and the Plugin won't know which nodes it is connected to.

This broken connection is is sometimes referred to as a breaking change or a broken Token.

In the Plugin

Remapping a Token is not an automatic process, you have to tell the Plugin which connections it should remap. There are several places where you can Remap Tokens depending on your current workflow:

  1. Tokens Page

  2. Inspect Page

    1. Single Token Remap

    2. Bulk Remap

1. Tokens Page

When you change the Name of an individual Token or Token group from the List View of the Tokens Page, the Plugin will launch the Remap feature to update the ID of attached connections to Figma nodes at the same time.

If you change the Name of a Token from the JSON View of the Token Page, you will need to use the Remap features on the Inspect page (↓ described below).

In the Plugin, once you edit a Token name and save your changes, you have the option to Remap all layers, styles or variables to the new name.

The Remap options you can configure vary based on:

  • If you are changing an individual Token Name or part of a group.

  • If you have more than one Token Set with the same Token Names (common with theming).

  • If you are using Themes in your Token project.

Two versions of the Rename Token options are shown, which are visible if your project uses the Themes (pro) feature. The version on the right shows an example of the options that should be selected if the Token you renamed is attached to a Variable in Figma with more than one mode.

Each of these workflows are described in detail in the Edit Token Names guide.

Edit Token Names

2. Inspect Page

From the Inspect Page of the Tokens Studio Plugin, select some design elements in your Figma file to display the list of Tokens applied to the layer.

Use the Deep Inspect control to see Tokens applied to all children layers if desired.

Tokens that have been applied using the Plugin can be Remapped. They appear with a chevron after their name.

Variables or Styles applied using the Figma UI can not be remapped using the Plugin. They appear with the hexagon or 2x2 dot icons before their name.

→ Jump to the Inspect Page guide if you'd like a detailed explanation on the Token List.

The left side example shows how the Inspect page looks before selecting a Figma design element compared with the right side example, showing many Tokens applied to a selected layer in Figma. The brand.accent-color and card.typography.heading Tokens can not be remapped as they have been applied using the Figma UI as Variables and Styles, indicated by the icons before their name.

Remap a single Token for a selected element

On the Inspect Page of the Plugin, once you have design elements in Figma selected with Tokens applied, you can remap a single token by selecting the chevron that appears after its name.

An example of the Inspect page of the Plugin shows how to open the remap feature by selecting the chevron next to the Name of a Token in the list.

Once the Remap Modal is open, you can:

  • Type the new Token Name in the input, or

  • Select the chevron to the right of the name to choose from the list of compatible Tokens.

    • You can use the input above the Token List to search for a text string.

Be sure to select the Remap button to save your changes.

An example of the Remap a single Token workflow. When the chevron next to the Token name is selected a select menu with search opens.

Once you are finished Remapping all desired Tokens, you'll need to navigate back to the Tokens Page and select the Apply Token Data button to push the new values to Figma to complete the process.

The workflow to Apply Token data to selected Tokens in Figma shows the navigation from the Remap modal on the Inspect page to the Tokens page.

It's important to note that the Remapping using this workflow will only change the connections IDs for the currently selected Figma elements. This means you may have to repeat this process on additional components or pages of your design file. If you want to Remap a Token across more of your Figma file at the same time, you'll want to use the Bulk Remap feature described below.

Bulk Remap Tokens

The Bulk Remap feature allows you to change the connection IDs of multiple design elements in your Figma file using a match and replace workflow.

If you are familiar with a "find and replace" feature in a text/code editor, it works very much the same way.

To access the Bulk Remap feature from the Inspect page of the Plugin:

  • Select a design element in your Figma file with Tokens applied.

  • Select the Bulk Remap button to open the modal.

The navigation to open the Bulk Remap modal from the Inspect page of the Plugin is shown on the left. On the right, the Bulk Remap modal is annotated with numbers to match their detailed descriptions below.

Bulk Remap Modal

The Bulk Remap modal allows you to match and replace strings of Token Names using the inputs:

  1. Match - the string you'd like the Plugin to find.

  2. Replace - the new string that will replace all instances the Plugin finds that match.

  3. Remap across document (slow) - tells the Plugin to expand the action across the entire Figma file instead of limiting it to the currently selected design elements.

Once you've filled out the inputs with your desired strings, be sure to select the Remap button to save your changes.

If you have a large file and have selected to Remap across document, it's important to let the Plugin complete this task before doing any other work in the Plugin or your Figma file.

An example of the Bulk Remap feature shows two broken Tokens listed on the Inspect page of the Plugin on the left. Selecting the Bulk Remap action opens the modal in the middle. Matching "card" to remap to "cards" shows the newly mapped Tokens on the right which are no longer broken.

Once you are finished Remapping all desired Tokens, you'll need to navigate back to the Tokens Page and select the Apply Token Data button to push the new values to Figma to complete the process.

You may want to configure the Apply Token Data button to Apply to document to ensure all Remapped Tokens are up to date.

→ Jump to the Apply Token Actions and Settings guide for more details.

The workflow to Apply Token data to all Tokens in Figma document shows the navigation from the Bulk Remap modal on the Inspect page to the Tokens page.

Power User Feature - Regular Expressions (RegEx)

The Bulk Remap feature in the Plugin supports Regular Expressions, also known as RegEx, which is the technical name for pattern matching when searching.

Searching for a pattern instead of a specific string of text is a powerful way to speed up your workflow when you need to remap more complex Token Names.

For example, if you want to target the beginning of a specific Token Name, you might want to use RegEx to say “only replace this if its the beginning of the string" by writing ^colors.fg where ^ tells the Plugin to look at the beginning of the Token Name.

RegEx learning resources:

Resources

Mentioned in this doc:

Community resources:

  • None yet!

💡 Something to share? Submit it here!

Known issues and bugs

Tokens Studio Plugin GitHub - Open issues for Token Remap

Tokens Studio Plugin Github - Open issued for Token Name Change Remap

🐞 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 [email protected]

Requests, roadmap and changelog

  • None yet.

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

PreviousInspect TokensNextStyle Dictionary + SD Transforms

Last updated

Was this helpful?