# APG Pattern Quick-Index

Use this reference when a component under review is a custom (JS-driven) interactive widget and you need to identify which WAI-ARIA Authoring Practices Guide (APG) pattern applies before comparing its actual keyboard/role/state implementation against the canonical model.

## What people get wrong

The common bad assumption is:

> "I added `role="button"` and a click handler, so it's accessible."

Wrong. A role only tells assistive technology what the element *is*; it does nothing for keyboard operability, focus management, or state exposure. Every non-trivial custom widget corresponds to exactly one (sometimes zero) APG pattern, and that pattern defines a full contract: role, required/optional states and properties, and a specific keyboard interaction model — not just "Enter activates it."

> Version note: WAI-ARIA and the APG evolve. Confirm the pattern's current keyboard model and required ARIA attributes via Context7 (`/mdn/content`) or the live `https://www.w3.org/WAI/ARIA/apg/patterns/` page before ruling — do not cite this file's summaries as the final word.

## Non-negotiable design rule: match first, judge second

Before writing any finding about a custom widget, identify its APG pattern by name. If no pattern fits, that itself is a finding: either the widget should not exist as a custom control (use a native element), or it needs a `role="group"`/`role="region"` treatment with no interactive-widget semantics at all. Never invent ad-hoc ARIA for a shape that doesn't match a documented pattern.

## Common widget → pattern map (starting point, not exhaustive)

| Widget seen in markup | Likely APG pattern | Minimum keyboard model to verify |
|---|---|---|
| Modal / overlay dialog | Dialog (Modal) | Focus moves into dialog on open; `Tab`/`Shift+Tab` trapped inside; `Escape` closes; focus returns to trigger on close |
| Non-modal panel toggle | Disclosure (Show/Hide) | `Enter`/`Space` toggles; `aria-expanded` reflects state; no focus trap |
| Dropdown menu (app-style, not `<select>`) | Menu / Menu Button | `Enter`/`Space`/`ArrowDown` opens; `ArrowUp`/`ArrowDown` moves; `Escape` closes and returns focus; `Home`/`End` jump to first/last |
| Custom text input with suggestions | Combobox | `ArrowDown` opens/moves listbox; `Escape` closes without selecting; `Enter` selects active option; `aria-activedescendant` or roving `tabindex` tracks active option |
| Tab strip | Tabs | Arrow keys move between tabs (auto- or manual-activation, pick one and document which); `Tab` key exits to panel; only active tab is in the sequential tab order |
| Accordion | Accordion (built from Disclosure) | Each header toggles its own panel independently; heading semantics preserved (see heading-landmark-rules.md) |
| Tree view (file explorer style) | Tree View | `ArrowUp`/`ArrowDown` moves; `ArrowRight`/`ArrowLeft` expands/collapses or moves to child/parent; `*` expands all siblings (optional) |
| Custom slider | Slider | `ArrowLeft`/`ArrowRight` (or `Up`/`Down`) adjusts by step; `Home`/`End` jump to min/max; `aria-valuenow`/`aria-valuemin`/`aria-valuemax` kept in sync |
| Toast / live status message | Alert or Status (live region, not a focusable widget) | No keyboard model — it must not steal focus; verify `role="alert"` (assertive, interrupting) vs `role="status"` (polite) is the deliberate choice, not a default |

## Verification targets

For each matched pattern, confirm in the markup/code:

- the root and child elements carry the pattern's required roles (native-implicit or explicit `role=`),
- every required `aria-*` state/property from the pattern is present and kept in sync with actual UI state (not just set once at mount),
- the full keyboard model is implemented, not a subset — a widget with only mouse/click handlers and no `keydown` logic fails regardless of correct roles,
- focus is visible (no `outline: none` without a replacement focus style) and moves predictably on open/close/select.

## High-risk assumptions to kill

- "It has the right `role`, so it's done" — role without keyboard model and state sync is theater.
- "Semantic-sounding class name (`.dropdown-menu`) means it follows the Menu pattern" — check the actual DOM/role/keydown handlers, not the class name.
- "We tested with the mouse and it felt fine" — APG conformance is a keyboard-first and AT-first contract; mouse-only QA proves nothing about it.
- "It matched a pattern last time we reviewed it" — widgets drift as code changes; re-verify against the current implementation every review, not from memory of a prior review.

## When to push back

Push back if the user asks to:

