skip to content

For a design token, why should the name describe its intent rather than its value, and what breaks when a name spells its value?

level: juniorimportance: must knowfreq 62%

answer

  1. the name is the contract people read
  2. what happens at the next rebrand
  3. two roles sharing one look-alike token
  4. a name that lies versus a mass rename
  5. palette names may honestly spell values

basics

~20 s

An intent name such as breaking-news text color stays true when its value changes; a value name like red-text either lies after a rebrand or forces a rename in every consumer, and it couples unrelated roles that merely looked alike.

solid answer

~40 s

A design token's name is its interface: designers and engineers on web, native apps and the design editor choose a token by reading it. If a role token's name spells its value, such as `color-red-text` for breaking-news labels, two things go wrong. When the brand turns breaking news orange, the name either lies or has to be renamed in every consuming app and design file. And because the name only describes a look, teams reuse it for anything that happens to be red, such as errors and sale prices, so those roles can no longer change independently. An intent name like `color-text-breaking` says where the token belongs, survives value changes, and lets the system retune one role without touching others. Value names remain honest for raw palette steps, whose meaning is the value itself.

go deeper

for a junior

Recall that a token's name is read by people choosing it, so it should say where the token is used. Be ready with one example of a value name failing after a rebrand.

for a middle

Explain both failures: the lying name versus a mass rename, and unrelated roles coupled to one look-alike token. Show where value names stay honest, in the raw palette.

for a senior

Show you can spot hidden value words such as dark, white or serif in names that look semantic, and argue when two roles sharing a value today deserve separate tokens.

for a principal

Frame naming as contract design across web, native and design files: the cost of a wrong name is paid by every consuming team at every rebrand, so the taxonomy deserves review up front.

## What a token name is for A **design token** is a named design decision - a color, a spacing step, a type size, a duration - stored once and consumed by every platform a system ships to: the web front end, the native mobile apps, and the design editor where designers work. The **value** is what renders; the **name** is what people read. An engineer building a live-blog header in the app and a designer choosing a fill in the editor both pick a token by its name, so the name is the token's public interface. It should describe the job the value does - its **intent** - rather than the value itself. Compare two names for the text color of a news site's breaking-news label: | Name | What it tells a consumer | What happens when breaking news turns orange | |---|---|---| | `color-red-text` | the value is red | the name now lies, or every usage is renamed | | `color-text-breaking` | use this for breaking-news text | the value changes; no consumer touches code | ## Two ways a value-named token fails 1. **The name lies after a value change.** A rebrand, an accessibility fix or a new editorial palette changes the value. With a value name the team has two bad options: leave `color-red-text` holding orange, so the next reader believes it is red and misuses it, or rename it everywhere, which touches every consuming app, every design file and every open branch. 2. **Unrelated roles get coupled.** When the name only says `red`, teams pick it because it looks right. The breaking-news label, the form error message and the sale price in a subscription offer all land on the same token. Later the newsroom wants breaking news in orange while errors stay red, and nobody can change one without the others; the token has to be split, and someone has to work out which of hundreds of usages means which role. A third, quieter failure is **mismatched pairs**. A designer who sees `color-white` and `color-gray-900` has to know which goes on which surface; `color-surface-default` and `color-text-primary` state the pairing in the name, so the right combination is the obvious one. ## Where a value name is honest Not every token should be named by intent. A system's raw palette - the list of available colors, or the plain steps of a spacing ladder - exists to name values, so `red-500` there is accurate: its meaning *is* its value, and nobody should use it to express a role. How a system layers raw tokens beneath role tokens is its own topic (token tiers and aliasing). For naming, the rule is narrower: **if a token represents a decision about where something is used, its name must describe that use, not its current look.** ## Writing intent names well - **Name the role, not the screen.** `color-text-breaking` survives a homepage redesign; `color-homepage-top-strip` does not. - **Keep one emphasis vocabulary.** Choose `primary / secondary / tertiary` or `default / subtle / strong` and use it in every category, so readers learn one set of words. - **Watch for hidden values.** `color-text-dark`, `color-surface-white` and `font-serif-headline` look like intent names but still spell a value; they break the first time a dark mode, a second brand or a new headline typeface arrives. - **Prefer a few broad roles to many narrow ones.** A token per article element (`color-byline-text`, `color-dateline-text`, `color-caption-text`) multiplies names that all hold the same value; one `color-text-secondary` usually covers them unless a role genuinely needs to vary on its own. - **Split roles that may diverge.** If breaking news and errors are different decisions, give them different tokens even while they share a value today. - **Document the intent.** A one-line purpose statement removes guesswork; the Design Tokens Community Group format provides an optional `$description` property on every token for exactly this. ## How the value stays discoverable A common objection is that intent names hide what a token looks like. The answer is that the name is the wrong place for that information. Documentation pages render a swatch or specimen beside each token, the design editor previews the value, and code editors can show the description on autocomplete. The name carries what cannot be shown - the purpose - and the tooling carries what can. ## Why interviewers ask it The question tests whether a candidate treats a token as a **contract** rather than a variable with a nicer spelling. A native mobile team gets the same benefit as a web team: the generated constants keep their names across a rebrand, so a new value ships as a data change instead of a code change in every screen. A candidate who says value names are fine because you can see the color has not yet lived through a rebrand; one who says every token, palette included, must be named by intent has missed that raw values need honest names too.

  • If intent names hide the value, how does a designer know what a design token looks like?
    Through tooling, not the name. The documentation site shows a swatch or specimen beside each token, the design editor previews the value where it is applied, and code editors can surface the token's description on autocomplete. The name carries the one thing tooling cannot show at a glance - where the token belongs.
  • Is a design token named color-text-dark an intent name?
    Only half. `text` names the property, but `dark` describes the value. Under a dark mode or a second brand that token would hold a light color and the name would lie. An emphasis word such as `primary` or `strong` expresses the same intent without promising a lightness.
  • Should breaking-news labels and form errors share one design token because both are red today?
    Usually not. They are different decisions owned by different people - the newsroom and the forms guidance - and one may change without the other. Sharing a token couples them, so a later change forces a split and a hunt through every usage. Share a token only when the roles are meant to change together.

saying these in an interview costs you the question

  • Value names are better because you can see the color in the name.
  • A find-and-replace makes renaming a token across consumers cheap.
  • Every token, including the raw palette, must be named by intent.
  • Roles that look the same today should always share one token.
  • A name like color-text-dark is intent-based because it mentions text.