squidfunk / mkdocs-material

Documentation that simply works

Home Page:https://squidfunk.github.io/mkdocs-material/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Improve Accessibility

JoeUser78 opened this issue · comments

Contribution guidelines

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

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.