Contrast

Gray text on a white background is the default aesthetic of modern UI. It signals hierarchy: this is secondary, this is metadata, this is less important. The problem is that most grays are less important and less readable.

WCAG AAWeb Content Accessibility Guidelines Level AA. Requires a minimum 4.5:1 contrast ratio for normal body text and 3:1 for large text against any background. requires 4.5:1 contrast ratioA numerical measure of luminance difference between two colors. Expressed as X:1, a ratio of 1:1 is identical colors, 21:1 is black on white. Calculated from relative luminance values per the WCAG formula. for body text. That's not bureaucracy. It's the threshold where text remains readable for users with low vision, on poor displays, in bright sunlight, and for everyone who is tired.

Drag the slider toward white. There is a precise moment where the text stops being "stylish gray" and becomes "unreadable gray." You crossed 4.5:1 without noticing if you weren't watching the number.

The calculator defaults to the light-background example above, regardless of site theme.

Enter your own text and background colors with the swatches or hex fields. The calculator applies the WCAG formula: relative luminance for each color, then (Llight + 0.05) / (Ldark + 0.05). Try #9E9E9E on white and watch it land around 2.85:1. Then try #ffffff on #000000 and watch it hit 21:1, a perfect score that can still fail real readers.

The #9E9E9E caption is everywhere: timestamps, helper text, disabled-looking labels that aren't disabled. It averages about 2.85:1 on white. It fails AA. It ships anyway because it looks clean on a Retina display in a dim room.

Low contrast doesn't just exclude users with color vision deficienciesA range of conditions affecting the perception of color. The most common form, red green deficiency, affects roughly 8% of men and 0.5% of women. Contrast failures are often invisible to unaffected designers.. About 8% of men have some form of it. It increases cognitive load for everyone. Gray text is slower text.

On light backgrounds, secondary text still needs to pass AA without drifting to #9E9E9E. The fixed caption in the comparison above uses #525252 at about 7.5:1 on white:

.caption, .muted, .secondary {
color: #525252;
}

.caption, .muted, .secondary {
color: #525252;
}

WCAG sets a floor, not a ceiling. There is no maximum contrast requirement in WCAG 2.x. A calculator will happily give you 21:1 for pure white on pure black and call it accessible. That number is technically correct and practically wrong for a large share of your audience.

HalationA visual effect where bright text on a very dark background appears to glow or bleed at the edges, reducing sharpness and readability. Also called the irradiation effect. Most pronounced with light-on-dark polarity. is the main failure mode. Light text on a near-black background can look haloed or blurred, especially at night, on OLED screens, and for users with astigmatismA refractive error where the eye cannot focus light evenly on the retina. Roughly 30-40% of adults have some degree of astigmatism. Halation from extreme light-on-dark contrast is a documented trigger.. The W3C's own contrast research notes that maximum contrast does not serve the broadest audience: older eyes struggle with scatter and glare, and excessive contrast increases fatigue. FAA Human Factors design standards cite 15:1 as a reasonable maximum for body text, well below the 21:1 of black on white.

This hits dark mode hardest. The same ratio feels harsher when text is lighter than its background. Pure #ffffff on #000000 is 21:1. Pure white on #121212 is still about 18.7:1. Both pass WCAG. Both can trigger halation. The fix is not less accessibility. It is softer extremes: off-white text around #e8e8e8 on dark gray around #121212, landing near 12-15:1. Still AAA. Much less glare.

On light backgrounds, near-black text on white is less prone to halation. #171717 on white at roughly 18:1 is fine for body copy. The danger zone is mostly light-on-dark at the extremes. The dark theme shipped as inverted light theme without retuning colors.

Dark backgrounds need a separate caption token. Reusing #525252 on #121212 drops to about 2.4:1. Fading body text with opacity is just as unreliable. The effective ratio shifts with every background you stack it on.

Softened dark mode body copy targets roughly 12-15:1. On this site, headings and body use #e8e8e8 on #181818 at about 14.5:1. Secondary and caption tokens keep the same hierarchy as light mode at #969696 and #757575:

@media (prefers-color-scheme: dark) {
body {
  color: #e8e8e8;
  background: #181818;
}

.secondary {
  color: #969696;
}

.caption, .muted {
  color: #757575;
}
}

@media (prefers-color-scheme: dark) {
body {
  color: #e8e8e8;
  background: #181818;
}

.secondary {
  color: #969696;
}

.caption, .muted {
  color: #757575;
}
}

This site toggles dark mode with a data-theme attribute (via next-themes), not only prefers-color-scheme. The media query above is still the pattern most teams ship; the values match this site's dark palette.

The upcoming APCA contrast model (the direction for WCAG 3) treats light-on-dark and dark-on-light as different problems and experiments with maximum contrast caps for dark themes. Until then, treat your calculator result as a range: below 4.5:1 fails, above 15:1 on dark backgrounds deserves a second look, and above 17:1 light-on-dark is halation territory for body text.