@supersoniks/concorde 5.0.3 → 5.0.5

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

@@ -1,6 +1,10 @@
 # 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.
 
 <sonic-code>
   <template>
@@ -29,7 +33,9 @@
   </template>
 </sonic-code>
 
-## 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.
 
 <sonic-code>
   <template>
@@ -39,7 +45,7 @@
           <sonic-th>Id</sonic-th>
           <sonic-th>Name</sonic-th>
           <sonic-th>Email</sonic-th>
-        </sonic-tr> 
+        </sonic-tr>
       </sonic-thead>
       <sonic-tbody>
         <sonic-list debug fetch serviceURL="/docs-mock-api" dataProvider="api/users" key="data" displayContents>
@@ -50,7 +56,7 @@
               <sonic-td data-bind ::inner-html="$email"></sonic-td>
             </sonic-tr>
           </template>
-        <sonic-list>
+        </sonic-list>
       </sonic-tbody>
     </sonic-table>
   </template>
@@ -58,6 +64,8 @@
 
 ## Size
 
+Default font size is **`md`** (omit **`size`**). Sizes follow the shared scale (`2xs` … `2xl`).
+
 <sonic-code>
   <template>
     <div class="grid grid-cols-4 gap-3">
@@ -91,6 +99,8 @@
 
 ## Bordered
 
+Set **`bordered`** on **`sonic-table`** for an outer frame and horizontal rules between rows.
+
 <sonic-code>
   <template>
     <sonic-table bordered>
@@ -122,7 +132,9 @@
   </template>
 </sonic-code>
 
-## MaxHeight
+## Max height
+
+**`maxHeight`** applies to the scroll container (for example `8rem`), so the body scrolls vertically while the table can still scroll horizontally.
 
 <sonic-code>
   <template>
@@ -132,10 +144,10 @@
           <sonic-th>Id</sonic-th>
           <sonic-th>Name</sonic-th>
           <sonic-th>Email</sonic-th>
-        </sonic-tr> 
+        </sonic-tr>
       </sonic-thead>
       <sonic-tbody>
-        <sonic-list  fetch serviceURL="/docs-mock-api" dataProvider="api/users" key="data" displayContents>
+        <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="api/users" key="data" displayContents>
           <template>
             <sonic-tr>
               <sonic-td data-bind ::inner-html="$id"></sonic-td>
@@ -143,7 +155,7 @@
               <sonic-td data-bind ::inner-html="$email"></sonic-td>
             </sonic-tr>
           </template>
-        <sonic-list>
+        </sonic-list>
       </sonic-tbody>
     </sonic-table>
   </template>
@@ -151,42 +163,43 @@
 
 ## 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`).
 
 <sonic-code>
   <template>
     <sonic-table bordered>
-        <sonic-tr>
-          <sonic-th type="info">Attribute type set on</sonic-th>
-          <sonic-th type="info">sonic-th</sonic-th>
-        </sonic-tr>
-        <sonic-tr>
-          <sonic-td type="danger">Attribute type set on</sonic-td>
-          <sonic-td type="danger">sonic-td</sonic-td>
-        </sonic-tr>
-        <sonic-tr type="success">
-          <sonic-td>Attribute type set on</sonic-td>
-          <sonic-td>sonic-tr</sonic-td>
-        </sonic-tr>
-      </sonic-tbody>
+      <sonic-tr>
+        <sonic-th type="info">Attribute type set on</sonic-th>
+        <sonic-th type="info">sonic-th</sonic-th>
+      </sonic-tr>
+      <sonic-tr>
+        <sonic-td type="danger">Attribute type set on</sonic-td>
+        <sonic-td type="danger">sonic-td</sonic-td>
+      </sonic-tr>
+      <sonic-tr type="success">
+        <sonic-td>Attribute type set on</sonic-td>
+        <sonic-td>sonic-tr</sonic-td>
+      </sonic-tr>
     </sonic-table>
   </template>
 </sonic-code>
 
-## Colspan / rowspan
+## Colspan and rowspan
+
+Use **`colSpan`** and **`rowSpan`** on **`sonic-th`** or **`sonic-td`** (maps to `colspan` / `rowspan` on the cell).
 
 <sonic-code>
   <template>
-    <sonic-table >
+    <sonic-table>
       <sonic-tbody>
         <sonic-tr>
-          <sonic-td colspan="2" class="bg-info text-neutral-0">colspan : 2</sonic-td>
+          <sonic-td colspan="2" class="bg-info text-neutral-0">colspan: 2</sonic-td>
           <sonic-td>cell</sonic-td>
         </sonic-tr>
         <sonic-tr>
           <sonic-td>cell</sonic-td>
           <sonic-td>cell</sonic-td>
