Skip to content
Velloreth
Design 11 min read

Color Systems: Building a Scalable Palette

How to build a color system that scales: perceptual color spaces, ten-step ramps, semantic tokens, contrast pairing, and the checks that catch failures early.

By

A color palette is a list of hex values. A color system is a set of roles, relationships, and rules that let you add a screen — or a second brand — without reopening the question of what the brand color is.

Most palettes fail not because someone picked an ugly blue, but because the palette encoded values instead of meaning. --blue-500 tells you nothing about where it may be used; --accent tells you everything and can be repointed at any blue you like.

Start in a perceptual color space

HSL is the default in every color picker and the wrong tool for building ramps. Its hue circle is borrowed from subtractive paint, its saturation axis does not correspond to vividness, and its lightness channel does not correspond to how light a color looks.

The result is predictable. Build a ramp by stepping HSL lightness from 10% to 90% at a fixed hue and saturation, and the yellow steps will look much lighter than the blue steps at the same value. Rotate the hue at fixed saturation and chroma jumps around — cyan peaks early, magenta stays flat.

OKLCH fixes both. It is a cylindrical form of OKLab: lightness L runs 0 to 1 and tracks perceived lightness roughly linearly, chroma C tracks vividness, and hue H runs 0–360. Steps in L of equal size look like equal steps.

:root {
  --blue-100: oklch(0.95 0.03 255);
  --blue-300: oklch(0.85 0.08 255);
  --blue-500: oklch(0.62 0.17 255);
  --blue-700: oklch(0.48 0.14 255);
  --blue-900: oklch(0.32 0.09 255);
}

Two cautions. First, oklch() is CSS Color 4 and supported in all current browsers, but any color outside sRGB must be handled by the whole pipeline — if your charts, canvas code, or image tools still assume sRGB hex, wide-gamut values will clip or shift. Set oklch() values you actually intend, and check them on a wide-gamut display and an sRGB one. Second, still audit every step for contrast; perceptual uniformity makes ramps nicer, it does not make them accessible.

If you cannot move off hex, at least generate your ramps from a perceptual tool and paste the results, rather than clicking through HSL lightness values by hand.

Build ramps, not swatches

A usable ramp for one hue:

StepRole in the rampTypical use
50–100TintsWashes, badges, selection backgrounds
200–300Light accentCharts on dark, disabled accents
400–500Core accentButtons, links, focus rings
600–700Deep accentHover/pressed, accent text on light
800–900ShadeDanger text on tints, footers

Ten steps is a good number. Fewer and you will find yourself interpolating at usage time; many more and nobody can remember which is which.

Design the ramp so it is useful in both directions: accent text on a white page (needs the 600–700 end to clear 4.5:1) and accent-filled controls with white text (needs the 400–500 end to clear 4.5:1 against white). A ramp tuned only for filled buttons usually has no step that works as link text.

Neutrals deserve the same treatment and more attention — they carry all the body text. Build a neutral ramp with a slight hue bias rather than pure gray; a cool gray reads modern, a warm gray reads soft, pure #808080 reads unfinished. Then verify:

text-primary     on  background   must be >= 4.5:1
text-secondary   on  background   must be >= 4.5:1
text-tertiary    on  background   target   >= 4.5:1  (4.5:1 even if it "feels" decorative)
border           on  surface      must be >= 3:1    (SC 1.4.11 if it conveys state)

Name by role, in layers

Three layers is the structure that scales:

  1. Primitives — the raw ramps. --blue-500, --gray-100. No semantics, no opinions, never referenced directly by a component.
  2. Semantic tokens — meaning. --color-bg, --color-surface, --color-text, --color-text-muted, --color-accent, --color-border, --color-danger.
  3. Component tokens — local overrides where a component genuinely needs one. --button-bg, --button-bg-hover.

Components consume layer 3, which falls back to layer 2, which points at layer 1. Nothing in your markup ever says #2563eb.

What this buys you:

  • Theming. Dark mode is a new layer-2 mapping, not a new set of component styles. So is high contrast.
  • Multi-brand. A second brand repoints layer 2 and ships.
  • Refactoring. “The blue is too saturated everywhere” becomes a one-line edit at layer 1 rather than a find-and-replace across 400 files.
  • Review. A reviewer can see in one file which colors are allowed to mean what.

