Token Names in Tokens Studio
The name
of a Design Token tells us who, or which parts of our system, this design decision is intended for.
You might recall from our Intro to Design Tokens Guide that the Token Name acts as the unique identifier for each design decision in the system and are the most customizable part of a Token's anatomy.

Each Design Token has a location of where it lives in our system files. In code, Design Tokens live in JSON files. In Tokens Studio, they live in Token Sets which are the no-code representation of a JSON file.
Each Design Token has to have a unique Name per location. However, Design Tokens in different locations may have identical names, and this provides the basis of Theming!
→ Jump to the guide on Theming.

theme/light-mode
which has the Token called theme-color.background.default
with a light color as its value, compared to the example on the right in the theme/dark-mode
Token Set which has the value as a dark color. Common Terms
We have seen many different ways to talk about Naming Tokens over the years and it can be really hard to keep them straight! So here's the common terms we will use across our technical docs that you should be aware of.
These terms are not the only way to describe Token Names; they are the labels the Tokens Studio team uses for simplicity across our documentation.
If your team uses different descriptive terms, that's totally okay!
Token Name
The Token Name is the ID of the design decision captured in the Design Token. Each Token within a Token Set must have a unique name. Token Names are used in code by engineers, so there are some specific nuances to be aware of covered in its own guide. The Name is also how the Plugin attaches a Token to a design element, style or variable in Figma.

button-label-color,
which could be applied directly to the button design element and represented as a hex code, color style, or variable in Figma. Token Groups
The period (.) character is used in a Token Name to create relationships between Tokens that should be grouped together.
Token Groups helps to organize your Tokens into a tree structure in the Tokens Studio plugin and their code files. In the guide for Token Groups, you'll learn about the powerful workflow features we've added to the Plugin which allows you to take bulk actions on Tokens in the same Group!

Here are some additional terms related to Token Names with Groups that might be helpful:
Alias Tokens
When a new Token is created, its Value can reference another Token. The new Token created is sometimes referred to as an Alias Token, because it's purpose is to provide an alias, or a new name, or an existing design decision with some context about how the design decision is intended to be used in the system.
This new name, or alias, is also referred to as its semantic name in the community.
For example, a new Token named success-default
with a value referencing {colors.green.500}
could be referred to as an Alias Token.
The name success-default
may also be referred to as a semantic Token, as it provides some meaningful context about how the colors.green.500
Token is intended to be used in the system.

Here are some additional terms related to Alias Tokens that might be helpful:
Working with Token Names
The Token Name appears anywhere in the Plugin you are creating, viewing or editing a Token.
From the Tokens Page of the Tokens Studio Plugin for Figma, there are three places to see the Name of a Token.
Token data on hover
Token form
JSON file
When Inspecting Design Elements or using Dev Mode in Figma, the Token Name will also appear to identify which Tokens are mapped to the specific layer you have selected.
1. Token Data on Hover
Hover on an existing Token to view its data. The name
appears as the first piece of data in the list.
If the Token has a flat name, you will see the full name on hover. If the Token has a name with Groups, you will only see the final part of the Token Path in the preview on hover.

2. Token Form
Right click on a Token Name and select Edit to view its properties as a form. The first input displays the Name.

name
input annotated. On the left side, the form is for a color
Token Type. On the right, the form is for a typography Token Type.
The Token Name also appears when it is being Referenced in the Value of another Token in the Value input.

color
Token form with its value
input open, showing available Token Names that can be referenced as the value. Once a Token Name is selected from the list, it appears wrapped in curly brackets as the value
in the Token Form. 3. JSON File
Use the Token View Toggle 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.

If you are comfortable working in code (and have edit permissions), you can edit Token Names in the JSON view. However, making changes to Token Names in the JSON files which have already been applied to design elements in Figma require a few extra steps to be aware of.
→ Jump to the guide on Editing Token Names for more details.
JSON ViewIn Figma
When you apply a Token to a design element in Figma, the name
of the Token can appear in a few placed in the Figma UI, depending on your project:
Styles and Variables - if the Token applied is attached to Style or Variable the matching name will appear in the design panel for the appropriate property when possible.
Unless you've set the Plugin to Apply all Tokens as Resolved Values.
Dev Mode - if you've configured Tokens Studio as a plugin in Dev Mode and selected it as your language.
If you want to learn more about how your Token names appear in Figma, check out these detailed guides:

Export to Figma as Styles or Variables

Apply Token Actions + Settings

Dev Mode + Tokens Studio
Transforming Tokens
Engineers typically transform Tokens used in code with Style Dictionary, which is tool-agnostic. Tokens coming from Tokens Studio require an additional step: @Tokens-studio/sd-transforms, an npm package that prepares Tokens for Style Dictionary.
During the transformation process, they often modify the Token names to match their preferred workflow.
Most common Token name modifications:
Change casing and punctuation.
Flatten them to remove groups.
Add or remove front matter/prefixes.
Remove designer-specific words.
It's important to consider how a Token Name may be modified during the transformation process to avoid unintentional naming collisions.
→ Jump to the Token Name Technical Specs for more details on naming transformations and collisions.
Naming Token Guides
Now that you've got the basics covered, check out these guides related to Naming Tokens in the Plugin:
Resources
Mentioned in this doc:
SD-Transforms - Read Me
Style Dictionary - https://styledictionary.com/
Design Tokens Community Group - W3C Draft
Design Tokens Community Group - W3C Draft, 5.1 Name and Value
Community resources:
None yet!
💡 Something to share? Submit it here!
Known issues and bugs
Tokens Studio Plugin GitHub - Open issues for Token Names
🐞 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?