Notification / messaging guidelines

[lukasoppermann]

This PR is a WIP to define guidelines for banner / toast and alert usage.

[khiga8]

Not sure where this belongs, but I think it's important to emphasize that feedback is placed near the source where possible. For example:

• A form error summary should be placed right above the form it relates.
• If we want to communicate that a user action failed, the feedback should be placed near where the action was taken rather than all the way at the top of the page (especially if this feedback is shown async).

This will help improve discoverability of the feedback for everyone!

In our Rails pages, a lot of feedback is shown on page reload above the <main> content, but I think this is a pattern we can move away from in our React pages/async interactions.

[khiga8]

Should we warn that Callout and Banners usage should be reserved/limited on a page?

Plaintext can be used for most information. There's also, just a typical plaintext form caption for providing supplementary information.

[lukasoppermann]

Maybe. I could see some guidelines like this:

• avoid using callouts and banners next to each other if possible
• never use multiple callouts after each other

I don't really know how we could create a rule to create a hard limit. I think guidelines is the best we can do, but please let me know if you have ideas for more precise rules.

[khiga8]

Hmm yeah, I'm not quite what the precise rule should be, but I like your suggested guidelines to start with!

On the tooling side, we could consider creating a custom axe rule that flags when there's like.. more than X number of callouts and banners on a given page, or when there are directly adjacent banners/callouts in the DOM.

[khiga8]

I've seen "danger"/red variant used to communicate when an action is super destructive or something needs immediate attention. Is that appropriate, and would that fall under this state?

[lukasoppermann]

Good question.

One the one side, technically it would be invalid because it is not an error state it is a warning state.
On the other side it is a pattern our users have grown accustomed too, so it may be dangerous to change this.

@langermank what do you think?

I feel like it would make sense to extend this definition to include destructive actions, this is also why we use the danger button, which is red as well.

[dipree]

We might want to rethink the purpose of this page. "Messaging" is a very broad term that includes more than the listed components. You already removed "Popover", which makes sense to me. Maybe it would help to further scope this to "Notifications". For example:

Notifications play a crucial role in communicating with users and offering feedback. They vary from detailed, inline reactions to specific user actions, to broader messages that span across the system.

[dipree]

The degraded experience where no content is shown is sort of an empty state. Data exists but could not be loaded. I wouldn't consider that a system notification respectively, it's documented as part of the existing degraded experience docs already and in the scope of notifications, it doesn't fit. It would fit if it's "messaging" though.

[langermank]

I don't agree that this is not related to messaging. I think it makes sense to at least mention it in these docs and link to degraded experience docs, as I have below.

[keithamus]

We might not need explicit UI elements to show it though. Visual treatment could be added to existing UI to show that data has failed to fetch (e.g. we use spinners to show data is loading, we could provide a new UI pattern that shows data has failed to load that is similar to a spinner, such as an X) - such treatment would be discrete from a banner, and more specific.

[dipree]

Could we make this a table for easier overview/consumption? For example something like this:

Status	Usage	Action	Color	Icon
Informational	Used for non-critical context and information. Examples: view impacts, feature prompts, ongoing processes.	Can be dismissed or left to persist based on the significance of the information.	Blue	info
Success	Indicates task completion or successful actions. Examples: confirmation of saved settings, successful issue transfers.	Can be dismissed or remain in view without intruding.	Green	check-circle
Warning	Alerts users to potential issues or impactful changes. Examples: important settings, possible connectivity concerns.	Requires acknowledgement, often remains visible until the user responds.	Yellow	alert
Error/Critical	Signals critical errors, system failures, or necessary destructive actions. Examples: form submission errors, critical confirmations.	Stays visible until the user addresses the issue or completes the required action.	Red	stop

[dipree]

