chore(docs): banner page in new format (VIV-2084)

apps/docs/content/_data/components.json

@@ -18,8 +18,13 @@
 	},
 	{
 		"title": "Banner",
-		"page": "legacy",
-		"markdown": "./libs/components/src/lib/banner/README.md"
+		"description": "Banner displays a prominent message, usually on system level, and provides actions for users to address or dismiss.",
+		"variations": "./libs/components/src/lib/banner/VARIATIONS.md",
+		"guidelines": "./libs/components/src/lib/banner/GUIDELINES.md",
+		"hideGuidelines": "true",
+		"code": "./libs/components/src/lib/banner/README.md",
+		"accessibility": "./libs/components/src/lib/banner/ACCESSIBILITY.md",
+		"useCases": "./libs/components/src/lib/banner/USE-CASES.md"
 	},
 	{
 		"title": "Alert",

libs/components/src/lib/banner/ACCESSIBILITY.md

@@ -0,0 +1,22 @@
+### Accessibility
+
+The banner defaults its role to `status` with a redundant aria-live attribute set to polite (to maximize compatibility when using this role).  
+This indicates that the screen reader should wait until the user is idle before presenting updates to the user.
+However, consumers can modify the above attributes (role and aria-live) to fit contextually.  
+If the information is critical, by altering the banner's role to `alert`, assistive technologies will interrupt other processes and provide users with immediate notification.
+
+- The `role` attribute is set to [`status`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) by default. This can be changed.
+- The [`aria-live`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) attribute is set to `polite` by default. This can be changed.
+- The banner can be dismissed by hitting the `escape` key when it is in focus.
+
+```js
+<vwc-banner
+	role="status"
+	aria-live="polite"
+	text="Here's some information that you may find important!"
+></vwc-banner>
+```
+
+## Resources
+
+[Vivid Banner: Manual accessibility test](https://docs.google.com/spreadsheets/d/1o7qO79yNLTEMN0w2vc9YYMZ5DF1FyxH_42150yoDPIo/edit?gid=1066167376#gid=1066167376)

libs/components/src/lib/banner/GUIDELINES.md

@@ -0,0 +1,77 @@
+## Text
+
+<docs-do-dont no-gutters headline="Avoid long sentences in the Banner">
+
+<docs-do>
+
+```html preview example
+<vwc-banner
+	text="Use Vivid in Your Design"
+	icon="sparkles-solid"
+	connotation="announcement"
+>
+	<vwc-button
+		slot="action-items"
+		size="condensed"
+		shape="pill"
+		href="https://vivid.deno.dev"
+		target="_blank"
+		appearance="filled"
+		connotation="accent"
+		label="Start Using Vivid Components Now"
+		icon="chevron-right-line"
+		icon-trailing
+	></vwc-button
+></vwc-banner>
+```
+
+</docs-do>
+
+<docs-do dont>
+
+```html preview example
+<vwc-banner
+	text="Use Vivid in Your Design in all of your design. Fill for designers and for developers as well"
+	icon="sparkles-solid"
+	connotation="announcement"
+>
+	<vwc-button
+		slot="action-items"
+		size="condensed"
+		shape="pill"
+		href="https://vivid.deno.dev"
+		target="_blank"
+		appearance="filled"
+		connotation="accent"
+		label="Start Now"
+		icon="chevron-right-line"
+		icon-trailing
+	></vwc-button
+></vwc-banner>
+```
+
+</docs-do>
+</docs-do-dont>
+
+## Connotation
+
+<docs-do-dont no-gutters headline="Use the banner connotation according to its purpose">
+
+<docs-do>
+
+```html preview example
+<vwc-banner text="Operation Successful!" connotation="success"> ></vwc-banner>
+```
+
+</docs-do>
+
+<docs-do dont>
+
+```html preview example
+<vwc-banner text="Operation Successful!" connotation="information">
+	></vwc-banner
+>
+```
+
+</docs-do>
+</docs-do-dont>

libs/components/src/lib/banner/README.md

@@ -1,85 +1,46 @@
-# Banner
+## Usage
 
-Banner displays a prominent message, usually on system level, and provides actions for users to address or dismiss.
-
-It is meant to be used at the top of pages, outside the main content.
+<vwc-tabs>
+<vwc-tab label="Web component"></vwc-tab>
+<vwc-tab-panel>
 
 ```js
-<script type="module">import '@vonage/vivid/banner';</script>
+import '@vonage/vivid/banner';
 ```
 
-## Members
-
-### Text
-
-- Type: `string`
-- Default: `''`
+or, if you need to use a unique prefix:
 
-Use the `text` attribute to set the banner's text.
+```js
+import { registerBanner } from '@vonage/vivid';
 
-```html preview full
-<vwc-banner
-	text="Here's some information that you may find important!"
-></vwc-banner>
+registerBanner('your-prefix');
 ```
 
-### Connotation
-
-The `connotation` attribute sets the colors according to the wanted connotation.
-
-- Type: `'information'` | `'announcement'` | `'success'` | `'warning'` | `'alert'`
-- Default: `'information'`
-
-Note that icon, if not specifically set, defaults to a connotation-associated icon.
-
 ```html preview
-<vwc-banner
-	text="Here's some information that you may find useful!"
-	connotation="information"
-></vwc-banner>
-<vwc-banner
-	text="Here's some information that you may find important!"
-	connotation="announcement"
-></vwc-banner>
-<vwc-banner text="Operation Successful!" connotation="success"></vwc-banner>
-<vwc-banner
-	text="Heads up - this is a warning"
-	connotation="warning"
-></vwc-banner>
-<vwc-banner
-	text="ALERT! Something went wrong!"
-	connotation="alert"
-></vwc-banner>
-```
+<script type="module">
+	import { registerBanner } from '@vonage/vivid';
+	registerBanner('your-prefix');
+</script>
 
-### Icon
-
-- Type: `string`
-- Default: `'information'`
-
-The `icon` attribute will override the icon set by connotation.
-
-```html preview full
-<vwc-banner
-	text="Here's some information that you may find important!"
-	icon="home-line"
-></vwc-banner>
+<your-prefix-banner text="My Banner"></your-prefix-banner>
 ```
 
-### Removable
-
-- Type: `boolean`
-- Default: `false`
-
-The `removable` attribute adds a remove button. On click it will remove the banner from the DOM.
-
-```html preview full
-<vwc-banner
-	text="Here's some information that you may find important!"
-	removable
-></vwc-banner>
+</vwc-tab-panel>
+<vwc-tab label="Vue"></vwc-tab>
+<vwc-tab-panel>
+
+```html
+<script setup lang="ts">
+	import { VBanner } from '@vonage/vivid-vue';
+</script>
+<template>
+	<VBanner connotation="success" text="Operation Successful!" />
+</template>
 ```
 
+</vwc-tab-panel>
+</vwc-tabs>
+
 ## Slots
 
 ### Action Items
@@ -90,6 +51,8 @@ You can add action items using slotted content in a named slot `action-items`:
 <vwc-banner text="A banner with an action button">
 	<vwc-button
 		slot="action-items"
+		href="https://vonage.com"
+		target="_blank"
 		appearance="filled"
 		connotation="accent"
 		label="Learn More"
@@ -220,7 +183,33 @@ If set, the `icon` attribute is ignored.
 </vwc-banner>
 ```
 
-## Events
+## API Reference
+
+### Properties
+
+<div class="table-wrapper">
+
+| Name          | Description                                                                                      |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| `text`        | `string`                                                                                         |
+| `connotation` | Enum\_:<br/>`information` (default) <br/>`announcement`<br/>`success`<br/>`warning` <br/>`alert` |
+| `icon`        | Enum\_:<br/>`[icon-name]`                                                                        |
+| `removable`   | `boolean`                                                                                        |
+
+</div>
+
+### Slots
+
+<div class="table-wrapper">
+
+| Name             | Description                                     |
+| ---------------- | ----------------------------------------------- |
+| **Action Items** | Add action items like buttons to the component. |
+| **Icon**         | Add an icon to the component.                   |
+
+</div>
+
+### Events
 
 <div class="table-wrapper">
 
@@ -231,7 +220,7 @@ If set, the `icon` attribute is ignored.
 
 </div>
 
-## Methods
+### Methods
 
 <div class="table-wrapper">
 
@@ -240,20 +229,3 @@ If set, the `icon` attribute is ignored.
 | `remove` | `void`  | Removes the banner from the DOM. Fires the `removing` event and starts the remove animation. When the animation finishes, it emits the `removed` event and removes the banner from the DOM completely. If you have a variable that refers to the banner element make sure to clear it otherwise it might cause a memory leak. |
 
 </div>
-
-## Accessibility
-
-The banner defaults its role to ‘status’ with a redundant aria-live attribute set to polite (to maximize compatibility when using this role). This indicates that the screen reader should wait until the user is idle before presenting updates to the user.
-However, consumers can modify the above attributes (role and aria-live) to fit contextually. If the information is critical, by altering the banner's role to 'alert', assistive technologies will interrupt other processes and provide users with immediate notification.
-
-- The `role` attribute is set to `status` by default. This can be changed.
-- The `aria-live` attribute is set to `polite` by default. This can be changed.
-- The banner can be dismissed by hitting the `escape` key when it is in focus.
-
-```js
-<vwc-banner
-	role="status"
-	aria-live="polite"
-	text="Here's some information that you may find important!"
-></vwc-banner>
-```

libs/components/src/lib/banner/USE-CASES.md

@@ -0,0 +1,69 @@
+## Banner Before Site Header
+
+```html preview 380px
+<div class="site">
+	<vwc-banner
+		class="banner"
+		text="Use Vivid in Your Design"
+		icon="sparkles-solid"
+		connotation="announcement"
+	>
+		<vwc-button
+			slot="action-items"
+			size="condensed"
+			shape="pill"
+			href="https://vivid.deno.dev"
+			target="_blank"
+			appearance="filled"
+			connotation="accent"
+			label="Start Now"
+			icon="chevron-right-line"
+			icon-trailing
+		></vwc-button
+	></vwc-banner>
+	<vwc-header alternate>Site Header</vwc-header>
+	<div class="body">
+		<h2>Site Content</h2>
+		<p>
+			Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam a placerat
+			velit, ac finibus mi. Maecenas placerat ex orci, ut pulvinar elit faucibus
+			vel. Cras tellus nisi, interdum ut diam quis, varius cursus magna. In
+			tempus eleifend dui, id porta orci vulputate eu. Donec porttitor neque in
+			feugiat viverra. Nam eget porttitor ligula. Aenean non turpis laoreet,
+			porta mauris sed, vulputate augue. Quisque sit amet lacinia dolor, sed
+			sollicitudin velit. Vestibulum nec libero ultrices, lacinia diam sed,
+			tincidunt massa.
+		</p>
+		<p>
+			Sed efficitur commodo dolor, nec commodo velit porttitor eget. Ut
+			ullamcorper efficitur eros, at convallis eros blandit et. Aliquam feugiat
+			vitae velit vitae lobortis. Integer a turpis non leo sagittis convallis ac
+			lobortis ligula. Ut gravida pharetra turpis. Suspendisse laoreet nibh nec
+			blandit tempus. Aenean laoreet luctus nunc luctus tincidunt. Praesent
+			aliquet ultrices lorem, venenatis hendrerit massa scelerisque id. Morbi
+			consectetur aliquam pretium. Quisque facilisis sapien et tortor venenatis
+			eleifend. Phasellus varius accumsan risus ut elementum. Maecenas bibendum
+			vestibulum metus quis consectetur. Morbi non eros nec enim eleifend
+			mollis. Duis luctus ex neque, sed hendrerit tellus commodo et.
+		</p>
+	</div>
+</div>
+
+<style>
+	.site {
+		display: flex;
+		flex-direction: column;
+		max-block-size: 360px;
+		position: relative;
+	}
+	.banner {
+		position: sticky;
+		inset-block-start: 0;
+		z-index: 2;
+	}
+	.body {
+		padding-inline: 16px;
+		background-color: var(--vvd-color-neutral-tint-100);
+	}
+</style>
+```