-          <sonic-td rowspan="2" class="bg-success text-neutral-0">rowspan : 2</sonic-td>
+          <sonic-td rowspan="2" class="bg-success text-neutral-0">rowspan: 2</sonic-td>
         </sonic-tr>
         <sonic-tr>
           <sonic-td>cell</sonic-td>
@@ -197,13 +210,9 @@ Values available : primary, info, success, warning, danger
   </template>
 </sonic-code>
 
-## 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.
 
 <sonic-code>
   <template>
@@ -232,17 +241,17 @@ The following attributes will be used to set the style of the component :
         <sonic-tr>
           <sonic-td align="right">right</sonic-td>
           <sonic-td>20rem</sonic-td>
-          <sonic-td>5rem - Lorem ipsum dolor</sonic-td>
-          <sonic-td width="60rem">15rem - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam porta sollicitudin mollis. Curabitur sit amet nibh diam. Vivamus a pharetra mauris.</sonic-td>
+          <sonic-td maxWidth="5rem">5rem — Lorem ipsum dolor</sonic-td>
+          <sonic-td width="60rem">15rem — Lorem ipsum dolor sit amet, consectetur adipiscing elit.</sonic-td>
         </sonic-tr>
+      </sonic-tbody>
     </sonic-table>
   </template>
 </sonic-code>
 
+## Responsive layout
 
-## Responsive
-
-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.
 
 <sonic-code>
   <template>
@@ -253,7 +262,7 @@ Every table is responsive by default
           <sonic-th>Name</sonic-th>
           <sonic-th>Email</sonic-th>
           <sonic-th>Comment</sonic-th>
-        </sonic-tr> 
+        </sonic-tr>
       </sonic-thead>
       <sonic-tbody>
         <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="api/users" key="data" displayContents>
@@ -263,18 +272,19 @@ Every table is responsive by default
               <sonic-td minWidth="10rem" data-bind ::inner-html="$first_name <b>$last_name</b>"></sonic-td>
               <sonic-td data-bind ::inner-html="$email"></sonic-td>
               <sonic-td minWidth="40rem">
-                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.
               </sonic-td>
             </sonic-tr>
           </template>
-        <sonic-list>
+        </sonic-list>
       </sonic-tbody>
     </sonic-table>
   </template>
 </sonic-code>
 
+## Sticky header and caption
 
