Alerts & Errors

Communicating Alert Messages & Errors

Refer to our Writing Style guidelines for general best practices in messaging.

‍

‍

Success Messages

For our writing style, if an action is successful, tell it to the user in the most succinct way possible. Don’t be afraid to add a little personality here.

• ❌ Don’t: Successfully changed 1,234 schema titles in NPI.
• ✅ Do: 1,234 titles changed. Nice job!

‍

‍

Error Messages

If an action is not successful, tell the it to the user succinctly what has happened and why. If possible, provide a quick way to remedy the situation.

Don’t be quirky with error messages. Avoid insubstantial words such as "Sorry," "Oops!" or "Uh-oh!"

‍

For user errors

Avoid words like "Invalid" or "Wrong" that may dishearten a user. Instead focus on how they can fix the error. We should be reassuring not negative

• ❌ Don’t: "Oops! You didn’t provide a valid email, so we couldn’t email your colleagues!"
• ✅ Do: "The email that you provided isn’t in our system. Change email?"

‍

For platform errors

If the error happened because of something on our end, we should tell the user that and take ownership.

• ❌ Don’t: "Sorry! We couldn’t email your colleagues."
• ✅ Do: "We couldn’t email your colleagues because something went wrong on our end. Our team has been notified and we’re working on a fix."

‍

‍

Types of Alerts & Errors

‍

Easily Fixable Errors

• Always provide a one-click resolution to an error whenever possible.

‍

User Input Errors

• Only show the error state when a user has finished interacting with a field.
• Show inline validation for user inputs whenever possible.
• By default, if there's a problem validating the user input, put the example/rule broken in red (example A)
• Otherwise, state very plainly what went wrong, and if possible provide a way to fix it (example B)

‍

Server Errors

• Server errors should be hidden unless it directly impacts the currently displayed content or a running or user-attempted task.
• These errors should be presented in the least intrusive manner possible without displaying incorrect content to the user.
• Use error modals only when the error requires user input or a user must be informed. Otherwise use less intrusive AlertBoxes or notifications.
• Always provide information for the quickest possible resolution.

‍

Permission Restrictions

• For actions that a user never has permissions to perform (e.g. Admin Settings) hide the action.
• For actions that are sometimes, but not currently, allowed see the "Disabled Actions" section below.

‍

‍

Disabled Actions

• If actions can't be performed due to an error or improper input, display that action in a disabled state and show a tooltip on hover with information around why it is not possible at the moment.

‍

Confirmations

• Avoid requiring action confirmations except for actions that may trigger: data loss, long-running processes, irreversible actions, or security risks.
• For irreversible actions that may result in significant data loss (e.g. deleting a data source), a confirmation modal should require explicit user text input before confirmation is allowed.