- add ARIA roles/states to make a widget "look accessible" without implementing the pattern's keyboard model,
- ship a custom widget where a native element (`<select>`, `<details>`, `<dialog>`) would satisfy the requirement with less code and less risk,
- treat "no pattern fits perfectly" as license to skip APG entirely rather than picking the closest pattern or reconsidering the widget design.

# Heading and Landmark Structure Rules

Use this reference when auditing the document outline of a page or component tree — heading hierarchy, landmark regions, and how components compose into a whole page's navigation structure.

## What people get wrong

The common bad assumption is:

> "Headings are for visual size; I'll pick whichever `<h*>` looks right at this font size, and CSS will fix the rest."

Wrong. Screen-reader users navigate primarily by heading level and landmark region — jumping "next heading," "next level-2 heading," or "next landmark" without reading surrounding text. A heading chosen for visual weight instead of document structure breaks that navigation model even when the page looks fine visually.

## Non-negotiable design rules

### 1. Heading levels must not skip

`<h1>` → `<h3>` with no `<h2>` between them is a structural break, not a style inconsistency. It reads to a screen-reader user as "I jumped past something — did I miss content?" Every component that renders a heading must accept its heading level as a prop/parameter from its parent context rather than hardcoding a level, so composed pages stay contiguous.

### 2. Exactly one `<h1>` per page (not per component)

A component library that hardcodes `<h1>` internally breaks the instant it's composed twice on one page, or nested inside a page that already has its own `<h1>`. Components should default to accepting a level and render the semantically-correct `<h1>`–`<h6>` element for that level (not just visually restyle a `<div>`).

### 3. Landmarks must be unique-per-page or explicitly labeled

A page may have only one unlabeled `<main>`, one unlabeled `<banner>` (`<header>` at the top level, not nested in `<article>`/`<section>`), and one unlabeled `<contentinfo>` (`<footer>` at the top level). Multiple instances of the same landmark type (e.g., two `<nav>` regions — primary nav and breadcrumb nav) MUST each carry a distinct accessible name via `aria-label` or `aria-labelledby`, or AT users hear "navigation, navigation" with no way to distinguish them.

### 4. Prefer semantic elements over `role=` on `<div>`

`<nav>`, `<main>`, `<header>`, `<footer>`, `<aside>`, `<section>` (with an accessible name) carry implicit landmark roles. Adding `role="navigation"` to a `<div>` works but is strictly worse than using `<nav>` — it adds a maintenance burden (the role can drift out of sync with a renamed/refactored element) for no benefit. Flag `role=` landmark attributes on generic elements as a downgrade unless there's a documented reason (e.g., legacy browser support matrix) — see MDN ARIA landmark-role guidance via the Context7 Documentation Protocol in SKILL.md for the "semantic HTML first" rule.

### 5. `<section>` and `<aside>` need an accessible name to count as landmarks

A bare `<section>` with no `aria-label`/`aria-labelledby`/heading-derived name does not expose as a landmark to most assistive technology — it is a generic grouping only. Do not report "landmark added" unless the accessible-name requirement is also met.

## Minimal safe audit flow

1. Extract the full heading tree (level + text) for the page or component in isolation.
2. Extract the full landmark tree (type + accessible name, or "unlabeled" if none).
3. Diff both trees against the pre-change version when reviewing a delta; against W3C rules from scratch when reviewing a new page.
4. Flag: any level skip, any second unlabeled instance of a unique-landmark type, any component that hardcodes a heading level instead of accepting one from its parent.
5. For component-tree-only reviews (no full-page context available), state explicitly that heading-level correctness cannot be fully verified without knowing the mount context, and flag it as a residual risk rather than asserting compliance.

## Verification targets

- Render (or read) the full page and extract the accessibility tree / heading outline via a real DOM inspection when live evidence is available; note this as `live evidence`.
- When only source is available (no live render), derive the outline from JSX/template structure and label the finding `inference` — a dynamically-computed heading level (e.g., `level={depth + 1}`) cannot be fully verified statically without knowing all call sites.

## When to push back

Push back if the user says:

- "just use `<div class="h2">`, we'll style it to look right" — that produces zero navigable structure for AT users regardless of visual styling,
- "we don't need `aria-label` on the second nav, screen-reader users will figure it out from context" — they cannot; landmark lists present regions out of visual context,
- "heading levels don't matter as long as visually it looks like a hierarchy" — visual hierarchy and semantic hierarchy are independent axes; both must be correct.

