What happened
We had a hero heading filled with a purple to light-lavender gradient on a dark background. The contrast plugin we ran gave it a pass, so we moved on.
Later, in review on a real laptop screen in a bright room, the right-hand end of the heading was noticeably hard to read. The checker had said it was fine, but people could not read it comfortably.
Why it happens
WCAG contrast ratios are defined between two colors, a foreground and a background. Most tools therefore take one foreground color for the text. With a gradient fill there is no single color, so the tool samples one point or an average, and that result says little about the weakest part of the text.
A gradient is only as readable as its worst stop. If the lightest end sits on a dark background with plenty of contrast, it will be fine, but a stop that drifts toward the background colour can fail badly while the sampled colour passes. Small text is stricter still, since normal text needs a higher ratio than large text.
What we do now
We now check each end of the gradient as its own solid color against the background, and test any midpoint where the hue changes a lot. If any point falls below the required ratio for that text size, we adjust that stop rather than trusting the single pass.
For small or important text such as body copy, labels and buttons, we simply use a solid color. Gradients are kept for large display headings, where there is more room for error and the ratio requirement is lower.
Quick checklist
- 1Pick the lightest and darkest stops of the gradient.
- 2Check each one as a solid color against the actual background.
- 3Check midpoints if the gradient shifts hue strongly.
- 4Use a solid color for small or critical text.
Rule of thumb
A gradient passes contrast only if its weakest point does, so test the ends, not the average.