English
Site menu

link-in-text-block

Links in text blocks must be distinguishable from surrounding text without relying on color alone

automaticWCAG 1.4.1 (A)confidence: highseverity: seriousperceivable

Checks that a link inside a run of text is visually distinguishable from the surrounding text by a non-color cue (underline, font-weight or style, border, background, icon), and asks about links distinguished only by a >=3:1 color difference, which also need a hover and focus cue.

Applies to. Applies to links (<a href> and elements whose role attribute resolves to link: its first known role token, in any case, is link) that draw text (text other than white space in the link's flat tree and, where the page has a layout, a box with some area) and whose immediate parent element also has text with a letter or a digit beside it: a direct-child text node, or text in an inline element on the same line that is not a link, is not drawn invisibly, and is not an item of a flex or grid parent (i.e. the link sits inline within a run of plain text, not as a standalone item, e.g. not the sole content of a <li> nav item, nor one of a row of links separated by "|" or "·"). A custom element whose ElementInternals give it the link role (this.attachInternals().role), with no role attribute naming another, counts as a native element with that role does.

Expectation. A link inside a text block must be visually distinguishable from the surrounding text by at least one non-color means:

  • text-decoration: underline, OR
  • a different font-weight or font-style than the surrounding text, OR
  • another visible mark on the link itself: a border, box-shadow or outline, a background color different from the surrounding one, a background image, an image or svg inside it, or a ::before/::after that draws something (content of its own, or an empty box painting a background, border, outline or shadow, as an underline drawn that way does), OR
  • a mark on all of its content: bold, italic, underlined, bordered, a background unlike the surrounding text's (a code chip, <mark>), or raised or lowered (a footnote's <sup>).

A link with none of these is distinguished by color alone. When its color contrasts with the surrounding text by at least 3:1, technique G183 is met only if hover and focus also bring a non-color cue, which a static scan cannot see, so the link is reported as cantTell. Below 3:1, with contrast confidently computable, color is demonstrably the only cue and the link fails. The ratio between the link's color and the text's needs no background, so where only the background, or an effect applied alike to both, keeps it from being measured, two opaque text colors still decide it. Margin (contrast-ratio): of the links told apart by color alone that reach 3:1, the one closest to it, with its ratio unrounded. Those links are also asked about (the hover and focus cue), so the margin appears on a cantTell or fail result. Only a link within 10% of 3:1 (up to 3.3:1) counts as close. measuredCount counts the links whose only cue is color.

What a finding reports.

  • metrics.ratio (a link set apart by color only): the contrast between the link's text color and the surrounding text's, as a ratio (3 for 3:1), against metrics.threshold (3).
  • metrics.ratioBeforeOpacity (a link set apart by color only, under ANCESTOR_OPACITY): that ratio before an ancestor's opacity fades the link and the text alike, in place of metrics.ratio. The fading brings the two colors closer, so the ratio drawn may be lower: below 3:1 the link fails all the same, at 3:1 or more it is asked about with no lean toward pass, and it gives no margin.
  • colors.linkForegroundHex, colors.surroundingTextForegroundHex (a link set apart by color only): the link's text color and the surrounding text's, as hex.
  • colorScheme (a link with a background color of its own, on the canvas of a page that supports light and dark): 'light' or 'dark', the scheme in which that background doesn't set it apart from the canvas around it, where it does in the other; the ratio and colors are that scheme's. Absent where it falls short in every scheme measured.
  • colorSchemesChecked (the same link): the schemes it was compared in, where the page supports both and one could not be measured (its colors or the backgrounds around it may change with the scheme). A binding can scan again with the browser in the other scheme.

These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.

Margin. This rule measures contrast-ratio as a ratio, and the value must reach the threshold. When a pass came near the threshold, the result’s margin names the element that came closest while still meeting it, so a pass that a small change would flip shows before it flips. Unlike the fields a finding reports, it is a stable contract. See Output schema.

Examples

pass
<p>Read <a href="#" style="text-decoration:underline">this underlined link</a> for more information.</p>

The link is underlined, distinguishing it from surrounding text by more than color.

fail
<p style="color:#222222; background:#ffffff;">Read <a href="#" style="text-decoration:none; color:#2a2a2a;">this link</a> for more information.</p>

The only difference from surrounding text is a color shift with about 1.1:1 contrast, well under the 3:1 minimum, and no underline or weight/style change.

