audit-core

A framework-agnostic accessibility audit engine for the web. Point it at a DOM, get back structured violations, passes, and incomplete checks — ready to power whatever interface you're building on top.

---

Installation

npm install audit-core

---

Quick start

import { createAuditor } from 'audit-core'

const auditor = createAuditor()
const results = await auditor.run(document)

console.log(results.violations)
// [
//   {
//     ruleId: 'contrast',
//     impact: 'serious',
//     title: 'Insufficient text contrast',
//     nodes: [
//       {
//         selector: 'p.subtitle',
//         reason: 'Lc 42 — below the recommended Lc 60 for UI text',
//         suggestion: 'Darken the text color or lighten the background to reach Lc 60+',
//       }
//     ]
//   }
// ]

---

Configuration

const auditor = createAuditor({
  // 'apca' (default) or 'wcag'
  contrastAlgorithm: 'wcag',

  // run only specific rules by ID — omit to run all
  rules: ['contrast', 'alt-text'],

  // CSS selectors to exclude from all checks
  exclude: ['.third-party-widget', '#cookie-banner'],
})

Available rule IDs

ID	What it checks
contrast	Text contrast against background (APCA or WCAG)
alt-text	Images with missing or non-descriptive alt attributes
heading-hierarchy	Heading levels that skip or are structurally invalid
landmarks	Presence and correct use of ARIA landmark regions
focus-visible	Interactive elements with no visible focus indicator
touch-target	Interactive elements below minimum tap target size
motion	Animations without a prefers-reduced-motion override
form-labels	Form inputs without an accessible label

---

Understanding results

interface AuditResult {
  violations: Violation[]  // rules that failed — fix these
  passes: string[]         // rule IDs that passed
  incomplete: {            // rules that need manual review
    ruleId: string
    reason: string         // why it couldn't be fully evaluated
  }[]
  meta: {
    algorithm: 'apca' | 'wcag'
    rulesRun: number
    timestamp: number
  }
}

incomplete means one of two things:

1. The rule found something it couldn't evaluate automatically (e.g. an image with a suspiciously generic alt text like alt="image" that a human should review)
2. The rule requires a real browser environment to run reliably (e.g. touch target sizes in a headless context)

Either way, it's not a pass — it's a flag for human review. The reason field explains what happened.

---

Using the DOM snapshot utility

If you want to capture a serialised snapshot of the page — useful for logging, debugging, or feeding into an LLM for richer advice — audit-core exports a captureSnapshot helper:

import { createAuditor, captureSnapshot } from 'audit-core'

const snapshot = captureSnapshot(document)
const auditor = createAuditor()
const results = await auditor.run(document)

// send both to your backend, an LLM, or save for later

---

Why another accessibility tool?

Most existing tools are WCAG compliance checkers. That's useful, but WCAG 2.x has real limitations — it was written before smartphones, it ignores font weight and size when evaluating contrast, and it produces false passes for color combinations that are genuinely hard to read.

audit-core defaults to APCA (Accessible Perceptual Contrast Algorithm) — a perceptually uniform contrast model built on modern vision science, and the candidate replacement for WCAG's contrast formula in WCAG 3.0. WCAG 2.x is still available for teams that need it for legal compliance.

The engine also adapts to its environment automatically. Rules that require a real rendered layout (touch targets, focus styles) behave differently in a headless context than in a live browser — and are honest about it instead of silently returning wrong results.

---

APCA vs WCAG

By default, audit-core uses APCA for contrast evaluation. Here's what that means in practice:

	WCAG 2.x	APCA
Output	Ratio (e.g. 4.5:1)	Lc value (e.g. Lc 75)
Font-aware	No	Yes — threshold varies by size and weight
Dark mode	Unreliable	Handles correctly
Legal compliance	Yes (ADA, EN 301 549)	Not yet — WCAG 3.0 is pending

If your users need to demonstrate legal compliance, switch to wcag:

const auditor = createAuditor({ contrastAlgorithm: 'wcag' })

---

Environment behaviour

audit-core detects whether it's running in a real browser or a headless environment automatically, using the navigator.webdriver flag set by the W3C WebDriver spec. You don't need to configure this.

Rules that depend on rendered layout or CSS pseudo-classes (:focus, :focus-visible) will return incomplete in headless environments rather than producing unreliable results.

---

Contributing

Contributions are welcome. If you want to add a rule, the pattern is straightforward — each rule is an object with an id and an evaluate function. See the existing rules for examples and the CLAUDE.md for the full technical spec.

Please open an issue before starting work on a significant change.

# install dependencies
npm install

# run tests
npm test

# build
npm run build

---

Roadmap

• Cognitive load scoring
• Reading level analysis
• Color vision deficiency simulation
• WCAG AAA rule coverage
• i18n for violation messages

---

License

MIT