@kerfjs/ui 5.0.0-beta.76 → 5.0.0-beta.78

package/README.md

@@ -37,6 +37,9 @@ 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).
+Failed Playwright tests retain traces and screenshots alongside an HTML report.
+The CI `ui` job uploads the report and per-test failure evidence for 14 days when
+the browser suite fails; the artifact is named `ui-browser-failure-<run>-<attempt>`.
 
 When authoring a component gallery, follow the single
 [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract)
@@ -243,6 +246,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`          |
@@ -794,3 +798,14 @@ 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/application-ui-diagnostic-ids-v1.json

@@ -29,6 +29,9 @@
     "KUI-D010",
     "KUI-D011",
     "KUI-D020",
+    "KUI-D030",
+    "KUI-D031",
+    "KUI-D032",
     "KUI-L001",
     "KUI-L002",
     "KUI-L003",

package/ai/component-catalog.json

@@ -761,13 +761,13 @@
       ],
       "appOwns": [
         "ordered view stack and stable keys",
-        "view content and titles",
+        "view content and structured top and bottom toolbar configurations",
         "push and pop actions",
         "preferred initial focus targets when DOM order is insufficient",
-        "per-view bottom toolbar content or a persistent fallback",
+        "per-view bottom toolbar or a persistent structured fallback",
         "per-view leading, center, and trailing top-toolbar groups",
-        "per-view fixed header content above the active view's scroll area",
-        "top-toolbar configuration, title size, and heading level",
+        "per-view header and footer with List and Pane configuration",
+        "top-toolbar defaults, title size, and heading level",
         "whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers)"
       ],
       "variants": [
@@ -821,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",
@@ -854,7 +859,6 @@
         "kui-nav-stack__chrome-copy",
         "kui-nav-stack__chrome-copy--bottom",
         "kui-nav-stack__chrome-copy--exiting",
-        "kui-nav-stack__header",
         "kui-nav-stack__viewport",
         "kui-nav-stack__view",
         "kui-nav-stack__view--entering",
@@ -978,6 +982,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",
@@ -1518,14 +1527,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."
@@ -1548,7 +1560,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."
@@ -1586,6 +1599,33 @@
               "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."
+            },
+            {
+              "name": "data-morph-preserve",
+              "on": "private aria-hidden measurement boxes and visibility state children",
+              "meaning": "Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them."
+            },
+            {
+              "name": "data-toolbar-visibility-state",
+              "on": "private hidden children of width-managed items and paired busy statuses",
+              "meaning": "Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback."
+            }
+          ]
         }
       ],
       "publicClasses": [
@@ -1612,6 +1652,9 @@
         "catalogRoute": "?component=toolbar",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#ambiguous-choices"
+      },
+      "publicExportImports": {
+        "wireToolbarVisibility": "@kerfjs/ui/wire-toolbar-visibility"
       }
     },
     {
@@ -1635,7 +1678,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.",
@@ -1674,7 +1720,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.",
@@ -1692,7 +1741,35 @@
           "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."
+            },
+            {
+              "name": "data-morph-preserve",
+              "on": "private aria-hidden measurement boxes and visibility state children",
+              "meaning": "Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them."
+            },
+            {
+              "name": "data-toolbar-visibility-state",
+              "on": "private hidden children of width-managed items and paired busy statuses",
+              "meaning": "Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback."
+            }
+          ]
+        }
+      ],
       "publicClasses": [
         "kui-toolbar-action-link",
         "kui-toolbar-control-group"
@@ -1722,13 +1799,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",
@@ -1736,7 +1874,7 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Typed Web Awesome dialog and popup surface sizing, presentation, and inset composition.",
+      "description": "Typed Web Awesome dialog preferred widths and viewport bounds, presentation, and popup inset composition.",
       "uses": [
         "wa-dialog",
         "wa-dropdown",
@@ -1749,7 +1887,8 @@
       ],
       "useWhen": [
         "A Web Awesome dialog or dropdown needs a standard size, presentation, body/footer inset, or list-compatible menu inset.",
-        "A dialog body should compose rows, sections, or aligned bare prose through List and ListInsetText."
+        "A dialog body should compose rows, sections, or aligned bare prose through List and ListInsetText.",
+        "A modal needs a typed preferred width, viewport gutter, or dynamic viewport-bounded height cap while retaining native body scrolling and footer actions."
       ],
       "avoidWhen": [
         "Do not use it as a generic layout wrapper or to replace application-owned modal state and focus lifecycle.",
@@ -1766,6 +1905,7 @@
       "variants": [
         "small, medium, or large dialog",
         "modal, side-sheet, or fullscreen dialog",
+        "typed modal preferred width, viewport gutter, and maximum height, including viewport cap",
         "none, compact, or comfortable body and footer inset",
         "standard, compact, or zero-inset popup menu"
       ],
@@ -1781,8 +1921,10 @@
       "delivery": {
         "browserImport": "@kerfjs/ui/surface-scaffold",
         "manualCssImport": "@kerfjs/ui/surface-scaffold.css",
+        "registrationImport": "@kerfjs/ui/surface-scaffold/register",
         "sideEffects": [
-          "browser-condition-css"
+          "browser-condition-css",
+          "custom-element-registration"
         ]
       },
       "wiring": [],
@@ -1799,7 +1941,86 @@
         "catalogRoute": "?component=surface-scaffold",
         "documentation": "docs/surface-scaffold.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
-      }
+      },
+      "cssValueProps": [
+        {
+          "path": "preferredWidth",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "remify",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "preferredWidth={remify(832)}"
+          ]
+        },
+        {
+          "path": "viewportGutter",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "remify",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "viewportGutter={remify(8)}"
+          ]
+        },
+        {
+          "path": "maxHeight",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "remify",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [
+            "viewport"
+          ],
+          "canonicalShorthands": [
+            "viewport"
+          ],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": [
+            "maxHeight=\"viewport\"",
+            "maxHeight={remify(640)}"
+          ]
+        }
+      ]
     },
     {
       "id": "floating-toolbar",
@@ -1913,11 +2134,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": [
         {
@@ -1943,7 +2166,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.",
@@ -1961,7 +2186,35 @@
           "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."
+            },
+            {
+              "name": "data-morph-preserve",
+              "on": "private aria-hidden measurement boxes and visibility state children",
+              "meaning": "Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them."
+            },
+            {
+              "name": "data-toolbar-visibility-state",
+              "on": "private hidden children of width-managed items and paired busy statuses",
+              "meaning": "Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback."
+            }
+          ]
+        }
+      ],
       "publicClasses": [
         "kui-toolbar-text"
       ],
@@ -1973,13 +2226,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",
@@ -2026,7 +2328,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.",
@@ -2035,11 +2338,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": {
@@ -4231,7 +4535,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."