Edit Token Names
By now you know the Name of a Token acts as the ID for a design decision. This means when you change the Name of a Token, you are also changing the ID being used throughout your system to find that particular design decision.
The Plugin has some optional features to make renaming an existing Token a quick and easy task. However, its important to understand how it works so you can avoid breaking changes when possible and know how to handle them when they do come up.

How it works
When you attach a Design Token to a node in Figma using the Tokens Studio Plugin, there is an invisible connection created.
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.
This connection allows the Plugin to send data to Figma so it can apply the design decisions captured in the Token to the node the Token has been applied to.
The way Figma identifies the individual connections mapped to a nodes is by the Name of the Token.
When you change the Name of a Token, the Plugin has a built in Remap feature to update the ID of attached connections to Figma nodes at the same time.
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
There are three steps to renaming a Token in the Plugin:
Enter the new Name of a Design Token
Configure your Remap options to tell the Plugin where to apply the new name in your Figma file.
The Plugin applies the new name to design elements, components, styles or variables based on your Remap options.
Sync the changes to your Remote Storage provider and publish any Figma library updates.
1. Enter the new Token Name
There are a few ways to change the Name of a Token, each with a slightly different workflow:
Token Form
Token Group
JSON view
Be sure to follow the best practices for Token Names based on your project requirements and the technical specifications!
→ Jump to the guide on Token Name Technical Specs if you need a refresh.
Token Form
From the Tokens page of the plugin, navigate to the Token you want to update. Right click on its name and select Edit to view its properties as a form.
The Token Form for each Token Type is unique, but the Name always appears as the first input.

colors.eggshell.300
has been right-clicked to reveal its action menu. When the edit
action is selected, its information appears as a form, pictured on the right. The annotations show the original name on the top of the Token form and a new name entered in the 1st input. Once you've entered the new name
in the first input, select the Save button at the bottom of the Token Form. The plugin will:
Update the JSON file for the current Token Set to the new name.
Update any Tokens values that reference it with the new name.
Open the Remap options modal so you can configure how the Plugin implements the new name in Figma, described below ↓.
If you've changed a grouped Token Name from its form, the change will only apply to that individual Token. If you want to apply the changes to all Tokens within that group, consider renaming the group from the Tokens Page directly (described below ↓).
Token Group
If your Token Names are written with periods in them to create groups, you can make bulk name changes to all Tokens with the same group.
If you only want to change the name of an individual Token with the group, consider renaming the Token from its Token Form (described above ↑).
→ Jump to the guide on Token Groups for more details
From the Tokens page of the plugin, navigate to the Token Group you want to update. Right click on a Token Group name to open its action menu:
Select Rename
Enter the new name in the input
Select the Change button to save your new name.

eggshell
has been right-clicked to reveal its action menu. When the edit
action is selected, its information appears as a form, pictured on the right. The annotations show the original name on the top of the Token form and a new name entered in the input. The plugin will:
Update the JSON file for the current Token Set to the new group name.
Update any Tokens values that reference these Tokens with the new group name.
Open the Remap options modal so you can configure how the Plugin implements the new name in Figma, described below ↓.
JSON View
Use the Token View Toggle to see your Tokens written in JSON code files. The Name will appear as the first part of data about the Token.
If the Token has a flat name, you will see the full name before the rest of the properties. If the Token has a name with Groups, the JSON file will organize the data by groups.
You can edit the Token name
or group directly in the JSON view, just be sure to save your changes using the action at the bottom of the plugin.
→ Jump to the JSON view docs to learn more about editing code files in the Plugin.

Once you've saved the changes to your JSON file, the Plugin does not perform any additional steps. This means you may have to manully update:
Any Token values referencing these Tokens with the new name. If you updated a group name, that impacts more than one Token.
Find those Tokens and update their Values from their Token Form.
Any Styles or Variables attached to that Token (the previous name will continue to be the ID that Figma is looking for).
Use the Export to Figma feature and select the Option to
Update existing style and variable names
Any design elements or components that have the Token applied to them in your Figma file.
Use the Remap feature from the Inspect page of the plugin.
2. Configure your remap options
After you've saved the new Token name from its Token Form or Group Name, the remap modal will open so you can configure where the Plugin should implement the name changes in the current Figma file.
Selecting one of these options changes the name of Tokens attached to layers of design elements:
Selection - Only elements actively selected on the Figma canvas.
Page - All elements on the current page within the Figma file.
Document - All elements on every page within the Figma file.
Rename in other sets - Select this to remap the Name across all sets.
Only visible when the name change happens from the Token form and there is a Token with the same name in another Token Set

rename in other sets,
which is only visible when certain conditions are met.If you are working with Themes (pro), selecting these options will automatically change the name of Styles of Variables attached to the Token with the name change.
Rename variable
If you are using mode switching, be sure to enable the Rename in other sets option at the same time.
Rename style

Confirm and wait
Once you've selected your Remap options, use the actions to confirm:
Select the Cancel button to save your Token name change in the Plugin and bypass the remapping feature.
Select the Yes button to confirm your selection, and start the remapping process.
The Plugin starts to scan your Figma file based on your configuration to remap to the new name.
You'll see the progress and a rough estimate of how long it will take at the top of the Plugin. If your file has a lot of pages, components, nested components, styles and variables, this could take some time.
It's best to let the Plugin complete remapping all nodes in the Figma file before doing anything thing else in the Plugin or your Figma file. If you rename another Token before closing the Plugin, the previous remap options will be selected for you to speed up your workflow!

If something unexpected happens and you have to close the Figma file before the remapping process finished, you can use the Remap feature from the Inspect page of the plugin at anytime. This is also helpful if you edited your Token names in the JSON view, or a non-local Figma file.
→ Jump to the guide on the Remap feature for more details.
3. Sync your changes
If you are syncing your Tokens to a remote storage provider, the Plugin will remind you to push (or send) your changes as soon as your Token Name change is saved by showing an indicator on the Push button in the footer of the Plugin.
Sync Changes to Remote Storage - Push and PullIf you haven't already, you may want to create a new branch dedicated to these name changes, and be sure to leave your developers a really nice commit message with additional details on the changes you made.
Branch Switching (pro) - Version ControlIf you are working in a multiple Figma file setup, be sure to publish your library changes so the rest of your team has access to any updated components, styles and variables related to the new names.
Update attached Styles and Variables
After you've changed a Token Name, you may need to update the name of any Style or Variable that is currently attached to the Token.
Jump to a guide on Exporting to Figma for more detials:
Resources
Mentioned in this doc:
Figma Plugin API Docs - Nodes
Figma Learn - Publish updates to a Library
Community resources:
None yet!
💡 Something to share? Submit it here!
Known issues and bugs
Tokens Studio Plugin GitHub - Open issues for Rename and Remap Tokens
🐞 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.

Last updated
Was this helpful?