The light/dark toggle button does not communicate its state

[gabalafou]

It communicates it visually but not through the accessibility tree

[trallard]

Not sure if we should also address https://github.com/pydata/pydata-sphinx-theme/discussions/1491

[Carreau]

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 ?

[gabalafou]

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.

[Carreau]

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

[Carreau]

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 ?

[Carreau]

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 ?

[Carreau]

be an option dropdown

And I suppose I mean a select

[Carreau]

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.

[Carreau]

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.

[gabalafou]

Related:

• https://github.com/pydata/pydata-sphinx-theme/discussions/1491#discussioncomment-9621593

[gabalafou]

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.

[gabalafou]

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.