@supersoniks/concorde 5.1.0 → 5.1.2

package/docs/src/core/components/ui/alert/alert.md

@@ -1,121 +1,186 @@
 # Alert
 
+Alerts **surface important feedback** inline—errors, confirmations, or contextual help. Use **`label`** / **`text`** for simple copy, or the **default slot** for rich content (links, buttons). Set **`announce`** when the message appears after an action so screen readers pick it up.
+
+## Basic example
+
 <sonic-code>
   <template>
-    <sonic-alert status="error" label="Email error" text="This address is already in use" background></sonic-alert>
+    <sonic-alert status="error" label="Gate change" text="CN 001 now departs from gate B12" background></sonic-alert>
   </template>
 </sonic-code>
 
 ## Status
 
+Color and icon follow `status`. With no `status`, behavior is `default`.
+
 <sonic-code>
   <template>
-  <div class="grid gap-4">
-  <sonic-alert label="Default"> This address is already in use. </sonic-alert>
-  <sonic-alert status="success" label="Success"> This address is already in use. </sonic-alert>
-  <sonic-alert status="error" label="Error"> This address is already in use. </sonic-alert>
-  <sonic-alert status="warning" label="Warning"> This address is already in use. </sonic-alert>
-  <sonic-alert status="info" label="Info"> This address is already in use. </sonic-alert>
-  </div>
+    <div class="grid gap-4">
+      <sonic-alert label="Default">CN 001 · CDG → JFK.</sonic-alert>
+      <sonic-alert status="success" label="Success">CN 001 has landed at JFK.</sonic-alert>
+      <sonic-alert status="error" label="Error">CN 001 is cancelled.</sonic-alert>
+      <sonic-alert status="warning" label="Warning">Turbulence expected over the Atlantic.</sonic-alert>
+      <sonic-alert status="info" label="Info">Boarding starts in 20 minutes.</sonic-alert>
+    </div>
   </template>
 </sonic-code>
 
-## Sizes
+## Accessibility (`announce`)
+
+By default, an alert already in the DOM is **not** announced (no `role` / `aria-live`). Set **`announce`** when the message appears **after** user action (API response, validation, etc.): screen readers get `role="alert"` for `error`, otherwise `role="status"` and `aria-live="polite"`.
+
+`sonic-alert-messages` sets `announce` on every rendered alert.
 
 <sonic-code>
   <template>
-  <div class="grid gap-4">
-  <sonic-alert status="error" label="Email error" size="2xs">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  <sonic-alert status="error" label="Email error" size="xs">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  <sonic-alert status="error" label="Email error" size="sm">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  <sonic-alert status="error" label="Email error">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  <sonic-alert status="error" label="Email error" size="lg">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  <sonic-alert status="error" label="Email error" size="xl">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  <sonic-alert status="error" label="Email error" size="2xl">
-    This address is already in use. Lorem ipsum dolor sit amet.
-  </sonic-alert>
-  </div>
+    <sonic-alert announce status="success" label="Checked in" text="Your boarding pass is ready."></sonic-alert>
   </template>
 </sonic-code>
 
-## Alert with link
+## Content and icon
+
+`label` and `text` accept plain text only. The default slot is rendered after `text`. Use the **`icon`** slot to replace the default `sonic-icon`. **`noIcon`** hides the icon.
 
 <sonic-code>
   <template>
