Dialogs display important information that users need to acknowledge. They appear over the interface and block further interactions until an action is selected.
All dialogs must have a title. Titles appear in bold at the top of the dialog and use a few words to convey the outcome of what will happen if a user continues with an action.
Dialogs can include a description. Descriptions briefly communicate any additional information or context that a user needs to know in order to make one of the decisions offered by the buttons.
Destructive dialogs are for when a user needs to confirm an action that will impact their data or experience in a potentially negative way, such as deleting files or contacts. This dialog has a red (negative) button to highlight the destructive action.
Error dialogs communicate critical information about an issue that a user needs to acknowledge. This dialog has a warning icon to reinforce its importance.
A dialog must have at least one button. The primary action label is for the first (right-most) button. It communicates what the button will do with a short, actionable phrase to either describe the next step if selected, or to acknowledge and dismiss the dialog.
A dialog can have a total of 3 buttons if the secondary outline button label is defined. If left undefined, the button won’t appear. The secondary outline button label communicates what the button will do with a short, actionable phrase to describe what will happen in the next step, if selected.
A dialog with a button that offers an option to go back and cancel the action will have a label of “Cancel,” by default.
From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework.
confirmation / information / destructive / error
If undefined, this button does not appear.
If undefined, this button does not appear.
When the title and body text are too long for the available horizontal space, they wrap to form another line.
A dialog can have up to 3 buttons. When horizontal space is limited, button groups stack vertically. They should appear in ascending order based on importance, with the most critical action at the bottom.
Dialogs are interruptive, so they're best for displaying important information that users need to acknowledge before moving forward with a task or workflow. Use dialogs only when absolutely necessary, not for low-signal notifications or excessive confirmations.
Dialogs are meant to interrupt the experience until a resolution is reached, so there should only be one dialog displayed at a time. Don't open a dialog from within another dialog. If the situation seems to require a sequence of decisions, look into using a different design altogether.
Writing for dialogs starts by determining the nature of the message. Each Spectrum dialog variant has its own communication goal and tone that work in partnership with its visual design.
|Confirmation||Asking a user to confirm an action they want to take.||Instructive|
|Information||Sharing important information that a user needs to acknowledge.||Helpful|
|Destructive||Telling a user that if they are to proceed with an action they want to take, it may impact their data in a negative way.||Instructive|
|Error||Communicating critical information about an issue that a user needs to resolve before they can move forward with a task.||Supportive|
All dialogs must have a title. The title communicates the upshot of the message, such as the eventual outcome or conclusion of an action. It should be as close as possible to a complete sentence (subject + verb). Don’t use punctuation at the end of the title.
Most dialog titles communicate the main effect of whatever a person is about to do. Titles ideally use the same or similar phrasing as the call-to-action that had led someone to the dialog in the first place.
The title of an error dialog communicates the result of the error. Don’t just state that an error has occurred.
Dialog descriptions share any additional information or context that a person needs to know in order to make one of the decisions offered by the actions. Descriptions are written in complete sentences, and any error code is included in parentheses at the end of the last sentence.
Use a short phrase to succinctly describe the options for next steps. If possible, have the button label use the same language as the action mentioned in the dialog title (e.g., if a dialog's title is “Delete conversation,” its primary action button label would be “Delete”).
For dialog buttons, make the labels as specific and actionable as possible. Even if someone were to only read the word or phrase on the button, they should be able to get a summary of the dialog’s entire message.
Questions in dialog titles — such as “Are you sure you want to quit?” or “Do you want to cancel?” — are redundant and undermine a user's agency in the decision they've already made by taking a previous action to get to the dialog. This phrasing also sets up for a yes/no set of actions, which can become confusing. Instead, reframe the message to focus on the outcome or effect.
It’s OK to ask a question in a dialog's description to confirm if someone wants to go ahead with a choice that the system is making on their behalf. However, this should still be paired with distinct actions that show that a person has control over what happens next.
For RTL (right-to-left) languages, the layout of the dialog is mirrored. Texts are right-aligned and buttons are left-aligned.
|Tab||Moves focus to the next button inside the dialog (last becomes first). If none of the buttons are selected, the focus is set on the first button.|
|Shift + Tab||Moves focus to the previous button inside the dialog (first becomes last). If none of the buttons are selected, the focus is set on the last button.|
|Esc||Dismisses the dialog. This is equivalent to choosing “Cancel” or an “OK” confirmation.|
|Mar 29, 2021||5.2.0|
|Feb 29, 2020||5.1.1|
|Aug 22, 2019||5.1.0|
|May 21, 2019||5.0.1|
|Apr 20, 2019||5.0.0|
Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).
Works properly across all four color themes (lightest, light, dark, darkest).
Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).
Color is not used as the only visual means of conveying information (WCAG 2.0 1.4.1).
Text has a contrast ratio of at least 4.5:1 for small text and at least 3:1 for large text (WCAG 2.0 1.4.3).
Visual information required to identify components and states (except inactive components) has a contrast ratio of at least 3:1 (WCAG 2.1 1.4.11).
UI language and information design considerations have been incorporated into component design.
Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)
Includes guidelines for keyboard focus, layout (wrapping, truncation, overflow), animation, interactions, etc.
Includes a list of dos and don'ts that highlight best practices and common mistakes.
Includes content standards or usage guidelines for how to write or format in-product content for the component.
Works properly across various locales and includes guidelines for bi-directionality (RTL).
Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.
All design attributes (color, typography, layout, animation, etc.) are available as design tokens.
Includes a downloadable XD file that shows multiple options, states, color themes, and platform scales.
Includes a downloadable XD file, generated by code using design tokens defined in Spectrum DNA, and shows multiple options, states, color themes, and platform scales.
Component is included in the Spectrum for Adobe XD plugin.