themelia-ui 1.0.3 → 2.0.0

package/.agents/skills/themelia-ui/references/components/INDEX.json

@@ -1,7 +1,7 @@
 {
   "note": "Generated by scripts/gen-agent-skill.mjs from docs/generated/component-index.json — the same records the human documentation reads. Filter by layer, profile, family or symbol. chooseWhen/avoidWhen/alternatives are the selection guidance; alternatives name family ids, never symbols.",
   "schemaVersion": 2,
-  "packageVersion": "1.0.3",
+  "packageVersion": "2.0.0",
   "package": "themelia-ui",
   "families": [
     {
@@ -72,6 +72,7 @@
         "features/resource-assignment",
         "features/overlays"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/action-menu",
@@ -611,13 +612,14 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Commerce blocks (/blocks-commerce)",
+      "doc": "Cart, checkout & billing (/blocks-commerce)",
       "apiDoc": "components/admin--patterns--commerce.md",
       "chooseWhen": "Admin screens present orders, invoices, carts, fulfilment and loyalty.",
       "avoidWhen": "The record is a catalogue product, whose options and readiness live in features/products.",
       "alternatives": [
         "features/products"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/action-menu",
@@ -646,7 +648,7 @@
         },
         {
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "route": "/blocks-order",
@@ -682,103 +684,103 @@
           "id": "cart-summary",
           "title": "CartSummary",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "tax-breakdown",
           "title": "TaxBreakdown",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "discount-stack",
           "title": "DiscountStack",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "code-entry",
           "title": "CodeEntry",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "order-status",
           "title": "OrderStatusCard",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "shipment-tracking",
           "title": "ShipmentTracking",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "refund-status",
           "title": "RefundStatus",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "invoice-header",
           "title": "InvoiceHeader",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "invoice-line-items",
           "title": "InvoiceLineItems",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "invoice-mini",
           "title": "InvoiceMini",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "address-card",
           "title": "AddressCard",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "payment-method",
           "title": "PaymentMethodCard",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "payment-timeline",
           "title": "PaymentTimeline",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "subscription-summary",
           "title": "SubscriptionSummary",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "inventory-level",
           "title": "InventoryLevel",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "upcoming-bookings",
           "title": "UpcomingBookings",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "loyalty-points",
           "title": "LoyaltyPoints",
           "route": "/blocks-commerce",
-          "page": "Commerce blocks"
+          "page": "Cart, checkout & billing"
         },
         {
           "id": "order-status-axes",
@@ -898,6 +900,7 @@
       "alternatives": [
         "base/display"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/typography"
@@ -927,7 +930,9 @@
       "publicSymbols": [
         "ActionButtons",
         "ActionMenu",
-        "defaultActionMenuStrings"
+        "defaultActionMenuStrings",
+        "resolveContextActions",
+        "splitActions"
       ],
       "components": [
         "ActionButtons",
@@ -952,7 +957,7 @@
           "publicImport": "themelia-ui/base/action-menu",
           "cssImport": "themelia-ui/base/action-menu.css",
           "apiDoc": "components/base--action-menu.md#actionmenu",
-          "description": "Overflow commands for a page, a card, a table, or a row.\n\nThere is deliberately one of these rather than a menu per surface: grouping, the\ndestructive ordering, the checkbox rows, and the link handling are the parts everyone\ngets subtly different when they assemble a menu by hand.",
+          "description": "Overflow commands for a page, a card, a table or a row — one component so grouping,\ndestructive ordering, checkbox rows and links behave the same everywhere.",
           "guidanceSource": "family",
           "chooseWhen": "A row, card or header offers the same set of actions repeatedly and the overflow must collapse consistently.",
           "avoidWhen": "You are building a bespoke menu anatomy, or the trigger is a right-click.",
@@ -961,7 +966,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Action buttons (/action-buttons)",
+      "doc": "Action menu & buttons (/action-menu)",
       "apiDoc": "components/base--action-menu.md",
       "chooseWhen": "A row, card or header offers the same set of actions repeatedly and the overflow must collapse consistently.",
       "avoidWhen": "You are building a bespoke menu anatomy, or the trigger is a right-click.",
@@ -969,6 +974,7 @@
         "base/dropdown-menu",
         "base/context-menu"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/buttons",
@@ -976,45 +982,41 @@
         "base/typography"
       ],
       "previews": [
-        {
-          "route": "/action-buttons",
-          "page": "Action buttons"
-        },
         {
           "route": "/action-menu",
-          "page": "Action menu"
+          "page": "Action menu & buttons"
         }
       ],
       "recipes": [
-        {
-          "id": "action-buttons",
-          "title": "ActionButtons",
-          "route": "/action-buttons",
-          "page": "Action buttons"
-        },
-        {
-          "id": "action-buttons-max",
-          "title": "Overflow",
-          "route": "/action-buttons",
-          "page": "Action buttons"
-        },
         {
           "id": "action-menu",
           "title": "ActionMenu",
           "route": "/action-menu",
-          "page": "Action menu"
+          "page": "Action menu & buttons"
         },
         {
           "id": "action-menu-order",
           "title": "Destructive last",
           "route": "/action-menu",
-          "page": "Action menu"
+          "page": "Action menu & buttons"
         },
         {
           "id": "action-menu-width",
           "title": "Width and row slots",
           "route": "/action-menu",
-          "page": "Action menu"
+          "page": "Action menu & buttons"
+        },
+        {
+          "id": "menus-in-context",
+          "title": "In a card header",
+          "route": "/action-menu",
+          "page": "Action menu & buttons"
+        },
+        {
+          "id": "context-actions",
+          "title": "Actions that depend on a record",
+          "route": "/action-menu",
+          "page": "Action menu & buttons"
         }
       ]
     },
@@ -1026,45 +1028,18 @@
       "publicImport": "themelia-ui/base/alert-dialog",
       "cssImport": "themelia-ui/base/alert-dialog.css",
       "publicSymbols": [
-        "AlertDialog",
         "AlertDialogAction",
-        "AlertDialogBody",
         "AlertDialogCancel",
         "AlertDialogContent",
-        "AlertDialogDescription",
-        "AlertDialogFooter",
-        "AlertDialogHeader",
-        "AlertDialogMedia",
-        "AlertDialogTitle",
-        "AlertDialogTrigger"
+        "AlertDialogMedia"
       ],
       "components": [
-        "AlertDialog",
         "AlertDialogAction",
-        "AlertDialogBody",
         "AlertDialogCancel",
         "AlertDialogContent",
-        "AlertDialogDescription",
-        "AlertDialogFooter",
-        "AlertDialogHeader",
-        "AlertDialogMedia",
-        "AlertDialogTitle",
-        "AlertDialogTrigger"
+        "AlertDialogMedia"
       ],
       "componentGuidance": [
-        {
-          "symbol": "AlertDialog",
-          "publicImport": "themelia-ui/base/alert-dialog",
-          "cssImport": "themelia-ui/base/alert-dialog.css",
-          "apiDoc": "components/base--alert-dialog.md#alertdialog",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the alert-dialog anatomy itself inside base.",
-          "avoidWhen": "You are confirming a destructive action in an app — that lifecycle, focus trap and async state belong to ConfirmDialog.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
         {
           "symbol": "AlertDialogAction",
           "publicImport": "themelia-ui/base/alert-dialog",
@@ -1078,19 +1053,6 @@
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         },
-        {
-          "symbol": "AlertDialogBody",
-          "publicImport": "themelia-ui/base/alert-dialog",
-          "cssImport": "themelia-ui/base/alert-dialog.css",
-          "apiDoc": "components/base--alert-dialog.md#alertdialogbody",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the alert-dialog anatomy itself inside base.",
-          "avoidWhen": "You are confirming a destructive action in an app — that lifecycle, focus trap and async state belong to ConfirmDialog.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
         {
           "symbol": "AlertDialogCancel",
           "publicImport": "themelia-ui/base/alert-dialog",
@@ -1117,45 +1079,6 @@
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         },
-        {
-          "symbol": "AlertDialogDescription",
-          "publicImport": "themelia-ui/base/alert-dialog",
-          "cssImport": "themelia-ui/base/alert-dialog.css",
-          "apiDoc": "components/base--alert-dialog.md#alertdialogdescription",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the alert-dialog anatomy itself inside base.",
-          "avoidWhen": "You are confirming a destructive action in an app — that lifecycle, focus trap and async state belong to ConfirmDialog.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "AlertDialogFooter",
-          "publicImport": "themelia-ui/base/alert-dialog",
-          "cssImport": "themelia-ui/base/alert-dialog.css",
-          "apiDoc": "components/base--alert-dialog.md#alertdialogfooter",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the alert-dialog anatomy itself inside base.",
-          "avoidWhen": "You are confirming a destructive action in an app — that lifecycle, focus trap and async state belong to ConfirmDialog.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "AlertDialogHeader",
-          "publicImport": "themelia-ui/base/alert-dialog",
-          "cssImport": "themelia-ui/base/alert-dialog.css",
-          "apiDoc": "components/base--alert-dialog.md#alertdialogheader",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the alert-dialog anatomy itself inside base.",
-          "avoidWhen": "You are confirming a destructive action in an app — that lifecycle, focus trap and async state belong to ConfirmDialog.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
         {
           "symbol": "AlertDialogMedia",
           "publicImport": "themelia-ui/base/alert-dialog",
@@ -1168,57 +1091,32 @@
           "capabilities": [],
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "AlertDialogTitle",
-          "publicImport": "themelia-ui/base/alert-dialog",
-          "cssImport": "themelia-ui/base/alert-dialog.css",
-          "apiDoc": "components/base--alert-dialog.md#alertdialogtitle",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the alert-dialog anatomy itself inside base.",
-          "avoidWhen": "You are confirming a destructive action in an app — that lifecycle, focus trap and async state belong to ConfirmDialog.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "AlertDialogTrigger",
-          "publicImport": "themelia-ui/base/alert-dialog",
-          "cssImport": "themelia-ui/base/alert-dialog.css",
-          "apiDoc": "components/base--alert-dialog.md#alertdialogtrigger",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the alert-dialog anatomy itself inside base.",
-          "avoidWhen": "You are confirming a destructive action in an app — that lifecycle, focus trap and async state belong to ConfirmDialog.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Alert dialog (/alert-dialog)",
+      "doc": "Overlay, dialog & sheet (/overlay)",
       "apiDoc": "components/base--alert-dialog.md",
       "chooseWhen": "Documenting or extending the alert-dialog anatomy itself inside base.",
       "avoidWhen": "You are confirming a destructive action in an app — that lifecycle, focus trap and async state belong to ConfirmDialog.",
       "alternatives": [
         "features/overlays"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/overlay"
       ],
       "previews": [
         {
-          "route": "/alert-dialog",
-          "page": "Alert dialog"
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
         }
       ],
       "recipes": [
         {
           "id": "alert-dialog",
           "title": "Alert dialog",
-          "route": "/alert-dialog",
-          "page": "Alert dialog"
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
         }
       ]
     },
@@ -1250,7 +1148,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Menubar & hover card (/menubar)",
+      "doc": "Aspect ratio (/aspect-ratio)",
       "apiDoc": "components/base--aspect-ratio.md",
       "chooseWhen": "A media box must hold a fixed ratio while its width is decided by the layout.",
       "avoidWhen": "The element already has intrinsic dimensions, or you want a square avatar.",
@@ -1258,20 +1156,21 @@
         "base/avatar",
         "base/upload"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
         {
-          "route": "/menubar",
-          "page": "Menubar & hover card"
+          "route": "/aspect-ratio",
+          "page": "Aspect ratio"
         }
       ],
       "recipes": [
         {
           "id": "aspect-ratio",
           "title": "AspectRatio",
-          "route": "/menubar",
-          "page": "Menubar & hover card"
+          "route": "/aspect-ratio",
+          "page": "Aspect ratio"
         }
       ]
     },
@@ -1402,6 +1301,7 @@
         "base/upload",
         "primitives"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
@@ -1462,6 +1362,7 @@
         "base/display",
         "base/typography"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/slot"
@@ -1524,6 +1425,7 @@
         "base/action-menu",
         "base/forms"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/buttons",
@@ -1582,7 +1484,7 @@
           "publicImport": "themelia-ui/base/buttons",
           "cssImport": "themelia-ui/base/buttons.css",
           "apiDoc": "components/base--buttons.md#button",
-          "description": "",
+          "description": "No `size` prop by design: geometry follows the scale factors, so a denser region is a\nscope (styles/FACTORS.md).",
           "guidanceSource": "family",
           "chooseWhen": "Any activation control — including one that carries a loading state, a tooltip, or sits in a group.",
           "avoidWhen": "The control navigates and should be an anchor, or it toggles a persistent state.",
@@ -1621,7 +1523,7 @@
           "publicImport": "themelia-ui/base/buttons",
           "cssImport": "themelia-ui/base/buttons.css",
           "apiDoc": "components/base--buttons.md#buttongrouptext",
-          "description": "A non-interactive segment inside a group — a unit, a prefix, a count.\n\nA `<span>`, deliberately: it is not activatable, so making it a disabled button would\nput a phantom stop in the tab order and announce a control that does nothing.",
+          "description": "A non-interactive segment — a unit, a prefix, a count. A span, so it adds no tab stop.",
           "guidanceSource": "family",
           "chooseWhen": "Any activation control — including one that carries a loading state, a tooltip, or sits in a group.",
           "avoidWhen": "The control navigates and should be an anchor, or it toggles a persistent state.",
@@ -1677,6 +1579,7 @@
         "base/typography",
         "base/toggle"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/slot",
@@ -1825,7 +1728,7 @@
           "publicImport": "themelia-ui/base/cards",
           "cssImport": "themelia-ui/base/cards.css",
           "apiDoc": "components/base--cards.md#cardheader",
-          "description": "The header region.\n\nA single row of title-line content with trailing controls pushed to the end, plus an\noptional full-width row above it. The title truncates rather than pushing the controls\noff the row — a header that reflows when a name gets longer is the usual failure.",
+          "description": "The header region: a title row with trailing controls, plus an optional full-width row\nabove. The title truncates rather than pushing the controls off the row.",
           "guidanceSource": "family",
           "chooseWhen": "A surface needs visible chrome — border, padding, header and footer regions.",
           "avoidWhen": "You are framing reusable content that the call site should frame instead, or the rows are a list.",
@@ -1838,7 +1741,7 @@
           "publicImport": "themelia-ui/base/cards",
           "cssImport": "themelia-ui/base/cards.css",
           "apiDoc": "components/base--cards.md#cardprimaryaction",
-          "description": "Makes a whole card one target.\n\nA covering link rather than a wrapping one: wrapping the card in an anchor nests its\nbuttons and menus inside it, which is invalid and makes them unreachable. This sits\nbehind the content, and anything interactive is lifted above it in CSS.",
+          "description": "Makes a whole card one target with a covering link (wrapping the card would nest its\ncontrols inside an anchor). Interactive children are lifted above it in CSS.",
           "guidanceSource": "family",
           "chooseWhen": "A surface needs visible chrome — border, padding, header and footer regions.",
           "avoidWhen": "You are framing reusable content that the call site should frame instead, or the rows are a list.",
@@ -1868,6 +1771,7 @@
         "base/item",
         "base/structure"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/action-menu",
@@ -2026,6 +1930,7 @@
         "base/structure",
         "base/navigation"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/buttons"
@@ -2167,6 +2072,7 @@
       "alternatives": [
         "patterns/analytics"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "recharts"
       ],
@@ -2506,7 +2412,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Card radio group (/card-radio-group)",
+      "doc": "Radio groups (/radio-group)",
       "apiDoc": "components/base--choice-inputs.md",
       "chooseWhen": "The user picks from a known, closed set — checkbox, radio, switch or select.",
       "avoidWhen": "The set is large enough to need filtering, or the values are free text.",
@@ -2514,6 +2420,7 @@
         "base/combobox",
         "base/text-inputs"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/display",
@@ -2523,25 +2430,13 @@
         "base/typography"
       ],
       "previews": [
-        {
-          "route": "/card-radio-group",
-          "page": "Card radio group"
-        },
         {
           "route": "/checkbox",
           "page": "Checkbox"
         },
-        {
-          "route": "/list-radio-group",
-          "page": "List radio group"
-        },
-        {
-          "route": "/pill-radio-group",
-          "page": "Pill radio group"
-        },
         {
           "route": "/radio-group",
-          "page": "Radio group"
+          "page": "Radio groups"
         },
         {
           "route": "/select",
@@ -2549,26 +2444,10 @@
         },
         {
           "route": "/switch",
-          "page": "Switch"
-        },
-        {
-          "route": "/toggle-field",
-          "page": "Toggle field"
+          "page": "Switch & toggle field"
         }
       ],
       "recipes": [
-        {
-          "id": "card-radio",
-          "title": "CardRadioGroup",
-          "route": "/card-radio-group",
-          "page": "Card radio group"
-        },
-        {
-          "id": "card-checkbox",
-          "title": "CardCheckboxGroup",
-          "route": "/card-radio-group",
-          "page": "Card radio group"
-        },
         {
           "id": "checkbox",
           "title": "Checkbox",
@@ -2576,22 +2455,34 @@
           "page": "Checkbox"
         },
         {
-          "id": "list-radio",
-          "title": "ListRadioGroup",
-          "route": "/list-radio-group",
-          "page": "List radio group"
+          "id": "radio-group",
+          "title": "Radio group",
+          "route": "/radio-group",
+          "page": "Radio groups"
         },
         {
-          "id": "pill-radio",
-          "title": "PillRadioGroup",
-          "route": "/pill-radio-group",
-          "page": "Pill radio group"
+          "id": "card-radio",
+          "title": "Cards",
+          "route": "/radio-group",
+          "page": "Radio groups"
         },
         {
-          "id": "radio-group",
-          "title": "Radio group",
+          "id": "card-checkbox",
+          "title": "Cards, several at once",
           "route": "/radio-group",
-          "page": "Radio group"
+          "page": "Radio groups"
+        },
+        {
+          "id": "list-radio",
+          "title": "List",
+          "route": "/radio-group",
+          "page": "Radio groups"
+        },
+        {
+          "id": "pill-radio",
+          "title": "Pills",
+          "route": "/radio-group",
+          "page": "Radio groups"
         },
         {
           "id": "select",
@@ -2603,13 +2494,13 @@
           "id": "switch",
           "title": "Switch",
           "route": "/switch",
-          "page": "Switch"
+          "page": "Switch & toggle field"
         },
         {
           "id": "toggle-rows",
-          "title": "SwitchCard and ToggleField",
-          "route": "/toggle-field",
-          "page": "Toggle field"
+          "title": "Settings rows and feature cards",
+          "route": "/switch",
+          "page": "Switch & toggle field"
         }
       ]
     },
@@ -2637,6 +2528,7 @@
         "ComboboxItemIndicator",
         "ComboboxList",
         "ComboboxPopup",
+        "ComboboxPopupInput",
         "ComboboxPortal",
         "ComboboxPositioner",
         "ComboboxRoot",
@@ -2664,6 +2556,7 @@
         "ComboboxItemIndicator",
         "ComboboxList",
         "ComboboxPopup",
+        "ComboboxPopupInput",
         "ComboboxPortal",
         "ComboboxPositioner",
         "ComboboxRoot",
@@ -2705,7 +2598,7 @@
           "publicImport": "themelia-ui/base/combobox",
           "cssImport": "themelia-ui/base/combobox.css",
           "apiDoc": "components/base--combobox.md#comboboxchip",
-          "description": "",
+          "description": "One selection inside `ComboboxChips`, with its remove control.\n\nThe remove control is named from the chip's text, so pass the label as plain text. For\na chip with richer content, `strings.removeChip` supplies the name instead.",
           "guidanceSource": "family",
           "chooseWhen": "Composing a filtered single- or multi-select from its parts, with options already in memory.",
           "avoidWhen": "Options arrive from a fetch, or you want the assembled control rather than the anatomy.",
@@ -2822,7 +2715,7 @@
           "publicImport": "themelia-ui/base/combobox",
           "cssImport": "themelia-ui/base/combobox.css",
           "apiDoc": "components/base--combobox.md#comboboxinputtrigger",
-          "description": "The input with its trailing chevron, and optionally a clear button — the shape a\nsearchable combobox almost always wants, with the padding that keeps the text clear of\nboth computed rather than guessed.",
+          "description": "The input with its trailing chevron and optional clear button, padded so text never\nruns under them. `strings` names the two trailing controls.",
           "guidanceSource": "family",
           "chooseWhen": "Composing a filtered single- or multi-select from its parts, with options already in memory.",
           "avoidWhen": "Options arrive from a fetch, or you want the assembled control rather than the anatomy.",
@@ -2882,12 +2775,25 @@
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         },
+        {
+          "symbol": "ComboboxPopupInput",
+          "publicImport": "themelia-ui/base/combobox",
+          "cssImport": "themelia-ui/base/combobox.css",
+          "apiDoc": "components/base--combobox.md#comboboxpopupinput",
+          "description": "The search band inside the popup, for the `ComboboxTrigger` shape: focus lands here when\nthe popup opens, typing filters the list, and the arrow keys and Enter drive it. Give it\nan `aria-label` — its placeholder is not a name.",
+          "guidanceSource": "family",
+          "chooseWhen": "Composing a filtered single- or multi-select from its parts, with options already in memory.",
+          "avoidWhen": "Options arrive from a fetch, or you want the assembled control rather than the anatomy.",
+          "capabilities": [],
+          "alternatives": [],
+          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
+        },
         {
           "symbol": "ComboboxPortal",
           "publicImport": "themelia-ui/base/combobox",
           "cssImport": "themelia-ui/base/combobox.css",
           "apiDoc": "components/base--combobox.md#comboboxportal",
-          "description": "",
+          "description": "The popup's portal, routed through the nearest `UIPortalHost` like every kit popup.",
           "guidanceSource": "family",
           "chooseWhen": "Composing a filtered single- or multi-select from its parts, with options already in memory.",
           "avoidWhen": "Options arrive from a fetch, or you want the assembled control rather than the anatomy.",
@@ -2952,7 +2858,7 @@
           "publicImport": "themelia-ui/base/combobox",
           "cssImport": "themelia-ui/base/combobox.css",
           "apiDoc": "components/base--combobox.md#comboboxtrigger",
-          "description": "The whole field as one trigger — a select-like combobox with no free text.",
+          "description": "The whole field as one trigger — a select-like combobox with no free text. Pair it with\n`ComboboxPopupInput`: Base UI drives the list's keyboard cursor from an input. For a\nshort list with no search, use `Select`.",
           "guidanceSource": "family",
           "chooseWhen": "Composing a filtered single- or multi-select from its parts, with options already in memory.",
           "avoidWhen": "Options arrive from a fetch, or you want the assembled control rather than the anatomy.",
@@ -2995,6 +2901,7 @@
         "features/combobox",
         "base/choice-inputs"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/typography"
@@ -3007,8 +2914,8 @@
       ],
       "recipes": [
         {
-          "id": "combobox-field",
-          "title": "One field surface",
+          "id": "combobox-rule",
+          "title": "The pickers do not filter",
           "route": "/combobox",
           "page": "Combobox"
         },
@@ -3175,7 +3082,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Command (/command)",
+      "doc": "Command palette (/command)",
       "apiDoc": "components/base--command.md",
       "chooseWhen": "A keyboard-first palette lists commands across groups, usually behind a shortcut.",
       "avoidWhen": "The palette searches application records rather than commands.",
@@ -3183,15 +3090,17 @@
         "features/global-search",
         "base/combobox"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/dialog",
-        "base/input-group"
+        "base/input-group",
+        "base/overlay"
       ],
       "previews": [
         {
           "route": "/command",
-          "page": "Command"
+          "page": "Command palette"
         }
       ],
       "recipes": [
@@ -3199,7 +3108,7 @@
           "id": "command",
           "title": "Command",
           "route": "/command",
-          "page": "Command"
+          "page": "Command palette"
         }
       ]
     },
@@ -3441,7 +3350,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Context menu (/context-menu)",
+      "doc": "Dropdown & context menu (/dropdown-menu)",
       "apiDoc": "components/base--context-menu.md",
       "chooseWhen": "The trigger is a right-click on a region that has its own actions.",
       "avoidWhen": "The trigger is a visible button, or the actions repeat across rows.",
@@ -3449,22 +3358,23 @@
         "base/dropdown-menu",
         "base/action-menu"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/dropdown-menu"
       ],
       "previews": [
         {
-          "route": "/context-menu",
-          "page": "Context menu"
+          "route": "/dropdown-menu",
+          "page": "Dropdown & context menu"
         }
       ],
       "recipes": [
         {
           "id": "context-menu",
-          "title": "Context menu",
-          "route": "/context-menu",
-          "page": "Context menu"
+          "title": "Opened by right-click",
+          "route": "/dropdown-menu",
+          "page": "Dropdown & context menu"
         }
       ]
     },
