@xplortech/apollo-core 2.10.0 → 2.12.0

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

@@ -4,6 +4,35 @@ Pagination bar allows users to navigate pages of content.
 
 > **Note:** This component is in beta. Use with caution and expect updates before the full release.
 
+## Design Tokens
+
+Pagination themes with the app (light/dark) using Apollo Foundation tokens
+(`packages/apollo-core/src/css/pagination.css`):
+
+| Element / state | Property | Token | Resolves (light / dark) |
+| --- | --- | --- | --- |
+| Pager button surface | `background-color` | `--xpl-background-action-secondary-default` | neutral-0 / neutral-1000 |
+| Pager button border | `border-color` | `--xpl-border-strong` | neutral-600 / neutral-400 |
+| Pager arrow icon | `color` (icon) | `--xpl-icon-default` | neutral-1000 / neutral-0 |
+| Pager button hover/active border | `border-color` | `--xpl-background-action-primary-default` | purple-700 / purple-300 |
+| Pager button focus | `outline-color` | `--xpl-border-focus` (2px, 2px offset) | purple-800 / purple-400 |
+| Pager button disabled icon | `color` (icon) | `--xpl-icon-disabled` | neutral-600 / neutral-500 |
+| Pager button disabled bg | `background-color` | `--xpl-background-action-disabled` | neutral-100 / neutral-800 |
+| Pager container text | `color` | `--xpl-text-default` | neutral-900 / neutral-50 |
+| Rows-per-page label | `color` | `--xpl-text-default` | neutral-900 / neutral-50 |
+| Rows-per-page label | `font-size` / `font-weight` / `line-height` | `@extend .xpl-text-body` (14px, normal, 1.4286) | — |
+| Go-to-page value | `color` | `--xpl-text-link-default` | purple-700 / purple-300 |
+| Active page background | `background-color` | `--xpl-background-brand-secondary-surface` | purple-50 / purple-900 |
+| Pager button / page size | `width` / `height` | `--xpl-size-250` | 40px |
+| Prev / next radius | `border-radius` | `--xpl-border-radius-full` | pill |
+
+> **Accessibility:** keyboard focus uses the Foundation `:focus-visible` outline pattern
+> (`--xpl-border-focus`, 2px outline + 2px offset) instead of a Tailwind `ring`, so the
+> focus ring stays visible on the pager buttons in both themes.
+>
+> **Note:** the rows-per-page (72px), page-select (88px), and page-info (70px) min-widths
+> have no matching Foundation size token and remain literals — see `TECH_DEBT.md`.
+
 <!-- Auto Generated Below -->
 
 

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

@@ -19,6 +19,18 @@ The radio component uses the following Apollo Foundation tokens:
 | `--xpl-border-small` | Default border width (1px) |
 | `--xpl-size-100` | Radio dimensions (16px) |
 
+### Label tokens (shared `label.css`)
+
+The radio 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-secondary-nav/readme.md

@@ -2,6 +2,31 @@
 
 The Secondary Nav component is a component that allows navigation within the content area. It yields one slot where a <ul> element with <xpl-nav-item> elements should be rendered.
 
+## Design Tokens
+
+The secondary nav uses Apollo Foundation purpose-specific tokens, which theme automatically in light and dark mode (no `.dark` overrides).
+
+| Element / state | Property | Token |
+| --- | --- | --- |
+| `nav`, `ul`, host, item | `background` | `--xpl-background-surface-default` |
+| item (default) | `color` | `--xpl-text-subdued` |
+| item | `font-size` | `--xpl-font-size-body` (0.875rem / 14px) |
+| item | `font-weight` | `--xpl-font-weight-normal` (400) |
+| item hover | `color` | `--xpl-text-strong` |
+| item hover | `background` | `--xpl-background-surface-transparent-0` |
+| item active | `color` | `--xpl-text-strong` |
+| item active | `background` | `--xpl-background-brand-primary-surface` |
+| item active | accent `border-color` | `--xpl-border-accent-brand` |
+| item `:focus-visible` | `outline-color` | `--xpl-border-focus` |
+| item `:focus-visible` | `z-index` (above scroll fade) | `--xpl-z-index-200` |
+| item accent border | `border-width` (4px) | `calc(2 * var(--xpl-border-large))` |
+| item (desktop) | `height` (48px) | `--xpl-size-300` |
+| scroll fade `nav::after` | `z-index` (below focused item) | `--xpl-z-index-100` |
+
+The horizontal-scroll fade (`nav::after`, mobile only) fills a strip with `--xpl-background-surface-default` and fades it out with an alpha-only `mask-image`, so it blends into the themed nav background in both modes. It is `pointer-events: none` and sits at `--xpl-z-index-100`, below a keyboard-focused item (`--xpl-z-index-200`), so it never intercepts taps or hides an item's `:focus-visible` ring.
+
+**Known token gaps** (see [`TECH_DEBT.md`](../../../../../../TECH_DEBT.md)): the item `height` (52px) and desktop `width` (200px) have no matching Foundation size token; the 4px accent border and the scroll-fade gradient stops have no dedicated Foundation tokens.
+
 <!-- Auto Generated Below -->
 
 

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

