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.