Toast alternative documentation #712
Conversation
|
Thanks for starting to document this. I have a few questions when looking at the alternatives:
|
| export default ComponentLayout | ||
| import {AccessibilityLink} from '~/src/components/accessibility-link' | ||
|
|
||
| /*This section feels more like an ADR?*/ |
There was a problem hiding this comment.
It would be useful to add what our shared definition of a Toast is. (This was a suggestion Alistair made on my engineering exploration documentation PR which I appreciated!)
There, we referred to these characteristics:
* Overlays other content (absolutely positioned)
* Visually positioned towards the bottom of the page
* Placed towards the end of the DOM
* Can either be auto-dismissed, or persists until manually dismissed
There was a problem hiding this comment.
- Visually positioned towards the bottom of the page
I feel this is not really part of it. In some implementations toasts are at the top right.
Maybe rather
- Visually positioned towards one of the edges of the screen
| - Zoomed in view | ||
| - Zoomed in view requires that focus is brought to a toast in order to be seen by someone using zoom on a screen. This can be distruptive to a user's orentiation of the screen, especially if not critial to their workflow. | ||
| - Toast fatigue (used too often for things that aren't important to a user's workflow) | ||
|
|
There was a problem hiding this comment.
A few additional things (pulling from https://github.com/github/accessibility/pull/5494) that I think could be mentioned here around a11y/usability concerns:
- A Toast appears at the end of the DOM making it challenging for keyboard users to navigate to it.
- For example, Memex spreadsheets have hundreds of Tab stops. If a Toast with an action appears based on a user action, it's impossible for a keyboard user to navigate to it especially if the Toast is transient. Even if the Toast is persisted, it can take hundreds of Tab stops for a keyboard user to navigate to the Toast.
- A Toast is positioned far from the source of the issue. There is usually no visual or programmatic association between the Toast, and the control or action it's referring to. If users are unable to immediately perceive the Toast when it appears, the message will have lost relevance/context.
- For example, consider a scenario where a user searches for an assignee within a SelectPanel. In one real-world example, we communicate a message like, "Assignee cannot be found". Users who are zoomed into the screen may not see the Toast message until they have moved forward. By the time they have reached the Toast, the message will have lost relevant and leave the user confused. This is not a usable experience, compared to if the SelectPanel itself contained an inline/Banner error message.
| - Before Android toasts and iOS push notifications, we were notified "You've got mail" when receiving a new email message from AOL on a desktop computer, which lead to subsequent overuse of dialogs and notifications. | ||
|
|
||
| ### Our use cases | ||
| GitHub has its own system for notifying our users of new or updated activity to be explored at their leisure in other parts of the product, GitHub notifications. With those use cases covered, we're left with a need to notify users of the status of actions they've taken on a page in the product to help them successfully complete their tasks. |
There was a problem hiding this comment.
Good point! This makes me wonder if we can move some subset of our notifications into Notification.
There was a problem hiding this comment.
I am not sure this is a good idea. We currently have more like an inbox for issues and PRs. If we add failed and succeeded actions in here, it will be a mess of mixed stuff. Also, I think the use case for preserving those kind of notifications is very limited.
|
|
||
| Another example: a user activating the save button on a page. If the save button action does not bring them to the next logical page, either back to the place before they enacted an edit button, closing a dialog that opened for the changes, or taking them to the new thing that was created, our save button should enter a loading state, complete, and return to a rest state. Absense of an error message should indicate that the save was successful. | ||
|
|
||
| If the change made on the page is not immediately visible to the user, such that a new item was created but we don't know for sure that a user wants to navigate to the newly created item, users should be notified of the successful action and given the option to navigate to the new item in a banner on the page or dialog. |
There was a problem hiding this comment.
Is dialog here referring to a modal dialog or something else?
I'm thinking a modal-dialog would be reserved for critical notifications.
There was a problem hiding this comment.
Agree, dialog feels a bit blocking for a success state.
Banner or inline message seems better.
| ### Our use cases | ||
| GitHub has its own system for notifying our users of new or updated activity to be explored at their leisure in other parts of the product, GitHub notifications. With those use cases covered, we're left with a need to notify users of the status of actions they've taken on a page in the product to help them successfully complete their tasks. | ||
|
|
||
| ## Alternatives to toasts |
There was a problem hiding this comment.
I would love to see an inline validation example here to discourage Toasts being used for form validation.
There was a problem hiding this comment.
Fine by me, but to we use toast for form validation atm? 😱
| Another example: a user activating the save button on a page. If the save button action does not bring them to the next logical page, either back to the place before they enacted an edit button, closing a dialog that opened for the changes, or taking them to the new thing that was created, our save button should enter a loading state, complete, and return to a rest state. Absense of an error message should indicate that the save was successful. | ||
|
|
||
| If the change made on the page is not immediately visible to the user, such that a new item was created but we don't know for sure that a user wants to navigate to the newly created item, users should be notified of the successful action and given the option to navigate to the new item in a banner on the page or dialog. | ||
|
|
There was a problem hiding this comment.
I think that we could add a note that in some scenarios, an explicit success message can help provide assurance, particularly if they just finished submitting a complex or multistep form... but don't use a Toast for that of course 😛
There was a problem hiding this comment.
Maybe this is more like a success page? E.g. at the end of a flow there is a page that states that you successfully completed the flow.
Do we have cases like this?
| - Some situations have successful interactions that then present an undo option to the action you've just performed, like a sent email message. It's a lot easier to perform an undo action on a desktop with the availability of keyboard shortcuts to undo actions than it is on mobile, whose keyboards are often hidden unless in an active text editor, and don't contain modifier keys. | ||
| - Before Android coined Toasts, iOS created push notifications whose use case was to notify of non-critical new things in other areas of the product to explore at a user's leisure. | ||
| - Before Android toasts and iOS push notifications, we were notified "You've got mail" when receiving a new email message from AOL on a desktop computer, which lead to subsequent overuse of dialogs and notifications. | ||
|
|
There was a problem hiding this comment.
I think it will be helpful to conclude with a takeaway of this history lesson -- perhaps that Toasts are not intended to be used for desktop? (You mention this in the beginning and I think it'll be helpful to re-iterate)
|
|
||
| /*Scenarios*/ | ||
| ### 1. Successful actions | ||
| Excessive use of successful notification messages can indicate product instability. If we have to really let users know every time something was successful, we're not building a reliable product. |
There was a problem hiding this comment.
Maybe we can add something like:
Success should be the expected result. Failure should be the exception that is called out.
|
|
||
| If the change made on the page is visible to the user, we can rely on the user's ability to see the change and know that it was successful. | ||
|
|
||
| For example, if a user activates a toggle control, and the toggle control doesn't flip back to the original postion, a user should be confident that the change has occured with the absense of an error message. Likewise for screen readers, after activating the toggle control the control should read out the current control's state. |
There was a problem hiding this comment.
I agree with this. But maybe we do need to look into our saving docs and add some standard checkmark indicator.
Personally, I find when you have a page with a save button and part of it is auto-saving, this is hard to trust, if you have no indicator.
A simple inline message "✅ changes saved" can help here.
|
|
||
| For example, if a user activates a toggle control, and the toggle control doesn't flip back to the original postion, a user should be confident that the change has occured with the absense of an error message. Likewise for screen readers, after activating the toggle control the control should read out the current control's state. | ||
|
|
||
| Another example: a user activating the save button on a page. If the save button action does not bring them to the next logical page, either back to the place before they enacted an edit button, closing a dialog that opened for the changes, or taking them to the new thing that was created, our save button should enter a loading state, complete, and return to a rest state. Absense of an error message should indicate that the save was successful. |
There was a problem hiding this comment.
While I generally agree, does this not have the same issue as the toasts, taht you may miss it by looking away? Especially if it is very quick?
This is the very first draft of toast alternative documentation. There will be grammatical errors and things that need to shift/be rephrased. Its location in the primer website isn't updated, so the build won't have it in the side navigation.
Comments are welcome but would appreciate it focus is made on if there are any patterns missing that should be included or any deep disagreements on the content. If there is a confusing example or thought, please note it because it's likely I need to rephrase!
I'm still planning on adding in visual aids and I'd like to include a decision tree as well that will be useful for everyone, including any FRs on primer who will need to gatekeep PR reviews that include any new toasts.
cc: @dipree, @khiga8, @lukasoppermann, @langermank