Skip to content
NewTemplates & toolkits are on the way — join the waitlist
Hecham Gazhi

Design Systems · Lesson 04 / 13

Color system

How to build the colour foundation of a design system: palettes and tonal scales, perceptual consistency, semantic colour roles, state colours, accessible pairings, dark mode and documenting colour for teams.

4 min read · 5 quiz questions

From palette to system

In a single design, you can pick colours by eye. In a design system used by many people across many screens, colour needs to be a system: a defined set of scales, a clear set of roles, and rules for which combinations are allowed.

A colour system answers questions before anyone asks them: Which grey for secondary text? Which red for an error border? What's the hover colour for a primary button in dark mode? Is this text readable on this background?

Building tonal scales

Each hue in the system — brand, neutral and each status colour — gets a tonal scale from very light to very dark, commonly numbered 50, 100, 200 … 900 (sometimes 950).

  • Light steps (50–200) — tinted backgrounds, subtle fills, selected rows.
  • Middle steps (400–600) — the main brand or status colour; fills of buttons and badges.
  • Dark steps (700–900) — text on light backgrounds, hover/pressed states.
  • Neutrals often need more steps than other hues, because most of the UI is built from them.

Live preview

blue

50

100

200

300

400

500

600

700

800

900

gray

50

100

200

300

400

500

600

700

800

900

Aim for perceptual consistency: step 500 of blue and step 500 of red should feel similarly light. Colour spaces like OKLCH make this easier than HSL, because equal lightness values look equally light to the eye.

Choosing the hues

GroupPurposeNotes
Brand / primaryActions, links, selected states, focusMay need adjusting from the logo colour to pass contrast
NeutralText, backgrounds, surfaces, borders, disabledSlightly tinted greys feel warmer and more cohesive
SuccessConfirmations, positive valuesGreen
WarningCaution, pending, needs attentionAmber/orange — yellow text rarely passes contrast
Danger / errorErrors, destructive actionsRed
InfoNeutral information, tipsOften blue — distinguish it from the brand blue if needed
Extended / data vizCharts, tags, avatars, categoriesA separate, carefully balanced set

Semantic colour roles

Components should never pick from the raw scales directly. Instead, define semantic roles (tokens) that describe what each colour is for. Roles are organised by what they colour:

GroupExample tokens
Backgroundcolor-bg-page, color-bg-subtle, color-bg-inverse
Surfacecolor-surface, color-surface-raised, color-surface-overlay
Textcolor-text-primary, color-text-secondary, color-text-disabled, color-text-on-action, color-text-link
Bordercolor-border, color-border-strong, color-border-focus, color-border-error
Actioncolor-action-primary, -hover, -pressed, color-action-secondary
Feedbackcolor-feedback-success-bg, -text, -border (and the same for warning, error, info)
Iconcolor-icon-primary, color-icon-secondary

States

Interactive colours need defined values for each state, so every component behaves consistently:

StateCommon approach
DefaultBase step, e.g. blue-500
HoverOne step darker (blue-600) or an overlay of 8% black
PressedTwo steps darker (blue-700) or 12% overlay
FocusVisible ring with color-border-focus, 2px with offset
SelectedTinted background (blue-50) plus a strong indicator
DisabledNeutral, reduced contrast — and not the only way to explain why it's unavailable

Accessible pairings

Contrast must be built into the system, not checked screen by screen. Test every text and icon role against every background it can appear on, and document which pairs pass WCAG AA (4.5:1 for normal text, 3:1 for large text and UI components).

  • Publish a contrast matrix or mark each swatch with the text colours that may sit on it.
  • Pick text-on-fill colours (color-text-on-action) for every filled component.
  • Keep status colours readable: warning text usually needs a dark amber or brown, not yellow.
  • Don't rely on colour alone — the system's components should pair colour with icons and text.

Live preview

Readable text?

1.7:1 — fails AA

Readable text?

5.6:1 — passes AA

Readable text?

4.6:1 — passes AA

Common mistake: Choosing the brand colour for small text without checking contrast. Many bright brand colours (yellow, light green, cyan) fail 4.5:1 on white and need a darker shade for text.

Dark mode and other themes

If the system supports dark mode, each semantic token gets a dark value. This is far easier when the roles are well defined:

  • Backgrounds and surfaces move to dark neutrals; higher surfaces get slightly lighter.
  • Text flips to light neutrals with reduced intensity for secondary text.
  • Brand and status colours shift to lighter, less saturated steps (e.g. 300–400 instead of 500–600).
  • Re-check every pairing for contrast — passing in light mode doesn't mean passing in dark mode.
Examplecss
[data-theme="light"] {
  --color-bg-page: var(--gray-0);
  --color-text-primary: var(--gray-900);
  --color-action-primary: var(--blue-500);
}
[data-theme="dark"] {
  --color-bg-page: var(--gray-950);
  --color-text-primary: var(--gray-50);
  --color-action-primary: var(--blue-300);
}

Documenting colour

  • Show every scale with hex values and token names, and a copy button.
  • Explain each semantic role with "use for" and "don't use for".
  • Show approved and forbidden combinations.
  • Provide guidance for data visualisation separately — charts have different needs.
  • Note the brand colour's meaning: when to use it generously, and when to hold back.

Do

  • Generate scales with consistent perceived lightness.
  • Expose semantic roles to designers and developers, not raw scales.
  • Define every interactive state.
  • Test and document contrast for every pairing.

Don't

  • Let teams pick any hex value they like.
  • Add a new colour for a single screen.
  • Use the same red for errors and for a decorative tag.
  • Assume dark mode is just inverted colours.

Key takeaways

  • A colour system defines scales, semantic roles and allowed combinations.
  • Build 50–900 tonal scales for brand, neutral and status hues with consistent perceived lightness.
  • Components use semantic roles (bg, surface, text, border, action, feedback), never raw scales.
  • Define every interactive state and document accessible pairings.
  • Themes remap semantic roles; check contrast again for each theme.

Exercise

Create a colour foundation

  1. Generate scales for a brand colour, a neutral and red, amber and green.
  2. Define 20 semantic tokens grouped by bg, surface, text, border, action and feedback.
  3. Map them for light and dark themes.
  4. Build a contrast matrix for text roles on background roles and fix failures.
  5. Write a one-paragraph usage guideline for the brand colour.

Test yourself

Color system quiz

5 questions. Score 70% or more to complete the lesson.

  1. 1.In a 50–900 tonal scale, which steps are usually used for text on light backgrounds?
  2. 2.Why should components use semantic colour roles instead of raw scales?
  3. 3.Which colour space makes perceptually consistent scales easier?
  4. 4.A typical hover state for a primary button is…
  5. 5.In dark mode, brand colours usually…