@adia-ai/web-components 0.8.34 → 0.8.36

package/custom-elements.json

@@ -30,6 +30,14 @@
               },
               "default": "false",
               "description": "Whether the section is expanded."
+            },
+            {
+              "name": "variant",
+              "type": {
+                "text": "string"
+              },
+              "default": "flat",
+              "description": "Per-item posture override. Items normally inherit their host accordion-ui's [variant] — set this directly on ONE item only to opt it out of (`flat`) or into (`contained`) the host's posture."
             }
           ],
           "slots": [
@@ -41,6 +49,10 @@
               "name": "action",
               "description": "§206 (v0.5.7): action buttons inside a custom header (e.g. Copy / Download / settings). Children placed at `[slot=\"action\"]` (or `[slot=\"actions\"]`, or marked `[data-no-toggle]`) are excluded from the toggle-on-click cascade — clicking them fires their own handler without also toggling the section."
             },
+            {
+              "name": "caret",
+              "description": "The disclosure indicator icon. Auto-stamped (a caret-down icon-ui) when absent — under BOTH the default header and an authored [slot=\"header\"]. Author your own [slot=\"caret\"] element (even empty) to opt out of the auto-stamp; no separate attribute needed."
+            },
             {
               "name": "body",
               "description": "The section's collapsible content. Renders below the header; hidden when `[open]` is unset. Author-fills with prose, lists, embedded forms, or any rich markup the panel needs."
@@ -73,6 +85,14 @@
               },
               "default": "false",
               "description": "Allow multiple panels to be open simultaneously"
