WCAG Contrast Requirements by UI Element

WCAG Contrast Requirements by UI Element

WCAG does not give one contrast number for a whole interface. Normal body text needs 4.5:1 for AA, large text such as headings needs 3:1, and the visible boundaries and states of controls, like a button outline or a focus ring, need 3:1 under the separate non-text contrast rule. Checking every pair against the strictest number rejects colors that comply, and checking a border against the text rows misses the rule that actually covers it.

The element decides the threshold, so this page is organized by element. Large text and headings come first, because that size cutoff is where most review disagreements start. Buttons and component states follow, then dark-mode text, where the dim grays that feel restful fail most often, and finally brand colors, which are usually chosen long before anyone checks them. Each section uses the same checker: enter the foreground and background, then read the Normal Text, Large Text or UI Component row that matches the element.

Checking Contrast for Large Text and Headings

A heading styled at 32 pixels can pass WCAG at a contrast ratio that would fail outright as body copy, and that gap trips up more design reviews than almost any other single rule in the guideline. WCAG defines large text as at least 18 point, which works out to 24 CSS pixels at regular weight, or roughly 14 point bold, close to 18.7 pixels, and grants that category a lower bar: 3:1 for AA instead of the 4.5:1 normal text needs, and 4.5:1 for AAA instead of 7:1. Knowing exactly where that size threshold sits, and checking a heading color against the right tier rather than the stricter one meant for paragraphs, is the difference between rejecting a perfectly compliant color and shipping it.

Finding the exact pixel size where the lower threshold kicks in

The 18-point and 14-point-bold definitions in the WCAG spec sound abstract until you convert them into the CSS pixel values a browser actually renders, which is where most of the confusion around this rule comes from. Point sizes are a print-era unit, and most designers today think entirely in pixels, so the guideline's own wording needs a translation step before it becomes actionable.

Converting point sizes into the CSS pixels your stylesheet uses

Eighteen point works out to 24 CSS pixels at regular font weight, using the standard 1 point equals 1.333 pixels conversion, while 14 point bold lands close to 18.7 pixels.¹ A 24px regular heading and an 18px bold label both qualify for the large-text thresholds, while a 20px regular subheading, a size many design systems use, falls just short and still needs to clear the stricter normal-text bar. That single missing pixel is easy to overlook in a spec review, yet it decides which of two very different ratio requirements actually applies.

That size boundary matters because thicker, taller letterforms genuinely stay legible at lower contrast than the same color pair would at body-text size,¹ which is the entire reasoning behind WCAG granting large text a lower bar in the first place rather than treating every visible pixel identically. Treating a headline and a caption as if they carried the same legibility risk would waste real design freedom on the headline for no accessibility benefit.

Bold weight lowers the size threshold, not the contrast requirement

Bumping a heading to bold weight, font-weight: bold or the numeric 700,² lowers the pixel size needed to qualify as large text, from 24px down to roughly 18.7px, but it does not change the ratio target itself once a piece of text does qualify. It's a useful lever for a compact UI label that needs large-text treatment without taking up as much vertical space as a full 24px line.

A bold 19px label and a regular 24px headline both need the same 3:1 for AA, so weight is a tool for hitting the large-text size threshold at a smaller footprint, not a separate lever on the ratio requirement. Confuse the two and you either reject a compliant bold label for a threshold it never needed to meet, or approve a regular-weight one that actually needed the stricter bar.

Checking a heading color against the right threshold

Type your heading's exact foreground and background into the fields above and read the Large Text row specifically, not the Normal Text row, since the two apply completely different thresholds to the same colors.³ Reading the wrong row is the single most common mistake in a heading-contrast review, and it goes in both directions, rejecting valid colors and approving invalid ones equally often.

A color that fails as body text can be a legitimate heading choice

A muted slate gray like #808a9c against a white background lands around 3.5:1, comfortably clearing the large-text AA bar while falling well short of the 4.5:1 normal text needs.⁴ Type that exact pair into the fields above and both outcomes appear side by side in the same preview panel, one badge green and the other red for the identical two colors.

