Felix
Articles

How I name colours in a design system

1 min read

The first colour system I built had names like blue-500 and warm-grey-2. It lasted until the first rebrand, when blue became green and every component had to be touched. Now I name colours after the job they do.

Two layers

I keep two layers of names. The bottom layer is the palette — raw values that nobody uses directly. The top layer is the tokens components actually reference.

CSS
:root {
  /* palette: what the colour is */
  --paper-50: oklch(0.985 0.004 84);
  --ink-900: oklch(0.2 0.004 70);
  --ink-500: oklch(0.53 0.006 70);

  /* tokens: what the colour does */
  --background: var(--paper-50);
  --foreground: var(--ink-900);
  --muted-foreground: var(--ink-500);
}

Components only ever see the second group. A rebrand changes the first.

Name the job, not the look

Good token names answer "where is this used?" rather than "what does it look like?". --foreground survives a dark mode; --black does not.

A colour name should still be true when the colour changes.

Fewer than you think

Most interfaces need surprisingly few tokens: a background, a foreground, one or two greys, a border and a single accent. Every extra token is a decision someone has to make later, usually in a hurry.

Restraint in naming leads to restraint in use, and restraint in use is most of what makes a palette feel considered.

Field Notes

A short letter every few weeks — new essays, small experiments and things worth reading.

1,846 readers already get it. No spam, unsubscribe any time.