+            },
+            {
+              "name": "variant",
+              "type": {
+                "text": "string"
+              },
+              "default": "flat",
+              "description": "Visual posture, inherited by child accordion-item-ui elements unless a child sets its own [variant]. `flat` (default) renders items with no chrome — settings pages, FAQ blocks, anywhere the accordion sits directly on the page canvas. `contained` gives every item a bounded surface (background + border + radius spanning header and open body, plus a divider between them when open) — the composition to reach for when nesting the accordion inside <card-ui>."
             }
           ],
           "slots": [
@@ -215,6 +235,94 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "components/adia-mark/adia-mark.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "The Adia brand mark — a rounded square with the \"Adia\" wordmark cut out in a contrasting color. Token-driven: the background always reads as the current scheme's inverse surface, and the wordmark always reads as the current scheme's inverse foreground, so a single asset replaces separate light/dark/transparent static exports (gh `icon-ui` registry entry — icon-ui is the Phosphor-glyph registry only; this is a fixed, one-off brand image, a separate delivery shape.",
+          "name": "UIAdiaMark",
+          "tagName": "adia-mark-ui",
+          "superclass": {
+            "name": "UIElement",
+            "module": "/core/element.js"
+          },
+          "attributes": [
+            {
+              "name": "size",
+              "type": {
+                "text": "string"
+              },
+              "default": "md",
+              "description": "Diameter of the square mark. Matches avatar-ui's size ladder for visual consistency when the two sit side by side (e.g. an app switcher row)."
+            },
+            {
+              "name": "inline",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Renders as `display:inline-block` instead of the block-level default (ADR-0037) — set this when the mark sits beside a text run (a topbar brand slot) rather than standing alone."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "adia-mark-ui",
+          "declaration": {
+            "name": "UIAdiaMark",
+            "module": "./components/adia-mark/adia-mark.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "components/adia-wordmark/adia-wordmark.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "The Adia wordmark — the \"Adia\" text logotype rendered as inline SVG. Unlike `adia-mark-ui` (gh this is a standalone mark meant to sit directly on a surface: its fill defaults to the current scheme's on-surface foreground token (`--a-fg-strong`) rather than a fixed inverse pairing, so it reads correctly wherever it's placed — a login header, a footer, a splash screen — without needing a background chip (gh",
+          "name": "UIAdiaWordmark",
+          "tagName": "adia-wordmark-ui",
+          "superclass": {
+            "name": "UIElement",
+            "module": "/core/element.js"
+          },
+          "attributes": [
+            {
+              "name": "size",
+              "type": {
+                "text": "string"
+              },
+              "default": "md",
+              "description": "Height of the wordmark; width follows via the fixed aspect ratio. Matches adia-mark-ui's size ladder for visual consistency when the two sit side by side."
+            },
+            {
+              "name": "inline",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Renders as `display:inline-block` instead of the block-level default (ADR-0037) — set this when the wordmark sits beside a text run rather than standing alone."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "adia-wordmark-ui",
+          "declaration": {
+            "name": "UIAdiaWordmark",
+            "module": "./components/adia-wordmark/adia-wordmark.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "components/agent-artifact/agent-artifact.js",
@@ -498,7 +606,7 @@
           "slots": [
             {
               "name": "default",
-              "description": "Default slot — primary child content."
+              "description": "Default slot — NOT a step-authoring surface: the component rebuilds its body from the addStep()/addThought() pipeline and does not consume authored children (gh#938)."
             }
           ],
           "events": [
@@ -726,7 +834,7 @@
                 "text": "string"
               },
               "default": "default",
-              "description": "Semantic color variant."
+              "description": "Semantic severity family — the only color axis alert exposes. A quiet/passive banner is the family-less `default` (no attribute): the retired `muted`/`neutral` values were exact aliases of it."
             },
             {
               "name": "pattern",
@@ -776,7 +884,7 @@
           "slots": [
             {
               "name": "content",
-              "description": "Alert body. For single-line text use the `text=` attribute (alert.js stamps a `<span slot=\"content\">` automatically). For rich content with title + description, wrap in `<col-ui slot=\"content\">` — the alert root is `display: flex` row, so multiple bare children would lay out side-by-side instead of stacking."
+              "description": "Alert body. For single-line text use the `text=` attribute (alert.js stamps a `<span slot=\"content\">` automatically). For structured banners use card-ui's section rhythm INSIDE the content element (gh `<footer>` (actions — right-aligned with its own step of air) children of the slotted wrapper; the component owns the gaps (`--alert-section-gap`, `--alert-footer-gap`), so spacing balances without per-banner col-ui/row-ui improvisation. Free-form content without those children lays out exactly as before."
             },
             {
               "name": "leading",
@@ -824,6 +932,88 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "components/anchor-bar/anchor-bar.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Persistent, anchored, elevated surface for chrome that must stay visible while a condition holds — floating bulk-action toolbars, undo bars, sticky wizard/commit footers. Distinct from <toast-ui> (auto-dismissing, notification semantics) and <modal-ui>/<drawer-ui> (blocking overlays with backdrop + focus-trap semantics). Default mode anchors [anchor] to the nearest scroll container via `position: sticky` — the shape gh bulk-action-toolbar pattern hand-rolled with card-ui + position:sticky. Opt into [viewport] for a surface that anchors to the browser viewport instead, promoted to the top layer via the Popover API (`popover=\"manual\"`) so it wins stacking over shell chrome without a z-index war. Visibility is [open] (default false, no auto-dismiss timer) — arbitrary content (typically <toolbar-ui> or <text-ui> + <button-ui>) rides the default slot.",
+          "name": "UIAnchorBar",
+          "tagName": "anchor-bar-ui",
+          "superclass": {
+            "name": "UIElement",
+            "module": "/core/element.js"
+          },
+          "attributes": [
+            {
+              "name": "anchor",
+              "type": {
+                "text": "string"
+              },
+              "default": "bottom",
+              "description": "Viewport/container edge the bar sticks to."
+            },
+            {
+              "name": "align",
+              "type": {
+                "text": "string"
+              },
+              "default": "center",
+              "description": "Horizontal alignment along the anchored edge."
+            },
+            {
+              "name": "viewport",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "false (default) anchors to the nearest scroll container via `position: sticky` — safe for content with ResizeObserver-driven children (e.g. <toolbar-ui>'s overflow measurement never sees a display:none reset). true anchors to the browser viewport via `position: fixed` + Popover API top-layer promotion — note the native Popover UA stylesheet applies `display:none` while closed, which DOES reset ResizeObserver-driven children on first open; prefer the default for content wrapping <toolbar-ui>."
+            },
+            {
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Controls visibility. No auto-dismiss — caller toggles explicitly."
+            }
+          ],
+          "slots": [
+            {
+              "name": "default",
+              "description": "Arbitrary bar content — typically <toolbar-ui> (bulk-action bars) or <text-ui> + <button-ui> (undo bars, wizard footers). The bar owns only the elevated surface chrome (bg/border/radius/shadow) and positioning; content layout is the slotted children's own."
+            }
+          ],
+          "events": [
+            {
+              "name": "open",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired when [open] becomes true."
+            },
+            {
+              "name": "close",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired when [open] becomes false."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "anchor-bar-ui",
+          "declaration": {
+            "name": "UIAnchorBar",
+            "module": "./components/anchor-bar/anchor-bar.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "components/avatar/avatar.js",
@@ -851,7 +1041,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Forwards to each child <avatar-ui> (xs|sm|md|lg|xl). Empty uses the per-avatar size."
+              "description": "Forwards to each child <avatar-ui> (sm|md|lg). Empty uses the per-avatar size. For denser or larger sets, set [scale] on an ancestor."
             }
           ]
         },
@@ -893,7 +1083,7 @@
                 "text": "string"
               },
               "default": "md",
-              "description": "Avatar size — canonical scale."
+              "description": "Avatar size (sm/md/lg). The former xs/xl diameters are the ancestor-[scale] grid cells (scale=\"ui-sm\", size=\"sm\") / (scale=\"ui-lg\", size=\"lg\")."
             },
             {
               "name": "src",
@@ -944,7 +1134,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Inline pill-shaped badge — READ-ONLY status flag, count, or notification dot. Text rendered via CSS `attr(text)`. Distinct from <tag-ui>, which is INTERACTIVE / removable and fires a `remove` event. Use badge-ui for status flags (Beta / New / Deprecated), notification counts, and unread indicators; use tag-ui for filter chips or user-managed labels.",
+          "description": "Inline pill-shaped badge — READ-ONLY status flag, count, or notification dot. Text rendered via CSS `attr(text)`. Distinct from <tag-ui>, which is INTERACTIVE / removable and fires a `remove` event. Use badge-ui for status flags (Beta / New / Deprecated), notification counts, and unread indicators; use tag-ui for filter chips or user-managed labels. REGISTER (gh issue 845; weight revised gh the same geometry family — pill radius (`--a-radius-full`) and padding token rhythm are identical, so shape is NOT how you tell them apart. Typography is: badge is UPPERCASE, mono (kbd-ui's `--a-font-family-code` stack), medium weight, wide-tracked (`--a-font-tracking-wider`, 0.06em), tabular numerals for counts. Tag stays proportional sentence-case, also weight 500 — weight no longer distinguishes the two (gh the register split now. Neither component exposes a prop that crosses this line; the registers cannot be mixed à la carte. Remaining distinctions: badge is non-interactive and carries the semantic-color voice (status tones ARE the message, solid by default — gh default for family variants (gh family-less variant (gh",
           "name": "UIBadge",
           "tagName": "badge-ui",
           "superclass": {
@@ -965,7 +1155,7 @@
                 "text": "string"
               },
               "default": "md",
-              "description": "Badge size"
+              "description": "Badge size (sm/md/lg). For a denser or larger register, set [scale] on an ancestor."
             },
             {
               "name": "status",
@@ -1001,8 +1191,8 @@
               "type": {
                 "text": "string"
               },
-              "default": "muted",
-              "description": "Fill style — orthogonal to [variant]. Badge defaults to `muted` (quiet metadata is the primitive's identity — counts, IDs, status pills in dense rows). Three values: - `muted` (default) — tinted bg + scheme-paired text. Same as the existing family-variant rules. - `solid` — saturated bg + on-strong text. Use for hero badges where the badge IS the state (e.g. a single inline error). The existing `primary` variant is a shortcut for accent + solid. - `outline` — transparent bg + family-colored border + family- colored text. Lightest visual weight; good in dense data rows. Vocabulary mirrors `<tag-ui>` (which defaults to solid, given its different role as filter / autocomplete chip)."
+              "default": "solid",
+              "description": "Fill style — orthogonal to [variant]. Badge defaults to `solid` (gh default formulas; this restores badge's own). Three values: - `solid` (default) — saturated bg + on-strong text. The badge IS the state (status stamp). `primary` is badge's sole brand-emphasis variant (`accent` retired, gh - `muted` — tinted bg + scheme-paired text. Use for quiet metadata — counts, IDs, status pills in dense rows. Family-tinted `muted` (e.g. `variant=\"info\" tone=\"muted\"`) shares `<tag-ui>`'s `[tone=\"muted\"]` shape; family-less `tone=\"muted\"` does NOT (gh `<tag-ui>`'s family-less muted stays on the lighter `--a-bg-muted` pair (gh - `outline` — transparent bg + family-colored border + family- colored text. Lightest visual weight; good in dense data rows. Vocabulary mirrors `<tag-ui>` (which now defaults to `muted` for its family variants, gh autocomplete chip)."
             }
           ]
         }
@@ -1232,7 +1422,7 @@
                 "text": "string"
               },
               "default": "md",
-              "description": "Sizing scale (xs/sm/md/lg/xl)."
+              "description": "Sizing scale (sm/md/lg). For a denser or larger register, set [scale] on an ancestor (scale=\\\"ui-sm\\\" … \\\"content-lg\\\") — scale picks the table, size picks the row."
             },
             {
               "name": "text",
@@ -1254,7 +1444,7 @@
                 "text": "string"
               },
               "default": "solid",
-              "description": "Visual style — `solid` (default fill), `outline`, `ghost`. `default` / `primary` are aliases of `solid`. Style is independent of semantic intent — to express destructive / success / info / warning intent, set [color=\"…\"] alongside. For **inline navigation** (Terms of Service, Privacy Policy, footer links, \"Sign in\" / \"Sign up\" cross-page affordances) use `<link-ui>` instead — it carries proper `<a href>` semantics, keyboard handling (Enter only, no Space), middle-click open-new-tab, and screen-reader announces \"link\" instead of \"button\". Mixing navigation and action affordances under the same primitive is a category error fixed at this junction."
+              "description": "Visual style — `solid` (default fill), `tonal` (soft container fill with in-family text — the emphasis tier between solid and outline; default rides the primary family), `outline`, `ghost`. `default` / `primary` are aliases of `solid`. Style is independent of semantic intent — to express destructive / success / info / warning intent, set [color=\"…\"] alongside (`variant=\"tonal\" color=\"danger\"` = the danger family's container fill). There is deliberately no `variant=\"secondary\"`: `secondary` names a color family in this system, and an unset variant already IS the secondary-rank look (compose-constitution); `tonal` is the named tier for a softer-than-solid filled action. For **inline navigation** (Terms of Service, Privacy Policy, footer links, \"Sign in\" / \"Sign up\" cross-page affordances) use `<link-ui>` instead — it carries proper `<a href>` semantics, keyboard handling (Enter only, no Space), middle-click open-new-tab, and screen-reader announces \"link\" instead of \"button\". Mixing navigation and action affordances under the same primitive is a category error fixed at this junction."
             },
             {
               "name": "color",
@@ -1860,6 +2050,21 @@
               "default": "0.4",
               "description": "Line smoothing factor"
             },
+            {
+              "name": "dots",
+              "type": {
+                "text": "string"
+              },
+              "default": "all",
+              "description": "Marker (dot) visibility for line and multi-line series. `all` draws a circle[data-dot] on every datum (default — matches pre-gh behavior). `none` hides all dots so a dense series reads as a clean line. `hover` shows only the currently-hovered datum's dot. `last` shows only the terminal point per series (sparkline convention). Tooltip hit targets ([data-hit]) are a separate always-rendered layer — every mode keeps hover/click working along the whole line."
+            },
+            {
+              "name": "seriesEmphasis",
+              "type": {
+                "text": "string"
+              },
+              "description": "Multi-line only. Names one series key (matching a `y` key) to render at full strength — area fill + full-opacity line. Every other series drops its area fill and renders line-only at --chart-deemphasized-opacity. Empty (default) applies full treatment to every series, unchanged from pre-gh"
+            },
             {
               "name": "loading",
               "type": {
@@ -2156,6 +2361,14 @@
               },
               "description": "Label text beside the checkbox"
             },
+            {
+              "name": "labelHidden",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "When true, [label] still sets the accessible name (aria-label) but the visible text is suppressed via the canonical sr-only technique (gh visually (e.g. a title next to a check-ui used as a list-item icon) and the plain-visible label would paint it twice."
+            },
             {
               "name": "value",
               "type": {
@@ -2952,6 +3165,14 @@
               },
               "default": "Type a command...",
               "description": "Placeholder text for the search input"
+            },
+            {
+              "name": "options",
+              "type": {
+                "text": "array"
+              },
+              "default": "[]",
+              "description": "Programmatic item list. Array of {value, label, icon?, shortcut?, disabled?} or grouped {label, options:[…]}. `icon` renders as a leading icon-ui, `shortcut` as a trailing keyboard-shortcut hint — the same fields as the data-icon/data-shortcut attributes on declarative <option> children. Alternative to declarative <option data-icon data-shortcut> / <optgroup label> children."
             }
           ],
           "slots": [
@@ -3083,7 +3304,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Compound form primitive for selecting a start + end date pair with optional named preset shortcuts (\"Today\", \"Last 7 days\", \"This month\", ...). Default presentation is a trigger button showing the formatted range; on activation a popover opens with two synchronized calendar panes + a preset side rail. Composes <calendar-picker-ui> twice; emits {from, to} ISO 8601 dates. Optional comparison-range mode emits a secondary range for analytics surfaces.",
+          "description": "Compound form primitive for selecting a start + end date pair with optional named preset shortcuts (\"Today\", \"Last 7 days\", \"This month\", ...). Default presentation is a trigger button showing the formatted range; on activation a popover opens with two synchronized calendar panes + a preset side rail. Composes <calendar-grid-ui> twice; emits {from, to} ISO 8601 dates. Both panes are ONE selection surface: first click = start, second click = end, in either grid; a second click earlier than the start restarts the range there. Optional comparison-range mode emits a secondary range for analytics surfaces.",
           "name": "UIDateRangePicker",
           "tagName": "date-range-picker-ui",
           "superclass": {
@@ -4032,7 +4253,7 @@
                 "text": "string"
               },
               "default": "default",
-              "description": "Semantic variant"
+              "description": "Semantic variant — `default | info | success | warning | danger | primary`. `primary` is the brand-emphasis fill (accent-filled bg + on-accent text), ported from toast.css's `primary` variant (gh posted toasts."
             },
             {
               "name": "duration",
@@ -4563,7 +4784,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Icon size. Accepts the named scale (`xs` 12px / `sm` 14px / `md` 16px / `lg` 20px / `xl` 32px / `2xl` 48px / `3xl` 64px / `4xl` 96px / `fill` 100% of parent) or a free-form pixel / rem / em value as a string (\"48\", \"3rem\", \"1.25em\"). Overrides the inherited `--a-icon-size` from the universal `[size]` system on ancestors."
+              "description": "Icon size. Named tiers `sm` 14px / `md` 16px / `lg` 20px ride the universal `[size]` system (`--a-icon-size`), which the ancestor `[scale]` tiers re-table. Anything beyond the row is a free-form pixel / rem / em / percent string (\"48\", \"3rem\", \"1.25em\", \"100%\" fills the parent box)."
             },
             {
               "name": "weight",
@@ -4572,6 +4793,13 @@
               },
               "default": "regular",
               "description": "Icon weight — selects the Phosphor weight variant (thin/light/regular/bold/fill/duotone)."
+            },
+            {
+              "name": "tone",
+              "type": {
+                "text": "string"
+              },
+              "description": "Semantic color role. Empty (default) inherits currentColor — unchanged from pre-tone behavior. Maps to the L3 role text tokens (--a-{family}-text / --a-fg-muted). Vocabulary mirrors <badge-ui>'s [variant] enum so a status color reads the same whether it comes from a Badge chip or a bare status/trend icon."
             }
           ]
         }
@@ -5255,6 +5483,13 @@
                 "text": "string"
               },
               "description": "Sizing scale: sm, md (default), lg."
+            },
+            {
+              "name": "textContent",
+              "type": {
+                "text": "string"
+              },
+              "description": "Key label text, extracted from innerHTML (e.g. \"Ctrl+K\"). The main payload field for Kbd components extracted from HTML — mirrors Text/Code's textContent prop."
             }
           ],
           "slots": [
@@ -5574,6 +5809,14 @@
             }
           ],
           "slots": [
+            {
+              "name": "text",
+              "description": "Override slot for richer primary-text markup than the plain [text] attribute string. Styled by `:scope [slot=\"text\"]` (list.css) and honored by UIListItem's stamping logic — a consumer-provided [slot=\"text\"] child is never overwritten (only component-stamped ones are). Undeclared until gh"
+            },
+            {
+              "name": "content",
+              "description": "Full-row escape hatch: when a [slot=\"content\"] child is present the component stamps NOTHING (no icon/text/description spans) and the child owns the entire row. Use for cards, rows, or any custom composition that the icon | content | action grid cannot express."
+            },
             {
               "name": "icon",
               "description": "Override the [icon] glyph with a custom slotted element (e.g. a colored <icon-ui>, an image, or an avatar-ui). Mutually exclusive with the [icon] attribute — slot child wins if both are present."
@@ -5754,7 +5997,7 @@
                 "text": "string"
               },
               "default": "warning",
-              "description": "Highlight color variant. Default `warning` is the conventional yellow-marker tone."
+              "description": "Highlight color family — the only color axis mark exposes. Default `warning` is the conventional yellow-marker tone and IS mark's family-less identity, so there is no `default` member. For a neutral (non-semantic) highlight, override the public tokens instead of the variant: `--mark-bg: var(--a-bg-muted); --mark-fg: var(--md-sys-color-neutral-on-surface)` — the successor to the retired `variant=\"muted\"` (gh#881)."
             }
           ],
           "slots": [
@@ -5792,7 +6035,7 @@
         },
         {
           "kind": "class",
-          "description": "Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + value.",
+          "description": "Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + subtitle + value.",
           "name": "UIMenuItem",
           "tagName": "menu-item-ui",
           "superclass": {
@@ -5814,6 +6057,13 @@
               },
               "description": "Item label text."
             },
+            {
+              "name": "subtitle",
+              "type": {
+                "text": "string"
+              },
+              "description": "Optional secondary description line rendered under the label."
+            },
             {
               "name": "value",
               "type": {
@@ -5846,6 +6096,14 @@
             {
               "name": "text",
               "description": "Custom label content; falls through to `[text]` prop if not slotted."
+            },
+            {
+              "name": "subtitle",
+              "description": "Custom secondary-line content override; falls through to `[subtitle]` prop if not slotted."
+            },
+            {
+              "name": "trailing",
+              "description": "Trailing element pinned to the far edge (shortcut hint, check mark)."
             }
           ]
         },
@@ -6001,7 +6259,7 @@
                 "text": "string"
               },
               "default": "md",
-              "description": "Width preset. sm=24rem, md=32rem, lg=48rem, full=95vw."
+              "description": "Width preset. sm=24rem, md=32rem, lg=48rem (each capped at 90vw)."
             },
             {
               "name": "text",
@@ -6094,6 +6352,14 @@
               "default": "false",
               "description": "Inline-expanded state. Toggled by header click when [collapsible]."
             },
+            {
+              "name": "selected",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Marks the group containing the selected route (consumers set it from active-route logic). Drives the filled header glyph — selection, never mere expansion (gh#459)."
+            },
             {
               "name": "collapsible",
               "type": {
@@ -6345,7 +6611,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Noodle stroke color. Defaults to --a-accent"
+              "description": "Noodle stroke color. Defaults to --a-primary-bg"
             },
             {
               "name": "curve",
@@ -6575,7 +6841,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Selectable card with radio semantics. A \"rich radio\" — single-select one of N where each option carries a heading, optional description, and optional leading icon. Siblings sharing a `name` form a radiogroup. The whole card is the click target; a CSS-rendered radio circle in the top-left signals state. Form-associated, so `name=value` submits with the parent form when checked.",
+          "description": "Selectable card with radio semantics. A \"rich radio\" — single-select one of N where each option carries a heading, optional description, and an optional icon at the trailing end of the header row. Siblings sharing a `name` form a radiogroup. The whole card is the click target; a CSS-rendered radio circle in the top-left signals state. Renders on a container-low tonal surface (no outline as the primary boundary); the checked state keeps an accent border + fill so selection stays unmistakable. Form-associated, so `name=value` submits with the parent form when checked.",
           "name": "UIOptionCard",
           "tagName": "option-card-ui",
           "superclass": {
@@ -6640,7 +6906,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Optional Phosphor icon name. Stamped as a leading <icon-ui slot=\"icon\"> when set."
+              "description": "Optional Phosphor icon name. Stamped as a trailing <icon-ui slot=\"icon\"> when set."
             },
             {
               "name": "layout",
@@ -6648,7 +6914,7 @@
                 "text": "string"
               },
               "default": "default",
-              "description": "Internal layout. `default` puts the indicator on the left and the icon adjacent. `tile` stacks vertically — icon top-left, indicator top-right, heading + description below — for hero pickers (source / role / plan tiles) where the icon is a primary brand cue."
+              "description": "Internal layout. `default` puts the indicator on the left and, when [icon] is set, the icon at the trailing end of the header row alongside the heading. `tile` stacks vertically — icon top-left, indicator top-right, heading + description below — for hero pickers (source / role / plan tiles) where the icon is a primary brand cue."
             }
           ],
           "slots": [
@@ -7090,26 +7356,26 @@
           },
           "attributes": [
             {
-              "name": "complete",
+              "name": "stage",
               "type": {
-                "text": "boolean"
+                "text": "string"
               },
-              "default": "false",
-              "description": "Component property: complete."
+              "description": "Current stage name (interpret, analyze, plan, generate, validate, render)."
             },
             {
               "name": "message",
               "type": {
                 "text": "string"
               },
-              "description": "Component property: message."
+              "description": "Current stage description shown alongside the stage label."
             },
             {
-              "name": "stage",
+              "name": "status",
               "type": {
                 "text": "string"
               },
-              "description": "Component property: stage."
+              "default": "idle",
+              "description": "Canonical stage-progress state. Set to `completed` to render the final state and collapse the history log."
             }
           ],
           "slots": [
@@ -7153,6 +7419,14 @@
               "default": "4",
               "description": "Pixel offset between the anchor and the popover"
             },
+            {
+              "name": "match-width",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Size the content panel to the trigger's width instead of max-content. Opt-in — the default (unset) keeps every existing consumer's content-sized panel unchanged."
+            },
             {
               "name": "open",
               "type": {
@@ -7476,6 +7750,59 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "components/radio-group/radio-group.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Groups a set of bare <radio-ui label=\"…\"> children under one accessible name — role=\"radiogroup\" on the host plus aria-labelledby pointing at its own [label]. Radio-ui already supports ancestor fieldset/[role=radiogroup] grouping for exclusivity + arrow-key navigation (unchanged by this wrapper); a plain layout container (Column) can carry neither the role nor the label association, which left the canonical questionnaire shape (radio.yaml's own example) with no programmatic question↔group link (gh mutually-exclusive radio-ui options — it is the ONLY primitive that carries the group's accessible name; radio-ui itself stays self-labeling per-option.",
+          "name": "UIRadioGroup",
+          "tagName": "radio-group-ui",
+          "superclass": {
+            "name": "UIElement",
+            "module": "/core/element.js"
+          },
+          "attributes": [
+            {
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "description": "The question or prompt text — rendered above the options and wired to the host via aria-labelledby. This is the group's accessible name; without it the group has none."
+            },
+            {
+              "name": "required",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Marks the group as requiring a selection for form validation (visual + aria-required only — the constraint itself lives on each radio-ui's own [required])."
+            }
+          ],
+          "slots": [
+            {
+              "name": "default",
+              "description": "radio-ui children sharing one [name=] — exclusivity and arrow-key navigation are unchanged; they still resolve via closest('fieldset, [role=radiogroup]'), which now matches this host."
+            },
+            {
+              "name": "label",
+              "description": "Auto-minted label element (mounted by radio-group-ui from the [label] prop) — do not author this slot directly."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "radio-group-ui",
+          "declaration": {
+            "name": "UIRadioGroup",
+            "module": "./components/radio-group/radio-group.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "components/radio/radio.js",
@@ -7893,6 +8220,14 @@
                 "text": "string"
               },
               "description": "Source URL (image, iframe, etc.)."
+            },
+            {
+              "name": "flush",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Paragraph-grade embedding mode — removes the article chrome (body padding and the 45rem reading measure, plus the trailing paragraph margin) so the rendered markdown sits flush in a host column like a plain text block. Use when richtext carries a single paragraph or fragment inside an already-measured layout (doc pages, cards); leave off for standalone articles and chat transcripts."
             }
           ],
           "slots": [
@@ -8192,6 +8527,14 @@
                 "text": "string"
               },
               "description": "Value of the currently selected segment."
+            },
+            {
+              "name": "allowEmpty",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Suppresses the connect-time self-select of the first enabled segment when value is falsy. Without it, an empty value silently selects the first segment; with it, a falsy value renders every segment unselected until a real value arrives — for path-bound consumers whose bound value can be a genuine empty state."
             }
           ],
           "slots": [
@@ -8232,7 +8575,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Single- and multi-select dropdown primitive — the canonical AdiaUI select control. Form-bearing via UIFormElement: [name], [value], [required], [disabled], fires `change`. Options via native <option> / <optgroup> children, programmatic `.options` array, or JSON [data-options] (hydrated by <editor-shell>'s wireSelects). Use for single-select with > 4 options; for ≤ 4 options use <segmented-ui> or <radio-ui>. Multi-select via [multiple]: trigger renders <tag-ui> chips per selection, popover shows checkbox-style option list, Backspace removes the last chip, [select-all] adds bulk controls, [max-chips] caps the visible chip count with a \"+N more\" pill. Form value stays a comma-separated string under [name] for native <form> compatibility (parse with .split(',')).",
+          "description": "Single- and multi-select dropdown primitive — the canonical AdiaUI select control. Form-bearing via UIFormElement: [name], [value], [required], [disabled], fires `change`. Options via native <option> / <optgroup> children, programmatic `.options` array, or JSON [data-options] (hydrated by <editor-shell>'s wireSelects). Use for single-select with > 4 options; for ≤ 4 options use <segmented-ui> or <radio-ui>. Multi-select via [multiple]: trigger renders <tag-ui> chips per selection, popover shows checkbox-style option list, Backspace removes the last chip, [select-all] adds bulk controls, [max-chips] caps the visible chip count with a \"+N more\" pill, and [summary-label] swaps the chip trigger for one text line — the single selection's label, or \"Label (N)\" for more. Form value stays a comma-separated string under [name] for native <form> compatibility (parse with .split(',')).",
           "name": "UISelect",
           "tagName": "select-ui",
           "superclass": {
@@ -8278,6 +8621,14 @@
               },
               "description": "URL for leading avatar image (takes precedence over icon)"
             },
+            {
+              "name": "mark",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Renders the Adia brand mark (`<adia-mark-ui>`) as the leading visual — takes precedence over avatar and icon. Token-driven (light/dark handled internally), so it fits a scheme-switching workspace/app switcher where a static logo URL can't invert. Per-option `mark` on an `<option>`/options-array entry works the same way, scoped to that row."
+            },
             {
               "name": "disabled",
               "type": {
@@ -8294,6 +8645,14 @@
               "default": "false",
               "description": "Reserved attribute on a select option that renders as a visual divider instead of a selectable row."
             },
+            {
+              "name": "no-radio",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Suppress the single-select radio indicator on option rows (gh For menu-shaped switchers — workspace or user identity menus — where the trigger already shows the committed value and a per-row radio reads as redundant selection language. Rows keep their layout and aria-selected state; the trigger and selected-row weight carry the signal. No effect under [multiple]. IMPLIED by [mark] — a mark declares an identity switcher, which is always menu-shaped (gh"
+            },
             {
               "name": "error",
               "type": {
@@ -8362,6 +8721,14 @@
               "default": "0",
               "description": "Multi-select only. Caps the number of chips visible in the trigger. When `value.length > max-chips`, the first N chips render plus a \"+M more\" pill that opens the popover on click. `0` (default) = unlimited."
             },
+            {
+              "name": "summary-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "null",
+              "description": "Multi-select only (gh text line: a single selection shows its own label; N > 1 shows \"<summary-label> (N)\" — e.g. \"Organizations (2)\"; none shows the placeholder. Popover checkbox rows, Backspace-removes-last, the comma-separated form value, [select-all], and [clearable] are unchanged. Absent (default) = tag-ui chip trigger. Prefer this form for narrow triggers (filter bars) where wrapping chips would balloon the control."
+            },
             {
               "name": "min",
               "type": {
@@ -8408,7 +8775,7 @@
                 "text": "array"
               },
               "default": "[]",
-              "description": "Option list. Array of {value, label, disabled?, icon?, avatar?} or grouped {label, options: [...]}. Alternative to declarative <option> / <optgroup> children. Per-option icon/avatar render in the list AND reflect in the trigger's selected state."
+              "description": "Option list. Array of {value, label, disabled?, icon?, avatar?, mark?} or grouped {label, options: [...]}. Alternative to declarative <option> / <optgroup> children. Per-option icon/avatar/mark render in the list AND reflect in the trigger's selected state (mark takes precedence over avatar, which takes precedence over icon). An {action, label} entry is a COMMAND row, not a selection: it dispatches the `action` event, never becomes the value, and renders without the single-select radio indicator (user menus: Account / Log out)."
             },
             {
               "name": "pattern",
@@ -8951,6 +9318,14 @@
               },
               "default": "false",
               "description": "Horizontal-bleed KPI layout. With a `slot=\"chart\"` child, the value / label / change stack on the left while the chart fills the right column at full height and bleeds to the card's top / right / bottom edges (the horizontal counterpart to a chart in a card `<section bleed>`). No effect without a chart slot."
+            },
+            {
+              "name": "band",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Chart-band KPI layout. With a `slot=\"chart\"` child, label / value / change stack full width top to bottom and the chart forms a short full-width band between the value and the change row (the Gmail/Vercel/shadcn stat-card shape). Composes with `icon` exactly as the base layout does. No effect without a chart slot."
             }
           ],
           "slots": [
@@ -8994,7 +9369,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Discrete-dash step-progress indicator. One <span> dash per step in [total]; the first [value] dashes are filled with --a-accent. Used in multi-step flows (registration, onboarding, wizards). Replaces the bespoke `[data-onb-progress]` + `[data-reg-progress]` markup that lived in onboarding.css + registration.css with a single primitive.",
+          "description": "Discrete-dash step-progress indicator. One <span> dash per step in [total]; the first [value] dashes are filled with --md-sys-color-primary. Used in multi-step flows (registration, onboarding, wizards). Replaces the bespoke `[data-onb-progress]` + `[data-reg-progress]` markup that lived in onboarding.css + registration.css with a single primitive.",
           "name": "UIStepProgress",
           "tagName": "step-progress-ui",
           "superclass": {
@@ -9091,6 +9466,14 @@
               },
               "default": "idle",
               "description": "Canonical stage-progress state. Mutually exclusive (prevents the `active && completed` footgun the prior multi-Boolean shape allowed)."
+            },
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "S2's phase-gating mechanism (gh#711 S1 review). Skipped in the parent's [interactive] roving tabindex/arrow order, unclickable, carries aria-disabled. Independent of [status] — a completed or upcoming step can still be disabled for a different reason (e.g. the visit phase hasn't unlocked it yet)."
             }
           ],
           "slots": [
@@ -9110,7 +9493,7 @@
         },
         {
           "kind": "class",
-          "description": "Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead.",
+          "description": "Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead. Add [interactive] to opt into click-to-navigate + roving- tabindex keyboard (arrow keys / Home / End) — the host still owns whether navigation is permitted: listen for the cancelable [step-request] event and call preventDefault() to veto a step before it lands, or set [disabled] on a stepper-item-ui to phase-gate it out of reach entirely.",
           "name": "UIStepper",
           "tagName": "stepper-ui",
           "superclass": {
@@ -9133,6 +9516,14 @@
               },
               "default": "0",
               "description": "Current step index (0-based)."
+            },
+            {
+              "name": "interactive",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Opt into click-to-navigate + roving-tabindex keyboard nav (arrow keys / Home / End / Enter / Space). Absent by default — a bare stepper is a read-only progress display, not a nav control (gh"
             }
           ],
           "slots": [
@@ -9140,6 +9531,22 @@
               "name": "default",
               "description": "Default slot — primary child content."
             }
+          ],
+          "events": [
+            {
+              "name": "step-request",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Cancelable — fires BEFORE [step] mutates, on a click or keyboard navigation. call preventDefault() to veto: the step does not change, [change] does not fire, and focus/roving-tabindex stay exactly where they were. A host that never listens for this event keeps the pre-veto uncontrolled behavior unchanged (gh"
+            },
+            {
+              "name": "change",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired after a click or keyboard navigation changes [step] (i.e. only when the preceding [step-request] wasn't vetoed). Only fires when [interactive] is set."
+            }
           ]
         }
       ],
@@ -9587,7 +9994,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Sizing scale (full tier — xs / sm / md / lg / xl)."
+              "description": "Sizing scale (sm / md / lg). For a denser or larger register, set [scale] on an ancestor."
             },
             {
               "name": "value",
@@ -9790,7 +10197,7 @@
                 "text": "array"
               },
               "default": "[]",
-              "description": "Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children."
+              "description": "Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, valign?, accessor?, format?, render?, sortFn?, filterType?, meta?}. `valign` ('top'|'center') overrides the host [valign] for that column's body cells only — header cells always stay centered. Alternative to declarative <col-def> children (<col-def valign=\"top\">); col-def also accepts `meta` as a JSON attribute (gh#925) — e.g. <col-def type=\"badge\" meta='{\"variants\":{\"Online\":\"success\"}}'> — so cell-type meta (badge variant maps, currency codes) is expressible in static HTML."
             },
             {
               "name": "data",
@@ -9798,7 +10205,7 @@
                 "text": "array"
               },
               "default": "[]",
-              "description": "Row records. Array of plain objects keyed to columns[].key."
+              "description": "JS property (set programmatically — `el.data = [...]`) — row records, an array of plain objects keyed to columns[].key. May also be supplied declaratively as a JSON-array `data=\"[…]\"` attribute, hydrated once at connect (gh Custom accessor on the element class, not a reflected attribute."
             },
             {
               "name": "density",
@@ -9838,7 +10245,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Visual-only passthrough — applies `<table-ui>`'s chrome reset (background / border / border-radius all transparent) AND short-circuits the data lifecycle entirely. The consumer owns the body shape: no header injection, no row reconciliation from `.data`, no empty-state / loading overlays, no aggregation or pagination footers. Use raw when embedding `<table-ui>` inside surfaces that supply their own chrome (e.g. `<card-ui><section bleed>`), or when wrapping a consumer-authored native `<table>` for design-token styling without the framework's data semantics. Pre-v0.6.33 (FB-53 §2) `raw` was visual-only and the data lifecycle still ran — wrapping a `.data`-unset native table produced a phantom \"No data\" overlay. v0.6.33+ matches the documented contract."
+              "description": "Visual-only passthrough — applies `<table-ui>`'s chrome reset (background / border / border-radius all transparent) AND short-circuits the data lifecycle entirely. The consumer owns the body shape: no header injection, no row reconciliation from `.data`, no empty-state / loading overlays, no aggregation or pagination footers. Use raw when embedding `<table-ui>` inside surfaces that supply their own chrome (e.g. `<card-ui><section bleed>`), or when wrapping a consumer-authored native `<table>` for design-token styling without the framework's data semantics. Note: a `<table-ui>` placed directly inside `<card-ui><section bleed>` drops the table's visual chrome automatically (card.css, gh#796) even without `raw` — `raw` is still required to also short-circuit the data lifecycle. Pre-v0.6.33 (FB-53 §2) `raw` was visual-only and the data lifecycle still ran — wrapping a `.data`-unset native table produced a phantom \"No data\" overlay. v0.6.33+ matches the documented contract."
             },
             {
               "name": "search",
@@ -9871,6 +10278,22 @@
               "default": "false",
               "description": "Alternate row background colors for visual scanning."
             },
