USWDS - Enhancement: Tooltip needs to announce "tooltip" for context

[amycole501]

Describe the bug

The tooltip component the word "tooltip" isn't announced as a label.

The element that serves as the tooltip container should have a role tooltip.

Screen reader users are not able to discern the purpose of elements with role="tooltip" that do not have an accessible name. Aria tooltip elements must have discernible text that clearly describes the destination, purpose, function, or action for screen reader users.

From w3c: Authors SHOULD ensure that elements with the role tooltip are referenced through the use of aria-describedby before or at the time the tooltip is displayed.

Steps to reproduce the bug

1. Go to the tooltip component page
2. Listen to the example buttons using assistive technology (in my case I used JAWS and NVDA)
3. You hear the tooltip wording announced ("show on top button; top") but it's not declaring it as a tooltip. Currently it sounds like the button is repeating itself.

Expected Behavior

Listen to the tooltip example on Deque's website. You can hear "tooltip colon" then the tooltip wording.

Ideally on our component examples you would hear "Tooltip colon: Top. Show on top".

Screenshots

No response

System setup

PC, Chrome, JAWS, NVDA

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct.
• I checked the current issues for duplicate bug reports.

[amyleadem]

@amycole501 and @alex-hull, I started investigating this issue and had a few questions and notes. The tl;dr is that I am trying to figure out if this is a true failure and bug, or if it should instead be classified as a possible enhancement.

I started diving into a solution for this and I found that our tooltip component does have a tooltip role and that it is correctly associated with its related element via aria-describedby (See screenshot below for the rendered code). I also confirmed that the USWDS tooltip does not include the word "Tooltip" in its readout.

I looked at the Deque example referenced in this issue. This example does read out "Tooltip" before the tooltip content. I dug into their code and it looks like they are adding the "Tooltip" text via an enhancement with JavaScript. They do this by adding an empty span that has an aria-label of "Tooltip:" before the tooltip content. (I added a screenshot of the code below in case it is helpful)

I also looked at what seems to be (as far as I can tell) the WIP for the W3C tooltip pattern demo. I found it in ⁠this comment in the W3C repo, which was listed as the related issue on the ARIA Authoring Practices Guide (APG) Tooltip pattern page. Granted, this demo is a work in progress, but seems to be considered accessible based on the comments in the thread. This demo does not announce that it is a tooltip (at least not in VoiceOver). I also don't see that they are adding a similar enhancement like Deque.

Since the Deque example is an additional enhancement (seemingly) outside of ARIA standards, I am curious if this should be considered a failure/bug OR if it should be considered an enhancement that we could add to improve the screen reader experience (but is not necessary to be considered complaint). Curious what you think!

Screenshots

USWDS Tooltip (v3.8.1):

Note that it already has an aria-describedby attribute and a tooltip role

Deque example:

Note that this is additional code inserted in the component, added via JavaScript

[mejiaj]

Nice find, @amyleadem.

Enhancement seems correct if the correct role is currently included & the description/trigger are linked to each other.

[amycole501]

Great information, Amy! I agree then, that this can be considered an enhancement. Albeit, the tooltip to me still sounded really confusing without the enhancement. The Deque example was much clearer. This would be a good example of something to test in our next round of usability research for conformance which is above and beyond compliance.

[amyleadem]

@amycole501 Great, I'll mark this as an enhancement instead of a bug. How does this impact the accessibility checklist for tooltip? Do we rewrite or remove the related tests?

[alex-hull]

I think we consider marking this as conditional? Since we're not marking it as fail, I also do not think it would fall into the passes with exceptions category. I think the gherkin could stay the same as well, since it is related to the intended action from the enhancement. @amycole501 @amyleadem

[amycole501]

I think conditional is correct; the accessible name of a tooltip can come from the content. So adding the ARIA properties to provide a tooltip with an accessible name is not recommended. https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role

[amyleadem]

@amycole501 @alex-hull
If we mark these as conditional with the tests as written, I worry that users will go looking for the word "tooltip" in their project readouts but won't find it.

If this is correctly coded according to the w3c standards (namely, aria-describedby), it just means that the tooltip content will be read by the screen reader when you focus on the tooltip trigger. Could the test for 4.1.2 and/or 1.31 just be re-written to be something like: "the screen reader announces the tooltip content"?

[amycole501]

Yes I think that would work.

[alex-hull]

So marking it as conditional and then simplifying the gherkin? I think that would work as well!