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
| Group | Purpose | Notes |
|---|---|---|
| Brand / primary | Actions, links, selected states, focus | May need adjusting from the logo colour to pass contrast |
| Neutral | Text, backgrounds, surfaces, borders, disabled | Slightly tinted greys feel warmer and more cohesive |
| Success | Confirmations, positive values | Green |
| Warning | Caution, pending, needs attention | Amber/orange — yellow text rarely passes contrast |
| Danger / error | Errors, destructive actions | Red |
| Info | Neutral information, tips | Often blue — distinguish it from the brand blue if needed |
| Extended / data viz | Charts, tags, avatars, categories | A 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:
| Group | Example tokens |
|---|---|
| Background | color-bg-page, color-bg-subtle, color-bg-inverse |
| Surface | color-surface, color-surface-raised, color-surface-overlay |
| Text | color-text-primary, color-text-secondary, color-text-disabled, color-text-on-action, color-text-link |
| Border | color-border, color-border-strong, color-border-focus, color-border-error |
| Action | color-action-primary, -hover, -pressed, color-action-secondary |
| Feedback | color-feedback-success-bg, -text, -border (and the same for warning, error, info) |
| Icon | color-icon-primary, color-icon-secondary |
States
Interactive colours need defined values for each state, so every component behaves consistently:
| State | Common approach |
|---|---|
| Default | Base step, e.g. blue-500 |
| Hover | One step darker (blue-600) or an overlay of 8% black |
| Pressed | Two steps darker (blue-700) or 12% overlay |
| Focus | Visible ring with color-border-focus, 2px with offset |
| Selected | Tinted background (blue-50) plus a strong indicator |
| Disabled | Neutral, 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.
[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
- Generate scales for a brand colour, a neutral and red, amber and green.
- Define 20 semantic tokens grouped by bg, surface, text, border, action and feedback.
- Map them for light and dark themes.
- Build a contrast matrix for text roles on background roles and fix failures.
- 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.
