Improve Accessibility
JoeUser78 opened this issue · comments
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
orreadthedocs
themes - ... the problem persists when all overrides are removed, i.e.
custom_dir
,extra_javascript
andextra_css
- ... the documentation does not mention anything about my problem
- ... there are no open or closed issues that are related to my problem
Description
The theme needs some improvements to make it (more) accessible to all.
Expected behaviour
No errors or alerts in at least the https://wave.webaim.org/ accessibility validotor.
Actual behaviour
See for example https://wave.webaim.org/report#/https://squidfunk.github.io/mkdocs-material/getting-started/
Steps to reproduce
Install and configure the theme as officially documented.
Create some docs and nested navs.
Run the published site through https://wave.webaim.org/
Package versions
- Python: 3.8.13
- MkDocs: 1.3.0
- Material: 8.3.3
Configuration
site_name: FooBar
site_url: https://www.example.com/
site_description: Some describtion
copyright: Copyright © 2022 FooBar
theme:
name: null
locale: de
language: de
custom_dir: theme/material
static_templates:
- 404.html
include_search_page: false
search_index_only: true
icon:
logo: material/book-open-page-variant
repo: fontawesome/brands/github
favicon: assets/favicons
palette:
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: amber
accent: indigo
toggle:
icon: material/weather-sunny
name: Switch to light mode
- media: "(prefers-color-scheme: light)"
scheme: default
primary: amber
accent: indigo
toggle:
icon: material/weather-night
name: Switch to dark mode
font:
text: Roboto
code: Roboto Mono
features:
- navigation.instant
- navigation.tracking
- navigation.tabs
- navigation.tabs.sticky
- navigation.indexes
- navigation.sections
- navigation.top
extra:
plugins:
- search:
lang:
- de
markdown_extensions:
- markdown.extensions.abbr:
- markdown.extensions.admonition:
- markdown.extensions.attr_list:
- markdown.extensions.def_list:
- markdown.extensions.footnotes:
- markdown.extensions.meta:
- markdown.extensions.md_in_html:
- markdown.extensions.smarty:
smart_quotes: false
- markdown.extensions.tables:
- markdown.extensions.toc:
permalink: true
permalink_title: Anchor link to this section for reference
slugify: !!python/name:pymdownx.slugs.uslugify
toc_depth: 3
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret:
- pymdownx.mark:
- pymdownx.tilde:
- pymdownx.details:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
- pymdownx.highlight:
use_pygments: true
auto_title: true
linenums: true
linenums_style: pymdownx-inline
- pymdownx.inlinehilite:
- pymdownx.superfences:
preserve_tabs: true
- pymdownx.keys:
separator: "\uff0b"
- pymdownx.smartsymbols:
- pymdownx.snippets:
base_path:
- docs/.snippets
check_paths: true
- pymdownx.tabbed:
alternate_style: true
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.magiclink:
- pymdownx.saneheaders:
- pymdownx.striphtml:
nav:
- Home: 'index.md'
- Category 1:
- 'cat_1/doc_1.md'
- Subcategory 1:
- 'cat_1/sub_1/doc_1.md'
- Subcategory 2:
- 'cat_1/sub_2/doc_2.md'
- Subcategory 3:
- 'cat_1/sub_3/doc_3.md'
- SubSubcategory 3:
- 'cat_1/sub_3/sub_3/doc_3.md'
- Category 2:
- 'cat_2/doc_1.md'
- Subcategory 1:
- 'cat_2/sub_1/doc_1.md'
- Subcategory 2:
- 'cat_2/sub_2/doc_2.md'
- Subcategory 3:
- 'cat_2/sub_3/doc_3.md'
- SubSubcategory 3:
- 'cat_2/sub_3/sub_3/doc_3.md'
- About:
- 'about/terms.md'
- 'about/privacy.md'
- 'about/imprint.md'
System information
- Operating system: FreeBSD 13.1
- Browser: Firefox, Chrome
Thanks for reporting. This issue is not concrete enough. Yes, there's a report, but it's very noisy. Please provide more details on what we should improve and why.
Currently there are multiple form-labels that are empty, for example the ones for __drawer or __search
Also there are multiple form-labels for the same form-elements, for example for __drawer or __search or _nav[0-9]
There are also empty buttons and missing fieldsets
And last but not least too low contrasts for example for the header links
Just see the provided link to the WebAIM Validator.
As an example lets look at the __drawer
The input is in https://github.com/squidfunk/mkdocs-material/blob/master/material/base.html#L90 and the corresponding labels are in https://github.com/squidfunk/mkdocs-material/blob/master/material/base.html#L92 (empty) and https://github.com/squidfunk/mkdocs-material/blob/master/material/partials/header.html#L13 (not empty)
HTML allows only one label per form-element, in this case the input. Multiple and/or empty labels aren't accessible for screenreaders and other devices like brailereaders.
Additionally i think that the input should moved from https://github.com/squidfunk/mkdocs-material/blob/master/material/base.html#L90 to https://github.com/squidfunk/mkdocs-material/blob/master/material/partials/header.html#L13
Thanks for providing details. Some of those errors are not fixable. For instance, yes, we have multiple labels that trigger __drawer
and __search
, but this is because they must work without JavaScript (e.g. on slow connections). That's not fixable, we need those labels.
The other errors and warnings may be fixable, but I would kindly ask you to provide details what you think is fixable and what not. Other than that, I'm not able to look into this issue. We go at great lengths for providing maximum accessibility, but most of the errors reported are, from my experience, false positives, i.e., they don't matter. I'm happy to be proven otherwise.
I'm closing this issue, as it's not actionable. Yes, you linked a report, but as I said, it's very noisy and I would like to discuss concrete measure you think are necessary. If you want to help improve accessibility, I'm happy to collaborate, but as noted, most of those things reported are essentialy non-issues.
Related:
HTML allows only one label per form-element, in this case the input.
MDN, citing the HTML spec says otherwise:
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#attr-for
Multiple label elements can be given the same value for their for attribute; doing so causes the associated form control (the form control that for value references) to have multiple labels.
Thus, it's valid HTML.
Multiple and/or empty labels aren't accessible for screenreaders and other devices like brailereaders.
If we can add an aria-*
attribute to improve screenreader handling, please create a PR where we can discuss changes!
MDN says "same value", but an empty value and a non-empty value are not the same, so it's not valid HTML.
OK, i may understand the problem for __drawer and __search and i also have no solution at hand for now :(
I will open new issues for some of the other problems, as soon as figure out solutions for them.
Thanks for your fast responses and keep up the work, it's great.