Dialogs

OverviewCopy Anchor Link

Both patterns share the same .nm-dialog card and sit inside a .nm-dialog-backdrop that dims and blocks the page behind them. They differ in scope: a Confirmation Dialog only ever asks for a single yes/no decision; a Modal Dialog can hold any short, focused task.

When to use — Confirmation DialogCopy Anchor Link

• Before a destructive or hard-to-reverse action (delete, discard, cancel a subscription).
• The decision is binary — proceed or don't — and needs no other input.

When to use — Modal DialogCopy Anchor Link

• A short, self-contained task that needs the user's full attention (a quick edit form, a single setting, reviewing terms before continuing).
• Content that's too long for a Confirmation Dialog's single description line but still doesn't warrant its own page.

Consider another component when:Copy Anchor Link

• The feedback doesn't need to block the page — use Alert or Toast.
• The content is anchored to a specific trigger and the rest of the page should stay usable — use Popover.

AnatomyCopy Anchor Link

Every dialog is a header (icon, title, close), a body, and a footer of actions, floating on a backdrop. Confirmation Dialog indents its body to align with the title, next to the header icon; Modal Dialog does not.

Tokens and values that drive each partCopy Anchor Link

Sizes (Modal Dialog)Copy Anchor Link

Modal Dialog scales via max-width, defaulting to md. Confirmation Dialog is fixed at its own 480px max-width and doesn't use these size modifiers.

Intent variantsCopy Anchor Link

Both patterns share seven intents that recolor the border and header icon; the card fill always stays neutral (--nm-dialog-bg).

Content typesCopy Anchor Link

Confirmation DialogCopy Anchor Link

Fixed-width, header icon paired with an indented, single-purpose description, and exactly two footer actions — a neutral escape and one committing action.

Modal DialogCopy Anchor Link

General body content, no forced indentation, sized to fit what it holds.

Modal Dialog — collapsibleCopy Anchor Link

.nm-dialog--collapsible animates its body and footer between shown and .is-collapsed, toggled by .nm-dialog__toggle instead of (or alongside) a close button — useful for "show details" style disclosure inside a modal.

Light & dark themeCopy Anchor Link

--nm-dialog-bg, -fg, -icon-color, and both shadow tokens are explicitly remapped under .dark — the card stays a neutral surface color independent of intent in both themes.

Both previews are locked — they don't follow the page theme switcher.

Do & don'tCopy Anchor Link

AccessibilityCopy Anchor Link

SemanticsCopy Anchor Link

• Give the card role="dialog" (or role="alertdialog" for a Confirmation Dialog on a destructive action), aria-modal="true", and label it with aria-labelledby pointing at .nm-dialog__title.
• Describe it with aria-describedby pointing at .nm-dialog__description.

FocusCopy Anchor Link

• On open, move focus to the dialog — the title, the first focusable element, or the least destructive footer action (never the destructive one by default).
• Trap Tab/Shift+Tab focus inside the dialog while it's open; nothing behind the backdrop should be reachable.
• On close, return focus to whatever triggered the dialog.

KeyboardCopy Anchor Link

• Escape closes the dialog, equivalent to the close button — unless the dialog represents an unsavable, irreversible in-progress action.
• Clicking the backdrop should close the dialog the same way Escape does, unless doing so would silently discard unsaved input.

LabelingCopy Anchor Link

• Never make the destructive action the visually dominant one by default focus/color alone — pair it with a clear, specific label.

Token referenceCopy Anchor Link

ImplementationCopy Anchor Link

Open/close state, focus trapping, and backdrop click handling need JavaScript (or the native <dialog> element); the card and backdrop themselves are pure CSS.

<link rel="stylesheet" href="namirial-theme.css">

<div class="nm-dialog-backdrop">
  <div class="nm-dialog nm-dialog--confirmation nm-dialog--negative" role="alertdialog" aria-modal="true" aria-labelledby="dlg-title" aria-describedby="dlg-desc">
    <div class="nm-dialog__header">
      <span class="nm-dialog__header-icon" aria-hidden="true"><!-- icon --></span>
      <h3 class="nm-dialog__title" id="dlg-title">Delete this document?</h3>
    </div>
    <div class="nm-dialog__body">
      <p class="nm-dialog__description" id="dlg-desc">This action can't be undone.</p>
    </div>
    <div class="nm-dialog__footer">
      <button type="button" class="nm-button nm-button--secondary nm-button--md nm-button--ghost">Cancel</button>
      <button type="button" class="nm-button nm-button--negative nm-button--md">Delete</button>
    </div>
  </div>
</div>

CSS classesCopy Anchor Link