@xplortech/apollo-core 2.10.0 → 2.12.0

package/dist/components/xpl-utility-bar.js

@@ -1 +1 @@
-import{p as t,H as s,d as a,h as i,c as e,t as n}from"./p-BT_Lq3Vd.js";import{d as l}from"./p-B1PBAEzg.js";const o=t(class extends s{constructor(t){super(),!1!==t&&this.__registerHost(),this.navOpen=a(this,"navOpen",7),this.open=!0}onNavToggle(){this.open=!this.open,this.navOpen.emit(this.open)}componentWillLoad(){this.open=void 0!==this.isNavOpenAtStartup?this.isNavOpenAtStartup:this.open}render(){return i(e,{key:"965003722d536d4b9b7acd326ed7ae0cc2ac302a"},i("nav",{key:"25d4348939fd65e00ce7bec962a31d65ff9473c3","aria-label":"utility navigation bar",class:"xpl-utility-bar"},this.navControl?i("div",null,i("button",{class:"xpl-utility-bar__nav-control",onClick:()=>this.onNavToggle()},i("xpl-icon",{class:"xpl-utility-nav__bars",icon:"three-bars"})),i("slot",{name:"aside"})):i("slot",{name:"aside"}),i("slot",{key:"3cb1d9038135c1892a3780c9242bbd544f6f0f5f",name:"main"})))}},[260,"xpl-utility-bar",{navControl:[4,"nav-control"],isNavOpenAtStartup:[4,"is-nav-open-at-startup"],open:[32]}]),c=o,r=function(){"undefined"!=typeof customElements&&["xpl-utility-bar","xpl-icon"].forEach((t=>{switch(t){case"xpl-utility-bar":customElements.get(n(t))||customElements.define(n(t),o);break;case"xpl-icon":customElements.get(n(t))||l()}}))};export{c as XplUtilityBar,r as defineCustomElement}
+import{p as t,H as a,d as s,h as i,c as e,t as n}from"./p-BSHdGbmH.js";import{d as l}from"./p-imCMp2Nl.js";const o=t(class extends a{constructor(t){super(),!1!==t&&this.__registerHost(),this.navOpen=s(this,"navOpen",7),this.open=!0}onNavToggle(){this.open=!this.open,this.navOpen.emit(this.open)}componentWillLoad(){this.open=void 0!==this.isNavOpenAtStartup?this.isNavOpenAtStartup:this.open}render(){return i(e,{key:"7ad1182d72a730df69cf714b665a6d02eac2e51a"},i("nav",{key:"f0d5ffc31cabc8a075cae2c1ebdaa0e82ca53943","aria-label":"utility navigation bar",class:"xpl-utility-bar"},this.navControl?i("div",null,i("button",{class:"xpl-utility-bar__nav-control",onClick:()=>this.onNavToggle()},i("xpl-icon",{class:"xpl-utility-nav__bars",icon:"three-bars"})),i("slot",{name:"aside"})):i("slot",{name:"aside"}),i("slot",{key:"dfbacf5921308bd6056b8e6d903b31df28613ce0",name:"main"})))}},[260,"xpl-utility-bar",{navControl:[4,"nav-control"],isNavOpenAtStartup:[4,"is-nav-open-at-startup"],open:[32]}]),c=o,r=function(){"undefined"!=typeof customElements&&["xpl-utility-bar","xpl-icon"].forEach((t=>{switch(t){case"xpl-utility-bar":customElements.get(n(t))||customElements.define(n(t),o);break;case"xpl-icon":customElements.get(n(t))||l()}}))};export{c as XplUtilityBar,r as defineCustomElement}

package/dist/css/typography.stories.js

