Best-practice rules
Every best-practice rule with its outcome class, source and reason.
A best-practice rule is anchored to the nearest WCAG success criterion without proving a breach of it. This page lists every such rule with what it reports today. It is the single source behind is_convention_rule (#919).
- Outcome:
failis a confirmed violation and counts in the score;reviewis a hint that needs a person.fail + reviewmeans both occur depending on the case. - Source:
barrierlabrules live in the shared library (a11y-rules) and change there first;localrules need the running browser or the AX tree and live in this repository. - Convention: the finding is never BFSG-relevant and raises no legal flag (#704).
- Keyword: the finding carries the
best-practicetag.names/title-onlyis the one row without it.
This page records the current classification; it does not change one.
| Rule | Criterion | Outcome | Source | Convention | Keyword | Reason |
|---|---|---|---|---|---|---|
aria/role-redundant |
4.1.2 | review | barrierlab | no | yes | The role is correct, 4.1.2 is met; ARIA in HTML merely discourages repeating the implicit role. |
description-duplicates-name |
4.1.2 | fail | local | yes | yes | The element has a name; a description that repeats it is redundant, not a missing name (#713). Anchored to 4.1.2 without breaching it. |
display/init-missing |
2.2.2 | fail | local | yes | yes | BarrierLab display-mode convention (#653): not a WCAG requirement, anchored to the nearest criterion and reported only on pages that use the convention. |
display/text-hidden |
1.1.1 | fail + review | local | yes | yes | BarrierLab display-mode convention (#653): not a WCAG requirement. A text layer removed from assistive technology is a fail; one that a rendered element still references by aria-describedby or aria-details is already a review note (#704). |
display/text-media-visible |
2.2.2 | fail | local | yes | yes | BarrierLab display-mode convention (#653): not a WCAG requirement, anchored to the nearest criterion and reported only on pages that use the convention. |
display/text-not-visible |
1.1.1 | fail | local | yes | yes | BarrierLab display-mode convention (#653): not a WCAG requirement, anchored to the nearest criterion and reported only on pages that use the convention. |
display/toggle-missing |
2.2.2 | fail | barrierlab | yes | yes | BarrierLab display-mode convention (#653): not a WCAG requirement, anchored to the nearest criterion and reported only on pages that use the convention. |
headings/h1-missing |
1.3.1 | review | barrierlab | no | yes | A correctly marked-up h2 is programmatically determinable as a heading (1.3.1); WCAG does not require a particular heading level. |
headings/skip-level |
1.3.1 | review | barrierlab | no | yes | 1.3.1 requires determinable levels, not gapless ones; G141 is sufficient, not mandatory. |
landmarks/banner-duplicate |
1.3.1 | review | barrierlab | no | yes | Several banner landmarks are WAI-ARIA practice; no success criterion limits their number (axe landmark-no-duplicate-banner is best practice). |
landmarks/content-outside |
1.3.1 | review | barrierlab | no | yes | No criterion requires content to sit in landmarks (axe region is best practice). |
landmarks/contentinfo-duplicate |
1.3.1 | review | barrierlab | no | yes | Several contentinfo landmarks are WAI-ARIA practice; no success criterion limits their number (axe landmark-no-duplicate-contentinfo is best practice). |
landmarks/main-duplicate |
1.3.1 | review | barrierlab | no | yes | HTML forbids multiple visible main elements, WCAG does not (4.1.1 was dropped). |
landmarks/main-missing |
2.4.1 | review | barrierlab | no | yes | 1.3.1 does not require landmarks; 2.4.1 is also met via headings (H69) or a skip link (G1). |
landmarks/not-top-level |
1.3.1 | review | barrierlab | no | yes | No criterion requires landmarks to be top-level (axe landmark-*-is-top-level is best practice). |
lists/empty |
1.3.1 | review | barrierlab | no | yes | An empty list withholds no information. |
lists/role-redundant |
4.1.2 | review | barrierlab | no | yes | With visible markers role=“list” repeats the implicit role and restores nothing; 4.1.2 is met. |
names/title-only |
4.1.2 | review | barrierlab | yes | no | title is a valid name source (H65), so 4.1.2 is met; the tooltip is only reachable by mouse hover (#711). The library reports a review hint without the best-practice keyword. |
patterns/tooltip-unreferenced |
1.4.13 | review | barrierlab | no | yes | 1.4.13 governs appearing and disappearing on hover and focus, not the association. |
viz/caption-missing |
1.1.1 | fail | barrierlab | yes | yes | BarrierLab display-mode convention (#653): not a WCAG requirement, anchored to the nearest criterion and reported only on pages that use the convention. |
viz/static-missing |
2.2.2 | fail | barrierlab | yes | yes | BarrierLab display-mode convention (#653): not a WCAG requirement, anchored to the nearest criterion and reported only on pages that use the convention. |
viz/table-missing |
1.3.1 | review | barrierlab | yes | yes | BarrierLab display-mode convention (#653): not a WCAG requirement; a review hint because a few values are also carried by a sentence. |
viz/text-missing |
1.1.1 | fail | barrierlab | yes | yes | BarrierLab display-mode convention (#653): not a WCAG requirement, anchored to the nearest criterion and reported only on pages that use the convention. |
zoom/viewport-missing |
1.4.4 | review | barrierlab | no | yes | Without a viewport declaration zooming stays possible (1.4.4) and reflow is measured in the browser (1.4.10); the declaration does not touch either. |
zoom/viewport-scale-limited |
1.4.4 | review | barrierlab | yes | yes | A maximum-scale of at least 2 does not block zooming under 1.4.4; the 500 % limit is a recommendation. |