@treeui/mcp 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -50,9 +50,9 @@ module.exports = __toCommonJS(index_exports);
 
 // src/generated/treeui.catalog.json
 var treeui_catalog_default = {
-  generatedAt: "2026-07-18T23:35:26.876Z",
+  generatedAt: "2026-07-21T20:31:07.075Z",
   packageName: "@treeui/vue",
-  packageVersion: "0.16.0",
+  packageVersion: "0.19.1",
   decisionGuides: [
     {
       id: "single-choice",
@@ -103,6 +103,14 @@ var treeui_catalog_default = {
             "The options are hierarchical."
           ],
           notes: []
+        },
+        {
+          use: "TLanguageSelect",
+          when: [
+            "The value is the application language or locale.",
+            "Each language should show a country flag beside its name."
+          ],
+          notes: []
         }
       ]
     },
@@ -415,6 +423,52 @@ var treeui_catalog_default = {
         "Prefer `TAppShell` (recipe `app-shell`) when you also need full-viewport sizing and a responsive mobile drawer."
       ]
     },
+    {
+      id: "brand-lockup",
+      name: "Product brand lockup in a shell header",
+      useWhen: [
+        "A shell header needs a logo plus a product name (and optional subtitle) that stays aligned as the sidebar collapses."
+      ],
+      compose: [
+        "TAppShell",
+        "TAvatar",
+        "TText",
+        "TStack"
+      ],
+      notes: [
+        "Put the lockup in the `header-start` slot, not `header`. Filling `header-start` switches the header to the shell's own grid, so the mark tracks `--tree-app-shell-sidebar-width` and animates with the collapse \u2014 no local column math.",
+        'The slot is scoped: use its `collapsed` binding to drop the wordmark and keep only the mark (`v-if="!collapsed"`), rather than hiding text with CSS.',
+        'Logo is `TAvatar` (`size`, `alt`, `initials` fallback) or a plain `<img>` sized with `--tree-size-icon-*`; name and subtitle are `TText` (`weight`, `tone="muted"`, `truncate`) \u2014 never raw `<strong>`/`<span>` with a local class.',
+        "TreeUI ships no `TBrand` component on purpose: the logo asset, the product name, and what survives collapse are product identity, which must stay in the consumer. See DECISIONS.md \u2192 Portability Boundary.",
+        "Company and service logos (AWS, LocalStack, social networks) are brand assets and are not TreeUI icons \u2014 source them from the app's brand policy, not the icon registry."
+      ]
+    },
+    {
+      id: "nav-menu-icons",
+      name: "Icons on navigation items",
+      useWhen: [
+        "Navigation items each carry an icon.",
+        "The navigation collapses to an icon-only rail, so the icon is the only thing left identifying a section.",
+        "Some of the icons the app needs are not TreeUI built-ins."
+      ],
+      compose: [
+        "TNavMenu",
+        "TIcon",
+        "registerTreeIcons",
+        "resetTreeIcons"
+      ],
+      notes: [
+        "Set `icon` on the item, as a registered NAME: `{ label: 'Dashboard', value: 'dashboard', icon: 'layout-dashboard' }`. Do not import an icon component per item, and do not put a `TIcon` in the `#item` slot just to get an icon \u2014 the item renders it for you.",
+        "`TNavMenuItem.icon` is `TIconInput`, so a component is accepted too. Prefer the name: `items` normally lives in a `ref`, a `computed`, or a route config, and a string is never made reactive \u2014 a component object there needs `markRaw` or Vue warns.",
+        "An item with no icon (or an unregistered name) falls back to a letter marker, and a `console.warn` lists the valid names \u2014 once per name, in production builds too. Give every item an icon before shipping a collapsible rail, or the collapsed state is a column of letters.",
+        "Icons the app needs but TreeUI does not ship are REGISTERED, not worked around: one `registerTreeIcons` call in `main.ts` and they are usable by name everywhere. Never hand-roll an `<svg>` \u2014 without the `absoluteStrokeWidth` correction its stroke scales with the icon (1.67px at size 20, 4px at 48), so it looks bolder than its neighbours at every size above 24.",
+        "Check the name is not already taken before registering it \u2014 `hasTreeIcon(name)` answers that. Registering one of the 364 built-in names replaces that built-in everywhere, silently, which is a supported swap but never what you want when the goal was adding an icon.",
+        "Keep the icon vocabulary consistent: built-ins use TreeUI's descriptive kebab-case names, so register custom ones with the same convention.",
+        "Icon registration is process-wide state. In component tests that register icons, call `resetTreeIcons()` in an `afterEach` so one case's icons do not leak into the next.",
+        "Set `to` for the route target on each item \u2014 `TNavMenuItem` has no `href` and no `id`; identity is `value`.",
+        "This recipe covers the icons only; the surrounding layout is its own recipe (`app-shell` or `sidebar-shell`)."
+      ]
+    },
     {
       id: "stat-grid",
       name: "Dashboard metric grid",
@@ -588,6 +642,150 @@ var treeui_catalog_default = {
       notes: [
         'Use `selectionMode="multiple"` when permissions or tag assignment spans nested nodes.'
       ]
+    },
+    {
+      id: "language-switcher",
+      name: "Application language switcher",
+      useWhen: [
+        "The app lets the user pick a language or locale, with an optional flag per option."
+      ],
+      compose: [
+        "TFormField",
+        "TLanguageSelect"
+      ],
+      notes: [
+        "The app owns the language list: TreeUI ships no locale dataset, so pass `options` with your own `label`, `value`, and optional `code` and `description`.",
+        "`TLanguageSelect` only emits the chosen `value` through `update:modelValue`; the app performs every locale side effect (i18n locale, persistence, `document.documentElement.lang`, route or API updates).",
+        "Set `code` only where a flag is meaningful \u2014 a language is not a country \u2014 and omit it to render that option without a flag.",
+        "Set `flagBaseUrl` once, at the switcher, when flag assets are self-hosted; it is forwarded to every nested `TFlag`.",
+        "Wrap with `TFormField` when the switcher sits in a form and needs a label, hint, or error text; drop the wrapper for a bare toolbar or header control."
+      ]
+    }
+  ],
+  practices: [
+    {
+      id: "interaction-feedback",
+      title: "Visual interaction feedback",
+      summary: "Every interaction answers back. Hover, focus, active, loading, and disabled are designed states \u2014 never afterthoughts left to the consumer.",
+      rules: [
+        "Interactive surfaces ship hover, active, and focus-visible treatments out of the box.",
+        "Loading states announce themselves (aria-busy plus a labelled, localizable spinner), replace the resting glyph instead of stacking beside it, and block duplicate activation.",
+        "Disabled and loading elements never emit activation events.",
+        "Focus indicators stay visible in both light and dark themes."
+      ],
+      components: [
+        "TButton",
+        "TLink",
+        "TInput",
+        "TSelect",
+        "TCheckbox",
+        "TSwitch",
+        "TTabs",
+        "TPagination",
+        "TDropdown",
+        "TSelectableList"
+      ]
+    },
+    {
+      id: "accessible-by-default",
+      title: "Accessible by default",
+      summary: "Native semantics first, ARIA where the pattern requires it, full keyboard support, and focus management the consumer never has to write.",
+      rules: [
+        'Native elements before roles; role="dialog", aria-modal, aria-labelledby only where semantics require them, and no composite-widget role (grid, tree) is claimed without its full keyboard model.',
+        "Tab/Shift+Tab order, Escape to close, Enter/Space to activate, arrow keys where the pattern expects them.",
+        "Overlays trap focus while open and restore it on close.",
+        "Clickable targets stay at or above 44\xD744px."
+      ],
+      components: [
+        "TModal",
+        "TDrawer",
+        "TConfirmDialog",
+        "TDropdown",
+        "TTooltip",
+        "TAccordion",
+        "TFormField",
+        "TTreeView",
+        "TToastProvider",
+        "TButton"
+      ]
+    },
+    {
+      id: "predictable-api",
+      title: "One predictable API",
+      summary: "The same contracts everywhere: one size scale, one action-variant scale, v-model for form controls, open/close for overlays. Learn one component and you know them all.",
+      rules: [
+        "Sizes are sm | md | lg across the library.",
+        "Action variants come from one scale: solid, outline, ghost, soft, danger.",
+        "Form controls speak modelValue + update:modelValue (v-model).",
+        "Overlays speak open/defaultOpen + update:open/open-change."
+      ],
+      components: [
+        "TButton",
+        "TInput",
+        "TSelect",
+        "TBadge",
+        "TTag",
+        "TCard",
+        "TModal"
+      ]
+    },
+    {
+      id: "state-clarity",
+      title: "Empty, loading, and error are designed states",
+      summary: "Screens communicate status honestly: skeletons while loading, purposeful empty states, and status surfaces on one semantic tone scale.",
+      rules: [
+        "Default, hover, active, focus, disabled, loading, and error/empty states are designed and documented \u2014 not just the happy path.",
+        "Status tones map to semantic tokens (success, warning, error, info) and pass both themes.",
+        "Async feedback is immediate: skeleton or spinner first, toast or alert on completion."
+      ],
+      components: [
+        "TSkeleton",
+        "TSpinner",
+        "TProgress",
+        "TEmptyState",
+        "TAlert",
+        "TToastProvider",
+        "TBadge",
+        "TTable"
+      ]
+    },
+    {
+      id: "content-alignment",
+      title: "Alignment without custom CSS",
+      summary: "Layout primitives absorb spacing, alignment, and rhythm so product code never hand-rolls the same flexbox again.",
+      rules: [
+        "Spacing comes from the --tree-space-* scale, applied by layout components.",
+        "Compose TPage, TStack, TGrid, and TSplit before writing a custom layout div.",
+        "Forms align through TFormField + TStack + TGrid \u2014 labels, hints, and errors line up by contract.",
+        "Reading widths and page gutters come from TContainer/TPage, not local max-widths."
+      ],
+      components: [
+        "TStack",
+        "TGrid",
+        "TSplit",
+        "TContainer",
+        "TSpacer",
+        "TPage",
+        "TPageHeader",
+        "TFormField"
+      ]
+    },
+    {
+      id: "token-driven",
+      title: "Token-driven clarity",
+      summary: "No raw hex, px, or font values anywhere. Every visual decision references a --tree-* token, so light/dark and brand theming stay coherent by construction.",
+      rules: [
+        "Zero hardcoded colors, spacing, or typography in component code.",
+        "Light and dark are first-class themes; every state passes both.",
+        "Themes switch by attribute (data-tree-theme) with no component changes."
+      ],
+      components: [
+        "TCard",
+        "TNavbar",
+        "TBadge",
+        "TTag",
+        "TChart"
+      ]
     }
   ],
   setup: {
@@ -662,6 +860,43 @@ var treeui_catalog_default = {
           "Use `maxVisibleTags` to control trigger density in compact layouts."
         ]
       },
