Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add docs for new banner #748

Merged
merged 19 commits into from
Jun 6, 2024
Merged

Add docs for new banner #748

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
f488232
add docs for new banner
lukasoppermann Mar 22, 2024
c9b92a9
add content for banner
lukasoppermann Mar 22, 2024
f0971c4
add banner to nav
lukasoppermann Mar 22, 2024
88a4709
fix paragraphs
lukasoppermann Mar 22, 2024
38ac3a5
update images
lukasoppermann Mar 26, 2024
47b4e5a
Apply suggestions from code review
lukasoppermann Mar 26, 2024
a3181fc
update asset
lukasoppermann Mar 26, 2024
f5cdb97
rm duplicate titles
lukasoppermann Mar 26, 2024
b85a81d
Update content/components/banner.mdx
lukasoppermann Mar 26, 2024
b23327f
simplify code structure by using markdown in box
lukasoppermann Mar 26, 2024
d46be99
replace box with div were possible
lukasoppermann Mar 27, 2024
9b2dab2
update asset
lukasoppermann Mar 27, 2024
e306ee7
add some context for dismiss
lukasoppermann Mar 27, 2024
4fed67e
added position content
lukasoppermann Mar 27, 2024
21a6142
improve title copy
lukasoppermann Mar 27, 2024
0217d35
Apply suggestions from code review
lukasoppermann Apr 1, 2024
bec7768
change title to be above content
lukasoppermann Apr 4, 2024
59c643a
Update content/components/banner.mdx
lukasoppermann May 7, 2024
0addac6
Update content/components/banner.mdx
lukasoppermann May 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
243 changes: 242 additions & 1 deletion content/components/banner.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,256 @@ tags:
- flash
---

import {Box} from '@primer/react'
import ComponentLayout from '~/src/layouts/component-layout'
export default ComponentLayout
import {AccessibilityLink} from '~/src/components/accessibility-link'

Banner can be used in one of two ways:
<img
width="960"
alt="Image displaying each variant of banenr, from top: critical, warning, success, info, upsell."
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
src="https://github.com/primer/primitives/assets/813754/f96b1eda-2413-4fc1-b1a7-3775b0c3b324"
/>

## Usage

Banner can be used in one of two ways:
1. To highlight prominent information on a page.
2. To communicate feedback in response to a user action.

