AlertDialog accessibility

WCAG 2.1 AA — release blocker

Semantics

• Root renders a native <dialog> element with role="alertdialog" and aria-modal="true".
• Title maps to a <h2> inside the dialog — screen readers announce it on open.
• Description uses <p> with muted styling for supporting context.

Modal behaviour

• Does NOT dismiss on backdrop click — the user must choose an explicit action.
• Does NOT dismiss on Escape — onCancel is intercepted and prevented.
• This matches WAI-ARIA alertdialog semantics: the dialog demands a response.

Focus management

• Focus is trapped inside the dialog while open (native <dialog> handles this).
• On open, focus moves to the first focusable element inside the dialog.
• On close, focus returns to the element that triggered the dialog.

Keyboard navigation

• Tab / Shift+Tab cycles through focusable elements within the dialog.
• Enter activates the focused button.
• Escape is blocked — the user must use Cancel or the action button.

Labelling

• AlertDialogTitle provides the accessible name for the dialog.
• AlertDialogDescription provides supplementary context.
• Action and Cancel buttons should have descriptive labels (e.g. "Delete" not "OK").

Audit checklist

• Screen reader announces dialog title and description on open.
• Focus is trapped inside the dialog.
• Escape does NOT close the dialog.
• Backdrop click does NOT close the dialog.
• Tab cycles through action buttons only.
• Focus returns to trigger element on close.
• Action buttons have descriptive labels.