@supersoniks/concorde 5.1.2 → 5.1.3-immutable.2

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

@@ -1,65 +1,158 @@
 # Table
 
-**`sonic-table`** lays out tabular data with **`sonic-tr`** · **`sonic-th`** · **`sonic-td`** children, optionally grouped in **`sonic-thead`** · **`sonic-tbody`** · **`sonic-tfoot`**. It scrolls horizontally when columns overflow; set **`minWidth`** on wide cells to keep them readable. Render fetched rows with **`sonic-list`**.
+**`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
 
-**`bordered`** adds an outer frame and row dividers. **`sonic-tbody`** stripes and highlights its rows on hover.
+A header row plus body rows is enough for static tables; **`sonic-thead`** / **`sonic-tbody`** are optional for simple layouts.
+
+<sonic-code>
+  <template>
+    <sonic-table>
+      <sonic-tr>
+        <sonic-th>Id</sonic-th>
+        <sonic-th>Name</sonic-th>
+        <sonic-th>Email</sonic-th>
+      </sonic-tr>
+      <sonic-tr>
+        <sonic-td>1</sonic-td>
+        <sonic-td>George Bluth</sonic-td>
+        <sonic-td>george.bluth@reqres.in</sonic-td>
+      </sonic-tr>
+      <sonic-tr>
+        <sonic-td>2</sonic-td>
+        <sonic-td>Janet Weaver</sonic-td>
+        <sonic-td>janet.weaver@reqres.in</sonic-td>
+      </sonic-tr>
+      <sonic-tr>
+        <sonic-td>3</sonic-td>
+        <sonic-td>Emma Wong</sonic-td>
+        <sonic-td>emma.wong@reqres.in</sonic-td>
+      </sonic-tr>
+    </sonic-table>
+  </template>
+</sonic-code>
+
+## 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>
+    <sonic-table>
+      <sonic-thead>
+        <sonic-tr>
+          <sonic-th>Id</sonic-th>
+          <sonic-th>Name</sonic-th>
+          <sonic-th>Email</sonic-th>
+        </sonic-tr>
+      </sonic-thead>
+      <sonic-tbody>
+        <sonic-list debug fetch serviceURL="/docs-mock-api" dataProvider="api/users" key="data" displayContents>
+          <template>
+            <sonic-tr>
+              <sonic-td data-bind ::inner-html="$id"></sonic-td>
+              <sonic-td data-bind ::inner-html="$first_name <b>$last_name</b>"></sonic-td>
+              <sonic-td data-bind ::inner-html="$email"></sonic-td>
+            </sonic-tr>
+          </template>
+        </sonic-list>
+      </sonic-tbody>
+    </sonic-table>
+  </template>
+</sonic-code>
+
+## 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">
+      <sonic-table size="2xs" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">2xs</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table size="xs" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">xs</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table size="sm" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">sm</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table size="md" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">md</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">default</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table size="lg" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">lg</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table size="xl" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">xl</sonic-td></sonic-tr>
+      </sonic-table>
+      <sonic-table size="2xl" bordered>
+        <sonic-tr><sonic-td class="w-[5rem]">2xl</sonic-td></sonic-tr>
+      </sonic-table>
+    </div>
+  </template>
+</sonic-code>
+
+## Bordered
+
+Set **`bordered`** on **`sonic-table`** for an outer frame and horizontal rules between rows.
 
 <sonic-code>
   <template>
     <sonic-table bordered>
       <sonic-thead>
         <sonic-tr>
-          <sonic-th>Flight</sonic-th>
-          <sonic-th>Destination</sonic-th>
-          <sonic-th>Status</sonic-th>
+          <sonic-th>Id</sonic-th>
+          <sonic-th>Name</sonic-th>
+          <sonic-th>Email</sonic-th>
         </sonic-tr>
       </sonic-thead>
       <sonic-tbody>
         <sonic-tr>
-          <sonic-td>CN 001</sonic-td>
-          <sonic-td>New York JFK</sonic-td>
-          <sonic-td>Boarding</sonic-td>
+          <sonic-td>1</sonic-td>
+          <sonic-td>George Bluth</sonic-td>
+          <sonic-td>george.bluth@reqres.in</sonic-td>
         </sonic-tr>
         <sonic-tr>
-          <sonic-td>CN 014</sonic-td>
-          <sonic-td>London LHR</sonic-td>
-          <sonic-td>On time</sonic-td>
+          <sonic-td>2</sonic-td>
+          <sonic-td>Janet Weaver</sonic-td>
+          <sonic-td>janet.weaver@reqres.in</sonic-td>
         </sonic-tr>
         <sonic-tr>
-          <sonic-td>CN 102</sonic-td>
-          <sonic-td>Rio de Janeiro GIG</sonic-td>
-          <sonic-td>Delayed</sonic-td>
+          <sonic-td>3</sonic-td>
+          <sonic-td>Emma Wong</sonic-td>
+          <sonic-td>emma.wong@reqres.in</sonic-td>
         </sonic-tr>
       </sonic-tbody>
     </sonic-table>
   </template>
 </sonic-code>
 
-## List, fetch and max height
+## Max height
 
-Put a **`sonic-list`** with `displayContents` inside **`sonic-tbody`** and render one **`sonic-tr`** per item; the list sets `even` · `odd` · `last` on each row. **`maxHeight`** caps the scroll container so the body scrolls vertically.
+**`maxHeight`** applies to the scroll container (for example `8rem`), so the body scrolls vertically while the table can still scroll horizontally.
 
 <sonic-code>
   <template>
-    <sonic-table maxHeight="10rem">
+    <sonic-table maxHeight="8rem">
       <sonic-thead>
         <sonic-tr>
-          <sonic-th>Time</sonic-th>
-          <sonic-th>Flight</sonic-th>
-          <sonic-th>Destination</sonic-th>
-          <sonic-th>Gate</sonic-th>
+          <sonic-th>Id</sonic-th>
+          <sonic-th>Name</sonic-th>
+          <sonic-th>Email</sonic-th>
         </sonic-tr>
       </sonic-thead>
       <sonic-tbody>
-        <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="flights" key="flights" displayContents>
+        <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="api/users" key="data" displayContents>
           <template>
             <sonic-tr>
-              <sonic-td data-bind ::inner-html="$time"></sonic-td>
-              <sonic-td data-bind ::inner-html="$code"></sonic-td>
-              <sonic-td minWidth="10rem" data-bind ::inner-html="$city <b>$airport</b>"></sonic-td>
-              <sonic-td data-bind ::inner-html="$gate"></sonic-td>
+              <sonic-td data-bind ::inner-html="$id"></sonic-td>
+              <sonic-td data-bind ::inner-html="$first_name <b>$last_name</b>"></sonic-td>
+              <sonic-td data-bind ::inner-html="$email"></sonic-td>
             </sonic-tr>
           </template>
         </sonic-list>
@@ -68,41 +161,23 @@ Put a **`sonic-list`** with `displayContents` inside **`sonic-tbody`** and rende
   </template>
 </sonic-code>
 
-## Size
-
-With no **`size`**, the table uses `md`.
-
-<sonic-code>
-  <template>
-    <div class="grid grid-cols-4 gap-3">
-      <sonic-table size="2xs" bordered><sonic-tr><sonic-td>2xs</sonic-td></sonic-tr></sonic-table>
-      <sonic-table size="xs" bordered><sonic-tr><sonic-td>xs</sonic-td></sonic-tr></sonic-table>
-      <sonic-table size="sm" bordered><sonic-tr><sonic-td>sm</sonic-td></sonic-tr></sonic-table>
-      <sonic-table size="md" bordered><sonic-tr><sonic-td>md</sonic-td></sonic-tr></sonic-table>
-      <sonic-table size="lg" bordered><sonic-tr><sonic-td>lg</sonic-td></sonic-tr></sonic-table>
-      <sonic-table size="xl" bordered><sonic-tr><sonic-td>xl</sonic-td></sonic-tr></sonic-table>
-      <sonic-table size="2xl" bordered><sonic-tr><sonic-td>2xl</sonic-td></sonic-tr></sonic-table>
-    </div>
-  </template>
-</sonic-code>
-
 ## Type
 
-**`type`** on **`sonic-tr`** · **`sonic-th`** · **`sonic-td`** sets a semantic text color.
+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">Set on</sonic-th>
+        <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">Set on</sonic-td>
+        <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>Set on</sonic-td>
+        <sonic-td>Attribute type set on</sonic-td>
         <sonic-td>sonic-tr</sonic-td>
       </sonic-tr>
     </sonic-table>
@@ -111,9 +186,11 @@ With no **`size`**, the table uses `md`.
 
 ## 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 bordered>
+    <sonic-table>
       <sonic-tbody>
         <sonic-tr>
           <sonic-td colspan="2" class="bg-info text-neutral-0">colspan: 2</sonic-td>
@@ -133,36 +210,73 @@ With no **`size`**, the table uses `md`.
   </template>
 </sonic-code>
 
-## Alignment and width
+## Cell alignment and width
 
-**`align`** sets horizontal alignment. **`width`** · **`minWidth`** · **`maxWidth`** set the cell dimensions. **`vAlign`** exists on **`sonic-td`** only.
+**`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>
     <sonic-table bordered>
       <sonic-thead>
         <sonic-tr>
