@adia-ai/a2ui-corpus 0.6.36 → 0.6.38

package/catalog-a2ui_0_9.json

@@ -336,6 +336,9 @@
           "action": {
             "description": "§206 (v0.5.7): action buttons inside a custom header (e.g. Copy /\nDownload / settings). Children placed at `[slot=\"action\"]` (or\n`[slot=\"actions\"]`, or marked `[data-no-toggle]`) are excluded from\nthe toggle-on-click cascade — clicking them fires their own handler\nwithout also toggling the section."
           },
+          "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."
+          },
           "header": {
             "description": "Custom header content. By default `[text]` renders as a plain header\nlabel, but a `[slot=\"header\"]` override lets consumers author rich\nheaders (icon + title + action buttons + caret)."
           }
@@ -418,7 +421,11 @@
           "MenuItem",
           "Button"
         ],
-        "slots": {},
+        "slots": {
+          "icon": {
+            "description": "Override the [icon] glyph with a custom slotted element (custom icon-ui, image, avatar). Mutually exclusive with the [icon] attribute — slot child wins."
+          }
+        },
         "states": [],
         "status": "stable",
         "synonyms": {
@@ -2829,6 +2836,16 @@
           "description": "Badge display text. Renderer routes this to the `text` attribute via CSS attr(text) on ::after.",
           "$ref": "#/$defs/DynamicString"
         },
+        "tone": {
+          "description": "Fill style — orthogonal to [variant]. Badge defaults to `muted`\n(quiet metadata is the primitive's identity — counts, IDs, status\npills in dense rows). Three values:\n  - `muted` (default) — tinted bg + scheme-paired text. Same as\n    the existing family-variant rules.\n  - `solid` — saturated bg + on-strong text. Use for hero badges\n    where the badge IS the state (e.g. a single inline error). The\n    existing `primary` variant is a shortcut for accent + solid.\n  - `outline` — transparent bg + family-colored border + family-\n    colored text. Lightest visual weight; good in dense data rows.\nVocabulary mirrors `<tag-ui>` (which defaults to solid, given its\ndifferent role as filter / autocomplete chip).\n",
+          "type": "string",
+          "enum": [
+            "muted",
+            "solid",
+            "outline"
+          ],
+          "default": "muted"
+        },
         "variant": {
           "description": "Semantic color variant.",
           "type": "string",
@@ -3368,6 +3385,125 @@
         "version": 1
       }
     },