+      TFlag: {
+        required: [
+          "Pass `code` as an ISO 3166-1 alpha-2 country code. Matching is case-insensitive \u2014 the value is trimmed and lowercased internally.",
+          "Allow `https://flagcdn.com` in the app `Content-Security-Policy` `img-src` directive, or point `baseUrl` at a self-hosted mirror \u2014 flag images are fetched from a third-party CDN at runtime."
+        ],
+        notes: [
+          "A mirror must serve `{baseUrl}/{segment}/{code}.png` for both steps of every size: 1x `h20` (sm), `h20` (md), `h24` (lg); 2x `h40` (sm), `h40` (md), `h60` (lg). The 2x asset is emitted through `srcset`.",
+          "Those fixed-height segments are part of the contract, and they are the CDN's flat artwork \u2014 a mirror must serve flat flags, not the waving ones.",
+          "Do not substitute the CDN's ratio-normalised width-by-height endpoints. They equalise aspect ratio only by switching to the waving artwork, which reads as decoration next to flat UI icons.",
+          "The fixed-height assets keep each flag's true proportions \u2014 Nepal is a pennant, Switzerland is square, Qatar is elongated. A shared height, not a shared ratio, is what aligns a column of flags.",
+          "CSS puts the image in a fixed 3:2 box (3:2 being the most common national flag ratio) with `object-fit: contain`, so outliers centre inside the box instead of being cropped or distorted.",
+          "Each retina segment is at least twice its box height \u2014 boxes are `--tree-size-icon-sm/md/lg` = 16px/20px/24px \u2014 so 2x screens never upscale.",
+          "`baseUrl` may be written with or without a trailing slash; trailing slashes are stripped before the path is built. An unknown `size` falls back to the `md` assets.",
+          "When the image cannot load \u2014 offline, blocked by CSP, unknown code \u2014 the component renders the uppercased `code` as text. Override that text with `fallbackText`.",
+          "The flag is `aria-hidden` by default. Pass `label` only when the flag carries meaning on its own; beside a visible country or language name it should stay decorative."
+        ]
+      },
+      TLanguageSelect: {
+        required: [
+          "Pass `options` as `{ label, value, code?, description?, disabled? }[]`. TreeUI ships no language, locale, or country dataset \u2014 the app owns its language list.",
+          "Apply locale side effects (i18n locale, `lang` attribute, persistence) in the app layer; the component only reports the selected `value`.",
+          "Pass an `aria-label` whenever `iconOnly` is set \u2014 the visible language name is gone, so it is the control's only accessible name. It also labels the listbox."
+        ],
+        notes: [
+          "`variant` is `field` (default) or `switcher`, typed as `TLanguageSelectVariant` and exported from `@treeui/vue`.",
+          'Use `variant="field"` inside a form, next to other inputs, or wrapped in `TFormField`: the flag leads the trigger, the trigger fills its container, and `width` applies. A visible field label already says what the control changes.',
+          'Use `variant="switcher"` for a page-level control in a navbar or app bar, where nothing nearby labels it. A translate icon (`TIcon name="languages"`) leads and the current flag trails before the chevron, so the control reads as "page language, now set to this" without an external label.',
+          "A switcher sizes to its content, so `width` does not apply, and its listbox aligns to the trigger's right edge.",
+          "`iconOnly` is switcher-only and drops the visible language name, leaving the translate icon and the current flag.",
+          "`value` is an opaque application key, typically a BCP-47 tag such as `pt-BR`. TreeUI never parses or validates it.",
+          "`code` is the ISO 3166-1 alpha-2 code used for the option flag. Omit it to render the option without a flag \u2014 a language is not a country, so many entries have no honest flag.",
+          "Use `description` for a secondary line such as the endonym.",
+          "Set `flagBaseUrl` once on the select rather than per option; it is forwarded to every nested `TFlag`.",
+          "Bind `modelValue` to a `string`, and use `v-model:open` when the app controls open state.",
+          "The CDN and Content-Security-Policy requirements under `TFlag` apply whenever any option carries a `code`."
+        ]
+      },
       TToggleGroup: {
         required: [],
         notes: [
@@ -711,7 +946,20 @@ var treeui_catalog_default = {
       TNavMenu: {
         required: [],
         notes: [
-          "When nested inside `TSidebar` or `TAppShell`, `collapsed` can be inherited from the sidebar provider."
+          "When nested inside `TSidebar` or `TAppShell`, `collapsed` can be inherited from the sidebar provider.",
+          "Pass `items` as `{ label, value, icon?, to?, badge?, description?, shortLabel?, disabled?, exact? }[]`.",
+          "`icon` is `TIconInput` \u2014 a registered icon name (`icon: 'layout-dashboard'`) or a component. Use the name: it needs no import, and no `markRaw` when the item list is reactive.",
+          "An item with no icon, or with a name that is not registered, shows a letter marker instead. That marker is also all a collapsed rail can show, so give every item an icon when the sidebar collapses.",
+          "Register any icon the app needs beyond the built-ins first \u2014 see `icons` above."
+        ]
+      },
+      TIcon: {
+        required: [
+          "Use a registered name: one of the built-ins, or one the app added with `registerTreeIcons`. See `icons` above."
+        ],
+        notes: [
+          '`size` is a pixel count, not `sm | md | lg`. Passing `size="md"` renders an unsized svg.',
+          "The icon is `aria-hidden` by default. Pass `label` only when the icon carries meaning on its own; beside visible text it should stay decorative."
         ]
       },
       TTreeView: {
@@ -783,6 +1031,7 @@ var treeui_catalog_default = {
       ],
       commonCompositions: [
         "TFormField + input-like control",
+        "TFormField + TLanguageSelect",
         "TGrid + TStat",
         "TStat + TSparkline",
         "TCard + TChart",
@@ -806,15 +1055,83 @@ var treeui_catalog_default = {
       storyFile: "apps/docs/src/stories/Accordion.stories.ts",
       storyTitle: "Components/Data Display/Accordion",
       manifestFile: "docs/ai/COMPONENTS/accordion.yaml",
-      props: [],
-      events: [],
-      slots: [],
+      props: [
+        {
+          name: "type",
+          type: "'single' | 'multiple'",
+          default: "'single'",
+          values: [
+            "single",
+            "multiple"
+          ],
+          description: "single \u2013 at most one item open at a time (opening one closes the rest). multiple \u2013 any number of items may be open simultaneously.\n"
+        },
+        {
+          name: "modelValue",
+          type: "string | string[] | undefined",
+          default: "undefined",
+          description: 'Controlled open state. For type="single" pass a string (the item value). For type="multiple" pass an array of strings. The accordion treats itself as controlled only while modelValue !== undefined; passing undefined leaves it uncontrolled and it falls back to its internal state.\n'
+        },
+        {
+          name: "defaultValue",
+          type: "string | string[] | undefined",
+          default: "undefined",
+          description: "Initial open state for uncontrolled usage. Read once when the accordion is created \u2014 changing it after mount has no effect. Ignored while modelValue is set. Do not combine it with modelValue: see notes.\n"
+        },
+        {
+          name: "disabled",
+          type: "boolean",
+          default: "false",
+          description: "Disables all items. OR-ed with each item's own disabled prop, so an item is disabled when either is true. Provided to items as a computed ref, so flipping it after mount updates every item.\n"
+        },
+        {
+          name: "collapsible",
+          type: "boolean",
+          default: "false",
+          description: 'Only applies when type="single". When true, the open item can be collapsed by clicking its trigger again, which emits undefined. When false, clicking the already-open trigger is a no-op and emits nothing. In type="multiple" any item can always be collapsed and this prop is ignored.\n'
+        }
+      ],
+      events: [
+        {
+          name: "update:modelValue",
+          description: 'Emitted when the open state changes (v-model support). type="single" emits the open item value as a string, or undefined when it is collapsed. type="multiple" always emits a string[] of the open values.\n',
+          payload: "string | string[] | undefined"
+        }
+      ],
+      slots: [
+        {
+          name: "default",
+          description: "Accepts TAccordionItem children."
+        }
+      ],
       a11y: [
-        'roles: {"trigger":"heading > button","panel":"region"}',
-        'attributes: {"trigger":["aria-expanded (reflects open state)","aria-controls (references panel id)"],"panel":["role=\\"region\\"","aria-labelledby (references trigger id)"]}',
-        'keyboard: [{"key":"Enter / Space","action":"Toggle the focused item"},{"key":"ArrowDown","action":"Move focus to the next item trigger"},{"key":"ArrowUp","action":"Move focus to the previous item trigger"},{"key":"Home","action":"Move focus to the first item trigger"},{"key":"End","action":"Move focus to the last item trigger"}]'
+        "container_is_a_plain_div_with_no_aria_role: true",
+        "trigger_is_a_heading_wrapped_native_button: h3 > button",
+        "aria_expanded_on_trigger_reflects_open_state: true",
+        "aria_controls_on_trigger_references_panel_id: true",
+        "panel_uses_role_region: true",
+        "aria_labelledby_on_panel_references_trigger_id: true",
+        "disabled_items_use_the_native_disabled_attribute: true",
+        "chevron_icon_is_aria_hidden: true",
+        "trigger_hit_area_is_at_least_44px: via the .t-accordion__trigger::after overlay",
+        "enter_space_toggle_the_focused_item: native button activation",
+        "arrow_down_focuses_next_enabled_trigger_wrapping_to_first: true",
+        "arrow_up_focuses_previous_enabled_trigger_wrapping_to_last: true",
+        "home_focuses_first_enabled_trigger: true",
+        "end_focuses_last_enabled_trigger: true"
+      ],
+      behavior: [
+        "controlled_only_while_model_value_is_not_undefined: true",
+        "default_value_seeds_uncontrolled_state_once: true",
+        "single_mode_opening_an_item_closes_the_previous_one: true",
+        "single_mode_collapsing_requires_collapsible: true",
+        "multiple_mode_ignores_collapsible: true",
+        "container_and_item_disabled_are_combined_with_or: true",
+        "arrow_navigation_skips_disabled_triggers: true",
+        "arrow_navigation_wraps_around: true",
+        "trigger_order_follows_item_mount_order: true",
+        "only_open_panels_are_rendered: true"
       ],
-      behavior: [],
       selection: {
         keywords: [
           "accordion",
@@ -845,7 +1162,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "accessible-by-default"
+      ]
     },
     {
       name: "TAlert",
@@ -862,14 +1182,15 @@ var treeui_catalog_default = {
       props: [
         {
           name: "variant",
-          type: "'info' | 'success' | 'warning' | 'danger'",
+          type: "TAlertVariant",
           default: "info",
           values: [
             "info",
             "success",
             "warning",
             "danger"
-          ]
+          ],
+          description: "Semantic tone. Sets the --tree-alert-* custom properties that colour the surface, border, icon, and dismiss button."
         },
         {
           name: "size",
@@ -879,42 +1200,55 @@ var treeui_catalog_default = {
             "sm",
             "md",
             "lg"
-          ]
+          ],
+          description: "Adjusts padding and font size only. md is the baseline defined on .t-alert itself."
         },
         {
           name: "dismissible",
           type: "boolean",
-          default: "false"
+          default: "false",
+          description: "Renders the trailing dismiss button. The button is the only thing gated by this prop; the alert never hides itself."
         }
       ],
       events: [
         {
           name: "dismiss",
-          description: "Emitted when the dismiss button is clicked.",
+          description: "Emitted when the dismiss button is clicked. TAlert is stateless \u2014 it does not hide, unmount, or animate itself out. The consumer owns removal (v-if, a list splice, or a store flag); without a handler the button is inert.\n",
           payload: "none"
         }
       ],
       slots: [
         {
           name: "default",
-          description: "Alert message content."
+          description: "Alert message content, rendered inside .t-alert__content."
         },
         {
           name: "icon",
-          description: "Optional leading icon; rendered with aria-hidden."
+          description: 'Optional leading icon. The .t-alert__icon wrapper span is rendered only when the slot is provided (v-if="$slots.icon") and is marked aria-hidden, so the icon is decorative \u2014 never put meaning there that is not also in the message text. The wrapper inherits the variant colour via --tree-alert-accent.\n'
         },
         {
           name: "dismiss-icon",
-          description: "Custom dismiss button content; replaces the default \xD7 icon."
+          description: 'Replaces the default 16x16 \xD7 SVG inside the dismiss button. Rendered only when dismissible is true, since the slot lives inside the button. Has a working default, so it is optional. The button keeps its aria-label="Dismiss" regardless of content.\n'
         }
       ],
       a11y: [
         "role: alert",
+        "role_is_on_root_element: true",
         "icon_slot_marked_aria_hidden: true",
+        "default_dismiss_icon_marked_aria_hidden: true",
         "dismiss_button_aria_label: Dismiss",
-        "keyboard: Tab to dismiss button, Enter/Space to activate"
+        "dismiss_button_label_is_hardcoded: true",
+        "dismiss_button_hit_area: 44x44 via a .t-alert__dismiss::after pseudo-element; the visible button is 1.5rem.",
+        "keyboard: Tab to dismiss button, Enter/Space to activate",
+        'live_region_caveat: role="alert" is an assertive live region. An alert that is already in the DOM on first paint is generally not announced \u2014 mount it dynamically (v-if / list insert) when you need the message read out.'
+      ],
+      behavior: [
+        "self_removes_on_dismiss: false",
+        "icon_wrapper_rendered_only_when_icon_slot_provided: true",
+        "dismiss_button_rendered_only_when_dismissible: true",
+        "size_md_emits_class_without_css_rule: t-alert--md is always emitted but carries no CSS rule of its own; .t-alert is the md baseline and only --sm and --lg override padding and font size.",
+        'variant_sets_local_custom_properties: ["--tree-alert-bg","--tree-alert-border","--tree-alert-text","--tree-alert-accent"]'
       ],
-      behavior: [],
       selection: {
         keywords: [
           "alert",
@@ -945,7 +1279,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "state-clarity"
+      ]
     },
     {
       name: "TAppShell",
@@ -963,7 +1300,8 @@ var treeui_catalog_default = {
         {
           name: "as",
           type: "string",
-          default: "div"
+          default: "div",
+          note: "Tag or component rendered as the shell root. The root is a plain `div` by default and is therefore not a landmark \u2014 the header/sidebar/main regions carry the semantics."
         },
         {
           name: "side",
@@ -977,164 +1315,254 @@ var treeui_catalog_default = {
         {
           name: "sidebarWidth",
           type: "string",
-          default: "17.5rem"
+          default: "17.5rem",
+          note: "Any CSS length. Sets `--tree-app-shell-sidebar-width` on the root, which drives the desktop rail track and also caps the mobile drawer at `min(100%, sidebarWidth)`."
         },
         {
           name: "collapsedWidth",
           type: "string",
-          default: "4.75rem"
+          default: "4.75rem",
+          note: "Any CSS length. Sets `--tree-app-shell-collapsed-width` on the root, but it only takes effect while the root carries `is-collapsed` (desktop + `collapsible` + collapsed)."
         },
         {
           name: "collapsible",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Master gate for the desktop rail. While false the root never gets `is-collapsed`, the built-in collapse toggle is not rendered, and `toggleCollapsed` is a no-op."
         },
         {
           name: "collapsed",
           type: "boolean",
-          default: "undefined"
+          default: "undefined",
+          note: "Controlled desktop rail state (v-model:collapsed). Leave undefined for uncontrolled. When set, the component only emits \u2014 the parent must apply the new value."
         },
         {
           name: "defaultCollapsed",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Initial value for uncontrolled use. Read once during setup; later changes to the prop are ignored."
         },
         {
           name: "mobile",
           type: "boolean",
-          default: "undefined"
+          default: "undefined",
+          note: "Forces mobile mode when explicitly true or false. Leave undefined to auto-detect from `breakpoint`."
         },
         {
           name: "breakpoint",
           type: "string",
-          default: "768px"
+          default: "768px",
+          note: "Any CSS length. Evaluated as `(max-width: <breakpoint>)` via matchMedia, and only consulted while `mobile` is undefined. Changing it tears down and rebuilds the media query listener."
         },
         {
           name: "sidebarOpen",
           type: "boolean",
-          default: "undefined"
+          default: "undefined",
+          note: "Controlled off-canvas drawer state (v-model:sidebarOpen). Mobile-only \u2014 the flag is tracked in desktop mode but nothing renders from it."
         },
         {
           name: "defaultSidebarOpen",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Initial value for uncontrolled use. Read once during setup."
+        },
+        {
+          name: "immersive",
+          type: "boolean",
+          default: "undefined",
+          note: "Controlled immersive state (v-model:immersive). Hides the header and sidebar so the content fills the viewport. The chrome is hidden with CSS rather than unmounted, so toggling never remounts the default slot. While immersive, the mobile drawer is not rendered."
+        },
+        {
+          name: "defaultImmersive",
+          type: "boolean",
+          default: "false",
+          note: "Initial value for uncontrolled use. Read once during setup."
         },
         {
           name: "closeOnEscape",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "Drawer only. Escape is handled on the drawer surface, so it fires only while focus is inside the drawer."
         },
         {
           name: "closeOnOverlay",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "Drawer only. Set false to keep the drawer open on backdrop clicks."
         },
         {
           name: "showMenuButton",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "Renders the built-in hamburger in the header. Mobile only. Set false to supply your own trigger and call the `toggleSidebar` slot prop from the `header` or `header-start` slot."
         },
         {
           name: "showCollapseButton",
           type: "boolean",
           default: "true",
-          note: "Renders the built-in collapse toggle in the sidebar footer. Desktop only, and only when `collapsible` is set \u2014 no need to wire your own."
+          note: "Renders the built-in collapse toggle in the sidebar footer. Desktop only, and only when `collapsible` is set \u2014 no need to wire your own. Never rendered in the mobile drawer."
         },
         {
           name: "collapseLabel",
           type: "string",
-          default: "Collapse sidebar"
+          default: "Collapse sidebar",
+          note: "aria-label of the collapse toggle while the rail is expanded."
         },
         {
           name: "expandLabel",
           type: "string",
-          default: "Expand sidebar"
+          default: "Expand sidebar",
+          note: "aria-label of the collapse toggle while the rail is collapsed."
         },
         {
           name: "menuLabel",
           type: "string",
-          default: "Open menu"
+          default: "Open menu",
+          note: "aria-label of the built-in hamburger. Static \u2014 it does not swap to a close label while the drawer is open."
         },
         {
           name: "closeLabel",
           type: "string",
-          default: "Close menu"
+          default: "Close menu",
+          note: "aria-label of the drawer's close button."
         },
         {
           name: "sidebarLabel",
           type: "string",
-          default: "Sidebar"
+          default: "Sidebar",
+          note: "aria-label applied to both the desktop <aside> and the drawer <aside>."
         }
       ],
       events: [
         {
-          name: "update:collapsed"
+          name: "update:collapsed",
+          description: "Desktop rail collapsed state changed. Enables v-model:collapsed.",
+          payload: "[value: boolean]"
         },
         {
-          name: "collapse-change"
+          name: "collapse-change",
+          description: "Same change as update:collapsed, for non-v-model usage. Both always fire together.",
+          payload: "[value: boolean]"
+        },
+        {
+          name: "update:sidebarOpen",
+          description: "Off-canvas drawer open state changed. Enables v-model:sidebarOpen.",
+          payload: "[value: boolean]"
         },
         {
-          name: "update:sidebarOpen"
+          name: "sidebar-open-change",
+          description: "Same change as update:sidebarOpen, for non-v-model usage. Both always fire together.",
+          payload: "[value: boolean]"
+        },
+        {
+          name: "update:immersive",
+          description: "Immersive state changed. Enables v-model:immersive.",
+          payload: "[value: boolean]"
         },
         {
-          name: "sidebar-open-change"
+          name: "immersive-change",
+          description: "Same change as update:immersive, for non-v-model usage. Both always fire together.",
+          payload: "[value: boolean]"
         }
       ],
       slots: [
         {
-          name: "header"
+          name: "header",
+          description: "Main header region. Spans the full header width by default; once `header-start` is filled it is constrained to the content column so it lines up with the panel underneath. On mobile the header falls back to a single flex row either way.\n",
+          note: "AppShellSlotProps \u2014 { mobile, collapsed, sidebarOpen, immersive, toggleSidebar, closeSidebar, toggleCollapsed, toggleImmersive }"
         },
         {
-          name: "header-start"
+          name: "header-start",
+          description: "Header region sitting over the sidebar rail (typically the brand mark). Filling it adds `has-start` to the header, which switches the header to the shell's own two-column grid and tracks the rail width as it collapses.\n",
+          note: "AppShellSlotProps"
         },
         {
-          name: "sidebar-header"
+          name: "sidebar-header",
+          description: "Pinned above the sidebar body, inset to line up with nav item icons. Rendered in both the desktop aside and the mobile drawer.\n",
+          note: "AppShellSlotProps"
         },
         {
-          name: "sidebar"
+          name: "sidebar",
+          description: "Sidebar body \u2014 the natural home for a TNavMenu, which picks up the collapsed state through provide/inject. Rendered in both the desktop aside and the mobile drawer, and takes the vertical slack so the footer pins to the bottom.\n",
+          note: "AppShellSlotProps"
         },
         {
-          name: "sidebar-footer"
+          name: "sidebar-footer",
+          description: "Pinned to the bottom of the sidebar, inset to line up with nav item icons. In the desktop aside it shares one container with the built-in collapse toggle, which is rendered after the slot content; in the mobile drawer the container holds the slot content alone.\n",
+          note: "AppShellSlotProps"
         },
         {
-          name: "default"
+          name: "default",
+          description: "Main content area. Scrolls independently of the header and sidebar.",
+          note: "{ mobile: boolean, collapsed: boolean, immersive: boolean, toggleImmersive: () => void } \u2014 a subset of AppShellSlotProps. toggleImmersive is included because immersive hides the chrome, so the content is the only place an exit control can live."
         },
         {
-          name: "menu-icon"
+          name: "menu-icon",
+          description: "Replaces the default hamburger glyph inside the built-in menu button. Use `sidebarOpen` to swap the icon while the drawer is open. Renders inside the button, so it must be presentational only.\n",
+          note: "{ sidebarOpen: boolean }"
         },
         {
-          name: "collapse-icon"
+          name: "collapse-icon",
+          description: "Replaces the default glyph inside the built-in collapse toggle. Renders inside the button, so it must be presentational only.\n",
+          note: "{ collapsed: boolean }"
         }
       ],
       a11y: [
-        "role: dialog",
+        "semantic_regions: <header>, <aside> and <main>; the shell root itself is a plain div and is not a landmark",
+        "role: dialog \u2014 on the mobile drawer only",
         "aria_modal: true",
-        "focus_trap: true",
-        "restores_focus_on_close: true",
+        "focus_trap: Tab and Shift+Tab cycle inside the drawer; with no focusable descendant, focus is pinned to the drawer itself",
+        "restores_focus_on_close: only when the drawer was opened through the built-in menu button or the toggleSidebar slot prop \u2014 those capture document.activeElement first",
         "escape_closes_when_enabled: true",
         "menu_button_aria_expanded: true",
-        "menu_button_aria_controls_drawer: true",
-        "sidebar_labelled_by_sidebar_label: true"
+        "menu_button_aria_controls_drawer: aria-controls always points at the sidebar id, and on mobile that element exists only while the drawer is open",
+        "collapse_button_aria_expanded: reflects the expanded rail, i.e. !collapsed",
+        "collapse_button_aria_controls_sidebar: true",
+        "collapse_button_label_swaps_by_state: collapseLabel while expanded, expandLabel while collapsed",
+        "drawer_close_button_labelled_by_close_label: true",
+        "sidebar_labelled_by_sidebar_label: true",
+        "drawer_focusable_via_tabindex_minus_one: true",
+        "backdrop_is_aria_hidden: true",
+        "built_in_icons_are_aria_hidden: true",
+        "menu_and_drawer_close_buttons_are_44px: true"
       ],
       behavior: [
         "fills_viewport_full_width_and_height: true",
+        "resets_body_margin_while_a_shell_is_mounted: body:has(.t-app-shell) { margin: 0 } \u2014 a deliberate global rule, scoped so it only applies to pages that mount a shell",
         "header_spans_full_width_above_sidebar_and_content: true",
         "content_area_scrolls_independently: true",
         "auto_switches_to_mobile_at_breakpoint_when_mobile_undefined: true",
         "mobile_prop_forces_mobile_mode: true",
         "mobile_sidebar_becomes_off_canvas_drawer: true",
+        "desktop_sidebar_is_removed_from_the_dom_on_mobile: crossing the breakpoint unmounts and remounts the sidebar slot, so component state inside it is not preserved",
+        "drawer_is_rendered_only_while_mobile_and_open: true",
         "auto_menu_button_in_header_on_mobile: true",
         "controlled_and_uncontrolled_collapsed_state: true",
         "controlled_and_uncontrolled_sidebar_open_state: true",
+        "controlled_and_uncontrolled_immersive_state: true",
+        "immersive_hides_chrome_without_remounting_content: the header and sidebar are hidden with CSS and the grid collapses to a single `main` area, so the default slot keeps its component state across the toggle \u2014 unlike the mobile breakpoint, which does remount the sidebar slot",
+        "immersive_suppresses_the_mobile_drawer: while immersive the overlay is not rendered, since the trigger that opens it lives in the hidden header",
+        "controlled_mode_does_not_self_update: when collapsed, sidebarOpen or immersive is bound, the component only emits \u2014 the parent must apply the value",
+        "no_emit_when_the_value_is_unchanged: true",
+        "toggle_collapsed_is_a_noop_when_collapsible_is_false: true",
+        "collapse_toggle_requires_desktop_and_collapsible_and_show_collapse_button: true",
         "provides_collapsed_state_to_descendants: true",
         "drawer_reports_collapsed_false_to_descendants_and_slots: true",
         "left_and_right_variants: true",
         "locks_body_scroll_while_drawer_open: true",
+        "releases_the_scroll_lock_when_leaving_mobile_while_open: true",
+        "rearms_the_overlay_when_reentering_mobile_while_open: true",
         "overlay_click_closes_when_enabled: true",
         "exposes_slot_props_with_mobile_collapsed_and_toggles: true",
         "sidebar_footer_pinned_to_bottom: true",
         "sidebar_header_and_footer_inset_to_align_with_nav_icons: true",
-        "header_mirrors_shell_columns_when_header_start_is_used: true"
+        "header_mirrors_shell_columns_when_header_start_is_used: true",
+        "header_start_falls_back_to_a_single_flex_row_on_mobile: true",
+        "animates_the_rail_width_via_grid_template_columns: true",
+        "main_panel_has_a_rounded_inner_corner_on_the_sidebar_side_on_desktop: true",
+        "drawer_width_is_capped_at_min_of_100_percent_and_sidebar_width: true",
+        'root_data_attribute: data-mobile="true" | "false" on the shell root',
+        "respects_prefers_reduced_motion: true"
       ],
       selection: {
         keywords: [
@@ -1180,15 +1608,17 @@ var treeui_catalog_default = {
         ]
       },
       recipes: [
-        "app-shell"
-      ]
+        "app-shell",
+        "brand-lockup"
+      ],
+      practices: []
     },
     {
       name: "TAvatar",
       aliases: [],
       package: "@treeui/vue",
       category: "Data Display",
-      description: "User image with fallback initials and optional status indicator dot.",
+      description: "User avatar that renders an image when `src` is set, otherwise initials derived from `alt`, plus an optional status indicator dot.",
       sourceFile: "packages/vue/src/components/TAvatar.vue",
       storyFile: "apps/docs/src/stories/Avatar.stories.ts",
       storyTitle: "Components/Data Display/Avatar",
@@ -1198,19 +1628,19 @@ var treeui_catalog_default = {
           name: "src",
           type: "string",
           required: false,
-          description: "URL of the avatar image."
+          description: "URL of the avatar image. When set, the `<img>` branch renders and the initials span is NOT in the DOM at all (`v-else`). If the image fails to load, the `<img>` is hidden via inline `display: none` \u2014 the component does NOT fall back to initials, leaving an empty circle. Pass no `src` if you want initials.\n"
         },
         {
           name: "alt",
           type: "string",
           default: '""',
-          description: "Accessible label for the avatar. Also used to derive initials if `initials` is not set."
+          description: "Accessible label for the avatar and the `alt` attribute of the `<img>`. Also the source for derived initials when `initials` is not set. Defaults to an empty string, in which case no `aria-label` is rendered at all (`alt || undefined`) and derived initials are empty \u2014 always pass a meaningful `alt`.\n"
         },
         {
           name: "initials",
           type: "string",
           required: false,
-          description: "Explicit initials to display when no image is provided. Overrides derived initials from `alt`."
+          description: 'Explicit initials, rendered only when `src` is unset. Takes precedence over initials derived from `alt`. When omitted, initials are derived from `alt` by splitting on spaces, taking the first character of the first two words, and uppercasing (e.g. "Jane Doe" -> "JD").\n'
         },
         {
           name: "size",
@@ -1220,7 +1650,8 @@ var treeui_catalog_default = {
             "sm",
             "md",
             "lg"
-          ]
+          ],
+          description: "Fixed square dimensions \u2014 sm 2rem, md 2.5rem, lg 3.5rem \u2014 with matching font size for initials."
         },
         {
           name: "status",
@@ -1232,20 +1663,23 @@ var treeui_catalog_default = {
             "busy",
             "away"
           ],
-          description: "Shows a colored status dot on the avatar."
+          description: "Shows a colored status dot pinned to the bottom-right of the avatar bounding box. Renders alongside either branch (image or initials). The dot sits on the corner outside the circular mask, so `.t-avatar` deliberately has no `overflow: hidden`.\n"
         }
       ],
       events: [],
       slots: [
         {
           name: "default",
-          description: "Optional overlay content inside the avatar."
+          description: 'Optional overlay content, rendered inside the `.t-avatar` span after the image/initials and before the status dot. The parent is `position: relative`, so children can be absolutely positioned. Note the wrapper carries `role="img"`, which makes its subtree presentational to assistive technology \u2014 slot content is visual only and will not be announced.\n'
         }
       ],
       a11y: [
-        "role: img",
-        "aria-label: Derived from `alt` prop.",
-        "status_dot: Has its own `aria-label` with the status value."
+        "role: img (always set on the root span, including when only initials render)",
+        'aria-label: Set from `alt`. Omitted entirely when `alt` is empty (the default), which leaves the `role="img"` element without an accessible name.',
+        'initials: Marked `aria-hidden="true"` \u2014 the name comes from `alt`, not the visible text.',
+        "image: Receives the `alt` prop as its native `alt` attribute.",
+        "status_dot: Carries `aria-label` with the status value, but the element is a bare `<span>` with no role, so the label is not exposed to assistive technology. Convey status in text if it matters.",
+        'slot_content: Not announced \u2014 the `role="img"` root makes descendant content presentational.'
       ],
       behavior: [],
       selection: {
@@ -1258,7 +1692,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [
+        "brand-lockup"
+      ],
+      practices: []
     },
     {
       name: "TBadge",
@@ -1283,7 +1720,8 @@ var treeui_catalog_default = {
             "ghost",
             "soft",
             "danger"
-          ]
+          ],
+          description: "Surface treatment. Selects which --tree-badge-<variant>-* colour variables the badge consumes; danger is a surface style, not a semantic guarantee \u2014 its red palette is replaced when tone is success, warning, or info."
         },
         {
           name: "tone",
@@ -1296,7 +1734,7 @@ var treeui_catalog_default = {
             "danger",
             "info"
           ],
-          description: "Optional semantic tone layered on top of the visual variant."
+          description: "Semantic palette. Re-maps the --tree-badge-* colour variables that the chosen variant consumes, so it recolours the badge without changing its surface treatment. neutral keeps the brand palette."
         },
         {
           name: "size",
@@ -1306,7 +1744,8 @@ var treeui_catalog_default = {
             "sm",
             "md",
             "lg"
-          ]
+          ],
+          description: "Changes min-height and font-size only; inline padding is constant across sizes."
         }
       ],
       events: [],
@@ -1319,10 +1758,19 @@ var treeui_catalog_default = {
         }
       ],
       a11y: [
+        "semantic_element: span",
         "interactive_by_default: false",
-        "icon_slot_marked_aria_hidden: true"
+        "icon_slot_marked_aria_hidden: true",
+        "tone_conveys_meaning_by_color_only: No role or aria state is set, so put the status word in the badge text rather than relying on tone alone."
+      ],
+      behavior: [
+        "always_applies_one_modifier_per_prop: true",
+        "tone_remaps_variant_color_variables: true",
+        "tone_overrides_variant_danger_palette: true",
+        "tone_neutral_has_no_stylesheet_rule: true",
+        "icon_wrapper_rendered_only_when_slot_filled: true",
+        "icon_renders_before_default_slot: true"
       ],
-      behavior: [],
       selection: {
         keywords: [],
         useWhen: [],
@@ -1335,6 +1783,11 @@ var treeui_catalog_default = {
       },
       recipes: [
         "pricing-section"
+      ],
+      practices: [
+        "predictable-api",
+        "state-clarity",
+        "token-driven"
       ]
     },
     {
@@ -1354,23 +1807,32 @@ var treeui_catalog_default = {
           name: "separator",
           type: "string",
           default: "/",
-          description: "Character or string used to separate breadcrumb items."
+          description: "Character or string shown between items. Applied as the inline CSS custom property --tree-breadcrumb-separator on the <ol>, wrapped in single quotes, and drawn by the .t-breadcrumb__item:not(:last-child)::after pseudo-element \u2014 it never enters the DOM as text. A value containing a single quote or a backslash produces an invalid CSS value and the separator stops rendering."
         }
       ],
       events: [],
       slots: [
         {
-          name: "default"
+          name: "default",
+          description: "Breadcrumb trail content, rendered inside the <ol class='t-breadcrumb__list'>. Expects TBreadcrumbItem children so each entry becomes an <li>. No scoped props."
         }
       ],
       a11y: [
         "element: nav",
         "aria_label: Breadcrumb",
+        "aria_label_hardcoded_but_overridable_via_fallthrough_attrs: true",
         "current_page_aria_current: page",
         "uses_ol_for_ordered_list: true",
         "interactive_by_default: false"
       ],
-      behavior: [],
+      behavior: [
+        "link_target_precedence: to + resolvable RouterLink, then href, then string to",
+        "string_to_without_router_renders_native_anchor: true",
+        "object_to_without_router_renders_current_span: true",
+        "current_state_is_not_positional: true",
+        "separator_rendered_by_css_pseudo_element: true",
+        "separator_ignores_pointer_events: true"
+      ],
       selection: {
         keywords: [],
         useWhen: [],
@@ -1384,7 +1846,8 @@ var treeui_catalog_default = {
           "Use `to` when the app has vue-router and breadcrumb items should render RouterLink."
         ]
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TButton",
@@ -1402,7 +1865,8 @@ var treeui_catalog_default = {
         {
           name: "as",
           type: "string",
-          default: "button"
+          default: "button",
+          note: "Root tag rendered through `<component :is>`. Any value other than `button` switches the component onto the non-native accessibility path (see `a11y`) and stops the `type` attribute from being rendered."
         },
         {
           name: "variant",
@@ -1426,23 +1890,50 @@ var treeui_catalog_default = {
             "sm",
             "md",
             "lg"
-          ]
+          ],
+          note: "`t-button--md` is emitted but carries no CSS rule of its own \u2014 md is the base sizing, and only sm/lg override height, padding, and font size."
         },
         {
           name: "disabled",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: 'Applied as the native `disabled` attribute only when `as` is `button`; for any other tag the component falls back to `aria-disabled="true"` plus `tabindex="-1"`. Clicks are blocked in both cases.'
         },
         {
           name: "loading",
           type: "boolean",
           default: "false",
-          note: "loading implies disabled behavior"
+          note: "loading implies disabled behavior \u2014 the effective disabled state is `disabled || loading`, so `loading` on its own disables the button and applies `is-disabled`."
+        },
+        {
+          name: "loadingLabel",
+          type: "string",
+          default: "Loading",
+          note: "Accessible announcement while loading, forwarded to the nested TSpinner's `label`. The default is English because TreeUI ships no i18n layer \u2014 pass the active locale's string to localize it (see DECISIONS.md \u2192 Locale Data)."
+        },
+        {
+          name: "hideIconWhileLoading",
+          type: "boolean",
+          default: "true",
+          note: "While loading, the `icon` slot is not rendered so the spinner replaces the icon instead of rendering beside it. Set to `false` to restore the pre-0.19 behavior of showing both."
+        },
+        {
+          name: "iconOnly",
+          type: "boolean",
+          default: "false",
+          note: "Square, icon-only button \u2014 collapses the inline padding to a 1:1 control matching the size token and suppresses the `t-button__label` wrapper. Requires an accessible name via `label` (or `aria-label`), since the icon slot is aria-hidden."
+        },
+        {
+          name: "label",
+          type: "string",
+          default: "undefined",
+          note: "Accessible name, rendered as `aria-label`. Required whenever `iconOnly` is set; ignored for ordinary buttons that already have visible text."
         },
         {
           name: "type",
           type: "button | submit | reset",
-          default: "button"
+          default: "button",
+          note: 'Only forwarded when `as` is `button`; for any other tag no `type` attribute is rendered. Set `type="submit"` for the submit control of an enclosing form.'
         },
         {
           name: "block",
@@ -1454,12 +1945,14 @@ var treeui_catalog_default = {
           name: "align",
           type: "start | center | end",
           default: "center",
-          note: "Content alignment; only meaningful together with `block`. Use `start` for left-aligned icon+label menu rows."
+          note: "Content alignment; only meaningful once the button is wider than its content, which in practice means together with `block`, since the base rule is `min-width: max-content`. Use `start` for left-aligned icon+label menu rows. The default `center` emits no modifier class \u2014 it is the base rule."
         }
       ],
       events: [
         {
-          name: "click"
+          name: "click",
+          description: "Emitted on activation. Suppressed while disabled or loading: the internal handler calls preventDefault() and stopPropagation() and returns without emitting.",
+          payload: "[event: MouseEvent]"
         }
       ],
       slots: [
@@ -1472,13 +1965,22 @@ var treeui_catalog_default = {
       ],
       a11y: [
         "native_button_by_default: true",
+        "native_disabled_attr_only_when_button: true",
         "aria_busy_when_loading: true",
         "aria_disabled_for_non_button: true",
-        "tabindex_minus_one_when_non_button_disabled: true"
+        "tabindex_minus_one_when_non_button_disabled: true",
+        "icon_slot_marked_aria_hidden: true",
+        "loading_spinner_is_announced: The nested TSpinner carries role=\"status\" and a visually hidden label, so the button's accessible name gains that text while loading. The text comes from `loadingLabel`, so it follows the app's locale.",
+        "icon_only_requires_an_accessible_name: With `iconOnly` there is no visible text and the icon slot is aria-hidden, so the name must come from `label` or `aria-label`. This is a documented requirement, not a runtime assertion \u2014 the package ships ESM+CJS with no dev-only build define, so there is no dev-stripped warning.",
+        "touch_targets: 44\xD744px minimum via the .t-button::after overlay",
+        "focus_visible: box-shadow focus ring on the root element"
       ],
       behavior: [
         "blocks_click_when_disabled_or_loading: true",
-        "renders_spinner_when_loading: true"
+        "renders_spinner_when_loading: true",
+        "spinner_replaces_the_icon_slot_while_loading: The spinner takes the icon's leading position, so by default the icon slot is withheld while loading and the order is spinner, label. Set `hideIconWhileLoading: false` for the older spinner, icon, label order.",
+        "icon_slot_wrapper_rendered_only_when_filled: true",
+        "default_slot_wrapped_in_label_element_unless_icon_only: true"
       ],
       selection: {
         keywords: [],
@@ -1493,6 +1995,11 @@ var treeui_catalog_default = {
       recipes: [
         "confirm-destructive-action",
         "pricing-section"
+      ],
+      practices: [
+        "interaction-feedback",
+        "accessible-by-default",
+        "predictable-api"
       ]
     },
     {
@@ -1502,7 +2009,7 @@ var treeui_catalog_default = {
       kind: "layout",
       category: "Data Display",
       status: "available",
-      purpose: "Surface container with optional header and footer slots.",
+      purpose: "Surface container with optional header, actions, and footer slots.",
       sourceFile: "packages/vue/src/components/TCard.vue",
       storyFile: "apps/docs/src/stories/Card.stories.ts",
       storyTitle: "Components/Data Display/Card",
@@ -1511,7 +2018,8 @@ var treeui_catalog_default = {
         {
           name: "as",
           type: "string",
-          default: "section"
+          default: "section",
+          description: 'Tag or component used for the polymorphic root, rendered through `<component :is="as">`. Change it to `article`, `aside`, `li`, or `div` when the default `section` element is wrong for the surrounding document structure. It only swaps the element \u2014 classes, slots, and layout are unchanged.\n'
         },
         {
           name: "variant",
@@ -1527,37 +2035,44 @@ var treeui_catalog_default = {
           name: "size",
           type: "TSize",
           default: "md",
-          values: [
-            "sm",
-            "md",
-            "lg"
-          ]
+          description: "Padding scale only \u2014 it does not change typography, border, or radius. `sm` uses --tree-space-3, `md` --tree-space-4, `lg` --tree-space-5.\n"
         },
         {
           name: "title",
           type: "string",
           default: "undefined",
-          description: "Optional card heading rendered inside the header area."
+          description: "Optional card heading. Rendered as the fallback content of the `header` slot inside a `span.t-card__title`, so supplying `#header` replaces it entirely. Setting it also forces the header element to render. Because it is declared as a prop it is consumed by the component and never reaches the root element as the native HTML `title` tooltip attribute.\n"
         }
       ],
       events: [],
       slots: [
         {
-          name: "header"
+          name: "header",
+          description: "Replaces the `title` fallback inside `header.t-card__header`. When this slot is supplied the `title` prop renders nothing. Receives no slot props.\n"
         },
         {
-          name: "actions"
+          name: "actions",
+          description: "Trailing controls wrapped in `span.t-card__actions`, rendered as a sibling after the header content inside the same `header.t-card__header`. Supplying it is enough to render the header on its own, with no `title` and no `header` slot. Receives no slot props.\n"
         },
         {
-          name: "default"
+          name: "default",
+          description: "Card body. Always rendered, wrapped in `div.t-card__body`. Receives no slot props.\n"
         },
         {
-          name: "footer"
+          name: "footer",
+          description: "Renders `footer.t-card__footer` only when the slot is supplied; there is no `footer` prop fallback. Receives no slot props.\n"
         }
       ],
-      a11y: [],
+      a11y: [
+        "root_role: None applied by the component \u2014 semantics come entirely from `as` (default `section`).",
+        "title_is_not_a_heading: `title` renders a `span.t-card__title`, styled at heading size and weight but carrying no heading semantics, so it does not enter the document outline. When the card must be reachable by heading navigation, put a real `<h2>`/`<h3>` in the `header` slot instead of using the prop.",
+        "unnamed_section_root: The default `section` root has no accessible name, so assistive tech exposes it as generic rather than as a region. The component sets no `inheritAttrs: false` and has a single root, so `aria-label` / `aria-labelledby` passed by the consumer fall through to that root when a named region is wanted."
+      ],
       behavior: [
         "body_wrapper_class: t-card__body",
+        "header_render_condition: The `header.t-card__header` element renders when ANY of the `header` slot, a truthy `title` prop, or the `actions` slot is present. All three branches are independent \u2014 actions alone still produces a header.",
+        "footer_render_condition: The `footer.t-card__footer` element renders only when the `footer` slot is supplied.",
+        "slot_props: None. No slot on this component is scoped; all four are plain content slots.",
         'variant_effects: {"outline":"Base surface with a default border. The styling baseline \u2014 the `t-card--outline` class is emitted but carries no CSS rule of its own.","soft":"Subtle tinted surface (bg-subtle), same border and shadow as outline.","inset":"Same tinted surface as soft, but with no shadow, so it reads as recessed inside another surface."}',
         "note: No card variant inverts its surface, so nested content inherits the normal color tokens. For a high-emphasis card, use a brand-colored border rather than an inverted background."
       ],
@@ -1592,6 +2107,10 @@ var treeui_catalog_default = {
       },
       recipes: [
         "chart-surface"
+      ],
+      practices: [
+        "predictable-api",
+        "token-driven"
       ]
     },
     {
@@ -1621,13 +2140,13 @@ var treeui_catalog_default = {
           name: "series",
           type: "TChartSeries[]",
           default: "[]",
-          note: "Each item is { name: string; data: number[]; color?: string }."
+          note: "Each item is { name: string; data: number[]; color?: string }. Series with an empty data array are dropped before rendering \u2014 they never reach the plot, legend, tooltip, or a11y table."
         },
         {
           name: "labels",
           type: "string[]",
           default: "[]",
-          note: "X-axis categories, aligned index-for-index to each series' data."
+          note: "X-axis categories, aligned index-for-index to each series' data. Labels past the longest series are ignored; a missing label falls back to '#<n>' in the tooltip and to an empty header cell in the a11y table."
         },
         {
           name: "height",
@@ -1639,80 +2158,91 @@ var treeui_catalog_default = {
           name: "smooth",
           type: "boolean",
           default: "false",
-          note: "Curved line/area."
+          note: "Curved line/area; ignored for bar."
         },
         {
           name: "stacked",
           type: "boolean",
           default: "false",
-          note: "Stacks bar series; ignored for line/area. Negative values are clamped to 0 in stacked mode (grouped mode renders them)."
+          note: "Stacks bar series; ignored for line/area. Negative values are clamped to 0 in stacked mode (grouped mode renders them below the baseline). The tooltip always reports the raw per-series values, not the cumulative stack."
         },
         {
           name: "showGrid",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "Horizontal gridlines at the y ticks. Independent of showYAxis, which controls the tick text."
         },
         {
           name: "showLegend",
-          type: "boolean",
-          default: "auto (true when more than one series)"
+          type: "boolean | undefined",
+          default: "auto (true when more than one series)",
+          note: "The legend is suppressed whenever there is no data, even when set to true."
         },
         {
           name: "showXAxis",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "When false the category labels are skipped and the bottom margin collapses from 28px to 10px."
         },
         {
           name: "showYAxis",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "When false the tick text is skipped and the left margin collapses from 44px to 10px. Gridlines are unaffected."
         },
         {
           name: "showTooltip",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "Gates hover tracking as a whole: the crosshair, the tooltip panel, and the point-click event all stop when false."
         },
         {
           name: "showPoints",
           type: "boolean",
           default: "false",
-          note: "Always draw markers on line/area points."
+          note: "Always draw markers on line/area points; ignored for bar."
         },
         {
           name: "yTicks",
           type: "number",
-          default: "5"
+          default: "5",
+          note: "Target tick count handed to niceScale \u2014 the rendered count may differ once the bounds are rounded."
         },
         {
           name: "valueFormat",
           type: "(value: number) => string",
-          default: "locale integers for |value| >= 1000"
+          default: "locale integers for |value| >= 1000",
+          note: "Applies to y-axis ticks, tooltip values, and the a11y table cells."
         },
         {
           name: "minY",
           type: "number",
-          default: "auto"
+          default: "auto (min(0, data min) for bar/area, data min for line)",
+          note: "A hint, not a hard bound: niceScale rounds the low end down, so the rendered domain can start below it."
         },
         {
           name: "maxY",
           type: "number",
-          default: "auto"
+          default: "auto",
+          note: "A hint, not a hard bound: niceScale rounds the high end up, so the rendered domain can extend above it."
         },
         {
           name: "animated",
           type: "boolean",
           default: "true",
-          note: "Draw-in animation; disabled under prefers-reduced-motion."
+          note: "Draw-in animation via the is-animated root class; disabled under prefers-reduced-motion."
         },
         {
           name: "loading",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Replaces the plot with five pulsing skeleton bars and adds the is-loading root class. Takes precedence over the empty state; the legend still renders when data is present."
         },
         {
           name: "ariaLabel",
           type: "string",
-          default: "auto-generated summary"
+          default: "auto-generated summary ('<type> chart with <n> series')",
+          note: "Rendered as the <caption> of the visually-hidden data table \u2014 it is not applied as an aria-label attribute on the root."
         }
       ],
       events: [
@@ -1734,14 +2264,19 @@ var treeui_catalog_default = {
       ],
       a11y: [
         "SVG is aria-hidden; a visually-hidden <table> mirrors the series data for assistive tech.",
+        "The table's <caption> carries ariaLabel (or the auto-generated summary); the root div itself has no role or accessible name.",
         "Legend defaults on for multiple series so identity is not color-only.",
-        "Provide a meaningful ariaLabel describing what the chart shows."
+        "Provide a meaningful ariaLabel describing what the chart shows.",
+        "point-click has no keyboard equivalent \u2014 do not make it the only way to reach a behavior."
       ],
       behavior: [
-        "colors_auto_assign_from_chart_palette: --tree-color-chart-1..8, cycling; per-series color overrides",
-        "bar_zero_baseline: true",
-        "line_domain_uses_nice_ticks: true",
-        "hover_shows_crosshair_and_tooltip: true"
+        "colors_auto_assign_from_chart_palette: --tree-color-chart-1..8, cycling by series index; per-series color overrides",
+        "zero_baseline_for_bar_and_area: the y domain is extended to include 0 for bar and area; line uses the data extent. minY overrides it.",
+        "y_domain_uses_nice_ticks: every type runs through niceScale, which rounds the min down and the max up to round numbers",
+        "hover_shows_crosshair_and_tooltip: only while showTooltip is true",
+        "width_measured_with_resize_observer: falls back to 640px until the canvas is mounted and measured",
+        "x_labels_decimate_when_crowded: keeps every max(2, floor(innerWidth / 52))-th label and hides the rest; the last category is always kept",
+        "empty_state_when_no_series_has_data: true"
       ],
       selection: {
         keywords: [
@@ -1788,6 +2323,9 @@ var treeui_catalog_default = {
       recipes: [
         "chart-surface",
         "metric-dashboard"
+      ],
+      practices: [
+        "token-driven"
       ]
     },
     {
@@ -1806,7 +2344,8 @@ var treeui_catalog_default = {
         {
           name: "modelValue",
           type: "boolean",
-          default: "false"
+          default: "false",
+          description: "Checked state. Fully controlled \u2014 the component holds no internal state and never mutates this prop; it emits update:modelValue and the parent must write the value back.\n"
         },
         {
           name: "size",
@@ -1816,44 +2355,60 @@ var treeui_catalog_default = {
             "sm",
             "md",
             "lg"
-          ]
+          ],
+          description: "Control and label scale. Always rendered as a t-checkbox--<size> modifier."
         },
         {
           name: "disabled",
           type: "boolean",
-          default: "false"
+          default: "false",
+          description: "Sets the native disabled attribute on the input and adds is-disabled to the root. No aria-disabled is emitted \u2014 the native attribute carries the state.\n"
         },
         {
           name: "indeterminate",
           type: "boolean",
-          default: "false"
+          default: "false",
+          description: `Mixed state. Renders the dash icon and sets aria-checked="mixed", taking precedence over modelValue for both. Synced to the input's native indeterminate DOM property.
+`
         },
         {
           name: "invalid",
           type: "boolean",
-          default: "false"
+          default: "false",
+          description: 'Adds is-invalid to the root and aria-invalid="true" to the input. When false the aria-invalid attribute is omitted entirely, not set to "false".\n'
         }
       ],
       events: [
         {
-          name: "update:modelValue"
+          name: "update:modelValue",
+          description: "Emitted on the native input's change event. The payload is always the negation of the current modelValue prop, not the DOM checked state. Enables v-model binding.\n",
+          payload: "[value: boolean]"
         }
       ],
       slots: [
         {
-          name: "default"
+          name: "default",
+          description: 'Label content, wrapped in <span class="t-checkbox__label">. Rendered only when the slot is supplied (v-if="$slots.default"). The root element is a <label> that wraps the input, so slot text labels the control implicitly \u2014 no for/id pairing is needed.\n'
         }
       ],
       a11y: [
         "role: native_checkbox",
+        "accessible_name: From the default slot; absent when the slot is omitted \u2014 supply aria-label or aria-labelledby",
+        "aria_checked_explicitly_bound: 'mixed' when indeterminate, otherwise the modelValue boolean",
         "aria_checked_mixed_when_indeterminate: true",
         "aria_invalid_when_invalid: true",
+        "native_indeterminate_property_synced: true",
+        "disabled_uses_native_attribute: true",
         "focus_visible_on_control: true",
+        "input_is_visually_hidden_but_focusable: clip-rect hidden input keeps native semantics and tab order; the focus ring is drawn on t-checkbox__control",
         "clickable_target_44x44: true"
       ],
       behavior: [
         "update_payload_type: boolean",
+        "controlled_only: No internal state; the checkbox does not change appearance until the parent updates modelValue",
+        "indeterminate_precedence: indeterminate wins over modelValue for the rendered icon and for aria-checked; is-checked and is-indeterminate can both be present at once",
         "indeterminate_clears_on_user_toggle: false",
+        "indeterminate_is_parent_owned: The component never clears indeterminate \u2014 set it to false yourself when handling update:modelValue",
         "label_click_toggles_checkbox: true"
       ],
       selection: {
@@ -1886,7 +2441,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "interaction-feedback"
+      ]
     },
     {
       name: "TColorSwatch",
@@ -1905,19 +2463,19 @@ var treeui_catalog_default = {
           name: "modelValue",
           type: "string",
           default: "undefined",
-          note: "Selected colour as a hex string. Matching is case-insensitive."
+          note: "Selected colour as a hex string. Matched against `options[].value` by case-insensitive exact string comparison, so `#0969DA` matches `#0969da` but `#fff` never matches `#ffffff`. A value matching no preset leaves every swatch unselected and is still written to the custom input."
         },
         {
           name: "options",
           type: "TColorSwatchOption[]",
           default: "[]",
-          note: "Preset swatches, each `{ label, value }`. `label` becomes the button's accessible name."
+          note: "Preset swatches, each `{ label, value }`. `value` is applied raw as the button `background`, so any CSS colour renders, but keep it `#rrggbb` so matching and the custom input agree. `label` is the button's only accessible name \u2014 the button renders no text content. An empty array renders an empty group (only the custom input, when enabled)."
         },
         {
           name: "allowCustom",
           type: "boolean",
           default: "false",
-          note: 'Appends a native `<input type="color">` for values outside the presets.'
+          note: 'Appends a native `<input type="color">` after the presets for values outside them. When false the input is not rendered at all and `customLabel` has no effect.'
         },
         {
           name: "size",
@@ -1927,23 +2485,26 @@ var treeui_catalog_default = {
             "sm",
             "md",
             "lg"
-          ]
+          ],
+          note: "Drives `--tree-color-swatch-size` (sm 1.5rem, md 1.75rem, lg 2rem). Swatches are square; the custom input is one `--tree-space-2` wider."
         },
         {
           name: "label",
           type: "string",
           default: "Color",
-          note: 'Accessible label for the swatch group (`role="group"`).'
+          note: 'Accessible label for the swatch group (`role="group"`). Rendered as `aria-label` on the root, so an `aria-label` passed by the consumer falls through to the same element and overrides it.'
         },
         {
           name: "customLabel",
           type: "string",
-          default: "Custom color"
+          default: "Custom color",
+          note: "Accessible label (`aria-label`) for the native colour input, and its only accessible name. Applies only when `allowCustom` is set."
         },
         {
           name: "disabled",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Sets the native `disabled` attribute on every preset button and on the custom input, so the group stops emitting and drops out of the Tab order. Not reflected on the wrapper, and there is no `is-disabled` class."
         }
       ],
       events: [
@@ -1953,14 +2514,21 @@ var treeui_catalog_default = {
       ],
       slots: [],
       a11y: [
-        'Wrapper is `role="group"` labelled by `label`.',
-        "Each swatch is a native button with `aria-pressed` reflecting selection and `aria-label` from the option label.",
-        "Selection is conveyed by an outline (not colour alone), since the swatch's own colour is the content."
+        'Wrapper is `role="group"` labelled by `label` via `aria-label`.',
+        'Each swatch is a native `<button type="button">` with `aria-pressed` reflecting selection and `aria-label` from the option label; it has no text content, so an option without a `label` is unnamed.',
+        "Selection is conveyed by an outline (not colour alone), since the swatch's own colour is the content.",
+        'The custom input is a native `<input type="color">` named only by `customLabel`.',
+        "No roving focus and no arrow-key navigation \u2014 every swatch and the custom input is its own Tab stop."
       ],
       behavior: [
+        "update_payload_type: string",
         "emits_on_preset_click: true",
         "emits_on_custom_input: true",
-        "blocks_interaction_when_disabled: true"
+        "blocks_interaction_when_disabled: true",
+        "selection_match_is_case_insensitive: true",
+        "custom_input_rendered_only_when_allow_custom: true",
+        "custom_input_emits_on_input_not_change: true",
+        "fully_controlled_no_internal_selection_state: true"
       ],
       selection: {
         keywords: [],
@@ -1972,7 +2540,8 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TCombobox",
@@ -1990,7 +2559,8 @@ var treeui_catalog_default = {
         {
           name: "modelValue",
           type: "string",
-          default: ""
+          default: "",
+          note: "The SELECTED option value, never the text in the input. The input renders an internal `query` string that is re-synced from the selected option's label whenever the listbox is closed. A `modelValue` with no matching entry in `options` resolves to an empty label."
         },
         {
           name: "options",
@@ -2001,12 +2571,14 @@ var treeui_catalog_default = {
         {
           name: "open",
           type: "boolean",
-          default: "undefined"
+          default: "undefined",
+          note: "Controlled open state. Once a boolean is passed the component stops tracking open state internally \u2014 it only emits update:open / open-change and the consumer MUST write the value back, or the listbox never opens."
         },
         {
           name: "defaultOpen",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Uncontrolled initial open state, read once on mount. Later changes to it are ignored."
         },
         {
           name: "size",
@@ -2016,17 +2588,20 @@ var treeui_catalog_default = {
             "sm",
             "md",
             "lg"
-          ]
+          ],
+          note: "Sizes the control only. `md` has no CSS rule of its own \u2014 it is the base `.t-combobox__control` styling."
         },
         {
           name: "disabled",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: 'Sets the native `disabled` attribute on the input, adds `is-disabled` to the root, and suppresses the listbox entirely (`v-if="isOpen && !disabled"`) \u2014 even while `open` is true. Also short-circuits opening, typing side effects, and keydown handling.'
         },
         {
           name: "loading",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: 'Presentational only. Replaces the chevron indicator with `<TSpinner size="sm" label="Loading" />` and sets aria-busy; it never blocks typing, opening, filtering, or selection.'
         },
         {
           name: "invalid",
@@ -2041,56 +2616,102 @@ var treeui_catalog_default = {
         {
           name: "emptyText",
           type: "string",
-          default: "No results found."
+          default: "No results found.",
+          note: "Fallback content of the `empty` slot \u2014 supplying that slot shadows this prop entirely."
         }
       ],
       events: [
         {
-          name: "update:modelValue"
+          name: "update:modelValue",
+          description: 'Emitted with the chosen option\'s `value` when an option is selected, and with `""` when the listbox closes while the input text is blank and a value was set (the clear-by-erasing path).',
+          payload: '["string"]'
         },
         {
-          name: "update:open"
+          name: "update:open",
+          description: "Emitted whenever the open state changes. Deduped \u2014 no emit when the next value equals the current one.",
+          payload: '["boolean"]'
         },
         {
-          name: "open-change"
+          name: "open-change",
+          description: "Emitted immediately after `update:open`, with the same payload. Alias for consumers that do not use v-model:open.",
+          payload: '["boolean"]'
         },
         {
-          name: "input-change"
+          name: "input-change",
+          description: "Emitted on every keystroke with the raw, untrimmed input text \u2014 the same string the `empty` slot receives as `query`. This is the only hook for server-side / async filtering; it does not replace or disable the built-in local filtering, so an async consumer must feed results back through `options`.",
+          payload: '["string"]'
         }
       ],
       slots: [
         {
-          name: "prefix"
+          name: "prefix",
+          description: 'Leading content inside `.t-combobox__control`, before the input. Rendered only when the slot is supplied, wrapped in `<span class="t-combobox__slot t-combobox__slot--prefix">`. No scoped props.'
         },
         {
-          name: "option"
+          name: "option",
+          description: 'Replaces the default option body (label, description, and the selected check icon). Renders INSIDE the row\'s `<li role="option">`, which owns the click and mouseenter handlers, so it must contain only presentational content. `selected` is `option.value === modelValue`; `active` is the keyboard-highlighted row, which is NOT DOM focus \u2014 focus stays on the input at all times.\n'
         },
         {
-          name: "empty"
+          name: "empty",
+          description: 'Replaces `emptyText` inside `<li class="t-combobox__empty">` when the filter matches no option. `query` is the current raw input text, untrimmed and uncased. Passing both this slot and `emptyText` renders only the slot.'
         }
       ],
       a11y: [
         "role: combobox",
+        "combobox_element: input",
+        "accessible_name: None is generated \u2014 there is no label element and no default slot. Pass aria-label or aria-labelledby (which also names the listbox), or pass `id` and wrap in TFormField with a matching `html-for`; TFormField does not link the label on its own.",
         "trigger_aria_haspopup: listbox",
         "trigger_aria_expanded: true",
+        "trigger_aria_controls_when_open: true",
         "aria_autocomplete: list",
         "aria_activedescendant_on_active_option: true",
+        "aria_activedescendant_cleared_while_closed: true",
         "aria_invalid_when_invalid: true",
         "aria_busy_when_loading: true",
+        "listbox_role: listbox",
+        "option_role: option",
+        "listbox_mirrors_aria_label_and_aria_labelledby: true",
         "aria_selected_on_options: true",
         "aria_disabled_on_disabled_options: true",
+        "focus_stays_on_the_input_options_are_never_focused: true",
         "keyboard_arrow_navigation: true",
+        "arrow_navigation_does_not_wrap_at_the_ends: true",
+        "arrow_navigation_skips_disabled_options: true",
         "escape_closes_and_restores_previous_selection: true",
+        "escape_is_ignored_while_closed: true",
         "enter_selects_active_option: true",
+        "tab_closes_and_restores_previous_selection: true",
         "home_end_navigation: true"
       ],
       behavior: [
         "update_payload_type: string",
+        "input_text_is_internal_state_not_model_value: true",
         "local_filtering_by_label_description_and_keywords: true",
+        "filtering_is_case_insensitive_substring_on_a_trimmed_query: true",
+        "empty_query_shows_all_options: true",
+        "input_change_emits_the_raw_query_for_async_filtering: true",
+        "async_results_are_fed_back_through_the_options_prop: true",
         "loading_does_not_disable_by_itself: true",
+        "spinner_replaces_the_chevron_when_loading: true",
+        "chevron_rotates_when_open: true",
+        "check_icon_on_selected_option: true",
+        "focus_opens_the_listbox: true",
+        "click_on_input_opens_the_listbox: true",
+        "typing_opens_the_listbox: true",
+        "arrow_down_opens_the_listbox_with_the_first_enabled_option_active: true",
+        "arrow_up_opens_the_listbox_with_the_last_enabled_option_active: true",
+        "active_option_defaults_to_the_current_selection_when_it_is_in_the_filtered_list: true",
+        "disabled_options_cannot_be_activated_selected_or_hovered: true",
+        "selecting_an_option_sets_the_input_text_to_its_label_and_closes_without_restoring: true",
         "outside_click_closes_dropdown: true",
+        "outside_click_is_detected_on_pointerdown_on_document: true",
         "query_clears_selection_when_closed_empty: true",
-        "selected_value_restores_when_search_is_abandoned: true"
+        "selected_value_restores_when_search_is_abandoned: true",
+        "external_model_value_and_options_changes_resync_the_input_text_only_while_closed: true",
+        "active_option_is_revalidated_when_the_filtered_list_changes: true",
+        "open_state_emits_are_deduped: true",
+        "listbox_is_not_rendered_while_disabled: true",
+        "listbox_renders_in_flow_with_no_portal_and_no_flip_positioning: true"
       ],
       selection: {
         keywords: [
@@ -2123,7 +2744,8 @@ var treeui_catalog_default = {
           "Pass `options` as labeled items and keep labels human-readable because search matches visible fields."
         ]
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TConfirmDialog",
@@ -2146,12 +2768,14 @@ var treeui_catalog_default = {
         {
           name: "defaultOpen",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Uncontrolled initial state. Read once on setup \u2014 later changes are ignored. Only meaningful when `open` is left undefined."
         },
         {
           name: "disabled",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Only blocks opening from the `trigger` slot (the trigger wrapper gets `aria-disabled` and its click is swallowed). It does NOT block a programmatic open through `open`/`defaultOpen`, and it does not disable the confirm/cancel buttons \u2014 use `confirmDisabled`/`cancelDisabled` for those."
         },
         {
           name: "size",
@@ -2161,47 +2785,63 @@ var treeui_catalog_default = {
             "sm",
             "md",
             "lg"
-          ]
+          ],
+          note: "Forwarded to TModal and applied as `t-modal__surface--<size>` \u2014 it sizes the dialog surface, not the confirm-dialog block, and it does not size the default footer buttons (those are always TButton `md`)."
         },
         {
           name: "title",
           type: "string",
-          default: ""
+          default: "",
+          note: "Rendered by TModal as `t-modal__title` and referenced by `aria-labelledby`. TConfirmDialog does not expose TModal's `header` slot, so an empty title leaves the dialog without an accessible name."
         },
         {
           name: "description",
           type: "string",
-          default: ""
+          default: "",
+          note: "Rendered by TModal as `t-modal__description` and referenced by `aria-describedby`. The default slot body is NOT part of the accessible description."
         },
         {
           name: "confirmLabel",
           type: "string",
-          default: "Confirm"
+          default: "Confirm",
+          note: "Ignored when the `actions` slot is supplied."
         },
         {
           name: "cancelLabel",
           type: "string",
-          default: "Cancel"
+          default: "Cancel",
+          note: "Ignored when the `actions` slot is supplied."
         },
         {
           name: "confirmVariant",
           type: "TVariant",
-          default: "danger"
+          default: "danger",
+          values: [
+            "solid",
+            "outline",
+            "ghost",
+            "soft",
+            "danger"
+          ],
+          note: "Ignored when the `actions` slot is supplied."
         },
         {
           name: "confirmDisabled",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Disables the default confirm button AND short-circuits the confirm handler \u2014 no `confirm` emit and no close, including when the handler is invoked from the `actions` slot scope."
         },
         {
           name: "cancelDisabled",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Disables the default cancel button AND short-circuits the cancel handler \u2014 no `cancel` emit and no close, including when the handler is invoked from the `actions` slot scope."
         },
         {
           name: "loading",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Puts the default confirm button into its spinner state (TButton adds `is-loading`, `aria-busy`, and the native `disabled` attribute) and short-circuits the confirm handler exactly like `confirmDisabled`. It does not affect the cancel button. Also passed to the `actions` slot scope so a custom footer can mirror the state."
         },
         {
           name: "closeOnEscape",
@@ -2211,27 +2851,32 @@ var treeui_catalog_default = {
         {
           name: "closeOnOverlay",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Deliberately opt-in \u2014 TModal defaults this to true, TConfirmDialog flips it to false so a confirmation is not dismissed by a stray backdrop click."
         },
         {
           name: "showCloseButton",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Deliberately opt-in \u2014 TModal defaults this to true. Enabling it adds a header close button that dismisses without emitting `cancel`."
         },
         {
           name: "closeLabel",
           type: "string",
-          default: "Close dialog"
+          default: "Close dialog",
+          note: "Accessible name of the header close button. Only rendered when `showCloseButton` is true."
         },
         {
           name: "closeOnConfirm",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "Set false for async confirmation: `confirm` fires but the dialog stays open, so the caller can hold it open with `loading` while the request resolves and then close it via `open`."
         },
         {
           name: "closeOnCancel",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "Set false to keep the dialog open after `cancel` \u2014 the caller then owns closing via `open`."
         }
       ],
       events: [
@@ -2250,16 +2895,20 @@ var treeui_catalog_default = {
       ],
       slots: [
         {
-          name: "trigger"
+          name: "trigger",
+          description: "Element that opens the dialog on click. Omit for imperative use."
         },
         {
-          name: "icon"
+          name: "icon",
+          description: "Decorative leading icon. Presence switches the block to the two-column icon layout."
         },
         {
-          name: "default"
+          name: "default",
+          description: "Extra body content rendered under the description."
         },
         {
-          name: "actions"
+          name: "actions",
+          description: "Replaces the whole footer. Scope gives you confirm(), cancel(), and loading."
         }
       ],
       a11y: [
@@ -2267,15 +2916,26 @@ var treeui_catalog_default = {
         "aria_modal: true",
         "focus_trap: inherited_from_modal",
         "restores_focus_on_close: inherited_from_modal",
+        "restore_focus_caveat: TModal only records the previously focused element when the dialog is opened by clicking its `trigger` slot. A dialog opened programmatically \u2014 by setting `open` from a row action, a menu item, or `defaultOpen` \u2014 has nothing recorded, so focus is not restored on close. Move focus back yourself in that case.",
+        "accessible_name_source: `title` prop, via aria-labelledby; absent when `title` is empty",
+        "accessible_description_source: `description` prop, via aria-describedby; the default slot body is not included",
+        "initial_focus: First focusable element inside the dialog surface. With the default footer and `showCloseButton: false` that is the cancel button, which is the safe landing spot for a destructive confirmation. Enabling `showCloseButton` moves initial focus to the header close button instead. A `loading` or `confirmDisabled` confirm button carries the native `disabled` attribute and is skipped.",
         "icon_slot_marked_aria_hidden: true"
       ],
       behavior: [
         "built_on_modal_contract: true",
         "default_confirm_button_variant: danger",
+        "default_cancel_button_variant: ghost",
         "overlay_click_disabled_by_default: true",
         "close_button_hidden_by_default: true",
         "loading_state_applies_to_confirm_button: true",
-        "default_actions_close_dialog_when_enabled: true"
+        "confirm_suppressed_when: confirmDisabled || loading \u2014 the handler returns before emitting, so neither `confirm` nor the close runs",
+        "cancel_suppressed_when: cancelDisabled \u2014 the handler returns before emitting, so neither `cancel` nor the close runs",
+        "closes_after_confirm_when: closeOnConfirm",
+        "closes_after_cancel_when: closeOnCancel",
+        "guards_and_auto_close_apply_to_actions_slot: true",
+        "close_button_and_escape_do_not_emit_cancel: true",
+        "inherits_teleport_scroll_lock_and_focus_trap_from_modal: true"
       ],
       selection: {
         keywords: [],
@@ -2289,6 +2949,9 @@ var treeui_catalog_default = {
       },
       recipes: [
         "confirm-destructive-action"
+      ],
+      practices: [
+        "accessible-by-default"
       ]
     },
     {
@@ -2341,7 +3004,9 @@ var treeui_catalog_default = {
         }
       ],
       a11y: [
-        "Acts as a structural wrapper only; semantics come from the `as` prop and child content."
+        "Acts as a structural wrapper only; semantics come from the `as` prop and child content.",
+        'Renders a non-semantic `div` by default. Pass `as` to make it a landmark (e.g. `as="main"`, `as="section"`, `as="header"`) \u2014 avoid nesting a second `main` inside an app shell or a TPage that already provides one.\n',
+        "`aria-*` and `role` attributes fall through to the root element (see `forwards_attrs_to`)."
       ],
       behavior: [
         "semantic_element_controlled_by_as: true",
@@ -2385,6 +3050,9 @@ var treeui_catalog_default = {
       },
       recipes: [
         "sidebar-shell"
+      ],
+      practices: [
+        "content-alignment"
       ]
     },
     {
@@ -2393,6 +3061,8 @@ var treeui_catalog_default = {
       package: "@treeui/vue",
       category: "Overlay",
       status: "stable",
+      description: "Right-click (contextmenu) menu teleported to body and positioned at the cursor. The component renders no chrome of its own \u2014 the root wrapper is `display: contents` and only wraps the slotted trigger area.\n",
+      sourceFile: "packages/vue/src/components/TContextMenu.vue",
       storyFile: "apps/docs/src/stories/ContextMenu.stories.ts",
       storyTitle: "Components/Overlay/ContextMenu",
       manifestFile: "docs/ai/COMPONENTS/context-menu.yaml",
@@ -2401,73 +3071,84 @@ var treeui_catalog_default = {
           name: "items",
           type: "TContextMenuItem[]",
           default: "[]",
-          description: "Menu items to render."
+          description: 'Menu items to render, one `role="menuitem"` <li> each. An empty array is allowed and still opens an empty `role="menu"` list with nothing focused.\n'
         },
         {
           name: "open",
           type: "boolean | undefined",
           default: "undefined",
-          description: "Controlled open state (v-model:open)."
+          description: "Controlled open state (v-model:open). When defined it wins over the internal state and `defaultOpen` is ignored; the component still emits and expects the parent to write the new value back. `disabled` overrides this \u2014 a disabled component renders no menu even while `open` is true.\n"
         },
         {
           name: "defaultOpen",
           type: "boolean",
           default: "false",
-          description: "Uncontrolled initial open state."
+          description: "Uncontrolled initial open state. Read once during setup \u2014 later changes to this prop have no effect.\n"
         },
         {
           name: "disabled",
           type: "boolean",
           default: "false",
-          description: "Prevents the context menu from opening."
+          description: "Prevents the context menu from opening, and hides it if it is already open. While disabled the component does not call preventDefault on `contextmenu`, so the native browser menu appears instead.\n"
         },
         {
           name: "size",
           type: "TSize",
           default: "md",
-          description: "Item sizing variant."
+          values: [
+            "sm",
+            "md",
+            "lg"
+          ],
+          description: "Item sizing variant. The modifier class is applied to both the root and the teleported menu, but only the copy on the menu is effective (the root is teleport-detached from the menu subtree).\n"
         }
       ],
       events: [
         {
           name: "select",
-          description: "Emitted when a menu item is selected.",
+          description: "Emitted with `item.value` when an enabled item is activated by click or Enter/Space. Disabled items emit nothing.\n",
           payload: "[value: string]"
         },
         {
           name: "update:open",
-          description: "Emitted when open state changes (v-model support).",
+          description: "Emitted when open state changes (v-model support). Only fires on an actual transition \u2014 setting the same value again is a no-op.\n",
           payload: "[value: boolean]"
         },
         {
           name: "open-change",
-          description: "Emitted when open state changes.",
+          description: "Emitted when open state changes. Always fires together with `update:open`, including in controlled mode.\n",
           payload: "[value: boolean]"
         }
       ],
       slots: [
         {
           name: "default",
-          description: "Content that acts as the right-click trigger area."
+          description: "Content that acts as the right-click trigger area. It is rendered inside the root <div>, which is `display: contents` and therefore contributes no box of its own \u2014 the slotted content keeps its own layout, and the `contextmenu` handler still fires through event bubbling.\n"
         },
         {
           name: "item",
-          description: "Custom rendering for each menu item."
+          description: 'Custom rendering for each menu item; scoped props `{ item, index }`, falls back to `{{ item.label }}`. Rendered inside the `role="menuitem"` <li>, which already owns click, keydown, tabindex and aria-disabled \u2014 keep the content presentational, nested interactive controls are not reachable inside a menuitem.\n'
         }
       ],
       a11y: [
-        "role: menu (on the floating list)",
+        "role: menu (on the teleported floating list)",
         "items_role: menuitem",
-        'keyboard: ["Right-click / contextmenu event opens menu at cursor","ArrowDown / ArrowUp navigates items","Home / End jumps to first / last enabled item","Enter / Space selects focused item","Escape closes menu and restores focus"]',
-        'aria: ["aria-disabled on disabled items","aria-label on menu element"]',
-        'focus: ["First enabled item receives focus on open","Focus restored to trigger area on close"]'
+        'keyboard: ["Right-click / contextmenu event opens menu at cursor","ArrowDown / ArrowUp move focus to the next / previous enabled item (clamped, no wrap)","Home / End jumps to first / last enabled item","Enter / Space selects focused item","Escape closes menu and restores focus","All key handling lives on the items \u2014 keys are only handled while an item has focus"]',
+        'aria: ["aria-disabled on disabled items (omitted, not false, when enabled)","aria-label=\\"Context menu\\" on the menu element \u2014 hardcoded, not configurable or localizable","Menu id is generated with createId(\'t-context-menu\'); there is no `id` prop","tabindex 0 on enabled items, -1 on disabled items \u2014 no roving tabindex, every enabled item is tab-reachable"]',
+        'focus: ["First enabled item receives focus on open","When every item is disabled, focus still goes to the first item; with an empty `items` array nothing is focused","Focus restored to trigger area on close from Escape or item selection","An outside click closes without restoring focus, leaving it where the pointer put it"]'
       ],
       behavior: [
-        "Opens at cursor position on right-click (contextmenu event).",
-        "Uses Teleport to body to escape stacking contexts.",
-        "Closes on click outside, Escape key, or item selection.",
-        "Prevents native browser context menu on trigger area.",
-        "Uses position fixed for viewport-relative placement."
+        "Opens at cursor position on right-click (contextmenu event), using event.clientX / clientY.",
+        "Uses Teleport to body to escape stacking contexts; the menu is not a DOM descendant of the trigger.",
+        "Uses position fixed at the raw cursor coordinates, stacked at var(--tree-z-dropdown).",
+        "No collision detection or viewport clamping \u2014 a menu opened near the right or bottom edge overflows.",
+        "Closes on pointerdown outside the menu (including on the trigger itself), Escape, or item selection.",
+        "Right-clicking again inside the trigger area repositions the menu \u2014 the outside pointerdown closes it and the following contextmenu reopens it at the new coordinates.",
+        "A document-level contextmenu listener covers keyboard-invoked menus (Shift+F10 / Menu key) raised outside the trigger.",
+        "Prevents native browser context menu on trigger area, but only while not disabled.",
+        'Exposes data-state="open" | "closed" on the root element for external styling.',
+        "Document pointerdown / contextmenu listeners are attached only while open, and removed on close and before unmount.",
+        "Menu enter / leave uses the shared t-fade transition (opacity plus scale 0.95)."
       ],
       selection: {
         keywords: [
@@ -2492,7 +3173,8 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TDatePicker",
@@ -2510,17 +3192,20 @@ var treeui_catalog_default = {
         {
           name: "modelValue",
           type: "string",
-          default: ""
+          default: "",
+          note: "Parsed with `parseDateValue`, which accepts ONLY a strict `YYYY-MM-DD` string that resolves to a real calendar date. Anything else (empty, `2026-13-01`, an ISO datetime, a Date object stringified) resolves to null and the trigger falls back to `placeholder`. The hidden input, when present, still submits the raw prop verbatim \u2014 an unparseable value renders as the placeholder but is submitted as-is."
         },
         {
           name: "open",
           type: "boolean",
-          default: "controlled_optional"
+          default: "undefined",
+          note: "Controlled open state. Once a boolean is passed the component stops tracking open state internally \u2014 it only emits update:open / open-change and the consumer MUST write the value back, or the calendar never opens."
         },
         {
           name: "defaultOpen",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Uncontrolled initial open state, read once on mount. Later changes to it are ignored. Opening this way skips `openCalendar`, so no day button receives DOM focus until the user tabs or arrows into the grid."
         },
         {
           name: "size",
@@ -2530,41 +3215,48 @@ var treeui_catalog_default = {
             "sm",
             "md",
             "lg"
-          ]
+          ],
+          note: "Sizes the trigger only, never the popover. `md` has no CSS rule of its own \u2014 it is the base `.t-date-picker__trigger` styling \u2014 but the `t-date-picker--md` class is still rendered."
         },
         {
           name: "disabled",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: 'Sets the native `disabled` attribute on the trigger, adds `is-disabled` to the root, short-circuits `openCalendar` and trigger keydown, makes `isDateDisabled` return true for every date, and suppresses the popover entirely (`v-if="isOpen && !disabled"`) even while `open` is true.'
         },
         {
           name: "invalid",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: 'Adds `is-invalid` to the root and `aria-invalid="true"` to the trigger. Purely presentational \u2014 it does not block opening or selection.'
         },
         {
           name: "placeholder",
           type: "string",
-          default: "Select date"
+          default: "Select date",
+          note: "Rendered inside `.t-date-picker__value` with a `data-placeholder` attribute whenever `modelValue` does not parse."
         },
         {
           name: "locale",
           type: "string",
-          default: "en-US"
+          default: "en-US",
+          note: "BCP-47 tag passed to three separate `Intl.DateTimeFormat` calls: the trigger text (day numeric / month long / year numeric), the popover month caption (month long / year numeric), and the weekday header (weekday short). It does NOT localize the per-day `aria-label`, which is always the raw `YYYY-MM-DD` key."
         },
         {
           name: "min",
           type: "string",
-          default: ""
+          default: "",
+          note: "Inclusive lower bound. Days before it get the native `disabled` attribute and cannot be selected or arrowed onto; the Previous-month nav button is disabled once the view reaches the min month. A value that fails `parseDateValue` is ignored, i.e. treated as no bound."
         },
         {
           name: "max",
           type: "string",
-          default: ""
+          default: "",
+          note: "Inclusive upper bound, mirroring `min`: out-of-range days are disabled and the Next-month nav button is disabled once the view reaches the max month."
         },
         {
           name: "weekStartsOn",
-          type: "number",
+          type: "0 | 1 | 2 | 3 | 4 | 5 | 6",
           default: "0",
           values: [
             "0",
@@ -2574,46 +3266,90 @@ var treeui_catalog_default = {
             "4",
             "5",
             "6"
-          ]
+          ],
+          note: "0 = Sunday. Drives the weekday header order, the leading offset of the day grid, and the Home/End keys (which jump to the first/last day of the week as defined by this prop)."
         },
         {
           name: "id",
           type: "string",
-          default: "auto"
+          default: "auto",
+          note: "Names the CALENDAR POPOVER, not the trigger. It becomes the popover's `id` (referenced by the trigger's `aria-controls` while open) and seeds the month caption id as `${id}-caption`. Read once at setup \u2014 later changes are ignored. Because `id` is a declared prop it never falls through to the trigger button, so the trigger has no id and a `<label for>` / `TFormField html-for` cannot target it; name the control with `aria-label` instead."
         }
       ],
       events: [
         {
-          name: "update:modelValue"
+          name: "update:modelValue",
+          description: 'Emitted with the chosen day as `YYYY-MM-DD` from `selectDate` only \u2014 a click or Enter/Space on an enabled day button. Nothing else in the component emits it; there is no clear affordance, so the value never becomes `""` on its own.',
+          payload: '["string"]'
         },
         {
-          name: "update:open"
+          name: "update:open",
+          description: "Emitted whenever the open state changes. Deduped \u2014 no emit when the next value equals the current one.",
+          payload: '["boolean"]'
         },
         {
-          name: "open-change"
+          name: "open-change",
+          description: "Emitted immediately after `update:open`, with the same payload. Alias for consumers that do not use v-model:open.",
+          payload: '["boolean"]'
         },
         {
-          name: "select"
+          name: "select",
+          description: "Emitted from `selectDate` immediately after `update:modelValue`, with the same `YYYY-MM-DD` payload. It is the user-intent signal: it fires only on an actual day activation and never when `modelValue` changes from outside, which is what distinguishes it from `update:modelValue`.",
+          payload: '["string"]'
         }
       ],
       slots: [
         {
-          name: "prefix"
+          name: "prefix",
+          description: 'Leading content inside the trigger button, before the value text. Rendered only when the slot is supplied, wrapped in `<span class="t-date-picker__slot t-date-picker__slot--prefix">`. No scoped props. Content is inside a `<button>`, so it must be presentational only.'
         },
         {
-          name: "suffix"
+          name: "suffix",
+          description: 'Trailing content inside the trigger button, in `<span class="t-date-picker__slot t-date-picker__slot--suffix">`. Unlike `prefix` the wrapper is always rendered; supplying the slot replaces the default calendar icon. No scoped props, and the same presentational-only restriction applies.'
         }
       ],
       a11y: [
+        "role: dialog",
+        "accessible_name: None is generated for the trigger beyond its own text content, which is the formatted date or the placeholder \u2014 that changes as the user picks, so it is not a stable label. Pass `aria-label` (see example). The `id` prop cannot be used to link an external <label>.",
         "trigger_has_popup_dialog: true",
+        "trigger_aria_expanded: true",
+        "trigger_aria_controls_when_open: true",
+        "aria_invalid_when_invalid: true",
         "calendar_uses_grid_roles: true",
+        "calendar_aria_modal: false",
+        "calendar_labelled_by_month_caption: true",
+        "weekday_header_is_aria_hidden: true",
+        "aria_selected_rendered_on_every_gridcell: true",
+        "aria_current_date_on_today: true",
+        "day_aria_label_is_the_raw_iso_key: true",
+        "nav_buttons_labelled_previous_month_and_next_month: true",
+        "roving_tabindex_one_focusable_day: true",
         "escape_closes: true",
-        "returns_focus_to_trigger_after_selection: true"
+        "returns_focus_to_trigger_after_selection: true",
+        "returns_focus_to_trigger_on_escape_from_a_day: true",
+        "focus_is_not_trapped_and_tab_leaves_the_open_calendar: true"
       ],
       behavior: [
+        "value_format: YYYY-MM-DD",
+        "controlled_and_uncontrolled_open: true",
+        "open_state_emits_are_deduped: true",
         "selection_closes_popover: true",
         "hidden_input_created_when_name_attr_present: true",
-        "out_of_range_dates_disabled: true"
+        "hidden_input_submits_the_raw_unparsed_model_value: true",
+        "out_of_range_dates_disabled: true",
+        "min_and_max_also_disable_the_month_nav_buttons: true",
+        "popover_is_not_rendered_while_disabled: true",
+        "outside_click_closes_calendar: true",
+        "outside_click_is_detected_on_pointerdown_on_document: true",
+        "outside_click_and_trigger_toggle_close_without_restoring_focus: true",
+        "grid_is_always_six_weeks_forty_two_days: true",
+        "leading_and_trailing_days_render_muted_and_stay_selectable: true",
+        "opening_syncs_the_view_to_the_selected_date_else_the_last_focused_date_else_today: true",
+        "external_model_value_changes_move_the_view_and_the_focused_day: true",
+        "clearing_the_model_value_resets_the_view_to_today_only_while_closed: true",
+        "month_nav_moves_the_focused_day_to_the_first_of_the_new_month_and_focuses_it: true",
+        "today_is_computed_once_at_setup_not_re_evaluated_across_midnight: true",
+        "popover_renders_in_flow_with_no_portal_and_no_flip_positioning: true"
       ],
       selection: {
         keywords: [
@@ -2641,13 +3377,14 @@ var treeui_catalog_default = {
           "Use `min` and `max` with the same format."
         ]
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TDateTimePicker",
       aliases: [],
       package: "@treeui/vue",
-      kind: "form",
+      kind: "form_overlay",
       category: "Data Entry",
       status: "available",
       purpose: "Date and time picker with a calendar grid, time selection, and overlay trigger.",
@@ -2660,7 +3397,7 @@ var treeui_catalog_default = {
           name: "modelValue",
           type: "string",
           default: "",
-          note: "Uses `YYYY-MM-DDTHH:mm`."
+          note: "Always emitted as `YYYY-MM-DDTHH:mm`. On input it also parses `YYYY-MM-DD` (midnight) and `YYYY-MM-DDTHH:mm:ss`; anything else parses to null and renders the placeholder."
         },
         {
           name: "open",
@@ -2680,17 +3417,20 @@ var treeui_catalog_default = {
             "sm",
             "md",
             "lg"
-          ]
+          ],
+          note: "Renders as `t-date-picker--<size>` on the root \u2014 there is no `t-date-time-picker--<size>` modifier."
         },
         {
           name: "disabled",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Blocks opening via click/keyboard and suppresses the overlay entirely, even when `open` is true."
         },
         {
           name: "loading",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Only swaps the default suffix icon for a TSpinner; the trigger stays enabled and interactive."
         },
         {
           name: "invalid",
@@ -2705,33 +3445,38 @@ var treeui_catalog_default = {
         {
           name: "locale",
           type: "string",
-          default: "en-US"
+          default: "en-US",
+          note: "Feeds all four Intl.DateTimeFormat calls: trigger text, draft preview, month caption, weekday labels."
         },
         {
           name: "min",
           type: "string",
-          default: ""
+          default: "",
+          note: "`YYYY-MM-DD` (resolved to 00:00 of that day) or `YYYY-MM-DDTHH:mm`."
         },
         {
           name: "max",
           type: "string",
-          default: ""
+          default: "",
+          note: "`YYYY-MM-DD` (resolved to 23:59:59.999 of that day) or `YYYY-MM-DDTHH:mm`."
         },
         {
           name: "weekStartsOn",
           type: "0 | 1 | 2 | 3 | 4 | 5 | 6",
-          default: "0"
+          default: "0",
+          note: "0 = Sunday. Reorders the weekday header labels, the grid start date, and Home/End day navigation."
         },
         {
           name: "id",
           type: "string",
-          default: "auto"
+          default: "auto",
+          note: "Id of the overlay dialog only \u2014 not of the root or the trigger. Read once at setup, so later changes are ignored. The trigger points at it with aria-controls while open."
         },
         {
           name: "step",
           type: "number",
           default: "60",
-          note: "Seconds between time options."
+          note: "Seconds between minute options. Must be a positive multiple of 60 below 3600; any other value falls back to 1-minute options. Hours are always 0-23 regardless of step."
         }
       ],
       events: [
@@ -2751,12 +3496,28 @@ var treeui_catalog_default = {
           name: "select"
         }
       ],
-      slots: [],
+      slots: [
+        {
+          name: "prefix"
+        },
+        {
+          name: "suffix"
+        }
+      ],
       a11y: [
         "role: dialog",
+        "aria_modal: false \u2014 the overlay is non-modal and does not trap focus",
         "trigger_aria_haspopup: dialog",
         "trigger_aria_expanded: true",
-        "focus_restores_on_close: true",
+        "trigger_aria_controls_when_open: true",
+        "overlay_labelled_by_month_caption: true",
+        "calendar_uses_grid_roles: true",
+        "day_buttons_use_roving_tabindex: true",
+        "day_buttons_aria_pressed_when_selected: true",
+        "gridcell_aria_selected: true",
+        "weekday_row_aria_hidden: true",
+        "time_selects_have_aria_labels: true",
+        "focus_restores_on_close: Only when closing via Apply, Clear, or Escape from a day button. Closing by clicking the trigger, Escape on the trigger, or an outside pointerdown leaves focus where it is.",
         "keyboard_calendar_navigation: true",
         "escape_closes_overlay: true",
         "aria_invalid_when_invalid: true",
@@ -2766,7 +3527,21 @@ var treeui_catalog_default = {
         "controlled_and_uncontrolled_open: true",
         "value_format: YYYY-MM-DDTHH:mm",
         "min_and_max_limit_available_values: true",
-        "time_options_generated_from_step: true"
+        "time_options_generated_from_step: true",
+        "draft_then_commit: Choosing a day and changing the Hour/Minute selects mutate an internal draft only. Nothing is emitted and the overlay does NOT close until Apply \u2014 unlike TDatePicker, where selecting a day commits and closes.",
+        "apply_emit_order: update:modelValue, then change, then select \u2014 all carrying the same `YYYY-MM-DDTHH:mm` string.",
+        "clear_emits_empty_string: Clear emits update:modelValue, change, and select with `''`, then closes.",
+        "default_draft_when_value_is_empty: Now, rounded UP to the next `step` boundary (minimum 60s) with seconds zeroed, then clamped into min/max.",
+        "draft_resyncs_from_model_value_only_while_closed: true",
+        "draft_is_clamped_into_min_max_on_open_and_on_day_select: true",
+        "minute_options_always_include_the_current_draft_minute: true",
+        "hour_option_disabled_when_no_minute_in_that_hour_is_available: true",
+        "month_nav_buttons_disabled_at_min_max_month: true",
+        "out_of_range_days_disabled: true",
+        "outside_pointerdown_closes: true",
+        "overlay_is_not_rendered_while_disabled: true",
+        "hidden_input_created_when_name_attr_present: true",
+        "open_state_emits_are_deduped: true"
       ],
       selection: {
         keywords: [
@@ -2799,14 +3574,15 @@ var treeui_catalog_default = {
       },
       recipes: [
         "date-range-form"
-      ]
+      ],
+      practices: []
     },
     {
       name: "TDivider",
       aliases: [],
       package: "@treeui/vue",
       category: "Layout",
-      description: "Horizontal or vertical visual separator.",
+      description: 'Horizontal or vertical visual separator. Renders a single native <hr> and nothing else \u2014 there is no default slot, so the "text in the middle of a rule" pattern (an "OR" divider) is NOT supported; compose that yourself from a flex row plus TText. The `label` prop is an accessible name only, never visible text. There are no size, variant, tone, or spacing props.\n',
       sourceFile: "packages/vue/src/components/TDivider.vue",
       storyFile: "apps/docs/src/stories/Divider.stories.ts",
       storyTitle: "Components/Layout/Divider",
@@ -2814,34 +3590,41 @@ var treeui_catalog_default = {
       props: [
         {
           name: "orientation",
-          type: "string",
+          type: '"horizontal" | "vertical"',
           default: "horizontal",
           values: [
             "horizontal",
             "vertical"
-          ]
+          ],
+          description: "Selects the `t-divider--{orientation}` modifier \u2014 the only class the component varies. `horizontal` spans the full inline width (width 100%, height 0) with `margin-block` spacing. `vertical` is a zero-width rule (width 0, height auto) that takes its height from `align-self: stretch`, so it is only visible inside a flex or grid row \u2014 in a plain block container it collapses to zero height and renders nothing.\n"
         },
         {
           name: "decorative",
           type: "boolean",
           default: "true",
-          description: "When true, renders role='none' (purely visual). When false, renders as role='separator'."
+          description: 'When true (the default) renders `role="none"` and no ARIA attributes at all \u2014 purely visual, removed from the accessibility tree, and the `label` prop is dropped. When false renders `role="separator"` plus `aria-orientation`, and `aria-label` when `label` is set.\n'
         },
         {
           name: "label",
           type: "string",
           required: false,
-          description: "Accessible label for non-decorative dividers."
+          description: 'Accessible name, applied as `aria-label` ONLY when `decorative` is false. Because `decorative` defaults to true, `<TDivider label="Section" />` on its own renders no label at all \u2014 pass `:decorative="false"` as well. Never rendered as visible text.\n'
         }
       ],
       events: [],
       slots: [],
       a11y: [
-        "role: none (decorative) or separator (semantic)",
-        "aria-orientation: Set when non-decorative.",
-        "aria-label: Set from `label` prop when non-decorative."
+        'role: "none" when decorative (the default), "separator" when `decorative` is false.',
+        'aria-orientation: Set to the `orientation` value only when `decorative` is false; omitted otherwise. Note that "horizontal" is already the implicit default for `role="separator"`, so it is redundant there but harmless.',
+        "aria-label: Set from the `label` prop only when `decorative` is false. Omitted when `label` is unset, so a non-decorative divider without a label is an unnamed separator (valid \u2014 separators need no name).",
+        'notes: The decorative default is the right one for most dividers: a purely visual rule should not be announced. Use `:decorative="false"` only when the rule genuinely separates two sections that assistive technology should perceive as distinct, and pair it with `label` when the sections need naming.'
+      ],
+      behavior: [
+        "Renders a native <hr> element as its single root node.",
+        "Extra attrs and class/style fall through to that <hr> (attribute inheritance is not disabled).",
+        "Applies exactly two classes; no state, size, or variant modifiers exist.",
+        "A vertical divider needs a flex or grid parent to have any height."
       ],
-      behavior: [],
       selection: {
         keywords: [],
         useWhen: [],
@@ -2852,7 +3635,8 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TDonutChart",
@@ -2871,67 +3655,73 @@ var treeui_catalog_default = {
           name: "segments",
           type: "TDonutSegment[]",
           default: "[]",
-          note: "Each item is { label: string; value: number; color?: string }. Non-positive values are omitted."
+          note: "Each item is { label: string; value: number; color?: string }. Values <= 0 are filtered out before anything renders \u2014 they reach neither the chart, the legend, nor the segment count in the auto aria-label. Because the palette cycles by *visible* index, dropping a non-positive item shifts the colors of every segment after it."
         },
         {
           name: "size",
           type: "number",
           default: "200",
-          note: "Square canvas in px."
+          note: "Square canvas in px; applied to both the svg and the figure box. Donut geometry insets the ring by thickness/2 + 3px so the hover growth cannot clip; pie geometry uses a radius of size/2 - 2."
         },
         {
           name: "thickness",
           type: "number",
           default: "26",
-          note: "Ring thickness; 0 renders a full pie."
+          note: "Ring thickness in px. `0` switches the whole render mode: segments become filled wedges to the center (a pie) and the center block is not rendered at all. Hovering a donut segment temporarily draws it at thickness + 4."
         },
         {
           name: "gap",
           type: "number",
           default: "2",
-          note: "Gap between slices, in degrees."
+          note: "Gap between slices, in degrees. In donut mode it is converted to arc length on the mid-radius circle and then floored \u2014 the effective gap is at least 2px, or at least thickness + 2px when rounded \u2014 so small values (including 0) still leave a visible seam. Forced to 0 whenever exactly one segment is visible."
         },
         {
           name: "rounded",
           type: "boolean",
           default: "false",
-          note: "Round the ends of donut segments (widens the gap to make room). Best with a thinner ring."
+          note: "Round the ends of donut segments (widens the gap to make room). Best with a thinner ring. Donut only \u2014 stroke-linecap is not applied to pie wedges, so it is ignored when thickness is 0."
         },
         {
           name: "showLegend",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "The legend only renders when there is data \u2014 it is suppressed in the empty state even when true, but it is NOT suppressed while loading, so real values sit next to the skeleton. The has-legend root class tracks the prop alone, not whether the legend actually rendered."
         },
         {
           name: "showPercent",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "Legend only. Percentages are rounded to whole numbers, so they may not sum to exactly 100%."
         },
         {
           name: "centerLabel",
           type: "string",
-          default: "Total",
-          note: "Donut only; ignored for pie."
+          default: "undefined",
+          note: "Static label under the center value. Falls back to the literal string 'Total' when unset, and is replaced by the hovered segment's label while a segment is hovered. Donut only; the center block is not rendered for a pie."
         },
         {
           name: "centerValue",
           type: "string | number",
-          default: "auto (sum of values)"
+          default: "undefined",
+          note: "Overrides the auto total in the center readout; falls back to the formatted sum of the visible values. Interpolated as-is (no valueFormat). Lower precedence than hover: hovering a segment replaces it with that segment's formatted value. Donut only."
         },
         {
           name: "valueFormat",
           type: "(value: number) => string",
-          default: "locale integers for |value| >= 1000"
+          default: "locale integers for |value| >= 1000",
+          note: "Applies to the legend values and to the center value. Not applied to percentages, nor to an explicitly supplied centerValue."
         },
         {
           name: "loading",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Replaces the figure with a pulsing skeleton disc and adds the is-loading root class. Takes precedence over the empty state; the legend still renders when data is present."
         },
         {
           name: "ariaLabel",
           type: "string",
-          default: "auto-generated summary"
+          default: "auto-generated summary ('Donut chart with <n> segments' / 'Pie chart with <n> segments')",
+          note: 'Applied to the inner <svg role="img">, which only exists in the data state \u2014 neither the loading nor the empty state carries it.'
         }
       ],
       events: [],
@@ -2944,13 +3734,20 @@ var treeui_catalog_default = {
         }
       ],
       a11y: [
-        "Renders role=img with an aria-label summarizing the chart.",
-        "Legend + percentages give a non-visual reading of each slice."
+        "The inner <svg> carries role=img plus the ariaLabel (or the auto-generated summary); the root div has no role or accessible name.",
+        "Legend + percentages give a non-visual reading of each slice.",
+        "The hover readout is pointer-only \u2014 segments are not focusable and there is no keyboard equivalent, so never make it the only way to reach a value. The legend already carries the same numbers.",
+        "Legend swatches are aria-hidden, so color is never the only carrier of identity.",
+        "Provide a meaningful ariaLabel describing what the chart shows."
       ],
       behavior: [
-        "colors_auto_assign_from_chart_palette: --tree-color-chart-1..8, cycling; per-segment color overrides",
-        "hovering_a_slice_dims_the_rest_and_updates_center: true",
-        "center_shows_total_or_the_hovered_segment: true"
+        "colors_auto_assign_from_chart_palette: --tree-color-chart-1..8, cycling by visible-segment index; per-segment color overrides",
+        "hovering_a_slice_dims_the_rest_and_updates_center: the other segments get is-dimmed, the hovered donut segment grows to thickness + 4, and its legend row gets is-active",
+        "hovering_a_legend_row_drives_the_same_highlight: legend items carry the same pointerenter/pointerleave handlers as the segments",
+        "center_readout_precedence: hovered segment > centerValue > formatted total; the label half is hovered segment label > centerLabel > 'Total'",
+        "single_segment_drops_the_gap: with exactly one visible segment the gap is forced to 0 in both donut and pie mode, so the ring/disc closes",
+        "empty_state_when_no_visible_segment_has_value: total <= 0 renders the empty slot instead of the svg; loading wins over it",
+        "segments_fade_in_staggered: 70ms animation delay per segment index; removed under prefers-reduced-motion"
       ],
       selection: {
         keywords: [
@@ -2988,7 +3785,8 @@ var treeui_catalog_default = {
       },
       recipes: [
         "metric-dashboard"
-      ]
+      ],
+      practices: []
     },
     {
       name: "TDrawer",
@@ -3006,17 +3804,20 @@ var treeui_catalog_default = {
         {
           name: "open",
           type: "boolean",
-          default: "controlled_optional"
+          default: "controlled_optional",
+          note: "Runtime default is `undefined`. While it holds anything other than `undefined` the drawer is fully controlled \u2014 the internal state is ignored and the panel only moves when the parent updates this prop."
         },
         {
           name: "defaultOpen",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Uncontrolled initial state. Read once on setup \u2014 later changes are ignored. Only meaningful while `open` is undefined. Opening this way skips the on-open side effects; see behavior.initial_open_skips_open_side_effects."
         },
         {
           name: "disabled",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Only blocks opening from the `trigger` slot \u2014 the trigger wrapper gets `aria-disabled` and its click is swallowed (preventDefault + stopPropagation). It does NOT block a programmatic open through `open`/`defaultOpen`, and it disables nothing inside the drawer."
         },
         {
           name: "size",
@@ -3026,7 +3827,8 @@ var treeui_catalog_default = {
             "sm",
             "md",
             "lg"
-          ]
+          ],
+          note: "Applied as `t-drawer__surface--<size>`. Sizes the cross axis of the panel: width for `side: left | right`, height for `side: top | bottom`."
         },
         {
           name: "side",
@@ -3037,42 +3839,50 @@ var treeui_catalog_default = {
             "right",
             "bottom",
             "left"
-          ]
+          ],
+          note: "Applied as `t-drawer__surface--<side>`. Also selects the slide-in translate direction and which corners are rounded."
         },
         {
           name: "title",
           type: "string",
-          default: ""
+          default: "",
+          note: "Rendered as `t-drawer__title` inside the fallback content of the `header` slot. An empty title with no `header` slot removes the header block entirely and leaves `aria-labelledby` unset \u2014 the dialog then has no accessible name."
         },
         {
           name: "description",
           type: "string",
-          default: ""
+          default: "",
+          note: "Rendered as `t-drawer__description` between the topbar and the body, and referenced by `aria-describedby`. Only rendered when non-empty. The `content`/`default` body is NOT part of the accessible description."
         },
         {
           name: "closeOnEscape",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "Escape is handled on the surface's own keydown, so it only fires while focus is inside the drawer. When enabled the handler also calls preventDefault."
         },
         {
           name: "closeOnOverlay",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "Applies to clicks on `t-drawer__backdrop` only. The backdrop is a sibling of the surface, not an ancestor, so clicks inside the panel never reach it regardless of this prop."
         },
         {
           name: "showCloseButton",
           type: "boolean",
-          default: "true"
+          default: "true",
+          note: "The topbar renders when `title` or the `header` slot is present OR this is true. Setting it false with no title and no `header` slot collapses the topbar entirely."
         },
         {
           name: "closeLabel",
           type: "string",
-          default: "Close drawer"
+          default: "Close drawer",
+          note: "Accessible name (aria-label) of the header close button, which is icon-only and has no text. Only rendered when `showCloseButton` is true. The component's only localisation hook."
         },
         {
           name: "id",
           type: "string",
-          default: "auto"
+          default: "auto",
+          note: "Id of the dialog surface; seeds `<id>-title` and `<id>-description`. Read once on setup (not reactive). Auto-generated via `createId('t-drawer')` when omitted."
         }
       ],
       events: [
@@ -3085,34 +3895,53 @@ var treeui_catalog_default = {
       ],
       slots: [
         {
-          name: "trigger"
+          name: "trigger",
+          description: "Element that opens the drawer on click. Omit for controlled or imperative use."
         },
         {
-          name: "header"
+          name: "header",
+          description: "Replaces the default title heading in the topbar."
         },
         {
-          name: "default"
+          name: "default",
+          description: "Drawer body content."
         },
         {
-          name: "content"
+          name: "content",
+          description: "Drawer body content; takes precedence over the default slot."
         },
         {
-          name: "footer"
+          name: "footer",
+          description: "Action row pinned under the body."
         }
       ],
       a11y: [
         "role: dialog",
         "aria_modal: true",
         "focus_trap: true",
-        "restores_focus_on_close: true",
-        "escape_closes_when_enabled: true"
+        'restores_focus_on_close: {"value":"partial","detail":"The previously focused element is recorded only in the trigger-click path. A drawer opened programmatically \u2014 by setting `open` from elsewhere, or by `defaultOpen` \u2014 records nothing, so focus is not restored on close. Move focus back yourself in that case.\\n"}',
+        "escape_closes_when_enabled: true",
+        "escape_scope: The keydown listener lives on the surface, so Escape only closes while focus is inside the drawer.",
+        "accessible_name_source: the `t-drawer__header` div, via aria-labelledby; unset when `title` is empty and no `header` slot is supplied",
+        "accessible_description_source: the `description` prop, via aria-describedby; the body slots are not included",
+        'initial_focus: First focusable element inside the surface, else the surface itself (`tabindex=\\"-1\\"`, with a visible `:focus-visible` ring). Applied on the closed \u2192 open transition only.',
+        "backdrop_marked_aria_hidden: true",
+        "trigger_state_not_announced: The trigger wrapper gets no aria-haspopup, aria-expanded, or aria-controls, and no scoped props are exposed to build them. A trigger that needs to announce the drawer must wire those attributes from consumer state."
       ],
       behavior: [
         "uses_teleport_to_body: true",
         "locks_body_scroll_while_open: true",
         "overlay_click_closes_when_enabled: true",
         "close_button_optional: true",
-        "slides_in_from_side: true"
+        "slides_in_from_side: true",
+        "root_uses_display_contents_without_trigger: `t-drawer` is `display: inline-flex`, but a root with no `t-drawer__trigger` child switches to `display: contents` so the empty wrapper does not generate a line box and add stray height to the page.",
+        "topbar_rendered_when: title is non-empty OR the `header` slot is supplied OR showCloseButton is true",
+        "body_slot_precedence: content > default",
+        "footer_rendered_when: the `footer` slot is supplied",
+        'data_state_attribute: `data-state="open" | "closed"` on both the `t-drawer` root and the `t-drawer__portal`',
+        "focus_trap_detail: Tab and Shift+Tab cycle within the surface. With no focusable descendants, Tab is swallowed and focus is pushed back to the surface itself.",
+        'initial_open_skips_open_side_effects: {"value":true,"detail":"The on-open work \u2014 body scroll lock and initial focus \u2014 runs from a watcher on the open state that is not immediate, so a drawer that starts open via `defaultOpen: true` (or an `open` prop already true on first render) never locks scroll and never moves focus into the surface. Focus trap and Escape therefore stay dormant until the user tabs in. Start closed and open on the next tick if you need the full behavior.\\n"}',
+        'body_scroll_lock_scope: {"value":"per_component_instance","detail":"The overlay counter and the saved `overflow` value are per instance, not shared across overlays. Two overlays open at once each restore what they individually saw, so closing the first-opened one while a second is still open unlocks page scroll early.\\n"}'
       ],
       selection: {
         keywords: [
@@ -3141,7 +3970,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "accessible-by-default"
+      ]
     },
     {
       name: "TDropdown",
@@ -3160,22 +3992,25 @@ var treeui_catalog_default = {
           name: "items",
           type: "TDropdownItem[]",
           default: "[]",
-          note: "Array of { label: string; value: string; disabled?: boolean }"
+          note: 'Array of { label: string; value: string; disabled?: boolean }. Each entry renders one `<li role="menuitem">`, keyed by `value` \u2014 values must be unique, because the internal element map that drives focus is also keyed by `value` and duplicates collide. With the default `[]` the component still renders an empty `<ul role="menu">` and focus stays on the trigger; there is no empty-state affordance (no `emptyText`, no `empty` slot), so guard on `items.length` yourself.'
         },
         {
           name: "open",
           type: "boolean",
-          default: "undefined"
+          default: "undefined",
+          note: "Controlled open state. Once a boolean is passed the component stops tracking open state internally \u2014 it only emits update:open / open-change and the consumer MUST write the value back, or the menu never opens. Flipping it externally does not run the open routine: no item is focused and the outside-click listener is only attached from the transition, so an initially-`true` value opens the menu with focus untouched."
         },
         {
           name: "defaultOpen",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: "Uncontrolled initial open state, read once on mount. Later changes to it are ignored. It renders the menu already open but does NOT focus the first item (focusedIndex stays -1, so no `is-focused` row) and does NOT arm the outside-click listener until the open state changes at least once \u2014 see behavior.outside_click_closes_menu."
         },
         {
           name: "disabled",
           type: "boolean",
-          default: "false"
+          default: "false",
+          note: 'Sets the native `disabled` attribute on the built-in trigger button, adds `is-disabled` to the root, and suppresses the menu entirely (`v-if="isOpen && !disabled"`) \u2014 even while `open` is true. Also short-circuits openMenu, toggleMenu and the trigger keydown handler. It is bound only to the default button, so a custom `trigger` slot must render its own disabled state.'
         },
         {
           name: "size",
@@ -3185,12 +4020,14 @@ var treeui_catalog_default = {
             "sm",
             "md",
             "lg"
-          ]
+          ],
+          note: "Sizes the trigger and the menu rows. `t-dropdown--md` is emitted but has no CSS rule of its own \u2014 it is the base `.t-dropdown__trigger` / `.t-dropdown__item` styling."
         },
         {
           name: "label",
           type: "string",
-          default: ""
+          default: "",
+          note: 'Text of the built-in trigger button AND the menu\'s accessible name (`:aria-label="label || undefined"` on the `<ul role="menu">`). A custom `trigger` slot does not render `label`, but it still names the menu \u2014 keep passing it, or the menu has no accessible name at all.'
         },
         {
           name: "align",
@@ -3200,18 +4037,30 @@ var treeui_catalog_default = {
             "start",
             "end"
           ],
-          note: "Horizontal alignment of the menu relative to the trigger. Use `end` when the trigger sits near the right edge of a clipping container (e.g. a table actions column)."
+          note: "Horizontal alignment of the menu relative to the trigger \u2014 `start` pins `left: 0`, `end` pins `right: 0`. Use `end` when the trigger sits near the right edge of a clipping container (e.g. a table actions column). There is no collision detection: the menu is a plain absolutely-positioned child of the root, so it never flips and is clipped by any ancestor with `overflow: hidden`."
+        },
+        {
+          name: "id",
+          type: "string",
+          default: "undefined",
+          note: "Custom id for the menu element. Auto-generated when omitted; also exposed to the `trigger` slot as `menuId` so a custom trigger can wire aria-controls. Resolved once during setup \u2014 it is NOT reactive, so changing `id` after mount has no effect."
         }
       ],
       events: [
         {
-          name: "select"
+          name: "select",
+          description: "Emitted with the chosen item's `value`. Disabled items never emit. Fires before the menu closes; the close that follows restores focus to the trigger.",
+          payload: '[{"value":"string"}]'
         },
         {
-          name: "update:open"
+          name: "update:open",
+          description: "Emitted whenever the open state changes. Deduped \u2014 no emit when the next value equals the current one.",
+          payload: '["boolean"]'
         },
         {
-          name: "open-change"
+          name: "open-change",
+          description: "Emitted immediately after `update:open`, with the same payload. Alias for consumers that do not use v-model:open.",
+          payload: '["boolean"]'
         }
       ],
       slots: [
@@ -3224,23 +4073,39 @@ var treeui_catalog_default = {
       ],
       a11y: [
         "role: menu",
+        "menu_accessible_name_comes_from_the_label_prop: true",
         "trigger_aria_haspopup: menu",
         "trigger_aria_expanded: true",
         "trigger_aria_controls: menu id, while open",
+        "custom_trigger_caveat: The three trigger_aria_* guarantees above describe the BUILT-IN trigger button only. A custom `trigger` slot replaces that button, so the consumer must bind them from the `isOpen` and `menuId` scoped props \u2014 see slots.trigger.",
+        "item_role: menuitem",
         "aria_disabled_on_disabled_items: true",
+        "disabled_items_get_tabindex_minus_1_but_stay_programmatically_focusable: true",
         "focus_visible_on_trigger: true",
+        "items_receive_real_dom_focus_no_aria_activedescendant: true",
         "keyboard_arrow_navigation: true",
+        "arrow_navigation_skips_disabled_items: true",
+        "arrow_navigation_does_not_wrap_at_the_ends: true",
+        "arrow_down_or_arrow_up_on_the_trigger_both_open_at_the_first_enabled_item: true",
         "escape_closes_menu: true",
         "enter_space_selects_item: true",
-        "home_end_navigation: true"
+        "home_end_navigation: true",
+        "no_typeahead: true",
+        "tab_does_not_close_the_menu: true"
       ],
       behavior: [
-        "outside_click_closes_menu: true",
+        'outside_click_closes_menu: {"value":true,"detail":"Detected on a document `pointerdown` listener that is attached by a watcher on the open state. The watcher is not immediate, so a menu that is already open on mount \u2014 via `defaultOpen` or an initially-`true` `open` \u2014 has no listener until the open state changes at least once, and outside clicks do not close it.\\n"}',
         "outside_click_restores_focus: false",
         "chevron_rotates_when_open: true",
         "menu_grows_to_fit_items_without_wrapping: true",
-        "opening_focuses_first_enabled_item: true",
-        'focus_restores_on_close: {"value":true,"detail":"Focus returns to the trigger when the menu closes from inside it \u2014 selecting an item or pressing Escape. It deliberately does NOT move focus on an outside click, where the pointer has already placed focus elsewhere.\\n","applies_to_custom_trigger":true}'
+        "menu_scrolls_vertically_past_15rem: true",
+        "menu_renders_in_flow_with_no_portal_and_no_flip_positioning: true",
+        "menu_is_not_rendered_while_disabled: true",
+        "open_state_emits_are_deduped: true",
+        "controlled_open_requires_writing_the_value_back: true",
+        'opening_focuses_first_enabled_item: {"value":true,"detail":"Applies to the open routine only \u2014 a click or Enter/Space/ArrowDown/ArrowUp on the trigger. `defaultOpen` and an externally driven `open` skip it, leaving focusedIndex at -1 with no row focused and no `is-focused` class. With an empty `items` array focus stays on the trigger; when every item is disabled, focus lands on the first (disabled) item.\\n"}',
+        'keyboard_activation_on_the_trigger_never_closes_the_menu: {"value":true,"detail":"Clicking the trigger toggles, but Enter/Space/Arrow keys always call the open routine, so pressing them while the menu is open re-focuses the first enabled item instead of closing. Escape is the keyboard close.\\n"}',
+        'focus_restores_on_close: {"value":true,"detail":"Focus returns to the trigger when the menu closes from inside it \u2014 selecting an item or pressing Escape on an item. Closing from the trigger itself (clicking it again, or Escape while the trigger holds focus) does not run the restore, because focus is already there. It deliberately does NOT move focus on an outside click, where the pointer has already placed focus elsewhere.\\n","applies_to_custom_trigger":true}'
       ],
       selection: {
         keywords: [
@@ -3269,7 +4134,11 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "interaction-feedback",
+        "accessible-by-default"
+      ]
     },
     {
       name: "TEmptyState",
@@ -3361,7 +4230,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "state-clarity"
+      ]
     },
     {
       name: "TFileUpload",
@@ -3395,7 +4267,7 @@ var treeui_catalog_default = {
           name: "disabled",
           type: "boolean",
           default: "false",
-          description: "The ONLY prop that gates interaction. Disables the dropzone, the native input, Clear all, and every per-row Remove/Retry."
+          description: "The ONLY prop that gates interaction. Disables the dropzone, the native input, Clear all, and every per-row Remove/Retry, and makes the paste and drop handlers early-return."
         },
         {
           name: "loading",
@@ -3420,13 +4292,15 @@ var treeui_catalog_default = {
         },
         {
           name: "maxFiles",
-          type: "number",
-          default: "none"
+          type: "number | null",
+          default: "null",
+          description: "Cap on the TOTAL list size, not on one batch \u2014 remaining slots are counted against the files already selected. `multiple: false` overrides it with a hard cap of 1. Values below 0 are clamped to 0, which rejects everything."
         },
         {
           name: "maxFileSize",
-          type: "number",
-          default: "none"
+          type: "number | null",
+          default: "null",
+          description: "Per-file byte cap. Enforced only when it is a number greater than 0 \u2014 both `null` and `0` disable the check."
         },
         {
           name: "label",
@@ -3606,13 +4480,138 @@ var treeui_catalog_default = {
         alternatives: []
       },
       setup: {
-        required: [],
+        required: [],
+        notes: [
+          "Bind `modelValue` to `File[]`.",
+          "Use `accept`, `multiple`, and size limits in the app layer to constrain uploads."
+        ]
+      },
+      recipes: [],
+      practices: []
+    },
+    {
+      name: "TFlag",
+      aliases: [],
+      package: "@treeui/vue",
+      kind: "display",
+      category: "Data Display",
+      status: "available",
+      purpose: "Render a flat country flag image from a CDN at a fixed height, centred in a 3:2 box, with a text fallback when the request fails.",
+      sourceFile: "packages/vue/src/components/TFlag.vue",
+      storyFile: "apps/docs/src/stories/Flag.stories.ts",
+      storyTitle: "Components/Data Display/Flag",
+      manifestFile: "docs/ai/COMPONENTS/flag.yaml",
+      props: [
+        {
+          name: "code",
+          type: "string",
+          required: true,
+          description: "ISO 3166-1 alpha-2 country code. Case-insensitive \u2014 trimmed and lowercased before the URL is built."
+        },
+        {
+          name: "baseUrl",
+          type: "string",
+          default: "https://flagcdn.com",
+          description: "Origin serving the flag assets. The component appends a fixed path built from the CDN's fixed-height segments, so a self-hosted mirror must reproduce it exactly: 1x is `${baseUrl}/h20/{code}.png` (sm), `${baseUrl}/h20/{code}.png` (md), `${baseUrl}/h24/{code}.png` (lg); the matching 2x asset is emitted via srcset as `${baseUrl}/h40/{code}.png` (sm), `${baseUrl}/h40/{code}.png` (md), `${baseUrl}/h60/{code}.png` (lg). A trailing slash is stripped, so `https://cdn.example.com/flags/` and `https://cdn.example.com/flags` behave identically."
+        },
+        {
+          name: "size",
+          type: "TSize",
+          default: "md",
+          values: [
+            "sm",
+            "md",
+            "lg"
+          ],
+          description: "Box height, taken from `--tree-size-icon-sm/md/lg` (16px / 20px / 24px); the box width is 3:2 of that height. Also selects which CDN asset pair is requested \u2014 see `baseUrl`."
+        },
+        {
+          name: "label",
+          type: "string",
+          default: "undefined",
+          description: 'Accessible label. When set, the flag becomes role="img" with aria-label; otherwise it is aria-hidden. An empty string counts as unset \u2014 the flag stays decorative.'
+        },
+        {
+          name: "fallbackText",
+          type: "string",
+          default: "undefined",
+          description: 'Text shown when the image cannot load. Defaults to the normalized `code` uppercased, so a padded `" br "` falls back to `BR`.'
+        }
+      ],
+      events: [],
+      slots: [],
+      a11y: [
+        "decorative_by_default: true",
+        "becomes_image_when_labeled: true",
+        'image_alt_is_always_empty: The `<img>` always carries `alt=""`, so the accessible name comes only from `label` on the root span \u2014 never from the image itself.',
+        'fallback_text_is_hidden_when_decorative: The fallback text renders inside the root span, so without `label` it inherits `aria-hidden="true"` and is not announced. It is a visual affordance, not an accessible name.',
+        'consumer_aria_label_does_not_replace_label: Fallthrough attributes land on the same root span, so a consumer-supplied `aria-label` overrides the one built from `label` \u2014 but it does not set `role="img"` or clear `aria-hidden="true"`, leaving the flag hidden and the label unannounced. Use the `label` prop instead.',
+        "rule: Provide `label` only when the flag carries meaning that is not already in adjacent text \u2014 inside a language option the label is redundant."
+      ],
+      behavior: [
+        "falls_back_to_text_when_image_fails: true",
+        "failed_state_resets_when_resolved_src_changes: true",
+        "code_is_trimmed_and_lowercased: true",
+        "fixed_height_endpoints_serve_flat_artwork_at_true_proportions: The CDN's ratio-normalised (width-by-height) endpoints do force every flag into one box, but only by serving the WAVING artwork, which reads as decoration next to flat UI icons. The fixed-height endpoints used here (h20, h24, h40, h60) serve the flat artwork at each flag's true proportions instead: Nepal stays a pennant, Switzerland stays square, Qatar stays elongated.",
+        "shared_height_not_shared_ratio_is_what_aligns_a_column: Within a size step every flag is requested at the same asset height, so a stacked list lines up even though the widths differ. CSS then places each flag in a fixed 3:2 box (3:2 being the most common national flag ratio) with `object-fit: contain`, so the majority fill the box and the outliers centre inside it rather than being cropped or distorted.",
+        "retina_asset_is_at_least_twice_the_box_height: Box heights come from `--tree-size-icon-sm/md/lg` (16px / 20px / 24px) and the srcset asset is h40 (sm, md) or h60 (lg), so a 2x screen never upscales.",
+        "size_outside_the_union_falls_back_to_md: A JS consumer can pass a size outside `TSize`; the asset lookup falls back to the md pair rather than throwing on an undefined entry.",
+        "base_url_trailing_slash_is_normalised: Trailing slashes are stripped from `baseUrl` before the path is appended, so a self-hosted mirror cannot silently produce a double-slashed URL.",
+        "sm_and_md_share_one_asset_pair: sm and md both request h20 (h40 at 2x); only lg differs (h24, h60 at 2x). Four distinct segments exist in total, not one pair per size step, so a mirror needs four directories per flag.",
+        "path_template_is_public_contract: Changing `baseUrl` is a config change, not a breaking one, as long as the mirror serves the same fixed-height segments (h20, h24, h40, h60).",
+        "image_element_is_removed_not_hidden_on_failure: The `<img>` is behind `v-if`, so a failed load takes it out of the DOM and swaps in the fallback span \u2014 it is not left in place with `display: none`.",
+        "no_country_or_locale_dataset_is_shipped: TreeUI never maps a language or locale to a country code \u2014 the application owns that decision."
+      ],
+      selection: {
+        keywords: [
+          "flag",
+          "country flag",
+          "country",
+          "nationality",
+          "region",
+          "iso 3166",
+          "alpha-2"
+        ],
+        useWhen: [
+          "You need a country flag rendered from an ISO 3166-1 alpha-2 code.",
+          "Flags stacked in a list must share one height so rows stay aligned \u2014 the flat assets keep each flag's true proportions and centre inside a fixed 3:2 box.",
+          "You want a text fallback when the flag asset cannot load."
+        ],
+        avoidWhen: [
+          "The flag would be the only carrier of meaning \u2014 always pair it with adjacent text such as the language or country name.",
+          "You need an interface glyph rather than a country flag.",
+          "You are treating the flag as a language identity \u2014 a flag names a country, not a language."
+        ],
+        alternatives: [
+          {
+            component: "TIcon",
+            when: "The graphic is a registered TreeUI icon, not a country flag."
+          },
+          {
+            component: "TLanguageSelect",
+            when: "The flag belongs to a language or locale picker rather than standing alone."
+          }
+        ]
+      },
+      setup: {
+        required: [
+          "Pass `code` as an ISO 3166-1 alpha-2 country code. Matching is case-insensitive \u2014 the value is trimmed and lowercased internally.",
+          "Allow `https://flagcdn.com` in the app `Content-Security-Policy` `img-src` directive, or point `baseUrl` at a self-hosted mirror \u2014 flag images are fetched from a third-party CDN at runtime."
+        ],
         notes: [
-          "Bind `modelValue` to `File[]`.",
-          "Use `accept`, `multiple`, and size limits in the app layer to constrain uploads."
+          "A mirror must serve `{baseUrl}/{segment}/{code}.png` for both steps of every size: 1x `h20` (sm), `h20` (md), `h24` (lg); 2x `h40` (sm), `h40` (md), `h60` (lg). The 2x asset is emitted through `srcset`.",
+          "Those fixed-height segments are part of the contract, and they are the CDN's flat artwork \u2014 a mirror must serve flat flags, not the waving ones.",
+          "Do not substitute the CDN's ratio-normalised width-by-height endpoints. They equalise aspect ratio only by switching to the waving artwork, which reads as decoration next to flat UI icons.",
+          "The fixed-height assets keep each flag's true proportions \u2014 Nepal is a pennant, Switzerland is square, Qatar is elongated. A shared height, not a shared ratio, is what aligns a column of flags.",
+          "CSS puts the image in a fixed 3:2 box (3:2 being the most common national flag ratio) with `object-fit: contain`, so outliers centre inside the box instead of being cropped or distorted.",
+          "Each retina segment is at least twice its box height \u2014 boxes are `--tree-size-icon-sm/md/lg` = 16px/20px/24px \u2014 so 2x screens never upscale.",
+          "`baseUrl` may be written with or without a trailing slash; trailing slashes are stripped before the path is built. An unknown `size` falls back to the `md` assets.",
+          "When the image cannot load \u2014 offline, blocked by CSP, unknown code \u2014 the component renders the uppercased `code` as text. Override that text with `fallbackText`.",
+          "The flag is `aria-hidden` by default. Pass `label` only when the flag carries meaning on its own; beside a visible country or language name it should stay decorative."
         ]
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TFormField",
@@ -3741,7 +4740,12 @@ var treeui_catalog_default = {
         "date-range-form",
         "color-field",
         "tag-input",
-        "hierarchy-picker"
+        "hierarchy-picker",
+        "language-switcher"
+      ],
+      practices: [
+        "accessible-by-default",
+        "content-alignment"
       ]
     },
     {
@@ -3843,6 +4847,9 @@ var treeui_catalog_default = {
         "date-range-form",
         "stat-grid",
         "metric-dashboard"
+      ],
+      practices: [
+        "content-alignment"
       ]
     },
     {
@@ -3863,24 +4870,380 @@ var treeui_catalog_default = {
           type: "TIconName",
           required: true,
           values: [
+            "account",
+            "activity",
+            "ai-studio",
             "alert-circle",
+            "align-left",
+            "app-window",
+            "apps-grid",
+            "archive",
+            "archive-restore",
+            "arrow-down",
+            "arrow-left",
+            "arrow-left-right",
+            "arrow-right",
+            "arrow-up",
+            "arrow-up-right",
+            "assistant",
+            "automation-key",
+            "automations",
+            "badge",
+            "badge-check",
+            "badge-star",
+            "ban",
+            "bell",
+            "book-open",
+            "bookmark",
+            "bot",
+            "bot-badge",
+            "bot-users",
+            "boxes",
+            "boxes-model",
+            "braces",
+            "brackets",
+            "brain",
+            "brain-circuit",
+            "brain-lock",
+            "browser",
+            "brush",
+            "brush-stroke",
+            "bug",
+            "building-2",
+            "calculator",
             "calendar",
+            "calendar-clock",
+            "calendar-day",
+            "calendar-days",
+            "calendar-dot",
+            "calendar-plus",
+            "calendar-range",
+            "calendar-x",
+            "carousel",
+            "catalog",
+            "chart-column",
+            "chart-line",
+            "chart-pie",
+            "chat",
             "check",
-            "chevron-left",
+            "check-circle",
+            "check-square",
             "chevron-down",
+            "chevron-left",
             "chevron-right",
+            "chevron-up",
+            "chevron-updown",
+            "chevrons-up-down",
+            "circle-alert",
+            "circle-check",
+            "circle-dot",
+            "circle-help",
+            "circle-x",
+            "clipboard-list",
+            "clock",
+            "clock-alert",
+            "clock-sparkles",
+            "clock-x",
+            "close",
+            "cloud",
+            "cloud-off",
+            "code",
+            "code-2",
+            "code-api",
+            "coins",
+            "comment",
+            "companion",
+            "compass",
+            "connections",
+            "contentpilot",
+            "copy",
+            "cpu",
+            "cpu-chip",
+            "credit-card",
+            "crosshair",
+            "crown",
+            "cube",
+            "database",
+            "developer-settings",
+            "device-link",
+            "dollar-circle",
+            "dollar-limit",
+            "download",
+            "download-video",
+            "draw",
+            "droplet",
+            "ellipsis",
+            "ellipsis-vertical",
+            "embed-code",
+            "eraser",
+            "extension",
+            "external-link",
+            "eye",
+            "eye-off",
+            "file",
+            "file-archive",
+            "file-audio",
+            "file-code",
+            "file-edit",
+            "file-image",
+            "file-pdf",
+            "file-plus",
+            "file-scan",
+            "file-text",
+            "file-video",
+            "file-warning",
+            "files",
+            "film",
+            "filter",
+            "filter-capabilities",
+            "fingerprint",
+            "flag",
+            "flask-play",
+            "folder",
+            "folder-input",
+            "folder-kanban",
+            "folder-open",
+            "folder-plus",
+            "folder-shared",
+            "folder-tree",
+            "folder-x",
+            "folders",
+            "gauge",
+            "gauge-high",
+            "gauge-low",
+            "gauge-medium",
+            "gavel",
+            "git-branch",
+            "git-fork",
+            "globe",
+            "globe-check",
+            "grid",
+            "grip-vertical",
+            "hand-check",
+            "hard-drive",
+            "hard-drive-alert",
+            "hard-drive-off",
+            "hash",
+            "heart",
+            "heart-chart-up",
+            "heart-pulse",
+            "help",
+            "hierarchy",
+            "history",
+            "home",
+            "hourglass",
+            "house",
+            "human-lock",
+            "id-badge",
+            "image",
+            "image-minus",
+            "image-plus",
+            "image-up",
+            "inbox",
+            "inbox-empty",
             "info",
+            "install",
+            "journal",
+            "key",
+            "key-off",
+            "key-round",
+            "languages",
+            "laptop",
+            "laptop-bridge",
+            "layers",
+            "layout-dashboard",
+            "layout-grid",
+            "layout-kanban",
+            "leaf",
+            "library-books",
+            "life-buoy",
+            "lightbulb",
+            "lightbulb-sparkles",
+            "line-width",
+            "link",
+            "link-2",
+            "link-off",
+            "list",
+            "list-checks",
+            "list-ordered",
+            "list-rule",
+            "list-todo",
+            "llm",
             "loader-circle",
+            "lock",
+            "lock-keyhole",
+            "log-in",
+            "log-out",
+            "log-out-all",
+            "magic-wand",
+            "mail",
+            "mail-check",
+            "mail-open",
+            "mail-plus",
+            "mail-warning",
+            "mails",
+            "market",
+            "maximize-2",
+            "megaphone",
+            "memory-stick",
+            "menu",
+            "message-circle",
+            "message-square",
+            "message-square-plus",
+            "messages-square",
+            "mic",
+            "microphone",
+            "minimize-2",
+            "minus",
+            "minus-square",
+            "monitor-home",
+            "monitor-smartphone",
+            "moon",
+            "more-horizontal",
+            "mouse-pointer-2",
+            "move-horizontal",
+            "network",
+            "network-nodes",
+            "newsletter",
+            "newspaper",
+            "octagon-x",
+            "package",
+            "package-download",
+            "page-snapshot",
+            "palette",
+            "panel-left",
+            "panel-right",
+            "panels-top-left",
+            "paper-plane",
+            "paperclip",
+            "pause",
+            "pause-circle",
+            "pencil",
+            "persona",
+            "piggy-bank",
+            "pipette",
+            "play",
+            "play-circle",
+            "plug",
+            "plug-cloud",
+            "plug-off",
+            "plug-plus",
+            "plugin",
+            "plus",
+            "price-tag",
+            "publish",
+            "quote",
+            "radio",
+            "radio-tower",
+            "receipt",
+            "refresh",
+            "refresh-cw",
+            "refresh-cw-off",
+            "repeat",
+            "repeat-2",
+            "repeat-fallback",
+            "repeat-interval",
+            "responses-list",
+            "rocket",
+            "rotate-ccw",
+            "rotate-cw",
+            "route",
+            "rss",
+            "save",
+            "scale",
+            "scan",
             "search",
-            "x"
+            "search-x",
+            "send",
+            "send-check",
+            "send-request",
+            "server",
+            "server-api",
+            "server-environment",
+            "settings",
+            "settings-2",
+            "share",
+            "share-nodes",
+            "shield",
+            "shield-check",
+            "shield-lock",
+            "shield-question",
+            "shield-x",
+            "shopping-basket",
+            "shopping-cart",
+            "shuffle",
+            "signal",
+            "signal-high",
+            "signal-low",
+            "signal-medium",
+            "signal-off",
+            "siren",
+            "sliders-horizontal",
+            "smartphone",
+            "sparkles",
+            "square",
+            "square-check",
+            "square-plus",
+            "square-terminal",
+            "star",
+            "sticker",
+            "storage",
+            "store",
+            "story",
+            "sun",
+            "support",
+            "target",
+            "target-choice",
+            "tasks",
+            "terminal",
+            "ticket",
+            "ticket-plus",
+            "tickets",
+            "timeline",
+            "timer",
+            "toggle-left",
+            "toggle-right",
+            "token-input",
+            "token-output",
+            "trail",
+            "trash-2",
+            "trend-up",
+            "triangle-alert",
+            "type",
+            "unlink",
+            "unplug",
+            "upload",
+            "upload-cloud",
+            "user",
+            "user-check",
+            "user-cog",
+            "user-minus",
+            "user-plus",
+            "user-round",
+            "user-x",
+            "users",
+            "users-round",
+            "vault",
+            "volume-2",
+            "wallet",
+            "wand-sparkles",
+            "warehouse",
+            "workflow",
+            "workspace",
+            "wrench",
+            "wrench-zap",
+            "x",
+            "zap"
           ],
-          description: "Icon identifier from the @treeui/icons registry."
+          description: "Icon identifier from the @treeui/icons registry. Widens as `TIconRegistry` is augmented, so registered app icons are valid values too.",
+          note: "Names use TreeUI's descriptive kebab-case vocabulary. The catalog covers common application needs; anything missing is one `registerTreeIcons` call away, and `listTreeIcons()` returns the live list at runtime."
         },
         {
           name: "size",
           type: "number | string",
           default: "20",
-          description: "Pixel size for both width and height of the rendered svg."
+          description: "Pixel size for both width and height of the rendered svg.",
+          note: 'This is a PIXEL COUNT, not the sm | md | lg token scale used by nearly every\nother TreeUI component. `<TIcon size="md" />` does not fail loudly: it writes\nwidth="md" / height="md" onto the svg, which the browser discards, so the\nicon becomes unsized and stretches to fill its container. Pass a number\n(20, 32) or a numeric string ("20"). To size an icon from tokens, leave `size`\nalone and set width/height in CSS from the icon scale \u2014 --tree-size-icon-sm |\n-md | -lg | -xl | -2xl (1rem / 1.25rem / 1.5rem / 2rem / 3rem) \u2014 which is what\nTLanguageSelect\'s switcher variant does.\n'
         },
         {
           name: "strokeWidth",
@@ -3907,33 +5270,60 @@ var treeui_catalog_default = {
         "becomes_image_when_labeled: true",
         "rule: Provide `label` only when the icon conveys meaning that is not already in adjacent text."
       ],
-      behavior: [],
+      behavior: [
+        "unknown_name_renders_nothing: An unregistered name makes `resolveTreeIcon` return `undefined`, and `TIcon`'s `v-if` then renders no element at all \u2014 no empty box, no placeholder, no error. A `console.warn` names the missing icon, suggests the `registerTreeIcons` call, and lists every valid name. It warns once per NAME (not per message \u2014 the message embeds the valid-name list, which changes on every registration), so a miss inside a render loop cannot flood the console. The warning is NOT gated on `process.env.NODE_ENV`: it fires in production builds too, deliberately, because a missing icon is a misconfiguration worth hearing about once and `process` is undefined in most browser bundles. Components with a marker fallback (TNavMenu) show that instead \u2014 see nav-menu.yaml.",
+        'absolute_stroke_width_math: Icons draw on `viewBox="0 0 24 24"` with the svg sized to `size`, so painted pixels = (stroke-width attribute) * size / 24. With `absoluteStrokeWidth` (the default) the attribute is set to `(strokeWidth * 24) / size`, which cancels the scale: at the default `strokeWidth: 2` the attribute is 2.4 at size 20, 1.5 at 32, and 1.0 at 48 \u2014 a constant 2px painted at every size. That is the entire point of the correction: a 48px icon sits beside a 20px one at the same optical weight. A `size` of 0 or a non-numeric value keeps the nominal stroke rather than producing NaN/Infinity. Setting `absoluteStrokeWidth: false` pins the attribute at `strokeWidth`, which is the hand-rolled behaviour: the painted stroke then scales WITH the icon (1.67px at 20, 2.67px at 32, 4px at 48 \u2014 double the library weight).',
+        "icons_are_built_lazily_and_cached: Geometry lives in a data registry; a component is created on first lookup and reused after that, so an unused icon stays as DATA instead of becoming a `defineComponent`. Note what this does not claim: the geometry for all 364 built-ins is retained by any import of the package (the registry copies `builtinTreeIconNodes` into a `Map` at module scope, so a live reference exists and nothing tree-shakes it away \u2014 `sideEffects: false` does not change that). The saving is component construction, not bundle bytes.",
+        "resolved_per_render: TIcon resolves its name in a computed, not once at setup, so an icon registered after the component mounted still appears.",
+        "migration_aliases: Twelve compatibility names resolve to the same geometry as their canonical names: grid \u2192 layout-grid, share \u2192 share-nodes, chevron-updown \u2192 chevrons-up-down, refresh \u2192 refresh-cw, comment/chat \u2192 message-circle, check-square \u2192 square-check, help \u2192 circle-help, automations \u2192 zap, connections \u2192 external-link, persona \u2192 user-round, and close \u2192 x.",
+        "company_logos_are_app_owned: Company logos are not built-ins. When an application needs one, it imports the official SVG as its own component and passes or registers that component under an application-owned name."
+      ],
       selection: {
         keywords: [
           "icon",
           "svg",
           "glyph",
-          "pictogram"
+          "pictogram",
+          "register",
+          "register icon",
+          "custom icon",
+          "icon registry",
+          "registerTreeIcons",
+          "createTreeIcon"
         ],
         useWhen: [
-          "You need to render a registered TreeUI icon by name.",
-          "You want consistent sizing and a11y defaults without importing the icon component directly."
+          "You need to render an interface icon. `TIcon` is the way to render one \u2014 it resolves the name through the registry and applies the shared size, stroke, and a11y defaults.",
+          'The icon is one of the built-ins: `<TIcon name="cpu" />`. `listTreeIcons()` returns every registered name at runtime.',
+          "The icon is your own: register it once with `registerTreeIcons`, then use it by name exactly like a built-in. A missing icon is registered, not worked around."
         ],
         avoidWhen: [
-          "The icon is not in the @treeui/icons registry \u2014 import or register it instead."
+          "The graphic is a country flag \u2014 a flag names a country, not an interface concept.",
+          "A slot already renders the icon for you (`#icon` on TAlert, TBadge, TButton, TConfirmDialog, TEmptyState, TFileUpload, TStat, TTag) \u2014 put the `TIcon` inside that slot rather than beside it. None of those components has an `icon` PROP; the slot is the whole interface."
         ],
         alternatives: [
           {
-            component: "named import from @treeui/icons",
-            when: "You need tree-shaken, statically-imported icon components."
+            component: "a component passed straight to `TNavMenuItem.icon`, or rendered into an `#icon` slot",
+            when: "You want the escape hatch with no registry entry \u2014 a one-off icon, an imported SVG component, or the result of `createTreeIcon(...)`. `TNavMenuItem.icon` is `TIconInput` and takes the component directly; everywhere else, render it inside the component's `#icon` slot. `TIcon` itself will not take a component \u2014 its `name` is `TIconName`. Prefer registering when the icon is used in more than one place."
+          },
+          {
+            component: "TFlag",
+            when: "The graphic is a country flag rendered from an ISO 3166-1 alpha-2 code."
           }
         ]
       },
       setup: {
-        required: [],
-        notes: []
+        required: [
+          "Use a registered name: one of the built-ins, or one the app added with `registerTreeIcons`. See `icons` above."
+        ],
+        notes: [
+          '`size` is a pixel count, not `sm | md | lg`. Passing `size="md"` renders an unsized svg.',
+          "The icon is `aria-hidden` by default. Pass `label` only when the icon carries meaning on its own; beside visible text it should stay decorative."
+        ]
       },
-      recipes: []
+      recipes: [
+        "nav-menu-icons"
+      ],
+      practices: []
     },
     {
       name: "TInput",
@@ -4059,6 +5449,10 @@ var treeui_catalog_default = {
       recipes: [
         "form-field-input",
         "tag-input"
+      ],
+      practices: [
+        "interaction-feedback",
+        "predictable-api"
       ]
     },
     {
@@ -4096,7 +5490,245 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: []
+    },
+    {
+      name: "TLanguageSelect",
+      aliases: [],
+      package: "@treeui/vue",
+      kind: "form_overlay",
+      category: "Data Entry",
+      status: "available",
+      purpose: "Language/locale picker with a listbox, a flag per option, and the shared overlay contract; controlled and uncontrolled via v-model and open/defaultOpen.",
+      sourceFile: "packages/vue/src/components/TLanguageSelect.vue",
+      storyFile: "apps/docs/src/stories/LanguageSelect.stories.ts",
+      storyTitle: "Components/Data Entry/LanguageSelect",
+      manifestFile: "docs/ai/COMPONENTS/language-select.yaml",
+      props: [
+        {
+          name: "modelValue",
+          type: "string",
+          default: ""
+        },
+        {
+          name: "options",
+          type: "TLanguageOption[]",
+          default: "[]",
+          note: "Array of { label: string; value: string; code?: string; description?: string; disabled?: boolean }. `value` is an opaque application key (typically a BCP-47 tag) \u2014 never parsed or validated. `code` is an ISO 3166-1 alpha-2 country code for the flag; omit it to render the option without one. `description` is a secondary line, e.g. the endonym."
+        },
+        {
+          name: "open",
+          type: "boolean",
+          default: "undefined"
+        },
+        {
+          name: "defaultOpen",
+          type: "boolean",
+          default: "false"
+        },
+        {
+          name: "size",
+          type: "TSize",
+          default: "md",
+          values: [
+            "sm",
+            "md",
+            "lg"
+          ]
+        },
+        {
+          name: "variant",
+          type: "TLanguageSelectVariant",
+          default: "field",
+          values: [
+            "field",
+            "switcher"
+          ],
+          note: "`field` is a form control, sized and laid out like any other input. `switcher` is a page-level control for a navbar/appbar where nothing nearby labels it: it leads with a translate icon, trails the current flag, and sizes to its content."
+        },
+        {
+          name: "iconOnly",
+          type: "boolean",
+          default: "false",
+          note: "`switcher` only \u2014 ignored by `field`. Drops the visible language name, leaving the translate icon, the current flag, and the chevron. The trigger then has no text, so the consumer MUST pass an `aria-label`."
+        },
+        {
+          name: "width",
+          type: "TFieldWidth",
+          default: "full",
+          values: [
+            "xs",
+            "sm",
+            "md",
+            "lg",
+            "xl",
+            "full"
+          ],
+          note: "Inline-size cap (max-inline-size). Fluid by default; use instead of an inline width style. Applies to `variant: field` only \u2014 a `switcher` sizes to its content and ignores it."
+        },
+        {
+          name: "disabled",
+          type: "boolean",
+          default: "false"
+        },
+        {
+          name: "loading",
+          type: "boolean",
+          default: "false"
+        },
+        {
+          name: "invalid",
+          type: "boolean",
+          default: "false"
+        },
+        {
+          name: "placeholder",
+          type: "string",
+          default: ""
+        },
+        {
+          name: "flagBaseUrl",
+          type: "string",
+          default: "undefined",
+          note: "Forwarded to every nested TFlag. When omitted, TFlag's own default origin applies. Set once here to self-host flag assets."
+        },
+        {
+          name: "emptyText",
+          type: "string",
+          default: "No languages available."
+        }
+      ],
+      events: [
+        {
+          name: "update:modelValue"
+        },
+        {
+          name: "update:open"
+        },
+        {
+          name: "open-change"
+        }
+      ],
+      slots: [
+        {
+          name: "prefix",
+          description: "Leading content inside the trigger, before everything else \u2014 the selected flag and label in `field`, the translate icon in `switcher`."
+        },
+        {
+          name: "option",
+          description: `Replaces the default option body (flag, label, description). Renders INSIDE the row's <li role="option">, so it must contain only presentational content.
+`
+        },
+        {
+          name: "empty",
+          description: "Replaces `emptyText` when `options` is empty."
+        }
+      ],
+      a11y: [
+        "role: listbox",
+        "trigger_aria_haspopup: listbox",
+        "trigger_aria_expanded: true",
+        "trigger_aria_controls_when_open: true",
+        "aria_invalid_when_invalid: true",
+        "aria_busy_when_loading: true",
+        "aria_selected_on_options: true",
+        "aria_disabled_on_disabled_options: true",
+        "focus_visible_on_trigger: true",
+        "keyboard_arrow_navigation: true",
+        "escape_closes_dropdown: true",
+        "enter_space_selects_option: true",
+        "home_end_navigation: true",
+        "home_end_target_first_last_enabled_option: true",
+        "focus_restores_to_trigger_on_close: true",
+        "icon_only_removes_the_visible_language_name: true",
+        "icon_only_requires_a_consumer_supplied_aria_label_on_the_trigger: true",
+        "translate_icon_and_flags_are_decorative_not_the_accessible_name: true"
+      ],
+      behavior: [
+        "update_payload_type: string",
+        "loading_does_not_disable_by_itself: true",
+        "placeholder_shown_as_muted_text: true",
+        "chevron_rotates_when_open: true",
+        "check_icon_on_selected_option: true",
+        "outside_click_closes_dropdown: true",
+        "listbox_flips_above_trigger_when_space_below_is_insufficient: true",
+        "options_without_a_code_render_without_a_flag: true",
+        "empty_options_render_the_empty_slot_or_empty_text: true",
+        "field_variant_leads_the_trigger_with_the_selected_flag: true",
+        "field_variant_trigger_fills_its_container: true",
+        "switcher_variant_leads_the_trigger_with_a_translate_icon: true",
+        "switcher_variant_trails_the_current_flag_before_the_chevron: true",
+        "switcher_variant_trigger_sizes_to_its_content: true",
+        "switcher_variant_ignores_the_width_prop: true",
+        "switcher_listbox_aligns_to_the_trigger_right_edge: true",
+        "switcher_listbox_may_be_wider_than_the_trigger: true",
+        "icon_only_applies_to_the_switcher_variant_only: true",
+        "root_classes: t-language-select--field | t-language-select--switcher, plus t-language-select--icon-only"
+      ],
+      selection: {
+        keywords: [
+          "language select",
+          "language picker",
+          "locale",
+          "locale picker",
+          "i18n",
+          "internationalization",
+          "translation",
+          "country flag"
+        ],
+        useWhen: [
+          "The user is picking the interface language or locale.",
+          'The control is a labelled form field for the language value \u2014 `variant="field"` (the default), where the flag leads the trigger and `width` applies.',
+          'The control is a page-level language switcher in a navbar or app bar, where nothing nearby says what it changes \u2014 `variant="switcher"` leads with a translate icon and trails the current flag, sizes to its content, and ignores `width`.',
+          "A navbar switcher should shrink to icon and flag only \u2014 `iconOnly` drops the language name, so pass an `aria-label` to name the control.",
+          "Each language should render with its country flag, and optionally an endonym as a second line.",
+          "The app owns the language list and applies the locale side effects itself."
+        ],
+        avoidWhen: [
+          "The values are not languages or locales.",
+          "The language list is long enough that the user must type to narrow it down.",
+          "You expect TreeUI to supply the locale dataset \u2014 it ships none, so pass your own `options`."
+        ],
+        alternatives: [
+          {
+            component: "TSelect",
+            when: "The values are ordinary application data rather than languages or locales."
+          },
+          {
+            component: "TCombobox",
+            when: "The language list is long enough that typing to narrow it down is required."
+          },
+          {
+            component: "TFlag",
+            when: "You only need to render one country flag, without a picker around it."
+          }
+        ]
+      },
+      setup: {
+        required: [
+          "Pass `options` as `{ label, value, code?, description?, disabled? }[]`. TreeUI ships no language, locale, or country dataset \u2014 the app owns its language list.",
+          "Apply locale side effects (i18n locale, `lang` attribute, persistence) in the app layer; the component only reports the selected `value`.",
+          "Pass an `aria-label` whenever `iconOnly` is set \u2014 the visible language name is gone, so it is the control's only accessible name. It also labels the listbox."
+        ],
+        notes: [
+          "`variant` is `field` (default) or `switcher`, typed as `TLanguageSelectVariant` and exported from `@treeui/vue`.",
+          'Use `variant="field"` inside a form, next to other inputs, or wrapped in `TFormField`: the flag leads the trigger, the trigger fills its container, and `width` applies. A visible field label already says what the control changes.',
+          'Use `variant="switcher"` for a page-level control in a navbar or app bar, where nothing nearby labels it. A translate icon (`TIcon name="languages"`) leads and the current flag trails before the chevron, so the control reads as "page language, now set to this" without an external label.',
+          "A switcher sizes to its content, so `width` does not apply, and its listbox aligns to the trigger's right edge.",
+          "`iconOnly` is switcher-only and drops the visible language name, leaving the translate icon and the current flag.",
+          "`value` is an opaque application key, typically a BCP-47 tag such as `pt-BR`. TreeUI never parses or validates it.",
+          "`code` is the ISO 3166-1 alpha-2 code used for the option flag. Omit it to render the option without a flag \u2014 a language is not a country, so many entries have no honest flag.",
+          "Use `description` for a secondary line such as the endonym.",
+          "Set `flagBaseUrl` once on the select rather than per option; it is forwarded to every nested `TFlag`.",
+          "Bind `modelValue` to a `string`, and use `v-model:open` when the app controls open state.",
+          "The CDN and Content-Security-Policy requirements under `TFlag` apply whenever any option carries a `code`."
+        ]
+      },
+      recipes: [
+        "language-switcher"
+      ],
+      practices: []
     },
     {
       name: "TLink",
@@ -4197,7 +5829,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "interaction-feedback"
+      ]
     },
     {
       name: "TMarkdownEditor",
@@ -4306,7 +5941,8 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TModal",
@@ -4454,7 +6090,11 @@ var treeui_catalog_default = {
           "Use `v-model:open` for the idiomatic Vue controlled pattern."
         ]
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "accessible-by-default",
+        "predictable-api"
+      ]
     },
     {
       name: "TMultiSelect",
@@ -4613,7 +6253,8 @@ var treeui_catalog_default = {
       },
       recipes: [
         "searchable-multi-choice"
-      ]
+      ],
+      practices: []
     },
     {
       name: "TNavbar",
@@ -4711,6 +6352,9 @@ var treeui_catalog_default = {
       },
       recipes: [
         "sidebar-shell"
+      ],
+      practices: [
+        "token-driven"
       ]
     },
     {
@@ -4803,10 +6447,13 @@ var treeui_catalog_default = {
         keywords: [
           "nav menu",
           "sidebar nav",
-          "section nav"
+          "section nav",
+          "nav icons",
+          "sidebar rail"
         ],
         useWhen: [
-          "You need app-section navigation inside a shell or sidebar."
+          "You need app-section navigation inside a shell or sidebar.",
+          "Each section should carry an icon \u2014 set `icon` on the item to a registered name (`icon: 'layout-dashboard'`). Items with no icon fall back to a letter marker, which is also what a collapsed rail shows."
         ],
         avoidWhen: [
           "You need tabs for small panel switching."
@@ -4825,13 +6472,19 @@ var treeui_catalog_default = {
       setup: {
         required: [],
         notes: [
-          "When nested inside `TSidebar` or `TAppShell`, `collapsed` can be inherited from the sidebar provider."
+          "When nested inside `TSidebar` or `TAppShell`, `collapsed` can be inherited from the sidebar provider.",
+          "Pass `items` as `{ label, value, icon?, to?, badge?, description?, shortLabel?, disabled?, exact? }[]`.",
+          "`icon` is `TIconInput` \u2014 a registered icon name (`icon: 'layout-dashboard'`) or a component. Use the name: it needs no import, and no `markRaw` when the item list is reactive.",
+          "An item with no icon, or with a name that is not registered, shows a letter marker instead. That marker is also all a collapsed rail can show, so give every item an icon when the sidebar collapses.",
+          "Register any icon the app needs beyond the built-ins first \u2014 see `icons` above."
         ]
       },
       recipes: [
         "app-shell",
-        "sidebar-shell"
-      ]
+        "sidebar-shell",
+        "nav-menu-icons"
+      ],
+      practices: []
     },
     {
       name: "TNumberInput",
@@ -4938,7 +6591,8 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TPage",
@@ -5031,7 +6685,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "content-alignment"
+      ]
     },
     {
       name: "TPageHeader",
@@ -5125,7 +6782,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "content-alignment"
+      ]
     },
     {
       name: "TPagination",
@@ -5238,6 +6898,9 @@ var treeui_catalog_default = {
       },
       recipes: [
         "data-listing"
+      ],
+      practices: [
+        "interaction-feedback"
       ]
     },
     {
@@ -5297,7 +6960,7 @@ var treeui_catalog_default = {
       slots: [
         {
           name: "trigger",
-          description: "Custom trigger element. Receives current open state."
+          description: "Custom trigger element. Receives the current open state and the id of the content panel, so aria-expanded and aria-controls can be wired by hand.\n"
         },
         {
           name: "default",
@@ -5306,9 +6969,9 @@ var treeui_catalog_default = {
       ],
       a11y: [
         "role: dialog",
-        'attrs: ["aria-haspopup=\\"dialog\\" on trigger","aria-expanded on trigger","aria-controls linking trigger to content","tabindex=\\"-1\\" on content for focus management"]',
+        'attrs: ["aria-haspopup=\\"dialog\\" on the built-in trigger (custom triggers must supply it)","aria-expanded on the built-in trigger (custom triggers bind it from `isOpen`)","aria-controls linking trigger to content (custom triggers bind it from `contentId`)","tabindex=\\"-1\\" on content for focus management"]',
         'keyboard: ["Click or Enter/Space on trigger toggles popover","Escape closes popover and restores focus to trigger","Tab navigates within popover content"]',
-        'focus: ["On open, focuses first focusable element inside content (or content itself)","On Escape close, restores focus to trigger"]',
+        'focus: ["On open, focuses first focusable element inside content (or content itself)","On Escape close, restores focus to trigger","Focus restore works with a custom trigger too: the ref lives on the `t-popover__anchor` wrapper, not on the built-in button, and focus returns to the first focusable element inside it.\\n"]',
         'dismiss: ["Outside click closes popover","Escape key closes popover"]'
       ],
       behavior: [],
@@ -5341,7 +7004,8 @@ var treeui_catalog_default = {
       },
       recipes: [
         "anchored-help"
-      ]
+      ],
+      practices: []
     },
     {
       name: "TPricing",
@@ -5405,7 +7069,8 @@ var treeui_catalog_default = {
       },
       recipes: [
         "pricing-section"
-      ]
+      ],
+      practices: []
     },
     {
       name: "TPricingCard",
@@ -5534,7 +7199,8 @@ var treeui_catalog_default = {
       },
       recipes: [
         "pricing-section"
-      ]
+      ],
+      practices: []
     },
     {
       name: "TProgress",
@@ -5596,7 +7262,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "state-clarity"
+      ]
     },
     {
       name: "TRadio",
@@ -5664,7 +7333,8 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TRadioGroup",
@@ -5739,7 +7409,8 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TSelect",
@@ -5894,6 +7565,10 @@ var treeui_catalog_default = {
       },
       recipes: [
         "chart-surface"
+      ],
+      practices: [
+        "interaction-feedback",
+        "predictable-api"
       ]
     },
     {
@@ -6004,7 +7679,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "interaction-feedback"
+      ]
     },
     {
       name: "TSidebar",
@@ -6152,7 +7830,8 @@ var treeui_catalog_default = {
       },
       recipes: [
         "sidebar-shell"
-      ]
+      ],
+      practices: []
     },
     {
       name: "TSkeleton",
@@ -6215,7 +7894,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "state-clarity"
+      ]
     },
     {
       name: "TSpacer",
@@ -6255,7 +7937,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "content-alignment"
+      ]
     },
     {
       name: "TSparkline",
@@ -6378,7 +8063,8 @@ var treeui_catalog_default = {
       },
       recipes: [
         "metric-dashboard"
-      ]
+      ],
+      practices: []
     },
     {
       name: "TSpinner",
@@ -6427,7 +8113,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "state-clarity"
+      ]
     },
     {
       name: "TSplit",
@@ -6503,7 +8192,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "content-alignment"
+      ]
     },
     {
       name: "TStack",
@@ -6604,9 +8296,13 @@ var treeui_catalog_default = {
         notes: []
       },
       recipes: [
+        "brand-lockup",
         "tag-input",
         "data-listing",
         "chart-surface"
+      ],
+      practices: [
+        "content-alignment"
       ]
     },
     {
@@ -6681,7 +8377,8 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TStat",
@@ -6803,7 +8500,8 @@ var treeui_catalog_default = {
       recipes: [
         "stat-grid",
         "metric-dashboard"
-      ]
+      ],
+      practices: []
     },
     {
       name: "TSteps",
@@ -6907,7 +8605,8 @@ var treeui_catalog_default = {
           "Pass explicit `status` per item only when the app should override the computed complete/current/upcoming logic."
         ]
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TSwitch",
@@ -6996,7 +8695,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: [
+        "interaction-feedback"
+      ]
     },
     {
       name: "TTable",
@@ -7036,6 +8738,13 @@ var treeui_catalog_default = {
           type: "TTableSortState",
           required: false,
           description: "Controlled sort state. When provided, overrides internal sort tracking."
+        },
+        {
+          name: "caption",
+          type: "string",
+          required: false,
+          description: "Visible `<caption>` naming the table.",
+          note: "For a name without visible text, pass `aria-label` / `aria-labelledby` instead \u2014 attribute inheritance is disabled and every non-class/style attr is forwarded to the `<table>`, so the name lands on the named element rather than the scroll wrapper."
         }
       ],
       events: [
@@ -7060,7 +8769,9 @@ var treeui_catalog_default = {
         }
       ],
       a11y: [
-        "role: grid",
+        "role: table (native). No explicit role is emitted.",
+        'why_not_grid: TTable previously set role="grid" without implementing the composite-widget keyboard model \u2014 no roving tabindex, no gridcell/row roles, no 2D arrow-key navigation. Screen readers switched to application/focus mode and offered cell navigation that did not exist. The role was removed so the component is honestly a reading table. An opt-in interactive grid mode is deliberately NOT offered until the keyboard model ships.',
+        "accessible_name: Use `caption` for a visible name or `aria-label` / `aria-labelledby` for an invisible one. Both land on the `<table>`.",
         "aria-sort: Set on sortable column headers (ascending, descending, none).",
         "keyboard: Sortable headers are focusable and activated with Enter or Space.",
         "scope: col on all th elements."
@@ -7097,6 +8808,9 @@ var treeui_catalog_default = {
       },
       recipes: [
         "data-listing"
+      ],
+      practices: [
+        "state-clarity"
       ]
     },
     {
@@ -7203,6 +8917,9 @@ var treeui_catalog_default = {
       },
       recipes: [
         "router-backed-tabs"
+      ],
+      practices: [
+        "interaction-feedback"
       ]
     },
     {
@@ -7283,6 +9000,10 @@ var treeui_catalog_default = {
       },
       recipes: [
         "tag-input"
+      ],
+      practices: [
+        "predictable-api",
+        "token-driven"
       ]
     },
     {
@@ -7347,6 +9068,12 @@ var treeui_catalog_default = {
           type: "boolean",
           default: "false",
           note: "Clip to a single line with an ellipsis."
+        },
+        {
+          name: "preserveWhitespace",
+          type: "boolean",
+          default: "false",
+          note: "Render authored line breaks and blank lines as written (`white-space: pre-wrap`) while still wrapping long lines. Use for plain-text output such as AI responses, so consumers never need a local `white-space: pre-wrap` class. Mutually exclusive with `truncate`, which needs `nowrap`; when both are set `truncate` wins and no `is-pre-wrap` class is emitted."
         }
       ],
       events: [],
@@ -7360,7 +9087,8 @@ var treeui_catalog_default = {
       ],
       behavior: [
         "semantic_element_controlled_by_as: true",
-        "token_driven_size_tone_weight: true"
+        "token_driven_size_tone_weight: true",
+        "truncate_takes_precedence_over_preserve_whitespace: true"
       ],
       selection: {
         keywords: [],
@@ -7372,7 +9100,10 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [
+        "brand-lockup"
+      ],
+      practices: []
     },
     {
       name: "TTextarea",
@@ -7489,7 +9220,8 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TTimeline",
@@ -7549,7 +9281,8 @@ var treeui_catalog_default = {
         required: [],
         notes: []
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TToast",
@@ -7612,7 +9345,8 @@ var treeui_catalog_default = {
       },
       recipes: [
         "confirm-destructive-action"
-      ]
+      ],
+      practices: []
     },
     {
       name: "TToggleGroup",
@@ -7729,7 +9463,8 @@ var treeui_catalog_default = {
           'Use `selectionMode="multiple"` for small visible multi-choice sets.'
         ]
       },
-      recipes: []
+      recipes: [],
+      practices: []
     },
     {
       name: "TTooltip",
@@ -7841,6 +9576,9 @@ var treeui_catalog_default = {
       },
       recipes: [
         "anchored-help"
+      ],
+      practices: [
+        "accessible-by-default"
       ]
     },
     {
@@ -7853,7 +9591,7 @@ var treeui_catalog_default = {
       purpose: "Hierarchical tree view with expansion, keyboard navigation, and single or multiple selection.",
       sourceFile: "packages/vue/src/components/TTreeView.vue",
       storyFile: "apps/docs/src/stories/TreeView.stories.ts",
-      storyTitle: "Components/Navigation & Disclosure/TView",
+      storyTitle: "Components/Navigation & Disclosure/TreeView",
       manifestFile: "docs/ai/COMPONENTS/tree-view.yaml",
       props: [
         {
@@ -7963,6 +9701,9 @@ var treeui_catalog_default = {
       },
       recipes: [
         "hierarchy-picker"
+      ],
+      practices: [
+        "accessible-by-default"
       ]
     }
   ],
@@ -9119,7 +10860,8 @@ var formatComponentSummary = (component) => {
       "Setup",
       [...component.setup.required, ...component.setup.notes]
     ),
-    component.recipes.length > 0 ? `Recipes: ${component.recipes.join(", ")}` : void 0
+    component.recipes.length > 0 ? `Recipes: ${component.recipes.join(", ")}` : void 0,
+    component.practices.length > 0 ? `Practices: ${component.practices.join(", ")}` : void 0
   ].filter(Boolean);
   return lines.join("\n");
 };
@@ -9660,6 +11402,21 @@ var normalizeRecipes = (value) => {
     };
   });
 };
+var normalizePractices = (value) => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((practice) => {
+    const record = practice;
+    return {
+      id: String(record.id),
+      title: String(record.title),
+      summary: stringifyValue(record.summary) ?? "",
+      rules: normalizeStringList(record.rules),
+      components: normalizeStringList(record.components)
+    };
+  });
+};
 var loadYamlDocuments = (filePath) => (0, import_yaml.parseAllDocuments)(readText(filePath)).map((document) => document.toJSON()).filter((document) => Boolean(document));
 var buildStoryIndex = (repoRoot) => {
   const storiesDir = import_node_path.default.join(repoRoot, "apps/docs/src/stories");
@@ -9698,10 +11455,12 @@ var buildCatalogFromRepo = (repoRoot) => {
   const setupDoc = loadYamlDocuments(import_node_path.default.join(docsDir, "SETUP.yaml"))[0] ?? {};
   const recipesDoc = loadYamlDocuments(import_node_path.default.join(docsDir, "RECIPES.yaml"))[0] ?? {};
   const contractsDoc = loadYamlDocuments(import_node_path.default.join(docsDir, "CONTRACTS.yaml"))[0] ?? {};
+  const practicesDoc = JSON.parse(readText(import_node_path.default.join(docsDir, "practices.json")));
   const componentProfiles = selectionDoc.component_profiles ?? {};
   const componentSetup = setupDoc.component_setup ?? {};
   const aliasMap = contractsDoc.compatibility_aliases ?? {};
   const recipes = normalizeRecipes(recipesDoc.recipes);
+  const practices = normalizePractices(practicesDoc.practices);
   const components = import_node_fs.default.readdirSync(componentsDir).filter((fileName) => fileName.endsWith(".yaml")).flatMap((fileName) => {
     const filePath = import_node_path.default.join(componentsDir, fileName);
     return loadYamlDocuments(filePath).flatMap((document) => {
@@ -9720,6 +11479,7 @@ var buildCatalogFromRepo = (repoRoot) => {
         )
       );
       const componentRecipes = recipes.filter((recipe) => recipe.compose.includes(name)).map((recipe) => recipe.id);
+      const componentPractices = practices.filter((practice) => practice.components.includes(name)).map((practice) => practice.id);
       const entry = {
         name,
         legacyAlias: aliasMap[name] ?? aliases.find((alias) => alias.startsWith("Tree")),
@@ -9741,7 +11501,8 @@ var buildCatalogFromRepo = (repoRoot) => {
         behavior: normalizeStringList(document.behavior),
         selection,
         setup: setup2,
-        recipes: componentRecipes
+        recipes: componentRecipes,
+        practices: componentPractices
       };
       return [entry];
     });
@@ -9784,6 +11545,7 @@ var buildCatalogFromRepo = (repoRoot) => {
     packageVersion: vuePackage.version,
     decisionGuides: normalizeDecisionGuides(selectionDoc.decision_guides),
     recipes,
+    practices,
     setup,
     components,
     tokens: buildTokenEntries()
@@ -9819,6 +11581,12 @@ var resourceList = [
     description: "Reusable multi-component composition recipes.",
     mimeType: "application/json"
   },
+  {
+    uri: "treeui://practices",
+    name: "TreeUI practices",
+    description: "Named UX practices and the components that follow them.",
+    mimeType: "application/json"
+  },
   {
     uri: "treeui://tokens",
     name: "TreeUI design tokens",
@@ -9852,6 +11620,9 @@ var readResourcePayload = (uri) => {
   if (uri === "treeui://recipes") {
     return catalog.recipes;
   }
+  if (uri === "treeui://practices") {
+    return catalog.practices;
+  }
   if (uri === "treeui://tokens") {
     return catalog.tokens;
   }