@@ -3519,6 +3429,7 @@
       "alternatives": [
         "primitives"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/buttons",
@@ -3560,7 +3471,6 @@
         "DatePickerHeader",
         "MonthYearPicker",
         "MultipleDatePicker",
-        "RANGE_PRESETS",
         "RangeDatePicker",
         "SingleDatePicker",
         "TimePicker",
@@ -3708,6 +3618,7 @@
         "base/value-inputs",
         "primitives"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/buttons",
@@ -3771,69 +3682,12 @@
       "publicImport": "themelia-ui/base/dialog",
       "cssImport": "themelia-ui/base/dialog.css",
       "publicSymbols": [
-        "Dialog",
-        "DialogBody",
-        "DialogClose",
-        "DialogContent",
-        "DialogDescription",
-        "DialogDismissArea",
-        "DialogFooter",
-        "DialogHeader",
-        "DialogTitle",
-        "DialogTrigger"
+        "DialogContent"
       ],
       "components": [
-        "Dialog",
-        "DialogBody",
-        "DialogClose",
-        "DialogContent",
-        "DialogDescription",
-        "DialogDismissArea",
-        "DialogFooter",
-        "DialogHeader",
-        "DialogTitle",
-        "DialogTrigger"
+        "DialogContent"
       ],
       "componentGuidance": [
-        {
-          "symbol": "Dialog",
-          "publicImport": "themelia-ui/base/dialog",
-          "cssImport": "themelia-ui/base/dialog.css",
-          "apiDoc": "components/base--dialog.md#dialog",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the dialog anatomy itself inside base.",
-          "avoidWhen": "You are presenting a modal in an app — the portal, focus trap, scroll lock and async confirm lifecycle belong to features/overlays.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "DialogBody",
-          "publicImport": "themelia-ui/base/dialog",
-          "cssImport": "themelia-ui/base/dialog.css",
-          "apiDoc": "components/base--dialog.md#dialogbody",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the dialog anatomy itself inside base.",
-          "avoidWhen": "You are presenting a modal in an app — the portal, focus trap, scroll lock and async confirm lifecycle belong to features/overlays.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "DialogClose",
-          "publicImport": "themelia-ui/base/dialog",
-          "cssImport": "themelia-ui/base/dialog.css",
-          "apiDoc": "components/base--dialog.md#dialogclose",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the dialog anatomy itself inside base.",
-          "avoidWhen": "You are presenting a modal in an app — the portal, focus trap, scroll lock and async confirm lifecycle belong to features/overlays.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
         {
           "symbol": "DialogContent",
           "publicImport": "themelia-ui/base/dialog",
@@ -3846,121 +3700,32 @@
           "capabilities": [],
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "DialogDescription",
-          "publicImport": "themelia-ui/base/dialog",
-          "cssImport": "themelia-ui/base/dialog.css",
-          "apiDoc": "components/base--dialog.md#dialogdescription",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the dialog anatomy itself inside base.",
-          "avoidWhen": "You are presenting a modal in an app — the portal, focus trap, scroll lock and async confirm lifecycle belong to features/overlays.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "DialogDismissArea",
-          "publicImport": "themelia-ui/base/dialog",
-          "cssImport": "themelia-ui/base/dialog.css",
-          "apiDoc": "components/base--dialog.md#dialogdismissarea",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the dialog anatomy itself inside base.",
-          "avoidWhen": "You are presenting a modal in an app — the portal, focus trap, scroll lock and async confirm lifecycle belong to features/overlays.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "DialogFooter",
-          "publicImport": "themelia-ui/base/dialog",
-          "cssImport": "themelia-ui/base/dialog.css",
-          "apiDoc": "components/base--dialog.md#dialogfooter",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the dialog anatomy itself inside base.",
-          "avoidWhen": "You are presenting a modal in an app — the portal, focus trap, scroll lock and async confirm lifecycle belong to features/overlays.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "DialogHeader",
-          "publicImport": "themelia-ui/base/dialog",
-          "cssImport": "themelia-ui/base/dialog.css",
-          "apiDoc": "components/base--dialog.md#dialogheader",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the dialog anatomy itself inside base.",
-          "avoidWhen": "You are presenting a modal in an app — the portal, focus trap, scroll lock and async confirm lifecycle belong to features/overlays.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "DialogTitle",
-          "publicImport": "themelia-ui/base/dialog",
-          "cssImport": "themelia-ui/base/dialog.css",
-          "apiDoc": "components/base--dialog.md#dialogtitle",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the dialog anatomy itself inside base.",
-          "avoidWhen": "You are presenting a modal in an app — the portal, focus trap, scroll lock and async confirm lifecycle belong to features/overlays.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "DialogTrigger",
-          "publicImport": "themelia-ui/base/dialog",
-          "cssImport": "themelia-ui/base/dialog.css",
-          "apiDoc": "components/base--dialog.md#dialogtrigger",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting or extending the dialog anatomy itself inside base.",
-          "avoidWhen": "You are presenting a modal in an app — the portal, focus trap, scroll lock and async confirm lifecycle belong to features/overlays.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Dialog (/dialog)",
+      "doc": "Overlay, dialog & sheet (/overlay)",
       "apiDoc": "components/base--dialog.md",
       "chooseWhen": "Documenting or extending the dialog anatomy itself inside base.",
       "avoidWhen": "You are presenting a modal in an app — the portal, focus trap, scroll lock and async confirm lifecycle belong to features/overlays.",
       "alternatives": [
         "features/overlays"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/overlay"
       ],
       "previews": [
         {
-          "route": "/dialog",
-          "page": "Dialog"
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
         }
       ],
       "recipes": [
         {
-          "id": "dialog",
-          "title": "Dialog",
-          "route": "/dialog",
-          "page": "Dialog"
-        },
-        {
-          "id": "dialog-surface",
-          "title": "Bare surface",
-          "route": "/dialog",
-          "page": "Dialog"
-        },
-        {
-          "id": "dialog-focus",
-          "title": "Where focus lands",
-          "route": "/dialog",
-          "page": "Dialog"
+          "id": "overlay-rule",
+          "title": "Three presets, one surface",
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
         }
       ]
     },
@@ -3999,6 +3764,7 @@
       "alternatives": [
         "ui-provider"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
@@ -4190,7 +3956,7 @@
           "publicImport": "themelia-ui/base/display",
           "cssImport": "themelia-ui/base/display.css",
           "apiDoc": "components/base--display.md#kbdgroup",
-          "description": "Several caps in a row — \"⌘ then K\", a two-key sequence.\n\nDistinct from passing a chord as one `Kbd`: that is one key combination pressed\ntogether and reads as one token; this is a SEQUENCE, and the gap between the caps is\nwhat says so.",
+          "description": "Several caps as a sequence (\"⌘ then K\"); the gap between caps marks it as a sequence, not a chord.",
           "guidanceSource": "family",
           "chooseWhen": "Presenting label/key and value facts, a collapsible region, a keyboard hint or a scrollable pane.",
           "avoidWhen": "The pair is an editable field, or the row carries identity and actions.",
@@ -4297,6 +4063,7 @@
         "base/forms",
         "base/item"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/badge",
@@ -4314,17 +4081,21 @@
           "route": "/content-block",
           "page": "Content block"
         },
+        {
+          "route": "/date-block",
+          "page": "Date block"
+        },
         {
           "route": "/inline-stat",
           "page": "Inline stat"
         },
         {
-          "route": "/metadata",
-          "page": "Metadata list"
+          "route": "/kbd",
+          "page": "Keyboard key"
         },
         {
-          "route": "/menubar",
-          "page": "Menubar & hover card"
+          "route": "/metadata",
+          "page": "Metadata list"
         },
         {
           "route": "/scroll-area",
@@ -4366,12 +4137,6 @@
           "route": "/content-block",
           "page": "Content block"
         },
-        {
-          "id": "date-block",
-          "title": "DateBlock",
-          "route": "/content-block",
-          "page": "Content block"
-        },
         {
           "id": "placeholder-pattern",
           "title": "PlaceholderPattern",
@@ -4379,23 +4144,41 @@
           "page": "Content block"
         },
         {
-          "id": "inline-stat-between",
-          "title": "between",
-          "route": "/inline-stat",
-          "page": "Inline stat"
+          "id": "date-block",
+          "title": "DateBlock",
+          "route": "/date-block",
+          "page": "Date block"
         },
         {
-          "id": "inline-stat-inline",
-          "title": "inline",
-          "route": "/inline-stat",
-          "page": "Inline stat"
+          "id": "date-block-parts",
+          "title": "Parts",
+          "route": "/date-block",
+          "page": "Date block"
+        },
+        {
+          "id": "date-block-in-a-list",
+          "title": "In a list",
+          "route": "/date-block",
+          "page": "Date block"
         },
         {
-          "id": "inline-stat-stacked",
-          "title": "stacked",
+          "id": "date-block-unboxed",
+          "title": "Unboxed and inline",
+          "route": "/date-block",
+          "page": "Date block"
+        },
+        {
+          "id": "inline-stat",
+          "title": "Three layouts for one fact",
           "route": "/inline-stat",
           "page": "Inline stat"
         },
+        {
+          "id": "kbd",
+          "title": "Kbd",
+          "route": "/kbd",
+          "page": "Keyboard key"
+        },
         {
           "id": "metadata-grid",
           "title": "grid",
@@ -4420,12 +4203,6 @@
           "route": "/metadata",
           "page": "Metadata list"
         },
-        {
-          "id": "kbd",
-          "title": "Kbd",
-          "route": "/menubar",
-          "page": "Menubar & hover card"
-        },
         {
           "id": "scroll-area",
           "title": "ScrollArea",
@@ -4711,7 +4488,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Dropdown menu (/dropdown-menu)",
+      "doc": "Dropdown & context menu (/dropdown-menu)",
       "apiDoc": "components/base--dropdown-menu.md",
       "chooseWhen": "Composing a menu anatomy — submenus, radio and checkbox items — from its parts.",
       "avoidWhen": "You want the assembled row-actions control, or the trigger is a right-click.",
@@ -4719,12 +4496,13 @@
         "base/action-menu",
         "base/context-menu"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
         {
           "route": "/dropdown-menu",
-          "page": "Dropdown menu"
+          "page": "Dropdown & context menu"
         }
       ],
       "recipes": [
@@ -4732,7 +4510,7 @@
           "id": "dropdown-menu",
           "title": "Dropdown menu",
           "route": "/dropdown-menu",
-          "page": "Dropdown menu"
+          "page": "Dropdown & context menu"
         }
       ]
     },
@@ -4985,6 +4763,7 @@
         "base/skeleton",
         "base/toaster"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/buttons",
@@ -5112,7 +4891,7 @@
           "publicImport": "themelia-ui/base/forms",
           "cssImport": "themelia-ui/base/forms.css",
           "apiDoc": "components/base--forms.md#errorsummary",
-          "description": "Collects what failed into one place at the top of a form.\n\nA form that only marks its failed fields red makes the reader hunt for them, and on a\nlong form the first failure is often off screen. The count is part of the heading\nbecause \"3 problems\" is the fact that decides whether to keep scrolling.",
+          "description": "Collects what failed into one place at the top of a form. The count is in the heading\nbecause it tells the reader how much there is to fix.",
           "guidanceSource": "family",
           "chooseWhen": "Assembling a form's visible structure — label, control, support text, sections and an actions bar.",
           "avoidWhen": "The fields come from a schema, or you only need the binding hooks.",
@@ -5182,7 +4961,7 @@
           "publicImport": "themelia-ui/base/forms",
           "cssImport": "themelia-ui/base/forms.css",
           "apiDoc": "components/base--forms.md#submitstatebutton",
-          "description": "A submit button that says what it is doing.\n\nThe label changes rather than the button disappearing behind a spinner, because\n\"Saving…\" is the answer to the question the reader is actually asking. It stays\ndisabled while submitting so a second click cannot double-submit.",
+          "description": "A submit button that says what it is doing. The label stays visible beside the spinner\n(unlike Button's `loading`). While submitting it is `aria-disabled`, keeping focus while\nblocking a second submission; \"Saved\" carries a check.",
           "guidanceSource": "family",
           "chooseWhen": "Assembling a form's visible structure — label, control, support text, sections and an actions bar.",
           "avoidWhen": "The fields come from a schema, or you only need the binding hooks.",
@@ -5199,6 +4978,7 @@
         "features/schema-form",
         "forms"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/buttons",
@@ -5423,6 +5203,7 @@
         "base/text-inputs",
         "primitives"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/choice-inputs",
@@ -5528,7 +5309,7 @@
           "publicImport": "themelia-ui/base/hover-card",
           "cssImport": "themelia-ui/base/hover-card.css",
           "apiDoc": "components/base--hover-card.md#hovercardtrigger",
-          "description": "The delays live here rather than on the root, and both have defaults.\n\n`closeDelay` is the load-bearing one: without it the card closes the instant the\npointer leaves the trigger, and the gap between trigger and card is exactly where the\npointer has to travel to read it.",
+          "description": "Trigger with default delays. `closeDelay` keeps the card open while the pointer crosses\nthe gap to it.",
           "guidanceSource": "family",
           "chooseWhen": "Hovering a reference reveals a preview the reader does not have to act on.",
           "avoidWhen": "The content is essential, interactive, or must be reachable by keyboard alone.",
@@ -5537,7 +5318,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Menubar & hover card (/menubar)",
+      "doc": "Hover card (/hover-card)",
       "apiDoc": "components/base--hover-card.md",
       "chooseWhen": "Hovering a reference reveals a preview the reader does not have to act on.",
       "avoidWhen": "The content is essential, interactive, or must be reachable by keyboard alone.",
@@ -5545,20 +5326,21 @@
         "base/popover",
         "base/tooltip"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
         {
-          "route": "/menubar",
-          "page": "Menubar & hover card"
+          "route": "/hover-card",
+          "page": "Hover card"
         }
       ],
       "recipes": [
         {
           "id": "hover-card",
           "title": "HoverCard",
-          "route": "/menubar",
-          "page": "Menubar & hover card"
+          "route": "/hover-card",
+          "page": "Hover card"
         }
       ]
     },
