Color Contrast and WCAG Guide
What Is Color Contrast?
Color contrast describes the measurable difference in relative luminance
between two colors. For text, the comparison is usually made between the
text color and the background directly behind it.
The contrast ratio ranges from 1:1 for identical colors to
21:1 for black and white.
Contrast Ratio Formula
After calculating the relative luminance of both colors, the contrast
ratio is calculated with the lighter luminance as L1 and
the darker luminance as L2.
contrast ratio = (L1 + 0.05) / (L2 + 0.05)
Relative Luminance Formula
Relative luminance is calculated from linearized red, green and blue
channel values.
L = 0.2126 × R + 0.7152 × G + 0.0722 × B
Converting sRGB Channels to Linear RGB
Each 8-bit channel must first be divided by 255. The
normalized channel is then converted to a linear value.
if channel <= 0.04045:
linear = channel / 12.92
otherwise:
linear = ((channel + 0.055) / 1.055) ^ 2.4
JavaScript Contrast Ratio Function
function normalizeHex(hex) {
let value = hex.trim().replace("#", "");
if (/^[0-9a-f]{3}$/i.test(value)) {
value = value
.split("")
.map(character => character + character)
.join("");
}
if (!/^[0-9a-f]{6}$/i.test(value)) {
throw new Error("Enter a valid 3-digit or 6-digit HEX color.");
}
return value;
}
function hexToRgb(hex) {
const value = normalizeHex(hex);
return {
r: parseInt(value.slice(0, 2), 16),
g: parseInt(value.slice(2, 4), 16),
b: parseInt(value.slice(4, 6), 16)
};
}
function srgbChannelToLinear(channel) {
const normalized = channel / 255;
if (normalized <= 0.04045) {
return normalized / 12.92;
}
return Math.pow((normalized + 0.055) / 1.055, 2.4);
}
function relativeLuminance(hex) {
const { r, g, b } = hexToRgb(hex);
const red = srgbChannelToLinear(r);
const green = srgbChannelToLinear(g);
const blue = srgbChannelToLinear(b);
return (
0.2126 * red +
0.7152 * green +
0.0722 * blue
);
}
function contrastRatio(foreground, background) {
const foregroundLuminance = relativeLuminance(foreground);
const backgroundLuminance = relativeLuminance(background);
const lighter = Math.max(
foregroundLuminance,
backgroundLuminance
);
const darker = Math.min(
foregroundLuminance,
backgroundLuminance
);
return (lighter + 0.05) / (darker + 0.05);
}
Classifying the Contrast Result
function getContrastResults(ratio) {
return {
normalTextAA: ratio >= 4.5,
largeTextAA: ratio >= 3,
normalTextAAA: ratio >= 7,
largeTextAAA: ratio >= 4.5,
nonTextAA: ratio >= 3
};
}
Formatting the Result
const ratio = contrastRatio("#003566", "#caf0f8");
const formattedRatio = `${ratio.toFixed(2)}:1`;
console.log(formattedRatio);
Normal Text Contrast
Normal text requires at least 4.5:1 for WCAG Level AA and
7:1 for Level AAA.
This category includes most paragraphs, navigation labels, button text,
form labels and other text that does not meet the large-text definition.
Large Text Contrast
Large text requires at least 3:1 for Level AA and
4.5:1 for Level AAA.
Do not assume text qualifies as large merely because it is bold. Both
font size and weight must be considered.
Non-Text Contrast
Meaningful visual information in interface components and graphics may
require a contrast ratio of at least 3:1 against adjacent
colors.
Examples include form control boundaries, selected states, chart lines,
icons and parts of graphics that users need to identify or understand.
Buttons and Form Controls
When checking a button, consider more than the label. Test:
- The button text against the button background.
- The button boundary against the surrounding page when the boundary is necessary.
- The hover state.
- The active state.
- The keyboard focus indicator.
- The disabled state, where applicable.
Links Inside Paragraphs
A link must remain readable against the page background. When color is
the only difference between the link and surrounding text, additional
contrast or another visual cue may be needed.
.content a {
color: #1d4ed8;
text-decoration: underline;
text-underline-offset: .15em;
}
Keyboard Focus Indicators
A custom focus indicator should be easy to distinguish from adjacent
colors. A thick outline with a strong contrasting color is usually more
reliable than a subtle shadow.
.button:focus-visible {
outline: 3px solid #111827;
outline-offset: 4px;
}
Text Over Images
A single contrast measurement may not represent an entire photograph.
Text placed over an image must remain readable against every part of the
image behind the letters.
A dark or light overlay can create a more predictable background.
.image-card {
background:
linear-gradient(
rgba(15, 23, 42, .2),
rgba(15, 23, 42, .88)
),
url("image.jpg") center / cover no-repeat;
color: #ffffff;
}
Text Over Gradients
Test contrast at the lightest and darkest parts of the gradient. The
average gradient color is not sufficient because individual letters may
appear over very different colors.
Opacity and Transparency
Contrast must be calculated from the final composited color shown on the
screen. A semi-transparent text or background color cannot be evaluated
correctly without including the color underneath it.
Placeholder Text
Placeholder text should not be used as the only visible label for a form
field. When it is displayed, it should still be readable against the
input background.
Disabled Controls
Inactive controls can be exempt from some contrast requirements, but
extremely faint disabled states may still confuse users. The state
should remain understandable in the context of the interface.
Dark Mode Contrast
Pure white text on pure black can provide maximum mathematical contrast,
but softer near-white and dark-gray combinations may be more comfortable
while still passing the required ratio.
.dark-theme {
background: #111827;
color: #f1f5f9;
}
Contrast and Color Vision Deficiencies
A passing luminance contrast ratio does not guarantee that every color
distinction will be obvious. Do not communicate errors, success, status
or selected states with color alone.
.error-message {
color: #b91c1c;
}
.error-message::before {
content: "Error: ";
font-weight: 700;
}
WCAG AA vs AAA
Level AA is the usual minimum target for accessible websites. Level AAA
uses stricter text contrast thresholds, but not every page or piece of
content is expected to satisfy every AAA success criterion.
WCAG 2.2 and Future Standards
The results in this tool should be described as WCAG 2.x contrast
results. Future accessibility standards may use additional perceptual
models, but draft standards should not replace the current normative
WCAG 2.2 checks in a production tool.
Best Practices
- Aim for at least 4.5:1 for normal text.
- Use 3:1 only when the text genuinely qualifies as large.
- Test all interactive states separately.
- Check focus outlines against adjacent colors.
- Test text over every part of an image or gradient.
- Calculate transparency after colors have been composited.
- Do not rely on color alone to communicate meaning.
- Test colors in the actual component, not only in isolation.
- Consider targeting AAA for important reading content when practical.