Accessibility Guides for colorblindness

Color contrast is one of the most common accessibility barriers on the web. When text doesn’t stand out enough from its background, it becomes difficult or impossible to read for many users. People with low vision experience reduced contrast sensitivity, meaning everything appears roughly the same brightness, making it hard to distinguish outlines, edges, and details. Approximately 1 in 12 people cannot see the full spectrum of colors — about 8% of men and 0.4% of women in the United States have some form of color vision deficiency. Nearly three times as many people have low vision compared to total blindness. Without sufficient contrast, these users simply cannot read your content.

This rule maps to WCAG 2.1 Success Criterion 1.4.3: Contrast (Minimum), which is a Level AA requirement. It is also referenced in WCAG 2.0, WCAG 2.2, the Trusted Tester methodology, EN 301 549, and RGAA. The user impact is considered serious because insufficient contrast directly prevents users from perceiving text content.

How Contrast Ratios Work

Contrast ratio is calculated by comparing the relative luminance of two colors on a scale from 1:1 (no contrast, e.g., white on white) to 21:1 (maximum contrast, black on white). WCAG defines two thresholds:

• Normal text (below 18pt or below 14pt bold): minimum 4.5:1 contrast ratio
• Large text (at least 18pt / 24px, or at least 14pt bold / 19px): minimum 3:1 contrast ratio

“Large text” is defined this way because larger characters have wider strokes that are easier to read at lower contrast levels.

What This Rule Checks

The color-contrast rule in axe-core examines each text element on the page and compares the computed foreground text color against the computed background color. It accounts for background color transparency and opacity. Elements that are found to have a 1:1 contrast ratio are flagged as “incomplete” and require manual review.

This rule does not flag:

• Text elements with a background-image (these require manual testing)
• Text that is visually hidden by other overlapping elements
• Images of text
• Text inside disabled controls (including child elements of disabled buttons)

Some foreground scenarios are harder for automated tools to evaluate, including CSS gradients, pseudo-element backgrounds, backgrounds created with CSS borders, and elements repositioned off-screen with CSS.

How to Fix It

1. Identify the failing elements by running axe. Each violation will report the current contrast ratio and the colors involved.
2. Adjust the foreground color, background color, or both until the required ratio is met (4.5:1 for normal text, 3:1 for large text).
3. Use a contrast checker tool like the axe DevTools browser extension, the WebAIM Contrast Checker, or the built-in color contrast analyzer in browser developer tools to test color combinations before deploying.
4. Test with real content — sometimes dynamic content or themed components produce contrast issues that static checks miss.

Examples

Insufficient contrast (fails)

This light gray text on a white background has a contrast ratio of approximately 2.6:1, which fails the 4.5:1 requirement.

<p style="color: #aaaaaa; background-color: #ffffff;">
  This text is hard to read.
</p>

Sufficient contrast (passes)

Darkening the text color to #595959 against a white background achieves a contrast ratio of approximately 7:1, meeting the requirement.

<p style="color: #595959; background-color: #ffffff;">
  This text is easy to read.
</p>

Large text with lower contrast requirement (passes)

Large text (18pt or larger) only needs a 3:1 contrast ratio. This example uses #767676 on white, which has a ratio of approximately 4.5:1 — well above the 3:1 threshold for large text.

<h1 style="font-size: 24pt; color: #767676; background-color: #ffffff;">
  Large heading text
</h1>

Semi-transparent background (fails)

Transparency can reduce effective contrast. Here, the semi-transparent white background doesn’t provide enough contrast depending on what’s behind it.

<div style="background-color: #cccccc;">
  <p style="color: #777777; background-color: rgba(255, 255, 255, 0.3);">
    Text with a semi-transparent background.
  </p>
</div>

Semi-transparent background fixed (passes)

Increasing the background opacity or adjusting colors restores sufficient contrast.

<div style="background-color: #cccccc;">
  <p style="color: #333333; background-color: rgba(255, 255, 255, 0.85);">
    Text with a more opaque background.
  </p>
</div>

Using CSS classes (passes)

In practice, you’ll likely use CSS classes rather than inline styles. Ensure your design system tokens and theme colors meet contrast requirements.

<style>
  .card {
    background-color: #1a1a2e;
  }
  .card-text {
    color: #e0e0e0;
  }
