Color Theory for Developers: HEX/RGB/HSL, Accessibility, Contrast Ratios & Palette Generation

This guide skips what a colour is and covers how to ship a palette that passes review: choosing a scheme, turning it into design tokens, and why a dark theme is not an inversion. For HEX/RGB/HSL definitions and the conversion formulas, see colour codes in practice; for the full path from a primary colour to sign-off, see the conversion guide.

Four relationships, each with a failure mode

Complementary sits 180° apart and works for accents and calls to action, but fails when both colours are light and compete for the same layer. Analogous sits within roughly 30° and sets an overall mood, yet fails when neighbours are so close that hierarchy disappears. Triadic spaces three hues evenly and fails when all three carry equal weight, which makes the screen busy. Monochromatic holds one hue and fails when lightness alone is asked to carry the hierarchy and the dark end collapses.

Programmatic generation is really just hue offsets:

function palette(baseHue, scheme = 'analogous') {
  const offsets = {
    complementary: [0, 180],
    analogous: [-30, 0, 30],
    triadic: [0, 120, 240],
    tetradic: [0, 90, 180, 270]
  }[scheme] || [-30, 0, 30];
  return offsets.map(o => `hsl(${(baseHue + o + 360) % 360}, 65%, 55%)`);
}

Filtering is the part that matters — can the primary cover an accent-sized area, do the secondaries stay distinguishable, and does every swatch have a foreground tone that passes contrast?

A monochromatic ramp is not automatically a scale

The ramp keeps one hue and pulls saturation and lightness apart. The trap is that equal steps in L are not equal steps in perception: near the dark end several stops read as the same colour. Measure the separation between adjacent stops after choosing values, rather than trusting the percentages.

From palette to tokens: three layers, four rules

Keep a raw layer that stores values and is never referenced directly, named by hue plus step (--primary-500). Keep a semantic layer that names intent (--surface, --text-primary, --border, --accent), and let components consume only that. Keep a theme layer that remaps semantics under [data-theme="dark"] without touching raw values:

:root {
  --primary-50:  #eff6ff;
  --primary-500: #3b82f6;
  --primary-900: #1e3a8a;
  --surface: #ffffff;
  --text-primary: #111827;
}

[data-theme="dark"] {
  --surface: #121212;
  --text-primary: #e5e7eb;
}

Finally, every semantic token carries one contrast obligation: --text-primary must pass on --surface, and that obligation is rechecked whenever the theme changes. The payoff is that theme switching, rebranding and contrast fixes each touch exactly one place.

Dark mode is not inversion

Never pair pure black with pure white — the extreme ratio produces halation; use a near-black such as #121212. Lower saturation, because a vivid colour that reads well on white glows and looks muddy on a dark surface, so it typically drops by 10–20%. Express elevation through surface lightness (#121212 → #1e1e1e → #2c2c2c) instead of shifting hue, which keeps stacked layers legible.

Let the browser do the derivation

color-mix() blends two colours by proportion; color(display-p3 …) addresses wide-gamut primitives; hsl(from var(--base) …) derives a value straight from a token so no ramp has to be written by hand. Theme switching then becomes a variable remap under prefers-color-scheme.

Sign-off: score every pair

Thresholds are 4.5:1 for body text and 7:1 for AAA, easing to 3:1 and 4.5:1 for large text and non-text elements. Run every candidate pair through the luminance function before shipping; it is far more reliable than eyeballing, and the same numbers appear in the palette generator and colour converter.

Frequently Asked Questions

When should I use HSL versus RGB?

RGB describes how to mix the colour; HSL describes what the colour is. For theming and generating a family of tints and shades, HSL is far more convenient — change L for a full ramp, change H to shift hue. For pixel-exact reproduction (sampling a design mock, image processing) use RGB or hex. CSS accepts both, and hsl(200 80% 45%) is much more tweakable than #1a7fc1. The [colour converter](/color-converter.html) converts between them.

What contrast ratio counts as accessible?

WCAG 2.1 AA requires: 4.5:1 for body text, 3:1 for large text (18pt regular or 14pt bold and above), and 3:1 for non-text elements (icons, input borders, chart fills). Level AAA raises these to 7:1 for body text and 4.5:1 for large text. Note this is a *relative contrast ratio*, not a brightness difference — light grey #999 on white is only 2.8:1, a common combination that looks fine but fails.

Why does a colour from the design mock look different in CSS?

Four common causes: (1) different colour spaces — design tools may work in sRGB or Display P3 while browsers default to sRGB, so vivid P3 colours get compressed; (2) alpha compositing — a semi-transparent layer in the mock sits on a background, so you must compute the composited result yourself; (3) no dark-mode variant — only the light value was defined, so contrast inverts under a dark theme; (4) ambient light and display calibration differences. Debug by first confirming both sides agree on the hex value, then checking for transparency.

What should I watch for when designing a dark theme?

Three hard rules: (1) never pair pure black #000 with pure white #fff — the contrast causes halation; use a dark grey such as #121212. (2) lower the saturation — colours that look great on a light background glow and muddy on a dark one, so reduce saturation by roughly 10–20%. (3) do not encode hierarchy with hue — express elevation by surface lightness, so nearer layers are lighter; a ramp like #121212 → #1e1e1e → #2c2c2c reads more clearly than switching colours.

← Back to Blog