USWDS - Bug: Replace aria-describedby with aria-labelledby on the tooltip trigger within the Tooltip component #6485

Activity

1. obliviga

   added

   Needs: ConfirmationReported behavior needs validation. Remove after recording reproduction or investigation results.Reported behavior needs validation. Remove after recording reproduction or investigation results.

   on May 28, 2025
2. daresTheDevil commented on Mar 29, 2026

   

   daresTheDevil

   on Mar 29, 2026

   Contributor

   More actions

   Dug into this one.

   The tooltip JS always sets aria-describedby on the trigger (line 330 of index.js). For buttons with visible text that's fine, the tooltip is supplementary. But for icon-only buttons with no text and no aria-label...aria-describedby doesn't give the
   button a name...it gives it a description.

   The ACCNAME spec says aria-describedby isn't part of the name computation at all. So the button is unlabeled, fails SC 4.1.2, and trips the Axe button-name rule...which is exactly what the screenshot in the issue shows.

   The fix depends on what the team wants the component to do:

   • JS could detect that the trigger has no accessible name and switch to aria-labelledby pointing at the tooltip body.
     • Handles both cases automatically. But the APG tooltip pattern only specifies aria-describedby right now
     • open W3C issue about this exact gap that's still unresolved
   • JS stays as-is
     • docs say icon-only tooltip buttons need aria-label (or visible text)
     • this seems to be the recommended approach by most a11y folks? Pls correct me if I'm wrong
     • simpler, but folks who skip the docs get Axe failures
   • JS could add aria-label from the title content when it detects no existing name
     • my issue with this is that aria-describedby pointing at the tooltip causes double announcement (screen reader reads the label, then the identical description)
     • TPGi specifically calls this out

   FWIW, WAI-ARIA 1.3 and WCAG 3.0 don't change the name vs. description architecture here. I'd lean toward option 2, but I don't know the team's appetite for breaking-change-adjacent fixes.

   @obliviga @heymatthenry what direction do y'all recommend?
3. olsonap

   added a commit that references this issue on May 20, 2026

   Issue captured in USWDS uswds#6485

   b1ba1fc
4. chandracarney

   added

   Package: ButtonWork affecting Button. Apply only when this area helps route or find the issue.Work affecting Button. Apply only when this area helps route or find the issue.

   Package: TooltipWork affecting Tooltip. Apply only when this area helps route or find the issue.Work affecting Tooltip. Apply only when this area helps route or find the issue.

   on Aug 20, 2026
5. ryparker

   added the

   Bug

   issue type on Sep 16, 2026
6. ryparker

   added

   Context: JavaScriptIssue is in JavaScriptIssue is in JavaScript

   Affects: Accessibility 🟡Affects access for disabled users or assistive tech. Record the barrier; not a severity score.Affects access for disabled users or assistive tech. Record the barrier; not a severity score.

   Needs: DiscussionAn unresolved decision blocks progress. Name the decision; remove this label when decided.An unresolved decision blocks progress. Name the decision; remove this label when decided.

   on Sep 17, 2026
7. ryparker commented on Sep 17, 2026

   

   ryparker

   on Sep 17, 2026

   Last edited by ryparker

   Member

   More actions

   I checked this on September 17, 2026, at commit eaef39533a0a0f78976d6888edf8ae56fe9334d6.

   I reproduced the problem with an icon-only tooltip button using title="Settings" and an SVG marked aria-hidden. Initialization removes title and adds aria-describedby, leaving the button without an accessible name. Both Chromium's accessibility tree and axe's button-name rule identify the unnamed button.

   This confirms the icon-only case. The fix needs to provide a fallback name while preserving names and descriptions that are already present; it shouldn't replace every trigger's name with the tooltip text.

   Reproduction details and limitations
8. ryparker

   removed

   Needs: ConfirmationReported behavior needs validation. Remove after recording reproduction or investigation results.Reported behavior needs validation. Remove after recording reproduction or investigation results.

   on Sep 17, 2026