Handling Gradients and Background Images

Sometimes text does not sit on a uniform background color, but on a gradient or a background image. In those cases a simple comparison of two declared colors is not enough to decide whether there is a color contrast (CC) failure, so the detector resorts to a visual analysis of the element.

This page explains, in plain language, how that analysis works today.

The short version

Accessibility guidelines ask that text stand out clearly from whatever is behind it — a ratio of at least 4.5:1 for normal text, and 3:1 for large text and non-text elements such as icons.

When text sits on a flat color, this is simple arithmetic: the detector reads the two colors declared in the page's style sheet and compares them.

When text sits on a gradient or a photo, there is no single background color to read. The detector then looks at what is actually painted on screen, checks many points behind the text, and reports the worst one — because a reader has to read the whole line, not just the easiest part of it.

Step by step

Step 1 — Work out what the text is really sitting on

For every piece of text, the detector inspects the element and its containers (several levels up) to answer one question: is there a gradient, a photo or an image behind these words?

It counts as a gradient or image background when it finds:

• a CSS gradient (linear, radial, conic, repeating),
• a background image file,
• or a picture, video or canvas positioned behind the text and covering most of it.

The opposite case is handled too: if a solid, opaque color is painted on top of the image, the image never reaches the reader's eye, so it is ignored and the check goes back to the simple flat-color path.

Even when the style sheet claims the background is a plain color, the detector takes a second look at the real pixels. This catches surfaces that look varied without being declared as gradients — semi-transparent panels, overlays and tinted layers.

Step 2 — Wait until the page actually looks finished

Measuring too early is the main way a contrast tool gets things wrong, so before measuring anything the detector:

• scrolls the element into view, because many sites only load a card's background photo once it appears on screen;
• waits for background images to finish loading (up to a couple of seconds). Otherwise it would measure a white gap where the photo is about to appear, and report white text on white;
• waits for animations and transitions to settle — highlight effects that sweep across text, or hover colors that fade in, would otherwise be caught half-way and produce a color nobody ever actually sees.

Step 3 — Measure

For a pure CSS gradient, the detector first reads the gradient's own declared colors. It compares the text against each color stop and keeps the worst result. If even that worst case comfortably passes, the check stops there — no screenshot needed, which keeps scans fast.

For a photo, an image, or a gradient that did not clearly pass, a precise measurement is taken:

1. The text itself is made temporarily invisible, so only the surface behind it is captured.
2. A small screenshot of just that element is taken.
3. 150–300 points are sampled across the exact area the text occupies — not just the middle. A photo is often perfectly readable in one corner and unreadable in another; sampling only the center is what makes an ordinary eyedropper check too generous.
4. The contrast is calculated at every sampled point.
5. The lowest ratio found is reported, together with the background color at that specific worst point.

Transparency is accounted for throughout: if the text or the surface is partly see-through, it is blended with what lies underneath before comparing, so the numbers match what the eye actually receives.

Step 4 — Report the finding

Because a gradient or a photo has no single color, the report shows the one color that produced the worst result, and labels it honestly:

• gradient <color> background, approx (#hex) — a CSS gradient
• image <color> background, approx (#hex) — a photo or image file
• sampled <color> background, approx (#hex) — a blended or semi-transparent surface that had to be read from the screen

The word approx is deliberate. It tells whoever verifies the issue that this value was measured from the rendered page, so an exact match against a line of CSS should not be expected — the surface genuinely varies from point to point.

Step 5 — Suggest a fix

The detector then proposes one single change, never two at once: either a new text color or a new background color. It picks whichever change:

• stays closest to the original design (it tries to keep the same color family and hue rather than jumping to near-black or near-white), and
• just reaches the required ratio, rather than overshooting it.

For gradient and image backgrounds, the suggestion is calculated against that worst-case approximated color, so a fix that satisfies it will hold across the whole surface.

Built-in safeguards against false alarms

A lot of the behavior exists specifically to avoid reporting problems that are not real:

Situation	What the detector does
Decorative image that does not actually sit under the words	Detects that the real surface is the page background, and measures against that instead
Background photo still loading	Waits for it, rather than measuring the empty space
Animated highlight or color transition in progress	Waits for it to finish before capturing
A banner, popup or overlay covering the element	Skips the pixel measurement rather than measuring the wrong thing
Rounded corners, clipped or masked shapes	Does not treat the exposed corner pixels as a gradient
Dropdown <select> controls	Samples only the text area, ignoring the arrow icon on the right
The capture accidentally catches the text itself	Detects this and discards the sample, falling back to the declared colors
Element inside an embedded frame, or no longer on the page	Not reported, because it could not be reliably re-checked by a human

Hover and focus states are measured the same way, but always with a fresh capture in that state — a color measured in the normal state is never reused for a hover or focus finding.

What to keep in mind when reading a result

• The reported background color is a representative sample, not the whole surface. It is the specific point where contrast was worst.
• The detector is deliberately strict. It reports the hardest-to-read spot, so a result may look worse than a manual check done with an eyedropper in the middle of the text. That is intentional: readability has to hold across the entire line.
• Measurements describe one moment in time. Backgrounds that are video, or that keep changing, are measured at the point of capture.
• Fix suggestions assume a solid replacement color. On a gradient or photo, the suggested value is the one that works against the worst part of the surface — applying it is safe everywhere else too.
• Common remedies for text over photography, beyond changing the color, include adding a solid or semi-transparent panel behind the text, or darkening/lightening the image in the area where the text sits. The detector reports the problem and one direct color fix; these design alternatives are equally valid answers to the same finding.

Related

Some compositions remain genuinely hard to measure — fixed or absolutely positioned backgrounds, blend modes and filters, or gradients used as the text color itself. Those known cases are documented in Gradient Limits.