Documentation keyboard navigation review

[isabela-pf]

To practice some of our manual accessibility testing skills, we teamed up to run some manual keyboard navigation tests on the Jupyter Accessibility documentation.

Many thanks to @gabalafou and @trallard for co-authoring this review with me!

Please note that this format of reporting the full review via issue is new and possibly a little messy. Please let me know if there's anything that would make it easier to understand or manage. Thanks!

Takeaways

Based on the full review, I'm going to briefly issues that stood out.

Content order

In the file browser

• Areas do not go fully left to right in a left-to-right language. Right now they jump from far left navigation to far right navigation and back to the middle for main content.
• There is no way to access the left sidebar footer (versions).
• There is no way to access the hamburger menu (collapse sidebar)

Skip links

• There does not appear to be a skip link to redirect the reader from the top of the page to the main content area.

Interactive areas

• GitHub icon dropdown, Download icon dropdown, Toggle navigation button ("hamburger" / triple line), Read the Docs version switcher, and Collapse/expand button in left nav cannot be navigated to and/or used with the keyboard alone. See full review below for more details per interaction.
• The search field has a clear "X" button that appears when you start typing characters in the search field. That X button is not reachable via keyboard; however, it is unclear if it's really needed.

Mixed input

• Page drop down menus (ie. GitHub and Download icons) do not respond to keyboard controls. The menus can be tabbed to, but they cannot be activated to open the drop down with the keyboard. They can be activated and navigated with a mouse. Even if the menus are opened with a mouse, the user cannot switch to navigate them with a keyboard.
• "I was also surprised because the left and right arrow keys—typically used for fine-grain navigation through things like drop down menu items—immediately move me to the next page in the documentation." The fact that it overrides keyboard navigation is a problem.

Full review

This is the full list of prompts and responses from our review session.

Content order

When accessed via keyboard, the content order is logical. (WCAG 2.2 Focus order)

1. From the top of the page, press the Tab key repeatedly until reviewer reaches the end of content.
2. Reviewers will know it is the end because if they press Tab once more their keyboard focus will return to the browser.
3. If the reviewer cannot make it to the end of content, please take note of where the focus gets stuck.

Does the content order follow reviewer expectations based on reading the content?
Result:

Kind of - the order is as follows:

1. Left sidebar: logo -> search bar -> sidebar items (top to down)
2. Top left menu: icons left to right
3. Table of contents: TOC items top to bottom
4. Main content: links as they appear top to bottom -> Next navigation button

I would expect Areas to go left to right in a left-to-right language
At no given point I accessed the footer

Does the content order make sense for interacting with the content?
Result:

I suppose it does - even if I find it confusing with the jumps left -> right -> center

Are any major content areas missed when navigating via keyboard?
Result:

There is no way to access the left sidebar footer (versions) or the hamburger menu (collapse sidebar)

Are any interactive content areas missed when navigating via keyboard?
Result:

• There is no way to access the dropdown menus in the left-sidebar
• Cannot access the hamburger menu (which should be a collapse icon instead)

Other notes or recommendations:

Skip links

When using keyboard navigation, there is a link to switch keyboard focus directly to the tool's main content and skip header navigation or repeated content. (WCAG 2.2 Bypass Blocks)

1. From the top of the page, press the Tab key. If you have already been interacting with the page, reviewer may need to reload page and then press Tab.
2. Once focus is on the skip link, press Space or Enter to activate it.

Is there a skip link?
Result:
No there is not

Is the skip link prompt visible?
Result:

N/A

What does the skip link prompt skip?
Result:

N/A

Where does the skip link prompt move user focus to?
Result:

N/A

Does the skip link behavior meet reviewer expectations?
Result:

I hoped there would be a skip link

Other notes or recommendations:

Would suggest adding a skip link that would redirect the reader to the main content area

Interactive Areas

All buttons, links, form fields, or similar interactive areas can be both accessed and activated using only the keyboard. (WCAG 2.2 Keyboard)

1. Navigate via the Tab key to interactive areas.
2. Activate interactive areas using the Enter or Spacebar key.

Interactive area	Able to navigate to the area (yes/no/not applicable)	Able to input information (yes/no/not applicable)	Able to activate the area (yes/no/not applicable)
Fullscreen mode button	yes	n/a	yes (pressing Enter or Space key turns on/off fullscreen mode)
GitHub icon dropdown	no	n/a	no (but if I open the dropdown with a mouse click, then I can activate the dropdown options with keyboard)
Download icon dropdown	no	n/a	no (but if I open the dropdown with a mouse click, then I can activate the dropdown options with keyboard)
Toggle navigation button ("hamburger" / triple line)	no	no	no
Read the Docs version switcher	no	no	no
Links in left side nav (Jupyter accessibility logo link to Jupyter Book link)	yes	n/a	yes (pressing Enter key opens the link)
Links in main area (from "Classic Jupyter Notebook" to "Next Jupyter Accessibility Statement")	yes	n/a	yes (pressing Enter key opens the link)
The two links in the right side nav	yes	n/a	yes (ditto)
Search this book...	yes	yes	yes (pressing Enter after typing search term performs a search on the docs)
Collapse/expand button in left nav	no	n/a	no

Other notes by area:

• Left side nav:
  • While the collapse/expand buttons in the left side nav cannot be accessed (and therefore can be activated using only the keyboard), the link adjacent to each expand button can be opened using the keyboard, which as the effect (after a round trip to the server) of opening/expanding that section in the side nav. But the expand/collapse button should be usable with only a keyboard.
  • The search field has an clear "X" button that appears when you start typing characters in the search field. That X button is not reachable via keyboard; however, I'm not sure it's really needed... at least if you know that you can type ctrl+a followed by the delete key in order to quickly delete everything you typed into the the field.

Mixed input

It is possible to complete tasks while switching between input mechanisms, for example using a keyboard and mouse and touch screen. (WCAG 2.2 Concurrent input mechanisms)

1. Locate an interactive area.
2. Complete the interaction using keyboard controls.
3. Complete the interaction using the mouse.
4. Complete the interaction using touch controls.
5. If the task has multiple steps, the reviewer can try using a different interaction for each step.
6. Repeat as needed across interactive areas.

Page drop down menus (ie. GitHub and Download icons)

Does the task have multiple steps? If yes, please list them.
Result: Tab to focus the page menu (GitHub and Download icons), reach focus for a menu with a drop down available, press space or enter, drop down menu appears, navigate drop down menu, select drop down item.

Can the task be completed with only keyboard controls?
Result: No. The menus can be tabbed to, but they cannot be activated to open the drop down with the keyboard. They can be activated and navigated with a mouse. Even if the menus are opened with a mouse, the user cannot switch to navigate them with a keyboard.

I was also surprised because the left and right arrow keys—typically used for fine-grain navigation through things like drop down menu items—immediately move me to the next page in the documentation. I am guessing this is because Jupyter Book is modeled like a book where turning pages to continue reading is high priority. The fact that it overrides keyboard navigation, concurrent with other navigation methods or not, is a problem.

Can the task be completed with only mouse controls?
Result: Yes.

Can the task be completed with only touch screen controls?
Result: n/a

[tonyfast]

• mark skip link as completed by Fix skiplink and add placeholder for additional skiplinks jupyterlab/jupyterlab#14597 which leaves extra space for me skip links

[trallard]

I am marking as not completed @tonyfast as this refers to JupyterBook (our accessibility docs engine) not JupyterLab

[tonyfast]

thanks. makes sense. i had this issue open next to another a lab issue and confused them.