Dialogs & Overlays

Scale dialog structure

Use the existing scrim and command-modal structure. The panel receives animation-scale while the scrim handles backdrop placement.

<div className="command-modal-scrim is-visible" role="presentation">
  <section
    className="command-modal animation-scale"
    role="dialog"
    aria-modal="true"
    aria-labelledby="dialog-title"
  >
    <header><h2 id="dialog-title">Task details</h2></header>
    <div className="dialog-body">...</div>
    <footer>...</footer>
  </section>
</div>

Use one scroll owner

Let the page body or scrim own viewport scrolling. Inside the dialog, make only the content body scroll when a fixed header and footer are required. Do not add overflow auto to both the panel and its body.

.feature-dialog {
  max-height: calc(100svh - 32px);
  overflow: hidden;
}

.feature-dialog-body {
  min-height: 0;
  overflow-y: auto;
}

Interaction contract

A modal dialog traps focus, closes on Escape when safe, restores focus to its trigger, and prevents interaction with the background.

• Meaningful title
• Initial focus
• Escape behavior
• Close button label
• Focus restoration
• Mobile viewport test

Destructive confirmation

Use alertdialog only when the user must acknowledge a consequential decision. State the affected record and whether the action can be undone.