Not sure if we should also address pydata/pydata-sphinx-theme#1491

It communicates it visually but not through the accessibility tree

I'm not sure I completely understand, can you expand on what should be done here, or how that should affect the accessibility tree ?

We went over this is in the team sync yesterday.

Reiterating here, for reference, the issue is that when you cycle through the three states (light, dark, auto) of the light/dark button (which is in the top right of the PST docs), the current state of the button is reflected visually, but nowhere is this visual state communicated in a textual way in the DOM. For assistive tech, it's important that the current state of the button is reflected in the accessibility tree.

Thanks, I managed to see the accessibility tree in my dev console and will look into modifying it when the button switches.

I'm reading the various aria things, and I'm wondering if the theme switch button should be an option dropdown with 3 options (auto, light, & dark).

It seem like a 3 state button is a bit of a hack (and maybe less discoverable than an option?)

I think the UI could be almost identical, but making it an option would maybe solve most of our Accessibility concerns.

Thoughts ?

Also, I'm not sure we can do anything abut that, but the button tooltip on hover/focus seem to be added/removed by js (via bootstrap?), which removes and add a new aria-describedby attribute on every hover.

Should this aria-describedby (and tooltip element) always be present, but just visually hidden to be properly supported by screen readers ?

be an option dropdown

And I suppose I mean a select

Speaking of, this is what MDN is doing, I'm trying to see if we can set aria-description anyway on the the body element, but that does not seem to work. There is no way to directly modify the accessibility tree.

Ok, so select won't work because we can't style it with icons. So we have a to do a custom dropdown which does not fix our accessibility issue. aria-desciption does no show up in the accessibility tree, and aria-label is already set to "light/dark" translatable string.

I guess we can change the aria label to a dynamic string like : "Switch theme. Current theme : %s". though it's unclear how to translate a dynamic js string. I also realize that "auto" is unclear. MDN uses "Os default" as a description.

Related:

• Theme switcher: can I only 'light' and 'dark' options? pydata/pydata-sphinx-theme#1491 (comment)

Responding to some of your points:

• I agree that the tri-state button is an unconventional pattern. A dropdown is probably preferred (that was the consensus in the discussion I linked in my previous comment). It's more work, though, and I think we could fix the specific accessibility issue here with much less effort. But I will leave it up to your judgment, whether to re-implement the theme switcher now or later.
• As for the Bootstrap tooltips/popovers, I would check the docs to see if they have some option that might address our use case here, otherwise I would just leave them alone as a completely other thing.
• As for translatable strings in JavaScript, it might be worth working on solving this problem once and for all, especially if it turns out their is an elegant, low-maintenance way to do so. I suspect it will come up again. However, I don't think you need it for this issue. We use Font Awesome icons in the theme-switcher.html Jinja template. I suspect that the Font Awesome accessibility docs provide a pathway to adding translatable strings in the Jinja template that then also show up in the accessibility tree.

Some thoughts from today's call:

• Eventually we should probably get rid of the light/dark/auto mode toggle button and push that functionality back to the system (browser, OS).
• Perhaps we imitate the search button and open a modal dialog with a deprecation notice and three buttons.
• The deprecation notice could link the user to info on how to set light/dark mode on their system.