@xplortech/apollo-core 2.9.0 → 2.11.0

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

@@ -4,6 +4,57 @@ A flexible form input that supports multiple `type` values: `text`, `number`, `p
 
 For `type="phone"`, the value is always emitted in **E.164** format (e.g. `+14155551234`). See [`xpl-input-phone`](xpl-input-phone) for full phone-input documentation.
 
+## Design Tokens
+
+The `xpl-input` component uses Apollo Foundation tokens for consistent theming across light and dark modes:
+
+| Element | Property | Token |
+|---------|----------|-------|
+| Input wrapper border (default) | `border-color` | `var(--xpl-border-default)` |
+| Input wrapper border (focus) | `border-color` | `var(--xpl-border-focus)` |
+| Input wrapper border (error) | `border-color` | `var(--xpl-border-negative)` |
+| Input wrapper background (default) | `background-color` | `var(--xpl-background-surface-default)` |
+| Input/textarea background | `background-color` | `var(--xpl-background-surface-transparent-0)` |
+| Disabled/readonly wrapper background | `background-color` | `var(--xpl-background-action-disabled)` |
+| Post element background | `background-color` | `var(--xpl-background-surface-subtle)` |
+| Input text | `color` | `var(--xpl-text-default)` |
+| Disabled/readonly text | `color` | `var(--xpl-text-disabled)` |
+| Label text | `color` | `var(--xpl-text-strong)` |
+| Description text | `color` | `var(--xpl-text-subdued)` |
+| Error text | `color` | `var(--xpl-text-negative)` |
+| Character counter background (default) | `background-color` | `var(--xpl-background-surface-default)` |
+| Character counter background (disabled/readonly) | `background-color` | `var(--xpl-background-action-disabled)` |
+| Character counter text | `color` | `var(--xpl-text-subdued)` |
+| Calendar/password icon | `color` | `var(--xpl-icon-default)` |
+
+### Spacing Tokens
+
+| Element | Property | Token |
+|---------|----------|-------|
+| Input | `padding-right` | `var(--xpl-space-8)` |
+| Textarea | `padding-top` | `var(--xpl-space-12)` |
+| Textarea | `padding-bottom` | `var(--xpl-space-8)` |
+| Wrapper | `padding-left` | `var(--xpl-space-12)` |
+| Pre element (leading icon/text) | `padding-right` | `var(--xpl-space-8)` |
+| Post element (trailing unit / AM-PM) | `padding-left`, `padding-right` | `var(--xpl-space-12)` |
+| Label | `padding-bottom` | `var(--xpl-space-4)` |
+| Character counter | `padding` | `var(--xpl-space-8) var(--xpl-space-12)` |
+| Error message | `padding`, `gap` | `var(--xpl-space-4)` |
+| Calendar icon | `right` | `var(--xpl-space-12)` |
+| Password button | `padding-left`, `padding-right` | `var(--xpl-space-12)` |
+
+### Dimension Tokens
+
+| Element | Property | Token |
+|---------|----------|-------|
+| Input | `height` | `var(--xpl-size-250)` (40px; matches Figma `form/height`) |
+| Textarea | `min-height` | `var(--xpl-size-250)` (40px) |
+| Textarea | `height` | `var(--xpl-size-700)` (112px; rounded up from 98px) |
+| Wrapper | `border-width` | `var(--xpl-border-small)` |
+| Wrapper | `border-radius` | `var(--xpl-border-radius-small)` (4px; matches Figma `border/radius/small`) |
+| Post element | `height` | `var(--xpl-size-250)` (40px; vertically centered via flex) |
+| Post element | `border-left-width` | `var(--xpl-border-small)` |
+
 ### Delegated types (`search`, `phone`, `date`, `time`, …)
 
 `valueChange`, `inputEvent`, `focusEvent`, and `blurEvent` are emitted by the inner component and **bubble** to `<xpl-input>`. For **`type="search"`**, **`focusEvent`** and **`blurEvent`** are **re-emitted from `<xpl-input>`** (parent uses **`onFocusEvent`** / **`onBlurEvent`** on **`<xpl-input-search>`** with **`stopPropagation`**) so **`event.target`** matches **`type="text"`**. For **`valueChange`** and **`inputEvent`** on search, events still **bubble** from **`xpl-input-search`** without parent re-emission; **`event.target`** may be the inner host—prefer **`event.detail`** (the string) or **`event.currentTarget`** when you attach the listener on **`<xpl-input>`**. Other delegated types follow the same **`event.detail`** / **`event.currentTarget`** guidance.

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

@@ -2,6 +2,13 @@
 
 
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-border-negative` — error state border color
+
 <!-- Auto Generated Below -->
 
 

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