-## Sticky header
+**`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.
 
 <sonic-code>
   <template>
@@ -296,53 +306,21 @@ Every table is responsive by default
           <sonic-td>Germany</sonic-td>
           <sonic-td align="center">2</sonic-td>
           <sonic-td align="right">40€</sonic-td>
-          <sonic-td td align="right"
-            ><sonic-button shape="circle" variant="outline" size="sm">
-              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon
-            ></sonic-button>
+          <sonic-td align="right">
+            <sonic-button shape="circle" variant="outline" size="sm">
+              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon>
+            </sonic-button>
           </sonic-td>
         </sonic-tr>
         <sonic-tr>
           <sonic-td>Centro comercial Moctezuma</sonic-td>
-          <sonic-td
-            colspan="2"
-            align="center"
-            class="
-              text-center
-              text-neutral-400
-            "
-            >no information yet</sonic-td
-          >
+          <sonic-td colspan="2" align="center" class="text-center text-neutral-400">no information yet</sonic-td>
           <sonic-td align="center">3</sonic-td>
           <sonic-td align="right">40€</sonic-td>
-          <sonic-td td align="right"
-            ><sonic-button shape="circle" variant="outline" size="sm">
-              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon
-            ></sonic-button>
-          </sonic-td>
-        </sonic-tr>
-        <sonic-tr>
-          <sonic-td>Ernst Handel</sonic-td>
-          <sonic-td>Roland Mendel</sonic-td>
-          <sonic-td>Austria</sonic-td>
-          <sonic-td align="center">4</sonic-td>
-          <sonic-td align="right">40€</sonic-td>
-          <sonic-td td align="right"
-            ><sonic-button shape="circle" variant="outline" size="sm">
-              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon
-            ></sonic-button>
-          </sonic-td>
-        </sonic-tr>
-        <sonic-tr>
-          <sonic-td>Island Trading</sonic-td>
-          <sonic-td>Helen Bennett</sonic-td>
-          <sonic-td>UK</sonic-td>
-          <sonic-td align="center">1</sonic-td>
-          <sonic-td align="right">40€</sonic-td>
-          <sonic-td td align="right"
-            ><sonic-button shape="circle" variant="outline" size="sm">
-              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon
-            ></sonic-button>
+          <sonic-td align="right">
+            <sonic-button shape="circle" variant="outline" size="sm">
+              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon>
+            </sonic-button>
           </sonic-td>
         </sonic-tr>
         <sonic-tr type="warning">
@@ -351,10 +329,10 @@ Every table is responsive by default
           <sonic-td>Canada</sonic-td>
           <sonic-td align="center">0</sonic-td>
           <sonic-td align="right">40€</sonic-td>
-          <sonic-td td align="right"
-            ><sonic-button shape="circle" variant="outline" size="sm">
-              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon
-            ></sonic-button>
+          <sonic-td align="right">
+            <sonic-button shape="circle" variant="outline" size="sm">
+              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon>
+            </sonic-button>
           </sonic-td>
         </sonic-tr>
         <sonic-tr>
@@ -363,93 +341,91 @@ Every table is responsive by default
           <sonic-td type="danger">Italy</sonic-td>
           <sonic-td align="center">20</sonic-td>
           <sonic-td align="right">40€</sonic-td>
-          <sonic-td td align="right"
-            ><sonic-button shape="circle" variant="outline" size="sm">
-              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon
-            ></sonic-button>
-          </sonic-td>
-        </sonic-tr>
-        <sonic-tr>
-          <sonic-td>Alfreds Futterkiste</sonic-td>
-          <sonic-td>Maria Anders</sonic-td>
-          <sonic-td>Germany</sonic-td>
-          <sonic-td align="center">2</sonic-td>
-          <sonic-td align="right">40€</sonic-td>
-          <sonic-td td align="right"
-            ><sonic-button shape="circle" variant="outline" size="sm">
-              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon
-            ></sonic-button>
-          </sonic-td>
-        </sonic-tr>
-        <sonic-tr>
-          <sonic-td>Centro comercial Moctezuma</sonic-td>
-          <sonic-td
-            colspan="2"
-            align="center"
-            class="
-              text-center
-              text-neutral-400
-            "
-            >no information yet</sonic-td
-          >
-          <sonic-td align="center">3</sonic-td>
-          <sonic-td align="right">40€</sonic-td>
-          <sonic-td td align="right"
-            ><sonic-button shape="circle" variant="outline" size="sm">
-              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon
-            ></sonic-button>
-          </sonic-td>
-        </sonic-tr>
-        <sonic-tr>
-          <sonic-td>Ernst Handel</sonic-td>
-          <sonic-td>Roland Mendel</sonic-td>
-          <sonic-td>Austria</sonic-td>
-          <sonic-td align="center">4</sonic-td>
-          <sonic-td align="right">40€</sonic-td>
-          <sonic-td td align="right"
-            ><sonic-button shape="circle" variant="outline" size="sm">
-              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon
-            ></sonic-button>
-          </sonic-td>
-        </sonic-tr>
-        <sonic-tr>
-          <sonic-td>Island Trading</sonic-td>
-          <sonic-td>Helen Bennett</sonic-td>
-          <sonic-td>UK</sonic-td>
-          <sonic-td align="center">1</sonic-td>
-          <sonic-td align="right">40€</sonic-td>
-          <sonic-td td align="right"
-            ><sonic-button shape="circle" variant="outline" size="sm">
-              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon
-            ></sonic-button>
-          </sonic-td>
-        </sonic-tr>
-        <sonic-tr type="warning">
-          <sonic-td>Laughing Bacchus Winecellars</sonic-td>
-          <sonic-td>Yoshi Tannamuri</sonic-td>
-          <sonic-td>Canada</sonic-td>
-          <sonic-td align="center">0</sonic-td>
-          <sonic-td align="right">40€</sonic-td>
-          <sonic-td td align="right"
-            ><sonic-button shape="circle" variant="outline" size="sm">
-              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon
-            ></sonic-button>
-          </sonic-td>
-        </sonic-tr>
-        <sonic-tr>
-          <sonic-td>Magazzini Alimentari Riuniti</sonic-td>
-          <sonic-td>Giovanni Rovelli</sonic-td>
-          <sonic-td>Italy</sonic-td>
-          <sonic-td align="center">20</sonic-td>
-          <sonic-td align="right">40€</sonic-td>
-          <sonic-td td align="right"
-            ><sonic-button shape="circle" variant="outline" size="sm">
-              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon
-            ></sonic-button>
+          <sonic-td align="right">
+            <sonic-button shape="circle" variant="outline" size="sm">
+              <sonic-icon library="iconoir" name="edit-pencil" size="lg"></sonic-icon>
+            </sonic-button>
           </sonic-td>
         </sonic-tr>
       </sonic-tbody>
-      <sonic-caption>table caption</sonic-caption>
+      <sonic-caption>Table caption</sonic-caption>
     </sonic-table>
   </template>
-</sonic-code>
+</sonic-code>
+
+## API reference
+
+### `sonic-table`
+
+| 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 |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Table sections and rows (`sonic-thead`, `sonic-tbody`, `sonic-tr`, …) |
+
+### `sonic-thead` · `sonic-tbody` · `sonic-tfoot`
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Row elements (`sonic-tr`) |
+
+`sonic-tbody` wraps slotted rows in a native `<tbody>` 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 |

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`**).