Dialogs

A dialog focuses attention on a task or decision. Titles use sentence case; allow one primary action per dialog. Use modals sparingly — they interrupt workflow.

When to use

• Confirmations and irreversible actions (delete, discard changes).
• Short focused tasks that must complete before continuing (apply settings, name a file).
• Critical information the user must acknowledge.

When not to use

• Long multi-step workflows — use Feature Panels or a dedicated view.
• Low-priority feedback — use inline validation or Error Handling toasts.
• Contextual hints — use Tooltips or Bubble.

Choose the right pattern

Pattern	Blocks app	Best for
Modal dialog	Yes	Confirmations, critical decisions, short forms
Modeless dialog	No	Tools that adjust the active view with live preview
Feature panel	No	Multi-section settings, wizards, persistent side panels
Bubble	No	Lightweight contextual UI anchored to a trigger

Anatomy

Element	Description
Scrim	Dimmed backdrop for modal dialogs
Container	Raised surface (elevation overlay level)
Title	Brief, clear — avoid alarmist copy
Body	Concise context; do not repeat the title
Actions	Max two recommended; one primary only

Button placement

Primary action on the right, secondary on the left. Labels should be outcome verbs: Delete, Save, Continue — not vague Yes/Submit.

Example

Accessibility

• Trap focus inside modal dialogs; restore focus to trigger on close.
• Escape dismisses modal overlays when appropriate.
• Title is referenced with aria-labelledby; describe purpose in the body.
• Do not disable the primary action without explaining why in the dialog body.

Related components

• Button — primary and secondary actions
• Forms — fields inside dialog body
• Feature Panels — non-blocking alternatives