Skip to content
UX Atlas
Plate FND·026 · UI foundationGrid C1 · Rev. 2026-08-14

Color Systems

A structured palette of ramps and semantic aliases, so colour decisions are made once rather than per screen.

UI foundationCraft conventionIntermediate

Definition

A colour system organises raw colour values into ramps, then maps those ramps to semantic roles through tokens. Designers and engineers consume the roles, not the raw values.

Craft convention. True because the industry converged on it. Breaking it costs familiarity, not correctness.

On this plate
  1. 1Definition
  2. 2Building one
  3. 3Three-layer token structure
  4. 4Keeping the layers honest
  5. 5In practice
  6. 6Local chart
  7. 7Continue from here

Reach for this when

  • Starting a design system.
  • Adding dark mode or a second brand.
  • Consolidating a palette that has grown organically.
  • The palette exists and components are about to start consuming it.

Common mistakes

  • Components referencing primitive tokens.
  • Semantic names that describe appearance rather than role.
  • Ramps generated without contrast verification.

Building one

  1. 1

    Choose hues

    One neutral, one accent, four semantic. Add more only when a real need appears.

  2. 2

    Generate ramps

    Nine to twelve steps per hue, stepping perceptual lightness at consistent chroma.

  3. 3

    Verify contrast

    Produce a matrix of every foreground and background pair, and mark which combinations are permitted.

  4. 4

    Define semantic tokens

    Map roles such as surface, surface-raised, text-primary, border-subtle and action-primary onto ramp steps.

  5. 5

    Define the dark theme

    Remap the same semantic tokens to different ramp steps. Never invert values arithmetically.

  6. 6

    Document usage

    State which token to use in which situation, with examples of the wrong choice.

Three-layer token structure

css
:root {
  /* 1. Primitives: raw values, never used directly in components */
  --neutral-50:  oklch(0.985 0.002 90);
  --neutral-600: oklch(0.505 0.010 90);
  --neutral-900: oklch(0.215 0.012 90);
  --accent-600:  oklch(0.560 0.170 38);

  /* 2. Semantics: meaning, remapped per theme */
  --surface:        var(--neutral-50);
  --text-primary:   var(--neutral-900);
  --text-secondary: var(--neutral-600);
  --action:         var(--accent-600);
}

[data-theme="dark"] {
  --surface:        oklch(0.180 0.008 90);
  --text-primary:   oklch(0.960 0.003 90);
  --text-secondary: oklch(0.720 0.010 90);
  --action:         oklch(0.700 0.150 38);
}

/* 3. Components consume semantics only */
.button-primary { background: var(--action); }

Primitives hold values, semantics hold meaning, components consume semantics. Only the middle layer changes between themes.

Keeping the layers honest

Do

  • Let components reference semantic tokens only.
  • Name semantic tokens for their role and surface, such as text on subtle background.
  • Add a primitive only when no existing one fits, and record why.
  • Test a theme swap early, which is the fastest way to find leaks.

Do not

  • Let a component import a raw palette value, which makes theming impossible later.
  • Create a semantic token used in exactly one place.
  • Encode the hue in the semantic name, which is how brand-danger-green happens.

In practice

  1. i.

    Themes as token remapping

    Multi-brand products

    A product supporting several brands changes only the semantic layer per brand. Component code never changes, which is what makes multi-brand maintainable at all.

  2. ii.

    The leak found by dark mode

    Why theming is the test

    Eleven components looked correct until dark mode shipped, at which point each one that had reached past the semantic layer to a raw grey appeared as a bright patch. The leak existed all along; the theme is what made it visible.

Local chart

FND·026 · Region II · Grid C1

This entry and the entries it is stated to connect with. Each line is labelled with what the connection means.

Style DictionaryTOOL·040 · OFTEN USED WITHDesign TokenTERM·071 · SHORT DEFINITIONOKLCHTERM·065 · SHORT DEFINITIONDesign System GovernanceSYS·004 · RELATED CONCEPTDesign TokensSYS·001 · RELATED CONCEPTThemingSYS·008 · RELATED CONCEPTBrand Color in InterfacesFND·024 · RELATED CONCEPTColor AccessibilityFND·028 · RELATED CONCEPTColor Theory for InterfacesFND·019 · RELATED CONCEPTDark ModeFND·027 · RELATED CONCEPTLightnessFND·022 · RELATED CONCEPTNeutralsFND·025 · RELATED CONCEPT

Continue from here

Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.

Often used with

These usually appear in the same screen or the same decision.

Short definition

The one-paragraph version, for when that is all you need.

Related concept

Connected closely enough to change how you apply this.