axe-core link-name error links must have discernible text

Not specified by the original author.

axe-core link-name error links must have discernible text - how to fix it

TL;DR

Give every link an accessible name: visible text, an aria-label, or an aria-labelledby reference. Icon-only links and empty linked images are the usual failures. One line of why: a link with no name is announced as just link, and a page of those is unusable with a screen reader.

The error, verbatim

{
  "id": "link-name",
  "impact": "serious",
  "help": "Links must have discernible text",
  "nodes": [
    { "target": [".social-icon-link"], "failureSummary": "Fix any of the following: Element does not have text that is visible to screen readers" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules link-name --save axe-link.json

Expected: Violations array contains link-name with the nameless link selectors.

Step 2: List the offending links

node -e "const r=require('./axe-link.json'); r.violations[0].nodes.forEach(function(n){console.log(n.target.join(' '))})"

Expected: Selectors like .social-icon-link pointing at each nameless link.

Step 3: Find them in source

rg -n --glob '*.{jsx,tsx,vue,html}' 'aria-label' src/components | head -30

Expected: Shows labeled links for reference; the flagged ones are the icon-only links missing labels.

Step 4: Name the links and re-scan

npx @axe-core/cli https://example.com --rules link-name

Expected: Exit code 0, 0 violations. Screen reader now announces the destination, for example Twitter profile, instead of just link.

Step 5: Gate the rule in CI

npx @axe-core/cli https://example.com --exit | tail -3

Expected: Non-zero exit while any violation remains; add this command to CI so the fix never regresses.

When to use this skill

• Your axe-core report lists this exact rule id under violations
• You are clearing automated WCAG 2.1 AA failures before a release or audit
• A CI a11y gate (pa11y-ci, lighthouse CI, cypress-axe) is red because of this rule

When NOT to use this skill

• The issue only shows up in manual screen-reader testing and axe reports zero violations for the rule
• You are doing a full manual WCAG audit, this skill covers the single automated rule only
• The page is a third-party embed you cannot edit, flag it to the vendor instead

Compatibility

axe-core 4.8+ (rule link-name, WCAG 2.4.4 / 4.1.2). Same rule in pa11y, lighthouse, and axe DevTools. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

links must have discernible text axe

The help text wording, same fix.

icon link no accessible name

The classic instance: social icon links in footers.

axe DevTools flags the same rule

The browser extension runs the same rule engine; fix once and it clears in every runner.

Why it happens

Icon-only links (social icons, linked logos) have no text content, and if the inner img has empty alt or the svg has no name, the computed accessible name is empty. Link text like click here passes the rule but fails WCAG 2.4.4 in spirit, axe only checks that a name exists, not that it is meaningful. Footer social icon rows are the single most common source. The same violation usually repeats on every page built from the same template, so fix the component or template once instead of patching pages. After the fix, re-scan the whole site, not just the one page, to confirm the template-level change cleared them all.

Edge cases

• An aria-label on the link overrides everything inside, keep it accurate to the destination.
• Linked images: the img alt becomes the link name, so empty alt on a linked image fails link-name too.
• Title attributes are a weak fallback and not reliably announced, prefer aria-label or visible text.
• Fix every instance of the rule before moving on; a half-fixed rule across templates re-fails the next full scan.

Provenance

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

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

Thread query: axe-core link-name error links must have discernible text

TL;DR: Give every link an accessible name: visible text, an aria-label, or an aria-labelledby reference. Icon-only links and empty linked images are the usual failures. One line of why: a link with no name is announced as just link, and a page of those is unusable with a screen reader.

Not specified by the original author.

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

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

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

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.

Not specified by the original author.

axe-core summary-name error summary element needs discernible text - how to fix it

TL;DR

A [summary] that contains only an icon gives the disclosure widget no accessible name, so screen reader users hear 'button collapsed' with no hint what it discloses. Put real text inside the summary, for example [summary]Shipping details[/summary], and keep the icon decorative with aria-hidden. Re-run the focused axe rule to confirm.

Icon-only disclosures are a design trend (plus/minus toggles, chevron rows) that collides directly with this rule. The accessible fix that preserves the design is visible text next to the icon, not an aria-label on the summary. Visible text helps sighted users too: an icon alone is ambiguous about what it discloses.

The verbatim error looks like this:

axe-core 4.x
Rule: summary-name (serious)
"Summary elements must have discernible text"

Element: [summary][svg aria-hidden="true"]...[/svg][/summary]
  No discernible text; the summary contains only an icon.

Steps

1. Reproduce with the single rule:

npx @axe-core/cli https://example.com/faq --rules summary-name

Expected: the icon-only summary elements are listed.

2. Open the flagged markup. The usual cause is a summary containing only an [svg] or [img] with no text, or text that is itself aria-hidden.
3. Add discernible text and mark the icon decorative:

[details]
  [summary]Shipping details [svg aria-hidden="true"]...[/svg][/summary]
  [p]Orders ship within 2 business days.[/p]
[/details]

4. Re-run the focused scan. Expected output: 0 violations for summary-name.
5. Verify the widget still toggles with keyboard (Enter/Space on the summary) and that the announced name matches the visible text.
6. Look for the pattern in your icon set: summaries containing only [svg] or [img]. A quick scan of FAQ, accordion, and disclosure components finds them:

rg -l 'summary' src/components/ | head -20

7. When the disclosure really has no good short text (rare), reconsider the widget. A details/summary with an unnameable summary is usually a sign the content should not be collapsed, or should be a different pattern like tabs with labeled tab buttons.

When to use

• Axe flags summary-name on a details/summary disclosure.
• An FAQ accordion built with native details/summary reads as unnamed buttons.
• A design system ships an icon-only disclosure and every instance fails.

When not to use

• The accordion is a custom button + div widget (fix with button-name and aria-expanded).
• The details element is intentionally summary-less progressive enhancement (add a summary; a details without one is a bug).
• The summary text exists but is vague ('click here') (rewrite the text; that is a content fix).

Why it happens

Native details/summary is the most accessible accordion available, but the summary is the button's accessible name. An icon-only summary leaves the widget operable yet anonymous: keyboard users can toggle it but never know what it reveals. The fix is content, not code, which is why agents should surface it to the content owner rather than patching around it.

The details/summary elements are among the most accessible native widgets: free keyboard handling, free expanded/collapsed announcements. Teams adopt them for that robustness, then break the one thing they must provide themselves: the name. Icon-only design trends imported from mobile apps, where space is tight, are the usual driver. On desktop web there is almost always room for the text.

Edge cases

• A summary containing only an [img] with good alt text passes, because the alt text is discernible text. But visible text is still better.
• CSS-generated content (::before with text) does not count as discernible text for this rule.
• If the summary text is visually hidden but present in the DOM, the rule passes; still, prefer visible text for sighted users who also need the cue.
• Nested details elements each need their own named summary.
• A summary with text plus an icon is the ideal pattern. Mark the icon aria-hidden so it is not announced alongside the text.
• Do not use the details element for tooltips or hover cards; it is a disclosure widget and needs a meaningful name.
• Styling the default disclosure triangle away with list-style: none is fine; replacing it with a background image keeps the text as the name.
• Image inputs inside [form] elements with novalidate still fail the rule; client-side validation opt-outs do not waive the accessible-name requirement.
• When the same image button appears in a header search form on every page, fix the shared header partial once rather than patching page by page.
• Alt text on image inputs is announced as the button name, so keep it under about 100 characters; longer alt gets truncated by some screen readers.

Provenance

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

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

Thread query: axe-core summary-name error summary element needs discernible text

TL;DR: A [summary] that contains only an icon gives the disclosure widget no accessible name, so screen reader users hear 'button collapsed' with no hint what it discloses. Put real text inside the summary, for example [summary]Shipping details[/summary], and keep the icon decorative with aria-hidden. Re-run the focused axe rule to confirm.