Summary of Axe accessibility issues

[gabalafou]

If you run the accessibility checks right now:

nox -s a11y

It opens several pages and runs the Axe checker against them to find accessibility issues. There are many test failures, but only several root causes.

This issue groups the failures and links to issues to fix them. Note that some of the issues exist outside this repo (in dependencies).

---

• color-contrast - Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds
  Root cause: insufficiently strong color palette for the a11y-light Accessible Pygments theme
  Related GitHub issue:
  a11y-light fails WCAG AA contrast with gray background Quansight-Labs/accessible-pygments#30
  Pages where this shows up:
  • /examples/kitchen-sink/blocks.html (light theme)
  • /examples/pydata.html (light theme)
  • /user_guide/theme-elements.html (light theme)
  • /user_guide/styling.html (light theme)

---

• scrollable-region-focusable - Ensure elements that have scrollable content are accessible by keyboard
  Root cause: tabindex=0 not set by Sphinx on code blocks
  Related GitHub issue:
  ENH - Make code blocks focusable #1100
  Pages where this shows up:
  • /examples/kitchen-sink/api.html
  • /examples/kitchen-sink/blocks.html
  • /examples/kitchen-sink/lists.html
  • /examples/pydata.html
  • /user_guide/styling.html

---

• duplicate-id-aria - Ensures every id attribute value used in ARIA and in labels is unique
  This is a site-wide issue so it shows up only on /user_guide/page_toc.html page in the test results.
  Fixed by: Fix duplicate HTML IDs #1425

---

The following two site-wide issues are both fixed by the same PR:

• aria-allowed-role - Ensures role attribute has an appropriate value for the element.
  Fixed by Remove redundant ARIA in breadcrumb navigation #1426
• listitem - Ensures <li> elements are used semantically.
  Fixed by Remove redundant ARIA in breadcrumb navigation #1426

---

There are also some color contrast issues that have to do with running Axe core (the accessibility checker) before certain animations (color transitions) finish running on the page. This results in false positive contrast failures. This is tracked in the following issue:

• False Axe contrast failures due to CSS animations (color transitions) #1427

---

The following violations are site-wide and appear at /user_guide/page-toc.html, which runs Axe against the entire page. These site-wide violations are fixed by #1454:

• landmark-main-is-top-level - Ensures the main landmark is at top level
• landmark-no-duplicate-main - Ensures the document has at most one main landmark
• landmark-unique - Landmarks should have a unique role or role/label/title (i.e. accessible name) combination
• region - Ensures all page content is contained by landmarks

---

The following site-wide violation has to do with the PyData Theme logo in the header. The alt text for the logo is PyData Theme, but text that immediately follows the logo icon is also PyData Theme. This causes the screen reader to say it twice. This issue is fixed in #1472 and #1471:

• image-redundant-alt - Ensure image alternative is not repeated as text

---

This is an issue in Sphinx Design with link cards:

• link-name - Ensures links have discernible text
  • /user_guide/web-components.html
  • Fix violation of Axe rule link-name #1633

---

• landmark-unique violation at /examples/kitchen-sink/generic.html #1479

---

• landmark-unique violation at /user_guide/theme-elements.html #1478

---

• empty-table-header violation at /examples/pydata.html #1480

[gabalafou]

cc @trallard

[gabalafou]

Update

Almost all of the Axe violations for our current set of test pages have been addressed. Our recent upgrade of Accessible-pygments fixed most of the remaining color contrast issues.

There are only two remaining color contrast issues:

• Notebook cell numbers (output via nbsphinx) do not have enough contrast, neither in light mode nor in dark mode.
• Xarray has some color contrast issues:
  • Fix some of these with Force light mode for notebook outputs #1812
  • For the others, write some special case style rules to override Xarray's own styles in the short-term,
  • Longer term, file an issue or pull request to fix upstream

The only other issue has to do with ipyleaflet. When that widget fails to load, it displays a SVG icon of a broken document, but that SVG icon does not have alt text. This is also something outside our control and we will need to file an issue or pull request upstream. In the meantime, I will add code to:

• Ignore the accessibility violation from the ipyleaflet error missing alt text

Future work

• Strategically add a few more of our docs pages to our set of test pages to scan with Axe-core