Accessibility Issues Needing Addressing for WCAG 2.1 compliance (As of Version 7.0.0a15) #6800

manfromjupyter · 2023-03-24T17:50:25Z

I know Jupyter Notebook v7 just announced huge accessibility improvements recently available in alpha but I wanted to throw my hat into the ring with remaining pieces before we celebrate fully that it's fully accessible. Lot of this is super low hanging fruit with potential huge impact.

Summary

Blind Users – minorly functional but with great annoyances. Grade C
Low Vision – almost completely supported, mostly minor annoyances. Grade A-
Color Blind – almost completely supported on light theme, Grade A-. Same A- on dark theme
Ambulatory - mostly usable, just a few blockers for supplementary actions. Grade B
Deaf/Hard of Hearing - completely supported. Grade A+
Cognitive - completely supported. Grade A+
Seizures - completely supported. Grade A+

Related to jupyterlab/jupyterlab#9399 but NotebookV7 obviously much better and what should be recommended to persons with disabilities and just needs a few small fixes to be fully supporting of Low Vision, Color Blind, and Ambulatory users.

Issues

Issues (Broken Down)

Language

Expectation: Language tags are specified on <html> element based on the language the content is being displayed as. If content is in English, needs to be <html lang="en">, etc. (WCAG Criteria 3.1.1 (A) and 3.1.2 (AA))
Observed:
- On all pages with my language set to English, lang="default" which reads my content in GERMAN (probably looking at the first 2 letters "de"). Need to have JS that powers this instead change to the proper lang codes.
- If importing over the Settings Editor to Notebookv7 ever, recommend adding dropdown menu for languages so user only selects from list of languages that are currently supported/installed so bilingual blind users can easily toggle without fear of messing up.

Focus

Issue Area # 1

Expectation: All supplementary elements that a user needs to interact with receive keyboard focus and be reached using only the keyboard. (WCAG Criteria 2.1.1 (A))
Observed:
- On new markdown and terminal pages, these don't let you escape the content body to do other things once you get inside of it.
- On Tree page, can't get to "Running" tab with just a keyboard. That section or each of those tabs need a tabindex="0" on it.
- Keyboard user cannot tab to the notebook title to trigger the modal to edit the notebook title. Needs tabindex="0" on it.

Issue Area # 2

Expectation: All supplementary elements that a user needs to interact with receive keyboard focus and be reached using only the keyboard. (WCAG Criteria 2.1.1 (A))
Observed:
- On both light and dark theme, when focused on the Jupyter logo in header, the focus indicator is just a vertical line on the left side. This is not sufficient and needs to either surround the logo or the logo needs to be visually and noticably altered.
- Assuming functionality is added to allow keyboard-only users to tab to the notebook title to trigger the modal to edit notebook titles, this focus on dark theme needs to be more visually different. THe change from dark gray to lighter gray is not enough. Make sure difference is a difference in 3.0:1 contract ratio from non-hover to hover.

Content, Organization, and Navigation

Issue Area # 1

Expectation: The user can skip navigation functions, sidebar, or other repetitive content go straight to the content. (WCAG Criteria 2.4.1 (A))
Observed: User is forced to tab 20 times every time on notebook page because getting to the main region (and slightly less times on the other non-notebook pages). Needs a skip link to appear in first tab or two to jump straight to #main

Issue Area # 2

Expectation: Tables used appropriately, clearly organized, and labeled. (WCAG Criteria 1.3.1 (A) & 4.1.2 (A))
Observed: Main table (tree page) is not a real table; it is made of <div>s within <div>s not Table > THEAD/TBODY > TR > TH/TD. Without this blind users/screen readers cannot decipher that this is row data or what element corresponds to what row, how many rows there are, etc.

Issue Area # 3

Expectation: Is content that appears on hover or keyboard focus dismissible, hovberable, and persistent? (WCAG Criteria 1.4.13 (AA))
Observed:
- All hoverables (tooltips) are not appearing on keyboard focus based on what I could tell. AKA, people using only keyboard do not know that the play button in the heading has meaning "Run the selected cells (Shift + Enter)". They just have to guess what all of these buttons do. Once implemented, make sure these users can dismiss these hoverables by pressing the ESC key.

Issue Area # 4

Expectation: User is informed when content changes dynamically away from the focus (WCAG Criteria 3.2.2 (A), 4.1.2 (A), & 4.1.3 (AA))
Observed: On notebook page when preforming all code cell actions (runs, stops, moves, duplications, etc.) it's not mentioning this to screenreaders. On move it should send a screenreader only alert saying ex. "Code cell number 4 has swapped with code cell 3 successfully" or at minimum "cell move successful". Whenever a cell is run, I expect it to say ex. "Running cell 3", say the output as it's happening, example "Packages already installed: pandas", etc. then will read either "Cell 3 finished successfully" or "Cell 3 failed. Error: {insert error}.

