@accesslint/core

Pure accessibility rule engine with zero browser dependencies. Covers WCAG 2.2 Level A and AA with best-practice rules included.

Building with AI coding agents? @accesslint/mcp wraps this engine as a Model Context Protocol server. The Claude Code plugin installs it in one step.

Looking for CI? AccessLint runs accessibility checks on every pull request and posts review comments directly on your GitHub PRs.

Contents

• Why @accesslint/core
• Install
• Quick start
• API
• Source mapping (React)
• Rules
• Compatibility
• Development

Why @accesslint/core

• Synchronous API — runAudit() returns results immediately, no async/await needed
• Works with happy-dom — full support for happy-dom, jsdom, and real browsers with no polyfills or workarounds, including color contrast checks in virtual DOMs
• Lightweight — 46 KB gzipped (IIFE), zero runtime dependencies
• Chunked audits — time-budgeted processing via createChunkedAudit to avoid long tasks on the main thread
• Source mapping (React) — opt-in attachReactFiberSource walks React DevTools fibers and resolves bundled-chunk URLs through their sourcemaps so violations point at real source files (src/Card.tsx:42:7) instead of opaque selectors
• ESM, CJS, and IIFE — tree-shakable ES modules, CommonJS for Node, and a single-file IIFE for script injection into any page

Install

npm install @accesslint/core

Quick start

Vitest + React Testing Library

Audit a rendered component in your existing test suite:

import { render } from "@testing-library/react";
import { runAudit } from "@accesslint/core";
import { LoginForm } from "./LoginForm";

test("LoginForm has no accessibility violations", () => {
  const { container } = render(<LoginForm />);
  const { violations } = runAudit(container.ownerDocument);
  expect(violations).toEqual([]);
});

Playwright

Inject the library into the page and audit the live DOM:

// a11y.spec.ts
import { test, expect } from "@playwright/test";

const iife = require.resolve("@accesslint/core/iife");

test("page has no accessibility violations", async ({ page }) => {
  await page.goto("https://example.com");

  await page.addScriptTag({ path: iife });

  const violations = await page.evaluate(() => {
    const { runAudit } = (window as any).AccessLint;
    return runAudit(document).violations.map((v: any) => ({
      ruleId: v.ruleId,
      message: v.message,
      selector: v.selector,
      impact: v.impact,
    }));
  });

  expect(violations).toEqual([]);
});

Cypress

Inject the library into the page and audit the live DOM:

// cypress/e2e/a11y.cy.js
Cypress.Commands.add("audit", () => {
  return cy.readFile("node_modules/@accesslint/core/dist/index.iife.js").then((src) => {
    return cy.window().then((win) => {
      win.eval(src);
      const result = win.AccessLint.runAudit(win.document);
      return result.violations;
    });
  });
});

describe("sample.html accessibility audit", () => {
  beforeEach(() => {
    cy.visit("sample.html");
  });

  it("has no accessibility violations", () => {
    cy.audit().should("have.length", 0);
  });
});

API

runAudit(doc: Document, options?: AuditOptions): AuditResult

Run all active rules against a document and return violations. All options are per-call and non-mutating — no global state is touched.

interface AuditOptions {
  additionalRules?: Rule[];
  disabledRules?: string[];
  includeAAA?: boolean;
  componentMode?: boolean;
  locale?: string;
}

interface AuditResult {
  url: string;
  timestamp: number;
  testEngine: TestEngine;
  testEnvironment: TestEnvironment;
  violations: Violation[];
  ruleCount: number;
  skippedRules: { ruleId: string; error: string }[];
}

interface TestEngine {
  name: "accesslint";
  version: string;
}

interface TestEnvironment {
  userAgent: string;
  windowWidth: number;
  windowHeight: number;
  orientationAngle: number;
  orientationType: string;
}

testEngine.version is the @accesslint/core engine version. testEnvironment describes the audited document's realm; unreadable values fall back to "", 0, and "portrait-primary".

