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 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:

Updating
Troubleshooting broken Tokens

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:

Inspect Page

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.

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.

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

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.

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.

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.

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.

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 Bulk Remap modal allows you to match and replace strings of Token Names using the inputs:

Match - the string you'd like the Plugin to find.
Replace - the new string that will replace all instances the Plugin finds that match.
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.

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.

Power User Feature - Regular Expressions (RegEx)

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: