chore(docs): Badge docs update (VIV-2083) (#2080)

Vonage · Jan 21, 2025 · c69d514 · c69d514
1 parent d8d8845
commit c69d514
Show file tree

Hide file tree

Showing 6 changed files with 248 additions and 195 deletions.
diff --git a/apps/docs/content/_data/components.json b/apps/docs/content/_data/components.json
@@ -11,8 +11,13 @@
 	},
 	{
 		"title": "Badge",
-		"page": "legacy",
-		"markdown": "./libs/components/src/lib/badge/README.md"
+		"description": "A small label, generally appearing inside or in proximity to another larger interface component, representing a status, property, or some other metadata.",
+		"variations": "./libs/components/src/lib/badge/VARIATIONS.md",
+		"guidelines": "./libs/components/src/lib/badge/GUIDELINES.md",
+		"hideGuidelines": "true",
+		"code": "./libs/components/src/lib/badge/README.md",
+		"accessibility": "./libs/components/src/lib/badge/ACCESSIBILITY.md",
+		"useCases": "./libs/components/src/lib/badge/USE-CASES.md"
 	},
 	{
 		"title": "Banner",

diff --git a/libs/components/src/lib/badge/ACCESSIBILITY.md b/libs/components/src/lib/badge/ACCESSIBILITY.md
@@ -0,0 +1,8 @@
+## Implementation
+
+Badges are informative elements and cannot be interacted with.  
+If you're looking for an intractable component, consider using a [tag](/components/tag/) instead.
+
+### Icon-only Badge
+
+Use the `aria-label` attribute to provide alternative text for icon-only badge. This text is read by screen readers and lets the user know the purpose of the badge.
diff --git a/libs/components/src/lib/badge/GUIDELINES.md b/libs/components/src/lib/badge/GUIDELINES.md
diff --git a/libs/components/src/lib/badge/README.md b/libs/components/src/lib/badge/README.md
@@ -1,204 +1,52 @@
-# Badge
+## Usage
 
-A small label, generally appearing inside or in proximity to another larger interface component, representing a status, property, or some other metadata.
+<vwc-tabs>
+<vwc-tab label="Web component"></vwc-tab>
+<vwc-tab-panel>
 
 ```js
-<script type="module">import '@vonage/vivid/badge';</script>
+import '@vonage/vivid/badge';
 ```
 
-## Members
+or, if you need to use a unique prefix:
 
-### Text
-
-Add a `text` attribute to add text to the badge.
-
-- Type: `string`
-- Default: `undefined`
-
-```html preview
-<vwc-badge text="A default badge"></vwc-badge>
-```
-
-### Shape
-
-Use the `shape` attribute to change the badge's edges.
-
-- Type: `'rounded'` | `'pill'`
-- Default: `'rounded'`
-
-```html preview
-<vwc-badge text="rounded" shape="rounded"></vwc-badge>
-<vwc-badge text="pill" shape="pill"></vwc-badge>
-```
-
-### Icon
-
-Use `icon` to set an icon to the badge.
-View the list of available icons at the [vivid icons gallery](/icons/icons-gallery/).
-
-Note: An icon on its own doesn't make a discernible text. An `aria-label` should be provided to ensure that the user can understand the avatar.
-
-- Type: `string`
-- Default: `undefined`
-
-```html preview
-<vwc-badge appearance="filled" icon="message-sent-line"></vwc-badge>
-<vwc-badge
-	appearance="filled"
-	icon="message-sent-line"
-	shape="pill"
-></vwc-badge>
-```
-
-### Icon with Text
-
-Use the `icon-trailing` attribute to control whether the icon is aligned to the start or end of the badge.
-
-- Type: `boolean`
-- Default: `undefined`
-
-```html preview
-<vwc-badge appearance="filled" text="icon" icon="check-line"></vwc-badge>
-<vwc-badge
-	appearance="filled"
-	text="icon-trailing"
-	icon="check-line"
-	icon-trailing
-></vwc-badge>
-```
-
-### Appearance
-
-Set the `appearance` attribute to change the badge's appearance.
-
-- Type: `'filled'` | `'subtle'` | `'subtle-light'` | `'duotone'`
-- Default: `'filled'`
+```js
+import { registerBanner } from '@vonage/vivid';
 
-```html preview
-<vwc-badge text="filled" appearance="filled"></vwc-badge>
-<vwc-badge text="subtle" appearance="subtle"></vwc-badge>
-<vwc-badge text="subtle-light" appearance="subtle-light"></vwc-badge>
-<vwc-badge text="duotone" appearance="duotone"></vwc-badge>
+registerBadge('your-prefix');
 ```
 
-### Connotation
-
-Set the `connotation` attribute to change the badge's connotation.
-It accepts a subset of predefined values.
-
-- Type: `'accent'` | `'cta'` | `'success'` | `'alert'` | `'warning'` | `'information'` | `'announcement'`
-- Default: `'accent'`
-
-#### Filled badge with connotation
-
 ```html preview
-<vwc-badge text="accent" connotation="accent" appearance="filled"></vwc-badge>
-<vwc-badge text="cta" connotation="cta" appearance="filled"></vwc-badge>
-<vwc-badge
-	text="information"
-	connotation="information"
-	appearance="filled"
-></vwc-badge>
-<vwc-badge
-	text="announcement"
-	connotation="announcement"
-	appearance="filled"
-></vwc-badge>
-<vwc-badge text="success" connotation="success"></vwc-badge>
-<vwc-badge text="warning" connotation="warning"></vwc-badge>
-<vwc-badge text="alert" connotation="alert"></vwc-badge>
-```
-
-#### Subtle badge with connotation
+<script type="module">
+	import { registerBadge } from '@vonage/vivid';
+	registerBadge('your-prefix');
+</script>
 
-```html preview
-<vwc-badge text="accent" appearance="subtle" connotation="accent"></vwc-badge>
-<vwc-badge text="cta" appearance="subtle" connotation="cta"></vwc-badge>
-<vwc-badge
-	text="information"
-	appearance="subtle"
-	connotation="information"
-></vwc-badge>
-<vwc-badge
-	text="announcement"
-	appearance="subtle"
-	connotation="announcement"
-></vwc-badge>
-<vwc-badge text="success" appearance="subtle" connotation="success"></vwc-badge>
-<vwc-badge text="warning" appearance="subtle" connotation="warning"></vwc-badge>
-<vwc-badge text="alert" appearance="subtle" connotation="alert"></vwc-badge>
+<your-prefix-badge text="My Badge"></your-prefix-badge>
 ```
 
-#### Subtle-Light badge with connotation
-
-```html preview
-<vwc-badge
-	text="accent"
-	appearance="subtle-light"
-	connotation="accent"
-></vwc-badge>
-<vwc-badge text="cta" appearance="subtle-light" connotation="cta"></vwc-badge>
-<vwc-badge
-	text="information"
-	appearance="subtle-light"
-	connotation="information"
-></vwc-badge>
-<vwc-badge
-	text="announcement"
-	appearance="subtle-light"
-	connotation="announcement"
-></vwc-badge>
-<vwc-badge
-	text="success"
-	appearance="subtle-light"
-	connotation="success"
-></vwc-badge>
-<vwc-badge
-	text="warning"
-	appearance="subtle-light"
-	connotation="warning"
-></vwc-badge>
-<vwc-badge
-	text="alert"
-	appearance="subtle-light"
-	connotation="alert"
-></vwc-badge>
+</vwc-tab-panel>
+<vwc-tab label="Vue"></vwc-tab>
+<vwc-tab-panel>
+
+```html
+<script setup lang="ts">
+	import { VBadge } from '@vonage/vivid-vue';
+</script>
+<template>
+	<VBadge connotation="success" text="My Badge" />
+</template>
 ```
 
-#### Duotone badge with connotation
-
-```html preview
-<vwc-badge text="accent" appearance="duotone" connotation="accent"></vwc-badge>
-<vwc-badge text="cta" appearance="duotone" connotation="cta"></vwc-badge>
-<vwc-badge
-	text="information"
-	appearance="duotone"
-	connotation="information"
-></vwc-badge>
-<vwc-badge
-	text="announcement"
-	appearance="duotone"
-	connotation="announcement"
-></vwc-badge>
-<vwc-badge
-	text="success"
-	appearance="duotone"
-	connotation="success"
-></vwc-badge>
-<vwc-badge
-	text="warning"
-	appearance="duotone"
-	connotation="warning"
-></vwc-badge>
-<vwc-badge text="alert" appearance="duotone" connotation="alert"></vwc-badge>
-```
+</vwc-tab-panel>
+</vwc-tabs>
 
 ## Slots
 
 ### Icon
 
-Set the `icon` slot to add an icon to the badge.
-If set, the `icon` attribute is ignored.
+Use the `icon` slot to customise icons.  
+If set, the icon attribute is ignored.
 
 ```html preview
 <vwc-badge text="with icon slot" appearance="filled">
@@ -210,22 +58,29 @@ If set, the `icon` attribute is ignored.
 </vwc-badge>
 ```
 
-## Use Cases
+## API Reference
 
-### Trim Text
+### Properties
 
-```html preview
-<vwc-badge text="with overflowing text" style="inline-size: 60px;"></vwc-badge>
-```
+<div class="table-wrapper">
 
-### Custom Width
+| Name            | Description                                                                                        | Description                  |
+| --------------- | -------------------------------------------------------------------------------------------------- | ---------------------------- |
+| `text`          | `string`                                                                                           | Sets a text on the badge     |
+| `connotation`   | Enum\_:<br/>`accent` (default), `announcement`,`alert`, `cta`, `success`, `warning`, `information` | Sets the badge connotation   |
+| `icon`          | Enum\_:<br/>`[icon-name]`                                                                          | Sets the element's icon      |
+| `icon-trailing` | `string`                                                                                           | Sets icon as trailing        |
+| `appearance`    | Enum\_:<br/>`filled` (default), `duotone`, `subtle`, `subtle-light`                                | Sets the badge appearance    |
+| `shape`         | Enum\_:<br/>`rounded` (default), `pill`                                                            | Sets the badge border-radius |
 
-```html preview
-<vwc-badge text="with min-width" style="min-width: 300px;"></vwc-badge>
-```
+</div>
+
+### Slots
 
-## Accessibility
+<div class="table-wrapper">
 
-Badges are informative elements and cannot be interacted with.
+| Name     | Description                   |
+| -------- | ----------------------------- |
+| **Icon** | Add an icon to the component. |
 
-If you're looking for an interactable component, consider using a [tag](/components/tag/) instead.
+</div>
diff --git a/libs/components/src/lib/badge/USE-CASES.md b/libs/components/src/lib/badge/USE-CASES.md
@@ -0,0 +1,23 @@
+## Trim Text
+
+```html preview
+<vwc-badge class="badge-trim" text="overflowing text"></vwc-badge>
+
+<style>
+	.badge-trim {
+		inline-size: 60px;
+	}
+</style>
+```
+
+## Custom Width
+
+```html preview
+<vwc-badge class="badge-inline-size" text="with min-width"></vwc-badge>
+
+<style>
+	.badge-inline-size {
+		min-width: 300px;
+	}
+</style>
+```