## When to use

Action is irreversible, affects others (workspace-wide delete, billing change), or violates a strong invariant (data loss). The interruption is the point — modal blocks the page; the user must explicitly confirm or cancel. Distinct from inline-dialog (reversible micro-decisions) and from confirm-toast (reversible with timed undo).

## Simple — one-click confirm

For ordinary destructive actions where the consequence is bounded (delete a single item). Title carries the question; body carries the consequence; Cancel + Delete actions. modal-ui's `[text]` attribute is the title — don't author a separate `<header>`.

This action cannot be undone. The item will be permanently removed from your workspace.

## Type-to-confirm — high-consequence gate

For workspace-wide / billing / account-level destructives. User must type the resource name (or a fixed string like "DELETE") into the input — the danger button stays disabled until the typed string matches verbatim. Friction is the point: prevents muscle-memory mistakes.

This will permanently delete the workspace, all members, all data, and all integrations. This cannot be undone.

## Warning — unsaved changes

Non-destructive but interrupts to surface a consequence ("leaving this page will lose your edits"). Same alertdialog role; primary action is the SAFE path (Save & close) with the risky path (Discard) as an outline button.

You have unsaved changes to this document. Leaving will lose them.

## Composition rules

- role="alertdialog" (not "dialog") — WAI-APG calls out alertdialog for "demands acknowledgement before continuing". Screen readers announce more assertively + don't allow tab-out to background content.
- Use modal-ui's `[text]` attribute for the title — NOT a child `<header>`. modal-ui auto-stamps the title bar from the attr; authoring your own header collides with the default slot (and the title ends up rendered as body content). See the modal-ui docs for its canonical slot vocabulary.
- Default size is md — don't downsize to `sm` "to look tighter". md gives the action buttons proper breathing room. Use `lg` only when the body has a multi-section form.
- Cancel is safe + first — render Cancel as `variant="ghost"` on the left; render the destructive action as `color="danger"` on the right. Pressing Enter on whatever has focus is the muscle-memory danger — keep Cancel-shaped affordances obvious.
- Type-to-confirm for high-consequence — disable the danger button until the user types the resource name verbatim. The inline `oninput` handler toggles `[disabled]`. Friction is the feature.
- Prose names the consequence + the scope — "all members, all data, all integrations" beats "this workspace and its contents". Specific scope reduces re-read time.
- Three buttons max — Cancel + 1 or 2 actions. Anything more is a settings surface, not an alert.

## Cross-references

- modal-ui — the surface primitive ([text] attribute for title; slot="footer" for actions; role override via `role="alertdialog"`).
- inline-dialog — reversible micro-decision alternative (anchored, non-modal).
- toast-ui — undo-able confirmation alternative (non-blocking, timed).
- WAI-APG alertdialog — pattern source.