Accessibility

This page states what has actually been checked about the accessibility of this course website, what was changed as a result, and — just as importantly — what has not been checked.

This is not a claim of conformance

No conformance evaluation of this website has been carried out, and no claim is made that it meets WCAG 2.2 at any level. What follows is the result of a set of automated programmatic checks plus a small number of fixes. Automated checks detect a minority of real accessibility problems, and a clean result here is not evidence that the course is usable by everyone.

What was checked

The checks run offline from the built site and the source, so they run on every change. They cover three things.

1. Contrast, computed from the stylesheet the site ships

The colour variables are read from the built theme stylesheets and from docs/stylesheets/extra.css, the one stylesheet this course layers on top of the theme, and the contrast ratio of every text/background pair the course relies on is computed with the WCAG 2.x formula. Both colour schemes are checked, because the site follows the reader's system setting and can be switched manually.

Pair	Light	Dark	Threshold
Body text on the page background	16.10:1	8.89:1	4.5:1
Secondary text (table captions, notes, labels)	4.61:1	4.91:1	4.5:1
Link at rest	6.86:1	4.64:1	4.5:1
Link on hover or keyboard focus	4.86:1	6.11:1	4.5:1
Code text on the code background	8.99:1	7.25:1	4.5:1
Header text on the header bar	6.86:1	6.86:1	4.5:1

The disclosure chevron on a collapsible block is a non-text state indicator, so the threshold that applies to it is 3:1. Light mode: 4.02:1 for a note block and 3.98:1 for a question block, from 2.98:1 and 1.66:1 before the fix described below. Dark mode already passed and is left alone.

2. Structure, on every built page

• a lang attribute on <html>;
• exactly one level-1 heading, and no skipped heading levels;
• a main landmark;
• a skip-to-content link (except on the themed 404 page, which has no navigation to skip past);
• a mobile viewport declaration (width=device-width), so a phone lays the page out at its own width and reflows it rather than shrinking a desktop-width page to fit;
• a non-empty alt on every image (the course currently uses none — every diagram is Mermaid, which is rendered as text and SVG rather than as a picture);
• a header row on every table, so a screen reader can announce which column a cell belongs to;
• no link whose text is “here”, “click here”, “read more” and similar, and no link with no accessible name at all;
• no status conveyed only by a colour token such as [Red] with no words beside it.

3. Diagram descriptions

Every Mermaid diagram carries Mermaid's own accessibility fields — accTitle and accDescr — so the diagram has a name and a prose description rather than only shape and colour. There are 19 diagrams on the site: 18 on course pages and one on the deployment page for contributors. Nothing checks whether the description text is good; that is a review question, not a programmatic one.

What was changed, and why

Two theme defaults fell below the thresholds against this site's palette. Both are overridden in one small, commented stylesheet rather than by changing course content.

Link hover and focus. Material recolours a link on hover or keyboard focus using its accent colour, which for the indigo palette is #526cfe in both schemes. Measured against this site's backgrounds that is 4.26:1 on white and 3.78:1 on the dark background — under 4.5:1, so hovering a link or tabbing to it made the text harder to read than leaving it alone, and worse in dark mode. The accent is now #5c6bc0 in light mode (4.86:1) and #7f9cf5 in dark mode (6.11:1), keeping both states legible and staying in the indigo family.

Collapsible disclosure indicator. The chevron on a note or question block takes the block type's colour, which measured 2.98:1 and 1.66:1 against the block's own tinted header. In light mode these are now #2f74e0 (4.02:1) and #3d8c0e (3.98:1). Dark mode is unchanged because it already passed.

Neither change alters wording, structure, or navigation.

What this does not establish

Stated plainly, because the difference matters:

• No assistive-technology testing. The site has not been read with NVDA, JAWS, VoiceOver, or any other screen reader, so nothing here tells you what those tools actually announce.
• No manual keyboard walkthrough. Focus order, focus visibility on every control, and trapping are not verified.
• No automated engine with wider coverage. Tools such as axe, Pa11y, or Lighthouse cover more rules than the checks described here, and none has been run.
• No testing with people. Nothing here reflects the experience of a person who uses assistive technology, which is the only test that finds the problems that matter most.
• No evaluation of diagram descriptions. The accDescr text exists and is checked for presence only. Whether it conveys the diagram's meaning is unchecked.
• Layout at a specific screen size. That the page reflows on a phone is checked (the viewport declaration is present and the theme is responsive); that it reads well at any particular width is not. Nothing here measures text wrapping, tap-target size, or the point at which a table starts to scroll, because those depend on the rendered font and the reader's device.
• Wide tables and keyboard scrolling. Material renders a table as a horizontally scrolling region when it does not fit, and it does not make that region focusable. A keyboard-only reader can reach the hidden columns only if their browser exposes scrollable regions to the keyboard — behaviour that varies between browsers, and which this course does not control. The widest tables in the course (the defect log, decision log, and issue log templates) are the most likely to be affected.
• Colour-only meaning inside diagrams. Diagrams use colour to group and distinguish. Their descriptions carry the same information in words, but a diagram is still a visual artefact.
• External dependencies. The theme font is fetched from Google Fonts and Mermaid from unpkg.com (see Deployment). On a network that blocks them, the fonts degrade harmlessly but diagrams do not render — and the description text is inside the diagram source, so a blocked diagram is unavailable rather than merely unstyled.
• Material's code-line anchors. The theme generates one anchor per code line with no accessible name (about 1,800 across the site). They are line targets rather than links, and removing them would mean patching the theme. They are reported by the check as a known upstream artefact, not hidden.

Reporting an accessibility problem

If something in this course is difficult or impossible to use, that is a defect and worth reporting. Please open an issue, saying what you were trying to do, what happened, and what you were using to read it (browser, assistive technology, or both). You do not need to know the technical cause or the standard that applies.

For contributors

The check is tools/check-accessibility.py. It reads the built site, so build first:

python -m mkdocs build --strict
python tools/check-accessibility.py

It exits non-zero when a contrast pair drops below its threshold, when the overrides in docs/stylesheets/extra.css disappear, or when a structural rule fails. It also warns when the theme's own value would now pass, which is the signal that an override has become unnecessary. See the Tools README for the full list of checks, and the script's own docstring for the limitations restated as a scope statement.

If you add a diagram, give it accTitle and accDescr — the check fails without them. If you add an image, give it a real alt describing its content, not its filename.