Colour Contrast in Builder Themes: The Most Common Failure on the Web

Two success criteria, both about the same thing at different levels of ambition.

SC 1.4.3 Contrast (Minimum), Level AA, asks for at least 4.5:1 for text, and 3:1 for large-scale text. This is the threshold almost every legal instrument that references WCAG is pointing at.

SC 1.4.6 Contrast (Enhanced), Level AAA, asks for at least 7:1 for text, and 4.5:1 for large-scale text.

"Large-scale" has a definition rather than a vibe: at least 18 point, or 14 point bold. In CSS terms that lands around 24px, or about 18.66px when bold.

There is a third criterion people forget entirely. SC 1.4.11 Non-text Contrast, Level AA, asks for 3:1 on the parts of the interface that are not text — the border of an input, the outline of a focus ring, the stroke of an icon that carries meaning. A form field whose only boundary is a pale grey hairline can fail this while every word on the page passes.

Rampline itself is built to the enhanced criterion rather than the minimum, and the working is a script in the repository rather than a claim: body text here measures 19.68:1, black on the yellow bands measures 13.75:1, and the lightest rule the design is allowed to draw measures 3.45:1. Three obvious uses of the yellow were measured and rejected — yellow type on white at 1.43:1, white type on yellow at the same, and a darkened yellow hairline on white at 1.87:1. That last set is the useful part of the exercise, because it is where the intuition fails.

Four mechanisms, and most low-contrast sites have several of them at once.

Theme previews are shot on ideal content. The demo has a two-word heading in 48px over a dark photograph. Your version has a paragraph of body copy in 15px over the light part of the same photograph. The theme was never wrong; it was demonstrated in a condition you do not share.

The greys are chosen by eye on a good screen. Designers work on bright, colour-accurate displays in controlled light. Your reader is outdoors, on a phone at 40% brightness, with a smeared screen protector. The grey that reads as "elegantly subdued" in the studio reads as "absent" on the train.

Text over images is unmeasurable by construction. Any contrast figure you calculate is against one pixel. Move the crop, change the image, resize the window, and the ratio changes. Builders encourage this layout because it photographs well.

Brand colour is treated as non-negotiable. A mid-tone brand colour used as body text can land just under the 4.5:1 minimum — close enough to look fine and far enough to fail. The resolution is almost always to keep the brand colour for large display type, backgrounds and shapes, and use a darker variant for running text. Nobody has ever noticed the difference except the people who could suddenly read the page.

Any browser's developer tools will give you a computed contrast ratio if you inspect an element and open the colour swatch next to its color property. That is the fastest route and it uses the colours actually rendered, which is better than the colours you think you specified.

Two habits make this considerably more useful.

Check the worst case, not the best. Find your smallest, lightest, longest piece of running text — usually the footer, a form's helper text, a date stamp, or a disclaimer. Those are the ones that fail. Headings are almost never the problem.

Check your states. Placeholder text, disabled controls, the hover colour of a link, and the text inside a button that changes appearance on focus. Placeholder text in particular is frequently three shades lighter than anything else on the page.

In rough order of how often we see it:

• Footer text. Small, pale, on a tinted background, and carrying your address and opening hours.
• Form helper and placeholder text. See above, plus an input border that fails 1.4.11 on its own.
• Captions under images. Styled as "quiet" by every theme on earth.
• Text over hero images. Unmeasurable, and usually white over something that is only dark in the corner it was cropped from.
• Button text on brand-coloured buttons. White on mid-blue, white on orange and white on yellow are the classic failures, and white on yellow is always catastrophic.
• Link colour inside body text. Often a lighter tint of the brand colour, which fails both the contrast criterion against the background and, if the underline has been removed, SC 1.4.1 Use of Color as well.
• Disabled buttons. Technically exempt from the contrast criteria as inactive elements, but if your visitor cannot tell why the button will not respond, you have solved a compliance question and created a usability one.

You very rarely need a new palette. You need two or three darker variants of the colours you already have.

1. Darken the body text first. If your running copy is a grey, take it towards black until it clears 4.5:1, then consider going further towards 7:1. Nobody has ever complained that body text was too legible.
2. Give links their underline back. This fixes a separate criterion and makes the link colour's exact value much less critical.
3. Split the brand colour in two. A display version and a text version. Use the text version anywhere the type is under 24px.
4. Put a solid panel behind text over images, rather than a gradient you have to guess about. This converts an unmeasurable case into a measurable one, which is the actual win.
5. Check the footer, because you have not.

None of this requires a subscription, a widget or a consultant, and none of it makes your site compliant with anything — that is a legal determination about your specific site and nothing here is legal advice. It does make your site readable, which is the point the standard is gesturing at.

How much your platform helps varies, and the assessment of ADA-compliant website builders covers which ones put a contrast check where the decision is being made rather than in a report afterwards.