</style>

<div class="card">
  <p class="card-text">
    Light text on a dark background with good contrast.
  </p>
</div>

This rule is an informational check rather than a pass/fail test. It identifies elements whose content is hidden from both sighted users and assistive technologies, meaning automated tools like axe cannot inspect that content for issues. The goal is to ensure you don’t overlook potentially inaccessible content simply because it’s currently not visible.

Why this matters

When content is hidden using CSS properties like display: none or visibility: hidden, it is removed from the accessibility tree entirely. This means screen readers cannot access it, and automated testing tools cannot evaluate it. If that hidden content is later revealed — through user interaction, JavaScript toggling, or media queries — it must be fully accessible when it becomes visible.

Several groups of users can be affected by inaccessible hidden content:

• Screen reader users may encounter content that lacks proper labels, headings, or semantic structure once it’s revealed.
• Keyboard-only users may find that revealed content contains focus traps or elements that aren’t keyboard operable.
• Users with low vision or color blindness may encounter contrast or styling issues in content that was never tested because it was hidden during analysis.

If there’s a compelling reason to hide content from sighted users, there’s usually an equally compelling reason to hide it from screen reader users too. Conversely, when content is available to sighted users, it should also be available to assistive technology users.

This rule aligns with Deque best practices for thorough accessibility testing. While it doesn’t map to a specific WCAG success criterion, failing to review hidden content could mask violations of criteria like 1.1.1 Non-text Content, 1.3.1 Info and Relationships, 2.1.1 Keyboard, 4.1.2 Name, Role, Value, and many others.

How to fix it

When axe flags hidden content, you need to:

1. Identify the hidden elements reported by the rule.
2. Trigger their display — interact with the page to make the content visible (e.g., open a modal, expand an accordion, hover over a tooltip).
3. Run accessibility checks again on the now-visible content.
4. Fix any issues found in that content, just as you would for any visible element.
5. Verify hiding technique is appropriate — make sure content hidden with display: none or visibility: hidden is truly meant to be hidden from all users, including assistive technology users.

If you intend content to be visually hidden but still accessible to screen readers, use a visually-hidden CSS technique instead of display: none or visibility: hidden.

Examples

Hidden content that cannot be analyzed

This content is completely hidden from all users and automated tools:

<div style="display: none;">
  <img src="chart.png">
  <p>Quarterly revenue increased by 15%.</p>
</div>

The img element inside may be missing an alt attribute, but axe cannot detect this because the entire div is hidden. You must reveal this content and test it separately.

Hidden content revealed for testing and fixed

Once the content is made visible, you can identify and fix issues:

<div style="display: block;">
  <img src="chart.png" alt="Bar chart showing quarterly revenue increased by 15%">
  <p>Quarterly revenue increased by 15%.</p>
</div>

Using visibility: hidden

<nav style="visibility: hidden;">
  <a href="/home">Home</a>
  <a href="/about">About</a>
</nav>

This navigation is hidden from everyone. If it becomes visible through a JavaScript interaction, ensure it is tested in that visible state.

Visually hidden but accessible to screen readers

If you want content hidden visually but still available to assistive technologies, don’t use display: none or visibility: hidden. Use a visually-hidden class instead:

<style>
  .visually-hidden {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border: 0;
  }
</style>

<button>
<!-- icon -->
</svg>
  <span class="visually-hidden">Close menu</span>
</button>

This approach keeps the text accessible to screen readers while hiding it visually. Axe can still analyze this content because it remains in the accessibility tree.

Interactive content that toggles visibility

When content is toggled dynamically, make sure both states are tested:

<button aria-expanded="false" aria-controls="panel1">Show details</button>
<div id="panel1" style="display: none;">
  <p>Additional product details go here.</p>
</div>

<script>
  const button = document.querySelector('button');
  const panel = document.getElementById('panel1');
  button.addEventListener('click', () => {
    const expanded = button.getAttribute('aria-expanded') === 'true';
    button.setAttribute('aria-expanded', String(!expanded));
    panel.style.display = expanded ? 'none' : 'block';
  });
</script>

To fully test this, click the button to reveal the panel content, then run your accessibility analysis again to check the revealed content for any violations.

