https://github.com/accesslint/a11y-agent
An AI agent for speeding up accessibility remediation
https://github.com/accesslint/a11y-agent
accessibility ai ruby
Last synced: 3 months ago
JSON representation
An AI agent for speeding up accessibility remediation
- Host: GitHub
- URL: https://github.com/accesslint/a11y-agent
- Owner: AccessLint
- Created: 2024-07-27T14:21:57.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-02-02T03:31:07.000Z (3 months ago)
- Last Synced: 2026-02-02T14:45:52.377Z (3 months ago)
- Topics: accessibility, ai, ruby
- Language: TypeScript
- Homepage:
- Size: 614 KB
- Stars: 7
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# A11y Agent
Real-time WCAG accessibility auditing for developers. Use it as a Chrome extension with a side panel, or from the terminal via the CLI.
The extension runs 80+ built-in WCAG audit rules on every page and re-audits automatically on DOM mutations (including HMR updates), so violations stay current as you code. Rules cover images, forms, ARIA, keyboard, landmarks, links, tables, language, media, and document structure.
## How it works
**Browser:** Install the extension, open the side panel, and violations appear for the active tab. Select a violation to see WCAG criteria, a description, and AI-powered remediation guidance (via Chrome's built-in language model). Click "Show element" to highlight it on the page.
**Terminal:** Run `a11y-agent ` and a browser opens automatically. Violations stream into an interactive TUI or as JSON lines.
## Components
### Chrome extension
Manifest V3 extension with a content script that runs the built-in rule engine and a side panel UI for browsing violations.
- Audits the page, shadow DOM, and same-origin iframes
- Re-audits on DOM mutations with chunked processing to avoid long tasks
- Side panel shows violations sorted by severity with a detail pane
- AI-powered remediation guidance using Chrome's LanguageModel API
- Element highlighting with DevTools-style overlay
- Copy `querySelector` expressions for any violation
- Multiple tabs tracked simultaneously
### CLI (`a11y-agent`)
Terminal interface that launches Chrome for Testing, loads the extension, and displays violations.
```
a11y-agent # Interactive TUI
a11y-agent --json # JSON lines output (auto-detected for non-TTY)
```
JSON mode is auto-detected when stdout is piped or when running inside an AI coding agent (Claude Code, Cursor, Codex).
The TUI shows violation severity, rule ID, and description. Use arrow keys to navigate, Enter to highlight in the browser, and left/right to switch tabs. A detail pane shows WCAG criteria, full description, and CSS selector.
### Bridge server (`cli/src/server.ts`)
Started automatically by the CLI on a dynamic port. Receives violations from the extension over WebSocket and streams them to the TUI. Deduplicates violations by tab, rule, and selector.
## Rules
83 rules across 11 categories:
| Category | Count | Examples |
|----------|-------|---------|
| ARIA | 22 | `aria-roles`, `aria-valid-attr`, `button-name`, `aria-hidden-focus` |
| Structure | 16 | `heading-order`, `landmark-one-main`, `region`, `list` |
| Document | 9 | `document-title`, `meta-viewport`, `bypass`, `frame-title` |
| Images | 9 | `img-alt`, `svg-img-alt`, `role-img-alt`, `area-alt` |
| Forms | 7 | `form-label`, `select-name`, `autocomplete-valid` |
| Keyboard | 5 | `tabindex`, `nested-interactive`, `scrollable-region-focusable` |
| Tables | 5 | `td-headers-attr`, `th-has-data-cells`, `scope-attr-valid` |
| Language | 4 | `html-has-lang`, `html-lang-valid`, `valid-lang` |
| Links | 3 | `link-name`, `skip-link`, `link-in-text-block` |
| Media | 2 | `video-captions`, `audio-captions` |
| Parsing | 1 | `duplicate-id-aria` |
## Development
```sh
# Build the extension
npm run build
# Build the CLI
cd cli && npm run build
# Link the CLI globally
cd cli && npm link
# Run tests
npm test
# Run benchmarks
npm run bench
```
Load the built extension from `dist/` as an unpacked extension in Chrome for standalone use.