@supersoniks/concorde 5.0.4 → 5.0.5

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

@@ -1,127 +1,188 @@
 # 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
 
-## 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="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>
   </template>
 </sonic-code>
 
-## Ghost
+### Ghost
+
 <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>
+      <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>
   </template>
 </sonic-code>
 
 ## Size
+
+Default size is `md` (omit the `size` attribute). Typography and padding follow `sonic-button`.
+
 <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>
+    <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>
 
+## Prefix and suffix slots
+
+Icons or short text before / after the main label.
 
-## Empty badges
 <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>
+    <sonic-badge type="info" size="sm">
+      <sonic-icon slot="prefix" name="info-empty" library="iconoir"></sonic-icon>
+      Info
+    </sonic-badge>
+    <sonic-badge type="success">
+      Verified
+      <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>
+  </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>
+        Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod.
+      </sonic-badge>
+      <sonic-badge ellipsis size="sm">
+        <sonic-icon slot="prefix" name="info-empty" library="iconoir"></sonic-icon>
+        Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod.
+      </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">
+        Messages <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">My account</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`) | 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 |

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

@@ -71,6 +71,7 @@ The length of the button depends on the size of its content
   <template>
     <sonic-button loading></sonic-button>
     <sonic-button loading>Loading button</sonic-button>
+    <sonic-button loading><span slot="prefix">🚀</span>Loading with prefix<span slot="suffix">😂</span></sonic-button>
   </template>
 </sonic-code>
 

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

@@ -1,12 +1,71 @@
 # Captcha
 
