@xplortech/apollo-core 2.6.0 → 2.7.1

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

@@ -0,0 +1,235 @@
+# xpl-spotlight
+
+`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.
+
+## Usage Examples
+
+Use the built-in title/body props and default actions for a simple tour step:
+
+```html
+<xpl-spotlight
+  heading="Review recent activity"
+  body="Check status updates here before moving to the next step."
+  action-layout="default"
+  anchor-position="top-right"
+  current-step="2"
+  total-steps="5"
+  is-dismissible="true"
+  is-open="true"
+  primary-action-label="Next"
+  secondary-action-label="Back"
+  show-actions="true"
+  show-image="true"
+  show-steps="true"
+  target=""
+></xpl-spotlight>
+```
+
+Anchor the spotlight to a specific element and provide custom media content:
+
+```html
+<button id="dashboard-filter-button" type="button">Filters</button>
+
+<xpl-spotlight
+  target="#dashboard-filter-button"
+  heading="Narrow the results"
+  body="Use filters to focus on the accounts or activity that matter most."
+  current-step="1"
+  total-steps="3"
+  primary-action-label="Next"
+  secondary-action-label="Skip"
+>
+  <div slot="image">
+    <img src="/assets/spotlight-filter-preview.png" alt="Preview of filter controls" />
+  </div>
+</xpl-spotlight>
+```
+
+
+Control visibility from the parent with `is-open` and close it by responding to `dismiss`:
+
+```html
+<xpl-spotlight
+  id="guided-tour-step"
+  is-open="true"
+  heading="Review recent activity"
+  body="Check status updates here before moving to the next step."
+></xpl-spotlight>
+
+<script>
+  const spotlight = document.getElementById('guided-tour-step');
+
+  spotlight?.addEventListener('dismiss', () => {
+    spotlight.setAttribute('is-open', 'false');
+  });
+</script>
+```
+
+Mirror the same layout in plain HTML when documenting or prototyping the component structure outside the custom element:
+
+```html
+<div class="xpl-spotlight xpl-spotlight--top-left xpl-spotlight--visible"
+     role="dialog" aria-modal="false" aria-labelledby="spotlight-title" tabindex="-1">
+  <button type="button" class="xpl-spotlight__target" aria-label="Spotlight indicator">
+    <div class="xpl-spotlight__target-outer"></div>
+    <div class="xpl-spotlight__target-inner"></div>
+  </button>
+  <div class="xpl-spotlight__dismiss">
+    <xpl-button variant="secondary" size="sm" icon-only aria-label="Dismiss tour step">
+      <xpl-icon icon="xmark" size="16"></xpl-icon>
+    </xpl-button>
+  </div>
+  <div class="xpl-spotlight__frame">
+    <div class="xpl-spotlight__image-container">
+      <img src="/assets/spotlight-preview.png" alt="Feature preview" />
+    </div>
+    <div class="xpl-spotlight__content">
+      <div class="xpl-spotlight__header">
+        <span class="xpl-spotlight__title" id="spotlight-title">Tour Title</span>
+        <p class="xpl-spotlight__body">Copy about the feature and/or functionality the dot is pointing to.</p>
+      </div>
+      <div class="xpl-spotlight__actions xpl-spotlight__actions--dual xpl-spotlight__actions--with-steps">
+        <div class="xpl-spotlight__action-slot xpl-spotlight__action-slot--secondary">
+          <xpl-button variant="secondary">Back</xpl-button>
+        </div>
+        <span class="xpl-spotlight__step-text">2 of 5</span>
+        <div class="xpl-spotlight__action-slot xpl-spotlight__action-slot--primary">
+          <xpl-button variant="primary">Next</xpl-button>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+## Accessibility
+
+`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:
+
+- When the default title is used, the generated heading element receives the internal `aria-labelledby` id.
+- 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).
+- 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.
+
+### Keyboard navigation
+
+| Key | Behavior |
+|-----|----------|
+| `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. |
+| `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. |
+| `Enter` / `Space` | Activates the focused button (dismiss, primary, or secondary action) via standard `xpl-button` behavior. |
+
+### Focus management
+
+- **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"`.
+- **On close:** focus returns to the element that was focused before the spotlight opened, provided that element is still in the DOM.
+- The decorative anchor dot (`.xpl-spotlight__target`) is marked `aria-hidden="true"` so it is not announced or focusable.
+
+
+## Design Tokens
+
+The component relies on Foundation purpose tokens in `spotlight.css` so light/dark mode works without component-level `.dark` overrides.
+
+| Property | Token |
+|----------|-------|
+| 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`) |
+| Image region min-height | `var(--xpl-spotlight-image-min-height)` on `.xpl-spotlight__image-container` (same note as card width) |
+| Card background | `var(--xpl-background-surface-default)` |
+| Host stacking | `var(--xpl-z-index-800)` |
+| Placeholder pattern | `var(--xpl-background-surface-subtle)` |
+| Heading text | `var(--xpl-text-default)` |
+| Body text | `var(--xpl-text-default)` |
+| Step text | `var(--xpl-text-subdued)` |
+| Open/closed visibility | `opacity` transition on `.xpl-spotlight--visible` |
+| Anchor outer ring | `var(--xpl-background-surface-information-bold)` |
+| Anchor inner dot | `var(--xpl-background-accent-default)` |
+| Image placeholder icon/text | `var(--xpl-icon-subtle)` |
+| Focus outline | `var(--xpl-border-focus)` |
+| Anchored host (when `target` is set) | `position: fixed` via `.xpl-spotlight--anchored`; `left` / `top` set from Floating UI (`strategy: 'fixed'`) |
+
+## Icon Mapping
+
+`xpl-spotlight` uses Apollo icons for fixed controls and fallback media placeholders:
+
+| UI area | `xpl-icon` name |
+|---------|------------------|
+| Dismiss button | `xmark` |
+| Empty image placeholder, image affordance | `photo` |
+| Empty image placeholder, video affordance | `video` |
+
+## Deprecated props
+
+None.
+
+## Notes
+
+- `showImage="false"` hides the media region even if `slot="image"` content is present.
+- 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.
+- `showActions="false"` removes the default actions row entirely.
+- `is-open="false"` keeps the host element mounted but renders no spotlight UI until it is opened again.
+- `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.
+- `primary-action-label` and `secondary-action-label` control the default button text without needing action slots.
+- `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`).
+- If `target` is missing or contains an invalid CSS selector, the component safely falls back to the requested `anchor-position` instead of throwing.
+- **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).
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property               | Attribute                | Description                                                                                                                                                                                                                                                                                                                                                    | Type                                                           | Default      |
+| ---------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------ |
+| `actionLayout`         | `action-layout`          | Footer action layout. `default` and `dual` both render the standard Back/Next layout, while `single` renders a single acknowledgement CTA (e.g. "Got it!"). Only applies when `showActions` is `true`.                                                                                                                                                         | `"default" \| "dual" \| "single"`                              | `'default'`  |
+| `anchorPosition`       | `anchor-position`        | Which corner of the card the anchor dot uses when not using `target`, or as the preferred side for Floating UI.                                                                                                                                                                                                                                                | `"bottom-left" \| "bottom-right" \| "top-left" \| "top-right"` | `'top-left'` |
+| `body`                 | `body`                   | Body copy when the `body` slot has no slotted content. Whitespace-only values are treated as empty (no fallback paragraph).                                                                                                                                                                                                                                    | `string`                                                       | `undefined`  |
+| `currentStep`          | `current-step`           | Current step index (1-based). Used with `totalSteps` for the step label and for disabling default Back/Next when `showSteps` is true.                                                                                                                                                                                                                          | `number`                                                       | `1`          |
+| `heading`              | `heading`                | Heading when the `title` slot has no slotted content. Whitespace-only values are treated as empty (no fallback title span).                                                                                                                                                                                                                                    | `string`                                                       | `undefined`  |
+| `isDismissible`        | `is-dismissible`         | Whether to show the dismiss (close) control.                                                                                                                                                                                                                                                                                                                   | `boolean`                                                      | `true`       |
+| `isOpen`               | `is-open`                | Controls whether the spotlight is rendered. When false, the host remains in the DOM but the spotlight UI is hidden.                                                                                                                                                                                                                                            | `boolean`                                                      | `true`       |
+| `primaryActionLabel`   | `primary-action-label`   | Label used for the default primary action button. Only applies when `showActions` is `true`.                                                                                                                                                                                                                                                                   | `string`                                                       | `'Next'`     |
+| `secondaryActionLabel` | `secondary-action-label` | Label used for the default secondary action button. Only applies when `showActions` is `true`.                                                                                                                                                                                                                                                                 | `string`                                                       | `'Back'`     |
+| `showActions`          | `show-actions`           | Whether to show the actions row (primary / secondary and optional step counter). When `false`, the spotlight has no action buttons — useful for single-step informational callouts that rely solely on the dismiss control.                                                                                                                                    | `boolean`                                                      | `true`       |
+| `showImage`            | `show-image`             | When true, the media region is shown. Slotted `image` content is rendered when present; otherwise the built-in placeholder UI is shown. When false, the entire media block is hidden.                                                                                                                                                                          | `boolean`                                                      | `true`       |
+| `showSteps`            | `show-steps`             | Whether to show the step counter between actions (`currentStep` of `totalSteps`) and whether default Back/Next use step-based disabled state.                                                                                                                                                                                                                  | `boolean`                                                      | `true`       |
+| `target`               | `target`                 | CSS selector for the element this spotlight anchors to. When set, placement uses Floating UI (`computePosition` with `strategy: 'fixed'`, plus `flip`, `shift`, `offset`) and `autoUpdate` for scroll/resize. The host receives `left` / `top` and the `xpl-spotlight--anchored` class. Invalid selectors are ignored; layout falls back to `anchor-position`. | `string`                                                       | `undefined`  |
+| `totalSteps`           | `total-steps`            | Total number of steps (1-based upper bound). Used with `currentStep` for the step label and for disabling default Back/Next when `showSteps` is true.                                                                                                                                                                                                          | `number`                                                       | `1`          |
+
+
+## Events
+
+| Event             | Description                                                                                    | Type                |
+| ----------------- | ---------------------------------------------------------------------------------------------- | ------------------- |
+| `dismiss`         | Emitted when the dismiss control is activated or Escape is pressed (when dismissible).         | `CustomEvent<void>` |
+| `primaryAction`   | Emitted when the primary action control is activated (default: Next).                          | `CustomEvent<void>` |
+| `secondaryAction` | Emitted when the secondary action control is activated (default: Back).                        | `CustomEvent<void>` |
+| `targetClick`     | Emitted when the target indicator is clicked. Consumers typically toggle `isOpen` in response. | `CustomEvent<void>` |
+
+
+## Slots
+
+| Slot      | Description                                                                                                    |
+| --------- | -------------------------------------------------------------------------------------------------------------- |
+| `"body"`  | Main description; falls back to the `body` prop when the slot is empty and `body` has non-whitespace text      |
+| `"image"` | Optional media slot. When empty and `showImage` is true, the component renders a built-in placeholder instead. |
+| `"title"` | Step title; falls back to the `heading` prop when the slot is empty and `heading` has non-whitespace text      |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-button](../xpl-button)
+- [xpl-icon](../xpl-icon)
+
+### Graph
+```mermaid
+graph TD;
+  xpl-spotlight --> xpl-button
+  xpl-spotlight --> xpl-icon
+  xpl-button --> xpl-icon
+  style xpl-spotlight fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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

@@ -1,24 +1,60 @@
 # xpl-tab
 
+`xpl-tab` is the **label / trigger** for one tab in an `xpl-tabs` group. Place each instance in the **`heading`** slot of `xpl-tabs`. The **`target`** string links this tab to the matching **`xpl-tab-panel`** (same `target` value). The parent sets **`selected`** and syncs **`value`**; you normally do not set `selected` by hand.
 
+Underline tabs render a native **`<button role="tab">`**; segment tabs render **`xpl-button`** with the same tab semantics on the inner control. For variant-specific examples, icon usage, and token tables, see the matching section on the **Tabs** or **Segment control** Storybook page.
+
+**`group-disabled`** is applied by `xpl-tabs` when the group has **`disabled`**; it keeps pills and underline buttons in a disabled state together with the parent.
+
+## Accessibility
+
+- **IDs and ARIA:** With a parent **`xpl-tabs`**, the tab control and matching **`xpl-tab-panel`** share scoped DOM ids derived from **`data-tabs-instance-id`** on the group and each pair’s **`target`** (see **`xpl-tabs`** accessibility notes). Underline tabs set **`id`**, **`role="tab"`**, **`aria-controls`**, and **`aria-selected`** on the native `<button>`. Segment tabs wrap **`xpl-button`**, which forwards **`id`**, **`role`**, and **`aria-*`** attributes to its inner `<button>` so focus and **`aria-labelledby`** stay correct.
+- Underline tabs expose a **single focusable button** per tab.
+- Segment tabs delegate rendering to **`xpl-button`** with the same tab semantics as underline mode; activation follows the same **`tabChange`** event.
+- Disabled tabs are skipped when moving with arrow keys.
 
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property   | Attribute  | Description                                                | Type      | Default     |
-| ---------- | ---------- | ---------------------------------------------------------- | --------- | ----------- |
-| `selected` | `selected` | Whether the tab is selected                                | `boolean` | `false`     |
-| `target`   | `target`   | The target of the tab, required for the tab to be selected | `string`  | `undefined` |
+| Property        | Attribute             | Description                                                                                                   | Type               | Default     |
+| --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------ | ----------- |
+| `disabled`      | `disabled`            | Disables this tab (pill or underline).                                                                        | `boolean`          | `false`     |
+| `groupDisabled` | `data-group-disabled` | Set when the parent `xpl-tabs` has `disabled` (group-disabled).                                               | `boolean`          | `false`     |
+| `icon`          | `icon`                | Optional icon name for segment-style pills (`type="segment"` on parent `xpl-tabs`). Ignored for default tabs. | `string`           | `undefined` |
+| `iconPosition`  | `icon-position`       | Icon position for segment-style pills.                                                                        | `"end" \| "start"` | `'start'`   |
+| `selected`      | `selected`            | Whether the tab is selected                                                                                   | `boolean`          | `false`     |
+| `target`        | `target`              | The target of the tab, required for the tab to be selected                                                    | `string`           | `undefined` |
 
 
 ## Events
 
-| Event       | Description                                     | Type                  |
-| ----------- | ----------------------------------------------- | --------------------- |
-| `tabChange` | Event that emits the target of the selected tab | `CustomEvent<string>` |
+| Event       | Description                                                                                                                                                                                                       | Type                  |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| `tabChange` | Emitted when this tab is activated (if not disabled). The event `detail` is this tab’s `target` string. Parent `xpl-tabs` listens and updates selection; use `tabChange` on `xpl-tabs` for the group-level event. | `CustomEvent<string>` |
+
+
+## Slots
+
+| Slot | Description                                                                        |
+| ---- | ---------------------------------------------------------------------------------- |
+|      | The label for the tab (or pill label when parent `xpl-tabs` has `type="segment"`). |
+
+
+## Dependencies
+
+### Depends on
+
+- [xpl-button](../xpl-button)
 
+### Graph
+```mermaid
+graph TD;
+  xpl-tab --> xpl-button
+  xpl-button --> xpl-icon
+  style xpl-tab fill:#f9f,stroke:#333,stroke-width:4px
+```
 
 ----------------------------------------------
 

package/dist/docs/xpl-tab-panel/readme.md

@@ -1,6 +1,41 @@
 # xpl-tab-panel
 
+`xpl-tab-panel` is the **content region** for one tab. Place each panel in the **`panel`** slot of `xpl-tabs` and set **`target`** to the same string as its paired **`xpl-tab`**. Only the panel whose `target` matches the group’s selection is visible; others stay hidden via CSS until selected.
 
+## When to use
+
+- One panel per tab in the same `xpl-tabs` as the corresponding `xpl-tab`.
+- Put any markup or other components in the **default slot** (panel body).
+
+## Usage
+
+```html
+<xpl-tabs value="overview">
+  <xpl-tab slot="heading" target="overview">Overview</xpl-tab>
+  <xpl-tab slot="heading" target="activity">Activity</xpl-tab>
+  <xpl-tab-panel slot="panel" target="overview">
+    <p class="xpl-text-body">Overview content.</p>
+  </xpl-tab-panel>
+  <xpl-tab-panel slot="panel" target="activity">
+    <p class="xpl-text-body">Activity content.</p>
+  </xpl-tab-panel>
+</xpl-tabs>
+```
+
+The parent **`xpl-tabs`** updates each panel’s **`selected`** state from **`value`** / user interaction; consumers typically only set **`target`** and slot content.
+
+## Accessibility
+
+- The host sets **`role="tabpanel"`**, a stable **`id`** (`…-panel-<target>` scoped by the parent **`xpl-tabs`** instance), and **`aria-labelledby`** referencing the paired tab control’s **`id`**. Use the same **`target`** on **`xpl-tab`** and **`xpl-tab-panel`** so the references stay aligned (see **`xpl-tabs`** accessibility section for the full id pattern).
+- Hidden panels use display toggling (`xpl-tab-panel` / `--selected` in `tabs.css`), not `aria-hidden` on the host; panel content stays in the DOM for simpler state sync.
+
+## Token use
+
+| Part | Token / approach |
+| ---- | ---------------- |
+| Panel visibility | `tabs.css`: hidden unless `xpl-tab-panel--selected` (`display` via Tailwind `@apply`) |
+| Default padding | `py-6` in `tabs.css` on `.xpl-tab-panel` |
+| Inner content | Use typography classes (`xpl-text-body`, etc.) and Foundation tokens as elsewhere in Apollo |
 
 <!-- Auto Generated Below -->
 
@@ -13,6 +48,13 @@
 | `target`   | `target`   | The target of the tab, required for the tab to be selected | `string`  | `undefined` |
 
 
+## Slots
+
+| Slot | Description                           |
+| ---- | ------------------------------------- |
+|      | Content rendered inside of the panel. |
+
+
 ----------------------------------------------
 
 *Built with [StencilJS](https://stenciljs.com/)*

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

@@ -1,23 +1,76 @@
 # xpl-tabs
 
-Tabs organize content across different screens, data sets, and other interactions.
+`xpl-tabs` groups related views into a single surface: users pick a **tab** to show the matching **panel**. It implements the WAI-ARIA tabs pattern with a horizontal tab list, optional full-width layout, and two visual styles—**underline** (`type="tabs"`, default) and **segment** (`type="segment"`, pill controls in a bordered track)—selected with the **`type`** prop. On narrow viewports the heading row is replaced by an `xpl-select` so the same targets and keyboard behavior stay consistent.
+
+The **Tabs** and **Segment control** Storybook entries document this **one component** with different defaults and Figma references. Each page adds variant-specific guidance (when to use, examples, tokens); the sections below describe behavior that is **the same for both** styles.
+
+Pair **`xpl-tab` (slot `heading`)** with **`xpl-tab-panel` (slot `panel`)** and use the same **`target`** string on each pair so selection stays in sync.
+
+## Usage
+
+### Web component (`<xpl-tabs>`)
+
+Minimal group with two tabs: each `xpl-tab` and `xpl-tab-panel` shares a `target` value. Set `value` on `xpl-tabs` to control the selected tab (defaults to the first tab’s `target` if omitted).
+
+```html
+<xpl-tabs value="one">
+  <xpl-tab slot="heading" target="one">First</xpl-tab>
+  <xpl-tab slot="heading" target="two">Second</xpl-tab>
+  <xpl-tab-panel slot="panel" target="one">Content for first tab.</xpl-tab-panel>
+  <xpl-tab-panel slot="panel" target="two">Content for second tab.</xpl-tab-panel>
+</xpl-tabs>
+```
+
+Listen for selection changes with the **`tabChange`** event (detail is the selected `target` string):
+
+```html
+<xpl-tabs id="demo" value="a">
+  <xpl-tab slot="heading" target="a">A</xpl-tab>
+  <xpl-tab slot="heading" target="b">B</xpl-tab>
+  <xpl-tab-panel slot="panel" target="a">…</xpl-tab-panel>
+  <xpl-tab-panel slot="panel" target="b">…</xpl-tab-panel>
+</xpl-tabs>
+<script>
+  document.getElementById('demo').addEventListener('tabChange', (e) => {
+    console.log(e.detail); // "a" | "b"
+  });
+</script>
+```
+
+Disable the entire group (headings, mobile select, and segment pills) with **`disabled`** on `xpl-tabs`. Disable individual tabs with **`disabled`** on `xpl-tab`.
+
+### Plain HTML (BEM classes)
+
+When styling with `tabs.css` without the Stencil component, mirror the structure: `xpl-tabs`, `xpl-tabs__headings` with `role="tablist"` and `aria-orientation="horizontal"`, `xpl-tabs__active-bar` for the underline variant (position/size normally set by JS), **`button.xpl-tab__button`** with **`role="tab"`** (not links), and **`xpl-tab-panel`** for panels. For **segment** (`xpl-tabs--segment`), each heading is **`xpl-tab.xpl-tab--segment`** wrapping **`xpl-button`** (not `.xpl-tab__button`). On small viewports, include **`xpl-tabs__mobile-select`** with **`xpl-select`** for parity with the component.
+
+## Accessibility
+
+- Each **`xpl-tabs`** root gets a unique **`data-tabs-instance-id`** (for example `xpl-tg-1`). **`xpl-tab`** and **`xpl-tab-panel`** derive matching DOM **`id`** values from that id plus the shared **`target`** string: the tab control is **`…-tab-<target>`**, the panel is **`…-panel-<target>`** (with `target` sanitized for HTML `id` rules). The tab exposes **`aria-controls`** pointing at the panel id, **`aria-selected`**, and the panel uses **`aria-labelledby`** pointing at the tab id. **Segment (pill) tabs** render **`xpl-button`**; because **`xpl-button`** does not forward **`id`** / **`role`** / **`aria-*`** to its inner `<button>`, **`xpl-tab`** sets those on the native button after render so focus order and **`aria-labelledby`** stay correct (same pattern as underline tabs, different host element).
+- The tab list container is **`role="tablist"`** with **`aria-orientation="horizontal"`**. Underline tabs use **`role="tab"`** on the inner `<button>`; panels use **`role="tabpanel"`** on **`xpl-tab-panel`**.
+- **Roving tabindex:** only the active tab’s control is in the tab order (`tabindex="0"`); others use `tabindex="-1"` until focused with arrows.
+- **Keyboard:** **Arrow Left/Right** (and **Arrow Up/Down** as next/previous), **Home**, and **End** move between enabled tabs; **Enter** and **Space** activate (via `xpl-button` in segment mode). Direction mirrors in **RTL**.
+- When **`disabled`** is set on `xpl-tabs`, tab keyboard navigation and selection are suppressed for the group.
+
+Variant-specific Foundation mappings for underline vs. segment live in the **Tabs** and **Segment control** Storybook pages. The **`xpl-select`** mobile row reuses **`xpl-select`** / **`xpl-dropdown`** tokens from those components.
 
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property    | Attribute    | Description                                              | Type      | Default     |
-| ----------- | ------------ | -------------------------------------------------------- | --------- | ----------- |
-| `fullWidth` | `full-width` | Whether to make the tabs full width                      | `boolean` | `false`     |
-| `value`     | `value`      | The selected tab target value, defaults to the first tab | `string`  | `undefined` |
+| Property    | Attribute    | Description                                                                   | Type                  | Default     |
+| ----------- | ------------ | ----------------------------------------------------------------------------- | --------------------- | ----------- |
+| `disabled`  | `disabled`   | Disables the whole tab group (headings, mobile select, and segment pills).    | `boolean`             | `false`     |
+| `fullWidth` | `full-width` | Whether to make the tabs full width                                           | `boolean`             | `false`     |
+| `type`      | `type`       | Visual and layout variant: classic underline tabs or segment (pill) controls. | `"segment" \| "tabs"` | `'tabs'`    |
+| `value`     | `value`      | The selected tab target value, defaults to the first tab                      | `string`              | `undefined` |
 
 
 ## Events
 
-| Event       | Description                                     | Type                  |
-| ----------- | ----------------------------------------------- | --------------------- |
-| `tabChange` | Event that emits the target of the selected tab | `CustomEvent<string>` |
+| Event       | Description                                                                                                                                                                                                                                                                                     | Type                  |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| `tabChange` | Emitted when the selected tab changes (click, keyboard, or mobile `xpl-select`). The event `detail` is the selected tab’s `target` string. Always dispatched from this host (including after heading clicks) so `event.target` is consistent for listeners on `xpl-tabs` or bubbling ancestors. | `CustomEvent<string>` |
 
 
 ## Slots
@@ -41,6 +94,7 @@ graph TD;
   xpl-select --> xpl-tag
   xpl-select --> xpl-icon
   xpl-select --> xpl-dropdown
+  xpl-tag --> xpl-icon
   xpl-dropdown --> xpl-dropdown-group
   xpl-dropdown --> xpl-dropdown-option
   xpl-dropdown-group --> xpl-dropdown-group