-  <sonic-alert status="info" label="New messages !">
-    You have 2 unread messages<br />
-    <div class="flex gap-2 mt-1">
-      <sonic-button variant="outline" type="info" size="xs">See messages</sonic-button>
-      <sonic-button variant="ghost" type="info" size="xs">dismiss</sonic-button>
+    <sonic-alert status="info" noIcon label="No icon" text="Cruising altitude reached."></sonic-alert>
+  </template>
+</sonic-code>
+
+## Custom icon slot
+
+Project any markup into **`slot="icon"`** (icon, image, custom component). Keep it decorative with `aria-hidden="true"` when the message text already conveys meaning.
+
+<sonic-code>
+  <template>
+    <sonic-alert status="success" label="Upgrade confirmed" background>
+      <sonic-icon slot="icon" library="iconoir" name="trophy" aria-hidden="true"></sonic-icon>
+      You are now seated in first class.
+    </sonic-alert>
+  </template>
+</sonic-code>
+
+## Size
+
+Default size is `md` (omit the `size` attribute). `inherit` follows the parent font size.
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4">
+      <sonic-alert status="error" label="Delayed" size="2xs">
+        CN 001 departure moved to 18:40.
+      </sonic-alert>
+      <sonic-alert status="error" label="Delayed" size="xs">
+        CN 001 departure moved to 18:40.
+      </sonic-alert>
+      <sonic-alert status="error" label="Delayed" size="sm">
+        CN 001 departure moved to 18:40.
+      </sonic-alert>
+      <sonic-alert status="error" label="Delayed">
+        CN 001 departure moved to 18:40.
+      </sonic-alert>
+      <sonic-alert status="error" label="Delayed" size="lg">
+        CN 001 departure moved to 18:40.
+      </sonic-alert>
+      <sonic-alert status="error" label="Delayed" size="xl">
+        CN 001 departure moved to 18:40.
+      </sonic-alert>
+      <sonic-alert status="error" label="Delayed" size="2xl">
+        CN 001 departure moved to 18:40.
+      </sonic-alert>
     </div>
-  </sonic-alert>
+  </template>
+</sonic-code>
+
+## Alert with link
+
+Rich content in the slot (buttons, links).
+
+<sonic-code>
+  <template>
+    <sonic-alert status="info" label="Gate change">
+      CN 001 now departs from gate B12<br />
+      <div class="flex gap-2 mt-1">
+        <sonic-button variant="outline" type="info" size="xs">View flight</sonic-button>
+        <sonic-button variant="ghost" type="info" size="xs">Dismiss</sonic-button>
+      </div>
+    </sonic-alert>
   </template>
 </sonic-code>
 
 ## Background
 
+Tinted background from the `status` color (`color-mix` on `currentColor`).
+
 <sonic-code>
   <template>
-  <div class="grid gap-4">
-  <sonic-alert background label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="success" background label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="error" background label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="warning" background label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="info" background label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  </div>
+    <div class="grid gap-4">
+      <sonic-alert background label="Flight update">Boarding is now open at gate B12.</sonic-alert>
+      <sonic-alert status="success" background label="Flight update">
+        Boarding is now open at gate B12.
+      </sonic-alert>
+      <sonic-alert status="error" background label="Flight update">
+        Boarding is now open at gate B12.
+      </sonic-alert>
+      <sonic-alert status="warning" background label="Flight update">
+        Boarding is now open at gate B12.
+      </sonic-alert>
+      <sonic-alert status="info" background label="Flight update">
+        Boarding is now open at gate B12.
+      </sonic-alert>
+    </div>
   </template>
 </sonic-code>
 
 ## Dismissible
 
+`dismissible` removes the alert from the DOM when the close control is clicked (i18n aria label). **`dismissible`** and **`background`** are independent: without `background`, close sits at the end of the row; with `background`, top-right.
+
 <sonic-code>
   <template>
-  <sonic-alert class="mb-3" dismissible label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="success" class="mb-3" dismissible label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="error" class="mb-3" dismissible label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="warning" class="mb-3" dismissible label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
-  <sonic-alert status="info" class="mb-3" dismissible label="Lorem ipsum dolor">
-    This address is already in use.
-  </sonic-alert>
+    <sonic-alert status="info" class="mb-3" dismissible label="Baggage claim moved to belt 4.">
+    </sonic-alert>
+    <sonic-alert class="mb-3" dismissible background label="Flight update">
+      Boarding is now open at gate B12.
+    </sonic-alert>
   </template>
 </sonic-code>
 
 ## Dismiss forever
 
+With **`dismissForever`**, dismissal is stored in `localStorage` (key `sonic-alert-dismissed`). A stable **`id`** on the element is **required**; without `id`, a warning is logged and nothing is persisted.
+
 <sonic-code>
   <template>
-  <sonic-alert class="mb-3" dismissible dismissForever label="Lorem ipsum dolor" id="addressUniqueId">
-    This address is already in use.
-  </sonic-alert>
+    <sonic-alert
+      class="mb-3"
+      dismissible
+      background
+      dismissForever
+      label="Flight update"
+      id="addressUniqueId"
+    >
+      Boarding is now open at gate B12.
+    </sonic-alert>
   </template>
 </sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `status` | `default` (default) · `info` · `success` · `warning` · `error` | Color and default icon |