Color, Contrast, and Zoom

Issue Area # 1

Expectation: Do the default text and background size and colors provide sufficient contrast? (WCAG Criteria 1.4.3 (AA))
Observed:
- On just dark theme, the links found on the "About Jupyter Notebook" dropdown have insufficient contrast. Needs a 4.5:1 ratio or higher but has a 1.71 ratio (dark blue on dark gray). When selecting this link as well it becomes a dark red on red (1.64 contrast ratio).
- On both dark and light themes, the colors found within the code blocks (the syntax highlighting) needs 4 and 6 color changes respectively. Both of these need to reach a 4.5:1 contrast ratio between and its background.These also ideally need to have a certain contrast (3:1) between one another so they stand out (a different WCAG requirement), but there are too many colors used that all may appear adjacent to one another that this does not seem possible so can ignore. I recognize this might be a different codebase but wanted to flag at least.

Issue Area # 2

Expectation: Can the page be zoomed to 400% zoom in a 1280px wide display without requiring two scroll bars? (WCAG Criteria 1.4.10 (AA)).
Observed:
- Notebook page at 400% magnification cannot see the notebook title, the language of the notebook, the jupyter link to go back, or the help dropdown. In addition the "Not Trusted" block is partially cut off when appearing (also can't edit the title of the notebook but revealing it will most likely fix this).
- Minor annoyance on /tree page. The top 2/3rds of the page is fixed so you can only see 1-2 notebooks from list as you scroll. Recommend making most (everything below the main header) if not all of it static to maximize scrollable area.

The text was updated successfully, but these errors were encountered:

seirani · 2023-04-15T17:12:59Z

Hello! I noticed that the "skip to main content" feature is still not implemented. I have some experience working with accessible design and would love to contribute to this or any other open tasks listed here if it would be of any help?

jtpio · 2023-04-17T08:38:06Z

Thanks @seirani! If you would like to get started on this please feel free to open a PR. Thanks again!

seirani · 2023-04-17T23:04:58Z

Awesome, thank you @jtpio! Quick question: I am trying to navigate the Jupyter Notebook codebase and am a little confused as to where exactly the HTML notebook files or .less files are located - I can find the template HTML files that are pretty sparse and seem to be configured elsewhere? But for a feature such as this one where I'd likely add a div and a link, where would I make that change to have it go into effect? Or do I have to run something first to make them appear? Thank you in advance!

jtpio · 2023-04-18T10:00:42Z

The templates are minimal and similar to the ones in JupyterLab. This is because the application populates the DOM on startup when the shell is created.

Probably it would have to be implemented similar to what was done in JupyterLab: jupyterlab/jupyterlab#10126

manfromjupyter · 2023-05-04T14:04:59Z

Sorry for scope creep, but I forgot 2-3 things that I found just recently that are worth noting to get fixed.

Color contrast of code blocks syntax highlighting (I recognize it might be another code base)
Few things being hidden when zoomed in to 400% that shouldn't be hidden

RRosio · 2023-05-30T16:56:44Z

There are at least 14 remaining tasks, could we identify which would be release blockers from these?

krassowski · 2023-05-31T17:56:08Z

Minor dark theme color contrast fix on "About Jupyter Notebook" modal.

Can we check this one? I believe this one was also reported in #6552 / jupyterlab/jupyterlab#14084 and fixed on JupyterLab side by jupyterlab/jupyterlab#14159.

isabela-pf · 2023-05-31T18:29:03Z

In the 31 May 2023 Jupyter Accessibility meeting (cc: @andrii-i), it was requested that people weigh in on which of the listed items on this issue are release blockers—defined as issues that prevent someone from using the notebook in full.

I can only speak for myself, but here is my brief-as-possible thoughts on which are blockers and which are not. I've copied the tasks listed above and added my thoughts in the second level of checklists for each item.

Blind users with screenreader read everything in German no matter what (JS sets lang as an invalid type: "default").
- Blocker. People can not successfully use Notebook with a misrepresented language.
Using just keyboard, user can't escape Terminal or Markdown block on New Terminal and New Markdown pages once they get inside them (perhaps also other non-notebook pages as well)?
- Blocker. Keyboard traps prevent users from completing any other tasks once they are trapped. There at least needs to be some kind of escape button that is made clear (an example on VS Code) even if it cannot be fully fixed within this release.
Using just keyboard, user can't get to Running tab on /tree page.
- Blocker. People using a keyboard should be able to navigate to all areas in order to be successful in notebook.
Keyboard-only users cannot modify notebook titles. Needs tabindex="0" on the notebook title link that triggers modal to rename.
- Blocker. Renaming a notebook is a basic (and very needed) functionality of Notebook. My only caveat is there may be workarounds for renaming outside of Notebook if that helps prioritize compared to things with no workarounds.
Keyboard-only user focus on Jupyter logo is just a vertical line not bounding box around the element they are focused on.
- Not a blocker. From my understanding, the logo does not function as anything other than a visual. This is more awkward than blocker.
On focus and hover on the notebook title on just the dark theme, this needs a more distinct color change. As is (change from dark gray to lighter gray) is not enough of a difference to visually demonstrate it's currently focused/it does something.
- Not a blocker. Unclear and not accessible, but probably not unusable.
No skip link found (keyboard-only users have to tab 20 times every time to get to main region to do work).
- I'm seeing this is checked off so I'm hoping it's handled. But if it is still an issue, it is definitely a blocker. Navigating is a necessary function.
Main page (tree page)'s table is not a real table; it's <div>s within <div>s which works for visual users but not blind users/screen readers.
- Blocker. While this description does not make it clear enough for me to know how it interacts/ how it is blocking, the tree page is a big and important part of the required user flow. It's needed to open a notebook at all. This needs to work with a screen reader.
Keyboard-only users (ambulatory), do not see the hoverable/tooltip of the icons in heading and in code cells when focusing on the elements.
- As much as it pains me, I think I have to call it not a blocker. The buttons working is more important. This is a major issue of focus. I could imagine it as a blocker if things are not named appropriately and their function is unclear, though.
Hovering over something with a hoverable popup/tooltip does not let you dismiss it with the ESC key.
- Blocker. The popup/tooltips that appear and cannot be dismissed may obstruct other functions.
Notebook cell actions are not announced to screenreader. User does not really know when cell was run, stopped, moved, duplicated, etc. successfully or what the cell is currently outputting automatically without manually doing it as it's popping out (which they won't be able to see to know to follow alone.
- This one is hard because it is so big. And important. I don't think we have an ideal experience for this even for our sighted users. I want to call it a blocker but I do not know how we would solve it.
Minor dark theme color contrast fix on "About Jupyter Notebook" modal.
- Not a blocker. Unclear and not accessible, but probably not unusable.
On dark theme, there are 4 colors a part of the code syntax hightlighter in the code blocks that needs better contrast from the background. On light theme this number is 6. Both of these need to reach a 4.5:1 contrast ratio.
- Blocker. Being able to read the code is a necessary function of the notebook, and I am not aware of a way to turn off or change the syntax highlighting to make it readable. If there is a way to remove or change the syntax highlighting right now, then it may not be a blocker.
Notebook page at 400% cannot see the notebook title, the language of the notebook, the jupyter link to go back, or the help dropdown. In addition the "Not Trusted" block is partially cut off when appearing (also can't edit the title of the notebook but revealing it will most likely fix this).
- Blocker. While it may sound only visual, when major elements get moved off the page they often cannot be accessed/activated at all. This sounds like it blocks functionality of the Notebook.
Tree page when at 400% zoom only lets you see a couple notebooks at a time when scrolling due to top 2/3rds of page being fixed on the page.
- Not a blocker. Unpleasant and not accessible, but probably not unusable.
Color contrast of code blocks syntax highlighting (I recognize it might be another code base). Even though this is not specific enough for me to be certain, I would call this a
- blocker. Being able to read the code is a necessary function of the notebook and cannot be otherwise managed to my knowledge. Switching out our current syntax highlighting theme for one designed for contrast (like the ones in ericwbailey/a11y-syntax-highlighting) may be all that is needed.
Few things being hidden when zoomed in to 400% that shouldn't be hidden.
- Blocker. This risks blocking functionality of the Notebook because hidden things cannot be accessed.

andrii-i · 2023-05-31T20:14:48Z

Thank you for quick and detailed feedback @isabela-pf.

andrii-i · 2023-05-31T20:25:40Z

Based on discussions during the calls, if certain issue is a regression vs Notebook 6 and if it is solvable in a reasonable amount of time should also be taken into account when determining release blockers.

gabalafou · 2023-06-01T12:26:19Z

This came up in yesterday's accessibility call.

During that call, I committed to attending the triage meeting on Tuesday, June 13 (I've added it to my calendar). If this issue still needs triaging at that point, I can help then. (I'm going to be out all next week, is why I can't attend next week's triage.)

In the meantime, here's how I would go about identifying release blockers by Andrii's definition in today's accessibility call. The definition he shared is that release blockers are problems that prevent people from using major features of the Notebook. I would start with the list of things that Isabela identified as blockers above and ask three questions:

Is this essential functionality? (I think Isabela already took that into consideration, though, in her pass-through)
Is there another way to do the same thing?
Is that alternative accessible?

If you answer (yes, no) or (yes, yes, no), then the issue should be triaged into the release blockers list. However, it came up in the call that it might be disingenuous or confusing to call them release blockers if they don't actually block the release.

I'm not really equipped to answer the first two questions, but I can help answer the third question about whether existing workarounds are accessible, which is why I think the fastest way to triage the above list is synchronously, so we have enough information in the heads of the people in the room to answer all three questions at once for each of the items in the list.

jtpio · 2023-06-01T12:35:55Z

release blockers are problems that prevent people from using major features of the Notebook

Since there are very limited resources on Notebook 7 at the moment, I think we should consider an issue as blocking if it prevents someone currently using Notebook 6 to migrate to Notebook 7. Either because there is a big regression, or because something is missing in Notebook 7. Normally accessibility should already be largely improved in Notebook 7 as of today compared to Notebook 6.

All the issues mentioned above should eventually be fixed for sure, but they could also go in 7.0.x patch releases to not block the 7.0 final release.

manfromjupyter · 2023-06-06T14:50:44Z

Just three comments on @isabela-pf's. Thank you making that btw.

Main page (tree page)'s table is not a real table; it's <div>s within <div>s which works for visual users but not blind users/screen readers.

Blocker. While this description does not make it clear enough for me to know how it interacts/ how it is blocking, the tree page is a big and important part of the required user flow. It's needed to open a notebook at all. This needs to work with a screen reader.

This is needed for blind users because properly made semantic <table>s give them a full suite of additional capability than if artificially constructed to look like such. These things include:

Visiting cells on a table it will announce the column (or row or both) it belongs to based on the <th> elements
Allows them to read the whole row at a time
They can copy entire rows
They can with a keyboard shortcut jump to top of table, bottom of table, left, or right.
They can list all tables on the page
They can jump straight to them if they know it exists (same way they can jump to the <h1>, <h2>s, etc. just by pressing "H"). So kind of a usability thing for this one but just speeds up their workflows tremendously.

Keyboard-only users (ambulatory), do not see the hoverable/tooltip of the icons in heading and in code cells when focusing on the elements.

As much as it pains me, I think I have to call it not a blocker. The buttons working is more important. This is a major issue of focus. I could imagine it as a blocker if things are not named appropriately and their function is unclear, though.

You're right that users with ambulatory disabilities can just try to figure out what these icons mean by looking at them and at worse try each one and remember. Being able to see the tooltip though that even says what the keyboard shortcut is to hit it at any time (ex. SHIFT + ENTER) to run a selected cell, this is pretty big for their experience and sanity.

Notebook cell actions are not announced to screenreader. User does not really know when cell was run, stopped, moved, duplicated, etc. successfully or what the cell is currently outputting automatically without manually doing it as it's popping out (which they won't be able to see to know to follow alone.

This one is hard because it is so big. And important. I don't think we have an ideal experience for this even for our sighted users. I want to call it a blocker but I do not know how we would solve it.

Not sure if this is a path you want to go but I always add this kind of capability by doing the following.

Create <div id="screenreaderAlerts" class="sr-only"></div> and slap at the bottom of your page somewhere (or perhaps at bottom of the notebook pages if we want to keep this small for now).
Insert following function in JS where the other JS files inherit it and can thus use it.

/* ===== Make Screenreader-Only Alert ===== */
function makeScreenreaderAlert(element_id, on_message, off_message){
  let element = '#' + element_id;
  if ($(element).length){
    $(element).text(message);
  }
  else {
    $('#screenreaderAlerts').apend('<div id="' + element_id + '" role="alert">' + message + '</div>');
  }
}

After what JS or whatever controlling the moving, running, deleting, etc. of the notebook cells, just follow it up with a:

makeScreenreaderAlert('notebookActionAlert', 'Cell has finished running.');

The purpose of the element_id part of it is so you can override it with other actions of the same type and users can re-read alerts as they wish and it doesn't take away from the visual-user experience. Example of the former is if you want to fire one on cell run start and cell run finish, if it's a 20 second cell run, it could alert them that "Cell has started running" and then would read that "Cell has finished running". If the cell only takes 0.5 seconds to run, it may only read "Cell-" of that first message before getting interrupted/replaced and reading "Cell has finished running" in full. Anyway that's just how I do it for my other apps, you do you though.

andrii-i · 2023-06-13T05:42:28Z

Thank you for feedback everyone. Moving to 7.0.x for further follow up after Notebook 7 release. Related comment: #6307 (comment)

tonyfast · 2023-06-16T06:03:06Z

it was shared there it might help to break the checklist into issues. i've started that process and added what i could.

it would be awesome if folks could add any knowledge they have about solving any of these. lines of code, relevent prs. the more information we have the better chance we have for success. please, if the urge strikes you, help with splitting out the rest of the checklist.

should we transition this issue into milestone?

andrii-i · 2023-06-16T07:03:29Z

Thank you very much for creating so many issues @tonyfast, this helps a lot. We absolutely should assign them to milestones and add additional details where possible. We should start triaging these issues individually (started) and during calls.

manfromjupyter added the bug label Mar 24, 2023

jupyterlab-probot bot added the status:Needs Triage Applied to issues that need triage label Mar 24, 2023

RRosio removed the status:Needs Triage Applied to issues that need triage label Mar 28, 2023

RRosio added this to the 7.0 milestone Mar 28, 2023

andrii-i mentioned this issue Mar 28, 2023

Weekly Triage meetings: Jan-Jun 2023 jupyterlab/frontends-team-compass#169

Closed

seirani mentioned this issue Apr 19, 2023

Add Skip Link to Notebook #6844

Merged

tonyfast added the tag:Accessibility label May 3, 2023

andrii-i mentioned this issue May 24, 2023

Notebook Weekly Meeting 2023 jupyter/notebook-team-compass#21

Closed

andrii-i mentioned this issue Jun 7, 2023

7.0 Release Plan #6307

Closed

andrii-i modified the milestones: 7.0, 7.0.x Jun 13, 2023

tonyfast mentioned this issue Jun 15, 2023

Rethinking the notebook cells weekly meeting jupyterlab/frontends-team-compass#182

Open

gabalafou mentioned this issue Jun 15, 2023

Team update - Jun 14, 2023 Quansight-Labs/jupyter-a11y-mgmt#217

Closed

tonyfast mentioned this issue Jun 16, 2023

Make the tree page file browser a table to support blind users/screen readers. #6925

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Accessibility Issues Needing Addressing for WCAG 2.1 compliance (As of Version 7.0.0a15) #6800

Accessibility Issues Needing Addressing for WCAG 2.1 compliance (As of Version 7.0.0a15) #6800

manfromjupyter commented Mar 24, 2023 •

edited by tonyfast

seirani commented Apr 15, 2023

jtpio commented Apr 17, 2023

seirani commented Apr 17, 2023

jtpio commented Apr 18, 2023

manfromjupyter commented May 4, 2023

RRosio commented May 30, 2023

krassowski commented May 31, 2023

isabela-pf commented May 31, 2023 •

edited

andrii-i commented May 31, 2023

andrii-i commented May 31, 2023

gabalafou commented Jun 1, 2023

jtpio commented Jun 1, 2023

manfromjupyter commented Jun 6, 2023 •

edited

andrii-i commented Jun 13, 2023

tonyfast commented Jun 16, 2023

andrii-i commented Jun 16, 2023

Accessibility Issues Needing Addressing for WCAG 2.1 compliance (As of Version 7.0.0a15) #6800

Accessibility Issues Needing Addressing for WCAG 2.1 compliance (As of Version 7.0.0a15) #6800

Comments

manfromjupyter commented Mar 24, 2023 • edited by tonyfast

Summary

Issues

Issues (Broken Down)

Language

Focus

Content, Organization, and Navigation

Color, Contrast, and Zoom

seirani commented Apr 15, 2023

jtpio commented Apr 17, 2023

seirani commented Apr 17, 2023

jtpio commented Apr 18, 2023

manfromjupyter commented May 4, 2023

RRosio commented May 30, 2023

krassowski commented May 31, 2023

isabela-pf commented May 31, 2023 • edited

andrii-i commented May 31, 2023

andrii-i commented May 31, 2023

gabalafou commented Jun 1, 2023

jtpio commented Jun 1, 2023

manfromjupyter commented Jun 6, 2023 • edited

andrii-i commented Jun 13, 2023

tonyfast commented Jun 16, 2023

andrii-i commented Jun 16, 2023

manfromjupyter commented Mar 24, 2023 •

edited by tonyfast

isabela-pf commented May 31, 2023 •

edited

manfromjupyter commented Jun 6, 2023 •

edited