Confirmation Flow

Composition

1. Modal container

   Use the `alertdialog` variant. `alertdialog` raises the screen reader announcement priority — assistive tech announces the contents the moment focus enters, instead of waiting for the user to navigate. `dialog` is wrong here even when the dialog asks for a decision; the variant exists precisely to mark "this is a decision the user must hear."

2. Button primary action (destructive)

   Use the `destructive` variant for the action that completes the consequential operation. The button text names the action, not the agreement — "Delete account", not "OK" or "Yes". Destructive tone is a brand-warm-mix accent in the canonical palette; it signals risk before the click, not after.

3. Button cancel action

   Use the `secondary` or `tertiary` variant. Cancel is the defensive default; it should be the focused button when the modal opens (per APG alertdialog guidance) so a reflexive Enter keypress does not commit the destructive action.

When to use

Use

When committing to the action would lose data, charge money, notify a third party, or otherwise produce an effect that is hard or impossible to reverse. Use whenever the action's consequence materially exceeds its undo cost.

Avoid

For low-stakes actions that have a clean undo (`Toast` with an Undo button is the right pattern instead). For multi-step flows where the destructive step is part of the flow rather than the end (use a `Stepper` with an explicit final commit step). For confirming success — that is a `Toast` or `Banner`.

Canonical decisions

1. Why `alertdialog` instead of `dialog` for confirmations?

   `alertdialog` is the variant; `dialog` is wrong here.

   The W3C ARIA Authoring Practices Guide reserves `alertdialog` for "dialogs that interrupt the user with an important message and require a response." Screen readers announce alertdialog contents on focus rather than waiting for the user to navigate into the surface; that announcement *is* the consent moment. Using `dialog` here forces the user to hunt for the message before they can respond.

2. Should Cancel or Confirm receive initial focus?

   Cancel.

   A reflexive Enter or Space keypress should not commit the destructive action. Initial focus on Cancel is the canonical defensive default; users who genuinely intend the destructive action explicitly Tab to it. APG, Polaris, Carbon, Material 3, and GOV.UK all converge on this rule for destructive confirmations specifically. Non-destructive confirmations may focus the primary action.

3. Are Escape and backdrop-click acceptable dismissal paths?

   Escape: yes. Backdrop-click: only if the dismissal path is semantically equivalent to Cancel.

   Escape is keyboard-canonical for any modal and never commits the action — APG. Backdrop-click is contested: Radix and Material 3 disable it for `alertdialog` to prevent accidental dismissal of an important decision; Headless UI and React Aria allow it. The canonical recommendation is to disable backdrop-click for destructive confirmations specifically and keep it enabled for low-stakes confirmations.

4. Can the title state the question, or must it state the consequence?

   State the consequence in the title; ask the question in the body.

   Screen readers announce the title first. "Are you sure?" gives the user no information; "Delete this account?" or "Discard your draft?" puts the consequence in the announcement and lets the body explain why. The body is also where you state the undo cost ("This cannot be undone") if it applies.