@kerfjs/ui 5.0.0-beta.75 → 5.0.0-beta.77

package/README.md

@@ -9,6 +9,31 @@ When adding a first-party public component, follow the
 entry drives one validator across package, build, barrel, CSS, demo, route, and
 AI signature projections, with a non-mutating dry-run report.
 
+### Shared semantic tones
+
+`SemanticTone` is the shared color-role type for `Badge`, `Chip`, `StateBanner`,
+and semantic `ContentItem` appearances: `neutral`, `info`, `pop`, `success`,
+`warning`, and `danger`. Import it as a type from `@kerfjs/ui`,
+`@kerfjs/ui/badge`, `@kerfjs/ui/state-banner`, or `@kerfjs/ui/content-item`.
+Use `info` for the role backed by the existing `--kui-color-brand-*` tokens.
+Migrate Badge/Chip `tone="brand"` to `tone="info"`; `BadgeTone` and
+`StateBannerTone` remain deprecated aliases of `SemanticTone`.
+
+## Source organization
+
+The flat files directly under `src/` are stable package entry facades. Keep
+component implementation and CSS together under
+`src/components/<family>/<component>/`. Put support code used by one component
+in its `internal/`, `model/`, `register/`, or `wiring/` folder. Shared types and
+utilities live under `src/shared/`; wiring that spans several components lives
+under `src/wiring/`; Web Awesome integration code lives under
+`src/integrations/`. Catalog-only implementation remains under `src/catalog/`.
+
+Choose an existing family by the component role, and add a family only when no
+current one fits. Public JavaScript and CSS subpaths remain flat through their
+root facades. `npm run check:source-organization` rejects implementation added
+back to the root or component-local support code placed in the wrong folder.
+
 Browser verification always builds current source: both `npm run test:e2e`
 and direct focused Playwright commands run the catalog/conformance preflights
 and production build before preview. See the [UX catalog contract](./docs/ux-demo.md).
@@ -218,6 +243,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `TabBar`                                                            | `@kerfjs/ui/tab-bar`                    | `@kerfjs/ui/tab-bar.css`               |
 | `wireTabBars`, `reorderTabs`                                        | `@kerfjs/ui/wire-tab-bars`              | —                                      |
 | `wireScrollDividers`                                                | `@kerfjs/ui/wire-scroll-dividers`       | —                                      |
+| `wireToolbarVisibility`                                             | `@kerfjs/ui/wire-toolbar-visibility`    | —                                      |
 | `LoadingSpinner`                                                    | `@kerfjs/ui/loading-spinner`            | `@kerfjs/ui/loading-spinner.css`       |
 | `Skeleton`                                                          | `@kerfjs/ui/skeleton`                   | `@kerfjs/ui/skeleton.css`              |
 | `SunkenPanel`                                                       | `@kerfjs/ui/sunken-panel`               | `@kerfjs/ui/sunken-panel.css`          |
@@ -497,7 +523,8 @@ or scope variables directly on a component instance.
 
 Applications can separately opt into `@kerfjs/ui/document.css` for border-box
 sizing, token-backed body typography/colors, zero body margin, plain-link color,
-and a definite full-height chain. Add `class="kui-app-root"` to the one direct
+inherited native table-cell and form-control font metrics, and a definite
+full-height chain. Add `class="kui-app-root"` to the one direct
 mount container when a percentage-height application shell must fill the
 viewport. This global baseline is deliberately absent from `styles.css` and
 component browser imports. See [Document baseline](./docs/document-baseline.md).
@@ -766,3 +793,16 @@ For dimensions that should scale with the root font size, author pixels with
 baseline. Keep intentional 1px borders in pixels and contextual `em` values
 explicit. `npm run build` emits standard CSS to `dist/styles`; `npm run dev`
 applies the same transform directly to source styles and hot-reloads edits.
