Add ARIA attributes to tab buttons

[lukavdplas]

This is about the buttons to toggle the pages in the live docs / status panel - which I also discussed in #3273. I decided to make this one a separate issue because you can tackle them independently.

From what I can see, these controls are <button> elements without any further semantics encoded (through a role or ARIA attributes). That indicates that you can push them, but there is no encoding that these buttons have an active/inactive status, or that they control a different part of the page. You can see these things visually, but it's not clear for assistive technologies.

Solution: the way these interactions are programmed matches the disclosure pattern. Set the aria-expanded and aria-controls attributes based on the state of the widget and this is good to go!

[fonsp]

Awesome, thanks!!

And what do you think about the Live Docs search interaction? It searches as you type in the search box, but also your cursor moves through the document or types content:

Schermopname.2025-06-22.om.22.41.43.mov

Most important is when you type in the Live Docs search bar, how does the result become accessible? It seems more difficult without an explicit "Search" action. Maybe with aria-live="polite"? (and aria-live="off" when docs appear from cursor movement in the document).

[lukavdplas]

Good question, I'm not sure to be honest, but I think just adding aria-live=polite would create a lot of annoying updates.

This blog post gives a good explanation of the challenges: considering dynamic search results and content.

I agree with that post that different technologies benefit from different interaction patterns; these constant updates work well in a visual layout, but not for a screen reader.

Based on that post, I think you could do this:

• Add an accessible description to the search field that makes it clear that results are updated as you type.
• Include a live region with a short status message that will announce whether there is a result. Don't make the whole panel a live region.
• When updates are triggered from outside of the panel, don't announce them. (Perhaps you could add a keyboard shortcut to open + jump to the documentation for a symbol?)

Re. this live region: the example in the blog post seems to assume you do substring search, and so there is no point in typing once you find no results. So the "no results" announcement is meant to interrupt the user. That's not the situation here, though.

I would add a status message that will announce whether there is a result (e.g. "documentation: sqrt" or "no documentation found"). This does not 100% overlap with the text you have on screen, but perhaps you could make it visually hidden? Since it's really just for the benefit of users who don't see visual updates.

I can think of two solutions:

1. Update the status when the user hits Enter in the search bar, but not as they type. This does not mimic what is on the screen, but the behaviour seems quite natural to me.
2. Add aria-live=polite and, while the user is typing, add aria-busy=true. The latter tells the browser to hold off on announcing updates. It's meant to indicate that the application is busy (not the user), but I think it works in this case.