# Your Theme Update Just Broke Contrast. Your Scanner Watched It Happen.

Source: https://accessignal.com/blog/2026-11-13-contrast-regression-theme-update.html

November 13, 2026

*A theme update that changes a color variable can drop body text below the 4.5 to 1 contrast minimum across the whole store in one deploy. Watch contrast as a monitored metric, not a one-time audit item, and alert on the ratio, not on the color.*

## Contrast breaks in deploys, not in design reviews

Nobody sets out to ship unreadable text. A designer picks a gray that passes 4.5 to 1 against white, the audit confirms it, and the site ships. Then a theme update swaps the background to a warm off-white, or a seasonal campaign changes the button color, and the same gray now measures 3.8 to 1. Nothing in the design review caught it, because the review looked at mockups, not at the live combination. The failure is a deploy artifact, and deploy artifacts are what monitoring exists to catch.

The ratio to watch is 4.5 to 1 for normal text and 3 to 1 for large text and non-text elements like [focus indicators and icons](2026-11-12-monitoring-404-error-pages-accessibility.md), both from WCAG 2.1 AA. Those numbers are the floor, not the goal, and they apply to the combination as rendered, not to the swatch in the brand guide. A text color that passes on the homepage can fail on the product page, where it sits on a different background, and fail again in the cart drawer, where the overlay darkens everything behind it.

## The three ratios worth alerting on

Alert on body text first, because it is the most text on the page and the first thing a low-vision user hits. Then alert on the primary button, because a button that cannot be read cannot be pressed, and button colors change more often than body colors do. Then alert on the focus indicator, which has its own 3 to 1 requirement and which theme updates love to restyle into a faint gray outline. Three alerts cover nearly every contrast regression a storefront ships, and each one maps to a specific WCAG criterion, so the alert text can say exactly what broke.

Set the threshold at the criterion, not at a margin above it. An alert that fires at 4.6 to 1 teaches the team to ignore it. An alert that fires at 4.4 to 1 means something real changed, and the fix is usually one variable in the theme settings. Record the ratio in the alert, not just the fact of the failure, so the person fixing it knows whether the text needs darkening by a little or a lot.

## What the alert should say

A useful contrast alert names the element, the two colors, and the measured ratio. Body text on product pages measures 3.8 to 1 against the new background, needs 4.5 to 1. That sentence is enough for a developer to fix it without opening a design tool. A useless alert says contrast issue detected on 14 pages, which sends someone hunting through screenshots to find which element and which color changed. The difference is the cost of the fix, and monitoring that produces unactionable alerts gets muted, which is worse than no monitoring at all.

Route the alert to the person who shipped the change, not to a general channel. [The deploy that broke contrast](2026-11-12-monitoring-recaptcha-bot-checks-keyboard-users.md) is the deploy that should fix it, and the owner is the person whose commit touched the theme variables. If the alert lands in a queue nobody owns, it becomes noise, and the next theme update breaks contrast again. The alert is only as good as the owner attached to it.

## The check that costs nothing

Run axe-core in CI against the homepage, a product page, and the cart, and fail the build on a contrast regression. The scan takes seconds and it catches the exact failure a human review misses, because it measures the rendered combination. Pair it with a visual check on the two pages where text sits on images, the hero and the collection banner, because automated contrast checks cannot judge text over a photograph. That pair, automated plus two manual spots, is the whole monitoring setup. It costs an afternoon to build and it catches the regression the day it ships instead of the month a user reports it.

## Frequently asked questions

### What contrast ratio does WCAG require for body text?

Normal text needs at least 4.5 to 1 against its background at Level AA. Large text, defined as 18 point or 14 point bold and above, needs 3 to 1. Non-text elements like focus indicators and icons also need 3 to 1.

### Why did contrast pass in design and fail live?

Because the design review checked a swatch against white, and the live page renders the text against a different background. Theme variables, overlays, and image backgrounds all change the combination. The ratio has to be measured as rendered.

### Can automation catch every contrast failure?

No. Automated checks measure solid color combinations reliably, but text over images and gradients needs a human eye. Run the automated scan on every deploy and check the hero and collection banner by hand.

### Should I alert on 4.5 to 1 exactly, or build in a margin?

Alert at the criterion. A margin trains the team to ignore alerts that fire on passing text. If you want a safety buffer, build it into the design tokens, not into the alert threshold.