+
+Lowered surfaces and decorative neutral fills/borders use translucent shared theme colors. Nested surfaces compound naturally; demos compose public components without per-depth overrides. See [contextual transparency](docs/webawesome-theme.md#contextual-transparency).
+
+`ToolbarText` and `ToolbarControlGroup` accept typed `hideBelow`/`showBelow`
+lengths (for example `px(416)`). Wire `wireToolbarVisibility(root)` from
+`@kerfjs/ui/wire-toolbar-visibility` and dispose on unmount. Thresholds use the
+nearest Toolbar content-box width: hideBelow hides strictly below, showBelow
+shows strictly below, with complementary behavior at equality. Percentages use
+that content width; em and custom properties use the item's own context. Invalid,
+negative, unresolved, or contradictory values leave the item visible under this
+width policy. Keep primary actions visible and offer a complementary overflow
+group. See `docs/component-contract.md` "Toolbar width visibility" for lifecycle
+details.

package/ai/component-catalog.json

@@ -37,7 +37,7 @@
         "accessible label for abbreviated content"
       ],
       "variants": [
-        "neutral, brand, pop, success, warning, or danger tone",
+        "neutral, info, pop, success, warning, or danger tone",
         "quiet, solid, or outline appearance",
         "pill or rounded shape",
         "compact or default size, or a text-free dot (size: 'dot')",
@@ -96,7 +96,7 @@
         "disabled policy"
       ],
       "variants": [
-        "neutral, brand, pop, success, warning, or danger tone",
+        "neutral, info, pop, success, warning, or danger tone",
         "quiet, solid, or outline appearance",
         "pill or rounded shape",
         "compact or default size",
@@ -161,6 +161,7 @@
       "variants": [
         "decorative",
         "labeled",
+        "inline text flow",
         "outline (default appearance)",
         "solid (appearance=solid)"
       ],
@@ -174,6 +175,11 @@
           "title": "Semantic icon color",
           "description": "Set an icon foreground with a semantic color token; omit color to inherit from surrounding text. Use foregroundColor() for a custom CSS color or foregroundColorVar() for an app variable.",
           "code": "<LucideIcon icon={Bell} name=\"alert\" color={uiColor('warning-on-quiet')} />"
+        },
+        {
+          "title": "Inline with text",
+          "description": "Let a decorative icon flow inside Text or other prose while preserving its inherited 1em size.",
+          "code": "<Text>Ready <LucideIcon icon={Bell} name=\"notification\" inline /> now.</Text>"
         }
       ],
       "accessibility": [
@@ -466,12 +472,12 @@
       "category": "Foundation",
       "kind": "composition",
       "source": "kerf",
-      "description": "Opt-in document-level defaults: border-box sizing, body margin/font/surface, link color, and the html → body → .kui-app-root full-height chain.",
+      "description": "Opt-in document-level defaults: border-box sizing, body margin/font/surface, native table-cell and form-control font metrics, link color, and the html → body → .kui-app-root full-height chain.",
       "uses": [],
       "purpose": "Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.",
       "publicExports": [],
       "useWhen": [
-        "An application wants Kerf UI to own document-level box sizing, body typography, surface, and link color.",
+        "An application wants Kerf UI to own document-level box sizing, body typography, native table-cell and form-control font metrics, surface, and link color.",
         "A full-height shell (Workbench, SplitView, NavStack, or TabScaffold) mounts into one direct container: put .kui-app-root on that container."
       ],
       "avoidWhen": [
@@ -815,6 +821,11 @@
               "on": "kui-nav-stack__chrome-copy",
               "meaning": "Marks the inert, aria-hidden snapshot of the outgoing chrome shown during the cross-fade."
             },
+            {
+              "name": "data-nav-revealed",
+              "on": "kui-nav-stack__view",
+              "meaning": "\"true\" on the preserved, aria-hidden previous view while an incoming view slides over it."
+            },
             {
               "name": "data-nav-exiting",
               "on": "kui-nav-stack__view",
@@ -972,6 +983,11 @@
               "on": "kui-nav-stack__chrome-copy",
               "meaning": "Marks the inert, aria-hidden snapshot of the outgoing chrome shown during the cross-fade."
             },
+            {
+              "name": "data-nav-revealed",
+              "on": "kui-nav-stack__view",
+              "meaning": "\"true\" on the preserved, aria-hidden previous view while an incoming view slides over it."
+            },
             {
               "name": "data-nav-exiting",
               "on": "kui-nav-stack__view",
@@ -1512,14 +1528,17 @@
       "uses": [
         "toolbar-text",
         "toolbar-control-group",
-        "wa-button"
+        "wa-button",
+        "popup-menu"
       ],
       "purpose": "Leading, centered, and trailing toolbar composition.",
       "publicExports": [
-        "Toolbar"
+        "Toolbar",
+        "wireToolbarVisibility"
       ],
       "useWhen": [
-        "Compose application chrome or a page, panel, or dialog heading with leading, center, and trailing regions."
+        "Compose application chrome or a page, panel, or dialog heading with leading, center, and trailing regions.",
+        "Use typed hideBelow/showBelow lengths with wireToolbarVisibility(root) for per-item toolbar priority; keep primary actions available and provide a showBelow overflow alternative."
       ],
       "avoidWhen": [
         "Do not use it as a generic wrapper when no toolbar or heading relationship exists."
@@ -1542,7 +1561,8 @@
         "trailing priority for an expanded trailing control at compact or narrow widths",
         "trailing groups and a standalone primary wa-button wrap instead of clipping",
         "outer inset independently configurable from zone gap",
-        "app bar or bottom bar claiming its screen edges (safeAreaEdges)"
+        "app bar or bottom bar claiming its screen edges (safeAreaEdges)",
+        "typed hideBelow/showBelow thresholds at the nearest Toolbar content width"
       ],
       "accessibility": [
         "Supply a label when the toolbar needs an accessible name."
@@ -1580,6 +1600,23 @@
               "meaning": "The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it."
             }
           ]
+        },
+        {
+          "export": "wireToolbarVisibility",
+          "import": "@kerfjs/ui/wire-toolbar-visibility",
+          "required": false,
+          "stateAttributes": [
+            {
+              "name": "data-toolbar-width-hidden",
+              "on": "ToolbarText, ToolbarControlGroup and its paired busy status",
+              "meaning": "True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers."
+            },
+            {
+              "name": "data-toolbar-visibility-probe",
+              "on": "private aria-hidden measurement boxes under Toolbar",
+              "meaning": "Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility."
+            }
+          ]
         }
       ],
       "publicClasses": [
@@ -1606,6 +1643,9 @@
         "catalogRoute": "?component=toolbar",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#ambiguous-choices"
+      },
+      "publicExportImports": {
+        "wireToolbarVisibility": "@kerfjs/ui/wire-toolbar-visibility"
       }
     },
     {
@@ -1629,7 +1669,10 @@
         "Use ToolbarActionLink for navigation or external resources that must retain native anchor semantics inside a group.",
         "Fill it with plain <button> controls (the group styles > button fully); use wa-button only for a Web Awesome feature. A popup menu is a PopupMenu in a single group with nestedDropdown; it renders its own trigger, so never hand-write wa-dropdown markup. Each control stays whole: an icon sits beside its label on one row and no trigger gets a fixed width. Use overflow=wrap for independent links that should move as whole actions to another row on narrow surfaces.",
         "For an avatar control, set content=avatar and avatarImage instead of inserting an img; one button paints the group and multiple buttons paint only the pressed highlight.",
-        "In a Workbench or CollapsiblePanel toolbar, mark a group relocateOnCollapse to keep it available in the work-area toolbar when the panel closes; place it directly or in an array in any toolbar zone."
+        "In a Workbench or CollapsiblePanel toolbar, mark a group relocateOnCollapse to keep it available in the work-area toolbar when the panel closes; place it directly or in an array in any toolbar zone.",
+        "Use tileTone for a contained single group containing only a direct decorative SVG icon; interactive or mixed groups retain their existing control chrome.",
+        "Set expandedOverflow=visible on an expanded search to anchor application suggestions, date pickers, or help below the group without overriding its geometry.",
+        "Use typed hideBelow/showBelow lengths with wireToolbarVisibility(root) for per-item toolbar priority; keep primary actions available and provide a showBelow overflow alternative."
       ],
       "avoidWhen": [
         "Do not use merely to align unrelated buttons or to imitate an exclusive choice.",
@@ -1668,7 +1711,10 @@
         "always visible or compact-only responsive visibility",
         "relocate on panel collapse",
         "avatar scrim",
-        "contained avatar background on a single group or selected multi-button highlight"
+        "contained avatar background on a single group or selected multi-button highlight",
+        "neutral, brand, success, warning, or danger quiet icon tile tone",
+        "clip or visible app-owned overflow while a search is expanded",
+        "typed hideBelow/showBelow thresholds at the nearest Toolbar content width"
       ],
       "accessibility": [
         "Name the group when its relationship is not evident from context.",
@@ -1686,7 +1732,25 @@
           "browser-condition-css"
         ]
       },
