Add audits in the Jupyter ecosystem

docs/_toc.yml

@@ -48,3 +48,9 @@ parts:
       - file: funding/index.md
       - file: funding/czi-grant-roadmap.md
       - file: funding/czi-grant-completed.md
+  # ------------------------------------------------------
+  # Accessibility audits and improvement strategies
+  - caption: Accessibility audits
+    chapters:
+      - file: audits/index.md
+      - glob: audits/*.md

docs/audits/index.md

@@ -0,0 +1,24 @@
+# Jupyter Accessibility Audits
+
+This is the compendium of accessibility audits in the Jupyter ecosystem. Each
+one of these identifies the current state of the interface regarding a given
+accessibility tool, area or topic as well as improvement strategies in order
+to fix shortcomings and/or failures on each of the topics.
+
+The aim of the findings is to determine the improvements needed for disabled
+users to avoid complicated strategies and workflows that may prevent them to
+use the software in its 100%.
+
+## Audits
+```{toctree}
+:maxdepth: 1
+
+zoom-audit
+keyboard-audit
+```
+
+## See also
+
+- [Notebook v7.0.0 for WCAG 2.1 audit](https://github.com/jupyter/notebook/issues/6800)
+- [Screen reader with keyboard shortcuts audit](https://github.com/jupyterlab/jupyterlab/issues/6573)
+- [Issues in JupyterLab v2.2.6 for WCAG 2.1 audit](https://github.com/jupyterlab/jupyterlab/issues/9399)

docs/audits/keyboard-audit.md

@@ -0,0 +1,77 @@
+# Notebook 7 Keyboard Navigation Audit
+
+## Background and Overview
+
+Keyboard navigation is a vital aspect of Web accessibility for many disabled users with motor and vision disabilities. The main objective of this functionality is to allow users to use Web interfaces by only using a keyboard.
+
+By default, there should be an alternative from a standard mouse for navigating Websites. WCAG standard states that all the content needs to be navigable without a specific keyboard timing. The recommendations from the W3C include using the `Tab` key for forward navigation and `Shift+Tab` for backward navigation. Other important and most common used keys include `Space`, `Enter` and the arrow keys.
+
+On the eve of the pre-release of Notebook 7 in the Jupyter ecosystem a keyboard navigation audit event was performed. The following document states the methodology, results and recommendations found in the audit.
+
+## Methodology
+
+The notebook interface has a lot of interactions, widgets and functionalities. The main goal for this event was for participants to learn how to perform and describe foundational tests for keyboard navigation. Each participant chose a WCAG criteria to focus the audit.
+
+The UI was divided in 11 areas, menu bar, files panel, new/upload/refresh buttons, search bar, breadcrumbs, columns of the file browser, file browser, running panel, file editor, notebook toolbar and the notebook cells. The participants where surveyed regarding the keyboard navigation in the following categories: `content order`, `areas to navigate`, `keyboard/tab traps`, `skip links`, `focus`, `mixed input` and `keyboard shortcuts`.
+
+Each of the areas was tested by the participants searching for [keyboard tab traps](https://www.w3.org/TR/WCAG22/#no-keyboard-trap) and [skip links](https://www.w3.org/TR/WCAG22/#bypass-blocks). The methodology used was to start from the beginning of the area and start using the `Tab` key until the end of the area. Then, record the behavior and flag any blockers.
+
+## Findings
+
+The major findings are listed below,
+
+### Content order
+
+In the file browser
+
+- The full order of the content isn't clear because of limited visible focus styling.
+- There are unknown focus areas where the user needs to use the tab key multiple times in a row to continue to the next section without visual feedback where they are. We're not sure if this will be solved by visible focus styling or if they content order is jumping somewhere we don't expect.
+- Files tabs, Running tabs, and File sorting UI (like Name and Last Modified ordering) are skipped over with keyboard navigation.
+
+### Areas to navigate
+
+- Navigating through the menu bar with a keyboard "leaves incorrect lm-mod-active class on last active item"
+- Notebook toolbar excess items cannot be navigated to with a keyboard
+- Leaving the active file editor with a keyboard must be done with the esc key. This isn't standard keyboard navigation behavior.
+- JupyterLab cannot switch between split areas Keyboard shortcuts for navigating panes
+
+### Keyboard/tab traps
+
+- Terminal is a major tab trap. Could only escape by using the command palette shortcut.
+- Notebook editor (like other file editors) and consoles must be exited with the esc key. This isn't standard keyboard navigation behavior.
+- Could not open new terminal with the Running tab using the keyboard. Only expands and collapses.
+- "If I hide the header (command palette, untoggle "Show Header"), I still tab through the hidden element?"
+- "Please check focus reset after Command Palette -> Find... -> Escape to exit out. I would expect focus to go back where I was prior to the command palette (e.g. in a specific cell editor)."
+
+### Skip links
+
+- There does not appear to be a skip link in either the file tree page or the notebook page. There should be skip link(s) to skip over menu bar(s), straight to main page content
+
+### Focus
+
+- There is visible focus in some areas, but it is not applied throughout. Some areas have blue outlines.
+- Sometimes a user is able to see focus because of an area's hover state, but these areas need a true focus state additionally.
+- "The behavior of hovering/colors/interactions is not the same doing it by the keyboard than doing it with the mouse." Meaning different interactive area states are not always triggered by keyboard focus?
+
+### Mixed input
+
+In the file browser,
+
+- "Could not select/unselect file using only keyboard. Multi-select and unselect is also busted"
+
+### Keyboard shortcuts
+
+- Shortcuts cannot be turned off
+- Shortcuts cannot be remapped/configured (via the UI)
+
+## Overall recommendations
+
+Each item in the findings can be described as it's own issue. Given that the goal for keyboard navigation is to remove all the keyboard traps and create skip links to ease the amount of keys needed to be pressed to move from one block to another.
+
+## References
+
+If you are interested in reading the full audit and be part of the discussions please refer to the following issues and pull requests,
+
+- [Notebook 7 keyboard navigation review: October 12](https://github.com/isabela-pf/a11y-events/pull/10/files)
+- [Notebook 7 prerelease keyboard navigation review](https://github.com/jupyter/notebook/issues/6595)
+- [Keyboard navigation workshops](https://github.com/isabela-pf/a11y-events/tree/main/workshop-resources/keyboard-navigation)

docs/audits/zoom-audit.md

@@ -0,0 +1,68 @@
+# Zoom Audit
+
+## Background and Overview
+
+Zoom is one of the mechanisms used by vision impaired users to navigate through Web interfaces and programs. This is a builtin functionality in any Web browser that can offer from 25% up to 400% zoom by resizing the contents of a webpage. Given the importance of this tool in the accessibility context, WCAG has a complete set of guidelines regarding the expected behavior of webpages when zoom is used.
+
+The main premise of the WCAG standard is that websites need to preserve all the information regardless of the zoom level and the size of the user’s screen. The reality is that the way zoom is handled in webpages varies, and a lot of them will often break when more than 200% zoom is used.
+
+Given the importance of this tool for disabled users it was important to recognize the state of JupyterLab when used in higher zoom values. The following document will state the methodology, results and recommendations found in the audit.
+
+## Methodology
+
+Given that the JupyterLab interface is so complex, it was impossible to do one general audit of the whole interface. Instead, it was decided to break down the UI in the main 7 areas, left sidebar, right sidebar, main content area, menu bar, context menu, settings and the status bar.
+
+Each of the areas was tested in 0%, 200% and 400% zoom. In all the scenarios, JupyterLab default settings were used.
+
+## Findings
+
+All of the tests were made using JupyterLab 3.4.3 in a 16-inch Macbook Pro in Google Chrome.
+
+The major findings are listed below,
+
+The definition of vertical padding and height are working as they are and they have sense to leave them in px in the sidebars items.
+We need to define a new UX for when the left sidebar is taking too much space compared to the main area. My suggestion will be to compress the left pane to give priority to the main content area.
+Files in the main content area are wrapping lines instead of having a horizontal scrollbar, which allows to see all the code without any action.
+If zoom is activated some filenames are not visible in the tabs, but hovering over them will give the complete information of the file
+Opening a lot of files in zoom may cause to just seeing the icon and not being able to even close it
+The notebook's toolbar is responsive and all the options are visible and usable
+Cell options layout breaks with 400% zoom
+Python logo in the launcher pixelates with zoom
+Dialogs occupy the complete interface with 400% zoom
+The menu items start getting lost as zoom increases
+The dropdown menus are not visible or usable with 400% zoom
+Modifying to responsive layouts break the menubar and its usability
+Automatically we have a scrollbar to navigate through the options in context menus if not visible at first
+The size of context menus is fixed in px which occupy a lot of space in small screens or high zoom
+Settings is not usable in small screens or with zoom, the options are chopped and not readable
+Settings left menu area doesn't resize
+Settings is using the same gear icon for multiple entries
+The Status bar is responsive for even mobile screen sizes
+
+## Overall recommendations
+
+The following list of tasks was proposed,
+
+- Define a new UX for the left sidebar when they are taking too much space compared to the main area
+- Define a new UX for the right sidebar when they are taking too much space compared to the main area
+- Define a new UX/UI for the tabs in the main content area, especially the cases where too many of them are opened.
+- Make the cell options layout be responsive (it may include removing some options or adding ellipsis when the space is small)
+- Change the python logo to a new image that has better resolution
+- Dialogs sizes need to be checked for high zoom or small screens
+- Add a hamburger menu in the main menu bar when the space is smaller to avoid losing items.
+- Dropdown menus from the main menu bar should open to the left/right depending on the space in the screen
+- Check and define the UI/UX for context menus in small screens and/or high zoom
+- Define a new UX for the Settings pane to handle small screens and/or high zoom
+
+## References
+
+If you are interested in reading the full audit, see the actual screenshots of the interface and be part of the discussions please refer to the following issues,
+
+- [Summary of the zoom audit](https://github.com/Quansight-Labs/jupyterlab-accessible-themes/issues/34#issuecomment-1210168155)
+- [Left sidebar audit](https://github.com/Quansight-Labs/jupyterlab-accessible-themes/issues/3)
+- [Right sidebar audit](https://github.com/Quansight-Labs/jupyterlab-accessible-themes/issues/6)
+- [Main content area audit](https://github.com/Quansight-Labs/jupyterlab-accessible-themes/issues/9)
+- [Menu bar audit](https://github.com/Quansight-Labs/jupyterlab-accessible-themes/issues/11)
+- [Context menu audit](https://github.com/Quansight-Labs/jupyterlab-accessible-themes/issues/14)
+- [Settings audit](https://github.com/Quansight-Labs/jupyterlab-accessible-themes/issues/16)
+- [Status bar](https://github.com/Quansight-Labs/jupyterlab-accessible-themes/issues/18)