Overview
Notification messaging is crucial for communicating with users and providing timely feedback. It can contain product updates, contextual information about the action they are performing, speak to system status, and more. How we deliver messages depends on their type and urgency.
Here are the key principles to follow when working with messaging:
|
Key principle |
Description |
|---|---|
|
Timely |
Deliver messages promptly concerning users’ actions so people are aware of urgent notifications as they happen. |
|
Concise |
Provide concise information that’s easily understood: if 1-3 sentences are insufficient, link to a relevant blog post or support documentation. |
|
Relevant |
Always connect messages to user’s context and what goal they’re trying to achieve. |
|
Considerate |
Consider when and how frequently you’re delivering messages: be thoughtful about people’s attention span and time. |
When to use notification messaging
Clearly communicating system status and helping users recover from errors are two key usability heuristics relevant to messaging. Additionally, you might be using messaging to educate about the product and its features.
Most messages fall into the following use cases, ordered by most urgent to the least (left to right):
|
Use case |
System updates |
Task feedback |
Educational |
|---|---|---|---|
|
Example preview |
|
|
|
|
Description |
System updates come from Octopus rather than responding to user action. In most cases, they are not dismissable and will be removed once an incident or notice period has passed (in the case of deprecation notices). |
Task feedback messages directly respond to a user’s action (e.g., submitting a form or changing settings). They can communicate success, warning or an error, with steps to resolve potential issues. Feedback should always be shown as close as possible to the related sections or fields. |
Educational messages communicate relevant (but not critical) information that is not related to the user’s actions. They use progressive disclosure to build knowledge and familiarity with the product and its features. |
|
Components |
Global banner, Error page, In app message, Inline Message |
Inline validation, Error Summary, Callout |
Popover, Tooltip, Tours, Callout |
Considerations for messaging
Message priority
Messages have different priority levels: based on how critical they are to users, they vary in disruptiveness. Following our key messaging principles, we avoid grabbing users’ attention when it’s unnecessary and are careful about the timeliness of notifications.
|
Priority |
Use case |
Placement |
Components |
|---|---|---|---|
|
High |
System updates |
Global |
Error pages, Global banners, In-app notifications |
|
Medium |
Task feedback |
Top of page/content area, inline |
Inline validation, Error Summary, Callout |
|
Low |
System updates, Task feedback, Educational |
Inline |
Popover, Tooltip, Tours, Inline Message |
Message placement
Proximity helps users understand and organize information faster and more efficiently. A message should be located nearby if it is connected to a specific element (e.g., an input field or a section). The placement of a message within a page also correlates to its priority and what area it affects.
Global
Use global messaging when the content of the communications affects the entirety of the application (e.g., deprecation notices, trial status, changes in access levels). Most global, in-app messaging is handled with Chameleon, which makes it possible to segment the audience and deliver contextual messaging. Only one global message should be present at a time.
Top of page (or content area)
Use top of page or content area messages when communicating in relation to a section or entirety of a page. This approach is useful when gathering feedback from users or requiring users to complete an action linked in the notification. Only one top of page (or content area) message should be present at a time.
Examples include:
- Callout, when communicating an important, high-visibility (standard variant) or non-urgent, medium-visibility (outlined variant) message. It may also prompt users to take action.
- Error Summary, when highlighting one or more server errors, either due to exceptional circumstances or form validation issues.
Inline
Use inline messages when providing information or feedback about a specific element in the interface.
Examples include:
- Error messages, when validating data provided by a user in an input field or adding guidance to a field
- Inline Message component, when providing a subtle system message in relation to another element, like a paragraph or input field
Inline messages are meant to be short (maximum of 3 sentences) and used sparingly (don’t crowd a page or section with inline messages, instead, summarize multiple messages in one container).
Message state
State conveys the importance of the message and the type of response it should invoke in users. State is conveyed through tone of voice, associated color, and iconography choice, all working together. Using states consistently creates a predictable experience for users.
Choose one of the following states based on the usage intention:
|
Message state |
Usage |
Color palette |
Iconography |
|---|---|---|---|
|
Informational |
Provides additional, but not critical, information that might not be tied to the action the user is currently performing. |
Blue |
info-circle |
|
Warning |
Informs about a potential unexpected or adverse result of a user action. |
Yellow |
exclamation-triangle |
|
Danger |
Used to alert the user about an error that occurred when completing an action, or critical information (e.g., an expired token, a deprecated feature, storage limit reached). |
Red |
exclamation-diamond |
|
Success |
Informs about a successfully completed action. |
Green |
check-circle |
|
Feature |
Informs about a new (or upcoming) feature, functionality, or beta program to raise user adoption. |
Purple |
rocket |
|
Upsell |
A special state reserved only for upsell flows by the Product Growth team. |
Purple |
gem |
AI and the sparkles icon
We previously used a sparkles icon for the Feature message state. Since the sparkles icon has become synonymous with AI, we now recommend avoiding it for anything unrelated to AI.
Message content
When writing notification messaging copy:
- Follow the Tone of Voice guidelines.
- Use a grammar checker and follow the Grammar guidelines.
- When writing error messages, follow the Error Messaging pattern.
- Adjust the tone based on the level of urgency of the message.
How to choose a messaging approach
Choosing the right way to communicate with users often isn’t straightforward. Refer to the flowchart below to pick the most suitable approach for your use case:
