@supersoniks/concorde 5.0.4 → 5.0.5

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

@@ -0,0 +1,122 @@
+# 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](#pop-container)). Import **`@supersoniks/concorde/theme`** once at the app entry. For the full public token list and brand overrides, see [Customization](#docs/_getting-started/theming.md/theming).
+
+## Basic example
+
+Wrap interactive components so tokens and overlays resolve from one root.
+
+<sonic-code>
+  <template>
+    <sonic-theme color font class="block bg-base p-6 rounded-lg">
+      <sonic-button type="primary">Save changes</sonic-button>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## 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).
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4 md:grid-cols-2">
+      <sonic-theme theme="light" color font class="block bg-base p-4 rounded-md border border-neutral-200">
+        <p class="text-sm mb-3 opacity-80">theme="light"</p>
+        <div class="flex flex-wrap gap-2">
+          <sonic-badge type="primary">Primary</sonic-badge>
+          <sonic-badge type="success">Success</sonic-badge>
+          <sonic-badge type="danger">Danger</sonic-badge>
+        </div>
+      </sonic-theme>
+      <sonic-theme theme="dark" color font class="block bg-base p-4 rounded-md">
+        <p class="text-sm mb-3 opacity-80">theme="dark"</p>
+        <div class="flex flex-wrap gap-2">
+          <sonic-badge type="primary">Primary</sonic-badge>
+          <sonic-badge type="success">Success</sonic-badge>
+          <sonic-badge type="danger">Danger</sonic-badge>
+        </div>
+      </sonic-theme>
+    </div>
+  </template>
+</sonic-code>
+
+## 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.
+
+<sonic-code>
+  <template>
+    <sonic-theme theme="light" color font class="block bg-base p-6 min-h-[8rem] rounded-lg">
+      <p>Body copy inherits base content color and font from the theme host.</p>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## 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.
+
+<sonic-code>
+  <template>
+    <sonic-theme
+      theme="custom"
+      color
+      font
+      class="block bg-base p-6 rounded-lg"
+      style="--sc-primary: #353429; --sc-rounded: 0.25rem;"
+    >
+      <sonic-button type="primary">Brand primary</sonic-button>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## 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.
+
+<sonic-code>
+  <template>
+    <sonic-theme theme="light" color font class="block bg-base p-4 rounded-lg">
+      <sonic-button onclick="document.getElementById('themePopModal').show()">
+        Open modal
+      </sonic-button>
+      <sonic-modal id="themePopModal">
+        <sonic-modal-title>Mounted on theme</sonic-modal-title>
+        <sonic-modal-content>
+          This dialog is appended under the nearest sonic-theme pop container.
+        </sonic-modal-content>
+        <sonic-modal-actions>
+          <sonic-button hideModal>Close</sonic-button>
+        </sonic-modal-actions>
+      </sonic-modal>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## 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 **`postMessage`**s them to same-page iframes. Iframes can request a refresh by posting **`{ type: "GetSonicTheme" }`**.
+
+<sonic-code language="javascript">
+  <template>
+// Inside the iframe — ask the parent theme to rebroadcast tokens
+window.parent.postMessage({ type: "GetSonicTheme" }, "*");
+  </template>
+</sonic-code>
+
+## 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`**).

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

@@ -1,166 +1,216 @@
 # 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.
 
 <sonic-code>
   <template>
-    <sonic-button onclick="window.SonicToast.add({ text: 'Message de notification simple' })">
-      Afficher un toast
+    <sonic-button onclick="SonicToast.add({ text: 'Simple notification' })">
+      Show toast
     </sonic-button>
   </template>
 </sonic-code>
 
-## 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.
 
 <sonic-code>
   <template>
     <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="window.SonicToast.add({ text: 'Message par défaut', status: '' })">
+      <sonic-button onclick="SonicToast.add({ text: 'Default message', status: '' })">
         Default
       </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Opération réussie !', status: 'success' })">
+      <sonic-button onclick="SonicToast.add({ text: 'Operation succeeded', status: 'success' })">
         Success
       </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Une erreur est survenue', status: 'error' })">
+      <sonic-button onclick="SonicToast.add({ text: 'Something went wrong', status: 'error' })">
         Error
       </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Attention à ce point', status: 'warning' })">
+      <sonic-button onclick="SonicToast.add({ text: 'Check this detail', status: 'warning' })">
         Warning
       </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Information importante', status: 'info' })">