+| `label` | string | Title (plain text) |
+| `text` | string | Short body (plain text), rendered before the slot |
+| `size` | `2xs` … `2xl` (default `md`) · `inherit` | Corner radius and typography |
+| `background` | boolean | Tinted background (`color-mix` on status color) |
+| `dismissible` | boolean | Close control; removes the element from the DOM |
+| `dismissForever` | boolean | Persists dismissal in `localStorage`; requires **`id`** |
+| `noIcon` | boolean | Hides the icon (including custom `icon` slot content) |
+| `announce` | boolean | `role="alert"` / `aria-live` for dynamically injected content |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Message body (HTML, actions); rendered after `text` |
+| `icon` | Replaces the default `sonic-icon` |

package/docs/src/core/components/ui/alert-messages/alert-messages.md

@@ -0,0 +1,85 @@
+# Alert messages
+
+**`sonic-alert-messages`** renders a vertical stack of **`sonic-alert`** items from a **`messages`** array on a linked **data provider** (typical pattern: **`submitResultDataProvider`** after a form submit). Only entries with **`type="public"`** are shown. Each alert gets **`announce`** so screen readers pick up feedback after the request.
+
+## With submit result
+
+Bind **`dataProvider`** to the same publisher as **`submitResultDataProvider`**. API **`messages`** entries need **`type`**: **`public`**, plus **`content`** and optional **`status`** (`warning` · `success` · `error` · `info`).
+
+<sonic-code>
+  <template>
+    <sonic-scope
+      serviceURL="/docs-mock-api"
+      formDataProvider="submit-example"
+      submitResultDataProvider="submit-example-result"
+    >
+      <sonic-alert-messages dataProvider="submit-example-result" background class="mb-4"></sonic-alert-messages>
+      <div class="grid gap-4 max-w-md">
+        <sonic-input name="email" type="email" label="Email" value=""></sonic-input>
+        <sonic-input name="password" type="password" label="Password" value=""></sonic-input>
+        <sonic-submit endPoint="api/register" onClick>
+          <sonic-button type="primary">Submit (empty fields → error messages)</sonic-button>
+        </sonic-submit>
+      </div>
+    </sonic-scope>
+  </template>
+</sonic-code>
+
+## Shared alert props
+
+**`size`** · **`background`** and **`noIcon`** apply to every rendered **`sonic-alert`** in the list.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      size="sm"
+      variant="outline"
+      class="mb-3"
+      onclick="SonicPublisherManager.get('submit-example-result').set({ messages: [{ type: 'public', content: 'Compact inline feedback without icons.', status: 'info' }] })"
+    >
+      Load sample messages
+    </sonic-button>
+    <sonic-alert-messages
+      dataProvider="submit-example-result"
+      size="sm"
+      background
+      noIcon
+    ></sonic-alert-messages>
+  </template>
+</sonic-code>
+
+## Message shape
+
+Example JSON on the result publisher (or API response merged into it):
+
+<sonic-code language="typescript">
+  <template>
+{
+  "messages": [
+    {
+      "type": "public",
+      "content": "The product has been added to your cart",
+      "status": "success"
+    }
+  ]
+}
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `dataProvider` | publisher id | Source object; **`messages`** array is auto-filled via **Subscriber** |
+| `size` | `2xs` … `2xl` (default `md`) | Passed to each **`sonic-alert`** |
+| `background` | boolean | Tinted background on each alert |
+| `noIcon` | boolean | Hides icons on each alert |
+| `messages` | `Message[]` | Usually set by the publisher; each item uses **`content`** as alert **`text`** |
+
+| Message field | Values | Description |
+|---------------|---------|-------------|
+| `type` | `public` | Required for the message to render |
+| `content` | string | Alert body (**`text`** on **`sonic-alert`**) |
+| `status` | `warning` · `success` · `error` · `info` | Alert **`status`**; defaults to **`default`** when omitted |
+
+No slots — alerts are generated from **`messages`**.

