Marcus Andrey Study
Ler em português Library

Framework · Design systems · 3 min read

Token naming formula

A fixed order for building token names from general to specific (category, concept, variant, state), with a list of allowed words for each part, so every name tells people when to use it and new names stay consistent.

1Category

The kind of value. Always first.

color, space, radius
2Concept

The job the token does. Purpose, never appearance.

action, text, surface
3Variant

Which one of the concept, or a size.

primary, danger, md
4State

An interaction condition. Last, and only when needed.

hover, pressed, disabled

color . action . primary . hover → --hb-color-action-primary-hover

A token name built from general to specific, in one fixed order, with each part from an agreed list.

Use it when

  • You are naming the first semantic tokens of a system.
  • The token list has synonyms (danger, error, critical) or mixed orders (color.text.subtle next to subtle.border.color).
  • Designers and developers see different names for the same token in Figma and in code.

How to use it

  1. Choose the parts and their order. Most systems go from general to specific: category, concept, variant, state. Write it as one line, for example category.concept.variant.state. Output: the naming pattern.
  2. List the allowed words for each part. Categories (color, space, radius, font), concepts (action, text, surface, border, feedback), variants (primary, subtle, danger, sm, md), states (hover, pressed, disabled). Output: a vocabulary table, one column per part.
  3. Ban the synonyms. For each concept, pick one word and write down the ones you won't use. "Error is not a variant; use danger." Output: a short list of banned words with their replacement.
  4. Name primitives and semantics differently. Primitives describe the value (color.blue.600, space.4). Semantics describe the purpose (color.action.primary). Never put a purpose in a primitive name or a value in a semantic name. Output: two clear sets of names.
  5. Map the name to every platform. The dots are a path through groups in the token file. Write how the same name looks in Figma, CSS (with a namespace prefix) and native code. Output: one row per platform for each token.
  6. Check new tokens against the pattern. In review, read the name left to right. Every part should come from the vocabulary, in order, and the state comes last and only when needed. Output: a yes or no per new token, before it ships.

Worked example

Harbour, the design system of the ferry company Tidewater, writes its pattern as category.concept.variant.state, with the CSS namespace hb-.

Part Allowed words (excerpt) Example
Category color, space, radius, font color
Concept action, text, surface, border, feedback, inset, stack action
Variant primary, subtle, danger, success, sm, md, lg primary
State (optional) hover, pressed, disabled, focus hover

So the hover colour of the main action is color.action.primary.hover. In CSS it's --hb-color-action-primary-hover, in Swift or Kotlin colorActionPrimaryHover. A team asks for color.red-error. The review rejects it twice: "red" is appearance, and "error" is a banned synonym. It ships as color.feedback.danger.

Watch out for

  • Appearance in semantic names. blue, light and big become wrong in dark mode or after a rebrand.
  • Two orders in one system. Autocomplete stops helping, and people create duplicates because they can't find the token they need.
  • Renaming often. Every rename is a breaking change for someone. Add the new name as an alias first, then deprecate the old one.
  • A pattern only in people's heads. If the grammar isn't written down, each new contributor invents their own.

Template

Copy this into the system's docs and fill the vocabulary before naming the next token.

Pattern:    category.concept.variant.state   (state only when needed)
Namespace:  css prefix "...-"

Category:   color | space | radius | font | ...
Concept:    action | text | surface | border | feedback | ...
Variant:    primary | subtle | danger | sm | md | lg | ...
State:      hover | pressed | disabled | focus

Banned:     error -> danger · critical -> danger · bg -> surface

New token:  ....................................
  Parts in order, all from the lists?      yes / no
  No appearance words (blue, light, big)?  yes / no
  Figma:  ...   CSS: --...-...   iOS/Android: ...
Source
Nathan Curtis, "Naming Tokens in Design Systems" (EightShapes, 2020). Group and reference syntax: W3C Design Tokens Community Group, Format Module 2025.10.
Where to find it
Design Systems in Practice: Naming tokens › A name is a sentence

"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close