@@ -99,6 +99,26 @@ Countries with custom formatters: US/CA, GB, AU, DE/AT/CH, FR, BR, MX, JP, CN, I
 
 28 countries are currently supported. See `phone-country-data.ts` for the full list. Countries with custom number formatting are noted above. To add a new country, add an entry to the `PHONE_COUNTRIES` array and optionally add a formatter in `phone-format.ts`.
 
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-background-surface-subtlest` — trigger background
+- `--xpl-background-surface-information` — trigger hover / open background
+- `--xpl-border-negative` — error state border
+- `--xpl-border-focus` — wrapper and trigger focus outline
+- `--xpl-border-default` — trigger divider, search border
+- `--xpl-text-default` — trigger text, dial code
+- `--xpl-text-subdued` — clear button color
+- `--xpl-icon-default` — search icon
+
+**Border**
+- `--xpl-border-small` — trigger divider width (1px)
+
+**Focus**
+- `--xpl-border-focus` — `:focus-visible` outline (inset, 2px)
+
 <!-- Auto Generated Below -->
 
 
@@ -108,6 +128,7 @@ Countries with custom formatters: US/CA, GB, AU, DE/AT/CH, FR, BR, MX, JP, CN, I
 | -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ----------- |
 | `defaultCountry`     | `default-country`  | Default country code (ISO 3166-1 alpha-2) when value is empty, e.g. "US".                                                                                                                                                      | `string`   | `'US'`      |
 | `disabled`           | `disabled`         | Whether the field is disabled                                                                                                                                                                                                  | `boolean`  | `undefined` |
+| `error`              | `error`            | Whether the field is in an error state. When true, the input renders with the error border styling. The error message itself is owned by the parent `xpl-input` wrapper.                                                       | `boolean`  | `undefined` |
 | `inputId`            | `input-id`         | The `inputId` is used to associate the input with a label.                                                                                                                                                                     | `string`   | `undefined` |
 | `isInternational`    | `is-international` | Enables international mode with a country selector and dial code prefix. When false, the input is locked to `defaultCountry` with no country picker and no dial code shown in the display value. Emitted value is still E.164. | `boolean`  | `true`      |
 | `name`               | `name`             | Most inputs are used in forms, and should have a `name` associated with the input for handling form data.                                                                                                                      | `string`   | `undefined` |

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

@@ -2,6 +2,30 @@
 
 A popover is an overlay that pops up over all other layers and is triggered by a click or tap, and dismissed by clicking outside the popover or a dismiss icon. Popovers can contain additional actions and allow those actions to be triggered.
 
+
+### Design Tokens
+
+Tokens used by this component from `@xplortech/apollo-foundation`.
+
+**Color**
+- `--xpl-background-surface-default` — content panel background and arrow fill
+- `--xpl-background-surface-transparent-10` — shadow primary layer
+- `--xpl-background-surface-transparent-5` — shadow secondary layer
+- `--xpl-text-default` — content text color
+- `--xpl-border-default` — content panel border and arrow stroke
+
+**Spacing**
+- `--xpl-space-8` — popover margin (offset from trigger), via `--xpl-popover-margin`
+- `--xpl-space-16` — content panel padding (Figma `padding/tight`; corrected from the legacy 24px during the Foundation migration — see `TECH_DEBT.md`)
+
+**Border**
+- `--xpl-border-small` — border width (1px)
+- `--xpl-border-radius-default` — content panel corner radius (8px)
+
+**Z-index**
+- `--xpl-z-index-100` — content panel stacking order
+- `--xpl-z-index-900` — arrow stacking order
+
 <!-- Auto Generated Below -->
 
 

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

@@ -1,7 +1,24 @@
-# xpl-radio
-
-Radio buttons allow users to make selections or choices. Radios are always single select, and can also act as controls.
-
+# xpl-radio
+
+Radio buttons allow users to make selections or choices. Radios are always single select, and can also act as controls.
+
+## Design Tokens
+
+The radio component uses the following Apollo Foundation tokens:
+
+| Token | Usage |
+|-------|-------|
+| `--xpl-background-surface-default` | Disabled checked state background; styled label background (resting/hover/focused) |
+| `--xpl-background-action-disabled` | Disabled state background; disabled label background (styled variant) |
+| `--xpl-background-surface-information` | Checked label background (styled variant) |
+| `--xpl-border-strong` | Resting (unchecked) border color |
+| `--xpl-border-hover` | Checked/hover/active border color; styled container hover/focus border |
+| `--xpl-border-default` | Disabled state border color |
+| `--xpl-border-focus` | Focus visible outline |
+| `--xpl-border-radius-small` | Styled container corner radius (4px) |
+| `--xpl-border-small` | Default border width (1px) |
+| `--xpl-size-100` | Radio dimensions (16px) |
+
 <!-- Auto Generated Below -->
 
 

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

@@ -27,7 +27,75 @@ Use the **`label`** prop for a unique accessible name on the `<nav>` when multip
 </xpl-side-nav>
 ```
 