package/docs/src/core/components/ui/badge/badge.md

@@ -1,127 +1,181 @@
 # Badge
 
+Badges are **compact, non-interactive** labels for status, counts, or categories. They mirror **`sonic-button`** styling (`type`, `variant`, `size`) without focus rings or click handling—use a button when the control should be actionable.
+
 ## Type
+
+`default` — subtle background (`base-100`). `neutral` — dark fill (`base-content`) with light text, useful on light backgrounds.
+
 <sonic-code>
   <template>
-  <sonic-badge>Default</sonic-badge>
-  <sonic-badge type="primary">Primary</sonic-badge>
-  <sonic-badge type="neutral">Neutral</sonic-badge>
-  <sonic-badge type="warning">Warning</sonic-badge>
-  <sonic-badge type="info">Info</sonic-badge>
-  <sonic-badge type="success">Success</sonic-badge>
-  <sonic-badge type="danger">Danger</sonic-badge>
-  <sonic-badge type="contrast">Contrast</sonic-badge>
+    <div class="flex flex-wrap gap-2">
+      <sonic-badge>Default</sonic-badge>
+      <sonic-badge type="primary">Primary</sonic-badge>
+      <sonic-badge type="neutral">Neutral</sonic-badge>
+      <sonic-badge type="warning">Warning</sonic-badge>
+      <sonic-badge type="info">Info</sonic-badge>
+      <sonic-badge type="success">Success</sonic-badge>
+      <sonic-badge type="danger">Danger</sonic-badge>
+    </div>
   </template>
 </sonic-code>
 
+## Variant
+
+Default **`variant`** is filled. **`outline`** — border and text in the `type` color. **`ghost`** — text only, no padding (except in forced-colors mode).
 
-## Outline
 <sonic-code>
   <template>
-  <div class="flex items-center flex-wrap gap-3">
-    <sonic-badge variant="outline">Default</sonic-badge>
-    <sonic-badge variant="outline" type="primary">Primary</sonic-badge>
-    <sonic-badge variant="outline" type="neutral">Neutral</sonic-badge>
-    <sonic-badge variant="outline" type="warning">Warning</sonic-badge>
-    <sonic-badge variant="outline" type="info">Info</sonic-badge>
-    <sonic-badge variant="outline" type="success">Success</sonic-badge>
-    <sonic-badge variant="outline" type="danger">Danger</sonic-badge>
-    <sonic-badge variant="outline" type="contrast">Contrast</sonic-badge>
-  </div>
+    <div class="grid gap-3">
+      <div class="flex items-center flex-wrap gap-3">
+        <sonic-badge variant="outline">Default</sonic-badge>
+        <sonic-badge variant="outline" type="primary">Primary</sonic-badge>
+        <sonic-badge variant="outline" type="neutral">Neutral</sonic-badge>
+        <sonic-badge variant="outline" type="warning">Warning</sonic-badge>
+        <sonic-badge variant="outline" type="info">Info</sonic-badge>
+        <sonic-badge variant="outline" type="success">Success</sonic-badge>
+        <sonic-badge variant="outline" type="danger">Danger</sonic-badge>
+      </div>
+      <div class="flex items-center flex-wrap gap-3">
+        <sonic-badge variant="ghost">Default</sonic-badge>
+        <sonic-badge variant="ghost" type="primary">Primary</sonic-badge>
+        <sonic-badge variant="ghost" type="neutral">Neutral</sonic-badge>
+        <sonic-badge variant="ghost" type="warning">Warning</sonic-badge>
+        <sonic-badge variant="ghost" type="info">Info</sonic-badge>
+        <sonic-badge variant="ghost" type="success">Success</sonic-badge>
+        <sonic-badge variant="ghost" type="danger">Danger</sonic-badge>
+      </div>
+    </div>
   </template>
 </sonic-code>
 
-## Ghost
+## Size
+
+Default size is `md` (omit the `size` attribute). Typography and padding follow `sonic-button`.
+
 <sonic-code>
   <template>