-      "wiring": [],
+      "wiring": [
+        {
+          "export": "wireToolbarVisibility",
+          "import": "@kerfjs/ui/wire-toolbar-visibility",
+          "required": false,
+          "stateAttributes": [
+            {
+              "name": "data-toolbar-width-hidden",
+              "on": "ToolbarText, ToolbarControlGroup and its paired busy status",
+              "meaning": "True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers."
+            },
+            {
+              "name": "data-toolbar-visibility-probe",
+              "on": "private aria-hidden measurement boxes under Toolbar",
+              "meaning": "Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility."
+            }
+          ]
+        }
+      ],
       "publicClasses": [
         "kui-toolbar-action-link",
         "kui-toolbar-control-group"
@@ -1716,13 +1780,74 @@
         "--kui-toolbar-control-pressed-color",
         "--kui-toolbar-control-selected-background",
         "--kui-toolbar-control-selected-color",
-        "--kui-toolbar-control-selected-shadow"
+        "--kui-toolbar-control-selected-shadow",
+        "--kui-color-neutral-fill-quiet",
+        "--kui-color-neutral-border-quiet",
+        "--kui-color-brand-fill-quiet",
+        "--kui-color-brand-border-quiet",
+        "--kui-color-success-fill-quiet",
+        "--kui-color-success-border-quiet",
+        "--kui-color-success-on-quiet",
+        "--kui-color-warning-fill-quiet",
+        "--kui-color-warning-border-quiet",
+        "--kui-color-warning-on-quiet",
+        "--kui-color-danger-fill-quiet",
+        "--kui-color-danger-border-quiet",
+        "--kui-color-danger-on-quiet"
       ],
       "links": {
         "catalogRoute": "?component=toolbar-control-group",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
-      }
+      },
+      "cssValueProps": [
+        {
+          "path": "hideBelow",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "hideBelow={px(416)}"
+          ]
+        },
+        {
+          "path": "showBelow",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "showBelow={px(416)}"
+          ]
+        }
+      ]
     },
     {
       "id": "surface-scaffold",
@@ -1907,11 +2032,13 @@
       ],
       "useWhen": [
         "Render toolbar identity or heading text at a supported hierarchy size; pass headingLevel for heading semantics.",
-        "Use action for an editable toolbar title: it renders a native button that shrinks and ellipsizes beside sibling status chips."
+        "Use action for an editable toolbar title: it renders a native button that shrinks and ellipsizes beside sibling status chips.",
+        "Use tone=dark for title or filename text on a loud toolbar surface, matching dark ToolbarControlGroups.",
+        "Use typed hideBelow/showBelow lengths with wireToolbarVisibility(root) for per-item toolbar priority; keep primary actions available and provide a showBelow overflow alternative."
       ],
       "avoidWhen": [
         "Do not omit headingLevel when the text is the page or section heading.",
-        "Large, default, and small are intentionally quiet toolbar identity text and have no tone option. Use xlarge-fixed for a normal-color toolbar heading at the fixed font-l step; use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section."
+        "Large, default, and small are intentionally quiet toolbar identity text in default tone. Use xlarge-fixed for a normal-color toolbar heading at the fixed font-l step; use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section."
       ],
       "alternatives": [
         {
@@ -1937,7 +2064,9 @@
         "default",
         "small",
         "xsmall",
-        "placeholder (loading)"
+        "placeholder (loading)",
+        "dark (loud-surface foreground)",
+        "typed hideBelow/showBelow thresholds at the nearest Toolbar content width"
       ],
       "accessibility": [
         "Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title.",
@@ -1955,7 +2084,25 @@
           "browser-condition-css"
         ]
       },
