What problem it solves
Color on a page does three jobs: it separates levels — background, text, captions; shows state — a link, an error, a success; and distinguishes categories — chart lines, page formats. If colors are picked on the spot, each job gets its own set of random shades, and dark mode turns into rewriting all the CSS.
Without a system
- captions in a gray picked by eye:
#999on white — 2.85:1 - an “error” status that’s only a red dot
- a
green-500button with white text — 2.28:1 - dark mode via
filter: invert(1) - hex colors right in the components
With a palette
- colors named by role:
--ink-3, not--gray-500 - captions in
#66605a— 5.6:1 against the background - a status is an icon and a word, with color added to them
- dark mode is its own set of the same tokens
- components use only
var(--…)
Hue, saturation, lightness
A screen mixes red, green and blue — that’s how #cc3f23, this site’s accent, is written. The eye describes color
differently: hue (red, blue), saturation (vivid or muted) and lightness. For a palette lightness matters most: contrast
depends on it, and hue doesn’t enter the contrast formula (Text contrast).
hsl() writes a color as hue, saturation and lightness, but its lightness isn’t what the eye sees. Yellow
hsl(60 100% 50%) and blue hsl(240 100% 50%) are both at 50%, yet on a white background yellow gives 1.07:1 and blue
8.59:1. In oklch() lightness is fitted to perception: the same yellow has an L of 96.8%, the blue 45.2%. Steps of
lightness in OKLCH give steps of perceived brightness, and contrast changes predictably with them. Tailwind 4’s palette,
for example, is defined in OKLCH. oklch() has worked in every browser since May 2023: Chrome 111, Firefox 113,
Safari 15.4.
| Notation | Example | When to use |
|---|---|---|
#rrggbb |
#cc3f23 |
a ready palette from a mockup; this site’s tokens are written this way |
rgb() with alpha |
rgb(204 63 35 / 0.09) |
a tint of the accent color — here --accent-soft |
hsl() |
hsl(10 71% 47%) — the same color, rounded |
shift the hue without touching the rest; don’t trust its lightness |
oklch() |
oklch(56.9% 0.182 33.1) — the same #cc3f23 |
a palette in lightness steps: 95%, 85% … 25% |
color-mix() |
color-mix(in srgb, var(--accent-ink) 35%, transparent) |
a shade from a token without a new hex — that’s how links are underlined here. Chrome 111, Firefox 113, Safari 16.2 |
What a palette is made of
| Role | This site’s tokens | Light theme | Why separate |
|---|---|---|---|
| backgrounds | --ground, --raised, --sunken |
#f4f2ee, #ffffff, #f0ece5 |
the page, a card above it, a field inside |
| text | --ink, --ink-2, --ink-3 |
15.8:1, 8.5:1 and 5.6:1 against the background | three levels of importance (Three levels of importance) |
| lines | --line, --line-strong |
1.34:1 and 1.59:1 against white | dividers between blocks. The 3:1 threshold (WCAG 1.4.11) is for borders without which a field or button can’t be seen |
| accent | --accent, --accent-ink, --accent-soft, --on-accent |
fill #cc3f23, text #bc3a1f |
the fill, the text and the tint each have their own contrast: #cc3f23 as text on the background is 4.37:1, short of AA |
| states | --ok, --warn |
#2e7d4f — 4.51:1, #9a4e0a — 5.42:1 |
success and warning, each with a pale -soft tint |
Names go by role: --ink-3, not --gray-500. In dark mode the values change, while the names and the components’ CSS
stay the same. There’s one accent: it works while it differs from everything else — like bold in text (Bold: one or two spots).
Dark mode is a set of its own
Flipping the light theme with filter: invert(1) doesn’t work: it flips every channel, photos become negatives, and
the accent #cc3f23 becomes cyan #33c0dc, its hue moving from 33° to 215°. So dark mode is the same tokens with
values picked anew:
- The background isn’t black and the text isn’t white:
#f2eee8on#131210is 16.2:1. People with astigmatism often complain about white letters on black: the letters seem to blur (Text contrast). - On a dark background shadows are nearly invisible, so lightness separates a card:
--raised#1f1d1ais lighter than the background#131210. - The accent gets lighter.
#cc3f23on the dark background is 3.84:1, short of AA, so here it’s#ff7a55— 7.28:1. White text on it is 2.57:1, so text on the accent turns dark:#1a0d08, 7.39:1. color-scheme: darkswitches what the browser draws itself: input fields, scrollbars, the default background.
The theme is chosen by the system setting (prefers-color-scheme) and by a toggle on the site; how to combine the two
without flashing white on load — The palette in CSS.
Meaning — not by color alone
About 8% of men of Northern European descent and fewer than 1% of women distinguish colors less well than others, most often red and green; in Asian and African populations it’s less common. Color is lost for everyone else too: in sunlight, in a screen’s night mode, on a black-and-white printout. WCAG 1.4.1 (level A) requires that color not be the only way to convey meaning.
| Color says | Add |
|---|---|
| an error in a field | the error text under the field |
| up or down | an icon and a word |
| a link in text | an underline — here semi-transparent, in the accent color |
| chart lines | a label at each line’s end, different dash patterns |
| the current menu item | font weight or a mark at the side |
Check in DevTools: the Rendering panel (in More tools), Emulate vision deficiencies — protanopia, deuteranopia, tritanopia, achromatopsia. In achromatopsia the page is gray: whatever is distinguishable there — by icon, word, lightness — doesn’t depend on color at all.
What you get and what it costs
What you get
- Dark mode by swapping values. Components write
var(--ink), dark mode redefines the tokens, and the components’ CSS stays untouched. - Contrast is checked once. Once
--ink-3on--raisedis computed, the pair is the same in every component. - A stray color turns up in a search. A hex outside the tokens file means someone bypassed the palette —
grepcatches it. - The palette changes in one file. A new accent is an edit to the tokens, not a hunt through every component.
What it costs
- Every color twice. A value for the light theme and one for the dark, and every pair’s contrast checked in both.
- The dark set is written twice. For both the system theme and the toggle to work, the dark tokens sit in both
[data-theme='dark']and@media (prefers-color-scheme: dark).light-dark()removes the repetition but only chooses between two colors or images: it can’t give a shadow a different shape (The palette in CSS). - One accent means few highlights. A link, a button and an active item share one color; shape and weight tell them apart.
- Old browsers skip
oklch()andcolor-mix(). CSS ignores a line with an unknown value entirely — you need a fallback hex on the line above.
Where to start
- Color: a palette by role, contrast and dark mode
- A palette in CSS: role-based tokens for the light and dark themesTokens by role, dark mode by system setting and by toggle,
light-dark()— line by line in this site’s file. - Text contrast: the WCAG thresholds and the colors that fail themThe WCAG thresholds and computed pairs: which gray is still readable, and which button color can carry white text.
If it doesn’t work
In dark mode, input fields and scrollbars stayed white
- Cause
- There’s no
color-scheme: dark: the browser draws its own elements light, whatever the page background. - Fix
color-scheme: darkin the dark token set; if the theme follows the system only,color-scheme: light darkon:root.
On load the page flashes white, then goes dark
- Cause
- The theme is picked by a script at the end of the page or after load, and the first paint is light.
- Fix
- Read the choice in a small script in
<head>and setdata-themeon<html>before the first paint. The system theme needs no script —@media (prefers-color-scheme: dark)is enough (The palette in CSS).
People confuse the red and green lines on a chart
- Cause
- The most common color vision deficiency is red–green: both colors look similar.
- Fix
- Label the lines at their ends and give them different dash patterns. Check in DevTools: the Rendering panel, Emulate vision deficiencies, deuteranopia.
Palette shades with the same lightness in HSL look differently bright
- Cause
- Lightness in
hsl()ignores the eye: yellow and blue at 50% give 1.07:1 and 8.59:1 on white. - Fix
- Build the palette in
oklch(): at the same L, perceived brightness is close.
After filter: invert(1) photos became negatives and the orange accent turned cyan
- Cause
- The filter flips every channel:
#cc3f23becomes#33c0dc. - Fix
- Give dark mode its own set of colors (The palette in CSS); don’t use the filter.