An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:AlertDialog authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-11-01 owners: [cixzhang] review_triggers: [public-api, behavior, accessibility, theming] verified_by: [ packages/core/src/AlertDialog/AlertDialog.test.tsx, packages/core/src/AlertDialog/useImperativeAlertDialog.test.tsx, packages/core/src/AlertDialog/tests/AlertDialog.interaction.browser.spec.ts, packages/core/src/hooks/useActionGroupTracking.test.tsx, packages/core/src/AlertDialog/tests/AlertDialog.a11y.test.tsx, packages/core/src/AlertDialog/tests/AlertDialog.a11y.chromium.spec.ts, packages/core/src/Dialog/Dialog.test.tsx, packages/core/src/Dialog/tests/DialogTouchEntrance.interaction.browser.spec.ts, scripts/check-knowledge.mjs, apps/storybook/rtl-audit/targets.json, ] modules: [] families: [family:overlay-dismissal] design_specs: [design:reduced-motion] architecture: [ architecture:public-component-api, architecture:component-theming-surface, architecture:layer-runtime, ] contributing: [] system_specs: [ spec:AST-020/FR15, spec:AST-094/FR4, spec:AST-094/FR13, spec:AST-094/FR35, spec:AST-094/DEC-15,
]
AlertDialog component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | AlertDialog, AlertDialogProps, and useImperativeAlertDialog are exported from @astryxdesign/core/AlertDialog; title, description, actionLabel, onAction, and onOpenChange are required with isOpen, plus cancel label, action variant, loading, width, and an inline preview mode. |
| Behavior | A modal confirmation that interrupts: it opens through the native dialog, cannot be dismissed by a click outside, closes on Escape or Cancel through onOpenChange(false), and runs onAction on the action button. |
| End-user impact | A keyboard or screen-reader user is told a decision is needed (the title and description are announced), lands on Cancel, and cannot lose the dialog by clicking past it. On a touch screen the alert scales in and fades out with iOS's look, on the theme's motion tokens, and ignores taps while it enters (FR6, FR7), and on a phone it is 320 px wide (FR9); on a touch screen a press slid from Cancel to the action runs the lifted action; a mouse's press acts natively (FR8). |
| Builder impact | None. |
| Compatibility/readiness | FR1–FR5, FR8 and AR1 record shipped behavior, apart from AR1's Tab wrap. FR7 ships in part, and FR6 and FR9 are requirements not shipped yet. Each gap is listed under Current-state impact. |
| Review checks | Reject a modal AlertDialog without role="alertdialog", a title or description not linked by id, initial focus on the destructive action, or a backdrop click that dismisses it. |
| Governing rules | architecture:public-component-api/INV1,INV5–INV8; architecture:component-theming-surface/INV3–INV7; architecture:layer-runtime; component:Dialog/AR1–AR3; spec:AST-020/FR15; spec:AST-094 FR4, FR7, FR45, FR13, FR35, DEC-15, DEC-17; family:action-groups; design:reduced-motion; spec:AST-017. |
This table is a review projection; the body below is authoritative.
Intent
AlertDialog asks a person to confirm or cancel one consequential action. It composes Dialog's modal, focus, and dismissal runtime with a fixed anatomy — title, description, Cancel, and one action — so a product gets an interrupting confirmation without assembling it.
Compatibility and migration
- Released default preserved:
no— under the touch presentation FR8 changes action activation under a slide; a mouse press keeps the native button's; shipping FR6, FR7 and FR9 changes the touch presentation and the phone width - Compatibility class: nonbreaking behavior change; no public API, DOM, or target change
- Controlled/uncontrolled behavior: unchanged —
isOpenwithonOpenChangeis controlled;useImperativeAlertDialogowns that pair for a caller that wantsshow/hide - Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
- The touch presentation is not shipped (FR6). Under a touch presentation the alert opens and closes with Dialog's default motion, not the scale-in and fade-out FR6 requires.
- Only the entrance hold ships (FR7). Under a touch presentation, Dialog holds pointer input while the alert enters. Nothing makes the content inert while the alert leaves, because its dismissal fade has not shipped (FR6).
- The phone width is not shipped (FR9). On a phone the alert keeps its default width rather than 320 px.
- Tab leaves the alert (AR1). Dialog does not yet contain Tab, so Tab from
the last button moves focus out of the alert to the browser's interface,
where AR1 has Tab wrap inside it through
component:DialogFR7.
Ownership boundary
Owns
- The confirmation anatomy and its order: title, description, then Cancel and action in the order FR3 states.
- The alert-dialog role, its name and description links, and the least-destructive initial focus.
- The imperative wrapper hook.
- The touch presentation's motion, input hold, and phone width (FR6, FR7, FR9).
Does not own / non-goals
- A press that slides across the actions acts on the lifted one, as
family:action-groupsowns (FR8). - Modal presentation, focus return, backdrop, and dismissal mechanics — owned by
component:Dialogandarchitecture:layer-runtime; AlertDialog inherits Dialog's backdrop (component:DialogFR9). - Button variants and loading — owned by
component:Button.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
isInline |
true, false |
Renders the content inline as a non-modal preview (role="group"). |
Always | false |
component:AlertDialog |
stable | Type-rejected |
actionVariant |
Button variants | The action button's emphasis. | Always | 'destructive' |
component:Button |
stable | Button's behavior |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | A modal AlertDialog opens through Dialog's native modal path and a click on the backdrop does not dismiss it. | shipped source (purpose="form"); Alert Dialog accessibility contract (pending) |
| FR2 | Escape and the Cancel button both call onOpenChange(false); the action button calls onAction and leaves closing to the caller. |
shipped source and focused tests |
| FR3 | The anatomy is title, description, then the buttons: Cancel then action on wider screens, the action stacked above Cancel on small screens, Cancel keeping initial focus either way; the action may show a loading state while isActionLoading. |
shipped source and focused tests |
| FR4 | isInline renders the same anatomy without modality and without the alert-dialog role. |
shipped source and public docs |
| FR5 | useImperativeAlertDialog returns show, hide, and the element to render, and owns isOpen/onOpenChange for its caller. |
shipped source and focused tests |
| FR6 | Under a touch presentation (spec:AST-094 FR13), a modal AlertDialog presents by scaling from 1.2 to 1 with its opacity and its backdrop's dimming rising from 0 to 1 on the theme's entrance duration and easing tokens (spec:AST-094 FR45), started at the browser's commit, with the larger start kept inside the viewport; it dismisses by a fade alone on the theme's exit duration and easing, --duration-exit and --ease-exit (spec:AST-094 FR7; spec:AST-090 FR14), and closes at the fade's end; a close during the presentation, or a reopen during the dismissal, turns back from where it is. springs.alertPresent and springs.alertDismiss stay as UIKit's measured reference, and no motion plays them (spec:AST-094 FR4). Under Reduce Motion both are the shared cross-fade (design:reduced-motion DR1–DR3). A fine primary pointer keeps today's motion (spec:AST-094 FR13 and its Non-goals). Implementation gap: not shipped yet (Current-state impact). |
proposed from measured iOS 26.2 behavior |
| FR7 | Under a touch presentation, pointer input to the alert is held while it enters (spec:AST-094 FR35); keyboard and assistive-technology input are never held, and the entrance never makes the content inert. While the alert leaves, its content is inert for the dismissal fade. The hold's timing stays internal (spec:AST-002 FR3). Implementation gap: the entrance hold ships through Dialog, and the leaving alert's inert content waits for FR6's dismissal (Current-state impact). |
spec:AST-094 FR35; owner decision (DEC-1) |
| FR8 | AlertDialog's actions are an action group (family:action-groups): under the touch presentation (spec:AST-094 FR13), a press that slides across them runs the action it lifts on, and a lift outside them runs nothing; a mouse press acts as the platform's native button does; keyboard and assistive-technology behavior is unchanged. |
family:action-groups; spec:AST-094 DEC-17; DEC-3 |
| FR9 | On a phone, a compact window (spec:AST-012 FR9: narrower than md or shorter than 500 px) under a coarse primary pointer, the alert is 320 px wide in every theme, as iOS's is; no theme role sets it. A caller's explicit width still wins there (architecture:public-component-api INV5), and Dialog's viewport clamp still applies on a screen narrower than the alert. Elsewhere it keeps today's width. Implementation gap: not shipped yet (Current-state impact). |
owner decision (DEC-2) |
Allowed variation
- AV1 — Layout. Spacing and button width follow Dialog and Layout; the small-screen stacking and order are FR3's.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| open, modal | role="alertdialog", named and described, focus on Cancel. |
Width, action variant. |
| action loading | The action shows loading; Cancel stays available. | Loading affordance. |
| inline preview | role="group", no modality, same content. |
Surrounding page. |
| imperative | show() opens and hide() closes the same dialog. |
Caller's trigger. |
Transformation and precedence order
- ORD1 — Dismissal. Escape or Cancel →
onOpenChange(false); backdrop click → nothing; action →onActiononly.
Performance and resources
PR1 — Dialog-owned resources. AlertDialog's own listeners are the small-screen media query behind the button order and the press tracking
family:action-groupsFR5 gives its actions; Dialog owns the modal lifecycle.PR2 — The touch presentation adds no element. The motion plays on the dialog surface and its
::backdrop; AlertDialog renders no extra element under a touch presentation, withinspec:AST-017FR60's open-layer allowance (architecture:component-style-authoringINV7).
Accessibility contract
- AR1 — AlertDialog adopts the APG Alert Dialog pattern (
spec:AST-020/FR15): the modal surface isrole="alertdialog", named by its title througharia-labelledbyand described by its description througharia-describedby; it is modal through Dialog (focus enters it and returns to the opener on close percomponent:Dialog/AR1–AR2, and Tab wraps inside it percomponent:Dialog/FR7); initial focus lands on Cancel, the least destructive action; Escape cancels; no click outside dismisses it. The inline preview is not an alert dialog and carriesrole="group". Implementation gap: Dialog does not yet contain Tab, so Tab from the last button leaves the alert for the browser's interface (Current-state impact).
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Title | Names the decision. | component:Heading |
Prominent | FR3, AR1 |
| Description | States the consequence. | component:Text |
Supporting | FR3, AR1 |
| Cancel button | The safe way out; receives initial focus. | component:Button |
Supporting | FR2, AR1 |
| Action button | The consequential choice, with its variant and loading; stacked above Cancel on small screens. | component:Button |
Prominent | FR2, FR3 |
| Backdrop | Separates the dialog from the page; does not dismiss it. | component:Dialog |
Supporting | FR1 |
Theming anatomy
{
"Title": {"delegatesTo": {"owner": "component:Text", "target": "heading"}},
"Description": {"delegatesTo": {"owner": "component:Text", "target": "text"}},
"Cancel button": {
"delegatesTo": {"owner": "component:Button", "target": "button"}
},
"Action button": {
"delegatesTo": {"owner": "component:Button", "target": "button"}
},
"Backdrop": {
"delegatesTo": {"owner": "component:Dialog", "target": "dialog"}
},
"Dialog surface": {"target": "alert-dialog"}
}
The dialog surface (the Dialog element AlertDialog renders) carries alert-dialog.
Family and system relationships
component:Dialogowns modality, focus return, and dismissal; AlertDialog composes it withpurpose="form"semantics and the alert-dialog role.family:overlay-dismissallists AlertDialog as a member: it dismisses through Dialog's shared owner with no deviation of its own; Escape cancels it and a backdrop click does not (FR1).spec:AST-020/FR15decides which APG parts a component adopts; AlertDialog adopts the Alert Dialog pattern's required parts because it already plays that role.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1–FR5 | AlertDialog.test.tsx ("calls onOpenChange(false) on Escape", "does not call onOpenChange when action is clicked", "does not call onAction on Escape", "does not disable the cancel button while the action is loading", "exposes a named group instead, with no aria-modal") and useImperativeAlertDialog.test.tsx ("opens on show()", "closes on hide()") |
open, loading, inline, imperative | Escape not cancelling, the action closing by itself, or the inline path claiming the role fails. | audit:AlertDialog/behavior |
| FR6, PR2 | Browser tests under a coarse pointer in Chromium and WebKit, a theme-token curve oracle for the present and the dismissal, a busy-main-thread case, real-device clips on iOS Safari, and Android Chrome clips in the Android emulator (spec:AST-094 DEC-27) |
present, dismiss, close during present, reopen during dismiss, Reduce Motion, a fine pointer, a narrow viewport | a present or a tap-, key- or program-started dismissal that plays a measured role instead of the theme's entrance or exit duration and easing, a start outside the viewport, a jump on interruption, a scale under Reduce Motion, changed motion under a fine pointer, or an added element fails. No test exists yet; FR6 is not shipped. | audit:AlertDialog/behavior |
| FR7 | DialogTouchEntrance.interaction.browser.spec.ts ("a tap on an alert's action while it enters runs nothing, and once it has entered the same tap runs it"; "keys and assistive technology stay live while the dialog enters") |
a tap during the presentation, Enter and Escape during it, a screen reader's activation, a tap during the dismissal; a mouse click during the presentation under a fine pointer | a held key or assistive-technology action, content made inert during the entrance, a tap that reaches a leaving alert, or a mouse click held under a fine pointer fails. No test covers the leaving alert, which FR6's dismissal brings. | audit:AlertDialog/behavior |
| FR8 | AlertDialog.test.tsx ("AlertDialog action tracking"), useActionGroupTracking.test.tsx and AlertDialog.interaction.browser.spec.ts |
a press on Cancel slid onto the action and lifted, and a press lifted outside the actions, each with a mouse, a pen, and a finger; Enter and Space on each action | the press-start action running after a slide, any action running on a lift outside, or a changed keyboard or assistive-technology activation fails. | audit:AlertDialog/behavior |
| FR9 | Browser tests at a phone width and at a desktop width, in the default and an alternate theme | a phone width and a desktop width, in the default and an alternate theme; a caller width at a phone width; a screen narrower than 320 px; a narrow window under a fine pointer; a coarse screen that is not compact |
a phone-width alert other than 320 px in any theme without a caller width, a caller width overridden, a desktop width changed, an alert wider than the viewport, or a 320 px alert in a narrow fine-pointer window or on a non-compact coarse screen fails. No test exists yet; FR9 is not shipped. |
audit:AlertDialog/behavior |
| AR1 | AlertDialog.test.tsx ("links title via aria-labelledby", "marks cancel as the initial focus target", "keeps the initial focus target on the least destructive action", "calls onOpenChange(false) on Escape", "stacks long destructive action labels above cancel on a narrow fine-pointer screen", "reaches both buttons by Tab, cancel first", "is a modal alertdialog", "does not claim the alertdialog role") and useImperativeAlertDialog.test.tsx; the Alert Dialog accessibility contract binding in __tests__/AlertDialog.a11y.test.tsx and __tests__/AlertDialog.a11y.chromium.spec.ts (role, description link, no backdrop dismiss, focus delegation) |
open modal; after Escape; after Cancel | The role, name link, description link, or Cancel initial focus is lost, or a click outside dismisses the dialog. Gap: the contract keeps alertdialog.focus.least-destructive-first and alertdialog.dismissal.click-beside-is-inert advisory, so a regression in either only reports; spec:AST-020 FR9 makes them required once this record is current. No test covers Tab wrapping inside the alert (Current-state impact). |
audit:AlertDialog/accessibility |
| PR1 | Source review | Small and wide screens | Gap: no automated check fails if AlertDialog adds a listener beyond the small-screen media query. | audit:AlertDialog/behavior |
| RTL relation | RTL audit curated D2 target (apps/storybook/rtl-audit/targets.json) on AlertDialog / Delete (dialog opened) |
Cancel and confirm actions; LTR and RTL | A cancel action that is not at the inline start of the confirm action fails D2. | audit:AlertDialog/i18n-rtl |
Decision log
DEC-1 — An alert holds pointer input while it enters
Reference: component:AlertDialog/DEC-1
Decider: cixzhang, 2026-10-26
An alert follows every touch presentation's entrance hold (spec:AST-094
FR35): pointer input only, never keyboard or assistive technology, and its
content is inert only while it fades out.
DEC-2 — On a phone an alert is 320 px wide in every theme
Reference: component:AlertDialog/DEC-2
Decider: cixzhang, 2026-10-26
A phone-width alert matches iOS's 320 px in every theme, so it reads as a system alert; a theme role for it is not added.
Rejected: a general compact-dialog width theme role.
DEC-3 — An alert's actions are an action group
Reference: component:AlertDialog/DEC-3
Decider: cixzhang, 2026-10-26
A press that slides from Cancel to the action runs the action it lifts on, as
in every group of sibling actions (spec:AST-094 DEC-17), so under the touch
presentation an alert's two buttons behave like a button group.
Rejected: keeping each action's activation on the browser's click alone.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables or examples
(AlertDialog.doc.mjs), Dialog's modal contract, or shared theming rules. It
links to their owners.