a11y-commit-validator

Pre-commit accessibility validator for HTML, JSX, JS and Liquid files.
Blocks Git commits that contain WCAG violations — with optional GitHub Copilot-powered AI fix suggestions.

What it does

Every time you run git commit, this tool:

1. Detects which .html, .jsx, .js, and .liquid files you've staged
2. Scans them for WCAG 2.1 / 2.2 accessibility violations using:
   • axe-core (deep audit for HTML via jsdom)
   • eslint-plugin-jsx-a11y (AST-level JSX/React analysis)
   • Regex rules (custom patterns for Liquid + extra JSX checks)
3. Explains every issue and suggests a fix (via GitHub Copilot AI or built-in rules)
4. Blocks the commit if issues are found — and optionally auto-fixes them

Installation

npm install --save-dev a11y-commit-validator

Wire it up as a pre-commit hook (Husky)

npx husky install
npx husky add .husky/pre-commit "npx validate-a11y"

Or add it directly in .husky/pre-commit:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx validate-a11y

Without Husky (manual)

Add to package.json:

{
  "scripts": {
    "validate-a11y": "validate-a11y"
  }
}

Rules checked

Plus all axe-core WCAG 2.0/2.1/2.2 rules for HTML files, and all jsx-a11y recommended rules for JSX/JS files.

GitHub Copilot AI suggestions (optional)

Set a GITHUB_TOKEN in a .env file at the root of your project:

GITHUB_TOKEN=ghp_your_token_here

When set, the tool calls the GitHub Models API (Copilot-powered) to give you a contextual one-sentence explanation and a corrected code snippet for every violation found.

Without a token, the tool still works — it uses built-in rule-based suggestions instead.

You can also choose the model:

A11Y_COPILOT_MODEL=gpt-4o

Default: gpt-4o-mini

Example output

╔══════════════════════════════════════════╗
║   ♿  A11Y COMMIT VALIDATOR  v1.0.0       ║
╚══════════════════════════════════════════╝

✔ Found 2 file(s) to scan

  📄 src/index.html
  📄 components/Button.jsx

♿ Accessibility Issues Found (2):

────────────────────────────────────────────────────────────
[1] img-missing-alt
    File    : src/index.html
    Issue   : <img> tag missing alt attribute
    Found   : <img src="banner.jpg" class="hero">
    WCAG    : wcag2a, wcag111

[2] jsx-a11y/anchor-is-valid
    File    : components/Button.jsx
    Issue   : Anchors must have content and the content must be accessible
    Found   : Line 14, Col 5
────────────────────────────────────────────────────────────

[a11y] ✖ Accessibility issues found. Commit blocked.
[a11y]   Fix the issues above, then re-run: git add . && git commit

Supported file types

Programmatic API

const { run } = require('a11y-commit-validator');
await run();

const { scanFile } = require('a11y-commit-validator/src/scanner');
const issues = await scanFile('src/index.html');

License

MIT — Rohit Sarkar