+    "Blockquote": {
+      "title": "Blockquote",
+      "description": "Styled quotation block with a left visual indicator (border rule) +\nitalic body text + optional `cite` attribution line. Use for pull-quotes,\ntestimonials, or inline citations within prose. The default visual\nfollows the prose typography family — pair with `<text-ui>` body\nvariants inside, or pass raw text in the default slot. The optional\n[cite] attribute (or [slot=cite]) renders a small attribution line\nbelow the quote prefixed with an em-dash. Semantic blockquote element\nwith `role=\"blockquote\"` implied via tag name (do NOT wrap in a native\n`<blockquote>` — that produces nested-blockquote semantics).\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "cite": {
+          "description": "Source attribution shown beneath the quote (small, muted, em-dash\nprefix). For richer attribution (links, multi-line), use the\n`[slot=\"cite\"]` content slot instead — when both are set, the slot\ncontent wins. Plain-string convenience prop for the common case.\n",
+          "type": "string",
+          "default": ""
+        },
+        "component": {
+          "const": "Blockquote"
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [],
+        "category": "display",
+        "composes": [],
+        "events": {},
+        "examples": [
+          {
+            "description": "Pull-quote with em-dash attribution.",
+            "a2ui": "[\n  {\n    \"id\": \"q\",\n    \"component\": \"Blockquote\",\n    \"cite\": \"Steve Jobs, Stanford Commencement, 2005\",\n    \"content\": \"Stay hungry. Stay foolish.\"\n  }\n]\n",
+            "name": "default"
+          },
+          {
+            "description": "Blockquote with a linked citation via slot.",
+            "a2ui": "[\n  {\n    \"id\": \"q\",\n    \"component\": \"Blockquote\",\n    \"children\": [\"body\", \"src\"]\n  },\n  {\n    \"id\": \"body\",\n    \"component\": \"Text\",\n    \"textContent\": \"The best way to predict the future is to invent it.\"\n  },\n  {\n    \"id\": \"src\",\n    \"component\": \"Link\",\n    \"slot\": \"cite\",\n    \"href\": \"https://en.wikipedia.org/wiki/Alan_Kay\",\n    \"text\": \"Alan Kay (1971)\"\n  }\n]\n",
+            "name": "rich-attribution"
+          }
+        ],
+        "keywords": [
+          "blockquote",
+          "quote",
+          "pull-quote",
+          "quotation",
+          "testimonial",
+          "citation",
+          "cite"
+        ],
+        "name": "UIBlockquote",
+        "related": [
+          "text",
+          "link",
+          "card"
+        ],
+        "slots": {
+          "default": {
+            "description": "The quote body. Plain text or composed `<text-ui>` / inline elements."
+          },
+          "cite": {
+            "description": "Optional citation override. Use for rich attribution (linked source,\nperson + role pairing) where [cite] string is insufficient.\n"
+          }
+        },
+        "states": [
+          {
+            "description": "Default, ready for reading.",
+            "name": "idle"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "quote": [
+            "blockquote",
+            "quotation",
+            "pull-quote"
+          ],
+          "testimonial": [
+            "blockquote",
+            "quote"
+          ]
+        },
+        "tag": "blockquote-ui",
+        "tokens": {
+          "--blockquote-cite-fg": {
+            "description": "Citation text color (muted).",
+            "default": "var(--a-fg-muted)"
+          },
+          "--blockquote-cite-size": {
+            "description": "Citation font size.",
+            "default": "var(--a-ui-sm)"
+          },
+          "--blockquote-fg": {
+            "description": "Quote text color.",
+            "default": "var(--a-fg-subtle)"
+          },
+          "--blockquote-pad-block": {
+            "description": "Vertical padding inside the blockquote.",
+            "default": "var(--a-space-2)"
+          },
+          "--blockquote-pad-inline": {
+            "description": "Inline padding between the rule and the quote text.",
+            "default": "var(--a-space-3)"
+          },
+          "--blockquote-rule-color": {
+            "description": "Color of the left indicator rule.",
+            "default": "var(--a-border-strong)"
+          },
+          "--blockquote-rule-width": {
+            "description": "Width of the left indicator rule.",
+            "default": "2px"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
     "Breadcrumb": {
       "title": "Breadcrumb",
       "description": "Breadcrumb trail with auto-inserted separators. Supports a leading icon (first child) and an overflow popover that collapses middle crumbs into a `…` menu.",
@@ -3899,6 +4035,21 @@
           "type": "string",
           "default": "Select date..."
         },
+        "placement": {
+          "description": "Popover placement relative to the trigger. Default `bottom` centers the calendar panel under the trigger (ADR-0034 Rule 2 — calendar panel wider than trigger).",
+          "type": "string",
+          "enum": [
+            "top",
+            "bottom",
+            "left",
+            "right",
+            "top-start",
+            "top-end",
+            "bottom-start",
+            "bottom-end"
+          ],
+          "default": "bottom"
+        },
         "value": {
           "description": "Selected date (ISO string)",
           "type": "string",
@@ -4165,7 +4316,23 @@
           "alert",
           "skeleton"
         ],
-        "slots": {},
+        "slots": {
+          "description": {
+            "description": "Optional descriptive text beneath the heading. Renders in the header slot at body-subtle typography. Use for short metadata lines (timestamp, author, status sentence)."
+          },
+          "action": {
+            "description": "Trailing action cluster in the header (e.g. icon-buttons, menu trigger, more-options). Aligns to the header's flex-end edge."
+          },
+          "action-leading": {
+            "description": "Leading action cluster in the header (e.g. back button, switcher, breadcrumb-context). Aligns to the header's flex-start edge, before the icon/heading column."
+          },
+          "heading": {
+            "description": "Card title. Renders in the header slot with title typography. Typically a short noun phrase or document/object name."
+          },
+          "icon": {
+            "description": "Optional leading icon for the card header (status / brand / type marker). Renders next to the heading. Use `<icon-ui name=\"…\">` or any inline icon element."
+          }
+        },
         "states": [
           {
             "description": "Default, ready for interaction.",
@@ -6220,7 +6387,7 @@
           "default": false
         },
         "placement": {
-          "description": "Popover placement relative to the trigger.",
+          "description": "Popover placement relative to the trigger. Default `bottom` centers the color-picker panel under the swatch button (ADR-0034 Rule 2 — panel wider than trigger).",
           "type": "string",
           "enum": [
             "top",
@@ -6232,7 +6399,7 @@
             "bottom-start",
             "bottom-end"
           ],
-          "default": "bottom-start"
+          "default": "bottom"
         },
         "value": {
           "description": "Current color as a string in the active [format].",
@@ -7249,9 +7416,24 @@
           "Text"
         ],
         "slots": {
+          "description": {
+            "description": "Override the stamped description line below the heading. Author-fills with richer markup when the [description] attribute isn't enough."
+          },
           "default": {
             "description": "Optional rich content rendered above the description — supplementary\nlists, hints, or markup the [description] string can't carry.\n"
           },
+          "body": {
+            "description": "Dialog body region (between header and footer). For rich content — paragraphs, lists, embedded form fields. Distinct from [slot=\"default\"] which sits above [description] in the header region."
+          },
+          "footer": {
+            "description": "Wholesale override of the stamped footer (Cancel / Confirm action cluster). Use only for full custom-footer markup; otherwise the host's [cancel-text] / [confirm-text] / [confirm-variant] attrs drive the default footer rendering."
+          },
+          "header": {
+            "description": "Wholesale override of the stamped header (icon + heading + description cluster). Use only when full custom-header markup is needed; otherwise prefer the granular icon/heading/description slot overrides."
+          },
+          "heading": {
+            "description": "Override the stamped heading. Author-fillable when richer markup than the plain [text] string is needed (inline links, code spans, etc.)."
+          },
           "icon": {
             "description": "Override the [icon] glyph with a custom node (e.g. a colored\n<icon-ui>, an image, or arbitrary markup). Mutually exclusive\nwith [icon]; if a slot child is present, the [icon] attribute\nis ignored.\n"
           }
@@ -7306,6 +7488,163 @@
         "version": 1
       }
     },
+    "ContextMenu": {
+      "title": "ContextMenu",
+      "description": "Right-click activated menu — the OS-native context-menu pattern as a\nweb component. Distinct from `menu-ui` (which is button-triggered):\nsame item shape (`menu-item-ui` children), different trigger surface\n(`contextmenu` event), and pointer-anchored positioning instead of\nelement-anchored. Pattern: WAI-APG Menu.\n\nTwo binding modes:\n **A. Wrap.** Default-slot child becomes the target:\n `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.\n **B. Selector.** Point at one or more existing elements via [for]:\n `<context-menu-ui for=\"#my-table\">...items</context-menu-ui>`.\n\nOn `contextmenu` event on a target: `preventDefault()`, position the\nmenu at the pointer coords, show via Popover API. Touch long-press\n(configurable via [long-press-ms]) does the same. Shift+F10 / Menu\nkey opens at the focused target's center for keyboard users.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "component": {
+          "const": "ContextMenu"
+        },
+        "for": {
+          "description": "CSS selector(s) for target element(s). Empty = use default-slot child.",
+          "type": "string",
+          "default": ""
+        },
+        "long-press-ms": {
+          "description": "Long-press duration (ms) on touch devices to open the menu.",
+          "type": "number",
+          "default": 500
+        },
+        "open": {
+          "description": "Programmatic open state. Set true to open at target center.",
+          "type": "boolean",
+          "default": false
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "Wrap a target: `<context-menu-ui><my-target></my-target>...items</context-menu-ui>` OR point at one: `<context-menu-ui for=\"#my-target\">...items</context-menu-ui>`.",
+            "why": "No target binding — the menu never opens.",
+            "wrong": "<context-menu-ui>...just items...</context-menu-ui>"
+          }
+        ],
+        "category": "container",
+        "composes": [
+          "menu-item-ui"
+        ],
+        "events": {
+          "context-menu-close": {
+            "description": "Fired when the menu closes (item-select / outside-click / Escape).",
+            "detail": {
+              "reason": {
+                "description": "\"select\" | \"outside\" | \"escape\"",
+                "type": "string"
+              }
+            }
+          },
+          "context-menu-open": {
+            "description": "Fired when the menu opens (right-click / long-press / keyboard).",
+            "detail": {
+              "target": {
+                "description": "The target element the menu was opened on.",
+                "type": "Element"
+              },
+              "x": {
+                "description": "Pointer x coord (viewport-relative); null for keyboard activation.",
+                "type": "number"
+              },
+              "y": {
+                "description": "Pointer y coord; null for keyboard activation.",
+                "type": "number"
+              }
+            }
+          },
+          "context-menu-select": {
+            "description": "Fired when an item is activated. Same shape as menu-ui's `action` event.",
+            "detail": {
+              "text": {
+                "description": "Selected item's text.",
+                "type": "string"
+              },
+              "value": {
+                "description": "Selected item's value.",
+                "type": "string"
+              }
+            }
+          }
+        },
+        "examples": [
+          {
+            "description": "Right-click a file row for Open / Rename / Delete.",
+            "a2ui": "[\n  { \"id\": \"root\", \"component\": \"ContextMenu\", \"children\": [\"target\", \"item-open\", \"item-rename\", \"div\", \"item-delete\"] },\n  { \"id\": \"target\", \"component\": \"Text\", \"textContent\": \"Right-click me\" },\n  { \"id\": \"item-open\",   \"component\": \"MenuItem\", \"value\": \"open\",   \"text\": \"Open\" },\n  { \"id\": \"item-rename\", \"component\": \"MenuItem\", \"value\": \"rename\", \"text\": \"Rename\" },\n  { \"id\": \"div\",         \"component\": \"MenuDivider\" },\n  { \"id\": \"item-delete\", \"component\": \"MenuItem\", \"value\": \"delete\", \"text\": \"Delete\", \"variant\": \"danger\" }\n]\n",
+            "name": "file-actions"
+          }
+        ],
+        "keywords": [
+          "context-menu",
+          "right-click",
+          "menu",
+          "popup-menu"
+        ],
+        "name": "UIContextMenu",
+        "related": [
+          "menu",
+          "menu-item",
+          "popover"
+        ],
+        "slots": {
+          "default": {
+            "description": "Two-purpose slot: the wrapped target element (mode A — first\nnon-menu-item-ui child) AND the menu-item-ui items. Items are\npromoted to the popover surface on open.\n"
+          }
+        },
+        "states": [
+          {
+            "description": "Default. Menu closed; trigger listeners attached.",
+            "name": "idle"
+          },
+          {
+            "description": "Menu visible at pointer position; focus inside.",
+            "attribute": "open",
+            "name": "open"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "popup-menu": [
+            "menu",
+            "context-menu"
+          ],
+          "right-click": [
+            "context-menu"
+          ]
+        },
+        "tag": "context-menu-ui",
+        "tokens": {
+          "--context-menu-bg": {
+            "description": "Menu surface background color.",
+            "default": "var(--a-bg-subtle)"
+          },
+          "--context-menu-border": {
+            "description": "Menu surface border color.",
+            "default": "var(--a-border-subtle)"
+          },
+          "--context-menu-radius": {
+            "description": "Menu surface border radius.",
+            "default": "var(--a-radius-md)"
+          },
+          "--context-menu-shadow": {
+            "description": "Menu surface shadow.",
+            "default": "var(--a-shadow-lg)"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
     "DashboardLayout": {
       "title": "DashboardLayout",
       "description": "Module-tier dashboard-body composite. Crystallizes the recurring\n\"toolbar + KPI grid + chart area + table\" dashboard layout into a\nsingle primitive with four named regions (toolbar / kpis / charts /\ntable) plus an optional aside column. Each region is filled by\nconsumer-supplied <card-ui>s; the composite owns band sizing,\nresponsive breakpoints, and a [density] knob that propagates to\nevery descendant primitive via the parametric --a-density cascade.\n\nSits inside an <admin-page-body>; replaces the hand-rolled\n<col-ui gap=\"4\"> + nested <grid-ui> + <card-ui> chains every\nanalytics consumer reinvents today. Per ADR-0033 (Light-DOM\nsubstrate) — slot= attributes are decorative metadata; CSS rules\nmatch `:scope > [slot=\"X\"]` to position bands in DOM order.\n\nSpec: docs/specs/implementation-ready/SPEC-018-dashboard-layout.md.\n",
@@ -7633,6 +7972,21 @@
           "type": "string",
           "default": "Select range"
         },
+        "placement": {
+          "description": "Popover placement relative to the trigger. Default `bottom` centers the two-calendar panel under the trigger (ADR-0034 Rule 2 — ~800px panel >> trigger).",
+          "type": "string",
+          "enum": [
+            "top",
+            "bottom",
+            "left",
+            "right",
+            "top-start",
+            "top-end",
+            "bottom-start",
+            "bottom-end"
+          ],
+          "default": "bottom"
+        },
         "readonly": {
           "description": "Block edits; allow keyboard navigation for screen-reader inspection.",
           "type": "boolean",
@@ -8156,19 +8510,34 @@
           "type": "string",
           "default": "Select date and time"
         },
-        "precision": {
-          "description": "Time-pane precision. `minute` (default) emits `HH:mm`; `second` exposes the seconds segment and emits `HH:mm:ss`.",
+        "placement": {
+          "description": "Popover placement relative to the trigger. Default `bottom` centers the calendar+time panel under the trigger (ADR-0034 Rule 2 — ~600px panel >> trigger).",
           "type": "string",
           "enum": [
-            "minute",
-            "second"
-          ],
-          "default": "minute"
-        },
-        "readonly": {
-          "description": "Block edits; allow keyboard navigation for screen-reader inspection.",
-          "type": "boolean",
-          "default": false
+            "top",
+            "bottom",
+            "left",
+            "right",
+            "top-start",
+            "top-end",
+            "bottom-start",
+            "bottom-end"
+          ],
+          "default": "bottom"
+        },
+        "precision": {
+          "description": "Time-pane precision. `minute` (default) emits `HH:mm`; `second` exposes the seconds segment and emits `HH:mm:ss`.",
+          "type": "string",
+          "enum": [
+            "minute",
+            "second"
+          ],
+          "default": "minute"
+        },
+        "readonly": {
+          "description": "Block edits; allow keyboard navigation for screen-reader inspection.",
+          "type": "boolean",
+          "default": false
         },
         "step": {
           "description": "Per-Arrow-keypress increment in seconds for the time pane. 60 = minute precision (default), 900 = 15-minute, 1 = second precision.",
@@ -9825,8 +10194,17 @@
           "select"
         ],
         "slots": {
+          "description": {
+            "description": "Override slot for the description text. Use for multi-paragraph or richly-marked-up explanatory copy."
+          },
           "action": {
             "description": "User-provided action element (e.g. button) displayed below the description"
+          },
+          "heading": {
+            "description": "Override slot for the heading text. Use when richer markup than the plain [heading] attribute is needed (line breaks, inline links, bold emphasis)."
+          },
+          "icon": {
+            "description": "Override slot for the [icon] glyph. Use when the attribute-driven Phosphor icon isn't enough (e.g., custom SVG, illustration, or a styled icon-ui with non-default weight). Mutually exclusive with [icon]."
           }
         },
         "states": [
@@ -9983,6 +10361,11 @@
         }
       ],
       "properties": {
+        "action": {
+          "description": "Label of an inline action button (the \"deep-link\" / \"undo\" pattern).\nPair with `onAction` callback in `UIFeed.post()` — click invokes the\ncallback then auto-dismisses. Empty string renders no action button.\n",
+          "type": "string",
+          "default": ""
+        },
         "component": {
           "const": "FeedItem"
         },
@@ -10176,6 +10559,12 @@
           "action": {
             "description": "Button adjacent to the control for inline actions (clear, reset, help popover)."
           },
+          "error": {
+            "description": "Override slot for error markup richer than the plain [error] attribute string. Rendered below the control with danger-text styling. Mutually exclusive with [error]."
+          },
+          "hint": {
+            "description": "Override slot for hint markup richer than the plain [hint] attribute string (inline links, code spans, abbreviations). Rendered below the control at body-subtle typography. Mutually exclusive with [hint]."
+          },
           "trailing": {
             "description": "Secondary text or badge aligned with the label in the stacked layout (right-aligned) or between label and control in the inline layout."
           }
@@ -11273,6 +11662,163 @@
         "version": 1
       }
     },
+    "InlineEdit": {
+      "title": "InlineEdit",
+      "description": "Click-to-edit text in place. Renders as static text until clicked /\nfocused + Enter, then becomes editable. Enter or blur commits; Escape\ncancels and restores the original value. Form-participating.\n\nUse for editable titles, breadcrumb labels, table-cell text fields,\ndraft document names — any case where a user expects to edit text\nwithout opening a separate dialog or input. Distinct from `<input-ui>`\n(always-editable chrome) and from `<field-ui>` (stacked label + input\ncomposition). inline-edit reads as text in static state.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "commit": {
+          "description": "When to commit pending edits. `blur` (default) — saves on focusout\nor Enter. `enter` — Enter saves, blur cancels (returns to original).\n`manual` — only programmatic `commitEdit()` saves.\n",
+          "type": "string",
+          "enum": [
+            "blur",
+            "enter",
+            "manual"
+          ],
+          "default": "blur"
+        },
+        "component": {
+          "const": "InlineEdit"
+        },
+        "editing": {
+          "description": "Reflected state — `true` when the element is actively being edited.\nToggles automatically on click / Enter / blur / Escape; rarely set\nby consumers. Listen to `edit-start` / `edit-end` events instead.\n",
+          "type": "boolean",
+          "default": false
+        },
+        "placeholder": {
+          "description": "Hint text shown when the value is empty (inline-edit reads this in the static state).",
+          "type": "string",
+          "default": "Click to edit"
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<inline-edit-ui value=\"Title\" name=\"title\"> — reads as text in static state; chrome only appears while editing.",
+            "why": "Ghost variant still renders input chrome (border on focus). Looks like a control, not text.",
+            "wrong": "<input-ui value=\"Title\" name=\"title\" variant=\"ghost\">"
+          },
+          {
+            "fix": "<inline-edit-ui value=\"Title\">",
+            "why": "No state machine — no commit/cancel semantics, no form participation, no a11y wiring.",
+            "wrong": "<text-ui contenteditable>Title</text-ui>"
+          }
+        ],
+        "category": "form",
+        "composes": [],
+        "events": {
+          "cancel": {
+            "description": "Fired when Escape (or blur with commit=enter) restores the original. Bubbles."
+          },
+          "change": {
+            "description": "Fired after a successful commit. detail = { value, oldValue }. Bubbles."
+          },
+          "edit-end": {
+            "description": "Fired when leaving edit mode. detail = { committed: boolean }. Bubbles."
+          },
+          "edit-start": {
+            "description": "Fired when entering edit mode. Bubbles."
+          }
+        },
+        "examples": [
+          {
+            "description": "A draft document title that becomes editable on click.",
+            "a2ui": "[{ \"id\": \"title\", \"component\": \"InlineEdit\", \"value\": \"Untitled draft\" }]\n",
+            "name": "editable-title"
+          }
+        ],
+        "keywords": [
+          "inline-edit",
+          "editable",
+          "click-to-edit",
+          "rename",
+          "edit-in-place"
+        ],
+        "name": "UIInlineEdit",
+        "related": [
+          "input",
+          "field",
+          "text"
+        ],
+        "slots": {},
+        "states": [
+          {
+            "description": "Static — text reads as plain text with a hover hint.",
+            "name": "idle"
+          },
+          {
+            "description": "Hover affordance — subtle background tint signals editability.",
+            "name": "hover"
+          },
+          {
+            "description": "contenteditable — host is the input surface; outline + caret.",
+            "name": "editing"
+          },
+          {
+            "description": "Value is empty and not editing — placeholder text renders.",
+            "name": "empty"
+          },
+          {
+            "description": "Locked; click + keyboard activation are no-ops.",
+            "name": "disabled"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "inline-edit": [
+            "editable",
+            "click-to-edit",
+            "edit-in-place",
+            "rename-in-place"
+          ]
+        },
+        "tag": "inline-edit-ui",
+        "tokens": {
+          "--inline-edit-bg-edit": {
+            "description": "Background while editing.",
+            "default": "var(--a-bg)"
+          },
+          "--inline-edit-bg-hover": {
+            "description": "Background tint on hover (idle state).",
+            "default": "var(--a-bg-muted)"
+          },
+          "--inline-edit-outline": {
+            "description": "Outline color in the editing state.",
+            "default": "var(--a-accent-strong)"
+          },
+          "--inline-edit-placeholder": {
+            "description": "Placeholder text color in empty-static state.",
+            "default": "var(--a-fg-subtle)"
+          },
+          "--inline-edit-px": {
+            "description": "Horizontal padding (inner gutter so hover tint reads as a pill, not a flush block).",
+            "default": "var(--a-space-1)"
+          },
+          "--inline-edit-py": {
+            "description": "Vertical padding.",
+            "default": "var(--a-space-0-5)"
+          },
+          "--inline-edit-radius": {
+            "description": "Border-radius for the hover / editing chrome.",
+            "default": "var(--a-radius-sm)"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
     "InlineMessage": {
       "title": "InlineMessage",
       "description": "In-flow message glyph + text used in form-field rows for validation\nfeedback, hint copy, and inline confirmations. Distinguished from\n<alert-ui> (banner / surface-bearing notice) by carrying no surface\nfill, no border, no padding box — severity is foreground color +\nicon only. Variants map to severity (info / success / warning /\ndanger). Nests inside <field-ui>, <col-ui>, <row-ui> without\nbreaking field rhythm. Non-interactive annotation only.\n",
@@ -13428,7 +13974,14 @@
           "MenuItem",
           "TreeItem"
         ],
-        "slots": {},
+        "slots": {
+          "description": {
+            "description": "Override slot for richer description markup than the plain [description] attribute string (inline links, code spans, multiple lines). Renders beneath the primary text at body-subtle typography."
+          },
+          "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."
+          }
+        },
         "states": [],
         "status": "stable",
         "synonyms": {
@@ -13894,6 +14447,113 @@
         "version": 1
       }
     },
+    "Mark": {
+      "title": "Mark",
+      "description": "Highlighted inline text — token-driven theme-aware wrapper around the\nnative `<mark>` semantic. Use for search-result match highlighting,\ndiff additions in prose, \"new since last visit\" emphasis, and any\ninline text that needs a visual rail without changing its weight.\n\nDistinct from `<text-ui strong>` (semantic emphasis via weight) and\nfrom `<tag-ui>` (block-shaped pill chrome). mark-ui keeps the inline\ntext flow intact — same line-height, same baseline — just paints a\nbackground highlight behind the matched span.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "component": {
+          "const": "Mark"
+        },
+        "variant": {
+          "description": "Highlight color variant. Default `warning` is the conventional yellow-marker tone.",
+          "type": "string",
+          "enum": [
+            "warning",
+            "info",
+            "success",
+            "danger",
+            "muted"
+          ],
+          "default": "warning"
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<mark-ui>matched</mark-ui> — same semantic role but theme-aware.",
+            "why": "Native <mark> uses UA default (yellow-on-white) that doesn't adapt to theme — invisible in dark mode + jarring in light mode.",
+            "wrong": "<mark>matched</mark>"
+          }
+        ],
+        "category": "typography",
+        "composes": [],
+        "events": {},
+        "examples": [
+          {
+            "description": "Highlight the search query within a result title.",
+            "a2ui": "[\n  { \"id\": \"row\", \"component\": \"Row\", \"children\": [\"pre\", \"mk\", \"post\"] },\n  { \"id\": \"pre\", \"component\": \"Text\", \"textContent\": \"Quarterly \" },\n  { \"id\": \"mk\",  \"component\": \"Mark\", \"textContent\": \"revenue\" },\n  { \"id\": \"post\", \"component\": \"Text\", \"textContent\": \" report — Q4 2025\" }\n]\n",
+            "name": "search-match"
+          }
+        ],
+        "keywords": [
+          "mark",
+          "highlight",
+          "search-match",
+          "emphasis"
+        ],
+        "name": "UIMark",
+        "related": [
+          "text",
+          "tag"
+        ],
+        "slots": {
+          "default": {
+            "description": "The text content to highlight (plain text or inline elements)."
+          }
+        },
+        "states": [
+          {
+            "description": "Default — highlighted background painted behind the slotted text.",
+            "name": "idle"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "highlight": [
+            "mark",
+            "emphasis"
+          ],
+          "search-match": [
+            "mark",
+            "highlight"
+          ]
+        },
+        "tag": "mark-ui",
+        "tokens": {
+          "--mark-bg": {
+            "description": "Background color of the highlight.",
+            "default": "var(--a-warning-muted)"
+          },
+          "--mark-fg": {
+            "description": "Foreground (text) color inside the highlight.",
+            "default": "var(--a-warning-text)"
+          },
+          "--mark-px": {
+            "description": "Horizontal padding around the highlighted text.",
+            "default": "var(--a-space-0-5)"
+          },
+          "--mark-radius": {
+            "description": "Border radius of the highlight box.",
+            "default": "var(--a-radius-xs)"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
     "Menu": {
       "title": "Menu",
       "description": "Dropdown action menu with roving focus and keyboard navigation. Uses Popover API.",
@@ -14273,6 +14933,15 @@
         "slots": {
           "default": {
             "description": "Content placed inside the modal surface. Accepts any elements (card-ui, command-ui, custom markup)."
+          },
+          "body": {
+            "description": "Main body region for prose, forms, or arbitrary content. Sits between header and footer; scrolls when content overflows."
+          },
+          "footer": {
+            "description": "Optional footer region rendered below the body, typically for action buttons. Author-fills with Confirm / Cancel buttons or similar trailing affordances."
+          },
+          "header": {
+            "description": "Optional header region rendered above the body. Author-fillable with title + supporting markup. CSS positions it at the top of the modal surface with consistent padding + the dismiss-close affordance."
           }
         },
         "states": [
@@ -14547,6 +15216,9 @@
           },
           "header": {
             "description": "Optional custom header. Auto-generated when missing."
+          },
+          "icon": {
+            "description": "Override the leading [icon] glyph in the auto-generated header with a custom slotted element. Mutually exclusive with the [icon] attribute."
           }
         },
         "states": [
@@ -14678,6 +15350,9 @@
         "slots": {
           "default": {
             "description": "Optional override of the default icon + text + badge stamping."
+          },
+          "icon": {
+            "description": "Override the leading [icon] glyph with a custom slotted element (custom icon-ui, image, avatar). Mutually exclusive with the [icon] attribute — slot child wins."
           }
         },
         "states": [
@@ -15145,9 +15820,9 @@
         "version": 1
       }
     },
-    "OnboardingChecklist": {
-      "title": "OnboardingChecklist",
-      "description": "Module-tier onboarding checklist — a progressive setup-step widget\n(\"Getting started\" card seen in Stripe / Linear / Vercel dashboards).\nComposes <progress-ui> (top fill bar), <list-ui> + <list-item-ui>\n(the step rows), <check-ui> (per-item completion checkbox), and\noptional <button-ui> (per-item action CTA).\n\nOwns the data model (items: array of {id, label, description, href,\ndone}), the persistence contract (storage-key writes a JSON blob to\nlocalStorage / sessionStorage), the auto-computed progress display,\nand the dismiss-on-complete behavior. Items are data, not slotted\nmarkup — host wiring uses stable per-item ids, not DOM positions.\n\nUse for the \"card of optional setup tasks\" case; use <step-progress-ui>\nfor horizontal multi-screen wizards where the user is locked into\nlinear progression.\n",
+    "NumberFormat": {
+      "title": "NumberFormat",
+      "description": "Display a numeric value with locale-aware formatting — currency,\npercentage, compact (1.2K / 3.4M), unit, or plain decimal. Wraps\n`Intl.NumberFormat`. Distinct from `<input-ui type=\"number\">`\n(an INPUT primitive); this is a DISPLAY primitive — read-only, no\nform participation, no keyboard handling. Pair with `<stat-ui>` for\nKPI surfaces or use standalone inline within prose.\n",
       "type": "object",
       "allOf": [
         {
@@ -15158,44 +15833,222 @@
         }
       ],
       "properties": {
-        "title": {
-          "description": "Header label above the progress bar. Defaults to \"Get started\".",
+        "compactDisplay": {
+          "description": "When [notation=\"compact\"], controls the compact-form length.\n`short` = \"1.2M\" (default); `long` = \"1.2 million\".\n",
           "type": "string",
-          "default": "Get started"
-        },
-        "items": {
-          "description": "Step list — each item is { id, label, description?, href?, done? }. Required, non-empty.",
-          "$ref": "#/$defs/DynamicStringList"
-        },
-        "collapsed": {
-          "description": "Initial / current collapsed state — hides the item list, keeps progress + header visible.",
-          "$ref": "#/$defs/DynamicBoolean"
-        },
-        "collapsible": {
-          "description": "Show a top-right collapse toggle.",
-          "type": "boolean",
-          "default": true
+          "enum": [
+            "short",
+            "long"
+          ],
+          "default": "short"
         },
         "component": {
-          "const": "OnboardingChecklist"
-        },
-        "dismiss-on-complete": {
-          "description": "Auto-hide the widget when all items are done.",
-          "type": "boolean",
-          "default": true
+          "const": "NumberFormat"
         },
-        "storage": {
-          "description": "Persistence backend when storage-key is set.",
+        "currency": {
+          "description": "ISO 4217 currency code (e.g. \"USD\", \"EUR\", \"JPY\"). Required when\n[number-style=\"currency\"]; ignored otherwise.\n",
           "type": "string",
-          "enum": [
-            "local",
-            "session",
-            "none"
-          ],
-          "default": "local"
+          "default": ""
         },
-        "storage-key": {
-          "description": "localStorage key for per-item completion persistence. Empty string disables storage (ephemeral).",
+        "locale": {
+          "description": "BCP-47 locale tag for the formatter. Empty defaults to the\ndocument locale (`<html lang>`) then to browser default.\n",
+          "type": "string",
+          "default": ""
+        },
+        "maximumFractionDigits": {
+          "description": "Maximum fractional digits (0–20). Default `2` for decimal/\ncurrency/percent, `1` for compact notation.\n",
+          "type": "number",
+          "default": 2
+        },
+        "minimumFractionDigits": {
+          "description": "Minimum fractional digits (0–20). Padded with trailing zeros.\nUseful for currency display to force \".00\" suffix.\n",
+          "type": "number",
+          "default": 0
+        },
+        "notation": {
+          "description": "`Intl.NumberFormat` `notation` option. `standard` is the\nthousands-grouped form (1,234,567); `compact` is the abbreviated\nform (1.2M); `scientific` and `engineering` are the exponent\nforms. Defaults to `standard`.\n",
+          "type": "string",
+          "enum": [
+            "standard",
+            "compact",
+            "scientific",
+            "engineering"
+          ],
+          "default": "standard"
+        },
+        "numberStyle": {
+          "description": "`Intl.NumberFormat` `style` option. `decimal` (default) renders a\nplain number with locale-aware grouping. `currency` requires\n[currency] to be set. `percent` formats 0–1 as 0%–100%. `unit`\nrequires [unit] to be set (e.g. \"kilobyte\", \"celsius\").\n",
+          "type": "string",
+          "enum": [
+            "decimal",
+            "currency",
+            "percent",
+            "unit"
+          ],
+          "default": "decimal"
+        },
+        "signDisplay": {
+          "description": "`Intl.NumberFormat` `signDisplay` option. `auto` (default) shows\n\"−\" for negatives only; `always` shows \"+\" / \"−\"; `exceptZero`\nshows sign for non-zero only; `never` hides signs.\n",
+          "type": "string",
+          "enum": [
+            "auto",
+            "always",
+            "exceptZero",
+            "never"
+          ],
+          "default": "auto"
+        },
+        "unit": {
+          "description": "`Intl.NumberFormat` unit identifier (e.g. \"kilometer-per-hour\",\n\"celsius\", \"byte\"). Required when [number-style=\"unit\"]; ignored\notherwise. See MDN's NumberFormat docs for the valid set.\n",
+          "type": "string",
+          "default": ""
+        },
+        "value": {
+          "description": "The numeric value to format. Empty string or non-numeric value\nrenders nothing.\n",
+          "type": "number",
+          "default": 0
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<number-format-ui value=\"0.5\" number-style=\"percent\"></number-format-ui>\n",
+            "why": "Renders \"5,000%\" — Intl.NumberFormat percent style multiplies the\ninput by 100. value=50 means \"5000%\".\n",
+            "wrong": "<number-format-ui value=\"50\" number-style=\"percent\"></number-format-ui>\n"
+          },
+          {
+            "fix": "<number-format-ui value=\"9.99\" number-style=\"currency\" currency=\"USD\"></number-format-ui>\n",
+            "why": "Missing [currency] code. Renders nothing rather than producing\nmalformed currency output.\n",
+            "wrong": "<number-format-ui value=\"9.99\" number-style=\"currency\"></number-format-ui>\n"
+          }
+        ],
+        "category": "display",
+        "composes": [],
+        "events": {},
+        "examples": [
+          {
+            "description": "Plain locale-grouped number — default style.",
+            "a2ui": "[\n  {\n    \"id\": \"n\",\n    \"component\": \"NumberFormat\",\n    \"value\": 1234567.89\n  }\n]\n",
+            "name": "decimal"
+          },
+          {
+            "description": "USD currency display.",
+            "a2ui": "[\n  {\n    \"id\": \"n\",\n    \"component\": \"NumberFormat\",\n    \"value\": 1299.99,\n    \"numberStyle\": \"currency\",\n    \"currency\": \"USD\"\n  }\n]\n",
+            "name": "currency"
+          },
+          {
+            "description": "Fraction → percent (0.876 → 87.6%).",
+            "a2ui": "[\n  {\n    \"id\": \"n\",\n    \"component\": \"NumberFormat\",\n    \"value\": 0.876,\n    \"numberStyle\": \"percent\",\n    \"maximumFractionDigits\": 1\n  }\n]\n",
+            "name": "percent"
+          },
+          {
+            "description": "Compact-form (1.2M, 3.4K).",
+            "a2ui": "[\n  {\n    \"id\": \"n\",\n    \"component\": \"NumberFormat\",\n    \"value\": 1234567,\n    \"notation\": \"compact\"\n  }\n]\n",
+            "name": "compact"
+          }
+        ],
+        "keywords": [
+          "number-format",
+          "format",
+          "currency",
+          "percent",
+          "percentage",
+          "compact",
+          "number",
+          "locale",
+          "intl"
+        ],
+        "name": "UINumberFormat",
+        "related": [
+          "stat",
+          "text",
+          "badge",
+          "input"
+        ],
+        "slots": {},
+        "states": [
+          {
+            "description": "Default, displaying the formatted value.",
+            "name": "idle"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "currency": [
+            "number-format",
+            "money",
+            "price"
+          ],
+          "number": [
+            "number-format",
+            "format"
+          ],
+          "percent": [
+            "number-format",
+            "percentage"
+          ]
+        },
+        "tag": "number-format-ui",
+        "tokens": {},
+        "traits": [],
+        "version": 1
+      }
+    },
+    "OnboardingChecklist": {
+      "title": "OnboardingChecklist",
+      "description": "Module-tier onboarding checklist — a progressive setup-step widget\n(\"Getting started\" card seen in Stripe / Linear / Vercel dashboards).\nComposes <progress-ui> (top fill bar), <list-ui> + <list-item-ui>\n(the step rows), <check-ui> (per-item completion checkbox), and\noptional <button-ui> (per-item action CTA).\n\nOwns the data model (items: array of {id, label, description, href,\ndone}), the persistence contract (storage-key writes a JSON blob to\nlocalStorage / sessionStorage), the auto-computed progress display,\nand the dismiss-on-complete behavior. Items are data, not slotted\nmarkup — host wiring uses stable per-item ids, not DOM positions.\n\nUse for the \"card of optional setup tasks\" case; use <step-progress-ui>\nfor horizontal multi-screen wizards where the user is locked into\nlinear progression.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "title": {
+          "description": "Header label above the progress bar. Defaults to \"Get started\".",
+          "type": "string",
+          "default": "Get started"
+        },
+        "items": {
+          "description": "Step list — each item is { id, label, description?, href?, done? }. Required, non-empty.",
+          "$ref": "#/$defs/DynamicStringList"
+        },
+        "collapsed": {
+          "description": "Initial / current collapsed state — hides the item list, keeps progress + header visible.",
+          "$ref": "#/$defs/DynamicBoolean"
+        },
+        "collapsible": {
+          "description": "Show a top-right collapse toggle.",
+          "type": "boolean",
+          "default": true
+        },
+        "component": {
+          "const": "OnboardingChecklist"
+        },
+        "dismiss-on-complete": {
+          "description": "Auto-hide the widget when all items are done.",
+          "type": "boolean",
+          "default": true
+        },
+        "storage": {
+          "description": "Persistence backend when storage-key is set.",
+          "type": "string",
+          "enum": [
+            "local",
+            "session",
+            "none"
+          ],
+          "default": "local"
+        },
+        "storage-key": {
+          "description": "localStorage key for per-item completion persistence. Empty string disables storage (ephemeral).",
           "type": "string",
           "default": ""
         },
@@ -15301,6 +16154,9 @@
           "StepProgress"
         ],
         "slots": {
+          "description": {
+            "description": "Optional subtitle / supporting prose rendered beneath the header. Renders at body-subtle typography. Use for richer markup than the plain [description] attribute string."
+          },
           "complete": {
             "description": "Content shown when all items are done and dismiss-on-complete is false."
           },
@@ -15930,14 +16786,28 @@
           "type": "number",
           "default": 1
         },
+        "size": {
+          "description": "Universal size — threads through to every nested `<button-ui size=…>`\nso pagination honors the substrate's 24/30/36 px size system\n(with [density] modifier). Default `md` matches `<button-ui>`'s\ndefault; pass `size=\"sm\"` for a denser numbered row.\n",
+          "type": "string",
+          "enum": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md"
+        },
         "total": {
           "description": "Total number of pages.",
           "type": "number",
           "default": 1
         },
         "variant": {
-          "description": "Visual variant",
+          "description": "Visual variant — `default` (ghost buttons w/ hover bg) or `button` (1×1 bordered cells; active page filled).",
           "type": "string",
+          "enum": [
+            "default",
+            "button"
+          ],
           "default": "default"
         }
       },
@@ -15948,7 +16818,10 @@
       "x-adiaui": {
         "anti_patterns": [],
         "category": "navigation",
-        "composes": [],
+        "composes": [
+          "button-ui",
+          "icon-ui"
+        ],
         "events": {
           "page-change": {
             "description": "Fired when a page button is clicked. detail contains { page }.",
@@ -16133,6 +17006,156 @@
         "version": 1
       }
     },
+    "PasswordStrength": {
+      "title": "PasswordStrength",
+      "description": "Visual strength indicator for password inputs — 4-segment bar (weak /\nfair / good / strong) computed from a heuristic combining length,\ncharacter-class diversity, and repeat-pattern penalty. Pairs with\n`<input-ui type=\"password\">` via JS:\n  input.addEventListener('input', e => meter.value = e.target.value)\nRead-only display primitive — no form participation. Emits a\n`score-change` event when the bucket changes so consumers can gate\na submit button on `detail.satisfied` (score ≥ min-score).\n\n**Security note:** [value] is held as a JS property only, NOT\nreflected to a DOM attribute. The element stamps the bar + label\nfrom the property; the password never appears in the rendered HTML.\nDo not set the value via setAttribute (it will be no-op).\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "component": {
+          "const": "PasswordStrength"
+        },
+        "minScore": {
+          "description": "Minimum acceptable score (0–3). The `score-change` event's\n`detail.satisfied` boolean reflects whether the current score\nmeets this threshold. Useful for gating a submit button.\n",
+          "type": "number",
+          "default": 2
+        },
+        "showLabel": {
+          "description": "Display the textual score label (\"Weak\" / \"Fair\" / \"Good\" /\n\"Strong\") below the bar. Defaults to true.\n",
+          "type": "boolean",
+          "default": true
+        },
+        "value": {
+          "description": "The password string to score. JS-property only — NOT reflected\nto a DOM attribute (so the password never leaks into rendered\nHTML). Wire to an input via `input.addEventListener('input', e =>\nmeter.value = e.target.value)`.\n",
+          "$ref": "#/$defs/DynamicString"
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<password-strength-ui id=\"m\"></password-strength-ui>\n<script>document.getElementById('m').value = pwd;</script>\n",
+            "why": "`value` is JS-property only; the attribute is ignored. The\npassword also shouldn't be authored into HTML at all (server\ntemplate / static page) — that defeats the purpose.\n",
+            "wrong": "<password-strength-ui value=\"hunter2\"></password-strength-ui>\n"
+          }
+        ],
+        "category": "display",
+        "composes": [],
+        "events": {
+          "score-change": {
+            "description": "Fired when the computed score crosses a bucket boundary (not on every keystroke). Detail carries the new score + label + satisfied flag.",
+            "detail": {
+              "label": "string",
+              "satisfied": "boolean",
+              "score": "number"
+            }
+          }
+        },
+        "examples": [
+          {
+            "description": "Standard pairing with input-ui[type=password] via input listener.",
+            "a2ui": "[\n  {\n    \"id\": \"field\",\n    \"component\": \"Field\",\n    \"label\": \"Password\",\n    \"children\": [\"pwd\", \"meter\"]\n  },\n  {\n    \"id\": \"pwd\",\n    \"component\": \"Input\",\n    \"type\": \"password\",\n    \"name\": \"password\"\n  },\n  {\n    \"id\": \"meter\",\n    \"component\": \"PasswordStrength\"\n  }\n]\n",
+            "name": "paired-with-input"
+          }
+        ],
+        "keywords": [
+          "password-strength",
+          "strength-meter",
+          "password",
+          "strength",
+          "meter",
+          "security"
+        ],
+        "name": "UIPasswordStrength",
+        "related": [
+          "input",
+          "field",
+          "progress"
+        ],
+        "slots": {
+          "default": {
+            "description": "Optional area for requirements checklist content (e.g. <ul> of \"at least 8 characters\", \"mixed case\", etc.)."
+          }
+        },
+        "states": [
+          {
+            "description": "Default — no value set, all segments grey.",
+            "name": "idle"
+          },
+          {
+            "description": "Value present; segments lit per score 0..3.",
+            "attribute": "data-score",
+            "name": "scored"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "password": [
+            "password-strength",
+            "strength-meter"
+          ],
+          "strength": [
+            "password-strength",
+            "meter"
+          ]
+        },
+        "tag": "password-strength-ui",
+        "tokens": {
+          "--password-strength-color-fair": {
+            "description": "Color for score=1 lit segments.",
+            "default": "var(--a-warning-bg)"
+          },
+          "--password-strength-color-good": {
+            "description": "Color for score=2 lit segments.",
+            "default": "var(--a-info-bg)"
+          },
+          "--password-strength-color-strong": {
+            "description": "Color for score=3 lit segments.",
+            "default": "var(--a-success-bg)"
+          },
+          "--password-strength-color-weak": {
+            "description": "Color for score=0 lit segments.",
+            "default": "var(--a-danger-bg)"
+          },
+          "--password-strength-gap": {
+            "description": "Gap between segments.",
+            "default": "var(--a-space-1)"
+          },
+          "--password-strength-label-fg": {
+            "description": "Label text color.",
+            "default": "var(--a-fg-muted)"
+          },
+          "--password-strength-label-size": {
+            "description": "Label font size.",
+            "default": "var(--a-ui-sm)"
+          },
+          "--password-strength-radius": {
+            "description": "Segment border radius.",
+            "default": "var(--a-radius-full)"
+          },
+          "--password-strength-segment-bg": {
+            "description": "Unlit segment background (track color).",
+            "default": "var(--a-canvas-1-scrim)"
+          },
+          "--password-strength-segment-height": {
+            "description": "Height of each bar segment.",
+            "default": "4px"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
     "PaymentMethodForm": {
       "title": "PaymentMethodForm",
       "description": "Form-participating composite for capturing a payment method —\ncard number, expiry, CVC, name on card, billing address (optional),\nand country. The form chrome + structured validation + a single\nnormalized emit event; it does NOT integrate with Stripe Elements\nor a tokenization SDK directly (consumer responsibility).\n\nEach sub-field is a <field-ui> wrapper around an <input-ui> (or\n<select-ui> for country). Card number is Luhn-validated; expiry is\nparsed as MM/YY with month + year bounds; CVC is 3-4 digits.\nBrand detection (visa / mastercard / amex / discover) runs against\na small regex map and surfaces via the `change` event detail.\n\nForm value is a JSON-encoded payload of normalized field values\nserialized through ElementInternals under [name] (default\n\"paymentMethod\"). On submit, the host fires\n`submit-payment-method` with a flat detail\n`{ token, last4, brand, expMonth, expYear, name, country }`.\n`token` is a synthetic local-mode token (sha-like opaque string);\nconsumers integrating with a real processor handle tokenization\nin their own submit listener using `last4` / `brand` / etc.\n\nSpec: docs/specs/implementation-ready/SPEC-009-payment-method-form.md.\n",
@@ -17633,6 +18656,158 @@
         "version": 1
       }
     },
+    "QRCode": {
+      "title": "QRCode",
+      "description": "Inline QR code generator — renders a scannable code as inline SVG.\nTwo modes:\n\n**A. Auto-encode (default).** Set `[value]` to a string (URL, plain\ntext, share link, 2FA secret). The component encodes the data with\nthe built-in zero-deps QR encoder (byte mode, ECC level configurable,\nversions 1–10 up to ~150 byte chars) and renders an SVG.\n\n**B. Bring-your-own matrix.** Set `[matrix]` to a JSON string of a\n2-D 0/1 array (`[[1,0,1,...],[...],...]`). The component renders the\nsupplied matrix directly without invoking its own encoder. Use this\nwhen you need versions 11–40, kanji/alphanumeric mode, or any\nencoder feature beyond the built-in. When both `[value]` and\n`[matrix]` are set, the matrix wins (BYO override).\n\nOutput is a single `<svg>` with `viewBox=\"0 0 N N\"`. Crisp-edges\nrendering preserves the scannable cell boundaries at any size.\nSizing is controlled by the `[size]` prop (host CSS-pixel dimension);\ninternal cell size is computed from `size / (matrix-size + 2 ·\nmargin)`. ARIA: `role=\"img\"` with `aria-label` (default \"QR code\"\nor the `[label]` prop).\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "background": {
+          "description": "Background (light-cell) color. **Empty defaults to `#ffffff` —\nhardcoded white** alongside the black foreground, for guaranteed\nscanability. Override only when paired with an explicit\n[color] (the contrast pair must scan).\n",
+          "type": "string",
+          "default": ""
+        },
+        "color": {
+          "description": "Foreground (dark-cell) color. Any CSS color string (hex, rgb,\ntoken reference). **Empty defaults to `#000000` — hardcoded black\nfor guaranteed scanability** (theme-aware `currentColor` would\nproduce light-on-dark in dark mode, which most phone scanners\nrefuse to decode). Override for branded QRs only when you've\nverified the chosen color/background pair scans on the target\ndevices.\n",
+          "type": "string",
+          "default": ""
+        },
+        "component": {
+          "const": "QRCode"
+        },
+        "errorCorrection": {
+          "description": "Error-correction level (auto-encode mode only). `L` (7% recovery),\n`M` (15%, default), `Q` (25%), `H` (30%). Higher levels recover\nfrom more damage at the cost of QR-version size growth.\n",
+          "type": "string",
+          "enum": [
+            "L",
+            "M",
+            "Q",
+            "H"
+          ],
+          "default": "M"
+        },
+        "label": {
+          "description": "`aria-label` for the SVG. Defaults to \"QR code\". Customize for\nbetter AT context (e.g. \"Share link QR code\", \"2FA setup QR\").\n",
+          "type": "string",
+          "default": "QR code"
+        },
+        "margin": {
+          "description": "Quiet zone in cells around the QR pattern. QR spec requires a\nminimum 4-cell margin for reliable scanning; smaller values may\nnot scan on some devices. Default `4`.\n",
+          "type": "number",
+          "default": 4
+        },
+        "matrix": {
+          "description": "BYO precomputed bit matrix as JSON — a 2-D array of 0/1\n(`[[1,0,...],[0,1,...],...]`). When set, the built-in encoder is\nbypassed and this matrix renders directly. Useful for QR variants\nthe built-in doesn't support (versions 11–40, alphanumeric mode,\nkanji, etc.) — bring your own encoder, pass the matrix here.\n",
+          "type": "string",
+          "default": ""
+        },
+        "size": {
+          "description": "Host display size in CSS pixels (width and height; the SVG is\nalways square). Default 200. Internal cell size is computed from\nthis divided by `matrix-size + 2·margin`.\n",
+          "type": "number",
+          "default": 200
+        },
+        "value": {
+          "description": "The string to encode (URL / text / share link / 2FA seed). When\n[matrix] is also set, the matrix wins. Empty value + empty matrix\nrenders nothing.\n",
+          "type": "string",
+          "default": ""
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "Drop the ECC level (lower L gives more capacity for the same\nversion), OR shorten the URL (use a URL shortener), OR encode\nwith a BYO encoder library + pass the [matrix]:\n`<qr-code-ui matrix=\"[[1,0,1,...],...]\"></qr-code-ui>`\n",
+            "why": "Built-in encoder covers versions 1–10. Data beyond v10 capacity\nthrows + renders empty + sets [data-error]. Console warns with\nthe byte length so consumers can diagnose.\n",
+            "wrong": "<qr-code-ui value=\"https://very.long.url.that.exceeds.150.bytes.of.utf8.encoded.length...\"></qr-code-ui>\n"
+          },
+          {
+            "fix": "<qr-code-ui value=\"...\" margin=\"4\"></qr-code-ui>\n",
+            "why": "Zero margin breaks scanning. QR spec requires a 4-cell quiet\nzone for reliable detection.\n",
+            "wrong": "<qr-code-ui value=\"...\" margin=\"0\"></qr-code-ui>\n"
+          }
+        ],
+        "category": "display",
+        "composes": [],
+        "events": {},
+        "examples": [
+          {
+            "description": "Plain URL encoding at default size + ECC-M.",
+            "a2ui": "[\n  {\n    \"id\": \"q\",\n    \"component\": \"QRCode\",\n    \"value\": \"https://example.com\"\n  }\n]\n",
+            "name": "default"
+          },
+          {
+            "description": "Custom colors matching brand chrome.",
+            "a2ui": "[\n  {\n    \"id\": \"q\",\n    \"component\": \"QRCode\",\n    \"value\": \"https://adia.health/share/abc123\",\n    \"size\": 280,\n    \"color\": \"#1e293b\",\n    \"background\": \"#ffffff\",\n    \"errorCorrection\": \"Q\"\n  }\n]\n",
+            "name": "branded"
+          },
+          {
+            "description": "BYO precomputed matrix from an external encoder.",
+            "a2ui": "[\n  {\n    \"id\": \"q\",\n    \"component\": \"QRCode\",\n    \"matrix\": \"[[1,1,1,1,1,1,1,0,1,...]...]\",\n    \"size\": 200,\n    \"label\": \"Boarding pass QR\"\n  }\n]\n",
+            "name": "byo-matrix"
+          }
+        ],
+        "keywords": [
+          "qr-code",
+          "qr",
+          "barcode",
+          "scan",
+          "share",
+          "2fa",
+          "share-link"
+        ],
+        "name": "UIQRCode",
+        "related": [
+          "link",
+          "share"
+        ],
+        "slots": {},
+        "states": [
+          {
+            "description": "Default — QR rendered (or empty if no value/matrix).",
+            "name": "idle"
+          },
+          {
+            "description": "Auto-encode failed (data too long for v1–10 at requested ECC). Renders an empty placeholder; logs a console warning. Switch to a BYO matrix from an external encoder, or downgrade the ECC level.",
+            "attribute": "data-error",
+            "name": "error"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "qr": [
+            "qr-code",
+            "barcode"
+          ],
+          "scan": [
+            "qr-code",
+            "barcode"
+          ]
+        },
+        "tag": "qr-code-ui",
+        "tokens": {
+          "--qr-code-bg": {
+            "description": "Background (light) color when [background] is empty.",
+            "default": "transparent"
+          },
+          "--qr-code-fg": {
+            "description": "Foreground (dark) color when [color] is empty.",
+            "default": "currentColor"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
     "Radio": {
       "title": "Radio",
       "description": "Radio button with pure CSS dot. Groups by name attribute (one selected value per group); form-associated and emits standard change events. Use for single-select option groups in forms; for richer styling or button-style options use <segment-ui> inside <segmented-ui> instead.",
@@ -18103,40 +19278,158 @@
           "[object Object]": {
             "description": "Fired on [object Object]."
           }
-        },
-        "examples": [],
+        },
+        "examples": [],
+        "keywords": [
+          "rating",
+          "stars",
+          "review",
+          "feedback",
+          "score",
+          "vote",
+          "heart",
+          "like"
+        ],
+        "name": "UIRating",
+        "related": [
+          "Field",
+          "AgentFeedbackBar"
+        ],
+        "slots": {},
+        "states": [
+          {
+            "description": "Default, ready for interaction.",
+            "name": "idle"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "rating": [
+            "rating",
+            "star rating",
+            "review score",
+            "feedback rating"
+          ]
+        },
+        "tag": "rating-ui",
+        "tokens": {},
+        "traits": [],
+        "version": 1
+      }
+    },
+    "RelativeTime": {
+      "title": "RelativeTime",
+      "description": "Display a timestamp as a human-readable relative time — \"3 hours ago\",\n\"in 2 days\", \"yesterday\". Wraps `Intl.RelativeTimeFormat` for i18n\n+ auto-updates on a configurable interval (default every 60 s) so\nrendered text stays current without re-mounting.\n\nSet `[datetime]` to an ISO 8601 timestamp; the element computes the\ndelta against `Date.now()` and renders the formatted string. Pair\nwith a `title` for full-precision-on-hover (the element sets one\nautomatically from a default locale-aware long format unless you\noverride).\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "component": {
+          "const": "RelativeTime"
+        },
+        "datetime": {
+          "description": "ISO 8601 timestamp (e.g. `2026-05-25T09:30:00Z`) or any string\nparseable by `Date`. Required for output — empty value renders\nnothing.\n",
+          "type": "string",
+          "default": ""
+        },
+        "locale": {
+          "description": "BCP-47 locale tag for the formatter. Empty defaults to the document\nlocale (`<html lang>`) then to the browser default.\n",
+          "type": "string",
+          "default": ""
+        },
+        "numeric": {
+          "description": "`Intl.RelativeTimeFormat` `numeric` option. `auto` lets the\nformatter substitute \"yesterday\" / \"tomorrow\" for ±1 day deltas;\n`always` keeps the numeric form (\"1 day ago\"). Defaults to `auto`.\n",
+          "type": "string",
+          "enum": [
+            "auto",
+            "always"
+          ],
+          "default": "auto"
+        },
+        "timeStyle": {
+          "description": "`Intl.RelativeTimeFormat` `style` option. `long` = \"3 hours ago\",\n`short` = \"3 hr. ago\", `narrow` = \"3h ago\". Defaults to `long`.\n",
+          "type": "string",
+          "enum": [
+            "long",
+            "short",
+            "narrow"
+          ],
+          "default": "long"
+        },
+        "updateInterval": {
+          "description": "Auto-refresh interval in seconds. The component restarts a\n`setInterval` tick that re-reads `Date.now()` and re-renders the\nrelative string. Set to `0` to disable auto-update (static\nrender). Default `60` (one minute) is the natural cadence for\n\"minutes ago\" granularity.\n",
+          "type": "number",
+          "default": 60
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [],
+        "category": "display",
+        "composes": [],
+        "events": {},
+        "examples": [
+          {
+            "description": "A timestamp rendered as a long relative phrase, auto-updating every 60 s.",
+            "a2ui": "[\n  {\n    \"id\": \"ts\",\n    \"component\": \"RelativeTime\",\n    \"datetime\": \"2026-05-25T09:00:00Z\"\n  }\n]\n",
+            "name": "default"
+          },
+          {
+            "description": "Tight UI affordances — narrow form for chat bubble timestamps.",
+            "a2ui": "[\n  {\n    \"id\": \"ts\",\n    \"component\": \"RelativeTime\",\n    \"datetime\": \"2026-05-25T11:30:00Z\",\n    \"timeStyle\": \"narrow\"\n  }\n]\n",
+            "name": "short-narrow"
+          },
+          {
+            "description": "A historical timestamp that doesn't need to tick (commit log row).",
+            "a2ui": "[\n  {\n    \"id\": \"ts\",\n    \"component\": \"RelativeTime\",\n    \"datetime\": \"2025-11-01T00:00:00Z\",\n    \"updateInterval\": 0\n  }\n]\n",
+            "name": "static-historical"
+          }
+        ],
         "keywords": [
-          "rating",
-          "stars",
-          "review",
-          "feedback",
-          "score",
-          "vote",
-          "heart",
-          "like"
+          "relative-time",
+          "timeago",
+          "time",
+          "timestamp",
+          "ago",
+          "elapsed",
+          "relative",
+          "duration"
         ],
-        "name": "UIRating",
+        "name": "UIRelativeTime",
         "related": [
-          "Field",
-          "AgentFeedbackBar"
+          "text",
+          "badge",
+          "stat"
         ],
         "slots": {},
         "states": [
           {
-            "description": "Default, ready for interaction.",
+            "description": "Default, displaying the formatted relative time.",
             "name": "idle"
           }
         ],
         "status": "stable",
         "synonyms": {
-          "rating": [
-            "rating",
-            "star rating",
-            "review score",
-            "feedback rating"
+          "ago": [
+            "relative-time",
+            "timeago"
+          ],
+          "timestamp": [
+            "relative-time",
+            "time",
+            "datetime"
           ]
         },
-        "tag": "rating-ui",
+        "tag": "relative-time-ui",
         "tokens": {},
         "traits": [],
         "version": 1
@@ -19076,6 +20369,9 @@
           "upload"
         ],
         "slots": {
+          "hint": {
+            "description": "Override slot for hint markup richer than the plain [hint] attribute string (inline links, code spans). Renders beneath the trigger at body-subtle typography. Mutually exclusive with [hint]."
+          },
           "label": {
             "description": "Label element above the trigger"
           },
@@ -19484,6 +20780,96 @@
         "version": 1
       }
     },
+    "SkipNav": {
+      "title": "SkipNav",
+      "description": "Accessibility utility — visually-hidden link that becomes visible on\nkeyboard focus, letting keyboard users skip past repetitive navigation\nto the main content. WCAG 2.1 Success Criterion 2.4.1 \"Bypass Blocks\".\n\nPlace as the FIRST focusable element on the page (typically inside\n`<body>` before any nav / shell chrome). Target an `id` on your main\ncontent region (commonly `#main` / `#main-content`).\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "component": {
+          "const": "SkipNav"
+        },
+        "target": {
+          "description": "CSS id (with leading `#`) of the main content region the link skips to.",
+          "type": "string",
+          "default": "#main"
+        },
+        "text": {
+          "description": "Link label. Defaults to \"Skip to main content\"; localize per site.",
+          "type": "string",
+          "default": "Skip to main content"
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<body><skip-nav-ui></skip-nav-ui><header>…nav…</header><main id=\"main\" tabindex=\"-1\">…</main></body>",
+            "why": "The skip link comes AFTER the nav — keyboard users have already tabbed through everything you wanted them to skip.",
+            "wrong": "<header>…nav…</header><skip-nav-ui></skip-nav-ui><main id=\"main\">…</main>"
+          }
+        ],
+        "category": "utility",
+        "composes": [],
+        "events": {},
+        "examples": [
+          {
+            "description": "Standard skip-nav at the top of the page.",
+            "a2ui": "[\n  { \"id\": \"skip\", \"component\": \"SkipNav\", \"target\": \"#main\" }\n]\n",
+            "name": "default"
+          }
+        ],
+        "keywords": [
+          "skip-nav",
+          "skip-link",
+          "bypass-blocks",
+          "a11y",
+          "accessibility",
+          "keyboard-navigation"
+        ],
+        "name": "UISkipNav",
+        "related": [
+          "visually-hidden"
+        ],
+        "slots": {},
+        "states": [
+          {
+            "description": "Default — link is visually hidden but focusable.",
+            "name": "idle"
+          },
+          {
+            "description": "Link is focused via keyboard and visible at the top of the viewport.",
+            "attribute": ":focus-within",
+            "name": "focused"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {},
+        "tag": "skip-nav-ui",
+        "tokens": {
+          "--skip-nav-bg": {
+            "description": "Background of the visible (focused) skip link.",
+            "default": "var(--a-accent-bg)"
+          },
+          "--skip-nav-fg": {
+            "description": "Foreground of the visible (focused) skip link.",
+            "default": "var(--a-accent-fg)"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
     "Slider": {
       "title": "Slider",
       "description": "Range slider with track, fill, and thumb. Supports label, suffix, and keyboard control. Form-associated.",
@@ -19510,6 +20896,11 @@
           "type": "boolean",
           "default": false
         },
+        "dual": {
+          "description": "Two-thumb range slider mode. When enabled, [lower-value] and\n[upper-value] are authoritative and [value] is ignored. The fill\nrenders between the two thumbs (not from left to thumb). Form-data\nunder [name] serializes as \"<lower>,<upper>\". Use for price filters,\ndate ranges, audio range gates, etc.",
+          "type": "boolean",
+          "default": false
+        },
         "error": {
           "description": "Validation error",
           "type": "string",
@@ -19525,6 +20916,11 @@
           "type": "string",
           "default": ""
         },
+        "lowerValue": {
+          "description": "Lower thumb value (dual mode only; clamped to ≤ [upper-value]).",
+          "type": "number",
+          "default": 0
+        },
         "max": {
           "description": "Maximum slider value",
           "type": "number",
@@ -19555,8 +20951,13 @@
           "type": "number",
           "default": 0
         },
+        "upperValue": {
+          "description": "Upper thumb value (dual mode only; clamped to ≥ [lower-value]).",
+          "type": "number",
+          "default": 100
+        },
         "value": {
-          "description": "Current slider value",
+          "description": "Current slider value (single-thumb mode; ignored when [dual] is set)",
           "type": "number",
           "default": 50
         }
@@ -19602,6 +21003,12 @@
           "embed"
         ],
         "slots": {
+          "header": {
+            "description": "Wholesale override of the stamped label + value-readout header row. Use only when full custom-header markup is needed; otherwise prefer the granular `label` / `value` slots and the [label] attribute."
+          },
+          "hint": {
+            "description": "Override slot for hint markup richer than the plain [hint] attribute string (inline links, code spans). Renders beneath the slider at body-subtle typography. Mutually exclusive with [hint]."
+          },
           "input": {
             "description": "Native range input element"
           },
@@ -20338,6 +21745,9 @@
           "description": {
             "description": "Custom description content; falls through to `[description]` prop if not slotted."
           },
+          "icon": {
+            "description": "Override the step-status glyph with a custom slotted element. By default the step renders a numeral / check / x indicator based on [status]; slot an `<icon-ui>` or image to customize."
+          },
           "label": {
             "description": "Custom label content; falls through to `[text]` prop if not slotted."
           }
@@ -21768,6 +23178,163 @@
         "version": 1
       }
     },
+    "TableOfContents": {
+      "title": "TableOfContents",
+      "description": "Auto-generated in-page table of contents. Scans a target container\nfor headings (default `h2,h3`), ensures each has an `id` (slugifies\nthe text content if missing), and stamps a `<nav>` list of anchor\nlinks. An `IntersectionObserver` tracks the active heading and\napplies `[data-active]` to the matching link so consumers can style\nthe currently-visible section. Smooth-scroll on click is handled by\nthe global `scroll-behavior: smooth` set in resets.css.\n\nPair with a sticky container (`position: sticky; top: <offset>;`) in\nan aside / right rail for the classic docs-site outline pattern.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "component": {
+          "const": "TableOfContents"
+        },
+        "headings": {
+          "description": "CSS selector listing the heading tags to include (e.g. `h2,h3`).\nThe selector is matched against the target container's\ndescendants. Default `h2,h3` produces the common two-level\noutline.\n",
+          "type": "string",
+          "default": "h2,h3"
+        },
+        "label": {
+          "description": "`aria-label` for the nav. Defaults to `Table of contents`.\n",
+          "type": "string",
+          "default": "Table of contents"
+        },
+        "offset": {
+          "description": "Top offset in pixels for active-state detection. The\nIntersectionObserver's `rootMargin` is set to\n`-<offset>px 0px -50% 0px` so the active item becomes the\nheading nearest the top of the viewport BELOW any sticky header\nchrome. Tune to match the height of your sticky topbar (default\n`80` is a reasonable docs-shell value).\n",
+          "type": "number",
+          "default": 80
+        },
+        "target": {
+          "description": "CSS selector pointing to the container to scan. Empty (default)\nscans the toc-ui's parent element. Set to `#article` /\n`[data-toc-target]` / `main` for a specific scope.\n",
+          "type": "string",
+          "default": ""
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<toc-ui target=\"#article\"></toc-ui>\n<article id=\"article\">\n  <h2>...</h2><h3>...</h3>\n</article>\n",
+            "why": "toc-ui's default scans its PARENT for headings. If toc-ui is a\nsibling of the content (not inside it), the scan finds the\nheadings inside the toc-ui's parent which usually means the\nheadings + the toc itself — works only by coincidence. Set\n[target] explicitly for clarity.\n",
+            "wrong": "<toc-ui></toc-ui>\n<h2>...</h2><h3>...</h3>\n"
+          }
+        ],
+        "category": "navigation",
+        "composes": [],
+        "events": {
+          "section-change": {
+            "description": "Fired when the active heading changes (the user scrolls into a new section). Detail carries the new active id.",
+            "detail": {
+              "activeId": "string"
+            }
+          }
+        },
+        "examples": [
+          {
+            "description": "TOC scanning the parent container.",
+            "a2ui": "[\n  {\n    \"id\": \"page\",\n    \"component\": \"Section\",\n    \"children\": [\"toc\", \"h1\", \"h2-1\", \"p-1\", \"h2-2\", \"p-2\"]\n  },\n  {\"id\": \"toc\",  \"component\": \"TableOfContents\"},\n  {\"id\": \"h1\",   \"component\": \"Text\", \"variant\": \"title\", \"textContent\": \"Article title\"},\n  {\"id\": \"h2-1\", \"component\": \"Text\", \"variant\": \"heading\", \"textContent\": \"Introduction\"},\n  {\"id\": \"p-1\",  \"component\": \"Text\", \"textContent\": \"...\"},\n  {\"id\": \"h2-2\", \"component\": \"Text\", \"variant\": \"heading\", \"textContent\": \"Conclusion\"},\n  {\"id\": \"p-2\",  \"component\": \"Text\", \"textContent\": \"...\"}\n]\n",
+            "name": "default"
+          },
+          {
+            "description": "TOC scanning a specific article container.",
+            "a2ui": "[\n  {\n    \"id\": \"shell\",\n    \"component\": \"Row\",\n    \"children\": [\"toc\", \"article\"]\n  },\n  {\n    \"id\": \"toc\",\n    \"component\": \"TableOfContents\",\n    \"target\": \"#main-article\",\n    \"headings\": \"h2,h3,h4\"\n  },\n  {\n    \"id\": \"article\",\n    \"component\": \"Section\",\n    \"attrs\": { \"id\": \"main-article\" },\n    \"children\": []\n  }\n]\n",
+            "name": "targeted"
+          }
+        ],
+        "keywords": [
+          "toc",
+          "table-of-contents",
+          "outline",
+          "sub-nav",
+          "page-nav",
+          "in-page-nav",
+          "heading-nav"
+        ],
+        "name": "UITableOfContents",
+        "related": [
+          "aside",
+          "nav",
+          "link",
+          "text"
+        ],
+        "slots": {
+          "default": {
+            "description": "Stamped automatically — a `<nav>` containing a flat `<ul>` of `<a href=\"#id\">` links. Override by authoring your own content; auto-stamp is skipped when a `<nav>` is already present."
+          }
+        },
+        "states": [
+          {
+            "description": "Default — no active section yet.",
+            "name": "idle"
+          },
+          {
+            "description": "A section is in view; the matching `<a>` carries `[data-active]`.",
+            "attribute": "data-active",
+            "name": "active"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "outline": [
+            "toc",
+            "table-of-contents"
+          ],
+          "toc": [
+            "table-of-contents",
+            "outline"
+          ]
+        },
+        "tag": "toc-ui",
+        "tokens": {
+          "--toc-fg": {
+            "description": "Default link color.",
+            "default": "var(--a-fg-muted)"
+          },
+          "--toc-fg-active": {
+            "description": "Active-link color.",
+            "default": "var(--a-fg)"
+          },
+          "--toc-fg-hover": {
+            "description": "Hover color.",
+            "default": "var(--a-fg)"
+          },
+          "--toc-gap": {
+            "description": "Vertical gap between links.",
+            "default": "var(--a-space-1)"
+          },
+          "--toc-indent": {
+            "description": "Per-depth-level indent.",
+            "default": "var(--a-space-3)"
+          },
+          "--toc-padding-block": {
+            "description": "Per-link block padding (top/bottom).",
+            "default": "var(--a-space-1)"
+          },
+          "--toc-padding-inline": {
+            "description": "Per-link inline padding.",
+            "default": "var(--a-space-2)"
+          },
+          "--toc-rule-active": {
+            "description": "Active-item indicator rule color (left border).",
+            "default": "var(--a-accent-bg)"
+          },
+          "--toc-size": {
+            "description": "Link font-size.",
+            "default": "var(--a-ui-sm)"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
     "TableToolbar": {
       "title": "TableToolbar",
       "description": "Header / companion bar for a sibling table-ui. Renders title + count badge, filter / sort / columns popovers, and a search input — all wired to the target table via an [for] id-ref. Modeled on chart-legend-ui's [for] binding pattern. Drop next to (or above) any table-ui to add the standard data-grid toolbar without re-implementing search, filter, sort, or column visibility. Filter rows auto-pick a primitive per column: ≤ 50 distinct values → multi- select (searchable when ≥ 12 options), id-like keys → free-text contains. The column descriptor's `filter` field overrides the auto-detect: `'select'` forces multi-select even on high-cardinality columns; `'text'` forces a contains input even on small enums.",
@@ -22192,11 +23759,12 @@
           "$ref": "#/$defs/DynamicString"
         },
         "tone": {
-          "description": "Fill style — orthogonal to [variant]. Default (`solid`) for family\nvariants is a saturated bg with on-strong (near-white) text — the\nchip IS the state. Opt-out via `tone=\"muted\"` for a tinted bg with\nscheme-paired text (matches <badge-ui>'s default look) when the\nchip is metadata in a dense list rather than a status stamp. The\n`default` variant stays quiet chrome regardless of tone unless\n`tone=\"solid\"` is set explicitly (high-contrast neutral inverse).\n",
+          "description": "Fill style — orthogonal to [variant]. Three values:\n  - `solid` (default for family variants) — saturated bg + on-strong\n    (near-white) text. The chip IS the state.\n  - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s\n    default look. Use on metadata chips in dense lists where the\n    saturated default would compete for attention.\n  - `outline` — transparent bg + family-colored border + family-colored\n    text. The lightest visual weight; good in dense data tables or\n    faceted filter rows where multiple chips would otherwise compete.\nThe `default` variant (no family) stays quiet chrome regardless of\ntone unless `tone=\"solid\"` is set explicitly (high-contrast neutral\ninverse), or `tone=\"outline\"` (fg-muted text + subtle border).\n",
           "type": "string",
           "enum": [
             "solid",
-            "muted"
+            "muted",
+            "outline"
           ],
           "default": "solid"
         },
@@ -23311,7 +24879,14 @@
           "FeedItem",
           "Stepper"
         ],
-        "slots": {},
+        "slots": {
+          "description": {
+            "description": "Override slot for rich description markup (inline links, code spans, embedded badges). Renders beneath the primary text at body-subtle typography."
+          },
+          "icon": {
+            "description": "Override the [icon] glyph with a custom slotted element. Use for branded icons, avatars, or non-Phosphor sources. Mutually exclusive with the [icon] attribute."
+          }
+        },
         "states": [],
         "status": "stable",
         "synonyms": {
@@ -24609,6 +26184,9 @@
         "slots": {
           "default (tree-item-ui children)": {
             "description": "Child content region for the `default (tree-item-ui children)` slot."
+          },
+          "icon": {
+            "description": "Override slot for the per-node icon glyph. Tree-item's `[icon]` attr stamps a default Phosphor icon; the slot lets consumers fill custom icons (folder open/closed, file-type glyphs, branded markers)."
           }
         },
         "states": [
@@ -24761,7 +26339,11 @@
           "Nav",
           "Accordion"
         ],
-        "slots": {},
+        "slots": {
+          "icon": {
+            "description": "Override the leading [icon] glyph with a custom slotted element (custom icon-ui, folder open/closed glyph, file-type marker). Mutually exclusive with the [icon] attribute — slot child wins."
+          }
+        },
         "states": [],
         "status": "stable",
         "synonyms": {
@@ -24961,6 +26543,75 @@
         "traits": [],
         "version": 1
       }
+    },
+    "VisuallyHidden": {
+      "title": "VisuallyHidden",
+      "description": "Accessibility utility — content visible to screen readers but hidden\nvisually (the canonical \"sr-only\" pattern). Use for icon-only buttons,\ncontextual labels on duplicate controls, status announcements via\nlive regions, and any text the AT needs but sighted users don't.\n\nDistinct from `[hidden]` / `display:none` (hidden from EVERYONE\nincluding AT) and from `aria-label` (which replaces visible text but\ndoesn't add invisible text). When you need both visible and invisible\ntext on the same element, `<visually-hidden-ui>` is the wrapper for\nthe invisible part.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "component": {
+          "const": "VisuallyHidden"
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<button-ui icon=\"trash\"><visually-hidden-ui>Delete</visually-hidden-ui></button-ui> OR set aria-label=\"Delete\" — but visually-hidden-ui scales to longer context (\"Delete row 42 in the orders table\") without overloading the label attribute.",
+            "why": "Icon-only buttons with no accessible name are unreadable for screen-reader users.",
+            "wrong": "<button-ui icon=\"trash\"></button-ui>"
+          }
+        ],
+        "category": "utility",
+        "composes": [],
+        "events": {},
+        "examples": [
+          {
+            "description": "Sr-only label for an icon-only button.",
+            "a2ui": "[\n  { \"id\": \"btn\", \"component\": \"Button\", \"icon\": \"trash\", \"children\": [\"lbl\"] },\n  { \"id\": \"lbl\", \"component\": \"VisuallyHidden\", \"textContent\": \"Delete row\" }\n]\n",
+            "name": "icon-button-label"
+          }
+        ],
+        "keywords": [
+          "visually-hidden",
+          "sr-only",
+          "screen-reader",
+          "a11y",
+          "accessibility"
+        ],
+        "name": "UIVisuallyHidden",
+        "related": [
+          "text"
+        ],
+        "slots": {
+          "default": {
+            "description": "The text or content to hide visually while keeping accessible."
+          }
+        },
+        "states": [
+          {
+            "description": "Default — content is visually hidden but in the accessibility tree.",
+            "name": "idle"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {},
+        "tag": "visually-hidden-ui",
+        "tokens": {},
+        "traits": [],
+        "version": 1
+      }
     }
   },
   "functions": {