+      <sonic-button onclick="SonicToast.add({ text: 'Helpful context', status: 'info' })">
         Info
       </sonic-button>
     </div>
   </template>
 </sonic-code>
 
-## Avec titre
+## Label
+
+Set **`label`** for a bold title above **`text`**. **`title`** still works but is deprecated—use **`label`** in new code.
 
 <sonic-code>
   <template>
     <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="window.SonicToast.add({ title: 'Succès', text: 'Votre demande a été traitée avec succès.', status: 'success' })">
-        Toast avec titre
+      <sonic-button
+        onclick="SonicToast.add({ label: 'Success', text: 'Your request was processed.', status: 'success' })"
+      >
+        Toast with label
       </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ title: 'Test', text: 'Une erreur est survenue lors du traitement.', status: 'error' })">
-        Toast d'erreur avec titre
+      <sonic-button
+        onclick="SonicToast.add({ label: 'Error', text: 'Processing failed. Try again.', status: 'error' })"
+      >
+        Error with label
       </sonic-button>
     </div>
   </template>
 </sonic-code>
 
-## 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.
 
 <sonic-code>
   <template>
-    <sonic-button onclick="window.SonicToast.add({ text: 'Message avec <strong>HTML</strong> et un <a href=&quot;#&quot;>lien cliquable</a>', status: 'info' })">
-      Toast avec HTML
+    <sonic-button
+      onclick="SonicToast.add({ text: 'Message with <strong>HTML</strong> and an <a href=&quot;#&quot;>action link</a>', status: 'info' })"
+    >
+      Toast with HTML
     </sonic-button>
   </template>
 </sonic-code>
 
+## Preserve
 
-## Persistance
-
-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.
 
 <sonic-code>
   <template>
-    <sonic-button onclick="window.SonicToast.add({ text: 'Ce toast ne disparaîtra pas automatiquement', status: 'info', preserve: true })">
-      Toast persistant
+    <sonic-button
+      onclick="SonicToast.add({ text: 'This toast stays until you dismiss it', status: 'info', preserve: true })"
+    >
+      Persistent toast
     </sonic-button>
   </template>
 </sonic-code>
 
-## 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.
 
 <sonic-code>
   <template>
-    <sonic-button onclick="window.SonicToast.add({ id: 'unique-toast-id', text: 'Ce toast peut être masqué définitivement', status: 'info', dismissForever: true })">
-      Toast avec dismiss forever
+    <sonic-button
+      onclick="SonicToast.add({ id: 'unique-toast-id', text: 'Dismiss forever hides this across reloads', status: 'info', dismissForever: true })"
+    >
+      Dismiss forever
     </sonic-button>
   </template>
 </sonic-code>
 
-## 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.
 
 <sonic-code>
   <template>
-    <sonic-button onclick="window.SonicToast.add({ text: 'Toast fantôme (semi-transparent)', status: 'info', ghost: true })">
-      Toast ghost
+    <sonic-button
+      onclick="SonicToast.add({ text: 'Ghost toast (non-interactive)', status: 'info', ghost: true })"
+    >
+      Ghost toast
     </sonic-button>
   </template>
 </sonic-code>
 
+## Dismissal
 
-## Méthodes de suppression
+Use static helpers to clear the stack from app logic (for example after navigation).
 
-### Tout supprimer
+### Remove all
 
-Supprime tous les toasts sauf ceux marqués comme `ghost`.
+Removes every toast except **`ghost`** items.
 
 <sonic-code>
   <template>
     <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast 1', status: 'info' })">Ajouter toast 1</sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast 2', status: 'success' })">Ajouter toast 2</sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast 3', status: 'warning' })">Ajouter toast 3</sonic-button>
-      <sonic-button onclick="window.SonicToast.removeAll()">Supprimer tous</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Toast 1', status: 'info' })">Add toast 1</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Toast 2', status: 'success' })">Add toast 2</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Toast 3', status: 'warning' })">Add toast 3</sonic-button>
+      <sonic-button onclick="SonicToast.removeAll()">Remove all</sonic-button>
     </div>
   </template>
 </sonic-code>
 
-### Supprimer par statut
-
-Supprime tous les toasts d'un statut spécifique.
+### Remove by status
 
 <sonic-code>
   <template>
     <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast success', status: 'success' })">Success</sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast error', status: 'error' })">Error</sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast warning', status: 'warning' })">Warning</sonic-button>
