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.

It might help to imagine each Design Token as a 'file' containing data about every individual design decision you make and the Token Set as the 'folder' where these 'files' are located, which helps you to keep things organized. However, like any folder and file system you might be familiar with, the Design Tokens in the Token Set must all have unique names. Have you ever tried to add a file to a folder on your computer that already has a file with the same name? Your computer will ask you if you want to keep both files and rename the new one or replace the old file.

In this mental model, Token Names with Groups create the individual "file" of a Token into a series of "sub-folders" or sections that enable you to quickly navigate through your design decisions and perform bulk actions.

For example, these Color Tokens do not have any grouping, also known as Flat names:

colors-green-100
colors-green-200
colors-green-300

Compared to grouped names, which replaces the dash (-) with a period (.):

colors.green.100
colors.green.200
colors.green.300

These 3 Tokens would end up being grouped in JSON file:

{
  "colors": {
    "green": {
      "100": {
        "value": "#0e1512",
        "type": "color"
      },
      "200": {
        "value": "#121b17",
        "type": "color"
      },
      "300": {
        "value": "#132d21",
        "type": "color"
      }
    }
  }
}
```

When you use groups in your Token Names, this helps to create logical grouping of similar design decisions which makes them easier find and faster to work with in code.

This is especially helpful when you start working with Component Specific Tokens! Your engineers will see all the Tokens related to a component grouped together which helps them work faster!

Working with Token Groups

In Tokens Studio, once a Token Group is created you can take advantage of powerful workflows which allow you take bulk actions on all Tokens with the Group:

Quickly add a new Token to a Group with it's name pre-filled.
Modify your Token Views by collapsing and expanding Token Groups.
Rename all Tokens within the Group.
Duplicate all Tokens in Group.
1. In the same Token Set (with a name change)
2. In a different Token Set
Delete all Tokens in a Group at the same time.
Tokens exported to Figma as Styles can be shortened

Create Token Groups

To create a Token Group, write the Name of the Token to include a period between each group. There is no limit to the number of groups within your Token Names.

1. Create a Token with a Group

Once a Token Group is created, hover on the Group Name to see a quick add action (icon button with a + symbol) to the right of the group name.

Selecting the quick add action allows you to create a new Token (same Token Type) within the same Group by pre-filling in the Token's name.

Once a Token is created with a grouped name, hovering on the Token Name displays only the final part of the name.

2. Collapse and expands Tokens by Group

Once a Token Group has been created, from the Tokens Page of the Plugin, select the name of any Token Group to collapse or expand all Tokens within the group.

The plugin is organized by Token Type, so to improve the workflow, when you collapse or expand a Token Group that behaviour is applied across all Token Types with the same group name in the current Token Set.

For example, collapsing the button.danger group in the Color Token part of the Plugin, also collapses that group in the Typography Token part of the plugin.

3. Rename all Tokens in a Group

Making the name change to the group will rename all children below it at the same time.

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.
- Or, select Cancel to close the confirmation modal without changing the name of any Tokens within the selected Group.

When choosing a new name for the Token Group, it's important to follow the best practices for naming based on your project requirements and the technical specs.

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!

Renaming only affects Tokens of the same type

You may have spotted the helper text on the rename group form as a reminder that renaming only affects Tokens of the same type . This means if you have many Token Types with the same group structure in the name, you have to remember to manually change the name of each Token Type.

For example, lets say you have a Token Set with all Tokens starting the word semanticand your team decides its not necessary anymore, you'll need to change the Group name for each Token Type in the set as a series of steps.

4. Duplicate all Tokens in a Group

Duplicating a group will duplicate all Tokens within the Group it at the same time in a Token Set of your choice. This is handy when ideating on new ideas, setting up new themes or components with similar Tokens.

Right click on a Token Group name to open its action menu.

Select Duplicate
Select the destination Token Set where the Tokens should be added
- If duplicating in the current Token Set, you must rename the group to ensure all Tokens maintain a unique name.
If you want to duplicate the Group to multiple destinations, you can re-open the Token Set select menu to add another destination.
Save and confirm your action.
Or, select Cancel to close the confirmation modal without duplicating the Tokens within the selected Group.

Known Issue

You must deselect the current Token Set from the menu as a manual step, the menu will close and any error messages should clear, then you can select a new Token Set as your destination for the duplication.

5. Delete all Tokens in a Group

Deleting a Token Group will permanently remove all children Tokens within the Group it at the same time.

This is a destructive task so be sure you are intending to delete all Tokens within the group and subgroups before confirming the action.

Right click on a Token Group name to open its action menu.

Select Delete
Save and confirm your action
Or, select Cancel to close the confirmation modal and keep your Token Group.

You may have to go through your Tokens to check for broken references due to Tokens being deleted as the plugin does not Surface this information to you.

6. Export to Figma as Styles

As your Token Names get more sophisticated, its common to add a prefix which helps to keep things organized for those on your team working with the Tokens.

But for those on your team not working with the Tokens directly, these prefixes may not be as helpful and often eat up the limited realestate they have to work with in the Figma UI.

W3C DTCG Token Format

A group is a set of tokens belonging to a specific category.
For example:
Brand
Alert
Layout
Groups are arbitrary and tools SHOULD NOT use them to infer the type or purpose of design tokens.

Figma uses the forward slash /to create their groups in variables and styles. The Plugin will automatically convert between period and forward slash when importing and exporting Tokens in Figma.

Tokens Studio is will be iterating on how we approach Groups in the near future to more closely align with the W3C DTCG specifications.