← Community

Build A Color System

Build a colour system with semantic tokens, a real contrast floor, and a dark mode that is not an inversion — so every new screen is legible by default. Use when defining colour tokens, adding a theme, or fixing contrast problems.

---
name: build-a-color-system
category: design
description: >-
  Build a colour system with semantic tokens, a real contrast floor, and a dark
  mode that is not an inversion — so every new screen is legible by default. Use
  when defining colour tokens, adding a theme, or fixing contrast problems.
---

# Build a Colour System

A palette is a set of colours. A **system** is a set of decisions about which
colour goes where, so the next screen is legible without anybody thinking about
it. Most accessibility bugs are not mistakes — they are the absence of a system.

## Name by role, never by value

The single highest-leverage rule.

```css
/* Breaks the moment you add a dark theme */
--grey-100: #f5f5f4;
--blue-500: #2563eb;

/* Survives every theme */
--surface:        #f5f5f4;
--text-primary:   #1c1917;
--text-secondary: #57534e;
--border:         #e7e5e4;
--accent:         #2563eb;
--accent-ink:     #ffffff;   /* text that sits ON accent */
```

With value names, dark mode means finding every usage and deciding again. With
role names you redefine six tokens and the whole product follows.

`--accent-ink` earns its place: text on an accent fill cannot use `--text-primary`,
because that inverts between themes while the accent fill often does not.

Shared publicly by the author and open for any use. See the Terms.