Epic: ADA Rule and WCAG 2.1 AA conformance

[wwarriner]

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