@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

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

@@ -1,158 +1,65 @@
 # Table
 
-**`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.
+**`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`**.
 
 ## 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>
-    <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.
+**`bordered`** adds an outer frame and row dividers. **`sonic-tbody`** stripes and highlights its rows on hover.
 
 <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>Flight</sonic-th>
+          <sonic-th>Destination</sonic-th>
+          <sonic-th>Status</sonic-th>
         </sonic-tr>
       </sonic-thead>
       <sonic-tbody>
         <sonic-tr>
-          <sonic-td>1</sonic-td>
-          <sonic-td>George Bluth</sonic-td>
-          <sonic-td>george.bluth@reqres.in</sonic-td>
+          <sonic-td>CN 001</sonic-td>
+          <sonic-td>New York JFK</sonic-td>
+          <sonic-td>Boarding</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-td>CN 014</sonic-td>
+          <sonic-td>London LHR</sonic-td>
+          <sonic-td>On time</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-td>CN 102</sonic-td>
+          <sonic-td>Rio de Janeiro GIG</sonic-td>
+          <sonic-td>Delayed</sonic-td>
         </sonic-tr>
       </sonic-tbody>
     </sonic-table>
   </template>
 </sonic-code>
 
-## Max height
+## List, fetch and max height
 
-**`maxHeight`** applies to the scroll container (for example `8rem`), so the body scrolls vertically while the table can still scroll horizontally.
+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.
 
 <sonic-code>
   <template>
-    <sonic-table maxHeight="8rem">
+    <sonic-table maxHeight="10rem">
       <sonic-thead>
         <sonic-tr>
-          <sonic-th>Id</sonic-th>
-          <sonic-th>Name</sonic-th>
-          <sonic-th>Email</sonic-th>
+          <sonic-th>Time</sonic-th>
+          <sonic-th>Flight</sonic-th>
+          <sonic-th>Destination</sonic-th>
+          <sonic-th>Gate</sonic-th>
         </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="flights" key="flights" 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-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-tr>
           </template>
         </sonic-list>
@@ -161,23 +68,41 @@ Set **`bordered`** on **`sonic-table`** for an outer frame and horizontal rules
   </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
 
-Set **`type`** on **`sonic-th`** / **`sonic-td`** / **`sonic-tr`** for semantic text color (`primary` · `info` · `success` · `warning` · `danger` · `neutral` · `default`).
+**`type`** on **`sonic-tr`** · **`sonic-th`** · **`sonic-td`** sets a semantic text color.
 
 <sonic-code>
   <template>
     <sonic-table bordered>
       <sonic-tr>
-        <sonic-th type="info">Attribute type set on</sonic-th>
+        <sonic-th type="info">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">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>Set on</sonic-td>
         <sonic-td>sonic-tr</sonic-td>
       </sonic-tr>
     </sonic-table>
@@ -186,11 +111,9 @@ Set **`type`** on **`sonic-th`** / **`sonic-td`** / **`sonic-tr`** for semantic
 
 ## 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 bordered>
       <sonic-tbody>
         <sonic-tr>
           <sonic-td colspan="2" class="bg-info text-neutral-0">colspan: 2</sonic-td>
@@ -210,73 +133,36 @@ Use **`colSpan`** and **`rowSpan`** on **`sonic-th`** or **`sonic-td`** (maps to
   </template>
 </sonic-code>
 
-## Cell alignment and width
+## Alignment and 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`** sets horizontal alignment. **`width`** · **`minWidth`** · **`maxWidth`** set the cell dimensions. **`vAlign`** exists on **`sonic-td`** only.
 
 <sonic-code>
   <template>
     <sonic-table bordered>
       <sonic-thead>
         <sonic-tr>
-          <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-th width="8rem">align</sonic-th>
+          <sonic-th maxWidth="8rem">maxWidth 8rem</sonic-th>
+          <sonic-th>vAlign</sonic-th>
         </sonic-tr>
       </sonic-thead>
       <sonic-tbody>
         <sonic-tr>
-          <sonic-td align="left">Left</sonic-td>
-          <sonic-td>20rem</sonic-td>
-          <sonic-td>5rem</sonic-td>
-          <sonic-td>15rem</sonic-td>
+          <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-tr>
         <sonic-tr>
           <sonic-td align="center">center</sonic-td>
-          <sonic-td>20rem</sonic-td>
-          <sonic-td maxWidth="5rem">5rem</sonic-td>
-          <sonic-td>15rem</sonic-td>
+          <sonic-td maxWidth="8rem">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</sonic-td>
+          <sonic-td vAlign="middle">middle</sonic-td>
         </sonic-tr>
         <sonic-tr>
           <sonic-td align="right">right</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-td maxWidth="8rem">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</sonic-td>
+          <sonic-td vAlign="bottom">bottom</sonic-td>
         </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>
@@ -284,16 +170,14 @@ Tables scroll horizontally by default when columns exceed the viewport. Use **`m
 
 ## 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.
+**`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-code>
   <template>
     <sonic-table bordered noCustomScroll>
       <sonic-thead class="sticky top-16">
         <sonic-tr>
