Learn

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-shadow for text on complex gradients.
  • Don't encode information using gradient alone — add text or patterns.
  • Respect prefers-reduced-motion for animated gradients.
  • Check pastel gradients carefully — low saturation doesn't guarantee enough contrast.