-    <div class="flex items-center flex-wrap gap-3">
-    <sonic-badge variant="ghost">Default</sonic-badge>
-    <sonic-badge variant="ghost" type="primary">Primary</sonic-badge>
-    <sonic-badge variant="ghost" type="neutral">Neutral</sonic-badge>
-    <sonic-badge variant="ghost" type="warning">Warning</sonic-badge>
-    <sonic-badge variant="ghost" type="info">Info</sonic-badge>
-    <sonic-badge variant="ghost" type="success">Success</sonic-badge>
-    <sonic-badge variant="ghost" type="danger">Danger</sonic-badge>
-    <sonic-badge variant="ghost" type="contrast">Contrast</sonic-badge>
-  </div>
+    <div class="flex flex-wrap items-center gap-2">
+      <sonic-badge size="2xs">2Xs</sonic-badge>
+      <sonic-badge size="xs">Xs</sonic-badge>
+      <sonic-badge size="sm">Sm</sonic-badge>
+      <sonic-badge>Md</sonic-badge>
+      <sonic-badge size="lg">Lg</sonic-badge>
+      <sonic-badge size="xl">Xl</sonic-badge>
+      <sonic-badge size="2xl">2Xl</sonic-badge>
+    </div>
   </template>
 </sonic-code>
 
-## Size
+## Prefix and suffix slots
+
+Icons or short text before / after the main label.
+
 <sonic-code>
   <template>
-  <sonic-badge size="2xs">2Xs badge</sonic-badge>
-  <sonic-badge size="xs">Xs badge</sonic-badge>
-  <sonic-badge size="sm">Sm badge</sonic-badge>
-  <sonic-badge>Md badge</sonic-badge>
-  <sonic-badge size="lg">Lg badge</sonic-badge>
-  <sonic-badge size="xl">Xl badge</sonic-badge>
-  <sonic-badge size="2xl">2Xl badge</sonic-badge>
+    <sonic-badge type="info" size="sm">
+      <sonic-icon slot="prefix" name="airplane" library="iconoir"></sonic-icon>
+      Boarding
+    </sonic-badge>
+    <sonic-badge type="success">
+      Landed
+      <sonic-icon slot="suffix" name="check" library="iconoir"></sonic-icon>
+    </sonic-badge>
   </template>
 </sonic-code>
 
-
 ## Empty badges
+
+Badge with no text (visual dot). `min-width` / `min-height` keep a readable shape.
+
 <sonic-code>
   <template>
-  <div class="flex items-center flex-wrap gap-3">
-    <sonic-badge type="danger" size="2xs"></sonic-badge>
-    <sonic-badge type="danger" size="xs"></sonic-badge>
-    <sonic-badge type="danger" size="sm"></sonic-badge>
-    <sonic-badge type="danger"></sonic-badge>
-    <sonic-badge type="danger" size="lg"></sonic-badge>
-    <sonic-badge type="danger" size="xl"></sonic-badge>
-    <sonic-badge type="danger" size="2xl"></sonic-badge>
-  </div>
+    <div class="flex items-center flex-wrap gap-3">
+      <sonic-badge type="danger" size="2xs"></sonic-badge>
+      <sonic-badge type="danger" size="xs"></sonic-badge>
+      <sonic-badge type="danger" size="sm"></sonic-badge>
+      <sonic-badge type="danger"></sonic-badge>
+      <sonic-badge type="danger" size="lg"></sonic-badge>
+      <sonic-badge type="danger" size="xl"></sonic-badge>
+      <sonic-badge type="danger" size="2xl"></sonic-badge>
+    </div>
   </template>
 </sonic-code>
 
-
 ## Ellipsis
+
+With `ellipsis`, long labels truncate. The parent must constrain width (`max-width`, grid, etc.).
+
 <sonic-code>
   <template>
