Accessibility Checklists

Accessible Dialog Checklist (WCAG)

Every Dialog rule that WCAG 2.2, WAI-ARIA or the APG backs, in one checklist, with the success criteria behind each rule and their level.

Here's every rule for the Dialog that WCAG 2.2, WAI-ARIA or the APG backs, in one list you can work through when you build or review one. Each row names the WCAG 2.2 success criteria behind its rule, with their level, and links to the rule's table on its layer's page, where we explain why it's there. A rule that rests on WAI-ARIA or the APG alone says "None".

We build this list from the Dialog's checklists, so it always matches them. It leaves out the rules that rest only on HTML and the ones that are our own, so you'll find every rule in the Dialog's checklist.

UI rules

RuleLevelRequirementWCAG 2.2Basis
dialog/contrastMustThe title, the description and the content have a contrast of 4.5:1 against the panel1.4.3 Contrast (Minimum) (AA)WCAG 1.4.3 (AA)
dialog/fits-screenMustIt's never wider or taller than the screen, less a margin, down to 320px wide1.4.10 Reflow (AA)WCAG 1.4.10 (AA)
dialog/resizableMustIt's sized in rem, so it grows with its text, and its title wraps rather than getting cut off1.4.4 Resize Text (AA), 1.4.12 Text Spacing (AA)Open Components, beyond WCAG 1.4.4, 1.4.12 (AA)
dialog/reduced-motionShouldIt only animates as it opens when prefers-reduced-motion is no-preference2.3.3 Animation from Interactions (AAA)WCAG 2.3.3 (AAA)

UX rules

RuleLevelRequirementWCAG 2.2Basis
dialog/native-elementMustIt's a native <dialog>, opened with showModal(), and never a <div> with role="dialog"2.1.2 No Keyboard Trap (A), 4.1.2 Name, Role, Value (A)Open Components, beyond WCAG 2.1.2, 4.1.2 (A)
dialog/modalMustWhile it's open, it's in the top layer and the rest of the page is inert, so nothing behind it can be focused, clicked or readNoneAPG
dialog/contain-focusMustTab and Shift+Tab never move focus to the page behind an open dialog2.4.3 Focus Order (A)WCAG 2.4.3 (A), APG
dialog/namedMustIt's named by its title, with aria-labelledby4.1.2 Name, Role, Value (A)WCAG 4.1.2 (A)
dialog/visible-titleMustEvery dialog has a visible title that says what it's for, like "Delete project?"1.3.1 Info and Relationships (A), 2.4.6 Headings and Labels (AA)WCAG 1.3.1 (A), 2.4.6 (AA)
dialog/describedShouldA short description is linked with aria-describedby, while longer content, like a form, isn'tNoneAPG
dialog/initial-focusMustOpening it moves focus inside, to the control marked with data-autofocus, or else the first in its body, then its first action2.4.3 Focus Order (A)WCAG 2.4.3 (A), APG
dialog/safe-focusMustAn alert dialog's initial focus is on its least destructive actionNoneAPG
dialog/return-focusMustClosing it moves focus back to the control that opened it, or to a logical place when that control is gone2.4.3 Focus Order (A)WCAG 2.4.3 (A), APG
dialog/escapeMustEscape asks to close every dialog, alert dialogs included, unless a control inside handles it firstNoneAPG

AX rules

RuleLevelRequirementWCAG 2.2Basis
dialog/role-and-nameMustIt can be found by its role and title alone, with getByRole("dialog", { name }), or "alertdialog"4.1.2 Name, Role, Value (A)WCAG 4.1.2 (A)

Sources

Copyright © 2026