Alert dialog

Problem Context

• A security, privacy, session, data-loss, permission, billing, or safety condition blocks the current workflow.
• The user must acknowledge, cancel, continue, sign out, retry, review, or choose another response before returning to the page.
• A non-modal alert would be too easy to miss or would leave users able to continue into an unsafe state.
• A generic modal task would understate the urgency or fail to communicate that a response is required.

Selection Rules

• Choose an alert dialog when an important message interrupts the current workflow and requires an immediate user response.
• Use a non-modal alert when users only need urgent notice and can continue working without answering the message.
• Use a modal dialog when the surface is a short contained task such as editing a field, choosing an object, or entering settings.
• Use a confirmation dialog when the alert-style decision is caused by a user-initiated consequential action that has not yet committed.
• Use warning text when the severe consequence can be explained inline before the risky action without blocking the whole page.
• Use a site alert or banner when the message applies across a service, account, product, or many pages rather than one current workflow.
• Do not use an alert dialog for page-load announcements, routine success messages, marketing notices, low-risk confirmations, or educational copy that does not need a response.
• Do not open several alert dialogs in a row; prioritize the highest consequence and route secondary detail to the dialog body or a recovery flow.

Required States

• Normal workflow state with a visible invoking event or system condition.
• Opening state that moves focus into the alert dialog and marks background content inactive.
• Urgent message state with accessible title, associated description, consequence copy, and response-labelled actions.
• Contained keyboard state where Tab and Shift+Tab stay within the dialog until it closes.
• Safe cancellation or escape state when cancellation is allowed.
• Positive response state that commits the user's chosen continuation, retry, acknowledgement, or sign-out path.
• Closed state that returns focus to the invoker or next logical recovery location.
• Escalated state for conditions that need a page, support route, or longer recovery task after the response.

Interaction Contract

• The alert dialog appears only for a condition that genuinely requires a response before continuation.
• The dialog has alertdialog semantics or the platform equivalent, an accessible name from the visible title, and a description connected to the consequence text.
• Opening the dialog moves focus to the safest useful element: often a non-destructive response, a detail link, or the message text when reading comes first.
• Background page controls cannot be clicked, focused, or changed while the alert dialog is open.
• Tab and Shift+Tab cycle through only the dialog controls.
• Escape cancels only when cancellation is safe; otherwise the available actions explain what response is required.
• Buttons use response labels such as Stay signed in, Sign out, Retry payment, or Keep editing rather than OK-only labels.
• Closing after any response returns focus to the trigger or a clear outcome state without losing the user's task context.

Implementation Checklist

• Classify the condition by urgency, affected workflow, user consequence, and whether a response is mandatory.
• Write a visible title that names the condition, such as Session locked or Payment authorization failed.
• Describe why the interruption is happening, what is blocked, and what each response changes.
• Use role alertdialog with aria-modal true where appropriate, and connect aria-labelledby and aria-describedby to visible content.
• Move focus into the dialog on open and contain focus until a response closes it.
• Make the page behind the dialog inert or otherwise unavailable to pointer and keyboard interaction.
• Prefer a safe or explanatory initial focus target unless the urgent condition has only one safe response.
• Provide Escape and an explicit safe action when cancellation is allowed.
• Return focus to the opener, the blocked control, or the next recovery location after close.
• Log and review alert-dialog frequency so users are not trained to dismiss critical interruptions.

Common Generated-UI Mistakes

• Using an alert dialog as a dramatic version of a routine non-modal alert.
• Showing a vague Warning dialog with only OK and no consequence or next step.
• Letting users interact with background controls while the response-required message is visible.
• Opening the dialog automatically on every page load for content that can be shown inline.
• Using alertdialog semantics for marketing, onboarding tips, or passive informational copy.
• Hiding the safe response or making the destructive response the accidental default.
• Failing to return focus after close, leaving keyboard users at the start of the page.

Critique Questions

• What unsafe or impossible state would occur if the user ignored this message?
• Does the message require a user response, or would a visible alert be enough?
• Is the interruption caused by a system condition, or by a user-initiated consequence that belongs to confirmation guidance?
• Does the title name the affected workflow or condition?
• Can users predict what each response button will do without rereading the whole body?
• Where does focus move on open, Tab wrap, Escape, response, and close?