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, and border.
• 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.