interface Violation {
  ruleId: string;
  selector: string;
  html: string;
  impact: "critical" | "serious" | "moderate" | "minor";
  message: string;
  context?: string;
  element?: Element;
  /** Source-code locations for the violating element, when populated by `attachReactFiberSource`. */
  source?: SourceLocation[];
}

interface SourceLocation {
  file: string;
  line: number;
  column?: number;
  /** Component or function name, when known (e.g. "ProductCard"). */
  symbol?: string;
  /** 0 = JSX literal that produced the element; 1+ = enclosing component(s). */
  ownerDepth: number;
}

version: string

The engine version, mirroring axe.version. Also available as AccessLint.version on the standalone (IIFE) global.

import { version } from "@accesslint/core";

createChunkedAudit(doc: Document, options?: AuditOptions): ChunkedAudit

Create a chunked audit that processes rules in time-boxed batches to avoid long tasks.

const audit = createChunkedAudit(document, { includeAAA: true });

function processNext() {
  const hasMore = audit.processChunk(16); // 16ms budget per frame
  if (hasMore) requestAnimationFrame(processNext);
  else console.log(audit.getViolations());
}

processNext();

rules

Array of all bundled Rule objects.

getActiveRules(options?: AuditOptions): Rule[]

Returns bundled rules filtered by the given options: excludes AAA-level rules unless includeAAA is set, excludes page-level rules when componentMode is true, excludes ids in disabledRules, and appends additionalRules. When locale is passed, returns shallow-cloned rules with translated descriptions and guidance.

getRuleById(id, options?: { locale?: string; additionalRules?: Rule[] }): Rule | undefined

Look up a rule by its ID. Pass locale to get the translated rule, or additionalRules to also search custom rules.

attachReactFiberSource(violations): Promise<void>

Opt-in, in-page post-processor that attaches source locations to each violation by walking React fibers. No-op on non-React pages, production builds, or when no fiber is found; never throws. Requires the JSX __source transform and dev sourcemaps (default in CRA, Next dev, Vite + React).

When the fiber carries _debugSource (Vite, CRA) it is trusted as-is; otherwise _debugStack (e.g. Next.js dev) is parsed and resolved through the chunk's .js.map.

Limitation: on the _debugSource path, dev servers that inject a per-module preamble (notably Vite, both React 18 and 19) offset the reported line/column — the file and component stay correct, but the line can point further down than the true source. The _debugStack path is unaffected.

// In a Playwright test, after the audit:
const violations = await page.evaluate(async () => {
  const { runAudit, attachReactFiberSource } = (window as any).AccessLint;
  const result = runAudit(document);
  await attachReactFiberSource(result.violations);
  return result.violations;
});

console.log(violations[0].source);
// [{ file: "src/components/ProductCard.tsx", line: 42, column: 7, symbol: "ProductCard", ownerDepth: 0 }, ...]

Utilities

Helpers for building custom rules:

• getAccessibleName(el) — compute the accessible name of an element
• getComputedRole(el) — get the computed ARIA role
• getImplicitRole(el) — get the implicit (native) ARIA role
• isAriaHidden(el) — check if an element is hidden via aria-hidden
• isValidRole(role) — check if a string is a valid ARIA role
• getAccessibleTextContent(el) — get text content respecting aria-hidden
• getSelector(el) — generate a CSS selector for an element
• getHtmlSnippet(el) — get a truncated HTML snippet of an element

Rules

Covers WCAG 2.2 Level A and AA, plus best-practice rules. One additional AAA-level rule (distinguishable/color-contrast-enhanced) is bundled but excluded by default; include it via runAudit(doc, { includeAAA: true }).

Rule IDs match the ruleId field in violations and are used with the disabledRules option and getRuleById().

Compatibility

Tested in the following environments:

Development

npm install
npm test        # 1191 tests
npm run bench   # performance benchmarks
npm run build   # produces dist/index.js, dist/index.cjs, dist/index.d.ts, dist/index.iife.js

Found a bug or have a suggestion? Open an issue.

License

MIT