+**`sonic-captcha`** embeds an **ALTCHA** widget and wires **`captchaToken`** / **`needsCaptchaValidation`** on the ancestor **`formDataProvider`** (or **`headersDataProvider`**). **`sonic-submit`** waits for a token before sending when validation is required. The widget loads only on **HTTPS**; on plain HTTP the host renders nothing.
+
+> Live widget calls the Supersoniks challenge service — not part of [docs mock API](#docs/_misc/docs-mock-api.md/docs-mock-api).
+
+## Basic example
+
+Wrap the form scope and place **`sonic-submit`** in the default slot so the challenge appears above the action.
+
+<sonic-code>
+  <template>
+    <sonic-scope
+      serviceURL="/docs-mock-api"
+      formDataProvider="captcha-docs-form"
+      submitResultDataProvider="captcha-docs-result"
+    >
+      <sonic-captcha formDataProvider="captcha-docs-form">
+        <sonic-input class="mb-3" name="email" type="email" label="Email" value="demo@example.com"></sonic-input>
+        <sonic-submit endPoint="api/register" onClick>
+          <sonic-button type="primary">Submit with captcha</sonic-button>
+        </sonic-submit>
+      </sonic-captcha>
+    </sonic-scope>
+  </template>
+</sonic-code>
+
+## Encrypted site key
+
+Optional **`key`** skips client-side key generation. When omitted, the component derives an encrypted key on connect (after **`generateEncryptedKey`**).
+
 <sonic-code>
   <template>
-  <sonic-captcha formDataProvider="captchaTestDataProvider" key="6Leq5V0iAAAAAB-41DlWN335jDlcIuXmhNtdd00t">
-    <sonic-submit serviceURL="/docs-mock-api" endPoint="api/unknown" onclick>
-      <sonic-button  class="mt-4">Submit with captcha</sonic-button>
-    </sonic-submit>
-  </sonic-captcha>
+    <sonic-captcha formDataProvider="captcha-docs-form" key="6Leq5V0iAAAAAB-41DlWN335jDlcIuXmhNtdd00t">
+      <sonic-button type="outline" disabled>Complete the challenge above to enable submit</sonic-button>
+    </sonic-captcha>
   </template>
 </sonic-code>
-                
+
+## Form publisher fields
+
+On connect (HTTPS only), **`needsCaptchaValidation`** is set to **`true`** and **`captchaToken`** is cleared. When the ALTCHA widget reaches **`verified`**, **`captchaToken`** is written on the form publisher and **`sonic-captcha-validate`** fires (`detail.valid` · **`detail.state`** · optional **`detail.token`** / **`detail.payload`**). **`sonic-submit`** still listens for **`request_token`** to refresh the token immediately before send.
+
+<sonic-code language="typescript">
+  <template>
+{
+  needsCaptchaValidation: true,
+  captchaKey: "…",
+  captchaToken: "…"
+}
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `formDataProvider` | publisher id | Same as ancestor form scope; reads/writes **`needsCaptchaValidation`** · **`captchaKey`** · **`captchaToken`** |
+| `key` | string | ALTCHA site key; auto-generated when empty |
+| `action` | string | Optional action name forwarded to the widget |
+| `zIndex` | number (default `9999`) | Stacking for the challenge overlay |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Form actions (typically **`sonic-submit`** and fields) rendered below the widget |
+
+| Event | Description |
+|-------|-------------|
+| `sonic-captcha-validate` | Fired when **`state`** is **`verified`** · **`error`** or **`expired`**; **`detail.valid`** is **`true`** only for **`verified`** |
+
+Related: [Submit](#core/components/functional/submit/submit.md/submit) — **`needsCaptchaValidation`** and deferred send.

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

@@ -1,97 +1,215 @@
 # Card
 
+Cards **group related content** on a padded surface with radius, theme **`type`** colors, and elevation. Default **`shadow`** is `lg`. Compose **`sonic-card-header`** / **`sonic-card-main`** / **`sonic-card-footer`**, or place any markup in the default slot.
+
+## Basic example
+
+<sonic-code>
+  <template>
+    <sonic-card class="max-w-sm">
+      <p class="m-0">Related content on a raised surface.</p>
+    </sonic-card>
+  </template>
+</sonic-code>
+
 ## Type
+
+Default **`type`** is `base`. **`default`** and **`light`** share the same surface tokens.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-3">
+      <sonic-card type="base" class="min-w-[8rem]">Base</sonic-card>
+      <sonic-card type="light" class="min-w-[8rem]">Light</sonic-card>
+      <sonic-card type="default" class="min-w-[8rem]">Default</sonic-card>
+      <sonic-card type="primary" class="min-w-[8rem]">Primary</sonic-card>
+      <sonic-card type="info" class="min-w-[8rem]">Info</sonic-card>
+      <sonic-card type="success" class="min-w-[8rem]">Success</sonic-card>
+      <sonic-card type="warning" class="min-w-[8rem]">Warning</sonic-card>
+      <sonic-card type="danger" class="min-w-[8rem]">Danger</sonic-card>
+      <sonic-card type="neutral" class="min-w-[8rem]">Neutral</sonic-card>
+      <sonic-card type="invert" class="min-w-[8rem]">Invert</sonic-card>
+    </div>
+  </template>
+</sonic-code>
+
+## Shadow
+
+Set **`shadow`** to control elevation. Default is `lg`.
+
 <sonic-code>
   <template>
-  <div class="grid grid-cols-3 gap-3">
-    <sonic-card type="base">Base</sonic-card>
-    <sonic-card type="light">Light</sonic-card>
-    <sonic-card type="primary">Primary</sonic-card>
-    <sonic-card type="warning">Warning</sonic-card>
-    <sonic-card type="danger">Danger</sonic-card>
-    <sonic-card type="success">Success</sonic-card>
-    <sonic-card type="info">Info</sonic-card>
-    <sonic-card type="neutral">Neutral</sonic-card>
-    <sonic-card type="invert">Invert</sonic-card>
-  </div>
+    <div class="grid gap-4 sm:grid-cols-2 max-w-2xl">
+      <sonic-card shadow="none" class="min-h-[5rem] flex items-center justify-center">None</sonic-card>
+      <sonic-card shadow="sm" class="min-h-[5rem] flex items-center justify-center">Small</sonic-card>
+      <sonic-card shadow="md" class="min-h-[5rem] flex items-center justify-center">Medium</sonic-card>
+      <sonic-card shadow="lg" class="min-h-[5rem] flex items-center justify-center">Large</sonic-card>
+    </div>
   </template>
 </sonic-code>
 
 ## Header
+
+Quick titles with **`label`** and **`description`**, or full control through the default slot. **`slot="suffix"`** aligns badges or actions on the right; suffix content does not shrink when the title wraps.
+
+`label` and `description` accept HTML (rendered as markup). Prefer plain text when possible; use **`sonic-card-header-description`** or the default slot for structured content.
+
 <sonic-code>
   <template>
-  <div class="grid grid-cols-1 gap-3">
-    <sonic-card >
-      <sonic-card-header label="Header simple, titre géré via l'attribut : label" description="Description via l'attribut : description">
-      </sonic-card-header>
-    </sonic-card>
-    <sonic-card type="neutral">
-      <sonic-card-header label="Header composé">
-        <sonic-card-header-description>Description rendu via le composant : "sonic-card-header-description"</sonic-card-header-description>
-        <div  slot="suffix" class="flex">
-          Suffix
-        </div>
-      </sonic-card-header>
-    </sonic-card>
-    <sonic-card type="invert">
-      <sonic-card-header>
-        <div>Header custom</div>
-        <div class="text-lg text-danger">Tout le contenu excepté l'icône ✈ passe par le slot du header</div>
-        <span slot="suffix" >✈</span>
-      </sonic-card-header>
-    </sonic-card>
-  </div>
+    <div class="grid gap-4 max-w-xl">
+      <sonic-card>
+        <sonic-card-header
+          label="Account settings"
+          description="Manage your profile and preferences."
+        ></sonic-card-header>
+        <p class="m-0 text-sm opacity-80">Body content goes in the card slot or in <code>sonic-card-main</code>.</p>
+      </sonic-card>
+
+      <sonic-card type="neutral">
+        <sonic-card-header label="Notifications">
+          <sonic-card-header-description>
+            Choose what we email you about.
+          </sonic-card-header-description>
+          <sonic-badge slot="suffix" type="warning" size="xs">3 new</sonic-badge>
+        </sonic-card-header>
+      </sonic-card>
+
+      <sonic-card>
+        <sonic-card-header label="Team workspace" description="Shared with 12 members">
+          <sonic-button
+            slot="suffix"
+            shape="circle"
+            variant="outline"
+            size="sm"
+            type="default"
+            icon
+            data-aria-label="Workspace settings"
+          >
+            <sonic-icon library="iconoir" name="settings"></sonic-icon>
+          </sonic-button>
+        </sonic-card-header>
+      </sonic-card>
+
+      <sonic-card type="primary">
+        <sonic-card-header>
+          <div>Custom header</div>
+          <sonic-card-header-description>
+            Use the header slot when attributes are not enough.
+          </sonic-card-header-description>
+          <sonic-button slot="suffix" shape="circle" variant="ghost" size="sm" type="primary" icon>
+            <sonic-icon library="iconoir" name="nav-arrow-right"></sonic-icon>
+          </sonic-button>
+        </sonic-card-header>
+      </sonic-card>
+    </div>
   </template>
 </sonic-code>
 
 ## Main
+
+Optional wrapper for the primary content area (typography, media, forms).
+
 <sonic-code>
   <template>
-  <sonic-card >
-    <sonic-card-main >
-      <h3>Main area</h3>
-      <p>Lorem ipsum dolor sit, amet consectetur adipisicing elit. Iure id dolor debitis deleniti eligendi natus dolorem a commodi sunt dicta? Ipsa asperiores magni consequuntur dolor voluptatibus. Maxime, nemo? Facere, odio.</p>
-      <iframe width="560" height="315" src="https://www.youtube.com/embed/aqz-KE-bpKQ" title="Big Buck Bunny (Blender Foundation)" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
-    </sonic-card-main>
-  </sonic-card>
+    <sonic-card class="max-w-xl">
+      <sonic-card-header label="Release notes" description="Version 2.4"></sonic-card-header>
+      <sonic-card-main>
+        <p class="mt-0">
+          Improved performance on large lists and fixed an issue with keyboard navigation in menus.
+        </p>
+        <sonic-divider></sonic-divider>
+        <p class="mb-0 text-sm opacity-80">See the changelog for details.</p>
+      </sonic-card-main>
+    </sonic-card>
   </template>
 </sonic-code>
 
 ## Footer
+
+Optional footer for actions, metadata, or secondary text.
+
 <sonic-code>
   <template>
-  <sonic-card >
-    <sonic-card-footer >
-      <div >
-        <h4 class="mb-0">Footer area</h4>
-        <small>Debitis deleniti eligendi natus dolorem aufdh.</small>
-        <div>
-          🛫 ✈ ✈ ✈ ✈ ✈ 🛬
+    <sonic-card class="max-w-xl">
+      <sonic-card-header label="Confirm deletion"></sonic-card-header>
+      <sonic-card-main>
+        <p class="m-0">This project and all of its data will be removed permanently.</p>
+      </sonic-card-main>
+      <sonic-card-footer>
+        <sonic-divider></sonic-divider>
+        <div class="flex flex-wrap gap-2 justify-end">
+          <sonic-button variant="ghost" size="sm">Cancel</sonic-button>
+          <sonic-button type="danger" size="sm">Delete</sonic-button>
         </div>
-      </div>
-    </sonic-card-footer>
-  </sonic-card>
+      </sonic-card-footer>
+    </sonic-card>
   </template>
 </sonic-code>
 
+## Full example
+
+Header, media, body, and footer together.
 
-## Example of use
 <sonic-code>
   <template>
-  <sonic-card >
-    <sonic-card-header label="Header" description="Header description">
-      <sonic-icon library="iconoir" name="nav-arrow-right" slot="suffix" ></sonic-icon>
-    </sonic-card-header>
-    <sonic-card-main >
-      <sonic-image rounded ratio="11/4" src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg">
-      </sonic-image>
-      <p><b>Main</b> - Lorem ipsum dolor sit, amet consectetur adipisicing elit. Iure id dolor debitis deleniti eligendi natus dolorem a commodi sunt dicta? Ipsa asperiores magni consequuntur dolor voluptatibus. Maxime, nemo? Facere, odio.</p>
-    </sonic-card-main>
-    <sonic-card-footer>
-      <div>
-        <i>Footer</i> - Amet consectetur adipisicing
-      </div>
-    </sonic-card-footer>
-  </sonic-card>
+    <sonic-card class="max-w-md">
+      <sonic-card-header label="Featured route" description="San Francisco → New York">
+        <sonic-icon slot="suffix" library="iconoir" name="airplane" aria-hidden="true"></sonic-icon>
+      </sonic-card-header>
+      <sonic-card-main>
+        <sonic-image
+          rounded
+          ratio="16/9"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+          alt="Airplane wing above the clouds"
+        ></sonic-image>
+        <p class="mb-0">
+          Nonstop flight with flexible dates. Prices shown include taxes and fees.
+        </p>
+      </sonic-card-main>
+      <sonic-card-footer>
+        <div class="flex items-center justify-between gap-3 flex-wrap">
+          <span class="text-sm font-semibold">From $249</span>
+          <sonic-button type="primary" size="sm">Book</sonic-button>
+        </div>
+      </sonic-card-footer>
+    </sonic-card>
   </template>
 </sonic-code>
+
+## API reference
+
+### `sonic-card`
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `type` | `base` (default) · `light` · `invert` · `default` · `primary` · `warning` · `danger` · `success` · `info` · `neutral` | Semantic background and text (`default` and `light` share the same surface) |
+| `shadow` | `none` · `sm` · `md` · `lg` (default `lg`) | Elevation on the card surface |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Free-form content (header, main, footer, or direct markup) |
+
+### `sonic-card-header`
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `label` | HTML | Title (rendered as markup) |
+| `description` | HTML | Subtitle below the title |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Custom title / description when attributes are not enough |
+| `suffix` | Actions or badges aligned on the right (does not shrink) |
+
+### `sonic-card-header-description`
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Subtitle text; styled below the title when slotted in **`sonic-card-header`** |
+
+### `sonic-card-main` · `sonic-card-footer`
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Primary content (`main`) or actions / metadata (`footer`) |