Relevant criteria

Heuristics

Structural signals & detection

When you run a1 audit, the engine scans the rendered DOM, accessibility tree, and document metadata for 15 categories of interactive and structural patterns:

Content structure heading, landmark, media, drag-and-drop, help

Interactive widgets dialog, menu, overlay, tablist, widget

Forms & dynamic state form, repeated-form, validation, live-region, auth

Each detected pattern produces a signal with a confidence score (high, medium, or low) and the matching DOM nodes:

\"signals\": [
  {
    \"category\": \"heading\", \"source\": \"dom\", \"value\": \"heading structure\", \"confidence\": \"high\",
    \"elements\": [{ \"xpath\": \"/html/body/main/h1\", \"tag\": \"h1\", \"snippet\": \"<h1>\" }]
  },
  {
    \"category\": \"form\", \"source\": \"dom\", \"value\": \"form controls\", \"confidence\": \"high\",
    \"elements\": [
      { \"xpath\": \"/html/body/main/form\", \"tag\": \"form\", \"snippet\": \"<form action=\\\"/checkout\\\" method=\\\"post\\\">\" },
      { \"xpath\": \"/html/body/main/form/label/input\", \"tag\": \"input\", \"snippet\": \"<input type=\\\"email\\\" name=\\\"email\\\">\" }
    ]
  }
]

Classification

Relevance assessment states

Every WCAG criterion is tagged with the topics it governs (such as forms, keyboard, navigation, or modals). By mapping the detected signals against these topic tags, a11ied assigns each criterion an assessment state:

applicable Active review required. A detected structure triggers this criterion with high confidence. You or your test suite must verify this criterion on this route.

not-detected No matching structure found. For example, on a simple text article, video captioning rules (1.2.2) and form validation rules (3.3.1) are marked not-detected.

out-of-scope Inherently inapplicable. The criterion does not apply to this type of media or presentation.

unknown The detected signals are insufficient to determine relevance definitively.

Pruning the checklist

Running a relevance audit

The terminal output of a1 audit synthesizes automated violations with the relevance matrix. Instead of presenting an intimidating list of all 50+ manual and hybrid WCAG criteria, the Check by hand section displays only the criteria that are both hybrid/manual and applicable to the page you are auditing:

a1 audit http://localhost:3000/

audit  http://localhost:3000/

✓ Nothing failed the automated checks.

Check by hand
  12 criteria this page triggers require interactive or manual review:
    • 1.3.1  Info and Relationships (detected headings & landmarks)
    • 2.1.1  Keyboard (detected dialog button)
    • 2.4.3  Focus Order (detected modal overlay)
    • 4.1.2  Name, Role, Value (detected custom widgets)

  Verify with screen reader:  a1 sr walk http://localhost:3000/

The page
  Titled Preferences Demo.
  It has 1 landmark, 1 heading (level 1), 1 button, 1 dialog container.

86 criteria were evaluated. Add --verbose for node details, or --json for the full matrix.

Pinpoint elements

With --json or --verbose, every applicable criterion lists the exact XPaths and snippets that triggered it. You can inspect elements directly in DevTools using $x('xpath').

Agentic workflows

Context efficiency for AI agents

Providing an AI coding assistant with the entire 86-criterion WCAG specification consumes thousands of tokens and causes hallucinated or generic advice.

When connected via the Model Context Protocol (MCP), agents call the audit tool and receive the filtered relevance matrix. This gives the agent a tight, actionable checklist:

If the component is a modal dialog, the agent focuses strictly on focus trapping (2.1.2), name/role attributes (4.1.2), and escape key dismissal.
It avoids wasting reasoning budget on media alternatives, time-based media, or audio descriptions.

Boundary considerations

Limits of static detection

The relevance matrix determines which criteria are worth testing; it does not declare conformance or failure.

Single-page applications & lazy mounting: The scan analyzes the DOM present at inspection time. If a modal dialog, confirmation toast, or complex form is only mounted into the DOM after a specific user click or API response, the initial scan may classify that structure as not-detected.

To audit dynamic states that render after interaction, use the --click flag or drive a screen reader session:

a1 audit http://localhost:3000/ --click "button#open-modal"