Messaging
Primer includes three different messaging components:
Messaging types
It's important to consider the context when selecting a component to convey your message. Does the message need to interrupt the user flow? Is this a global message that needs to be shown on every page? Does it require the user to take an action, or is it more of a notice? Most messaging on GitHub falls into one of the following categories:
Feedback: communicates something to the user based on an action they've taken or a change in context
- Toasts or flash alerts are best suited for this type of messaging.
Highlights: bring attention to how and why to engage with a feature
- Popovers are best suited for this type of messaging.
Updates: inform the user of necessary updates or changes to the product as it relates to them.
- Flash alerts are best suited for this type of messaging.
Toasts
Toasts are used to provide relevant feedback to the user, typically after they've taken an action. Primer includes styles for success, warning, error, loading, and default toasts. Some examples include:
- Confirmation that an action was successfully taken
- Communicating that an action is pending
- Notifying the user if an action failed to complete
- Providing general information
Toasts are best used in context of the page they're referring to (rather than a global notification that can appear on any page) and should require minimal user interaction. Toasts are best used to display time-sensitive information. For global notices and messaging, see the flash component.
Toasts should be brief and not bog down the experience with superfluous copy. If multiple toasts appear on the page, they will stack naturally.
Use brief and direct communication
Don't use wordy and redundant copy
Accessibility
Toasts are non-modal components and should contain role=log, which implies the element has aria-live="polite". This notifies the user of the toast via Assistance Technologies without having to change focus to the toast. You can read more about role=log at W3: Using role=log to identify sequential information updates.
Toasts are generally informative and should not receive focus when they appear. For that reason, we suggest you avoid using interactive elements in the component (aside from a dismiss action). Keep in mind that, even without an explicit dismiss action, the user can always hit esc to dismiss the toast. For more information on how interactive children affect web accessibility, check out this issue.
Flash alerts
Though flash alerts don't need to be as concise as a typical Toast message, they should still be direct and not exceed two to three sentences. If additional context is needed, provide a link for the user to learn more.
Don't use headings or multiple type sizes in flash alerts, rely on our default paragraph size instead.
Full-width
Flash alerts that affect every page (e.g. a global message) should use the full-width style, which spans the entire page and is intended to sit beneath the top-level navigation. When using a full-width flash alert, be sure to include the container class to append a max-width on the content and avoid long line-lengths, which can be difficult to read.
Use a container class to give the text a max-width
Don’t let a single text block span the entire width of the window (non-text elements can still span the entire width, such as left-aligned text and right-aligned buttons)
Interactive elements
Flash alerts can contain links or buttons depending on the type CTA and how much attention it should draw.
They typically do not timeout on their own, but can include a dismiss action for messages that can be closed or hidden.
Popovers
Popovers are used to call attention to a new feature, change to an existing feature, or to provide additional context. Popovers can be helpful for flows that require light onboarding or instruction.
Use sparingly to avoid cognitive overload. Though they can be used for a variety of things, they should be used sparingly to avoid cognitive overload. It's important to consider the context in which the popover appears. Are there other popovers on the page? Does it appear on page load, or require the user to open the popover?
Unlike other messaging components, popovers should never include critical information (such as errors) and should always include a dismiss action.
