@accesslint/core

Pure accessibility rule engine for WCAG auditing. 84 bundled rules and zero browser dependencies.

Highlights

• Lightweight — 31 KB gzipped (IIFE), with zero runtime dependencies
• Chunked audits — time-budgeted processing via createChunkedAudit to avoid long tasks on the main thread
• ESM, CJS, and IIFE — tree-shakable ES modules, CommonJS for Node, and a single-file IIFE for script injection into any page
• Runs anywhere — works with happy-dom, jsdom, and real browsers with no DOM polyfills or compatibility workarounds. Run accessibility audits in Vitest and React Testing Library using the same environment as the rest of your tests
• MIT licensed

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).AccessLintCore;
    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.AccessLintCore.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): AuditResult

Run all active rules against a document and return violations.

interface AuditResult {
  url: string;
  timestamp: number;
  violations: Violation[];
  ruleCount: number;
}

interface Violation {
  ruleId: string;
  selector: string;
  html: string;
  impact: "critical" | "serious" | "moderate" | "minor";
  message: string;
  context?: string;
  element?: Element;
}

createChunkedAudit(doc: Document): ChunkedAudit

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

const audit = createChunkedAudit(document);

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

processNext();

configureRules(options: ConfigureOptions)

Customize which rules are active.

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

configureRules({
  disabledRules: ["heading-order"],
});

rules

Array of all 84 bundled Rule objects.

getActiveRules(): Rule[]

Returns bundled rules (minus disabled) plus any additional rules from configureRules().

getRuleById(id: string): Rule | undefined

Look up a rule by its ID.

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

84 rules covering WCAG 2.1 Level A and AA.

