@supersoniks/concorde 5.0.4 → 5.0.5

package/docs/llms-full.txt

@@ -948,13 +948,59 @@ I prefer
 
 ---
 
-## Concorde
+## Alert messages
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/alert-messages/alert-messages.html
 - Doc ID: core/components/ui/alert-messages/alert-messages
-- Keywords: Concorde, supersoniks, core/components/ui/alert-messages/alert-messages, alert-messages, UI component, sonic-alert-messages, web component
+- Keywords: Concorde, supersoniks, core/components/ui/alert-messages/alert-messages, alert-messages, Alert messages, UI component, sonic-alert-messages, web component, sonic-alert, messages, submitResultDataProvider, type="public", announce, dataProvider, type
 
+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).
+
+           Submit (empty fields → error messages)
+
+Shared alert props
+
+size · background and noIcon apply to every rendered sonic-alert in the list.
+
+      Load sample messages
+
+Message shape
+
+Example JSON on the result publisher (or API response merged into it):
+
+{
+  "messages": [
+    {
+      "type": "public",
+      "content": "The product has been added to your cart",
+      "status": "success"
+    }
+  ]
+}
+
+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.
 
 ---
 
@@ -962,68 +1008,118 @@ I prefer
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/alert/alert.html
 - Doc ID: core/components/ui/alert/alert
-- Keywords: Concorde, supersoniks, core/components/ui/alert/alert, alert, Alert, UI component, sonic-alert, web component
+- Keywords: Concorde, supersoniks, core/components/ui/alert/alert, alert, Alert, UI component, sonic-alert, web component, label, text, announce, status, default, role, aria-live
 
 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
+
 Status
 
-    This address is already in use.
-    This address is already in use.
-    This address is already in use.
-    This address is already in use.
-    This address is already in use.
+Color and icon follow status. With no status, behavior is default.
+
+       This address is already in use.
+       This address is already in use.
+       This address is already in use.
+       This address is already in use.
+       This address is already in use.
+
+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.
+
+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.
+
+Custom icon slot
+
+Project any markup into slot="icon" (emoji, image, custom component). Keep it decorative with aria-hidden="true" when the message text already conveys meaning.
+
+       🎉
+      You unlocked a new badge.
 
 Sizes
 
-    This address is already in use. Lorem ipsum dolor sit amet.
+        This address is already in use. Lorem ipsum dolor sit amet.
 
-    This address is already in use. Lorem ipsum dolor sit amet.
+        This address is already in use. Lorem ipsum dolor sit amet.
 
-    This address is already in use. Lorem ipsum dolor sit amet.
+        This address is already in use. Lorem ipsum dolor sit amet.
 
-    This address is already in use. Lorem ipsum dolor sit amet.
+        This address is already in use. Lorem ipsum dolor sit amet.
 
-    This address is already in use. Lorem ipsum dolor sit amet.
+        This address is already in use. Lorem ipsum dolor sit amet.
 
-    This address is already in use. Lorem ipsum dolor sit amet.
+        This address is already in use. Lorem ipsum dolor sit amet.
 
-    This address is already in use. Lorem ipsum dolor sit amet.
+        This address is already in use. Lorem ipsum dolor sit amet.
 
 Alert with link
 
-    You have 2 unread messages
+Rich content in the slot (buttons, links).
+
+      You have 2 unread messages
 
-       See messages
-       dismiss
+         See messages
+         Dismiss
 
 Background
 
-    This address is already in use.
+Tinted background from the status color (color-mix on currentColor).
 
-    This address is already in use.
+       This address is already in use.
 
-    This address is already in use.
+        This address is already in use.
 
-    This address is already in use.
+        This address is already in use.
 
-    This address is already in use.
+        This address is already in use.
+
+        This address is already in use.
 
 Dismissible
 
-    This address is already in use.
+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.
+
+      This address is already in use.
 
-    This address is already in use.
+      This address is already in use.
 
-    This address is already in use.
+      This address is already in use.
 
-    This address is already in use.
+      This address is already in use.
 
-    This address is already in use.
+      This address is already in use.
 
 Dismiss forever
 
-    This address is already in use.
+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.
+
+      This address is already in use.
+
+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 |
 
 ---
 
@@ -1031,68 +1127,105 @@ Dismiss forever
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/badge/badge.html
 - Doc ID: core/components/ui/badge/badge
-- Keywords: Concorde, supersoniks, core/components/ui/badge/badge, badge, Badge, UI component, sonic-badge, web component
+- Keywords: Concorde, supersoniks, core/components/ui/badge/badge, badge, Badge, UI component, sonic-badge, web component, sonic-button, type, variant, size, default, base-100, neutral, base-content, outline
 
 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
-   Primary
-   Neutral
-   Warning
-   Info
-   Success
-   Danger
-   Contrast
+default — subtle background (base-100). neutral — dark fill (base-content) with light text, useful on light backgrounds.
+
+       Default
+       Primary
+       Neutral
+       Warning
+       Info
+       Success
+       Danger
+
+Variant
+
+Default variant is filled. outline — border and text in the type color. ghost — text only, no padding (except in forced-colors mode).
 
 Outline
 
-     Default
-     Primary
-     Neutral
-     Warning
-     Info
-     Success
-     Danger
-     Contrast
+       Default
+       Primary
+       Neutral
+       Warning
+       Info
+       Success
+       Danger
 
 Ghost
 
-     Default
-     Primary
-     Neutral
-     Warning
-     Info
-     Success
-     Danger
-     Contrast
+       Default
+       Primary
+       Neutral
+       Warning
+       Info
+       Success
+       Danger
 
 Size
 
- 2Xs badge
-   Xs badge
-   Sm badge
-   Md badge
-   Lg badge
-   Xl badge
-   2Xl badge
+Default size is md (omit the size attribute). Typography and padding follow sonic-button.
+
+       2Xs
+       Xs
+       Sm
+       Md
+       Lg
+       Xl
+       2Xl
+
+Prefix and suffix slots
+
+Icons or short text before / after the main label.
+
+      Info
+
+      Verified
 
 Empty badges
 
+Badge with no text (visual dot). min-width / min-height keep a readable shape.
+
 Ellipsis
 
-           Lorem ipsum dolor sit consectetur adipiscing elit. Lorem ipsum dolor sit consectetur adipiscing elit.
-             Lorem ipsum dolor sit consectetur adipiscing elit. Lorem ipsum dolor sit consectetur adipiscing elit.
+With ellipsis, long labels truncate. The parent must constrain width (max-width, grid, etc.).
+
+        Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod.
+
+        Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod.
 
 Badge in button
 
-      Messages  5
+Count inside a button (slot="suffix") or a badge absolutely positioned on a button / icon.
+
+        Messages  5
+
+         My account
+         12
 
-        Mon compte
-       12
+         33
 
-       33
+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 |
 
 ---
 
@@ -1154,6 +1287,7 @@ Loading
 The length of the button depends on the size of its content
 
      Loading button
+      🚀 Loading with prefix 😂
 
 Swap
 
@@ -1203,11 +1337,54 @@ Custom styles & active states with tailwind
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/captcha/captcha.html
 - Doc ID: core/components/ui/captcha/captcha
-- Keywords: Concorde, supersoniks, core/components/ui/captcha/captcha, captcha, Captcha, UI component, sonic-captcha, web component
+- Keywords: Concorde, supersoniks, core/components/ui/captcha/captcha, captcha, Captcha, UI component, sonic-captcha, web component, captchaToken, needsCaptchaValidation, formDataProvider, headersDataProvider, sonic-submit, key, generateEncryptedKey
 
 Captcha
 
-       Submit with 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.
+
+Basic example
+
+Wrap the form scope and place sonic-submit in the default slot so the challenge appears above the action.
+
+           Submit with captcha
+
+Encrypted site key
+
+Optional key skips client-side key generation. When omitted, the component derives an encrypted key on connect (after generateEncryptedKey).
+
+       Complete the challenge above to enable submit
+
+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 requesttoken to refresh the token immediately before send.
+
+{
+  needsCaptchaValidation: true,
+  captchaKey: "…",
+  captchaToken: "…"
+}
+
+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 — needsCaptchaValidation and deferred send.
 
 ---
 
@@ -1215,49 +1392,118 @@ Captcha
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/card/card.html
 - Doc ID: core/components/ui/card/card
-- Keywords: Concorde, supersoniks, core/components/ui/card/card, card, Card, UI component, sonic-card, web component
+- Keywords: Concorde, supersoniks, core/components/ui/card/card, card, Card, UI component, sonic-card, web component, type, shadow, lg, sonic-card-header, sonic-card-main, sonic-card-footer, base, default, light
 
 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
+
+       Related content on a raised surface.
+
 Type
 
-     Base
-     Light
-     Primary
-     Warning
-     Danger
-     Success
-     Info
-     Neutral
-     Invert
+Default type is base. default and light share the same surface tokens.
+
+       Base
+       Light
+       Default
+       Primary
+       Info
+       Success
+       Warning
+       Danger
+       Neutral
+       Invert
+
+Shadow
+
+Set shadow to control elevation. Default is lg.
+
+       None
+       Small
+       Medium
+       Large
 
 Header
 
-         Description rendu via le composant : "sonic-card-header-description"
+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.
+
+         Body content goes in the card slot or in  sonic-card-main .
 
-          Suffix
+            Choose what we email you about.
 
-         Header custom
-         Tout le contenu excepté l'icône ✈ passe par le slot du header
-         ✈
+           3 new
+
+           Custom header
+
+            Use the header slot when attributes are not enough.
 
 Main
 
-       Main area
-       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.
+Optional wrapper for the primary content area (typography, media, forms).
+
+          Improved performance on large lists and fixed an issue with keyboard navigation in menus.
+
+         See the changelog for details.
 
 Footer
 
-         Footer area
-         Debitis deleniti eligendi natus dolorem aufdh.
+Optional footer for actions, metadata, or secondary text.
+
+         This project and all of its data will be removed permanently.
+
+           Cancel
+           Delete
+
+Full example
+
+Header, media, body, and footer together.
+
+          Nonstop flight with flexible dates. Prices shown include taxes and fees.
+
+           From $249
+           Book
 
-          🛫 ✈ ✈ ✈ ✈ ✈ 🛬
+API reference
 
-Example of use
+sonic-card
 
-        Main  - 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.
+| 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 |
 
-         Footer  - Amet consectetur adipisicing
+| 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) |
 
 ---
 
@@ -1265,19 +1511,72 @@ Example of use
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/divider/divider.html
 - Doc ID: core/components/ui/divider/divider
-- Keywords: Concorde, supersoniks, core/components/ui/divider/divider, divider, Divider, UI component, sonic-divider, web component
+- Keywords: Concorde, supersoniks, core/components/ui/divider/divider, divider, Divider, UI component, sonic-divider, web component, sonic-menu, label, align, center, lineStyle, solid, size, 0.5rem
 
 Divider
 
-Default
+sonic-divider draws a horizontal or vertical rule with optional centered label copy. Use it to separate sections in forms, cards, and sonic-menu. Set label for simple HTML captions or use the default slot for richer markup; default align is center and default lineStyle is solid.
 
-Align
+Basic example
+
+A bare divider is a full-width line with vertical margin. Omit size to use the host default spacing (0.5rem block margin).
+
+Label and align
+
+label renders inside the line (HTML via the same pipeline as other form labels). align controls which side(s) of the line remain visible: left drops the leading segment, right drops the trailing segment, center keeps both.
 
 Size
 