@@ -5673,6 +5455,7 @@
         "base/text-inputs",
         "base/forms"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/buttons",
@@ -5743,7 +5526,7 @@
           "publicImport": "themelia-ui/base/item",
           "cssImport": "themelia-ui/base/item.css",
           "apiDoc": "components/base--item.md#item",
-          "description": "Item — a row.\n\nNo size prop: rows come from the same factor chain as everything else, so a list cannot\ncontain two rows at different heights. A denser list is a scope with a smaller\n`--density-scale`.",
+          "description": "Item — a row. No size prop: row height follows `--density-scale`, so use a denser\nscope for a denser list.",
           "guidanceSource": "component",
           "chooseWhen": "An identity row with a title, description, media and actions.",
           "avoidWhen": "A definition list of facts or an editable field.",
@@ -5884,6 +5667,7 @@
         "base/table",
         "base/cards"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/display",
@@ -5952,6 +5736,7 @@
         "base/typography",
         "base/display"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/typography"
@@ -5980,38 +5765,10 @@
       "cssImport": "themelia-ui/base/menubar.css",
       "publicSymbols": [
         "Menubar",
-        "MenubarCheckboxItem",
-        "MenubarContent",
-        "MenubarGroup",
-        "MenubarItem",
-        "MenubarLabel",
-        "MenubarMenu",
-        "MenubarPortal",
-        "MenubarRadioGroup",
-        "MenubarRadioItem",
-        "MenubarSeparator",
-        "MenubarShortcut",
-        "MenubarSub",
-        "MenubarSubContent",
-        "MenubarSubTrigger",
         "MenubarTrigger"
       ],
       "components": [
         "Menubar",
-        "MenubarCheckboxItem",
-        "MenubarContent",
-        "MenubarGroup",
-        "MenubarItem",
-        "MenubarLabel",
-        "MenubarMenu",
-        "MenubarPortal",
-        "MenubarRadioGroup",
-        "MenubarRadioItem",
-        "MenubarSeparator",
-        "MenubarShortcut",
-        "MenubarSub",
-        "MenubarSubContent",
-        "MenubarSubTrigger",
         "MenubarTrigger"
       ],
       "componentGuidance": [
@@ -6028,194 +5785,12 @@
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         },
-        {
-          "symbol": "MenubarCheckboxItem",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubarcheckboxitem",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarContent",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubarcontent",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarGroup",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubargroup",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarItem",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubaritem",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarLabel",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubarlabel",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarMenu",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubarmenu",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarPortal",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubarportal",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarRadioGroup",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubarradiogroup",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarRadioItem",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubarradioitem",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarSeparator",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubarseparator",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarShortcut",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubarshortcut",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarSub",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubarsub",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarSubContent",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubarsubcontent",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "MenubarSubTrigger",
-          "publicImport": "themelia-ui/base/menubar",
-          "cssImport": "themelia-ui/base/menubar.css",
-          "apiDoc": "components/base--menubar.md#menubarsubtrigger",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
-          "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
         {
           "symbol": "MenubarTrigger",
           "publicImport": "themelia-ui/base/menubar",
           "cssImport": "themelia-ui/base/menubar.css",
           "apiDoc": "components/base--menubar.md#menubartrigger",
-          "description": "",
+          "description": "One menu's word in the bar. Place it inside a `DropdownMenu`, beside its content.",
           "guidanceSource": "family",
           "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
           "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
@@ -6224,7 +5799,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Menubar & hover card (/menubar)",
+      "doc": "Menubar (/menubar)",
       "apiDoc": "components/base--menubar.md",
       "chooseWhen": "An application-style menu bar sits persistently across the top of a workspace.",
       "avoidWhen": "The menu hangs off a single button, or the bar is site navigation.",
@@ -6232,14 +5807,15 @@
         "base/dropdown-menu",
         "base/navigation-menu"
       ],
-      "optionalPeers": [],
-      "dependsOnFamilies": [
+      "composeWith": [
         "base/dropdown-menu"
       ],
+      "optionalPeers": [],
+      "dependsOnFamilies": [],
       "previews": [
         {
           "route": "/menubar",
-          "page": "Menubar & hover card"
+          "page": "Menubar"
         }
       ],
       "recipes": [
@@ -6247,7 +5823,7 @@
           "id": "menubar",
           "title": "Menubar",
           "route": "/menubar",
-          "page": "Menubar & hover card"
+          "page": "Menubar"
         }
       ]
     },
@@ -6434,6 +6010,7 @@
         "layout/navigation",
         "features/data-view"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/badge",
@@ -6549,7 +6126,7 @@
           "publicImport": "themelia-ui/base/navigation-menu",
           "cssImport": "themelia-ui/base/navigation-menu.css",
           "apiDoc": "components/base--navigation-menu.md#navigationmenu",
-          "description": "",
+          "description": "The bar, and the one panel every entry shares: each `NavigationMenuContent` is drawn into\nits viewport, so moving between entries resizes one panel.",
           "guidanceSource": "family",
           "chooseWhen": "Site navigation needs grouped panels of links under top-level triggers.",
           "avoidWhen": "The items are commands rather than destinations, or the shell owns the navigation.",
@@ -6562,7 +6139,7 @@
           "publicImport": "themelia-ui/base/navigation-menu",
           "cssImport": "themelia-ui/base/navigation-menu.css",
           "apiDoc": "components/base--navigation-menu.md#navigationmenucontent",
-          "description": "The panel, positioned once for the whole bar.\n\n`Viewport` is what makes moving between entries animate as one surface resizing rather\nthan one panel closing and another opening — which is the difference between a mega-menu\nand a row of dropdowns.",
+          "description": "One entry's panel content, drawn into the bar's shared panel while its entry is open.\nPlacement belongs to the panel, so it is set on `NavigationMenu`, not here.",
           "guidanceSource": "family",
           "chooseWhen": "Site navigation needs grouped panels of links under top-level triggers.",
           "avoidWhen": "The items are commands rather than destinations, or the shell owns the navigation.",
@@ -6575,7 +6152,7 @@
           "publicImport": "themelia-ui/base/navigation-menu",
           "cssImport": "themelia-ui/base/navigation-menu.css",
           "apiDoc": "components/base--navigation-menu.md#navigationmenuindicator",
-          "description": "The arrow that tracks the open entry.\n\nOptional and off by default: it is a pointer affordance on a bar most readers navigate\nby clicking, and one more moving part on a surface that already resizes between entries.",
+          "description": "The caret inside a trigger, turning over while its panel is open. Renders a chevron;\npass children for another glyph.",
           "guidanceSource": "family",
           "chooseWhen": "Site navigation needs grouped panels of links under top-level triggers.",
           "avoidWhen": "The items are commands rather than destinations, or the shell owns the navigation.",
@@ -6636,7 +6213,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Menubar & hover card (/menubar)",
+      "doc": "Navigation menu (/navigation-menu)",
       "apiDoc": "components/base--navigation-menu.md",
       "chooseWhen": "Site navigation needs grouped panels of links under top-level triggers.",
       "avoidWhen": "The items are commands rather than destinations, or the shell owns the navigation.",
@@ -6644,20 +6221,21 @@
         "base/menubar",
         "layout/navigation"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
         {
-          "route": "/menubar",
-          "page": "Menubar & hover card"
+          "route": "/navigation-menu",
+          "page": "Navigation menu"
         }
       ],
       "recipes": [
         {
           "id": "navigation-menu",
           "title": "Navigation menu",
-          "route": "/menubar",
-          "page": "Menubar & hover card"
+          "route": "/navigation-menu",
+          "page": "Navigation menu"
         }
       ]
     },
@@ -6690,29 +6268,30 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Menubar & hover card (/menubar)",
+      "doc": "One-time code input (/otp-input)",
       "apiDoc": "components/base--otp-input.md",
       "chooseWhen": "A one-time code is entered as separate character cells.",
       "avoidWhen": "The code is pasted as one string into an ordinary field.",
       "alternatives": [
         "base/text-inputs"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/display"
       ],
       "previews": [
         {
-          "route": "/menubar",
-          "page": "Menubar & hover card"
+          "route": "/otp-input",
+          "page": "One-time code input"
         }
       ],
       "recipes": [
         {
           "id": "otp-input",
           "title": "OtpInput",
-          "route": "/menubar",
-          "page": "Menubar & hover card"
+          "route": "/otp-input",
+          "page": "One-time code input"
         }
       ]
     },
@@ -6826,7 +6405,7 @@
           "publicImport": "themelia-ui/base/overlay",
           "cssImport": "themelia-ui/base/overlay.css",
           "apiDoc": "components/base--overlay.md#overlaydismissarea",
-          "description": "Wraps children so any button inside dismisses the overlay.\n\nThe verbose form — `<OverlayClose render={<Button/>}/>` per action — is\nstill available and is the right tool when only SOME footer actions should close. This\nexists because \"every button in this footer closes\" is the common case, and repeating\nthe wrapper per button is where the wiring gets forgotten.",
+          "description": "Wraps children so any button inside dismisses the overlay. When only some actions\nshould close, use `<OverlayClose render={<Button />} />` per action.",
           "guidanceSource": "family",
           "chooseWhen": "Building a new modal surface inside the kit that must share the dialog/sheet anatomy.",
           "avoidWhen": "You are consuming the kit — application modals come from features/overlays.",
@@ -6887,13 +6466,14 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Overlay (/overlay)",
+      "doc": "Overlay, dialog & sheet (/overlay)",
       "apiDoc": "components/base--overlay.md",
       "chooseWhen": "Building a new modal surface inside the kit that must share the dialog/sheet anatomy.",
       "avoidWhen": "You are consuming the kit — application modals come from features/overlays.",
       "alternatives": [
         "features/overlays"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/slot",
@@ -6903,39 +6483,75 @@
       "previews": [
         {
           "route": "/overlay",
-          "page": "Overlay"
-        }
-      ],
-      "recipes": [
+          "page": "Overlay, dialog & sheet"
+        }
+      ],
+      "recipes": [
+        {
+          "id": "overlay-placement",
+          "title": "placement",
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
+        },
+        {
+          "id": "modality",
+          "title": "modality",
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
+        },
+        {
+          "id": "overlay-dismissal",
+          "title": "dismissal",
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
+        },
+        {
+          "id": "overlay-controlled",
+          "title": "Controlled",
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
+        },
+        {
+          "id": "overlay-structure",
+          "title": "Header, body and footer",
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
+        },
         {
-          "id": "overlay-placement",
-          "title": "placement",
+          "id": "dialog-surface",
+          "title": "Bare surface",
           "route": "/overlay",
-          "page": "Overlay"
+          "page": "Overlay, dialog & sheet"
         },
         {
-          "id": "overlay-modality",
-          "title": "modality",
+          "id": "dialog-focus",
+          "title": "Where focus lands",
           "route": "/overlay",
-          "page": "Overlay"
+          "page": "Overlay, dialog & sheet"
         },
         {
-          "id": "overlay-shape",
-          "title": "size, length and inset",
+          "id": "dialog-popups",
+          "title": "Popups inside an overlay",
           "route": "/overlay",
-          "page": "Overlay"
+          "page": "Overlay, dialog & sheet"
         },
         {
-          "id": "overlay-dismissal",
-          "title": "dismissal",
+          "id": "overlay-rule",
+          "title": "Three presets, one surface",
           "route": "/overlay",
-          "page": "Overlay"
+          "page": "Overlay, dialog & sheet"
         },
         {
-          "id": "overlay-controlled",
-          "title": "Controlled",
+          "id": "alert-dialog",
+          "title": "Alert dialog",
           "route": "/overlay",
-          "page": "Overlay"
+          "page": "Overlay, dialog & sheet"
+        },
+        {
+          "id": "alert-dialog-rule",
+          "title": "An alert dialog cannot be dismissed by accident",
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
         }
       ]
     },
@@ -7080,6 +6696,7 @@
         "base/popover-menu",
         "features/overlays"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/slot",
