Sunbelt Computer Software

@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.

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().

View all rules

Rule	Level	WCAG	Description
`navigable/document-title`	A	2.4.2	Documents must have a `<title>` element.
`navigable/bypass`	A	—	Page must have a mechanism to bypass repeated blocks.
`navigable/page-has-heading-one`	A	—	Page should contain a level-one heading.
`labels-and-names/frame-title`	A	4.1.2	Frames must have an accessible name.
`labels-and-names/frame-title-unique`	A	4.1.2	Frame titles should be unique.
`distinguishable/meta-viewport`	AA	1.4.4	Viewport meta must not disable user scaling.
`enough-time/meta-refresh`	A	2.2.1	Meta refresh must not redirect or refresh automatically.
`enough-time/meta-refresh-no-exception`	A	2.2.1	Meta refresh must not be used with a delay (no exceptions).
`enough-time/blink`	A	2.2.2	`<blink>` must not be used.
`enough-time/marquee`	A	2.2.2	`<marquee>` must not be used.
`text-alternatives/img-alt`	A	1.1.1	Images must have alternate text.
`text-alternatives/svg-img-alt`	A	1.1.1	SVG images must have an accessible name.
`text-alternatives/input-image-alt`	A	1.1.1, 4.1.2	Image inputs must have alternate text.
`text-alternatives/image-redundant-alt`	A	—	Image alt should not duplicate adjacent text.
`text-alternatives/image-alt-words`	A	—	Alt text should not contain "image", "photo", etc.
`text-alternatives/area-alt`	A	1.1.1, 4.1.2	`<area>` elements must have alt text.
`text-alternatives/object-alt`	A	1.1.1	`<object>` elements must have alt text.
`text-alternatives/role-img-alt`	A	1.1.1	`role="img"` elements must have an accessible name.
`keyboard-accessible/server-image-map`	A	2.1.1	Server-side image maps must not be used.
`labels-and-names/form-label`	A	4.1.2	Form elements must have labels.
`labels-and-names/multiple-labels`	A	—	Form fields should not have multiple labels.
`labels-and-names/input-button-name`	A	4.1.2	Input buttons must have discernible text.
`adaptable/autocomplete-valid`	AA	1.3.5	Autocomplete attribute must use valid values.
`labels-and-names/label-content-mismatch`	A	—	Accessible name must contain visible text.
`labels-and-names/label-title-only`	A	—	Forms should not use title as the only label.
`keyboard-accessible/tabindex`	A	—	tabindex should not be greater than 0.
`keyboard-accessible/focus-order`	A	—	Focusable elements must have an appropriate role.
`keyboard-accessible/nested-interactive`	A	4.1.2	Interactive controls must not be nested.
`keyboard-accessible/scrollable-region`	A	2.1.1	Scrollable regions must be keyboard accessible.
`keyboard-accessible/accesskeys`	A	—	Accesskey values must be unique.
`keyboard-accessible/focus-visible`	AA	2.4.7	Elements in focus order must have a visible focus indicator.
`navigable/heading-order`	A	—	Heading levels should increase by one.
`navigable/empty-heading`	A	—	Headings must have discernible text.
`navigable/p-as-heading`	A	—	Paragraphs should not be styled as headings.
`landmarks/landmark-main`	A	—	Page should have one main landmark.
`landmarks/no-duplicate-banner`	A	—	No duplicate banner landmarks.
`landmarks/no-duplicate-contentinfo`	A	—	No duplicate contentinfo landmarks.
`landmarks/no-duplicate-main`	A	—	No duplicate main landmarks.
`landmarks/banner-is-top-level`	A	—	Banner landmark should be top-level.
`landmarks/contentinfo-is-top-level`	A	—	Contentinfo landmark should be top-level.
`landmarks/main-is-top-level`	A	—	Main landmark should be top-level.
`landmarks/complementary-is-top-level`	A	—	Aside landmark should be top-level.
`landmarks/landmark-unique`	A	—	Landmarks of the same type should have unique labels.
`landmarks/region`	A	—	All content should be within landmarks.
`adaptable/list-children`	A	1.3.1	`<ul>` and `<ol>` must only contain valid children.
`adaptable/listitem-parent`	A	1.3.1	`<li>` must be in a `<ul>`, `<ol>`, or `<menu>`.
`adaptable/dl-children`	A	1.3.1	`<dt>` and `<dd>` must be in a `<dl>`.
`adaptable/definition-list`	A	1.3.1	`<dl>` must only contain valid children.
`distinguishable/letter-spacing`	AA	1.4.12	Letter spacing with `!important` must be at least 0.12em.
`distinguishable/line-height`	AA	1.4.12	Line height with `!important` must be at least 1.5.
`distinguishable/word-spacing`	AA	1.4.12	Word spacing with `!important` must be at least 0.16em.
`adaptable/orientation-lock`	AA	1.3.4	Page orientation must not be restricted.
`aria/aria-roles`	A	4.1.2	ARIA role values must be valid.
`aria/aria-valid-attr`	A	4.1.2	ARIA attributes must be valid (correctly spelled).
`aria/aria-valid-attr-value`	A	4.1.2	ARIA attributes must have valid values.
`aria/aria-required-attr`	A	4.1.2	Required ARIA attributes must be present.
`aria/aria-allowed-attr`	A	4.1.2	ARIA attributes must be allowed for the role.
`aria/aria-allowed-role`	A	4.1.2	ARIA role must be appropriate for the element.
`adaptable/aria-required-children`	A	1.3.1	ARIA roles must have required child roles.
`adaptable/aria-required-parent`	A	1.3.1	ARIA roles must be in required parent roles.
`aria/aria-hidden-body`	A	4.1.2	`aria-hidden` must not be on `<body>`.
`aria/aria-hidden-focus`	A	4.1.2	`aria-hidden` regions must not contain focusable elements.
`labels-and-names/aria-command-name`	A	4.1.2	ARIA commands must have an accessible name.
`labels-and-names/aria-input-field-name`	A	4.1.2	ARIA input fields must have an accessible name.
`labels-and-names/aria-toggle-field-name`	A	4.1.2	ARIA toggle fields must have an accessible name.
`labels-and-names/aria-meter-name`	A	4.1.2	ARIA meters must have an accessible name.
`labels-and-names/aria-progressbar-name`	A	4.1.2	ARIA progressbars must have an accessible name.
`labels-and-names/aria-dialog-name`	A	4.1.2	ARIA dialogs must have an accessible name.
`labels-and-names/aria-tooltip-name`	A	4.1.2	ARIA tooltips must have an accessible name.
`labels-and-names/aria-treeitem-name`	A	4.1.2	ARIA treeitems must have an accessible name.
`aria/aria-prohibited-attr`	A	4.1.2	ARIA attributes must not be prohibited for the role.
`aria/presentation-role-conflict`	A	4.1.2	Presentation role must not conflict with focusability.
`aria/presentational-children-focusable`	A	4.1.2	Presentational children must not contain focusable content.
`labels-and-names/button-name`	A	4.1.2	Buttons must have discernible text.
`labels-and-names/summary-name`	A	4.1.2	`<summary>` elements must have an accessible name.
`navigable/link-name`	A	2.4.4, 4.1.2	Links must have discernible text.
`navigable/skip-link`	A	2.4.1	Skip links must point to a valid target.
`distinguishable/link-in-text-block`	A	1.4.1	Links in text blocks must be distinguishable by more than color.
`readable/html-has-lang`	A	3.1.1	`<html>` must have a `lang` attribute.
`readable/html-lang-valid`	A	3.1.1	`lang` on `<html>` must be valid.
`readable/valid-lang`	AA	3.1.2	`lang` attribute must have a valid value on all elements.
`readable/html-xml-lang-mismatch`	A	3.1.1	`lang` and `xml:lang` must match.
`adaptable/td-headers-attr`	A	1.3.1	Table headers references must be valid.
`adaptable/th-has-data-cells`	A	1.3.1	Table headers should be associated with data cells.
`adaptable/td-has-header`	A	1.3.1	Data cells in large tables should have associated headers.
`adaptable/scope-attr-valid`	A	1.3.1	`scope` attribute must have a valid value.
`adaptable/empty-table-header`	A	—	Table headers should have visible text.
`labels-and-names/duplicate-id-aria`	A	4.1.2	IDs used in ARIA must be unique.
`time-based-media/video-captions`	A	1.2.2	Videos must have captions.
`time-based-media/audio-transcript`	A	1.2.1	Audio elements should have a text alternative.
`distinguishable/color-contrast`	AA	1.4.3	Text must have sufficient color contrast.
`input-assistance/accessible-authentication`	AA	3.3.8	Password inputs must not block password managers.
`distinguishable/color-contrast-enhanced`	AAA	1.4.6	Text must have enhanced color contrast (AAA).

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

