@xplortech/apollo-core 2.11.0 → 3.0.0

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,42 @@ 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`.
+
+## Accessibility
+
+`xpl-modal` renders a native `<dialog>` shown via `showModal()`: focus is trapped inside the modal while it is open, and `Escape` closes it (emitting `modalClosed`).
+
+Keyboard tab order follows the DOM order of the footer slots: **close (×) → `primary` → `secondary` → `tertiary` → back to ×**. The footer's visual layout (tertiary pinned far-left, secondary and primary right-aligned) is produced with CSS `order` in `modal.css`, so the visual arrangement and the tab order are independent by design — do not reorder the `<slot>` elements in the component template to change the layout.
+
+### Accessible names
+
+The dialog is named by the `title` slot: the component wraps that slot in `.xpl-modal__title-text`, gives it a per-instance id, and points the dialog's `aria-labelledby` at it. Always provide a `title` slot — without one the dialog is announced only as "dialog". The label deliberately references the title text rather than the whole `.xpl-modal__title` row, which would fold the close button's own name into the dialog's name.
+
+The close (×) button carries `aria-label="Close modal"`, so screen readers announce its purpose instead of the underlying icon name.
+
+## Mounting and unmounting
+
+`showModal()` promotes the dialog into the browser's top layer, where it survives the removal of its host element. `xpl-modal` closes the dialog when the host disconnects so a removed modal cannot leave a blocking overlay behind, and re-opens it — reattaching the `Escape` and backdrop listeners — if the host is connected again while `isOpen` is still `true`. Frameworks that move or reparent DOM nodes therefore get consistent state without extra work from the consumer.
+
 <!-- Auto Generated Below -->
 
 
@@ -40,15 +76,15 @@ Modals are disruptive and should only be used when disrupting the user’s flow
 ### Depends on
 
 - [xpl-backdrop](../xpl-backdrop)
-- [xpl-icon](../xpl-icon)
 - [xpl-button](../xpl-button)
+- [xpl-icon](../xpl-icon)
 
 ### Graph
 ```mermaid
 graph TD;
   xpl-modal --> xpl-backdrop
-  xpl-modal --> xpl-icon
   xpl-modal --> xpl-button
+  xpl-modal --> xpl-icon
   xpl-button --> xpl-icon
   style xpl-modal fill:#f9f,stroke:#333,stroke-width:4px
 ```

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 -->
 
 

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