@xplortech/apollo-core 2.11.0 → 3.0.0

package/dist/docs/xpl-side-nav/xpl-side-nav-section/readme.md

@@ -0,0 +1,126 @@
+# xpl-side-nav-section
+
+Grouping / accordion header for [`xpl-side-nav`](../xpl-side-nav). Wraps nested `xpl-side-nav-item` (and optional divider separators) elements in the default slot and collapses them as a unit.
+
+## Usage
+
+### Collapsible (default)
+
+```html
+<xpl-side-nav-section heading="Settings">
+  <xpl-side-nav-item label="Location" icon="pin"></xpl-side-nav-item>
+  <xpl-side-nav-item label="Schedule" icon="calendar"></xpl-side-nav-item>
+</xpl-side-nav-section>
+```
+
+### Static (label only, `collapsible=false`)
+
+```html
+<xpl-side-nav-section heading="Product" collapsible="false">
+  <xpl-side-nav-item label="Location" icon="pin"></xpl-side-nav-item>
+</xpl-side-nav-section>
+```
+
+### With a badge (`slot="badge"`)
+
+Compose the existing `xpl-badge` — there is no `badge` boolean prop. The wrapper is suppressed automatically when the slot is empty.
+
+```html
+<xpl-side-nav-section heading="Updates">
+  <xpl-badge slot="badge" variant="purple" size="small">4</xpl-badge>
+  <xpl-side-nav-item label="Webhooks"></xpl-side-nav-item>
+</xpl-side-nav-section>
+```
+
+## Rules
+
+| Topic | Behavior |
+|---|---|
+| **Child indent** | Unlike `xpl-side-nav-item[has-children]`, section children are **not indented** — they align with top-level items at the same leading-icon column, and keep their own leading icon. |
+| **Dividers** | Sections do **not** render their own dividers. Place an `<hr class="xpl-side-nav-divider">` as a sibling (e.g. above and below a closed section) when a visual break is needed — no dedicated component. |
+| **Coordination** | Sections behave independently — there is no built-in single-open accordion coordination between sibling sections. |
+| **Chevron** | Auto-rendered for collapsible sections: `chevron-right` collapsed / `chevron-down` expanded (the glyph swaps, no rotation). Not rendered when `collapsible="false"`. |
+
+## Accessibility
+
+- The collapsible header is a real `<button type="button">` with `aria-expanded` (mirrors `expanded`) and `aria-controls` pointing to the children region's `id`.
+- The button's accessible name comes from the visible `heading` text or `slot="badge"` content. It falls back to `aria-label="Toggle section"` only when both are absent or whitespace-only; the chevron is `aria-hidden`.
+- The decorative chevron carries `aria-hidden="true"` — the button's `aria-expanded` already conveys state.
+- Collapsed children are marked `inert`, removing them from the tab order (not just visually hidden) — same pattern as `xpl-side-nav-item[has-children]`.
+- The static variant (`collapsible="false"`) renders a plain `<div>` header — no button semantics, since there is nothing to toggle.
+
+## Token reference
+
+| Token | Usage |
+|---|---|
+| `--xpl-text-subdued` | Title color |
+| `--xpl-icon-subtle` | Chevron color |
+| `--xpl-font-weight-bold` | Title font weight (extends `.xpl-text-callout` for size/line-height) |
+| `--xpl-space-8` | Title-row gap; horizontal header padding (desktop, reconciled against the parent section's own 8px padding) |
+| `--xpl-space-24` / `--xpl-space-4` | Header vertical padding (closed: 24/24; expanded or static: 24/4) |
+| `--xpl-size-100` / `--xpl-size-150` | Chevron box: 16px desktop, 24px mobile |
+| `--xpl-size-250` | Header `min-height` (40px) |
+| `--xpl-border-focus` | Focus outline color |
+
+## Related
+
+- [xpl-side-nav](../xpl-side-nav) — Sidebar container (`slot="section"`, `slot="nav-footer"`).
+- [xpl-side-nav-item](../xpl-side-nav-item) — Navigation row.
+- `<hr class="xpl-side-nav-divider">` — Standalone separator (no dedicated component), often placed around a section.
+- [xpl-badge](../../xpl-badge) — Composed via `slot="badge"`.
+
+<!-- Auto Generated Below -->
+
+
+## Overview
+
+Grouping / accordion header for `xpl-side-nav`. Wraps nested `xpl-side-nav-item`
+(and optional divider separators) elements in the default slot and collapses
+them as a unit.
+
+Two variants:
+- **Collapsible (default, `collapsible=true`)** — a `<button>` header with a
+  chevron (`chevron-right` collapsed / `chevron-down` expanded, no rotation —
+  the glyph itself swaps). Click toggles `expanded` and emits `expandedChange`.
+- **Static (`collapsible=false`)** — a non-interactive title row with no chevron;
+  children are always shown. Used for a static section label (e.g. a future
+  product-name / location-changer header).
+
+Unlike `xpl-side-nav-item[has-children]`, section children are **not indented**
+— they align with top-level items at the same leading-icon column.
+
+`slot="badge"` renders an optional badge (e.g. `xpl-badge`) in the header title
+row. The wrapper is suppressed when the slot is empty.
+
+## Properties
+
+| Property      | Attribute     | Description                                                                                                                                                                                                                            | Type      | Default     |
+| ------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- |
+| `collapsible` | `collapsible` | Whether the section can be collapsed/expanded. When `false`, renders a static title (no chevron, not a button) and children are always shown.                                                                                          | `boolean` | `true`      |
+| `expanded`    | `expanded`    | Whether the section is currently expanded. Only meaningful when `collapsible` is true.                                                                                                                                                 | `boolean` | `false`     |
+| `heading`     | `heading`     | The section title text. Optional, but when `collapsible` is true and both `heading` and `slot="badge"` lack an accessible name, the toggle `<button>` falls back to `aria-label="Toggle section"` so it always has an accessible name. | `string`  | `undefined` |
+
+
+## Events
+
+| Event            | Description                                                                                            | Type                   |
+| ---------------- | ------------------------------------------------------------------------------------------------------ | ---------------------- |
+| `expandedChange` | Emitted when the expanded state changes (collapsible sections only). Detail is the new expanded value. | `CustomEvent<boolean>` |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-icon](../../xpl-icon)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-side-nav-section --> xpl-icon
+  style xpl-side-nav-section fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-slideout/readme.md