-          <sonic-th width="8rem">align</sonic-th>
-          <sonic-th maxWidth="8rem">maxWidth 8rem</sonic-th>
-          <sonic-th>vAlign</sonic-th>
+          <sonic-th width="7rem">align</sonic-th>
+          <sonic-th minWidth="20rem">minWidth</sonic-th>
+          <sonic-th>maxWidth</sonic-th>
+          <sonic-th>width</sonic-th>
         </sonic-tr>
       </sonic-thead>
       <sonic-tbody>
         <sonic-tr>
-          <sonic-td align="left">left</sonic-td>
-          <sonic-td maxWidth="8rem">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</sonic-td>
-          <sonic-td vAlign="top">top</sonic-td>
+          <sonic-td align="left">Left</sonic-td>
+          <sonic-td>20rem</sonic-td>
+          <sonic-td>5rem</sonic-td>
+          <sonic-td>15rem</sonic-td>
         </sonic-tr>
         <sonic-tr>
           <sonic-td align="center">center</sonic-td>
-          <sonic-td maxWidth="8rem">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</sonic-td>
-          <sonic-td vAlign="middle">middle</sonic-td>
+          <sonic-td>20rem</sonic-td>
+          <sonic-td maxWidth="5rem">5rem</sonic-td>
+          <sonic-td>15rem</sonic-td>
         </sonic-tr>
         <sonic-tr>
           <sonic-td align="right">right</sonic-td>
