Two accessibility tiers that extend
@acoyfellow/visual-diff's
structure/style/pixel cascade. Two renders can match pixel-for-pixel and share
an identical DOM structure while a screen reader reads them differently: a
button that lost its aria-expanded, a <label> that stopped pointing at its
control. Tiers S and R catch that class of difference.
| Tier | Name | Checks | Example it catches |
|---|---|---|---|
| A–C | from visual-diff | structure, style, pixel | missing element, wrong size or color, literal pixel drift |
| S | Semantic | accessible name, description, state | a Dialog trigger with no aria-expanded; a checkbox whose aria-checked is flipped |
| R | Reference graph | id-reference shape (for, aria-labelledby, and similar) |
a <label> that no longer links to its control, whatever the framework-generated id strings happen to be |
A pair passes when every tier passes: A AND B AND C AND S AND R. The
reasoning for a fail-closed AND of independent tiers is in
visual-diff's methodology.
It came out of porting one React component library to Svelte, Vue, and Solid.
The same defect kept shipping: a generated component matched its React
reference in pixels and structure but had dropped an ARIA attribute or a
label-to-control link. Each time, someone found it by hand, fixed the
compiler, and then hit the same shape of bug on the next component, because the
check itself was never written down as something runnable. This library is
that check. Every gap found while building it is recorded in
docs/explanation/limitations.md.
npm install @acoyfellow/semantic-diff
# Tier X (real-browser accessibility tree) and the examples need a pinned Chromium:
npx playwright install chromiumimport { semanticCascade } from '@acoyfellow/semantic-diff';
const golden = { elements: [{ tag: 'button', role: 'button', attrs: { 'aria-expanded': 'false' }, text: 'Add' }] };
const native = { elements: [{ tag: 'button', role: 'button', attrs: {}, text: 'Add' }] }; // aria-expanded dropped
const result = semanticCascade(golden, native);
result.pass; // false
result.tiers; // { A: true, B: true, C: null, S: false, R: true }
result.S.deltas; // [{ kind: 'accessible-state', attr: 'aria-expanded', baseline: 'false', candidate: '(absent)' }]A and B are both true: this pair is structurally and style-identical, and
visual-diff alone reports pass: true on it. Tier S is what fails it.
- Tutorials: Getting started
- How-to guides:
- Reference:
- Explanation:
npm testruns 39 unit tests across every module (test/*.test.js).npm run experimentsruns 5 hardening experiments, each written to break the tool rather than confirm it, each with a committed receipt (experiments/E-*/receipt.json):- E-REAL-DEFECT reproduces the actual homepage defects this tool was
built for.
visual-diffalone misses every one; S and R catch every one. - E-ADVERSARIAL runs 6 cases built to force false positives and negatives. It surfaced 2 real tradeoffs, documented in the limitations doc.
- E-FALSE-POSITIVE runs the id-normalization registry against 22 real observed id strings: 0 false positives, 0 false negatives.
- E-LEVERAGE-SCALE reproduces the ~650-element homepage scale and failure shape from the source project: 100% top-bucket signal in 11ms.
- E-CDP-GROUND-TRUTH drives a pinned Chromium and diffs the
axname.jsalgorithm against the browser's own computed accessibility tree. It found a role-awareness gap, now recorded in the limitations doc.
- E-REAL-DEFECT reproduces the actual homepage defects this tool was
built for.
npm run proofdrives a browser end-to-end and writesexamples/out/REPORT.html.
- A new tier joins the cascade as a hard requirement, never a soft score.
- Every capability ships proven against a known-pass and a known-broken pair.
- Every claim in this README is backed by a committed receipt or a passing test.
- The normalization registry logs every value it suppresses and why.
- No new required runtime dependency beyond
@acoyfellow/visual-diff; the browser tier is optional and loaded on demand.
MIT