Epic: ADA Rule and WCAG 2.1 AA conformance

Tools

• Static HTML analyzer for a subset of conformance issues. Use my fork for now because it resolves various issues. https://github.com/wwarriner/be-a11y

Conformance Notes and Issues

• Tables
  • Accessible Name (invisible <caption>) 1.3.1
  • Accessible Description (<aria-describedby>)
  • Header elements need a scope attribute H63
    • Columns: <th scope="col">Column Name</th>
    • Rows: <th scope="row">Row Name</th>
• Links should have meaningful descriptions in their programmatic context (text description same

  element counts) 2.4.4

• Links with target="_blank" must announce they open in a new tab via, e.g., aria-label.
• Nav items making use of navigation.indexes with no other subitems receive an aria-labelledby attribute that references a non-existent label. (https://github.com/squidfunk/mkdocs-material/blob/0d11a2d01174a0ab3bec97300c4432da44128253/material/templates/partials/nav-item.html#L125)
• Bug in either pygments or pymdownx causing <a> tags with no href and no text. This appears to occur on a per-page basis when line numbers are used in at least one code block, but not in others. In those other code blocks, there are invisible, zero-size <a> tags with no href attribute and no text.
• Search form should have aria-label attribute.
• All SVG should have aria-label attribute, this may take some post-hoc editing, or a plugin. There are a LOT of material icons.

Invisible Elements

Elements that need to be invisible for aesthetics for sighted users can be made "invisible" using, e.g., https://stackoverflow.com/a/19758620 and https://webaim.org/techniques/css/invisiblecontent/

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0,0,0,0);
  border: 0;
}

Captions in MkDocs

Captions using pwmdownx.blocks.caption.

• https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#caption
• https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/caption/#adding-captions

Start by running the listed static HTML analyzer against the generated documentation and review the conformance checklist, including tables, links, navigation, search, SVGs, captions, and code blocks. Inspect the referenced nav-item.html entry point and the generated HTML to identify affected templates or content. Done means the listed WCAG 2.1 AA issues are resolved and the analyzer and accessibility checks pass.