axe-core summary-name error summary element needs discernible text

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