@xplortech/apollo-core 2.5.0 → 2.7.0

package/.typings/apollo-components.html-data.json

@@ -5,7 +5,7 @@
       "name": "xpl-accordion",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "Accordions are collapsable containers and allow users to collapse or expand the container. Useful when many items are present in a section and users may benefit from closing content to gain more space or focus on content that is most important to them. \n\nUse the content slot in the opened state to swap in Apollo components or make your own local component with groups of Apollo components or custom content.\n\nNote: Users will often miss any content that is hidden behind an interaction. If it is important that users see the content, use an accordion's open state on load `initialExpanded`, or use another pattern."
       },
       "attributes": [
         {
@@ -85,7 +85,7 @@
       "name": "xpl-avatar",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "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."
       },
       "attributes": [
         {
@@ -113,17 +113,21 @@
           "name": "disabled",
           "description": "Sets a disabled state on the avatar when set to true"
         },
+        {
+          "name": "group-data",
+          "description": "When `variant` is `group`, data for each face (max 4 visible + overflow count). Each item: { src?, name?, color? }."
+        },
         {
           "name": "href",
           "description": "The URL if the avatar should be hyperlinked"
         },
         {
           "name": "name",
-          "description": "Alt text for the image if there is an image src"
+          "description": "Alt text for the image; also used for initials when no image and no slot."
         },
         {
           "name": "size",
-          "description": "Size of the avatar",
+          "description": "Size of the avatar (and of each avatar in a group).",
           "values": [
             {
               "name": "md"
@@ -139,22 +143,62 @@
         },
         {
           "name": "status",
-          "description": "Color styles for the dot indicator to indicate varied states",
+          "description": "Shown for the default avatar, `profile`, and `with-text`; not shown when `variant` is `group`.\n**Legacy",
           "values": [
             {
               "name": "active"
             },
+            {
+              "name": "blue"
+            },
+            {
+              "name": "gray"
+            },
+            {
+              "name": "green"
+            },
             {
               "name": "inactive"
             },
+            {
+              "name": "orange"
+            },
+            {
+              "name": "purple"
+            },
+            {
+              "name": "red"
+            },
             {
               "name": "warning"
+            },
+            {
+              "name": "yellow"
             }
           ]
         },
+        {
+          "name": "sub-text",
+          "description": "Secondary text shown when `variant` is `with-text` (e.g. email)."
+        },
         {
           "name": "target",
           "description": "Where to open the URL chosen for the `href` prop:\n`_self` (default), `_blank`, `_parent`, or `_top`"
+        },
+        {
+          "name": "variant",
+          "description": "Optional layout: `profile` (large profile sizes), `group` (stacked faces + `groupData`; `status` not shown),\n`with-text` (avatar with `name` / `subText` beside it). Omit for the default single avatar.",
+          "values": [
+            {
+              "name": "group"
+            },
+            {
+              "name": "profile"
+            },
+            {
+              "name": "with-text"
+            }
+          ]
         }
       ]
     },
@@ -162,7 +206,7 @@
       "name": "xpl-backdrop",
       "description": {
         "kind": "markdown",
-        "value": "This backdrop is used to add a transparent darker layer on top of the content area when the main nav is active."
+        "value": "This backdrop is used to add a transparent darker layer on top of the content area to focus the user’s attention. Typically used when a dialog such as a modal or slide out panel is active."
       },
       "attributes": [
         {
@@ -175,30 +219,142 @@
       "name": "xpl-badge",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "`xpl-badge` is a small, non-interactive status indicator used to communicate counts, states, or supplementary information next to another element. Badges are **never clickable** – use a button or link if you need interaction.\n\nBadges support multiple **variants** (colors), **sizes**, **shapes**, and **dot styles**, so they can be used both as pill labels and as compact status / notification indicators."
       },
       "attributes": [
+        {
+          "name": "bordered",
+          "description": "Whether badge shows a bordered ring"
+        },
         {
           "name": "dot",
-          "description": "Whether badge shows a dot icon before the text"
+          "description": "Whether badge shows a dot icon before the text (inside the pill)"
+        },
+        {
+          "name": "dot-only",
+          "description": "When true, render a compact badge built around the dot.\n- With no children: just a dot (status/dot badge)\n- With children: a small dot badge with the text/number inside"
+        },
+        {
+          "name": "shape",
+          "description": "Badge shape\nrounded (pill) boxy (rounded corners)",
+          "values": [
+            {
+              "name": "boxy"
+            },
+            {
+              "name": "rounded"
+            }
+          ]
+        },
+        {
+          "name": "size",
+          "description": "Badge size\ndefault | small",
+          "values": [
+            {
+              "name": "default"
+            },
+            {
+              "name": "small"
+            }
+          ]
         },
         {
           "name": "variant",
-          "description": "Color styles to indicate varied states",
+          "description": "Badge variant (color).\n\nPreferred values: `purple`, `green`, `yellow`, `orange`, `gray`, `red`, `blue`.\n\nThe legacy semantic names `success`, `warning`, `inactive`, and `error` are still\naccepted and map to `green`, `yellow`, `gray`, and `red` respectively. Prefer the\ncolor names for new code.",
           "values": [
+            {
+              "name": "blue"
+            },
             {
               "name": "error"
             },
+            {
+              "name": "gray"
+            },
+            {
+              "name": "green"
+            },
             {
               "name": "inactive"
             },
+            {
+              "name": "orange"
+            },
+            {
+              "name": "purple"
+            },
+            {
+              "name": "red"
+            },
             {
               "name": "success"
             },
+            {
+              "name": "warning"
+            },
+            {
+              "name": "yellow"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "xpl-banner",
+      "description": {
+        "kind": "markdown",
+        "value": "Banners display a system level or page level message at the top of the screen. The section-banner variant displays important messages inline within a section."
+      },
+      "attributes": [
+        {
+          "name": "action-text",
+          "description": "Primary action label. When provided, an action button is rendered."
+        },
+        {
+          "name": "appearance",
+          "description": "Controls the visual appearance and semantic meaning of the banner.\nThese values map to messaging background/border token sets in `banner.css`.\nBanner icons use `--xpl-icon-default`, except `error` which uses inverse icon/text\ntokens for contrast on dark backgrounds.",
+          "values": [
+            {
+              "name": "error"
+            },
+            {
+              "name": "information"
+            },
+            {
+              "name": "positive"
+            },
             {
               "name": "warning"
             }
           ]
+        },
+        {
+          "name": "description",
+          "description": "Optional supporting message shown after the heading.\nDescription text uses `--xpl-text-default`."
+        },
+        {
+          "name": "has-icon",
+          "description": "Whether to render the leading icon in section layout.\nIgnored in bar layout — bar banners always show the icon."
+        },
+        {
+          "name": "heading",
+          "description": "Primary banner message shown with stronger title typography."
+        },
+        {
+          "name": "is-dismissible",
+          "description": "Whether to show the trailing dismiss control."
+        },
+        {
+          "name": "is-section",
+          "description": "Renders the section-style banner layout when true."
+        },
+        {
+          "name": "secondary-action-text",
+          "description": "Secondary action label. When provided, a second action button is rendered."
+        },
+        {
+          "name": "truncate-desc",
+          "description": "When true, `description` is constrained to one line with ellipsis so banner height stays stable."
         }
       ]
     },
@@ -222,24 +378,44 @@
       "name": "xpl-button",
       "description": {
         "kind": "markdown",
-        "value": "Buttons allow users to take an action.  Three sizes and three sentiments are available with leading and trailing icons. Hide an icon and the label for an icon-only button."
+        "value": "Buttons allow users to take an action with clear visual hierarchy (variant), semantic meaning (sentiment), and size."
       },
       "attributes": [
         {
           "name": "disabled",
-          "description": "whether button should be disabled"
+          "description": "Whether button should be disabled"
         },
         {
           "name": "form",
-          "description": ""
+          "description": "An optional form attribute for the button if type is submit"
         },
         {
           "name": "full-width",
-          "description": "whether button should render with full width"
+          "description": "Whether the button should be of full width as per parent container."
+        },
+        {
+          "name": "icon",
+          "description": "Icon to render - icon name as string (from xpl-icon library)."
         },
         {
           "name": "icon-only",
-          "description": "whether button should render icon only"
+          "description": "When true, the button renders in icon-only circular style. Use for icon-only buttons."
+        },
+        {
+          "name": "icon-position",
+          "description": "Icon position relative to slot content. Ignored if no icon is provided.",
+          "values": [
+            {
+              "name": "end"
+            },
+            {
+              "name": "start"
+            }
+          ]
+        },
+        {
+          "name": "is-loading",
+          "description": "When true, shows a loading overlay with spinner over the button. Button is non-interactive."
         },
         {
           "name": "link",
@@ -247,11 +423,26 @@
         },
         {
           "name": "name",
-          "description": ""
+          "description": "Name of the button, submitted with form data. Passed through to the native button element."
+        },
+        {
+          "name": "sentiment",
+          "description": "Sentiment of the button, which applies different color schemes to indicate purpose/intent.",
+          "values": [
+            {
+              "name": "negative"
+            },
+            {
+              "name": "neutral"
+            },
+            {
+              "name": "positive"
+            }
+          ]
         },
         {
           "name": "size",
-          "description": "",
+          "description": "Button size. Use 'default', 'xs' (extra small), or 'sm' (small).",
           "values": [
             {
               "name": "default"
@@ -281,7 +472,7 @@
         },
         {
           "name": "type",
-          "description": "",
+          "description": "HTML button type attribute.",
           "values": [
             {
               "name": "button"
@@ -296,11 +487,11 @@
         },
         {
           "name": "value",
-          "description": ""
+          "description": "Value of the button, submitted with form data. Passed through to the native button element."
         },
         {
           "name": "variant",
-          "description": "",
+          "description": "Button variant/style. Use \"primary\", \"secondary\", \"tertiary\" for new usage. \"subtle\" is deprecated but still supported for backward compatibility.",
           "values": [
             {
               "name": "primary"
@@ -310,6 +501,9 @@
             },
             {
               "name": "subtle"
+            },
+            {
+              "name": "tertiary"
             }
           ]
         }
@@ -355,7 +549,7 @@
       "name": "xpl-calendar",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "Calendars allow users to view and select dates.  Use XPL-Calendar when date picking is needed on a page or in a in a container.\nIf a calendar is needed within a form, use [XPL-Datepicker](https://apollo.xplordocs.com/?path=/story/components-input--datepicker)."
       },
       "attributes": [
         {
@@ -396,9 +590,13 @@
       "name": "xpl-checkbox",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "Checkboxes allow users to make selections or choices. Checkboxes can be multi-select, and also act as controls.\r\n\r\nProvide visible label text in the default slot, or set `aria-label` when the checkbox has no adjacent label (for example, icon-only toolbars or table selection cells)."
       },
       "attributes": [
+        {
+          "name": "aria-label",
+          "description": "Accessible name for the native checkbox input (sets `aria-label` on the `input`).\nUse when there is no visible label text in the default slot.\nDefaults to `''`; empty or whitespace-only values omit `aria-label` on the input so a visible `<label>` remains the sole name source."
+        },
         {
           "name": "checked",
           "description": "Whether the input is checked"
@@ -441,7 +639,7 @@
       "name": "xpl-choicelist",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "A Choice List allows users to make single or multiple selections from a list of choices.  This component is meant to consume the radio and checkbox components, either styled or unstyled, then allow for customizing an option list very quickly."
       },
       "attributes": [
         {
@@ -502,7 +700,7 @@
       "name": "xpl-data-card",
       "description": {
         "kind": "markdown",
-        "value": "The `icon` and `smallStatIcon` properties accept icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.\n\n---"
+        "value": "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."
       },
       "attributes": [
         {
@@ -582,7 +780,7 @@
       "name": "xpl-divider",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "Allows for easy separation and titling of sections within forms or other content."
       },
       "attributes": [
         {
@@ -595,7 +793,7 @@
       "name": "xpl-dropdown",
       "description": {
         "kind": "markdown",
-        "value": "A Dropdown is a menu with a list of actions a user can take. Use a dropdown when you want to present a list of actions in a limited space. Dropdowns are single-select ***actions***, can be presented in groups, and can be triggered by other elements such as a button, icon, text etc. \nA selection within a dropdown does not change the parent trigger.\n\n***If you want to present a list of **options** a user can select, or multi-select options, please use [XPL-Select](https://xplor-apollo.herokuapp.com/?path=/story/components-select--select).***"
+        "value": "A Dropdown is a menu with a list of actions a user can take. Use a dropdown when you want to present a list of actions in a limited space. Dropdowns are single-select ***actions***, can be presented in groups, and can be triggered by other elements such as a button, icon, text etc. \nA selection within a dropdown does not change the parent trigger.\n\n***If you want to present a list of **options** a user can select, or multi-select options, please use [XPL-Select](https://apollo.xplordocs.com/?path=/story/components-select--select).***"
       },
       "attributes": [
         {
@@ -669,6 +867,10 @@
         "value": ""
       },
       "attributes": [
+        {
+          "name": "icon",
+          "description": "optional icon name to display before the label (uses xpl-icon)"
+        },
         {
           "name": "disabled",
           "description": "whether option is disabled"
@@ -695,7 +897,7 @@
       "name": "xpl-dynamic-table",
       "description": {
         "kind": "markdown",
-        "value": "> **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."
+        "value": "> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases.\r\n\r\nThe Dynamic Table is a rich content table that can accommodate multiple types of data."
       },
       "attributes": []
     },
@@ -816,7 +1018,7 @@
       "name": "xpl-input",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "A flexible form input that supports multiple `type` values: `text`, `number`, `password`, `date`, `time`, `file`, `color`, `phone`, and `search`. Each type delegates to a dedicated sub-component (`xpl-input-date`, `xpl-input-time`, `xpl-input-phone`, `xpl-input-search`, etc.) while sharing a common label, description, and error-message wrapper.\n\nFor `type=\"phone\"`, the value is always emitted in **E.164** format (e.g. `+14155551234`). See [`xpl-input-phone`](xpl-input-phone) for full phone-input documentation."
       },
       "attributes": [
         {
@@ -831,14 +1033,22 @@
           "name": "allow-custom-option",
           "description": "For time inputs, whether to allow custom option in the input even if not available in the dropdown.\nExample: A step of 30 minutes will allow 15:03, 15:37, etc.\n\nApplies to time inputs."
         },
+        {
+          "name": "aria-label",
+          "description": "Accessible name for search inputs when there is no visible `label` (after trim).\nIgnored for naming when a visible label is shown.\nDefaults to `''`; whitespace-only values are treated as missing and fall back to `'Search'` so the field is never unnamed when there is no visible label.\n\nApplies to search inputs (`type=\"search\"`)."
+        },
         {
           "name": "autocomplete",
-          "description": "Hint for form autofill feature\n\nApplies to text, password, number."
+          "description": "Hint for form autofill feature\n\nApplies to text, password, number, and search inputs."
         },
         {
           "name": "date-format",
           "description": "The date format to use for the datepicker input.\nThis is used by flatpickr to format the date.\nDefault is 'Y-m-d' (e.g., 2023-10-01).\n\nSee https://flatpickr.js.org/formatting/ for more details.\n\nApplies to date inputs."
         },
+        {
+          "name": "default-country",
+          "description": "Default country code (ISO 3166-1 alpha-2) when value is empty, e.g. \"US\".\n\nApplies to phone inputs."
+        },
         {
           "name": "description",
           "description": "Optional text that appears below the input label.\n\nApplies to all input types."
@@ -867,6 +1077,10 @@
           "name": "hide-trigger-on-select",
           "description": "Hides the trigger element when a file is selected.\nThis is useful for cases where you want to hide the trigger after a file is selected.\n\nApplies to file inputs."
         },
+        {
+          "name": "is-international",
+          "description": "Enables international mode with country selector for phone inputs.\nWhen false, the phone input is locked to defaultCountry with no country picker."
+        },
         {
           "name": "label",
           "description": "Label text for the field\n\nApplies to all input types."
@@ -909,7 +1123,7 @@
         },
         {
           "name": "placeholder",
-          "description": "Placeholder text that appears when the field has no value\n\nApplies to text, password, number, and date inputs."
+          "description": "Placeholder text that appears when the field has no value\n\nApplies to text, password, number, date, and search inputs."
         },
         {
           "name": "post",
@@ -921,12 +1135,24 @@
         },
         {
           "name": "readonly",
-          "description": "Whether the input is editable\n\nApplies to text, password, number, and date inputs."
+          "description": "Whether the input is editable\n\nApplies to text, password, number, date, and search inputs."
         },
         {
           "name": "required",
           "description": "Whether the input is required\n\nApplies to all input types."
         },
+        {
+          "name": "shape",
+          "description": "Shell corner radius for search inputs: `rounded` (pill) or `box` (rounded rectangle).\n\nApplies to search inputs (`type=\"search\"`).",
+          "values": [
+            {
+              "name": "box"
+            },
+            {
+              "name": "rounded"
+            }
+          ]
+        },
         {
           "name": "step",
           "description": "The granularity that the value in a `number` input must adhere to when\nincrementing or decrementing. The default stepping value for number\ninputs is 1\n\nApplies to number and time inputs."
@@ -962,6 +1188,12 @@
             {
               "name": "password"
             },
+            {
+              "name": "phone"
+            },
+            {
+              "name": "search"
+            },
             {
               "name": "text"
             },
@@ -972,7 +1204,7 @@
         },
         {
           "name": "value",
-          "description": "Including a `value` will pre-populate the input\nwith the given string.\n\nApplies to text, password, number, and date inputs."
+          "description": "Including a `value` will pre-populate the input\nwith the given string.\n\nApplies to text, password, number, date, and search inputs."
         }
       ]
     },
@@ -1116,15 +1348,15 @@
       ]
     },
     {
-      "name": "xpl-input-time",
+      "name": "xpl-input-phone",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "The Phone Input Field allows users to input properly formatted phone numbers. It supports two modes: **international** (country selector + dial code prefix) and **domestic** (single country, no selector). Used as a subcomponent of `xpl-input` when `type=\"phone\"`. The value is always emitted in **E.164** format (e.g. `+14155551234`)."
       },
       "attributes": [
         {
-          "name": "allow-custom-option",
-          "description": "For time inputs, whether to allow custom option in the input even if not available in the dropdown.\nExample: A step of 30 minutes will allow 15:03, 15:37, etc.\n\nApplies to time inputs."
+          "name": "default-country",
+          "description": "Default country code (ISO 3166-1 alpha-2) when value is empty, e.g. \"US\"."
         },
         {
           "name": "disabled",
@@ -1135,32 +1367,16 @@
           "description": "The `inputId` is used to associate the input with a label."
         },
         {
-          "name": "max",
-          "description": "Maximum value for the input."
-        },
-        {
-          "name": "min",
-          "description": "The minimum value for the input."
-        },
-        {
-          "name": "mode",
-          "description": "Whether the input is a single time or a range of times.\n\nCurrently, only single time is supported.",
-          "values": [
-            {
-              "name": "range"
-            },
-            {
-              "name": "single"
-            }
-          ]
+          "name": "is-international",
+          "description": "Enables international mode with a country selector and dial code prefix.\nWhen false, the input is locked to `defaultCountry` with no country picker\nand no dial code shown in the display value. Emitted value is still E.164."
         },
         {
           "name": "name",
-          "description": "Most inputs are used in forms, and should have a\n`name` associated with the input for handling form data.\n\nApplies to all input types."
+          "description": "Most inputs are used in forms, and should have a\n`name` associated with the input for handling form data."
         },
         {
           "name": "placeholder",
-          "description": "Placeholder text that appears when the field has no value\n\nApplies to text, password, number, and date inputs."
+          "description": "Placeholder text that appears when the field has no value"
         },
         {
           "name": "readonly",
@@ -1171,40 +1387,170 @@
           "description": "Whether the input is required"
         },
         {
-          "name": "step",
-          "description": "Time increment for dropdown options"
+          "name": "value",
+          "description": "Including a `value` will pre-populate the input (E.164 format, e.g. +14155551234)."
+        }
+      ]
+    },
+    {
+      "name": "xpl-input-search",
+      "description": {
+        "kind": "markdown",
+        "value": "Inner search field used by [`xpl-input`](../readme.md) when `type=\"search\"`. It provides a leading magnifier, a native text field with `role=\"searchbox\"`, an optional clear control, and a `shape` shell (`rounded` pill vs `box`). You normally consume search through **`xpl-input`**; use `xpl-input-search` only when composing a custom shell that still matches Apollo search visuals."
+      },
+      "attributes": [
+        {
+          "name": "aria-label",
+          "description": "Accessible name when there is no visible label from the parent; maps to `aria-label` on the input.\nWhen the parent provides a visible label, the input is named by `<label for=\"…\">` — this prop is ignored for naming.\nEmpty or whitespace-only values are treated as missing and fall back to `'Search'` so the field is never unnamed."
         },
         {
-          "name": "time-format",
-          "description": "The time format to display for the input.",
+          "name": "autocomplete",
+          "description": "Passed to the native input (`autocomplete` attribute). Default `off` matches common\ninline-search UX; browsers may still apply heuristics."
+        },
+        {
+          "name": "disabled",
+          "description": "Disables the field and clear control."
+        },
+        {
+          "name": "error-message-id",
+          "description": "Element id for `aria-describedby` when `hasError` (error message lives on `xpl-input`)."
+        },
+        {
+          "name": "has-error",
+          "description": "Set by `xpl-input` when `error` is shown — drives `aria-invalid` / `aria-describedby`."
+        },
+        {
+          "name": "has-visible-label",
+          "description": "When true, parent `xpl-input` renders a visible label — omit `aria-label` on the input."
+        },
+        {
+          "name": "input-id",
+          "description": "Associates the control with the parent `xpl-input` label (`for` / `id`)."
+        },
+        {
+          "name": "name",
+          "description": "Form field `name` on the native input."
+        },
+        {
+          "name": "placeholder",
+          "description": "Placeholder shown when the value is empty."
+        },
+        {
+          "name": "readonly",
+          "description": "Whether the input is editable."
+        },
+        {
+          "name": "required",
+          "description": "Whether the input is required."
+        },
+        {
+          "name": "shape",
+          "description": "Shell corner radius: `rounded` (pill) or `box` (rounded rectangle).",
           "values": [
             {
-              "name": "12h"
+              "name": "box"
             },
             {
-              "name": "24h"
+              "name": "rounded"
             }
           ]
         },
         {
           "name": "value",
-          "description": "Including a `value` will pre-populate the input\nwith the given string.\n\nMust be in 24 hour format, ex: 15:25 for 3:25 PM"
+          "description": "Current value (controlled-friendly)."
         }
       ]
     },
     {
-      "name": "xpl-large-card",
+      "name": "xpl-input-time",
       "description": {
         "kind": "markdown",
         "value": ""
       },
       "attributes": [
         {
-          "name": "description",
-          "description": "Description of the Card"
+          "name": "allow-custom-option",
+          "description": "For time inputs, whether to allow custom option in the input even if not available in the dropdown.\nExample: A step of 30 minutes will allow 15:03, 15:37, etc.\n\nApplies to time inputs."
         },
         {
-          "name": "link",
+          "name": "disabled",
+          "description": "Whether the field is disabled"
+        },
+        {
+          "name": "input-id",
+          "description": "The `inputId` is used to associate the input with a label."
+        },
+        {
+          "name": "max",
+          "description": "Maximum value for the input."
+        },
+        {
+          "name": "min",
+          "description": "The minimum value for the input."
+        },
+        {
+          "name": "mode",
+          "description": "Whether the input is a single time or a range of times.\n\nCurrently, only single time is supported.",
+          "values": [
+            {
+              "name": "range"
+            },
+            {
+              "name": "single"
+            }
+          ]
+        },
+        {
+          "name": "name",
+          "description": "Most inputs are used in forms, and should have a\n`name` associated with the input for handling form data.\n\nApplies to all input types."
+        },
+        {
+          "name": "placeholder",
+          "description": "Placeholder text that appears when the field has no value\n\nApplies to text, password, number, and date inputs."
+        },
+        {
+          "name": "readonly",
+          "description": "Whether the input is editable"
+        },
+        {
+          "name": "required",
+          "description": "Whether the input is required"
+        },
+        {
+          "name": "step",
+          "description": "Time increment for dropdown options"
+        },
+        {
+          "name": "time-format",
+          "description": "The time format to display for the input.",
+          "values": [
+            {
+              "name": "12h"
+            },
+            {
+              "name": "24h"
+            }
+          ]
+        },
+        {
+          "name": "value",
+          "description": "Including a `value` will pre-populate the input\nwith the given string.\n\nMust be in 24 hour format, ex: 15:25 for 3:25 PM"
+        }
+      ]
+    },
+    {
+      "name": "xpl-large-card",
+      "description": {
+        "kind": "markdown",
+        "value": "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."
+      },
+      "attributes": [
+        {
+          "name": "description",
+          "description": "Description of the Card"
+        },
+        {
+          "name": "link",
           "description": "Whether the card is a link or not"
         },
         {
@@ -1217,9 +1563,118 @@
       "name": "xpl-list",
       "description": {
         "kind": "markdown",
-        "value": "A list item is a card with interactive states. List items allow users to select items from a list of items and view more information or make edits."
+        "value": ""
       },
-      "attributes": []
+      "attributes": [
+        {
+          "name": "label",
+          "description": "Accessible name for the list, exposed as `aria-label` on the host when set.\nUse when the list has no visible heading.\nIgnored when `labelledBy` is set (see `labelledBy` for precedence)."
+        },
+        {
+          "name": "labelled-by",
+          "description": "Element id(s) that label this list (space-separated), exposed as `aria-labelledby` when set.\nWhen set, `label` is not applied as `aria-label` so the list has a single naming source."
+        },
+        {
+          "name": "reorderable",
+          "description": "When true, enables reorder UI and behavior for **slot-based** child rows (drag handle + keyboard).\nLegacy rows rendered from the deprecated `items` prop do **not** show a drag handle; migrate to slots if reorder is required."
+        },
+        {
+          "name": "selectable",
+          "description": "Determines if this list is selectable (shows `xpl-radio` per row in a shared group).\nPress Escape while focus is on the **selected** row to clear selection (same as `clearSelection()`)."
+        }
+      ]
+    },
+    {
+      "name": "xpl-list-item",
+      "description": {
+        "kind": "markdown",
+        "value": "Single row for [`xpl-list`](../xpl-list/readme.md). **Slot-based** rows expose `role=\"listitem\"` on the inner row surface (`.xpl-list-item__wrapper` or `.xpl-list-item__listitem-shell` when `href` is set); **legacy** `item` rows use `role=\"listitem\"` on the host. Hand-written integration notes for slots, attributes, and events live in the [list readme](../xpl-list/readme.md); the section below is Stencil-generated API for this component.\n\n**Reorder handle (slot mode):** When `reorderable` is enabled and the row uses **slot-based** content, the handle is an **`xpl-button`** wrapping a native **`<button>`**. Reorder logic is wired on the **`xpl-button` host** (`mousedown` / `keydown`); those events originate on the inner `<button>` and **bubble** to the host, which is how the list item receives them today. If `xpl-button` ever stopped bubbling for those events, reorder handlers would need to attach directly to the inner button (similar to `componentDidRender` syncing `aria-*` on that element).\n\n**Legacy `item` prop:** Prop-driven rows **do not** render the reorder handle, radios, or keyboard reorder affordances. Parent `xpl-list` **does not** set `selectable`, `radio-name`, or `reorderable` on those rows (those attributes are removed so they are not mistaken for supported behavior). Use slots if you need selection, drag, or keyboard reorder."
+      },
+      "attributes": [
+        {
+          "name": "disabled",
+          "description": "Whether the item is disabled."
+        },
+        {
+          "name": "error",
+          "description": "Whether to show the item in an error state."
+        },
+        {
+          "name": "hidden",
+          "description": "When true, the row is not shown and does not participate in visible-only list behavior\n(e.g. `orderChange` / `orderedItemIds`, reorder targets). Use for filtering, conditional\ndisplay, or keeping stable `item-id` while the row is off-screen. See `xpl-list` readme\n“Hidden rows”.\n\n**Accessibility:** Renders an empty host with the native `hidden` attribute only (no\n`role=\"listitem\"`), consistent with the row not participating as a list item while hidden."
+        },
+        {
+          "name": "href",
+          "description": "URL for link behavior. When provided, the entire row becomes clickable.\nClicks on `actions` or `avatar` slots are prevented from triggering navigation."
+        },
+        {
+          "name": "item-id",
+          "description": "Unique identifier for this item. Used for selection and drag/drop.\nMutable so the host can sync from `item-id` / `id` in `componentWillLoad` without breaking one-way data flow."
+        },
+        {
+          "name": "keyboard-active",
+          "description": "When set by the parent, indicates this item is the active keyboard reorder item."
+        },
+        {
+          "name": "radio-name",
+          "description": "Name attribute for radio inputs (shared across selectable items in a list)."
+        },
+        {
+          "name": "reorderable",
+          "description": "Whether this item is reorderable (shows a drag handle in **slot-based** layout).\nWhen the deprecated `item` prop is used, legacy markup has **no** reorder handle even if this is true."
+        },
+        {
+          "name": "selectable",
+          "description": "Whether this item is selectable (shows `xpl-radio` in a shared group)."
+        },
+        {
+          "name": "selected",
+          "description": "Whether this item is selected (radio checked state)."
+        },
+        {
+          "name": "show-divider",
+          "description": "Whether to show a divider below the item."
+        },
+        {
+          "name": "title-badge-variant",
+          "description": "Optional badge to display next to the title (dot badge).\nOnly used when `item` prop is not provided (slot mode).\nMatches `xpl-badge` variant values (e.g. purple, green, red).",
+          "values": [
+            {
+              "name": "blue"
+            },
+            {
+              "name": "error"
+            },
+            {
+              "name": "gray"
+            },
+            {
+              "name": "green"
+            },
+            {
+              "name": "inactive"
+            },
+            {
+              "name": "orange"
+            },
+            {
+              "name": "purple"
+            },
+            {
+              "name": "red"
+            },
+            {
+              "name": "success"
+            },
+            {
+              "name": "warning"
+            },
+            {
+              "name": "yellow"
+            }
+          ]
+        }
+      ]
     },
     {
       "name": "xpl-main-nav",
@@ -1249,7 +1704,7 @@
       "name": "xpl-modal",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "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."
       },
       "attributes": [
         {
@@ -1285,6 +1740,23 @@
         }
       ]
     },
+    {
+      "name": "xpl-nav-header-menu",
+      "description": {
+        "kind": "markdown",
+        "value": "Profile / account block (username, email, default slot for **`xpl-top-nav-item`** / **`xpl-divider`**).\nTag **`xpl-nav-header-menu`**; implementation folder **`xpl-nav-header-menu`**. **`.xpl-nav-header-menu__slot`** is\n**`role=\"list\"`** for slotted **`xpl-top-nav-item`** (**`role=\"listitem\"`**).\n\n**Slotted content:** do not add **`xpl-nav-header-menu__*`** BEM classes on nodes you pass into the default slot —\nprofile, list shell, and **`xpl-top-nav-item`** **`role=\"listitem\"`** are handled by the component. Use\n**`xpl-top-nav-item`** (or plain elements that are not Apollo **`xpl-*`** BEM hooks) in the slot only.\n\n**`slot=\"right-aside-mobile\"`** — optional block **between** the profile header and the default-slot list (e.g. narrow-only\nduplicate of **every** **`slot=\"right-aside\"`** control per Figma when **`xpl-top-nav`** hides **`right-aside`** on narrow viewports (always)).\nNot **`role=\"list\"`**; use **`xpl-button`** / **`xpl-top-nav-item`** as needed. Shown only on **narrow viewports** (one pixel below Tailwind **`md`** — **`top-nav.css`**) so bar actions stay in **`slot=\"right-aside\"`** on wider viewports.\nLight-DOM **`slotchange`** is unreliable; a host **`MutationObserver`** (child / subtree / **`slot`** attribute) keeps\n**`xpl-nav-header-menu--has-right-aside-mobile`** in sync when nodes are added or retargeted after mount (same pattern as **`xpl-top-nav`**).\nStencil **`newSpecPage`** / mock-doc does not define **`MutationObserver`**; slot presence still updates on the next\ndeferred flush (**`setTimeout(0)`** coalesced with **`componentDidRender`**). In real browsers the observer handles child /\n**`slot`** mutations without stacking uncancellable microtasks.\n\n**Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens resolve to dark-mode\nvalues even when the page root is light (same contract as **`xpl-top-nav`** / **`xpl-top-nav-item`**)."
+      },
+      "attributes": [
+        {
+          "name": "email",
+          "description": "Email address shown below the username."
+        },
+        {
+          "name": "username",
+          "description": "Display name shown in the profile block."
+        }
+      ]
+    },
     {
       "name": "xpl-nav-item",
       "description": {
@@ -1302,7 +1774,7 @@
       "name": "xpl-pagination",
       "description": {
         "kind": "markdown",
-        "value": "> **Note:** This component is in beta. Use with caution and expect updates before the full release."
+        "value": "Pagination bar allows users to navigate pages of content.\n\n> **Note:** This component is in beta. Use with caution and expect updates before the full release."
       },
       "attributes": [
         {
@@ -1327,11 +1799,59 @@
         }
       ]
     },
+    {
+      "name": "xpl-panel",
+      "description": {
+        "kind": "markdown",
+        "value": "A stateless container that defines a section on a page and can house any\ntype of content. Panels are not dismissible and may contain a top accent."
+      },
+      "attributes": [
+        {
+          "name": "accent",
+          "description": "Color accent bar displayed at the top of the panel.\n\n- `none` – no accent (default)\n- `primary` – brand primary color\n- `secondary` – brand secondary color\n- `positive` – positive / success color\n- `negative` – negative / error color\n- `highlight` – highlight / warning color",
+          "values": [
+            {
+              "name": "highlight"
+            },
+            {
+              "name": "negative"
+            },
+            {
+              "name": "none"
+            },
+            {
+              "name": "positive"
+            },
+            {
+              "name": "primary"
+            },
+            {
+              "name": "secondary"
+            }
+          ]
+        },
+        {
+          "name": "padding",
+          "description": "Padding density applied to the content area.\n(default and tight keep desktop padding through tablet; mobile ≤480px).\n\n- `default` – 24 px desktop & tablet / 16 px mobile\n- `tight`   – 16 px desktop & tablet / 8 px mobile\n- `loose`   – 40 px desktop / 32 px tablet / 24 px mobile",
+          "values": [
+            {
+              "name": "default"
+            },
+            {
+              "name": "loose"
+            },
+            {
+              "name": "tight"
+            }
+          ]
+        }
+      ]
+    },
     {
       "name": "xpl-popover",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "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."
       },
       "attributes": [
         {
@@ -1399,15 +1919,90 @@
       ]
     },
     {
-      "name": "xpl-progress",
+      "name": "xpl-progress-bar",
+      "description": {
+        "kind": "markdown",
+        "value": "The `xpl-progress-bar` component displays the progress of an operation, such as file uploads, form completion, or loading states. It supports multiple visual variants including default, success, error, and indeterminate states, with optional label and helper text."
+      },
+      "attributes": [
+        {
+          "name": "helper-text",
+          "description": "The helper text displayed below the progress bar (recommended for error state)"
+        },
+        {
+          "name": "label",
+          "description": "The label text displayed above the progress bar"
+        },
+        {
+          "name": "max",
+          "description": "The maximum value of the progress (mirrors native <progress> max attribute)"
+        },
+        {
+          "name": "size",
+          "description": "The size of the progress bar height: sm = 4px, lg = 6px",
+          "values": [
+            {
+              "name": "lg"
+            },
+            {
+              "name": "sm"
+            }
+          ]
+        },
+        {
+          "name": "value",
+          "description": "The current value of the progress (mirrors native <progress> value attribute)"
+        },
+        {
+          "name": "variant",
+          "description": "The visual variant of the progress bar",
+          "values": [
+            {
+              "name": "default"
+            },
+            {
+              "name": "error"
+            },
+            {
+              "name": "indeterminate"
+            },
+            {
+              "name": "success"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "xpl-progress-indicator",
       "description": {
         "kind": "markdown",
-        "value": "A progress indicator guides users through any linear, multi-step task by showing the user their completed, current, and future steps.\n\nProgress indicators help manage a user’s expectations when completing a multistep process. They show which step the user is currently on, the total number of steps, and overall progress in completing a task.\n\nHorizontal Progress Indicator is used in most desktop applications where a stepped process is required to finish a task and it is beneficial to the user to see their progress. This creates confidence in the user and sets expectations for the length and complexity of the process."
+        "value": "A progress indicator that guides users through linear, multi-step tasks by displaying completed, current, and future steps. Progress indicators help manage user expectations by showing their position in a multi-step process, the total number of steps, and overall progress toward task completion."
       },
       "attributes": [
         {
           "name": "current-step",
-          "description": "Current step, is the index of the current active step"
+          "description": "Current step index. Steps with index < currentStep are \"finished\",\nthe step at currentStep is \"active\", and steps beyond are \"waiting\".\nSet to steps.length to mark all steps as finished.\nAutomatically clamped to [0, steps.length]."
+        },
+        {
+          "name": "layout",
+          "description": "Layout direction - 'horizontal' or 'vertical'",
+          "values": [
+            {
+              "name": "horizontal"
+            },
+            {
+              "name": "vertical"
+            }
+          ]
+        },
+        {
+          "name": "show-labels",
+          "description": "Whether to show step labels"
+        },
+        {
+          "name": "show-numbers",
+          "description": "Whether to show step numbers inside circles"
         }
       ]
     },
@@ -1460,7 +2055,7 @@
       "name": "xpl-select",
       "description": {
         "kind": "markdown",
-        "value": "Select allows users to make a single selection or multiple selections from a list of options.  Items can be a simple list, grouped, simple multi-select. User selections typically appear within the Select Box once created unless multiple selections are made, where truncation or another method of showing these selections is required.\n\n***When the list of options contains “Actions”, use a ***[Dropdown component](https://xplor-apollo.herokuapp.com/?path=/story/components-dropdown--simple). \n\nThe `selectIcon` property accepts icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.\n\n---"
+        "value": "Select allows users to make a single selection or multiple selections from a list of options.  Items can be a simple list, grouped, simple multi-select. User selections typically appear within the Select Box once created unless multiple selections are made, where truncation or another method of showing these selections is required.\n\n***When the list of options contains “Actions”, use a ***[Dropdown component](https://apollo.xplordocs.com/?path=/story/components-dropdown--simple).\n\nThe `selectIcon` property accepts icon names as strings. See [xpl-icon available icons](../xpl-icon/ICONS.md) for the complete list.\n\n---"
       },
       "attributes": [
         {
@@ -1521,6 +2116,60 @@
         }
       ]
     },
+    {
+      "name": "xpl-side-nav",
+      "description": {
+        "kind": "markdown",
+        "value": "Slot-based sidebar for app navigation: scrollable main area and a fixed footer. Compose with [`xpl-side-nav-item`](./xpl-side-nav-item) for rows in the section and footer."
+      },
+      "attributes": [
+        {
+          "name": "label",
+          "description": "Accessible label for the navigation landmark.\nMaps to `aria-label` on the `<nav>` element.\nRecommended when multiple navigation landmarks exist on a page\n(e.g., side nav + top nav + breadcrumbs) to help screen readers distinguish them."
+        }
+      ]
+    },
+    {
+      "name": "xpl-side-nav-item",
+      "description": {
+        "kind": "markdown",
+        "value": "Row for [`xpl-side-nav`](../xpl-side-nav): place items in `slot=\"section\"` or `slot=\"nav-footer\"`. Supports **leaf** (button), **expandable** (`has-children`), and **link** (slot-only) modes, plus `selected`, `disabled`, and `hidden`."
+      },
+      "attributes": [
+        {
+          "name": "disabled",
+          "description": "Whether the component is disabled"
+        },
+        {
+          "name": "expanded",
+          "description": "Whether the item is currently expanded (only applies when hasChildren is true)"
+        },
+        {
+          "name": "has-children",
+          "description": "Whether the item has child items; when true, shows expand/collapse and a default slot for nested items.\nMutually exclusive with <code>link</code>. If <code>link</code> is already true, setting\n<code>has-children</code> is reverted (<code>@Watch('hasChildren')</code>, <code>@Watch('link')</code>,\n<code>componentWillLoad</code>, and <code>componentWillRender</code>) so reflected attributes match CSS."
+        },
+        {
+          "name": "hidden",
+          "description": "Whether the component is hidden"
+        },
+        {
+          "name": "icon",
+          "description": "Optional icon name; default content for <code>slot=\"icon\"</code> (leaf and footer rows only).\nExpandable parents (<code>has-children</code>) do not show an icon column — only the chevron and label.\nOmit for nested children under a <code>has-children</code> parent — the icon column is hidden for sub-items."
+        },
+        {
+          "name": "label",
+          "description": "The display label for the navigation item (button / expandable rows; omit in <code>link</code> mode)."
+        },
+        {
+          "name": "link",
+          "description": "When true, the row becomes a slot-only container for consumer-provided links.\nThe consumer provides the full anchor element (or router link) via the default slot.\nIn link mode, <code>label</code> and <code>icon</code> props should not be used.\nLink mode does not support <code>has-children</code>; use the default button mode for expandable items.\nWhen <code>link</code> is true, <code>hasChildren</code> is always false (enforced by\n<code>@Watch('link')</code>, <code>@Watch('hasChildren')</code>, <code>componentWillLoad</code>, and\n<code>componentWillRender</code>)."
+        },
+        {
+          "name": "selected",
+          "description": "Whether the item is currently in a selected state"
+        }
+      ]
+    },
     {
       "name": "xpl-skeleton",
       "description": {
@@ -1590,51 +2239,165 @@
           ]
         },
         {
-          "name": "width",
-          "description": "The width of the skeleton. (e.g. '100px', '100%', 'auto')\naccepts any valid CSS width value"
+          "name": "width",
+          "description": "The width of the skeleton. (e.g. '100px', '100%', 'auto')\naccepts any valid CSS width value"
+        }
+      ]
+    },
+    {
+      "name": "xpl-slideout",
+      "description": {
+        "kind": "markdown",
+        "value": "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."
+      },
+      "attributes": [
+        {
+          "name": "backdrop",
+          "description": "Whether to show a backdrop behind the slideout."
+        },
+        {
+          "name": "is-open",
+          "description": "Whether the slideout is open."
+        },
+        {
+          "name": "show-footer",
+          "description": "Whether to show the footer section in the slideout."
+        },
+        {
+          "name": "variant",
+          "description": "The visual style variant of the slideout.\nCan be 'default' or 'warning'.",
+          "values": [
+            {
+              "name": "default"
+            },
+            {
+              "name": "warning"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "xpl-spotlight",
+      "description": {
+        "kind": "markdown",
+        "value": "`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."
+      },
+      "attributes": [
+        {
+          "name": "action-layout",
+          "description": "Footer action layout. `default` and `dual` both render the standard Back/Next layout, while\n`single` renders a single acknowledgement CTA (e.g. \"Got it!\").\nOnly applies when `showActions` is `true`.",
+          "values": [
+            {
+              "name": "default"
+            },
+            {
+              "name": "dual"
+            },
+            {
+              "name": "single"
+            }
+          ]
+        },
+        {
+          "name": "anchor-position",
+          "description": "Which corner of the card the anchor dot uses when not using `target`, or as the preferred side for Floating UI.",
+          "values": [
+            {
+              "name": "bottom-left"
+            },
+            {
+              "name": "bottom-right"
+            },
+            {
+              "name": "top-left"
+            },
+            {
+              "name": "top-right"
+            }
+          ]
+        },
+        {
+          "name": "body",
+          "description": "Body copy when the `body` slot has no slotted content. Whitespace-only values are treated as empty (no fallback paragraph)."
+        },
+        {
+          "name": "current-step",
+          "description": "Current step index (1-based). Used with `totalSteps` for the step label and for disabling\ndefault Back/Next when `showSteps` is true."
+        },
+        {
+          "name": "heading",
+          "description": "Heading when the `title` slot has no slotted content. Whitespace-only values are treated as empty (no fallback title span)."
+        },
+        {
+          "name": "is-dismissible",
+          "description": "Whether to show the dismiss (close) control."
+        },
+        {
+          "name": "is-open",
+          "description": "Controls whether the spotlight is rendered. When false, the host remains in the DOM but the spotlight UI is hidden."
+        },
+        {
+          "name": "primary-action-label",
+          "description": "Label used for the default primary action button. Only applies when `showActions` is `true`."
+        },
+        {
+          "name": "secondary-action-label",
+          "description": "Label used for the default secondary action button. Only applies when `showActions` is `true`."
+        },
+        {
+          "name": "show-actions",
+          "description": "Whether to show the actions row (primary / secondary and optional step counter).\nWhen `false`, the spotlight has no action buttons — useful for single-step\ninformational callouts that rely solely on the dismiss control."
+        },
+        {
+          "name": "show-image",
+          "description": "When true, the media region is shown. Slotted `image` content is rendered when present;\notherwise the built-in placeholder UI is shown. When false, the entire media block is hidden."
+        },
+        {
+          "name": "show-steps",
+          "description": "Whether to show the step counter between actions (`currentStep` of `totalSteps`) and whether\ndefault Back/Next use step-based disabled state."
+        },
+        {
+          "name": "target",
+          "description": "CSS selector for the element this spotlight anchors to. When set, placement uses Floating UI\n(`computePosition` with `strategy: 'fixed'`, plus `flip`, `shift`, `offset`) and `autoUpdate`\nfor scroll/resize. The host receives `left` / `top` and the `xpl-spotlight--anchored` class.\nInvalid selectors are ignored; layout falls back to `anchor-position`."
+        },
+        {
+          "name": "total-steps",
+          "description": "Total number of steps (1-based upper bound). Used with `currentStep` for the step label and\nfor disabling default Back/Next when `showSteps` is true."
         }
       ]
     },
     {
-      "name": "xpl-slideout",
+      "name": "xpl-tab",
       "description": {
         "kind": "markdown",
-        "value": "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://xplor-apollo.herokuapp.com/?path=/story/components-backdrop--backdrop) component to overlay content and create focus on the Slide Out Panel content."
+        "value": "`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.\n\nUnderline 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.\n\n**`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."
       },
       "attributes": [
         {
-          "name": "backdrop",
-          "description": "Whether to show a backdrop behind the slideout."
+          "name": "disabled",
+          "description": "Disables this tab (pill or underline)."
         },
         {
-          "name": "is-open",
-          "description": "Whether the slideout is open."
+          "name": "data-group-disabled",
+          "description": "Set when the parent `xpl-tabs` has `disabled` (group-disabled)."
         },
         {
-          "name": "show-footer",
-          "description": "Whether to show the footer section in the slideout."
+          "name": "icon",
+          "description": "Optional icon name for segment-style pills (`type=\"segment\"` on parent `xpl-tabs`). Ignored for default tabs."
         },
         {
-          "name": "variant",
-          "description": "The visual style variant of the slideout.\nCan be 'default' or 'warning'.",
+          "name": "icon-position",
+          "description": "Icon position for segment-style pills.",
           "values": [
             {
-              "name": "default"
+              "name": "end"
             },
             {
-              "name": "warning"
+              "name": "start"
             }
           ]
-        }
-      ]
-    },
-    {
-      "name": "xpl-tab",
-      "description": {
-        "kind": "markdown",
-        "value": ""
-      },
-      "attributes": [
+        },
         {
           "name": "selected",
           "description": "Whether the tab is selected"
@@ -1649,7 +2412,7 @@
       "name": "xpl-tab-panel",
       "description": {
         "kind": "markdown",
-        "value": ""
+        "value": "`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."
       },
       "attributes": [
         {
@@ -1666,24 +2429,120 @@
       "name": "xpl-table",
       "description": {
         "kind": "markdown",
-        "value": "Tables are used to organize and display information from a data set."
+        "value": "Compositional tables use CSS grid on the host (`role=\"grid\"`). Legacy mode uses a `<table>`."
       },
       "attributes": [
         {
           "name": "freeze",
-          "description": "When true, the first column of the table is sticky and will cover the leftmost rows in a horizontally scrollable container."
+          "description": "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`."
         },
         {
           "name": "is-sortable",
-          "description": "Toggles to show the sort button on each table head"
+          "description": ""
+        },
+        {
+          "name": "label",
+          "description": "Accessible label for the table. Maps to `aria-label` in compositional mode."
         },
         {
           "name": "multiselect",
-          "description": "Toggles a selectable checkbox for each row in the table"
+          "description": ""
+        },
+        {
+          "name": "reorder-handle-icon",
+          "description": "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`."
+        },
+        {
+          "name": "reorder-handle-icon-keyboard",
+          "description": "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)."
+        },
+        {
+          "name": "row-reorderable",
+          "description": "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."
+        },
+        {
+          "name": "selectable",
+          "description": "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."
         },
         {
           "name": "striped",
-          "description": "Toggles an optional styling of the background of each even row of the table body."
+          "description": "Toggles an optional styling of the background of each even row of the\ntable body."
+        }
+      ]
+    },
+    {
+      "name": "xpl-table-body",
+      "description": {
+        "kind": "markdown",
+        "value": ""
+      },
+      "attributes": []
+    },
+    {
+      "name": "xpl-table-cell",
+      "description": {
+        "kind": "markdown",
+        "value": "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."
+      },
+      "attributes": [
+        {
+          "name": "align",
+          "description": "Horizontal text alignment within the cell.",
+          "values": [
+            {
+              "name": "center"
+            },
+            {
+              "name": "left"
+            },
+            {
+              "name": "right"
+            }
+          ]
+        },
+        {
+          "name": "bold",
+          "description": "Renders cell text in bold (--xpl-font-weight-semibold)."
+        },
+        {
+          "name": "disabled",
+          "description": "Whether the cell and its interactive children are disabled. Set automatically by xpl-table-row."
+        },
+        {
+          "name": "underline",
+          "description": "Adds an underline to cell text."
+        }
+      ]
+    },
+    {
+      "name": "xpl-table-footer",
+      "description": {
+        "kind": "markdown",
+        "value": ""
+      },
+      "attributes": []
+    },
+    {
+      "name": "xpl-table-footer-cell",
+      "description": {
+        "kind": "markdown",
+        "value": ""
+      },
+      "attributes": [
+        {
+          "name": "align",
+          "description": "Horizontal text alignment within the cell.",
+          "values": [
+            {
+              "name": "center"
+            },
+            {
+              "name": "left"
+            },
+            {
+              "name": "right"
+            }
+          ]
         }
       ]
     },
@@ -1691,7 +2550,7 @@
       "name": "xpl-table-header",
       "description": {
         "kind": "markdown",
-        "value": "Component parts used to assemble the Dynamic Table.\n\n> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases."
+        "value": "Semantic wrapper for the header **row group** in a compositional `xpl-table` (`role=\"rowgroup\"`). Place one `xpl-table-row` (with `xpl-table-header-cell` children) inside.\r\n\r\n> **Note:** This component is currently in beta. Use with caution as it may have breaking changes in future releases."
       },
       "attributes": []
     },
@@ -1699,28 +2558,78 @@
       "name": "xpl-table-header-cell",
       "description": {
         "kind": "markdown",
-        "value": "> **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---"
+        "value": "> **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\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---"
       },
       "attributes": [
+        {
+          "name": "align",
+          "description": "Horizontal text alignment within the header cell.",
+          "values": [
+            {
+              "name": "center"
+            },
+            {
+              "name": "left"
+            },
+            {
+              "name": "right"
+            }
+          ]
+        },
+        {
+          "name": "checkbox-aria-label",
+          "description": "Accessible name for the header checkbox (native `aria-label`).\nDefaults to “Select all rows” when `type` is `checkbox`."
+        },
+        {
+          "name": "checked",
+          "description": "Whether the header checkbox is checked"
+        },
+        {
+          "name": "column-width",
+          "description": "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."
+        },
         {
           "name": "icon",
           "description": "Icon to display in the cell.\n\nSee [xpl-icon available icons](../xpl-icon/ICONS.md) for valid icon names."
         },
+        {
+          "name": "indeterminate",
+          "description": "Whether the checkbox is in indeterminate (partially selected) state"
+        },
         {
           "name": "label",
-          "description": ""
+          "description": "Text to display in the cell."
+        },
+        {
+          "name": "sort-direction",
+          "description": "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.",
+          "values": [
+            {
+              "name": "asc"
+            },
+            {
+              "name": "desc"
+            }
+          ]
+        },
+        {
+          "name": "sort-key",
+          "description": "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."
         },
         {
           "name": "sortable",
-          "description": ""
+          "description": "When true (and `type` is `label`), renders a sort control (button + affordance icon)."
         },
         {
           "name": "type",
-          "description": "",
+          "description": "The type of cell to render.",
           "values": [
             {
               "name": "checkbox"
             },
+            {
+              "name": "empty"
+            },
             {
               "name": "icon"
             },
@@ -1731,7 +2640,28 @@
         },
         {
           "name": "width",
-          "description": ""
+          "description": "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)."
+        }
+      ]
+    },
+    {
+      "name": "xpl-table-row",
+      "description": {
+        "kind": "markdown",
+        "value": ""
+      },
+      "attributes": [
+        {
+          "name": "disabled",
+          "description": "Whether the row and its cells are disabled."
+        },
+        {
+          "name": "row-id",
+          "description": "Stable identifier for this row when used with a selectable compositional\n`xpl-table`. If omitted, the parent table assigns a unique id."
+        },
+        {
+          "name": "selected",
+          "description": "Whether the row is visually selected."
         }
       ]
     },
@@ -1739,13 +2669,29 @@
       "name": "xpl-tabs",
       "description": {
         "kind": "markdown",
-        "value": "Tabs organize content across different screens, data sets, and other interactions."
+        "value": "`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.\n\nThe **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.\n\nPair **`xpl-tab` (slot `heading`)** with **`xpl-tab-panel` (slot `panel`)** and use the same **`target`** string on each pair so selection stays in sync."
       },
       "attributes": [
+        {
+          "name": "disabled",
+          "description": "Disables the whole tab group (headings, mobile select, and segment pills)."
+        },
         {
           "name": "full-width",
           "description": "Whether to make the tabs full width"
         },
+        {
+          "name": "type",
+          "description": "Visual and layout variant: classic underline tabs or segment (pill) controls.",
+          "values": [
+            {
+              "name": "segment"
+            },
+            {
+              "name": "tabs"
+            }
+          ]
+        },
         {
           "name": "value",
           "description": "The selected tab target value, defaults to the first tab"
@@ -1756,15 +2702,44 @@
       "name": "xpl-tag",
       "description": {
         "kind": "markdown",
-        "value": "Tags represent a set of interactive keywords that help label, organize, and categorize objects. Tags can be added or removed from an object by the user. Unlike Badges, Tags are clickable, draggable, used in dropdowns, multi-select, search bars, etc.."
+        "value": "Tags represent a set of interactive keywords that help label, organize, and categorize objects. Tags can be added or removed from an object by the user. Unlike Badges, Tags are clickable, used in dropdowns, multi-select, search bars, etc."
       },
-      "attributes": []
+      "attributes": [
+        {
+          "name": "disabled",
+          "description": "Whether the tag is disabled"
+        },
+        {
+          "name": "dismissible",
+          "description": "Whether the tag shows a dismiss button"
+        },
+        {
+          "name": "is-draggable",
+          "description": "When true, the tag label uses native HTML5 drag (the inner label is the drag source).\nNamed `isDraggable` so the Stencil prop does not collide with the native `HTMLElement.draggable`\nAPI. `reflect: false` avoids syncing a `draggable` attribute onto the host; the inner label\nremains the drag source. Host `onDragStart` still suppresses stray native drags from host chrome."
+        },
+        {
+          "name": "size",
+          "description": "The size of the tag",
+          "values": [
+            {
+              "name": "default"
+            },
+            {
+              "name": "sm"
+            }
+          ]
+        },
+        {
+          "name": "tag-id",
+          "description": "Optional stable id for the tag. When set, it is included in `tagDragStart` / `tagDragEnd` detail\nand written to `dataTransfer` as `application/x-tag-id`."
+        }
+      ]
     },
     {
       "name": "xpl-toast",
       "description": {
         "kind": "markdown",
-        "value": "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://xplor-apollo.herokuapp.com/?path=/story/components-modal--modal) instead."
+        "value": "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."
       },
       "attributes": [
         {
@@ -1905,6 +2880,72 @@
         }
       ]
     },
+    {
+      "name": "xpl-top-nav",
+      "description": {
+        "kind": "markdown",
+        "value": "Horizontal top navigation with **`left-aside`** and a **right rail**: **`right-aside`** then **user menu**\n(see **`.xpl-top-nav__right-rail`** in `render()`). The account menu uses an internal **`xpl-popover`** (**`bottom-end`**, **`display=\"menu\"`**): built-in trigger uses **`child-account-label`** (prop / attribute) as the label beside a trailing **`chevron-down`** on **`xpl-button`** (**`icon`** / **`iconPosition=\"end\"`**), or **`slot=\"user-menu-trigger\"`** for a custom trigger; panel from **`slot=\"user-menu\"`** (e.g. **`xpl-nav-header-menu`**).\nOptional **`nav-control`** and **`navOpen`**. **`left-aside`** uses **`role=\"list\"`** for primary **`xpl-top-nav-item`** rows (**`role=\"listitem\"`** on each item host). The built-in **`xpl-top-nav__brand`** item omits **`listitem`** (it is not a child of that list). **`label`** maps to **`nav`** **`aria-label`**. Opening state is internal (not a prop) — use **`navOpen`** and host **`xpl-top-nav--open`** for styling.\n\n**Escape:** With **`nav-control`**, **Escape** closes the mobile drawer and emits **`navOpen`** **`false`** (skips while **any** descendant **`xpl-popover`** is open — detected from each popover’s inner **`.xpl-popover--is-open`** marker — or when a **`xpl-top-nav-item`** dropdown is open — capture/bubble order). Focus returns to the nav toggle after the drawer closes (**Escape** or second toggle click).\n**`xpl-top-nav-item`** **`slot=\"dropdown\"`** uses document **capture** for **Escape** first; the shell uses **bubble**\non **`ownerDocument`** so nested dropdowns close before the drawer.\n\n**Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens under this subtree\nresolve to dark-mode values even when the page root is light. Floating overlays (e.g. **`xpl-popover`** / **`xpl-dropdown`**\ncontent teleported outside the host) do not inherit this scope — add **`dark`** on those panels if they should match.\n\n**Layout:** **`right-aside`** and the user-menu region are wrapped internally (**`.xpl-top-nav__right-lead`**, etc.).\nConsumers should not add those BEM classes — slot content only.\n\n**Brand logo:** use **`brand-logo`** (URL) for a built-in **`<img>`**, or **`slot=\"brand-logo\"`** for custom markup (e.g. **`xpl-icon`**, SVG). When the URL prop is set, it takes precedence and the slot is not used for the image. On **narrow viewports** (one pixel below Tailwind **`md`** — see **`top-nav.css`**), **`brand-name`** text is hidden in the bar (logo / slot mark only); keep a meaningful **`alt`** on **`brand-logo`** or accessible slotted mark for context.\n\n**Narrow / mobile** (same breakpoint as above): **`slot=\"left-aside\"`** is **hidden** in the bar until **`nav-control`**\nis set **and** the drawer is open (floating panel per Figma). **Without **`nav-control`**, there is no mobile drawer** —\nprimary links remain hidden below **`md`** until the viewport is wide enough for the horizontal bar. The built-in **brand**\nstays in the top bar (**hamburger → brand** when **`nav-control`** is set). **`right-aside`** is hidden in the bar on narrow\nviewports (**`top-nav.css`**, one pixel below Tailwind **`md`**); duplicate those actions into **`xpl-nav-header-menu`**\n**`slot=\"right-aside-mobile\"`** (below profile, above the list; narrow-only CSS in **`top-nav.css`**) per Figma.\n\n**Account menu vs drawer:** Opening the built-in account **`xpl-popover`** while the mobile drawer is open **closes the drawer**\nand emits **`navOpen(false)`** so the two layers do not stack."
+      },
+      "attributes": [
+        {
+          "name": "brand-href",
+          "description": "Destination URL for the brand control when using native navigation (**`<a href>`**). When unset, the brand is a\n**`role=\"button\"`** control and **`brandClick`** fires on activation instead."
+        },
+        {
+          "name": "brand-logo",
+          "description": "Optional image URL for the brand mark (leading the brand row, before **`brand-name`** text). When set, renders\n**`<img class=\"xpl-top-nav__brand-logo\">`** and ignores **`slot=\"brand-logo\"`** for the mark. When unset, use\n**`slot=\"brand-logo\"`** for custom logo content."
+        },
+        {
+          "name": "brand-name",
+          "description": "Visible product / app name next to **`brand-logo`**. Omit for logo-only; provide **`brand-logo`** and/or this\nstring to show the built-in brand row (**`left-aside`** is then primary nav links only)."
+        },
+        {
+          "name": "child-account-label",
+          "description": "Label text for the built-in account menu trigger (shown **before** the **`chevron-down`** icon) when **`slot=\"user-menu\"`**\nis present and **`slot=\"user-menu-trigger\"`** is not used. When empty or whitespace-only, the trigger shows only the\nchevron and uses **`aria-label=\"Open account menu\"`** on the button."
+        },
+        {
+          "name": "label",
+          "description": "Accessible name for the `<nav>` landmark (maps to `aria-label`).\nUse a unique label when the page has multiple navigation regions (e.g. side nav + top nav).\nWhen unset, defaults to `top-navigation-bar`."
+        },
+        {
+          "name": "nav-control",
+          "description": "When true, renders the navigation control (hamburger) for toggling the left slot on small viewports.\nThe control is **hidden from the Tailwind `md` breakpoint up**; collapse/show for **`left-aside`** uses **`max-width: calc(theme('screens.md') - 1px)`** in **`top-nav.css`** (Figma’s 767px at a 16px root and default **`screens.md`**).\nReflected to the **`nav-control`** attribute so host updates (framework props) re-run **`@Watch`**: drawer state and\ndocument **Escape** handling stay in sync, the host **`xpl-top-nav--nav-control`** class toggles for **`top-nav.css`**, and\n**`navOpen(false)`** is emitted if **`nav-control`** is cleared while the drawer was open."
+        }
+      ]
+    },
+    {
+      "name": "xpl-top-nav-item",
+      "description": {
+        "kind": "markdown",
+        "value": "Single nav row for **`xpl-top-nav`** / **`xpl-nav-header-menu`**. The host uses **`role=\"listitem\"`** when the row\nparticipates in a list: a **`role=\"list\"`** parent, **`slot=\"left-aside\"`** on **`xpl-top-nav`** (list host is\n**`.xpl-top-nav__left-primary`** while slotted nodes stay light-DOM children of **`xpl-top-nav`**), or default-slot rows\nunder **`xpl-nav-header-menu`**. That flag is\nkept in **`@State`** and refreshed after render plus via **`MutationObserver`** on the host (**`class`**, **`slot`**) and\non **`parentElement`** (**`role`**) or on **`.xpl-top-nav__left-primary`** (**`role`**) for **`slot=\"left-aside\"`** under **`xpl-top-nav`**) so DOM context changes\nwithout a full reconnect still re-sync. The internal\n**`xpl-top-nav__brand`** row omits **`listitem`** (it sits in **`.xpl-top-nav__brand-bar`**, not **`.xpl-top-nav__left-primary`**),\nas do **`slot=\"right-aside-mobile\"`** rows (not a list). **`slot=\"dropdown\"`** uses a local **`.xpl-top-nav-item__dropdown`**\npanel (not **`xpl-dropdown`**); see **`TECH_DEBT.md`**.\n\n**Default slot (no `label`):** do not put **`xpl-top-nav-item__inner`** or other **`xpl-top-nav-item__*`** classes on\ncustom trigger content — the component renders the inner wrapper and BEM elements.\n\n**Theming:** The host always includes Foundation’s **`dark`** class so **`--xpl-*`** purpose tokens resolve to dark-mode\nvalues even when the page root is light (consistent with **`xpl-top-nav`**)."
+      },
+      "attributes": [
+        {
+          "name": "active",
+          "description": "When true, adds **`xpl-top-nav-item--active`** for persistent accent styling (e.g. link color on the bar, or\nchrome inside **`xpl-nav-header-menu`**). Separate from **`selected`**, which sets **`aria-current=\"page\"`** and\n**`--selected`**. Use both when the design needs “current page” semantics plus the active visual treatment."
+        },
+        {
+          "name": "href",
+          "description": "If set without **`slot=\"dropdown\"`**, the inner control renders as a native **`<a href>`** (link mode)."
+        },
+        {
+          "name": "icon",
+          "description": "Icon name from **`@xplortech/apollo-icons`** (shown before the label when **`label`** is set)."
+        },
+        {
+          "name": "item-aria-label",
+          "description": "Accessible name for the inner control when there is no **`label`** and no default-slot text (e.g. icon-only).\nIf omitted in that case, **`aria-label`** defaults to **`Navigation item`**. Ignored when **`label`** or default-slot\ncontent supplies a visible name."
+        },
+        {
+          "name": "label",
+          "description": "Text label. If omitted, use the default slot for custom trigger content. Long labels use **`text-ellipsis`**\non **`.xpl-top-nav-item__label`** (see `top-nav.css`); **`title`** is set to the full string for hover tooltips\nwhen the visual line clips."
+        },
+        {
+          "name": "selected",
+          "description": "When true, sets **`aria-current=\"page\"`** and selected styling."
+        }
+      ]
+    },
     {
       "name": "xpl-utility-bar",
       "description": {