Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
39.6 KB
Raw Blame

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 — isOpen with onOpenChange is controlled; useImperativeAlertDialog owns that pair for a caller that wants show/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:Dialog FR7.

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-groups owns (FR8).
  • Modal presentation, focus return, backdrop, and dismissal mechanics — owned by component:Dialog and architecture:layer-runtime; AlertDialog inherits Dialog's backdrop (component:Dialog FR9).
  • 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 → onAction only.

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-groups FR5 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, within spec:AST-017 FR60's open-layer allowance (architecture:component-style-authoring INV7).

Accessibility contract

  • AR1 — AlertDialog adopts the APG Alert Dialog pattern (spec:AST-020/FR15): the modal surface is role="alertdialog", named by its title through aria-labelledby and described by its description through aria-describedby; it is modal through Dialog (focus enters it and returns to the opener on close per component:Dialog/AR1–AR2, and Tab wraps inside it per component: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 carries role="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:Dialog owns modality, focus return, and dismissal; AlertDialog composes it with purpose="form" semantics and the alert-dialog role.
  • family:overlay-dismissal lists 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/FR15 decides 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.