-    <div class="grid grid-cols-3 gap-4" >
-        <sonic-badge ellipsis size="sm" variant="outline"  >
-        <sonic-icon slot="prefix" name="info-empty" library="iconoir"></sonic-icon> Lorem ipsum dolor sit consectetur adipiscing elit. Lorem ipsum dolor sit consectetur adipiscing elit.</sonic-badge>
-        <sonic-badge ellipsis size="sm" > <sonic-icon slot="prefix" name="info-empty" library="iconoir"></sonic-icon> Lorem ipsum dolor sit consectetur adipiscing elit. Lorem ipsum dolor sit consectetur adipiscing elit.</sonic-badge>
+    <div class="grid grid-cols-2 gap-4 max-w-xl">
+      <sonic-badge ellipsis size="sm" variant="outline">
+        <sonic-icon slot="prefix" name="info-empty" library="iconoir"></sonic-icon>
+        CN 001 · CDG → JFK · Gate change: now boarding at gate B12, terminal 2E
+      </sonic-badge>
+      <sonic-badge ellipsis size="sm">
+        <sonic-icon slot="prefix" name="info-empty" library="iconoir"></sonic-icon>
+        CN 001 · CDG → JFK · Gate change: now boarding at gate B12, terminal 2E
+      </sonic-badge>
     </div>
   </template>
 </sonic-code>
 
 ## Badge in button
+
+Count inside a button (`slot="suffix"`) or a badge absolutely positioned on a button / icon.
+
 <sonic-code>
   <template>
-  <div class="flex flex-wrap gap-4 items-center">
-    <sonic-button type="default">
-      Messages <sonic-badge slot="suffix" type="danger" size="xs">5</sonic-badge>
-    </sonic-button>
-    <div class="relative inline-block">
-      <sonic-button type="success" class="relative"> Mon compte </sonic-button>
-      <sonic-badge type="danger" size="xs" class="absolute right-1 top-0 pe-none transform -translate-y-1/2"
-        >12</sonic-badge
-      >
-    </div>
-    <div class="relative inline-block">
-      <sonic-button type="neutral" shape="circle" variant="outline"
-        ><sonic-icon library="iconoir" name="user"></sonic-icon>
-      </sonic-button>
-      <sonic-badge
-        type="danger"
-        size="xs"
-        class="absolute right-1 bottom-1 pe-none transform translate-y-1/2 translate-x-1/2"
-        >33</sonic-badge
-      >
-    </div>
-    <div class="relative inline-block">
-      <sonic-button type="neutral" shape="circle" variant="outline"
-        ><sonic-icon library="iconoir" name="user"></sonic-icon>
+    <div class="flex flex-wrap gap-4 items-center">
+      <sonic-button type="default">
+        Departures <sonic-badge slot="suffix" type="danger" size="xs">5</sonic-badge>
       </sonic-button>
-      <sonic-badge
-        type="danger"
-        size="xs"
-        class="absolute right-2 bottom-2 pe-none transform translate-y-1/2 translate-x-1/2"
-      ></sonic-badge>
+      <div class="relative inline-block">
+        <sonic-button type="success" class="relative">Crew</sonic-button>
+        <sonic-badge
+          type="danger"
+          size="xs"
+          class="absolute right-1 top-0 pe-none transform -translate-y-1/2"
+          >12</sonic-badge
+        >
+      </div>
+      <div class="relative inline-block">
+        <sonic-button type="neutral" shape="circle" variant="outline">
+          <sonic-icon library="iconoir" name="user"></sonic-icon>
+        </sonic-button>
+        <sonic-badge
+          type="danger"
+          size="xs"
+          class="absolute right-1 bottom-1 pe-none transform translate-y-1/2 translate-x-1/2"
+          >33</sonic-badge
+        >
+      </div>
+      <div class="relative inline-block">
+        <sonic-button type="neutral" shape="circle" variant="outline">
+          <sonic-icon library="iconoir" name="user"></sonic-icon>
+        </sonic-button>
+        <sonic-badge
+          type="danger"
+          size="xs"
+          class="absolute right-2 bottom-2 pe-none transform translate-y-1/2 translate-x-1/2"
+        ></sonic-badge>
+      </div>
     </div>
-  </div>
   </template>
 </sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `type` | `default` (default) · `primary` · `neutral` · `warning` · `info` · `success` · `danger` | Semantic color (`--sc-*` tokens) |
+| `variant` | `default` (default) · `outline` · `ghost` | Filled, bordered, or text-only |
+| `size` | `2xs` … `2xl` (default `md`) · `inherit` | Typography and padding (aligned with **`sonic-button`**) |
+| `ellipsis` | boolean | Single-line truncation; parent must constrain width |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Main label |
+| `prefix` | Icon or short text before the label |
+| `suffix` | Icon or short text after the label |