@@ -7121,10 +6738,12 @@
       "cssImport": "themelia-ui/base/popover-menu.css",
       "publicSymbols": [
         "PopoverMenu",
+        "PopoverMenuPanel",
         "defaultPopoverMenuStrings"
       ],
       "components": [
-        "PopoverMenu"
+        "PopoverMenu",
+        "PopoverMenuPanel"
       ],
       "componentGuidance": [
         {
@@ -7132,7 +6751,20 @@
           "publicImport": "themelia-ui/base/popover-menu",
           "cssImport": "themelia-ui/base/popover-menu.css",
           "apiDoc": "components/base--popover-menu.md#popovermenu",
-          "description": "The recurring \"trigger → optional header → search → list\" picker: filter facets,\noperator selects, assignee menus.\n\nFor anything outside that shape, compose `Popover` and `Command` directly — this is a\nbounded convenience over them, not a replacement.",
+          "description": "A \"trigger → optional header → search → list\" picker: filter facets, operator selects,\nassignee menus. For other shapes compose `Popover` and `Command`; inside a surface\nsomething else owns, render `PopoverMenuPanel`.",
+          "guidanceSource": "family",
+          "chooseWhen": "A popover's content is a simple list of actions and does not need the full menu anatomy.",
+          "avoidWhen": "Items need submenus, checkboxes or radios, or the actions repeat across rows.",
+          "capabilities": [],
+          "alternatives": [],
+          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
+        },
+        {
+          "symbol": "PopoverMenuPanel",
+          "publicImport": "themelia-ui/base/popover-menu",
+          "cssImport": "themelia-ui/base/popover-menu.css",
+          "apiDoc": "components/base--popover-menu.md#popovermenupanel",
+          "description": "The body of a `PopoverMenu` (header, search, rows, footer) without the popover, for a\nsurface something else owns: one step of a two-step popup, a sheet on a phone.",
           "guidanceSource": "family",
           "chooseWhen": "A popover's content is a simple list of actions and does not need the full menu anatomy.",
           "avoidWhen": "Items need submenus, checkboxes or radios, or the actions repeat across rows.",
@@ -7149,8 +6781,10 @@
         "base/dropdown-menu",
         "base/action-menu"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
+        "base/buttons",
         "base/command",
         "base/popover",
         "base/typography"
@@ -7167,6 +6801,18 @@
           "title": "PopoverMenu",
           "route": "/popover-menu",
           "page": "Popover menu"
+        },
+        {
+          "id": "popover-menu-states",
+          "title": "Error and minimum search",
+          "route": "/popover-menu",
+          "page": "Popover menu"
+        },
+        {
+          "id": "popover-menu-panel",
+          "title": "PopoverMenuPanel",
+          "route": "/popover-menu",
+          "page": "Popover menu"
         }
       ]
     },
@@ -7206,6 +6852,7 @@
       "alternatives": [
         "base/copyable"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
@@ -7352,10 +6999,12 @@
         "features/schema-form",
         "base/forms"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/buttons",
         "base/choice-inputs",
+        "base/display",
         "base/forms",
         "base/structure",
         "base/text-inputs"
@@ -7451,7 +7100,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Menubar & hover card (/menubar)",
+      "doc": "Resizable panels (/resizable)",
       "apiDoc": "components/base--resizable.md",
       "chooseWhen": "The user sets the split between panes and the size should persist.",
       "avoidWhen": "The split is fixed by the layout, or the region is a page shell.",
@@ -7459,20 +7108,21 @@
         "layout/containers",
         "base/structure"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
         {
-          "route": "/menubar",
-          "page": "Menubar & hover card"
+          "route": "/resizable",
+          "page": "Resizable panels"
         }
       ],
       "recipes": [
         {
           "id": "resizable",
           "title": "Resizable",
-          "route": "/menubar",
-          "page": "Menubar & hover card"
+          "route": "/resizable",
+          "page": "Resizable panels"
         }
       ]
     },
@@ -7484,67 +7134,12 @@
       "publicImport": "themelia-ui/base/sheet",
       "cssImport": "themelia-ui/base/sheet.css",
       "publicSymbols": [
-        "Sheet",
-        "SheetBody",
-        "SheetClose",
-        "SheetContent",
-        "SheetDescription",
-        "SheetFooter",
-        "SheetHeader",
-        "SheetTitle",
-        "SheetTrigger"
+        "SheetContent"
       ],
       "components": [
-        "Sheet",
-        "SheetBody",
-        "SheetClose",
-        "SheetContent",
-        "SheetDescription",
-        "SheetFooter",
-        "SheetHeader",
-        "SheetTitle",
-        "SheetTrigger"
+        "SheetContent"
       ],
       "componentGuidance": [
-        {
-          "symbol": "Sheet",
-          "publicImport": "themelia-ui/base/sheet",
-          "cssImport": "themelia-ui/base/sheet.css",
-          "apiDoc": "components/base--sheet.md#sheet",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting the sheet anatomy, or inside base where features/overlays cannot be imported.",
-          "avoidWhen": "You are presenting an edge-anchored modal in an app.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "SheetBody",
-          "publicImport": "themelia-ui/base/sheet",
-          "cssImport": "themelia-ui/base/sheet.css",
-          "apiDoc": "components/base--sheet.md#sheetbody",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting the sheet anatomy, or inside base where features/overlays cannot be imported.",
-          "avoidWhen": "You are presenting an edge-anchored modal in an app.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "SheetClose",
-          "publicImport": "themelia-ui/base/sheet",
-          "cssImport": "themelia-ui/base/sheet.css",
-          "apiDoc": "components/base--sheet.md#sheetclose",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting the sheet anatomy, or inside base where features/overlays cannot be imported.",
-          "avoidWhen": "You are presenting an edge-anchored modal in an app.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
         {
           "symbol": "SheetContent",
           "publicImport": "themelia-ui/base/sheet",
@@ -7557,108 +7152,44 @@
           "capabilities": [],
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "SheetDescription",
-          "publicImport": "themelia-ui/base/sheet",
-          "cssImport": "themelia-ui/base/sheet.css",
-          "apiDoc": "components/base--sheet.md#sheetdescription",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting the sheet anatomy, or inside base where features/overlays cannot be imported.",
-          "avoidWhen": "You are presenting an edge-anchored modal in an app.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "SheetFooter",
-          "publicImport": "themelia-ui/base/sheet",
-          "cssImport": "themelia-ui/base/sheet.css",
-          "apiDoc": "components/base--sheet.md#sheetfooter",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting the sheet anatomy, or inside base where features/overlays cannot be imported.",
-          "avoidWhen": "You are presenting an edge-anchored modal in an app.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "SheetHeader",
-          "publicImport": "themelia-ui/base/sheet",
-          "cssImport": "themelia-ui/base/sheet.css",
-          "apiDoc": "components/base--sheet.md#sheetheader",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting the sheet anatomy, or inside base where features/overlays cannot be imported.",
-          "avoidWhen": "You are presenting an edge-anchored modal in an app.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "SheetTitle",
-          "publicImport": "themelia-ui/base/sheet",
-          "cssImport": "themelia-ui/base/sheet.css",
-          "apiDoc": "components/base--sheet.md#sheettitle",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting the sheet anatomy, or inside base where features/overlays cannot be imported.",
-          "avoidWhen": "You are presenting an edge-anchored modal in an app.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "SheetTrigger",
-          "publicImport": "themelia-ui/base/sheet",
-          "cssImport": "themelia-ui/base/sheet.css",
-          "apiDoc": "components/base--sheet.md#sheettrigger",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Documenting the sheet anatomy, or inside base where features/overlays cannot be imported.",
-          "avoidWhen": "You are presenting an edge-anchored modal in an app.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Sheet (/sheet)",
+      "doc": "Overlay, dialog & sheet (/overlay)",
       "apiDoc": "components/base--sheet.md",
       "chooseWhen": "Documenting the sheet anatomy, or inside base where features/overlays cannot be imported.",
       "avoidWhen": "You are presenting an edge-anchored modal in an app.",
       "alternatives": [
         "features/overlays"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/overlay"
       ],
       "previews": [
         {
-          "route": "/sheet",
-          "page": "Sheet"
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
         }
       ],
       "recipes": [
         {
-          "id": "sheet",
-          "title": "Sheet",
-          "route": "/sheet",
-          "page": "Sheet"
+          "id": "modality",
+          "title": "modality",
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
+        },
+        {
+          "id": "alert-dialog-rule",
+          "title": "An alert dialog cannot be dismissed by accident",
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
         },
         {
           "id": "sheet-shape",
           "title": "Size, length, and inset",
-          "route": "/sheet",
-          "page": "Sheet"
-        },
-        {
-          "id": "modality",
-          "title": "Modality",
-          "route": "/sheet",
-          "page": "Sheet"
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
         }
       ]
     },
@@ -7847,7 +7378,7 @@
           "publicImport": "themelia-ui/base/sidebar",
           "cssImport": "themelia-ui/base/sidebar.css",
           "apiDoc": "components/base--sidebar.md#sidebarinset",
-          "description": "The page beside the panel. Renders `<main>`, so it is the document's main landmark.\n\n`render` is how it stops being one. A page may hold exactly one main landmark, and a shell\nembedded in a host page — a documentation example, a widget inside someone else's layout —\nwould otherwise nest a second inside the first. The host says so:\n\n```tsx\n<SidebarInset render={<div />}>…</SidebarInset>\n```\n\n`<main>` stays the default, because a shell that IS the page is the ordinary case and it\nshould not have to ask for the correct element.",
+          "description": "The page beside the panel. Renders `<main>`; a shell embedded in a host page that already\nhas one should pass `render={<div />}`.",
           "guidanceSource": "family",
           "chooseWhen": "Composing a collapsible sidebar from its parts, including the mobile presentation.",
           "avoidWhen": "You want the assembled application sidebar with logo, user and workspace slots.",
@@ -7990,7 +7521,7 @@
           "publicImport": "themelia-ui/base/sidebar",
           "cssImport": "themelia-ui/base/sidebar.css",
           "apiDoc": "components/base--sidebar.md#sidebarrail",
-          "description": "The strip on the panel's edge. Deliberately not a tab stop: it duplicates the trigger,\nand a second stop for the same action is noise for a keyboard user.",
+          "description": "The strip on the panel's edge. Not a tab stop: it duplicates the trigger.",
           "guidanceSource": "family",
           "chooseWhen": "Composing a collapsible sidebar from its parts, including the mobile presentation.",
           "avoidWhen": "You want the assembled application sidebar with logo, user and workspace slots.",
@@ -8029,7 +7560,7 @@
           "publicImport": "themelia-ui/base/sidebar",
           "cssImport": "themelia-ui/base/sidebar.css",
           "apiDoc": "components/base--sidebar.md#useoptionalsidebar",
-          "description": "The context, or `null` outside a provider.\n\nFor the parts a shell renders whether or not it HAS a sidebar — a header used above a\nplain page still wants its breadcrumbs, and throwing there takes the page down over a\ntoggle that simply has nothing to toggle.",
+          "description": "The context, or `null` outside a provider — for shell parts that render with or without\na sidebar (a header above a plain page).",
           "guidanceSource": "family",
           "chooseWhen": "Composing a collapsible sidebar from its parts, including the mobile presentation.",
           "avoidWhen": "You want the assembled application sidebar with logo, user and workspace slots.",
@@ -8059,13 +7590,16 @@
         "layout/sidebar",
         "layout/workspace"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/buttons",
         "base/display",
+        "base/overlay",
         "base/sheet",
         "base/skeleton",
         "base/text-inputs",
+        "base/tooltip",
         "base/typography"
       ],
       "previews": [
@@ -8191,7 +7725,7 @@
           "publicImport": "themelia-ui/base/skeleton",
           "cssImport": "themelia-ui/base/skeleton.css",
           "apiDoc": "components/base--skeleton.md#twocolumnpageskeleton",
-          "description": "A main column and a sidebar — the shape of most detail pages.",
+          "description": "A detail page: a title over the record's panel, beside its owner and facts.",
           "guidanceSource": "family",
           "chooseWhen": "A placeholder should hold the eventual layout's shape while data loads.",
           "avoidWhen": "The wait is indeterminate and unstructured, or the region failed.",
@@ -8208,8 +7742,11 @@
         "base/spinner",
         "base/feedback"
       ],
+      "composeWith": [],
       "optionalPeers": [],
-      "dependsOnFamilies": [],
+      "dependsOnFamilies": [
+        "base/display"
+      ],
       "previews": [
         {
           "route": "/skeleton",
@@ -8266,6 +7803,7 @@
       "alternatives": [
         "base/buttons"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
@@ -8319,6 +7857,7 @@
         "base/skeleton",
         "base/feedback"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
@@ -8456,7 +7995,7 @@
           "composition": "Use shared gap and inset props; do not pin local pixel spacing."
         }
       ],
-      "doc": "Stack & Grid (/structure)",
+      "doc": "Stack & grid (/structure)",
       "apiDoc": "components/base--structure.md",
       "chooseWhen": "Passive siblings need consistent spacing, a grid, or a stack — with no semantics of their own.",
       "avoidWhen": "The children form a titled page region, or the arrangement carries meaning.",
@@ -8464,12 +8003,13 @@
         "layout/containers",
         "base/item"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
         {
           "route": "/structure",
-          "page": "Stack & Grid"
+          "page": "Stack & grid"
         }
       ],
       "recipes": [
@@ -8477,37 +8017,37 @@
           "id": "stack",
           "title": "Stack",
           "route": "/structure",
-          "page": "Stack & Grid"
+          "page": "Stack & grid"
         },
         {
           "id": "responsive-props",
           "title": "Responsive props",
           "route": "/structure",
-          "page": "Stack & Grid"
+          "page": "Stack & grid"
         },
         {
           "id": "grid",
           "title": "Grid",
           "route": "/structure",
-          "page": "Stack & Grid"
+          "page": "Stack & grid"
         },
         {
           "id": "adaptivegrid",
           "title": "AdaptiveGrid",
           "route": "/structure",
-          "page": "Stack & Grid"
+          "page": "Stack & grid"
         },
         {
           "id": "split",
           "title": "Split",
           "route": "/structure",
-          "page": "Stack & Grid"
+          "page": "Stack & grid"
         },
         {
           "id": "bleed",
           "title": "Bleed",
           "route": "/structure",
-          "page": "Stack & Grid"
+          "page": "Stack & grid"
         }
       ]
     },
@@ -8527,7 +8067,8 @@
         "TableFooter",
         "TableHead",
         "TableHeader",
-        "TableRow"
+        "TableRow",
+        "defaultTableStrings"
       ],
       "components": [
         "Table",
@@ -8598,7 +8139,7 @@
           "publicImport": "themelia-ui/base/table",
           "cssImport": "themelia-ui/base/table.css",
           "apiDoc": "components/base--table.md#tableempty",
-          "description": "The \"no rows\" row.\n\nA table that renders an empty `<tbody>` looks broken rather than empty — the header\nhangs over nothing and the reader cannot tell a filter that matched nothing from a\nrequest that failed.",
+          "description": "The \"no rows\" row, spanning every column.",
           "guidanceSource": "family",
           "chooseWhen": "Writing table markup directly, with rows you control and no sorting or selection.",
           "avoidWhen": "The table needs columns, sorting, selection or a toolbar.",
@@ -8667,6 +8208,7 @@
         "features/table",
         "features/data-view"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/typography"
@@ -8727,6 +8269,7 @@
         "Textarea",
         "defaultInputStrings",
         "defaultPasswordInputStrings",
+        "defaultSearchInputStrings",
         "slugify",
         "useFieldValue"
       ],
@@ -8843,7 +8386,7 @@
           "publicImport": "themelia-ui/base/text-inputs",
           "cssImport": "themelia-ui/base/text-inputs.css",
           "apiDoc": "components/base--text-inputs.md#usefieldvalue",
-          "description": "The value bookkeeping every text control repeats: controlled-versus-not, a generated\nid, the character count, and the limit.\n\nA hook rather than four copies, because getting the controlled/uncontrolled branch\nsubtly different between Input, Textarea, and SearchInput is precisely how two fields\nin one form end up behaving differently under a form library.",
+          "description": "Value bookkeeping shared by the text controls (Input, Textarea): controlled or not, a\ngenerated id, the character count and the limit — one branch, so fields agree.",
           "guidanceSource": "family",
           "chooseWhen": "Free text is typed — plain, multiline, password, search or slug.",
           "avoidWhen": "The value is numeric with a unit, or picked from a set.",
@@ -8860,6 +8403,7 @@
         "base/forms-numeric",
         "base/choice-inputs"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
@@ -8867,14 +8411,6 @@
           "route": "/input",
           "page": "Input"
         },
-        {
-          "route": "/password-input",
-          "page": "Password input"
-        },
-        {
-          "route": "/search-input",
-          "page": "Search input"
-        },
         {
           "route": "/slug-field",
           "page": "Slug field"
@@ -8903,18 +8439,6 @@
           "route": "/input",
           "page": "Input"
         },
-        {
-          "id": "password",
-          "title": "Password input",
-          "route": "/password-input",
-          "page": "Password input"
-        },
-        {
-          "id": "search",
-          "title": "Search input",
-          "route": "/search-input",
-          "page": "Search input"
-        },
         {
           "id": "slug-field",
           "title": "SlugField",
@@ -8937,12 +8461,28 @@
       "publicImport": "themelia-ui/base/timeline",
       "cssImport": "themelia-ui/base/timeline.css",
       "publicSymbols": [
-        "Timeline"
+        "Stepper",
+        "Timeline",
+        "defaultStepperStrings"
       ],
       "components": [
+        "Stepper",
         "Timeline"
       ],
       "componentGuidance": [
+        {
+          "symbol": "Stepper",
+          "publicImport": "themelia-ui/base/timeline",
+          "cssImport": "themelia-ui/base/timeline.css",
+          "apiDoc": "components/base--timeline.md#stepper",
+          "description": "",
+          "guidanceSource": "family",
+          "chooseWhen": "Composing a generic vertical sequence of dated entries.",
+          "avoidWhen": "The sequence is a changelog, milestones or a step tracker.",
+          "capabilities": [],
+          "alternatives": [],
+          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
+        },
         {
           "symbol": "Timeline",
           "publicImport": "themelia-ui/base/timeline",
@@ -8965,8 +8505,10 @@
         "patterns/timelines",
         "features/activities"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
+        "base/display",
         "base/typography"
       ],
       "previews": [
@@ -8993,6 +8535,18 @@
           "title": "Entries that carry more than a line",
           "route": "/timeline",
           "page": "Timeline"
+        },
+        {
+          "id": "timeline-props",
+          "title": "Props",
+          "route": "/timeline",
+          "page": "Timeline"
+        },
+        {
+          "id": "stepper-pressable",
+          "title": "Going back a step",
+          "route": "/timeline",
+          "page": "Timeline"
         }
       ]
     },