Why This Matters

Many users cannot perceive color differences reliably. Approximately 8% of men and 0.4% of women have some form of color vision deficiency, and there are nearly three times more people with low vision than those who are totally blind. For these users, if a link within a paragraph is styled only with a different color — say, blue text in a block of black text — it can be completely invisible as a link.

People with low vision often experience reduced contrast sensitivity, meaning everything appears roughly the same brightness. Without a non-color cue like an underline or a sufficient luminance difference, these users cannot detect that certain text is interactive. This can cause them to miss important navigation, actions, or information entirely.

This rule relates to WCAG 2.0/2.1/2.2 Success Criterion 1.4.1: Use of Color (Level A), which requires that color is not used as the only visual means of conveying information, indicating an action, or distinguishing a visual element. Links embedded in text are one of the most common places where this requirement is violated.

How the Rule Works

The axe rule link-in-text-block checks links that appear inside blocks of text (such as paragraphs) and evaluates them in three steps:

1. Non-color distinction present → Pass. If the link has a visual style that doesn’t depend on color — such as an underline, a border, a background color, or a distinct font weight/style — the rule passes automatically.

2. No non-color distinction and contrast below 3:1 → Fail. If the link relies only on color and the contrast ratio between the link text color and the surrounding text color is less than 3:1, the rule fails.

3. No non-color distinction but contrast is 3:1 or higher → Needs Review. If the link relies only on color but meets the 3:1 contrast threshold, the rule flags it for manual testing. You must verify that the link receives a distinct visual style (such as an underline) on :focus and :hover states.

How to Fix It

The simplest and most reliable fix is to give links a non-color visual indicator. Here are your options, in order of recommendation:

• Underline the link — This is the most universally understood link indicator.
• Add a border — A border-bottom can work as an alternative to text-decoration.
• Use a distinct font style — Bold or italic can help, though underline is more conventional for links.
• Add a background or outline — A subtle background color difference can work if it’s clearly visible.

If you choose to rely on color contrast alone (3:1 minimum between link text and surrounding text), you must also ensure the link gains a distinct non-color style on :hover and :focus. This two-part requirement exists because static contrast alone may not be sufficient for all users, but a visual change on interaction confirms the element is interactive.

Examples

Incorrect: Link distinguished only by color with insufficient contrast

<style>
  p { color: #333333; }
  a { color: #555555; text-decoration: none; }
</style>

<p>
  Learn more about our
  <a href="/services">consulting services</a>
  and how we can help.
</p>

In this example, the link has no underline and the color contrast between #555555 and #333333 is well below 3:1. Users with low vision or color blindness cannot identify the link.

Correct: Link has an underline (recommended)

<style>
  p { color: #333333; }
  a { color: #0056b3; text-decoration: underline; }
</style>

<p>
  Learn more about our
  <a href="/services">consulting services</a>
  and how we can help.
</p>

The underline provides a clear non-color visual cue, making the link identifiable regardless of color perception.

Correct: Link uses a bottom border instead of underline

<style>
  p { color: #333333; }
  a {
    color: #0056b3;
    text-decoration: none;
    border-bottom: 2px solid #0056b3;
  }
</style>

<p>
  Read our
  <a href="/guide">accessibility guide</a>
  for detailed instructions.
</p>

Correct: Color-only link with sufficient contrast plus hover/focus styles

<style>
  p { color: #333333; }
  a {
    color: #0000ee;
    text-decoration: none;
  }
  a:hover,
  a:focus {
    text-decoration: underline;
  }
</style>

<p>
  Visit our
  <a href="/help">help center</a>
  for answers to common questions.
</p>

Here the contrast between #0000ee and #333333 exceeds 3:1, and the link gains an underline on hover and focus. This satisfies the requirement, though note that axe will still flag this for manual review since it cannot automatically verify the hover/focus styles in all cases.

Incorrect: Underline removed with no replacement

<style>
  a { color: #1a73e8; text-decoration: none; }
  p { color: #000000; }
</style>

<p>
  Check out our
  <a href="/blog">latest blog posts</a>
  for updates.
</p>

Even though the blue color may seem obvious to sighted users with full color vision, removing the underline without providing another non-color indicator makes this link invisible to users with color blindness or low contrast sensitivity.