The failure mode to avoid is a semantic token that silently points at a different semantic token. Keep the graph shallow — layer 3 to layer 1, at most one hop through layer 2 — or you will spend an afternoon chasing an override.

Contrast is a matrix, not a sample

Checking the three combinations in the design mockup is how subtle failures ship. The real question is the full matrix: every text token against every surface it can appear on, in every theme.

backgroundsurface-1surface-2accent-500
text-primary✓✓✓check
text-secondary✓✓✓check
text-on-accentcheck——✓
border3:13:13:1—

Rules that come out of it:

  • 4.5:1 for normal text (WCAG 2.2 SC 1.4.3), 3:1 for text at 18px regular / 14px bold or larger, 3:1 for non-text UI components and graphics (SC 1.4.11).
  • A color used as a background for white text needs 4.5:1 against white, which knocks most mid-tone accents out of contention and is why brand blues often have to darken when you put text on them.
  • Never encode state with color alone (SC 1.4.1). Success and danger need an icon, a label, or a shape alongside the hue — color-blind readers, forced-colors mode, and grayscale print all remove the signal.
  • Placeholder text and disabled text are still text. They get checked.

Automate this. A script that parses your built CSS and asserts the matrix turns a design review question into a CI failure. The first run will find problems; every run after that prevents them.

Saturation discipline

A palette with five equally vivid accents has no accent. Saturation is a hierarchy tool, and spending it everywhere means it signals nothing.

A workable policy:

  • One high-chroma accent, used for primary actions and active states.
  • Semantic colors (success, warning, danger) at moderate chroma, because they repeat and would otherwise compete.
  • Everything else — neutrals, surfaces, dividers, chart series beyond the third — at low chroma.

For charts specifically, pick series colors by distinctness in the perceptual space, not by evenly spaced hues. Two hues that look clearly different on white can sit within a just-noticeable difference once both are desaturated and small. Test your categorical palette by shrinking the swatches to legend size and viewing them at 3:1 against the plot background.

Handling the exceptions

Systems fail when the only escape hatch is to hardcode. Plan for exceptions explicitly.

Off-palette brand colors. A partner logo or an acquisition’s identity will not match your ramps. Give them a documented path: a --color-partner-* token with a comment, used only where required, and excluded from contrast assertions that cannot be satisfied.

One-off tints. Reach for color-mix() against your primitives instead of adding a hex:

.selected {
  background: color-mix(in oklch, var(--color-accent) 12%, var(--color-surface));
}

This keeps the value derivable and theme-aware, and avoids the --blue-500-alpha-12 explosion.

Seasonal or campaign colors. Same mechanism — a semantic token repointed for a defined period, with an owner and an end date.

Documented failures. If something genuinely cannot meet 4.5:1, write it down with the measured ratio and the compensating treatment. An exception list you can audit beats an invisible shortcut.

Deriving states without a combinatorial explosion

A control has rest, hover, active, focus, and disabled states, in light and dark. Multiply that by every component and you either end up with hundreds of hardcoded values or a small set of derivation rules. Take the rules.

Hover and pressed come from the base, one step each. Hover moves one step toward the opposite end of the ramp; pressed moves two. Never hand-pick them per component — the moment a hover color is its own token, buttons drift apart visually within a few sprints.