| Rule | Level | WCAG | Description | | ---- | ----- | ---- | ----------- | | document-title | A | 2.4.2 | Documents must have a <title> element. | | bypass | A | 2.4.1 | Page must have a mechanism to bypass repeated blocks. | | page-has-heading-one | A | — | Page should contain a level-one heading. | | frame-title | A | 4.1.2 | Frames must have an accessible name. | | frame-title-unique | A | 4.1.2 | Frame titles should be unique. | | meta-viewport | AA | 1.4.4 | Viewport meta must not disable user scaling. | | meta-refresh | A | 2.2.1, 2.2.4, 3.2.5 | Meta refresh must not redirect automatically. | | blink | A | 2.2.2 | <blink> must not be used. | | marquee | A | 2.2.2 | <marquee> must not be used. | | img-alt | A | 1.1.1 | Images must have alternate text. | | svg-img-alt | A | 1.1.1 | SVG images must have an accessible name. | | input-image-alt | A | 1.1.1, 4.1.2 | Image inputs must have alternate text. | | image-redundant-alt | A | — | Image alt should not duplicate adjacent text. | | image-alt-redundant-words | A | — | Alt text should not contain "image", "photo", etc. | | area-alt | A | 1.1.1, 4.1.2 | <area> elements must have alt text. | | object-alt | A | 1.1.1 | <object> elements must have alt text. | | role-img-alt | A | 1.1.1 | role="img" elements must have an accessible name. | | server-side-image-map | A | 2.1.1 | Server-side image maps must not be used. | | label | A | 4.1.2 | Form elements must have labels. | | form-field-multiple-labels | A | — | Form fields should not have multiple labels. | | select-name | A | 4.1.2 | Select elements must have a label. | | input-button-name | A | 4.1.2 | Input buttons must have discernible text. | | autocomplete-valid | AA | 1.3.5 | Autocomplete must use valid values. | | label-content-name-mismatch | A | 2.5.3 | Accessible name must contain visible text. | | label-title-only | A | — | Forms should not use title as the only label. | | tabindex | A | — | tabindex should not be greater than 0. | | focus-order-semantics | A | — | Focusable elements must have an appropriate role. | | nested-interactive | A | 4.1.2 | Interactive controls must not be nested. | | scrollable-region-focusable | A | 2.1.1 | Scrollable regions must be keyboard accessible. | | accesskeys | A | — | Accesskey values must be unique. | | heading-order | A | — | Heading levels should increase by one. | | empty-heading | A | — | Headings must have discernible text. | | p-as-heading | A | — | Paragraphs should not be styled as headings. | | landmark-one-main | A | — | Page should have one main landmark. | | landmark-no-duplicate-banner | A | — | No duplicate banner landmarks. | | landmark-no-duplicate-contentinfo | A | — | No duplicate contentinfo landmarks. | | landmark-no-duplicate-main | A | — | No duplicate main landmarks. | | landmark-banner-is-top-level | A | — | Banner landmark should be top-level. | | landmark-contentinfo-is-top-level | A | — | Contentinfo landmark should be top-level. | | landmark-main-is-top-level | A | — | Main landmark should be top-level. | | landmark-complementary-is-top-level | A | — | Aside landmark should be top-level. | | landmark-unique | A | — | Landmarks of the same type should have unique labels. | | region | A | — | All content should be within landmarks. | | list | A | 1.3.1 | Lists must only contain valid children. | | dlitem | A | 1.3.1 | <dt>/<dd> must be in a <dl>. | | definition-list | A | 1.3.1 | <dl> must only contain valid children. | | aria-roles | A | 4.1.2 | ARIA role values must be valid. | | aria-valid-attr | A | 4.1.2 | ARIA attributes must be correctly spelled. | | aria-valid-attr-value | A | 4.1.2 | ARIA attributes must have valid values. | | aria-required-attr | A | 4.1.2 | Required ARIA attributes must be present. | | aria-allowed-attr | A | 4.1.2 | ARIA attributes must be allowed for the role. | | aria-allowed-role | A | 4.1.2 | ARIA role must be appropriate for the element. | | aria-required-children | A | 4.1.2 | Required child roles must be present. | | aria-required-parent | A | 4.1.2 | Required parent roles must be present. | | aria-hidden-body | A | 4.1.2 | aria-hidden must not be on <body>. | | aria-hidden-focus | A | 4.1.2 | aria-hidden regions must not contain focusable elements. | | aria-command-name | A | 4.1.2 | ARIA commands must have an accessible name. | | aria-input-field-name | A | 4.1.2 | ARIA input fields must have an accessible name. | | aria-toggle-field-name | A | 4.1.2 | ARIA toggle fields must have an accessible name. | | aria-meter-name | A | 4.1.2 | ARIA meters must have an accessible name. | | aria-progressbar-name | A | 4.1.2 | ARIA progressbars must have an accessible name. | | aria-dialog-name | A | 4.1.2 | ARIA dialogs must have an accessible name. | | aria-tooltip-name | A | 4.1.2 | ARIA tooltips must have an accessible name. | | aria-treeitem-name | A | 4.1.2 | ARIA treeitems must have an accessible name. | | aria-prohibited-attr | A | 4.1.2 | Prohibited ARIA attributes must not be used. | | presentation-role-conflict | A | 4.1.2 | Presentation role must not conflict with focusability. | | button-name | A | 4.1.2 | Buttons must have discernible text. | | summary-name | A | 4.1.2 | <summary> elements must have an accessible name. | | link-name | A | 2.4.4, 4.1.2 | Links must have discernible text. | | skip-link | A | 2.4.1 | Skip links must point to a valid target. | | link-in-text-block | A | 1.4.1 | Links in text must be distinguishable by more than color. | | html-has-lang | A | 3.1.1 | <html> must have a lang attribute. | | html-lang-valid | A | 3.1.1 | lang on <html> must be valid. | | valid-lang | AA | 3.1.2 | lang attributes must have valid values. | | html-xml-lang-mismatch | A | 3.1.1 | lang and xml:lang must match. | | td-headers-attr | A | 1.3.1 | Table headers references must be valid. | | th-has-data-cells | A | 1.3.1 | Table headers should have data cells. | | td-has-header | A | 1.3.1 | Data cells in large tables should have headers. | | scope-attr-valid | A | 1.3.1 | scope attribute must have a valid value. | | empty-table-header | A | — | Table headers should have visible text. | | duplicate-id-aria | A | 4.1.2 | IDs used in ARIA must be unique. | | video-caption | A | 1.2.2 | Videos must have captions. | | audio-caption | A | 1.2.1 | Audio elements should have a text alternative. | | color-contrast | AA | 1.4.3 | Text must have sufficient color contrast. |

Benchmarks

Full audit (runAudit) on synthetic documents with a realistic mix of valid and invalid elements.

Concordance with axe-core

On a synthetic 500-element document exercising all rule categories:

| Metric | Value | | ------ | ----: | | Rules where both agree | 44 | | @accesslint/core only | 9 | | axe-core only | 4 | | Concordance (agreement / core findings) | 83% | | Coverage (agreement / axe findings) | 92% |

Development

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

License

MIT