+            {
+              "name": "frameless",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Drop the table's outer 1px perimeter and nothing else (gh#511) — row dividers are untouched (the perimeter is split onto its own --table-perimeter token, defaulting to --table-border). For card-composed tables: the card owns the frame, so the table's square perimeter otherwise renders a doubled edge (flush bleed) or a stray inner box (with content above). Standalone tables keep their chrome by default. Theming path without the attribute: set --table-perimeter to transparent per instance. Note: `<card-ui><section bleed>` already drops a direct-child table-ui's chrome automatically (card.css, gh instance still applies and is honored, but is no longer required just to avoid the doubled-edge look in that composition."
+            },
+            {
+              "name": "valign",
+              "type": {
+                "text": "string"
+              },
+              "default": "center",
+              "description": "Vertical alignment of body-cell content. 'center' (default) keeps today's behavior — every cell centers on the row's cross-axis, which reads well for single-line rows. 'top' aligns each cell's content to the top of its padding box instead, so tall/wrapped rows (a [wrap] title column, a stacked identity cell) share one first-line scan anchor across the row rather than each cell floating at a different vertical center (gh (or <col-def valign=\"…\">) overrides the host per-column — e.g. keep a checkbox column centered while data cells top-align. Header cells always stay centered regardless of this prop (single-line by contract) — the checkbox/expand structural columns also default to centered under [valign=\"top\"] since they're not part of columns[]."
+            },
             {
               "name": "wrap",
               "type": {
@@ -10120,7 +10543,7 @@
                 "text": "string"
               },
               "default": "md",
-              "description": "Size preset controlling font-size and padding."
+              "description": "Size preset controlling font-size and padding (sm/md/lg — same size system as badge-ui). For a denser or larger register, set [scale] on an ancestor."
             },
             {
               "name": "text",
@@ -10142,15 +10565,15 @@
                 "text": "string"
               },
               "default": "default",