That's not a bug in the guideline or a loophole to exploit carefully; it's the intended outcome of a rule built around a real legibility difference between big, bold letterforms and small, dense body copy. Confirm the size and weight of the text you're actually shipping before you approve a color on the strength of the large-text row alone, since a heading style that later gets reused at a smaller size or lighter weight needs to be re-checked against the stricter thresholds.⁵

When to use this

Use this guide when choosing or auditing a heading, label, or any large-text element, whenever you need to confirm a color against the correct large-text threshold instead of the stricter bar meant for body copy.

Examples

Foreground #808a9c, background #ffffff

The Large Text (24px Bold) row clears AA at roughly 3.5:1, while the Normal Text (16px) row fails, since both rows render side by side for the same pair and only the large-text threshold is low enough to pass here.

Foreground #6b7280, background #ffffff

This pair clears the Normal Text (16px) row at AA as well as the Large Text (24px Bold) row, so it works as a heading or as body copy without needing a separate check for either.

Checking Contrast for Button and UI Component States

A button's fill color and label text usually get a careful contrast check before launch, but the border around an outline button, or the ring around a focus state, quietly gets skipped far more often. WCAG covers that gap under success criterion 1.4.11, the non-text contrast rule, which requires visible interface boundaries and states to reach 3:1 against their surrounding color,¹ a separate and lower bar than the 4.5:1 body text needs. Testing a button's border, disabled state, and hover treatment here, one pair at a time, catches the interface elements a text-focused contrast review tends to walk right past.

The UI component row most contrast checks skip entirely

Most contrast audits focus on text, since that's where the highest-profile failures live, but WCAG's 1.4.11 criterion covers a different category: the visual boundaries and states of interface components like button outlines, input borders, and focus rings. A design review that checks every heading and paragraph but never opens this tool on a border color has only covered half of what WCAG actually requires.

Why default design-system grays often fail this specific threshold

A design system's default muted border color, chosen to look subtle and unobtrusive against a white background, is frequently the exact color that fails 1.4.11's 3:1 requirement.² A slate gray border like #94a3b8 on white, for instance, reads as a soft, tasteful boundary to the eye while sitting well under the ratio the guideline actually requires, precisely because subtlety and sufficient contrast pull in opposite directions. Design teams rarely set out to fail this rule; they simply prioritize a quiet visual tone over a specific ratio number nobody checked.

The UI row in the preview panel above checks exactly this scenario. Unlike the text rows, it shows only a single AA badge, since WCAG defines no enhanced AAA tier for non-text contrast, meaning there's no stricter target to aim for beyond the one 3:1 bar every visible boundary needs to clear. Once that single badge turns green, the boundary color is done, with nothing further to chase toward a higher tier.

Hover and focus states need their own separate check

A button's default border is only the first check, not the last one. Hover, focus, and active states frequently swap in a different color entirely, and each of those states needs its own pass against 1.4.11 rather than inheriting a pass from the resting state. A design system that only checks the resting border and assumes every interactive variant inherits the same result is checking the easiest state and skipping the rest.

A focus ring in particular carries real accessibility weight, since keyboard users rely on it to track where they are on the page,³ which makes a low-contrast focus indicator a functional barrier, not just a cosmetic shortcoming. Someone tabbing through a long form with a faint focus ring can lose their place entirely, in a way a mouse user navigating the same page would never notice.

Disabled states and where WCAG intentionally looks away

Disabled controls occupy a genuine exception in WCAG's guidance: a button or input that is fully disabled, inert, and cannot be interacted with is not required to meet 1.4.11's contrast threshold at all,¹ since a control a user cannot act on carries less risk from being visually faint. That exception is narrow and specific, not a blanket excuse to leave every muted gray in a design system unchecked.

The exception ends the moment a control becomes interactive again

That exception evaporates the instant the same element becomes interactive, whether that's a form field unlocking after a previous step or a submit button re-enabling once required fields are filled.⁴ Multi-step forms and wizard-style flows are the most common place this transition gets missed, since the disabled-state color was approved once and never revisited for the enabled version.

