Effective in-product messaging is key to a good user experience.
In-product communications
ExperimentalUpdated May 12, 2026
The Design System has multiple components available to convey messages, but it's important to know how to apply them.
This guide will help you select the most appropriate components to suit your particular use case. Remember, it's OK to have variations, to adapt to specific needs. The Design System covers most use cases, but there will always be times when we have to adapt for more unique scenarios.
Considerations
Does the user need to know this right now?
Before you continue, consider if the user really needs to know this bit of information. Users can be overwhelmed with excessive messaging – including notifications – which can lead to messages being ignored.
Use messages sparingly and only when trying to convey important, or contextually relevant information to the user.
Additional things to consider
- What triggers the message? Was it the current user? Did something happen in the background (system or another user)?
- Is it related to the content on the current screen? Is it more general?
- How urgent is it to the user?
- How important is the message in relation to the user's work or life?
Read on for best practice on in-product messaging. Start with our decision tree for simple scenarios.
Detailed component guide
Component decision tree
Use our decision tree to walk through some basic scenarios to help you find the right component.
Decision tree
If your scenario is more complex, try our interactive component finder (opens in new tab).
Additional component finder tools
The 'Guess Who?' component board
Use our 'Guess Who?' board for a quick reference to find the right component.
Guess who board
Criteria ranges
You could also use our criteria ranges to help you decide.
Importance level range – should we disrupt the user's workflow?
Should the message be pushed in front of the user to interrupt their workflow and force them to act? Or should it be more subtle to let the user know something has happened in the system, but it can wait?
Disruptive
Action required
The message can be important, but not necessarily something the user needs to do something about (such as a notification).
Action
Context
This defines the message's relationship with the content on the page.
Contextual
Where to position your components
- Contextual messages tend to perform best when placed inline with content on the page.
- Out-of context messages are more suited to components like dialogs and notifications.
If you're still unsure where to position your message or multiple messages, use our specific component guides.
Content guidelines
- Use the active voice in the present tense.
- Use direct, plain language to explain what happened, why it happened, and how to fix it.
- Provide reassurance, empathize with the user, and do not blame them.
- Give the user a way out of the situation.
- Use specific error messages for specific error states. Avoid generic error messages where possible.
- Do not use exclamation marks or all capital letters.
- Do not include error codes or technical jargon.
- Avoid using sorry, must, or please.
In-product communications content examples
Helpful error message
Unhelpful error message
System and API errors
| Error | Description | Component |
|---|---|---|
| Global error | Generated by the system or API.For example, the system cannot connect to the network or data is not sent from a related system because of problems with the system.Cannot be resolved by the user. | Message full-width and pinned to the bottom of the app bar (pushing the rest of the content down).orError page in the associated data container. For example, a dashboard, table, tile, sidebar, or full page. |
| Background process error | Background process fails.Can be caused by a previous action on the same page or a previous page.For example, automatic data import cannot be completed.Usually requires user intervention to resolve the error. | Message above the page content, below the top navigation bar.Note: Display error messages generated by asynchronous actions in the notification center. |
| Validation error | There are issues with the user's account (not the user input).For example, the user has reached their maximum limit for adding items.Cannot be resolved by the user. | Message below the sidebar content. |
User action errors
| Error | Description | Component |
|---|---|---|
| Component error state | User input does not meet data or format requirements for a component.There is an error state for the component. | Message at the top of the page with links to the error state message for each affected component. |
| Validation error | User input meets a component's data and format requirements.There's a different issue with the input. For example individual figures have an incorrect total or there's no match for the data in the database. | If the component is in a sidebar: Message above the sidebar content.If the component is on the main page: Message close to the affected component. |
| Data input error | User input is not in an accepted format.There is no error state for the component and no space to display a message directly above it. For example, a table with an error on a table row. | Message close to the affected component. |
| Data access error | Configuration is needed so the user can access the data.The user does not have permission to view the data. | Error page in the associated data container. For example, a dashboard, table, tile, sidebar, or full page. |
| Unsupported action | The user tries to perform an unsupported action. For example, upload an unsupported file type. | Error page in the associated data container. For example, a dashboard, table, tile, sidebar, or full page. |
| Date | Change |
|---|---|
| September 2024 | New page |