Dialog / Modal — Accessibility Specification (WCAG 2.1 AA)

What is this component?

What is this component? A dialog is a modal window that captures focus for a short task. It must trap focus within, restore focus on close, and be announced to AT.

Accessibility Requirements

Requirement	WCAG Criteria	Description
Focus management	2.4.3, 2.4.7	Move focus to dialog on open; keep focus inside; return focus to trigger on close.
Keyboard support	2.1.1	Esc closes; Tab/Shift+Tab cycle within.
Name/Role	4.1.2	Announce dialog role and label; describe purpose.

ARIA Roles and Attributes

ARIA Role/Attribute	Used On	Purpose & Usage
`<dialog>` + `aria-labelledby`/`aria-describedby`	Native dialog	Use `showModal()`, ensure focus trapping and labeled title.
`role="dialog"` or `alertdialog`	Custom modal	Trap focus; use backdrop; restore focus on close.

Implementation Guidelines




  Confirm delete
  This action cannot be undone.

DO’s

Label the dialog with a clear title and description.
Trap focus inside the dialog; return focus when closing.
Provide Escape to close and visible focus states.

Don’ts

Don’t open modals without moving focus.
Don’t allow background content to be focusable when modal is open.
Don’t hide close controls.

Common Pitfalls

Focus loss: keyboard users land behind modal.
Screen reader confusion: unlabeled dialog content.

Testing Checklist

Test Item	WCAG Criteria	Pass Criteria
Role/Label	4.1.2	AT announces “dialog” with title.
Focus trap	2.1.1, 2.4.3	Tab cycles within; background is inert.
Escape closes	2.1.1	Esc closes reliably.