-Custom
+size adjusts block margin and label font size. Values follow the shared Concorde scale (2xs … 2xl).
+
+Line style
+
+lineStyle sets the stroke of the rule (solid · dashed · dotted). In HTML use the reflected attribute linestyle (case-insensitive).
+
+Vertical and margin
+
+Set vertical for a column rule (for example between toolbar actions). noMargin removes host margin when a parent layout already provides spacing.
+
+       Before
+
+       After
+
+Default slot
+
+Slotted content replaces or augments label. Useful for badges, icons, or mixed markup in menus.
+
+       Section title
+       +25
+
+Inside typed cards
+
+On sonic-card with semantic type (primary · warning · danger · info · success), the rule uses the card’s text color at reduced opacity so it stays visible on tinted surfaces. label and slotted captions use the same foreground color as surrounding copy.
+
+         This action cannot be undone.
+
+           Project files
+           Shared links
+
+         Maintenance is scheduled for tonight.
+
+         Expected downtime: about 15 minutes.
 
-  Lorem ipsum dolor sit amet  +25
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| label | string (HTML) | Caption centered on the rule; combined with default-slot content when both are set |
+| align | left · center · right (default center) | Hides the leading or trailing line segment for left/right alignment |
+| size | 2xs · xs · sm · md · lg · xl · 2xl · inherit | Vertical margin and label font-size; omit for host defaults |
+| lineStyle | solid · dashed · dotted (default solid) | Stroke style of the rule (HTML attribute linestyle) |
+| vertical | boolean | Renders a vertical rule; swap block/inline margins |
+| noMargin | boolean | Sets host margin to 0 |
+
+| Slot | Description |
+|------|-------------|
+| (default) | Label markup when label is insufficient or empty |
+
+The inner flex container exposes part="divider" for theme overrides.
 
 ---
 