-              "description": "Semantic variant — `default | info | success | warning | danger`."
+              "description": "Semantic variant — `default | info | success | warning | danger | primary`."
             },
             {
               "name": "tone",
               "type": {
                 "text": "string"
               },
-              "default": "solid",
-              "description": "Fill style — orthogonal to [variant]. Three values: - `solid` (default for family variants) — saturated bg + on-strong (near-white) text. The chip IS the state. - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s default look. Use on metadata chips in dense lists where the saturated default would compete for attention. - `outline` — transparent bg + family-colored border + family-colored text. The lightest visual weight; good in dense data tables or faceted filter rows where multiple chips would otherwise compete. The `default` variant (no family) stays quiet chrome regardless of tone unless `tone=\"solid\"` is set explicitly (high-contrast neutral inverse), or `tone=\"outline\"` (fg-muted text + subtle border)."
+              "default": "muted",
+              "description": "Fill style — orthogonal to [variant]. Three values: - `muted` (default for the family variants — info/success/warning/ danger/primary — gh their reported default formulas; this restores tag's own) — tinted bg with scheme-paired text. Matches <badge-ui>'s `[tone=\"muted\"]` look. Use on metadata / citation chips in dense lists or tables where a saturated fill would compete for attention (gh the family-less `default` variant, which stays solid unconditionally (gh `<tag-ui text=\"…\">` still renders that solid look with no attributes at all. - `solid` — saturated bg + on-strong (near-white) text. The chip IS the state. Opt in explicitly for a family variant (gh or it's already the unconditional look for the family-less `default` variant (gh - `outline` — transparent bg + family-colored border + family-colored text. The lightest visual weight; good in dense data tables or faceted filter rows where multiple chips would otherwise compete. `tone` is a declarative presentational attribute (not a reactive prop — see tag.class.js) so its schema `default` here is documentation of the rendered-by-default look, not a reflected attribute value."
             }
           ],
           "events": [
@@ -10327,7 +10750,7 @@
           "slots": [
             {
               "name": "chip",
-              "description": "Custom chip template — receives `{value, index}` per token. When absent, each token renders as a default `<tag-ui removable text=\"<value>\">`."
+              "description": "Custom per-token chip template (TKT-0023). Provide a single `<template slot=\"chip\">` child; it's cloned once per committed token, with `{{value}}` / `{{index}}` substituted into every text node and attribute value in the clone (e.g. `<tag-ui removable text=\"{{value}}\" title=\"Item #{{index}}\">`). The template's first element child is the reconcile unit — data-* bookkeeping attrs land on it, so removal / re-render still track by position the same way the default chip does. When absent, or when the template has no element content (malformed), each token renders as the default `<tag-ui removable text=\"<value>\">`. Readonly/disabled toggling of the built-in `removable` affordance only applies to the default chip — a custom template always owns its own removability, independent of the host's readonly/disabled state."
             }
           ],
           "events": [
@@ -10628,7 +11051,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Typographic / density register for the subtree — \"verse\" (compact) or \"prose\" (long-form). Adopts the matching register layer on demand; maps onto the [verse]/[prose] attribute (additive)."
+              "description": "Sizing register for the subtree — one of the six [scale] tiers: ui-sm (dense product UI), ui-md (base), ui-lg (touch/presentation), content-sm (compact article), content-md (long-form), content-lg (hero/marketing). Adopts the scale layer on demand; the reflected attribute is the [scale=\"…\"] CSS hook. Deprecated aliases \"verse\" (→ ui-sm) and \"prose\" (→ content-md) still map onto the legacy [verse]/[prose] attributes; removed at v1.0."
             }
           ]
         }
