CI a11y-ci
GitHub
Open source

a11y-ci Block regressions. Not developers.

CI gate for accessibility scorecards. Severity thresholds, baseline regression detection, time-boxed allowlists, and low-vision-first What/Why/Fix output.

Get started Read the Handbook

Install

pip install a11y-ci

Gate

a11y-ci gate --current a11y.scorecard.json

Baseline

a11y-ci gate --current current.json --baseline baseline.json

Core Features

Accessibility linting is only useful if it blocks regressions.

Severity Gate

Fail the build when findings meet or exceed your configured severity threshold. Default: serious.

Baseline Regression

Compare against a saved baseline. Fail if serious+ count increases or new serious+ IDs appear.

Time-Boxed Allowlists

Suppress known findings temporarily. Expired entries automatically fail the gate — no permanent suppressions.

Low-Vision-First Output

Every message follows the What/Why/Fix contract. No cryptic status codes or one-liners.

Fully Deterministic

No network calls. Same input always produces the same result. Runs anywhere Python runs.

Clear Exit Codes

Exit 0 = passed, exit 2 = input error, exit 3 = policy failure. No ambiguity.

Quick Start

Install & gate

# Install
pip install a11y-ci

# Generate scorecard with a11y-lint
a11y-lint scan output.txt --json > a11y.scorecard.json

# Gate on the scorecard
a11y-ci gate --current a11y.scorecard.json

With baseline + allowlist

# Full pipeline
a11y-ci gate \
  --current a11y.scorecard.json \
  --baseline baseline/a11y.scorecard.json \
  --allowlist a11y-ci.allowlist.json \
  --fail-on moderate

Severity Levels

Level
When to Use
critical
Only block on show-stoppers
serious
Default — blocks on barriers that affect daily use
moderate
Stricter — includes usability issues
minor
Strictest practical — catches most issues
info
Catches everything including informational notes

Exit Codes

Code
Meaning
0
All checks passed
2
Input or validation error (bad JSON, missing file, schema mismatch)
3
Policy gate failed (severity threshold, regression, or expired allowlist)

CLI Reference

a11y-ci gate --current PATH

Gate on a scorecard. Fails if findings meet or exceed the severity threshold.

--baseline PATH

Compare against a saved baseline. Fails on regression.

--allowlist PATH

Suppress known findings temporarily. Expired entries auto-fail.

--fail-on SEVERITY

Minimum severity to fail on: info | minor | moderate | serious | critical (default: serious).

Companion Tools

Tool
Description
a11y-lint
Accessibility linter for CLI output — produces scorecards
a11y-assist
Low-vision-first assistant for CLI failures
a11y-demo-site
End-to-end demo with provenance verification