How rules are organized

This describes how the 145 rules in the catalog are structured — useful for making sense of a result, or for finding the rule you're looking for. It reflects what already exists in the ruleset, not an abstract design.

Automatic vs. manual

Every rule's type is one of two kinds, and the difference is about what the rule is capable of deciding — not which outcome it happens to report:

• automatic — decides deterministically, with no heuristics and no guessing. Can report fail. cantTell still shows up here, in these situations: a real violation exists but doesn't on its own establish that the mapped WCAG criterion fails (an ARIA author requirement, or the HTML content model, whose exposed name/role/value still survives: since core 1.15, uncertainty spec-only, in the ARIA and HTML structure rules); the rule decides deterministically that a best practice is broken, claims no Success Criterion, and what it found need not harm anyone, since the role or element still reaches assistive technology as it is (aria-allowed-role, landmark-role-name-present, tagged best-practice); or the rule can only confirm a mechanism is present, while whether what's present is actually valid belongs to a sibling rule (aria-required-children, paired with aria-prohibited-children); or the rule cannot decide without a guess, so it asks instead of failing: a name that may come from a closed shadow root, from ElementInternals the engine can't read, or from content nested too deep to read (the *-name-present rules), text that may be clipped or overlap once spaced (text-spacing-content-loss), an orientation media block that turns an element other than the page's content (css-orientation-lock), a placeholder below its ratio whose colors can't be told to be the page's or the browser's, or a lone character standing in for its control's name below its ratio (contrast-minimum), or a color or size that cannot be computed (the contrast rules, target-size-minimum). A rule that throws is reported as cantTell too, as a safety net.
• manual — signals that a human has to decide; the rule cannot decide whether what it found is a problem. Reports cantTell or notApplicable, and pass only when the answer that needs no judgment is the one found — never fail. landmark-unique cannot decide whether two landmarks sharing a name are a problem (the APG allows it when their content is identical), so that is cantTell; but "every name differs" is a fact, so that is pass. A rule that asks a person to judge every target it finds, such as whether an image's text alternative is accurate, never reports pass. A manual rule that asks only where a heuristic finds a sign, and finds none, reports notApplicable, not pass: it applies only to what its heuristic flags, and finding nothing there doesn't show that all is well. image-redundant-alt looks for alt text that repeats the text next to the image; finding none says nothing about whether the alt text is right. form-control-label-quality, password-paste-enabled, scrollable-region-focusable and image-of-text do the same.

A rule tagged best-practice claims no Success Criterion, and still reports fail when what it decides is itself a barrier: an empty heading is announced as a heading with nothing in it (empty-heading, as W3C's ACT rule for it reports it). Its fail says the rule's own expectation is not met, not that a criterion is: no WCAG rollup counts it. Where the finding may harm no one, it reports cantTell instead, as above.

A manual rule reporting cantTell is not the same event as an automatic rule reporting cantTell, even though the value is identical: the automatic rule has decided and is telling you what it found; the manual rule is telling you the question isn't decidable from markup at all. Either way, a core rule's cantTell says how to answer it (howToCheck), and some say which way the page's evidence points (lean, see Leans). See Results & Reports for the full outcome/severity/confidence reference.

How rule IDs are structured

A rule id is generally <family>-<intent>: which elements/mechanism the rule targets, then what question it asks about them. The image-alternatives family (WCAG 1.1.1) is the clearest example:

• present — verifies a required mechanism exists. Typically automatic.
• quality — verifies appropriateness, correctness, or meaningfulness. Always manual.
• decorative — verifies correct treatment of purely decorative content. Always manual.

Intent determines whether a rule can be automatic: "is something present" is often decidable from markup alone, while "is it good" almost never is. This is also the logic behind the Related rules links on each rule page — rules sharing a family (everything before the last - segment of the id) are the ones grouped there. The ruleset spans dozens of families beyond img — aria-*, contrast-*, dialog-*, iframe-*, label-*, link-*, list-*, landmark-*, and more — the catalog is the current, generated list.

Rules never mix families: each one queries one kind of element, using helpers appropriate to it. That's also why the ruleset has 145 narrow rules rather than a dozen broad ones — two checks that differ in what they decide, what they target, or what WCAG facet they cover are kept as separate rules rather than merged, so a result never has to be untangled after the fact to say what specifically was found.

WCAG facets

A WCAG Success Criterion is usually bigger than any one rule can decide deterministically. Internally, each SC is broken into named "facets" — for 1.1.1 Non-text Content, that's things like whether an alt attribute is present, whether its text is meaningful, and whether decorative images are correctly marked null. A rule maps to one or more facets, and multiple rules commonly cover different facets of the same SC — which is exactly what the img-alt family above does for 1.1.1.

This matters when reading a composite (WCAG-SC rollup) result: a composite passes only when its rules check everything the criterion asks, and none does yet. So where every automated check for an SC comes back clean, the composite is ?can't tell, partly checked: the facets its rules cover are met, and a person checks the rest. See Conformance for the three layers (atomic rules, facets, composites) and how a composite's outcome is actually computed. Each facet of a criterion a rule evaluates has a procedure, how a person checks it by hand (see Test procedures).