-      "wiring": [],
+      "wiring": [
+        {
+          "export": "wireToolbarVisibility",
+          "import": "@kerfjs/ui/wire-toolbar-visibility",
+          "required": false,
+          "stateAttributes": [
+            {
+              "name": "data-toolbar-width-hidden",
+              "on": "ToolbarText, ToolbarControlGroup and its paired busy status",
+              "meaning": "True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers."
+            },
+            {
+              "name": "data-toolbar-visibility-probe",
+              "on": "private aria-hidden measurement boxes under Toolbar",
+              "meaning": "Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility."
+            }
+          ]
+        }
+      ],
       "publicClasses": [
         "kui-toolbar-text"
       ],
@@ -1967,13 +2114,62 @@
         "--kui-font-l",
         "--kui-font-m",
         "--kui-font-s",
-        "--kui-font-xs"
+        "--kui-font-xs",
+        "--kui-color-neutral-on-loud"
       ],
       "links": {
         "catalogRoute": "?component=toolbar-text",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
-      }
+      },
+      "cssValueProps": [
+        {
+          "path": "hideBelow",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "hideBelow={px(416)}"
+          ]
+        },
+        {
+          "path": "showBelow",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "showBelow={px(416)}"
+          ]
+        }
+      ]
     },
     {
       "id": "text",
@@ -2020,7 +2216,8 @@
         "default, quiet, or danger tone",
         "compact, default, large, or xlarge size",
         "default or monospace font",
-        "flush item geometry and tight line height"
+        "flush item geometry and tight line height",
+        "controlMargins selects exterior 8px gutters with canonical physical Sides"
       ],
       "accessibility": [
         "Text renders a native paragraph by default; choose an h1 through h6 variant by document outline rather than appearance, or span for inline secondary text.",
@@ -2029,11 +2226,12 @@
         "FieldLabel is plain text, not a native label; give it an id and associate the preview group with aria-labelledby."
       ],
       "geometry": {
-        "margin": "none",
+        "margin": "self",
         "border": "self",
         "padding": "self",
         "notes": [
-          "Block Text variants reset native margins and add a 1px transparent border plus the standard 8px item padding; flush removes the border and padding. Tight line height is available for compact copy. Span has no margin, border, or padding. FieldLabel mirrors the themed Web Awesome label typography, 9px inline inset, and bottom gap."
+          "Block Text variants reset native margins and add a 1px transparent border plus the standard 8px item padding; flush removes the border and padding. Tight line height is available for compact copy. Span has no margin by default, border, or padding. FieldLabel mirrors the themed Web Awesome label typography, 9px inline inset, and bottom gap.",
+          "controlMargins adds the shared control gutter outside selected physical edges without changing border or padding; avoid duplicating a parent inset. Spans retain inline display and native inline margin behavior."
         ]
       },
       "delivery": {
@@ -2354,7 +2552,7 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Equal-width columns with a fixed count or a minimum-width responsive mode, typed gaps, and optional flex participation.",
+      "description": "Equal-width columns with a fixed count or a minimum-width responsive mode, typed gaps, physical-side text/control insets, and optional flex participation.",
       "uses": [],
       "purpose": "Arrange related siblings in equal-width columns with either a fixed count or automatic container-width collapse.",
       "publicExports": [
@@ -2483,7 +2681,7 @@
       "appOwns": [
         "child semantics and content",
         "fixed column count or responsive minimum width",
-        "typed gap and flex choices"
+        "typed gap, flex, and physical-side inset choices"
       ],
       "variants": [
         "any positive safe-integer equal-track count",
@@ -2491,6 +2689,7 @@
         "named none/2xs/xs/s/m/l/xl token gap",
         "typed CssLength gap",
         "boolean, finite-keyword, or typed CssFlex flex",
+        "top/right/bottom/left text and control inset combinations",
         "fill: the layout root fills a definite-height parent",
         "rootAttributes: safe data-* metadata on the root",
         "selectionMode=multiple: labeled multi-select grid for ContentItem tiles"
@@ -2503,8 +2702,9 @@
       "geometry": {
         "margin": "none",
         "border": "none",
-        "padding": "none",
+        "padding": "conditional",
         "notes": [
+          "textInsets adds 17px and controlInsets adds 8px on selected physical sides; text wins on overlap.",
           "Fixed tracks use minmax(0, 1fr); responsive tracks use auto-fit with a minimum width capped at 100%, preserving equal distribution without narrow overflow."
         ]
       },
@@ -3373,22 +3573,23 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "One self-contained content child with the shared 8px margin + 1px border + 8px padding geometry, a typed frame, and a rounded or pill shape.",
+      "description": "One self-contained content child with shared geometry plus typed transparent, surface, or semantic appearance, frame, and shape choices.",
       "uses": [],
-      "purpose": "Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, and radius, with framing and shape chosen by typed props instead of hand-written modifier classes.",
+      "purpose": "Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, radius, and optional coordinated surface colors.",
       "publicExports": [
         "ContentItem"
       ],
       "useWhen": [
         "An ordinary surface-like child of a Pane or .kui-content stack needs the shared content-item geometry so its content edge lands at the standard 17px inset.",
         "A content item marks a real distinction and must read as visibly bounded: pass frame=\"framed\" (the border is always reserved, so geometry does not change).",
+        "A content item needs the base surface or a coordinated semantic status treatment: pass appearance=\"surface\" or a semantic appearance such as success or danger.",
         "A content item should follow a pill control's 22px radius: pass shape=\"pill\".",
         "A selectable rich card needs nested controls: use selectionMode=\"multiple\" inside a labeled List multi-select grid."
       ],
       "avoidWhen": [
         "Do not wrap a component that already owns content-item geometry (ListItem, ListHeader, StateBanner, Toolbar, ValueTable) or pad around a ContentItem; either double-insets.",
         "Do not frame an item only to make it look contained; hierarchy comes from alignment, spacing, and type first.",
-        "Do not use it as a filled or lowered card; use SunkenPanel for a lowered surface.",
+        "Do not use its surface appearance for a lowered inset panel around a stack; use SunkenPanel for that structure.",
         "Do not use it for bare text alone; use ListInsetText, which adds the same inset without claiming a surface."
       ],
       "alternatives": [
@@ -3411,6 +3612,7 @@
       "appOwns": [
         "the item content",
         "whether the item marks a real distinction that warrants a visible frame",
+        "whether the item needs a surface or semantic appearance",
         "corner shape",
         "region semantics and accessible name",
         "whether the item is a programmatic focus target",
@@ -3421,6 +3623,8 @@
         "framed rounded item",
         "pill item",
         "framed pill item",
+        "base surface item",
+        "neutral, info, pop, success, warning, or danger semantic item",
         "named focus-target region",
         "multi-select rich grid row"
       ],
@@ -3435,7 +3639,7 @@
         "border": "self",
         "padding": "self",
         "notes": [
-          "The 1px border is always reserved and transparent unless frame=\"framed\", so framed and unframed items share the same geometry."
+          "The 1px border is always reserved; transparent items paint it only when frame=\"framed\", while surface and semantic appearances coordinate its color with their background and foreground."
         ]
       },
       "delivery": {
@@ -4219,7 +4423,8 @@
       ],
       "useWhen": [
         "Choose a controlled value from a moderate or long list, including grouped and icon-bearing choices.",
-        "Color an optional choice icon with a CssForegroundColor: uiColor() with a foreground token such as success-on-quiet, foregroundColorVar() for an app-owned property, or foregroundColor() for a direct custom CSS color. Fill tokens such as success are backgrounds that leave the icon nearly invisible, so they, lengths, raw color strings, and unqualified colorVar() values are rejected."
+        "Color an optional choice icon with a CssForegroundColor: uiColor() with a foreground token such as success-on-quiet, foregroundColorVar() for an app-owned property, or foregroundColor() for a direct custom CSS color. Fill tokens such as success are backgrounds that leave the icon nearly invisible, so they, lengths, raw color strings, and unqualified colorVar() values are rejected.",
+        "Use the default content-sized menu for long option labels; native popup shifting keeps it within 10px viewport gutters. fitMenu instead matches trigger width and wraps labels."
       ],
       "avoidWhen": [
         "Do not use for commands or a small choice set that should stay visible."