-**Link rows:** use `xpl-side-nav-item` with `link` and an anchor in the default slot — see [xpl-side-nav-item](./xpl-side-nav-item) **Link mode**.
+**Link rows:** use `xpl-side-nav-item` with `link` when the row needs to be a real `<a>` element (framework router components, right-click / open-in-new-tab, semantic link role). For typical in-app navigation, the default button mode is simpler. See [xpl-side-nav-item](./xpl-side-nav-item) **Link mode** for usage and styling guidance.
+
+## Mobile behavior
+
+Below the Tailwind `md` breakpoint (768px) the sidebar collapses to a ~56px top bar with a built-in toggle button (`sidebar-left-show` / `sidebar-left-hide`). Activating the toggle opens a drawer containing the `section` + `nav-footer` content over an [`xpl-backdrop`](../xpl-backdrop) scrim. Above `md` the toggle and backdrop are hidden and the sidebar renders inline — no markup changes are needed for either layout.
+
+**Keyboard / focus:**
+- **Escape** closes the drawer and returns focus to the toggle.
+- A **backdrop click** closes the drawer.
+- **Focus is trapped** inside the open drawer — Tab cycles only through the toggle and drawer rows.
+- The toggle exposes `aria-expanded` and a dynamic `aria-label` ("Open/Close navigation menu").
+
+**Row-level responsive scaling (applied automatically inside the drawer):**
+
+| Property | Desktop (≥ 768px) | Mobile (< 768px) |
+|---|---|---|
+| Tap target (`xpl-side-nav-item` wrapper) | — (inner button sized by content) | `min-height: 48px; padding: 6px 8px` |
+| Leading / trailing icon size | 16px | 24px |
+| Top-level label typography | `title-4` (16px, medium) | `title-3` (20px, medium) |
+| Child item label typography | `title-5` | `title-4` (16px, medium) |
+| Footer item label typography | `title-5` | `title-4` (16px, medium) |
+| Footer row min-height | `28px` | `--xpl-size-200` (32px) |
+| Footer leading / trailing icon | 16px | 20px |
+
+No markup or props are needed for these changes — they are driven entirely by CSS.
+
+### Open state API
+
+The `open` prop, `openChange` event, and `toggle()` / `setOpen()` methods control and observe the drawer. The component works **uncontrolled** (the built-in toggle flips `open`) or **controlled** (the consumer owns `open`).
+
+**Uncontrolled** — the built-in toggle manages everything; listen to `openChange` if you need to react:
+
+```html
+<xpl-side-nav label="Main navigation" id="nav">
+    <div slot="section">…</div>
+    <div slot="nav-footer">…</div>
+</xpl-side-nav>
+<script>
+    document.getElementById('nav').addEventListener('openChange', (e) => {
+        console.log('drawer open:', e.detail);
+    });
+</script>
+```
+
+**Controlled** — own `open` and update it from `openChange` (and/or the imperative methods):
+
+```html
+<xpl-side-nav label="Main navigation" id="nav" open>…</xpl-side-nav>
+<script>
+    const nav = document.getElementById('nav');
+    // Keep your state in sync with user-driven changes (toggle, Escape, backdrop):
+    nav.addEventListener('openChange', (e) => {
+        nav.open = e.detail;
+    });
+    // Programmatic control:
+    await nav.toggle();
+    await nav.setOpen(false);
+</script>
+```
+
+> **v2 breaking change (beta):** the mobile toggle + drawer are now built in. Consumers who previously wrapped their own toggle around `xpl-side-nav` should remove it.
+
+### Implementation details (mobile drawer)
+
+- **Host class hooks** — when the drawer is open the host carries `xpl-side-nav--open` alongside `xpl-side-nav`. Useful for app-level CSS that needs to react (e.g. lock body scroll).
+- **Drawer transition** — `transform` + `opacity` + `visibility` over **300 ms** with `ease-out`. Closed state is `translateX(-100%)` + `opacity: 0` + `visibility: hidden`; the `visibility` flip is delayed 300 ms on close so the slide is visible.
+- **Backdrop transition** — `opacity` + `visibility` over **500 ms** with `ease-in-out`. Open state uses `opacity-50` (matches the native `xpl-backdrop` value, not full opaque). Visibility delayed 500 ms on close. `pointer-events: none` applies immediately on close so page content is tappable while the scrim fades out.
+- **Drawer geometry** — width `80vw` with a `min-width: 300px` floor (Figma spec; no Foundation token yet — see `TECH_DEBT.md`). The remaining `20vw` shows the backdrop scrim.
+- **Toggle styling overrides** — the built-in `xpl-button` toggle uses `padding-inline: var(--xpl-space-12)` on its inner `<button>` and renders its icon at `var(--xpl-size-200)` (32 px) so the icon's left edge aligns with the drawer's nav-item icon column.
 
 ### Multi-Navigation Layouts (Accessibility)
 