For system wide information, consider using an [announcement](../ui-patterns/messaging#message-types).

## Anatomy

<img
width="960"
alt="Anatomy of a banner, including the message, title, icon, dismiss button, primary, and secondary action"
src="https://github.com/primer/design/assets/813754/defa52f8-49bb-4332-aaa1-872a22a563a9"
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
/>

## Options

### Variant
mperrotti marked this conversation as resolved.
Show resolved Hide resolved
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved

<Box
mb={3}
display="flex"
alignItems="flex-start"
flexDirection={['column', 'column', 'column', 'column', 'row']}
sx={{gap: 4}}
>
<img
width="456"
alt="critical banner"
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
src="https://github.com/primer/design/assets/813754/8b135c8e-898d-423c-81c4-9dbb4736a4d5"
/>
<Box as="p" mt="0">
<h4>Critical</h4>
Use critical banners to signal critical errors, system failures, or necessary destructive actions. Examples: form validation error summary, repo deletion confirmations.
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
</Box>
</Box>

<Box
mb={3}
display="flex"
alignItems="flex-start"
flexDirection={['column', 'column', 'column', 'column', 'row']}
sx={{gap: 4}}
>
<img
width="456"
alt="warning banner"
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
src="https://github.com/primer/design/assets/813754/fc82519b-60e1-45b3-a0de-c5f89108e96e"
/>
<Box as="p" mt="0">
<h4>Warning</h4>
Use warning banners to alert users about potential issues or impactful changes. For example possible connectivity concerns or hidden items due to active filters.
</Box>
</Box>

<Box
mb={3}
display="flex"
alignItems="flex-start"
flexDirection={['column', 'column', 'column', 'column', 'row']}
sx={{gap: 4}}
>
<img
width="456"
alt="success banner"
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
src="https://github.com/primer/design/assets/813754/fe04a355-d343-4a79-9948-efc64d6de76e"
/>
<Box as="p" mt="0">
<h4>Success</h4>
Use success banners to indicate task completion or successful actions. For example to confirm saving of settings or successful issue transfer. Only use success messages if the success is not easily apparent in the UI.
</Box>
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
</Box>

<Box
mb={3}
display="flex"
alignItems="flex-start"
flexDirection={['column', 'column', 'column', 'column', 'row']}
sx={{gap: 4}}
>
<img
width="456"
alt="info banner"
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
src="https://github.com/primer/design/assets/813754/172e3eb4-35ea-4d75-a015-6d00d3ebd914"
/>
<Box as="p" mt="0">
<h4>Info</h4>
Use info banners to inform about non-critical context and information. For example feature prompts or ongoing processes.
</Box>
</Box>

<Box
mb={3}
display="flex"
alignItems="flex-start"
flexDirection={['column', 'column', 'column', 'column', 'row']}
sx={{gap: 4}}
>
<img
width="456"
alt="upsell banner"
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
src="https://github.com/primer/design/assets/813754/48b37115-c0e0-40c3-83f1-3e831178f175"
/>
<Box as="p" mt="0">
<h4>Upsell</h4>
Use upsell banners to inform the users about a feature that can be enabled by upgrading their plan.
</Box>
</Box>

### Title

<Box
mb={3}
display="flex"
alignItems="flex-start"
flexDirection={['column', 'column', 'column', 'column', 'row']}
sx={{gap: 4}}
>
<img
width="456"
alt="banner without title and banner with title"
src="https://github.com/primer/design/assets/813754/c5876803-7b5b-486d-b2ec-27fcfdf0c5d8"
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
/>
<Box as="p" mt="0">
<h4>Title</h4>
Use a title to consisly present the topic of the banner when the message of the banner is complex and too long to scan.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add something about title being required but may be visually hidden?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@joshblack is this how we implement it, or is there a separate a11y title which will just use the title the user defines if they do?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lukasoppermann I think this is how it's implemented now where the title is required but may be visually hidden 👍 At the moment, this would mean they wrap the title in VisuallyHidden but we could also simplify this with a dedicated prop if that would be helpful.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure if this is the right place for a discussion, but I am a bit afraid that if the title is not hidden by default, we will get a lot of duplicates with title and body being the same text.

My only thought to improve this would be to have two props like aria-title and title where aria-title is set to title if present. So, using typescript we could require on of the two to be set.

But I am no react dev and this may be an uncommon or anti-pattern.

</Box>
</Box>

### Dismissable

<Box
mb={3}
display="flex"
alignItems="flex-start"
flexDirection={['column', 'column', 'column', 'column', 'row']}
sx={{gap: 4}}
>
<img
width="456"
alt="banners with a dismiss button"
src="https://github.com/primer/design/assets/813754/e9863c48-cf3a-472b-a066-0ba139a633ca"
/>
<Box as="p" mt="0">
<h4>Dismiss button</h4>
Banners with an <i>onDismiss</i> property automatically show a dismiss button.
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
</Box>
</Box>
<Box
mb={3}
display="flex"
alignItems="flex-start"
flexDirection={['column', 'column', 'column', 'column', 'row']}
sx={{gap: 4}}
>
<img
width="456"
alt="a critical banner with no actions and one with a single action"
src="https://github.com/primer/design/assets/813754/2463e14c-5cb9-4bb4-9e3a-474c60c32da4"
/>
<Box as="p" mt="0">
<h4>Critical banner</h4>
<p>
Critical banner can't be made dismissable. Since they should only be used for errors that need to be resolved, the only way to get rid of a critical banner is to resolve the error. If they are used to warn the user about destructive actions the banner should also not be dismissable.</p>
<p>
If the error must be resolved on a different page, it is recommended to add an action that directs the user to the page where the error can be resolved.
</p>
</Box>
</Box>

### Actions

<Box
mb={3}
display="flex"
alignItems="flex-start"
flexDirection={['column', 'column', 'column', 'column', 'row']}
sx={{gap: 4}}
>
<img
width="456"
alt="trailing actions on a banner"
src="https://github.com/primer/design/assets/813754/b4d2e88e-2f0e-4b29-8f21-13ac8399c943"
/>
<Box as="p" mt="0">
<h4>Actions</h4>
A maximum of 2 actions can be added to a banner. Whenever possible it is recommended to only add a single action to better direct the users attention.
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved

You can choose between adding a primary or secondary action, depending on how much attention you want to draw to the action.
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved

If you do need two actions in your banner, one of them must be primary and the other must be secondary. In this case, use the primary action for the recommended action for example, to enable a feature and the secondary one to get more information.
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
</Box>
</Box>

### Icon

<Box
mb={3}
display="flex"
alignItems="flex-start"
flexDirection={['column', 'column', 'column', 'column', 'row']}
sx={{gap: 4}}
>
<img
width="456"
alt="banners with icons, some of which are customized"
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
src="https://github.com/primer/design/assets/813754/dd6d9159-8de7-4f71-b69b-ede15284aeb4"
/>
<Box as="p" mt="0">
<h4>Icon</h4>
The icon relates to the selected <a href="#variant">variant</a> and can't be disabled. It can only be changed for banners of variant <i>info</i> or <i>upsell</i>.
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
</Box>
</Box>

## Breakpoints
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
<img
width="960"
alt="Anatomy of a banner, including the message, title, icon, dismiss button, primary, and secondary action"
src="https://github.com/primer/design/assets/813754/b1db8982-43ce-4a95-b25a-407020b53440"
/>

On large screens the layout of the elements within the banner adjust depending on which elements are enabled. On small screensthe banner always uses the stacked layout.
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved

## Layouts
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
<img
width="960"
alt="Layouts depending on which elements are enabled"
src="https://github.com/primer/design/assets/813754/fe702f23-de88-47a9-b703-b8b262698a50"
/>
Text missing
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved

## Best practices
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved
Use banners sparingly and only when necessary. Banners can disrupt the user experience and should only be used when and where relevant.

Keep the message concise and direct. Don't use headings or multiple type sizes in banners, rely on the default paragraph size and use the title when appropiate.
lukasoppermann marked this conversation as resolved.
Show resolved Hide resolved

Don't show more than one banner at a time. For more information, see this article on [alert fatigue](https://www.nngroup.com/videos/alert-fatigue-user-interfaces/).

## Accessibility
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you confirm that none of the proposed Banner updates affect our existing a11y guidance?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I'd love to get this info form @ichelsea

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding this to my list of things to look at this week!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, this entire a11y section was written up form the work that @lindseywild and @khiga8 did, so it's valid! There are a couple of things that we want to adjust based on feedback from engineering office hours earlier this week that has also been on my to-do list to get to.

We can create a separate PR for that if you want to get this one merged, or I can add to it before this one is merged.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add it to this PR. We will keep it open until the react components are implemented and shipped, so it will be open for a bit.


### Feedback Banners
Expand Down
2 changes: 2 additions & 0 deletions src/@primer/gatsby-theme-doctocat/nav.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,6 +209,8 @@
url: /components/avatar-pair
- title: Avatar stack
url: /components/avatar-stack
- title: Banner
url: /components/banner
- title: Blankslate
url: /components/blankslate
- title: Border box
Expand Down
Loading