Reading design tokens

Understanding how design tokens are named will help you to use and apply them correctly.

Naming convention

The naming convention enables you to choose a design token that matches your design intent. Design token names may include terms that define the context, object, and modifier for a design token. For example:

[group].[component].[variant/category].[element].[position].[relationship].[property].[type].[scale].[state]

Context

Context provides the circumstances for the design token. For example, action.danger.[…] is the start of a design token that is in an action group of the danger variant. Similarly, banner.promotion.[…] is for a banner component of the promotion variant. Context can be either a group or component, but never both at the same time — the context is either broad or narrow. Design tokens that don't include a context are the most generally applied.

• Group: Broad context that can apply to many things. Examples are feedback, action, and control.
• Component: Narrow context that only applies to the component. Examples are avatar, button, and toggle.
• Variant/category: Further describes the context. Examples are confirm, danger, and neutral.

Object

An object is the element that the design decision applies to, and may include its position and relationship to other elements or constraints. For example, […].icon.left.[…] lets you know that the icon element referenced is in the left position. Another example is […].element.to-top.[…] that tells you this is about a generic element's relationship to the top boundary. An object is always present in a semantic and contextual design token name.

• Element: What's being addressed. Examples are background, border, and text.
• Position: Location of the element. Examples are top, right, or outer.
• Relationship: Association to other elements or constraints. Examples are to-edge, to-top, and gap.

Modifier

A modifier is an attribute of the object that's being addressed. The property itself can be further described by other modifiers to give it more meaning or to understand how it's being changed. For example, […].color.strong.hover identifies this as a color property that is strong in scale and in the hover state. Likewise, […].font-weight.semibold identifies that the font weight property is semibold in scale.

• Property: Defines what's being addressed. Examples are color, space, and size.
• Type: Similar to how a variant describes context, the type describes the property. Examples are info, link, and overlay. Type can include the same terms as a variant or category, like danger or success, but the same term will never be in two places for a single design token. It's one of the most flexible parts of the naming convention.
• Scale: An ordinal range that is finite and doesn't define distance between steps. Example ordinal scale are default, subtle, strong and sm, md, lg.
• State: Interactive or programmatically unique state. Examples include default, hover, and checked.

Examples

General design tokens with wide applicability.

More specific design tokens with specific use cases.

The most specific design tokens that are related to components.

Formats

One of the features of design tokens is their adaptability. They are defined in one place (input), and then output for various formats. This means that they won't always appear the same — differences in delimiters and language formatting — but the naming convention remains unchanged.

Unless indicating a specific format, a design token referenced in documentation will use the json formatting with a dot notation to separate terms and a dash to join compound terms. For example, focus-ring.outer.color.

Below is what the json input looks like, followed by a few examples of the design tokens formatted for different platforms.

Input

json

{
  "color": {
    "neutral": {
      "950": {
        "$value": "#1f1e24",
        "$type": "color"
      }
    }
  },
  "text": {
    "color": {
      "strong": {
        "$value": "{color.neutral.950}",
        "$type": "color"
      }
    }
  }
}

Output

CSS

--color-neutral-950: #1f1e24;
--text-color-strong: var(--gl-color-neutral-950);

SCSS

$color-neutral-950: #1f1e24 !default;
$text-color-strong: $gl-color-neutral-950 !default;

JavaScript

export const COLOR_NEUTRAL_950 = "#1f1e24";
export const TEXT_COLOR_STRONG = "#1f1e24";

Figma variables

color/neutral/950: #1f1e24
text/color/strong: color/neutral/950

Next, learn how to use design tokens →