@@ -1336,98 +1635,212 @@ Checked blacklistFlags values are sent to the mock API (?blacklistFlags=racist,s
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/form/fieldset/fieldset.html
 - Doc ID: core/components/ui/form/fieldset/fieldset
-- Keywords: Concorde, supersoniks, core/components/ui/form/fieldset/fieldset, fieldset, Fieldset, UI component, form, sonic-fieldset, web component
+- Keywords: Concorde, supersoniks, core/components/ui/form/fieldset/fieldset, fieldset, Fieldset, UI component, form, sonic-fieldset, web component, , sonic-legend, label, description, iconName, variant, default, sonic-form-layout, ghost
 
 Fieldset
 
+sonic-fieldset groups related form controls with a bordered container and an accessible   semantics layer. Put fields in the default slot; add a title with sonic-legend or the shorthand label / description / iconName attributes. Default variant is default. Pair the body with sonic-form-layout for responsive columns.
+
+Basic example
+
 Variant
 
-      Default
+ghost and shadow use a transparent border; shadow also applies --sc-shadow-lg.
 
-      Ghost
+Tight layout
 
-      Shadow
+Set tight to remove horizontal padding and side borders (flat strip inside a parent).
 
 Legend
 
-      Custom legend via  slot
+Use sonic-legend for the group title. Set label and description for simple copy, or use the default slot for custom markup. Add secondary text with sonic-legend-description. Place actions in slot="suffix" on the legend.
+
+Attribute values on sonic-legend are rendered as HTML—use only trusted content.
+
+          Custom title in the default slot
+           Description via sonic-legend-description
+
+Shorthand legend on the fieldset
+
+When label is set on sonic-fieldset, the component renders sonic-legend for you. Pass description iconName iconLibrary and iconPrefix the same way. Do not combine shorthand label with a separate slotted sonic-legend—you will get two legends.
+
+Legend actions
+
+Use slot="suffix" on sonic-legend for menus or icon buttons aligned to the end of the legend row.
+
+             Legal notice
+             Terms of use
+
+Form association and disabled state
+
+Associating a distant form
+
+Set form on sonic-fieldset to the id of a   elsewhere in the page (same as the native form attribute on  ). Named fields in the fieldset then belong to that form for submit and constraint validation—for example a toolbar form and a field group rendered lower on the layout.
+
+         Save billing
+
+Disabling a group
+
+Set disabled on sonic-fieldset to disable the inner   and every control in the group (same as a native fieldset). Use it for read-only steps or sections gated by permissions.
 
-        Description via composant : sonic-legend-description
+Accessibility
 
-Short hand
+The inner   carries grouping semantics. disabled is applied on that element so nested controls are disabled in the usual way. sonic-legend renders a native   for the group label.
 
-Example of use
+API reference
 
-          Informations personnelles
-           Description du fieldset lorem ipsum dolor
+sonic-fieldset
 
-               Mentions légales
-               Conditions générales d'utilisation
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| variant | default · ghost · shadow (default default) | Border and shadow treatment |
+| tight | boolean | Removes horizontal padding and side borders |
+| label | string | Shorthand legend title; renders sonic-legend when set |
+| description | string | Shorthand legend description (HTML) |
+| iconName | string | Shorthand legend icon name |
+| iconLibrary | string | Shorthand legend icon library |
+| iconPrefix | string | Shorthand legend icon prefix |
+| disabled | boolean | Disables the native   and its controls |
+| form | string | id of an associated form |
+| dataProvider | string | Subscriber key; can autofill properties that match publisher fields (e.g. label) |
 
-             - Sélectionner -
-             Je préfère ne pas le dire
-             Homme
-             Femme
+| Slot | Description |
+|------|-------------|
+| (default) | Legend (optional) and field group content in visual order |
 
-          Coordonnées
+sonic-legend
 
-          S'inscrire
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| label | string | Title HTML when not using the default slot |
+| description | string | Description HTML (wrapped in sonic-legend-description) |
+| iconName | string | Leading sonic-icon name |
+| iconLibrary | string | Icon library |
+| iconPrefix | string | Icon prefix |
+| forceAutoFill | boolean | Allows Subscriber autofill to override attribute-backed label / description |
 
-            Continuer sans m'inscrire
+| Slot | Description |
+|------|-------------|
+| (default) | Legend title and description components |
+| suffix | Trailing actions (menus, icon buttons) |
 
-        Submitted informations...
+sonic-legend-description
+
+Muted description line below the legend title. No attributes—project content through the default slot.
 
 ---
 
-## Form-actions
+## Form actions
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/form/form-actions/form-actions.html
 - Doc ID: core/components/ui/form/form-actions/form-actions
-- Keywords: Concorde, supersoniks, core/components/ui/form/form-actions/form-actions, form-actions, Form-actions, UI component, form, sonic-form-actions, web component
+- Keywords: Concorde, supersoniks, core/components/ui/form/form-actions/form-actions, form-actions, Form actions, UI component, form, sonic-form-actions, web component, sonic-form-layout, direction, row, justify, flex-start, alignItems, center, justify-content
 
-Form-actions
+Form actions
 
-Left by default
+sonic-form-actions lays out submit / cancel and other form footer controls in a wrapping flex row with a small fixed gap. Place it inside sonic-form-layout (full-width row) or any block that should end with actions. Defaults: direction row · justify flex-start · alignItems center.
 
-            Submit
-             Cancel
+Basic example
 
-Justify
+With no attributes, actions align to the start of the row (typical for left-to-right forms).
 
-            Submit
-             Cancel
+              Submit
+              Cancel
 
-Direction
+Justify content
+
+justify maps to CSS justify-content. Use flex-end for dialog-style footers or center for balanced toolbars.
+
+              Submit
+              Cancel
+
+Flex direction
+
+direction maps to flex-direction. row-reverse swaps visual order while keeping DOM order (focus order unchanged).
+
+              Submit
+              Cancel
+
+Mixed controls
+
+Combine sonic-button with sonic-divider vertical or other slotted content. Default alignItems center keeps unlike heights aligned on the cross axis.
 
-            Submit
-             Cancel
+            Left seats
 
-Center
+            Right seats
 
-          Left seats
+API reference
 
-          Right seats
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| direction | row (default) · column · row-reverse · column-reverse | Main-axis layout of slotted controls |
+| justify | CSS justify-content (default flex-start) | Distribution along the main axis |
+| alignItems | CSS align-items (default center) | Cross-axis alignment when items differ in height |
+
+The component exposes a single unnamed slot; there are no named slots. Slotted nodes use the host’s flex gap (0.3rem) and flex-wrap.
+
+| Slot | Description |
+|------|-------------|
+| (default) | Footer actions (sonic-button and related controls) |
 
 ---
 
-## Form-layout
+## Form layout
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/form/form-layout/form-layout.html
 - Doc ID: core/components/ui/form/form-layout/form-layout
-- Keywords: Concorde, supersoniks, core/components/ui/form/form-layout/form-layout, form-layout, Form-layout, UI component, form, sonic-form-layout, web component
+- Keywords: Concorde, supersoniks, core/components/ui/form/form-layout/form-layout, form-layout, Form layout, UI component, form, sonic-form-layout, web component, sonic-input, sonic-select, sonic-input-autocomplete, sonic-form-actions, sonic-fieldset, offsetWidth
+
+Form layout
+
+sonic-form-layout arranges slotted form controls in a responsive CSS grid with consistent vertical spacing. Pair sonic-input · sonic-select and sonic-input-autocomplete fields side by side when the host is wider than 440px; textareas, toggles, dividers, and sonic-form-actions span the full width. Wrap a form or sonic-fieldset body—no attributes are required.
+
+Basic example
+
+Typical registration-style form: short fields flow in two columns on wide layouts; long or grouped blocks stay full width.
+
+           — Select —
+           Prefer not to say
+           Male
+           Female
+
+         Enable optional feature
+         Subscribe to newsletter
 
-Form-layout
+          I accept the
+           terms and conditions
 
-         - Sélectionner -
-         Je préfère ne pas le dire
-         Homme
-         Femme
+           Submit
 
-       Activer une superbe option
-       Inscription à la newsletter
-       J'ai lu et accepte les  Conditions générales de ventes
+Responsive columns
 
-         Valider
+When the host offsetWidth is greater than 440px, the grid uses two equal columns with slightly larger gap (1.75rem). Below that breakpoint, fields stack in a single column (1.5rem gap).
+
+If the slot contains exactly one direct sonic-input, sonic-select, or sonic-input-autocomplete, the layout stays one column even above the breakpoint so a lone field does not sit in half an empty row.
+
+         Narrow host (single column)
+
+       Wide host (two columns for inputs)
+
+Full-width slotted blocks
+
+Everything except sonic-input, sonic-select, sonic-input-autocomplete, and slotted elements with class form-item-container is assigned grid-column: 1 / -1. Use this for sonic-textarea, sonic-checkbox, sonic-switch, sonic-form-actions, sonic-divider, and similar blocks.
+
+Slotted sonic-divider sets --sc-divider-my: 0 so divider spacing matches the grid rhythm. Slotted sonic-submit uses display: contents so submit controls participate in the grid without an extra wrapper box.
+
+         Send
+
+Custom column wrapper
+
+Add class form-item-container on a slotted wrapper (for example a div) when a field is not a direct sonic-input / sonic-select / sonic-input-autocomplete but should still share the two-column flow with short inputs.
+
+API reference
+
+No public attributes — layout follows slotted children and host width.
+
+| Slot | Description |
+|------|-------------|
+| (default) | Form fields and blocks in visual order; column vs full-width rules apply per slotted tag or form-item-container class |
 
 ---
 
@@ -1469,7 +1882,7 @@ data-keyboard-nav sur le champ et les items (flèches haut / bas).
 
 Input
 
-  Native attibutes list
+  Native attributes list
 
 Label
 
@@ -1640,7 +2053,7 @@ Same mock filter as Checkbox; switches can enable several flags (comma-separated
 
 Textarea
 
-  Native attibutes list
+  Native attributes list
 
 Label
 
@@ -1662,47 +2075,91 @@ Size
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/group/group.html
 - Doc ID: core/components/ui/group/group
-- Keywords: Concorde, supersoniks, core/components/ui/group/group, group, Group, UI component, sonic-group, web component
+- Keywords: Concorde, supersoniks, core/components/ui/group/group, group, Group, UI component, sonic-group, web component, sonic-button, sonic-input, sonic-select, label, description, radio, name, formDataProvider
 
 Group
 
+sonic-group lays out slotted sonic-button · sonic-input and sonic-select controls in a single horizontal row with shared corner radius (first / middle / last items). Optional label and description follow form field styling. Use it for button groups, radio rows, or input + action toolbars.
+
 Radio group
 
+Pair with sonic-button radio and a shared name; ancestor formDataProvider stores the selected value.
+
        😎 Standard
        ⭐ Premium
        💎 Diamond
 
 Button group
 
-       🗼Air France
+Adjacent link or action buttons without merging into one control.
+
+       🗼 Air France
        🌴 Air Tahiti
        💣 Air Corsica
 
 Input actions prefix
 
+Action control before the field. label or description on sonic-group annotate the row.
+
 Input actions suffix
 
+Field first, action after (submit, validate, etc.).
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| label | string (HTML) | Label above the row; slot="label" overrides / extends |
+| description | string (HTML) | Help text below the row; slot="description" overrides / extends |
+| alignItems | CSS align-items (default center) | Cross-axis alignment of the main flex row |
+
+| Slot | Description |
+|------|-------------|
+| (default) | sonic-button · sonic-input · sonic-select in visual order |
+| label | Custom label markup |
+| description | Custom description markup |
+
 ---
 
 ## Icon
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/icon/icon.html
 - Doc ID: core/components/ui/icon/icon
-- Keywords: Concorde, supersoniks, core/components/ui/icon/icon, icon, Icon, UI component, sonic-icon, web component
+- Keywords: Concorde, supersoniks, core/components/ui/icon/icon, icon, Icon, UI component, sonic-icon, web component, name, library, prefix, size, currentColor, aria-hidden, icons.json
 
 Icon
 
-Custom
+sonic-icon renders inline SVG icons from the bundled core set or from CDN libraries. Set name (and library / prefix when needed); scale with size. Icons inherit currentColor and are aria-hidden by default—keep visible text nearby or label the control that contains them.
 
- Icons located in the following folder :  /svg/$prefix/$name.svg
+Core library
 
-           regular
+Omit library to use the bundled set in icons.json. Available name values: cancel · check · check-circled-outline · emoji-puzzled · info-empty · loader · minus-small · more-horiz · more-vert · nav-arrow-down · warning-circled-outline.
 
-           solid
+         cancel
 
-           default prefix
+         check
+
+         check-circled-outline
+
+         emoji-puzzled
+
+         info-empty
+
+         loader
+
+         minus-small
+
+         more-horiz
 
-External
+         more-vert
+
+         nav-arrow-down
+
+         warning-circled-outline
+
+External libraries
+
+Set library to load SVGs from a built-in CDN template. prefix falls back to each library’s default when omitted (outline for heroicons, regular for fontAwesome and material, and so on).
 
          heroicons
 
@@ -1718,8 +2175,20 @@ External
 
          lucide
 
+Custom library
+
+Use library="custom" with SVG files on your origin. On an ancestor (for example sonic-scope or sonic-code), set customIconLibraryPath to a URL template with $prefix and $name placeholders, and optionally customIconDefaultPrefix when prefix is omitted.
+
+           regular
+
+           solid
+
+           default prefix
+
 Size
 
+Omit size for the default scale (1em height). Larger steps use 3xl.
+
          2xs
 
          xs
@@ -1736,87 +2205,250 @@ Size
 
          3xl
 
+Accessibility
+
+On connect, the host sets aria-hidden="true". Treat icons as decorative unless the surrounding control already has an accessible name. Do not rely on sonic-icon alone for meaning—use visible text or aria-label on the parent button / link.
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| name | string | Icon id in the core bundle or in the remote library |
+| library | heroicons · iconoir · feathers · lucide · material · fontAwesome · custom | CDN or custom template; omit for bundled core icons |
+| prefix | string | Library-specific variant; defaults per library when empty |
+| size | 2xs · xs · sm · lg · xl · 2xl · 3xl (default md) | em-based SVG scale on the host |
+
+Ancestor attributes (for library="custom" only): customIconLibraryPath (URL template with $prefix and $name) and customIconDefaultPrefix. May be set on sonic-scope, theme roots, or globally in the document.
+
+No slots — the component inlines fetched or bundled SVG markup.
+
 ---
 
 ## Image
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/image/image.html
 - Doc ID: core/components/ui/image/image
-- Keywords: Concorde, supersoniks, core/components/ui/image/image, image, Image, UI component, sonic-image, web component
+- Keywords: Concorde, supersoniks, core/components/ui/image/image, image, Image, UI component, sonic-image, web component, , object-fit: cover, --sc-placeholder-bg, loading, lazy, loading="eager", rounded, --sc-rounded
 
 Image
 
+sonic-image wraps a responsive   with aspect ratio, object-fit: cover, optional rounded corners, and load transitions. The host shows a placeholder background (--sc-placeholder-bg) until the asset loads. Default loading is lazy; use loading="eager" for above-the-fold heroes.
+
 Rounded
 
-Ratio
+Omit rounded for square corners. Boolean rounded uses the theme token --sc-rounded. Sizes: sm, md, lg, xl, full (circle — pair with ratio="1/1"), none (explicit reset).
+
+         default
+
+         sm
+
+         rounded
+
+         md
+
+         lg
+
+         xl
+
+           full
+
+Aspect ratio
+
+ratio sets CSS aspect-ratio on the image (default auto). The image still fills the host width (width: 100%).
 
 Object position
 
+objectPosition maps to CSS object-position (default center center). Useful on wide crops when the subject sits off-center.
+
 Cover
 
+cover stretches the image to fill a positioned parent (position: relative + fixed height or inset). Aspect ratio on the host is ignored while cover is set.
+
+Load transition
+
+Set transition to fade (default when the attribute is present) or fade-scale-out. The image stays at opacity: 0 until the browser fires load, then the loaded class runs the animation. Changing src on an existing element does not replay the effect — mount a new sonic-image when you need another entrance (galleries, infinite scroll).
+
+Click Add image to append small thumbnails and replay the transition. Clear resets the row.
+
+        Add image (fade)
+
+        Add image (fade-scale-out)
+
+        Clear
+
+Accessibility and parts
+
+Always set meaningful alt text (empty string only for decorative images).
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| src | URL | Image URL passed to   |
+| alt | string | Accessible description; use "" only for decorative images |
+| loading | lazy (default), eager | Native lazy loading |
+| ratio | CSS ratio, auto (default) | Host aspect-ratio on the image (ignored when cover is set) |
+| rounded | none (default), boolean, base, sm, md, lg, xl, full | Corner radius from theme tokens; full is a circle (often with ratio="1/1") |
+| objectPosition | CSS position | Maps to object-position (default center center) |
+| imageRendering | CSS value | Maps to image-rendering (default auto) |
+| cover | boolean | Absolutely fills a positioned parent; host aspect ratio is ignored |
+| transition | fade, fade-scale-out | Opacity (and scale) animation after load; remount to replay on src change |
+
+No slots — content is driven entirely by attributes on the inner  .
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| src | URL | Image URL passed to   |
+| alt | string | Accessible description; use "" only for decorative images |
+| loading | lazy (default), eager | Native lazy loading |
+| ratio | CSS ratio, auto (default) | Host aspect-ratio on the image (ignored when cover is set) |
+| rounded | none (default), boolean, base, sm, md, lg, xl, full | Corner radius from theme tokens; full is a circle (often with ratio="1/1") |
+| objectPosition | CSS position | Maps to object-position (default center center) |
+| imageRendering | CSS value | Maps to image-rendering (default auto) |
+| cover | boolean | Absolutely fills a positioned parent; host aspect ratio is ignored |
+| transition | fade, fade-scale-out | Opacity (and scale) animation after load; remount to replay on src change |
+
+No slots — content is driven entirely by attributes on the inner  .
+
 ---
 
 ## Link
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/link/link.html
 - Doc ID: core/components/ui/link/link
-- Keywords: Concorde, supersoniks, core/components/ui/link/link, link, Link, UI component, sonic-link, web component
+- Keywords: Concorde, supersoniks, core/components/ui/link/link, link, Link, UI component, sonic-link, web component, href, pushstate, autoActive, active, target="_blank", rel="noopener noreferrer", partial
 
 Link
 
-Href
+Links navigate with inherited typography: internal routes, anchors, or external URLs. The default slot is the anchor label. For in-app routing, pair href with pushstate; use autoActive to reflect the current URL on the host (active).
 
- Basic link with href attibute
+Basic example
+
+ Basic link with href attribute
 
 Target
 
- Link with target attibute
+target="blank" opens a new browsing context and sets rel="noopener noreferrer".
+
+ Link with target attribute
+
+Pushstate
+
+Set pushstate on same-origin href values to intercept clicks and navigate through Concorde’s client router without a full reload.
+
+ Client navigation (pushstate)
 
 AutoActive
 
+Default autoActive is partial: the host gets active when the current URL starts with href. Style with [&[active]]: utilities or host selectors.
+
  autoActive partial (default)
 
-AutoActive Strict vs partial
+AutoActive strict vs partial
+
+strict requires pathname, search, and hash to match. strict-path-only matches pathname and hash but ignores search.
 
        autoActive strict
-       autoActive strict
+       autoActive strict (long href)
+       autoActive strict-path-only
 
 AutoActive disabled
 
  autoActive disabled
 
+Accessibility
+
+The inner   uses focus-visible outline styling. Set data-aria-label when the slot text is not sufficient on its own.
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| href | URL | Link target; without href, only the slot is rendered (no  ) |
+| target | e.g. blank | Navigation target; blank adds rel="noopener noreferrer" |
+| pushstate | boolean | Intercepts click for Concorde client navigation without reload |
+| autoActive | partial (default) · strict · strict-path-only · disabled | When the host gets the active attribute (same-origin href only) |
+| data-aria-label | string | Accessible aria-label when the slot text is not enough |
+
+| Slot | Description |
+|------|-------------|
+| (default) | Link content (text, icons) |
+
 ---
 
 ## Loader
 
-- URL: https://concorde.supersoniks.org/crawl/core/components/ui/loader/loader.html
-- Doc ID: core/components/ui/loader/loader
-- Keywords: Concorde, supersoniks, core/components/ui/loader/loader, loader, Loader, UI component, sonic-loader, web component
+- URL: https://concorde.supersoniks.org/crawl/core/components/ui/loader/loader.html
+- Doc ID: core/components/ui/loader/loader
+- Keywords: Concorde, supersoniks, core/components/ui/loader/loader, loader, Loader, UI component, sonic-loader, web component, mode, fixed, inline, noDelay, sonic-fetch, sonic-list, currentColor
+
+Loader
+
+sonic-loader shows a loading animation in the page or as a viewport overlay. Default mode is fixed (centered overlay). Use inline inside lists and fetch placeholders. Pair noDelay when the spinner should appear without the default fade-in wait. For sonic-fetch / sonic-list, set the parent loader attribute instead of embedding a tag manually.
+
+Basic example
+
+Inline loaders fit content areas; they use the theme primary color unless currentColor is set.
+
+Mode
+
+inline — ellipsis animation in the document flow. fixed — centered overlay (position: fixed); default when the tag is omitted.
+
+Use the checkbox below to toggle a fixed loader over the page (default mode on sonic-loader).
+
+Inline alignment and color
+
+align only affects mode="inline": left · center (default) · right. Set currentColor so dots follow the host color (for example on a purple parent).
+
+noDelay
+
+By default mode="fixed" waits briefly before fading in. mode="inline" already skips that wait. Set noDelay on fixed (or pass noDelay: true to Loader.show()) to appear immediately.
+
+Accessibility (announce)
+
+The animation is aria-hidden by default so screen readers are not spammed on every fetch. Set announce when the loader is injected after user action (for example a global overlay): the host gets role="status", aria-live="polite", and a localized aria-label (“Loading” / “Chargement en cours”, …). For in-button loading, prefer sonic-button loading and aria-busy on the control—not on the loader.
+
+Show and hide programmatically
+
+Import Loader and call Loader.show() / Loader.hide(). hide() is reference-counted: call it once per show(). With no container, the loader is appended to the theme pop container and mode is always fixed. Pass container and mode: "inline" to mount an inline instance in a specific element.
+
+import { Loader } from "@supersoniks/concorde/core/components/ui/loader/loader";
+
+Loader.show({
+  mode: "fixed",
+  noDelay: false,
+  announce: true,
+  container: document.querySelector("#foo"),
+});
 
-Loader
+Loader.hide();
 
-Inline mode
+Composition
 
-CurrentColor
+sonic-button loading shows an icon spinner and sets aria-busy on the button. sonic-fetch and sonic-list render sonic-loader when their loader attribute is set: true or an empty string maps to fixed; otherwise use inline or fixed.
 
-Align
+ Save changes
 
-Fixed mode
+API reference
 
-Loading button
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| mode | inline · fixed (default fixed) | Layout: in-flow ellipsis vs viewport-centered overlay |
+| noDelay | boolean | Skips the initial fade-in delay before the animation appears |
+| announce | boolean | role="status" and aria-live="polite" with localized loading label when the loader should be announced |
+| align | left · center · right | Horizontal alignment for mode="inline" only (attribute selector; default centered) |
+| currentColor | boolean | Uses currentColor for dot fill instead of --sc-primary |
 
- A loading button
+This component has no slots. The animation markup is internal.
 
-Hide / show programmatically
+Static methods
 
-import {Loader} from "@supersoniks/concorde/core/components/ui/loader/loader";
-  // Show
-  Loader.show({
-    mode:"fixed" // optional : fixed | inline
-    container : document.querySelector('#foo') // optional, default : parent sonic-theme || document.body
-  });
-  // Hide
-  Loader.hide();
+| Method | Description |
+|--------|-------------|
+| Loader.show(conf?) | Mounts the shared loader instance. conf.mode, conf.noDelay, conf.announce, optional conf.container. Without container, uses the theme pop container and forces fixed. |
+| Loader.hide() | Decrements the show counter and removes the instance from the DOM when it reaches zero. |
 
 ---
 
@@ -1824,12 +2456,24 @@ import {Loader} from "@supersoniks/concorde/core/components/ui/loader/loader";
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/menu/menu.html
 - Doc ID: core/components/ui/menu/menu
-- Keywords: Concorde, supersoniks, core/components/ui/menu/menu, menu, Menu, UI component, sonic-menu, web component
+- Keywords: Concorde, supersoniks, core/components/ui/menu/menu, menu, Menu, UI component, sonic-menu, web component, direction, sonic-menu-item, variant, shape, sonic-divider, more, href, pushstate, autoActive
 
 Menu
 
+sonic-menu lays out navigation or actions as a direction row or column of sonic-menu-item entries (ghost variant and block shape by default), optional sonic-divider separators, and overflow content in the more slot (popover “…” trigger). Set href / pushstate / autoActive on each sonic-menu-item—same API as sonic-button—not on the menu host.
+
+Basic example
+
+        Home
+
+        Profile
+
+        Log out
+
 Direction
 
+Default direction is column. Use row for horizontal toolbars or tabs.
+
         Row
 
         Profile
@@ -1852,7 +2496,9 @@ Direction
 
 Size
 
-          XS
+size on the menu propagates to items and the more trigger when they omit their own size.
+
+         XS
 
           Profile
 
@@ -1860,7 +2506,7 @@ Size
 
           Orders
 
-          Small
+         Small
 
           Profile
 
@@ -1868,7 +2514,7 @@ Size
 
           Orders
 
-          Medium
+         Medium
 
           Profile
 
@@ -1876,7 +2522,7 @@ Size
 
           Orders
 
-          Large
+         Large
 
           Profile
 
@@ -1884,7 +2530,7 @@ Size
 
           Orders
 
-          XL
+         XL
 
           Profile
 
@@ -1894,30 +2540,36 @@ Size
 
 Shadow
 
-          None
+Optional shadow wraps the menu surface (no shadow when omitted).
 
-          Small
+         None
 
-          Medium
+         Small
 
-          Large
+         Medium
+
+         Large
 
 Align
 
-        Home
+align propagates to items except square / circle shape.
 
-        Profile
+          Home
 
-        Home
+          Profile
 
-        Profile
+          Home
 
-        Home
+          Profile
 
-        Profile
+          Home
+
+          Profile
 
 More
 
+Assign nodes to slot="more" to show the overflow popover. The trigger appears only when the slot has content. Icon orientation follows direction (vertical ellipsis in a row menu).
+
         Home
 
         Profile
@@ -1934,6 +2586,8 @@ More
 
 Scrollable
 
+With scrollable, the main slot scrolls with edge fade masks; drag-to-scroll works on pointer devices. When exactly one item is active, the menu scrolls it into view.
+
         Home
 
         Profile
@@ -1968,74 +2622,189 @@ Scrollable
 
           Log out
 
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| direction | column (default) · row | Vertical list or horizontal bar |
+| align | left (default) · center · right | Alignment propagated to items (except square / circle shape) |
+| size | xs · sm · md · lg · xl | Propagated to items and the more trigger when unset on the item |
+| shadow | sm · md · lg | Shadow around the menu; omitted for none |
+| minWidth | CSS length | Minimum width of the container (default 0) |
+| scrollable | boolean | Scroll with edge fade; auto-scroll when a single item is active |
+| moreShape | circle (default) · square | Shape of the more slot trigger button |
+
+| Slot | Description |
+|------|-------------|
+| (default) | Visible items: sonic-menu-item, sonic-divider, nested sonic-menu |
+| more | Popover content for the “…” control; shown only when the slot has assigned nodes |
+
+sonic-menu-item extends sonic-button (defaults: variant="ghost", shape="block"). Use the button docs for type, variant, href, pushstate, autoActive, and item slots.
+
 ---
 
-## Concorde
+## Modal
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/modal/modal.html
 - Doc ID: core/components/ui/modal/modal
-- Keywords: Concorde, supersoniks, core/components/ui/modal/modal, modal, UI component, sonic-modal, web component
+- Keywords: Concorde, supersoniks, core/components/ui/modal/modal, modal, Modal, UI component, sonic-modal, web component, , sonic-modal-title, sonic-modal-subtitle, sonic-modal-content, sonic-modal-actions, show(), hideModal, hide(), forceAction
 
 Modal
 
-      Simple modal
+sonic-modal presents focused content in a   overlay with backdrop, enter/exit animation, and a built-in close control. Compose sonic-modal-title / sonic-modal-subtitle / sonic-modal-content / sonic-modal-actions, or use the default slot. Call show() on the element to open; use hideModal on action buttons or hide() from script. Set forceAction when dismissal must go through explicit actions only. Imperative dialogs: Modal.create() (also window.SonicModal).
+
+Basic example
+
+Click the trigger to open. sonic-modal-actions lays out footer buttons; hideModal closes the modal on click. Scope form state with formDataProvider on sonic-modal-actions so child sonic-button elements share one publisher.
 
-       Lorem ipsum dolor sit amet  +33
-       Donec sed vestibulum augue.
+      Open modal
 
-        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed eget quam eu mi luctus faucibus.
+        Export ready
+         New
 
-          Click don't close
+       Your report finished processing.
 
-         Confirm
+        Download the CSV now or review the summary in your dashboard before sharing.
 
-Long text
+          Save draft
 
-  Long text
+         Download
 
-       Infos et tarifs
+Scrollable content
 
-             Horaires d’ouverture
-            Du mercredi au samedi de 13h30 à 19h et le dimanche de 13h30 à 18h
-            + horaires spécifiques pour événements ou festivals 
+Long copy scrolls inside the dialog. Default maxHeight is 90vh. Default align is left.
 
-              Billetterie 
-            La participation à certains événements et activités est soumise à un système de billetterie avec achats ou
-            réservations disponibles en ligne ou au guichet.  
+ Venue details
 
-            Les tarifs (Tarif plein / Tarif Réduit / Tarif Spécifique) sont indiqués pour chaque événement et peuvent
-            varier selon la nature de l’événement. Les tarifs sont identiques en ligne et au guichet. Il est néanmoins
-            conseillé de réserver les billets en avance pour s’assurer une place.
+       Hours and tickets
 
-            L’accès au Skatepark, Fablab et Halle C sont soumis à adhésions. Les adhésions sont gratuites et
-            nominatives. Elle donnent accès aux espaces dans la limite des places disponibles.
+             Opening hours
+            Wednesday–Saturday, 1:30 p.m.–7:00 p.m.; Sunday, 1:30 p.m.–6:00 p.m.
 
-             + d’infos   billetterie@laconditionpublique.com  +33 (0)328334833 
+             Ticketing
+            Some events require online or box-office reservations. Prices vary by event; booking ahead is recommended when capacity is limited.
 
-             Accès   14, place Faidherbe  59100 Roubaix  Métro / Tram : Arrêt
-            Eurotéléport, Ligne 2  Bus / V’Lille : Arrêt Condition Publique 
+             Contact
+            tickets@example.com · +33 3 28 33 48 33
 
-            Accès handicapés : nous contacter avant votre venue au 03 28 33 48 33 ou par mail
-            billetterie@laconditionpublique.com
+             Access
+            14 Place Faidherbe, 59100 Roubaix
+            Metro line 2, Eurotéléport stop
 
 Force action
 
-  Force action to close
+With forceAction, backdrop click, Escape, and the default close button are disabled. Provide sonic-modal-actions (or sonic-modal-close) so users can finish the flow.
 
-       Do you want some cookies ?
+ Cookie consent
 
-        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed eget quam eu mi luctus faucibus.
+       Allow analytics cookies?
 
-          Nope
-         Hell yes !
+        We use cookies to measure traffic and improve the product. You can change this later in settings.
+
+         Decline
+         Accept
 
 Custom dimensions
 
-  Custom width
+Set width / height / maxWidth / maxHeight (CSS lengths). On narrow viewports the panel becomes a bottom sheet. Use rounded="none" for edge-to-edge media.
+
+ Image preview
 
 Fullscreen
 
-  Fullscreen
+fullscreen fills the viewport and hides the backdrop.
+
+ Fullscreen
+
+Programmatic creation
+
+Use Modal.create(options) when there is no modal in the template—for confirmations, toasts that need a follow-up, or one-off flows from script. The modal is appended to the nearest sonic-theme pop container (same as declarative modals), opened automatically, and returns the sonic-modal instance. Set removeOnHide: true to detach it from the DOM after close. In the browser, window.SonicModal is the same class after the module loads.
+
+Pass title / subtitle / content / actions as HTML strings (or Lit template results from application code). Put hideModal on action buttons in the actions string so clicks close the dialog.
+
+      Open programmatic modal
+
+import { Modal } from "@supersoniks/concorde/core/components/ui/modal/modal";
+
+const modal = Modal.create({
+  title: "Delete project?",
+  subtitle: "This cannot be undone.",
+  content: " All files in  Acme HQ  will be removed. ",
+  actions:
+     Cancel
+     Delete
+  ,
+  removeOnHide: true,
+  forceAction: false,
+  maxWidth: "min(100vw, 28rem)",
+});
+
+modal.addEventListener("hidden", () => {
+  console.log("Modal removed from the DOM");
+});
+
+// Or close from script: await modal.hide(); await modal.dispose();
+
+API reference
+
+sonic-modal
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| align | left (default) · center · right | Align title and slotted content |
+| maxWidth | CSS length (default min(100vw, 40rem)) | Dialog max width |
+| maxHeight | CSS length (default 90vh) | Scrollable body max height |
+| width | CSS length (default 100%) | Dialog width |
+| height | CSS length (default fit-content) | Dialog height |
+| paddingX · paddingY | CSS length | Override content padding (--sc-modal-px / --sc-modal-py) |
+| zIndex | CSS number | Stacking order (default 990) |
+| effect | slide (default) · fade · none | Open/close animation |
+| fullscreen | boolean | Full viewport; no backdrop |
+| forceAction | boolean | Disable overlay, Escape, and default close button |
+| noCloseButton | boolean | Hide built-in close when not forceAction |
+| closeButtonType | sonic-button type | Style of built-in close |
+| visible | boolean | When toggled, opens or closes the dialog |
+| removeOnHide | boolean | Remove element from DOM after close |
+| removeHashOnHide | boolean | Clear URL hash on close |
+| closeOnLocationChange | boolean | Close when app location changes |
+| resetDataProviderOnHide | string | Reset named formDataProvider on close |
+| rounded | none | Square dialog corners (useful for full-bleed media) |
+
+| Slot | Description |
+|------|-------------|
+| (default) | Additional markup alongside structured children |
+
+| Event | Description |
+|-------|-------------|
+| show | Fired when open animation completes |
+| hide | Fired when close starts |
+| hidden | Fired when close finishes |
+
+Methods: show() · hide() · dispose() (hide and remove). Static Modal.create(options) appends a modal to the theme pop container and opens it. options / styleSheet are JavaScript-only.
+
+sonic-modal-title · sonic-modal-subtitle · sonic-modal-content
+
+| Slot | Description |
+|------|-------------|
+| (default) | Title, subtitle, or main body content |
+
+sonic-modal-actions
+
+| Slot | Description |
+|------|-------------|
+| (default) | Footer actions (typically sonic-button) |
+
+Put hideModal on a sonic-button to close the parent modal on click. Ancestor formDataProvider on this element is inherited by child form controls.
+
+sonic-modal-close
+
+Rendered automatically unless forceAction or noCloseButton is set. Calls hide() on the parent modal.
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| type | sonic-button type | Close button color |
+| reset | string | Passed to inner sonic-button reset |
+| translation | UI label object | Overrides default close aria-label |
 
 ---
 
@@ -2043,103 +2812,237 @@ Fullscreen
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/pop/pop.html
 - Doc ID: core/components/ui/pop/pop
-- Keywords: Concorde, supersoniks, core/components/ui/pop/pop, pop, Pop, UI component, sonic-pop, web component
+- Keywords: Concorde, supersoniks, core/components/ui/pop/pop, pop, Pop, UI component, sonic-pop, web component, slot="content", manual, placement, bottom, top, left, right, -start
 
 Pop
 
+sonic-pop anchors floating panels to a trigger: put the control in the default slot and the panel in slot="content" (menus, forms, custom markup). Click toggles open/closed unless manual is set; default placement is bottom (start-aligned). Position updates while open and flips inside the viewport when space is tight.
+
+Basic example
+
+       Notifications
+
+          Notifications
+
+          Settings
+
 Placement
 
-       Left
+Use top · bottom · left · right for the main axis. Add -start · -center · -end to align along the trigger edge. With no align suffix, content aligns to start. Legacy space syntax (placement="bottom center") still works but is deprecated—prefer bottom-center.
+
+         Left
+
+            Notifications
+
+         Right
+
+            Notifications
+
+         Top
+
+            Notifications
+
+         Bottom
+
+            Notifications
+
+Center-aligned sides
+
+         Bottom center
 
-           Notifications
+            Notifications
 
-       Right
+         Top center
 
-           Notifications
+            Notifications
 
-       Top
+         Left center
 
-           Notifications
+            Notifications
 
-       Bottom
+         Right center
 
-           Notifications
+            Notifications
 
 Shadow
 
-       None
+Default shadow is lg. The shadow applies to the floating content panel.
 
-           Notifications
+         None
 
-       Small
+            Notifications
 
-           Notifications
+         Small
 
-       Medium
+            Notifications
 
-           Notifications
+         Medium
 
-       Large
+            Notifications
+
+         Large
+
+            Notifications
+
+Inline
+
+By default the host is middle-aligned with siblings. Set inline to baseline-align the trigger inside running text.
 
-           Notifications
+      The Concorde flew from Paris to
 
-noToggle
+         New York
 
-       No toggle on click
+           See flights
+           Book a seat
 
-           Notifications
+      in about 3.5 hours.
 
-       Default toggle on click
+No toggle
 
-           Notifications
+With noToggle, a click on the trigger still opens the pop but does not close it when it is already open. Use hide() or an outside click to dismiss.
 
-manual
+         No toggle on click
 
-       Manual doesn't open on click
+            Notifications
 
-         Hourra !
+         Default toggle on click
+
+            Notifications
+
+Manual control
+
+Set manual to disable built-in click and keyboard toggle on the trigger. Call show() and hide() on the element instead. The pop dispatches show when it opens and hide when it closes.
+
+Click Click to open pop to open the panel programmatically.
+
+       Manual trigger
+
+         It worked!
 
       Click to open pop
 
+Keep open on select
+
+By default, a click inside content closes the pop (same as an outside click). Set data-on-select="keep" on the panel or a descendant to keep it open while selecting checkboxes, toggles, or menu items.
+
+         Closes on select
+
+           Option A
+           Option B
+
+         Stays open on select
+
+           Option A
+           Option B
+
+Keyboard and dismissal
+
+ArrowDown on the trigger opens the pop when it is closed. Escape closes the most recently opened pop (capture phase, before ancestors such as sonic-modal) and returns focus to that trigger. Multiple pops on the page stack in open order for Escape.
+
+       Focus me — ArrowDown opens, Escape closes
+
+         First item
+         Second item
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| placement | bottom (default) · top · left · right · top-start · top-center · top-end · bottom-start · bottom-center · bottom-end · left-start · left-center · left-end · right-start · right-center · right-end | Side and alignment relative to the trigger; repositions while open and flips within the viewport |
+| shadow | none · sm · md · lg (default lg) | Box shadow on the content panel |
+| inline | boolean | Baseline-align the host for inline triggers |
+| noToggle | boolean | When open, trigger click does not close the pop |
+| manual | boolean | Disable default trigger toggle; use show() / hide() |
+
+| Slot | Description |
+|------|-------------|
+| (default) | Trigger; listens for click and keydown (ArrowDown opens when closed) unless manual |
+| content | Floating panel; receives focus tabindex="0" while open |
+
+Methods: show() · hide() on the host element.
+
+Events: show · hide (non-bubbling CustomEvent).
+
+Content attribute: data-on-select="keep" on content or descendants prevents close-on-click inside the panel.
+
 ---
 
-## Progress bar
+## Progress
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/progress/progress.html
 - Doc ID: core/components/ui/progress/progress
-- Keywords: Concorde, supersoniks, core/components/ui/progress/progress, progress, Progress bar, UI component, sonic-progress, web component
+- Keywords: Concorde, supersoniks, core/components/ui/progress/progress, progress, Progress, UI component, sonic-progress, web component, value, max, , remaining, invert, sonic-card,  to **, ** (default 
 
-Progress bar
+Progress
 
-Displays an indicator showing the completion progress of a task.
+Shows task completion on a value / max scale via a native   bar. Omit value for an indeterminate loading animation. Put primary copy in the default slot and optional secondary text in remaining; set invert when the bar sits on a colored surface such as sonic-card.
 
-Indeterminate
+Basic example
 
-Remaining
+Set value from 0 to max (default 100). Label text uses the type color.
 
-    80% Used  20% left
+ 50%
 
-Sizes
+Indeterminate
 
-   25%
-   25%
-   25%
-   25%
-   25%
-   25%
-   25%
+With no value, the bar animates until progress is known.
 
 Type
 
-   50%
-   50%
-   50%
-   50%
-   50%
+Semantic color follows type. With no type, behavior is default.
+
+       50%
+       50%
+       50%
+       50%
+       50%
+       50%
+       50%
+
+Size
+
+Bar height scales with typography via size. With no size, font size matches md (1rem).
+
+       25%
+       25%
+       25%
+       25%
+       25%
+       25%
+       25%
+
+Default and remaining slots
+
+The default slot is the main label (left). remaining is right-aligned with lighter weight—use it for “left to complete” copy.
+
+      80% Used  20% left
 
 Invert
 
-   50%
+On tinted backgrounds, invert adjusts track and fill tokens so the bar stays readable (pair with matching type on sonic-card or similar).
+
+         50%
+
+         50%
+
+         50%
+
+         50%
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| value | number | Completion amount; omit for indeterminate state |
+| max | number (default 100) | Upper bound for value |
+| type | default (default) · primary · neutral · warning · info · success · danger | Semantic bar and label color |
+| size | 2xs · xs · sm · md · lg · xl · 2xl · inherit | Typography scale (bar height follows em) |
+| invert | boolean | High-contrast tokens on colored backgrounds |
+
+| Slot | Description |
+|------|-------------|
+| (default) | Primary label below the bar (left) |
+| remaining | Secondary label below the bar (right) |
 
 ---
 
@@ -2147,11 +3050,15 @@ Invert
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/table/table.html
 - Doc ID: core/components/ui/table/table
-- Keywords: Concorde, supersoniks, core/components/ui/table/table, table, Table, UI component, sonic-table, web component
+- Keywords: Concorde, supersoniks, core/components/ui/table/table, table, Table, UI component, sonic-table, web component, sonic-tr, sonic-th, sonic-td, size, maxHeight, sonic-thead, sonic-tbody, sonic-list
 
 Table
 
-Basic usage
+sonic-table lays out tabular data with composable sonic-tr / sonic-th / sonic-td children. The root applies shared typography via size, scrolls horizontally when content overflows, and optionally caps height with maxHeight. Pair with sonic-thead and sonic-tbody for structure and with sonic-list to render fetched rows.
+
+Basic example
+
+A header row plus body rows is enough for static tables; sonic-thead / sonic-tbody are optional for simple layouts.
 
          Id
          Name
@@ -2169,7 +3076,9 @@ Basic usage
          Emma Wong
          emma.wong@reqres.in
 
-List / fetch
+List and fetch
+
+Place sonic-list inside sonic-tbody so each item template renders a sonic-tr. sonic-list sets row metadata (even / odd / last) on sonic-tr for striping and borders.
 
            Id
            Name
@@ -2179,6 +3088,8 @@ List / fetch
 
 Size
 
+Default font size is md (omit size). Sizes follow the shared scale (2xs … 2xl).
+
           2xs
 
           xs
@@ -2197,6 +3108,8 @@ Size
 
 Bordered
 
+Set bordered on sonic-table for an outer frame and horizontal rules between rows.
+
            Id
            Name
            Email
@@ -2213,7 +3126,9 @@ Bordered
            Emma Wong
            emma.wong@reqres.in
 
-MaxHeight
+Max height
+
+maxHeight applies to the scroll container (for example 8rem), so the body scrolls vertically while the table can still scroll horizontally.
 
            Id
            Name
@@ -2223,36 +3138,34 @@ MaxHeight
 
 Type
 
-Values available : primary, info, success, warning, danger
+Set type on sonic-th / sonic-td / sonic-tr for semantic text color (primary · info · success · warning · danger · neutral · default).
+
+         Attribute type set on
+         sonic-th
 
-           Attribute type set on
-           sonic-th
+         Attribute type set on
+         sonic-td
 
-           Attribute type set on
-           sonic-td
+         Attribute type set on
+         sonic-tr
 
-           Attribute type set on
-           sonic-tr
+Colspan and rowspan
 
-Colspan / rowspan
+Use colSpan and rowSpan on sonic-th or sonic-td (maps to colspan / rowspan on the cell).
 
-           colspan : 2
+           colspan: 2
            cell
 
            cell
            cell
-           rowspan : 2
+           rowspan: 2
 
            cell
            cell
 
-Cell style attributes
+Cell alignment and width
 
-The following attributes will be used to set the style of the component :
-- align
-- minWidth
-- maxWidth
-- width
+align sets horizontal alignment (left · center · right). minWidth / maxWidth / width set inline dimensions on the cell. vAlign is available on sonic-td only.
 
            align
            minWidth
@@ -2271,12 +3184,12 @@ The following attributes will be used to set the style of the component :
 
            right
            20rem
-           5rem - Lorem ipsum dolor
-           15rem - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam porta sollicitudin mollis. Curabitur sit amet nibh diam. Vivamus a pharetra mauris.
+           5rem — Lorem ipsum dolor
+           15rem — Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
-Responsive
+Responsive layout
 
-Every table is responsive by default
+Tables scroll horizontally by default when columns exceed the viewport. Use minWidth on wide columns to preserve readable line length.
 
            Id
            Name
@@ -2285,9 +3198,11 @@ Every table is responsive by default
 
                $lastname ">
 
-                hasellus suscipit vulputate lacus, in tempor turpis aliquam vel. Nunc eleifend, velit id ultrices elementum, ipsum felis porttitor dui, id laoreet diam nulla sed urna.
+                Phasellus suscipit vulputate lacus, in tempor turpis aliquam vel. Nunc eleifend, velit id ultrices elementum, ipsum felis porttitor dui, id laoreet diam nulla sed urna.
 
-Sticky header
+Sticky header and caption
+
+sonic-th uses position: sticky with top: 0 inside the table. For page-level sticky headers, set noCustomScroll on sonic-table and position sonic-thead (for example class="sticky top-16"). Add sonic-caption for a table title below the grid.
 
            Company
            Contact
@@ -2306,18 +3221,6 @@ Sticky header
            3
            40€
 
-           Ernst Handel
-           Roland Mendel
-           Austria
-           4
-           40€
-
-           Island Trading
-           Helen Bennett
-           UK
-           1
-           40€
-
            Laughing Bacchus Winecellars
            Yoshi Tannamuri
            Canada
@@ -2330,42 +3233,165 @@ Sticky header
            20
            40€
 
-           Alfreds Futterkiste
-           Maria Anders
-           Germany
-           2
-           40€
+       Table caption
 
-           Centro comercial Moctezuma
-           no information yet
-           3
-           40€
+API reference
 
-           Ernst Handel
-           Roland Mendel
-           Austria
-           4
-           40€
+sonic-table
 
-           Island Trading
-           Helen Bennett
-           UK
-           1
-           40€
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| size | 2xs · xs · sm · md · lg · xl · 2xl · inherit (default md) | Scales table font size via shared size tokens |
+| bordered | boolean | Outer border and row dividers |
+| noCustomScroll | boolean | Disables custom scrollbar styling on the horizontal scroll container |
+| rounded | boolean | Reflected on the host; no default table styles |
+| maxHeight | CSS length | Max height on the scroll container; enables vertical scrolling |
 
-           Laughing Bacchus Winecellars
-           Yoshi Tannamuri
-           Canada
-           0
-           40€
+| Slot | Description |
+|------|-------------|
+| (default) | Table sections and rows (sonic-thead, sonic-tbody, sonic-tr, …) |
 
-           Magazzini Alimentari Riuniti
-           Giovanni Rovelli
-           Italy
-           20
-           40€
+sonic-thead · sonic-tbody · sonic-tfoot
+
+| Slot | Description |
+|------|-------------|
+| (default) | Row elements (sonic-tr) |
+
+sonic-tbody wraps slotted rows in a native   and applies zebra / hover backgrounds to sonic-tr children.
+
+sonic-caption
+
+| Slot | Description |
+|------|-------------|
+| (default) | Caption text rendered as table-caption |
+
+sonic-tr
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| type | default · primary · info · success · warning · danger · neutral | Semantic text color for the row |
+| even | boolean | Striping background; usually set by sonic-list metadata |
+| odd | boolean | Alternate striping background; usually set by sonic-list |
+| last | boolean | Removes bottom cell border on the last row when bordered |
+
+| Slot | Description |
+|------|-------------|
+| (default) | Header or data cells (sonic-th / sonic-td) |
+
+sonic-th
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| type | default · primary · info · success · warning · danger · neutral | Semantic text color |
+| align | left · center · right | Horizontal text alignment |
+| colSpan | number | Column span |
+| rowSpan | number | Row span |
+| minWidth | CSS length | Minimum cell width |
+| maxWidth | CSS length | Maximum cell width |
+| width | CSS length | Cell width |
+| noBorder | boolean | Removes the bottom border under the header cell |
+
+| Slot | Description |
+|------|-------------|
+| (default) | Header label content |
+
+sonic-td
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| type | default · primary · info · success · warning · danger · neutral | Semantic text color |
+| align | left · center · right | Horizontal text alignment |
+| vAlign | CSS vertical-align value | Vertical alignment |
+| colSpan | number | Column span |
+| rowSpan | number | Row span |
+| minWidth | CSS length | Minimum cell width |
+| maxWidth | CSS length | Maximum cell width |
+| width | CSS length | Cell width |
+
+| Slot | Description |
+|------|-------------|
+| (default) | Cell content |
+
+---
+
+## Theme
+
+- URL: https://concorde.supersoniks.org/crawl/core/components/ui/theme/theme.html
+- Doc ID: core/components/ui/theme/theme
+- Keywords: Concorde, supersoniks, core/components/ui/theme/theme, theme, Theme, UI component, sonic-theme, web component, --sc-*, theme="custom", light, dark, auto, color, font, bg-base
+
+Theme
+
+sonic-theme wraps a Concorde UI: it registers --sc- design tokens and provides the default slot for your app. With no theme attribute (or theme="custom"), only shared primitives and your overrides apply—built-in light / dark / auto palettes are opt-in. Set color and font when the host should carry base text and typography; add Tailwind bg-base and block (or min-h-screen) on the tag for a full surface fill. Popovers, modals, and toasts mount under the nearest connected theme (see Pop container). Import @supersoniks/concorde/theme once at the app entry. For the full public token list and brand overrides, see Customization.
+
+Basic example
+
+Wrap interactive components so tokens and overlays resolve from one root.
+
+       Save changes
+
+Theme mode
+
+Default: omit theme or set theme="custom". The host loads core tokens (--sc-rounded, shadows, form defaults, …) and any --sc- you set; it does not apply the built-in light or dark palette.
+
+Set theme to light or dark for Concorde’s preset palettes. Set theme="auto" to follow prefers-color-scheme (light palette until the OS prefers dark).
 
-       table caption
+         theme="light"
+
+           Primary
+           Success
+           Danger
+
+         theme="dark"
+
+           Primary
+           Success
+           Danger
+
+Presentation
+
+color sets text from --sc-base-content. font applies --sc-font-family-base, --sc-font-weight-base, and --sc-font-style-base. For the page or shell background, use bg-base on sonic-theme (maps to --sc-base in Tailwind) with block so the host paints the surface. Components keep their own fallbacks when color / font are omitted.
+
+       Body copy inherits base content color and font from the theme host.
+
+Custom tokens
+
+Override primitives on sonic-theme (or :root / a project stylesheet). Derived radii, shadows, and control rounding are computed from tokens such as --sc-rounded—avoid copying long lists of internal variables unless you have a specific need.
+
+       Brand primary
+
+Pop container
+
+Theme.getPopContainer() returns the last connected sonic-theme, or document.body if none is connected. When a theme disconnects, the previous connected instance is adopted. Imperative Modal.create() and declarative sonic-modal use the same container.
+
+        Open modal
+
+         Mounted on theme
+
+          This dialog is appended under the nearest sonic-theme pop container.
+
+           Close
+
+Embedded iframes
+
+On connect, the theme publishes resolved --sc- values and linked font stylesheet URLs (Google Fonts / Adobe Fonts) to the sonic-theme data channel and postMessages them to same-page iframes. Iframes can request a refresh by posting { type: "GetSonicTheme" }.
+
+// Inside the iframe — ask the parent theme to rebroadcast tokens
+window.parent.postMessage({ type: "GetSonicTheme" }, "");
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| theme | omitted · custom (default) · light · dark · auto | Omitted or custom: core tokens and your --sc- only. light / dark: fixed presets. auto: presets follow prefers-color-scheme |
+| color | boolean | Host text color uses --sc-base-content |
+| font | boolean | Host font uses --sc-font-family-base and related base weight/style tokens |
+
+| Slot | Description |
+|------|-------------|
+| (default) | Application markup and Concorde components |
+
+Surface background: Tailwind bg-base on sonic-theme (requires Concorde Tailwind color base → --sc-base).
 
 ---
 
@@ -2373,17 +3399,21 @@ Sticky header
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/toast/toast.html
 - Doc ID: core/components/ui/toast/toast
-- Keywords: Concorde, supersoniks, core/components/ui/toast/toast, toast, Toast, UI component, sonic-toast, web component, success, error, warning, info, preserve: true, dismissForever: true, id, ghost: true
+- Keywords: Concorde, supersoniks, core/components/ui/toast/toast, toast, Toast, UI component, sonic-toast, web component, SonicToast.add(), SonicToast, label, preserve, text, status
 
 Toast
 
-Utilisation de base
+Toasts surface short-lived feedback in a fixed stack (bottom-right in the main window). Queue messages with SonicToast.add() on the global SonicToast class—the host sonic-toast is created automatically. Prefer label for a heading; use preserve or interactive text when the user must read or act before dismiss.
+
+Basic example
+
+Click the button to show a toast.
 
-      Afficher un toast
+      Show toast
 
-Statut
+Status
 
-Les statuts disponibles sont : success, error, warning, info ou vide (par défaut).
+status drives color, icon, and live-region behavior. Omit status or pass an empty string for a neutral toast.
 
         Default
 
@@ -2395,69 +3425,105 @@ Les statuts disponibles sont : success, error, warning, info ou vide (par défau
 
         Info
 
-Avec titre
+Label
+
+Set label for a bold title above text. title still works but is deprecated—use label in new code.
 
-        Toast avec titre
+        Toast with label
 
-        Toast d'erreur avec titre
+        Error with label
 
-Avec contenu HTML
+HTML in text
 
-Le contenu du toast peut contenir du HTML.
+text (and label) can include HTML strings. Links and controls in text automatically enable preserve so the toast does not auto-hide while the user interacts.
 
- HTML  et un  lien cliquable ', status: 'info' })">
-      Toast avec HTML
+ HTML  and an  action link ', status: 'info' })"
+    >
+      Toast with HTML
 
-Persistance
+Preserve
 
-Par défaut, les toasts disparaissent automatiquement. Avec preserve: true, le toast reste affiché jusqu'à ce qu'il soit fermé manuellement.
+Without preserve, toasts auto-hide after about six seconds (timer pauses on hover or focus). Set preserve to keep the toast until the user closes it.
 
-      Toast persistant
+      Persistent toast
 
-Masquer définitivement
+Dismiss forever
 
-Avec dismissForever: true et un id, le toast peut être masqué définitivement. Une fois fermé, il ne réapparaîtra plus même après rechargement de la page.
+With dismissForever and a stable id, closing the toast stores dismissal in localStorage—SonicToast.add skips it on later visits. Duplicate payloads (same fields, ignoring id) are not queued twice.
 
-      Toast avec dismiss forever
+      Dismiss forever
 
-Fantôme
+Ghost
 
-Avec ghost: true, le toast devient semi-transparent et non-interactif.
+ghost renders a semi-transparent, non-interactive toast—useful for loading or background states. SonicToast.removeAll leaves ghost toasts in place.
 
-      Toast ghost
+      Ghost toast
 
-Méthodes de suppression
+Dismissal
 
-Tout supprimer
+Use static helpers to clear the stack from app logic (for example after navigation).
 
-Supprime tous les toasts sauf ceux marqués comme ghost.
+Remove all
 
-       Ajouter toast 1
-       Ajouter toast 2
-       Ajouter toast 3
-       Supprimer tous
+Removes every toast except ghost items.
 
-Supprimer par statut
+       Add toast 1
+       Add toast 2
+       Add toast 3
+       Remove all
 
-Supprime tous les toasts d'un statut spécifique.
+Remove by status
 
        Success
        Error
        Warning
-       Supprimer success
-       Supprimer error
+       Remove success
+       Remove error
+
+Remove temporary items
 
-Supprimer les éléments temporaires
+Removes toasts that are not preserve.
 
-Supprime tous les toasts qui ne sont pas marqués comme preserve.
+       Temporary
 
-       Temporaire
-       Persistant
-       Supprimer temporaires
+        Persistent
 
-Exemple complet
+       Remove temporary
 
-      Toast complet
+Combined options
+
+      Full example
+
+Accessibility
+
+Each toast uses role="alert" for error and role="status" otherwise (with aria-live="polite" when applicable). Status icons are decorative (aria-hidden). The close control has an i18n aria-label. When there is no label, a truncated string aria-label may be derived from plain text.
+
+API reference
+
+Options passed to SonicToast.add(conf):
+
+| Option | Values | Description |
+|----------|---------|-------------|
+| text | string · Lit template | Main body; HTML strings are supported |
+| label | string · Lit template | Optional heading above text |
+| title | string · Lit template | Deprecated alias for label |
+| status | success · error · warning · info ·  (empty) | Semantic styling and live region behavior |
+| id | string · number | Stable id for deduplication and dismissForever (defaults to timestamp) |
+| preserve | boolean | Skip auto-hide; forced when text contains interactive markup |
+| ghost | boolean | Semi-transparent and non-interactive; kept by removeAll |
+| dismissForever | boolean | Persist dismissal in localStorage when closed (requires stable id) |
+| styleSheet | modal style input | Extra adopted styles on the toast item shadow root |
+| useSlot | boolean | Legacy: project text into the light DOM slot |
+
+| Method | Description |
+|--------|-------------|
+| SonicToast.add(conf) | Append a toast; returns the config or null if skipped (dismissed forever or duplicate) |
+| SonicToast.removeAll() | Remove all non-ghost toasts |
+| SonicToast.removeItemsByStatus(status) | Remove toasts matching status |
+| SonicToast.removeItemById(id) | Remove a single toast by id |
+| SonicToast.removeTemporaryItems() | Remove toasts without preserve |
+
+sonic-toast is mounted automatically; sonic-toast-item is internal. In iframes, toasts can delegate to the parent window via postMessage.
 
 ---
 
@@ -2465,25 +3531,29 @@ Exemple complet
 
 - URL: https://concorde.supersoniks.org/crawl/core/components/ui/tooltip/tooltip.html
 - Doc ID: core/components/ui/tooltip/tooltip
-- Keywords: Concorde, supersoniks, core/components/ui/tooltip/tooltip, tooltip, Tooltip, UI component, sonic-tooltip, web component
+- Keywords: Concorde, supersoniks, core/components/ui/tooltip/tooltip, tooltip, Tooltip, UI component, sonic-tooltip, web component, label, placement, top, disabled, bottom, left, right, -start
 
 Tooltip
 
- hover me
+Tooltip shows a short label on hover (and on focus when the trigger can receive focus). Wrap the trigger in the default slot—buttons, icons, or plain text. Default placement is top (center-aligned). An empty label hides the bubble the same way as disabled.
+
+Basic example
+
+       Hover me
 
 Placement
 
-By default, tooltip is centered next to its content
+Use top · bottom · left · right for the main axis. Add -start or -end to align the bubble along the anchor edge.
 
-       Top
+         Top
 
-       Bottom
+         Bottom
 
-       Right
+         Right
 
-       Left
+         Left
 
-More placement
+Aligned placements
 
          Top start
 
@@ -2501,14 +3571,39 @@ More placement
 
          Left end
 
+Label formatting
+
+label supports line breaks (\n in markup or multiline text). Lines are trimmed;   is normalized to spaces. white-space: pre-line preserves breaks in the bubble (max width 18rem).
+
+       Multiline label
+
 Focusable
 
-         Focus or hover non interactive element
+On non-interactive triggers, set focusable so the host gets tabindex="0" and the tooltip opens on keyboard focus as well as hover.
+
+      Focus or hover this text
 
 Disabled
 
        Tooltip disabled
 
+Accessibility
+
+The bubble uses popover="hint" (non-modal, no pointer capture). Prefer focusable when the slotted content is not already focusable. When the Popover API is unavailable, the host falls back to the native title attribute with a single-line label. Opacity transitions respect prefers-reduced-motion.
+
+API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| label | string | Tooltip copy; whitespace-only values suppress the bubble |
+| placement | top (default) · bottom · left · right · top-start · top-end · bottom-start · bottom-end · left-start · left-end · right-start · right-end | Position relative to the trigger; repositions while open |
+| disabled | boolean | Suppress show/hide; sets tabindex="-1" on the host |
+| focusable | boolean | Add tabindex="0" on the host for keyboard access |
+
+| Slot | Description |
+|------|-------------|
+| (default) | Trigger content (hover target) |
+
 ---
 
 ## Data flow
@@ -2808,8 +3903,9 @@ Behavior
 - By default (dynamic: false), the value is read once at connect time and is not updated afterward
 - With { dynamic: true }, the property stays in sync when:
   - an ancestor changes the attribute value
-  - a closer ancestor gains the attribute (that value wins)
-  - the nearest ancestor loses the attribute (falls back to the next one up, or null)
+  - a closer ancestor gains / loses the attribute (fallback / null)
+  - the component is reparented (no extra opt-in) — parent childList only reacts if this node moves
+- Observers are shared (one per ancestor attribute / one per parent) so large lists of sonic-icon stay cheap on Firefox.
 - When dynamic is enabled, updates also propagate to @subscribe / @bind paths that depend on the decorated property (e.g. ${dataProvider})
 
 Dynamic mode
@@ -4612,8 +5708,8 @@ In the HTML of a JS or TS component or in the HTML of the web page containing th
 
 Installation
 
-    For almost all new projects, use  create-concorde-ts-starter .
-   You get Vite + TypeScript + Lit + Tailwind, an example component,  npx concorde enable-short-paths  ready to run, and  yarn ai:sync  for  AI agent skills  ( AGENTS.md , Cursor / JetBrains rules) without extra setup.
+ For almost all new projects, use  create-concorde-ts-starter
+ You get Vite + TypeScript + Lit + Tailwind, an example component,  npx concorde enable-short-paths  ready to run, and  yarn ai:sync  for  AI agent skills  ( AGENTS.md , Cursor / JetBrains rules) without extra setup.
 
 Starter
 
@@ -5076,7 +6172,7 @@ Introduction
 What is Concorde?
 
 Based on lit.dev, Concorde is a collection of web components for shared apps and websites.
-Build UIs without tying components to a specific host stack, while keeping visual consistency through a small set of CSS variables.
+Build UIs without tying components to a specific host stack, while keeping visual consistency through the smallest set of CSS variables needed to define a theme.
 
 Why and use case
 
@@ -5117,91 +6213,242 @@ The starter runs yarn ai:sync for you. Details: AI agents (skills). Manual Vite
 
 ---
 
-## Adding styles
+## Customization
 
 - URL: https://concorde.supersoniks.org/crawl/docs/_getting-started/theming.html
 - Doc ID: docs/_getting-started/theming
-- Keywords: Concorde, supersoniks, docs/_getting-started/theming, theming, Adding styles, guide, , size, {reflect: true}, :host(), :host([type='primary']){...}, inline, block, display, contents
-
-Adding styles
-
-Normal Behavior
-
-No style crosses the shadow root of a component, except for inheritable properties (which have the "inherit" property possible) and CSS variables.
-Properties integrated via a "slot" remain stylizable in a conventional way.
-
-- During creation / from the inside:
-  - We edit the static "styles" property of the lit component, which can also reference shared and dynamic styles.
-    These styles are scoped and do not impact the outside.
-  - We use CSS variables as the value of properties intended to be customized from the outside.
-    For each variable, we define a default value to have a simple but consistent base style.
-  - We only rewrite inheritable properties with hard values if they are truly specific to the component.
-  - The   tag as a direct child can be used as a last resort, especially if there is a need for particularly dynamic customization. Performance is reduced.
-- During use / from the outside:
-  We define values for inheritable CSS properties (e.g., font-\, color...) using tools like Tailwind.
-  We modify the value of CSS variables used by the component.
-
-Choosing Style Presets via Reactive Properties:
-
-The declaration of reactive properties is useful for selecting a particular configuration that mostly affects a set of properties.
-
-For example, a size property (xs, sm, md, xl) will affect margins, font, line heights to align them with the corresponding CSS vars, which can be customized using the methods mentioned earlier if necessary.
+- Keywords: Concorde, supersoniks, docs/_getting-started/theming, theming, Customization, guide, , :root, theme="custom", --sc-*, theme="light", "dark", "auto", auto, prefers-color-scheme
+
+Customization
+
+Theme-first customization
+
+Concorde components ship with default styles (fallback values in each component and in  ).
+You do not need to define any CSS variables to get a usable UI.
+
+To align the kit with your brand, override only the essential theme tokens on  , on :root, or in a project stylesheet.
+Concorde derives radius steps, button/input rounding, shadows, and most per-component layout from these primitives—do not copy long lists of derived variables unless you have a specific need.
+
+import "@supersoniks/concorde/theme";
+
+| Attribute | Effect |
+|-----------|--------|
+| (omit) \| theme="custom" | Default: core tokens + your --sc-; no built-in light/dark palette |
+| theme="light" \| "dark" \| "auto" | Opt-in presets; auto follows prefers-color-scheme |
+| class="bg-base block" (Tailwind) | Page/surface background (--sc-base) |
+| color | Text color (--sc-base-content) |
+| font | Base font family/weight (--sc-font-family-base, etc.) |
+
+Popovers, modals, and toasts mount under the nearest  .
+
+Customization example
+
+Example (full brand override on   or :root). Set every essential token below; derived radii and shadows still come from the theme engine—only --sc-rounded is listed here.
+
+sonic-theme {
+  / Semantic fills /
+  --sc-primary: #353429;
+  --sc-secondary: #f43f5e;
+  --sc-info: #7c3aed;
+  --sc-danger: #d71839;
+  --sc-warning: #f97316;
+  --sc-success: #10b981;
+  --sc-contrast: #111;
+
+  / Text/icons on semantic fills /
+  --sc-primary-content: #fff;
+  --sc-secondary-content: #fff;
+  --sc-info-content: #fff;
+  --sc-danger-content: #fff;
+  --sc-warning-content: #fff;
+  --sc-success-content: #fff;
+  --sc-contrast-content: #fff;
+
+  / Neutral fills /
+  --sc-base: #fff;
+  --sc-base-50: #f6f6f5;
+  --sc-base-100: #ededec;
+  --sc-base-200: #d7d7d4;
+  --sc-base-300: #c8c7c4;
+  --sc-base-400: #a8a7a2;
+  --sc-base-500: #94938c;
+  --sc-base-600: #76756c;
+  --sc-base-700: #59584e;
+  --sc-base-800: #47463b;
+  --sc-base-900: #353429;
+
+  / Text/icons on neutral surfaces /
+  --sc-base-content: var(--sc-base-900);
+
+  / Typography /
+  --sc-font-family-base: "Oswald", system-ui, -apple-system, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+  --sc-headings-font-family: "alternate-gothic-compressed", system-ui, sans-serif;
+  --sc-headings-line-height: 1.1;
+  --sc-headings-font-weight: bold;
+  --sc-headings-text-transform: none;
+
+  / Shape (primitive only) /
+  --sc-rounded: 0;
+
+  / Forms /
+  --sc-border-width: 0.2rem;
+  --sc-form-height: 2em;
+  --sc-input-bg: var(--sc-base);
+  --sc-input-color: var(--sc-base-content);
+  --sc-input-border-color: var(--sc-input-color);
+  --sc-input-active-bg: var(--sc-primary);
+  --sc-input-active-color: var(--sc-primary-content);
+  --sc-input-active-border-color: var(--sc-primary);
+}
 
-It is recommended to use the {reflect: true} property for reactive properties that have an associated style on the :host(). For example: :host([type='primary']){...}
+  Palette generator: concordecolors
 
-☢️ Caution: Passing class names via reactive properties / HTML attributes of the component should be avoided as it can quickly lead to difficult-to-manage situations.
+Without these overrides, components keep Concorde’s per-component fallbacks. Built-in light/dark palettes apply only when you set theme="light", theme="dark", or theme="auto".
 
-CSS "display" Property
+What we intentionally avoid: large public --sc-alert- / --sc-badge- APIs or ::part() styling hooks on most components. Prefer attributes (type, status, size, …) and the theme tokens above.
 
-By default, the display property is inline.
-Therefore, be careful to define it according to the needs, as one might mistakenly expect it to be block as with a regular  .
+Only essential CSS variables (public theme API)
 
-☢️ Caution: Defining the display property as contents may seem attractive at first, but:
+These are the smallest set we recommend customizing. Everything else should stay internal to the theme or to components (--sc private variables, attributes like type, size, variant).
 
-- It almost always leads to the creation of wrappers to style the content (instead of using :host).
-- It is no longer possible to directly add classes to the component or style it from the outside.
-  Ultimately, the amount of code to write increases significantly.
+Surfaces and foreground
 
-TAILWIND Functional Classes
+Tokens without a -content suffix are fill / background colors.
+Tokens with -content are text and icons on top of the matching fill (solid buttons, badges, alerts, etc.).
 
-tailwind has been integrated into Concorde and is available in scoped components (with Shadow DOM).
-To use it, you need to import the following:
+Neutral fills
 
-import { tailwind } from "@supersoniks/concorde/la-billetterie/ui/theme/theme";
+| Variable | Role |
+|----------|------|
+| --sc-base | Main surface / page background |
+| --sc-base-50 … --sc-base-900 | Neutral scale (borders, subtle backgrounds, muted UI) |
 
-Then include the tailwind style in the static styles property of the component:
+Neutral foreground
 
-static styles = [tailwind];
+| Variable | Role |
+|----------|------|
+| --sc-base-content | Default body text and icons on neutral surfaces |
 
-Finally, use it in the HTML within the render function:
+Semantic fills
 
- A paragraph with margin
+| Variable | Role |
+|----------|------|
+| --sc-primary | Primary actions, links, emphasis |
+| --sc-secondary | Secondary brand accent (when used) |
+| --sc-info, --sc-success, --sc-warning, --sc-danger | Status and feedback |
+| --sc-contrast | High-contrast fills (e.g. on media) |
 
-The colors from Concorde's theme are referenced in Tailwind's theme.
+Semantic foreground
 
-Operation without Shadow DOM
+| Variable | Role |
+|----------|------|
+| --sc-primary-content, --sc-secondary-content, … | Text/icons on the matching semantic fill (--sc-primary, etc.) |
 
-Usefulness
+Shape
 
-This operation is particularly useful when it comes to adding behavior to a simple existing element.
-It may also become necessary to establish compatibility with a traditional JS library.
+| Variable | Role |
+|----------|------|
+| --sc-rounded | Single primitive corner radius; the theme computes --sc-rounded-sm, --sc-btn-rounded, --sc-input-rounded, etc. |
 
-For example, with a text input:
+Typography
 
-- Trigger automatic data or filter update when typing text.
-- Automatic formatting.
-- Constraints that cannot be handled by native methods.
+| Variable | Role |
+|----------|------|
+| --sc-font-family-base | Body UI text |
+| --sc-font-weight-base, --sc-font-style-base | Optional |
+| --sc-headings-font-family, --sc-headings-line-height, --sc-headings-font-weight, --sc-headings-text-transform | Headings (modal titles, etc.) |
 
-Consequences
+Forms (only if you customize inputs globally)
 
-If there is no shadow DOM (see the noShadowDom property of Subscriber):
+Interactive controls expose a few extra theme-level tokens; prefer these over styling individual inputs from outside.
 
-- Styling using the static "styles" property of the lit component will not be applied.
-- The element and its content can be styled in a traditional manner.
+| Variable | Role |
+|----------|------|
+| --sc-border-width | Default border thickness |
+| --sc-form-height | Control height |
+| --sc-input-bg, --sc-input-color, --sc-input-border-color | Default field chrome |
+| --sc-input-active-bg, --sc-input-active-color, --sc-input-active-border-color | Focus/active state |
 
-For example, the components queue, list, and fetch do not have a shadow DOM.
+---
 
-ℹ️ Note: Specifically in this case, it may be useful to set the display property to contents.
+Tailwind in new components ?
+
+Set  tailwind.config.js  to match concorde style token in your custom component.
+
+...
+theme: {
+  borderRadius: {
+    DEFAULT: "var(--sc-rounded)",
+    none: "0",
+    sm: "var(--sc-rounded-sm)",
+    md: "var(--sc-rounded-md)",
+    lg: "var(--sc-rounded-lg)",
+    xl: "var(--sc-rounded-xl)",
+    full: "9999px",
+  },
+  boxShadow: {
+    DEFAULT: "var(--sc-shadow)",
+    none: "none",
+    sm: "var(--sc-shadow-sm)",
+    md: "var(--sc-shadow-md)",
+    lg: "var(--sc-shadow-lg)",
+    xl: "var(--sc-shadow-xl)",
+  },
+  colors: {
+    transparent: "transparent",
+    current: "currentColor",
+    content: "var(--sc-base-content)",
+    base: "var(--sc-base)",
+    neutral: {
+      0: "var(--sc-base)",
+      50: "var(--sc-base-50)",
+      100: "var(--sc-base-100)",
+      200: "var(--sc-base-200)",
+      300: "var(--sc-base-300)",
+      400: "var(--sc-base-400)",
+      500: "var(--sc-base-500)",
+      600: "var(--sc-base-600)",
+      700: "var(--sc-base-700)",
+      800: "var(--sc-base-800)",
+      900: "var(--sc-base-900)",
+      content: "var(--sc-base)",
+    },
+    primary: {
+      DEFAULT: "var(--sc-primary)",
+      content: "var(--sc-primary-content)",
+    },
+    success: {
+      DEFAULT: "var(--sc-success)",
+      content: "var(--sc-success-content)",
+    },
+    danger: {
+      DEFAULT: "var(--sc-danger)",
+      content: "var(--sc-danger-content)",
+    },
+    warning: {
+      DEFAULT: "var(--sc-warning)",
+      content: "var(--sc-warning-content)",
+    },
+    info: {
+      DEFAULT: "var(--sc-info)",
+      content: "var(--sc-info-content)",
+    },
+    contrast: {
+      DEFAULT: "var(--sc-contrast)",
+      content: "var(--sc-contrast-content)",
+    },
+  },
+  extend: {
+    borderWidth: {
+      DEFAULT: "var(--sc-border-width)",
+    },
+    fontFamily: {
+      headings: ["var(--sc-headings-font-family, var(--sc-font-family-base, sans-serif))"],
+      body: ["var(--sc-font-family-base)"],
+      monospace: ["var(--sc-font-family-monospace, monospace)"],
+    }
+  }
 
 ---