Writing for alert dialogs starts by determining the nature of the message. Each Spectrum alert dialog variant has its own communication goal and tone that work in partnership with its visual design.

Alert dialog variant
Goal
Tone
Confirmation
Asking a user to confirm an action they want to take.
Instructive
Information
Sharing important information that a user needs to acknowledge.
Helpful
Warning
Sharing time-sensitive information that a user needs to consider, but won’t block them from proceeding.
Instructive to 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

Writing the title

All alert 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 alert 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 alert dialog in the first place.

The title of an error alert dialog communicates the result of the error. Don’t just state that an error has occurred.

Writing the description

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

Writing the 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 alert dialog title (e.g., if a dialog's title is “Delete conversation,” its primary action button label would be “Delete”).

Make button labels specific and actionable

For alert 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 alert dialog’s entire message.

Avoid asking questions

Questions in alert 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 alert 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.

Pair confirmation with distinct actions

It’s OK to ask a question in an alert 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.