Marcus Andrey Study
Ler em português Library

Design Systems · Step 2 · 6 min read

Naming tokens

A token name is a tiny piece of documentation people read hundreds of times a day. How to build names from general to specific, name primitives by what they are and semantics by what they're for, pick a scale people can extend, and keep one name across Figma, JSON, CSS and native code.

The name is the interface of a token. Nobody reads a token's value; they read its name, in a Figma picker, in autocomplete, in a code review. A good name tells you when to use it without opening the docs. A bad one gets used wherever its colour happens to look right, and then the system means nothing. Naming is the cheapest place to get a design system right, and the most expensive place to fix later.

What you'll be able to do after reading:

  • Build a token name from general to specific, in a fixed order
  • Name primitives by what they are and semantic tokens by what they're for
  • Choose a scale that can grow without renaming
  • Keep one name across design tools and platforms

1. A name is a sentence

  1. colorcategory: what kind of value
  2. feedbackconcept: the job
  3. dangervariant: which one
  1. buttoncomponent
  2. primaryvariant
  3. padding-inlineproperty
SystemA real token nameThe order of its parts
Harbourcolor.feedback.dangercategory, concept, variant
Atlassiancolor.icon.successfoundation, property, modifier
Adobe Spectrumnegative-content-color-defaultconcept, property, category, state
IBM Carbon$text-primaryproperty, emphasis; the theme sets the value
Material Web--md-sys-color-primarynamespace, tier, category, role
A token name is a short sentence read from general to specific. Every big system orders the parts its own way; what matters is that one system uses one order, always.Names from each system's public documentation, linked in the lesson. Diagram: Marcus Andrey, CC BY 4.0.

Read color.feedback.danger left to right: it's a colour, for feedback, the danger kind. Each part narrows the one before. That's the main rule: from general to specific, always in the same order.

Atlassian describes its names the same way, in three parts: a foundation ("such as color, elevation, or space"), a property ("the UI element the token is being applied to, such as a border, background, shadow"), and an optional modifier ("its color role, emphasis, or interaction state"). It also notes that "not every token has a modifier. For example, color.text is our default body text color" (Atlassian, Design tokens).

The figure shows that big systems choose different orders. Spectrum puts the concept first (negative-content-color-default); Atlassian and Harbour put the category first. Either works. Mixing orders inside one system is what doesn't.


2. Primitives: what they are

Primitive names describe the value, neutrally, so they never become wrong:

  • Colour: hue and step. color.blue.600, color.sand.50, color.coral.600. Higher numbers are darker. The gaps (50, 100 … 900) leave room to add a step later without renaming.
  • Space: a numbered scale. Harbour uses space.1 to space.8 for 4 to 64 px.
  • Radius, font size: small named or numbered sets. radius.sm, radius.md; font.size.300.

Never put a purpose in a primitive name (color.brand-blue): the day the brand changes, the name lies. And never put a value in it (space.16px): the day you change the value, it lies the other way.


3. Semantics: what they're for

Semantic names describe purpose, never appearance:

Instead of Use Why
color.blue-button color.action.primary In dark mode it isn't the same blue
color.red-text color.feedback.danger A rebrand might make danger coral or orange
color.light-grey-bg color.surface.subtle "Light" is wrong in dark mode
space.16 space.inset.md The value can change with density

GOV.UK makes the same point for its colours: use govuk-functional-colour("brand") "rather than #1d70b8", and "only use the variables in the context they're designed for" (GOV.UK Design System, Colour). A purpose name used for the wrong purpose is still drift, just better disguised.

Useful parts for semantic names, in Harbour's order:

  • Category: color, space, radius, font
  • Concept: action, text, surface, border, feedback, inset, stack
  • Variant: primary, subtle, danger, success, or a size: sm, md, lg
  • State, last and only when needed: hover, pressed, disabled

So: color.action.primary.hover, color.text.subtle, color.border.focus, space.stack.lg.


4. Scales that can grow

Two kinds of scale names are common, and both work if you choose once:

  • Numbers (space.1 … space.8, font.size.100 … 600): easy to extend at the top, hard to squeeze a step in between unless you leave gaps (100, 200, 300).
  • T-shirt sizes (sm, md, lg, xl): easy to read, and fine for semantic tokens with few steps (space.inset.sm/md/lg). Awkward past xxxl.

Harbour uses numbers for primitives and t-shirt sizes for semantics, so space.inset.md → space.4 reads naturally.


5. One name, many syntaxes

A token is written differently in each place, but it should be the same name:

Where Harbour's color.action.primary
Token file (DTCG JSON) groups color › action › primary; referenced as {color.action.primary}
Figma variable primary inside the groups color › action, in a Semantic collection
CSS --hb-color-action-primary
Swift or Kotlin colorActionPrimary

The DTCG format doesn't allow ., { or } inside a single name, because the dot is how groups and references are written (DTCG, Format Module 2025.10). So the dots in color.action.primary are a path through groups, not part of one long name. The hb- prefix in CSS is a namespace: it keeps Harbour's properties from clashing with anyone else's on the page.

Figma lets you set a code name per platform for each variable, which Dev Mode then shows in its code snippets; there's room for up to three, for Web, Android and iOS (Figma Help, Create and manage variables). Fill them in, so designers and developers see the same token.


6. Common mistakes

  • Appearance in semantic names: blue, light, big.
  • Purpose in primitive names: brand-blue, error-red.
  • Two orders in one system: color.text.subtle next to subtle.border.color.
  • Synonyms: danger, error and critical for the same thing.
  • Renaming tokens often. Every rename is a breaking change for someone (see Deprecation and breaking changes).

7. Vocabulary

Term Meaning
Category The kind of value: colour, space, radius, font
Concept The job a semantic token does: action, text, surface, feedback
Variant Which one of the concept: primary, subtle, danger, md
State An interaction condition: hover, pressed, disabled
Namespace A prefix that marks a system's names, like hb-
Path The groups a token sits in, written with dots

8. Try it (no tools needed)

  1. Write five colour names you've seen in a real file or codebase.
  2. Mark each: does it describe the value, the purpose, or both?
  3. Rename the ones that mix the two, using category, concept, variant, state.

Reflection questions: Which of your new names would still be right after a rebrand? After dark mode?


9. If you already practise

  • Write your naming grammar down as a one-line pattern, like category.concept.variant.state, with the allowed words for each part. New tokens get checked against it.
  • Keep a list of banned synonyms. "Error is not a variant; use danger."
  • Before renaming, add the new name as an alias of the old one and deprecate the old name over a release, so nobody breaks overnight.

Checklist

Learn more

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Token tiers · Colour, type and spacing as tokens · Tokens from Figma to code · Deprecation and breaking changes · Motion tokens · Token naming formula

Saved only on this device.

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