Rubric: diagram text alternatives

Written by a person. Last read by a person on 2026-09-04, 4 days ago. Its facts were checked by the eval suite on 2026-09-07.

Enforced by check_diagram_alternatives.

The claim

Every diagram carries a text alternative that conveys what the diagram conveys, so that the document works for a reader who cannot see it.

Observable evidence

• Each fenced mermaid block in the content tree.
• Whether its fence info string carries text after the language name.

The pass bar

Every mermaid fence has a non-empty alternative. WCAG 2.1 AA is a hard constraint (spec 3.8 constraint 5), not a preference, so this fails the build rather than warning.

The alternative lives in the fence rather than in frontmatter deliberately. Frontmatter would let the description and the diagram drift apart silently as one is edited and the other is not, and a stale alt text is worse than an absent one because nothing looks wrong.

Ambiguous cases

Whether the alternative is any good. Not checkable. A fence reading mermaid a diagram passes this rubric and helps nobody. The check enforces that someone was made to write something; only review can enforce that what they wrote is useful.

Diagrams that are decorative. There are none here yet. If one appears, the correct alternative is an explicit statement that the diagram adds nothing the prose does not already say, which is also a strong hint the diagram should be deleted.

Prose that already explains the diagram. Common on these pages, and the alternative is still required. A screen reader reaching a figure announces the figure; sending the reader to hunt for a paragraph that may be above or below it is not equivalent to captioning it.

Diagrams in other formats. Only mermaid fences are checked, because they are the only diagram format this repo uses. An inline SVG or an image would pass unexamined, which is a gap that closes when the first one is added rather than in advance.