@adia-ai/a2ui-corpus 0.6.37 → 0.6.39

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": {
@@ -4309,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.",
@@ -7393,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"
           }
@@ -10156,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": [
@@ -10314,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"
         },
@@ -10507,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."
           }
@@ -11604,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",
@@ -13759,7 +13974,17 @@
           "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."
+          },
+          "action": {
+            "description": "Trailing action affordance on the row (typically a `<button-ui>`). Promotes the row's grid from 2-column (icon | content) to 3-column (icon | content | action), right-aligned + vertically centered across both content rows. Used by `<onboarding-checklist-ui>` item rows and any consumer that needs an end-aligned action button on a list-item."
+          },
+          "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": {
@@ -14225,6 +14450,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.",
@@ -14604,6 +14936,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": [
@@ -14878,6 +15219,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": [
@@ -15009,6 +15353,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": [
@@ -15810,6 +16157,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."
           },
@@ -20022,6 +20372,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"
           },
@@ -20653,6 +21006,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"
           },
@@ -21389,6 +21748,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."
           }
@@ -24520,7 +24882,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": {
@@ -25739,6 +26108,266 @@
         "version": 1
       }
     },
+    "Tour": {
+      "title": "Tour",
+      "description": "Spotlight-driven product tour / guided walkthrough. Hosts a sequence\nof `<tour-step>` children, each targeting an element via CSS selector.\nWhen active, dims the page with a scrim, cuts a \"hole\" around the\ncurrent step's target, and renders a popover next to it with step\ncontent + Skip / Previous / Next navigation.\n\nUse for first-run onboarding tours, feature introductions after a\nrelease, and inline walkthroughs the user opts into (\"Take the tour\").\nDistinct from `<onboarding-checklist-ui>` (persistent todo-list of\nsetup steps the user works through at their own pace) and from\n`<tooltip-ui>` (single hover hint with no orchestration).\n\nArchitecture: tour-ui is a behavioral wrapper (`display: contents`)\nthat reads target / title / content from `<tour-step>` children. On\nstart, mounts a spotlight + popover surface into `document.body`\n(top-layer via Popover API). The spotlight is a transparent\nposition:fixed element with a huge box-shadow that produces the\ndimmed scrim outside its bounds (single-element backdrop, no clip-path\nor SVG mask needed). The popover is anchored to the target via the\nsame `core/anchor.js` pattern used by menu-ui / context-menu-ui /\npopover-ui.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "active": {
+          "description": "Whether the tour is currently running. Setting to `true` mounts\nthe spotlight + popover; setting to `false` tears down.\n",
+          "type": "boolean",
+          "default": false
+        },
+        "auto-start": {
+          "description": "Start the tour automatically when the element connects. Useful for\nfirst-run flows gated by a storage flag on the consumer side.\n",
+          "type": "boolean",
+          "default": false
+        },
+        "component": {
+          "const": "Tour"
+        },
+        "step": {
+          "description": "Current step index (0-based). Setting this property advances the\ntour to that step (updating spotlight + popover position).\n",
+          "type": "number",
+          "default": 0
+        },
+        "storage-key": {
+          "description": "Optional localStorage key. When set, the tour records its\ncompletion state (`\"done\"`) to that key on finish/skip — and\nrefuses to auto-start on subsequent loads if the key is \"done\".\nUseful for \"show this tour once per user\" flows.\n",
+          "type": "string",
+          "default": ""
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<tour-ui><tour-step target=\"#dashboard\" title=\"Dashboard\">Tour the dashboard…</tour-step>…</tour-ui>",
+            "why": "Bare divs have no target / title — tour-ui can't position the spotlight.",
+            "wrong": "<tour-ui><div>step 1 content</div><div>step 2 content</div></tour-ui>"
+          },
+          {
+            "fix": "<tour-step target=\"#dashboard\">",
+            "why": "target is a CSS selector — bare \"dashboard\" matches a <dashboard> element, NOT an id; use the # prefix.",
+            "wrong": "<tour-step target=\"dashboard\">"
+          }
+        ],
+        "category": "feedback",
+        "composes": [
+          "button-ui",
+          "tour-step-ui"
+        ],
+        "events": {
+          "tour-finish": {
+            "description": "Fired when the user completes the last step. detail = { totalSteps }. Bubbles."
+          },
+          "tour-skip": {
+            "description": "Fired when the user skips the tour mid-way. detail = { step, totalSteps }. Bubbles."
+          },
+          "tour-start": {
+            "description": "Fired when the tour starts (after spotlight + popover mount). detail = { step }. Bubbles."
+          },
+          "tour-step-change": {
+            "description": "Fired when the active step changes. detail = { from, to, totalSteps }. Bubbles."
+          }
+        },
+        "examples": [
+          {
+            "description": "A 3-step product tour anchored to selector-resolved elements.",
+            "a2ui": "[\n  { \"id\": \"tour\", \"component\": \"Tour\", \"auto-start\": true, \"children\": [\"s1\", \"s2\", \"s3\"] },\n  { \"id\": \"s1\", \"component\": \"TourStep\", \"target\": \"#dashboard\", \"title\": \"Your dashboard\", \"textContent\": \"Here's where you'll see your latest activity.\" },\n  { \"id\": \"s2\", \"component\": \"TourStep\", \"target\": \"#filters\", \"title\": \"Filters\", \"textContent\": \"Narrow results by status, owner, or date.\" },\n  { \"id\": \"s3\", \"component\": \"TourStep\", \"target\": \"#export\", \"title\": \"Export\", \"textContent\": \"Download a CSV of the current view.\" }\n]\n",
+            "name": "basic-tour"
+          }
+        ],
+        "keywords": [
+          "tour",
+          "product-tour",
+          "walkthrough",
+          "guided-tour",
+          "spotlight",
+          "coachmark",
+          "feature-introduction"
+        ],
+        "name": "UITour",
+        "related": [
+          "tooltip",
+          "popover",
+          "onboarding-checklist"
+        ],
+        "slots": {
+          "default": {
+            "description": "<tour-step> children — each declares target + title + body content."
+          }
+        },
+        "states": [
+          {
+            "description": "Tour is dormant; no scrim / popover rendered.",
+            "name": "idle"
+          },
+          {
+            "description": "Tour is running; scrim dims the page, current target is spotlighted.",
+            "name": "active"
+          },
+          {
+            "description": "Last step reached (Done is shown instead of Next).",
+            "name": "complete"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "spotlight": [
+            "coachmark",
+            "feature-highlight"
+          ],
+          "tour": [
+            "product-tour",
+            "guided-tour",
+            "walkthrough",
+            "feature-intro"
+          ]
+        },
+        "tag": "tour-ui",
+        "tokens": {
+          "--tour-popover-bg": {
+            "description": "Background of the step-content popover.",
+            "default": "var(--a-bg-subtle)"
+          },
+          "--tour-popover-border": {
+            "description": "Border color of the popover.",
+            "default": "var(--a-border-subtle)"
+          },
+          "--tour-popover-max-width": {
+            "description": "Maximum width of the popover.",
+            "default": "22rem"
+          },
+          "--tour-popover-min-width": {
+            "description": "Minimum width of the popover (so step text wraps reasonably).",
+            "default": "18rem"
+          },
+          "--tour-popover-radius": {
+            "description": "Border-radius of the popover.",
+            "default": "var(--a-radius-lg)"
+          },
+          "--tour-popover-shadow": {
+            "description": "Shadow of the popover.",
+            "default": "var(--a-shadow-lg)"
+          },
+          "--tour-scrim": {
+            "description": "Backdrop scrim color (everything outside the spotlight).",
+            "default": "var(--a-scrim-dialog)"
+          },
+          "--tour-spotlight-padding": {
+            "description": "Padding around the target bounding box (the spotlight's \"halo\").",
+            "default": "var(--a-space-2)"
+          },
+          "--tour-spotlight-radius": {
+            "description": "Border radius of the spotlight cutout.",
+            "default": "var(--a-radius-md)"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
+    "TourStep": {
+      "title": "TourStep",
+      "description": "Single step inside a `<tour-ui>` walkthrough. Declares a target\nelement (via CSS selector), a title, and body content. The host\n`<tour-ui>` reads these declaratively and renders them in the\npopover as the user advances through the tour.\n\n`<tour-step>` itself renders nothing — it's a data carrier (light\nDOM source of truth). The tour-ui orchestrator clones the body\ncontent into the spotlight popover when the step becomes active.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "title": {
+          "description": "Step heading rendered in the popover.",
+          "type": "string",
+          "default": ""
+        },
+        "component": {
+          "const": "TourStep"
+        },
+        "placement": {
+          "description": "Preferred popover placement relative to the target. Same vocabulary\nas `core/anchor.js` (`top`, `bottom`, `left`, `right`,\n`bottom-start`, `bottom-end`, etc.). Auto-flips on viewport overflow\nvia position-try-fallbacks.\n",
+          "type": "string",
+          "enum": [
+            "top",
+            "bottom",
+            "left",
+            "right",
+            "top-start",
+            "top-end",
+            "bottom-start",
+            "bottom-end",
+            "left-start",
+            "left-end",
+            "right-start",
+            "right-end"
+          ],
+          "default": "bottom"
+        },
+        "target": {
+          "description": "CSS selector for the element to spotlight when this step is\nactive. Resolved via `document.querySelector(target)` at step\nactivation time. If the selector matches nothing, the spotlight\nfalls back to viewport-center and the popover anchors to the\npage (no halo cutout).\n",
+          "type": "string",
+          "default": ""
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<tour-step target=\"#dashboard\">",
+            "why": "target is a CSS selector — bare \"dashboard\" doesn't match.",
+            "wrong": "<tour-step target=\"dashboard\">"
+          }
+        ],
+        "category": "feedback",
+        "composes": [],
+        "events": {},
+        "examples": [],
+        "keywords": [
+          "tour-step",
+          "walkthrough-step",
+          "guided-step"
+        ],
+        "name": "UITourStep",
+        "related": [
+          "tour"
+        ],
+        "slots": {
+          "default": {
+            "description": "Body content rendered inside the step popover (plain text or inline HTML)."
+          }
+        },
+        "states": [],
+        "status": "stable",
+        "synonyms": {
+          "step": [
+            "tour-step",
+            "walkthrough-step"
+          ]
+        },
+        "tag": "tour-step-ui",
+        "tokens": {},
+        "traits": [],
+        "version": 1
+      }
+    },
     "Tree": {
       "title": "Tree",
       "description": "Collapsible tree container with keyboard navigation (arrow keys, Enter/Space). Manages selection across nested tree-item-ns.",
@@ -25818,6 +26447,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": [
@@ -25970,7 +26602,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": {