-      <sonic-button onclick="window.SonicToast.removeItemsByStatus('success')">Supprimer success</sonic-button>
-      <sonic-button onclick="window.SonicToast.removeItemsByStatus('error')">Supprimer error</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Success toast', status: 'success' })">Success</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Error toast', status: 'error' })">Error</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Warning toast', status: 'warning' })">Warning</sonic-button>
+      <sonic-button onclick="SonicToast.removeItemsByStatus('success')">Remove success</sonic-button>
+      <sonic-button onclick="SonicToast.removeItemsByStatus('error')">Remove error</sonic-button>
     </div>
   </template>
 </sonic-code>
 
-### Supprimer les éléments temporaires
+### Remove temporary items
 
-Supprime tous les toasts qui ne sont pas marqués comme `preserve`.
+Removes toasts that are not **`preserve`**.
 
 <sonic-code>
   <template>
     <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast temporaire', status: 'info' })">Temporaire</sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast persistant', status: 'success', preserve: true })">Persistant</sonic-button>
-      <sonic-button onclick="window.SonicToast.removeTemporaryItems()">Supprimer temporaires</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Temporary toast', status: 'info' })">Temporary</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Persistent toast', status: 'success', preserve: true })">
+        Persistent
+      </sonic-button>
+      <sonic-button onclick="SonicToast.removeTemporaryItems()">Remove temporary</sonic-button>
     </div>
   </template>
 </sonic-code>
 
-## Exemple complet
+## Combined options
 
 <sonic-code>
   <template>
-    <sonic-button onclick="window.SonicToast.add({ 
+    <sonic-button
+      onclick="SonicToast.add({
       id: 'welcome-toast',
-      title: 'Bienvenue',
-      text: 'Bienvenue sur notre plateforme ! Vous pouvez commencer à explorer les fonctionnalités.',
+      label: 'Welcome',
+      text: 'Welcome to the platform. Explore the docs to get started.',
       status: 'success',
       dismissForever: true
-    })">
-      Toast complet
+    })"
+    >
+      Full example
     </sonic-button>
   </template>
 </sonic-code>
 
+## 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`**.

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

@@ -1,71 +1,97 @@
 # Tooltip
 
+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
+
 <sonic-code>
   <template>
-    <sonic-tooltip label="Tada : Text appears">hover me</sonic-tooltip>
+    <sonic-tooltip label="Additional context on hover">
+      <sonic-button variant="outline">Hover me</sonic-button>
+    </sonic-tooltip>
   </template>
 </sonic-code>
 
 ## 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.
 
 <sonic-code>
   <template>
-    <sonic-tooltip placement="top" label="Top text">
-      <sonic-button>Top</sonic-button>
-    </sonic-tooltip>
-    <sonic-tooltip placement="bottom" label="Bottom text">
-      <sonic-button>Bottom</sonic-button>
-    </sonic-tooltip>
-     <sonic-tooltip placement="right" label="Right text">
-      <sonic-button>Right</sonic-button>
-    </sonic-tooltip>
-    <sonic-tooltip placement="left" label="Left text">
-      <sonic-button>Left</sonic-button>
-    </sonic-tooltip>
+    <div class="flex flex-wrap gap-2">
+      <sonic-tooltip placement="top" label="Top">
+        <sonic-button>Top</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="bottom" label="Bottom">
+        <sonic-button>Bottom</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="right" label="Right">
+        <sonic-button>Right</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="left" label="Left">
+        <sonic-button>Left</sonic-button>
+      </sonic-tooltip>
+    </div>
   </template>
 </sonic-code>
 
-## More placement
+### Aligned placements
+
 <sonic-code>
   <template>
     <div class="flex gap-3 flex-wrap">
-      <sonic-tooltip placement="top-start" label="My tooltip">
+      <sonic-tooltip placement="top-start" label="Top start">
         <sonic-button class="size-40 bg-neutral-200 rounded-lg">Top start</sonic-button>
       </sonic-tooltip>
-      <sonic-tooltip placement="top-end" label="My tooltip">
+      <sonic-tooltip placement="top-end" label="Top end">
         <sonic-button class="size-40 bg-neutral-200 rounded-lg">Top end</sonic-button>
       </sonic-tooltip>
-      <sonic-tooltip placement="bottom-start" label="My tooltip">
+      <sonic-tooltip placement="bottom-start" label="Bottom start">
         <sonic-button class="size-40 bg-neutral-200 rounded-lg">Bottom start</sonic-button>
       </sonic-tooltip>
