Skip to content

About

Two fail-closed accessibility/semantic tiers (accessible name/description/state + id-reference-graph shape) extending @acoyfellow/visual-diff's 3-tier cascade to a 5-tier 'means the same thing' verdict.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

Repository files navigation

semantic-diff

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.

Why this exists

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.

Install

npm install @acoyfellow/semantic-diff
# Tier X (real-browser accessibility tree) and the examples need a pinned Chromium:
npx playwright install chromium

Quick look

import { 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.

Documentation

Receipts

  • npm test runs 39 unit tests across every module (test/*.test.js).
  • npm run experiments runs 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-diff alone 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.js algorithm against the browser's own computed accessibility tree. It found a role-awareness gap, now recorded in the limitations doc.
  • npm run proof drives a browser end-to-end and writes examples/out/REPORT.html.

Design principles (inherited from visual-diff, applied one tier up)

  1. A new tier joins the cascade as a hard requirement, never a soft score.
  2. Every capability ships proven against a known-pass and a known-broken pair.
  3. Every claim in this README is backed by a committed receipt or a passing test.
  4. The normalization registry logs every value it suppresses and why.
  5. No new required runtime dependency beyond @acoyfellow/visual-diff; the browser tier is optional and loaded on demand.

License

MIT

About

Two fail-closed accessibility/semantic tiers (accessible name/description/state + id-reference-graph shape) extending @acoyfellow/visual-diff's 3-tier cascade to a 5-tier 'means the same thing' verdict.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages