A11y Audit

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 `` (critical)
• Empty links or buttons (warning)
• Skipped heading levels (warning)
• Tables without `` 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"
# Ratio: 4.54:1 — AA normal: PASS, AA large: PASS, AAA normal: FAIL, AAA large: PASS

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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JansenAnalytics
• Source: JansenAnalytics/claudex
• License: MIT

Install and usage instructions live in the source repository linked above.