A gray so faint it's barely visible is a defensible choice while a button stays genuinely disabled, but the same color needs a real contrast check the moment it can be clicked, since at that point it's a functional control again, not a placeholder.⁵ Type that exact gray into the fields above the moment a control regains interactivity, rather than assuming the disabled-state shade was ever meant to double as the active one.

When to use this

Use this guide when auditing a button, input, or focus ring for WCAG success criterion 1.4.11, whenever you want to check a specific border or state color that a text-only contrast review would otherwise miss.

Examples

Foreground #94a3b8, background #ffffff

The UI component row fails 3:1 here, even though the border reads as a tasteful, subtle line to the eye, which is exactly the kind of near-miss a visual review alone tends to approve.

Foreground #64748b, background #ffffff

Darkening the border by roughly one design-token step is often enough to clear 3:1 without the boundary reading as heavy or out of place.

Checking Contrast for Dark-Mode UI Text

Dark mode looks effortless until you actually have to pick the gray that text sits on top of, and the wrong choice either burns a faint afterimage into a reader's eyes or fails WCAG outright. The relative luminance formula this tool runs works exactly the same whether your background is near-black or pure white, but designers regularly get dark-mode pairs wrong in a specific, predictable way: choosing a foreground gray dim enough to feel restful, then discovering it barely clears 3:1 instead of the 4.5:1 body text actually needs.¹ A near-black background and a near-white foreground, like #121212 against #e0e0e0, is a safe, comfortably passing starting point worth understanding before you start narrowing the gap for aesthetic reasons.

Why dark mode tempts you toward failing contrast more than light mode does

Light-mode text almost always defaults toward black on white, a pairing so extreme that most designers would have to work hard to make it fail. Dark mode flips that instinct on its head, because pure white text on pure black can feel harsh and glary, especially in a dim room, so many interfaces deliberately soften both ends toward gray.

The gray-on-gray trap that fails more often than it should

That softening is exactly where trouble starts. A designer who lightens black to a comfortable charcoal and dims white to an easy-on-the-eyes off-white can end up with two colors that sit much closer together in relative luminance than either extreme would, sometimes without realizing how far the ratio dropped. Because both colors moved toward the middle of the brightness range at once, the contrast gap shrinks from both directions simultaneously, which is a faster way to fail than dimming just one side.

A safer approach keeps the background genuinely dark, close to true black, while giving the foreground more room to breathe than it would need against pure white. Material Design's widely used dark-theme baseline of a #121212 background against roughly 87% white text works for exactly this reason:² the background stays dark enough to avoid glare while the foreground stays light enough to clear AAA with room to spare.

Testing your own dark palette before you commit to it

Type your candidate background and text colors into the fields above and read the Normal Text row specifically, since that is the threshold most of your body copy actually needs to clear. The Large Text row still matters for headings inside the same dark palette, but it is a separate, more forgiving check worth reading on its own.

If the badge shows a fail or a bare AA pass and you'd rather have more headroom, click Fix text to see the closest lighter foreground that reaches AAA without drifting off your original hue, which the tool's OKLab-based search handles automatically,³ letting you keep the same general gray rather than jumping to an unrelated color.

Reading the ratio for an #e0e0e0-on-#121212 pair

Type #e0e0e0 into the foreground field and #121212 into the background field above and the badge clears every WCAG tier by a comfortable margin, including AAA's stricter 7:1 requirement for normal text.⁴ Swap the two around with the Swap button and the result stays every bit as comfortable, since the ratio treats foreground and background symmetrically.

Why this specific pairing has so much room to spare

That headroom exists because both colors sit near the extremes of the brightness range rather than compromising toward a shared middle gray. The background's near-black luminance and the foreground's near-white luminance stay far enough apart that even a slightly different gray on either side would likely still pass, which gives you real flexibility to warm or cool the palette slightly for brand reasons without risking a fail.

Treat a result this comfortable as a ceiling you can spend, not a target you need to hit exactly, since a slightly softer pairing that still clears AA is often more pleasant to read for long stretches than the maximum-contrast version.⁵ Use the ratio number above to decide how much of that ceiling you actually want to spend on any given screen.

When to use this

