Real A11y
Accessibility tooling built on the semantic tree — what assistive tech actually perceives, extracted as plain data. Reach it six ways: a shell command, a testing library, an MCP server for AI agents, an embeddable panel (plain JS, React, or Storybook), and a Chrome extension.
Beta. APIs across the 0.1.x line may change before 0.2.0. Feedback and issues very welcome — see Status.
📖 Full documentation: real-a11y.dev
Why
Rule checkers — axe, WAVE, Lighthouse — catch broken individual elements: a missing label, invalid ARIA, failing contrast. What they can't tell you is whether the heading structure is skimmable, whether tab order follows the visual flow, or where focus landed after the modal closed. Those are questions about the tree as a whole.
Real A11y extracts that tree — roles, accessible names, states, focus, live regions — so you can read it, assert on it, diff it across a change, and act through it. If a page doesn't make sense as a tree, it doesn't make sense at all.
→ Snapshots vs. other tools covers where it sits next to axe, Playwright's ARIA snapshots and screen-reader testing.
Pick your surface
Install everything under devDependencies — this is a developer-time audit suite, not runtime infrastructure. Getting started walks through each stack.
Quick start
Audit from the shell. Playwright is an optional peer dependency — install it to audit live URLs; local HTML files need no browser.
npm i -D @real-a11y-dev/cli@beta # beta dist-tag while the family is in pre-release
npx real-a11y install # downloads Chrome for Testing, first time only
npx real-a11y audit https://example.com
audit exits non-zero on screen-reader-fidelity findings — a CI gate with no config. Alongside it are perception views (tree, outline, tabs, list, inspect), act commands (click, type, focus, interact), and snapshot + diff for tracking regressions. → All commands
Assert in tests. The committed snapshot is the accessibility tree, not a DOM dump.
import { expect, test } from "vitest";
import { treeSnapshot, assertNoUnlabeledInteractive } from "@real-a11y-dev/testing";
test("the sign-in form is labeled", () => {
const root = document.querySelector("main")!;
assertNoUnlabeledInteractive(root);
expect(treeSnapshot(root)).toMatchSnapshot();
});
→ Testing docs · assertions · Playwright adapter
Hand it to an AI agent. npx -y fetches the package on first run:
npx -y @real-a11y-dev/mcp
Serves audit_page, get_semantic_tree, inspect_page and snapshot checkpoints to any MCP client. To audit pages behind a login, point REAL_A11Y_MCP_STORAGE_STATE at a saved Playwright session and set REAL_A11Y_MCP_ALLOWED_ORIGINS to pin auditing to trusted origins. → MCP docs
Embed a panel in your own app — DOM, A11y, and TAB views, live-updating, with search, role filters, focus tracking, and keyboard navigation:
import { createInspector } from "@real-a11y-dev/inspector";
createInspector({
root: document.getElementById("app"),
container: document.getElementById("tree-panel"),
viewMode: "a11y", // "dom" | "a11y" | "tab"
theme: "auto", // "light" | "dark" | "auto"
}).mount();
→ Inspector docs · using the panel, shared by every surface that renders the tree
Or install the Chrome extension — Semantic Navigator on the Web Store. Chrome may show a "Proceed with caution — not trusted by Enhanced Safe Browsing" notice on first install; that's the default for any newly listed extension, not a signal about this one. → Extension guide
Documentation
Packages
Six packages are published to npm (the table above); the Chrome extension ships on the Web Store. Eight more — the extraction engine, serializers, audit rules, snapshot engine, browser driver, session registry, ARIA validation, and the Preact tree components — are internal: their code ships bundled inside the published packages, so there is nothing to install and no version to pin. packages/ has the source, and the architecture doc explains each seam.
Migrating from a direct engine import? Seven of the eight were published before the split and are frozen at their last beta. Most of that vocabulary moved rather than vanished — @real-a11y-dev/testing carries the queries, diff, serializers and assert* primitives; @real-a11y-dev/mcp carries BrowserSession. The extractors (extractA11yTree, extractDomTree) have no published home: run real-a11y --format json or the MCP tools instead. → Full migration table
Development
pnpm install && pnpm build && pnpm test
Node.js >= 20, pnpm >= 9 — except @real-a11y-dev/cli, which requires Node.js >= 22.12 (@puppeteer/browsers). CONTRIBUTING.md is the canonical guide — project structure, the surface manifest, branch and commit conventions, and how to get a PR merged.
Status
Real A11y is in public beta (0.1.x). The extraction engine and the Chrome extension are stable and used in production; the npm packages are newer and may see minor API changes before 0.2.0.
The contract for what counts as a breaking change, what's internal vs. public, and how deprecations work is in docs/STABILITY.md.
See SECURITY.md for how to report security issues, and CODE_OF_CONDUCT.md before opening an issue or PR.
License
MIT — see LICENSE
About Real A11y
"Real Accessibility is the practice of building digital products that actually hold up for real people in real conditions."
Learn more at real-a11y.dev
