@adia-ai/a2ui-corpus 0.6.35 → 0.6.37

package/catalog-a2ui_0_9.json

@@ -2829,6 +2829,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 +3378,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 +4028,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",
@@ -6220,7 +6364,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 +6376,7 @@
             "bottom-start",
             "bottom-end"
           ],
-          "default": "bottom-start"
+          "default": "bottom"
         },
         "value": {
           "description": "Current color as a string in the active [format].",
@@ -7306,6 +7450,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",
@@ -7387,7 +7688,7 @@
             "wrong": "<dashboard-layout-ui>\n  <dashboard-layout-ui slot=\"charts\">...</dashboard-layout-ui>\n</dashboard-layout-ui>\n"
           },
           {
-            "description": "kpi-columns out of range. Eight cards in a row produces KPI\ncards narrower than --dashboard-layout-kpi-min (16em); the\ncontainer-query collapse misfires.\n",
+            "description": "kpi-columns out of range. Eight cards in a row is too narrow\nto be legible at typical container widths; the container-query\ncollapse (≤48em → 2 cols, ≤32em → 1 col) won't help when N is\nalready that large at desktop.\n",
             "right": "<dashboard-layout-ui kpi-columns=\"4\">...</dashboard-layout-ui>\n",
             "rule": "kpi-columns ∈ {2,3,4,5,6}. Split into 2 rows of 4 by composing\n2 DashboardLayouts vertically if 8 cards are truly necessary.\n",
             "wrong": "<dashboard-layout-ui kpi-columns=\"8\">...</dashboard-layout-ui>\n"
@@ -7541,10 +7842,6 @@
             "description": "Inter-card gap inside the chart band.",
             "default": "var(--a-space-4)"
           },
-          "--dashboard-layout-chart-min": {
-            "description": "Minimum chart card inline-size.",
-            "default": "22em"
-          },
           "--dashboard-layout-gap": {
             "description": "Band-to-band vertical gap.",
             "default": "var(--a-space-4)"
@@ -7553,10 +7850,6 @@
             "description": "Inter-card gap inside the KPI band.",
             "default": "var(--a-space-2)"
           },
-          "--dashboard-layout-kpi-min": {
-            "description": "Minimum KPI card inline-size before container-query collapse.",
-            "default": "16em"
-          },
           "--dashboard-layout-padding": {
             "description": "Outer padding around the composite.",
             "default": "0"
@@ -7641,6 +7934,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",
@@ -8164,6 +8472,21 @@
           "type": "string",
           "default": "Select date and time"
         },
+        "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": [
+            "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",
@@ -15153,9 +15476,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": [
         {
@@ -15166,28 +15489,206 @@
         }
       ],
       "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"
+          "const": "NumberFormat"
         },
-        "dismiss-on-complete": {
+        "currency": {
+          "description": "ISO 4217 currency code (e.g. \"USD\", \"EUR\", \"JPY\"). Required when\n[number-style=\"currency\"]; ignored otherwise.\n",
+          "type": "string",
+          "default": ""
+        },
+        "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
@@ -15938,14 +16439,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"
         }
       },
@@ -15956,7 +16471,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 }.",
@@ -16141,6 +16659,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",
@@ -17641,6 +18309,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.",
@@ -18099,52 +18919,170 @@
         }
       },
       "required": [
-        "component",
-        "value"
+        "component",
+        "value"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [],
+        "category": "form",
+        "composes": [],
+        "events": {
+          "[object Object]": {
+            "description": "Fired on [object Object]."
+          }
+        },
+        "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": "form",
+        "category": "display",
         "composes": [],
-        "events": {
-          "[object Object]": {
-            "description": "Fired on [object Object]."
+        "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"
           }
-        },
-        "examples": [],
+        ],
         "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
@@ -19492,6 +20430,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.",
@@ -19518,6 +20546,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",
@@ -19533,6 +20566,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",
@@ -19563,8 +20601,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
         }
@@ -21776,6 +22819,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.",
@@ -22199,6 +23399,16 @@
           "description": "Tag label. Renderer routes this to the `text` attribute, rendered via CSS attr(text) on ::after.",
           "$ref": "#/$defs/DynamicString"
         },
+        "tone": {
+          "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",
+            "outline"
+          ],
+          "default": "solid"
+        },
         "variant": {
           "description": "Semantic variant — `default | info | success | warning | danger`.",
           "type": "string",
@@ -24960,6 +26170,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": {