@@ -9019,7 +8573,7 @@
           "publicImport": "themelia-ui/base/toaster",
           "cssImport": "themelia-ui/base/toaster.css",
           "apiDoc": "components/base--toaster.md#toaster",
-          "description": "Mount once, near the application root.\n\nThe store lives at module scope so `toast()` works from anywhere; this component is\nonly the view. That split is what lets a catch block in a route loader raise a toast\nwithout a hook, a context, or a ref passed down through the tree.",
+          "description": "Mount once, near the application root. The store lives at module scope so `toast()` works\nfrom anywhere; this component is only the view.",
           "guidanceSource": "family",
           "chooseWhen": "A message is transient, non-blocking, and reports the outcome of an action.",
           "avoidWhen": "The message belongs to a region, or the user must act on it.",
@@ -9036,6 +8590,7 @@
         "base/feedback",
         "features/overlays"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
@@ -9074,13 +8629,11 @@
       "cssImport": "themelia-ui/base/toggle.css",
       "publicSymbols": [
         "Toggle",
-        "ToggleGroup",
-        "ToggleGroupItem"
+        "ToggleGroup"
       ],
       "components": [
         "Toggle",
-        "ToggleGroup",
-        "ToggleGroupItem"
+        "ToggleGroup"
       ],
       "componentGuidance": [
         {
@@ -9101,20 +8654,7 @@
           "publicImport": "themelia-ui/base/toggle",
           "cssImport": "themelia-ui/base/toggle.css",
           "apiDoc": "components/base--toggle.md#togglegroup",
-          "description": "A set of toggles that share a value.\n\n`multiple` on the primitive decides whether it behaves as a radio group (one at a\ntime — a view mode) or a checkbox set (several — text styles). Both are common enough\nthat neither is a sensible default to hide.",
-          "guidanceSource": "family",
-          "chooseWhen": "A control holds a pressed state, alone or as one of a mutually exclusive group.",
-          "avoidWhen": "The state is a form value that submits, or the control performs an action.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "ToggleGroupItem",
-          "publicImport": "themelia-ui/base/toggle",
-          "cssImport": "themelia-ui/base/toggle.css",
-          "apiDoc": "components/base--toggle.md#togglegroupitem",
-          "description": "",
+          "description": "A set of `Toggle`s (each given a `value`) sharing one value. `multiple` makes it a\ncheckbox set rather than one-at-a-time.",
           "guidanceSource": "family",
           "chooseWhen": "A control holds a pressed state, alone or as one of a mutually exclusive group.",
           "avoidWhen": "The state is a form value that submits, or the control performs an action.",
@@ -9131,6 +8671,7 @@
         "base/choice-inputs",
         "base/buttons"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
@@ -9266,6 +8807,7 @@
         "base/toggle",
         "base/navigation"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/buttons"
@@ -9289,7 +8831,7 @@
         },
         {
           "id": "why-two-levels",
-          "title": "Why a factor and not a size prop",
+          "title": "Why two factors, and no third",
           "route": "/scale",
           "page": "Scale & density"
         },
@@ -9382,6 +8924,7 @@
         "base/popover",
         "base/hover-card"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
@@ -9506,6 +9049,7 @@
       "alternatives": [
         "primitives"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
@@ -9732,7 +9276,7 @@
           "publicImport": "themelia-ui/base/upload",
           "cssImport": "themelia-ui/base/upload.css",
           "apiDoc": "components/base--upload.md#usefiledroptarget",
-          "description": "Drag state that survives descendants.\n\n`dragleave` fires every time the pointer crosses into a CHILD of the drop target, so\nthe naive \"set false on leave\" flickers the whole time the pointer is over the zone's\nown icon and text. Counting enter against leave and only clearing at zero is what makes\nit stable.",
+          "description": "Drag state that survives descendants: `dragleave` fires on entering a child, so enters\nand leaves are counted and dragging clears only at zero.",
           "guidanceSource": "family",
           "chooseWhen": "The user contributes files — dropzone, avatar, image, or a tray with progress.",
           "avoidWhen": "Existing assets are being browsed and picked rather than added.",
@@ -9741,32 +9285,25 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Image upload (/image-upload)",
+      "doc": "File upload (/file-upload)",
       "apiDoc": "components/base--upload.md",
       "chooseWhen": "The user contributes files — dropzone, avatar, image, or a tray with progress.",
       "avoidWhen": "Existing assets are being browsed and picked rather than added.",
       "alternatives": [
         "features/media-library"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/badge",
         "base/buttons",
-        "base/feedback",
-        "base/structure"
+        "base/display",
+        "base/feedback"
       ],
       "previews": [
         {
           "route": "/file-upload",
           "page": "File upload"
-        },
-        {
-          "route": "/image-upload",
-          "page": "Image upload"
-        },
-        {
-          "route": "/upload-queue",
-          "page": "Upload queue"
         }
       ],
       "recipes": [
@@ -9777,28 +9314,28 @@
           "page": "File upload"
         },
         {
-          "id": "media-upload",
-          "title": "AvatarUpload and ImageUpload",
-          "route": "/image-upload",
-          "page": "Image upload"
+          "id": "upload-rule",
+          "title": "Validation is not the dialog's job",
+          "route": "/file-upload",
+          "page": "File upload"
         },
         {
           "id": "upload-queue",
-          "title": "Upload progress",
-          "route": "/upload-queue",
-          "page": "Upload queue"
+          "title": "Files on their way: upload progress",
+          "route": "/file-upload",
+          "page": "File upload"
         },
         {
           "id": "upload-tray",
           "title": "UploadTray",
-          "route": "/upload-queue",
-          "page": "Upload queue"
+          "route": "/file-upload",
+          "page": "File upload"
         },
         {
           "id": "media-gallery",
           "title": "MediaGallery",
-          "route": "/upload-queue",
-          "page": "Upload queue"
+          "route": "/file-upload",
+          "page": "File upload"
         }
       ]
     },
@@ -9920,10 +9457,12 @@
         "base/text-inputs",
         "base/forms-numeric"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/choice-inputs",
         "base/date-pickers",
+        "base/display",
         "base/structure",
         "base/text-inputs",
         "base/typography"
@@ -10216,7 +9755,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Actions (/actions)",
+      "doc": "Action definitions (/actions)",
       "apiDoc": "components/features--actions.md",
       "chooseWhen": "The same operation runs from a table row, a card menu and the command palette, and all three must get one confirm, one loading state and one error path.",
       "avoidWhen": "One surface owns the action and nothing else invokes it — a registry then adds indirection for a single caller.",
@@ -10224,18 +9763,15 @@
         "features/overlays",
         "base/action-menu"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
-        "base/alert-dialog",
-        "base/buttons",
-        "base/dialog",
-        "base/feedback",
-        "base/sheet"
+        "features/overlays"
       ],
       "previews": [
         {
           "route": "/actions",
-          "page": "Actions"
+          "page": "Action definitions"
         }
       ],
       "recipes": [
@@ -10243,7 +9779,7 @@
           "id": "actions",
           "title": "One definition, many surfaces",
           "route": "/actions",
-          "page": "Actions"
+          "page": "Action definitions"
         }
       ]
     },
@@ -10336,7 +9872,7 @@
           "publicImport": "themelia-ui/features/activities",
           "cssImport": "themelia-ui/features/activities.css",
           "apiDoc": "components/features--activities.md#activityemptystate",
-          "description": "The feed with nothing in it, as a named export.\n\nA feed is a stack of rows against a marker rail, so a bare sentence where the rows were\nreads as a rail that failed to render. The soft glyph gives the empty state the same\nleft-hand mark the rows have, which is what makes it read as \"nothing happened here\"\nrather than as a broken list.",
+          "description": "The empty feed, with a glyph in the marker column so it reads as empty rather than broken.",
           "guidanceSource": "family",
           "chooseWhen": "An audit or activity log renders actor, change and time, grouped by day.",
           "avoidWhen": "The entries are milestones or a changelog, or the thread is a discussion.",
@@ -10481,6 +10017,7 @@
         "patterns/timelines",
         "features/comments"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "@tiptap/core",
         "@tiptap/pm",
@@ -10703,7 +10240,7 @@
           "publicImport": "themelia-ui/features/ai-chat",
           "cssImport": "themelia-ui/features/ai-chat.css",
           "apiDoc": "components/features--ai-chat.md#aichatmessage",
-          "description": "── Why text goes in a bubble and everything else does not ───────────────────────────\nA tool call, an artifact, a code block already carry their own border and header. Put\ninside a bubble they are a box in a box, and the bubble's padding pushes them off the\ntranscript's grid. Text has no chrome, so it is the only part that belongs in one.\n\n── Why the DECLARED order is kept ───────────────────────────────────────────────────\nSorting the parts into \"text\" and \"everything else\" is one line shorter and wrong: a\nturn is normally reasoning, then a tool call, then the answer, and hoisting the answer\nabove the work reverses the one sequence a reader is following. So the parts split\naround the first run of text — what came before it stays before, what came after stays\nafter — and only that run gets a bubble.",
+          "description": "One turn. Only the first run of text parts goes in a bubble (other parts bring their own\nchrome); parts before and after it keep their declared order around the bubble.",
           "guidanceSource": "family",
           "chooseWhen": "A conversational surface streams assistant messages, tool calls, artifacts and attachments.",
           "avoidWhen": "The thread is human discussion on a record, or the input is a single prompt field.",
@@ -10876,6 +10413,7 @@
         "features/comments",
         "features/rich-text-editor"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/badge",
@@ -10989,7 +10527,7 @@
           "publicImport": "themelia-ui/features/async-preview",
           "cssImport": "themelia-ui/features/async-preview.css",
           "apiDoc": "components/features--async-preview.md#asyncpreviewbody",
-          "description": "The success case, with the data non-null.\n\nThe narrowing is the point: a caller writing `data.name` inside this does not need a\nguard, because the component has already decided there is a record.",
+          "description": "The success case, with the data narrowed to non-null.",
           "guidanceSource": "family",
           "chooseWhen": "A trigger fetches its content when it opens, and needs loading, empty and error states.",
           "avoidWhen": "The content is already loaded, or the surface is modal.",
@@ -11136,6 +10674,7 @@
         "base/popover",
         "features/overlays"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/badge",
@@ -11179,8 +10718,11 @@
         "DEFAULT_MIN_SEARCH_LENGTH",
         "HighlightedText",
         "ResourceCombobox",
+        "SuggestionsCombobox",
         "defaultAsyncComboboxStrings",
-        "useComboboxCore"
+        "defaultSuggestionsStrings",
+        "useComboboxCore",
+        "useSuggestions"
       ],
       "components": [
         "AsyncCombobox",
@@ -11188,7 +10730,9 @@
         "ComboboxDropdown",
         "HighlightedText",
         "ResourceCombobox",
-        "useComboboxCore"
+        "SuggestionsCombobox",
+        "useComboboxCore",
+        "useSuggestions"
       ],
       "componentGuidance": [
         {
@@ -11198,8 +10742,8 @@
           "apiDoc": "components/features--combobox.md#asynccombobox",
           "description": "",
           "guidanceSource": "family",
-          "chooseWhen": "Options arrive from a fetch, or the field selects application resources.",
-          "avoidWhen": "The options are a small in-memory list, or you are composing a bespoke anatomy.",
+          "chooseWhen": "Options arrive from a fetch, the field selects application resources, or it proposes completions as the user types.",
+          "avoidWhen": "The options are a small in-memory list, you are composing a bespoke anatomy, or a trigger character inserts entities into text.",
           "capabilities": [],
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
@@ -11211,8 +10755,8 @@
           "apiDoc": "components/features--combobox.md#asyncmulticombobox",
           "description": "",
           "guidanceSource": "family",
-          "chooseWhen": "Options arrive from a fetch, or the field selects application resources.",
-          "avoidWhen": "The options are a small in-memory list, or you are composing a bespoke anatomy.",
+          "chooseWhen": "Options arrive from a fetch, the field selects application resources, or it proposes completions as the user types.",
+          "avoidWhen": "The options are a small in-memory list, you are composing a bespoke anatomy, or a trigger character inserts entities into text.",
           "capabilities": [],
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
@@ -11224,8 +10768,8 @@
           "apiDoc": "components/features--combobox.md#comboboxdropdown",
           "description": "",
           "guidanceSource": "family",
-          "chooseWhen": "Options arrive from a fetch, or the field selects application resources.",
-          "avoidWhen": "The options are a small in-memory list, or you are composing a bespoke anatomy.",
+          "chooseWhen": "Options arrive from a fetch, the field selects application resources, or it proposes completions as the user types.",
+          "avoidWhen": "The options are a small in-memory list, you are composing a bespoke anatomy, or a trigger character inserts entities into text.",
           "capabilities": [],
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
@@ -11237,8 +10781,8 @@
           "apiDoc": "components/features--combobox.md#highlightedtext",
           "description": "",
           "guidanceSource": "family",
-          "chooseWhen": "Options arrive from a fetch, or the field selects application resources.",
-          "avoidWhen": "The options are a small in-memory list, or you are composing a bespoke anatomy.",
+          "chooseWhen": "Options arrive from a fetch, the field selects application resources, or it proposes completions as the user types.",
+          "avoidWhen": "The options are a small in-memory list, you are composing a bespoke anatomy, or a trigger character inserts entities into text.",
           "capabilities": [],
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
@@ -11250,8 +10794,21 @@
           "apiDoc": "components/features--combobox.md#resourcecombobox",
           "description": "",
           "guidanceSource": "family",
-          "chooseWhen": "Options arrive from a fetch, or the field selects application resources.",
-          "avoidWhen": "The options are a small in-memory list, or you are composing a bespoke anatomy.",
+          "chooseWhen": "Options arrive from a fetch, the field selects application resources, or it proposes completions as the user types.",
+          "avoidWhen": "The options are a small in-memory list, you are composing a bespoke anatomy, or a trigger character inserts entities into text.",
+          "capabilities": [],
+          "alternatives": [],
+          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
+        },
+        {
+          "symbol": "SuggestionsCombobox",
+          "publicImport": "themelia-ui/features/combobox",
+          "cssImport": "themelia-ui/features/combobox.css",
+          "apiDoc": "components/features--combobox.md#suggestionscombobox",
+          "description": "",
+          "guidanceSource": "family",
+          "chooseWhen": "Options arrive from a fetch, the field selects application resources, or it proposes completions as the user types.",
+          "avoidWhen": "The options are a small in-memory list, you are composing a bespoke anatomy, or a trigger character inserts entities into text.",
           "capabilities": [],
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
@@ -11263,21 +10820,36 @@
           "apiDoc": "components/features--combobox.md#usecomboboxcore",
           "description": "",
           "guidanceSource": "family",
-          "chooseWhen": "Options arrive from a fetch, or the field selects application resources.",
-          "avoidWhen": "The options are a small in-memory list, or you are composing a bespoke anatomy.",
+          "chooseWhen": "Options arrive from a fetch, the field selects application resources, or it proposes completions as the user types.",
+          "avoidWhen": "The options are a small in-memory list, you are composing a bespoke anatomy, or a trigger character inserts entities into text.",
+          "capabilities": [],
+          "alternatives": [],
+          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
+        },
+        {
+          "symbol": "useSuggestions",
+          "publicImport": "themelia-ui/features/combobox",
+          "cssImport": "themelia-ui/features/combobox.css",
+          "apiDoc": "components/features--combobox.md#usesuggestions",
+          "description": "",
+          "guidanceSource": "family",
+          "chooseWhen": "Options arrive from a fetch, the field selects application resources, or it proposes completions as the user types.",
+          "avoidWhen": "The options are a small in-memory list, you are composing a bespoke anatomy, or a trigger character inserts entities into text.",
           "capabilities": [],
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Async combobox (/async-combobox)",
+      "doc": "Combobox (/combobox)",
       "apiDoc": "components/features--combobox.md",
-      "chooseWhen": "Options arrive from a fetch, or the field selects application resources.",
-      "avoidWhen": "The options are a small in-memory list, or you are composing a bespoke anatomy.",
+      "chooseWhen": "Options arrive from a fetch, the field selects application resources, or it proposes completions as the user types.",
+      "avoidWhen": "The options are a small in-memory list, you are composing a bespoke anatomy, or a trigger character inserts entities into text.",
       "alternatives": [
         "base/combobox",
-        "base/choice-inputs"
+        "base/choice-inputs",
+        "features/mentions"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/buttons",
@@ -11289,40 +10861,52 @@
       ],
       "previews": [
         {
-          "route": "/async-combobox",
-          "page": "Async combobox"
-        }
-      ],
-      "recipes": [
+          "route": "/combobox",
+          "page": "Combobox"
+        }
+      ],
+      "recipes": [
+        {
+          "id": "combobox-picker",
+          "title": "A picker that fetches",
+          "route": "/combobox",
+          "page": "Combobox"
+        },
+        {
+          "id": "suggestions",
+          "title": "SuggestionsCombobox",
+          "route": "/combobox",
+          "page": "Combobox"
+        },
+        {
+          "id": "resource-combobox",
+          "title": "When the fetch fails",
+          "route": "/combobox",
+          "page": "Combobox"
+        },
         {
           "id": "async-combobox",
-          "title": "AsyncCombobox",
-          "route": "/async-combobox",
-          "page": "Async combobox"
+          "title": "Results you already hold",
+          "route": "/combobox",
+          "page": "Combobox"
         },
         {
           "id": "async-multi-combobox",
-          "title": "AsyncMultiCombobox",
-          "route": "/async-combobox",
-          "page": "Async combobox"
+          "title": "Several at once",
+          "route": "/combobox",
+          "page": "Combobox"
         },
         {
           "id": "apply-button",
-          "title": "applyButton",
-          "route": "/async-combobox",
-          "page": "Async combobox"
+          "title": "Apply before it counts",
+          "route": "/combobox",
+          "page": "Combobox"
         },
         {
           "id": "creatable",
-          "title": "creatable",
-          "route": "/async-combobox",
-          "page": "Async combobox"
-        },
-        {
-          "id": "resource-combobox",
-          "title": "ResourceCombobox",
-          "route": "/async-combobox",
-          "page": "Async combobox"
+          "title": "Create what is missing",
+          "route": "/combobox",
+          "page": "Combobox"
         }
       ]
     },
