Accessibility: "Toggle Table of Content" hamburger menu is not keyboard focusable

[ShamrockLee]

Problem

Keyboard-only users or users with disabilities may navigate a web page by pressing the key Tab to navigate to the next focus or the keys ShiftTab to navigate to the previous one. When an item gains focus, a rectangular square, called the "focus indicator," will surround it. For screen-reader users, the screen reader is at "focus mode" when keyboard-navigating the web page, which is contrary to "browse mode" when reading textual content inside a web page. Users proceed with the desired focus by pressing the key Enter (announced as "Return" by the Orca screen reader), which is functionally equivalent to a mouse click.

At the top-left corner of the rendered Nix Reference Manual comes three buttons: "Toggle Table of Content" (hamburger menu icon), "Change theme" (pen icon), and "Toggle Searchbar" (magnifier icon). Such buttons should also be the first three focusable item at the page, as the Manual currently doesn't offer the "skip to the main content" hidden focusable item.

Since the button "Toggle Table of Content" should be the first focusable item, it should be focused when pressing the key Tab right after the page finishes loading.

When keyboard-navigating the rendered Nix Reference Manual page with the Mozilla Firefox browser, the button "Navigation Table of Content" is not focusable. The first key press Tab after the page finishes loading turns out ineffective. The second key press Tab focuses the button "Change theme," and the screen reader announces "Change theme collapsed button opens menu." When navigating to the previous item from "Change theme," the visual focus indicator is lost, and the screen reader announces "Browse mode." When navigating again to the previous item, the focus goes to the toolbar of the browser, and the screen reader starts to announce them.

On Chromium, the first key press Tab after the page load brings the focus to the button "Change theme." When navigating onto the previous focus, the focus indicator is also lost. However, the screen reader will then announce "Navigation Tabel of Content," and starts announcing the whole Table of Content. When pressing the keyDown and the keyUp, the screen reader announces the items inside Table of Content as if the user is navigating them, and the visual hint of links being focused appears at the bottom-left of the page. When pressing the key Enter, the browser brings the user to the page of the corresponding section.

Steps