@@ -1,4 +1,13 @@
+import { setAutoSnapshotOptions } from "vitest-plugin-vis";
+import { waitForHydration } from "../../.storybook/utils/wait-for-hydration";
 export default {
+    tags: ['vrt'],
+    beforeEach() {
+        setAutoSnapshotOptions({ enable: true });
+    },
+    async play({ canvasElement }) {
+        await waitForHydration(canvasElement);
+    },
     title: 'Base Styles/Typography',
     argTypes: {
         headingOne: {

package/dist/docs/xpl-application-shell/readme.md

@@ -1,6 +1,39 @@
 # xpl-application-shell
 
+`xpl-application-shell` is the top-level layout container for an Apollo application. It arranges the main navigation rail, an optional utility bar, an optional secondary navigation column, and the page content into a responsive CSS grid, and drives the CSS-only open/close animation of the navigation rail.
 
+## Usage
+
+```html
+<xpl-application-shell with-subnav is-nav-open-at-startup="true">
+  <xpl-main-nav slot="nav" width="default"><!-- ... --></xpl-main-nav>
+  <xpl-utility-bar slot="utility"><!-- ... --></xpl-utility-bar>
+  <xpl-secondary-nav slot="subnav"><!-- ... --></xpl-secondary-nav>
+  <xpl-content-area slot="content"><!-- ... --></xpl-content-area>
+</xpl-application-shell>
+```
+
+## Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`. All purpose-specific tokens theme automatically in dark mode (no `.dark` overrides in the CSS).
+
+**Color**
+
+| Element | Property | Token | Resolves (light / dark) |
+| --- | --- | --- | --- |
+| Host nav rail | `background-color` | `--xpl-background-surface-inverse-on-light` | neutral-1000 / neutral-1000 (always dark) |
+| `&__subnav` | `background-color` | `--xpl-background-surface-default` | neutral-0 / neutral-1000 |
+| `&__content` | `background-color` | `--xpl-background-surface-subtlest` | neutral-50 / neutral-900 |
+| `&__subnav`, `&__content` | `color` (on-surface text) | `--xpl-text-default` | neutral-900 / neutral-50 |
+| `&__subnav` (top), `&__content` (left/top), `&__utility` (left) | `border-color` | `--xpl-border-default` | neutral-400 / neutral-600 |
+
+**Border width**
+
+- `--xpl-border-small` (0.0625rem / 1px) — all shell dividers.
+
+**Layout literals (not themeable)**
+
+The nav rail widths / transforms (`74px`, `112px`, `240px`) drive the CSS-only open/close animation and are kept as literals; no Foundation size token set covers animated grid-track widths. `grid-template`, `100vh`, and `-webkit-fill-available` are also kept as literals. See `TECH_DEBT.md`.
 
 <!-- Auto Generated Below -->
 

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

@@ -2,6 +2,13 @@
 
 This backdrop is used to add a transparent darker layer on top of the content area to focus the user’s attention. Typically used when a dialog such as a modal or slide out panel is active. 
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-background-surface-backdrop` — backdrop scrim fill. The token bakes the neutral alpha into the color (`rgba(48 45 59 / 0.5)` light / `rgba(48 45 59 / 0.75)` dark), so the standalone `opacity` property was removed to avoid double-dimming. It themes automatically — no `.dark` override.
+
 <!-- Auto Generated Below -->
 
 

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

@@ -147,12 +147,14 @@ Tokens used by this component from `@xplortech/apollo-foundation`.
 
  - [xpl-avatar](../xpl-avatar)
  - [xpl-list-item](../xpl-list/xpl-list-item)
+ - [xpl-tab](../xpl-tab)
 
 ### Graph
 ```mermaid
 graph TD;
   xpl-avatar --> xpl-badge
   xpl-list-item --> xpl-badge
+  xpl-tab --> xpl-badge
   style xpl-badge fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

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

@@ -7,6 +7,15 @@ This component can be used as a wrapper to `<xpl-breadcrumb-item>` components.
 The number of items is not restricted, although per Apollo's design guidelines, a maximum of three items should be used.
 In small screens (xs), only the 2 deepest items will be visible, even if 3 items are provided.
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation` (light/dark handled automatically — no `.dark` overrides).
+
+**Color**
+- `--xpl-text-subdued` — breadcrumb list text and the separator glyph
+- `--xpl-text-link-hovered` — hovered breadcrumb item (per Figma node 1536:178167 UX note)
+- `--xpl-text-default` — current page (last item)
+
 <!-- Auto Generated Below -->
 
 

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

@@ -50,7 +50,7 @@ Use `icon` with a name from the xpl-icon library; use `icon-position` to place t
 Use `icon-only` when the button shows only an icon (no label). Always set `icon` and use a descriptive `aria-label` on the host or inner button for accessibility:
 
 ```html
-<xpl-button icon-only icon="x" aria-label="Close"></xpl-button>
+<xpl-button icon-only icon="xmark" aria-label="Close"></xpl-button>
 ```
 
 ### Loading state
@@ -126,7 +126,7 @@ The **`state`** prop (`neutral` | `warning` | `success`) is deprecated. Use **`s
 
 - The component renders a native `<button>`, so it is focusable and keyboard-activable by default.
 - When **`is-loading`** is true, the inner button has `aria-busy="true"` and the loading spinner is marked **`aria-hidden="true"`** so the label remains the accessible name.
-- For **icon-only** buttons, provide an accessible name via **`aria-label`** on the host (e.g. `<xpl-button icon-only icon="x" aria-label="Close">`) so screen readers announce the action.
+- For **icon-only** buttons, provide an accessible name via **`aria-label`** on the host (e.g. `<xpl-button icon-only icon="xmark" aria-label="Close">`) so screen readers announce the action.
 - For **WAI-ARIA composite widgets** (like tabs), use the **`controlAttrs`** prop to apply `id`, `role`, `aria-controls`, `aria-selected`, and `aria-current` directly to the inner `<button>`. This is preferred over setting these attributes on the host, which would be forwarded and removed from the host.
 
 <!-- Auto Generated Below -->
@@ -166,6 +166,7 @@ The **`state`** prop (`neutral` | `warning` | `success`) is deprecated. Use **`s
  - [xpl-slideout](../xpl-slideout)
  - [xpl-spotlight](../xpl-spotlight)
  - [xpl-tab](../xpl-tab)
+ - [xpl-toast](../xpl-toast)
  - [xpl-top-nav](../xpl-top-nav)
 
 ### Depends on
@@ -184,6 +185,7 @@ graph TD;
   xpl-slideout --> xpl-button
   xpl-spotlight --> xpl-button
   xpl-tab --> xpl-button
+  xpl-toast --> xpl-button
   xpl-top-nav --> xpl-button
   style xpl-button fill:#f9f,stroke:#333,stroke-width:4px
 ```

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

@@ -24,6 +24,18 @@ The checkbox component uses the following Apollo Foundation tokens:
 | `--xpl-border-small` | Border width (1px) |
 | `--xpl-size-100` | Checkbox dimensions (16px) |
 
+### Label tokens (shared `label.css`)
+
+The checkbox label and description are styled by the shared `.xpl-label` / `.xpl-description` classes.
+
+| Token | Usage |
+|-------|-------|
+| `--xpl-text-strong` | Label text color (matches `.xpl-input-label`; resolves to white in dark mode) |
+| `--xpl-text-disabled` | Disabled label text color |
+| `--xpl-text-subdued` | Description text color (enabled and disabled) |
+| `.xpl-text-body` | Label typography: `--xpl-font-size-body` (14px) / normal / 1.4286 line-height |
+| `.xpl-text-callout` | Description typography: `--xpl-font-size-callout` (12px) / normal / 1.3333 line-height |
+
 <!-- Auto Generated Below -->
 
 

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

@@ -1,6 +1,27 @@
 # xpl-choicelist
 
 A Choice List allows users to make single or multiple selections from a list of choices.  This component is meant to consume the radio and checkbox components, either styled or unstyled, then allow for customizing an option list very quickly.
+
+## Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+| Token | Usage |
+|-------|-------|
+| `--xpl-text-strong` | Heading (`h3`) text color |
+| `--xpl-text-subdued` | Description (`p`) text color |
+| `--xpl-background-surface-information` | Selected row background (styled variant) — matches the `xpl-checkbox` / `xpl-radio` styled selected state |
+| `--xpl-border-default` | Styled container border and per-row dividers — matches the `xpl-checkbox` / `xpl-radio` styled card border |
+| `--xpl-border-radius-small` | Styled container corner radius (4px) — matches the `xpl-checkbox` / `xpl-radio` styled card |
+| `--xpl-border-small` | Border width (1px) |
+| `--xpl-border-none` | Removes the divider on the last styled row (0) |
+| `.xpl-text-title-5` | Heading typography: `--xpl-font-size-title-5` (14px) / medium (500) / 1.4286 line-height |
+| `.xpl-text-callout` | Description typography: `--xpl-font-size-callout` (12px) / normal / 1.3333 line-height |
+| `--xpl-space-{8,12,16}` | Heading, row, and styled input/label spacing |
+| `--xpl-size-100` | Control width used to offset the styled label padding (16px) |
+
+Choice item labels and descriptions inherit their text tokens from the shared `label.css` (see `xpl-checkbox` / `xpl-radio`).
+
 <!-- Auto Generated Below -->
 
 

package/dist/docs/xpl-content-area/readme.md

@@ -2,6 +2,14 @@
 
 The `<xpl-content-area>` sets up the area for the main content of the page. This component renders a `<main>` element with an unnamed `<slot>`, and should not be combined with another `<main>` in the same page.
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-background-surface-subtlest` — page surface behind the content (neutral-50 light / neutral-900 dark). Themes automatically — no `.dark` override. Matches the intended application-shell content surface.
+- `--xpl-text-default` — default text color (neutral-900 light / neutral-50 dark).
+
 <!-- Auto Generated Below -->
 
 

package/dist/docs/xpl-data-card/readme.md

@@ -4,6 +4,32 @@ Data Cards display snippets of information and can be linked to larger data sets
 
 The `icon` and `smallStatIcon` properties accept icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.
 
+## Design Tokens
+
+The card is styled entirely with Apollo Foundation purpose-specific tokens (dark mode is automatic — no `.dark` overrides).
+
+| Element / state | Property | Token |
+| --- | --- | --- |
+| Host surface | `background-color` | `--xpl-background-surface-default` |
+| Host / anchor border | `border-color` | `--xpl-border-default` |
+| Host, header, stats text | `color` | `--xpl-text-default` |
+| Header arrow (chevron) icon | `color` | `--xpl-icon-default` |
+| Detail text | `color` | `--xpl-text-subdued` |
+| `.positive` stat | `color` | `--xpl-text-positive` |
+| `.negative` stat | `color` | `--xpl-text-negative` |
+| `.neutral` stat | `color` | `--xpl-text-subdued` |
+| Primary leading icon | `color` | `--xpl-icon-brand` (orange) |
+| Secondary leading icon | `color` | `--xpl-background-action-primary-default` (purple) |
+| Anchor hover / active border | `border` | `--xpl-border-small` + `--xpl-background-action-primary-default` |
+| Anchor focus-visible border | `border` | `--xpl-border-small` + `--xpl-border-focus` (purple) |
+| Anchor focus-visible outline | `outline` | `--xpl-border-focus`, 2px width / 2px offset |
+| Anchor hover / focus-visible radius | `border-radius` | `--xpl-border-radius-default` |
+| Anchor hover shadow | `box-shadow` | `--xpl-background-surface-transparent-10` / `--xpl-background-surface-transparent-5` |
+| Header / stat spacing | `margin` | `--xpl-space-4`, `--xpl-space-6` |
+| Container-query stat | `font-size` | `--xpl-font-size-title-2` |
+
+The resting anchor overlay keeps a `0.375rem` (6px) radius to match the card's `rounded-md`; Foundation has no 6px radius token (see `TECH_DEBT.md`).
+
 <!-- Auto Generated Below -->
 
 

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

@@ -5,6 +5,32 @@ A selection within a dropdown does not change the parent trigger.
 
 ***If you want to present a list of **options** a user can select, or multi-select options, please use [XPL-Select](https://apollo.xplordocs.com/?path=/story/components-select--select).***
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`. The panel surface and border are aligned with the migrated [xpl-popover](../xpl-popover).
+
+**Color**
+- `--xpl-background-surface-default` — panel background
+- `--xpl-text-default` — panel text color (inherited default), option label color, and heading color
+- `--xpl-icon-default` — leading option icon color (`--xpl-icon` via the `icon` prop)
+- `--xpl-border-default` — panel border and heading bottom border
+- `--xpl-text-subdued` — list-item subtitle color
+- `--xpl-background-action-tertiary-hover` — option `:focus` background
+- `--xpl-background-surface-subtlest` — option `:hover` background (neutral subtle surface)
+- `--xpl-background-surface-information` — `--selected` background (purple-50 light / neutral-700 dark)
+- `--xpl-background-action-primary-default` — `--selected` right accent border color
+
+**Border**
+- `--xpl-border-small` — panel and heading border width (1px)
+- `--xpl-border-large` — used via `calc(2 * …)` for the 4px `--selected` accent border (see `TECH_DEBT.md`)
+- `--xpl-border-radius-small` — panel corner radius (4px), matching the anchored `xpl-select` trigger
+
+**Typography**
+- `@extend .xpl-text-callout-bold` — heading: 12px / semibold weight / line-height 1.3333
+- `@extend .xpl-text-callout` — list-item subtitle: 12px / normal weight / line-height 1.3333
+
+**Note:** The multi-select checkmark is a data-URI SVG whose `fill` cannot be themed by a CSS variable, so a `.dark` override supplies the dark-mode glyph; and the disabled option keeps `opacity-60`. Both are tracked in `TECH_DEBT.md`.
+
 <!-- Auto Generated Below -->
 
 
@@ -22,7 +48,7 @@ A selection within a dropdown does not change the parent trigger.
 | `selectOnFocus`          | `select-on-focus`   | whether selection should be made when focusing on interactive element                                                                  | `boolean`                                                                                                                                                            | `false`          |
 | `selectedValues`         | `selected-values`   | The currently selected value(s) in the dropdown.                                                                                       | `string \| string[]`                                                                                                                                                 | `undefined`      |
 | `triggerId`              | `trigger-id`        | the id for the element that triggers the open state                                                                                    | `string`                                                                                                                                                             | `undefined`      |
-| `update`                 | --                  | call back function invoked when a selection is made                                                                                    | `(e: any, { component }: { component: Dropdown; }) => void`                                                                                                          | `undefined`      |
+| `update`                 | --                  | call back function invoked when a selection is made                                                                                    | `(e: Event, context: { component: Dropdown; }) => void`                                                                                                              | `undefined`      |
 
 
 ## Events
@@ -34,16 +60,16 @@ A selection within a dropdown does not change the parent trigger.
 
 ## Methods
 
-### `handleSelect(e: any, { component }: { component: XplDropdownOption; }) => Promise<void>`
+### `handleSelect(e: Event | null, { component }: DropdownSelectContext) => Promise<void>`
 
 called on dropdown option click and keydown events to update isSelected states
 
 #### Parameters
 
-| Name  | Type                                | Description |
-| ----- | ----------------------------------- | ----------- |
-| `e`   | `any`                               |             |
-| `__1` | `{ component: XplDropdownOption; }` |             |
+| Name  | Type                    | Description |
+| ----- | ----------------------- | ----------- |
+| `e`   | `Event`                 |             |
+| `__1` | `DropdownSelectContext` |             |
 
 #### Returns
 

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

@@ -4,6 +4,41 @@
 
 The Dynamic Table is a rich content table that can accommodate multiple types of data. 
 
+## Design Tokens
+
+The table, cells, and rows use Apollo Foundation purpose-specific tokens (light / dark resolve automatically — no `.dark` overrides):
+
+**Table** (`.xpl-dynamic-table`)
+
+| Element | Property | Token |
+| --- | --- | --- |
+| Grid columns | `grid-template-columns` | `--xpl-column-widths` (set at runtime from header cell widths) |
+| Row gap (with accordions) | `row-gap` (8px) | `--xpl-space-8` |
+
+**Cell** (`.xpl-dynamic-table-cell`)
+
+| Element | Property | Token |
+| --- | --- | --- |
+| Cell | Background | `--xpl-background-surface-default` |
+| Cell | Border | `--xpl-border-default` |
+| Cell | Text | `--xpl-text-default` |
+| Cell | Typography (title-5 / medium / 1.4286) | `@extend .xpl-text-title-5` |
+| Cell | Height (56px) | `--xpl-size-350` |
+| Cell | Min width (48px) | `--xpl-size-300` |
+| Cell rounded corners | Border radius (8px) | `--xpl-border-radius-default` |
+| Cell icons (chevron, kebab) | Color | `--xpl-icon-default` |
+| Dropdown button (`:focus-visible`) | Inset ring | `--xpl-border-focus` |
+
+**Row** (`.xpl-dynamic-table-row`)
+
+| State | Property | Token |
+| --- | --- | --- |
+| First cell | Left border | `--xpl-border-default` |
+| Selected | Cell background | `--xpl-background-surface-information` |
+| Disabled | Cell background | `--xpl-background-surface-subtlest` |
+| Disabled | Cell / badge text | `--xpl-text-disabled` |
+| Disabled | Cell icons | `--xpl-icon-disabled` |
+
 <!-- Auto Generated Below -->
 
 

package/dist/docs/xpl-header-accordion/readme.md

@@ -4,6 +4,24 @@ The toolbar component allows users to manipulate selections within the Dynamic T
 
 > **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.
 
+## Design Tokens
+
+The header uses Apollo Foundation purpose-specific tokens (light / dark resolve automatically — no `.dark` overrides):
+
+| Element | Property | Token |
+| --- | --- | --- |
+| Header bar | Background | `--xpl-background-surface-subtlest` |
+| Header bar | Border | `--xpl-border-default` |
+| Header bar | Text | `--xpl-text-subdued` |
+| Header bar | Typography (title-5 / medium / 1.4286) | `@extend .xpl-text-title-5` |
+| Header bar | Min height (56px) | `--xpl-size-350` |
+| Header bar corners | Border radius (8px) | `--xpl-border-radius-default` |
+| Toggle area (`:focus-visible`) | Outline color | `--xpl-border-focus` |
+| Chevron icon | Color | `--xpl-icon-default` |
+| Content panel | Background | `--xpl-background-surface-default` |
+| Content panel | Border | `--xpl-border-default` |
+| Content panel | Text | `--xpl-text-link-default` |
+| Content grid | `grid-template-columns` | `--xpl-column-widths` (set at runtime by `xpl-dynamic-table`) |
 
 <!-- Auto Generated Below -->
 

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

@@ -14,6 +14,21 @@ You can also browse icons visually in [Storybook](?path=/story/components-icons-
 
 The `icon` property accepts any icon name as a string. See the links above for the full list of available icons.
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color — icon accent backgrounds (`&--with-background`)**
+
+Subtle per-hue accent tints use primitive color tokens (`-50` light / `-900` dark). Foundation has no purpose-specific token for these subtle tints (`--xpl-background-accent-*` are far bolder), so primitives are used and the `.dark` overrides are **deliberately retained** to swap the dark value. This is a documented exception to the "no `.dark`" migration DoD (tracked in `TECH_DEBT.md`).
+
+- `--xpl-icon-default` — fallback glyph color for accent-background icons (neutral-900 light / neutral-50 dark). Set explicitly so the glyph themes with the background instead of relying on inherited `currentColor` (which left a dark glyph on the dark `-900` tint in dark mode). Note: `xpl-data-card` also uses the accent-background prop and overrides the glyph color with a hue-matched value directly on `.xpl-icon`, so it is unaffected by this fallback.
+- `--xpl-color-neutral-50` / `--xpl-color-neutral-900` — `--gray` background
+- `--xpl-color-orange-50` / `--xpl-color-orange-900` — `--orange` background
+- `--xpl-color-purple-50` / `--xpl-color-purple-900` — `--purple` background
+- `--xpl-color-red-50` / `--xpl-color-red-900` — `--red` background
+- `--xpl-color-yellow-50` / `--xpl-color-yellow-900` — `--yellow` background
+
 ---
 
 <!-- Auto Generated Below -->
@@ -52,15 +67,19 @@ The `icon` property accepts any icon name as a string. See the links above for t
  - [xpl-progress-bar](../xpl-progress-bar)
  - [xpl-progress-indicator](../xpl-progress-indicator)
  - [xpl-select](../xpl-select)
+ - [xpl-side-nav-header-item](../xpl-side-nav/xpl-side-nav-header-item)
  - [xpl-side-nav-item](../xpl-side-nav/xpl-side-nav-item)
+ - [xpl-side-nav-section](../xpl-side-nav/xpl-side-nav-section)
  - [xpl-slideout](../xpl-slideout)
  - [xpl-spotlight](../xpl-spotlight)
+ - [xpl-tab](../xpl-tab)
  - [xpl-table](../xpl-table)
  - [xpl-table-header-cell](../xpl-table-header-cell)
  - [xpl-tag](../xpl-tag)
  - [xpl-toast](../xpl-toast)
  - [xpl-top-nav](../xpl-top-nav)
  - [xpl-top-nav-item](../xpl-top-nav/xpl-top-nav-item)
+ - [xpl-top-nav-menu](../xpl-top-nav/xpl-top-nav-menu)
  - [xpl-utility-bar](../xpl-utility-bar)
 
 ### Graph
@@ -86,15 +105,19 @@ graph TD;
   xpl-progress-bar --> xpl-icon
   xpl-progress-indicator --> xpl-icon
   xpl-select --> xpl-icon
+  xpl-side-nav-header-item --> xpl-icon
   xpl-side-nav-item --> xpl-icon
+  xpl-side-nav-section --> xpl-icon
   xpl-slideout --> xpl-icon
   xpl-spotlight --> xpl-icon
+  xpl-tab --> xpl-icon
   xpl-table --> xpl-icon
   xpl-table-header-cell --> xpl-icon
   xpl-tag --> xpl-icon
   xpl-toast --> xpl-icon
   xpl-top-nav --> xpl-icon
   xpl-top-nav-item --> xpl-icon
+  xpl-top-nav-menu --> xpl-icon
   xpl-utility-bar --> xpl-icon
   style xpl-icon fill:#f9f,stroke:#333,stroke-width:4px
 ```

package/dist/docs/xpl-input/xpl-input-color/readme.md

@@ -2,6 +2,24 @@
 
 
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-border-default` — display and swatch border
+- `--xpl-text-default` — display text color
+- `--xpl-text-subdued` — placeholder text color
+- `--xpl-background-action-disabled` — disabled display background
+- `--xpl-border-negative` — error state border color (unified with input-date / input-time)
+- `--xpl-icon-default` — toggle icon color
+- `--xpl-background-action-primary-default` — toggle icon hover color (purple; intentionally not `--xpl-icon-brand`, which is orange)
+- `--xpl-border-subtle` — picker saturation/lightness grid, preview, and range-track borders
+- `--xpl-color-neutral-0`, `--xpl-color-neutral-600` — fixed-color picker thumb ring/shadow (functional, non-themeable)
+
+**Typography**
+- `__placeholder`, `__value` — `@extend .xpl-text-body` (14 px normal)
+
 <!-- Auto Generated Below -->
 
 

package/dist/docs/xpl-input/xpl-input-file/readme.md

@@ -2,6 +2,19 @@
 
 
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-text-default` — selected file list text color
+- `--xpl-text-subdued` — accepted-types (help) text color
+- `--xpl-icon-default` — remove (x-circle) icon color
+
+**Typography**
+- `__file-name` — `@extend .xpl-text-callout` (12 px normal) — uploaded file names
+- `__accept` — `@extend .xpl-text-caption` (10 px normal) — accepted file types help text
+
 <!-- Auto Generated Below -->
 
 

package/dist/docs/xpl-input/xpl-input-time/readme.md

@@ -2,6 +2,15 @@
 
 
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-border-negative` — error state border color (unified with input-date / input-color)
+- `--xpl-icon-default` — leading clock icon color (matches input-date's calendar icon)
+- `--xpl-background-surface-transparent-10`, `--xpl-background-surface-transparent-5` — time dropdown box-shadow (purpose-specific; flips to white-based transparency in dark mode)
+
 <!-- Auto Generated Below -->
 
 

package/dist/docs/xpl-large-card/readme.md

@@ -2,6 +2,24 @@
 
 A card is a container and can contain any type of information. Cards contain actions and a content slot. Cards are flexible and can be arranged in grids or lists.
 
+## Design Tokens
+
+The card is styled entirely with Apollo Foundation purpose-specific tokens (dark mode is automatic — no `.dark` overrides).
+
+| Element / state | Property | Token |
+| --- | --- | --- |
+| Host surface | `background-color` | `--xpl-background-surface-default` |
+| Host / anchor border | `border-color` | `--xpl-border-default` |
+| Host, header text | `color` | `--xpl-text-default` |
+| Header arrow (chevron) icon | `color` | `--xpl-icon-default` |
+| Description text | `color` | `--xpl-text-subdued` |
+| Anchor hover / active border | `border` | `--xpl-border-small` + `--xpl-background-action-primary-default` |
+| Anchor focus-visible border | `border` | `--xpl-border-small` + `--xpl-border-focus` (purple) |
+| Anchor focus-visible outline | `outline` | `--xpl-border-focus`, 2px width / 2px offset |
+| Anchor hover / focus-visible radius | `border-radius` | `--xpl-border-radius-default` |
+| Anchor hover shadow | `box-shadow` | `--xpl-background-surface-transparent-10` / `--xpl-background-surface-transparent-5` |
+| Header / tooltip / icon spacing | `margin` | `--xpl-space-4`, `--xpl-space-6`, `--xpl-space-8` |
+
 <!-- Auto Generated Below -->
 
 

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

@@ -328,14 +328,14 @@ Type: `Promise<void>`
 ```mermaid
 graph TD;
   xpl-list --> xpl-list-item
-  xpl-list-item --> xpl-avatar
   xpl-list-item --> xpl-icon
   xpl-list-item --> xpl-badge
   xpl-list-item --> xpl-button
   xpl-list-item --> xpl-radio
   xpl-list-item --> xpl-divider
-  xpl-avatar --> xpl-badge
+  xpl-list-item --> xpl-avatar
   xpl-button --> xpl-icon
+  xpl-avatar --> xpl-badge
   style xpl-list fill:#f9f,stroke:#333,stroke-width:4px
 ```
 

package/dist/docs/xpl-list/xpl-list-item/readme.md

@@ -72,24 +72,24 @@ Single row for [`xpl-list`](../xpl-list/readme.md). **Slot-based** rows expose `
 
 ### Depends on
 
-- [xpl-avatar](../../xpl-avatar)
 - [xpl-icon](../../xpl-icon)
 - [xpl-badge](../../xpl-badge)
 - [xpl-button](../../xpl-button)
 - [xpl-radio](../../xpl-radio)
 - [xpl-divider](../../xpl-divider)
+- [xpl-avatar](../../xpl-avatar)
 
 ### Graph
 ```mermaid
 graph TD;
-  xpl-list-item --> xpl-avatar
   xpl-list-item --> xpl-icon
   xpl-list-item --> xpl-badge
   xpl-list-item --> xpl-button
   xpl-list-item --> xpl-radio
   xpl-list-item --> xpl-divider
-  xpl-avatar --> xpl-badge
+  xpl-list-item --> xpl-avatar
   xpl-button --> xpl-icon
+  xpl-avatar --> xpl-badge
   xpl-list --> xpl-list-item
   style xpl-list-item fill:#f9f,stroke:#333,stroke-width:4px
 ```

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

@@ -5,6 +5,22 @@ The middle area is where the main navigation links go. It's a `<nav>` tag with a
 
 The bottom area is fixed to the bottom and should be used for actions. To render content within this area use the slot `footer` with a `<ul slot="footer">` tag.
 
+### Design Tokens
+
+`xpl-main-nav` is the legacy always-dark side-nav rail; its surface never mode-switches, so colors resolve to the same dark-appropriate value in both page themes.
+
+**Color**
+- `--xpl-background-surface-inverse-on-light` — rail surface (neutral-1000, both modes; matches the application-shell nav host)
+- `--xpl-color-neutral-1100` — footer surface (primitive; no purpose token — see `TECH_DEBT.md`)
+- `--xpl-text-subdued` — rail on-surface base text and nav-item rest label (neutral-600 light / neutral-500 dark; Figma-confirmed; keeps text off the ambient page color on the dark rail)
+- `--xpl-text-inverse-on-dark` — brand name + footer primary text (white, both modes)
+- `--xpl-icon-subtle` — muted footer icon (neutral-500, both modes)
+
+**Typography**
+- `--xpl-font-size-body` — collapsed (`sm`/`md`) nav item label size
+
+**Layout**
+- Collapse-state widths (240 / 112 / 74px) and the 42px brand logo box are raw literals — no matching Foundation size token (see `TECH_DEBT.md`)
 
 <!-- Auto Generated Below -->
 

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

@@ -4,6 +4,26 @@ Modals are dialogs that focus the user’s attention exclusively on one task or
 
 Modals are disruptive and should only be used when disrupting the user’s flow is desired.
 
+## Token Use
+
+`xpl-modal` 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 |
+| ------- | -------- | ----- |
+| `&__dialog` | background | `--xpl-background-surface-default` |
+| `&__dialog` | text color | `--xpl-text-default` |
+| `&__dialog` | radius | `--xpl-border-radius-large` |
+| `&__dialog` | shadow color | `--xpl-color-transparent-neutral-10` / `--xpl-color-transparent-neutral-5` |
+| `&__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-callout` → `callout` / `normal` / `1.3333` |
+| `&__body` | typography (size / weight / line-height) | `@extend .xpl-text-body` → `body` / `normal` / `1.4286` |
+| `&__alert-icon` | color | `--xpl-icon-negative` |
+
+Modal widths are documented CSS literals: small `400px`, medium `600px`, large `800px`, mobile `350px` (see `modal.css` and `TECH_DEBT.md`).
+
+> **Elevation shadow (interim):** Figma specs the dialog 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-nav-item/readme.md

@@ -2,6 +2,20 @@
 
 This component should be used within sections of the `<xpl-main-nav>`. This component yields a slot named `link`, where a `<a>` tag should be used. Within the `<a>` tag, there are two slots, one named `icon`, where any svg can be placed. An an unnamed slot, where the link text should be placed.
 
+### Design Tokens
+
+`xpl-nav-item` renders on the legacy always-dark side-nav rail, so its colors resolve to the same dark-appropriate value in both light and dark page themes.
+
+**Color**
+- `--xpl-icon-subtle` — rest icon (neutral-500, both modes)
+- `--xpl-text-subdued` — rest label text (neutral-600 light / neutral-500 dark; Figma-confirmed)
+- `--xpl-text-inverse-on-dark` / `--xpl-icon-inverse-on-dark` — hover / focus / active / selected label and icon (white, both modes)
+- `--xpl-color-neutral-1200` — hover / focus / active background (primitive; no purpose token — see `TECH_DEBT.md`)
+- `--xpl-color-orange-400` — active brand accent border + icon (primitive; consult-Figma — see `TECH_DEBT.md`)
+
+**Border**
+- `calc(2 * var(--xpl-border-large))` — 4px active accent border width (no 4px Foundation token)
+
 <!-- Auto Generated Below -->