Name		Name	Last commit message	Last commit date
parent directory ..
.github/workflows		.github/workflows
scripts		scripts
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package.json		package.json
playwright.config.ts		playwright.config.ts
tsconfig.json		tsconfig.json
tsconfig.lib.json		tsconfig.lib.json
tsdown.config.ts		tsdown.config.ts
vite.config.ts		vite.config.ts
vite.iife.config.ts		vite.iife.config.ts

Environment	Support
Node.js 18+	Yes
happy-dom	Yes
jsdom	Yes
Chrome / Edge	Yes
Firefox	Yes
Safari	Yes

Sunbelt Computer Software

PL/B Language Development and Support

Navigation Menu

Repository navigation

core

core

README.md

@accesslint/core

Contents

Why @accesslint/core

Install

Quick start

Vitest + React Testing Library

Playwright

Cypress

API

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

`version: string`

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

`rules`

`getActiveRules(options?: AuditOptions): Rule[]`

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

`attachReactFiberSource(violations): Promise<void>`

Utilities

Rules

Compatibility

Development

License

Sunbelt Computer Software

PL/B Language Development and Support

FilesExpand file tree

core

Directory actions

More options

Directory actions

More options

Latest commit

History

core

Folders and files

parent directory

README.md

@accesslint/core

Contents

Why @accesslint/core

Install

Quick start

Vitest + React Testing Library

Playwright

Cypress

API

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

version: string

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

rules

getActiveRules(options?: AuditOptions): Rule[]

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

attachReactFiberSource(violations): Promise<void>

Utilities

Rules

Compatibility

Development

License

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

`version: string`

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

`rules`

`getActiveRules(options?: AuditOptions): Rule[]`

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

`attachReactFiberSource(violations): Promise<void>`