.button {
  background: var(--color-accent);
}
.button:hover {
  background: color-mix(in oklch, var(--color-accent) 88%, #000);
}
.button:active {
  background: color-mix(in oklch, var(--color-accent) 76%, #000);
}

Mixing in oklch keeps the darkening perceptually even; mixing in hex or HSL produces a hue shift you can see on the second or third step.

Disabled is a relationship, not a color. Disabled controls are de-emphasized but must still be legible enough to read — aim for 4.5:1 where the label carries meaning, and always for the control’s boundary (SC 1.4.11 applies to inactive components too if they must be identified). Common approach: drop to a muted surface, mute the text one step, and remove the shadow rather than dropping opacity to 0.4.

Focus is its own token, independent of state. One focus color that clears 3:1 against every surface it can sit on — which usually means a lighter ring in light mode and a darker-to-lighter adjusted ring in dark, checked against both. Do not derive focus from the accent if the accent can appear as a background on the same screen.

Selection, hover, and active must not collide. If row hover, row selection, and row focus are all tints of the same hue at 8–12%, the selected row becomes invisible the moment the pointer lands on it. Give selection either a much stronger tint, a left border, or a checkmark alongside the color.

Color in charts and data visualization

Data color is where a palette that passed a UI review usually fails, because the constraints are different: many colors at once, small area, on a surface you did not test them against.

A working approach:

  1. Pick the categorical palette by distinctness, not by hue spacing. Space your picks in OKLab so that neighbors differ in lightness and hue. Two mid-lightness hues at the same L collapse at legend size even when they are far apart on the wheel.
  2. Force a lightness rhythm. Alternating light/dark series colors gives you a second channel that survives color-blindness and grayscale printing.
  3. Reserve the accent for the series you want people to look at. Everything else goes neutral-ish.
  4. Re-verify on the plot background. A series color at 3.1:1 against white can drop to 2.6:1 against a surface-1 chart card.
  5. Never rely on color alone for a category that matters — direct labels, patterns, or ordered dash styles carry the distinction when color does not.

Sequential and diverging scales need the same perceptual discipline as ramps: equal steps in a sequential scale should look equal in amount, and a diverging scale must be balanced around a meaningful midpoint rather than around 50% in HSL.

The failure worth watching for

Systems rarely collapse from a bad palette choice. They collapse when the semantic layer stops being the only path to a color — a component that “just this once” needs a raw hex, a second theme that ships with three unmapped tokens, a chart library configured with hardcoded series colors.

Guard the invariant mechanically: assert in CI that no component stylesheet contains a hex literal or an oklch() literal, and that every semantic token has a defined value in every theme. Both checks are a few lines against your built CSS, and both catch the slow drift that no design review will.

Migration path from a hex soup

If you are inheriting an existing product with 200 hardcoded colors, do not rewrite it all:

  1. Inventory. Extract every distinct color from the codebase and count usage. You will find roughly 30 values doing 90% of the work.
  2. Cluster them into ramps by hue and lightness, and name the ramps.
  3. Introduce semantic tokens and map the top 20 usages.
  4. Add the contrast matrix check, and fix whatever it flags — these are your real bugs.
  5. Replace the long tail opportunistically. Every file you touch loses its hex values.

Two sprints of this gets you a system; six months of touching things as you go gets you consistency without a freeze.

What “done” looks like

You are finished when: every color in the UI traces to a token; the token file is the source both design and code read; the contrast matrix passes in CI for every theme; adding a theme means adding one mapping block; and a new developer can find the right color by asking what the element means rather than what it looks like.

That last property is the whole point. A palette answers “what color is this button.” A system answers “what is this button allowed to be,” and keeps answering correctly after the brand refresh.

Frequently asked questions

Why not just use HSL for a palette?
HSL's lightness channel does not track perceived lightness, so a 50% lightness yellow and a 50% lightness blue look wildly different in weight. Chroma also peaks unpredictably as you rotate the hue, which makes equal HSL steps produce uneven ramps. Perceptual spaces like OKLCH fix both problems.
How many colors does a design system actually need?
Six to eight semantic roles — background, surface, text primary, text secondary, accent, border, success, danger — mapped onto ramps of about ten steps each. That is under fifty primitive values and covers almost every screen, with room to add roles later.
Should designers and developers share the same color source?
Yes, and it should be a file both can read: JSON or a token format that Figma can import and your build can compile to CSS. Handoff through screenshots or hex values in tickets is where drift starts, and drift is the failure mode a color system exists to prevent.
How do I handle colors that fail contrast?
Change the role, not the rule. Either darken the text token, lighten the surface token, increase the font size until the large-text threshold applies, or accept a documented exception with a compensating treatment. Silently shipping 3.4:1 because it looks better is the option to remove.