Alert, Notification, Information
Message
ECT approvedUpdated May 21, 2026
Description
- A message displays information related to the user workflow such as announcing the success or failure of an action, or advice to support the user and prevent errors.
- A message should not appear on top of other elements and should not block the user.
- It can include an action button or link.
- It remains on screen until the user closes it, performs the suggested action, or selects the link.
Anatomy
Anatomy
Size
M size: Recommended for small screens.
L size: Recommended for large screens.
- Adjust the width of the component according to the context, available space, and screen size.
- Do not reduce the padding within the component.
- The message heading and text should have a maximum width of 560px to aid readability.
Types
Standard
Subtle
Position
A message is integrated into the page content. Follow the recommendations below, depending on the use case.
- Place the message directly above the element to which it refers, when possible. For example, place an API error message just above the button that triggered it. This makes it clear to the user that they need to click the button again to retry.
Note: some scenarios may require the message to be placed below the element. See example in Dos and don'ts.
- Place the message where the user expects it to be.
For example, all the messages related to a table should be placed directly above the table, no matter where the trigger is. For example, the trigger could be a button on the table, or an action on the sidebar.
- Place the message where the user is most likely to find it.
For example, a message that's not related to one particular area can be placed directly below the page title and subtitle.
Always ensure the message draws the focus so that it's noticed and read by screen readers.
States
A message does not have a hover or focus state but the optional links, buttons, and close icons do.
Variations
Status
Positive
Negative
Caution
Informative
Ai
Callout
Dos and don'ts
Do
Do
Do
Do
Do
Do
Don't
Technical example
Heading
- Create a short, scannable heading that summarizes the message.
- Use sentence case.
- Do not use punctuation unless it's a question.
- Where possible, write the heading as a positive statement.
Body
- Try to keep the body text to fewer than 2 lines, as it will likely expand when translated.
- Use the active voice in the present tense whenever possible.
- Offer a next step or a way to find more information.
- Optionally, include a button or link to make the message actionable.
- Do not use all capital letters.
Status messages
Success message
- Avoid messages such as Success!, Done, or "No more to come" that do not include any context.
- Avoid adverbs such as correctly or successfully.
- Instead, clearly state what was completed. For example: "Invoice sent."
Error message
- Say what happened and why.
- Avoid using please and sorry.
- Never blame the user.
- Help them fix the problem.
Warning message
- Clearly describe the potential issue or situation.
- If possible, provide a button or link to help users prevent or resolve the issue or situation.
Requirements
Users should be able to:
- Perceive and understand the message and what it relates to.
- Identify the type of message and severity (error, warning, info, success).
Interactions
Messages should be persistent and dismissable by the user.
Keyboard interactions
- Tab. If the message does not contain a link:
- Moves focus from the previous interactive element on the page to the message ‘close’ button.
- When the message is removed, focus moves to the next interactive element on the page.
- Tab. If the message contains a link:
- Moves focus from the previous interactive message on the page to the link in the message.
Design considerations
- Provide a clear, concise message so users are aware of the purpose of the message.
- Position messages close to the relevant content to maintain context.
- Make sure that informative icons within the message meet a 3:1 minimum contrast ratio with the message banner background.
- Make sure that the message is not sticky and does not obscure other content on the page.
- Make sure that the message is persistent and only removed if no longer relevant to the user, is dismissed by the user, or has been on screen longer than 20 hours.
Development considerations
- Messages should be announced to screen reader users if they appear while these users are performing other actions within the product.
- Use role=”status” to inform screen reader users of any changes to content via the message.
- Note: role=”status” has an implicit value of aria-live=”polite” which means messages will be announced while the screen reader is idle.
- If the message is dismissable, make sure that the close button has a clear accessible name, provided by an aria-label.
- Make sure any icons used as part of conveying the information in the message have appropriate accessible equivalents to convey the tone of the message.
| Date | Changes |
|---|---|
| November 2025 | Renamed 'Contextual message' to 'Message', following the deprecation of Global message |
| October 2025 | Removed subtle type for error messages. |
| August 2025 | Updated guidance on the accessibility tab.Removed Examples tab and moved images to new section in Design tab. |
| July 2025 | Reinstated marketing callout variation. |
| July 2025 | Replaced 'close' icon with the 'cross' icon.Fixed vertical alignment.Removed marketing variation. |
| October 2024 | Updated link text weight in Importance section. Added guidance re focus.Updated text in Dos and don’ts section in Figma file.Updated all ZH assets as they were linking to an old Figma file.Updated maximum text width in Size section.Updated text in Position section. |
| September 2024 | New version created. Previous versions archived in the frozen Web and Product design system. |