Version 5.1.1

Dialog

Dialogs display important information that users need to acknowledge. They appear over the interface and block further interactions until an action is selected.

Key example of a confirmation dialog. Dialog title, Enable smart filters. Dialog description, Smart filters are nondestructive and will preserve your original images. Two calls to action, Cancel and Enable.Key example of a confirmation dialog. Dialog title, Enable smart filters. Dialog description, Smart filters are nondestructive and will preserve your original images. Two calls to action, Cancel and Enable.

Anatomy#


Image illustrating through labels the component parts of a confirmation dialog, including its title, background, and background overlay.

Options#


Key example of a dialog title with horizontal divider underneath. Dialog title, Enable smart filters.

Title#

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.

Key example of a dialog description wrapped in two lines, Smart filters are nondestructive and will preserve your original images.

Description#

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.

Key example of a confirmation dialog. Dialog title, Enable smart filters? Dialog description, Smart filters are nondestructive and will preserve your original images. Two calls to action, Cancel and Enable.

Confirmation variant#

This is the default variant for dialogs. Use a confirmation dialog for asking a user to confirm a choice. This dialog has a call to action button to highlight a strong preference for which action to take.

Key example of a confirmation dialog. Dialog title, Connect fo wifi. Dialog description, Please connect to wifi to sync your projects or go to Settings to change your preferences. Two calls to action, Cancel and Continue.

Information variant#

Information dialogs communicate important information that a user needs to acknowledge. Before using this kind of dialog, make sure it's the appropriate communication channel for the message instead of a toast or a more lightweight messaging option.

Key example of a confirmation dialog. Dialog title, Delete 3 documents. Dialog description, The selected documents will be deleted. Two calls to action, Cancel and Delete.

Destructive variant#

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.

Key example of a confirmation dialog. Dialog title, Unable to share. Dialog description, An error occurred while sharing your project. Please verify the email address and try again. One call to action, OK.

Error variant#

Error dialogs communicate critical information about an issue that a user needs to acknowledge. This dialog has a warning icon to reinforce its importance.

Key example of primary button in button group of 3. Call-to-action button. Label, Enable.

Primary action label#

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.

Key example showing button group of 3 where middle button is a secondary button labelled Remind me later.

Secondary action label#

A dialog can have a total of 3 buttons if the secondary button label is defined. If left undefined, the button won’t appear. The secondary button label communicates what the button will do with a short, actionable phrase to describe what will happen in the next step, if selected.

Key example of cancel button on the left-most of a button group, labelled Cancel.

Cancel action label#

A dialog with a button that offers an option to go back and cancel the action will have a label of “Cancel,” by default.

Table of options#

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.

PropertyValuesDefault Value
title
text
description
text
variant
confirmation / information / destructive / error
confirmation
primary label
text
secondary label
text
If undefined, this button does not appear.
cancel label
text
If undefined, this button does not appear.
Cancel

Behaviors#


Key example of a confirmation dialog. Dialog title, Use Creative Cloud Libraries in Bridge. Dialog description, Your Creative Cloud Libraries are now available in Bridge in a new workspace called Libraries, giving you quick access to the colors, text, materials, brushes, images, videos, and other creative assets you use most. You can also add images to libraries from Bridge. Two calls to action, Cancel and Go to Libraries.

Text overflow#

When the title and body text are too long for the available horizontal space, they wrap to form another line.

Key example of a confirmation dialog. Dialog title, Rate this app. Dialog description, If you enjoy our app, would you mind taking a moment to rate it? Three calls to action stacked vertically, No, thanks, Remind me later, and Rate now.

Button group overflow#

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.

Usage guidelines#


Use dialogs sparingly#

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.

Key example showing incorrect usage of a dialog. Dialog title, Success. Dialog description, Your file is uploaded. One call to action, OK.

Don't nest dialogs#

Dialogs are meant to interrupt the experience until a resolution is reached, so there should only be one dialog displayed on the screen 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.

