CSS Color Contrast

CSS Color Contrast

Color contrast is the visual difference between foreground content and its background. Sufficient contrast makes text, controls, icons, focus indicators, and other important interface elements easier to distinguish.

CSS controls many of the colors that affect contrast, including text color, background color, borders, outlines, and interactive states. Accessible color choices should remain understandable across the different states and contexts in which content appears.

How Color Contrast Works

Contrast describes how visually different two colors are when displayed together. For text, this usually means comparing the text color with the color immediately behind it.

.example {
  color: #222;
  background-color: #fff;
}

A strong difference in relative luminance generally makes foreground content easier to distinguish. Colors that appear different in hue can still have insufficient contrast if their relative luminance values are too similar.

Contrast should therefore be evaluated using the actual foreground and background colors rather than relying only on how different the colors appear.

Contrast Ratio

Contrast is commonly expressed as a ratio ranging from 1:1 to 21:1. A ratio of 1:1 represents no luminance contrast, while 21:1 is the maximum contrast between black and white.

WCAG defines minimum contrast ratios for certain types of text and user interface content. For WCAG 2.2 Level AA, normal text generally requires a contrast ratio of at least 4.5:1, while qualifying large text generally requires at least 3:1.

These ratios are accessibility requirements rather than CSS syntax. CSS determines the colors, while the resulting color combination determines the contrast ratio.

Normal Text

For WCAG 2.2 Level AA, text that does not qualify as large text generally needs a contrast ratio of at least 4.5:1 against its background.

.article-text {
  color: #333;
  background-color: #fff;
}

The exact contrast ratio depends on the colors being used. A color combination should be measured rather than assumed to meet the requirement.

Very light gray text on a white background is a common example of styling that can become difficult to read.

.low-contrast {
  color: #bbb;
  background-color: #fff;
}

Large Text

WCAG 2.2 defines large-scale text as at least 18 point regular text or at least 14 point bold text. In CSS terms, 18 points corresponds to 24 CSS pixels and 14 points corresponds to approximately 18.67 CSS pixels under the CSS reference conversion of 1 point to 1.333 CSS pixels.

Large-scale text generally requires a contrast ratio of at least 3:1 for WCAG 2.2 Level AA.

.large-heading {
  font-size: 24px;
  color: #555;
  background-color: #fff;
}

Font size and weight determine whether the lower large-text contrast threshold applies. Visual appearance alone should not be used to decide whether text qualifies as large-scale text.

Non-text Contrast

Contrast requirements are not limited to text. WCAG also addresses visual information needed to identify user interface components and meaningful graphical objects.

Relevant visual boundaries and states generally need a contrast ratio of at least 3:1 against adjacent colors.

.text-input {
  border: 2px solid #555;
  background-color: #fff;
}

Examples can include form control boundaries, meaningful icons, and visual indicators that users need in order to identify or operate an interface.

Not every decorative graphic or every part of a component has a contrast requirement. The requirement concerns visual information necessary to understand or operate the content.

Choosing CSS Colors

CSS provides many ways to specify colors, including hexadecimal, RGB, HSL, HWB, and named colors. The color format does not determine accessibility.

.one {
  color: #222;
}
.two {
  color: rgb(34 34 34);
}
.three {
  color: hsl(0 0% 13%);
}

These declarations can describe the same or similar colors using different syntax. What matters for contrast is the resulting rendered foreground and background colors.

This means changing from hexadecimal to HSL, for example, does not improve contrast unless the actual color value also changes.

Contrast and Backgrounds

Text contrast can become more difficult to control when content appears over gradients, photographs, patterns, or other backgrounds containing multiple colors.

.banner {
  color: #fff;
  background: linear-gradient(90deg, #00334d, #0088cc);
}

The text should have sufficient contrast against the background wherever the text is displayed, not just against one selected part of the background.

A solid or partially opaque background behind the text can make contrast more predictable.

.caption {
  color: #fff;
  background-color: rgb(0 0 0 / 80%);
}

Interactive States

Interactive elements can use several visual states, including default, hover, focus, active, visited, checked, and disabled states. Contrast should be considered for the states that communicate information or allow users to identify and operate controls.

a {
  color: #005f8f;
}
a:hover {
  color: #004466;
}
a:focus-visible {
  outline: 3px solid #005f8f;
  outline-offset: 3px;
}

A link that has sufficient contrast in its default state can become difficult to see if its hover or focus styling changes to a low-contrast color.

Focus indicators should also remain distinguishable from adjacent colors so keyboard users can identify the currently focused control.

Do Not Rely on Color Alone

Good contrast does not mean color should be the only visual method used to communicate important information. Some users may have difficulty distinguishing particular colors even when the colors meet a contrast requirement.

For example, form validation should not identify an error only by changing an input border from one color to another.

.error {
  color: #b00020;
  font-weight: bold;
}

The visual styling can be combined with explanatory text, an icon, or another meaningful indicator.

<p class="error"><strong>Error:</strong> Enter a valid email address.</p>

This gives users information in addition to the color change.

Testing Color Contrast

Contrast should be measured with a contrast checker rather than estimated by eye. Testing tools compare the foreground and background colors and calculate their contrast ratio.

Test the actual colors used by the page, including colors used for text, links, controls, focus indicators, and important graphics.

When text appears over an image, gradient, transparency, or changing background, test the areas where the contrast is weakest.

Automated accessibility tools can identify many contrast problems, but manual review is still useful for checking interactive states, complex backgrounds, and whether color is being used as the only way to communicate information.

Color Contrast Practices

CSS Color Contrast Example

The following example compares two text and background combinations. The first uses light gray text against white, while the second uses dark text against white.

.low-contrast {
  color: #aaa;
  background-color: #fff;
}
.stronger-contrast {
  color: #222;
  background-color: #fff;
}

Open the example in the editor and change the foreground and background colors. Compare how easily the text can be read, but remember that visual inspection does not replace measuring the actual contrast ratio with a contrast checker.