-          <sonic-td maxWidth="8rem">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</sonic-td>
-          <sonic-td vAlign="bottom">bottom</sonic-td>
+          <sonic-td>20rem</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
+
+Tables scroll horizontally by default when columns exceed the viewport. Use **`minWidth`** on wide columns to preserve readable line length.
+
+<sonic-code>
+  <template>
+    <sonic-table bordered>
+      <sonic-thead>
+        <sonic-tr>
+          <sonic-th>Id</sonic-th>
+          <sonic-th>Name</sonic-th>
+          <sonic-th>Email</sonic-th>
+          <sonic-th>Comment</sonic-th>
         </sonic-tr>
+      </sonic-thead>
+      <sonic-tbody>
+        <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>
+              <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">
+                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-tbody>
     </sonic-table>
   </template>
@@ -170,14 +284,16 @@ With no **`size`**, the table uses `md`.
 
 ## Sticky header and caption
 
-**`sonic-th`** cells stick to the top of the scroll container. To stick the header to the page instead, set **`noCustomScroll`** (which removes the scroll container) and position **`sonic-thead`** yourself. **`sonic-caption`** adds a 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.
 
 <sonic-code>
   <template>
     <sonic-table bordered noCustomScroll>
       <sonic-thead class="sticky top-16">
         <sonic-tr>
-          <sonic-th minWidth="12rem">Product</sonic-th>
+          <sonic-th minWidth="max(20ch,12rem)">Company</sonic-th>
+          <sonic-th type="success">Contact</sonic-th>
+          <sonic-th>Country</sonic-th>
           <sonic-th align="center">Quantity</sonic-th>
           <sonic-th align="right">Price</sonic-th>
           <sonic-th></sonic-th>
@@ -185,37 +301,54 @@ With no **`size`**, the table uses `md`.
       </sonic-thead>
       <sonic-tbody>
         <sonic-tr>
-          <sonic-td>Desk lamp</sonic-td>
+          <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 align="right">40€</sonic-td>
+          <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 align="center">3</sonic-td>
+          <sonic-td align="right">40€</sonic-td>
           <sonic-td align="right">
-            <sonic-button shape="circle" variant="outline" size="sm" aria-label="Edit">
+            <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>Notebook</sonic-td>
+          <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">8 €</sonic-td>
+          <sonic-td align="right">40€</sonic-td>
           <sonic-td align="right">
-            <sonic-button shape="circle" variant="outline" size="sm" aria-label="Edit">
+            <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>Headphones</sonic-td>
-          <sonic-td align="center">1</sonic-td>
-          <sonic-td align="right" type="danger">120 €</sonic-td>
+          <sonic-td>Magazzini Alimentari Riuniti</sonic-td>
+          <sonic-td>Giovanni Rovelli</sonic-td>
+          <sonic-td type="danger">Italy</sonic-td>
+          <sonic-td align="center">20</sonic-td>
+          <sonic-td align="right">40€</sonic-td>
           <sonic-td align="right">