@@ -11474,6 +11058,7 @@
         "features/activities",
         "features/ai-chat"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "@tiptap/core",
         "@tiptap/pm",
@@ -11651,7 +11236,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Data view (/data-view)",
+      "doc": "Data view & data table (/data-view)",
       "apiDoc": "components/features--data-view.md",
       "chooseWhen": "One dataset is presented through switchable views with saved tabs, a toolbar and pagination.",
       "avoidWhen": "There is one table and no view switching, or you need the table body alone.",
@@ -11659,6 +11244,7 @@
         "features/table",
         "base/table"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "@tanstack/react-table"
       ],
@@ -11674,7 +11260,7 @@
       "previews": [
         {
           "route": "/data-view",
-          "page": "Data view"
+          "page": "Data view & data table"
         }
       ],
       "recipes": [
@@ -11682,13 +11268,13 @@
           "id": "data-view",
           "title": "An index",
           "route": "/data-view",
-          "page": "Data view"
+          "page": "Data view & data table"
         },
         {
           "id": "data-view-states",
           "title": "Pending results and recovery",
           "route": "/data-view",
-          "page": "Data view"
+          "page": "Data view & data table"
         }
       ]
     },
@@ -11838,6 +11424,7 @@
         "base/date-pickers",
         "patterns/timelines"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/action-menu",
@@ -12214,7 +11801,7 @@
           "publicImport": "themelia-ui/features/filters",
           "cssImport": "themelia-ui/features/filters.css",
           "apiDoc": "components/features--filters.md#usefiltercache",
-          "description": "The filter cache in scope, or `null`.\n\n`useAsyncOptions` is public and may be called outside a provider; it makes its own\nshort-lived cache in that case rather than reaching for a global one.",
+          "description": "The filter cache in scope, or `null` (then `useAsyncOptions` makes its own short-lived one).",
           "guidanceSource": "family",
           "chooseWhen": "Users build predicates over fields, with operators, editors and pills.",
           "avoidWhen": "Filtering is one search box, or the choices are fixed tabs.",
@@ -12257,6 +11844,7 @@
         "features/data-view",
         "base/text-inputs"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/badge",
@@ -12268,7 +11856,9 @@
         "base/feedback",
         "base/item",
         "base/navigation",
+        "base/overlay",
         "base/popover",
+        "base/popover-menu",
         "base/sheet",
         "base/spinner",
         "base/text-inputs",
@@ -12447,10 +12037,12 @@
         "base/command",
         "features/combobox"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/avatar",
         "base/badge",
+        "base/buttons",
         "base/display",
         "base/feedback",
         "base/item",
@@ -12667,6 +12259,7 @@
         "features/data-view",
         "features/table"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "@dnd-kit/core",
         "@dnd-kit/sortable",
@@ -12815,7 +12408,7 @@
           "publicImport": "themelia-ui/features/map",
           "cssImport": "themelia-ui/features/map.css",
           "apiDoc": "components/features--map.md#mapcontrolcontainer",
-          "description": "The frame every control sits in.\n\nIts one job beyond placement is suppressing Leaflet's own handlers: without it a click\non a button also pans the map, and a scroll over a menu also zooms it.",
+          "description": "The frame every control sits in. Beyond placement it suppresses Leaflet's handlers, so\na click on a button does not pan the map and a scroll over a menu does not zoom it.",
           "guidanceSource": "family",
           "chooseWhen": "Geographic data is displayed or drawn, including markers, shapes and draw controls.",
           "avoidWhen": "The location is a single coordinate value to read or type.",
@@ -13166,7 +12759,7 @@
           "publicImport": "themelia-ui/features/map",
           "cssImport": "themelia-ui/features/map.css",
           "apiDoc": "components/features--map.md#useleaflet",
-          "description": "Leaflet itself, plus draw and fullscreen, once they have loaded.\n\n`null` until then, and every caller checks — a control that assumed `L` was there\nrendered before the module arrived and threw on the first mount.",
+          "description": "Leaflet plus draw and fullscreen once loaded; `null` until then, so callers must check.",
           "guidanceSource": "family",
           "chooseWhen": "Geographic data is displayed or drawn, including markers, shapes and draw controls.",
           "avoidWhen": "The location is a single coordinate value to read or type.",
@@ -13196,6 +12789,7 @@
         "primitives",
         "base/forms-numeric"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "leaflet",
         "leaflet-draw",
@@ -13334,7 +12928,7 @@
           "publicImport": "themelia-ui/features/media-library",
           "cssImport": "themelia-ui/features/media-library.css",
           "apiDoc": "components/features--media-library.md#medialibrarydialog",
-          "description": "The same library, in a modal — for picking assets from elsewhere on a page.",
+          "description": "The same library in a modal, for picking assets from elsewhere on a page.",
           "guidanceSource": "family",
           "chooseWhen": "Existing assets are browsed, previewed, searched and picked.",
           "avoidWhen": "The user is contributing new files, or one image is being replaced.",
@@ -13347,7 +12941,7 @@
           "publicImport": "themelia-ui/features/media-library",
           "cssImport": "themelia-ui/features/media-library.css",
           "apiDoc": "components/features--media-library.md#medialibraryemptystate",
-          "description": "The browser's own empty state, as a named export.\n\nBordered and inset rather than bare, because it stands in for a GRID: an unframed\nparagraph where a wall of tiles was reads as the page having failed to load rather than\nas a search that matched nothing.",
+          "description": "The browser's empty state: bordered and inset, since it stands in for a grid.",
           "guidanceSource": "family",
           "chooseWhen": "Existing assets are browsed, previewed, searched and picked.",
           "avoidWhen": "The user is contributing new files, or one image is being replaced.",
@@ -13386,7 +12980,7 @@
           "publicImport": "themelia-ui/features/media-library",
           "cssImport": "themelia-ui/features/media-library.css",
           "apiDoc": "components/features--media-library.md#medialibraryfootersummary",
-          "description": "What the footer says, which depends on the tab it is under: a selection count while\nbrowsing, a staged-file tally while uploading.\n\nA live region, because it is the only thing on screen that changes when a tile is\npicked with the keyboard — the tick appears inside a grid the reader may not be looking\nat, and the count is the announcement.",
+          "description": "The footer line: a selection count while browsing, a staged-file tally while uploading.\nA live region, so keyboard picks inside the grid are announced.",
           "guidanceSource": "family",
           "chooseWhen": "Existing assets are browsed, previewed, searched and picked.",
           "avoidWhen": "The user is contributing new files, or one image is being replaced.",
@@ -13477,7 +13071,7 @@
           "publicImport": "themelia-ui/features/media-library",
           "cssImport": "themelia-ui/features/media-library.css",
           "apiDoc": "components/features--media-library.md#mediapreview",
-          "description": "The asset's picture, or a stand-in.\n\nA broken `src` falls back to the type glyph rather than the browser's own broken-image\nmark, which is the one visual in a grid of assets nobody can interpret. The `tint`\ngives an asset without a preview something of its own to be recognised by.",
+          "description": "The asset's picture, or a stand-in: a broken `src` falls back to the type glyph, and\n`tint` gives an asset without a preview a recognisable colour.",
           "guidanceSource": "family",
           "chooseWhen": "Existing assets are browsed, previewed, searched and picked.",
           "avoidWhen": "The user is contributing new files, or one image is being replaced.",
@@ -13519,6 +13113,7 @@
       "alternatives": [
         "base/upload"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/badge",
@@ -13719,9 +13314,9 @@
       "chooseWhen": "Typing a trigger character suggests entities and inserts them as chips.",
       "avoidWhen": "The field selects one resource up front, or the suggestions are commands.",
       "alternatives": [
-        "features/combobox",
-        "features/suggestions"
+        "features/combobox"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/avatar",
@@ -13854,7 +13449,7 @@
           "publicImport": "themelia-ui/features/overlays",
           "cssImport": "themelia-ui/features/overlays.css",
           "apiDoc": "components/features--overlays.md#useoverlayvisibilitygroup",
-          "description": "Several overlays keyed by name, from one hook.\n\nA screen with an edit dialog, a delete confirm, and an export drawer otherwise carries\nthree `useState`s and three pairs of handlers — and the three are exactly the thing that\nhas to coordinate when `closeOthersOnOpen` matters.",
+          "description": "Several overlays keyed by name from one hook, coordinated by `closeOthersOnOpen`.",
           "guidanceSource": "family",
           "chooseWhen": "Any application modal — dialog, sheet or confirmation — including its async confirm lifecycle.",
           "avoidWhen": "The panel is non-modal and anchored to its trigger.",
@@ -13871,6 +13466,7 @@
         "base/popover",
         "features/async-preview"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/alert-dialog",
@@ -13878,6 +13474,7 @@
         "base/dialog",
         "base/display",
         "base/feedback",
+        "base/overlay",
         "base/sheet"
       ],
       "previews": [
@@ -14067,7 +13664,7 @@
           "publicImport": "themelia-ui/features/products",
           "cssImport": "themelia-ui/features/products.css",
           "apiDoc": "components/features--products.md#productoptionactionmenu",
-          "description": "The per-option overflow menu, as its own export.\n\nThe summary card renders one already; this exists for the screen that lays out options\nitself — a table, a rail, a drag-ordered list — and wants the same three verbs under\nthe same labels rather than reinventing them beside it.",
+          "description": "The per-option overflow menu, exported for screens that lay out options themselves and\nwant the same verbs and labels as the summary card.",
           "guidanceSource": "family",
           "chooseWhen": "Presenting catalogue records — options, readiness, policies and quotes — in the admin profile.",
           "avoidWhen": "The record is an order, invoice or shipment.",
@@ -14223,7 +13820,7 @@
           "publicImport": "themelia-ui/features/products",
           "cssImport": "themelia-ui/features/products.css",
           "apiDoc": "components/features--products.md#productthumbnail",
-          "description": "A variant's picture, or the space where one would go.\n\n── Why the empty state is dashed and not a grey square ──────────────────────────────\nA filled grey square reads as an image that failed to load. A dashed outline reads as a\nslot — something that is meant to hold a picture and does not yet — which is the true\nstatement for a variant nobody has photographed.\n\n── Why it is only a button when it can do something ─────────────────────────────────\nWithout `onSelect` there is nothing behind the plus, so there is no plus: the slot is\ninert, and the glyph is the muted one that says \"empty\" rather than the accent one that\nsays \"press me\".",
+          "description": "A variant's picture, or a dashed slot where one would go (a grey square reads as a\nfailed image). Only a button with `onSelect`; otherwise the slot is inert and muted.",
           "guidanceSource": "family",
           "chooseWhen": "Presenting catalogue records — options, readiness, policies and quotes — in the admin profile.",
           "avoidWhen": "The record is an order, invoice or shipment.",
@@ -14262,7 +13859,7 @@
           "publicImport": "themelia-ui/features/products",
           "cssImport": "themelia-ui/features/products.css",
           "apiDoc": "components/features--products.md#productvariantcell",
-          "description": "A label/value pair that survives losing its table.\n\nOn a wide screen the column heading names the value and repeating it in every cell is\nnoise — so it is there for a screen reader and nothing else. Narrow, the headings are\ngone and the same word is the only thing telling a reader what \"€1,850\" is, so it\nbecomes visible and the pair reads as a row.",
+          "description": "A label/value pair whose label is visually hidden while a column heading names the value,\nand shown once the table collapses at narrow widths.",
           "guidanceSource": "family",
           "chooseWhen": "Presenting catalogue records — options, readiness, policies and quotes — in the admin profile.",
           "avoidWhen": "The record is an order, invoice or shipment.",
@@ -14314,7 +13911,7 @@
           "publicImport": "themelia-ui/features/products",
           "cssImport": "themelia-ui/features/products.css",
           "apiDoc": "components/features--products.md#productvariantsmanager",
-          "description": "The options and the variants they generate — in ONE surface, not two beside each other.\n\n── Why one card ─────────────────────────────────────────────────────────────────────\nAdding a value to an option changes the variant list. Two bordered cards say these are\ntwo things a reader may consider separately; one card with the options at the top, the\ngrouping control in the middle and the grid underneath says what is actually true — the\nlower half is the consequence of the upper half, and the reader is looking at one\neditor, not at two components that happen to share a page.\n\n── Why the grouping control lives here ──────────────────────────────────────────────\nWhat to group by is a question about the options, and the options are right above it.\nAs a prop it belonged to whatever assembled the page; as a control between the two\nhalves it belongs to the thing it changes.",
+          "description": "The options and the variants they generate, in one card: the variant grid is a\nconsequence of the options above it. The grouping control sits between the two halves\nbecause it is a question about the options that changes the grid.",
           "guidanceSource": "family",
           "chooseWhen": "Presenting catalogue records — options, readiness, policies and quotes — in the admin profile.",
           "avoidWhen": "The record is an order, invoice or shipment.",
@@ -14344,6 +13941,7 @@
         "admin/patterns/commerce",
         "features/resource"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "@tanstack/react-table"
       ],
@@ -14554,6 +14152,7 @@
         "layout/page",
         "features/data-view"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/avatar",
@@ -14622,7 +14221,7 @@
           "publicImport": "themelia-ui/features/resource-assignment",
           "cssImport": "themelia-ui/features/resource-assignment.css",
           "apiDoc": "components/features--resource-assignment.md#defaultdialogcontent",
-          "description": "The dialog body, when the consumer has not replaced it: just the picker.",
+          "description": "The dialog body when not replaced: just the picker.",
           "guidanceSource": "family",
           "chooseWhen": "A resource is shared with or assigned to principals through a dialog.",
           "avoidWhen": "You are displaying permissions rather than changing them.",
@@ -14635,7 +14234,7 @@
           "publicImport": "themelia-ui/features/resource-assignment",
           "cssImport": "themelia-ui/features/resource-assignment.css",
           "apiDoc": "components/features--resource-assignment.md#defaultdialogsummary",
-          "description": "What is about to be committed, restated above the confirm.\n\nA picker can scroll, and the chosen row is often out of sight by the time the reader\nreaches the button. Falling back to a `label` field is a guess, but a cheap and usually\nright one; `getSelectionLabel` is the way to be sure.",
+          "description": "Restates the pending choice above the confirm, since the chosen row may have scrolled\nout of sight. Falls back to a `label` field; pass `getSelectionLabel` to be exact.",
           "guidanceSource": "family",
           "chooseWhen": "A resource is shared with or assigned to principals through a dialog.",
           "avoidWhen": "You are displaying permissions rather than changing them.",
@@ -14678,6 +14277,7 @@
         "admin/patterns/access",
         "features/overlays"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/action-menu",
@@ -14740,7 +14340,7 @@
           "publicImport": "themelia-ui/features/rich-text-editor",
           "cssImport": "themelia-ui/features/rich-text-editor.css",
           "apiDoc": "components/features--rich-text-editor.md#editorcounts",
-          "description": "Character and word counts.\n\nOver the limit the character count turns error-toned rather than the editor refusing\ninput. A composer that stops accepting characters mid-word loses whatever the writer\nwas in the middle of; saying \"you are over\" and letting the form decide does not.",
+          "description": "Character and word counts. Over the limit the count turns error-toned; input is never\nrefused, so the form decides.",
           "guidanceSource": "family",
           "chooseWhen": "Users author formatted content with a toolbar and counts.",
           "avoidWhen": "The input is plain multiline text, or the content is only displayed.",
@@ -14783,6 +14383,7 @@
         "base/text-inputs",
         "base/typography"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "@tiptap/core",
         "@tiptap/pm",
@@ -14840,6 +14441,7 @@
       "alternatives": [
         "features/rich-text-editor"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "@tiptap/core",
         "@tiptap/pm",
@@ -14935,6 +14537,7 @@
         "base/forms",
         "forms-rhf"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/badge",
@@ -14970,78 +14573,6 @@
         }
       ]
     },
