{"id":"l-ds-2-2","courseId":"design-systems","lang":"en","kind":"lesson","summary":"Name design tokens with a written grammar of category, concept, property, variant and state, so names stay true through dark mode, new brands and years of growth.","html":"

In Northwind’s old token file there was a token called --color-blue-new. Two years later there was also --color-blue-new-2 and --color-blue-newer. Nobody knew which was the brand blue. Naming is the part of a design system that looks like bikeshedding and turns out to be architecture: names are the API every designer and engineer types hundreds of times a week.

\n

A grammar, not a list

\n

Good token names come from a grammar: a fixed set of parts in a fixed order. Northwind’s semantic tokens follow this one:

\n
Text
--nw-{category}-{concept}-{property}-{variant}-{state}\n\n--nw-color-action-bg                 category=color concept=action property=bg\n--nw-color-action-bg-hover           … state=hover\n--nw-color-danger-text               concept=danger property=text\n--nw-color-text-subtle               concept=text variant=subtle\n--nw-space-inset-md                  category=space concept=inset variant=md\n--nw-radius-control                  category=radius concept=control
\n

Not every token uses every part, but the parts that appear always appear in that order. That buys you two things. People can guess names they’ve never seen: if --nw-color-action-bg-hover exists, --nw-color-danger-bg-hover probably does too. And sorted alphabetically, related tokens cluster together in every editor and in Figma’s variable panel.

\n

The nw prefix is a namespace. It stops collisions with third-party CSS and makes system tokens easy to search for, which you’ll use for adoption metrics later.

\n

Name the purpose, not the look

\n

At the primitive tier, naming the look is correct: --nw-blue-600 is a blue. At the semantic tier, the look is exactly what themes change, so names must describe purpose.

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Fragile nameWhy it breaksDurable name
--nw-color-red-bgTidewater’s error color is orange--nw-color-danger-bg
--nw-color-text-lightIn dark mode it is not light--nw-color-text-subtle
--nw-color-header-bgNamed after its first user--nw-color-surface-inverse
--nw-color-text-2Says nothing--nw-color-text-muted
\n

Scales: numbers or sizes

\n

Primitive scales need a naming scheme too. There are two common choices:

\n\n

Northwind uses numeric scales for primitives and t-shirt sizes for the handful of semantic spacing tokens (--nw-space-inset-sm, -md, -lg), because designers think in sizes and that set rarely grows. Pick one scheme per scale and stick to it. Mixing them inside one scale, such as --nw-space-2, --nw-space-md and --nw-space-24px, is the fastest way to make a scale nobody trusts, because people can no longer tell which values are siblings.

\n

Enforce the grammar

\n

A grammar that lives only in a wiki page lasts until the first busy contributor. Turn it into a check that runs in CI:

\n
JavaScript
const grammar = /^--nw-(color|space|radius|font|shadow|motion)(-[a-z]+)+(-[0-9]+)?$/;\nconst banned = /-(red|blue|green|light|dark|new|old|[0-9]+px)(-|$)/;\n\nconst proposed = [\n  '--nw-color-action-bg-hover',\n  '--nw-color-text-light',\n  '--nw-color-blue-new',\n  '--nw-space-inset-md',\n  '--nwColorDangerText',\n  '--nw-color-danger-text',\n];\n\nfor (const name of proposed) {\n  const ok = grammar.test(name) && !banned.test(name);\n  console.log(ok ? 'ok    ' : 'reject', name);\n}
\n

The banned list catches the habits that break first: color words, “light” and “dark”, “new” and “old”, and raw pixel values. Run it against every token file in pull requests, and print the rule that failed so contributors learn the grammar from the error instead of from a wiki page. It’s a blunt tool, and it will occasionally reject a good name. That’s fine; a contributor who hits it asks the core team, and the conversation is the point.

\n\n

Renaming without breaking people

\n

You will get some names wrong; everybody does. When you rename a token, keep the old name as an alias of the new one for at least one release, mark it deprecated, and announce it in the changelog. Section 4 covers the full deprecation path. In the exercise below, you review a batch of proposed names the way the Northwind core team does every week. Next, you put the semantic tier to work: one set of components, several themes.

\n","toc":[{"id":"sec-1","text":"A grammar, not a list","level":2},{"id":"sec-2","text":"Name the purpose, not the look","level":2},{"id":"sec-3","text":"Scales: numbers or sizes","level":2},{"id":"sec-4","text":"Enforce the grammar","level":2},{"id":"sec-5","text":"Renaming without breaking people","level":2}],"takeaways":["Semantic token names describe purpose (danger, subtle), never appearance (red, light), because appearance changes with themes.","A fixed order of name parts, such as category-concept-property-variant-state, makes tokens predictable to guess and easy to sort.","Numeric scales like 100 to 900 leave room to insert values later; t-shirt sizes read better but fill up.","Write the naming grammar down and enforce it with a lint rule, or every contributor invents their own."],"further":[{"title":"Custom properties (--*) (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/--*"},{"title":"Design tokens (Material Design 3)","url":"https://m3.material.io/foundations/design-tokens"},{"title":"Design Tokens Format Module 2025.10 (source on GitHub)","url":"https://github.com/design-tokens/community-group"}],"quiz":[{"q":"

Which semantic token name will still be accurate after Northwind adds dark mode?

","options":[{"text":"--nw-color-text-subtle","why":"Correct. “Subtle” describes the role (lower emphasis text), which holds in light and dark themes alike."},{"text":"--nw-color-text-light","why":"In dark mode the subtle text is a mid-grey on a dark background, so “light” either lies or gets confused with the theme name."},{"text":"--nw-color-text-gray-500","why":"Embedding a primitive in a semantic name means the name breaks the moment the theme maps it to a different grey."},{"text":"--nw-color-text-2","why":"A bare number says nothing about purpose, so nobody can pick it correctly without opening the docs."}],"answer":0},{"q":"

The dispatch team created --nw-color-header-bg for the top bar. Now the sidebar needs the same color. What’s the best move?

","options":[{"text":"Use --nw-color-header-bg in the sidebar too.","why":"The sidebar now depends on a token named for the header; when the header changes, the sidebar changes by accident."},{"text":"Copy the value into a new --nw-color-sidebar-bg.","why":"Two tokens for one decision drift apart, which is how the 64 greys happened."},{"text":"Rename it to a purpose-based token like --nw-color-surface-inverse and alias the old name to it during a deprecation period.","why":"Correct. The name now describes the shared role, and the alias gives consumers time to migrate."}],"answer":2},{"q":"

Your spacing scale is --nw-space-sm, -md, -lg. Designers now need a value between sm and md. What does this show?

","options":[{"text":"T-shirt sizes should never be used for tokens.","why":"They’re readable and work well for small, stable scales; the issue is only that they’re hard to extend in the middle."},{"text":"The new value should be a one-off pixel value in that component.","why":"A hard-coded value bypasses the scale and starts the drift again."},{"text":"Spacing tokens should be component tokens instead.","why":"Spacing is shared across components, so it belongs in the shared scale."},{"text":"Named steps fill up; a numeric scale like 100, 200, 300 leaves room for 150 later.","why":"Correct. Numeric scales trade some readability for room to grow, which is why many systems use them for primitives."}],"answer":3},{"q":"

Why does the DTCG format forbid . inside token names?

","options":[{"text":"Periods are not valid in JSON keys.","why":"JSON keys can contain any string, including periods."},{"text":"The period separates path segments in references like {color.action.bg}.","why":"Correct. A period inside a name would make the reference path ambiguous."},{"text":"CSS custom properties cannot contain periods.","why":"The rule comes from the token format’s reference syntax, not from CSS."}],"answer":1}],"exercise":{"kind":"choice","multiple":true,"options":["success-border","orange-badge","text-inverse","modal-shadow-v2","focus-ring","dark-surface"],"correct":["success-border","text-inverse","focus-ring"],"title":"Review this week's token proposals","prompt":"

Six semantic token names were proposed to Northwind UI this week. The system must support light and dark themes and two brands (Northwind and Tidewater), and follows the grammar --nw-{category}-{concept}-{property}-{variant}-{state}. Select every name you would approve as written.

\n","hints":["For each name, imagine it in dark mode and in the Tidewater brand. Does it still tell the truth?","Watch for color words, theme words, version numbers and names that only fit one component."],"explanation":"

The approved names describe a role: a success border, text on an inverse surface, the focus ring. Each stays accurate in every theme and brand. orange-badge describes a look that Tidewater’s palette will change, modal-shadow-v2 encodes history instead of purpose (and the next redesign gives you v3), and dark-surface breaks in dark mode, where most surfaces are dark. A role-based alternative would be --nw-color-surface-raised or --nw-color-surface-inverse.

\n","checkLabels":{},"optionText":{"success-border":{"text":"--nw-color-success-border","why":"Approve. It names a role (the border of success messages) and follows the grammar’s order."},"orange-badge":{"text":"--nw-color-orange-badge-bg","why":"Reject. ‘Orange’ is appearance; when the warning color changes for Tidewater, the name lies."},"text-inverse":{"text":"--nw-color-text-inverse","why":"Approve. ‘Inverse’ means text on the opposite surface, which holds in both themes."},"modal-shadow-v2":{"text":"--nw-shadow-modal-v2","why":"Reject. A version number records history, not purpose, and guarantees a v3 later."},"focus-ring":{"text":"--nw-color-focus-ring","why":"Approve. Every interactive component shares the focus ring, and the role is stable across themes."},"dark-surface":{"text":"--nw-color-dark-surface","why":"Reject. In dark mode almost every surface is dark, so the name stops meaning anything."}}},"words":686,"readMinutes":3}