@xplortech/apollo-core 3.1.0 → 3.2.0

package/dist/docs.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-08-24T17:43:34",
+  "timestamp": "2026-08-26T18:32:08",
   "compiler": {
     "name": "@stencil/core",
     "version": "4.43.5",
@@ -466,7 +466,7 @@
       "filePath": "src/components/components/xpl-avatar/xpl-avatar.tsx",
       "encapsulation": "none",
       "tag": "xpl-avatar",
-      "readme": "# xpl-avatar\n\nThe **Avatar** component shows a person or entity: a photo, initials on a colored surface, or custom slot content. It aligns with Apollo’s Figma patterns for default avatars, profile layouts, stacked groups, and rows with supporting text.\n\n## When to use\n\n- **Default (no `variant`)** — Inline UI: tables, nav, comments, lists. Supports image (`src`), initials from `name`, and an optional status dot (`status`).\n- **Profile (`variant=\"profile\"`)** — Large avatars for profile pages and settings surfaces; optional `status` dot uses the same badge palette as the default avatar.\n- **Group (`variant=\"group\"`)** — Stacked avatar groups with overflow count (`+N`). The `status` prop is not used (status dots are not shown for groups).\n- **With Text (`variant=\"with-text\"`)** — Horizontal layout with avatar paired with name and optional sub-text; optional `status` on the avatar image.\n\n\n| Variant     | Purpose                                                | `status` dot |\n| ----------- | ------------------------------------------------------ | ------------ |\n| *(none)*    | Standard single avatar                                 | Supported    |\n| `profile`   | Larger profile-sized avatar for settings/profile pages | Supported    |\n| `group`     | Stacked avatar group with overflow count (`+N`)        | Not shown    |\n| `with-text` | Avatar paired with name and optional sub-text          | Supported    |\n\n\n---\n\n## Quick Start\n\n### Basic Avatar (Image)\n\n```html\n<xpl-avatar name=\"Katie Wilson\" src=\"https://example.com/photo.jpg\"></xpl-avatar>\n```\n\n### Initials Placeholder (No Image)\n\n```html\n<!-- Automatic initials from name -->\n<xpl-avatar name=\"Katie Wilson\" color=\"green\"></xpl-avatar>\n\n<!-- Custom initials via slot -->\n<xpl-avatar color=\"primary\">KW</xpl-avatar>\n```\n\n### With Status Dot\n\nStatus dots are rendered with [`xpl-badge`] using `dot-only` and `bordered`. The `status` prop sets the badge **variant** , so avatar status colors stay aligned with badge semantics across the system.\n\n**Where `status` applies:** default (no `variant`), `profile`, and `with-text`. It does **not** apply to `group` — stacked groups ignore `status`.\n\n**`status` values** (same names as `xpl-badge` `variant` palette values):\n\n\n| `status` | Badge palette    | Typical meaning (choose per product copy) |\n| -------- | ---------------- | ----------------------------------------- |\n| `purple` | Purple (default) | Default / general presence                |\n| `green`  | Green            | Positive, available, success-aligned      |\n| `yellow` | Yellow           | Caution, pending, away, warning-aligned   |\n| `orange` | Orange           | Attention, busy, secondary emphasis       |\n| `gray`   | Gray             | Neutral, offline, inactive                |\n| `red`    | Red              | Error, do not disturb, critical           |\n| `blue`   | Blue             | Informational, notifications              |\n\n\n```html\n<xpl-avatar name=\"Alex Chen\" src=\"photo.jpg\" status=\"green\"></xpl-avatar>\n<xpl-avatar name=\"Jordan Lee\" status=\"red\"></xpl-avatar>\n<xpl-avatar name=\"Sam Smith\" status=\"gray\"></xpl-avatar>\n<xpl-avatar variant=\"with-text\" name=\"Riley Park\" sub-text=\"Designer\" src=\"photo.jpg\" status=\"blue\"></xpl-avatar>\n```\n\n### Clickable Avatar (Link)\n\n```html\n<xpl-avatar name=\"Profile\" src=\"photo.jpg\" href=\"/profile\" target=\"_blank\"></xpl-avatar>\n```\n\n---\n\n## Variant Examples\n\n### Profile Avatar (Larger Size)\n\nFor profile pages and settings surfaces. Optional `status` uses the same badge palette as other non-group variants.\n\n```html\n<!-- Large profile avatar (144px) -->\n<xpl-avatar variant=\"profile\" name=\"Katie Wilson\" src=\"photo.jpg\"></xpl-avatar>\n\n<!-- With status dot -->\n<xpl-avatar variant=\"profile\" name=\"Katie Wilson\" src=\"photo.jpg\" status=\"green\"></xpl-avatar>\n\n<!-- Small profile avatar (80px) -->\n<xpl-avatar variant=\"profile\" name=\"Jordan Lee\" size=\"sm\"></xpl-avatar>\n```\n\n### Avatar Group (Stacked)\n\nDisplays up to 4 visible avatars with a `+N` overflow pill for additional members. The `status` prop is not used in this layout (no per-avatar or group-level status dot).\n\n```html\n<!-- Basic group with JSON data -->\n<xpl-avatar\n  variant=\"group\"\n  group-data='[\n    {\"name\": \"Alex\", \"color\": \"green\"},\n    {\"name\": \"Jordan\", \"color\": \"yellow\"},\n    {\"name\": \"Sam\", \"color\": \"pink\"},\n    {\"src\": \"https://example.com/photo.jpg\", \"name\": \"Dana\"},\n    {\"name\": \"Extra User\"}\n  ]'\n></xpl-avatar>\n\n<!-- Medium group -->\n<xpl-avatar variant=\"group\" size=\"md\" group-data='[...]'></xpl-avatar>\n\n<!-- Small group -->\n<xpl-avatar variant=\"group\" size=\"sm\" group-data='[...]'></xpl-avatar>\n```\n\n**Group data format:**\n\n```typescript\ninterface AvatarGroupItem {\n  src?: string;     // Image URL (optional)\n  name?: string;      // Used for initials and alt text\n  color?: 'green' | 'yellow' | 'pink' | 'primary' | 'secondary';\n}\n```\n\n### Avatar with Text\n\nHorizontal layout with avatar + name + optional sub-text (e.g., email).\n\n```html\n<!-- Basic with-text -->\n<xpl-avatar\n  variant=\"with-text\"\n  name=\"Katie Wilson\"\n  sub-text=\"katie@example.com\"\n  src=\"photo.jpg\"\n></xpl-avatar>\n\n<!-- Clickable version -->\n<xpl-avatar\n  variant=\"with-text\"\n  name=\"View Profile\"\n  sub-text=\"Product Designer\"\n  src=\"photo.jpg\"\n  href=\"/profile\"\n></xpl-avatar>\n\n<!-- With status dot on the avatar -->\n<xpl-avatar\n  variant=\"with-text\"\n  name=\"Katie Wilson\"\n  sub-text=\"katie@example.com\"\n  src=\"photo.jpg\"\n  status=\"green\"\n></xpl-avatar>\n```\n\n---\n\n## Size Options\n\n\n| Size     | Default Avatar | Profile Avatar | Group              |\n| -------- | -------------- | -------------- | ------------------ |\n| *(none)* | 40×40px        | 144×144px      | 40×40px per avatar |\n| `md`     | 32×32px        | —              | 32×32px per avatar |\n| `sm`     | 24×24px        | 80×80px        | 24×24px per avatar |\n\n\n---\n\n## Status vs placeholder `color`\n\n- **`status`** — Badge palette for the **status dot** (`purple` | `green` | `yellow` | `orange` | `gray` | `red` | `blue`). Passed through to `xpl-badge` as `variant`. Not used when `variant=\"group\"`.\n- **`color`** — Placeholder **surface** behind initials when there is no `src` (`green` | `yellow` | `pink` | `primary` | `secondary`). Unrelated to the status dot.\n\n## Color Options (Placeholder Backgrounds)\n\nUse `color` when no `src` is provided to set the placeholder background:\n\n- `green` — Positive accent\n- `yellow` — Highlight accent\n- `pink` — Pink accent\n- `primary` — Brand primary\n- `secondary` — Action primary (purple)\n\n---\n\n## Design tokens\n\nThese are the main Apollo Foundation tokens used in `packages/apollo-core/src/css/avatar.css`. Use them when overriding or migrating styles.\n\n| Role | Token(s) |\n| ---- | -------- |\n| Circular shape | `var(--xpl-border-radius-full)` |\n| Placeholder surface (default) | `var(--xpl-background-brand-secondary)`, `var(--xpl-text-inverse)` |\n| Placeholder `green` / `yellow` / `pink` | `var(--xpl-background-accent-positive)` / `var(--xpl-background-accent-highlight)` / `var(--xpl-background-accent-pink)` with `var(--xpl-text-inverse-on-light)` where applicable |\n| Placeholder `primary` / `secondary` | `var(--xpl-background-accent-brand)` / `var(--xpl-background-brand-secondary)` |\n| Link hover overlay | `var(--xpl-background-surface-transparent-25)` |\n| Focus outline | `var(--xpl-border-accent-default)` base; `color` modifiers use `var(--xpl-border-positive)`, `var(--xpl-border-accent-highlight)`, `var(--xpl-border-accent-brand)`, etc. (`outline` / `outline-offset` per `avatar.css`) |\n| With-text primary line | `var(--xpl-text-strong)`, `var(--xpl-font-size-title-5)`, `var(--xpl-font-weight-medium)` |\n| With-text secondary line | `var(--xpl-text-subdued)`, `var(--xpl-font-size-body)` |\n| Group overflow pill | `var(--xpl-background-surface-subtle)`, `var(--xpl-text-subdued)` |\n| Group avatar ring | `box-shadow` using `var(--xpl-border-large)` and `var(--xpl-background-surface-default)` |\n| Width / height | `var(--xpl-size-*)` for standard sizes; profile default uses `9rem` (documented in `TECH_DEBT.md`) |\n| Spacing & overlap | `var(--xpl-space-*)`, `var(--xpl-z-index-*)` |\n\n**Status dots** are styled by `xpl-badge`; see [`xpl-badge` readme](../xpl-badge/readme.md) for badge token usage.\n\n---\n\n## Accessibility\n\n- `name` is required for proper `alt` text on images and screen reader announcements\n- **Status dots** are implemented via `xpl-badge` and marked `aria-hidden` (purely visual); convey meaning in surrounding UI copy or labels if required\n- **Group overflow** includes `aria-label=\"{count} more\"` for screen readers\n- **Links** use native `<a>` elements with full keyboard support\n- **Disabled state**: Use `disabled` prop to disable link behavior while keeping visual styles\n- **Focus management**: All interactive avatars (links) use `:focus-visible` for keyboard focus indicators\n\n---\n\n## Best Practices\n\n1. **Always provide `name`** — Essential for accessibility (alt text and screen readers; for placeholder initials, slot input has higher priority than the value passed in `name`)\n2. **Use `color` for placeholder consistency** — Assign consistent colors to users based on ID or name hash\n3. **Limit group data** — While the component handles any number, consider capping at reasonable numbers for UX\n4. **Slot content** — Use the default slot sparingly; prefer `name` prop for consistent initials generation\n\n---\n\n## Migration Notes\n\n### Status Dot Implementation:\n\n**What changed:** Status dots are implemented with `xpl-badge` (`dot-only` + `bordered`). The `status` prop uses the **badge color palette** (`purple`, `green`, `yellow`, `orange`, `gray`, `red`, `blue`) — the same names as `xpl-badge` `variant` — so avatar status stays consistent with badge semantics.\n\n**Impact:**\n\n- **Internal markup:** The status dot renders as `<xpl-badge dot-only bordered variant=\"...\">` (with `variant` from `status`), not legacy `.xpl-avatar__dot--` classes.\n- **CSS targeting:** Custom selectors like `.xpl-avatar__dot--active` / `--warning` / `--inactive` are not used. Target `.xpl-avatar .xpl-badge--dot-only` if you must override styles.\n- **Prop values:** Use palette names above. Older examples sometimes used labels like `active` / `warning` / `inactive`; map those concepts to the palette (e.g. available → `green`, caution → `yellow`, offline → `gray`) per your design guidelines.\n\n**Recommended migration:**\n\n1. Replace custom CSS on `.xpl-avatar__dot--` with `.xpl-avatar .xpl-badge--dot-only` if needed\n2. Set `status` to the badge palette value that matches the intended color (see the status table in this readme)\n3. Remember `status` applies to default, `profile`, and `with-text` only — not `group`\n\n### Legacy `status` values — scheduled for removal (next major release)\n\n**These legacy string values are deprecated.** They exist only for backward compatibility with older integrations. They **will be removed** in the **next major** version of `@xplortech/apollo-core`. Plan your migration now; do not introduce new usage of the legacy names.\n\n| Deprecated `status` | Current mapping (temporary) | Replace with (badge palette) |\n| ------------------- | --------------------------- | ---------------------------- |\n| `active`            | `green`                     | `green`                      |\n| `inactive`          | `gray`                      | `gray`                       |\n| `warning`           | `red`                       | `red`                        |\n\n**Why:** Status dots use the same vocabulary as `xpl-badge` variants (`purple`, `green`, `yellow`, `orange`, `gray`, `red`, `blue`). The old semantic aliases (`active` / `warning` / `inactive`) duplicate that meaning with different names and increase maintenance cost, so they are being dropped from the public API.\n\n**Action items before the major release:**\n\n1. Search your codebase for `status=\"active\"`, `status=\"inactive\"`, and `status=\"warning\"` on `<xpl-avatar>` (and framework wrappers).\n2. Replace each with the **`green`**, **`gray`**, or **`red`** value from the table above, matching your product intent.\n3. Re-test visuals: the mapped colors are unchanged today; after removal, only palette names will be accepted.\n\n### Component Dependency\n\nThis component now depends on `xpl-badge`. Ensure `xpl-badge` is loaded in your application when using avatars with status dots.\n\n",
+      "readme": "# xpl-avatar\n\nThe **Avatar** component shows a person or entity: a photo, initials on a colored surface, or custom slot content. It aligns with Apollo’s Figma patterns for default avatars, profile layouts, stacked groups, and rows with supporting text.\n\n## When to use\n\n- **Default (no `variant`)** — Inline UI: tables, nav, comments, lists. Supports image (`src`), initials from `name`, and an optional status dot (`status`).\n- **Profile (`variant=\"profile\"`)** — Large avatars for profile pages and settings surfaces; optional `status` dot uses the same badge palette as the default avatar.\n- **Group (`variant=\"group\"`)** — Stacked avatar groups with overflow count (`+N`). The `status` prop is not used (status dots are not shown for groups).\n- **With Text (`variant=\"with-text\"`)** — Horizontal layout with avatar paired with name and optional sub-text; optional `status` on the avatar image.\n\n\n| Variant     | Purpose                                                | `status` dot |\n| ----------- | ------------------------------------------------------ | ------------ |\n| *(none)*    | Standard single avatar                                 | Supported    |\n| `profile`   | Larger profile-sized avatar for settings/profile pages | Supported    |\n| `group`     | Stacked avatar group with overflow count (`+N`)        | Not shown    |\n| `with-text` | Avatar paired with name and optional sub-text          | Supported    |\n\n\n---\n\n## Quick Start\n\n### Basic Avatar (Image)\n\n```html\n<xpl-avatar name=\"Katie Wilson\" src=\"https://example.com/photo.jpg\"></xpl-avatar>\n```\n\n### Initials Placeholder (No Image)\n\n```html\n<!-- Automatic initials from name -->\n<xpl-avatar name=\"Katie Wilson\" color=\"green\"></xpl-avatar>\n\n<!-- Custom initials via slot -->\n<xpl-avatar color=\"primary\">KW</xpl-avatar>\n```\n\n### With Status Dot\n\nStatus dots are rendered with [`xpl-badge`] using `dot-only` and `bordered`. The `status` prop sets the badge **variant** , so avatar status colors stay aligned with badge semantics across the system.\n\n**Where `status` applies:** default (no `variant`), `profile`, and `with-text`. It does **not** apply to `group` — stacked groups ignore `status`.\n\n**`status` values** (same names as `xpl-badge` `variant` palette values):\n\n\n| `status` | Badge palette    | Typical meaning (choose per product copy) |\n| -------- | ---------------- | ----------------------------------------- |\n| `purple` | Purple (default) | Default / general presence                |\n| `green`  | Green            | Positive, available, success-aligned      |\n| `yellow` | Yellow           | Caution, pending, away, warning-aligned   |\n| `orange` | Orange           | Attention, busy, secondary emphasis       |\n| `gray`   | Gray             | Neutral, offline, inactive                |\n| `red`    | Red              | Error, do not disturb, critical           |\n| `blue`   | Blue             | Informational, notifications              |\n\n\n```html\n<xpl-avatar name=\"Alex Chen\" src=\"photo.jpg\" status=\"green\"></xpl-avatar>\n<xpl-avatar name=\"Jordan Lee\" status=\"red\"></xpl-avatar>\n<xpl-avatar name=\"Sam Smith\" status=\"gray\"></xpl-avatar>\n<xpl-avatar variant=\"with-text\" name=\"Riley Park\" sub-text=\"Designer\" src=\"photo.jpg\" status=\"blue\"></xpl-avatar>\n```\n\n### Clickable Avatar (Link)\n\n```html\n<xpl-avatar name=\"Profile\" src=\"photo.jpg\" href=\"/profile\" target=\"_blank\"></xpl-avatar>\n```\n\n---\n\n## Variant Examples\n\n### Profile Avatar (Larger Size)\n\nFor profile pages and settings surfaces. Optional `status` uses the same badge palette as other non-group variants.\n\n```html\n<!-- Large profile avatar (144px) -->\n<xpl-avatar variant=\"profile\" name=\"Katie Wilson\" src=\"photo.jpg\"></xpl-avatar>\n\n<!-- With status dot -->\n<xpl-avatar variant=\"profile\" name=\"Katie Wilson\" src=\"photo.jpg\" status=\"green\"></xpl-avatar>\n\n<!-- Small profile avatar (80px) -->\n<xpl-avatar variant=\"profile\" name=\"Jordan Lee\" size=\"sm\"></xpl-avatar>\n```\n\n### Avatar Group (Stacked)\n\nDisplays up to 4 visible avatars with a `+N` overflow pill for additional members. The `status` prop is not used in this layout (no per-avatar or group-level status dot).\n\n```html\n<!-- Basic group with JSON data -->\n<xpl-avatar\n  variant=\"group\"\n  group-data='[\n    {\"name\": \"Alex\", \"color\": \"green\"},\n    {\"name\": \"Jordan\", \"color\": \"yellow\"},\n    {\"name\": \"Sam\", \"color\": \"pink\"},\n    {\"src\": \"https://example.com/photo.jpg\", \"name\": \"Dana\"},\n    {\"name\": \"Extra User\"}\n  ]'\n></xpl-avatar>\n\n<!-- Medium group -->\n<xpl-avatar variant=\"group\" size=\"md\" group-data='[...]'></xpl-avatar>\n\n<!-- Small group -->\n<xpl-avatar variant=\"group\" size=\"sm\" group-data='[...]'></xpl-avatar>\n```\n\n**Group data format:**\n\n```typescript\ninterface AvatarGroupItem {\n  src?: string;     // Image URL (optional)\n  name?: string;      // Used for initials and alt text\n  color?: 'green' | 'yellow' | 'pink' | 'primary' | 'secondary';\n}\n```\n\n### Avatar with Text\n\nHorizontal layout with avatar + name + optional sub-text (e.g., email).\n\n```html\n<!-- Basic with-text -->\n<xpl-avatar\n  variant=\"with-text\"\n  name=\"Katie Wilson\"\n  sub-text=\"katie@example.com\"\n  src=\"photo.jpg\"\n></xpl-avatar>\n\n<!-- Clickable version -->\n<xpl-avatar\n  variant=\"with-text\"\n  name=\"View Profile\"\n  sub-text=\"Product Designer\"\n  src=\"photo.jpg\"\n  href=\"/profile\"\n></xpl-avatar>\n\n<!-- With status dot on the avatar -->\n<xpl-avatar\n  variant=\"with-text\"\n  name=\"Katie Wilson\"\n  sub-text=\"katie@example.com\"\n  src=\"photo.jpg\"\n  status=\"green\"\n></xpl-avatar>\n```\n\n---\n\n## Size Options\n\n\n| Size     | Default Avatar | Profile Avatar | Group              |\n| -------- | -------------- | -------------- | ------------------ |\n| *(none)* | 40×40px        | 144×144px      | 40×40px per avatar |\n| `md`     | 32×32px        | —              | 32×32px per avatar |\n| `sm`     | 24×24px        | 80×80px        | 24×24px per avatar |\n\n\n---\n\n## Status vs placeholder `color`\n\n- **`status`** — Badge palette for the **status dot** (`purple` | `green` | `yellow` | `orange` | `gray` | `red` | `blue`). Passed through to `xpl-badge` as `variant`. Not used when `variant=\"group\"`.\n- **`color`** — Placeholder **surface** behind initials when there is no `src` (`green` | `yellow` | `pink` | `primary` | `secondary`). Unrelated to the status dot.\n\n## Color Options (Placeholder Backgrounds)\n\nUse `color` when no `src` is provided to set the placeholder background:\n\n- `green` — Positive accent\n- `yellow` — Highlight accent\n- `pink` — Pink accent\n- `primary` — Brand primary\n- `secondary` — Action primary (purple)\n\n---\n\n## Design tokens\n\nThese are the main Apollo Foundation tokens used in `packages/apollo-core/src/css/avatar.css`. Use them when overriding or migrating styles.\n\n| Role | Token(s) |\n| ---- | -------- |\n| Circular shape | `var(--xpl-border-radius-full)` |\n| Placeholder surface (default) | `var(--xpl-background-brand-secondary)`, `var(--xpl-text-inverse)` |\n| Placeholder `green` / `yellow` / `pink` | `var(--xpl-background-accent-positive)` / `var(--xpl-background-accent-highlight)` / `var(--xpl-background-accent-pink)` with `var(--xpl-text-inverse-on-light)` where applicable |\n| Placeholder `primary` / `secondary` | `var(--xpl-background-accent-brand)` / `var(--xpl-background-brand-secondary)` |\n| Link hover overlay | `var(--xpl-background-surface-transparent-25)` |\n| Focus outline | `var(--xpl-border-accent-default)` base; `color` modifiers use `var(--xpl-border-positive)`, `var(--xpl-border-accent-highlight)`, `var(--xpl-border-accent-brand)`, etc. (`outline` / `outline-offset` per `avatar.css`) |\n| With-text primary line | `var(--xpl-text-strong)`, `var(--xpl-font-size-title-5)`, `var(--xpl-font-weight-medium)` |\n| With-text secondary line | `var(--xpl-text-subdued)`, `var(--xpl-font-size-body)` |\n| Group overflow pill | `var(--xpl-background-surface-subtle)`, `var(--xpl-text-subdued)` |\n| Group avatar ring | `box-shadow` using `var(--xpl-border-large)` and `var(--xpl-background-surface-default)` |\n| Width / height | `var(--xpl-size-*)` for standard sizes; profile default uses `var(--xpl-size-900)` (144px) |\n| Spacing & overlap | `var(--xpl-space-*)`, `var(--xpl-z-index-*)` |\n\n**Status dots** are styled by `xpl-badge`; see [`xpl-badge` readme](../xpl-badge/readme.md) for badge token usage.\n\n---\n\n## Accessibility\n\n- `name` is required for proper `alt` text on images and screen reader announcements\n- **Status dots** are implemented via `xpl-badge` and marked `aria-hidden` (purely visual); convey meaning in surrounding UI copy or labels if required\n- **Group overflow** includes `aria-label=\"{count} more\"` for screen readers\n- **Links** use native `<a>` elements with full keyboard support\n- **Disabled state**: Use `disabled` prop to disable link behavior while keeping visual styles\n- **Focus management**: All interactive avatars (links) use `:focus-visible` for keyboard focus indicators\n\n---\n\n## Best Practices\n\n1. **Always provide `name`** — Essential for accessibility (alt text and screen readers; for placeholder initials, slot input has higher priority than the value passed in `name`)\n2. **Use `color` for placeholder consistency** — Assign consistent colors to users based on ID or name hash\n3. **Limit group data** — While the component handles any number, consider capping at reasonable numbers for UX\n4. **Slot content** — Use the default slot sparingly; prefer `name` prop for consistent initials generation\n\n---\n\n## Migration Notes\n\n### Status Dot Implementation:\n\n**What changed:** Status dots are implemented with `xpl-badge` (`dot-only` + `bordered`). The `status` prop uses the **badge color palette** (`purple`, `green`, `yellow`, `orange`, `gray`, `red`, `blue`) — the same names as `xpl-badge` `variant` — so avatar status stays consistent with badge semantics.\n\n**Impact:**\n\n- **Internal markup:** The status dot renders as `<xpl-badge dot-only bordered variant=\"...\">` (with `variant` from `status`), not legacy `.xpl-avatar__dot--` classes.\n- **CSS targeting:** Custom selectors like `.xpl-avatar__dot--active` / `--warning` / `--inactive` are not used. Target `.xpl-avatar .xpl-badge--dot-only` if you must override styles.\n- **Prop values:** Use palette names above. Older examples sometimes used labels like `active` / `warning` / `inactive`; map those concepts to the palette (e.g. available → `green`, caution → `yellow`, offline → `gray`) per your design guidelines.\n\n**Recommended migration:**\n\n1. Replace custom CSS on `.xpl-avatar__dot--` with `.xpl-avatar .xpl-badge--dot-only` if needed\n2. Set `status` to the badge palette value that matches the intended color (see the status table in this readme)\n3. Remember `status` applies to default, `profile`, and `with-text` only — not `group`\n\n### Legacy `status` values — scheduled for removal (next major release)\n\n**These legacy string values are deprecated.** They exist only for backward compatibility with older integrations. They **will be removed** in the **next major** version of `@xplortech/apollo-core`. Plan your migration now; do not introduce new usage of the legacy names.\n\n| Deprecated `status` | Current mapping (temporary) | Replace with (badge palette) |\n| ------------------- | --------------------------- | ---------------------------- |\n| `active`            | `green`                     | `green`                      |\n| `inactive`          | `gray`                      | `gray`                       |\n| `warning`           | `red`                       | `red`                        |\n\n**Why:** Status dots use the same vocabulary as `xpl-badge` variants (`purple`, `green`, `yellow`, `orange`, `gray`, `red`, `blue`). The old semantic aliases (`active` / `warning` / `inactive`) duplicate that meaning with different names and increase maintenance cost, so they are being dropped from the public API.\n\n**Action items before the major release:**\n\n1. Search your codebase for `status=\"active\"`, `status=\"inactive\"`, and `status=\"warning\"` on `<xpl-avatar>` (and framework wrappers).\n2. Replace each with the **`green`**, **`gray`**, or **`red`** value from the table above, matching your product intent.\n3. Re-test visuals: the mapped colors are unchanged today; after removal, only palette names will be accepted.\n\n### Component Dependency\n\nThis component now depends on `xpl-badge`. Ensure `xpl-badge` is loaded in your application when using avatars with status dots.\n\n",
       "docs": "The **Avatar** component shows a person or entity: a photo, initials on a colored surface, or custom slot content. It aligns with Apollo’s Figma patterns for default avatars, profile layouts, stacked groups, and rows with supporting text.",
       "docsTags": [
         {
@@ -2823,7 +2823,6 @@
       "dependents": [
         "xpl-choicelist",
         "xpl-header-accordion",
-        "xpl-table",
         "xpl-table-header-cell"
       ],
       "dependencies": [],
@@ -2834,9 +2833,6 @@
         "xpl-header-accordion": [
           "xpl-checkbox"
         ],
-        "xpl-table": [
-          "xpl-checkbox"
-        ],
         "xpl-table-header-cell": [
           "xpl-checkbox"
         ]
@@ -3152,7 +3148,7 @@
       "filePath": "src/components/components/xpl-data-card/xpl-data-card.tsx",
       "encapsulation": "none",
       "tag": "xpl-data-card",
-      "readme": "# xpl-data-card\n\nData Cards display snippets of information and can be linked to larger data sets. Data Cards give users \"at a glance\" information about their data.\n\nThe `icon` and `smallStatIcon` properties accept icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.\n\n## Design Tokens\n\nThe card is styled entirely with Apollo Foundation purpose-specific tokens (dark mode is automatic — no `.dark` overrides).\n\n| Element / state | Property | Token |\n| --- | --- | --- |\n| Host surface | `background-color` | `--xpl-background-surface-default` |\n| Host / anchor border | `border-color` | `--xpl-border-default` |\n| Host, header, stats text | `color` | `--xpl-text-default` |\n| Header arrow (chevron) icon | `color` | `--xpl-icon-default` |\n| Detail text | `color` | `--xpl-text-subdued` |\n| `.positive` stat | `color` | `--xpl-text-positive` |\n| `.negative` stat | `color` | `--xpl-text-negative` |\n| `.neutral` stat | `color` | `--xpl-text-subdued` |\n| Primary leading icon | `color` | `--xpl-icon-brand` (orange) |\n| Secondary leading icon | `color` | `--xpl-background-action-primary-default` (purple) |\n| Anchor hover / active border | `border` | `--xpl-border-small` + `--xpl-background-action-primary-default` |\n| Anchor focus-visible border | `border` | `--xpl-border-small` + `--xpl-border-focus` (purple) |\n| Anchor focus-visible outline | `outline` | `--xpl-border-focus`, 2px width / 2px offset |\n| Anchor hover / focus-visible radius | `border-radius` | `--xpl-border-radius-default` |\n| Anchor hover shadow | `box-shadow` | `--xpl-background-surface-transparent-10` / `--xpl-background-surface-transparent-5` |\n| Header / stat spacing | `margin` | `--xpl-space-4`, `--xpl-space-6` |\n| Container-query stat | `font-size` | `--xpl-font-size-title-2` |\n\nThe resting anchor overlay keeps a `0.375rem` (6px) radius to match the card's `rounded-md`; Foundation has no 6px radius token (see `TECH_DEBT.md`).\n",
+      "readme": "# xpl-data-card\n\nData Cards display snippets of information and can be linked to larger data sets. Data Cards give users \"at a glance\" information about their data.\n\nThe `icon` and `smallStatIcon` properties accept icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.\n\n## Design Tokens\n\nThe card is styled entirely with Apollo Foundation purpose-specific tokens (dark mode is automatic — no `.dark` overrides).\n\n| Element / state | Property | Token |\n| --- | --- | --- |\n| Host surface | `background-color` | `--xpl-background-surface-default` |\n| Host / anchor border | `border-color` | `--xpl-border-default` |\n| Host, header, stats text | `color` | `--xpl-text-default` |\n| Header arrow (chevron) icon | `color` | `--xpl-icon-default` |\n| Detail text | `color` | `--xpl-text-subdued` |\n| `.positive` stat | `color` | `--xpl-text-positive` |\n| `.negative` stat | `color` | `--xpl-text-negative` |\n| `.neutral` stat | `color` | `--xpl-text-subdued` |\n| Primary leading icon | `color` | `--xpl-icon-brand` (orange) |\n| Secondary leading icon | `color` | `--xpl-background-action-primary-default` (purple) |\n| Anchor hover / active border | `border` | `--xpl-border-small` + `--xpl-background-action-primary-default` |\n| Anchor focus-visible border | `border` | `--xpl-border-small` + `--xpl-border-focus` (purple) |\n| Anchor focus-visible outline | `outline` | `--xpl-border-focus`, 2px width / 2px offset |\n| Anchor hover / focus-visible radius | `border-radius` | `--xpl-border-radius-default` |\n| Anchor hover shadow | `box-shadow` | `--xpl-elevation-2` (theme-aware) |\n| Header / stat spacing | `margin` | `--xpl-space-4`, `--xpl-space-6` |\n| Container-query stat | `font-size` | `--xpl-font-size-title-2` |\n\nThe resting anchor overlay keeps a `0.375rem` (6px) radius to match the card's `rounded-md`; Foundation has no 6px radius token (see `TECH_DEBT.md`).\n",
       "docs": "Data Cards display snippets of information and can be linked to larger data sets. Data Cards give users \"at a glance\" information about their data.\n\nThe `icon` and `smallStatIcon` properties accept icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.",
       "docsTags": [
         {
@@ -4413,8 +4409,8 @@
       "filePath": "src/components/components/xpl-dynamic-table/xpl-dynamic-table.tsx",
       "encapsulation": "none",
       "tag": "xpl-dynamic-table",
-      "readme": "# xpl-dynamic-table\n\n> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\nThe Dynamic Table is a rich content table that can accommodate multiple types of data. \n\n## Design Tokens\n\nThe table, cells, and rows use Apollo Foundation purpose-specific tokens (light / dark resolve automatically — no `.dark` overrides):\n\n**Table** (`.xpl-dynamic-table`)\n\n| Element | Property | Token |\n| --- | --- | --- |\n| Grid columns | `grid-template-columns` | `--xpl-column-widths` (set at runtime from header cell widths) |\n| Row gap (with accordions) | `row-gap` (8px) | `--xpl-space-8` |\n\n**Cell** (`.xpl-dynamic-table-cell`)\n\n| Element | Property | Token |\n| --- | --- | --- |\n| Cell | Background | `--xpl-background-surface-default` |\n| Cell | Border | `--xpl-border-default` |\n| Cell | Text | `--xpl-text-default` |\n| Cell | Typography (title-5 / medium / 1.4286) | `@extend .xpl-text-title-5` |\n| Cell | Height (56px) | `--xpl-size-350` |\n| Cell | Min width (48px) | `--xpl-size-300` |\n| Cell rounded corners | Border radius (8px) | `--xpl-border-radius-default` |\n| Cell icons (chevron, kebab) | Color | `--xpl-icon-default` |\n| Dropdown button (`:focus-visible`) | Inset ring | `--xpl-border-focus` |\n\n**Row** (`.xpl-dynamic-table-row`)\n\n| State | Property | Token |\n| --- | --- | --- |\n| First cell | Left border | `--xpl-border-default` |\n| Selected | Cell background | `--xpl-background-surface-information` |\n| Disabled | Cell background | `--xpl-background-surface-subtlest` |\n| Disabled | Cell / badge text | `--xpl-text-disabled` |\n| Disabled | Cell icons | `--xpl-icon-disabled` |\n",
-      "docs": "> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\nThe Dynamic Table is a rich content table that can accommodate multiple types of data.",
+      "readme": "# xpl-dynamic-table\n\n> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\nThe Dynamic Table is a rich content table that can accommodate multiple types of data.\n\n> **[DEPRECATED]** Use the compositional `<xpl-table>` API instead.\n> This component will be removed in a future major release.\n\n## Design Tokens\n\nThe table, cells, and rows use Apollo Foundation purpose-specific tokens (light / dark resolve automatically — no `.dark` overrides):\n\n**Table** (`.xpl-dynamic-table`)\n\n| Element | Property | Token |\n| --- | --- | --- |\n| Grid columns | `grid-template-columns` | `--xpl-column-widths` (set at runtime from header cell widths) |\n| Row gap (with accordions) | `row-gap` (8px) | `--xpl-space-8` |\n\n**Cell** (`.xpl-dynamic-table-cell`)\n\n| Element | Property | Token |\n| --- | --- | --- |\n| Cell | Background | `--xpl-background-surface-default` |\n| Cell | Border | `--xpl-border-default` |\n| Cell | Text | `--xpl-text-default` |\n| Cell | Typography (title-5 / medium / 1.4286) | `@extend .xpl-text-title-5` |\n| Cell | Height (56px) | `--xpl-size-350` |\n| Cell | Min width (48px) | `--xpl-size-300` |\n| Cell rounded corners | Border radius (8px) | `--xpl-border-radius-default` |\n| Cell icons (chevron, kebab) | Color | `--xpl-icon-default` |\n| Dropdown button (`:focus-visible`) | Inset ring | `--xpl-border-focus` |\n\n**Row** (`.xpl-dynamic-table-row`)\n\n| State | Property | Token |\n| --- | --- | --- |\n| First cell | Left border | `--xpl-border-default` |\n| Selected | Cell background | `--xpl-background-surface-information` |\n| Disabled | Cell background | `--xpl-background-surface-subtlest` |\n| Disabled | Cell / badge text | `--xpl-text-disabled` |\n| Disabled | Cell icons | `--xpl-icon-disabled` |\n",
+      "docs": "> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\nThe Dynamic Table is a rich content table that can accommodate multiple types of data.\n\n> **[DEPRECATED]** Use the compositional `<xpl-table>` API instead.\n> This component will be removed in a future major release.",
       "docsTags": [
         {
           "name": "since",
@@ -4466,8 +4462,8 @@
       "filePath": "src/components/components/xpl-dynamic-table-cell/xpl-dynamic-table-cell.tsx",
       "encapsulation": "none",
       "tag": "xpl-dynamic-table-cell",
-      "readme": "# xpl-dynamic-table-cell\n\n> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\n",
-      "docs": "> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.",
+      "readme": "# xpl-dynamic-table-cell\n\n> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\n> **[DEPRECATED]** Use `<xpl-table-cell>` instead.\n> This component will be removed in a future major release.\n",
+      "docs": "> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\n> **[DEPRECATED]** Use `<xpl-table-cell>` instead.\n> This component will be removed in a future major release.",
       "docsTags": [
         {
           "name": "since",
@@ -4521,8 +4517,8 @@
       "filePath": "src/components/components/xpl-dynamic-table-row/xpl-dynamic-table-row.tsx",
       "encapsulation": "none",
       "tag": "xpl-dynamic-table-row",
-      "readme": "# xpl-dynamic-table-row\n\n> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\n",
-      "docs": "> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.",
+      "readme": "# xpl-dynamic-table-row\n\n> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\n> **[DEPRECATED]** Use `<xpl-table-row>` instead.\n> This component will be removed in a future major release.\n",
+      "docs": "> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\n> **[DEPRECATED]** Use `<xpl-table-row>` instead.\n> This component will be removed in a future major release.",
       "docsTags": [
         {
           "name": "since",
@@ -8085,7 +8081,7 @@
       "filePath": "src/components/components/xpl-input/xpl-input-time/xpl-input-time.tsx",
       "encapsulation": "none",
       "tag": "xpl-input-time",
-      "readme": "# xpl-input-time\n\n\n\n### Design Tokens\n\nTokens used by this component from `@xplortech/apollo-foundation`.\n\n**Color**\n- `--xpl-border-negative` — error state border color (unified with input-date / input-color)\n- `--xpl-icon-default` — leading clock icon color (matches input-date's calendar icon)\n- `--xpl-background-surface-transparent-10`, `--xpl-background-surface-transparent-5` — time dropdown box-shadow (purpose-specific; flips to white-based transparency in dark mode)\n",
+      "readme": "# xpl-input-time\n\n\n\n### Design Tokens\n\nTokens used by this component from `@xplortech/apollo-foundation`.\n\n**Color**\n- `--xpl-border-negative` — error state border color (unified with input-date / input-color)\n- `--xpl-icon-default` — leading clock icon color (matches input-date's calendar icon)\n- `--xpl-elevation-2` — time dropdown box-shadow (theme-aware; references the surface-transparent tokens, which flip to white-based transparency in dark mode)\n",
       "docs": "",
       "docsTags": [],
       "usage": {},
@@ -8532,7 +8528,7 @@
       "filePath": "src/components/components/xpl-large-card/xpl-large-card.tsx",
       "encapsulation": "none",
       "tag": "xpl-large-card",
-      "readme": "# xpl-large-card\n\nA 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.\n\n## Design Tokens\n\nThe card is styled entirely with Apollo Foundation purpose-specific tokens (dark mode is automatic — no `.dark` overrides).\n\n| Element / state | Property | Token |\n| --- | --- | --- |\n| Host surface | `background-color` | `--xpl-background-surface-default` |\n| Host / anchor border | `border-color` | `--xpl-border-default` |\n| Host, header text | `color` | `--xpl-text-default` |\n| Header arrow (chevron) icon | `color` | `--xpl-icon-default` |\n| Description text | `color` | `--xpl-text-subdued` |\n| Anchor hover / active border | `border` | `--xpl-border-small` + `--xpl-background-action-primary-default` |\n| Anchor focus-visible border | `border` | `--xpl-border-small` + `--xpl-border-focus` (purple) |\n| Anchor focus-visible outline | `outline` | `--xpl-border-focus`, 2px width / 2px offset |\n| Anchor hover / focus-visible radius | `border-radius` | `--xpl-border-radius-default` |\n| Anchor hover shadow | `box-shadow` | `--xpl-background-surface-transparent-10` / `--xpl-background-surface-transparent-5` |\n| Header / tooltip / icon spacing | `margin` | `--xpl-space-4`, `--xpl-space-6`, `--xpl-space-8` |\n",
+      "readme": "# xpl-large-card\n\nA 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.\n\n## Design Tokens\n\nThe card is styled entirely with Apollo Foundation purpose-specific tokens (dark mode is automatic — no `.dark` overrides).\n\n| Element / state | Property | Token |\n| --- | --- | --- |\n| Host surface | `background-color` | `--xpl-background-surface-default` |\n| Host / anchor border | `border-color` | `--xpl-border-default` |\n| Host, header text | `color` | `--xpl-text-default` |\n| Header arrow (chevron) icon | `color` | `--xpl-icon-default` |\n| Description text | `color` | `--xpl-text-subdued` |\n| Anchor hover / active border | `border` | `--xpl-border-small` + `--xpl-background-action-primary-default` |\n| Anchor focus-visible border | `border` | `--xpl-border-small` + `--xpl-border-focus` (purple) |\n| Anchor focus-visible outline | `outline` | `--xpl-border-focus`, 2px width / 2px offset |\n| Anchor hover / focus-visible radius | `border-radius` | `--xpl-border-radius-default` |\n| Anchor hover shadow | `box-shadow` | `--xpl-elevation-2` (theme-aware) |\n| Header / tooltip / icon spacing | `margin` | `--xpl-space-4`, `--xpl-space-6`, `--xpl-space-8` |\n",
       "docs": "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.",
       "docsTags": [
         {
@@ -9545,7 +9541,7 @@
       "filePath": "src/components/components/xpl-modal/xpl-modal.tsx",
       "encapsulation": "none",
       "tag": "xpl-modal",
-      "readme": "# xpl-modal\n\nModals are dialogs that focus the user’s attention exclusively on one task or piece of information via a window layer above the current content.\n\nModals are disruptive and should only be used when disrupting the user’s flow is desired.\n\n## Token Use\n\n`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.\n\n| Element | Property | Token |\n| ------- | -------- | ----- |\n| `&__dialog` | background | `--xpl-background-surface-default` |\n| `&__dialog` | text color | `--xpl-text-default` |\n| `&__dialog` | radius | `--xpl-border-radius-large` |\n| `&__dialog` | shadow color | `--xpl-color-transparent-neutral-10` / `--xpl-color-transparent-neutral-5` |\n| `&__title` | typography (size / weight / line-height) | `@extend .xpl-text-title-3` → `title-3` / `bold` / `1.4` |\n| `&__subtitle` | color | `--xpl-text-subdued` |\n| `&__subtitle` | typography (size / weight / line-height) | `@extend .xpl-text-callout` → `callout` / `normal` / `1.3333` |\n| `&__body` | typography (size / weight / line-height) | `@extend .xpl-text-body` → `body` / `normal` / `1.4286` |\n| `&__alert-icon` | color | `--xpl-icon-negative` |\n\nModal widths are documented CSS literals: small `400px`, medium `600px`, large `800px`, mobile `350px` (see `modal.css` and `TECH_DEBT.md`).\n\n> **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`.\n\n## Accessibility\n\n`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`).\n\nKeyboard 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.\n\n### Accessible names\n\nThe 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.\n\nThe close (×) button carries `aria-label=\"Close modal\"`, so screen readers announce its purpose instead of the underlying icon name.\n\n## Mounting and unmounting\n\n`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.\n",
+      "readme": "# xpl-modal\n\nModals are dialogs that focus the user’s attention exclusively on one task or piece of information via a window layer above the current content.\n\nModals are disruptive and should only be used when disrupting the user’s flow is desired.\n\n## Token Use\n\n`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.\n\n| Element | Property | Token |\n| ------- | -------- | ----- |\n| `&__dialog` | background | `--xpl-background-surface-default` |\n| `&__dialog` | text color | `--xpl-text-default` |\n| `&__dialog` | radius | `--xpl-border-radius-large` |\n| `&__dialog` | shadow | `--xpl-elevation-4` (theme-aware) |\n| `&__title` | typography (size / weight / line-height) | `@extend .xpl-text-title-3` → `title-3` / `bold` / `1.4` |\n| `&__subtitle` | color | `--xpl-text-subdued` |\n| `&__subtitle` | typography (size / weight / line-height) | `@extend .xpl-text-callout` → `callout` / `normal` / `1.3333` |\n| `&__body` | typography (size / weight / line-height) | `@extend .xpl-text-body` → `body` / `normal` / `1.4286` |\n| `&__alert-icon` | color | `--xpl-icon-negative` |\n\nModal widths are documented CSS literals: small `400px`, medium `600px`, large `800px`, mobile `350px` (see `modal.css` and `TECH_DEBT.md`).\n\n> **Elevation shadow:** the dialog uses `--xpl-elevation-4` (theme-aware), which matches Figma's \"Shadow 4\" style (`y=20`, `blur=25`, color `background-surface-transparent-10`). See `TECH_DEBT.md`.\n\n## Accessibility\n\n`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`).\n\nKeyboard 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.\n\n### Accessible names\n\nThe 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.\n\nThe close (×) button carries `aria-label=\"Close modal\"`, so screen readers announce its purpose instead of the underlying icon name.\n\n## Mounting and unmounting\n\n`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.\n",
       "docs": "Modals are dialogs that focus the user’s attention exclusively on one task or piece of information via a window layer above the current content.\n\nModals are disruptive and should only be used when disrupting the user’s flow is desired.",
       "docsTags": [
         {
@@ -10256,7 +10252,7 @@
       "filePath": "src/components/components/xpl-popover/xpl-popover.tsx",
       "encapsulation": "none",
       "tag": "xpl-popover",
-      "readme": "# xpl-popover\n\nA 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.\n\n\n### Design Tokens\n\nTokens used by this component from `@xplortech/apollo-foundation`.\n\n**Color**\n- `--xpl-background-surface-default` — content panel background and arrow fill\n- `--xpl-background-surface-transparent-10` — shadow primary layer\n- `--xpl-background-surface-transparent-5` — shadow secondary layer\n- `--xpl-text-default` — content text color\n- `--xpl-border-default` — content panel border and arrow stroke\n\n**Spacing**\n- `--xpl-space-8` — popover margin (offset from trigger), via `--xpl-popover-margin`\n- `--xpl-space-16` — content panel padding (Figma `padding/tight`; corrected from the legacy 24px during the Foundation migration — see `TECH_DEBT.md`)\n\n**Border**\n- `--xpl-border-small` — border width (1px)\n- `--xpl-border-radius-default` — content panel corner radius (8px)\n\n**Z-index**\n- `--xpl-z-index-100` — content panel stacking order\n- `--xpl-z-index-900` — arrow stacking order\n",
+      "readme": "# xpl-popover\n\nA 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.\n\n\n### Design Tokens\n\nTokens used by this component from `@xplortech/apollo-foundation`.\n\n**Color**\n- `--xpl-background-surface-default` — content panel background and arrow fill\n- `--xpl-elevation-2` — content panel shadow (theme-aware)\n- `--xpl-text-default` — content text color\n- `--xpl-border-default` — content panel border and arrow stroke\n\n**Spacing**\n- `--xpl-space-8` — popover margin (offset from trigger), via `--xpl-popover-margin`\n- `--xpl-space-16` — content panel padding (Figma `padding/tight`; corrected from the legacy 24px during the Foundation migration — see `TECH_DEBT.md`)\n\n**Border**\n- `--xpl-border-small` — border width (1px)\n- `--xpl-border-radius-default` — content panel corner radius (8px)\n\n**Z-index**\n- `--xpl-z-index-100` — content panel stacking order\n- `--xpl-z-index-900` — arrow stacking order\n",
       "docs": "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.",
       "docsTags": [
         {
@@ -12755,7 +12751,7 @@
       "filePath": "src/components/components/xpl-slideout/xpl-slideout.tsx",
       "encapsulation": "none",
       "tag": "xpl-slideout",
-      "readme": "# xpl-slideout\n\nContent 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.\n\n## Token Use\n\n`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.\n\n| Element | Property | Token |\n| ------- | -------- | ----- |\n| `.slideout` | background | `--xpl-background-surface-default` |\n| `.slideout` | shadow color | `--xpl-color-transparent-neutral-10` / `--xpl-color-transparent-neutral-5` |\n| `.title` | color | `--xpl-text-default` |\n| `.title` | typography (size / weight / line-height) | `@extend .xpl-text-title-3` → `title-3` / `bold` / `1.4` |\n| `.subtitle` | color | `--xpl-text-subdued` |\n| `.subtitle` | typography (size / weight / line-height) | `@extend .xpl-text-body` → `body` / `normal` / `1.4286` |\n| `.content` | text color | `--xpl-text-default` |\n| `.content.has-shadow` | scroll-overflow shadow (top/bottom only) | `--xpl-color-transparent-neutral-10` / `--xpl-color-transparent-neutral-5` |\n| search `.xpl-input-wrapper` | background | `--xpl-background-surface-default` |\n| search `input` | color | `--xpl-text-default` |\n\nPanel widths are documented CSS literals: `min-width: 21.5rem`, `max-width: 37.5rem` (see `slideout.css` and `TECH_DEBT.md`).\n\nThe `.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.\n\n> **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`.\n",
+      "readme": "# xpl-slideout\n\nContent 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.\n\n## Token Use\n\n`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.\n\n| Element | Property | Token |\n| ------- | -------- | ----- |\n| `.slideout` | background | `--xpl-background-surface-default` |\n| `.slideout` | shadow color | `--xpl-color-transparent-neutral-10` / `--xpl-color-transparent-neutral-5` |\n| `.title` | color | `--xpl-text-default` |\n| `.title` | typography (size / weight / line-height) | `@extend .xpl-text-title-3` → `title-3` / `bold` / `1.4` |\n| `.subtitle` | color | `--xpl-text-subdued` |\n| `.subtitle` | typography (size / weight / line-height) | `@extend .xpl-text-body` → `body` / `normal` / `1.4286` |\n| `.content` | text color | `--xpl-text-default` |\n| `.content.has-shadow` | scroll-overflow shadow (top/bottom only) | `--xpl-color-transparent-neutral-10` / `--xpl-color-transparent-neutral-5` |\n| search `.xpl-input-wrapper` | background | `--xpl-background-surface-default` |\n| search `input` | color | `--xpl-text-default` |\n\nPanel widths are documented CSS literals: `min-width: 21.5rem`, `max-width: 37.5rem` (see `slideout.css` and `TECH_DEBT.md`).\n\nThe `.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.\n\n> **Elevation shadow (documented deviation):** the panel shadow is a custom single-edge shadow cast left onto the page content (`-10px 0 15px -3px`, `4px 0 6px -2px` over `--xpl-color-transparent-neutral-10 / -5`). Figma specs a leading-edge-only shadow for this right-anchored panel; the shared `--xpl-elevation-*` tokens are vertical (bottom-cast) and do not fit a side-anchored panel, so the hand-authored geometry is kept — see `TECH_DEBT.md`.\n",
       "docs": "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.",
       "docsTags": [
         {
@@ -12939,7 +12935,7 @@
       "filePath": "src/components/components/xpl-spotlight/xpl-spotlight.tsx",
       "encapsulation": "none",
       "tag": "xpl-spotlight",
-      "readme": "# xpl-spotlight\n\n`xpl-spotlight` renders a guided-tour callout with an anchor dot, optional media, step messaging, and prop-driven footer actions. It can either render inline using the requested `anchorPosition` or attach to a target element with Floating UI when `target` is provided.\n\n## Usage Examples\n\nUse the built-in title/body props and default actions for a simple tour step:\n\n```html\n<xpl-spotlight\n  heading=\"Review recent activity\"\n  body=\"Check status updates here before moving to the next step.\"\n  action-layout=\"default\"\n  anchor-position=\"top-right\"\n  current-step=\"2\"\n  total-steps=\"5\"\n  is-dismissible=\"true\"\n  is-open=\"true\"\n  primary-action-label=\"Next\"\n  secondary-action-label=\"Back\"\n  show-actions=\"true\"\n  show-image=\"true\"\n  show-steps=\"true\"\n  target=\"\"\n></xpl-spotlight>\n```\n\nAnchor the spotlight to a specific element and provide custom media content:\n\n```html\n<button id=\"dashboard-filter-button\" type=\"button\">Filters</button>\n\n<xpl-spotlight\n  target=\"#dashboard-filter-button\"\n  heading=\"Narrow the results\"\n  body=\"Use filters to focus on the accounts or activity that matter most.\"\n  current-step=\"1\"\n  total-steps=\"3\"\n  primary-action-label=\"Next\"\n  secondary-action-label=\"Skip\"\n>\n  <div slot=\"image\">\n    <img src=\"/assets/spotlight-filter-preview.png\" alt=\"Preview of filter controls\" />\n  </div>\n</xpl-spotlight>\n```\n\n\nControl visibility from the parent with `is-open` and close it by responding to `dismiss`:\n\n```html\n<xpl-spotlight\n  id=\"guided-tour-step\"\n  is-open=\"true\"\n  heading=\"Review recent activity\"\n  body=\"Check status updates here before moving to the next step.\"\n></xpl-spotlight>\n\n<script>\n  const spotlight = document.getElementById('guided-tour-step');\n\n  spotlight?.addEventListener('dismiss', () => {\n    spotlight.setAttribute('is-open', 'false');\n  });\n</script>\n```\n\nMirror the same layout in plain HTML when documenting or prototyping the component structure outside the custom element:\n\n```html\n<div class=\"xpl-spotlight xpl-spotlight--top-left xpl-spotlight--visible\"\n     role=\"dialog\" aria-modal=\"false\" aria-labelledby=\"spotlight-title\" tabindex=\"-1\">\n  <button type=\"button\" class=\"xpl-spotlight__target\" aria-label=\"Spotlight indicator\">\n    <div class=\"xpl-spotlight__target-outer\"></div>\n    <div class=\"xpl-spotlight__target-inner\"></div>\n  </button>\n  <div class=\"xpl-spotlight__dismiss\">\n    <xpl-button variant=\"secondary\" size=\"sm\" icon-only aria-label=\"Dismiss tour step\">\n      <xpl-icon icon=\"xmark\" size=\"16\"></xpl-icon>\n    </xpl-button>\n  </div>\n  <div class=\"xpl-spotlight__frame\">\n    <div class=\"xpl-spotlight__image-container\">\n      <img src=\"/assets/spotlight-preview.png\" alt=\"Feature preview\" />\n    </div>\n    <div class=\"xpl-spotlight__content\">\n      <div class=\"xpl-spotlight__header\">\n        <span class=\"xpl-spotlight__title\" id=\"spotlight-title\">Tour Title</span>\n        <p class=\"xpl-spotlight__body\">Copy about the feature and/or functionality the dot is pointing to.</p>\n      </div>\n      <div class=\"xpl-spotlight__actions xpl-spotlight__actions--dual xpl-spotlight__actions--with-steps\">\n        <div class=\"xpl-spotlight__action-slot xpl-spotlight__action-slot--secondary\">\n          <xpl-button variant=\"secondary\">Back</xpl-button>\n        </div>\n        <span class=\"xpl-spotlight__step-text\">2 of 5</span>\n        <div class=\"xpl-spotlight__action-slot xpl-spotlight__action-slot--primary\">\n          <xpl-button variant=\"primary\">Next</xpl-button>\n        </div>\n      </div>\n    </div>\n  </div>\n</div>\n```\n\n## Accessibility\n\n`xpl-spotlight` renders with `role=\"dialog\"` and `aria-modal=\"false\"` so assistive technologies treat it as a **non-modal** tour callout: focus is not trapped inside the card, and users can tab to the rest of the page while the step is open. The accessible name comes from the title region:\n\n- When the default title is used, the generated heading element receives the internal `aria-labelledby` id.\n- When a custom `title` slot is provided, the component assigns that same id to the first slotted title element if it does not already have one. If the slotted element already has an `id`, that value is kept and `aria-labelledby` references it (the host does not point at a missing id).\n- When neither a `heading` prop nor a `title` slot is provided, the dialog falls back to `aria-label=\"Tour step\"` so that assistive technologies always have an accessible name.\n\n### Keyboard navigation\n\n| Key | Behavior |\n|-----|----------|\n| `Tab` / `Shift+Tab` | Moves focus between interactive controls (dismiss button, secondary action, primary action). Focus is **not** trapped — users can tab out of the spotlight to the rest of the page. |\n| `Escape` | Emits `dismiss` when `isDismissible` is true and focus is inside the spotlight. Does nothing when focus is outside the component or the spotlight is closed. |\n| `Enter` / `Space` | Activates the focused button (dismiss, primary, or secondary action) via standard `xpl-button` behavior. |\n\n### Focus management\n\n- **On open:** focus moves automatically to the dismiss button (if `isDismissible` is true) or the first action button. When neither a dismiss button nor action buttons are rendered, the host element itself receives focus via `tabindex=\"-1\"`.\n- **On close:** focus returns to the element that was focused before the spotlight opened, provided that element is still in the DOM.\n- The decorative anchor dot (`.xpl-spotlight__target`) is marked `aria-hidden=\"true\"` so it is not announced or focusable.\n\n\n## Design Tokens\n\nThe component relies on Foundation purpose tokens in `spotlight.css` so light/dark mode works without component-level `.dark` overrides.\n\n| Property | Token |\n|----------|-------|\n| Card width | `var(--xpl-spotlight-width)` on the host (defined in `spotlight.css`; design-specific width until shared layout tokens exist — see `TECH_DEBT.md`) |\n| Image region min-height | `var(--xpl-spotlight-image-min-height)` on `.xpl-spotlight__image-container` (same note as card width) |\n| Card background | `var(--xpl-background-surface-default)` |\n| Host stacking | `var(--xpl-z-index-800)` |\n| Placeholder pattern | `var(--xpl-background-surface-subtle)` |\n| Heading text | `var(--xpl-text-default)` |\n| Body text | `var(--xpl-text-default)` |\n| Step text | `var(--xpl-text-subdued)` |\n| Open/closed visibility | `opacity` transition on `.xpl-spotlight--visible` |\n| Anchor outer ring | `var(--xpl-background-surface-information-bold)` |\n| Anchor inner dot | `var(--xpl-background-accent-default)` |\n| Image placeholder icon/text | `var(--xpl-icon-subtle)` |\n| Focus outline | `var(--xpl-border-focus)` |\n| Anchored host (when `target` is set) | `position: fixed` via `.xpl-spotlight--anchored`; `left` / `top` set from Floating UI (`strategy: 'fixed'`) |\n\n## Icon Mapping\n\n`xpl-spotlight` uses Apollo icons for fixed controls and fallback media placeholders:\n\n| UI area | `xpl-icon` name |\n|---------|------------------|\n| Dismiss button | `xmark` |\n| Empty image placeholder, image affordance | `photo` |\n| Empty image placeholder, video affordance | `video` |\n\n## Deprecated props\n\nNone.\n\n## Notes\n\n- `showImage=\"false\"` hides the media region even if `slot=\"image\"` content is present.\n- When `showImage` is left enabled and no `slot=\"image\"` content is provided, the component renders the built-in placeholder instead of collapsing the media region.\n- `showActions=\"false\"` removes the default actions row entirely.\n- `is-open=\"false\"` keeps the host element mounted but renders no spotlight UI until it is opened again.\n- `action-layout` defaults to `\"default\"`. `action-layout=\"default\"` renders the Back/Next pair with **disabled** edge buttons at step boundaries (Back disabled on step 1, Next disabled on the last step). `action-layout=\"dual\"` renders the Back/Next pair with **hidden** edge buttons at step boundaries. `action-layout=\"single\"` renders a single primary action.\n- `primary-action-label` and `secondary-action-label` control the default button text without needing action slots.\n- `target` enables Floating UI positioning with `offset`, `flip`, `shift`, and `autoUpdate` so the spotlight follows the referenced element on resize and scroll. Default offset and shift padding match Foundation spacing (`--xpl-space-12` / `--xpl-space-8`).\n- If `target` is missing or contains an invalid CSS selector, the component safely falls back to the requested `anchor-position` instead of throwing.\n- **Storybook:** open **Components → Spotlight** to adjust props via controls. Set `target` to `#spotlight-story-anchor` to preview Floating UI anchoring against the demo button on the canvas. The **Design** addon links to the Apollo Web Figma file (replace the `node-id` in Storybook with the Spotlight frame when Design publishes a dedicated link).\n",
+      "readme": "# xpl-spotlight\n\n`xpl-spotlight` renders a guided-tour callout with an anchor dot, optional media, step messaging, and prop-driven footer actions. It can either render inline using the requested `anchorPosition` or attach to a target element with Floating UI when `target` is provided.\n\n## Usage Examples\n\nUse the built-in title/body props and default actions for a simple tour step:\n\n```html\n<xpl-spotlight\n  heading=\"Review recent activity\"\n  body=\"Check status updates here before moving to the next step.\"\n  action-layout=\"default\"\n  anchor-position=\"top-right\"\n  current-step=\"2\"\n  total-steps=\"5\"\n  is-dismissible=\"true\"\n  is-open=\"true\"\n  primary-action-label=\"Next\"\n  secondary-action-label=\"Back\"\n  show-actions=\"true\"\n  show-image=\"true\"\n  show-steps=\"true\"\n  target=\"\"\n></xpl-spotlight>\n```\n\nAnchor the spotlight to a specific element and provide custom media content:\n\n```html\n<button id=\"dashboard-filter-button\" type=\"button\">Filters</button>\n\n<xpl-spotlight\n  target=\"#dashboard-filter-button\"\n  heading=\"Narrow the results\"\n  body=\"Use filters to focus on the accounts or activity that matter most.\"\n  current-step=\"1\"\n  total-steps=\"3\"\n  primary-action-label=\"Next\"\n  secondary-action-label=\"Skip\"\n>\n  <div slot=\"image\">\n    <img src=\"/assets/spotlight-filter-preview.png\" alt=\"Preview of filter controls\" />\n  </div>\n</xpl-spotlight>\n```\n\n\nControl visibility from the parent with `is-open` and close it by responding to `dismiss`:\n\n```html\n<xpl-spotlight\n  id=\"guided-tour-step\"\n  is-open=\"true\"\n  heading=\"Review recent activity\"\n  body=\"Check status updates here before moving to the next step.\"\n></xpl-spotlight>\n\n<script>\n  const spotlight = document.getElementById('guided-tour-step');\n\n  spotlight?.addEventListener('dismiss', () => {\n    spotlight.setAttribute('is-open', 'false');\n  });\n</script>\n```\n\nMirror the same layout in plain HTML when documenting or prototyping the component structure outside the custom element:\n\n```html\n<div class=\"xpl-spotlight xpl-spotlight--top-left xpl-spotlight--visible\"\n     role=\"dialog\" aria-modal=\"false\" aria-labelledby=\"spotlight-title\" tabindex=\"-1\">\n  <button type=\"button\" class=\"xpl-spotlight__target\" aria-label=\"Spotlight indicator\">\n    <div class=\"xpl-spotlight__target-outer\"></div>\n    <div class=\"xpl-spotlight__target-inner\"></div>\n  </button>\n  <div class=\"xpl-spotlight__dismiss\">\n    <xpl-button variant=\"secondary\" size=\"sm\" icon-only aria-label=\"Dismiss tour step\">\n      <xpl-icon icon=\"xmark\" size=\"16\"></xpl-icon>\n    </xpl-button>\n  </div>\n  <div class=\"xpl-spotlight__frame\">\n    <div class=\"xpl-spotlight__image-container\">\n      <img src=\"/assets/spotlight-preview.png\" alt=\"Feature preview\" />\n    </div>\n    <div class=\"xpl-spotlight__content\">\n      <div class=\"xpl-spotlight__header\">\n        <span class=\"xpl-spotlight__title\" id=\"spotlight-title\">Tour Title</span>\n        <p class=\"xpl-spotlight__body\">Copy about the feature and/or functionality the dot is pointing to.</p>\n      </div>\n      <div class=\"xpl-spotlight__actions xpl-spotlight__actions--dual xpl-spotlight__actions--with-steps\">\n        <div class=\"xpl-spotlight__action-slot xpl-spotlight__action-slot--secondary\">\n          <xpl-button variant=\"secondary\">Back</xpl-button>\n        </div>\n        <span class=\"xpl-spotlight__step-text\">2 of 5</span>\n        <div class=\"xpl-spotlight__action-slot xpl-spotlight__action-slot--primary\">\n          <xpl-button variant=\"primary\">Next</xpl-button>\n        </div>\n      </div>\n    </div>\n  </div>\n</div>\n```\n\n## Accessibility\n\n`xpl-spotlight` renders with `role=\"dialog\"` and `aria-modal=\"false\"` so assistive technologies treat it as a **non-modal** tour callout: focus is not trapped inside the card, and users can tab to the rest of the page while the step is open. The accessible name comes from the title region:\n\n- When the default title is used, the generated heading element receives the internal `aria-labelledby` id.\n- When a custom `title` slot is provided, the component assigns that same id to the first slotted title element if it does not already have one. If the slotted element already has an `id`, that value is kept and `aria-labelledby` references it (the host does not point at a missing id).\n- When neither a `heading` prop nor a `title` slot is provided, the dialog falls back to `aria-label=\"Tour step\"` so that assistive technologies always have an accessible name.\n\n### Keyboard navigation\n\n| Key | Behavior |\n|-----|----------|\n| `Tab` / `Shift+Tab` | Moves focus between interactive controls (dismiss button, secondary action, primary action). Focus is **not** trapped — users can tab out of the spotlight to the rest of the page. |\n| `Escape` | Emits `dismiss` when `isDismissible` is true and focus is inside the spotlight. Does nothing when focus is outside the component or the spotlight is closed. |\n| `Enter` / `Space` | Activates the focused button (dismiss, primary, or secondary action) via standard `xpl-button` behavior. |\n\n### Focus management\n\n- **On open:** focus moves automatically to the dismiss button (if `isDismissible` is true) or the first action button. When neither a dismiss button nor action buttons are rendered, the host element itself receives focus via `tabindex=\"-1\"`.\n- **On close:** focus returns to the element that was focused before the spotlight opened, provided that element is still in the DOM.\n- The decorative anchor dot (`.xpl-spotlight__target`) is marked `aria-hidden=\"true\"` so it is not announced or focusable.\n\n\n## Design Tokens\n\nThe component relies on Foundation purpose tokens in `spotlight.css` so light/dark mode works without component-level `.dark` overrides.\n\n| Property | Token |\n|----------|-------|\n| Card width | `var(--xpl-spotlight-width)` on the host (defined in `spotlight.css`; design-specific width until shared layout tokens exist — see `TECH_DEBT.md`) |\n| Image region min-height | `var(--xpl-spotlight-image-min-height)` on `.xpl-spotlight__image-container` (same note as card width) |\n| Card background | `var(--xpl-background-surface-default)` |\n| Card shadow | `var(--xpl-elevation-3)` (theme-aware elevation token) |\n| Host stacking | `var(--xpl-z-index-800)` |\n| Placeholder pattern | `var(--xpl-background-surface-subtle)` |\n| Heading text | `var(--xpl-text-default)` |\n| Body text | `var(--xpl-text-default)` |\n| Step text | `var(--xpl-text-subdued)` |\n| Open/closed visibility | `opacity` transition on `.xpl-spotlight--visible` |\n| Anchor outer ring | `var(--xpl-background-surface-information-bold)` |\n| Anchor inner dot | `var(--xpl-background-accent-default)` |\n| Image placeholder icon/text | `var(--xpl-icon-subtle)` |\n| Focus outline | `var(--xpl-border-focus)` |\n| Anchored host (when `target` is set) | `position: fixed` via `.xpl-spotlight--anchored`; `left` / `top` set from Floating UI (`strategy: 'fixed'`) |\n\n## Icon Mapping\n\n`xpl-spotlight` uses Apollo icons for fixed controls and fallback media placeholders:\n\n| UI area | `xpl-icon` name |\n|---------|------------------|\n| Dismiss button | `xmark` |\n| Empty image placeholder, image affordance | `photo` |\n| Empty image placeholder, video affordance | `video` |\n\n## Deprecated props\n\nNone.\n\n## Notes\n\n- `showImage=\"false\"` hides the media region even if `slot=\"image\"` content is present.\n- When `showImage` is left enabled and no `slot=\"image\"` content is provided, the component renders the built-in placeholder instead of collapsing the media region.\n- `showActions=\"false\"` removes the default actions row entirely.\n- `is-open=\"false\"` keeps the host element mounted but renders no spotlight UI until it is opened again.\n- `action-layout` defaults to `\"default\"`. `action-layout=\"default\"` renders the Back/Next pair with **disabled** edge buttons at step boundaries (Back disabled on step 1, Next disabled on the last step). `action-layout=\"dual\"` renders the Back/Next pair with **hidden** edge buttons at step boundaries. `action-layout=\"single\"` renders a single primary action.\n- `primary-action-label` and `secondary-action-label` control the default button text without needing action slots.\n- `target` enables Floating UI positioning with `offset`, `flip`, `shift`, and `autoUpdate` so the spotlight follows the referenced element on resize and scroll. Default offset and shift padding match Foundation spacing (`--xpl-space-12` / `--xpl-space-8`).\n- If `target` is missing or contains an invalid CSS selector, the component safely falls back to the requested `anchor-position` instead of throwing.\n- **Storybook:** open **Components → Spotlight** to adjust props via controls. Set `target` to `#spotlight-story-anchor` to preview Floating UI anchoring against the demo button on the canvas. The **Design** addon links to the Apollo Web Figma file (replace the `node-id` in Storybook with the Spotlight frame when Design publishes a dedicated link).\n",
       "docs": "`xpl-spotlight` renders a guided-tour callout with an anchor dot, optional media, step messaging, and prop-driven footer actions. It can either render inline using the requested `anchorPosition` or attach to a target element with Floating UI when `target` is provided.",
       "docsTags": [
         {
@@ -13888,9 +13884,21 @@
       "filePath": "src/components/components/xpl-table/xpl-table.tsx",
       "encapsulation": "none",
       "tag": "xpl-table",
-      "readme": "# xpl-table\n\nTables are used to organize and display information from a data set. \n",
-      "docs": "Tables are used to organize and display information from a data set.",
+      "readme": "# xpl-table\r\n\r\nTables are used to organize and display information from a data set.\r\n\r\n## Rendering modes\r\n\r\n1. **Compositional (recommended)** — Provide `xpl-table-header`, `xpl-table-body`, and optional `xpl-table-footer` with `xpl-table-row` / `xpl-table-header-cell` / `xpl-table-cell` / `xpl-table-footer-cell`. The host uses CSS grid (`role=\"grid\"`). Column widths come from each **`xpl-table-header-cell`** (`width` in px, or `column-width` for any grid track; default `auto` / content-sized). Use `label` for an accessible name. **Sorting:** set `sortable` (and optional `sort-key`) on label header cells; `xpl-table` emits **`sortChanged`** with sort-key slugs → `asc` / `desc` / `null`. The host does **not** reorder row DOM — listen and update your data (or reorder nodes yourself), same as the main Table Storybook demo.\r\n2. **Legacy data-driven** — Set `columns`, `data`, and optionally `footer` for a built-in `<table>` implementation. That path supports `isSortable` / `sortableColumns`, `multiselect`, and emits `sortChanged` / `tableSelect` (legacy can reorder rows unless you `preventDefault`). Prefer compositional markup for new work.\r\n\r\nComposable **selection** (`selectable`), **toolbar**, and copy-paste examples live under **[Usage](#usage)** below (read the breaking-change note first if you are migrating from auto-injected selection cells).\r\n\r\n### Row reorder (`row-reorderable`, managed grip column)\r\n\r\nWhen `row-reorderable` is set, Apollo can **inject** a leading reorder column with a native **button** + optional `xpl-icon` on each body row (unless you author that column yourself). Keyboard and pointer reorder share the same grip; **keyboard mode** is indicated by `aria-pressed`, updated labels, the class `xpl-table__row-drag-handle--keyboard-mode`, and optionally a **different icon**.\r\n\r\n**Pointer drag (full row):** Body rows use CSS **`subgrid`** so `xpl-table-row` is a real grid box (like `xpl-list-item`’s row surface). When `CSS.supports('grid-template-columns','subgrid')` is true, **`draggable`** is set on **`xpl-table-row`** so the browser’s drag image matches the whole row; drag still **starts only from the grip** (pointer-down there sets the drag token—dragging from other cells is ignored). Engines without subgrid keep **`draggable`** on the grip button only.\r\n\r\n| Attribute | When it applies | Purpose |\r\n| --------- | ---------------- | ------- |\r\n| `reorder-handle-icon` | Default / drag affordance | Icon name for `xpl-icon` (default `grip-dots-vertical`). Use `reorder-handle-icon=\"\"` to omit the injected icon and use CSS or your own markup in a **custom** reorder cell instead. |\r\n| `reorder-handle-icon-keyboard` | While that row is in **keyboard reorder mode** (Enter or Space on the grip) | Icon name for the same grip when the user is using **Arrow Up/Down** to move the row (default `caret-expand-y`, matching `xpl-list`). Use `reorder-handle-icon-keyboard=\"\"` to show **no** icon in keyboard mode only. |\r\n\r\n**Recommended for product UIs:** Set **both** attributes to your design-system icon names so drag vs keyboard modes are visually distinct. You can still add styles targeting `.xpl-table__row-drag-handle--keyboard-mode` (e.g. outline) for extra clarity.\r\n\r\n**Interaction:** Focus the grip → **Enter** or **Space** → **Arrow Up/Down** to reorder → **Escape** to exit. Pointer down on the row exits keyboard mode; starting a drag also exits keyboard mode.\r\n\r\n**Custom reorder column:** If you add reorder cells in your own template (not injected), **you** own icons, keyboard behavior, and `rowOrderChange` — these attributes apply only to **managed** injected grips.\r\n\r\n## Usage\r\n\r\n### Breaking change — compositional `selectable`\r\n\r\n**Before:** Setting `selectable` alone caused the table to **inject** selection header/body/footer cells into the light DOM (including nodes marked `data-xpl-selection-managed`).\r\n\r\n**After:** You **must** add the selection column in your own markup (see **Selection** below). `xpl-table` no longer creates or removes those cells; it only syncs selection state and emits events. If you previously relied on automatic injection, add the header checkbox column, per-row checkbox cells, and (when using a footer) leading footer cells so column counts match.\r\n\r\n### Selection (`selectable`) and `rowSelectionChange`\r\n\r\nSet `selectable` on `xpl-table` and **author the selection column in your template** so the framework that renders the table owns every cell node.\r\n\r\n**Required pieces:**\r\n\r\n- **Header:** one [`xpl-table-header-cell`](xpl-table-header-cell) with `type=\"checkbox\"` (tri-state “select all”).\r\n- **Body:** in each `xpl-table-row`, a cell aligned with that column containing **`xpl-checkbox`** (value is driven from `row-id` on the row).\r\n- **Footer:** if you use `xpl-table-footer`, add a leading `xpl-table-footer-cell` per row for the selection column (often empty) so column counts stay aligned.\r\n\r\n**Behavior:** After `customElements.whenDefined('xpl-table')`, listen for **`rowSelectionChange`** on the **same** `<xpl-table>` element (`bubbles: false`, `composed: true`). The event payload is `{ selectedRowIds: string[] }`. The host maintains `selectedRowIds`, syncs `checked` / `indeterminate` on the header and row checkboxes, sets `selected` on rows, and shows the bulk toolbar while at least one row is selected. Row checkbox **`aria-label`** is derived from the first **non-selection** data cell in that row (e.g. `Select row, Jordan Lee`); the header uses “Select all rows” unless you set **`checkbox-aria-label`** on the checkbox header cell.\r\n\r\n**Example (web component):**\r\n\r\n```html\r\n<xpl-table id=\"roster\" selectable label=\"Team roster\">\r\n  <xpl-table-header>\r\n    <xpl-table-row>\r\n      <xpl-table-header-cell type=\"checkbox\"></xpl-table-header-cell>\r\n      <xpl-table-header-cell label=\"Name\" sortable sort-key=\"name\"></xpl-table-header-cell>\r\n    </xpl-table-row>\r\n  </xpl-table-header>\r\n  <xpl-table-body>\r\n    <xpl-table-row row-id=\"1\">\r\n      <xpl-table-cell><xpl-checkbox></xpl-checkbox></xpl-table-cell>\r\n      <xpl-table-cell>Ada</xpl-table-cell>\r\n    </xpl-table-row>\r\n  </xpl-table-body>\r\n</xpl-table>\r\n<script type=\"module\">\r\n  await customElements.whenDefined('xpl-table');\r\n  document.getElementById('roster')?.addEventListener('rowSelectionChange', (e) => {\r\n    console.log(e.detail.selectedRowIds);\r\n  });\r\n</script>\r\n```\r\n\r\n#### Framework notes (Vue / React / etc.)\r\n\r\nUse **`xpl-checkbox`** in the selection column so `xpl-table` can sync `checked`, `indeterminate`, and `value` from `row-id`. On **`xpl-table-header-cell`**, the selection header uses **`type=\"checkbox\"`**; the prop is **reflected** to the host attribute so Vue bindings like `:type=\"'checkbox'\"` still expose `type=\"checkbox\"` in the DOM for the table’s column detection and CSS.\r\n\r\n### Legacy (`columns` / `data`)\r\n\r\nSet `columns`, `data`, and optional `footer` as **properties** after `customElements.whenDefined('xpl-table')`, or use attributes where your bundler passes JSON strings.\r\n\r\n```html\r\n<xpl-table id=\"legacy\"></xpl-table>\r\n<script type=\"module\">\r\n  await customElements.whenDefined('xpl-table');\r\n  const t = document.getElementById('legacy');\r\n  t.columns = ['Name', 'Score'];\r\n  t.data = [\r\n    ['Ada', '100'],\r\n    ['Bob', '95'],\r\n  ];\r\n  t.multiselect = true;\r\n  t.addEventListener('tableSelect', (e) => console.log(e.detail));\r\n</script>\r\n```\r\n\r\n## Accessibility\r\n\r\n| Concern | Behavior |\r\n| ------- | -------- |\r\n| Table landmark | Compositional host uses **`role=\"grid\"`**; set **`label`** (maps to `aria-label`). |\r\n| Columns | Header cells use **`role=\"columnheader\"`** with `aria-colindex`; sortable label headers expose sort state via **`aria-sort`**. |\r\n| Selection | Checkbox column: header reflects **checked / mixed** via `aria-checked`; row checkboxes get **`aria-label`** from the first non-selection cell’s text (or override with `checkbox-aria-label` on the checkbox header cell). |\r\n| Sort | Sorting is a **`<button type=\"button\">`** inside the header cell; focus uses **`:focus-visible`** with focus tokens in `table-header-cell.css`. |\r\n| Row reorder | Managed grip is a **`<button>`** with `aria-label` / `aria-pressed` for keyboard reorder mode; live region announces reorder when enabled. |\r\n\r\nKeyboard: **Tab** through sort buttons, checkboxes, reorder grips, and cell actions. **Enter** / **Space** activate sort and the reorder grip per native button semantics.\r\n\r\n## Design Tokens\r\n\r\nCompositional grid layout tokens live in `table.css`; cell, row, header, and toolbar tokens are split across sibling CSS files.\r\n\r\n| Element | Property | Token | Light | Dark |\r\n| ------- | -------- | ----- | ----- | ---- |\r\n| Host (compositional) | border | `--xpl-border-small`, `--xpl-border-default` | neutral-200 | neutral-800 |\r\n| Host (compositional) | border-radius | `--xpl-border-radius-default` | 8px | 8px |\r\n| Host (compositional) | grid columns | `--column-widths` (runtime from header cells) | — | — |\r\n| Selection toolbar | sticky z-index | `--xpl-z-index-200` | 200 | 200 |\r\n| Selection toolbar | min-height | `--xpl-size-350` | 56px | 56px |\r\n| Freeze shadow | gradient | `--xpl-background-surface-transparent-10` → `-0` | near-black 10% | near-white 10% |\r\n| Freeze column | sticky z-index | `--xpl-z-index-100` | 100 | 100 |\r\n| Freeze scroll hint | width | `--xpl-space-24` | 24px | 24px |\r\n| Striped even rows | cell background | `--xpl-background-surface-subtlest` | neutral-50 | neutral-950 |\r\n| Striped + selected | cell background | `--xpl-background-surface-information-bold` | blue-100 | blue-900 |\r\n\r\n## Icon mapping\r\n\r\nWhen Apollo **injects** the reorder column, icons come from table props (override with `\"\"` to omit):\r\n\r\n| Context | Default `xpl-icon` `icon` value |\r\n| ------- | -------------------------------- |\r\n| Pointer / idle grip | `grip-dots-vertical` |\r\n| Keyboard reorder mode | `caret-expand-y` |\r\n\r\nSort direction uses **`xpl-icon`** names from header-cell internals (`graph`, carets, etc.) — see Storybook **Components → Table**.\r\n\r",
+      "docs": "Compositional tables use CSS grid on the host (`role=\"grid\"`). Legacy mode uses a `<table>`.",
       "docsTags": [
+        {
+          "name": "slot",
+          "text": "- `xpl-table-header`, `xpl-table-body`, and optional `xpl-table-footer`."
+        },
+        {
+          "name": "slot",
+          "text": "toolbar-actions-left - Bulk actions in the selection toolbar (left group). Only when `selectable` is set; the toolbar is shown only while at least one row is selected."
+        },
+        {
+          "name": "slot",
+          "text": "toolbar-actions-right - Bulk actions in the selection toolbar (right group). Same visibility as `toolbar-actions-left`."
+        },
         {
           "name": "since",
           "text": "0.1.1"
@@ -13908,8 +13916,14 @@
           },
           "mutable": false,
           "reflectToAttr": false,
-          "docs": "The header values for each column.",
-          "docsTags": [],
+          "docs": "",
+          "docsTags": [
+            {
+              "name": "deprecated",
+              "text": "Legacy data-driven table API only (`columns` / `data` / `footer`). May be removed in a future major release.\n\nThe header values for each column."
+            }
+          ],
+          "deprecation": "Legacy data-driven table API only (`columns` / `data` / `footer`). May be removed in a future major release.\n\nThe header values for each column.",
           "values": [
             {
               "type": "string[]"
@@ -13930,8 +13944,14 @@
           },
           "mutable": false,
           "reflectToAttr": false,
-          "docs": "The data for the body of the table.",
-          "docsTags": [],
+          "docs": "",
+          "docsTags": [
+            {
+              "name": "deprecated",
+              "text": "Legacy data-driven table API only (`columns` / `data` / `footer`). May be removed in a future major release.\n\nThe data for the body of the table."
+            }
+          ],
+          "deprecation": "Legacy data-driven table API only (`columns` / `data` / `footer`). May be removed in a future major release.\n\nThe data for the body of the table.",
           "values": [
             {
               "type": "string[][]"
@@ -13952,8 +13972,14 @@
           },
           "mutable": false,
           "reflectToAttr": false,
-          "docs": "The data for the footer of the table.",
-          "docsTags": [],
+          "docs": "",
+          "docsTags": [
+            {
+              "name": "deprecated",
+              "text": "Legacy data-driven table API only (`columns` / `data` / `footer`). May be removed in a future major release.\n\nThe data for the footer of the table."
+            }
+          ],
+          "deprecation": "Legacy data-driven table API only (`columns` / `data` / `footer`). May be removed in a future major release.\n\nThe data for the footer of the table.",
           "values": [
             {
               "type": "string[][]"
@@ -13975,7 +14001,7 @@
           "mutable": false,
           "attr": "freeze",
           "reflectToAttr": false,
-          "docs": "When true, the first column of the table is sticky and will cover the leftmost rows in a horizontally scrollable container.",
+          "docs": "When true, the first **data** column (per row) is sticky during horizontal scroll.\nLeading compositional columns are skipped: `selectable` (checkbox) and/or `row-reorderable`\n(grip) are not frozen so they scroll with the grid; the next column stays pinned at `left: 0`.",
           "docsTags": [],
           "values": [
             {
@@ -13998,20 +14024,48 @@
           "mutable": false,
           "attr": "is-sortable",
           "reflectToAttr": false,
-          "docs": "Toggles to show the sort button on each table head",
+          "docs": "",
           "docsTags": [
+            {
+              "name": "deprecated",
+              "text": "Legacy data-driven table API only. May be removed in a future major release.\n\nToggles to show the sort button on each table head."
+            },
             {
               "name": "default",
               "text": "false"
             }
           ],
           "default": "false",
+          "deprecation": "Legacy data-driven table API only. May be removed in a future major release.\n\nToggles to show the sort button on each table head.",
           "values": [
             {
               "type": "boolean"
             }
           ],
-          "optional": false,
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "complexType": {
+            "original": "string",
+            "resolved": "string",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "label",
+          "reflectToAttr": false,
+          "docs": "Accessible label for the table. Maps to `aria-label` in compositional mode.",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "string"
+            }
+          ],
+          "optional": true,
           "required": false,
           "getter": false,
           "setter": false
@@ -14027,7 +14081,111 @@
           "mutable": false,
           "attr": "multiselect",
           "reflectToAttr": false,
-          "docs": "Toggles a selectable checkbox for each row in the table",
+          "docs": "",
+          "docsTags": [
+            {
+              "name": "deprecated",
+              "text": "Legacy data-driven table API only. May be removed in a future major release.\n\nToggles a selectable checkbox for each row in the table."
+            }
+          ],
+          "deprecation": "Legacy data-driven table API only. May be removed in a future major release.\n\nToggles a selectable checkbox for each row in the table.",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "reorderHandleIcon",
+          "type": "string",
+          "complexType": {
+            "original": "string",
+            "resolved": "string",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "reorder-handle-icon",
+          "reflectToAttr": false,
+          "docs": "Icon name for the optional `xpl-icon` inside each **managed** reorder grip when the row is **not** in\nkeyboard reorder mode (pointer / idle). Set to `\"\"` to omit the icon so you can style the button or author a\nfully custom reorder column in markup. When omitted, defaults to `grip-dots-vertical`.",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "string"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "reorderHandleIconKeyboard",
+          "type": "string",
+          "complexType": {
+            "original": "string",
+            "resolved": "string",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "reorder-handle-icon-keyboard",
+          "reflectToAttr": false,
+          "docs": "Icon name for the managed reorder grip **while that row is in keyboard reorder mode** (after the user\nactivates the grip with Enter or Space). Use a different icon than `reorder-handle-icon` so users can see\nthey should use arrow keys. When omitted, defaults to `caret-expand-y` (same as `xpl-list` keyboard reorder).\nSet to `\"\"` to show no icon in keyboard mode only (combine with CSS on\n`.xpl-table__row-drag-handle--keyboard-mode` if needed).",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "string"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "rowReorderable",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "row-reorderable",
+          "reflectToAttr": false,
+          "docs": "When true (compositional mode only), **prepends** a managed reorder column as the **first** grid\ncolumn (empty header + grip button per body row) and enables HTML5 drag-and-drop row reordering\n(same interaction model as `xpl-list`). With `selectable`, DOM order is **reorder | selection |\ndata** unless you author a custom reorder column. The table updates the DOM and emits\n`rowOrderChange`; consumers should persist order if needed. Ignored in legacy `columns`/`data` mode.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "selectable",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "selectable",
+          "reflectToAttr": false,
+          "docs": "When true (compositional mode only), enables row selection state, the selection toolbar\n(“N Selected”), and `rowSelectionChange`. **You must add the selection column in your\nmarkup:** a header cell with `type=\"checkbox\"`, a body cell containing `xpl-checkbox` per row\n(aligned with that column), and matching `xpl-table-footer-cell` cells when you use a footer.\nEach body row should use `row-id` on `xpl-table-row` (or accept auto-generated ids) so\n`rowSelectionChange` can report `selectedRowIds`.\n\nThe toolbar uses the same layout as `xpl-toolbar` and is visible only while at least one row\nis selected. Use `toolbar-actions-left` / `toolbar-actions-right` slots on this host for bulk\nactions.",
           "docsTags": [],
           "values": [
             {
@@ -14049,20 +14207,25 @@
           },
           "mutable": false,
           "reflectToAttr": false,
-          "docs": "The values for the input for each row when multiselect is activated.",
+          "docs": "",
           "docsTags": [
+            {
+              "name": "deprecated",
+              "text": "Legacy data-driven table API only. May be removed in a future major release.\n\nThe values for the input for each row when multiselect is activated."
+            },
             {
               "name": "default",
               "text": "[]"
             }
           ],
           "default": "[]",
+          "deprecation": "Legacy data-driven table API only. May be removed in a future major release.\n\nThe values for the input for each row when multiselect is activated.",
           "values": [
             {
               "type": "string[]"
             }
           ],
-          "optional": false,
+          "optional": true,
           "required": false,
           "getter": false,
           "setter": false
@@ -14077,20 +14240,25 @@
           },
           "mutable": false,
           "reflectToAttr": false,
-          "docs": "Manually determined if the column is sortable",
+          "docs": "",
           "docsTags": [
+            {
+              "name": "deprecated",
+              "text": "Use the compositional slot-based API instead. Will be removed in a future major release.\n\nManually determined if the column is sortable."
+            },
             {
               "name": "default",
               "text": "[]"
             }
           ],
           "default": "[]",
+          "deprecation": "Use the compositional slot-based API instead. Will be removed in a future major release.\n\nManually determined if the column is sortable.",
           "values": [
             {
               "type": "boolean[]"
             }
           ],
-          "optional": false,
+          "optional": true,
           "required": false,
           "getter": false,
           "setter": false
@@ -14106,7 +14274,7 @@
           "mutable": false,
           "attr": "striped",
           "reflectToAttr": false,
-          "docs": "Toggles an optional styling of the background of each even row of the table body.",
+          "docs": "Toggles an optional styling of the background of each even row of the\ntable body.",
           "docsTags": [],
           "values": [
             {
@@ -14122,17 +14290,57 @@
       "methods": [],
       "events": [
         {
-          "event": "sortChanged",
-          "detail": "{ colNum: number; colName: string; sortTypeArr: (\"desc\" | \"asc\")[]; }",
+          "event": "rowOrderChange",
+          "detail": "XplTableRowOrderChangeDetail",
+          "bubbles": false,
+          "complexType": {
+            "original": "XplTableRowOrderChangeDetail",
+            "resolved": "XplTableRowOrderChangeDetail",
+            "references": {
+              "XplTableRowOrderChangeDetail": {
+                "location": "local",
+                "path": "/home/runner/work/apollo/apollo/packages/apollo-core/src/components/components/xpl-table/xpl-table.tsx",
+                "id": "src/components/components/xpl-table/xpl-table.tsx::XplTableRowOrderChangeDetail"
+              }
+            }
+          },
+          "cancelable": true,
+          "composed": true,
+          "docs": "Emitted after body rows are reordered via drag-and-drop (compositional `row-reorderable` mode).",
+          "docsTags": []
+        },
+        {
+          "event": "rowSelectionChange",
+          "detail": "{ selectedRowIds: string[]; }",
           "bubbles": false,
           "complexType": {
-            "original": "{\n        colNum: number;\n        colName: string;\n        sortTypeArr: ('asc' | 'desc' | null)[];\n    }",
-            "resolved": "{ colNum: number; colName: string; sortTypeArr: (\"desc\" | \"asc\")[]; }",
+            "original": "{ selectedRowIds: string[] }",
+            "resolved": "{ selectedRowIds: string[]; }",
             "references": {}
           },
           "cancelable": true,
           "composed": true,
-          "docs": "Emits an event whenever the sort changes.\nThe 'sortChanged' event passes an object with colNum (number), colName (string), sortTypeArr(('asc' | 'desc' | null)[]).\nThe default action can be overridden by calling event.preventDefault().",
+          "docs": "Emitted when row selection changes in compositional `selectable` mode (`bubbles: false`,\n`composed: true`).\nListen on this `xpl-table` instance only; the event does not bubble to parents—use\n`table.addEventListener('rowSelectionChange', …)` on the same element. When wiring from a\nscript in static HTML, wait for `customElements.whenDefined('xpl-table')` so the host is ready.\n(Named `rowSelectionChange` to avoid clashing with the native `selectionchange` event.)",
+          "docsTags": []
+        },
+        {
+          "event": "sortChanged",
+          "detail": "XplTableSortChangedDetail",
+          "bubbles": false,
+          "complexType": {
+            "original": "XplTableSortChangedDetail",
+            "resolved": "XplTableSortChangedDetail",
+            "references": {
+              "XplTableSortChangedDetail": {
+                "location": "local",
+                "path": "/home/runner/work/apollo/apollo/packages/apollo-core/src/components/components/xpl-table/xpl-table.tsx",
+                "id": "src/components/components/xpl-table/xpl-table.tsx::XplTableSortChangedDetail"
+              }
+            }
+          },
+          "cancelable": true,
+          "composed": true,
+          "docs": "Emitted when sort changes in **legacy** or **compositional** mode. `event.detail` is a plain\nobject: **sort-key slug → `'asc' | 'desc' | null`** (null = that column not sorted). Keys match\nlegacy column titles (slugified) or compositional `sort-key` / label slugs. Call\n`event.preventDefault()` in legacy mode to skip built-in row sorting; compositional tables do\nnot reorder rows automatically.",
           "docsTags": []
         },
         {
@@ -14146,24 +14354,106 @@
           },
           "cancelable": true,
           "composed": true,
-          "docs": "Callback function that is called when the checkbox for a row of a\n`multiselect` table is checked",
+          "docs": "Callback function that is called when the checkbox for a row of a\n`multiselect` table is checked.",
           "docsTags": []
         }
       ],
-      "listeners": [],
-      "styles": [],
-      "slots": [],
-      "parts": [],
-      "states": [],
-      "dependents": [],
-      "dependencies": [
-        "xpl-checkbox",
-        "xpl-icon"
+      "listeners": [
+        {
+          "event": "xplTableColumnWidthsChange",
+          "capture": false,
+          "passive": false
+        },
+        {
+          "event": "checkboxChange",
+          "capture": false,
+          "passive": false
+        },
+        {
+          "event": "headerCheckboxChange",
+          "capture": false,
+          "passive": false
+        },
+        {
+          "event": "pointerdown",
+          "capture": true,
+          "passive": true
+        },
+        {
+          "event": "pointerdown",
+          "capture": true,
+          "passive": true
+        },
+        {
+          "event": "dragstart",
+          "capture": true,
+          "passive": true
+        },
+        {
+          "event": "dragend",
+          "capture": true,
+          "passive": true
+        },
+        {
+          "event": "dragover",
+          "capture": true,
+          "passive": false
+        },
+        {
+          "event": "dragenter",
+          "capture": true,
+          "passive": false
+        },
+        {
+          "event": "dragleave",
+          "capture": true,
+          "passive": true
+        },
+        {
+          "event": "drop",
+          "capture": true,
+          "passive": false
+        },
+        {
+          "event": "headerSortChange",
+          "capture": false,
+          "passive": false
+        }
       ],
-      "dependencyGraph": {
-        "xpl-table": [
-          "xpl-checkbox",
-          "xpl-icon"
+      "styles": [],
+      "slots": [
+        {
+          "name": "",
+          "docs": "`xpl-table-header`, `xpl-table-body`, and optional `xpl-table-footer`."
+        },
+        {
+          "name": "toolbar-actions-left",
+          "docs": "Bulk actions in the selection toolbar (left group). Only when `selectable` is set; the toolbar is shown only while at least one row is selected."
+        },
+        {
+          "name": "toolbar-actions-right",
+          "docs": "Bulk actions in the selection toolbar (right group). Same visibility as `toolbar-actions-left`."
+        }
+      ],
+      "parts": [],
+      "states": [],
+      "dependents": [],
+      "dependencies": [
+        "xpl-table-header-cell",
+        "xpl-table-cell",
+        "xpl-icon",
+        "xpl-table-footer-cell"
+      ],
+      "dependencyGraph": {
+        "xpl-table": [
+          "xpl-table-header-cell",
+          "xpl-table-cell",
+          "xpl-icon",
+          "xpl-table-footer-cell"
+        ],
+        "xpl-table-header-cell": [
+          "xpl-icon",
+          "xpl-checkbox"
         ]
       }
     },
@@ -14171,7 +14461,7 @@
       "filePath": "src/components/components/xpl-table/xpl-table-body/xpl-table-body.tsx",
       "encapsulation": "none",
       "tag": "xpl-table-body",
-      "readme": "# xpl-table-body\n\nRow group for compositional table body content. Uses `display: contents` so slotted rows participate in the parent grid layout.\n\n### Design Tokens\n\n| Element | Property | Token | Value |\n| -- | -- | -- | -- |\n| Host | display | — | `contents` |\n",
+      "readme": "# xpl-table-body\n\nRow group for compositional table body content. Uses `display: contents` so slotted rows participate in the parent grid layout.\n\n## Design Tokens\n\n| Element | Property | Token | Light | Dark |\n| ------- | -------- | ----- | ----- | ---- |\n| Host | display | — | `contents` | `contents` |\n",
       "docs": "Row group for compositional table body content. Uses `display: contents` so slotted rows participate in the parent grid layout.",
       "docsTags": [],
       "usage": {},
@@ -14187,11 +14477,163 @@
       "dependencies": [],
       "dependencyGraph": {}
     },
+    {
+      "filePath": "src/components/components/xpl-table/xpl-table-cell/xpl-table-cell.tsx",
+      "encapsulation": "none",
+      "tag": "xpl-table-cell",
+      "readme": "# xpl-table-cell\n\nBody cell for compositional [`xpl-table`](../readme.md). Place content in the default slot; use `align`, `bold`, and `underline` for typography. Interactive controls inside the cell inherit `disabled` when the parent [`xpl-table-row`](../xpl-table-row) is disabled.\n\n## Design Tokens\n\nExtends `.xpl-table-cell-base` (`table-cell-base.css`); row states (selected, disabled, striped) are applied from `table-row.css`.\n\n| Element | Property | Token | Light | Dark |\n| ------- | -------- | ----- | ----- | ---- |\n| Cell | background | `--xpl-background-surface-default` | neutral-0 | neutral-1000 |\n| Cell | text | `--xpl-text-default` | neutral-900 | neutral-50 |\n| Cell | border (right/bottom) | `--xpl-border-small`, `--xpl-border-default` | 1px, neutral-200 | 1px, neutral-800 |\n| Cell | padding | `--xpl-space-10`, `--xpl-space-16` | 10px / 16px | 10px / 16px |\n| Cell | min-height | `--xpl-size-350` | 56px | 56px |\n| Cell | typography | `@extend .xpl-text-title-5` | title-5 / medium | title-5 / medium |\n| Bold text | font-weight | `--xpl-font-weight-semibold` | 600 | 600 |\n| Disabled | text | `--xpl-text-disabled` | neutral-400 | neutral-600 |\n| Caption slot | text | `--xpl-text-subdued` | neutral-600 | neutral-400 |\n| Icon | color | `--xpl-icon-default` | neutral-900 | neutral-50 |\n| Reorder grip | color | `--xpl-icon-subtle` | neutral-600 | neutral-400 |\n| Reorder grip focus | outline | `--xpl-border-focus` | purple-500 | purple-400 |\n| Checkbox-only column | padding | `--xpl-space-16` + `--xpl-space-4` | 20px / 16px | 20px / 16px |\n",
+      "docs": "Body cell for compositional [`xpl-table`](../readme.md). Place content in the default slot; use `align`, `bold`, and `underline` for typography. Interactive controls inside the cell inherit `disabled` when the parent [`xpl-table-row`](../xpl-table-row) is disabled.",
+      "docsTags": [],
+      "usage": {},
+      "props": [
+        {
+          "name": "align",
+          "type": "\"center\" | \"left\" | \"right\"",
+          "complexType": {
+            "original": "'left' | 'right' | 'center'",
+            "resolved": "\"center\" | \"left\" | \"right\"",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "align",
+          "reflectToAttr": false,
+          "docs": "Horizontal text alignment within the cell.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "'left'"
+            }
+          ],
+          "default": "'left'",
+          "values": [
+            {
+              "value": "center",
+              "type": "string"
+            },
+            {
+              "value": "left",
+              "type": "string"
+            },
+            {
+              "value": "right",
+              "type": "string"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "bold",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "bold",
+          "reflectToAttr": false,
+          "docs": "Renders cell text in bold (--xpl-font-weight-semibold).",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "disabled",
+          "reflectToAttr": false,
+          "docs": "Whether the cell and its interactive children are disabled. Set automatically by xpl-table-row.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "underline",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "underline",
+          "reflectToAttr": false,
+          "docs": "Adds an underline to cell text.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        }
+      ],
+      "methods": [],
+      "events": [],
+      "listeners": [],
+      "styles": [],
+      "slots": [],
+      "parts": [],
+      "states": [],
+      "dependents": [
+        "xpl-table"
+      ],
+      "dependencies": [],
+      "dependencyGraph": {
+        "xpl-table": [
+          "xpl-table-cell"
+        ]
+      }
+    },
     {
       "filePath": "src/components/components/xpl-table/xpl-table-footer/xpl-table-footer.tsx",
       "encapsulation": "none",
       "tag": "xpl-table-footer",
-      "readme": "# xpl-table-footer\n\nRow group for compositional table footer content. Uses `display: contents` so slotted footer rows participate in the parent grid layout.\n\n### Design Tokens\n\n| Element | Property | Token | Value |\n| -- | -- | -- | -- |\n| Host | display | — | `contents` |\n",
+      "readme": "# xpl-table-footer\n\nRow group for compositional table footer content. Uses `display: contents` so slotted footer rows participate in the parent grid layout.\n\n## Design Tokens\n\n| Element | Property | Token | Light | Dark |\n| ------- | -------- | ----- | ----- | ---- |\n| Host | display | — | `contents` | `contents` |\n",
       "docs": "Row group for compositional table footer content. Uses `display: contents` so slotted footer rows participate in the parent grid layout.",
       "docsTags": [],
       "usage": {},
@@ -14211,8 +14653,8 @@
       "filePath": "src/components/components/xpl-table/xpl-table-footer-cell/xpl-table-footer-cell.tsx",
       "encapsulation": "none",
       "tag": "xpl-table-footer-cell",
-      "readme": "# xpl-table-footer-cell\n\nFooter cell for compositional tables. Extends the shared `.xpl-table-cell-base` styles with a strong top border.\n\n### Design Tokens\n\n| Element | Property | Token | Value |\n| -- | -- | -- | -- |\n| Cell | extends | `.xpl-table-cell-base` | (shared compositional cell base) |\n| Cell | background | `--xpl-background-surface-default` | neutral-0 (lm) / neutral-900 (dm) |\n| Cell | text | `--xpl-text-default` | neutral-900 (lm) / neutral-50 (dm) |\n| Cell | border (right/bottom) | `--xpl-border-small`, `--xpl-border-default` | 1px, neutral-200 |\n| Footer row border | border-top | `--xpl-border-large`, `--xpl-border-strong` | 2px, neutral-300 |\n| Cell | height | `--xpl-size-350` | 56px |\n| Cell | min-width | `--xpl-size-300` | 48px |\n| Cell | padding | `--xpl-space-16` | 16px |\n| Cell | typography | `@extend .xpl-text-title-5` | title-5 / medium |\n",
-      "docs": "Footer cell for compositional tables. Extends the shared `.xpl-table-cell-base` styles with a strong top border.",
+      "readme": "# xpl-table-footer-cell\n\nFooter cell for compositional tables. Extends the shared `.xpl-table-cell-base` styles with footer-row border rules from `table.css`.\n\n## Design Tokens\n\n| Element | Property | Token | Light | Dark |\n| ------- | -------- | ----- | ----- | ---- |\n| Cell | extends | `.xpl-table-cell-base` | (shared compositional cell base) | (shared compositional cell base) |\n| Cell | background | `--xpl-background-surface-default` | neutral-0 | neutral-1000 |\n| Cell | text | `--xpl-text-default` | neutral-900 | neutral-50 |\n| Cell | border (right/bottom) | `--xpl-border-small`, `--xpl-border-default` | 1px, neutral-200 | 1px, neutral-800 |\n| Last footer row | border-bottom | none (host draws frame) | — | — |\n",
+      "docs": "Footer cell for compositional tables. Extends the shared `.xpl-table-cell-base` styles with footer-row border rules from `table.css`.",
       "docsTags": [],
       "usage": {},
       "props": [
@@ -14262,9 +14704,15 @@
       "slots": [],
       "parts": [],
       "states": [],
-      "dependents": [],
+      "dependents": [
+        "xpl-table"
+      ],
       "dependencies": [],
-      "dependencyGraph": {}
+      "dependencyGraph": {
+        "xpl-table": [
+          "xpl-table-footer-cell"
+        ]
+      }
     },
     {
       "filePath": "src/components/components/xpl-table-header/xpl-table-header.tsx",
@@ -14292,19 +14740,127 @@
       "dependencyGraph": {}
     },
     {
-      "filePath": "src/components/components/xpl-table-header-cell/xpl-table-header-cell.tsx",
+      "filePath": "src/components/components/xpl-table/xpl-table-header-cell/xpl-table-header-cell.tsx",
       "encapsulation": "none",
       "tag": "xpl-table-header-cell",
-      "readme": "# xpl-table-header-cell\n\n> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\nThe `icon` property accepts icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.\n\n---\n",
-      "docs": "> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\nThe `icon` property accepts icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.\n\n---",
-      "docsTags": [
-        {
-          "name": "since",
-          "text": "1.3.0"
-        }
-      ],
+      "readme": "# xpl-table-header-cell\r\n\r\n> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\r\n\r\nThe `icon` property accepts icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.\r\n\r\nWhen this cell is used inside a compositional [`xpl-table`](../xpl-table) with `selectable`, **you** add a `type=\"checkbox\"` header cell for select-all; `xpl-table` keeps `checked` and `indeterminate` in sync with row selection.\r\n\r\n**Frameworks (Vue / etc.):** `type` is **reflected** to the DOM. You may bind with `:type=\"'checkbox'\"` or `type=\"checkbox\"`; the host will still expose `type=\"checkbox\"` as an attribute so the table’s selection column logic and styles stay correct.\r\n\r\nFor **sortable** columns (`type=\"label\"`), set **`sortable`** and optionally **`sort-key`**; the parent table emits **`sortChanged`** (see [`xpl-table` events](../xpl-table#events)).\r\n\r\n**Column width (compositional grid):** Each header cell defines one grid column on the parent `xpl-table`. By default the track is **`auto`** (sizes from content). Set **`width`** for a fixed pixel width (minimum 48px), or **`column-width`** for any CSS grid track string (`1fr`, `minmax(120px, 1fr)`, etc.). When both are set, **`column-width` wins**.\r\n\r\n## Design Tokens\r\n\r\n| Element | Property | Token | Light | Dark |\r\n| ------- | -------- | ----- | ----- | ---- |\r\n| Cell | background | `--xpl-background-surface-subtlest` | neutral-50 | neutral-950 |\r\n| Cell | text | `--xpl-text-subdued` | neutral-600 | neutral-400 |\r\n| Cell | border (right/bottom) | `--xpl-border-small`, `--xpl-border-default` | 1px, neutral-200 | 1px, neutral-800 |\r\n| Cell | min-width | `--xpl-size-300` | 48px | 48px |\r\n| Cell | min-height | `--xpl-size-350` | 56px | 56px |\r\n| Cell | typography | `@extend .xpl-text-title-5` | title-5 / medium | title-5 / medium |\r\n| Sort button | padding | `--xpl-space-12`, `--xpl-space-16` | 12px / 16px | 12px / 16px |\r\n| Sort button focus | outline | `--xpl-border-focus` | purple-500 | purple-400 |\r\n| Sort icon (default) | color | `--xpl-text-subdued` | neutral-600 | neutral-400 |\r\n| Sort icon (active) | color | `--xpl-icon-information` | blue-500 | blue-400 |\r\n| Checkbox column | padding | `--xpl-space-16` + `--xpl-space-4` | 20px / 16px | 20px / 16px |\r\n\r\n---\r\n\r",
+      "docs": "> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\r\n\r\nThe `icon` property accepts icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.\r\n\r\nWhen this cell is used inside a compositional [`xpl-table`](../xpl-table) with `selectable`, **you** add a `type=\"checkbox\"` header cell for select-all; `xpl-table` keeps `checked` and `indeterminate` in sync with row selection.\r\n\r\n**Frameworks (Vue / etc.):** `type` is **reflected** to the DOM. You may bind with `:type=\"'checkbox'\"` or `type=\"checkbox\"`; the host will still expose `type=\"checkbox\"` as an attribute so the table’s selection column logic and styles stay correct.\r\n\r\nFor **sortable** columns (`type=\"label\"`), set **`sortable`** and optionally **`sort-key`**; the parent table emits **`sortChanged`** (see [`xpl-table` events](../xpl-table#events)).\r\n\r\n**Column width (compositional grid):** Each header cell defines one grid column on the parent `xpl-table`. By default the track is **`auto`** (sizes from content). Set **`width`** for a fixed pixel width (minimum 48px), or **`column-width`** for any CSS grid track string (`1fr`, `minmax(120px, 1fr)`, etc.). When both are set, **`column-width` wins**.",
+      "docsTags": [],
       "usage": {},
       "props": [
+        {
+          "name": "align",
+          "type": "\"center\" | \"left\" | \"right\"",
+          "complexType": {
+            "original": "'left' | 'right' | 'center'",
+            "resolved": "\"center\" | \"left\" | \"right\"",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "align",
+          "reflectToAttr": false,
+          "docs": "Horizontal text alignment within the header cell.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "'left'"
+            }
+          ],
+          "default": "'left'",
+          "values": [
+            {
+              "value": "center",
+              "type": "string"
+            },
+            {
+              "value": "left",
+              "type": "string"
+            },
+            {
+              "value": "right",
+              "type": "string"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "checkboxAriaLabel",
+          "type": "string",
+          "complexType": {
+            "original": "string",
+            "resolved": "string",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "checkbox-aria-label",
+          "reflectToAttr": false,
+          "docs": "Accessible name for the header checkbox (native `aria-label`).\nDefaults to “Select all rows” when `type` is `checkbox`.",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "string"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "checked",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "checked",
+          "reflectToAttr": false,
+          "docs": "Whether the header checkbox is checked",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "columnWidth",
+          "type": "string",
+          "complexType": {
+            "original": "string",
+            "resolved": "string",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "column-width",
+          "reflectToAttr": true,
+          "docs": "CSS grid track size for this column (e.g. `1fr`, `minmax(120px, 1fr)`, `auto`). When set, overrides `width`.\nUse this when you need flexible columns; default layout uses `auto` per column unless you set a track here.",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "string"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "icon",
           "type": "string",
@@ -14328,6 +14884,35 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "indeterminate",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "indeterminate",
+          "reflectToAttr": false,
+          "docs": "Whether the checkbox is in indeterminate (partially selected) state",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "label",
           "type": "string",
@@ -14339,12 +14924,8 @@
           "mutable": false,
           "attr": "label",
           "reflectToAttr": false,
-          "docs": "",
+          "docs": "Text to display in the cell.",
           "docsTags": [
-            {
-              "name": "property",
-              "text": "{string} - Text to display in the cell"
-            },
             {
               "name": "default",
               "text": "''"
@@ -14361,6 +14942,57 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "sortDirection",
+          "type": "\"asc\" | \"desc\"",
+          "complexType": {
+            "original": "'asc' | 'desc' | null",
+            "resolved": "\"asc\" | \"desc\"",
+            "references": {}
+          },
+          "mutable": true,
+          "attr": "sort-direction",
+          "reflectToAttr": true,
+          "docs": "Active sort direction for this column when `sortable`. Set by `xpl-table` when used inside\na compositional table; may be set by the app for controlled updates.",
+          "docsTags": [],
+          "values": [
+            {
+              "value": "asc",
+              "type": "string"
+            },
+            {
+              "value": "desc",
+              "type": "string"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "sortKey",
+          "type": "string",
+          "complexType": {
+            "original": "string",
+            "resolved": "string",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "sort-key",
+          "reflectToAttr": false,
+          "docs": "When `sortable` is true, optional stable id used as the key in `sortChanged`’s detail object.\nFalls back to a slug of `label` when omitted.",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "string"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "sortable",
           "type": "boolean",
@@ -14372,12 +15004,8 @@
           "mutable": false,
           "attr": "sortable",
           "reflectToAttr": false,
-          "docs": "",
+          "docs": "When true (and `type` is `label`), renders a sort control (button + affordance icon).",
           "docsTags": [
-            {
-              "name": "property",
-              "text": "{boolean} - Whether the cell is sortable or not"
-            },
             {
               "name": "default",
               "text": "false"
@@ -14389,28 +15017,24 @@
               "type": "boolean"
             }
           ],
-          "optional": true,
+          "optional": false,
           "required": false,
           "getter": false,
           "setter": false
         },
         {
           "name": "type",
-          "type": "\"checkbox\" | \"icon\" | \"label\"",
+          "type": "\"checkbox\" | \"empty\" | \"icon\" | \"label\"",
           "complexType": {
-            "original": "'label' | 'checkbox' | 'icon'",
-            "resolved": "\"checkbox\" | \"icon\" | \"label\"",
+            "original": "'label' | 'checkbox' | 'icon' | 'empty'",
+            "resolved": "\"checkbox\" | \"empty\" | \"icon\" | \"label\"",
             "references": {}
           },
           "mutable": false,
           "attr": "type",
-          "reflectToAttr": false,
-          "docs": "",
+          "reflectToAttr": true,
+          "docs": "The type of cell to render. **Reflected** to the host `type` attribute so `xpl-table` (and CSS\n`[type=\"checkbox\"]`) can find the selection column after frameworks set the prop without syncing\nthe attribute (e.g. Vue `:type=\"'checkbox'\"`).",
           "docsTags": [
-            {
-              "name": "property",
-              "text": "{string} - The type of cell to render"
-            },
             {
               "name": "default",
               "text": "'label'"
@@ -14422,6 +15046,10 @@
               "value": "checkbox",
               "type": "string"
             },
+            {
+              "value": "empty",
+              "type": "string"
+            },
             {
               "value": "icon",
               "type": "string"
@@ -14446,14 +15074,9 @@
           },
           "mutable": false,
           "attr": "width",
-          "reflectToAttr": false,
-          "docs": "",
-          "docsTags": [
-            {
-              "name": "property",
-              "text": "{number} - Width of the cell, in pixels. Minimum width is 48px. If no value is provided, it will default\nto fit the content of the cell with 16px of padding on each side"
-            }
-          ],
+          "reflectToAttr": true,
+          "docs": "Fixed width for this column in pixels (minimum 48px). Sets the grid track to `Npx`.\nIgnored when `columnWidth` is set. When omitted, the column track defaults to `auto` (content-sized).",
+          "docsTags": [],
           "values": [
             {
               "type": "number"
@@ -14468,17 +15091,37 @@
       "methods": [],
       "events": [
         {
-          "event": "sortChanged",
-          "detail": "\"asc\" | \"desc\" | \"none\"",
+          "event": "headerCheckboxChange",
+          "detail": "boolean",
           "bubbles": true,
           "complexType": {
-            "original": "'asc' | 'desc' | 'none'",
-            "resolved": "\"asc\" | \"desc\" | \"none\"",
+            "original": "boolean",
+            "resolved": "boolean",
             "references": {}
           },
           "cancelable": true,
           "composed": true,
-          "docs": "Emitted when the sort direction changes.",
+          "docs": "Emitted when header checkbox changes",
+          "docsTags": []
+        },
+        {
+          "event": "headerSortChange",
+          "detail": "HeaderSortChangeDetail",
+          "bubbles": true,
+          "complexType": {
+            "original": "HeaderSortChangeDetail",
+            "resolved": "HeaderSortChangeDetail",
+            "references": {
+              "HeaderSortChangeDetail": {
+                "location": "local",
+                "path": "/home/runner/work/apollo/apollo/packages/apollo-core/src/components/components/xpl-table/xpl-table-header-cell/xpl-table-header-cell.tsx",
+                "id": "src/components/components/xpl-table/xpl-table-header-cell/xpl-table-header-cell.tsx::HeaderSortChangeDetail"
+              }
+            }
+          },
+          "cancelable": true,
+          "composed": true,
+          "docs": "Emitted when a sortable label header is activated. Parent `xpl-table` coordinates columns and emits `sortChanged`.",
           "docsTags": []
         }
       ],
@@ -14487,15 +15130,20 @@
       "slots": [],
       "parts": [],
       "states": [],
-      "dependents": [],
+      "dependents": [
+        "xpl-table"
+      ],
       "dependencies": [
-        "xpl-checkbox",
-        "xpl-icon"
+        "xpl-icon",
+        "xpl-checkbox"
       ],
       "dependencyGraph": {
         "xpl-table-header-cell": [
-          "xpl-checkbox",
-          "xpl-icon"
+          "xpl-icon",
+          "xpl-checkbox"
+        ],
+        "xpl-table": [
+          "xpl-table-header-cell"
         ]
       }
     },
@@ -14503,7 +15151,7 @@
       "filePath": "src/components/components/xpl-table/xpl-table-row/xpl-table-row.tsx",
       "encapsulation": "none",
       "tag": "xpl-table-row",
-      "readme": "# xpl-table-row\n\nData row for compositional tables. Uses `display: contents` by default so cells align to the parent grid; when the body supports subgrid, the row becomes a full-width subgrid for drag interactions.\n\n### Design Tokens\n\n| Element | Property | Token | Value |\n| -- | -- | -- | -- |\n| Host (default) | display | — | `contents` |\n| Host (subgrid body) | display | — | `grid` with `subgrid` |\n| Disabled row | background | `--xpl-background-surface-subtlest` | neutral-50 (lm) / neutral-950 (dm) |\n| Disabled row | text | `--xpl-text-disabled` | neutral-400 (lm) / neutral-600 (dm) |\n| Dragging row | background | `--xpl-background-surface-subtle` | neutral-100 (lm) / neutral-900 (dm) |\n| Dragging row | opacity | `--xpl-opacity-75` | 0.75 (custom, mirrors xpl-list) |\n| Selected row | background | `--xpl-background-surface-information` | blue-50 (lm) / blue-950 (dm) |\n| Drag-over outline | color | `--xpl-border-focus` | purple-500 |\n| Striped even | background | `--xpl-background-surface-subtlest` | neutral-50 (lm) / neutral-950 (dm) |\n| Striped selected | background | `--xpl-background-surface-information-bold` | blue-100 (lm) / blue-900 (dm) |\n",
+      "readme": "# xpl-table-row\n\nData row for compositional tables. Uses `display: contents` by default so cells align to the parent grid; when the body supports subgrid, the row becomes a full-width subgrid for drag interactions.\n\n## Design Tokens\n\nRow state styles target descendant `.xpl-table-cell` nodes (see `table-row.css`).\n\n| Element | Property | Token | Light | Dark |\n| ------- | -------- | ----- | ----- | ---- |\n| Host (default) | display | — | `contents` | `contents` |\n| Host (subgrid body) | display | — | `grid` with `subgrid` | `grid` with `subgrid` |\n| Disabled row | background | `--xpl-background-surface-subtlest` | neutral-50 | neutral-950 |\n| Disabled row | text | `--xpl-text-disabled` | neutral-400 | neutral-600 |\n| Dragging row | background | `--xpl-background-surface-subtle` | neutral-100 | neutral-900 |\n| Dragging row | opacity | `--xpl-opacity-75` | 0.75 | 0.75 |\n| Selected row | background | `--xpl-background-surface-information` | blue-50 | blue-950 |\n| Selected grip (reorder) | icon color | `--xpl-icon-information` | blue-500 | blue-400 |\n| Drag-over outline | inset ring | `--xpl-border-focus`, `--xpl-border-small` | purple-500 | purple-400 |\n| Striped even | background | `--xpl-background-surface-subtlest` | neutral-50 | neutral-950 |\n| Striped selected | background | `--xpl-background-surface-information-bold` | blue-100 | blue-900 |\n| Keyboard reorder grip | outline | `--xpl-border-focus` | purple-500 | purple-400 |\n",
       "docs": "Data row for compositional tables. Uses `display: contents` by default so cells align to the parent grid; when the body supports subgrid, the row becomes a full-width subgrid for drag interactions.",
       "docsTags": [],
       "usage": {},
@@ -15067,7 +15715,7 @@
       "filePath": "src/components/components/xpl-toast/xpl-toast.tsx",
       "encapsulation": "none",
       "tag": "xpl-toast",
-      "readme": "# xpl-toast\n\nToasts are brief, non-disruptive messages that provide quick, at-a-glance feedback. They can have 3 sentiments; neutral, positive and negative and contain actions such as a button or link, or a close button. Messaging can include a title and caption limited to 85 characters. Keep your toast messaging short and to the point and tone in line with the sentiment of the Toast. \n\nThe Toast component is configurable by Sentiment plus show/hide properties for Icon, Caption, Button and Dismissible. Use the nested component’s properties to customize further as needed. \n\nWhen possible, Toasts should auto-dismiss after 8 seconds. When an action is present, it may not be desirable to time out the Toast depending on your specific context.  \n\nMatch your messaging with the sentiment of the toast. Most messages will have a neutral sentiment. Reserve negative sentiments for when an explicit failure has occurred. Give users the information they need to correct the issue. \n\nToasts only support a single action and up to 85 characters. If multiple actions can be taken, or the message is longer than a few words, use a [Modal component](https://apollo.xplordocs.com/?path=/story/components-modal--modal) instead.\n\n## Usage\n\n```html\n<!-- Neutral toast with a caption, auto-dismissing after the default 8s -->\n<xpl-toast caption=\"Your changes have been saved.\">\n    <p slot=\"title\">Saved</p>\n</xpl-toast>\n\n<!-- With an action. Auto-dismiss is suppressed while the action slot has content -->\n<xpl-toast variant=\"warning\" caption=\"We couldn't reach the server.\">\n    <p slot=\"title\">Sync failed</p>\n    <xpl-button slot=\"action\" size=\"sm\">Retry</xpl-button>\n</xpl-toast>\n\n<!-- No close button; disable auto-dismiss with timeout=\"0\" -->\n<xpl-toast dismissible=\"false\" timeout=\"0\">\n    <p slot=\"title\">Uploading…</p>\n</xpl-toast>\n```\n\n## Deprecations\n\n### `dismissable` → `dismissible`\n\nThe **`dismissable`** prop is misspelled and is **deprecated**. Use **`dismissible`** instead.\n\n```html\n<!-- Before -->\n<xpl-toast dismissable=\"false\">…</xpl-toast>\n\n<!-- After -->\n<xpl-toast dismissible=\"false\">…</xpl-toast>\n```\n\nBoth props are supported during the deprecation window, so no consumer change is required immediately:\n\n| `dismissable` | `dismissible` | Close button shown | Notes |\n| ------------- | ------------- | ------------------ | ----- |\n| unset | unset | ✅ | Default (`dismissible` defaults to `true`) |\n| unset | `false` | ❌ | Recommended usage |\n| `false` | unset | ❌ | Existing markup keeps working |\n| `false` | `true` | ❌ | `dismissable` wins while it exists |\n\n`dismissable` has **no default** (`undefined` when unset) so the component can tell \"not set\" from \"set to `false`\". When it is used, the component logs a one-time deprecation warning to the console. `dismissable` will be removed in the next major version, at which point `dismissible` becomes the only option.\n\n## Positioning\n\nThe default position is arbitrarily set to `40px` from top and `40px` from right of the browser viewport on desktop and bottom-center on mobile. This position should be adjusted to ensure it's not covering your App's header. Apollo, by design, does not prescribe a position for toasts because this will be dependent on the app that it is being used in.\n\nPositioning of toasts should be global to your app. For example, if it is decided that your app will always position the toast in the top right corner, then this convention should be followed throughout. It should not be positioned top-right on one screen and bottom-center on another.\n\n*****Consult your designer for the best placement for your product.**\n\n### Overriding the default position\n\nThe toast uses `position: fixed` and can be repositioned by overriding the `.xpl-toast` CSS class in your app's stylesheet. Set `top`, `right`, `bottom`, and `left` as needed and use `unset` or `initial` to clear any defaults you don't want.\n\n**Top-left example:**\n```css\n.xpl-toast {\n  top: 24px;\n  right: unset;\n  left: 24px;\n}\n```\n\n**Bottom-right example:**\n```css\n.xpl-toast {\n  top: unset;\n  right: 24px;\n  bottom: 24px;\n}\n```\n\n**Centered at the top:**\n```css\n.xpl-toast {\n  top: 24px;\n  right: unset;\n  left: 50%;\n  transform: translateX(-50%);\n}\n```\n\nThe mobile breakpoint (≤ 768px) resets the toast to bottom-center. If your app needs a different mobile position, override the media query as well:\n\n```css\n@media screen and (max-width: 768px) {\n  .xpl-toast {\n    /* your mobile overrides */\n    bottom: 16px;\n    left: 50%;\n    transform: translateX(-50%);\n  }\n}\n```\n\n> **Tip:** Place these overrides in a global stylesheet so every toast in your app appears in the same location.\n\n## Token Use\n\n`xpl-toast` follows the same messaging-component token pattern as [`xpl-banner`](../xpl-banner) (background `--xpl-background-messaging-*` + accent/sentiment border). Light and dark mode are handled by the Foundation token definitions, so the component has no `.dark` overrides.\n\n| Variant / element | Property | Token |\n| ----------------- | -------- | ----- |\n| `neutral` (default) | background | `--xpl-background-messaging-information` |\n| `neutral` (default) | border | `--xpl-border-accent-information` |\n| `&--warning` | background | `--xpl-background-messaging-negative` |\n| `&--warning` | border | `--xpl-border-negative` |\n| `&--success` | background | `--xpl-background-messaging-positive` |\n| `&--success` | border | `--xpl-border-positive` |\n| `&__icon--neutral` | color | `--xpl-icon-default` |\n| `&__icon--warning` | color | `--xpl-icon-negative` |\n| `&__icon--success` | color | `--xpl-icon-positive` |\n| `&` | body radius | `--xpl-border-radius-small` |\n| `&` | shadow color | `--xpl-color-transparent-neutral-10` / `--xpl-color-transparent-neutral-5` |\n| `&__title` | typography (size / weight / line-height) | `@extend .xpl-text-title-5` → `title-5` / `medium` / `1.4286` |\n| `&__caption` | typography (size / weight / line-height) | `@extend .xpl-text-callout` → `callout` / `normal` / `1.3333` |\n| `&__close` | margin | `@apply ml-4` |\n\nThe close control is an [`xpl-button`](../xpl-button) (`variant=\"tertiary\"`, `size=\"sm\"`, `iconOnly`), so its radius, colors, and hover / focus / active states come from `button.css` rather than `toast.css`.\n\nLike `xpl-banner`, the messaging backgrounds resolve to transparent in dark mode; the sentiment border and page surface carry the visual treatment in that theme.\n\n## Accessibility\n\n- The close control is an [`xpl-button`](../xpl-button), so it is focusable and keyboard-activable (Tab, then Enter or Space) and gets the shared `:focus-visible` outline.\n- It carries `aria-label=\"Dismiss notification\"` and `type=\"button\"` — the explicit type keeps a toast rendered inside a `<form>` from submitting it when the toast is closed.\n- Toast content is projected through the `title` and `action` slots. Provide the title as text (e.g. `<p slot=\"title\">`) so screen readers announce the message.\n- Dismissing runs a fade-out animation and then removes the host element from the DOM, so a dismissed toast leaves nothing behind in the accessibility tree.\n\n> **Elevation shadow (interim):** Figma specs the toast shadow as the single \"Shadow 4\" elevation style (`y=20`, `blur=25`, color `background-surface-transparent-10`). Foundation has no elevation/shadow tokens yet, so the shadow geometry is hand-authored and its color uses the primitive `--xpl-color-transparent-neutral-10 / -5`. This migrates to the purpose-specific `--xpl-background-surface-transparent-10` (theme-aware) once elevation tokens land — tracked in `TECH_DEBT.md`.\n",
+      "readme": "# xpl-toast\n\nToasts are brief, non-disruptive messages that provide quick, at-a-glance feedback. They can have 3 sentiments; neutral, positive and negative and contain actions such as a button or link, or a close button. Messaging can include a title and caption limited to 85 characters. Keep your toast messaging short and to the point and tone in line with the sentiment of the Toast. \n\nThe Toast component is configurable by Sentiment plus show/hide properties for Icon, Caption, Button and Dismissible. Use the nested component’s properties to customize further as needed. \n\nWhen possible, Toasts should auto-dismiss after 8 seconds. When an action is present, it may not be desirable to time out the Toast depending on your specific context.  \n\nMatch your messaging with the sentiment of the toast. Most messages will have a neutral sentiment. Reserve negative sentiments for when an explicit failure has occurred. Give users the information they need to correct the issue. \n\nToasts only support a single action and up to 85 characters. If multiple actions can be taken, or the message is longer than a few words, use a [Modal component](https://apollo.xplordocs.com/?path=/story/components-modal--modal) instead.\n\n## Usage\n\n```html\n<!-- Neutral toast with a caption, auto-dismissing after the default 8s -->\n<xpl-toast caption=\"Your changes have been saved.\">\n    <p slot=\"title\">Saved</p>\n</xpl-toast>\n\n<!-- With an action. Auto-dismiss is suppressed while the action slot has content -->\n<xpl-toast variant=\"warning\" caption=\"We couldn't reach the server.\">\n    <p slot=\"title\">Sync failed</p>\n    <xpl-button slot=\"action\" size=\"sm\">Retry</xpl-button>\n</xpl-toast>\n\n<!-- No close button; disable auto-dismiss with timeout=\"0\" -->\n<xpl-toast dismissible=\"false\" timeout=\"0\">\n    <p slot=\"title\">Uploading…</p>\n</xpl-toast>\n```\n\n## Deprecations\n\n### `dismissable` → `dismissible`\n\nThe **`dismissable`** prop is misspelled and is **deprecated**. Use **`dismissible`** instead.\n\n```html\n<!-- Before -->\n<xpl-toast dismissable=\"false\">…</xpl-toast>\n\n<!-- After -->\n<xpl-toast dismissible=\"false\">…</xpl-toast>\n```\n\nBoth props are supported during the deprecation window, so no consumer change is required immediately:\n\n| `dismissable` | `dismissible` | Close button shown | Notes |\n| ------------- | ------------- | ------------------ | ----- |\n| unset | unset | ✅ | Default (`dismissible` defaults to `true`) |\n| unset | `false` | ❌ | Recommended usage |\n| `false` | unset | ❌ | Existing markup keeps working |\n| `false` | `true` | ❌ | `dismissable` wins while it exists |\n\n`dismissable` has **no default** (`undefined` when unset) so the component can tell \"not set\" from \"set to `false`\". When it is used, the component logs a one-time deprecation warning to the console. `dismissable` will be removed in the next major version, at which point `dismissible` becomes the only option.\n\n## Positioning\n\nThe default position is arbitrarily set to `40px` from top and `40px` from right of the browser viewport on desktop and bottom-center on mobile. This position should be adjusted to ensure it's not covering your App's header. Apollo, by design, does not prescribe a position for toasts because this will be dependent on the app that it is being used in.\n\nPositioning of toasts should be global to your app. For example, if it is decided that your app will always position the toast in the top right corner, then this convention should be followed throughout. It should not be positioned top-right on one screen and bottom-center on another.\n\n*****Consult your designer for the best placement for your product.**\n\n### Overriding the default position\n\nThe toast uses `position: fixed` and can be repositioned by overriding the `.xpl-toast` CSS class in your app's stylesheet. Set `top`, `right`, `bottom`, and `left` as needed and use `unset` or `initial` to clear any defaults you don't want.\n\n**Top-left example:**\n```css\n.xpl-toast {\n  top: 24px;\n  right: unset;\n  left: 24px;\n}\n```\n\n**Bottom-right example:**\n```css\n.xpl-toast {\n  top: unset;\n  right: 24px;\n  bottom: 24px;\n}\n```\n\n**Centered at the top:**\n```css\n.xpl-toast {\n  top: 24px;\n  right: unset;\n  left: 50%;\n  transform: translateX(-50%);\n}\n```\n\nThe mobile breakpoint (≤ 768px) resets the toast to bottom-center. If your app needs a different mobile position, override the media query as well:\n\n```css\n@media screen and (max-width: 768px) {\n  .xpl-toast {\n    /* your mobile overrides */\n    bottom: 16px;\n    left: 50%;\n    transform: translateX(-50%);\n  }\n}\n```\n\n> **Tip:** Place these overrides in a global stylesheet so every toast in your app appears in the same location.\n\n## Token Use\n\n`xpl-toast` follows the same messaging-component token pattern as [`xpl-banner`](../xpl-banner) (background `--xpl-background-messaging-*` + accent/sentiment border). Light and dark mode are handled by the Foundation token definitions, so the component has no `.dark` overrides.\n\n| Variant / element | Property | Token |\n| ----------------- | -------- | ----- |\n| `neutral` (default) | background | `--xpl-background-messaging-information` |\n| `neutral` (default) | border | `--xpl-border-accent-information` |\n| `&--warning` | background | `--xpl-background-messaging-negative` |\n| `&--warning` | border | `--xpl-border-negative` |\n| `&--success` | background | `--xpl-background-messaging-positive` |\n| `&--success` | border | `--xpl-border-positive` |\n| `&__icon--neutral` | color | `--xpl-icon-default` |\n| `&__icon--warning` | color | `--xpl-icon-negative` |\n| `&__icon--success` | color | `--xpl-icon-positive` |\n| `&` | body radius | `--xpl-border-radius-small` |\n| `&` | shadow | `--xpl-elevation-3` (theme-aware) |\n| `&__title` | typography (size / weight / line-height) | `@extend .xpl-text-title-5` → `title-5` / `medium` / `1.4286` |\n| `&__caption` | typography (size / weight / line-height) | `@extend .xpl-text-callout` → `callout` / `normal` / `1.3333` |\n| `&__close` | margin | `@apply ml-4` |\n\nThe close control is an [`xpl-button`](../xpl-button) (`variant=\"tertiary\"`, `size=\"sm\"`, `iconOnly`), so its radius, colors, and hover / focus / active states come from `button.css` rather than `toast.css`.\n\nLike `xpl-banner`, the messaging backgrounds resolve to transparent in dark mode; the sentiment border and page surface carry the visual treatment in that theme.\n\n## Accessibility\n\n- The close control is an [`xpl-button`](../xpl-button), so it is focusable and keyboard-activable (Tab, then Enter or Space) and gets the shared `:focus-visible` outline.\n- It carries `aria-label=\"Dismiss notification\"` and `type=\"button\"` — the explicit type keeps a toast rendered inside a `<form>` from submitting it when the toast is closed.\n- Toast content is projected through the `title` and `action` slots. Provide the title as text (e.g. `<p slot=\"title\">`) so screen readers announce the message.\n- Dismissing runs a fade-out animation and then removes the host element from the DOM, so a dismissed toast leaves nothing behind in the accessibility tree.\n\n> **Elevation shadow:** the toast uses `--xpl-elevation-3` (theme-aware), re-specified by design during the elevation 1–4 formalization — an earlier note citing the single \"Shadow 4\" style was superseded. See `TECH_DEBT.md`.\n",
       "docs": "Toasts are brief, non-disruptive messages that provide quick, at-a-glance feedback. They can have 3 sentiments; neutral, positive and negative and contain actions such as a button or link, or a close button. Messaging can include a title and caption limited to 85 characters. Keep your toast messaging short and to the point and tone in line with the sentiment of the Toast. \n\nThe Toast component is configurable by Sentiment plus show/hide properties for Icon, Caption, Button and Dismissible. Use the nested component’s properties to customize further as needed. \n\nWhen possible, Toasts should auto-dismiss after 8 seconds. When an action is present, it may not be desirable to time out the Toast depending on your specific context.  \n\nMatch your messaging with the sentiment of the toast. Most messages will have a neutral sentiment. Reserve negative sentiments for when an explicit failure has occurred. Give users the information they need to correct the issue. \n\nToasts only support a single action and up to 85 characters. If multiple actions can be taken, or the message is longer than a few words, use a [Modal component](https://apollo.xplordocs.com/?path=/story/components-modal--modal) instead.",
       "docsTags": [
         {
@@ -15287,7 +15935,7 @@
       "filePath": "src/components/components/xpl-toggle/xpl-toggle.tsx",
       "encapsulation": "none",
       "tag": "xpl-toggle",
-      "readme": "# xpl-toggle\n\nA Toggle is a type of form control that is used to switch between enabled and disabled states of an element.\n\n## Usage\n\n```html\n<xpl-toggle heading=\"Notifications\" label=\"Email me\" checked></xpl-toggle>\n<xpl-toggle label=\"Compact\" variant=\"small\"></xpl-toggle>\n<xpl-toggle label=\"Unavailable\" disabled></xpl-toggle>\n```\n\n## Design Tokens\n\nThe toggle uses Apollo Foundation purpose-specific tokens so it themes automatically\nin light and dark mode (no `.dark` overrides).\n\n| Element / state | Property | Token |\n| --- | --- | --- |\n| Track (off) | `background-color` | `--xpl-background-accent-neutral` |\n| Track (off, hover) | `background-color` | `--xpl-background-accent-neutral-bold` |\n| Track (on) | `background-color` | `--xpl-background-action-primary-default` |\n| Track (on, hover) | `background-color` | `--xpl-background-action-primary-hover` |\n| Track (disabled, on/off) | `background-color` | `--xpl-background-action-disabled` |\n| Track border | `border-color` | `--xpl-border-default` |\n| Knob (all states) | `background-color` | `--xpl-background-surface-inverse-on-dark` (always-light — resolves to neutral-0 in both modes) |\n| Knob shadow | `box-shadow` color | `--xpl-color-transparent-neutral-10` |\n| Focus ring | `outline-color` | `--xpl-border-focus` (2px outline, 2px offset) |\n| Heading | `color` | `--xpl-text-strong` |\n| Heading | typography | `@extend .xpl-text-title-5` — 14px / medium / 1.4286 (via shared `label.css`) |\n| Trailing label | `color` | `--xpl-text-strong` |\n| Trailing label | typography | `@extend .xpl-text-body` — 14px / normal / 1.4286 |\n| Label (disabled) | `color` | `--xpl-text-disabled` |\n| Description (`small`) | `color` | `--xpl-text-subdued` |\n| Description (`small`) | typography | `@extend .xpl-text-callout` — 12px / normal / 1.3333 (via shared `label.css`) |\n\n**Sizing:** knob (`--xpl-size-125` / small `--xpl-size-075`), default track height\n(`--xpl-size-150`), small track height/radius (`--xpl-size-100` / `--xpl-border-radius-default`),\ndefault track + knob radius (`--xpl-border-radius-full`), inset (`--xpl-space-2`), knob travel\n(`translateX(--xpl-size-125)` / small `--xpl-size-075`). The `44px`/`28px` track widths have no\nmatching Foundation token and remain literals (see TECH_DEBT.md).\n\nThe knob glyphs (X / check marks) remain hardcoded data-URI SVGs; a `mask-image` +\n`var(--xpl-icon-*)` refactor is tracked in TECH_DEBT.md.\n\n## Accessibility\n\nThe toggle renders a native `<input type=\"checkbox\">`, so it is keyboard-focusable and\noperable with Tab and Space. The `:focus-visible` outline is applied to the control itself.\n",
+      "readme": "# xpl-toggle\n\nA Toggle is a type of form control that is used to switch between enabled and disabled states of an element.\n\n## Usage\n\n```html\n<xpl-toggle heading=\"Notifications\" label=\"Email me\" checked></xpl-toggle>\n<xpl-toggle label=\"Compact\" variant=\"small\"></xpl-toggle>\n<xpl-toggle label=\"Unavailable\" disabled></xpl-toggle>\n```\n\n## Design Tokens\n\nThe toggle uses Apollo Foundation purpose-specific tokens so it themes automatically\nin light and dark mode (no `.dark` overrides).\n\n| Element / state | Property | Token |\n| --- | --- | --- |\n| Track (off) | `background-color` | `--xpl-background-accent-neutral` |\n| Track (off, hover) | `background-color` | `--xpl-background-accent-neutral-bold` |\n| Track (on) | `background-color` | `--xpl-background-action-primary-default` |\n| Track (on, hover) | `background-color` | `--xpl-background-action-primary-hover` |\n| Track (disabled, on/off) | `background-color` | `--xpl-background-action-disabled` |\n| Track border | `border-color` | `--xpl-border-default` |\n| Knob (all states) | `background-color` | `--xpl-background-surface-inverse-on-dark` (always-light — resolves to neutral-0 in both modes) |\n| Knob shadow | `box-shadow` | `--xpl-elevation-1` (theme-aware) |\n| Focus ring | `outline-color` | `--xpl-border-focus` (2px outline, 2px offset) |\n| Heading | `color` | `--xpl-text-strong` |\n| Heading | typography | `@extend .xpl-text-title-5` — 14px / medium / 1.4286 (via shared `label.css`) |\n| Trailing label | `color` | `--xpl-text-strong` |\n| Trailing label | typography | `@extend .xpl-text-body` — 14px / normal / 1.4286 |\n| Label (disabled) | `color` | `--xpl-text-disabled` |\n| Description (`small`) | `color` | `--xpl-text-subdued` |\n| Description (`small`) | typography | `@extend .xpl-text-callout` — 12px / normal / 1.3333 (via shared `label.css`) |\n\n**Sizing:** knob (`--xpl-size-125` / small `--xpl-size-075`), default track height\n(`--xpl-size-150`), small track height/radius (`--xpl-size-100` / `--xpl-border-radius-default`),\ndefault track + knob radius (`--xpl-border-radius-full`), inset (`--xpl-space-2`), knob travel\n(`translateX(--xpl-size-125)` / small `--xpl-size-075`). The `44px`/`28px` track widths have no\nmatching Foundation token and remain literals (see TECH_DEBT.md).\n\nThe knob glyphs (X / check marks) remain hardcoded data-URI SVGs; a `mask-image` +\n`var(--xpl-icon-*)` refactor is tracked in TECH_DEBT.md.\n\n## Accessibility\n\nThe toggle renders a native `<input type=\"checkbox\">`, so it is keyboard-focusable and\noperable with Tab and Space. The `:focus-visible` outline is applied to the control itself.\n",
       "docs": "A Toggle is a type of form control that is used to switch between enabled and disabled states of an element.",
       "docsTags": [
         {
@@ -15500,7 +16148,7 @@
       "filePath": "src/components/components/xpl-toolbar/xpl-toolbar.tsx",
       "encapsulation": "none",
       "tag": "xpl-toolbar",
-      "readme": "# xpl-toolbar\n\n> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\n## Design Tokens\n\nThe toolbar is an **always-dark** selection bar (nav-rail pattern) — its surface stays dark\nin both light and dark themes. Styling comes from Apollo Foundation tokens\n(`packages/apollo-core/src/css/toolbar.css`):\n\n| Element | Property | Token | Resolves (light / dark) |\n| --- | --- | --- | --- |\n| `.toolbar` surface | `background-color` | `--xpl-background-surface-inverse-on-light` | neutral-1000 / neutral-1000 |\n| `.toolbar` top/bottom border | `border-color` | `--xpl-border-default` | neutral-600 (always-dark host) |\n| `.toolbar` elevation | `box-shadow` | `--xpl-color-transparent-neutral-10`, `--xpl-color-transparent-neutral-5` | fixed neutral transparent |\n| `.toolbar` height | `height` | `--xpl-size-350` | 56px |\n| `.selected-item-count` text | `color` | `--xpl-text-inverse-on-dark` | white / white |\n| `.selected-item-count` divider | `border-color` | `--xpl-border-default` | neutral-600 (always-dark host) |\n| `.selected-item-count` label | `font-size` / `font-weight` / `line-height` | `@extend .xpl-text-title-5` (14px, medium, 1.4286) | — |\n\n> **Design note:** the always-dark surface decision is confirmed (there is no\n> toolbar node in `figma-manifest.json`). Foundation defines no shadow tokens, so the\n> elevation uses the neutral transparent primitives. See `TECH_DEBT.md`.\n",
+      "readme": "# xpl-toolbar\n\n> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\n\n## Design Tokens\n\nThe toolbar is an **always-dark** selection bar (nav-rail pattern) — its surface stays dark\nin both light and dark themes. Styling comes from Apollo Foundation tokens\n(`packages/apollo-core/src/css/toolbar.css`):\n\n| Element | Property | Token | Resolves (light / dark) |\n| --- | --- | --- | --- |\n| `.toolbar` surface | `background-color` | `--xpl-background-surface-inverse-on-light` | neutral-1000 / neutral-1000 |\n| `.toolbar` top/bottom border | `border-color` | `--xpl-border-default` | neutral-600 (always-dark host) |\n| `.toolbar` elevation | `box-shadow` | `--xpl-elevation-1` | theme-aware (near-black light / near-white dark) |\n| `.toolbar` height | `height` | `--xpl-size-350` | 56px |\n| `.selected-item-count` text | `color` | `--xpl-text-inverse-on-dark` | white / white |\n| `.selected-item-count` divider | `border-color` | `--xpl-border-default` | neutral-600 (always-dark host) |\n| `.selected-item-count` label | `font-size` / `font-weight` / `line-height` | `@extend .xpl-text-title-5` (14px, medium, 1.4286) | — |\n\n> **Design note:** the always-dark surface decision is confirmed (there is no\n> toolbar node in `figma-manifest.json`). The elevation uses the theme-aware\n> `--xpl-elevation-1` token: in dark mode the shadow color flips to near-white, so\n> the always-dark bar gets a light halo beneath it — flagged for design verification\n> (see `TECH_DEBT.md`).\n",
       "docs": "> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.",
       "docsTags": [
         {
@@ -15562,7 +16210,7 @@
       "filePath": "src/components/components/xpl-tooltip/xpl-tooltip.tsx",
       "encapsulation": "none",
       "tag": "xpl-tooltip",
-      "readme": "# xpl-tooltip\n\nTooltips are intended to be short one to two sentence messages adding contextual information for the user. Keep messages short and to the point. Tooltips are static and do not contain actions, and only appear when the context is hovered.\n\nTooltip variants control one of 8 arrow positions indicating the direction the tooltip will appear in relation to it's trigger:\n\"bottom-left\" | \"bottom-middle\" | \"bottom-right\" | \"left\" | \"right\" | \"top-left\" | \"top-middle\" | \"top-right\"\n\n\n### Design Tokens\n\nTokens used by this component from `@xplortech/apollo-foundation`.\n\n**Color**\n- `--xpl-background-surface-default` — tooltip background and arrow fill\n- `--xpl-background-surface-transparent-10` — shadow primary layer\n- `--xpl-background-surface-transparent-5` — shadow secondary layer\n- `--xpl-text-default` — tooltip text color\n- `--xpl-border-default` — tooltip border and arrow stroke (keeps the arrow edge theme-aware in dark mode)\n\n**Spacing**\n- `--xpl-space-6` — vertical padding\n- `--xpl-space-8` — horizontal padding\n- `--xpl-space-12` — offset from trigger, via `--xpl-tooltip-margin`\n\n**Typography**\n- `.xpl-text-callout` — text style (via `@extend`)\n\n**Border**\n- `--xpl-border-small` — border width (1px)\n- `--xpl-border-radius-small` — corner radius (4px)\n\n**Z-index**\n- `--xpl-z-index-900` — tooltip stacking order\n- `--xpl-z-index-100` — arrow base stacking order (elevated to `--xpl-z-index-900` per position variant)\n",
+      "readme": "# xpl-tooltip\n\nTooltips are intended to be short one to two sentence messages adding contextual information for the user. Keep messages short and to the point. Tooltips are static and do not contain actions, and only appear when the context is hovered.\n\nTooltip variants control one of 8 arrow positions indicating the direction the tooltip will appear in relation to it's trigger:\n\"bottom-left\" | \"bottom-middle\" | \"bottom-right\" | \"left\" | \"right\" | \"top-left\" | \"top-middle\" | \"top-right\"\n\n\n### Design Tokens\n\nTokens used by this component from `@xplortech/apollo-foundation`.\n\n**Color**\n- `--xpl-background-surface-default` — tooltip background and arrow fill\n- `--xpl-elevation-3` — tooltip shadow (theme-aware)\n- `--xpl-text-default` — tooltip text color\n- `--xpl-border-default` — tooltip border and arrow stroke (keeps the arrow edge theme-aware in dark mode)\n\n**Spacing**\n- `--xpl-space-6` — vertical padding\n- `--xpl-space-8` — horizontal padding\n- `--xpl-space-12` — offset from trigger, via `--xpl-tooltip-margin`\n\n**Typography**\n- `.xpl-text-callout` — text style (via `@extend`)\n\n**Border**\n- `--xpl-border-small` — border width (1px)\n- `--xpl-border-radius-small` — corner radius (4px)\n\n**Z-index**\n- `--xpl-z-index-900` — tooltip stacking order\n- `--xpl-z-index-100` — arrow base stacking order (elevated to `--xpl-z-index-900` per position variant)\n",
       "docs": "Tooltips are intended to be short one to two sentence messages adding contextual information for the user. Keep messages short and to the point. Tooltips are static and do not contain actions, and only appear when the context is hovered.\n\nTooltip variants control one of 8 arrow positions indicating the direction the tooltip will appear in relation to it's trigger:\n\"bottom-left\" | \"bottom-middle\" | \"bottom-right\" | \"left\" | \"right\" | \"top-left\" | \"top-middle\" | \"top-right\"",
       "docsTags": [
         {
@@ -16628,6 +17276,21 @@
       "docstring": "",
       "path": "src/components/components/xpl-badge/xpl-badge.tsx"
     },
+    "src/components/components/xpl-table/xpl-table.tsx::XplTableRowOrderChangeDetail": {
+      "declaration": "export interface XplTableRowOrderChangeDetail {\n    /** Stable id of the moved row (`row-id`). */\n    rowId: string;\n    direction: 'up' | 'down';\n    /** Visible body row ids in DOM order after the move. */\n    orderedRowIds: string[];\n    fromIndex: number;\n    toIndex: number;\n}",
+      "docstring": "",
+      "path": "src/components/components/xpl-table/xpl-table.tsx"
+    },
+    "src/components/components/xpl-table/xpl-table.tsx::XplTableSortChangedDetail": {
+      "declaration": "export interface XplTableSortChangedDetail {\n    /**\n     * @deprecated Prefer slug keys on this object. Index of the column whose sort was toggled (legacy tables).\n     */\n    colNum?: number;\n    /**\n     * @deprecated Prefer slug keys. Legacy **slugified** column title for `colNum` (same rules as sort-key slugs).\n     */\n    colName?: string;\n    /**\n     * @deprecated Prefer slug keys. Per-column sort state in visual column order (`null` when unsorted / N/A).\n     */\n    sortTypeArr?: ('asc' | 'desc' | null)[];\n    [slug: string]: 'asc' | 'desc' | null | number | string | ('asc' | 'desc' | null)[] | undefined;\n}",
+      "docstring": "`sortChanged` event detail: sort-key slug → direction, plus **legacy** fields for consumers that\nstill read `colNum` / `colName` / `sortTypeArr` from the data-driven table API.\n\nIndex signature allows slug keys alongside legacy properties (cannot use `Record<>` alone without conflicting\nwith `colNum`).",
+      "path": "src/components/components/xpl-table/xpl-table.tsx"
+    },
+    "src/components/components/xpl-table/xpl-table-header-cell/xpl-table-header-cell.tsx::HeaderSortChangeDetail": {
+      "declaration": "export interface HeaderSortChangeDetail {\n    columnIndex: number;\n    sortKey: string;\n}",
+      "docstring": "",
+      "path": "src/components/components/xpl-table/xpl-table-header-cell/xpl-table-header-cell.tsx"
+    },
     "src/components/components/xpl-tag/xpl-tag.tsx::TagDragEndDetail": {
       "declaration": "export interface TagDragEndDetail {\n    tagId?: string;\n    dropped: boolean;\n    originalEvent: DragEvent;\n}",
       "docstring": "Detail for drag end event",