real-a11y-dev

Real A11y

Accessibility tooling that works in the real world — semantic tree extraction, testing utilities, React integration, a Storybook panel, and a Chrome extension, all powered by the same engine.

Beta. APIs across the 0.1.x line may change before 0.2.0. Feedback and issues very welcome — see Status below.

Semantic Navigator replaces the visual browser rendering with an interactive DOM/accessibility tree view. Click links, fill forms, activate buttons — all through the tree. If your page doesn’t make sense as a tree, it doesn’t make sense at all.

Why

Existing tools (Chrome DevTools, Axe, WAVE) show the accessibility tree as a passive inspector. Semantic Navigator flips this: the tree is the interface. This enforces good semantic HTML by making bad structure immediately obvious through use.

Packages

Package	Description	npm
@real-a11y-dev/core	Tree extraction, data model, interaction engine
@real-a11y-dev/semantic-navigator-ui	Preact tree rendering components
@real-a11y-dev/inspector	Framework-agnostic interactive accessibility tree panel
@real-a11y-dev/testing	Headless audit helpers — snapshots, assertions, flow() chain
@real-a11y-dev/react	React hooks and <SemanticNavigator /> component
@real-a11y-dev/storybook-addon	Per-story A11y tree panel for Storybook 8+
extension	Chrome extension with Side Panel UI	—

Quick start

npm package

npm install @real-a11y-dev/inspector

import { createInspector } from "@real-a11y-dev/inspector";

const nav = createInspector({
  root: document.getElementById("app"),
  container: document.getElementById("tree-panel"),
  viewMode: "a11y", // "dom" | "a11y"
  interactive: true,
  theme: "auto",    // "light" | "dark" | "auto"
});

nav.mount();

Chrome extension

1. Clone this repo
2. Run pnpm install && pnpm build
3. Open chrome://extensions, enable Developer mode
4. Click “Load unpacked” and select packages/extension/dist
5. Navigate to any page and click the Semantic Navigator icon to open the side panel

Features

Two tree views (toggleable)

• DOM tree — Raw HTML elements with tag names, attributes, and text content
• Accessibility tree — Roles, accessible names, and states (what screen readers see). Generic/decorative nodes are flattened out

Full interactivity

Not just viewing — interact with the page through the tree:

• Click links and buttons
• Navigate to link destinations
• Focus form inputs
• Toggle details/summary elements
• Submit forms

Keyboard navigation

Follows the WAI-ARIA TreeView pattern:

Key	Action
Arrow Down/Up	Move between nodes
Arrow Right	Expand node or move to first child
Arrow Left	Collapse node or move to parent
Enter	Activate node’s primary action
Space	Toggle expand/collapse
Home/End	Jump to first/last node
*	Expand all siblings

Search and filter

Type to search across tag names, roles, accessible names, attributes, and text content. Matching nodes and their ancestors stay visible.

Live updates

The tree automatically updates when the DOM changes (via MutationObserver with debounced re-extraction).

Node highlighting

Hover or select a node in the tree to see the corresponding element highlighted on the page.

Architecture

core ───┬── ui ──┬── inspector ──┬── react
        │        │               │
        │        └── storybook-addon
        │
        └── testing   (headless — no UI dep)

extension ──→ ui ──→ core

• core — Zero UI dependencies. Tree extraction (TreeWalker), role mapping (80+ HTML elements to ARIA roles), interaction engine (ActionDispatcher), DOM observation, query helpers (findByRole, linearize, getOutline, getTabSequence, diffTrees)
• ui — Preact components (≈3KB gzipped). TreeView, TreeNode, TreeToolbar with self-contained CSS and light/dark themes
• inspector — Framework-agnostic embed. Shadow-DOM isolation by default; opt-in host-app side effects
• testing — Headless audit helpers (auditSnapshot, assertHeadingOrder, flow(), Vitest serializer, Playwright adapter). No UI dependency
• react — useSemanticTree and useActiveModal hooks (concurrent-mode safe via useSyncExternalStore) plus <SemanticNavigator /> component
• storybook-addon — Per-story A11y tree panel for Storybook 8+
• extension — Chrome MV3. Content script extracts the tree and dispatches actions; Side Panel renders the tree UI; Background service worker routes messages

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Watch mode (all packages)
pnpm dev

Requirements

• Node.js >= 20
• pnpm >= 9

Tech stack

• TypeScript (strict mode)
• pnpm workspaces
• Preact 10 (3KB, React-compatible API)
• tsup (core, ui, npm bundling)
• Vite (extension bundling)
• Vitest + jsdom (testing)

Status

Real A11y is in public beta (0.1.x). The core extraction engine and the Chrome extension are stable and used in production; the npm packages (@real-a11y-dev/inspector, @real-a11y-dev/testing, @real-a11y-dev/react, @real-a11y-dev/storybook-addon) are newer and may have minor API changes before 0.2.0. Breaking changes will ship behind a minor bump and be called out in the changelog.

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

This site is open source. Improve this page.