@@ -54,17 +122,97 @@ When multiple navigation landmarks exist on a page (e.g., side nav, top nav, bre
 
 ## Related components
 
-- [xpl-side-nav-item](../xpl-side-nav-item) — Navigation rows (leaf, expandable, or link) for section and footer.
+- [xpl-side-nav-item](./xpl-side-nav-item) — Navigation rows for section and footer: leaf button, expandable parent, or link (real `<a>`) mode.
 
 <!-- Auto Generated Below -->
 
 
+## Overview
+
+Slot-based sidebar for app navigation: a scrollable main `section` 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`).
+Activating the toggle opens a drawer containing the `section` + `nav-footer`
+content behind an `xpl-backdrop` scrim. The drawer traps focus while open;
+Escape or a backdrop click closes it and returns focus to the toggle. Above
+`md` the toggle and backdrop are hidden via CSS and the sidebar renders inline.
+
+The toggle is always rendered (no gating prop) and hidden above the breakpoint
+in CSS. Open state is exposed via the `open` prop (controlled or uncontrolled),
+the `openChange` event, and the `toggle()` / `setOpen()` methods.
+
+**v2 breaking change (beta):** consumers who wrapped their own mobile toggle
+around `xpl-side-nav` should remove it — the toggle and drawer are now built in.
+
 ## Properties
 
-| Property | Attribute | Description                                                                                                                                                                                                                                 | Type     | Default     |
-| -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------- |
-| `label`  | `label`   | Accessible label for the navigation landmark. Maps to `aria-label` on the `<nav>` element. Recommended when multiple navigation landmarks exist on a page (e.g., side nav + top nav + breadcrumbs) to help screen readers distinguish them. | `string` | `undefined` |
+| Property | Attribute | Description                                                                                                                                                                                                                                                                      | Type      | Default     |
+| -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- |
+| `label`  | `label`   | Accessible label for the navigation landmark. Maps to `aria-label` on the `<nav>` element. Recommended when multiple navigation landmarks exist on a page (e.g., side nav + top nav + breadcrumbs) to help screen readers distinguish them.                                      | `string`  | `undefined` |
+| `open`   | `open`    | Whether the mobile drawer is open. Reflected to the `open` attribute so CSS and host state stay in sync. Controlled (consumer owns `open`) or uncontrolled (built-in toggle flips it). Has no visible effect above the `md` breakpoint, where the sidebar always renders inline. | `boolean` | `false`     |
+
+
+## Events
 
+| Event        | Description                                                                                                                                                        | Type                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
+| `openChange` | Emitted when the mobile drawer open state changes: toggle activation, Escape, or a backdrop click. Detail is the new open state (`true` = open, `false` = closed). | `CustomEvent<boolean>` |
+
+
+## Methods
+
+### `setOpen(open: boolean) => Promise<void>`
+
+Programmatically set the mobile drawer open state. Emits `openChange` when it changes.
+
+#### Parameters
+
+| Name   | Type      | Description |
+| ------ | --------- | ----------- |
+| `open` | `boolean` |             |
+
+#### Returns
+
+Type: `Promise<void>`
+
+
+
+### `toggle() => Promise<void>`
+
+Programmatically toggle the mobile drawer open/closed. Emits `openChange`.
+
+#### Returns
+
+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`).              |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-button](../xpl-button)
+- [xpl-backdrop](../xpl-backdrop)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-side-nav --> xpl-button
+  xpl-side-nav --> xpl-backdrop
+  xpl-button --> xpl-icon
+  style xpl-side-nav fill:#f9f,stroke:#333,stroke-width:4px
+```
 
 ----------------------------------------------
 

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

@@ -2,42 +2,108 @@
 
 Row for [`xpl-side-nav`](../xpl-side-nav): place items in `slot="section"` or `slot="nav-footer"`. Supports **leaf** (button), **expandable** (`has-children`), and **link** (slot-only) modes, plus `selected`, `disabled`, and `hidden`.
 
+## Changes in v2 (breaking)
+
+`xpl-side-nav` is in **beta**. v2 makes the following breaking changes — no compat shims are provided.
+
+### Migration table
+
+| API | v1 (before) | v2 (after) | Action required |
+|---|---|---|---|
+| Leading icon slot | `slot="icon"` | `slot="leading"` | Rename the `slot` attribute on slotted icon elements |
+| Parent leading icon | Not rendered (chevron only) | Rendered alongside the trailing chevron | Pass `icon` prop or `slot="leading"` content to parent rows |
+| 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 |
+
+### Before / after examples
+
+**Leading icon slot rename:**
+```html
+<!-- v1 -->
+<xpl-side-nav-item label="Dashboard">
+  <xpl-icon slot="icon" icon="house-4" size="16"></xpl-icon>
+</xpl-side-nav-item>
+
+<!-- v2 -->
+<xpl-side-nav-item label="Dashboard">
+  <xpl-icon slot="leading" icon="house-4" size="16"></xpl-icon>
+</xpl-side-nav-item>
+<!-- or use the icon prop shorthand -->
+<xpl-side-nav-item label="Dashboard" icon="house-4"></xpl-side-nav-item>
+```
+
+**Parent rows now show leading icon + chevron:**
+```html
+<!-- v1: icon prop was ignored on parents -->
+<xpl-side-nav-item has-children label="Settings" icon="gear">...</xpl-side-nav-item>
+
+<!-- v2: icon prop renders in the leading slot; chevron auto-renders in trailing -->
+<xpl-side-nav-item has-children label="Settings" icon="gear">...</xpl-side-nav-item>
+```
+
+**Adding a trailing icon to a leaf item:**
+```html
+<!-- v2: slot="trailing" for custom trailing content -->
+<xpl-side-nav-item label="Xplor Growth" icon="chart-line-up">
+  <xpl-icon slot="trailing" icon="external-link" size="16" aria-hidden="true"></xpl-icon>
+</xpl-side-nav-item>
+```
+
+---
+
 ## Modes
 
-- **Leaf (default)** — Button with optional `label`, `icon`, and `slot="icon"`. Click emits **`navClick`** (not used for expandable rows).
-- **Expandable (`has-children`)** — Put nested `xpl-side-nav-item` elements in the **default slot**. Parent row is **chevron + label only** (no icon column; the `icon` prop is ignored). Click toggles **`expanded`** and emits **`expandedChange`**. “Only one section open” / accordion behavior is **not** built in — your app coordinates `expanded` if needed.
-- **Link (`link`)** — **Default slot only**: pass a real `<a>` or router link with full content. Renders a single `<slot>` (no inner button). **Cannot** be combined with `has-children` (see **Rules**).
+- **Leaf (default)** — Button with optional `label`, `icon` prop / `slot="leading"`, and `slot="trailing"`. Click emits **`navClick`**.
+- **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`.
 
 ## Rules
 
 | Topic | Behavior |
