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.

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

If you are syncing your Tokens to a remote storage provider, here's a friendly reminder to create a new branch to capture your new Token names as these can introduce breaking changes requiring attention from your engineers.

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!

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.

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.

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.

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.

If you want to add or remove a group within a Token Name, select any group following where you want the name change to take place. This shows the full Token path before the group you selected so you can choose where you want to change the group name. This also works for renaming more than one group at a time!

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.

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 nameor group directly in the JSON view, just be sure to save your changes using the action at the bottom of the plugin.

Editing the JSON files does not have the same workflow as changing names in the Token View of 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.
Any Styles or Variables attached to that Token (the previous name will continue to be the ID that Figma is looking for).
Any design elements or components that have the Token applied to them in your Figma file.

2. Configure your remap options

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 variable
- If you are using mode switching, be sure to enable the Rename in other sets option at the same time.
Rename style

Known Limitation - These option appear as soon as Themes are present in the Token Project. Even when the Token you are renaming is not included in a theme, or not attached to a style or variable.

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!

We've observed Figma files to appear frozen or offline while scanning very large files. Normally if you leave the file alone Figma will come back online and finish the process.

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.

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.

It's important to note that changing the Name of Tokens applied to components and design elements being using in code may introduce a breaking change requiring attention from your engineering team!

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