Skip to content

Commit

Permalink
address feedback
Browse files Browse the repository at this point in the history
  • Loading branch information
@langermank
langermank committed Jul 10, 2024
1 parent e00479c commit 9070da9
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 62 deletions.
36 changes: 1 addition & 35 deletions content/deprecated-components/toast.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,39 +12,5 @@ import { AccessibilityLink } from '~/src/components/accessibility-link'

<Note variant="warning">
<Text sx={{display: 'block', fontWeight: 'bold', mb: 2}}>Usage for this component is not encouraged</Text>
<Text>Instead, please see <Link as={GatsbyLink} to="/components/banner">banner</Link>.</Text>
<Text>Instead, please see <Link as={GatsbyLink} to="/ui-patterns/notification-messaging">notification messaging guidelines</Link>.</Text>
</Note>

## Usage

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](/components/flash).

Toasts should be brief and not bog down the experience with superfluous copy. If multiple toasts appear on the page, they will stack naturally.

<DoDontContainer>
<Do>
<img src="https://user-images.githubusercontent.com/586552/63106528-06de5100-bf51-11e9-8a5e-98583ed74874.png" />
<Caption>Use brief and direct communication.</Caption>
</Do>
<Dont>
<img src="https://user-images.githubusercontent.com/586552/63106527-06de5100-bf51-11e9-858c-72de6a5c728a.png" />
<Caption>Don't use wordy and redundant copy, and avoid exceeding 140 characters.</Caption>
</Dont>
</DoDontContainer>

