# Dialog

Stops the page for a decision or a short task and returns focus to the control that opened it.

* Kind: component
* Page: https://design.werklist.com/components/dialog
* Version: 2.1.2

## When to use it

* A decision the page cannot go on without, such as deleting a candidate for good
* A short form that belongs to one moment, such as adding a task
* A record with its history, in the large size

## When not to use it

* An action that can be undone: act at once and offer Undo in a toast
* Details read beside the page: use a side sheet
* A few controls for one item: use a popover
* Information that needs no answer: use a toast or an inline message
* A dialog opened from a dialog, except a confirmation about the dialog beneath

## Anatomy

* Layer: covers the whole window, above the page (--layer-dialog)
* Scrim: no blur, fades in over 150 ms (--overlay)
* Margin to the window: 24 px (--space-6)
* Panel: radius 16 px, at most 92 percent of the window high (--glass-fill-raised, --glass-blur-raised, --elevation-3, --radius-2xl)
* Panel edge, dark theme: a 1 px top highlight and a 0.5 px ring over the shadow. The light theme shows the shadow alone (--glass-highlight, --glass-ring-raised)
* Header: padding 16 px top, 20 px left, 12 px right (--space-4, --space-5, --space-3)
* Title: h2, 17 px on a 24 px line, weight 700 (--text)
* Description: 14 px on 22 px, 4 px below the title (--type-small, --text-muted)
* Close button: icon button, 32 px, 44 px on touch screens, with a 16 px cross
* Body: padding 8 px top, 20 px sides, 20 px bottom without a footer, 8 px with one. Scrolls on its own, and the page behind stays still (--space-2, --space-5, --type-small, --text)
* Footer: padding 16 px top and bottom, 20 px sides. Actions at the end, 8 px apart (--space-4, --space-5, --space-2)
* Footer buttons: 36 px high, 44 px on touch screens
* Line while scrolled: 1 px under the header while content is hidden above, above the footer while content is hidden below (--border-rule)

## Variants

* Standard: A form or content. role dialog, close button, closes on a scrim click when nothing is typed
* Confirmation: A question before an action that cannot be undone. role alertdialog, small size, no close button, the scrim does nothing, focus starts on Cancel, the verb takes the danger button when it deletes

## Sizes

* Small, 448 px wide: confirmations and notices
* Medium, 512 px wide: forms
* Large, 896 px wide: a record with its history
* Below 640 px: a bottom sheet. Large fills the screen inside the safe areas

## States

* Opening: The scrim fades in over 150 ms. The panel fades in, grows from 97 percent and rises 8 px, over 200 ms (--duration-fast, --duration-base, --ease-soft)
* Closing: Reverse, over 150 ms (--duration-fast, --ease-standard)
* Reduced motion: Opacity only (--duration-fast)
* Scrolled: The 1 px line shows under the header or above the footer while content is hidden behind it (--border-rule)
* Busy: The completing button is busy at once (aria-busy, presses ignored) and shows its spinner after 300 ms. The rest of the dialog stays usable (--duration-slow)
* Save failed: A message in the error tone at the top of the body, role alert. The entries stay as typed and focus stays on the button (--error-ink)
* Invalid entry: After a failed submit, focus moves to the first field with an error, and its message sits under that field
* Content loading: Header and footer show at once over a skeleton of the body
* Unsaved entries: Escape, the close button, a scrim click and a swipe open the confirmation Discard the changes? with Keep editing and Discard. Cancel closes without asking

## Keyboard

* Tab: Next control. From the last back to the first
* Shift+Tab: Previous control. From the first to the last
* Enter in a single line field: Submits the form
* Enter or Space on a button: Activates it
* Escape: Closes the front layer only. Asks first when entries are unsaved. In a confirmation, answers Cancel

## Accessibility

* role dialog or alertdialog, aria-modal true, aria-labelledby the title. Aria-describedby the body of a confirmation
* Focus on open: the first field of a form, Cancel in a confirmation, the panel itself (tabindex -1) when it only shows content
* Tab reaches only the controls that show in the dialog
* Focus on close: the control that opened the dialog, if it is still on the page. Otherwise the next row, the previous row, then the list
* The page behind ignores the pointer, keys and screen readers, and does not scroll or shift sideways
* The close button is named Close
* Controls at least 44 px high on touch screens
* In forced colors mode the panel draws a 1 px outline in the system text color
* Escape reaches the front layer only, so a menu open inside the dialog closes before the dialog

## Content

* The title names the task or asks the question. No end punctuation except a question mark
* The body adds only what the title cannot hold and starts with the consequence
* Buttons answer the title with a verb, plus a noun when the verb alone is ambiguous. Cancel is always Cancel. No OK, Yes or No
* Example: Delete this candidate permanently? / Sunita Rai's CV, passport scan and interview notes are removed now and cannot be restored / Cancel, Delete candidate
* Save failed message: The task was not added. Try again

## Tokens

* --layer-dialog
* --overlay
* --glass-fill-raised
* --glass-blur-raised
* --glass-highlight
* --glass-ring-raised
* --elevation-3
* --radius-2xl
* --space-2
* --space-3
* --space-4
* --space-5
* --space-6
* --type-small
* --text
* --text-muted
* --border-rule
* --error-ink
* --duration-fast
* --duration-base
* --duration-slow
* --ease-soft
* --ease-standard
* --focus-ring