| name | a11y-audit |
| description | Accessibility auditing: WCAG compliance checking, contrast ratios, ARIA labels, keyboard navigation, semantic HTML, screen reader compatibility. |
| category | frontend |
| maturity | stable |
| tags | ["accessibility","wcag","aria","contrast-ratio","keyboard-nav"] |
a11y-audit
Accessibility auditing: WCAG compliance checking, contrast ratios, ARIA labels, keyboard navigation, semantic HTML, screen reader compatibility.
Use When
- Auditing web pages for accessibility compliance
- Checking color contrast ratios against WCAG standards
- Verifying ARIA attributes and landmark usage
- Ensuring keyboard navigability
- Meeting WCAG 2.1 AA standards
- Reviewing HTML for semantic correctness and screen reader compatibility
Scripts
contrast-checker.py
Calculates WCAG contrast ratios between foreground and background colors. Pure Python, no dependencies.
Single pair:
python3 scripts/contrast-checker.py --fg "#333333" --bg "#ffffff"
Batch mode (reads JSON file with array of {"fg": "#hex", "bg": "#hex", "label": "optional"} objects):
python3 scripts/contrast-checker.py --batch colors.json
Output includes:
- Contrast ratio (e.g., 12.63:1)
- Pass/fail for AA normal text (≥4.5:1), AA large text (≥3:1)
- Pass/fail for AAA normal text (≥7:1), AAA large text (≥4.5:1)
html-a11y-scan.py
Scans an HTML file for common accessibility issues. Uses Python's built-in html.parser.
python3 scripts/html-a11y-scan.py page.html
python3 scripts/html-a11y-scan.py page.html --format json
python3 scripts/html-a11y-scan.py page.html --format text
Checks for:
- Images without
alt attributes (critical)
- Form inputs without labels or
aria-label (critical)
- Missing
lang attribute on <html> (critical)
- Empty links or buttons (warning)
- Skipped heading levels (warning)
- Tables without
<th> headers (warning)
- Missing ARIA landmarks:
main, nav, banner, contentinfo (info)
Output (JSON by default): array of issues with severity, element, line, issue, and suggestion fields.
keyboard-nav-checklist.sh
Generates a Markdown checklist for manual keyboard navigation testing.
bash scripts/keyboard-nav-checklist.sh
bash scripts/keyboard-nav-checklist.sh --output checklist.md
Covers: focus management, tab order, focus indicators, modal behavior, keyboard traps, skip links, and more.
References
- wcag-quickref.md — WCAG 2.1 AA requirements organized by principle (Perceivable, Operable, Understandable, Robust)
- aria-patterns.md — Common ARIA patterns with correct role/state/property usage for tabs, modals, accordions, menus, comboboxes
Examples
Quick contrast check
python3 scripts/contrast-checker.py --fg "#767676" --bg "#ffffff"
Full page audit
python3 scripts/html-a11y-scan.py mypage.html --format text
Batch color audit for a design system
[
{ "fg": "#333333", "bg": "#ffffff", "label": "body text" },
{ "fg": "#767676", "bg": "#ffffff", "label": "muted text" },
{ "fg": "#ffffff", "bg": "#0066cc", "label": "button text" }
]
python3 scripts/contrast-checker.py --batch design-colors.json
Dependencies
- Python 3.6+ (standard library only)
- Bash (for keyboard checklist)