@@ -10858,7 +11281,7 @@
                 "text": "string"
               },
               "default": "idle",
-              "description": "Lifecycle state (idle | pending | done | failed)."
+              "description": "Lifecycle state (idle | active | completed | error). Pairs with `spinner` on \"active\" for an in-progress step."
             },
             {
               "name": "spinner",
@@ -10866,7 +11289,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Show a spinner instead of the icon while status=pending."
+              "description": "Show a spinner instead of the dot/icon while status=\"active\"."
             }
           ],
           "slots": [
@@ -10986,7 +11409,7 @@
                 "text": "string"
               },
               "default": "info",
-              "description": "Semantic variant — `default | info | success | warning | danger`. `primary` and `muted` are style hints; canonical \"neutral but interesting\" tone is `info`."
+              "description": "Semantic variant — `default | info | success | warning | danger | primary`. `primary` is the brand-emphasis fill (mirrors badge-ui/button-ui's `primary`); canonical \"neutral but interesting\" tone is `info`."
             }
           ]
         }
@@ -11267,7 +11690,7 @@
                 "text": "string"
               },
               "default": "md",
-              "description": "Sizing scale forwarded to the internal <button-ui>."
+              "description": "Sizing scale (sm/md/lg) forwarded to the internal <button-ui>."
             },
             {
               "name": "variant",