Skip to content

Banner specification

Jump to bottom
Radoslav Karaivanov edited this page Jun 10, 2024 · 1 revision

Banner specification

Owned by

Team name: Astrea

Developer name: Riva Ivanova

Designer name: Silvia Ivanova

Requires approval from

  • Radoslav Karaivanov | Date:
  • Svilen Dimchevski | Date:

Signed off by

  • Radoslav Mirchev | Date:
  • Damyan Petev | Date:

Revision history

Version Author Date Notes
1 Radoslav Karaivanov 2024-04-08 Initial draft
1.1 Radoslav Karaivanov 2024-04-24 Updated draft specification
1.2 Radoslav Karaivanov 2024-06-10 Finalized specification

Overview

The igc-banner component displays important and concise message(s) for a user to address, that is specific to a page or feature. It can also indicate actions to take based on the context of the message. Banners usually remain until dismissed by the user or if the state that caused the banner is resolved.

Acceptance criteria

The igc-banner:

  • must support slotting content for the main message
  • must support slotting additional "leading" content such as icons, badges, avatars, etc.
  • must support slotting action elements
  • must be WAI-ARIA compliant

User stories

Developer stories:

As a developer I expect to be able to:

  • provide a message informing users about certain state of functionality.
  • provide additional information and aid through icons, badges, etc.
  • have a default action with which users can confirm that they have been notified.
  • provide more actions for users.
  • customize the look and feel of the banner component.

End-user stories:

As an end-user I expect to be able to:

  • get informed about events/states that are not crucial in a less obtrusive way.
  • take actions based on the provided message context.

Functionality

End-user experience

Design hand-off

Developer experience

  • The banner features a default action that acknowledges user notifications. The igcClosing/igcClosed events are triggered exclusively by interacting with this default action. Inserting actions into the action slot will replace the default action, leaving the developer responsible for closing the component as per the specific use case.

Basic usage

<igc-banner>
  You are currently not logged in! Please, log into your account first.
</igc-banner>

Using available slots

<igc-banner>
  <igc-icon name="success" slot="prefix"></igc-icon>

  Build <strong>f58a1815-c069-429d-ab20-860849e96a59</strong> completed!

  <div slot="actions">
    <igc-button>OK</igc-button>
    <igc-button href="...">View log</igc-button>
  </div>
</igc-banner>

Localization

No specific points are applicable for localization.

Keyboard navigation

No additional implementation is required.

API

Properties

Property Attribute Reflected Type Default Description
open open Yes boolean false Whether the banner is being shown/hidden.

Methods

Method Type Description
show (): Promise<boolean> Shows the banner if not already shown.
hide (): Promise<boolean> Hides the banner if not already hidden.
toggle (): Promise<boolean> Toggles between shown/hidden state.

Slots

Name Description
(default) Renders the text content of the banner message.
prefix Renders additional content at the start of the message block.
actions Renders any action elements.

Events

Name Cancellable Description
igcClosing Yes Emitted when a user interacts (click) with the default action of the banner.
igcClosed No Emitted when a user interacts (click) with the default action of the banner.

CSS Parts

Name Description
base The base wrapper of the banner.
spacer The inner wrapper that sets the space around the banner.
message The part that holds the text and the illustration.
illustration the part that holds the banner icon/illustration.
content the part that holds the banner text content.
actions the part that holds the banner action buttons.

Test scenarios

Automation

  1. The banner is correctly initialized and rendered both in shown/hidden states.
  2. The banner passes automated WAI-ARIA tests.
  3. The banner correctly renders slotted content.
  4. Correct event sequence is fired for the default action of the banner component.

Accessibility

ARIA

  • While there is a defined banner role, it is usually reserved for a global site header. One of the landmark, alert or status roles should be picked after testing with an accessibility tool such as NVDA.

  • The banner show/hide animations respect the prefers-reduced-motion query. If the end-user has requested from their OS to minimize the amount of animation or motion, the banner animations will finish immediately.

RTL support

The component should work in a Right-To-Left context without additional setup or configuration.

Assumptions and limitations

None applicable.

Clone this wiki locally