🛫 a11y-pilot

Your accessibility co-pilot for the terminal. AI-powered CLI that scans frontend codebases for accessibility issues and auto-fixes them using GitHub Copilot CLI.

What is a11y-pilot?

a11y-pilot is a CLI tool that works like ESLint for accessibility. Run it in any frontend project directory to:

1. Scan your HTML, JSX, and TSX files for accessibility violations
2. Report issues with file, line number, severity, and WCAG references
3. Auto-fix issues by invoking GitHub Copilot CLI as the refactoring engine

It catches real problems that affect real users — missing alt text, non-semantic buttons, unlabeled form inputs, broken heading hierarchies, and more.

Why?

95%+ of websites fail basic accessibility checks (WebAIM Million Report). Most developers don't skip accessibility on purpose — they just don't have the tools that make it easy. a11y-pilot brings a11y linting right into your terminal workflow, and uses Copilot CLI to fix issues intelligently.

Installation

# Install globally
npm install -g a11y-pilot

# Or use directly with npx (no install needed)
npx a11y-pilot scan ./src

Quick Start

# Scan your frontend project
a11y-pilot scan ./src

# Scan a specific file
a11y-pilot scan ./src/App.tsx

# Show Copilot CLI fix commands for each issue
a11y-pilot scan ./src --fix

# Auto-fix all issues using GitHub Copilot CLI
a11y-pilot fix ./src

# Or use the scan command with --auto-fix flag
a11y-pilot scan ./src --auto-fix

Note: Auto-fix requires GitHub Copilot CLI to be installed and authenticated.

Commands

scan [path]

Scan files for accessibility issues.

a11y-pilot scan                      # Scan current directory
a11y-pilot scan ./src/components     # Scan specific directory
a11y-pilot scan ./src/App.tsx        # Scan a single file

Flags:

| Flag | Description | |------|-------------| | -r, --rules <rules> | Comma-separated rule IDs to check (e.g., img-alt,no-div-button) | | -f, --format <format> | Output format: text (default) or json | | --fix | Show Copilot CLI commands for each issue | | --auto-fix | Invoke Copilot CLI to auto-fix issues | | --dry-run | Preview what auto-fix would do (no changes) | | --one-by-one | Fix issues individually instead of batching |

fix [path]

Convenience command — scans and auto-fixes in one step.

a11y-pilot fix ./src
a11y-pilot fix ./src --dry-run

rules

List all available accessibility rules.

a11y-pilot rules

Rules

a11y-pilot ships with 8 high-impact accessibility rules:

| Rule | Severity | WCAG | What it catches | |------|----------|------|----------------| | img-alt | error | 1.1.1 | <img> without alt attribute | | button-content | error | 4.1.2 | Empty <button> with no text/aria-label | | no-div-button | error | 4.1.2, 2.1.1 | <div>/<span> with onClick but no role/tabIndex | | form-label | error | 1.3.1, 4.1.2 | <input> without associated label or aria-label | | heading-order | warning | 1.3.1 | Skipped heading levels (h1 → h3) | | anchor-content | error | 2.4.4, 4.1.2 | <a> with no text content or aria-label | | no-autofocus | warning | 3.2.1 | Usage of autoFocus attribute | | semantic-nav | warning | 1.3.1, 2.4.1 | Navigation links not wrapped in <nav> |

Copilot CLI Integration

a11y-pilot uses GitHub Copilot CLI as its AI-powered fix engine. When you run --auto-fix or a11y-pilot fix:

1. Detection — a11y-pilot scans your code and identifies issues
2. Prompt Engineering — For each issue, it builds a precise, context-rich prompt
3. Copilot Invocation — It spawns copilot CLI with the fix prompt
4. Intelligent Fixing — Copilot CLI reads your file, understands the context, and makes the fix
5. Progress Reporting — You see real-time status of each fix

