Review HTML Accessibility: Baselines, Source Findings and Browser Evidence
Build a repeatable static HTML worklist, compare repairs within the same page scope and retain unperformed live checks. Run the offline example before applying the workflow to your own app.
Fastest way
Ask your AI to do it
Paste this into the AI agent you already use:
Use Accessibility Review Studio to review my authorized HTML sources. Confirm the user task and page scope, retain a before report, compare the exact corrected sources and distinguish resolved, persisting, new and removed-from-scope findings. Inspect each finding’s line, excerpt and source hash. Keep live checks not-run until actually performed; record specific browser evidence and rebuild only with matching source hashes. Deliver the worklist and remaining review scope without claiming WCAG certification. Do not call paid APIs or publish source files.
What does Accessibility Review Studio check?
Accessibility Review Studio v1.0.0 checks authorized HTML source for a bounded set of naming and structural problems. It records source paths, lines, excerpts and hashes, compares a repair against a baseline and collects separately authored browser observations. The package costs USD 4.99 individually and runs offline with Python 3.10+ and its standard library. No API key, paid scanner or dependency installation is needed for the bundled example.
The source checker does not execute CSS or JavaScript, inspect the runtime DOM or establish full WCAG conformance. An empty worklist does not establish usable keyboard operation, contrast, screen-reader behavior or successful error recovery. Keep static findings and actual user-flow observations separate.
Freeze the pages and the user task before comparing builds
Name the actual task, such as finding a booking field, correcting an invalid value and reaching the next step. Include relevant loading, empty, error and overlay states in the browser review. In review-input.json, retain a stable project id and list the authorized relative HTML pages. The input supports 1–30 unique pages; sources over 1 MB, symlinks and path traversal are rejected. This is a source directory, not an automatic public-site crawler.
Use the same intended page scope before and after a correction. A page removed from the input moves its old findings to Removed from scope; it does not become a repaired page. Finding correspondence uses a unique authored element ID or a per-tag source ordinal, so manually review matches after reordering anonymous elements.
Run the two-page example and inspect the actual difference
From the complete installed package, run these commands into new output folders. The Wayfinder pages are fictional fixtures. Do not replace your own source with them. The second command compares the improved source with the saved first report; rerunning into an occupied output folder is refused.
| Evidence | Expected fixture result | What it establishes |
|---|---|---|
| Initial source findings | 20 findings across two pages | The included rules detected these source patterns |
| Current source findings | 2 findings remain | The unnamed iframe and headerless table still need review |
| Comparison | 18 resolved; 2 persisting; 0 new | A bounded change within the retained scope |
| Live categories | All 8 remain not-run | No browser or assistive-technology result was invented |
python3 scripts/build-review.py --input examples/review.json --root examples/site-before --output ./review-before
python3 scripts/build-review.py --input examples/review.json --root examples/site-after --baseline review-before/report.json --output ./review-afterFollow each finding back to its own source bytes
Open review-after/index.html. Search a rule, filter severity and switch Current, New, Resolved and Removed from scope. Select the iframe-title finding and compare its page, source line and inert excerpt with booking.html. Inspect its own SHA-256 rather than assuming every panel shows the current build. Resolved findings retain the old baseline hash.
Prioritize the blocked task. Supply useful control names and native semantics, connect labels and ARIA references, and review document language, headings, landmarks and table relationships in context. Presence is only a starting check: an alt attribute can exist yet describe the wrong image, and an empty alt is a decorative-image claim that needs contextual review.
Review semantic tokens and rendered controls in a design-system handoff
Record actual browser observations without filling every row with pass
For each observed pass or fail, write a concrete note naming the source/build, browser or tool, action and result. Download manual-review.json, then rebuild with --manual against the exact same source hashes. The importer rejects changed hashes or a pass/fail without a note. It checks the note’s structure and provenance, not whether the described inspection was honest or complete.
- Keyboard and focus: operate the actual task without a pointer; inspect focus order, visible focus, overlay entry and return, and escape behavior where applicable.
- Zoom and contrast: inspect 200% text zoom, narrow reflow and rendered foreground/background pairs. Source attribute presence does not measure these results.
- Screen reader and errors: check names, roles, announcements, required fields, invalid values and recovery in the intended application. Leave checks not-run when the required tool or review has not been used.
- Motion and dynamic changes: inspect reduced-motion preferences, dialogs and updates that occur after interaction. A source-only scan does not exercise those states.
python3 scripts/build-review.py --input examples/review.json --root examples/site-after --baseline review-before/report.json --manual manual-review.json --output ./review-with-observationsHand off the worklist, scope and remaining checks
Deliver report.json, findings.csv, remediation.md, the review input, inert sources/*.html.txt copies, the supplied baseline and delivery-manifest.json. Keep the completed manual review when one exists. Review every remaining finding and unexplored state before describing the result. Static counts are not a universal accessibility grade.
For CI, --fail-on serious or --fail-on moderate returns exit 2 when qualifying findings remain after a valid report is written. Input errors do not create a delivery. Keep that distinction in automation, and do not treat a generated report as a successful gate merely because files exist.
Keep a reproducible before-and-after defect record
Check localized labels and placeholder handoff as another review task