Primer includes three different messaging components:
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
Highlights: bring attention to how and why to engage with a feature
Updates: inform the user of necessary updates or changes to the product as it relates to them.
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:
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
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.
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.
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)
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 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.