How it works under the hood

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   a11y-pilot    │────▶│  Issue detected   │────▶│  Build prompt   │
│   scanner       │     │  (rule engine)    │     │  (context-rich) │
└─────────────────┘     └──────────────────┘     └────────┬────────┘
                                                          │
                                                          ▼
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   File fixed!   │◀────│  Copilot applies  │◀────│  copilot CLI    │
│   ✔ Report      │     │  the fix          │     │  invoked        │
└─────────────────┘     └──────────────────┘     └─────────────────┘

Prerequisites

• Node.js 18+
• GitHub Copilot CLI installed and authenticated (required only for auto-fix)

# Install a11y-pilot
npm install -g a11y-pilot

# Install & authenticate Copilot CLI (for auto-fix)
# See: https://github.com/github/copilot-cli
copilot auth login

JSON Output (CI-friendly)

a11y-pilot scan ./src --format json

Outputs structured JSON:

{
  "version": "1.0.0",
  "timestamp": "2026-02-14T10:00:00.000Z",
  "summary": {
    "filesScanned": 23,
    "filesWithIssues": 5,
    "totalErrors": 12,
    "totalWarnings": 3,
    "totalIssues": 15
  },
  "files": {
    "src/Hero.tsx": [
      {
        "ruleId": "img-alt",
        "severity": "error",
        "message": "<img> is missing the `alt` attribute",
        "line": 12,
        "fix": "Add alt=\"descriptive text\" or alt=\"\" if decorative",
        "copilotCommand": "copilot \"In file src/Hero.tsx at line 12...\""
      }
    ]
  }
}

Supported File Types

| Extension | Parser | |-----------|--------| | .jsx | Babel (JSX) | | .tsx | Babel (TSX + TypeScript) | | .html, .htm | htmlparser2 | | .vue | htmlparser2 (template) | | .svelte | htmlparser2 (template) | | .astro | htmlparser2 (template) |

Project Structure

a11y-pilot/
├── bin/
│   └── a11y-pilot.js            # CLI entry point
├── src/
│   ├── cli.js                   # Commander setup & orchestration
│   ├── scanner.js               # File discovery & walking
│   ├── parsers/
│   │   ├── jsx-parser.js        # JSX/TSX AST parsing
│   │   └── html-parser.js       # HTML parsing
│   ├── rules/
│   │   ├── index.js             # Rule registry
│   │   ├── img-alt.js           # Missing alt attributes
│   │   ├── button-content.js    # Empty buttons
│   │   ├── no-div-button.js     # Non-semantic click handlers
│   │   ├── form-label.js        # Unlabeled form inputs
│   │   ├── heading-order.js     # Heading hierarchy
│   │   ├── anchor-content.js    # Empty links
│   │   ├── no-autofocus.js      # autoFocus anti-pattern
│   │   └── semantic-nav.js      # Missing <nav> landmarks
│   ├── reporter.js              # Terminal output (colors/formatting)
│   └── copilot-bridge.js        # Copilot CLI invocation engine
├── test/
│   └── fixtures/                # Sample files with a11y issues
├── docs/
│   └── PLAN.md                  # Project plan
├── package.json
├── LICENSE
└── README.md

Built With GitHub Copilot CLI

This entire project was built using GitHub Copilot CLI as a core development tool. Copilot CLI was used for:

• Scaffolding the project structure
• Writing parser logic for JSX/TSX AST traversal
• Implementing accessibility rules with WCAG references
• Debugging edge cases in HTML parsing
• Generating test fixtures
• Writing documentation

See the submission article for terminal screenshots and a full walkthrough.

License

MIT — see LICENSE for details.

Contributing

Contributions welcome! Ideas for new rules, parser improvements, or better Copilot CLI integration are all appreciated.

# Clone the repo
git clone https://github.com/AnasMHD-Off0/a11y-pilot.git
cd a11y-pilot
npm install

# Run tests
npm test

# Scan the test fixtures during development
a11y-pilot scan test/fixtures/