-      <sonic-tooltip placement="bottom-end" label="My tooltip">
+      <sonic-tooltip placement="bottom-end" label="Bottom end">
         <sonic-button class="size-40 bg-neutral-200 rounded-lg">Bottom end</sonic-button>
       </sonic-tooltip>
-      <sonic-tooltip placement="right-start" label="My tooltip">
+      <sonic-tooltip placement="right-start" label="Right start">
         <sonic-button class="size-40 bg-neutral-200 rounded-lg">Right start</sonic-button>
       </sonic-tooltip>
-      <sonic-tooltip placement="right-end" label="My tooltip">
+      <sonic-tooltip placement="right-end" label="Right end">
         <sonic-button class="size-40 bg-neutral-200 rounded-lg">Right end</sonic-button>
       </sonic-tooltip>
-      <sonic-tooltip placement="left-start" label="My tooltip">
+      <sonic-tooltip placement="left-start" label="Left start">
         <sonic-button class="size-40 bg-neutral-200 rounded-lg">Left start</sonic-button>
       </sonic-tooltip>
-      <sonic-tooltip placement="left-end" label="My tooltip">
+      <sonic-tooltip placement="left-end" label="Left end">
         <sonic-button class="size-40 bg-neutral-200 rounded-lg">Left end</sonic-button>
       </sonic-tooltip>
     </div>
   </template>
 </sonic-code>
 
+## Label formatting
+
+**`label`** supports line breaks (`\n` in markup or multiline text). Lines are trimmed; **`&nbsp;`** is normalized to spaces. **`white-space: pre-line`** preserves breaks in the bubble (max width **18rem**).
+
+<sonic-code>
+  <template>
+    <sonic-tooltip label="First line&#10;Second line">
+      <sonic-button variant="outline">Multiline label</sonic-button>
+    </sonic-tooltip>
+  </template>
+</sonic-code>
 
 ## Focusable
 
+On non-interactive triggers, set **`focusable`** so the host gets **`tabindex="0"`** and the tooltip opens on keyboard focus as well as hover.
+
 <sonic-code>
   <template>
-    <sonic-tooltip focusable label="The Concorde made its first transatlantic crossing on September 26, 1973">
-      <sonic-icon library="iconoir" name="chat-bubble-question"></sonic-icon> Focus or hover non interactive element 
+    <sonic-tooltip
+      focusable
+      label="The Concorde made its first transatlantic crossing on September 26, 1973"
+    >
+      <sonic-icon library="iconoir" name="chat-bubble-question"></sonic-icon>
+      Focus or hover this text
     </sonic-tooltip>
   </template>
 </sonic-code>
@@ -74,9 +100,25 @@ By default, tooltip is centered next to its content
 
 <sonic-code>
   <template>
-    <sonic-tooltip disabled label="Disabled text">
+    <sonic-tooltip disabled label="Not shown">
       <sonic-button>Tooltip disabled</sonic-button>
     </sonic-tooltip>
   </template>
 </sonic-code>
 
+## 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) |

package/docs/src/docs/_decorators/ancestor-attribute.md

@@ -69,8 +69,9 @@ This decorator is particularly useful for:
 - 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

package/docs/src/docs/_getting-started/concorde-outside.md

@@ -1,8 +1,8 @@
 # Installation
 
-<sonic-alert status="success" label="Recommended — use the starter" size="xl" background>
-  <p><strong>For almost all new projects, use <a href="https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter">create-concorde-ts-starter</a>.</strong></p>
-  <p>You get Vite + TypeScript + Lit + Tailwind, an example component, <code>npx concorde enable-short-paths</code> ready to run, and <code>yarn ai:sync</code> for <a href="#docs/_getting-started/ai-agents.md/ai-agents">AI agent skills</a> (<code>AGENTS.md</code>, Cursor / JetBrains rules) without extra setup.</p>
+<sonic-alert status="info" label="Recommended — use the starter" background>
+<p>For almost all new projects, use <a href="https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter">create-concorde-ts-starter</a></p>
+<p>You get Vite + TypeScript + Lit + Tailwind, an example component, <code>npx concorde enable-short-paths</code> ready to run, and <code>yarn ai:sync</code> for <a href="#docs/_getting-started/ai-agents.md/ai-agents">AI agent skills</a> (<code>AGENTS.md</code>, Cursor / JetBrains rules) without extra setup.</p>
 </sonic-alert>
 
 ## Starter

package/docs/src/docs/_getting-started/start.md

@@ -3,7 +3,7 @@
 ## What is Concorde?
 
 Based on **[lit.dev](https://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