@@ -2,6 +2,29 @@
 
 Content and Footer subcomponents are optional and can be hidden.  Slideout always has a header with an X close button upper right. Slide Out Panel OPTIONALLY uses the [<xpl-backdrop>](https://apollo.xplordocs.com/?path=/story/components-backdrop--backdrop) component to overlay content and create focus on the Slide Out Panel content.
 
+## Token Use
+
+`xpl-slideout` uses Apollo Foundation purpose-specific tokens; light and dark mode are handled by the token definitions, so the component has no `.dark` overrides.
+
+| Element | Property | Token |
+| ------- | -------- | ----- |
+| `.slideout` | background | `--xpl-background-surface-default` |
+| `.slideout` | shadow color | `--xpl-color-transparent-neutral-10` / `--xpl-color-transparent-neutral-5` |
+| `.title` | color | `--xpl-text-default` |
+| `.title` | typography (size / weight / line-height) | `@extend .xpl-text-title-3` → `title-3` / `bold` / `1.4` |
+| `.subtitle` | color | `--xpl-text-subdued` |
+| `.subtitle` | typography (size / weight / line-height) | `@extend .xpl-text-body` → `body` / `normal` / `1.4286` |
+| `.content` | text color | `--xpl-text-default` |
+| `.content.has-shadow` | scroll-overflow shadow (top/bottom only) | `--xpl-color-transparent-neutral-10` / `--xpl-color-transparent-neutral-5` |
+| search `.xpl-input-wrapper` | background | `--xpl-background-surface-default` |
+| search `input` | color | `--xpl-text-default` |
+
+Panel widths are documented CSS literals: `min-width: 21.5rem`, `max-width: 37.5rem` (see `slideout.css` and `TECH_DEBT.md`).
+
+The `.content.has-shadow` shadow is a scroll affordance applied only to the top and bottom edges (per Figma node 52462-9896) to signal that content is hidden behind the header/footer when it overflows.
+
+> **Elevation shadow (interim):** Figma specs the panel shadow as the single "Shadow 4" elevation style (`y=20`, `blur=25`, color `background-surface-transparent-10`). Foundation has no elevation/shadow tokens yet, so the shadow geometry is hand-authored and its color uses the primitive `--xpl-color-transparent-neutral-10 / -5`. This migrates to the purpose-specific `--xpl-background-surface-transparent-10` (theme-aware) once elevation tokens land — tracked in `TECH_DEBT.md`.
+
 <!-- Auto Generated Below -->
 
 

package/dist/docs/xpl-tab/readme.md

@@ -18,14 +18,16 @@ Underline tabs render a native **`<button role="tab">`**; segment tabs render **
 
 ## Properties
 
-| Property        | Attribute             | Description                                                                                                   | Type               | Default     |
-| --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------ | ----------- |
-| `disabled`      | `disabled`            | Disables this tab (pill or underline).                                                                        | `boolean`          | `false`     |
-| `groupDisabled` | `data-group-disabled` | Set when the parent `xpl-tabs` has `disabled` (group-disabled).                                               | `boolean`          | `false`     |
-| `icon`          | `icon`                | Optional icon name for segment-style pills (`type="segment"` on parent `xpl-tabs`). Ignored for default tabs. | `string`           | `undefined` |
-| `iconPosition`  | `icon-position`       | Icon position for segment-style pills.                                                                        | `"end" \| "start"` | `'start'`   |
-| `selected`      | `selected`            | Whether the tab is selected                                                                                   | `boolean`          | `false`     |
-| `target`        | `target`              | The target of the tab, required for the tab to be selected                                                    | `string`           | `undefined` |
+| Property        | Attribute             | Description                                                                                                                                                                                            | Type                                                                       | Default     |
+| --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ----------- |
+| `badge`         | `badge`               | Optional trailing number badge (e.g. a count). Rendered after the label as a compact `xpl-badge` in both underline (`type="tabs"`) and segment (`type="segment"`) tabs. Leave empty to omit the badge. | `string`                                                                   | `undefined` |
+| `badgeVariant`  | `badge-variant`       | Color palette for the trailing number badge. Only applies when `badge` is set. Defaults to `purple` — the standard number-badge color in the Figma XPL-Tab Group spec.                                 | `"blue" \| "gray" \| "green" \| "orange" \| "purple" \| "red" \| "yellow"` | `'purple'`  |
+| `disabled`      | `disabled`            | Disables this tab (pill or underline).                                                                                                                                                                 | `boolean`                                                                  | `false`     |
+| `groupDisabled` | `data-group-disabled` | Set when the parent `xpl-tabs` has `disabled` (group-disabled).                                                                                                                                        | `boolean`                                                                  | `false`     |
+| `icon`          | `icon`                | Optional leading icon name (from the Apollo icon set). Rendered in both underline (`type="tabs"`) and segment (`type="segment"`) tabs.                                                                 | `string`                                                                   | `undefined` |
+| `iconPosition`  | `icon-position`       | Icon position relative to the label. Applies to both underline and segment tabs.                                                                                                                       | `"end" \| "start"`                                                         | `'start'`   |
+| `selected`      | `selected`            | Whether the tab is selected                                                                                                                                                                            | `boolean`                                                                  | `false`     |
+| `target`        | `target`              | The target of the tab, required for the tab to be selected                                                                                                                                             | `string`                                                                   | `undefined` |
 
 
 ## Events
@@ -46,12 +48,16 @@ Underline tabs render a native **`<button role="tab">`**; segment tabs render **
 
 ### Depends on
 
+- [xpl-badge](../xpl-badge)
 - [xpl-button](../xpl-button)
+- [xpl-icon](../xpl-icon)
 
 ### Graph
 ```mermaid
 graph TD;
+  xpl-tab --> xpl-badge
   xpl-tab --> xpl-button
+  xpl-tab --> xpl-icon
   xpl-button --> xpl-icon
   style xpl-tab fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/docs/xpl-table/readme.md

@@ -22,10 +22,10 @@ Tables are used to organize and display information from a data set.
 
 ## Events
 
-| Event         | Description                                                                                                                                                                                                               | Type                                                                       |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `sortChanged` | Emits an event whenever the sort changes. The 'sortChanged' event passes an object with colNum (number), colName (string), sortTypeArr(string[]). The default action can be overridden by calling event.preventDefault(). | `CustomEvent<{ colNum: number; colName: string; sortTypeArr: string[]; }>` |
-| `tableSelect` | Callback function that is called when the checkbox for a row of a `multiselect` table is checked                                                                                                                          | `CustomEvent<any>`                                                         |
+| Event         | Description                                                                                                                                                                                                                                  | Type                                                                                  |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `sortChanged` | Emits an event whenever the sort changes. The 'sortChanged' event passes an object with colNum (number), colName (string), sortTypeArr(('asc' \| 'desc' \| null)[]). The default action can be overridden by calling event.preventDefault(). | `CustomEvent<{ colNum: number; colName: string; sortTypeArr: ("desc" \| "asc")[]; }>` |
+| `tableSelect` | Callback function that is called when the checkbox for a row of a `multiselect` table is checked                                                                                                                                             | `CustomEvent<any>`                                                                    |
 
 
 ## Dependencies

package/dist/docs/xpl-table/xpl-table-body/readme.md

@@ -0,0 +1,16 @@
+# xpl-table-body
+
+Row group for compositional table body content. Uses `display: contents` so slotted rows participate in the parent grid layout.
+
+### Design Tokens
+
+| Element | Property | Token | Value |
+| -- | -- | -- | -- |
+| Host | display | — | `contents` |
+
+<!-- Auto Generated Below -->
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-table/xpl-table-footer/readme.md

@@ -0,0 +1,16 @@
+# xpl-table-footer
+
+Row group for compositional table footer content. Uses `display: contents` so slotted footer rows participate in the parent grid layout.
+
+### Design Tokens
+
+| Element | Property | Token | Value |
+| -- | -- | -- | -- |
+| Host | display | — | `contents` |
+
+<!-- Auto Generated Below -->
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-table/xpl-table-footer-cell/readme.md

@@ -0,0 +1,31 @@
+# xpl-table-footer-cell
+
+Footer cell for compositional tables. Extends the shared `.xpl-table-cell-base` styles with a strong top border.
+
+### Design Tokens
+
+| Element | Property | Token | Value |
+| -- | -- | -- | -- |
+| Cell | extends | `.xpl-table-cell-base` | (shared compositional cell base) |
+| Cell | background | `--xpl-background-surface-default` | neutral-0 (lm) / neutral-900 (dm) |
+| Cell | text | `--xpl-text-default` | neutral-900 (lm) / neutral-50 (dm) |
+| Cell | border (right/bottom) | `--xpl-border-small`, `--xpl-border-default` | 1px, neutral-200 |
+| Footer row border | border-top | `--xpl-border-large`, `--xpl-border-strong` | 2px, neutral-300 |
+| Cell | height | `--xpl-size-350` | 56px |
+| Cell | min-width | `--xpl-size-300` | 48px |
+| Cell | padding | `--xpl-space-16` | 16px |
+| Cell | typography | `@extend .xpl-text-title-5` | title-5 / medium |
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property | Attribute | Description                                  | Type                            | Default  |
+| -------- | --------- | -------------------------------------------- | ------------------------------- | -------- |
+| `align`  | `align`   | Horizontal alignment of footer cell content. | `"center" \| "left" \| "right"` | `'left'` |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-table/xpl-table-row/readme.md

@@ -0,0 +1,34 @@
+# xpl-table-row
+
+Data row for compositional tables. Uses `display: contents` by default so cells align to the parent grid; when the body supports subgrid, the row becomes a full-width subgrid for drag interactions.
+
+### Design Tokens
+
+| Element | Property | Token | Value |
+| -- | -- | -- | -- |
+| Host (default) | display | — | `contents` |
+| Host (subgrid body) | display | — | `grid` with `subgrid` |
+| Disabled row | background | `--xpl-background-surface-subtlest` | neutral-50 (lm) / neutral-950 (dm) |
+| Disabled row | text | `--xpl-text-disabled` | neutral-400 (lm) / neutral-600 (dm) |
+| Dragging row | background | `--xpl-background-surface-subtle` | neutral-100 (lm) / neutral-900 (dm) |
+| Dragging row | opacity | `--xpl-opacity-75` | 0.75 (custom, mirrors xpl-list) |
+| Selected row | background | `--xpl-background-surface-information` | blue-50 (lm) / blue-950 (dm) |
+| Drag-over outline | color | `--xpl-border-focus` | purple-500 |
+| Striped even | background | `--xpl-background-surface-subtlest` | neutral-50 (lm) / neutral-950 (dm) |
+| Striped selected | background | `--xpl-background-surface-information-bold` | blue-100 (lm) / blue-900 (dm) |
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property   | Attribute  | Description                                 | Type      | Default     |
+| ---------- | ---------- | ------------------------------------------- | --------- | ----------- |
+| `disabled` | `disabled` | Whether the row and its cells are disabled. | `boolean` | `false`     |
+| `rowId`    | `row-id`   | Stable identifier for selection.            | `string`  | `undefined` |
+| `selected` | `selected` | Whether the row is visually selected.       | `boolean` | `false`     |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

package/dist/docs/xpl-toast/readme.md

@@ -10,6 +10,51 @@ Match your messaging with the sentiment of the toast. Most messages will have a
 
 Toasts only support a single action and up to 85 characters. If multiple actions can be taken, or the message is longer than a few words, use a [Modal component](https://apollo.xplordocs.com/?path=/story/components-modal--modal) instead.
 
+## Usage
+
+```html
+<!-- Neutral toast with a caption, auto-dismissing after the default 8s -->
+<xpl-toast caption="Your changes have been saved.">
+    <p slot="title">Saved</p>
+</xpl-toast>
+
+<!-- With an action. Auto-dismiss is suppressed while the action slot has content -->
+<xpl-toast variant="warning" caption="We couldn't reach the server.">
+    <p slot="title">Sync failed</p>
+    <xpl-button slot="action" size="sm">Retry</xpl-button>
+</xpl-toast>
+
+<!-- No close button; disable auto-dismiss with timeout="0" -->
+<xpl-toast dismissible="false" timeout="0">
+    <p slot="title">Uploading…</p>
+</xpl-toast>
+```
+
+## Deprecations
+
+### `dismissable` → `dismissible`
+
+The **`dismissable`** prop is misspelled and is **deprecated**. Use **`dismissible`** instead.
+
+```html
+<!-- Before -->
+<xpl-toast dismissable="false">…</xpl-toast>
+
+<!-- After -->
+<xpl-toast dismissible="false">…</xpl-toast>
+```
+
+Both props are supported during the deprecation window, so no consumer change is required immediately:
+
+| `dismissable` | `dismissible` | Close button shown | Notes |
+| ------------- | ------------- | ------------------ | ----- |
+| unset | unset | ✅ | Default (`dismissible` defaults to `true`) |
+| unset | `false` | ❌ | Recommended usage |
+| `false` | unset | ❌ | Existing markup keeps working |
+| `false` | `true` | ❌ | `dismissable` wins while it exists |
+
+`dismissable` has **no default** (`undefined` when unset) so the component can tell "not set" from "set to `false`". When it is used, the component logs a one-time deprecation warning to the console. `dismissable` will be removed in the next major version, at which point `dismissible` becomes the only option.
+
 ## Positioning
 
 The default position is arbitrarily set to `40px` from top and `40px` from right of the browser viewport on desktop and bottom-center on mobile. This position should be adjusted to ensure it's not covering your App's header. Apollo, by design, does not prescribe a position for toasts because this will be dependent on the app that it is being used in.
@@ -65,18 +110,53 @@ The mobile breakpoint (≤ 768px) resets the toast to bottom-center. If your app
 
 > **Tip:** Place these overrides in a global stylesheet so every toast in your app appears in the same location.
 
+## Token Use
+
+`xpl-toast` follows the same messaging-component token pattern as [`xpl-banner`](../xpl-banner) (background `--xpl-background-messaging-*` + accent/sentiment border). Light and dark mode are handled by the Foundation token definitions, so the component has no `.dark` overrides.
+
+| Variant / element | Property | Token |
+| ----------------- | -------- | ----- |
+| `neutral` (default) | background | `--xpl-background-messaging-information` |
+| `neutral` (default) | border | `--xpl-border-accent-information` |
+| `&--warning` | background | `--xpl-background-messaging-negative` |
+| `&--warning` | border | `--xpl-border-negative` |
+| `&--success` | background | `--xpl-background-messaging-positive` |
+| `&--success` | border | `--xpl-border-positive` |
+| `&__icon--neutral` | color | `--xpl-icon-default` |
+| `&__icon--warning` | color | `--xpl-icon-negative` |
+| `&__icon--success` | color | `--xpl-icon-positive` |
+| `&` | body radius | `--xpl-border-radius-small` |
+| `&` | shadow color | `--xpl-color-transparent-neutral-10` / `--xpl-color-transparent-neutral-5` |
+| `&__title` | typography (size / weight / line-height) | `@extend .xpl-text-title-5` → `title-5` / `medium` / `1.4286` |
+| `&__caption` | typography (size / weight / line-height) | `@extend .xpl-text-callout` → `callout` / `normal` / `1.3333` |
+| `&__close` | margin | `@apply ml-4` |
+
+The close control is an [`xpl-button`](../xpl-button) (`variant="tertiary"`, `size="sm"`, `iconOnly`), so its radius, colors, and hover / focus / active states come from `button.css` rather than `toast.css`.
+
+Like `xpl-banner`, the messaging backgrounds resolve to transparent in dark mode; the sentiment border and page surface carry the visual treatment in that theme.
+
+## Accessibility
+
+- The close control is an [`xpl-button`](../xpl-button), so it is focusable and keyboard-activable (Tab, then Enter or Space) and gets the shared `:focus-visible` outline.
+- It carries `aria-label="Dismiss notification"` and `type="button"` — the explicit type keeps a toast rendered inside a `<form>` from submitting it when the toast is closed.
+- Toast content is projected through the `title` and `action` slots. Provide the title as text (e.g. `<p slot="title">`) so screen readers announce the message.
+- Dismissing runs a fade-out animation and then removes the host element from the DOM, so a dismissed toast leaves nothing behind in the accessibility tree.
+
+> **Elevation shadow (interim):** Figma specs the toast shadow as the single "Shadow 4" elevation style (`y=20`, `blur=25`, color `background-surface-transparent-10`). Foundation has no elevation/shadow tokens yet, so the shadow geometry is hand-authored and its color uses the primitive `--xpl-color-transparent-neutral-10 / -5`. This migrates to the purpose-specific `--xpl-background-surface-transparent-10` (theme-aware) once elevation tokens land — tracked in `TECH_DEBT.md`.
+
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property      | Attribute     | Description | Type                                  | Default     |
-| ------------- | ------------- | ----------- | ------------------------------------- | ----------- |
-| `caption`     | `caption`     |             | `string`                              | `undefined` |
-| `dismissable` | `dismissable` |             | `boolean`                             | `true`      |
-| `showIcon`    | `show-icon`   |             | `boolean`                             | `true`      |
-| `timeout`     | `timeout`     |             | `number`                              | `8000`      |
-| `variant`     | `variant`     |             | `"neutral" \| "success" \| "warning"` | `'neutral'` |
+| Property      | Attribute     | Description                                                                                                                                                                                                                                                                   | Type                                  | Default     |
+| ------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------- |
+| `caption`     | `caption`     | The caption of the toast, limited to 85 characters.                                                                                                                                                                                                                           | `string`                              | `''`        |
+| `dismissable` | `dismissable` | <span style="color:red">**[DEPRECATED]**</span> Misspelled. Use `dismissible` instead. When both are set, `dismissable` wins so existing markup keeps working; `dismissable` is removed in the next major version.<br/><br/>Whether the toast shows a dismiss (close) button. | `boolean`                             | `undefined` |
+| `dismissible` | `dismissible` | Whether the toast shows a dismiss (close) button.                                                                                                                                                                                                                             | `boolean`                             | `true`      |
+| `showIcon`    | `show-icon`   | Whether to show the leading sentiment icon.                                                                                                                                                                                                                                   | `boolean`                             | `true`      |
+| `timeout`     | `timeout`     | How long the toast waits before auto-dismissing, in ms. Set to `0` to disable auto-dismiss. Ignored when the `action` slot has content.                                                                                                                                       | `number`                              | `8000`      |
+| `variant`     | `variant`     | The sentiment of the toast.                                                                                                                                                                                                                                                   | `"neutral" \| "success" \| "warning"` | `'neutral'` |
 
 
 ## Dependencies
@@ -84,11 +164,14 @@ The mobile breakpoint (≤ 768px) resets the toast to bottom-center. If your app
 ### Depends on
 
 - [xpl-icon](../xpl-icon)
+- [xpl-button](../xpl-button)
 
 ### Graph
 ```mermaid
 graph TD;
   xpl-toast --> xpl-icon
+  xpl-toast --> xpl-button
+  xpl-button --> xpl-icon
   style xpl-toast fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

package/dist/docs/xpl-toggle/readme.md

@@ -2,6 +2,52 @@
 
 A Toggle is a type of form control that is used to switch between enabled and disabled states of an element.
 
+## Usage
+
+```html
+<xpl-toggle heading="Notifications" label="Email me" checked></xpl-toggle>
+<xpl-toggle label="Compact" variant="small"></xpl-toggle>
+<xpl-toggle label="Unavailable" disabled></xpl-toggle>
+```
+
+## Design Tokens
+
+The toggle uses Apollo Foundation purpose-specific tokens so it themes automatically
+in light and dark mode (no `.dark` overrides).
+
+| Element / state | Property | Token |
+| --- | --- | --- |
+| Track (off) | `background-color` | `--xpl-background-accent-neutral` |
+| Track (off, hover) | `background-color` | `--xpl-background-accent-neutral-bold` |
+| Track (on) | `background-color` | `--xpl-background-action-primary-default` |
+| Track (on, hover) | `background-color` | `--xpl-background-action-primary-hover` |
+| Track (disabled, on/off) | `background-color` | `--xpl-background-action-disabled` |
+| Track border | `border-color` | `--xpl-border-default` |
+| Knob (all states) | `background-color` | `--xpl-background-surface-inverse-on-dark` (always-light — resolves to neutral-0 in both modes) |
+| Knob shadow | `box-shadow` color | `--xpl-color-transparent-neutral-10` |
+| Focus ring | `outline-color` | `--xpl-border-focus` (2px outline, 2px offset) |
+| Heading | `color` | `--xpl-text-strong` |
+| Heading | typography | `@extend .xpl-text-title-5` — 14px / medium / 1.4286 (via shared `label.css`) |
+| Trailing label | `color` | `--xpl-text-strong` |
+| Trailing label | typography | `@extend .xpl-text-body` — 14px / normal / 1.4286 |
+| Label (disabled) | `color` | `--xpl-text-disabled` |
+| Description (`small`) | `color` | `--xpl-text-subdued` |
+| Description (`small`) | typography | `@extend .xpl-text-callout` — 12px / normal / 1.3333 (via shared `label.css`) |
+
+**Sizing:** knob (`--xpl-size-125` / small `--xpl-size-075`), default track height
+(`--xpl-size-150`), small track height/radius (`--xpl-size-100` / `--xpl-border-radius-default`),
+default track + knob radius (`--xpl-border-radius-full`), inset (`--xpl-space-2`), knob travel
+(`translateX(--xpl-size-125)` / small `--xpl-size-075`). The `44px`/`28px` track widths have no
+matching Foundation token and remain literals (see TECH_DEBT.md).
+
+The knob glyphs (X / check marks) remain hardcoded data-URI SVGs; a `mask-image` +
+`var(--xpl-icon-*)` refactor is tracked in TECH_DEBT.md.
+
+## Accessibility
+
+The toggle renders a native `<input type="checkbox">`, so it is keyboard-focusable and
+operable with Tab and Space. The `:focus-visible` outline is applied to the control itself.
+
 <!-- Auto Generated Below -->
 
 

package/dist/docs/xpl-toolbar/readme.md

@@ -2,6 +2,25 @@
 
 > **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.
 
+## Design Tokens
+
+The toolbar is an **always-dark** selection bar (nav-rail pattern) — its surface stays dark
+in both light and dark themes. Styling comes from Apollo Foundation tokens
+(`packages/apollo-core/src/css/toolbar.css`):
+
+| Element | Property | Token | Resolves (light / dark) |
+| --- | --- | --- | --- |
+| `.toolbar` surface | `background-color` | `--xpl-background-surface-inverse-on-light` | neutral-1000 / neutral-1000 |
+| `.toolbar` top/bottom border | `border-color` | `--xpl-border-default` | neutral-600 (always-dark host) |
+| `.toolbar` elevation | `box-shadow` | `--xpl-color-transparent-neutral-10`, `--xpl-color-transparent-neutral-5` | fixed neutral transparent |
+| `.toolbar` height | `height` | `--xpl-size-350` | 56px |
+| `.selected-item-count` text | `color` | `--xpl-text-inverse-on-dark` | white / white |
+| `.selected-item-count` divider | `border-color` | `--xpl-border-default` | neutral-600 (always-dark host) |
+| `.selected-item-count` label | `font-size` / `font-weight` / `line-height` | `@extend .xpl-text-title-5` (14px, medium, 1.4286) | — |
+
+> **Design note:** the always-dark surface decision is confirmed (there is no
+> toolbar node in `figma-manifest.json`). Foundation defines no shadow tokens, so the
+> elevation uses the neutral transparent primitives. See `TECH_DEBT.md`.
 
 <!-- Auto Generated Below -->
 

package/dist/docs/xpl-top-nav/readme.md

@@ -1,6 +1,6 @@
 # xpl-top-nav
 
-Top navigation shell for brand, primary navigation, right-side actions, and an optional account menu.
+Top navigation shell for navigating between Xplor applications and account controls — brand, cross-app navigation, right-side actions, and an optional account menu. In Xplor's primary use case it switches between Xplor products within one account, while the side navigation handles primary navigation within a single app.
 
 ## Usage
 
@@ -103,6 +103,7 @@ Horizontal top navigation with **`left-aside`** and a **right rail**: **`right-a
 Optional **`nav-control`** and **`navOpen`**. **`left-aside`** uses **`role="list"`** for primary **`xpl-top-nav-item`** rows (**`role="listitem"`** on each item host). The built-in **`xpl-top-nav__brand`** item omits **`listitem`** (it is not a child of that list). **`label`** maps to **`nav`** **`aria-label`**. Opening state is internal (not a prop) — use **`navOpen`** and host **`xpl-top-nav--open`** for styling.
 
 **Escape:** With **`nav-control`**, **Escape** closes the mobile drawer and emits **`navOpen`** **`false`** (skips while **any** descendant **`xpl-popover`** is open — detected from each popover’s inner **`.xpl-popover--is-open`** marker — or when a **`xpl-top-nav-item`** dropdown is open — capture/bubble order). Focus returns to the nav toggle after the drawer closes (**Escape** or second toggle click).
+**Outside click:** With **`nav-control`**, a click outside the drawer panel (**`.xpl-top-nav__left-primary`**) also closes it and emits **`navOpen`** **`false`** (document **capture**, mirroring **`xpl-top-nav-item`**); it skips clicks on the hamburger toggle and while a descendant **`xpl-popover`** is open, and does not move focus.
 **`xpl-top-nav-item`** **`slot="dropdown"`** uses document **capture** for **Escape** first; the shell uses **bubble**
 on **`ownerDocument`** so nested dropdowns close before the drawer.
 

package/dist/docs/xpl-top-nav/xpl-top-nav-item/readme.md

@@ -114,11 +114,11 @@ Type: `Promise<void>`
 
 ## Slots
 
-| Slot              | Description                                                                                                                                                                                                         |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `"dropdown"`      | Panel content (e.g. `<xpl-top-nav-menu>`). Presence of this slot makes the row a disclosure trigger.                                                                                                                |
-| `"leading-icon"`  | Illustrative icon before the label. Overrides the **`icon`** prop when present.                                                                                                                                     |
-| `"trailing-icon"` | Functional icon after the label (e.g. **`external-link`** for "opens in new window"). When **`slot="dropdown"`** is present and no **`trailing-icon`** content is slotted, an auto **`chevron-down`** renders here. |
+| Slot              | Description                                                                                                                                                                                                                                                                                              |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"dropdown"`      | Panel content (e.g. `<xpl-top-nav-menu>`). Presence of this slot makes the row a disclosure trigger.                                                                                                                                                                                                     |
+| `"leading-icon"`  | Illustrative icon before the label. Overrides the **`icon`** prop when present.                                                                                                                                                                                                                          |
+| `"trailing-icon"` | Functional icon after the label (e.g. **`external-link`** for "opens in new window"). When **`slot="dropdown"`** is present and no **`trailing-icon`** content is slotted, an auto chevron renders here: **`chevron-down`** on the desktop flyout, **`chevron-right`** on the mobile cascade (drill-in). |
 
 
 ## Dependencies

package/dist/docs/xpl-utility-bar/readme.md

@@ -19,6 +19,18 @@ To add content to the slots, just create a `<ul>` tag and target the desired slo
 
 `<ul slot="aside">...</ul>`
 
+## Design Tokens
+
+The utility bar uses Apollo Foundation purpose-specific tokens, which theme automatically in light and dark mode (no `.dark` overrides).
+
+| Element | Property | Token |
+| --- | --- | --- |
+| `.xpl-utility-bar` | `background-color` | `--xpl-background-surface-default` |
+| `.xpl-utility-bar` | `color` (muted text) | `--xpl-text-subdued` |
+| `.xpl-utility-nav__bars` | `color` (nav-control icon) | `--xpl-icon-default` |
+| `.xpl-utility-nav__bars` | `height` | `--xpl-size-100` |
+| `.xpl-utility-bar__nav-control` `:focus-visible` | `outline-color` | `--xpl-border-focus` |
+
 <!-- Auto Generated Below -->