@supersoniks/concorde 5.1.1 → 5.1.3

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

@@ -0,0 +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>
+    <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).
+
+<sonic-code>
+  <template>
+    <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>
+
+## Size
+
+Default size is `md` (omit the `size` attribute). Typography and padding follow `sonic-button`.
+
+<sonic-code>
+  <template>
+    <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.
+
+<sonic-code>
+  <template>
+    <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>
+  </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-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">
+        Departures <sonic-badge slot="suffix" type="danger" size="xs">5</sonic-badge>
+      </sonic-button>
+      <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>
+  </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 |

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

@@ -0,0 +1,216 @@
+# Button
+
+**`sonic-button`** is the clickable control of the library: a plain button, a link when `href` is set, or a form toggle when it has a `name` and `value`. It shares `type` / `variant` / `size` with **`sonic-badge`**, and exposes `prefix` / `suffix` slots for icons.
+
+## Type
+
+With no `type`, the button is `default`. Use `custom` with `--sc-btn-custom-color` and `--sc-btn-custom-bg` for a one-off color.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button>Default</sonic-button>
+      <sonic-button type="primary">Primary</sonic-button>
+      <sonic-button type="neutral">Neutral</sonic-button>
+      <sonic-button type="warning">Warning</sonic-button>
+      <sonic-button type="info">Info</sonic-button>
+      <sonic-button type="success">Success</sonic-button>
+      <sonic-button type="danger">Danger</sonic-button>
+      <sonic-button type="custom" style="--sc-btn-custom-color: #fde68a; --sc-btn-custom-bg: #5b21b6">Custom</sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+## Variant
+
+With no `variant`, the button is filled. The `outline` / `ghost` / `link` variants take their color from `type`. `unstyled` removes all styling so you can apply your own classes.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button type="primary">Default</sonic-button>
+      <sonic-button type="primary" variant="outline">Outline</sonic-button>
+      <sonic-button type="primary" variant="ghost">Ghost</sonic-button>
+      <sonic-button type="primary" variant="link">Link</sonic-button>
+      <sonic-button variant="unstyled">Unstyled</sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+## Size
+
+With no `size`, the button is `md`.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap items-center gap-2">
+      <sonic-button size="2xs">2xs</sonic-button>
+      <sonic-button size="xs">xs</sonic-button>
+      <sonic-button size="sm">sm</sonic-button>
+      <sonic-button>md</sonic-button>
+      <sonic-button size="lg">lg</sonic-button>
+      <sonic-button size="xl">xl</sonic-button>
+      <sonic-button size="2xl">2xl</sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+## Shape
+
+`circle` and `square` make a fixed-size icon button. `block` stretches to the full width of the parent.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap items-center gap-2 mb-2">
+      <sonic-button shape="circle" type="primary"><sonic-icon library="iconoir" name="plus"></sonic-icon></sonic-button>
+      <sonic-button shape="square" type="primary"><sonic-icon library="iconoir" name="plus"></sonic-icon></sonic-button>
+    </div>
+    <sonic-button shape="block" type="primary">Block</sonic-button>
+  </template>
+</sonic-code>
+
+## Prefix and suffix slots
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button type="primary" variant="outline">
+        <sonic-icon library="iconoir" slot="prefix" name="arrow-left"></sonic-icon>
+        Previous flight
+      </sonic-button>
+      <sonic-button type="primary">
+        Next flight
+        <sonic-icon library="iconoir" slot="suffix" name="arrow-right"></sonic-icon>
+      </sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+## Loading
+
+`loading` replaces the content with a spinner and blocks clicks. The button keeps the width of its content.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button loading></sonic-button>
+      <sonic-button loading>Loading button</sonic-button>
+      <sonic-button loading type="primary">
+        <sonic-icon library="iconoir" slot="prefix" name="check"></sonic-icon>
+        Checking in
+      </sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+## Link
+
+With `href`, the button renders as a link. For a relative `href`, the button gets `active` when the current URL matches, according to `autoActive` (default `partial`). Add `pushState` to navigate without reloading the page.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button href="https://example.com" target="_blank" type="primary">External link</sonic-button>
+      <sonic-button href="/core/components/ui/button" variant="ghost">Current page</sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+## Toggle and radio
+
+A button with `name` and `value` writes to its `formDataProvider` and toggles `active` when clicked. Add `radio` for a single choice in a group, or `unique` to also allow deselecting. Children marked `swap="on"` / `swap="off"` show only in the active / inactive state.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap items-center gap-4">
+      <sonic-button formDataProvider="button-toggle-demo" name="visible" value="yes" type="primary" shape="circle" variant="outline">
+        <sonic-icon library="iconoir" swap="on" name="eye-empty"></sonic-icon>
+        <sonic-icon library="iconoir" swap="off" name="eye-off"></sonic-icon>
+      </sonic-button>
+      <sonic-group formDataProvider="button-radio-demo">
+        <sonic-button radio minWidth="7rem" name="plan" value="free">Free</sonic-button>
+        <sonic-button radio minWidth="7rem" name="plan" value="pro">Pro</sonic-button>
+        <sonic-button radio minWidth="7rem" name="plan" value="team">Team</sonic-button>
+      </sonic-group>
+    </div>
+  </template>
+</sonic-code>
+
+## Reset
+
+`reset` clears the button's own `formDataProvider`. Give it a value to clear another one by name.
+
+<sonic-code>
+  <template>
+    <div formDataProvider="button-reset-demo" class="mb-2">
+      <sonic-checkbox name="agree" value="yes">Extra baggage</sonic-checkbox>
+      <sonic-button reset>Reset this form</sonic-button>
+    </div>
+    <sonic-button reset="button-reset-demo">Reset by name</sonic-button>
+  </template>
+</sonic-code>
+
+## Go back
+
+`goBack` navigates back in history. When there is no previous page on the same origin, it goes to the attribute value, or to the site root if empty.
+
+<sonic-code>
+  <template>
+    <sonic-button goBack="/" variant="outline">
+      <sonic-icon library="iconoir" slot="prefix" name="arrow-left"></sonic-icon>
+      Back
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Accessibility
+
+Icon-only buttons need a label. Use `data-aria-label`, which is forwarded to the inner `button` (and link).
+
+<sonic-code>
+  <template>
+    <sonic-button shape="circle" data-aria-label="Close">
+      <sonic-icon library="iconoir" name="cancel"></sonic-icon>
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `type` | `default` (default) · `primary` · `neutral` · `warning` · `info` · `success` · `danger` · `custom` | Color; `custom` reads `--sc-btn-custom-color` and `--sc-btn-custom-bg` |
+| `variant` | `default` (default) · `outline` · `ghost` · `link` · `unstyled` | Visual style |
+| `size` | `2xs` … `2xl` (default `md`) · `inherit` | Typography and padding |
+| `shape` | `default` (default) · `circle` · `square` · `block` | Icon button or full width |
+| `icon` | boolean | Enlarges a lone icon |
+| `loading` | boolean | Shows a spinner and blocks clicks |
+| `disabled` | boolean | Dims the button and blocks clicks |
+| `active` | boolean | Active state, set automatically for links and toggles |
+| `align` | `left` · `center` · `right` | Text alignment |
+| `direction` | flex direction (default `row`) | Layout of slots |
+| `alignItems` | flex `align-items` (default `center`) | Cross-axis alignment of slots |
+| `justify` | flex `justify-content` (default `center`) | Main-axis alignment of slots |
+| `minWidth` | CSS length (default `0`) | Minimum width of the button |
+| `href` | URL | Renders the button as a link |
+| `target` | `_self` · `_blank` · `_parent` · `_top` | Link target |
+| `download` | string | Link `download` attribute |
+| `pushState` | boolean | Navigates with `history.pushState` |
+| `autoActive` | `partial` (default) · `strict` · `strict-path-only` · `disabled` | URL matching for `active` |
+| `goBack` | URL or empty | Goes back in history, with a fallback URL |
+| `reset` | empty or provider name | Clears the current or named form data provider |
+| `name` / `value` | string | Form field written to the data provider |
+| `formDataProvider` | string | Data provider to write to (default: nearest ancestor) |
+| `radio` | boolean | Single choice among buttons with the same `name` |
+| `unique` | boolean | Like `radio`, but can be deselected |
+| `autoRepeat` | boolean | Repeats the click while the pointer is held |
+| `data-aria-label` | string | `aria-label` of the inner button |
+| `data-aria-labelledby` | string | `aria-labelledby` of the inner button |
+| `data-aria-controls` | string | `aria-controls` of the inner button |
+| `data-aria-expanded` | boolean | `aria-expanded` of the inner button |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Label |
+| `prefix` | Icon or text before the label |
+| `suffix` | Icon or text after the label |

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

@@ -0,0 +1,56 @@
+# Captcha
+
+**`sonic-captcha`** embeds an [ALTCHA](https://altcha.org) proof-of-work widget and makes the nearest form wait for it. Place it inside a form scope and put **`sonic-submit`** in its default slot: the widget renders above the slot content, and the submit sends only once a token is available.
+
+## Basic example
+
+The widget loads only on **HTTPS**. On plain HTTP the component renders nothing and the form is not blocked.
+
+<sonic-code>
+  <template>
+    <sonic-scope
+      serviceURL="/docs-mock-api"
+      formDataProvider="captcha-docs-form"
+      submitResultDataProvider="captcha-docs-result"
+    >
+      <sonic-captcha>
+        <sonic-input class="mb-3 block" name="email" type="email" label="Email" value="demo@example.com"></sonic-input>
+        <sonic-submit endPoint="api/register" onClick>
+          <sonic-button type="primary">Join the crew</sonic-button>
+        </sonic-submit>
+      </sonic-captcha>
+    </sonic-scope>
+  </template>
+</sonic-code>
+
+## Form integration
+
+The component writes to the publisher named by the closest `headersDataProvider`, or else `formDataProvider`, on itself or an ancestor. On connect it sets `needsCaptchaValidation` to `true`. When **`sonic-submit`** sees that flag, it requests a token, the captcha copies the solved ALTCHA payload into `captchaToken` and its key into `captchaKey`, and the request is sent. `needsCaptchaValidation` is stripped from the payload. On disconnect both fields are reset.
+
+<sonic-code language="typescript">
+  <template>
+{
+  email: "demo@example.com",
+  captchaKey: "…",
+  captchaToken: "…"
+}
+  </template>
+</sonic-code>
+
+## Key and challenge endpoint
+
+With no `key`, the component generates an encrypted key on connect. The widget fetches its challenge from the `chalengeUrl` property (a JavaScript property, not an attribute) with `key` and `maxNumber` (default `50000`) as query parameters. Point it at your own ALTCHA server and verify `captchaToken` there.
+
+Labels follow the page language: French when `<html lang>` starts with `fr`, English otherwise.
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `key` | string (default generated) | Key sent to the challenge endpoint and copied to `captchaKey` |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Form fields and actions, rendered below the widget |
+
+No events.

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

@@ -0,0 +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">CN 001 · CDG → JFK · On time.</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 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 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 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 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>
+      </sonic-card-footer>
+    </sonic-card>
+  </template>
+</sonic-code>
+
+## Full example
+
+Header, media, body, and footer together.
+
+<sonic-code>
+  <template>
+    <sonic-card class="max-w-md">
+      <sonic-card-header label="Featured route" description="CDG → JFK">
+        <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="/img/concorde/plane_04.jpg"
+          alt="Concorde on the apron under a blue sky"
+        ></sonic-image>
+        <p class="mb-0">
+          Nonstop at Mach 2.04, with flexible dates.
+        </p>
+      </sonic-card-main>
+      <sonic-card-footer>
+        <div class="flex items-center justify-between gap-3 flex-wrap">
+          <span class="text-sm font-semibold">Cabin class: Business</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`) |