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.

In this infographic, the Token examples on the right side highlight the Name. The top code block shows a Token Name with groups. The bottom code block shows a flat Token Name.

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.

Two Token Sets in the same project are shown side by side. Both examples contain Tokens with identical names which is allowed because they are located in different Token Sets. The example on the left shows a Token set named theme/light-modewhich has the Token called theme-color.background.defaultwith 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.

Before you get started Naming your Tokens, you'll want to get familiar with the Common Terms related to Naming and how to work with them in the Plugin for Figma.

---

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.

The infographic shows the name of a Token called 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!

Two examples of Token names are shown. On the left, the Token names are considered "flat" because they do not contain any groups. On the right, the Token names have groups which create a tree structure which can be collapsed and expanded as needed.

Here are some additional terms related to Token Names with Groups that might be helpful:

Flat Name

A Token name which is flat does not contain any groups.

For example: colors-green-500

Folder Name or Tree Name

A Token name which contains groups are sometimes referred to as a folder or tree name because the groups organize the Tokens in a tree structure that behaves like a series of sub-folders.

Token Path

The Token Path is the full nameof the Token including any Groups. For example: colors-green-500 or colors.green.500

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

An example of a button is shown with a label annotated to show a series of Tokens with values referencing each other to arrive at the final color of the label text.

Here are some additional terms related to Alias Tokens that might be helpful:

Component Tokens or Component Specific Tokens

Although Component Token may sound like a type of Token, its industry jargon to describe the name of a Token that is specific to a component.

They are also referred to as Component Specific Tokens for this reason.

For example, a Color Token named action.button.success.hover.background-colorhas a Grouped Name specific to a Button component. The different groups within the name help communicate that the Token is intended to be used for success actions when they are interacted with on hover and applied to the background container.

You can see by this example that a component specific name can also be considered an alias or semantic name which can be confusing!

Semantic Tokens

A Semantic Token is another way to say "Alias Token". While this term might sound like a type of Token, its really just industry jargon to describe the name of a Token with a new name (or alias) for an existing Token in our system that has meaninful context about how it is intended to be used.

For example, a new Token named success-defaultwith a value referencing {colors.green.500} could 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.

Primitive Tokens

Although a Primitive Token sounds like a type of Token, its industry jargon to describe the name of a Token that does not contain any context about how it is intended to be used.

For example colors.green.500 could be referred to as a Primitive Token.

Token Taxonomy

Token Taxonomy is a technical way to describe how a Token is named based on some agreed upon logic. Or in other words, a really fancy way to say "Token Name Template".

For example, for the Tokens in your system that have hard-coded values representing the options you have to choose from, you may decide on a Token Taxonomy that is attribute.category.identifier which looks like colors.green.500when naming a Color Token belonging to a green scale located at the 5th position on the scale.

Your team may decide to have different Token Naming templates for different parts of your Token Structure. A good example of this is the component specific Token Name above action.button.success.hover.background-color which follows a template that more closely resembles CSS.

---

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.

1. Token data on hover

2. Token form

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

Each Token will have different data to view on Hover depending on its type and value, however the position the data remains the same.

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.

Two examples of Token Sets being viewed from the Tokens page of the Plugin. The left example shows flat Token Names, the right shows Token Names with groups. When the Token Name is hovered on, it appears differently if the Name is flat or grouped.

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.

The Token Form for each Token Type is unique, but the Name always appears as the first input.

Two Token forms are pictured with its nameinput annotated. On the left side, the form is for a colorToken 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.

The image on the right shows a colorToken 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 valuein 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.

Two examples of Token Sets being viewed as their JSON file from within the Plugin. The left example shows flat Token Names, the right shows Token Names with 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.

The JSON view functions similar to Visual Studio Code thanks to an amazing open-source contribution from a Tokens Studio community member. 🫶

JSON View

---

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

Technical Specs for Token Names

The do's and don'ts of writing great Token Names.

Token Groups

A deep dive into how to take advantage of powerful workflows using Token Groups in the plugin.

Edit Token Names

Changing Token Names can be tricky! Here's what you need to know to be successful.

---

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 [e-mail]

Requests, roadmap and changelog

• None yet.

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