can't tell
<p style="color:#000000;">Read <a href="#" style="text-decoration:none; color:#d00000;">this link</a> for more information.</p>

The link's color contrasts with the text by more than 3:1, but color is its only cue. Technique G183 also needs a non-color cue on hover and focus, which a person checks.

How to check

When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.

ANCESTOR_OPACITY

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is set apart by an underline, bold, italics, a border or another mark; read colors from the screen, since the fading changes them.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

BACKGROUND_FILTER_OR_BACKDROP_FILTER

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is set apart by an underline, bold, italics, a border or another mark; read colors from the screen, since the filter changes them.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

BACKGROUND_IMAGE_OR_GRADIENT

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is set apart by an underline, bold, italics, a border or another mark, not just its color over the background image.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

BACKGROUND_NOT_OPAQUE_AT_ROOT

  1. Find the link the report names inside its paragraph; the page sets no opaque background, so what shows around it is the canvas the browser paints, or, in a frame, the page around it.
  2. View the page where it is shown: inside the page that embeds it, with forced colors off, and in each color scheme the page supports (light and dark).
  3. In each setting, check whether the link's background color stands out from the background around it, or an underline or another non-color mark sets the link apart.

Pass. In every setting where the page is shown, the link's background stands out from the one around it, or another non-color mark sets the link apart.

Fail. In some setting the link's background matches the one around it and only a color difference of less than 3:1 sets the link apart, which fails WCAG 1.4.1 (F73).

BACKGROUND_OVERLAP

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is set apart by an underline, bold, italics, a border or another mark, not just its color.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

COLOR_NOT_COMPUTABLE

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is set apart on screen by an underline, bold, italics, a border or another mark.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

CONTRAST_HELPERS_UNAVAILABLE

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is set apart by an underline, bold, italics, a border or another mark.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

ELEMENT_OPACITY

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is set apart by an underline, bold, italics, a border or another mark; read its color from the screen, since its own opacity changes it.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

ENGINE_EXCEPTION

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is set apart by an underline, bold, italics, a border or another mark.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

  1. Find the link the report names inside its paragraph; the report gives its contrast with the surrounding text.
  2. Hover the pointer over the link and check whether an underline or another non-color mark appears.
  3. Click just before the link and press Tab until it has focus, and check again for a non-color mark.

Pass. Both hover and focus add a non-color cue, such as an underline, to the link.

Fail. Hover or focus changes only the color, so color alone sets the link apart, which fails WCAG 1.4.1 (G183, F73).

MIX_BLEND_MODE

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is set apart by an underline, bold, italics, a border or another mark; read colors from the screen, since blending changes them.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

PSEUDO_ELEMENT_COLOR

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is set apart by an underline, bold, italics, a border or another mark; if it sits on the paragraph's first line or first letter, compare it with the text on that line.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

SELECT_OPTION_COLOR

  1. Find the drop-down the report names and open its list of options.
  2. Look at the option the report names next to the other options' text.
  3. Check whether it is set apart by something other than color (an underline, bold, a mark); if only color differs, read both colors with the color picker's eyedropper and check the contrast is at least 3:1.

Pass. The option is set apart by a non-color cue, or its color contrasts with the other text by at least 3:1 with a non-color cue on focus.

Fail. Color alone sets the option apart, below 3:1 or with no other cue, which fails WCAG 1.4.1 (F73).

TEXT_DECORATION_NOT_RESOLVABLE

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is underlined on screen, or set apart by bold, italics, a border or another mark.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

TEXT_SHADOW

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is set apart by an underline, bold, italics, a border or another mark; a shadow shared with the text does not count.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

TEXT_STROKE

  1. Find the link the report names inside its paragraph and look at it next to the surrounding text.
  2. Check whether the link is set apart by an underline, bold, italics, a border or another mark; read colors from the screen, where the stroke is drawn.
  3. If nothing but color differs, use the color picker's eyedropper in the developer tools to read the link color and the text color as drawn, and check their contrast is at least 3:1.
  4. Then hover the pointer over the link and Tab to it, and check that an underline or another non-color mark appears.

Pass. The link has a non-color cue such as an underline, bold or a border, or its color contrasts with the text by at least 3:1 and hover and focus add a non-color cue.

Fail. The link has no non-color cue and it is told apart from the text by color alone, at less than 3:1 or with no non-color cue on hover and focus, which fails WCAG 1.4.1 (F73).

View source