JM Family Design System

Dialog

Dialogs interrupt the current workflow for a focused decision, confirmation, or short task. Use them carefully; interruption should earn its place.

Guidance for adoption

Start here before choosing examples or props. These notes explain where Dialog helps, where another pattern is better, and what should stay true in product work.

When to use

  • Critical confirmations
  • Short focused tasks
  • Required decisions
  • Contextual detail

When not to use

  • Long workflows
  • Routine page content
  • Non-blocking feedback
  • Navigation destinations

Accessibility expectations

  • Use role="dialog" or the native dialog element with an accessible name.
  • Trap focus while modal dialogs are open and return focus to the trigger on close.
  • Support Escape to close when closing is allowed.
  • Do not hide essential context behind hover-only content.

Content guidance

  • Write the title as the decision or task, such as "Archive vendor?" or "Add reviewer".
  • Keep body copy concise and focused on the consequence, requirement, or next step.
  • Label primary actions with a specific verb plus object, such as "Delete vendor" or "Send invite".
  • For destructive dialogs, name what will happen and what cannot be undone.

Implementation notes

  • Use the native dialog element until a Dialog component implementation ships.
  • Manage focus trap, scroll lock, Escape behavior, backdrop handling, and return-to-trigger in the consumer.
  • Move long workflows, multi-section forms, and deep navigation to a page instead of a dialog.
  • Use aria-labelledby and aria-describedby so assistive technology gets the title and context.

Usage

<dialog aria-labelledby="…" />

Use the native dialog element for now. A focus-trapping wrapper component is planned.

Usage patterns

Dialogs should be short, specific, and easy to leave. They are not a replacement for pages, panels, or ordinary explanatory content.

Standard dialog
Vendor requirements

Review the required documents before sending the request.

Got it

Use for short, focused content that needs immediate attention.

Confirmation
Submit request?

Procurement will receive this vendor request for review.

CancelSubmit

Use when users need to review a meaningful decision before continuing.

Destructive
Delete vendor?

This cannot be undone and removes the vendor from active workflows.

CancelDelete

Use clear consequence text and a destructive action for irreversible choices.

Short form
Add reviewer
Reviewer email
CancelAdd

Use only for brief tasks; move multi-step work to a page.

Anatomy

A dialog needs a semantic container, accessible title, concise content, clear actions, and focus behavior that does not strand keyboard users.

Archive vendor?

This removes the vendor from active requests.

CancelArchive
  1. Overlay or modal layer
  2. Accessible title
  3. Concise body copy
  4. Primary action
  5. Secondary or close action
  6. Focus management

Usage rules

Use dialogs for justified interruption

A dialog should focus the user on a decision, confirmation, or short task that cannot wait.

Do not put long workflows in dialogs

If the task needs multiple sections, review, or deep navigation, create a page or flow instead.

Return focus after close

Focus should move into the dialog when it opens and return to the trigger when it closes.

Do not hide consequences

Destructive dialogs must name what will happen, what cannot be undone, and the exact object affected.

Known limitations

What Dialog does not do yet, and what consumers need to compose themselves.

  • No Dialog component implementation. The page documents the pattern but no Dialog.tsx ships yet; consumers must use the native dialog element directly until a focus-trapping wrapper lands.
  • Focus management, scroll lock, backdrop click handling, and return-to-trigger behavior are entirely the consumer’s responsibility today.

Related anti-patterns

Catalog entries to watch for when using Dialog. Read these before shipping; they describe the failure modes the system has already documented.

Agent guidance

Agents should generate dialogs only when the user must make a focused decision or complete a short task before returning to the page.

Generation rules

  • Use a dialog only when interrupting the page is justified.
  • Every dialog needs a visible title and a clear primary action.
  • Keep dialog content short; move long workflows to a page.
  • Use destructive confirmation patterns for irreversible actions.
  • Render the native dialog element with showModal() until a wrapper ships. Manage focus trap, scroll lock, backdrop click, and return-to-trigger behavior in the consumer; none of that is built in.
  • Use a Dialog, not a toast or transient alert, when the user must respond before continuing. Hiding a blocking decision in a fading message matches the toast-for-critical-errors anti-pattern.
  • Label the primary action with the specific verb plus object ("Delete project", "Send invite"). Generic labels such as "Confirm" or "Yes" leave assistive tech users guessing what they are confirming.
  • Move focus to the dialog title or the primary action on open, and return focus to the trigger element on close. Save the trigger ref before opening.

Baseline example

<dialog aria-labelledby="archive-title" aria-describedby="archive-desc">
  <h2 id="archive-title">Archive vendor?</h2>
  <p id="archive-desc">This removes the vendor from active requests.</p>
  <button type="button">Cancel</button>
  <button type="button">Archive vendor</button>
</dialog>
If generated content grows beyond a short decision or task, agents should move it to a page, panel, or workflow pattern before adding more controls to the dialog.

Decision standard

Use a dialog when the user must stop and decide. Do not use a dialog just because content feels secondary or the page is crowded.