diff --git a/docs/img/design-tokens/40-tokens-groups.webp b/docs/img/design-tokens/40-tokens-groups.webp new file mode 100644 index 0000000000..3e482f1c26 Binary files /dev/null and b/docs/img/design-tokens/40-tokens-groups.webp differ diff --git a/docs/user-guide/design-systems/design-tokens.njk b/docs/user-guide/design-systems/design-tokens.njk index b259a4bff0..b83b984a63 100644 --- a/docs/user-guide/design-systems/design-tokens.njk +++ b/docs/user-guide/design-systems/design-tokens.njk @@ -690,6 +690,50 @@ ExtraBold Italic
Exporting tokens as a single file.
+

Token groups

+

Token names are rarely short and simple. They often contain multiple sections that represent token type, state, property, variant, and more. To help manage this complexity, Penpot automatically organizes tokens into groups based on the structure of their names.

+ +

How token groups work

+

When Penpot encounters a dot (.) in a token name, it breaks down the name and structures it as nested groups. For example, a token named button.primary.default.background-color is organized into groups like this:

+ +

If you have another token like button.primary.hover.background-color, it shares the same group structure (button.primary) and appears nested within those groups.

+

This structure matches how tokens are organized in JSON format. When you export tokens, a token like button.primary.default.background-color is structured like this:

+
{
+  "button": {
+    "primary": {
+      "default": {
+        "background-color": {
+          "$value": "#f00",
+          "$type": "color"
+        }
+      }
+    }
+  }
+}
+ +

Visual appearance

+

In the Tokens panel, token groups appear as nested, collapsible folders. Only the last segment of the token name (the actual token) appears as a pill. The segments before it appear as group folders that you can expand or collapse.

+

When you create a new token, Penpot automatically unfolds the required path so you can see your newly created token. If you manually unfold a group path, it stays open even when you navigate to other areas of the app (this state resets if you reload the page).

+
+ Design Tokens Grouping +
+ +

Working with token groups

+

Token pills keep the same actions as before: you can delete, edit, and duplicate tokens from the context menu. When editing a token name, you'll see the full token path including all group segments.

+ +

Moving tokens between groups

+

When you edit a token name and change the group segments, the token moves to its new group automatically. If the new group doesn't exist, Penpot creates it. If the group already exists, the token is moved there.

+

For example, if you rename color.background.secondary to c.bg.sec, the token moves from the color.background group to a new c.bg group.

+ +

Deleting token groups

+

When you delete a token, if it's the last token in its group, the empty group is automatically removed as well. You can also delete entire token groups directly, which removes all tokens within that group.

+

Deleting a token group removes all tokens it contains. Make sure you want to delete all tokens in a group before removing it.

+