Rules reference
This page mirrors the repo’s rule registry — the file a reviewer reads to learn a rule’s tier, basis, and spec citation without reading implementation code. The registry is the source of truth; nothing is marked shipped there that isn’t tested and CI-gated in the repo.
Removes an explicit role that duplicates the element's implicit role (<button role="button"> → <button>).
Resolves ancestor-dependent roles statically and stays silent on anything undecidable — a broken ancestor chain, a spread, a dynamic role.
Removes aria-* attributes WAI-ARIA doesn't support on the element's resolved role (<button aria-checked> → <button>).
Global ARIA properties are never touched, and an unresolved role means every aria-* on the element stays put.
Canonical lowercase for ARIA attribute names (aria-Label → aria-label) and enumerated values (aria-hidden="True" → "true").
Only ever changes character case — tested as a property, not a promise. Attribute ordering and role-value casing are deliberately out of scope.
Most carry inferred basis. Several are the interesting exception: a native fact that is still lint-tier — because the finding is advisory (idref-resolves), because only a human can author the repair (img-needs-alt, control-needs-name), or because multiple valid repairs exist and Aria refuses to pick (aria-hidden-not-focusable). Basis and tier deliberately diverge, and the registry documents each reason.
Flags a generic element (div, span) with a click handler and no role, then inspects its children to decide what to say.
A button-like element gets a role="button" suggestion; an ambiguous one is report-only. Every intrinsic diagnostic is inferred basis, so the gate keeps it a suggestion — until config declares the component with injectRole, when it graduates to a real auto-fix.
Flags an interactive control with no accessible name — an icon-only <button>/<a href>, an unlabeled <input>/<textarea>/<select>.
A name can come from text content, aria-label, a resolving aria-labelledby, or an associated <label>. A placeholder is explicitly not a name.
Flags an <img> exposed as an image with no accessible name and no decorative signal.
alt="", role="presentation", aria-label, aria-labelledby, and aria-hidden all legitimately silence it — the point is presence of some valid encoding, not the word "alt".
Flags aria-labelledby / aria-describedby / aria-controls references to an id that doesn't exist anywhere in the file.
The first rule where basis and tier deliberately diverge: the detection is a native fact, but it stays advisory because a reference can legitimately point across files. Literal-to-literal only.
Flags aria-hidden="true" on a focusable element — or on a subtree that still contains one (the common modal/dropdown bug).
A "focusable ghost" a keyboard user can reach but assistive tech can't see. Report-only because several valid repairs exist and which is right depends on intent the tool can't see.
This page is generated from a structured snapshot of the registry (see data/rules.ts in the site repo), checked against the live registry by a drift script. If the registry and this page ever disagree, the registry wins.