@@ -8,6 +8,19 @@ The `selectIcon` property accepts icon names as strings. See [xpl-icon available
 
 ---
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-icon-default` — chevron icon color
+- `--xpl-text-subdued` — trigger and placeholder value color (empty state)
+- `--xpl-text-default` — selected value color (`.has-value`)
+
+The options panel surface, borders, and option states are styled by [xpl-dropdown](../xpl-dropdown) — see its Design Tokens section.
+
+**Note:** the trigger `height` (44px) and `.xpl-input-wrapper` `min-height` (46px) are kept as literals — no `--xpl-size` token matches (250 = 40px, 300 = 48px). See `TECH_DEBT.md`.
+
 <!-- Auto Generated Below -->
 
 

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

@@ -1,11 +1,12 @@
 # xpl-side-nav
 
-Slot-based sidebar for app navigation: scrollable main area and a fixed footer. Compose with [`xpl-side-nav-item`](./xpl-side-nav-item) for rows in the section and footer.
+Slot-based sidebar for app navigation: a scrollable `nav-header` + `section` area and a fixed footer. Compose with [`xpl-side-nav-item`](./xpl-side-nav-item) for rows in the section and footer.
 
 ## Slots
 
 | Slot | Description |
 | ---- | ----------- |
+| `nav-header` | Optional header row — place an [`xpl-side-nav-header-item`](./xpl-side-nav-header-item) inside. Hidden entirely (no wrapper, no border) when the slot is empty. |
 | `section` | Primary navigation. Place `xpl-side-nav-item` elements (or wrappers) inside this slot; layout uses internal section markup. |
 | `nav-footer` | Footer actions (e.g. Help, Logout). Same item component; typically smaller label styling via CSS. |
 
@@ -15,6 +16,9 @@ Use the **`label`** prop for a unique accessible name on the `<nav>` when multip
 
 ```html
 <xpl-side-nav label="Main navigation">
+  <div slot="nav-header">
+    <xpl-side-nav-header-item type="sub-account" label="Acme Inc" icon="office-3"></xpl-side-nav-header-item>
+  </div>
   <div slot="section">
     <xpl-side-nav-item label="Dashboard" icon="house-4" selected></xpl-side-nav-item>
     <xpl-side-nav-item has-children label="Settings" expanded>
@@ -129,8 +133,8 @@ When multiple navigation landmarks exist on a page (e.g., side nav, top nav, bre
 
 ## Overview
 
-Slot-based sidebar for app navigation: a scrollable main `section` and a fixed
-`nav-footer`. Compose with `xpl-side-nav-item` for rows.
+Slot-based sidebar for app navigation: a scrollable `nav-header` + `section`
+area and a fixed `nav-footer`. Compose with `xpl-side-nav-item` for rows.
 
 **Mobile (v2):** below the Tailwind `md` breakpoint, the sidebar collapses to a
 ~56px top bar with a toggle button (`sidebar-left-show` / `sidebar-left-hide`).
@@ -192,10 +196,11 @@ Type: `Promise<void>`
 
 ## Slots
 
-| Slot           | Description                                                  |
-| -------------- | ------------------------------------------------------------ |
-| `"nav-footer"` | Footer items (e.g. Help, Logout), separated by a top border. |
-| `"section"`    | Primary navigation items (`xpl-side-nav-item`).              |
+| Slot           | Description                                                                                                                                     |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"nav-footer"` | Footer items (e.g. Help, Logout), separated by a top border.                                                                                    |
+| `"nav-header"` | Optional header row (e.g. `xpl-side-nav-header-item`), separated by a bottom border. Hidden entirely (no border, no reserved space) when empty. |
+| `"section"`    | Primary navigation items (`xpl-side-nav-item`).                                                                                                 |
 
 
 ## Dependencies

package/dist/docs/xpl-side-nav/xpl-side-nav-header-item/readme.md

@@ -0,0 +1,155 @@
+# xpl-side-nav-header-item
+
+Header row sub-component for [`xpl-side-nav`](../xpl-side-nav)'s `slot="nav-header"` (Figma navHeaderItem, node `51299-9007`).
+
+## Usage
+
+### Product label (static)
+
+```html
+<xpl-side-nav-header-item type="product-label" label="My Product"></xpl-side-nav-header-item>
+```
+
+### Sub account (interactive)
+
+```html
+<xpl-side-nav-header-item
+    type="sub-account"
+    label="Acme Inc"
+    icon="pin"
+></xpl-side-nav-header-item>
+<script>
+    document
+        .querySelector('xpl-side-nav-header-item[type="sub-account"]')
+        .addEventListener('navigate', () => {
+            // open a location / account switcher, e.g. a modal
+        });
+</script>
+```
+
+### Selected sub account
+
+```html
+<xpl-side-nav-header-item
+    type="sub-account"
+    label="Acme Inc"
+    selected
+></xpl-side-nav-header-item>
+```
+
+### Custom trailing icon (replaces the auto chevron)
+
+```html
+<xpl-side-nav-header-item type="sub-account" label="Xplor Growth">
+    <xpl-icon slot="trailing" icon="external-link" size="16" aria-hidden="true"></xpl-icon>
+</xpl-side-nav-header-item>
+```
+
+## Rules
+
+| Topic | Behavior |
+|---|---|
+| **Leading / trailing columns** | Unlike `xpl-side-nav-item`, these are **not** unconditionally reserved — they only render when there is an `icon` prop or slotted content, matching the Figma variants where the leading icon is an optional toggle. |
+| **Auto chevron** | `sub-account` auto-renders `chevron-expand-y` (a static dual-arrow glyph) in the trailing column when no `slot="trailing"` content is provided. It does not rotate. |
+| **`selected`** | Only meaningful on `sub-account` — wraps the label + trailing chevron in an information-surface pill. Ignored on `product-label`. |
+| **Selected + leading icon** | Figma's selected variant absolute-positions the leading icon over the pill's edge (an auto-layout artifact, not a deliberate detail). This component keeps the leading icon in normal flow outside the pill for a simpler, more maintainable DOM structure. |
+
+## Accessibility
+
+- `product-label` renders a plain, non-interactive `<div>` — no button semantics, since there is nothing to activate.
+- `sub-account` renders a real `<button type="button">`, so Enter/Space activation and focus are native. Activation emits the `navigate` event (pointer or keyboard).
+- **Selected state** — a selected `sub-account` exposes `aria-current="true"` on the button so assistive tech announces which sub-account is active (the pill is a visual-only cue). `'true'` is used rather than `'page'` because a sub-account switcher is not a page.
+- **Accessible name** — the `label` supplies the button's accessible name, so a `label` is strongly recommended for `sub-account`. When `label` is omitted (icon-only), the leading icon is decorative and the auto chevron is `aria-hidden`, so the component falls back to `aria-label="Sub-account"` to guarantee the button is never unnamed. Provide a meaningful `label` for a better experience.
+- The decorative auto chevron carries `aria-hidden="true"`; a custom `slot="trailing"` icon is left to the consumer to label appropriately.
+
+## Token reference
+
+| Token | Usage |
+|---|---|
+| `--xpl-text-subdued` | `product-label` label color |
+| `--xpl-text-strong` | `sub-account` label color |
+| `--xpl-icon-default` | Leading / non-auto trailing icon color |
+| `--xpl-icon-subtle` | Auto chevron color |
+| `--xpl-background-surface-information` | Selected pill background |
+| `--xpl-background-surface-transparent-10` | `sub-account` hover background |
+| `--xpl-border-focus` | Focus outline color |
+| `--xpl-space-4` / `--xpl-space-8` / `--xpl-space-16` | Row / pill padding and gap |
+| `--xpl-size-100` / `--xpl-size-150` | Leading/trailing icon box: 16px desktop, 24px mobile |
+| `--xpl-size-200` | Row `min-height` (32px) |
+
+## Related
+
+- [xpl-side-nav](../xpl-side-nav) — Sidebar container.
+- [xpl-side-nav-item](../xpl-side-nav-item) — Navigation row (shares the leading/trailing slot + icon-prop convention).
+
+<!-- Auto Generated Below -->
+
+
+## Overview
+
+Header row for `xpl-side-nav`'s `nav-header` slot (Figma `<navHeaderItem>`,
+node `51299-9007`). Two types:
+
+- **`product-label` (default)** — a non-interactive `<div>` row that shows the
+  current product/area name in a subdued color. No click behavior.
+- **`sub-account`** — an interactive `<button>` row (e.g. a location / account
+  switcher). Emits `navigate` on activation (pointer click or keyboard); the
+  consumer wires this to open a modal or other entity-switching experience.
+  When no `slot="trailing"` content is provided, an auto chevron
+  (`chevron-expand-y`, a static dual-arrow glyph — no rotation) renders by default.
+
+Both types support `slot="leading"` / `slot="trailing"` (the `icon` prop is a
+convenience shorthand for `slot="leading"`, same as `xpl-side-nav-item`) so they
+can scale to future uses. Unlike `xpl-side-nav-item`, the leading/trailing
+columns are NOT unconditionally reserved — they only render when there is
+content, matching the Figma variants where the leading icon is an optional toggle.
+
+**Note on the `sub-account` hover / selected visual:** the interactive row
+mirrors `xpl-side-nav-item` — the hover and selected backgrounds fill a single
+`__content` pill that wraps the leading icon + label + trailing chevron, with
+an 8px (`--xpl-border-radius-default`) radius. The pill insets 8px from the nav
+edge (an 8px gutter on the button) so it lines up with the item rows below it,
+and hover/selected therefore highlight the whole row content rather than a
+partial fragment.
+
+## Properties
+
+| Property   | Attribute  | Description                                                                                                                                                                 | Type                               | Default           |
+| ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------- |
+| `icon`     | `icon`     | Optional icon name; renders as the default content for `slot="leading"`. When `slot="leading"` content is present, this prop is ignored.                                    | `string`                           | `undefined`       |
+| `label`    | `label`    | The display label for the header item (e.g. the product name or sub-account name).                                                                                          | `string`                           | `undefined`       |
+| `selected` | `selected` | Whether the item is currently in a selected state. Only meaningful when `type` is `sub-account` — applies the information-surface pill around the label + trailing chevron. | `boolean`                          | `false`           |
+| `type`     | `type`     | The header item variant. `product-label` is a static, non-interactive label. `sub-account` is an interactive button that emits `navigate`.                                  | `"product-label" \| "sub-account"` | `'product-label'` |
+
+
+## Events
+
+| Event      | Description                                                                                                                                                               | Type                |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| `navigate` | Emitted when a `sub-account` item is activated (pointer click or keyboard activation of the native `<button>`). Not emitted for `product-label` (static, no interaction). | `CustomEvent<void>` |
+
+
+## Slots
+
+| Slot         | Description                                                                                                                   |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `"leading"`  | Leading icon column. The `icon` prop renders an `xpl-icon` here as a shorthand when no slotted `leading` content is present.  |
+| `"trailing"` | Trailing content. On `sub-account`, an auto `chevron-expand-y` icon renders here when no `trailing` slot content is provided. |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-icon](../../xpl-icon)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-side-nav-header-item --> xpl-icon
+  style xpl-side-nav-header-item fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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

@@ -15,6 +15,7 @@ Row for [`xpl-side-nav`](../xpl-side-nav): place items in `slot="section"` or `s
 | Trailing slot | Not available | `slot="trailing"` | Add to leaf items for custom trailing content |
 | Chevron position | Leading (left side) | Trailing (right side), auto-rendered for parents | No action needed for auto chevron; remove manual chevron markup if any |
 | Chevron override | Not possible | `slot="trailing"` content replaces auto chevron on parents | Pass `slot="trailing"` to customize the trailing column on a parent |
+| Leaf click event | `navClick` event | `navigate` event | Rename listeners: `navClick` → `navigate` (React `onNavClick` → `onNavigate`) |
 
 ### Before / after examples
 
@@ -50,11 +51,20 @@ Row for [`xpl-side-nav`](../xpl-side-nav): place items in `slot="section"` or `s
 </xpl-side-nav-item>
 ```
 
+**Leaf click event rename:**
+```js
+// v1
+item.addEventListener('navClick', handler);
+// v2
+item.addEventListener('navigate', handler);
+```
+In React the prop changes from `onNavClick` to `onNavigate`.
+
 ---
 
 ## Modes
 
-- **Leaf (default)** — Button with optional `label`, `icon` prop / `slot="leading"`, and `slot="trailing"`. Click emits **`navClick`**.
+- **Leaf (default)** — Button with optional `label`, `icon` prop / `slot="leading"`, and `slot="trailing"`. Activation (click or keyboard) emits **`navigate`**.
 - **Expandable (`has-children`)** — Put nested `xpl-side-nav-item` elements in the **default slot**. Row renders **leading icon** (from `icon` prop or `slot="leading"`) **+ label + auto chevron** in the trailing position (**`chevron-down`** when collapsed, **`chevron-up`** when expanded). The chevron is replaced if `slot="trailing"` content is provided. Click toggles **`expanded`** and emits **`expandedChange`**.
 - **Link (`link`)** — **Default slot only**: renders a bare `<slot>` with no inner button. Use when the row must be a real `<a>` element — for framework router components, browser right-click / open-in-new-tab behaviour, or when semantic link vs. button distinction matters for screen readers. For typical in-app navigation the default button mode is simpler. The `label` and `icon` props are ignored in link mode; supply all content in your slotted anchor. **Cannot** be combined with `has-children`.
 
@@ -65,7 +75,7 @@ Row for [`xpl-side-nav`](../xpl-side-nav): place items in `slot="section"` or `s
 | **`link` vs `has-children`** | Mutually exclusive. When **`link`** is true, **`hasChildren`** is always false; if both attributes appear in markup, `has-children` is cleared. |
 | **Leading icon** | `icon` prop / `slot="leading"` apply to all item types including parents. Nested sub-items (inside a parent) have the leading column hidden in CSS — use label only. |
 | **Trailing chevron** | Auto-rendered for `has-children` items when `slot="trailing"` is empty. Providing `slot="trailing"` content replaces the auto chevron. |
-| **Events** | **`navClick`** — leaf button rows. **`expandedChange`** — expandable rows only (detail = new `expanded` boolean). |
+| **Events** | **`navigate`** — leaf button rows (pointer or keyboard activation). **`expandedChange`** — expandable rows only (detail = new `expanded` boolean). |
 
 ## Usage
 
@@ -224,10 +234,10 @@ anchor container (`link` mode). Three slot positions are available:
 
 ## Events
 
-| Event            | Description                                                                                            | Type                   |
-| ---------------- | ------------------------------------------------------------------------------------------------------ | ---------------------- |
-| `expandedChange` | Emitted when the expanded state changes (`has-children` items only). Detail is the new expanded value. | `CustomEvent<boolean>` |
-| `navClick`       | Emitted when a leaf item is clicked. Expandable parents use `expandedChange` instead.                  | `CustomEvent<void>`    |
+| Event            | Description                                                                                                                                             | Type                   |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `expandedChange` | Emitted when the expanded state changes (`has-children` items only). Detail is the new expanded value.                                                  | `CustomEvent<boolean>` |
+| `navigate`       | Emitted when a leaf item is activated (pointer click or keyboard activation of the native `<button>`). Expandable parents use `expandedChange` instead. | `CustomEvent<void>`    |
 
 
 ## Dependencies

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