Skip to main content

Search rules

Search all UI Guides rules by name, category, or source

designRAMS

Insufficient Text Contrast

MUST

MUST: Text needs >= 4.5:1 against its background (WCAG 1.4.3); large text (>= 24px, or >= 19px bold) may use 3:1. Secondary text, captions and disabled states are where this fails. For UI component boundaries and states, `design-non-text-contrast` sets the separate 3:1 bar (WCAG 1.4.11). Test in both themes.

Text must have sufficient contrast with its background — including secondary text

Bad

Good

Why it matters

That is the whole upstream rule — one bullet under "Color & Contrast" in the Rams review. The number is WCAG 1.4.3 Level AA: 4.5:1 for body text, relaxed to 3:1 for large text (18pt / 14pt bold and above). The reasoning here is ours. The failures are almost never the headline; they are the quiet text — captions, helper text, placeholders, timestamps, and "muted" secondary copy, where a designer reached for light gray on white to make the layout calmer.

Disabled controls are formally exempt from 1.4.3, but if the disabled label is the only thing telling a user why they cannot proceed, exempt is not the same as readable. Check with a contrast tool rather than by eye, and re-check in dark mode, where a token that passed on white can fail on near-black. This rule sets the floor for TEXT only. The parts of a control that are not text — an input outline, a checkbox in its off state, a focus ring, a chart line — are governed by design-non-text-contrast (WCAG 1.4.11), whose AA floor is 3:1, not 4.5:1. The two numbers are not in conflict; they measure different things.

Built by Gleb Stroganov, design engineer at Evil Martians.

The rules come from other people's skills and guidelines — Vercel, Rauno Freiberg, @Ibelick, impeccable, Emil Kowalski, Tailwind, RAMS — each one credited on the Sources page. The work here is extraction and wiring: every rule is pulled into one corpus, given a good and a bad example you can operate, a MUST/SHOULD/NEVER rule an agent can paste, and a link back to where it came from.