diff --git a/content/ui-patterns/danger.mdx b/content/ui-patterns/danger.mdx new file mode 100644 index 000000000..4cec872a1 --- /dev/null +++ b/content/ui-patterns/danger.mdx @@ -0,0 +1,72 @@ +--- +title: Danger patterns +--- + +import Img1 from '../../images/danger/danger1.png' +import Img2 from '../../images/danger/danger2.png' +import Img3 from '../../images/danger/danger3.png' +import Img4 from '../../images/danger/danger4.png' +import Img5 from '../../images/danger/danger5.png' +import Img6 from '../../images/danger/danger6.png' +import Img7 from '../../images/danger/danger7.png' + +Danger patterns in GitHub cover both destructive and non-destructive changes that a user can make to existing data. These range from closing an issue and converting a pull request to a draft, to more extreme actions such as deleting a repository or account. + +## Destructive changes + +When users are making a destructive change to their GitHub account, you should make sure they have a clear understanding of what is about to happen. Many times these changes are reversible, but may have irreversible side effects (for example, when making a repository public). Other times, they're not reversible at all (deleting an organization). In both cases, ensure that you've communicated the consequences to the user clearly so they are aware of all potential negative effects. + +### Non-critical data + +There are several types of data within GitHub that need to be deleted from time to time. Many of these are non-critical and can be handled without using a `danger` visual treatment. These non-critical destructive flows include deleting a comment, issue, pull request, or discussion. + +### Critical data + +For critical destructive flows (for example: modifying user access, deleting repositories, making private data public), there are 3 basic treatments you can apply that will ensure the full effects of a change are clear to users and that we minimize loss of trust. + +#### Visual treatment + +1. Highlight all destructive flows visually. + - All page sections that will trigger a destructive sequence should be highlighted with a [`red border`](https://primer.style/css/utilities/borders#border-colors) and an [`alert` octicon](https://primer.style/octicons/alert-16) to build an accessible, intuitive pattern of recognition. When users notice those details, they should know to tread carefully. Ideally, these will be centralized into a "Danger zone" section. + - Any actions that will delete significant user data must use the [`danger button`](https://primer.style/css/components/buttons#danger-button) component. + +Visual treatment of Danger Zone + +2. Any actions that have prerequisites should remain disabled until those prerequisites have been completed. + +Example image of a destructive action whose prerequisites have not been met + +3. Use standard danger buttons for standard views to avoid drawing unnecessary attention to the danger flows. You want to indicate that they are dangerous without pulling the user's attention away from what their current task. + +Example image of a danger zone with many "danger" buttons + + +#### Secondary confirmation + +Take users into a secondary confirmation flow (usually a [box overlay](https://primer.style/css/components/box-overlay)) to ensure they understand the full impact of the decision. + +1. The user should be informed of exactly which data **will** be destroyed and required to confirm that they understand it. This should be explained clearly and concisely in a bulleted list form, using the [`x` octicon](https://primer.style/octicons/x-16) to both draw attention and emphasize that it will be deleted. Don't list out data that will *not* be deleted. + +2. Each step in the confirmation flow enables the next step. This forces users to work through each step in sequence and adds a layer of friction that is not prohibitive, but should help minimize errors. + +Example image of detailed list of data deletions + +3. The user should be informed of the steps to revert the changes (if reversible) and requested to confirm again. + +Example image of UI describing if or how data can be recovered + +4. In cases where the data will delete a user account, an organization, or a repository, the user should be asked to enter their password before confirming. + +Example image of password-protected confirmation step + +5. On secondary confirmation modals, the button should always be red to indicate its severity. It should be disabled by default. It should be enabled when all prior confirmation steps are completed. + +Example of a second-stage danger button + +**Note:** All data deletion events should be logged for the support team to help in handling cases where something has gone wrong. + +## Non-destructive changes + +There are several cases where GitHub treats conversions or feature enablements as `danger` patterns. Examples include converting a pull request to a draft (no data is deleted) and enabling GitHub Pages (no data is deleted, some pages are published). These should not follow the `danger` patterns established before *unless* data is being deleted since the previously mentioned treatments are specifically reserved for deletions. + +In these cases, make sure users are sufficiently informed of what will happen without visually implying that data will be lost. If you're concerned that the user may not have enough context to make a decision, we should use a yellow-themed [`flash alert`](https://primer.style/css/components/box#boxes-with-flash-alerts) with an [`alert` octicon](https://primer.style/octicons/alert-16) to provide the necessary information. If an action is required, use a [`default button`](https://primer.style/css/components/buttons#default-button) or [`outline button`](https://primer.style/css/components/buttons#outline-button) instead of a `danger button`. diff --git a/images/danger/danger1.png b/images/danger/danger1.png new file mode 100644 index 000000000..e3d66b8cd Binary files /dev/null and b/images/danger/danger1.png differ diff --git a/images/danger/danger2.png b/images/danger/danger2.png new file mode 100644 index 000000000..9cbc247e2 Binary files /dev/null and b/images/danger/danger2.png differ diff --git a/images/danger/danger3.png b/images/danger/danger3.png new file mode 100644 index 000000000..af178b9a2 Binary files /dev/null and b/images/danger/danger3.png differ diff --git a/images/danger/danger4.png b/images/danger/danger4.png new file mode 100644 index 000000000..7f4273ef0 Binary files /dev/null and b/images/danger/danger4.png differ diff --git a/images/danger/danger5.png b/images/danger/danger5.png new file mode 100644 index 000000000..51868c840 Binary files /dev/null and b/images/danger/danger5.png differ diff --git a/images/danger/danger6.png b/images/danger/danger6.png new file mode 100644 index 000000000..81f5a2902 Binary files /dev/null and b/images/danger/danger6.png differ diff --git a/images/danger/danger7.png b/images/danger/danger7.png new file mode 100644 index 000000000..619129e2b Binary files /dev/null and b/images/danger/danger7.png differ diff --git a/images/danger/dangerPatterns1.png b/images/danger/dangerPatterns1.png new file mode 100644 index 000000000..b88c78e2d Binary files /dev/null and b/images/danger/dangerPatterns1.png differ diff --git a/images/danger/dangerPatterns2.png b/images/danger/dangerPatterns2.png new file mode 100644 index 000000000..2977f5e6d Binary files /dev/null and b/images/danger/dangerPatterns2.png differ diff --git a/images/danger/dangerPatterns3.png b/images/danger/dangerPatterns3.png new file mode 100644 index 000000000..57b679f7e Binary files /dev/null and b/images/danger/dangerPatterns3.png differ diff --git a/images/danger/dangerPatterns4.png b/images/danger/dangerPatterns4.png new file mode 100644 index 000000000..17209bf22 Binary files /dev/null and b/images/danger/dangerPatterns4.png differ diff --git a/images/danger/dangerPatterns5.png b/images/danger/dangerPatterns5.png new file mode 100644 index 000000000..e5ceee90c Binary files /dev/null and b/images/danger/dangerPatterns5.png differ diff --git a/images/danger/dangerPatterns6.png b/images/danger/dangerPatterns6.png new file mode 100644 index 000000000..cc98a2586 Binary files /dev/null and b/images/danger/dangerPatterns6.png differ diff --git a/images/danger/dangerPatterns7.png b/images/danger/dangerPatterns7.png new file mode 100644 index 000000000..d8fe892e7 Binary files /dev/null and b/images/danger/dangerPatterns7.png differ diff --git a/src/@primer/gatsby-theme-doctocat/nav.yml b/src/@primer/gatsby-theme-doctocat/nav.yml index e02e080a7..9c8afded8 100644 --- a/src/@primer/gatsby-theme-doctocat/nav.yml +++ b/src/@primer/gatsby-theme-doctocat/nav.yml @@ -13,12 +13,14 @@ children: - title: Button usage url: /ui-patterns/button-usage + - title: Danger + url: /ui-patterns/danger - title: Empty states url: /ui-patterns/empty-states - - title: Progressive disclosure - url: /ui-patterns/progressive-disclosure - title: Messaging url: /ui-patterns/messaging + - title: Progressive disclosure + url: /ui-patterns/progressive-disclosure - title: Design tools url: /tools children: