@supersoniks/concorde 5.0.4 → 5.1.0

package/src/core/components/ui/_css/type.ts

@@ -25,6 +25,22 @@ export function statusAriaLive(status?: StatusIconKey): "polite" | null {
   return status === "error" ? null : "polite";
 }
 
+/** Types sémantiques partagés (badge, progress, …). */
+export const defaultTypes = [
+  "default",
+  "primary",
+  "warning",
+  "danger",
+  "success",
+  "info",
+  "neutral",
+] as const;
+
+export type DefaultType = (typeof defaultTypes)[number];
+
+/** `sonic-card` `type` — `DefaultType` plus surface variants (`typesBg`). */
+export type CardType = DefaultType | "base" | "light" | "invert";
+
 export const statusColor = css`
   :host {
     --sc-_color: var(--sc-base-content, #000);
@@ -51,7 +67,7 @@ export const statusColor = css`
 
 export const typeColor = css`
   :host {
-    --sc-_color: inherit;
+    --sc-_color: var(--sc-base-content, #000);
     color: var(--sc-_color);
   }
 
@@ -70,21 +86,88 @@ export const typeColor = css`
   :host([type="success"]) {
     --sc-_color: var(--sc-success, var(--sc-base-content, #000));
   }
+  :host([type="neutral"]) {
+    --sc-_color: var(--sc-base-content, #000);
+  }
 
   .inherit-color {
     color: var(--sc-_color);
   }
 `;
 
+export const typeColorInvert = css`
+  :host([type="default"][invert]) {
+    --sc-_color: var(--sc-base, #fff);
+    --sc-_bg: color-mix(
+      in srgb,
+      var(--sc-base-content, #000) 8%,
+      var(--sc-base, #fff)
+    );
+  }
+  :host([type="primary"][invert]) {
+    --sc-_color: var(--sc-primary-content, var(--sc-base, #fff));
+    --sc-_bg: color-mix(
+      in srgb,
+      var(--sc-primary, var(--sc-base-content, #000)) 85%,
+      var(--sc-primary-content, #fff)
+    );
+  }
+  :host([type="warning"][invert]) {
+    --sc-_color: var(--sc-warning-content, var(--sc-base, #fff));
+    --sc-_bg: color-mix(
+      in srgb,
+      var(--sc-warning, var(--sc-base-content, #000)) 85%,
+      var(--sc-warning-content, #fff)
+    );
+  }
+  :host([type="danger"][invert]) {
+    --sc-_color: var(--sc-danger-content, var(--sc-base, #fff));
+    --sc-_bg: color-mix(
+      in srgb,
+      var(--sc-danger, var(--sc-base-content, #000)) 85%,
+      var(--sc-danger-content, #fff)
+    );
+  }
+  :host([type="info"][invert]) {
+    --sc-_color: var(--sc-info-content, var(--sc-base, #fff));
+    --sc-_bg: color-mix(
+      in srgb,
+      var(--sc-info, var(--sc-base-content, #000)) 85%,
+      var(--sc-info-content, #fff)
+    );
+  }
+  :host([type="success"][invert]) {
+    --sc-_color: var(--sc-success-content, var(--sc-base, #fff));
+    --sc-_bg: color-mix(
+      in srgb,
+      var(--sc-success, var(--sc-base-content, #000)) 85%,
+      var(--sc-success-content, #fff)
+    );
+  }
+  :host([type="neutral"][invert]) {
+    --sc-_color: var(--sc-base, #fff);
+    --sc-_bg: color-mix(
+      in srgb,
+      var(--sc-base, #fff) 80%,
+      var(--sc-base-content, #000)
+    );
+  }
+`;
+
 export const typesBg = css`
   :host {
-    --sc-_color: inherit;
-    --sc-_bg: inherit;
+    --sc-_bg: var(--sc-base-100, rgba(0, 0, 0, 0.07));
+    --sc-_color: var(--sc-base-content, #000);
     color: var(--sc-_color);
     background: var(--sc-_bg);
   }
 
   /*TYPES*/
+  :host([type="default"]),
+  :host([type="light"]) {
+    --sc-_bg: var(--sc-base-100, rgba(0, 0, 0, 0.07));
+    --sc-_color: var(--sc-base-content, #000);
+  }
   :host([type="primary"]) {
     --sc-_bg: var(--sc-primary, var(--sc-base-content, #000));
     --sc-_color: var(--sc-primary-content, var(--sc-base, #fff));
@@ -120,11 +203,6 @@ export const typesBg = css`
     --sc-_bg: var(--sc-base, #fff);
     --sc-_color: var(--sc-base-content, #000);
   }
-  :host([type="default"]),
-  :host([type="light"]) {
-    --sc-_bg: var(--sc-base-100, rgba(0, 0, 0, 0.07));
-    --sc-_color: var(--sc-base-content, #000);
-  }
 
   :host([type="neutral"]) {
     --sc-_bg: var(--sc-base-content, #000);

package/src/core/components/ui/_i18n/ui-aria-labels.ts

@@ -89,6 +89,14 @@ export const uiAriaLabels = {
     es: "Cerrar información",
     it: "Chiudi informazione",
   },
+  loading: {
+    en: "Loading",
+    fr: "Chargement en cours",
+    de: "Wird geladen",
+    nl: "Laden",
+    es: "Cargando",
+    it: "Caricamento in corso",
+  },
 } as const satisfies Record<string, UiLabelDict>;
 
 const toastCloseByStatus: Record<string, UiLabelDict> = {

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

@@ -1,8 +1,8 @@
 # Alert
 
-Inline message in the page: title (`label`), body (`text` or default slot), icon from `status`. For HTML or actions, use the slot instead of `label` / `text` (plain text only).
+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.
 
-Use **`status`**: `default`, `info`, `success`, `warning`, `error`.
+## Basic example
 
 <sonic-code>
   <template>
@@ -175,3 +175,22 @@ With **`dismissForever`**, dismissal is stored in `localStorage` (key `sonic-ale
     </sonic-alert>
   </template>
 </sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `status` | `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` | 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/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/src/core/components/ui/badge/badge.md

@@ -1,8 +1,6 @@
 # Badge
 
-A **non-interactive** pill for labels, counts, or highlights (counter, status, category). The API mirrors `sonic-button` (`type`, `variant`, `size`) without focus or click states.
-
-Colors come from theme tokens (`--sc-primary`, `--sc-danger`, …) or the semantic `type` values below. 
+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
 
@@ -24,9 +22,9 @@ Colors come from theme tokens (`--sc-primary`, `--sc-danger`, …) or the semant
 
 ## Variant
 
-`outline` — border and text in the `type` color. `ghost` — text only, no padding (except in forced-colors mode).
+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>
@@ -42,7 +40,7 @@ Colors come from theme tokens (`--sc-primary`, `--sc-danger`, …) or the semant
   </template>
 </sonic-code>
 
-## Ghost
+### Ghost
 
 <sonic-code>
   <template>
@@ -173,3 +171,18 @@ Count inside a button (`slot="suffix"`) or a badge absolutely positioned on a bu
     </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/src/core/components/ui/badge/badge.ts

@@ -4,7 +4,11 @@ import {
   fontSize,
   Size,
 } from "@supersoniks/concorde/core/components/ui/_css/size";
-import { typesBg } from "@supersoniks/concorde/core/components/ui/_css/type";
+import {
+  typesBg,
+  DefaultType,
+  typeColorInvert,
+} from "@supersoniks/concorde/core/components/ui/_css/type";
 
 const tagName = "sonic-badge";
 /**
@@ -17,6 +21,7 @@ export class Badge extends LitElement {
   static styles = [
     fontSize,
     typesBg,
+    typeColorInvert,
     css`
       :host {
         --sc-_gap: 0.3em;
@@ -111,14 +116,8 @@ export class Badge extends LitElement {
    * Le type change surtout la couleur composant
    */
   @property({ type: String, reflect: true })
-  type:
-    | "default"
-    | "primary"
-    | "warning"
-    | "danger"
-    | "success"
-    | "info"
-    | "neutral" = "default";
+  type: DefaultType = "default";
+
   /**
    * Le composant par defaut sans se paramètre à forte afordance
    * * ghost : composant super léger visuellement

package/src/core/components/ui/button/button.ts

@@ -18,6 +18,7 @@ import {
 } from "@supersoniks/concorde/core/components/ui/_css/size";
 import { PublisherManager } from "@supersoniks/concorde/utils";
 import { Route } from "@supersoniks/concorde/core/utils/route";
+import { Align } from "../_css/align";
 
 export type ButtonType =
   | "default"
@@ -458,10 +459,7 @@ export class Button extends FormCheckable(FormElement(LitElement)) {
   /**
    * Propriété text-align du bouton
    */
-  @property({ type: String, reflect: true }) align?:
-    | "right"
-    | "left"
-    | "center";
+  @property({ type: String, reflect: true }) align?: Align;
 
   /**
    * Propriété min-width du bouton
@@ -647,17 +645,9 @@ export class Button extends FormCheckable(FormElement(LitElement)) {
         @click=${this.handleChange}
         @pointerdown=${this.handleRepeatStart}
       >
-        <slot
-          @slotchange=${this.onSlotChange}
-          part="prefix"
-          name="prefix"
-        ></slot>
-        <slot part="main" class="main-slot"></slot>
-        <slot
-          @slotchange=${this.onSlotChange}
-          part="suffix"
-          name="suffix"
-        ></slot>
+        <slot @slotchange=${this.onSlotChange} name="prefix"></slot>
+        <slot class="main-slot"></slot>
+        <slot @slotchange=${this.onSlotChange} name="suffix"></slot>
         ${this.loading == true
           ? html`<sonic-icon name="loader" class="loader"></sonic-icon>`
           : ""}

package/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/src/core/components/ui/card/card.md

@@ -1,16 +1,27 @@
 # Card
 
-A **surface** for grouped content: padding, radius, shadow, and semantic **`type`** colors via shared theme tokens. Compose **`sonic-card-header`**, **`sonic-card-main`**, and **`sonic-card-footer`** inside the card, or put any markup in the default slot.
+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.
 
-Default **`type`** is `base` (page background). Use `light` for a subtle gray panel, `invert` / `neutral` for high-contrast blocks, and `primary`, `info`, `success`, `warning`, or `danger` for tinted surfaces (divider tokens apply on colored types).
+## 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>
@@ -22,9 +33,26 @@ Default **`type`** is `base` (page background). Use `light` for a subtle gray pa
   </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`** attributes, 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.
+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>
@@ -42,7 +70,7 @@ Quick titles with **`label`** and **`description`** attributes, or full control
           <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-badge slot="suffix" type="warning" size="xs">3 new</sonic-badge>
         </sonic-card-header>
       </sonic-card>
 
@@ -77,8 +105,6 @@ Quick titles with **`label`** and **`description`** attributes, or full control
   </template>
 </sonic-code>
 
-`label` and `description` accept HTML (rendered as markup). Prefer plain text when possible; use the slot for structured content.
-
 ## Main
 
 Optional wrapper for the primary content area (typography, media, forms).
@@ -110,7 +136,7 @@ Optional footer for actions, metadata, or secondary text.
         <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>
+        <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>
@@ -128,14 +154,14 @@ Header, media, body, and footer together.
   <template>
     <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"></sonic-icon>
+        <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://images.unsplash.com/photo-1436491865332-7a61a109cc05?w=800&q=80"
-          alt=""
+          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.
@@ -150,3 +176,40 @@ Header, media, body, and footer together.
     </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`) |