## 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](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA23).

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](https://github.com/jackbsteinberg/std-toast/issues/29).

### Known accessibility issues (GitHub staff only)

<AccessibilityLink label="Toast"/>
66 changes: 39 additions & 27 deletions content/ui-patterns/notification-messaging.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,21 @@ import { InfoIcon, CheckCircleIcon, StopIcon, AlertIcon } from '@primer/octicons

Primer messaging components:

- Announcement (not yet available)
- [Banner](../components/banner)
- Inline message (coming soon)
- [InlineMessage](../components/inline-message)

## Message types

Messaging holds differing levels of prominence which can be used to determine the appropriate component to use. Most messages fall into one of the following categories, from most prominent to least:

**System updates**: These types of messages originate from GitHub and are not user initiated. A global site wide announcement (outage, missing payment details, critical and blocking) or messaging related to user account/permissions should use the **Announcement** component. System announcements related to a specific product area such as a single sign-on message should use the **Banner** component. System update type messages cannot be dismissed until the issue is resolved, or may be perminent if they are purely informative.
**System updates**: These types of messages originate from GitHub and are not user initiated. System announcements related to a specific product area such as a single sign-on message should use the **Banner** component. System update type messages cannot be dismissed until the issue is resolved, or may be perminent if they are purely informative.

**Feedback**: Communicates the result of a user action (submitting a form, toggling a setting, etc.) Feedback can be positive, negative, or a warning. Feedback is shown in either a **Banner** or **Inline message**. For forms, an inline message is used for individual field validation which may be combined with a banner if multiple fields have errors. Banners are placed at the top of the page or section they are related to, but still within the body content. Inline messages are placed near the action they are related to.

**Awareness**: Communicates information that is relevant to the user but not necessarily related to an action they've taken. This type of message is typically used to provide context or additional information about a feature or product. A **Banner** using the `info` state might be used to suggest an action, while an **InlineMessage** might suggest a helpful tip.

See the [message type flowchart](#choosing-a-message-type) to help determine the appropriate message type for specific use cases.

## Message states

<img
Expand All @@ -39,7 +40,7 @@ Icons sized at 12px utilize the filled variant, while 16px and 24px utilize the
<img
width="960"
alt="An example of an input field with a 12px error message next to two examples of 14px icon usage, which uses an outline icon."
src="https://github.com/primer/design/assets/18661030/6ab6f9e9-d7e9-4f75-907f-0e08aec0db3c"
src="https://github.com/user-attachments/assets/2ee98e32-0a1c-4b40-8111-80cea6cf1177"
/>

### Overview
Expand All @@ -49,9 +50,10 @@ Messaging components combine state with message type to provide the appropriate
| State | Use case |
|--------|--------|
| <Box sx={{color: 'accent.fg', display: 'flex', alignItems: 'center', gap: '0.5rem'}}><InfoIcon /><span>Info</span></Box> | Highlights important information that has an influence on the current view or offers an action. |
| <Box sx={{color: 'success.fg', display: 'flex', alignItems: 'center', gap: '0.5rem'}}><CheckCircleIcon /><span>Success</span></Box> | Informs about successfully completing an action. |
| <Box sx={{color: 'attention.fg', display: 'flex', alignItems: 'center', gap: '0.5rem'}}><StopIcon /><span>Warning</span></Box> | Informs about a potential issue or consequence as the result of an action. |
| <Box sx={{color: 'danger.fg', display: 'flex', alignItems: 'center', gap: '0.5rem'}}><AlertIcon /><span>Critical</span></Box> | Informs about an error that occured or warns about loss of access or data as a result of an action. |
| <Box sx={{color: 'success.fg', display: 'flex', alignItems: 'center', gap: '0.5rem'}}><CheckCircleIcon /><span>Success</span></Box> | Informs about successfully completing an action. |
| <Box sx={{color: 'fg.muted', display: 'flex', alignItems: 'center', gap: '0.5rem'}}><StopIcon /><span>Unavailable</span></Box> | Informs about degraded experiences or outages. |
| <Box sx={{color: 'done.fg', display: 'flex', alignItems: 'center', gap: '0.5rem'}}><InfoIcon /><span>Upsell</span></Box> | Highlights features that are available for specific account types such as Enterprice. |

### Info
Expand Down Expand Up @@ -79,18 +81,10 @@ Examples:

<img
width="960"
alt="A global warning announcement above GitHub's global navigation bar inside a browser window."
src="https://github.com/primer/design/assets/18661030/468b73b1-de8b-45e0-b8bb-325516df942e"
alt="A yellow warning banner inside a repo Codespace settings page explaining that there may be a billable charge if settings are changed."
src="https://github.com/user-attachments/assets/91e138d2-15ce-438b-b133-ac807afb3bf1"
/>

### Success

Use the `success` state to notify users that the results of an action were successful if it is not apparent from other parts of the UI. **Use success messaging sparingly** and rely more on interaction context.

Examples:
- Saving an account setting if there's no page reload or redirect
- A background process has successfully completed

### Critical

Use the `critical` state to notify users that an action was unsuccessful, to display form errors, or to inform that an action is destructive.
Expand All @@ -105,9 +99,17 @@ Examples:
src="https://github.com/primer/design/assets/18661030/5da2e479-6bc7-46dc-9179-46002412b9f5"
/>

### Neutral
### Success

Use the `success` state to notify users that the results of an action were successful if it is not apparent from other parts of the UI. **Use success messaging sparingly** and rely more on interaction context.

Examples:
- Saving an account setting if there's no page reload or redirect
- A background process has successfully completed

### Unavailable

Reserve the `neutral` state for **inline** system related degraded experiences, or for surfacing account related permission messages.
Reserve the `unavailable` state for **inline** system related degraded experiences, or for surfacing account related permission messages.

Examples:
- A row of a data table could not be loaded
Expand All @@ -133,16 +135,6 @@ Examples:

Message proximity contributes to the prominence of a message. Whenever possible, place messages near the action they are related to.

### Above global navigation

Announcements displayed above the global navigation are reserved for site wide issues that require immediate attention. These messages are not dismissable and should only be used for critical issues that impact the entire site.

<img
width="960"
alt="Highlights a global announcement banner above the GitHub global navigation bar inside a browser window."
src="https://github.com/primer/design/assets/18661030/3d843939-5100-424e-a9a4-d663c517432f"
/>

### Top of body

If messaging pertains to an entire page or section, place it at the top of the body content. This is the most common placement for messaging components. Banners should fill the container width but maintain appropriate spacing between elements and not appear full width or flush under the global nav.
Expand Down Expand Up @@ -172,3 +164,23 @@ Banners should be placed below the Dialog header and appear full width within th
alt="Highlights a banner inside a dialog showing an error state has occured."
src="https://github.com/primer/design/assets/18661030/f4e3a125-94b6-4b12-b9ec-6b881c25f82c"
/>


## Choosing a message type

<img
width="960"
alt=""
src="https://github.com/user-attachments/assets/b8635f19-629c-42d6-9102-0014257288e5"
/>

<details style={{padding: "0.5em 0.5em 0"}}>
<summary>View image description</summary>
<h3>Success messaging flowchart</h3>
Is the success of the action evident on the page? If yes, Additional visual messaging not needed, but state must be conveyed to screen reader users. If no, Is the action a results of pressing a save or submit button? If no, display success in a banner or inline messaging on the page in a logical place. Link to newly created item if needed. If yes, Does pressing the save or submit button take you to a different page? If yes, Is success is not evident from the change in URL, display a banner indicating the success. If no, Display inline message in close proximity to the save button.
<h3>Error messaging flowchart</h3>
<h4>We know what went wrong branch</h4>
Do we know what went wrong? If yes, is the error in a form or a text input? If yes, use Primer form validation guidance. If no, Is the error from a failed drag and drop action with a mouse? If yes, Use a simple modal error dialog that can be dismissed with close button or click-outside. Include guidance to correct the error. If no, was the action triggered from choices in a dialog? If no, Banner or inline message closest to the part of the UI that makes logical sense. If yes, Is the error after an action that takes a long time to complete? If no, don't close the dialog until the action completes. If it failed, use a banner at the top of the dialog. If yes, Is it important that the user can move on in the same window while the action completes? If no, don't close the dialog until the action completes. If it failed, use a banner at the top of the dialog. If yes, progress updates in a banner that is replaced with an error or success message. If the user can leave the page during the action, we should utilize GitHub's notification system.
<h4>We don't know what went wrong branch</h4>
Do we know what went wrong? If no, is the error obvious without additional messaging? If yes, vague visual error message not needed, but make sure error is conveyed to screen reader users. If no, Is the error in a form or a text input? If yes, use Primer form validation guidance. If no, Is the error a result of something that user initiated? If no, use a banner at the top of the UI if it is crucial to inform the user. If yes, is it crucial that the user knows the error in order to complete their main task? If no, use a banner or inline message closest to the part of the UI that makes logical sense. If yes, use a simple modal error dialog that can be dismissed with close button or click-outside. Include guidance to correct the error.
</details>

0 comments on commit 9070da9

Please sign in to comment.