Gradients and Accessibility
Gradients introduce a specific accessibility challenge: the contrast between text and a shifting background is never constant. Here's how to handle it.
The core problem
WCAG contrast requirements (4.5:1 for normal text, 3:1 for large text) are defined for a fixed background color. When the background is a gradient, contrast changes across the element. The lightest part of the gradient might pass the check, while the darkest part fails — or vice versa.
Rule 1: Never place important text directly on a complex gradient
If you need readable text, add a solid overlay, scrim, or a text-shadow that guarantees contrast regardless of what the gradient does underneath:
/* Scrim approach — semi-opaque overlay above the gradient, text above the overlay */
.card {
background: linear-gradient(135deg, #6366f1, #a855f7);
position: relative;
}
.card::after {
content: '';
position: absolute;
inset: 0;
background: rgba(0, 0, 0, 0.45);
border-radius: inherit;
z-index: 1; /* overlay sits above the gradient */
}
.card-text {
position: relative;
z-index: 2; /* text sits above the overlay */
color: #ffffff;
}Note: a semi-opaque overlay reduces but does not eliminate the gradient's influence on contrast. Always verify the actual contrast ratio after adding the overlay, rather than assuming a fixed opacity is sufficient.
Rule 2: Check contrast at the weakest point
For gradient backgrounds, always check contrast at the worst-case point for your text color:
- For dark text: the darkest part of the gradient is the worst case — it provides the least contrast against dark text.
- For light text: the lightest part of the gradient is the worst case — it provides the least contrast against light text.
- For other text colors: the actual contrast must be computed at each relevant point along the gradient, including intermediate positions.
Use the worst-case scenario, not the average. Tools like the APCA checker or the WebAIM Contrast Checker can help — but you'll need to sample colors manually from different points along the gradient.
Rule 3: Use gradients for decoration, not information encoding
If a gradient is used to convey meaning (e.g., a heatmap, a risk indicator), make sure the information is also available in a non-color form:
- Add a text label or numeric value.
- Use a high-contrast border or pattern overlay at critical thresholds.
- Don't rely solely on the lightness or hue of the gradient to encode data.
Rule 4: Avoid gradient animations for users with vestibular disorders
Animated gradients (moving, pulsing, or rotating) can trigger discomfort or nausea for users with vestibular disorders. Always respect the prefers-reduced-motion media query:
@media (prefers-reduced-motion: no-preference) {
.animated-bg {
animation: gradient-shift 8s ease infinite;
}
}
/* For users who prefer reduced motion — static fallback */
.animated-bg {
background: linear-gradient(135deg, #6366f1, #a855f7);
}Rule 5: Be careful with low-contrast pastel gradients
Pastel gradients are beautiful — but they're inherently light-value colors with low chroma. Any text or icon placed on them needs to use a very dark color, and even then the contrast might be marginal. When using pastels as backgrounds:
- Aim for a contrast ratio of at least 4.5:1 for body text (WCAG AA).
- Consider adding a subtle inner shadow on text containers to boost contrast locally.
- Avoid light grey text on pastel backgrounds — the combination often falls below 3:1.
Summary checklist
- Test contrast at the lightest and darkest point of the gradient.
- Use scrim overlays or
text-shadowfor text on complex gradients. - Don't encode information using gradient alone — add text or patterns.
- Respect
prefers-reduced-motionfor animated gradients. - Check pastel gradients carefully — low saturation doesn't guarantee enough contrast.