Use this guide whenever you are picking or auditing text colors for a dark-mode interface, and want to confirm a specific foreground and background pair before it ships rather than relying on how restful the pairing looks at a glance.

Examples

Foreground #e0e0e0, background #121212

Both colors plug directly into the formula above and clear every WCAG tier, including AAA, since the near-black background and near-white foreground sit far apart in relative luminance.

Foreground #757575, background #1e1e1e

The Normal Text row fails AA here, even though both colors read as comfortably dark and readable to the eye, since dimming the foreground reduced the ratio more than it looks like it should have.

Checking a Brand Color Pair Against WCAG

A brand color usually gets chosen in a logo file or a mood board long before anyone checks whether it can carry body text or button labels without failing accessibility review. That gap between this is our blue and this blue passes WCAG at 16px is exactly where design systems run into trouble months after launch, when a component built around the brand color turns out to fail a contrast audit.¹ Testing a candidate brand pair here, before it gets baked into buttons, links, and headings across a whole product, catches the problem while it's still a five-minute color adjustment rather than a re-brand.

Why a brand color that looks bold can still fail contrast

Saturated brand colors, the kind that make a logo pop on a business card, often sit in a middle brightness range that neither reads as clearly light nor clearly dark. That middle ground is precisely where contrast failures cluster, because a color that's too bright to work well against white and too dark to work well against black ends up compromised against both.

The saturation trap: vivid does not mean high contrast

A vivid blue like #2563eb looks confident and energetic on a white background, and it does clear AA's 4.5:1 threshold for normal text, but it falls short of AAA's stricter 7:1 bar.² A lighter, equally on-brand blue like #93c5fd can look almost identical in a logo lockup yet fail even the more forgiving large-text threshold against the same white background, because a small shift in lightness moves the ratio far more than it moves the color's apparent brand identity.

That's the trap: two shades of the same brand hue can sit on opposite sides of a pass or fail line while looking, to a design team eyeballing a mood board, like minor variations on the same color. Checking the exact hex value your team plans to ship, rather than judging the palette by eye, is the only way to know for certain which side of that line you landed on.

Keeping the hue while fixing the ratio

When a brand color fails, the instinct to just pick a completely different color is usually the wrong one, since it throws away the brand recognition the color exists to build. What you actually need is the smallest possible nudge that gets the same color over the line, not a replacement that starts the approval process over from scratch.

Auto-Fix solves the narrower problem instead: it searches for the closest lightness adjustment in OKLab space that reaches your target ratio while holding hue and chroma constant,³ so a failing brand blue comes back as a lighter or darker blue, not a color a brand guideline would reject. That's usually the difference between a fix your brand team signs off on in minutes and one that reopens a debate about the whole palette.

Locking in a pair once it passes, and sharing it with your team

Once a brand pair clears the tier you need, whether that's AA for general use or AAA for a long-form reading context,⁴ the Share button turns your exact foreground and background into a link anyone on your team can open to see the same result. No screenshot, spreadsheet cell, or verbal description of a color has to stand in for the real, checkable value again.

Documenting the decision instead of re-litigating it later

That link is worth attaching directly to the design system documentation or the ticket where the color got approved, since it saves the next person from re-deriving the ratio from scratch or trusting a screenshot that might not reflect the final hex value.⁵ Anyone who opens it later sees the live, current result rather than a snapshot that could have drifted out of date.

A shared, bookmarkable link that shows the exact pass or fail state removes the ambiguity that usually creeps in between a color being approved in a design file and it actually shipping in production CSS, and it gives future reviewers a live result instead of a static image that could quietly go stale.

When to use this

Use this guide before a brand color moves from a logo file into production CSS, whenever you need to confirm the exact hex pair clears WCAG rather than approving a palette by eye.

Examples

Foreground #2563eb, background #ffffff

The badge shows a clear AA pass for normal text, just short of AAA, giving you a real number to attach to the design decision instead of a guess.

Foreground #93c5fd, background #ffffff

Every tier fails here, including the more forgiving large-text threshold, which is exactly the kind of near-miss a mood board comparison would never catch.