axe-core link-in-text-block error link not distinguishable without color

axe-core link-in-text-block error link not distinguishable without color - how to fix it

TL;DR

When a link sits inside a block of text, color alone is not enough to identify it: color-blind users and users with low vision cannot tell it apart from surrounding text. Add a persistent underline (or another non-color cue like a border or icon) to text links via CSS, for example a { text-decoration: underline; }. Keep the underline on all states, not just hover.

Design systems love the clean look of color-only links, and the pushback on underlines is predictable. The data point that settles it: links must be identifiable without color per WCAG 1.4.1, and this is one of the few color rules that automated tooling can check reliably. Offer the design team underline-offset and thickness tuning; a well-styled underline looks intentional, not dated.

The verbatim error looks like this:

axe-core 4.8+
Rule: link-in-text-block (serious)
"Links must be distinguishable without relying on color"

Element: [a href="/terms"]terms of service[/a] inside a paragraph
  Link uses color alone; no underline or other non-color indicator.

Steps

1. Reproduce with the single rule:

npx @axe-core/cli https://example.com/article --rules link-in-text-block

Expected: inline links that rely on color alone are listed.

2. Confirm the flagged links are inline within text blocks. Standalone links in navs, footers, or buttons are out of scope for this rule.
3. Add a non-color indicator in your stylesheet:

a {
  text-decoration: underline;
  text-underline-offset: 2px;
}

If the design forbids underlines, use a persistent border-bottom or an inline icon that is present in every state.

4. Re-run the focused scan. Expected output: 0 violations for link-in-text-block.
5. Check contrast too: the link text must still meet the 4.5:1 contrast ratio against the background (the color-contrast rule), and the non-color indicator must survive forced-colors mode.
6. Check the design system's link component, not just the page. A 'subtle' or 'plain' link variant that strips the underline will fail everywhere it is used in body text. Fix the variant or restrict it to contexts outside text blocks (navs, buttons, standalone CTAs).
7. Verify in forced-colors mode (Windows High Contrast). Some underline styles vanish there; text-decoration underline generally survives, but border-bottom tricks may not. Test with the OS high-contrast theme on.

When to use

• Axe flags link-in-text-block on inline links.
• A content site styles links with color only and no underline.
• A design system ships a 'subtle link' variant that removes the underline everywhere.

When not to use

• The link has no discernible text at all (that is link-name).
• The link is a standalone nav item or button (this rule targets links inside text blocks).
• You are restyling visited/hover states only (keep the default-state indicator; that is what the rule checks).

Why it happens

About 1 in 12 men has some form of color-vision deficiency, and low-vision users may not perceive subtle color shifts at all. A link that is only 'blue text' is invisible as a link to them. The underline is the web's oldest affordance for a reason: it works without color perception. WCAG 1.4.1 (Use of Color) is the underlying criterion.

The web's default link style (blue and underlined) existed because early browsers could not rely on color alone on monochrome displays. As design matured, the underline was dropped for aesthetics while the blue remained, recreating the exact problem the underline solved. Axe added link-in-text-block as an experimental rule precisely because color-only links became the default in modern design systems.

Edge cases

• The rule is experimental in axe-core; some CI configs do not enable experimental rules. If your gate misses it, enable experimental rules or check it manually.
• Links that are already underlined on hover only still fail. The indicator must be present in the default state.
• Icons next to links count as a non-color indicator only if they are always visible, not hover-revealed.
• Email and print stylesheets sometimes strip underlines; keep the screen stylesheet compliant regardless.
• The rule ignores links that are the only content of a list item or nav, where position already identifies them as links.
• Links styled as buttons (background, border, padding) pass because the button affordance is a non-color indicator.
• Print stylesheets that underline all links are good practice; keep the screen styles compliant too.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_q4xYaYOoiDWKVapSbCGqBw