Skip to content

SYSTEM Cited by 1 source

GitHub Accessibility Scanner alt-text plugin

Definition

A plugin for the GitHub Accessibility Scanner that judges the quality of image alt text, not merely its presence. It embodies a prove-vs-suspect split: five cheap deterministic rules that can prove alt is wrong, plus one opt-in vision-model rule for judgments a string can't support on its own. (Source: sources/2026-08-24-github-your-alt-text-passes-automated-checks-that-doesnt-mean-its-any-good)

Architecture

  • Image selection via accessibility tree. Uses Playwright's role-based locator rather than querySelectorAll('img'), so anything absent from the browser accessibility tree — including alt="" (author-declared decorative) — drops out and is never flagged.
  • Five deterministic rules (default-on, no creds/network): absent or whitespace-only alt; filename-as-alt (hero.png); placeholder (TODO, tbd); single generic word naming the medium (image, logo, chart) — matched by exact match against a curated closed set after normalization; and repeated alt across spatially adjacent images.
  • Repeated-alt rule uses layout, not DOM order — see layout-proximity-clustering-over-dom-order. A run only extends when the bounding-box gap is small relative to box size; when a box is unmeasurable the check fails open (concepts/fail-open-vs-fail-closed).
  • One opt-in alt-text-quality rule calls a vision model via systems/github-models with the image plus extracted page context (nearest heading, title, <figcaption>, link/button ancestry, ≤600 chars of nearby prose). Shaped as a decision procedure with reasoning-before-verdict structured output.
  • Privacy/data-flow controls: off by default, requires a GitHub Models token, and redacts URLs before they enter model context or logs (url-redaction-before-model-context). Optional Azure AI Vision OCR pre-pass sends image bytes to a second location.
  • Offline grading harness built from WebAIM / W3C images tutorial / POET, sharing one prompt with the runtime rule (offline-grading-harness-shares-runtime-prompt).

Limitations

Deterministic rules are literal (miss fluent-but-wrong alt); reads alt not the computed accessible name; only HTML <img> (no SVG / role="img" / CSS backgrounds / canvas); model rule produces false positives and can silently skip images it can't re-fetch.

Last updated · 766 distilled / 2,225 read