@boostdev/design-system-components 1.1.0 → 1.1.1

package/src/web-components/ui/BdsBadge.mdx

@@ -0,0 +1,74 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsBadge.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-badge&gt;
+
+Framework-agnostic badge custom element for short status labels and counts. Five semantic variants covering the common status palette.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Primary
+<Canvas of={Stories.Primary} />
+
+### Secondary
+<Canvas of={Stories.Secondary} />
+
+### Success
+<Canvas of={Stories.Success} />
+
+### Error
+<Canvas of={Stories.Error} />
+
+### Warning
+<Canvas of={Stories.Warning} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `variant` | `"primary" \| "secondary" \| "success" \| "error" \| "warning"` | `"primary"` | Semantic colour |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Badge label text |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--badge_bg` | Badge background colour |
+| `--badge_text` | Badge text colour |
+| `--badge_font-size` | Font size |
+| `--badge_radius` | Border radius |
+
+## Usage in plain HTML
+
+```html
+<bds-badge variant="success">Active</bds-badge>
+<bds-badge variant="error">3</bds-badge>
+<bds-badge variant="warning">Pending</bds-badge>
+```
+
+## Accessibility
+
+- Badge is a purely visual element — wrap in an element with `aria-label` when the colour alone conveys meaning (e.g. status indicators)
+- For count badges next to icon buttons, use `aria-label` on the parent: `aria-label="3 notifications"`