Maturity
This is a work-in-progress documentation. You can provide feedback here.
Pre-Alpha
FYQ2 target
Beta
Figma component
-
Repository
-
Storybook
-
Overview
A Callout is a communication component that uses Secondary Emphasis and semantic sentiments to highlight important details and provide context for a flow.
What sets Callout apart from other communication components are two key factors:
- They are synchronous: They load with the rest of the page content to provide context before taking action. There are other options for giving reactive feedback, such as Error Text—for Form Controls—, Confirmation, or Notification.
- They cannot be dismissed: The message remains until the underlying situation is resolved. If the message is disposable, you shouldn’t use a Callout.
Types
Anatomy
The Callouts are composed of an icon, a short description, and an optional link. They purposely lack properties like headings or actions that can distract people from their primary tasks.
Properties
|
Name |
Values |
Default |
|---|---|---|
|
Type |
General | Specific |
General |
|
Sentiment |
Warning | Success | Critical | Featured |
Critical |
|
Heading (General only) |
Boolean |
False |
How to use
Type
General
General Callouts are relevant to an entire page or an entire landmark. We should position them right below the page, landmark, or region header—to ensure people read them first so they can better understand the context.
Specific
Specific Callouts are related to a particular page element and should be positioned immediately below to associate them more effectively.
Sentiment
Semantic colors are intended to draw attention to essential experience elements and, through specific sentiments, assign them a particular meaning that facilitates their differentiation.
Further reading
Critical
A critical or unexpected situation
When to use
- Something’s not working and requires immediate action because of its importance and severity; regardless if it’s a person’s error or a system error.
- A problem happened, or a person made a mistake that prevented them from finishing their task or a process.
- Indicate actions that are destructive and can’t be undone—they require confirmation.
Purpose
Clearly state what’s going on and provide an actionable solution.
Example
- "We’ve got a problem, and we need to act now."
Warning
Cautionary advice about a potential problem
When to use
Informs about/indicates an action that can be taken to prevent errors or unwanted things from happening.
Purpose
Clearly state what’s going on and provide an actionable solution.
Example
- "We’re letting you know about a potential problem."
- "Unverified"
Success
Achievement of a goal
When to use
When things are done or went accordingly to plan.
Purpose
Inform about success.
Example
- "This is done; everything went well."
- "Enabled"
Featured
Highlighted for special attention, neither good nor bad
When to use
Provides valuable information to people about something important or out of the ordinary, essential to understand the context and making a decision.
Purpose
Neutrally inform people.
Example
- "We’re letting you know about…"
- "New"
- "Beta"
- "AI"
Examples
Heading
Headings are only available in the General Callout.
Headings should be added when there is a lot of information to make it easier for people to scan. But we must use them sparingly to avoid diverting the focus of the task.
Writing guidelines:
- Write Headings in sentence case (only the first word and proper nouns are capitalized)
- Do not end with a period.
Description
Clear and concise descriptions help people understand the context and complete their tasks. Including too much information or links can be distracting and hinder their ability to do so.
Writing guidelines:
- If there‘s a Heading, we must avoid repeating the same information.
- It must go with a period at the end, except if it works as a Heading occupying only one line.
Best practices
To ensure effective communication, we must follow a consistent structure and order when writing our messages. They should include the following:
- Main message: Clearly states the reason for displaying the Callout.
- Additional info: Provides further details and suggests potential solutions for the main message, whether Warning or Critical.
Related content
Adding Links
Including external links can distract people from their primary goal. Use sparingly.
Sometimes, people must go elsewhere to help solve an issue, learn more about a process they may struggle with, or improve their experience. You can add them as part of the Description.
Writing guidelines:
- They should be four words or less to avoid wrapping.
- They must be descriptive and meaningfully indicate the link’s destination.
- They don’t necessarily have to be at the end of the sentence—they can also be part of it.
Related content
Sizing and spacing
We use standard sizing and spacing to improve the experience depending on the information density and make our interface more accessible, predictable, and easy to use.
Further reading
Full-width
Callouts are designed to adjust its width to fit within its parent container while accounting for any padding. Once they reach the maximum width allowed by the container, the text will automatically wrap to the next line, causing the height of the container to increase as needed.
Min-width
Callout are set to have a minimum width of 180px. Less than that, the information is hard to read and overall the interface might suffer.
Behavior
Frequency
Only one Callout of each type may be shown at a time. When multiple Callouts of the same variant are necessary, and the messages aren‘t related, they should appear one at a time, based on importance. Avoid stacking Banners on top of one another.
Lists
If the callout uses a list, it should always have a heading that gives context as to what that list is about.
