How rules are organized

This describes how the 132 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 three situations: a real violation exists but doesn't on its own establish that the mapped WCAG criterion fails (an ARIA author requirement whose exposed name/role/value still survives); the rule decides deterministically but claims no Success Criterion at all (aria-allowed-role, 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).
• manual — signals that a human has to decide; the rule cannot settle the question from markup at all. Capped at cantTell/notApplicable — never fail.

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. 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 132 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 ✓pass means every automated check for that SC came back clean, but if a facet has no automated coverage at all, the composite is silent about that facet rather than asserting it's fine. See Conformance for the three layers (atomic rules, facets, composites) and how a composite's outcome is actually computed.