# WCAG 2.2 Success-Criterion Mapping

Use this reference when a finding from this skill needs to be tied to a specific WCAG 2.2 success criterion (SC) for a compliance-audit deliverable — e.g. when the output feeds an ADA / Section 508 / EN 301 549 conformance report and "looks wrong" is not an acceptable citation.

## Grounding rule

This file gives a starting map from common findings to likely SC numbers so review output cites *something* concrete instead of vague prose. It does not replace reading the actual SC "Understanding" doc for edge cases — verify exact wording and Level (A/AA/AAA) against `https://www.w3.org/TR/WCAG22/` or via the Context7 Documentation Protocol before finalizing a compliance-facing citation, since SC numbering and scope can be easy to misremember (e.g., confusing 4.1.2 Name/Role/Value with 1.3.1 Info and Relationships).

## Finding → likely success criterion

| Finding category | Likely SC (Level) | Why |
|---|---|---|
| Heading level skip / missing heading structure | 1.3.1 Info and Relationships (A) | Structure conveyed visually must also be conveyed programmatically |
| Duplicate unlabeled landmark of the same type | 1.3.1 Info and Relationships (A), 2.4.1 Bypass Blocks (A) | Landmarks are the mechanism for bypassing repeated content; ambiguous landmarks break that mechanism |
| Custom widget missing/incorrect role | 4.1.2 Name, Role, Value (A) | AT must be able to programmatically determine the role of every UI component |
| Custom widget state (`aria-expanded`, `aria-checked`, etc.) not kept in sync with actual UI state | 4.1.2 Name, Role, Value (A) | Same SC — "Value" includes states that change |
| Custom widget missing full keyboard operability (e.g. no `Escape`, no arrow-key navigation per its APG pattern) | 2.1.1 Keyboard (A) | All functionality must be operable through a keyboard interface |
| Positive `tabindex` values / illogical focus order | 2.4.3 Focus Order (A) | Focus order must preserve meaning and operability |
| `outline: none` / removed focus indicator with no replacement | 2.4.7 Focus Visible (AA) | Keyboard focus indicator must be visible |
| `aria-hidden="true"` trapping a focusable descendant | 4.1.2 Name, Role, Value (A), 2.1.1 Keyboard (A) | Element is reachable by keyboard but hidden from AT (or vice versa) — a dual failure |
| Toast/alert stealing focus or interrupting unexpectedly | 4.1.3 Status Messages (AA) | Status messages must be programmatically determinable without receiving focus |
| Native element replaced with unlabeled `<div>`/`<span>` + click handler (fake button/link) | 4.1.2 Name, Role, Value (A), 2.1.1 Keyboard (A) | No role exposed, no keyboard access by default |
| Missing/incorrect accessible name on interactive control (icon-only button, ambiguous link text) | 4.1.2 Name, Role, Value (A), 2.4.4 Link Purpose (In Context) (A) | Control lacks a determinable/discriminable accessible name |

## Non-negotiable rule for compliance-facing output

Never present an SC citation as authoritative without the Level (A/AA/AAA) attached — an auditor reading "1.3.1" without a level cannot assess conformance-target scope (most orgs target AA). If uncertain of the exact SC number for a novel finding, say so explicitly (`inference — needs SC verification`) rather than guessing a plausible-sounding number; a wrong citation in a compliance deliverable is worse than an honest gap.

## Verification targets

- Cross-check any SC number cited in this table against the live WCAG 2.2 "Understanding" page for that SC before it goes into a compliance-audit-facing deliverable (not required for a routine PR review comment, where this table's mapping is sufficient).
- For AAA-level findings, flag explicitly that AAA is rarely a required conformance target — do not imply a blocking failure at AAA carries the same severity as an A/AA failure unless the user has stated AAA is their target.

## When to push back

Push back if the user asks to:

- label every accessibility finding as a single generic "WCAG violation" for a compliance deliverable without SC-level granularity — auditors and legal teams need the specific criterion and level,
- downgrade a Level A finding to "nice to have" — Level A is the floor of any recognized conformance claim (WCAG A/AA/AAA, Section 508, EN 301 549 all build on Level A as mandatory),
- treat this skill's static-review findings as a substitute for a full conformance audit — this skill narrows and grounds findings but does not replace testing with real assistive technology across the criteria this file does not cover (e.g., color contrast, captions, timing).