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.

[waako]

Good point, sorry not actually familiar with GitHub Discussions, and I probably should have added/expanded to #3156

1. Switch for Dark/Light/System Preference mode

You are correct that it works as expected in Chrome & Firefox, but not in Safari, which requires a fieldset/radiogroup container.
In fact the form element is unnecessary here as no actual "form" action (e.g post/get) is performed, so replacing that with fieldset role="radiogroup" would be optimal and would ensure works in Safari.

2. checkbox hack for show sidebar (__drawer)

Will try to create a PR to that effect, it should also allow using sidebar menu on desktop.

And will continue to identify items that need reviewing as I go, including solution for resolving where possible of course.

[squidfunk]

I can confirm that Safari behaves very weird also in regards to tabbing behavior. If you can make sure that the form is not needed, we can replace it with a fieldset. Note however, that I'm not considering going down the painful path of bringing Safari en par in terms of A11Y due to its rather low market share among desktop browsers of 5%. The general recommendation is to use another browser, as the problems reported are likely also to happen on many other websites.

[waako]

Agreed that Safari is a PITA for many things, it's an extra PITA with regards a11y as (normally) the best experience when using VoiceOver…

I've not checked with Safari on iOS, but in this case the changes would ensure correct pattern used (e.g. radiogroup), and a pretty painless swap to provide optimal experience at least.

Will spin up an MR soon.

[cmuncharaz]

I'd like to join this discussion, a year and a half later, to mention that the problem with the color scheme switch (dark/light/system) still poses a challenge for a specific group: sighted keyboard users.

These users rely on the keyboard to move around and use their eyes to perceive the content. The color scheme switch looks like a button but doesn't have a label. Because it looks like a button, keyboard users would think they could activate it using the Enter key. However, pressing the Enter key doesn't do anything. Also, without a clear label, the button's purpose is confusing. In short, users in this group might think the button is broken.

Since these users don't use a screen reader, they don't hear any announcements about this component being a radio selector.

Furthermore, because they don't use a mouse, they can't see the tooltips explaining this component's function when hovering over it.

It would be great to address this problem to improve keyboard accessibility.

[squidfunk]

Sure, happy to address it. So, as I understand, allowing cycling with Enter should do the trick? Also, we should activate the tooltip on focus. All of this needs to be done in JavaScript, and is very likely to be very hacky, but we can check for sure. If you like us to go forward on this, please create a new bug report with a minimal reproduction.

[brynpickering]

I just set up some CI to test our docs accessibility against the WCAG2AA standard (using Pa11y-ci) and came across a number of issues:

Search plugin lacks a submit button

I don't think this is an issue since the search bar doesn't need a submit button (it auto-loads results as an extension of the search bar which are then accessible via the keyboard).

Error: This form does not contain a submit button, which creates issues for those who cannot submit the form using the keyboard. Submit buttons are INPUT elements with type attribute "submit" or "image", or BUTTON elements with type "submit" or omitted/invalid.

[htmlcs: WCAG2AA.Principle3.Guideline3_2.3_2_2.H32.2](https://squizlabs.github.io/HTML_CodeSniffer/Standards/WCAG2/#sc3_2_2)

<form class="md-search__form" name="search"> <input type="text" class...</form>
(selector "html > body > header > nav > div:nth-child(6) > div > form")

Checkbox input doesn't have a name

I assume this is the "hack" mentioned earlier in the discussion

This checkboxinput element does not have a name available to an accessibility API. Valid names are: label element, title undefined, aria-label undefined, aria-labelledby undefined.

[htmlcs: WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.InputCheckbox.Name](https://squizlabs.github.io/HTML_CodeSniffer/Standards/WCAG2/#sc4_1_2)

<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
(selector "#__toc")

Form field needs filling

Is this also the "hack" mentioned earlier in the discussion?
This is specific to #__toc, which is linked to currently open nav items?

Error: This form field should be labelled in some way. Use the label element (either with a "for" attribute or wrapped around the form field), or "title", "aria-label" or "aria-labelledby" attributes as appropriate.

[htmlcs: WCAG2AA.Principle1.Guideline1_3.1_3_1.F68](https://squizlabs.github.io/HTML_CodeSniffer/Standards/WCAG2/#sc1_3_1)

<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
(selector "#__toc")

Code line href without link content

This appears irrespective of the code content features that are switched on.

Error: Anchor element found with a valid href attribute, but no link content has been supplied.

[htmlcs: WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.A.NoContent](https://squizlabs.github.io/HTML_CodeSniffer/Standards/WCAG2/#sc4_1_2)

<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
(selector "#__codelineno-0-2")

Insufficient contrast

I know this is something that a user can configure, but these are results using the out-of-the-box mkdocs Material theme, so I feel they should be accessible by default.

Error/Serious: Elements must have sufficient color contrast

Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds

[axe: color-contrast](https://dequeuniversity.com/rules/axe/4.2/color-contrast?application=axeAPI)

<span id="__span-0-5"><a id="__codelineno-0-5" name="...</span>
(selector "#__span-0-5")

[squidfunk]

Thanks for proividing the information – always good to run an accessibility checker, but as I mentioned countless times before, they have their limits and report things that might not be issues at all or that we cannot fix due to technical reasons.

1. Yes, no submit button, as it executes immediately. I'm not an expert, but if we can somehow add an aria attribute or role that indicates this to fix the behavior, PR appreciated ☺️
2. Correct, I don't know how we can fix it, except for taking it away from the accessibility tree, but I'm not sure whether this would break functionality.
3. Same.
4. This code is generated by the Highlight extension. It might be a good idea to run this by @facelessuser – maybe there's a way to denote that this is merely an anchor for positioning and the content is outside. Again, not an expert.
5. If you can provide a reproduction that shows exactly what the problem is, we can evaluate and probably fix it. Please create a new issue for this and carefully read our bug reporting guidelines. Thanks!

[brynpickering]

Yep, I'm not taking the checker results as gospel, just that the known (non-)issues flood out the fixable issues that might be in there (e.g. missing alt text in a figure), so it's good to know what is and isn't fixable. For the above issues, I suppressed all but the contrast one via Pa11y config: "hideElements": "[id^='__codelineno'], .md-search__form, #__toc". It's a brute force approach that might suppress fixable issues, but does the job for now!

[brynpickering]

RE contrast issues, this seems to be a pa11y bug caused axe not being able to determine the contrast ratio: pa11y/pa11y#697. From a manual inspection of the Material defaults, all seems fine for WCAG2AA (although not for WCAG2AAA).