Tokens
Bridging the gap between design tools and code couldn’t be easier than with tokens. Tokens have been a concept in design systems for a number of years and is simply a single design decision in code. In Figma these manifest as Variables.
The leverage semantic tokens gives us is that we no longer need to decide what to pick on a scale of options. Instead, semantic tokens gives us the where or when. It does this by expressing intent.
Token anatomy moodboard showing all five parts
Anatomy
Our tokens are built using five main parts: purpose, priority, modifier, state, and property.
Purpose
The purpose defines the token’s role in the user interface, based on user expectations. There are five categories:
| Purpose | Example token | Typical use |
|---|---|---|
| surface | --surface-primary-background-color | Non-interactive regions where content lives (modals, cards, dropdowns, entire pages) |
| action | --action-default-foreground-color | Interactive elements triggered by user actions (buttons) |
| control | --control-background-color | Interactive regions where users provide values (text fields, sliders) |
| feedback | --feedback-default-background-color | Non-interactive regions that sit on surfaces for system feedback (alerts, badges) |
| text | --text-header-md-font-weight | All text-related elements, defined by font properties (colors come from other purposes) |
Priority
Priority reflects the importance of a UI element to the user. It comes in three categories:
| Priority | Example token | Typical use |
|---|---|---|
| primary | --action-primary-background-color | Most important elements (headlines, primary buttons, attention-grabbing modals) |
| secondary | --action-secondary-border | Next level of importance (body text, secondary buttons, interactive flyouts) |
| auxiliary | --surface-auxiliary-foreground-color | Supporting elements (help text/messages, minimally-designed buttons) |
Auxiliary does not mean default. What is considered default priority for components depends on the purpose. In the case of text, the default is secondary because body copy is more common than smaller details for passive information.
Modifier
The modifier part describes specific visual or semantic treatments within a given token purpose, distinct from priority. While priority indicates hierarchical importance, modifier captures alternative stylistic or contextual presentations. Modifier is optional and only apply when further differentiation is necessary beyond purpose and priority.
| Modifier | Example token | Typical use |
|---|---|---|
| default | --action-default-background-color | Standard interaction elements |
| modal | --surface-modal-background-color | Elevated overlays (dialogs, drawers) |
| switch | --control-switch-background-color | Toggle controls |
| destructive | --feedback-destructive-background-color | Error or alert states |
| label | --text-label-font-size | Descriptive text for inputs or controls |
Modifiers enable nuanced, context-specific design decisions without compromising the structured clarity provided by purpose and priority.
State
States describe momentary conditions of interactive elements. They modify the base token without changing its purpose, priority, or modifier.
| State | Example token | Typical use |
|---|---|---|
| hover | --action-secondary-hover-background-color | Pointer resting on the element |
| focus | --action-default-focus-border | Keyboard or programmatic focus |
| selected | --control-selected-border | Element actively chosen |
| unselected | --control-unselected-border | Element available but not selected |
| disabled | --action-default-disabled-foreground-color | Element unavailable for interaction |
State is appended after the modifier when needed, e.g. --action-secondary-focus-background-color.
If no state is necessary, this part is omitted.
Property
The final part of a token describes the stylistic property being modified. Here are some general ideas, but available properties depend on the category:
- surface, action, modifier, and control categories handle properties like
color,corner-radius, andborder. - text handles font-related properties.
These properties often map directly to CSS, and the structure of a token mirrors CSS declaration syntax.
Examples of tokens in CSS variable form
Global tokens
Global tokens live outside the purpose/priority/modifier/state/property hierarchy and solve cross-cutting needs.
| Global family | Example token | Typical use |
|---|---|---|
| color | --color-blue-500 | Base color palette for all UI elements |
| opacity | --opacity-50 | Overlays and disabled states |
| space | --space-100 | Consistent padding and margins |
| corner-radius | --corner-radius-100 | Border radius for UI elements |
| font-family | --font-family-text | Typography system fonts |
| font-size | --font-size-200 | Typography scale for text elements |
| font-weight | --font-weight-500 | Text emphasis and hierarchy |
| border-width | --border-width-100 | Stroke thickness for borders |
| tint/shade | --tint-100 | Overlay effects and transparency |
Global tokens can be freely composed with semantic tokens in CSS/Figma variables, but they do not replace semantic naming.
Global token families
Footnote—Modes
All semantic token names remain constant across visual modes (Light, Dark, High-Contrast, etc.). A mode switch alters only the property of a token, ensuring designs reference the same intent regardless of user theme. Support for Dark and High-Contrast modes is planned for future releases.
Curation
The act of selecting values to associate with an intent is called curation. The name of the intent should provide a clear indication about where or when the token is meant to be used within an experience, typically a group of similar components or user expectations.