-| ----- | ---------- |
+|---|---|
 | **`link` vs `has-children`** | Mutually exclusive. When **`link`** is true, **`hasChildren`** is always false; if both attributes appear in markup, `has-children` is cleared. |
-| **Icons** | `icon` / `slot="icon"` only for **non-link** leaf/footer rows. **Not** rendered for expandable parents. **Nested** items under a parent should use **label only** (icon column hidden in CSS). |
-| **Events** | **`navClick`** — leaf button rows. **`expandedChange`** — expandable rows only (detail = new `expanded` boolean). See **Events** table below. |
+| **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). |
 
 ## Usage
 
-### Leaf
+### Leaf (icon prop)
 ```html
 <xpl-side-nav-item label="Dashboard" icon="house-4" selected></xpl-side-nav-item>
 ```
 
-### Expandable parent
+### Leaf (slot="leading")
+```html
+<xpl-side-nav-item label="Dashboard">
+  <xpl-icon slot="leading" icon="house-4" size="16"></xpl-icon>
+</xpl-side-nav-item>
+```
+
+### Leaf with trailing icon
+```html
+<xpl-side-nav-item label="Xplor Growth" icon="chart-line-up">
+  <xpl-icon slot="trailing" icon="external-link" size="16" aria-hidden="true"></xpl-icon>
+</xpl-side-nav-item>
+```
+
+### Expandable parent (leading icon + auto chevron)
 ```html
-<xpl-side-nav-item has-children label="Settings" expanded>
+<xpl-side-nav-item has-children label="Settings" icon="gear" expanded>
   <xpl-side-nav-item label="Profile"></xpl-side-nav-item>
   <xpl-side-nav-item label="Billing"></xpl-side-nav-item>
 </xpl-side-nav-item>
 ```
 
 ### Link (slot-only)