Key example showing incorrect usage of a dialog, with one dialog over another. Dialog title, Confirm logout. Dialog description, Are you sure you want to log out? Two calls to action, Cancel and OK.

Content standards#


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.

Dialog variantGoalTone
ConfirmationAsking a user to confirm an action they want to take.Instructive
InformationSharing important information that a user needs to acknowledge.Helpful
DestructiveTelling 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
ErrorCommunicating critical information about an issue that a user needs to resolve before they can move forward with a task.Supportive


Title#

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.

Key examples of how to write titles for dialogs. 2 examples of titles for confirmation dialogs. Delete 13 files. Move final.pdf to library. 3 examples of titles for error dialogs. Adobe XD needs to restart. We can’t show your complete file list. Can’t share for review or development.

Description#

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.

3 key examples of how to write descriptions for dialogs. First example text, Creative Cloud Sync isn’t up to date or isn’t running correctly. (Error 50). Second example text, You aren’t the owner of this document. Save as a new document to share it, or ask the document owner to share. Third example text, Your files and shared files now live on the newly redesigned site. We’re moving libraries and mobile creations there soon.

Actions#

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”).

5 key examples of how to write button labels for dialog actions. 4 primary action labels, text Save as…, Go to new site, OK, Try again. 1 secondary action label, text Cancel.

Make button labels specific and actionable#

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.

Key example of correct way to write a dialog button label that is actionable Primary action button, label Delete.
Key example of incorrect way to write a dialog button label. Primary action button, label Yes.

Avoid asking questions#

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.

Key example of correct way to write a dialog, not using any questions. Dialog title, Delete conversation. Dialog description, The original post and all replies will be deleted. Primary action, label Delete. Secondary action, label Cancel.
Key example of incorrect way to write a dialog, by using questions. Dialog title, Delete conversation? Dialog description, Are you sure you want to delete the conversation? The original post and all replies will be deleted if you delete it. Primary action, label Yes. Secondary action, label No.

Pair confirmation with distinct actions#

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.

Key example of writing a dialog to show confirmation with distinct actions. Dialog title, Different account found. Dialog description, We’ve found an existing subscription associated with your Adobe ID: wilson@adobe.com. Do you want to sign into that account instead? Primary action, Continue. Secondary action, Change account.

Internationalization#


Key example of a confirmation dialog in Arabic. Dialog title, Enable smart filters?. Dialog description, Smart filters are nondestructive and will preserve your original images. Two calls to action, Cancel and Enable.

RTL#

For RTL (right-to-left) languages, the layout of the dialog is mirrored. Texts are right-aligned and buttons are left-aligned.

Keyboard interactions#


KeyInteraction
TabMoves 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 + TabMoves 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.
EscDismisses the dialog. This is equivalent to choosing “Cancel” or an “OK” confirmation.

Changelog#


DateNumberNotes
Feb 29, 20205.1.1
  • Changed the title color of the error variant from red-500 to gray-900
Aug 22, 20195.1.0
  • Added text overflow behavior
May 21, 20195.0.1
  • Fixed the mobile (large scale) font size for the title and body text in the UI Kit.
Apr 20, 20195.0.0
  • This component is now individually versioned (individual versions of existing components start at 5.0.0)
  • Added RTL (right-to-left) guidelines

Design checklist#


All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

Accessible use of color

Color is not used as the only visual means of conveying information (WCAG 2.0 1.4.1).

Accessible contrast for text

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).

Accessible contrast for UI components

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).

Content design

UI language and information design considerations have been incorporated into component design.

Defined options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

Defined behaviors

Includes guidelines for keyboard focus, layout (wrapping, truncation, overflow), animation, interactions, etc.

Usage guidelines

Includes a list of dos and don'ts that highlight best practices and common mistakes.

Writing guidelines

Includes content standards or usage guidelines for how to write or format in-product content for the component.

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are available as design tokens.

N/A

UI kit

Includes a downloadable XD file that shows multiple options, states, color themes, and platform scales.

Generated UI kit

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.

In Spectrum for Adobe XD plugin

Component is included in the Spectrum for Adobe XD plugin.