Version 5.1.0

Dialog

Dialogs display important information that users need to acknowledge. They appear over the interface and block further interactions.

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. Confirmation dialogs should be used when asking users to confirm a choice. The confirmation 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 should be used to communicate important information to users that they need to acknowledge. Before using an information dialog, make sure this is the appropriate communication channel for the message, rather than a toast or a more lightweight 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 should be used when a user has to confirm an action that will impact their data in a destructive way, such as deleting files or contacts. The destructive dialog has a red (negative) button to highlight that 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 should be used to communicate critical information to users in relation to an issue that needs to be acknowledged. The error 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 the dialog’s message (“OK”).

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 show up.
cancel label
text
If undefined, this button does not show up.
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 three 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 best for displaying important information that users need to acknowledge. Use dialogs only when absolutely necessary, not for simple 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.

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 28, 20205.1.0
  • Changed the title color of the error variant from red-500 to gray-900
Aug 22, 20195.1.0
  • Added text overflow behavior
May 20, 20195.0.1
  • Fixed the mobile (large scale) font size for the title and body text in the UI Kit.
Apr 19, 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#


N/A

All interactive states

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

Multiple options

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

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

Defined behaviors

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

Usage guidelines

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

Accessible contrast

Follows WCAG 2.0 standards for contrast (AA).

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.

Generated UI kit

Includes a downloadable XD file that has been generated by code and shows multiple variations, states, color themes, and scales.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are included in Spectrum DNA.