-          <sonic-th minWidth="max(20ch,12rem)">Company</sonic-th>
-          <sonic-th type="success">Contact</sonic-th>
-          <sonic-th>Country</sonic-th>
+          <sonic-th minWidth="12rem">Product</sonic-th>
           <sonic-th align="center">Quantity</sonic-th>
           <sonic-th align="right">Price</sonic-th>
           <sonic-th></sonic-th>
@@ -301,54 +185,37 @@ Tables scroll horizontally by default when columns exceed the viewport. Use **`m
       </sonic-thead>
       <sonic-tbody>
         <sonic-tr>
-          <sonic-td>Alfreds Futterkiste</sonic-td>
-          <sonic-td>Maria Anders</sonic-td>
-          <sonic-td>Germany</sonic-td>
+          <sonic-td>Desk lamp</sonic-td>
           <sonic-td align="center">2</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">40 €</sonic-td>
           <sonic-td align="right">
-            <sonic-button shape="circle" variant="outline" size="sm">
+            <sonic-button shape="circle" variant="outline" size="sm" aria-label="Edit">
               <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>Notebook</sonic-td>
           <sonic-td align="center">0</sonic-td>
-          <sonic-td align="right">40€</sonic-td>
+          <sonic-td align="right">8 €</sonic-td>
           <sonic-td align="right">
-            <sonic-button shape="circle" variant="outline" size="sm">
+            <sonic-button shape="circle" variant="outline" size="sm" aria-label="Edit">
               <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 type="danger">Italy</sonic-td>
-          <sonic-td align="center">20</sonic-td>
-          <sonic-td align="right">40€</sonic-td>
+          <sonic-td>Headphones</sonic-td>
+          <sonic-td align="center">1</sonic-td>
+          <sonic-td align="right" type="danger">120 €</sonic-td>
           <sonic-td align="right">
-            <sonic-button shape="circle" variant="outline" size="sm">
+            <sonic-button shape="circle" variant="outline" size="sm" aria-label="Edit">
               <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>Cart contents</sonic-caption>
     </sonic-table>
   </template>
 </sonic-code>
@@ -359,72 +226,41 @@ Tables scroll horizontally by default when columns exceed the viewport. Use **`m
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `size` | `2xs` · `xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `inherit` (default `md`) | Scales table font size via shared size tokens |
+| `size` | `2xs` … `2xl` · `inherit` (default `md`) | Font size |
 | `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`
+| `maxHeight` | CSS length | Max height of the scroll container |
+| `noCustomScroll` | boolean | Remove the scroll container and its custom scrollbar |
 
 | 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.
+| *(default)* | Sections, rows and caption |
 
-### `sonic-caption`
+### `sonic-thead` · `sonic-tbody` · `sonic-tfoot` · `sonic-caption`
 
-| Slot | Description |
-|------|-------------|
-| *(default)* | Caption text rendered as `table-caption` |
+No attributes. Default slot only. `sonic-tbody` stripes and highlights its rows.
 
 ### `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 |
+| `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` |
 
 | Slot | Description |
 |------|-------------|
-| *(default)* | Header label content |
+| *(default)* | `sonic-th` or `sonic-td` cells |
 
-### `sonic-td`
+### `sonic-th` · `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 |
+| `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) |
 
 | Slot | Description |
 |------|-------------|

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

@@ -1,11 +1,9 @@
 # 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).
+**`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).
 
 ## 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">
@@ -16,9 +14,7 @@ Wrap interactive components so tokens and overlays resolve from one root.
 
 ## 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).
+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`.
 
 <sonic-code>
   <template>
@@ -43,39 +39,21 @@ Set **`theme`** to **`light`** or **`dark`** for Concorde’s preset palettes. S
   </template>
 </sonic-code>
 
-## Presentation
+## Text color and font
 
-**`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.
+`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.
 
 <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 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>
   </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.
+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.
 
 <sonic-code>
   <template>
@@ -98,11 +76,10 @@ Override **primitives** on **`sonic-theme`** (or **`:root`** / a project stylesh
 
 ## 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" }`**.
+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:
 
 <sonic-code language="javascript">
   <template>
-// Inside the iframe — ask the parent theme to rebroadcast tokens
 window.parent.postMessage({ type: "GetSonicTheme" }, "*");
   </template>
 </sonic-code>
@@ -111,12 +88,10 @@ window.parent.postMessage({ type: "GetSonicTheme" }, "*");
 
 | 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` |
+| `theme` | `custom` (default) · `light` · `dark` · `auto` | Built-in palette; `custom` applies core tokens and your overrides only |
 | `color` | boolean | Host text color uses `--sc-base-content` |
-| `font` | boolean | Host font uses `--sc-font-family-base` and related base weight/style tokens |
+| `font` | boolean | Host uses the base font family, weight and 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`**).
+| *(default)* | Application content |