skip to content

In a design token naming taxonomy, what do the namespace, category, property, variant, state and scale segments carry, and why fix their order?

level: middleimportance: must knowfreq 50%

answer

  1. general to specific, left to right
  2. who owns it, what kind, applied where
  3. role, then condition, then step
  4. one order means no permuted duplicates
  5. segments map onto nested groups

basics

~20 s

Namespace says which system owns a token, category the kind of decision, property what it applies to, variant the role, state the condition, scale the step. A fixed order makes names guessable, sortable, checkable and free of permuted duplicates.

solid answer

~40 s

A common convention builds names general-to-specific: **namespace** (`news`, the owning system), **category** (`color`, `space`, `font`), **property** (`text`, `background`, `inset`), **variant** (the role, such as `breaking` or `secondary`), **state** (`hover`, `visited`, `disabled`) and **scale** (`sm`, `200`). So `news-color-text-link-visited` reads as the system's text color for visited links. Segments that do not apply are omitted, but the rest keep their positions. Fixing the order means a consumer can guess a name before looking it up, autocomplete narrows by prefix, related tokens cluster in sorted lists, the same decision cannot be created twice as `color-text-primary` and `text-color-primary`, and a simple pattern can reject malformed names. The exact order matters less than choosing one and documenting it.

code

json · 15 lines
json
{
  "news": {
    "color": {
      "text": {
        "link": {
          "visited": {
            "$type": "color",
            "$value": { "colorSpace": "srgb", "components": [0.36, 0.2, 0.55] },
            "$description": "Text color for article links the reader has already opened"
          }
        }
      }
    }
  }
}

go deeper

for a junior

Recall the six segments in order and what each carries, and be able to read a name like news-color-text-link-visited aloud as a sentence.

for a middle

Explain why the order is fixed: guessability, sorting, no permuted duplicates, mechanical checks. Mention that empty segments are omitted and the format forbids periods and braces in names.

for a senior

Show judgement on extending the grammar: when a new concept is a variant word versus a new position, and how to keep each segment's vocabulary closed across many contributing teams.

for a principal

Treat the grammar as a published contract across web, native and design files; weigh a richer grammar's precision against the cost of every team learning and applying it.

## The six segments Many design systems compose **design token** names from a fixed sequence of segments, read from general to specific. Not every token uses every segment, but each segment always sits in the same position. The order below is one widely used convention; the point is to pick one and hold it. | Segment | Carries | Examples in a news product | |---|---|---| | Namespace | which system owns the token | `news` | | Category | the kind of decision | `color`, `space`, `font`, `radius`, `duration` | | Property | what the value is applied to | `text`, `background`, `border`, `inset`, `size` | | Variant | the role or emphasis | `primary`, `secondary`, `breaking`, `opinion`, `link` | | State | an interaction or status condition | `hover`, `pressed`, `visited`, `disabled` | | Scale | a step on an ordered ladder | `sm`, `md`, `lg`, `100`, `200` | Composed examples: `news-color-text-link-visited`, `news-color-background-breaking`, `news-space-inset-md`, `news-font-size-headline-lg`. ## What each segment earns - **Namespace** keeps the system's names apart from a product team's own variables and from any second system sharing the page or app bundle, such as an embedded advertising or partner widget. It also makes system tokens recognisable at a glance in review. - **Category** groups every color, every spacing step and every duration together, so a reader browsing the list sees one kind of decision at a time. - **Property** separates decisions that share a category but not a use. A text color and a background color are chosen against different surfaces and contrast needs, so they are different tokens even when their values match today. - **Variant** carries the **intent**: which role in the product this value serves. It is where a news product's own vocabulary lives - breaking, opinion, sponsored, live. - **State** distinguishes the same role under a condition: a link at rest versus visited, a control at rest versus disabled. - **Scale** picks a step when a role comes in several sizes, such as headline sizes on a section front. ## Why the order is fixed 1. **Predictability.** A consumer who knows the grammar can guess `news-color-text-link-visited` before searching, and autocomplete narrows as they type category, then property. 2. **Sorting and grouping.** Documentation tables, code autocomplete and the design editor's variable list cluster related tokens because the shared prefix runs general-first. 3. **No permuted duplicates.** Without a fixed order, `color-text-primary` and `text-color-primary` can both be created for the same decision, and consumers split between them. 4. **Mechanical checks.** A fixed grammar with a closed vocabulary per segment can be validated by a pattern, so a review or an automated check can reject a name that puts state before property. 5. **Fit with the source file.** In the Design Tokens Community Group format a token's path is its group names and its own name joined by periods, so general-to-specific segments map naturally onto nested groups: `news` contains `color`, which contains `text`, and so on. ## Rules that keep the grammar clean - **Omit, do not pad.** `news-space-inset-md` has no variant or state; inventing filler words for empty positions makes every name longer and no clearer. - **Close each vocabulary.** Document the allowed categories, properties and states. A new word enters through review, not through one team's pull request. - **One concept per segment.** A segment holding two ideas (`breaking-hover`) hides a state inside a variant and defeats sorting. - **Respect the format's character limits.** The Design Tokens Community Group format says a token or group name must not begin with `$` and must not contain `{`, `}` or `.` anywhere, because those characters carry meaning in properties, alias references and paths. It also treats names as case-sensitive and notes that names differing only in case are likely to collapse into duplicates when a tool converts them for another language. - **Leave platform spelling to the build.** How each platform writes the final name - separators and letter case for web versus native code - is decided when tokens are generated per platform, not in the taxonomy. ## Where teams legitimately differ Some systems put property before category (`text-color`), some put scale before state, and some add a segment for a component or a content type. None of these is wrong. What causes damage is **two orders in one system**, or an order that exists only in someone's head. A short naming page with the grammar, the vocabulary for each segment and a handful of worked examples is usually enough; the tokens themselves then teach the pattern to every new consumer, whether they write web, native or design files.

  • A news team needs tokens specific to live blogs; where does live-blog go in a fixed design token naming grammar?
    Usually into the variant vocabulary, as a role like `live`, added through review. That keeps the grammar unchanged for everyone. Adding a new segment position is a bigger decision, because it changes how every existing name reads and sorts, so it should be reserved for a concept that cuts across many categories.
  • Why is a period a poor separator inside a design token name?
    The Design Tokens Community Group format forbids `.` anywhere in a token or group name, because paths and alias references join group and token names with periods. A name containing a period would be ambiguous in a reference. Segments inside one name are therefore commonly joined with hyphens, while nesting uses groups.

saying these in an interview costs you the question

  • Every token must fill all six segments, even with filler words.
  • Order does not matter as long as each word appears somewhere.
  • A build tool can infer a token's type from its group or name.
  • The six-segment order is a standard every design system must follow.
  • A state word can be folded into the variant, like breaking-hover.