import { Meta, Story, Controls, Canvas, Primary } from "@storybook/addon-docs";

import * as stories from "./banner.stories";

<Meta of={stories} />

# Banner

Banners are used for important communication with the user that needs to be seen right away, but has
little effect on the experience. Banners appear at the top of the user's screen on page load and
persist across all pages a user navigates to.

- They should always be dismissible and never use a timeout. If a user dismisses a banner, it should
  not reappear during that same active session.
- Use banners sparingly, as they can feel intrusive to the user if they appear unexpectedly. Their
  effectiveness may decrease if too many are used.
- Avoid stacking multiple banners.
- Banners support a button link (text button).

<Primary />

<Controls />

## Types

Icons should remain consistent across these types. Do not change the icon without consulting
designers.

Use the following guidelines to help choose the correct type of banner.

### Premium

<Story of={stories.Premium} />

Used primarily to encourage user to upgrade to premium.

### Info

<Story of={stories.Info} />

Used to communicate release notes, server maintenance or other informative event.

### Warning

<Story of={stories.Warning} />

Used to alert the user of outdated info or versions.

### Danger

<Story of={stories.Danger} />

Rarely used, but may be used to alert users over critical messages or very outdated versions.

## Accessibility

Banners sets the `role="status"` and `aria-live="polite"` attributes to ensure screen readers
announce the content prior to the test of the page. This behaviour can be disabled by setting
`[useAlertRole]="false"`.