I found the bug in the Nix Reference Manual version 2.26 rendered using mdBook, and filed an issue there (NixOS/nix#12657) before realizing that the issue should be filed to the mdBook project. It is reproducible with the mdBook Documentation. Since it takes a lot of effort to regenerate the reproduction steps and screen recording videos, I'll reuse the reproduction steps targeting the Nix manual below.

Prerequisites

1. Prepare the browsers Mozilla Firefox and the Chromium.
2. (Optional) Prepare and run the Orca screen reader (nix run github:NixOS/nixpkgs/nixos-unstable#orca) (Linux-only). Toggle it off or on with the keys AltSupers.
   Windows and MacOS users enjoy more mature screen reader options like NVDA and VoiceOver.

The Mozilla Firefox reproducer

1. Visit the following URL with the browser Mozilla Firefox: https://nix.dev/manual/nix/2.26/
2. Here the screen reader announced "Finish loading Nix Reference Manual."
3. Press the key Tab. The screen reader will announce "Tab."
4. See no focus indicator and hear no further announcement.
5. See the top-left pen icon gets focused and hear the screen reader announces "Change theme collapsed button opens menu. Focus mode."
6. Press the keys ShiftTab.
7. See the focus indicator disappears, and the screen reader announces "browse mode."
8. Press again the keys ShiftTab.
9. See the focus indicator goes to the browser toolbar, on the "Save to Pocket" button. The screen reader should announce accordingly.
10. Press the key Tab. The screen reader will announce "Tab."
11. See no focus indicator and hear no further announcement.

The Chromium reproducer

1. Visit the following URL with the browser Chromium: https://nix.dev/manual/nix/2.26/
2. Here the screen reader announced "Finish loading Nix Reference Manual."
3. Press the key Tab.
4. See the focus indicator goes to the pen icon, and hear the screen reader announces "Tab" and "Change theme collapsed button opens menu."
5. Press the keys ShiftTab.
6. See the focus indicator disappears, but hear the screen reader announces "Navigation Table of Content. Introduction ..."
7. Press again the keys ShiftTab.
8. See the keyboard indicator goes up to the bookmark (star) icon at the right of the address bar, and hear the screen reader announces "Panel. Bookmark this tab button."
9. Press the key Tab.
10. See the focus indicator disappears, and hear the screen reader announces "Navigation Table of Content. Introduction ..."
11. Press again the key Tab.
12. See the focus indicator goes to the pen icon, and hear the screen reader announces "Leaving navigation. Change theme collapsed button opens menu."
13. Press the keys ShiftTab.
14. See the focus indicator disappears, but hear the screen reader announces "Navigation Table of Content. Introduction ..."
15. Press the key Down.
16. See nothing happen to the top-left corner, but a hint of link https://nix.dev/manual/nix/2.26/quick-start shows up at the down-left corner. Hear the screen reader announces "Quick Start link." ("Quick Start" is the second page, the page next to the first page "Introduction.")
17. Press the key Enter. The screen reader will announce "Return."
18. See the "Quick Start" page loaded, and hear the screen reader announces the content of the page.
19. Press the key Tab.
20. Hear the screen reader announces "Navigation Table of Content ..."
21. Press again the key Tab.
22. See the pen icon gets focused and hear the screen reader announces "Change theme ..."
23. Press the keys ShiftTab.
24. See the focus indicator disappears, and the screen reader announces "Navigation Table of Content ..."
25. Press the key Down.
26. See a hint of link https://nix.dev/manual/nix/2.26/quick-start shows up at the down-left corner. Hear the screen reader announces "Quick Start link."
27. Press the key Up.
28. See a hint of link https://nix.dev/manual/nix/2.26/introduction shows up at the down-left corner. Hear the screen reader announces "Introduction link."
29. Press the key Enter.
30. See the "Introduction" page loaded, and hear the screen reader announces the content of the page.

Possible Solution(s)

As I'm new to this project and have yet inspect the code, I'll describe the expected behaviors:

• The button "Toggle Table of Content" (the hamburger menu) should be focused before the button "Change theme" (the pen).
• When proceed with the key Enter, the menu should visually show up.

Update:

I saw the hamburger menu button is constructed with the <label> tag, while both the edit button and the search button are constructed with the <button> tag. From accessibility perspective, semantic tags are preferred over ARIA roles and attributes, so using <label> would be better than <label role=button>.

Fiddling the HTML with the browsers' Inspector, I found that changing the tag from <label> to <button> makes it focusable, but its functionality was lost. Keeping the tag <label> but add the attribute role="button" doesn't help. Adding the attribute tabindex="0" makes it focusable, but it doesn't respond to the key Enter the way it was clicked (the sidebar didn't expand or collapse).

As mentioned above, the ideal solution would be constructing it with the <button> and fixing the functionality.

Notes

Below are two screen-recording videos with audio from the screen reader showing the issues. They don't precisely follow the reproduction steps, but should be able to demonstrate the issues.

To hear the audio while playing the video, navigate to the "Unmute" button of the video, press the key Enter, navigate back to the "Play" button, and press the key Enter.

Mozilla Firefox demo video

nix_manual_toc_not_focusable_firefox_Kooha-2025-03-15-08-24-36.webm

Chromium demo video

nix_manual_toc_not_focusable_chromium_Kooha-2025-03-14-22-07-43.webm

Version

0.4.40

[ShamrockLee]

I saw the hamburger menu button is constructed with the <label> tag, while both the edit button and the search button are constructed with the <button> tag. From accessibility perspective, semantic tags are preferred over ARIA roles and attributes, so using <label> would be better than <label role=button>.

Fiddling the HTML with the browsers' Inspector, I found that changing the tag from <label> to <button> makes it focusable, but its functionality was lost. Keeping the tag <label> but add the attribute role="button" doesn't help. Adding the attribute tabindex="0" makes it focusable, but it doesn't respond to the key Enter the way it was clicked (the sidebar didn't expand or collapse).

As mentioned above, the ideal solution would be constructing it with the <button> and fixing the functionality.