Accessibility Issues

[waako]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I've found a bug and checked that ...

• ... the problem doesn't occur with the mkdocs or readthedocs themes
• ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
• ... the documentation does not mention anything about my problem
• ... there are no open or closed issues that are related to my problem

Description

There are a number of sub-optimal implementations for accessibility, and some misuse of ARIA roles, particularly around navigation (e.g. sidebar) and search.

This causes some major difficulties for keyboard navigation.

Whilst #4006 touches on a few issues, I'd like to build this into a Meta issue to document the existing issue, the challenges they cause and potential directions to ensure improved accessibility.

To that effect, I'll be slowly adding as I go, so this is a WIP bug report.

Expected behaviour

Ability to navigate, use and interact with menu (on narrow screen), search and operate interactive components using keyboard and assistive technology.

Actual behaviour

• Unable to "toggle" sidebar menu using keyboard.
• On Safari, focus order goes back to beginning after focus is on search "dialog" making it impossible to tab through rest of page (wide and narrow screens).

Steps to reproduce

Use keyboard to tab through page elements.

Package versions

• Python: python --version
• MkDocs: mkdocs --version
• Material: pip show mkdocs-material | grep -E ^Version

Configuration

site_name: Material for MkDocs
site_url: https://squidfunk.github.io/mkdocs-material/

System information

• Operating system: macOS
• Browser: Safari/Firefox

[waako]

The problem with using checkbox hack for showing the sidebar (e.g. __drawer) even when no javascript is the input and label are not together, even if they were together the input has display:none making it not focusable by keyboard.

Heydon Pickering has a working example of accessible dropdown menu using checkbox hack, see codepen and inclusive-components article.

However, to retain the expected behaviour here using an anchor link to the drawer container (using id) and enhancing that with javascript to be a button with correct aria behaviours would probably make more sense.

Here's a "fallback" example codepen that would be enhanced using javascript to have all relevant aria attributes, behaving mostly like a disclosure pattern with a bit of dialog pattern.

See ARIA Authoring Practices Guide (APG) patterns

[waako]

Having all the Switch to [option] (dark/light/system preferences) radio input elements grouped inside a fieldset would be much better as users of assistive technology could loop through the options using left/right arrows.

[squidfunk]

Thanks for reporting. Accessibility is an ongoing effort and a priority for this project. I try to make it as accessible as possible, but I understand that there are some things (e.g. the checkbox "hack") for which improvements might need fundamentally different solutions with other downsides, as you already noticed. I'm regularly testing the theme by using a screen reader, but I'm not a regular user of those, so I can only guess whether it works well enough.

My comments for the things you already mentioned:

Having all the Switch to [option] (dark/light/system preferences) radio input elements grouped inside a fieldset would be much better as users of assistive technology could loop through the options using left/right arrows.

My testing in Chrome and Firefox shows that this is exactly possible. Please provide more details when you don't find this to be working. I can Tab to the selector and then use the arrow keys to toggle between the different states. Also note that all toggles are grouped inside a form element, so adding another level of nesting via a fieldset is questionable.

The problem with using checkbox hack for showing the sidebar (e.g. __drawer) even when no javascript is the input and label are not together, even if they were together the input has display:none making it not focusable by keyboard.

If you come up with a better solution or manage to integrate the one you posted without any loss in functionality, I'm happy to merge it. Please see #4006 (comment) for further implementation details.

I'm converting this issue to a discussion, which we can branch out into PRs and issues, if necessary. You can create issues for missing aria-* attributes, or changes in markup. However, if you want to see a completely different solution for a specific problem, I invite you to send a PR, where we can discuss changes.