+
+Wrap the anchor's children in the component CSS classes to match the icon color, label color, and spacing of button-mode items. Avoid whitespace text nodes between flex children — they render as a space character and add an unwanted gap.
+
 ```html
 <xpl-side-nav-item link>
-  <a href="#reports">
-    <xpl-icon icon="chart-line" size="16"></xpl-icon>
-    Reports
-  </a>
+    <!-- No whitespace between __leading / __label spans and the closing </a> -->
+    <a href="/reports" class="xpl-side-nav-item__link"><span class="xpl-side-nav-item__leading"><xpl-icon icon="chart-line" size="16"></xpl-icon></span><span class="xpl-side-nav-item__label">Reports</span></a>
 </xpl-side-nav-item>
 ```
 
@@ -50,14 +116,17 @@ Row for [`xpl-side-nav`](../xpl-side-nav): place items in `slot="section"` or `s
 ## Slots
 
 | Slot | Description |
-| ---- | ----------- |
-| `icon` | **Button rows only** (`link` and `has-children` do not expose this slot in the DOM). Optional leading icon: default content from the `icon` prop, or override with slotted content. Omit on nested items under an expandable parent. |
-| *(default)* | **`has-children`:** nested `xpl-side-nav-item` elements. **`link`:** one anchor (or router component) with icon + text as needed. |
+|---|---|
+| `leading` | Leading icon column. Default content is an `xpl-icon` from the `icon` prop. Override with slotted content. Applies to all item types including parents. Renamed from `icon` in v2. |
+| `trailing` | Trailing content (e.g. `xpl-icon icon="external-link"`). On `has-children` items, the auto chevron is rendered here when this slot is empty (`chevron-down` collapsed, `chevron-up` expanded); slotted content replaces the chevron. |
+| *(default)* | **`has-children`:** nested `xpl-side-nav-item` children. **`link`:** one `<a>` (or router link component) containing all row content. Unused in leaf button mode. |
 
 ## Link mode checklist
 
-- Do **not** use `label` or `icon` props — put text and icons inside your anchor.
-- Set **`aria-current="page"`** on the anchor when the route is active.
+- Do **not** use `label` or `icon` props — they are ignored in link mode. Put all text and icons inside your slotted anchor.
+- Use **`class="xpl-side-nav-item__link"`** on the anchor, **`class="xpl-side-nav-item__leading"`** on the icon wrapper, and **`class="xpl-side-nav-item__label"`** on the text span for consistent icon color, label typography, hover, and focus styling.
+- **No whitespace between flex children** — ensure no newlines or spaces sit between `__leading`, `__label`, and the `</a>` tag. Whitespace between flex items renders as a space character and shifts the label to the right.
+- Set **`aria-current="page"`** on the anchor (not the host) when the route is active.
 - For **disabled** links: set `disabled` on the host and `aria-disabled="true"` + `tabindex="-1"` on the anchor (see **Accessibility**).
 
 ## Accessibility
@@ -65,9 +134,45 @@ Row for [`xpl-side-nav`](../xpl-side-nav): place items in `slot="section"` or `s
 - **Selected (non-link):** `aria-current="page"` on the `button` (leaf or expandable row).
 - **Selected (link):** set `aria-current="page"` on your slotted anchor.
 - **Expandable:** `aria-expanded` on the parent `button` matches `expanded`.