-    {
-      "family": "features/suggestions",
-      "layer": "features",
-      "profile": "general",
-      "status": "stable",
-      "publicImport": "themelia-ui/features/suggestions",
-      "cssImport": "themelia-ui/features/suggestions.css",
-      "publicSymbols": [
-        "SuggestionsCombobox",
-        "defaultSuggestionsStrings",
-        "useSuggestions"
-      ],
-      "components": [
-        "SuggestionsCombobox",
-        "useSuggestions"
-      ],
-      "componentGuidance": [
-        {
-          "symbol": "SuggestionsCombobox",
-          "publicImport": "themelia-ui/features/suggestions",
-          "cssImport": "themelia-ui/features/suggestions.css",
-          "apiDoc": "components/features--suggestions.md#suggestionscombobox",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "A field proposes completions as the user types, without owning the value set.",
-          "avoidWhen": "The user must choose from a closed list, or the trigger is a character.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "useSuggestions",
-          "publicImport": "themelia-ui/features/suggestions",
-          "cssImport": "themelia-ui/features/suggestions.css",
-          "apiDoc": "components/features--suggestions.md#usesuggestions",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "A field proposes completions as the user types, without owning the value set.",
-          "avoidWhen": "The user must choose from a closed list, or the trigger is a character.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        }
-      ],
-      "doc": "Async combobox (/async-combobox)",
-      "apiDoc": "components/features--suggestions.md",
-      "chooseWhen": "A field proposes completions as the user types, without owning the value set.",
-      "avoidWhen": "The user must choose from a closed list, or the trigger is a character.",
-      "alternatives": [
-        "features/combobox",
-        "features/mentions"
-      ],
-      "optionalPeers": [],
-      "dependsOnFamilies": [
-        "base/feedback",
-        "features/combobox"
-      ],
-      "previews": [
-        {
-          "route": "/async-combobox",
-          "page": "Async combobox"
-        }
-      ],
-      "recipes": [
-        {
-          "id": "suggestions",
-          "title": "SuggestionsCombobox",
-          "route": "/async-combobox",
-          "page": "Async combobox"
-        }
-      ]
-    },
     {
       "family": "features/sync",
       "layer": "features",
@@ -15078,6 +14609,7 @@
       "alternatives": [
         "base/date-pickers"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "react-hook-form"
       ],
@@ -15176,7 +14708,7 @@
           "publicImport": "themelia-ui/features/table",
           "cssImport": "themelia-ui/features/table.css",
           "apiDoc": "components/features--table.md#cellstack",
-          "description": "Several values in one cell, stacked.\n\nThe common two-line cell — a name over an email, a title over a reference — without a\nbespoke component per column.",
+          "description": "Several values stacked in one cell (a name over an email) without a bespoke component.",
           "guidanceSource": "family",
           "chooseWhen": "A table needs columns, sorting, selection, cell renderers and a toolbar.",
           "avoidWhen": "The dataset needs several saved views, or you are writing table markup directly.",
@@ -15363,7 +14895,7 @@
           "publicImport": "themelia-ui/features/table",
           "cssImport": "themelia-ui/features/table.css",
           "apiDoc": "components/features--table.md#statusclustercell",
-          "description": "Several chips in one cell — a row that is both overdue AND partially paid.",
+          "description": "Several chips in one cell, e.g. overdue and partially paid.",
           "guidanceSource": "family",
           "chooseWhen": "A table needs columns, sorting, selection, cell renderers and a toolbar.",
           "avoidWhen": "The dataset needs several saved views, or you are writing table markup directly.",
@@ -15411,7 +14943,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Data table (/data-table)",
+      "doc": "Data view & data table (/data-view)",
       "apiDoc": "components/features--table.md",
       "chooseWhen": "A table needs columns, sorting, selection, cell renderers and a toolbar.",
       "avoidWhen": "The dataset needs several saved views, or you are writing table markup directly.",
@@ -15419,6 +14951,7 @@
         "features/data-view",
         "base/table"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "@tanstack/react-table"
       ],
@@ -15439,28 +14972,28 @@
       ],
       "previews": [
         {
-          "route": "/data-table",
-          "page": "Data table"
+          "route": "/data-view",
+          "page": "Data view & data table"
         }
       ],
       "recipes": [
         {
-          "id": "table",
-          "title": "An index table",
-          "route": "/data-table",
-          "page": "Data table"
+          "id": "data-view-rules",
+          "title": "What the data view decides",
+          "route": "/data-view",
+          "page": "Data view & data table"
         },
         {
           "id": "table-cells",
           "title": "Cells",
-          "route": "/data-table",
-          "page": "Data table"
+          "route": "/data-view",
+          "page": "Data view & data table"
         },
         {
           "id": "table-selection",
           "title": "Acting on a selection",
-          "route": "/data-table",
-          "page": "Data table"
+          "route": "/data-view",
+          "page": "Data view & data table"
         }
       ]
     },
@@ -15568,19 +15101,20 @@
       "alternatives": [
         "ui-provider"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/accordion",
         "base/badge",
         "base/buttons",
         "base/choice-inputs",
-        "base/dialog",
         "base/display",
         "base/feedback",
         "base/forms",
         "base/forms-numeric",
         "base/item",
         "base/navigation",
+        "base/overlay",
         "base/structure",
         "base/text-inputs",
         "base/typography",
@@ -15636,7 +15170,7 @@
           "publicImport": "themelia-ui/forms",
           "cssImport": null,
           "apiDoc": "components/forms.md#usestateformcontrol",
-          "description": "A `FormControl` over plain React state — the zero-dependency default.\n\nEnough for the common case of a handful of fields, and it means the headless contract\nis usable without installing a form library at all.",
+          "description": "A `FormControl` over plain React state — the zero-dependency default.",
           "guidanceSource": "family",
           "chooseWhen": "Binding a field to state you already own, without a form library.",
           "avoidWhen": "React Hook Form owns the state, or the fields come from a schema.",
@@ -15653,6 +15187,7 @@
         "forms-rhf",
         "features/schema-form"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
@@ -15696,6 +15231,7 @@
         "forms",
         "features/schema-form"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "react-hook-form"
       ],
@@ -15770,6 +15306,7 @@
         "base/sidebar",
         "layout/workspace"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/sidebar"
@@ -15860,7 +15397,7 @@
           "publicImport": "themelia-ui/layout/auth",
           "cssImport": "themelia-ui/layout/auth.css",
           "apiDoc": "components/layout--auth.md#authsplitpanel",
-          "description": "Form beside a panel, for a caller composing the two halves itself.\n\n`AuthShell variant=\"split\"` is the same arrangement with the shell's own card inside it;\nthis one takes both halves as given, for a page whose form is not an AuthCard at all.",
+          "description": "Form beside a panel, for a caller composing both halves itself. `AuthShell\nvariant=\"split\"` is the same arrangement with the shell's own card.",
           "guidanceSource": "family",
           "chooseWhen": "Sign-in, registration and recovery pages share a centred card and optional split panel.",
           "avoidWhen": "The page sits inside the authenticated shell.",
@@ -15877,8 +15414,10 @@
         "layout/page",
         "layout/containers"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
+        "base/cards",
         "base/typography"
       ],
       "previews": [
@@ -15995,6 +15534,7 @@
         "base/structure",
         "layout/workspace"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
@@ -16081,7 +15621,7 @@
           "publicImport": "themelia-ui/layout/header",
           "cssImport": "themelia-ui/layout/header.css",
           "apiDoc": "components/layout--header.md#headerglobalsearchtrigger",
-          "description": "The same trigger, reporting into a controlled `open`.\n\nTwo components rather than one with an optional prop, because the palette this opens is\nusually controlled from elsewhere entirely — and a trigger that sometimes owns the state\nand sometimes does not is the shape that produces two palettes on one page.",
+          "description": "The same trigger, reporting into a controlled `open`. A separate component so a trigger\nnever half-owns the palette's state.",
           "guidanceSource": "family",
           "chooseWhen": "The application header carries breadcrumbs, search, notifications and the user menu.",
           "avoidWhen": "The heading names a page rather than the application.",
@@ -16163,6 +15703,7 @@
         "layout/page",
         "base/navigation"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/action-menu",
@@ -16280,10 +15821,12 @@
         "base/navigation",
         "layout/sidebar"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/badge",
         "base/item",
+        "base/timeline",
         "base/typography"
       ],
       "previews": [
@@ -16304,6 +15847,12 @@
           "title": "SectionNav",
           "route": "/side-nav",
           "page": "Side nav & section nav"
+        },
+        {
+          "id": "settings-shell-rule",
+          "title": "One component, named for its shape",
+          "route": "/side-nav",
+          "page": "Side nav & section nav"
         }
       ]
     },
@@ -16381,6 +15930,7 @@
         "features/resource",
         "layout/containers"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/action-menu",
@@ -16420,7 +15970,7 @@
         },
         {
           "id": "why-two-levels",
-          "title": "Why a factor and not a size prop",
+          "title": "Why two factors, and no third",
           "route": "/scale",
           "page": "Scale & density"
         }
@@ -16434,12 +15984,10 @@
       "publicImport": "themelia-ui/layout/settings",
       "cssImport": "themelia-ui/layout/settings.css",
       "publicSymbols": [
-        "AsideNavShell",
-        "SettingsShell"
+        "AsideNavShell"
       ],
       "components": [
-        "AsideNavShell",
-        "SettingsShell"
+        "AsideNavShell"
       ],
       "componentGuidance": [
         {
@@ -16454,22 +16002,9 @@
           "capabilities": [],
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
-        },
-        {
-          "symbol": "SettingsShell",
-          "publicImport": "themelia-ui/layout/settings",
-          "cssImport": "themelia-ui/layout/settings.css",
-          "apiDoc": "components/layout--settings.md#settingsshell",
-          "description": "",
-          "guidanceSource": "family",
-          "chooseWhen": "Settings pages share an aside navigation beside their content.",
-          "avoidWhen": "The navigation is the application sidebar, or the sections are tabs.",
-          "capabilities": [],
-          "alternatives": [],
-          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Settings shell (/settings-shell)",
+      "doc": "Side nav & section nav (/side-nav)",
       "apiDoc": "components/layout--settings.md",
       "chooseWhen": "Settings pages share an aside navigation beside their content.",
       "avoidWhen": "The navigation is the application sidebar, or the sections are tabs.",
@@ -16477,6 +16012,7 @@
         "layout/navigation",
         "base/navigation"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/navigation",
@@ -16485,16 +16021,16 @@
       ],
       "previews": [
         {
-          "route": "/settings-shell",
-          "page": "Settings shell"
+          "route": "/side-nav",
+          "page": "Side nav & section nav"
         }
       ],
       "recipes": [
         {
           "id": "settings-shell",
-          "title": "SettingsShell",
-          "route": "/settings-shell",
-          "page": "Settings shell"
+          "title": "The rail beside its content: AsideNavShell",
+          "route": "/side-nav",
+          "page": "Side nav & section nav"
         }
       ]
     },
@@ -16543,7 +16079,7 @@
           "publicImport": "themelia-ui/layout/sidebar",
           "cssImport": "themelia-ui/layout/sidebar.css",
           "apiDoc": "components/layout--sidebar.md#sidebaricon",
-          "description": "Resolves an icon that may be a NAME.\n\nExported because a caller supplying `renderItem` still wants the same resolution — a\nrow rendered by hand should not need its own copy of \"string means look it up in the\niconMap, component means render it, node means use it\".",
+          "description": "Resolves an icon that may be a name (looked up in `iconMap`), a component or a node.\nExported for `renderItem` callers.",
           "guidanceSource": "family",
           "chooseWhen": "The assembled application sidebar with logo, workspace switcher and user footer.",
           "avoidWhen": "You are composing a bespoke sidebar from its parts.",
@@ -16599,6 +16135,7 @@
         "base/sidebar",
         "layout/workspace"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/action-menu",
@@ -16707,12 +16244,14 @@
         "layout/sidebar",
         "layout/auth"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/badge",
         "base/display",
         "base/feedback",
         "base/item",
+        "base/navigation",
         "base/typography"
       ],
       "previews": [
@@ -16927,6 +16466,7 @@
       "alternatives": [
         "base/chart"
       ],
+      "composeWith": [],
       "optionalPeers": [
         "recharts"
       ],
@@ -16938,6 +16478,7 @@
         "base/display",
         "base/feedback",
         "base/skeleton",
+        "base/tooltip",
         "base/typography"
       ],
       "previews": [
@@ -17039,6 +16580,7 @@
       "alternatives": [
         "patterns/timelines"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/accordion",
@@ -17128,7 +16670,7 @@
           "publicImport": "themelia-ui/patterns/timelines",
           "cssImport": "themelia-ui/patterns/timelines.css",
           "apiDoc": "components/patterns--timelines.md#stepsbar",
-          "description": "The horizontal form: numbered dots with connectors between them.\n\nIt scrolls rather than clipping. Five steps with real labels overrun a panel long before\nthey overrun a page, and a clipped final label reads as a missing step.",
+          "description": "The horizontal form: numbered markers with connectors, over base's `Stepper`. Scrolls\nrather than clipping.",
           "guidanceSource": "family",
           "chooseWhen": "A sequence is presented as changelog entries, milestones, or a step tracker.",
           "avoidWhen": "The entries are a system audit log, or the sequence is a calendar.",
@@ -17145,10 +16687,10 @@
         "features/activities",
         "base/timeline"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/badge",
-        "base/display",
         "base/feedback",
         "base/timeline",
         "base/typography"
@@ -17671,7 +17213,7 @@
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         }
       ],
-      "doc": "Address (/primitive-address)",
+      "doc": "Addresses & places (/primitive-address)",
       "apiDoc": "components/primitives.md",
       "chooseWhen": "Displaying or formatting exactly one read-only value — currency/money, date, email, file size, initials — with no interaction.",
       "avoidWhen": "The value is editable, or the text is prose in a typographic role.",