I would say that Callout is not a way to notify users, it's about emphasizing content. I would mention it as part of Banner and refer to it, but wouldn't want to confuse to use it for notifications (unless this page continues to be about all things messaging but it's getting a lot).

[ichelsea]

Some small comments here as a first pass.

It's a bit harder to review guidance for banners/toasts until we're sure that we want to allow for toasts. I agree with the confusion on callout vs banner though. In general I think more images and examples will help this!

[ichelsea]

I would move the section up to the top of message states since the image is relevant to this section and it also helps people visualize as they go through each of the states

[lukasoppermann]

Suggested change

- a nudge towards a new feature

A marketing banner should be used instead.

[lukasoppermann]

One big issue we have is that users are not sure which state to use. So, I am trying to define the differences here.

State	Use case	Examples
Critical	Inform user about an error that occurs or an action they are about to perform that results in lost access or content	- an error occurred - the action deletes content irreversibly (e.g. delete repo) - the action removes access irreversibly (e.g. transfer repo)
Warning	Warn users of side-effect of an action they are about to take or if something happens they may not know about which results in a specific state	- an action will incur costs as a side-effect - an action will have additional side-effects, e.g. changing visibility will reset repo url - part of a search query is invalid and will be ignored, but the search continues with the rest of the query - informing about an upcoming change that requires your attention as you need to change something to not lose access / have problems
Success	Informs about successfully completing action.	- content was saved and it is not easily apparent in the UI - export is ready - item was created (if not visible in UI)
Info	Use to highlight important information that has an influence on the current view or offers an action	- some items are hidden due to filters / config that is controlled on a different page / settings file - an action is possible / suggested due to outer circumstances (e.g. a review is requested) - an action is restricted due to not having the correct plan (e.g. upgrade to use copilot)

[keithamus]

Some initial thoughts

[keithamus]

Why would a banner be preferred over, say, multiple inline messages?

[keithamus]

Where could this be seen? I am imagining this is part of a form? Is this complementary info in a form field?

[lukasoppermann]

Not necessarily a form like you'd imagine. It could be information on any page that helps you perform the action by understanding what you are doing. Or by explaining why you may not see something you expect to see (e.g. you have a settings file that hides it.)

[keithamus]

Why would a banner or toast be used instead of a spinner or interstitial page, or are they included in this?

[lukasoppermann]

I assume you are referring to the last point:

• a process is in progress

If a loading spinner works, this is preferred. But sometimes there may be a need to show a message as well. Either one that includes the loading spinner or if the process is running for a long time and the user may leave the page and come back. In those cases, info would be the correct state.

Maybe you have an idea of how to better write this?

[langermank]

I don't think I've ever seen an interstitial page at GitHub 😆 we'll try and add an image for this one

[keithamus]

Kooha-2024-01-19-09-34-10.webm

A screenshot of that page:

[keithamus]

This flow chart lacks a lot of nuance. I worry people may make a distinction that feature announcements are one bucket, and any other messaging falls in the bucket of banner. In reality we'd want to steer engineers away from banners as much as possible, and more toward inline messaging.

[keithamus]

If it is not apparent from the UI already, maybe there could be guidance on how it could be made apparent from the UI?

[lukasoppermann]

I feel this is not the correct page for this kind of guidance. If we have this somewhere or add this (great idea) we could link it.

However it is not always possible to make it apparent in the UI.

[keithamus]

This sounds like poor UX. It should be evident, without the need for a banner/toast, that a change I have made has been propagated.

[lukasoppermann]

This is not always simple, e.g. when saving on a settings page with a text field, we don't redirect. So, it visually looks the same after the save.

I am actually not sure this really is poor UX or to put it a different way, I have no immediate solution that is better.

[keithamus]

We might not need explicit UI elements to show it though. Visual treatment could be added to existing UI to show that data has failed to fetch (e.g. we use spinners to show data is loading, we could provide a new UI pattern that shows data has failed to load that is similar to a spinner, such as an X) - such treatment would be discrete from a banner, and more specific.