+- **Trailing decorative icons:** add `aria-hidden="true"` to trailing `xpl-icon` elements. If the trailing icon conveys meaning (e.g. external link), provide accessible labeling in the surrounding context.
 - **Disabled:** use the `disabled` prop on non-link rows; for link mode, coordinate host `disabled` with the anchor as above.
 - **Hidden:** `hidden` hides the row; it does not disable interaction by itself — use `disabled` when appropriate.
 
+## Mobile behavior (below `md` / 768px)
+
+Inside the `xpl-side-nav` mobile drawer, items are automatically restyled by CSS — no props or markup changes needed.
+
+| Property | Desktop | Mobile |
+|---|---|---|
+| Outer wrapper tap target | — | `min-height: 48px; padding: 6px 8px` |
+| Inner button `min-height` | 32px | 0 (tap target comes from wrapper) |
+| Leading / trailing icon size | 16px (`--xpl-size-100`) | 24px (`--xpl-size-150`) |
+| Top-level label | `title-4` (16px, medium, lh 1.5) | `title-3` (20px, medium, lh 1.4) |
+| Child item label | `title-5` | `title-4` (16px, medium, lh 1.5) |
+| Footer item label | `title-5` | `title-4` (16px, medium, lh 1.5) |
+| Footer row min-height | `28px` (one step smaller than section rows) | `--xpl-size-200` (32px) |
+| Footer leading / trailing icon | 16px (`--xpl-size-100`) | 20px (`--xpl-size-125`) |
+| Child label alignment offset | `padding-left: var(--xpl-side-nav-child-indent)` (32px) | Same — child labels stay aligned with the parent label column on every viewport |
+
+**Link mode and mobile icons:** in button mode the component automatically adjusts the `xpl-icon` `size` prop to 24 below `md`. In link mode, where the consumer controls the anchor content, the CSS scales the `svg` element inside `__leading` / `__trailing` via a presentational-attribute override — no `size` prop change needed.
+
+## Token reference
+
+| Token | Usage |
+|---|---|
+| `--xpl-icon-default` | Leading and trailing icon color (default, hover, selected) |
+| `--xpl-icon-disabled` | Leading, trailing, and label color when disabled |
+| `--xpl-text-strong` | Label color |
+| `--xpl-text-disabled` | Label color when disabled |
+| `--xpl-background-brand-secondary-surface` | Selected row background |
+| `--xpl-background-surface-transparent-10` | Hover row background |
+| `--xpl-border-focus` | Focus outline color |
+| `--xpl-space-8` | `margin-right` on the leading icon box (spacing between icon and label); `margin-left` on the trailing box |
+| `--xpl-size-100` | Leading / trailing icon box: 16px on desktop |
+| `--xpl-size-150` | Leading / trailing icon box on mobile (overrides `--xpl-size-100` below `md`) |
+| `--xpl-size-200` | `min-height` of the inner link / button (32px desktop) |
+| `--xpl-size-300` | `min-height` of the outer row wrapper on mobile (48px tap target) |
+
 ## Related
 
 - [xpl-side-nav](../xpl-side-nav) — Sidebar container (`slot="section"`, `slot="nav-footer"`).