@@ -17679,6 +17221,7 @@
         "base/typography",
         "base/text-inputs"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [
         "base/typography"
@@ -17686,43 +17229,15 @@
       "previews": [
         {
           "route": "/primitive-address",
-          "page": "Address"
-        },
-        {
-          "route": "/primitive-coordinates",
-          "page": "Coordinates"
+          "page": "Addresses & places"
         },
         {
-          "route": "/primitive-date-range",
-          "page": "Date range"
+          "route": "/primitive-contact",
+          "page": "Contact details"
         },
         {
           "route": "/primitive-date",
-          "page": "Date and time"
-        },
-        {
-          "route": "/primitive-dimensions",
-          "page": "Dimensions"
-        },
-        {
-          "route": "/primitive-duration",
-          "page": "Duration"
-        },
-        {
-          "route": "/primitive-email",
-          "page": "Email"
-        },
-        {
-          "route": "/primitive-file-size",
-          "page": "File size"
-        },
-        {
-          "route": "/primitive-initials",
-          "page": "Initials"
-        },
-        {
-          "route": "/primitive-inline-list",
-          "page": "Inline list"
+          "page": "Dates & times"
         },
         {
           "route": "/primitive-money",
@@ -17730,39 +17245,19 @@
         },
         {
           "route": "/primitive-name",
-          "page": "Name"
+          "page": "Names & initials"
         },
         {
           "route": "/primitive-number",
-          "page": "Number and percent"
-        },
-        {
-          "route": "/primitive-phone",
-          "page": "Phone"
+          "page": "Numbers, ranges & ratios"
         },
         {
           "route": "/primitive-quantity",
-          "page": "Quantity and measure"
-        },
-        {
-          "route": "/primitive-range",
-          "page": "Range"
-        },
-        {
-          "route": "/primitive-ratio",
-          "page": "Ratio and rating"
-        },
-        {
-          "route": "/primitive-relative-time",
-          "page": "Relative time"
-        },
-        {
-          "route": "/primitive-url",
-          "page": "URL"
+          "page": "Measures & file sizes"
         },
         {
           "route": "/primitive-value",
-          "page": "Value"
+          "page": "Values & lists"
         }
       ],
       "recipes": [
@@ -17770,91 +17265,79 @@
           "id": "address",
           "title": "Ordered by country",
           "route": "/primitive-address",
-          "page": "Address"
+          "page": "Addresses & places"
         },
         {
           "id": "address-inline",
           "title": "Inline, for a cell",
           "route": "/primitive-address",
-          "page": "Address"
+          "page": "Addresses & places"
         },
         {
           "id": "address-partial",
           "title": "Missing fields",
           "route": "/primitive-address",
-          "page": "Address"
+          "page": "Addresses & places"
         },
         {
           "id": "coordinates",
           "title": "Coordinates",
-          "route": "/primitive-coordinates",
-          "page": "Coordinates"
+          "route": "/primitive-address",
+          "page": "Addresses & places"
+        },
+        {
+          "id": "email",
+          "title": "Email",
+          "route": "/primitive-contact",
+          "page": "Contact details"
         },
         {
-          "id": "date-range",
-          "title": "DateRange",
-          "route": "/primitive-date-range",
-          "page": "Date range"
+          "id": "phone",
+          "title": "Phone",
+          "route": "/primitive-contact",
+          "page": "Contact details"
+        },
+        {
+          "id": "url",
+          "title": "URL",
+          "route": "/primitive-contact",
+          "page": "Contact details"
         },
         {
           "id": "date",
           "title": "Dates and times",
           "route": "/primitive-date",
-          "page": "Date and time"
+          "page": "Dates & times"
         },
         {
           "id": "date-locale",
           "title": "Localised names",
           "route": "/primitive-date",
-          "page": "Date and time"
-        },
-        {
-          "id": "dimensions",
-          "title": "Dimensions",
-          "route": "/primitive-dimensions",
-          "page": "Dimensions"
-        },
-        {
-          "id": "duration",
-          "title": "Duration",
-          "route": "/primitive-duration",
-          "page": "Duration"
-        },
-        {
-          "id": "email",
-          "title": "Email",
-          "route": "/primitive-email",
-          "page": "Email"
+          "page": "Dates & times"
         },
         {
-          "id": "file-size",
-          "title": "File size",
-          "route": "/primitive-file-size",
-          "page": "File size"
-        },
-        {
-          "id": "file-size-base",
-          "title": "Which megabyte",
-          "route": "/primitive-file-size",
-          "page": "File size"
+          "id": "date-rule",
+          "title": "date-fns, not hand-rolled Date",
+          "route": "/primitive-date",
+          "page": "Dates & times"
         },
         {
-          "id": "initials",
-          "title": "Initials",
-          "route": "/primitive-initials",
-          "page": "Initials"
+          "id": "relative-time",
+          "title": "RelativeTime",
+          "route": "/primitive-date",
+          "page": "Dates & times"
         },
         {
-          "id": "inline-list",
-          "title": "Inline list",
-          "route": "/primitive-inline-list",
-          "page": "Inline list"
+          "id": "relative-time-shape",
+          "title": "Suffix and precision",
+          "route": "/primitive-date",
+          "page": "Dates & times"
         },
         {
-          "id": "inline-list-locale",
-          "title": "The same list, three locales",
-          "route": "/primitive-inline-list",
-          "page": "Inline list"
+          "id": "relative-time-rule",
+          "title": "Pass the clock in",
+          "route": "/primitive-date",
+          "page": "Dates & times"
         },
         {
           "id": "money",
@@ -17890,73 +17373,85 @@
           "id": "name",
           "title": "Name",
           "route": "/primitive-name",
-          "page": "Name"
+          "page": "Names & initials"
+        },
+        {
+          "id": "initials",
+          "title": "Initials",
+          "route": "/primitive-name",
+          "page": "Names & initials"
         },
         {
           "id": "number",
           "title": "Number and percent",
           "route": "/primitive-number",
-          "page": "Number and percent"
+          "page": "Numbers, ranges & ratios"
         },
         {
-          "id": "phone",
-          "title": "Phone",
-          "route": "/primitive-phone",
-          "page": "Phone"
+          "id": "range",
+          "title": "Range",
+          "route": "/primitive-number",
+          "page": "Numbers, ranges & ratios"
+        },
+        {
+          "id": "ratio",
+          "title": "Ratio",
+          "route": "/primitive-number",
+          "page": "Numbers, ranges & ratios"
+        },
+        {
+          "id": "rating",
+          "title": "Rating",
+          "route": "/primitive-number",
+          "page": "Numbers, ranges & ratios"
         },
         {
           "id": "quantity",
           "title": "Quantity",
           "route": "/primitive-quantity",
-          "page": "Quantity and measure"
+          "page": "Measures & file sizes"
         },
         {
           "id": "measure",
           "title": "Measure",
           "route": "/primitive-quantity",
-          "page": "Quantity and measure"
-        },
-        {
-          "id": "range",
-          "title": "Range",
-          "route": "/primitive-range",
-          "page": "Range"
+          "page": "Measures & file sizes"
         },
         {
-          "id": "ratio",
-          "title": "Ratio",
-          "route": "/primitive-ratio",
-          "page": "Ratio and rating"
+          "id": "dimensions",
+          "title": "Dimensions",
+          "route": "/primitive-quantity",
+          "page": "Measures & file sizes"
         },
         {
-          "id": "rating",
-          "title": "Rating",
-          "route": "/primitive-ratio",
-          "page": "Ratio and rating"
+          "id": "file-size",
+          "title": "File size",
+          "route": "/primitive-quantity",
+          "page": "Measures & file sizes"
         },
         {
-          "id": "relative-time",
-          "title": "RelativeTime",
-          "route": "/primitive-relative-time",
-          "page": "Relative time"
+          "id": "file-size-base",
+          "title": "Which megabyte",
+          "route": "/primitive-quantity",
+          "page": "Measures & file sizes"
         },
         {
-          "id": "relative-time-shape",
-          "title": "Suffix and precision",
-          "route": "/primitive-relative-time",
-          "page": "Relative time"
+          "id": "value",
+          "title": "Value",
+          "route": "/primitive-value",
+          "page": "Values & lists"
         },
         {
-          "id": "url",
-          "title": "URL",
-          "route": "/primitive-url",
-          "page": "URL"
+          "id": "value-rule",
+          "title": "Absent is a state",
+          "route": "/primitive-value",
+          "page": "Values & lists"
         },
         {
-          "id": "value",
-          "title": "Value",
+          "id": "inline-list-locale",
+          "title": "The same list, three locales",
           "route": "/primitive-value",
-          "page": "Value"
+          "page": "Values & lists"
         }
       ]
     },
@@ -18015,6 +17510,7 @@
         "features/theme-tweaker",
         "ui-provider"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [],
@@ -18045,6 +17541,7 @@
         "useDensity",
         "useFormatting",
         "useMoneyConfig",
+        "useOverlayConfig",
         "useScale",
         "useTypographyConfig",
         "useUIConfig",
@@ -18064,6 +17561,7 @@
         "useDensity",
         "useFormatting",
         "useMoneyConfig",
+        "useOverlayConfig",
         "useScale",
         "useTypographyConfig",
         "useUIConfig",
@@ -18088,7 +17586,7 @@
           "publicImport": "themelia-ui/ui-provider",
           "cssImport": null,
           "apiDoc": "components/ui-provider.md#scope",
-          "description": "`<Scope>` — a token boundary without the config machinery.\n\nOverriding a factor requires a SCOPE BOUNDARY, not just any element. Derived tokens are\ndeclared at `:root, [data-ui-scope], [data-density], [data-theme], .light, .dark` (see\nstyles/SCOPES.md), so a plain `<div style={{ \"--density-scale\": 0.8 }}>` sets the\nvariable and nothing reads it — the measurements above it already resolved.\n\nThis renders `data-ui-scope`, which puts the element on that list and makes every\nderived token re-compute from whatever it overrides. Use `<UIProvider>` when the change\ninvolves JavaScript config too; use this when it is purely tokens.\n\n  <Scope vars={{ \"--density-scale\": 0.8 }}>\n    <Toolbar />\n  </Scope>",
+          "description": "`<Scope>` — a token boundary without the config machinery. Derived tokens re-compute\nonly at a scope boundary (styles/SCOPES.md), so a factor set on a plain `div` changes\nnothing; this renders `data-ui-scope`. Use `<UIProvider>` when JavaScript config changes too.\n\n  <Scope vars={{ \"--density-scale\": 0.8 }}>\n    <Toolbar />\n  </Scope>",
           "guidanceSource": "family",
           "chooseWhen": "Setting display defaults, theme, density and scale for the app or a subtree.",
           "avoidWhen": "The value is per-feature policy or domain data, which stays a prop.",
@@ -18127,7 +17625,7 @@
           "publicImport": "themelia-ui/ui-provider",
           "cssImport": null,
           "apiDoc": "components/ui-provider.md#uiportalhost",
-          "description": "Keeps popups inside this subtree, so they inherit the scope around them.\n\nA portal renders outside the scope's DOM subtree, and that subtree is what carries both\nthe custom properties and the `[data-density]` / `[data-theme]` attributes. So a menu\nopened inside a compact dark panel came out at the root's density and theme, and neither\ncomponent's source said why. The host puts the target back inside the scope.\n\n```tsx\n<UIScope config={{ density: \"compact\", colorScheme: \"dark\" }}>\n  <UIPortalHost>\n    <DropdownMenu>…</DropdownMenu>\n  </UIPortalHost>\n</UIScope>\n```\n\nOpt-in per region: with no host, every popup portals exactly where it always did.",
+          "description": "Keeps popups inside this subtree, so they inherit the scope's custom properties and\n`[data-density]` / `[data-theme]` attributes instead of the root's.\n\n```tsx\n<UIScope config={{ density: \"compact\", colorScheme: \"dark\" }}>\n  <UIPortalHost>\n    <DropdownMenu>…</DropdownMenu>\n  </UIPortalHost>\n</UIScope>\n```\n\nOpt-in per region; without a host, popups portal to the document as usual.",
           "guidanceSource": "family",
           "chooseWhen": "Setting display defaults, theme, density and scale for the app or a subtree.",
           "avoidWhen": "The value is per-feature policy or domain data, which stays a prop.",
@@ -18140,7 +17638,7 @@
           "publicImport": "themelia-ui/ui-provider",
           "cssImport": null,
           "apiDoc": "components/ui-provider.md#uiprovider",
-          "description": "`<UIProvider>` — the compatibility composition.\n\nIt was one component doing two jobs, and the two have different contracts. At the top of\nan application it owned the DOCUMENT, because `<body>` sits above anything it renders and\na page canvas that stays light while its contents go dark is not a theme. Nested, it owned\na REGION and had no business touching the document at all. Which of the two you got was\ninferred from whether a provider happened to be above you.\n\nThat inference is the part that could not be made safe. Two independent React roots each\nthink they are the top; the first to unmount deleted the attributes and took the other's\ntheme with it. And \"the root also dresses the document\" is a side effect on shared state\nthat nobody asked for and no prop could decline.\n\nSo the jobs are now `UIRoot` and `UIScope`, and this composes them with the behaviour it\nhas always had: at the top, a root that targets `documentElement`; nested, a scope.\nPrefer the two directly — a root that does not want the document simply does not ask for\nit, which was not previously expressible.",
+          "description": "`<UIProvider>` — composes `UIRoot` and `UIScope`: outermost, a root that themes\n`documentElement` plus a scope; nested, a scope only. Prefer `UIRoot` and `UIScope`\ndirectly, which let a root decline the document.",
           "guidanceSource": "family",
           "chooseWhen": "Setting display defaults, theme, density and scale for the app or a subtree.",
           "avoidWhen": "The value is per-feature policy or domain data, which stays a prop.",
@@ -18153,7 +17651,7 @@
           "publicImport": "themelia-ui/ui-provider",
           "cssImport": null,
           "apiDoc": "components/ui-provider.md#uiroot",
-          "description": "`<UIRoot>` — the application's configuration, once.\n\nIt renders NO element. The root's job is the resolved defaults and, when asked, the\ndocument's attributes; a box would put a layout node at the top of every application\nthat used one. Region scoping is `UIScope`, which does render.",
+          "description": "`<UIRoot>` — the application's configuration, once. Renders no element; region scoping\nis `UIScope`, which does.",
           "guidanceSource": "family",
           "chooseWhen": "Setting display defaults, theme, density and scale for the app or a subtree.",
           "avoidWhen": "The value is per-feature policy or domain data, which stays a prop.",
@@ -18166,7 +17664,7 @@
           "publicImport": "themelia-ui/ui-provider",
           "cssImport": null,
           "apiDoc": "components/ui-provider.md#uiscope",
-          "description": "`<UIScope>` — a region with its own tokens.\n\nNests freely: the cascade merges the custom properties, context merges the JavaScript\nhalf. It writes only its OWN overrides, because inherited values already cascade in, and\nit never touches the document — that is the root's job and only when asked.\n\n`render` decides the element. A scope forced to be a `div` is unusable in the places that\nmost want one: inside a `<table>`, a `<dl>`, a `<ul>`, or anywhere the surrounding markup\nhas an opinion. `<UIScope render={<aside />}>` is a real aside.",
+          "description": "`<UIScope>` — a region with its own tokens. Nests freely; writes only its own custom\nproperty overrides and never touches the document. `render` picks the element, e.g.\n`<UIScope render={<aside />}>`, for places a `div` is invalid.",
           "guidanceSource": "family",
           "chooseWhen": "Setting display defaults, theme, density and scale for the app or a subtree.",
           "avoidWhen": "The value is per-feature policy or domain data, which stays a prop.",
@@ -18192,7 +17690,7 @@
           "publicImport": "themelia-ui/ui-provider",
           "cssImport": null,
           "apiDoc": "components/ui-provider.md#usedefaults",
-          "description": "Per-component prop defaults for one family.\n\nThe component passes its OWN defaults; the scope's overrides merge on top. That keeps\nthe values next to the component instead of in a central table, makes the call\norder-independent, and lets an unused family tree-shake away — unlike the source kit,\nwhere every component's defaults sat in one core object.",
+          "description": "Per-component prop defaults for one family: the component passes its own defaults and\nthe scope's overrides merge on top, so defaults stay beside their component.",
           "guidanceSource": "family",
           "chooseWhen": "Setting display defaults, theme, density and scale for the app or a subtree.",
           "avoidWhen": "The value is per-feature policy or domain data, which stays a prop.",
@@ -18239,6 +17737,19 @@
           "alternatives": [],
           "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
         },
+        {
+          "symbol": "useOverlayConfig",
+          "publicImport": "themelia-ui/ui-provider",
+          "cssImport": null,
+          "apiDoc": "components/ui-provider.md#useoverlayconfig",
+          "description": "Overlay policy — whether menus render dark, and the modal scrim's blur.",
+          "guidanceSource": "family",
+          "chooseWhen": "Setting display defaults, theme, density and scale for the app or a subtree.",
+          "avoidWhen": "The value is per-feature policy or domain data, which stays a prop.",
+          "capabilities": [],
+          "alternatives": [],
+          "composition": "Start with props; inspect the public declarations for supported parts and callbacks."
+        },
         {
           "symbol": "useScale",
           "publicImport": "themelia-ui/ui-provider",
@@ -18283,7 +17794,7 @@
           "publicImport": "themelia-ui/ui-provider",
           "cssImport": null,
           "apiDoc": "components/ui-provider.md#useuiportalcontainer",
-          "description": "The container a portal in this subtree should use.\n\nPrecedence, most specific first: what the caller passed to the component, then the\nnearest `UIPortalHost`, then `undefined` — which leaves the primitive's own default\nalone. `undefined` and not `document.body`: a component that names the default has taken\nthe decision away from the primitive, and the primitive is the thing that knows about\nshadow roots, SSR and nested portals.",
+          "description": "The container a portal in this subtree should use: the caller's `explicit` value, else\nthe nearest `UIPortalHost`, else `undefined` so the primitive keeps its own default.",
           "guidanceSource": "family",
           "chooseWhen": "Setting display defaults, theme, density and scale for the app or a subtree.",
           "avoidWhen": "The value is per-feature policy or domain data, which stays a prop.",
@@ -18299,24 +17810,29 @@
       "alternatives": [
         "features/theme-tweaker"
       ],
+      "composeWith": [],
       "optionalPeers": [],
       "dependsOnFamilies": [],
       "previews": [
+        {
+          "route": "/dropdown-menu",
+          "page": "Dropdown & context menu"
+        },
         {
           "route": "/form-field",
           "page": "Form field"
         },
         {
-          "route": "/primitive-relative-time",
-          "page": "Relative time"
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
         },
         {
-          "route": "/scale",
-          "page": "Scale & density"
+          "route": "/primitive-date",
+          "page": "Dates & times"
         },
         {
-          "route": "/sheet",
-          "page": "Sheet"
+          "route": "/scale",
+          "page": "Scale & density"
         },
         {
           "route": "/tokens",
@@ -18328,17 +17844,35 @@
         }
       ],
       "recipes": [
+        {
+          "id": "dropdown-scheme",
+          "title": "Dark by default, decided by the provider",
+          "route": "/dropdown-menu",
+          "page": "Dropdown & context menu"
+        },
         {
           "id": "forms-scale",
           "title": "Scale",
           "route": "/form-field",
           "page": "Form field"
         },
+        {
+          "id": "sheet-provider",
+          "title": "Decided once, not per call site",
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
+        },
+        {
+          "id": "overlay-backdrop",
+          "title": "A blurred scrim, when a product wants one",
+          "route": "/overlay",
+          "page": "Overlay, dialog & sheet"
+        },
         {
           "id": "relative-time-locale",
           "title": "In another language",
-          "route": "/primitive-relative-time",
-          "page": "Relative time"
+          "route": "/primitive-date",
+          "page": "Dates & times"
         },
         {
           "id": "the-factor",
@@ -18360,7 +17894,7 @@
         },
         {
           "id": "why-two-levels",
-          "title": "Why a factor and not a size prop",
+          "title": "Why two factors, and no third",
           "route": "/scale",
           "page": "Scale & density"
         },
@@ -18370,12 +17904,6 @@
           "route": "/scale",
           "page": "Scale & density"
         },
-        {
-          "id": "sheet-provider",
-          "title": "Decided once, not per call site",
-          "route": "/sheet",
-          "page": "Sheet"
-        },
         {
           "id": "semantic-tier",
           "title": "Semantic tier",