-            <sonic-button shape="circle" variant="outline" size="sm" aria-label="Edit">
+            <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>Cart contents</sonic-caption>
+      <sonic-caption>Table caption</sonic-caption>
     </sonic-table>
   </template>
 </sonic-code>
@@ -226,41 +359,72 @@ With no **`size`**, the table uses `md`.
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `size` | `2xs` … `2xl` · `inherit` (default `md`) | Font size |
+| `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 |
-| `maxHeight` | CSS length | Max height of the scroll container |
-| `noCustomScroll` | boolean | Remove the scroll container and its custom scrollbar |
+| `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)* | Sections, rows and caption |
+| *(default)* | Row elements (`sonic-tr`) |
+
+`sonic-tbody` wraps slotted rows in a native `<tbody>` and applies zebra / hover backgrounds to **`sonic-tr`** children.
 
-### `sonic-thead` · `sonic-tbody` · `sonic-tfoot` · `sonic-caption`
+### `sonic-caption`
 
-No attributes. Default slot only. `sonic-tbody` stripes and highlights its rows.
+| Slot | Description |
+|------|-------------|
+| *(default)* | Caption text rendered as `table-caption` |
 
 ### `sonic-tr`
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `type` | `default` · `primary` · `info` · `success` · `warning` · `danger` · `neutral` | Text color |
-| `even` · `odd` | boolean | Striping background; set by `sonic-list` |
-| `last` | boolean | No bottom border; set by `sonic-list` |
+| `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)* | `sonic-th` or `sonic-td` cells |
+| *(default)* | Header label content |
 
-### `sonic-th` · `sonic-td`
+### `sonic-td`
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `type` | same as `sonic-tr` | Text color |
-| `align` | `left` · `center` · `right` | Horizontal alignment |
-| `vAlign` | CSS `vertical-align` | Vertical alignment (`sonic-td` only) |
-| `colSpan` · `rowSpan` | number | Column and row span |
-| `width` · `minWidth` · `maxWidth` | CSS length | Cell dimensions |
-| `noBorder` | boolean | No bottom border (`sonic-th` only) |
+| `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 |
 |------|-------------|

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

@@ -1,9 +1,11 @@
 # Theme
 
-**`sonic-theme`** is the root element of a Concorde UI: it holds the `--sc-*` design tokens, optionally applies a built-in palette, and is where popovers, modals and toasts are mounted. Import `@supersoniks/concorde/theme` once at the app entry and wrap your app in it. Token names and brand overrides are covered in [Theming](/docs/getting-started/theming).
+**`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">
@@ -14,7 +16,9 @@
 
 ## Theme mode
 
-With no `theme` (or `theme="custom"`), only the core tokens and your own `--sc-*` overrides apply. `light` and `dark` apply the built-in palettes; `auto` switches between them with `prefers-color-scheme`.
+**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>
@@ -39,21 +43,39 @@ With no `theme` (or `theme="custom"`), only the core tokens and your own `--sc-*
   </template>
 </sonic-code>
 
-## Text color and font
+## Presentation
 
-`color` sets the host text color to `--sc-base-content`. `font` applies the base font family, weight and style tokens. Both are off by default. To paint the background, add the Tailwind classes `block` and `bg-base` on the host.
+**`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 rounded-lg">
-      <p>Body copy inherits the base content color and font from the theme.</p>
+    <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
 
-Overlays such as `sonic-modal` are appended to the last connected `sonic-theme`, or to `document.body` when there is none. `Theme.getPopContainer()` returns that element.
+**`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>
@@ -76,10 +98,11 @@ Overlays such as `sonic-modal` are appended to the last connected `sonic-theme`,
 
 ## Embedded iframes
 
-On connect, the theme posts its resolved `--sc-*` values and linked Google Fonts / Adobe Fonts stylesheets to every iframe on the page (message type `SonicTheme`). An iframe can ask for them again:
+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>
@@ -88,10 +111,12 @@ window.parent.postMessage({ type: "GetSonicTheme" }, "*");
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `theme` | `custom` (default) · `light` · `dark` · `auto` | Built-in palette; `custom` applies core tokens and your overrides only |
+| `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 uses the base font family, weight and style tokens |
+| `font` | boolean | Host font uses `--sc-font-family-base` and related base weight/style tokens |
 
 | Slot | Description |
 |------|-------------|
-| *(default)* | Application content |
+| *(default)* | Application markup and Concorde components |
+
+Surface background: Tailwind **`bg-base`** on **`sonic-theme`** (requires Concorde Tailwind color **`base`** → **`--sc-base`**).