Names that survive the next change

The name outlives the value

--colour-red-error is a token that was named twice and will be wrong once. When the error colour becomes orange because red tested badly, the name is a lie that stays in the codebase for years, and every new person has to learn that red means orange here.

The rule is straightforward and the discipline is not: name by role, never by appearance.

Good: --colour-danger        Bad: --colour-red
Good: --colour-surface-raised Bad: --colour-light-grey
Good: --button-primary        Bad: --button-blue
Good: --card-interactive      Bad: --card-with-shadow

The exception is the primitive layer from the previous lesson, which is supposed to describe values, because that is its job. --blue-500 is a correct primitive name and an incorrect semantic one.

Numbers beat sizes

For any ramp, number the steps. Do not use light, medium and dark, because within a month you will need one between light and medium and there is no name for it.

--grey-50  --grey-100 --grey-200 ... --grey-900
--space-1 --space-2 --space-3 ... --space-8

The 50-to-900 convention is borrowed from font weights and has the useful property that there is always room to insert: 150 sits between 100 and 200, 250 between 200 and 300.

T-shirt sizes — xs, sm, md, lg, xl — are common and have two real problems. They run out, which produces xxxl and then xxxxl. And they have no arithmetic: you cannot reason that --space-6 is twice --space-3, because lg and sm do not relate.

Where t-shirt sizes genuinely work is for a small closed set that will not grow — component sizes, where small, medium and large are the whole space and always will be.

Order the words from general to specific

A consistent word order makes tokens findable by typing, because an editor's autocomplete groups by prefix.

--colour-text-primary
--colour-text-secondary
--colour-text-inverse
--colour-surface-base
--colour-surface-raised
--colour-border-subtle

Type --colour-text- and every text colour appears. Name them the other way round — --primary-text-colour — and they scatter across the list alphabetically, which sounds trivial and is the difference between a system people use and one they work around.

The general pattern that most published systems converge on:

[category]-[element]-[role]-[state]

--colour-button-primary-hover
--space-card-inset
--text-heading-lg

You do not need every slot every time. You do need the order to be the same every time.

Naming components

Same principle, one step up. A component's name should describe what it is for, not what it looks like.

Callout survives being redesigned from a yellow box to a bordered panel. YellowBox does not. Toast and Snackbar are both appearance-neutral and both widely understood; BottomPopup describes a position that may change.

The harder version of this is naming by role in the interface rather than by visual treatment: ActionBar rather than StickyFooter, FieldHint rather than SmallGreyText.

The honest part: naming is genuinely hard

There is no consensus in the industry. Major published design systems disagree about almost every convention above — singular versus plural, hyphens versus dots, whether to include the category prefix, whether background or surface or bg. Reading three systems will give you three answers, all defensible.

What matters far more than which convention you pick is that you pick one and apply it everywhere. A system with an idiosyncratic but consistent naming scheme is usable. A system that follows best practice in three places and something else in a fourth is not.

Naming things that come in pairs

One recurring difficulty deserves a concrete answer. A colour used as a background needs a partner colour for the text that sits on it, and the pair has to stay together or somebody will put dark text on a dark action colour.

The convention that works is an on- prefix, borrowed from Material Design and now widespread:

--colour-action      the surface
--colour-on-action   the text and icons that sit on it
--colour-danger
--colour-on-danger

The name states the relationship, so the pairing survives being copied into a component by somebody who was not thinking about contrast. This is a small convention that prevents one of the most common accessibility regressions, which is a themed background whose foreground was never updated with it.

Do not encode the value in the name

A related trap: --space-16 meaning sixteen pixels. It reads as helpful and it makes the value impossible to change, because a token called --space-16 set to 20px is a lie, and everybody who reads the name will assume 16.

Number the position on the scale, not the value at that position. --space-3 can be 16px today and 18px after a density review, and every name remains true.

The same applies to type: --text-lg survives a change; --text-20 does not.

The test that actually works

Ask somebody who did not build the system to find the right token for a task. Give them a concrete job — the colour for a destructive button's hover state, the space between a label and its input — and watch.

If they find it on the first attempt, the names work. If they have to open the file and read the whole list, the names do not, and the fix is usually word order or a missing category prefix rather than the individual names.

Do this once, early, with three people. Renaming tokens later is expensive because every usage moves, so the twenty minutes spent testing names before they spread is the best-value twenty minutes in the whole exercise.