@@ -75,26 +180,54 @@ Row for [`xpl-side-nav`](../xpl-side-nav): place items in `slot="section"` or `s
 <!-- Auto Generated Below -->
 
 
+## Overview
+
+Navigation row for `xpl-side-nav`. Renders a button (default) or a slot-only
+anchor container (`link` mode). Three slot positions are available:
+
+- `slot="leading"` — leading icon column (renamed from `slot="icon"` in v2).
+  The `icon` prop is a convenience shorthand that renders an `xpl-icon` here
+  when no slotted `leading` content is present.
+- `slot="trailing"` — trailing content (e.g. `xpl-icon icon="external-link"`).
+  When `has-children` is true and no `trailing` slot content is provided, an
+  auto chevron is rendered automatically in this position: `chevron-down` when
+  collapsed, `chevron-up` when expanded.
+- default slot — nested `xpl-side-nav-item` children (expandable parents only).
+
+**v2 breaking changes (beta):**
+- `slot="icon"` renamed to `slot="leading"` — no alias kept.
+- Parent rows (`has-children`) now render the leading icon alongside the chevron.
+  Previously parents showed chevron + label only (no leading icon).
+- The chevron has moved from the leading position to the trailing position.
+- A slotted `slot="trailing"` replaces the auto chevron on parent rows.
+
+**Migration:**
+| Before (v1) | After (v2) | Action |
+|---|---|---|
+| `slot="icon"` | `slot="leading"` | Rename the slot attribute |
+| Parent row: chevron only (no leading) | Parent row: leading icon + chevron | Pass `icon` prop or `slot="leading"` |
+| (no trailing slot) | `slot="trailing"` | Add for custom trailing content |
+
 ## Properties
 
-| Property      | Attribute      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Type      | Default     |
-| ------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- |
-| `disabled`    | `disabled`     | Whether the component is disabled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `boolean` | `false`     |
-| `expanded`    | `expanded`     | Whether the item is currently expanded (only applies when hasChildren is true)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `boolean` | `false`     |
-| `hasChildren` | `has-children` | Whether the item has child items; when true, shows expand/collapse and a default slot for nested items. Mutually exclusive with <code>link</code>. If <code>link</code> is already true, setting <code>has-children</code> is reverted (<code>@Watch('hasChildren')</code>, <code>@Watch('link')</code>, <code>componentWillLoad</code>, and <code>componentWillRender</code>) so reflected attributes match CSS.                                                                                                                                                                         | `boolean` | `false`     |
-| `hidden`      | `hidden`       | Whether the component is hidden                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `boolean` | `false`     |
-| `icon`        | `icon`         | Optional icon name; default content for <code>slot="icon"</code> (leaf and footer rows only). Expandable parents (<code>has-children</code>) do not show an icon column — only the chevron and label. Omit for nested children under a <code>has-children</code> parent — the icon column is hidden for sub-items.                                                                                                                                                                                                                                                                        | `string`  | `undefined` |
-| `label`       | `label`        | The display label for the navigation item (button / expandable rows; omit in <code>link</code> mode).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `string`  | `undefined` |
-| `link`        | `link`         | When true, the row becomes a slot-only container for consumer-provided links. The consumer provides the full anchor element (or router link) via the default slot. In link mode, <code>label</code> and <code>icon</code> props should not be used. Link mode does not support <code>has-children</code>; use the default button mode for expandable items. When <code>link</code> is true, <code>hasChildren</code> is always false (enforced by <code>@Watch('link')</code>, <code>@Watch('hasChildren')</code>, <code>componentWillLoad</code>, and <code>componentWillRender</code>). | `boolean` | `false`     |
-| `selected`    | `selected`     | Whether the item is currently in a selected state                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `boolean` | `false`     |
+| Property      | Attribute      | Description                                                                                                                                                                                                                                                                                                                                                                    | Type      | Default     |
+| ------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ----------- |
+| `disabled`    | `disabled`     | Whether the item is currently disabled.                                                                                                                                                                                                                                                                                                                                        | `boolean` | `false`     |
+| `expanded`    | `expanded`     | Whether the item is currently expanded (only applies when `has-children` is true).                                                                                                                                                                                                                                                                                             | `boolean` | `false`     |
+| `hasChildren` | `has-children` | Whether the item has child items; when true, shows expand/collapse and a default slot for nested items. Mutually exclusive with `link`. If `link` is already true, setting `has-children` is reverted.                                                                                                                                                                         | `boolean` | `false`     |
+| `hidden`      | `hidden`       | Whether the component is hidden.                                                                                                                                                                                                                                                                                                                                               | `boolean` | `false`     |
+| `icon`        | `icon`         | Optional icon name; renders as the default content for `slot="leading"`. When `slot="leading"` content is present, this prop is ignored. In v2, this prop applies to all item types including parent rows (`has-children`).                                                                                                                                                    | `string`  | `undefined` |
+| `label`       | `label`        | The display label for the navigation item (button / expandable rows; omit in `link` mode).                                                                                                                                                                                                                                                                                     | `string`  | `undefined` |
+| `link`        | `link`         | When true, the row becomes a slot-only container for consumer-provided links. The consumer provides the full anchor element (or router link) via the default slot. In link mode, `label` and `icon` props should not be used. Link mode does not support `has-children`; use the default button mode for expandable items. When `link` is true, `hasChildren` is always false. | `boolean` | `false`     |
+| `selected`    | `selected`     | Whether the item is currently in a selected state.                                                                                                                                                                                                                                                                                                                             | `boolean` | `false`     |
 
 
 ## Events
 
-| Event            | Description                                                                                         | Type                   |
-| ---------------- | --------------------------------------------------------------------------------------------------- | ---------------------- |
-| `expandedChange` | Emitted when the expanded state changes (hasChildren 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>` |
+| `navClick`       | Emitted when a leaf item is clicked. Expandable parents use `expandedChange` instead.                  | `CustomEvent<void>`    |
 
 
 ## Dependencies