@kerfjs/ui 5.0.0-beta.50 → 5.0.0-beta.52

package/ai/component-catalog.json

@@ -256,6 +256,10 @@
         "--kui-toolbar-group-inner-size",
         "--kui-toolbar-group-size",
         "--kui-toolbar-gap",
+        "--kui-safe-area-block-start",
+        "--kui-safe-area-block-end",
+        "--kui-safe-area-inline-start",
+        "--kui-safe-area-inline-end",
         "--kui-radius-s",
         "--kui-radius-m",
         "--kui-radius-l",
@@ -453,6 +457,7 @@
         "accessible labels",
         "header, content, and footer children",
         "which logical boundaries show separators",
+        "which sides may compensate for device safe areas in an app-owned arrangement (safeAreaEdges)",
         "responsive placement and visibility"
       ],
       "variants": [
@@ -473,7 +478,8 @@
         "border": "conditional",
         "padding": "child",
         "notes": [
-          "The pane is unpadded; separators are independently opt-in on logical edges and default off."
+          "The pane is unpadded; separators are independently opt-in on logical edges and default off.",
+          "Safe areas: the root and separators paint through unsafe areas while header, content, and footer pad the sides the pane still reaches (routed by --kui-edge-inset-*); content block insets are scroll padding."
         ]
       },
       "delivery": {
@@ -492,6 +498,10 @@
         "kui-pane__toolbar"
       ],
       "publicTokens": [
+        "--kui-edge-inset-block-end",
+        "--kui-edge-inset-block-start",
+        "--kui-edge-inset-inline-end",
+        "--kui-edge-inset-inline-start",
         "--kui-pane-separator-color",
         "--kui-pane-separator-width"
       ],
@@ -575,7 +585,24 @@
         {
           "export": "wireNavStack",
           "import": "@kerfjs/ui/wire-nav-stack",
-          "required": true
+          "required": true,
+          "stateAttributes": [
+            {
+              "name": "data-nav-chrome-transition",
+              "on": "kui-nav-stack",
+              "meaning": "\"true\" while the chrome cross-fades between the outgoing and incoming view."
+            },
+            {
+              "name": "data-nav-chrome-copy",
+              "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-exiting",
+              "on": "kui-nav-stack__view",
+              "meaning": "\"true\" on a popped view the helper briefly re-inserts to slide it out."
+            }
+          ]
         }
       ],
       "publicClasses": [
@@ -678,12 +705,41 @@
         {
           "export": "wireResizableRegions",
           "import": "@kerfjs/ui/wire-resizable-regions",
-          "required": false
+          "required": false,
+          "stateAttributes": [
+            {
+              "name": "data-handle-inset",
+              "on": "kui-resizable-region",
+              "meaning": "Present while a clipping edge clamps the region: the handle and its focus ring sit inside the region instead of overhanging that edge."
+            },
+            {
+              "name": "data-resizing",
+              "on": "kui-resizable-region",
+              "meaning": "\"true\" during an active pointer drag of the handle."
+            }
+          ]
         },
         {
           "export": "wireNavStack",
           "import": "@kerfjs/ui/wire-nav-stack",
-          "required": true
+          "required": true,
+          "stateAttributes": [
+            {
+              "name": "data-nav-chrome-transition",
+              "on": "kui-nav-stack",
+              "meaning": "\"true\" while the chrome cross-fades between the outgoing and incoming view."
+            },
+            {
+              "name": "data-nav-chrome-copy",
+              "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-exiting",
+              "on": "kui-nav-stack__view",
+              "meaning": "\"true\" on a popped view the helper briefly re-inserts to slide it out."
+            }
+          ]
         }
       ],
       "publicClasses": [
@@ -965,7 +1021,24 @@
         {
           "export": "wireSidebar",
           "import": "@kerfjs/ui/wire-sidebar",
-          "required": true
+          "required": true,
+          "stateAttributes": [
+            {
+              "name": "data-collapsible-responsive",
+              "on": "the root passed to wireSidebar",
+              "meaning": "With a deviceClass: \"inline\" on a wide device class, otherwise the compact presentation (\"overlay\" or \"hidden\"). Re-applied if a re-render drops it."
+            },
+            {
+              "name": "data-collapsible-overlay",
+              "on": "the root passed to wireSidebar",
+              "meaning": "With a deviceClass on a compact device: \"true\" for the overlay presentation, \"false\" for hidden. Absent on a wide device class. Re-applied if a re-render drops it."
+            },
+            {
+              "name": "data-morph-preserve",
+              "on": "kui-collapsible-panel__backdrop",
+              "meaning": "Keeps the injected compact-overlay backdrop through the application's re-render; the helper creates and removes the backdrop itself."
+            }
+          ]
         }
       ],
       "publicClasses": [
@@ -1091,13 +1164,19 @@
       "appOwns": [
         "actions",
         "command availability",
-        "responsive relocation"
+        "responsive relocation",
+        "which screen edges an app bar or bottom bar outside a Pane header or footer claims for device safe areas (safeAreaEdges)"
       ],
       "variants": [
         "bottom divider (default)",
         "no dividers",
         "top/right/bottom/left divider combinations",
-        "centered content"
+        "centered content",
+        "stacked zones at compact or narrow widths",
+        "content-driven wrap that keeps a heading title whole",
+        "center priority for an expanded center control",
+        "trailing groups wrap instead of clipping",
+        "app bar or bottom bar claiming its screen edges (safeAreaEdges)"
       ],
       "accessibility": [
         "Supply a label when the toolbar needs an accessible name."
@@ -1107,7 +1186,8 @@
         "border": "conditional",
         "padding": "self",
         "notes": [
-          "Padding belongs to the toolbar; dividerSides selects any canonical combination of its physical top, right, bottom, and left edges."
+          "Padding belongs to the toolbar; dividerSides selects any canonical combination of its physical top, right, bottom, and left edges.",
+          "Safe areas: a Pane header or footer hands a sole Toolbar its inline edges; an app bar or bottom bar at a screen edge claims its sides with safeAreaEdges and pads each claimed side by the --kui-edge-inset-* context or the full device inset, while its box and dividers paint through."
         ]
       },
       "delivery": {
@@ -1402,9 +1482,21 @@
         "Render toolbar identity or heading text at a supported hierarchy size; pass headingLevel for heading semantics."
       ],
       "avoidWhen": [
-        "Do not omit headingLevel when the text is the page or section heading."
+        "Do not omit headingLevel when the text is the page or section heading.",
+        "Do not use a size below xlarge as a normal-color subsection title: large, default, and small are intentionally quiet toolbar identity text and have no tone option. Use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section."
+      ],
+      "alternatives": [
+        {
+          "id": "text",
+          "relationship": "semantic-alternative",
+          "when": "Use Text variant h2-h6 for a normal-color subsection title in content rather than toolbar identity."
+        },
+        {
+          "id": "list-header",
+          "relationship": "semantic-alternative",
+          "when": "Use ListHeader for a list or menu section label with a count, badge, action, or disclosure."
+        }
       ],
-      "alternatives": [],
       "appOwns": [
         "text",
         "responsive priority"
@@ -1436,8 +1528,10 @@
       ],
       "publicTokens": [
         "--kui-color-neutral-on-quiet",
+        "--kui-color-text",
+        "--kui-font-2xl",
+        "--kui-font-l",
         "--kui-font-m",
-        "--kui-font-mono",
         "--kui-font-s",
         "--kui-font-xs"
       ],
@@ -1453,12 +1547,14 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Semantic native paragraph text by default, with heading variants, composable semantic presentation roles, and standard padded content geometry.",
+      "description": "Semantic native paragraph text by default, with heading and inline-span variants plus composable semantic presentation roles.",
       "uses": [],
-      "purpose": "Render paragraph semantics by default or h1 through h6 when selected, while independently configuring quiet or danger tone, compact size, or monospace font and consistently supplying standard geometry.",
-      "publicExports": ["Text"],
+      "purpose": "Render paragraph semantics by default, h1 through h6 when selected, or geometry-free inline secondary text as a span while independently configuring quiet or danger tone, compact size, or monospace font.",
+      "publicExports": [
+        "Text"
+      ],
       "useWhen": [
-        "Render ordinary application headings or paragraphs that should use native document semantics and the standard text-box inset."
+        "Render ordinary application headings or paragraphs with native document semantics, or inline secondary text inside rows, labels, and table cells."
       ],
       "avoidWhen": [
         "Do not use Text for toolbar identity or title content; use ToolbarText inside a Toolbar zone.",
@@ -1483,13 +1579,13 @@
         "document heading hierarchy"
       ],
       "variants": [
-        "p or h1 through h6 semantic variant",
+        "p, h1 through h6, or inline span semantic variant",
         "default, quiet, or danger tone",
         "default or compact size",
         "default or monospace font"
       ],
       "accessibility": [
-        "Text renders a native paragraph by default; choose an h1 through h6 variant by document outline rather than appearance.",
+        "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.",
         "Ordinary global, data, and ARIA attributes pass through to the native element.",
         "Choose tone, size, and font independently of the heading level so appearance does not distort the document outline."
       ],
@@ -1498,16 +1594,20 @@
         "border": "self",
         "padding": "self",
         "notes": [
-          "Text resets the native variant's margin and adds a 1px transparent border plus the standard 8px item padding."
+          "Block Text variants reset native margins and add a 1px transparent border plus the standard 8px item padding; span has no margin, border, or padding."
         ]
       },
       "delivery": {
         "browserImport": "@kerfjs/ui/text",
         "manualCssImport": "@kerfjs/ui/text.css",
-        "sideEffects": ["browser-condition-css"]
+        "sideEffects": [
+          "browser-condition-css"
+        ]
       },
       "wiring": [],
-      "publicClasses": ["kui-text"],
+      "publicClasses": [
+        "kui-text"
+      ],
       "publicTokens": [
         "--kui-color-danger-text",
         "--kui-color-text-quiet",
@@ -1652,60 +1752,107 @@
     {
       "id": "row",
       "name": "Row",
-    "category": "Structure",
+      "category": "Structure",
       "kind": "component",
       "source": "kerf",
       "description": "A horizontal flex row with physical-axis alignment, side-selectable text/control insets, a typed xs gap by default, flex participation, and opt-in wrapping.",
       "uses": [],
       "purpose": "Arrange related content horizontally with consistent spacing, optional physical-side text/control insets, and explicit left/center/right/full plus top/middle/bottom/full/baseline alignment instead of application-owned flex wrappers.",
-    "publicExports": ["Row"],
+      "publicExports": [
+        "Row"
+      ],
       "cssValueProps": [
         {
           "path": "gap",
           "grammar": "length",
-          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
-          "nonStandaloneHelpers": ["plus"],
-          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
-          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
-          "exceptionalShorthands": ["s", "xl"],
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [
+            "none",
+            "2xs",
+            "xs",
+            "s",
+            "m",
+            "l",
+            "xl"
+          ],
+          "canonicalShorthands": [
+            "none",
+            "2xs",
+            "xs",
+            "m",
+            "l"
+          ],
+          "exceptionalShorthands": [
+            "s",
+            "xl"
+          ],
           "rawPolicy": "forbid",
-          "examples": ["gap=\"xs\"", "gap={space(\"m\")}", "gap={calc(plus(rem(0.25), pct(10)))}"]
+          "examples": [
+            "gap=\"xs\"",
+            "gap={space(\"m\")}",
+            "gap={calc(plus(rem(0.25), pct(10)))}"
+          ]
         },
         {
           "path": "flex",
           "grammar": "flex",
-          "helpers": ["flex"],
-          "shorthands": ["none", "auto", "initial"],
-          "canonicalShorthands": ["none", "auto", "initial"],
+          "helpers": [
+            "flex"
+          ],
+          "shorthands": [
+            "none",
+            "auto",
+            "initial"
+          ],
+          "canonicalShorthands": [
+            "none",
+            "auto",
+            "initial"
+          ],
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
-          "examples": ["flex", "flex=\"none\"", "flex={flex(1, 1, rem(20))}"]
+          "examples": [
+            "flex",
+            "flex=\"none\"",
+            "flex={flex(1, 1, rem(20))}"
+          ]
         }
       ],
       "useWhen": [
         "Arrange a group of sibling components horizontally.",
         "Choose physical horizontal distribution and vertical alignment without writing one-off flex CSS.",
         "Use a finite flex keyword or the flex() builder when Row participates in a flexible parent layout.",
-        "Allow a bounded group to wrap while retaining the same typed gap and alignment contract."
-        ,"Apply the standard text or control inset to selected physical sides without an application wrapper."
+        "Allow a bounded group to wrap while retaining the same typed gap and alignment contract.",
+        "Apply the standard text or control inset to selected physical sides without an application wrapper."
       ],
       "avoidWhen": [
         "Do not use Row when content belongs in a semantic list or when a named-zone component such as Toolbar owns the composition.",
         "Do not pass raw CSS strings to gap or flex, mix their distinct grammars, or use s/xl spacing steps without a deliberate exception.",
         "Do not use alignment to replace semantic grouping or responsive relocation."
       ],
-    "alternatives": [
-      {
-        "id": "list",
-        "relationship": "axis-alternative",
-        "when": "Use List when the main layout axis is vertical."
-      },
-      {
-        "id": "toolbar",
-        "relationship": "semantic-alternative",
-        "when": "Use Toolbar when content belongs to named leading, center, and trailing application-chrome zones."
-      }
-    ],
+      "alternatives": [
+        {
+          "id": "list",
+          "relationship": "axis-alternative",
+          "when": "Use List when the main layout axis is vertical."
+        },
+        {
+          "id": "toolbar",
+          "relationship": "semantic-alternative",
+          "when": "Use Toolbar when content belongs to named leading, center, and trailing application-chrome zones."
+        }
+      ],
       "appOwns": [
         "child semantics and content",
         "alignment and wrapping policy",
@@ -1718,7 +1865,9 @@
         "typed CssLength gap",
         "boolean, finite-keyword, or typed CssFlex flex",
         "nowrap or wrapping",
-        "top/right/bottom/left text and control inset combinations"
+        "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"
       ],
       "accessibility": [
         "Row adds layout only and no grouping role; children retain responsibility for native or ARIA semantics.",
@@ -1735,11 +1884,18 @@
       "delivery": {
         "browserImport": "@kerfjs/ui/row",
         "manualCssImport": "@kerfjs/ui/row.css",
-        "sideEffects": ["browser-condition-css"]
+        "sideEffects": [
+          "browser-condition-css"
+        ]
       },
       "wiring": [],
-      "publicClasses": ["kui-row"],
-      "publicTokens": ["--kui-layout-item-gap", "--kui-row-gap"],
+      "publicClasses": [
+        "kui-row"
+      ],
+      "publicTokens": [
+        "--kui-layout-item-gap",
+        "--kui-row-gap"
+      ],
       "links": {
         "catalogRoute": "?component=row",
         "documentation": "docs/layout.md",
@@ -1755,28 +1911,75 @@
       "description": "A fixed positive number of evenly distributed minmax columns with a typed xs gap by default and optional flex participation.",
       "uses": [],
       "purpose": "Arrange related siblings in equal-width columns without repeating application-owned grid-template-columns CSS.",
-      "publicExports": ["Grid"],
+      "publicExports": [
+        "Grid"
+      ],
       "cssValueProps": [
         {
           "path": "gap",
           "grammar": "length",
-          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
-          "nonStandaloneHelpers": ["plus"],
-          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
-          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
-          "exceptionalShorthands": ["s", "xl"],
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [
+            "none",
+            "2xs",
+            "xs",
+            "s",
+            "m",
+            "l",
+            "xl"
+          ],
+          "canonicalShorthands": [
+            "none",
+            "2xs",
+            "xs",
+            "m",
+            "l"
+          ],
+          "exceptionalShorthands": [
+            "s",
+            "xl"
+          ],
           "rawPolicy": "forbid",
-          "examples": ["gap=\"m\"", "gap={space(\"m\")}", "gap={calc(plus(rem(0.25), pct(10)))}"]
+          "examples": [
+            "gap=\"m\"",
+            "gap={space(\"m\")}",
+            "gap={calc(plus(rem(0.25), pct(10)))}"
+          ]
         },
         {
           "path": "flex",
           "grammar": "flex",
-          "helpers": ["flex"],
-          "shorthands": ["none", "auto", "initial"],
-          "canonicalShorthands": ["none", "auto", "initial"],
+          "helpers": [
+            "flex"
+          ],
+          "shorthands": [
+            "none",
+            "auto",
+            "initial"
+          ],
+          "canonicalShorthands": [
+            "none",
+            "auto",
+            "initial"
+          ],
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
-          "examples": ["flex", "flex=\"none\"", "flex={flex(1, 1, rem(20))}"]
+          "examples": [
+            "flex",
+            "flex=\"none\"",
+            "flex={flex(1, 1, rem(20))}"
+          ]
         }
       ],
       "useWhen": [
@@ -1816,7 +2019,9 @@
         "any positive safe-integer equal-track count",
         "named none/2xs/xs/s/m/l/xl token gap",
         "typed CssLength gap",
-        "boolean, finite-keyword, or typed CssFlex flex"
+        "boolean, finite-keyword, or typed CssFlex flex",
+        "fill: the layout root fills a definite-height parent",
+        "rootAttributes: safe data-* metadata on the root"
       ],
       "accessibility": [
         "Grid adds layout only and no grid role; children retain responsibility for native or ARIA semantics.",
@@ -1833,11 +2038,18 @@
       "delivery": {
         "browserImport": "@kerfjs/ui/grid",
         "manualCssImport": "@kerfjs/ui/grid.css",
-        "sideEffects": ["browser-condition-css"]
+        "sideEffects": [
+          "browser-condition-css"
+        ]
       },
       "wiring": [],
-      "publicClasses": ["kui-grid"],
-      "publicTokens": ["--kui-grid-gap", "--kui-layout-item-gap"],
+      "publicClasses": [
+        "kui-grid"
+      ],
+      "publicTokens": [
+        "--kui-grid-gap",
+        "--kui-layout-item-gap"
+      ],
       "links": {
         "catalogRoute": "?component=grid",
         "documentation": "docs/layout.md",
@@ -1853,29 +2065,92 @@
       "description": "A decorative, non-shrinking fixed gap or flexible main-axis spacer with typed physical width and height.",
       "uses": [],
       "purpose": "Express an intentional empty dimension or consume remaining flex space without application-owned spacer markup or raw CSS lengths.",
-      "publicExports": ["Spacer"],
+      "publicExports": [
+        "Spacer"
+      ],
       "cssValueProps": [
         {
           "path": "width",
           "grammar": "length",
-          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
-          "nonStandaloneHelpers": ["plus"],
-          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
-          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
-          "exceptionalShorthands": ["s", "xl"],
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [
+            "none",
+            "2xs",
+            "xs",
+            "s",
+            "m",
+            "l",
+            "xl"
+          ],
+          "canonicalShorthands": [
+            "none",
+            "2xs",
+            "xs",
+            "m",
+            "l"
+          ],
+          "exceptionalShorthands": [
+            "s",
+            "xl"
+          ],
           "rawPolicy": "forbid",
-          "examples": ["width=\"m\"", "width={space(\"m\")}", "width={calc(plus(rem(0.25), pct(10)))}"]
+          "examples": [
+            "width=\"m\"",
+            "width={space(\"m\")}",
+            "width={calc(plus(rem(0.25), pct(10)))}"
+          ]
         },
         {
           "path": "height",
           "grammar": "length",
-          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
-          "nonStandaloneHelpers": ["plus"],
-          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
-          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
-          "exceptionalShorthands": ["s", "xl"],
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [
+            "none",
+            "2xs",
+            "xs",
+            "s",
+            "m",
+            "l",
+            "xl"
+          ],
+          "canonicalShorthands": [
+            "none",
+            "2xs",
+            "xs",
+            "m",
+            "l"
+          ],
+          "exceptionalShorthands": [
+            "s",
+            "xl"
+          ],
           "rawPolicy": "forbid",
-          "examples": ["height=\"xs\"", "height={rem(1)}"]
+          "examples": [
+            "height=\"xs\"",
+            "height={rem(1)}"
+          ]
         }
       ],
       "useWhen": [
@@ -1925,10 +2200,14 @@
       "delivery": {
         "browserImport": "@kerfjs/ui/spacer",
         "manualCssImport": "@kerfjs/ui/spacer.css",
-        "sideEffects": ["browser-condition-css"]
+        "sideEffects": [
+          "browser-condition-css"
+        ]
       },
       "wiring": [],
-      "publicClasses": ["kui-spacer"],
+      "publicClasses": [
+        "kui-spacer"
+      ],
       "publicTokens": [],
       "links": {
         "catalogRoute": "?component=spacer",
@@ -1965,23 +2244,67 @@
         {
           "path": "gap",
           "grammar": "length",
-          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
-          "nonStandaloneHelpers": ["plus"],
-          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
-          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
-          "exceptionalShorthands": ["s", "xl"],
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [
+            "none",
+            "2xs",
+            "xs",
+            "s",
+            "m",
+            "l",
+            "xl"
+          ],
+          "canonicalShorthands": [
+            "none",
+            "2xs",
+            "xs",
+            "m",
+            "l"
+          ],
+          "exceptionalShorthands": [
+            "s",
+            "xl"
+          ],
           "rawPolicy": "forbid",
-          "examples": ["gap=\"xs\"", "gap={rem(0.25)}", "gap={calc(plus(rem(0.25), pct(10)))}"]
+          "examples": [
+            "gap=\"xs\"",
+            "gap={rem(0.25)}",
+            "gap={calc(plus(rem(0.25), pct(10)))}"
+          ]
         },
         {
           "path": "flex",
           "grammar": "flex",
-          "helpers": ["flex"],
-          "shorthands": ["none", "auto", "initial"],
-          "canonicalShorthands": ["none", "auto", "initial"],
+          "helpers": [
+            "flex"
+          ],
+          "shorthands": [
+            "none",
+            "auto",
+            "initial"
+          ],
+          "canonicalShorthands": [
+            "none",
+            "auto",
+            "initial"
+          ],
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
-          "examples": ["flex=\"none\"", "flex={flex(1, 1, rem(20))}"]
+          "examples": [
+            "flex=\"none\"",
+            "flex={flex(1, 1, rem(20))}"
+          ]
         }
       ],
       "useWhen": [
@@ -1989,8 +2312,8 @@
         "Let one bounded list own vertical scrolling, flex growth, or one or more physical-edge dividers.",
         "Choose a finite gap shorthand such as xs or m, or compose a typed length with @kerfjs/ui/css-values when the spacing scale is insufficient.",
         "Use a finite flex keyword or the flex() builder when List participates in flexible layout.",
-        "Apply the standard text or control inset to selected physical sides without an application wrapper."
-        ,"Align children horizontally or distribute them vertically with the same physical alignment vocabulary as Row."
+        "Apply the standard text or control inset to selected physical sides without an application wrapper.",
+        "Align children horizontally or distribute them vertically with the same physical alignment vocabulary as Row."
       ],
       "avoidWhen": [
         "Do not use List as semantic list markup; use ul/ol when list semantics are required and apply layout deliberately.",
@@ -2013,7 +2336,9 @@
         "left/center/right/full horizontal alignment",
         "top/middle/bottom/full vertical alignment",
         "top/right/bottom/left divider combinations",
-        "top/right/bottom/left text and control inset combinations"
+        "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"
       ],
       "accessibility": [
         "List adds layout only and no list role; children retain responsibility for their native or ARIA semantics.",
@@ -2168,7 +2493,9 @@
           "canonicalShorthands": [],
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
-          "examples": ["className=\"app-row\""]
+          "examples": [
+            "className=\"app-row\""
+          ]
         }
       ],
       "useWhen": [
@@ -2294,7 +2621,9 @@
           "canonicalShorthands": [],
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
-          "examples": ["className=\"app-row\""]
+          "examples": [
+            "className=\"app-row\""
+          ]
         }
       ],
       "useWhen": [
@@ -2507,7 +2836,9 @@
       "uses": [
         "tabs",
         "tab-bar",
-        "toolbar-control-group"
+        "toolbar-control-group",
+        "text",
+        "wa-card"
       ],
       "purpose": "Show AppTab and TabBar in a complete controlled composition.",
       "publicExports": [],
@@ -2728,7 +3059,24 @@
         {
           "export": "wireTabBars",
           "import": "@kerfjs/ui/wire-tab-bars",
-          "required": true
+          "required": true,
+          "stateAttributes": [
+            {
+              "name": "data-tab-dragging",
+              "on": "AppTab (data-component=\"app-tab\")",
+              "meaning": "\"true\" on the tab being dragged."
+            },
+            {
+              "name": "data-tab-drop-position",
+              "on": "AppTab (data-component=\"app-tab\")",
+              "meaning": "\"before\" or \"after\" on the tab under the pointer: where the dragged tab would land."
+            },
+            {
+              "name": "data-tab-autoscroll",
+              "on": "kui-tab-bar__tabs",
+              "meaning": "\"start\" or \"end\" while a drag near that edge auto-scrolls the strip."
+            }
+          ]
         },
         {
           "export": "reorderTabs",
@@ -2932,7 +3280,19 @@
         {
           "export": "wireTokenSearchFields",
           "import": "@kerfjs/ui/wire-token-search-fields",
-          "required": true
+          "required": true,
+          "stateAttributes": [
+            {
+              "name": "data-token-search-text",
+              "on": "the text span inside kui-token-search__editor",
+              "meaning": "Marks the plain-text span the helper inserts when the editor is emptied."
+            },
+            {
+              "name": "data-empty",
+              "on": "the text span inside kui-token-search__editor",
+              "meaning": "\"true\" on that span while it holds no text."
+            }
+          ]
         }
       ],
       "publicClasses": [
@@ -3046,7 +3406,19 @@
         {
           "export": "wireResizableRegions",
           "import": "@kerfjs/ui/wire-resizable-regions",
-          "required": true
+          "required": true,
+          "stateAttributes": [
+            {
+              "name": "data-handle-inset",
+              "on": "kui-resizable-region",
+              "meaning": "Present while a clipping edge clamps the region: the handle and its focus ring sit inside the region instead of overhanging that edge."
+            },
+            {
+              "name": "data-resizing",
+              "on": "kui-resizable-region",
+              "meaning": "\"true\" during an active pointer drag of the handle."
+            }
+          ]
         },
         {
           "export": "clampRegionSize",
@@ -3072,6 +3444,7 @@
         "--kui-color-text-link",
         "--kui-focus-ring",
         "--kui-radius-s",
+        "--kui-resizable-region-edge-extent",
         "--kui-resizable-region-handle-active-color",
         "--kui-resizable-region-handle-color",
         "--kui-resizable-region-overlay-z",
@@ -3103,23 +3476,27 @@
       "publicExports": [
         "Select",
         "uiColor",
-        "colorVar"
+        "colorVar",
+        "foregroundColorVar"
       ],
       "cssValueProps": [
         {
           "path": "choices[].color",
           "grammar": "color",
-          "helpers": ["uiColor", "colorVar"],
+          "helpers": [
+            "uiColor",
+            "foregroundColorVar"
+          ],
           "shorthands": [],
           "canonicalShorthands": [],
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
-          "examples": ["color: uiColor(\"success\")", "color: colorVar(\"--app-choice-color\")"]
+          "examples": ["color: uiColor(\"success-on-quiet\")", "color: foregroundColorVar(\"--app-choice-color\")"]
         }
       ],
       "useWhen": [
         "Choose a controlled value from a moderate or long list, including grouped and icon-bearing choices.",
-        "Color an optional choice icon with uiColor() or colorVar(); the CssColor contract intentionally rejects lengths and raw color strings."
+        "Color an optional choice icon with a CssForegroundColor: uiColor() with a foreground token such as success-on-quiet, or foregroundColorVar() for an app-owned property. 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."
       ],
       "avoidWhen": [
         "Do not use for commands or a small choice set that should stay visible."
@@ -3570,35 +3947,92 @@
         {
           "path": "width",
           "grammar": "size",
-          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
-          "nonStandaloneHelpers": ["plus"],
-          "shorthands": ["auto", "min-content", "max-content", "fit-content"],
-          "canonicalShorthands": ["auto", "min-content", "max-content", "fit-content"],
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [
+            "auto",
+            "min-content",
+            "max-content",
+            "fit-content"
+          ],
+          "canonicalShorthands": [
+            "auto",
+            "min-content",
+            "max-content",
+            "fit-content"
+          ],
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
-          "examples": ["width={em(12)}", "width=\"fit-content\""]
+          "examples": [
+            "width={em(12)}",
+            "width=\"fit-content\""
+          ]
         },
         {
           "path": "height",
           "grammar": "size",
-          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
-          "nonStandaloneHelpers": ["plus"],
-          "shorthands": ["auto", "min-content", "max-content", "fit-content"],
-          "canonicalShorthands": ["auto", "min-content", "max-content", "fit-content"],
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
+          "shorthands": [
+            "auto",
+            "min-content",
+            "max-content",
+            "fit-content"
+          ],
+          "canonicalShorthands": [
+            "auto",
+            "min-content",
+            "max-content",
+            "fit-content"
+          ],
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
-          "examples": ["height={em(1.5)}"]
+          "examples": [
+            "height={em(1.5)}"
+          ]
         },
         {
           "path": "radius",
           "grammar": "length",
-          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
-          "nonStandaloneHelpers": ["plus"],
+          "helpers": [
+            "px",
+            "rem",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": [
+            "plus"
+          ],
           "shorthands": [],
           "canonicalShorthands": [],
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
-          "examples": ["radius={px(999)}"]
+          "examples": [
+            "radius={px(999)}"
+          ]
         }
       ],
       "useWhen": [
@@ -6412,13 +6846,17 @@
       "source": "kerf",
       "purpose": "Toolbar, navigation, content, and inspector shell with controlled resizing and explicit pane scroll owners.",
       "uses": [
+        "pane",
         "toolbar",
         "toolbar-text",
         "toolbar-control-group",
+        "row",
+        "grid",
+        "resize",
         "list-header",
         "list-item",
-        "resize",
         "value-table",
+        "lucide-icon",
         "layout"
       ],
       "useWhen": [
@@ -6455,10 +6893,15 @@
       "source": "kerf",
       "purpose": "Navigation sections with icon and iconless rows, a content-item surface, disclosure, and pane footer actions.",
       "uses": [
+        "pane",
         "list-header",
         "list-item",
+        "list",
+        "text",
         "toolbar",
-        "toolbar-control-group"
+        "toolbar-control-group",
+        "lucide-icon",
+        "layout"
       ],
       "useWhen": [
         "A workspace sidebar needs the shared toolbar/content/footer pane model, 24px major section rhythm, and 44px row and utility-action targets."
@@ -6497,6 +6940,9 @@
         "toolbar",
         "toolbar-control-group",
         "toolbar-text",
+        "list",
+        "list-inset-text",
+        "text",
         "state-banner",
         "layout"
       ],
@@ -6532,14 +6978,17 @@
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
-      "purpose": "Production modal containing a Toolbar heading, navigable record master list, and ValueTable detail.",
+      "purpose": "Production modal whose labeled Web Awesome header frames a SplitView record list and ValueTable detail, becoming a full-screen drill-down on compact devices.",
       "uses": [
-        "toolbar",
-        "toolbar-control-group",
-        "toolbar-text",
+        "surface-scaffold",
+        "split-view",
+        "nav-stack",
+        "row",
+        "list",
         "list-header",
         "list-item",
         "value-table",
+        "lucide-icon",
         "wa-dialog",
         "wa-button"
       ],
@@ -6552,11 +7001,12 @@
       "appOwns": [
         "open state",
         "selected record",
+        "pushed compact detail",
         "dismiss policy",
         "record actions"
       ],
       "accessibility": [
-        "Web Awesome owns modal focus and Escape; the application adapter restores the invoking control after hide, and Toolbar plus ToolbarText supply the visible hierarchy."
+        "Web Awesome owns modal focus, Escape, and the labeled header with its close control; the application adapter restores the invoking control after hide, and the compact NavStack back control returns to the list."
       ],
       "delivery": {
         "sideEffects": [
@@ -6579,8 +7029,11 @@
       "purpose": "One visible publishing-form surface with Toolbar heading hierarchy, fields and actions on the shared 8px control gutter, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface.",
       "uses": [
         "toolbar",
-        "toolbar-control-group",
         "toolbar-text",
+        "list",
+        "list-inset-text",
+        "text",
+        "row",
         "select",
         "state-banner",
         "wa-input",
@@ -6623,9 +7076,12 @@
       "source": "kerf",
       "purpose": "Deterministic loading, empty, populated, stale refresh, and error states around one stable list workspace.",
       "uses": [
+        "pane",
         "toolbar",
         "toolbar-control-group",
         "toolbar-text",
+        "list-item",
+        "row",
         "state-banner",
         "empty-state",
         "loading-spinner",
@@ -6670,7 +7126,11 @@
         "toolbar-control-group",
         "segmented-control",
         "select",
-        "lucide-icon"
+        "lucide-icon",
+        "grid",
+        "list",
+        "list-inset-text",
+        "text"
       ],
       "useWhen": [
         "A dense workspace toolbar mixes a few distinct control semantics."
@@ -6707,8 +7167,12 @@
       "source": "kerf",
       "purpose": "A push/pop navigation stack drill-down with animated slides and a live device class.",
       "uses": [
+        "nav-stack",
+        "list",
         "list-header",
         "list-item",
+        "row",
+        "text",
         "lucide-icon",
         "layout"
       ],
@@ -6746,9 +7210,13 @@
       "source": "kerf",
       "purpose": "A record inspector whose per-record values load asynchronously — every value-bearing component takes a shared placeholder flag, so the same chrome renders a faithful loading state and then the populated record.",
       "uses": [
+        "pane",
         "toolbar",
         "toolbar-control-group",
         "toolbar-text",
+        "list-inset-text",
+        "text",
+        "list",
         "value-table",
         "select",
         "segmented-control",
@@ -6791,11 +7259,20 @@
       "source": "kerf",
       "purpose": "A mini app frame whose left navigation rail and bottom activity drawer are standalone CollapsiblePanels driven by wireSidebar: per-side collapse/expand toggles, focus move-in and restore, a dismissable compact overlay, and per-panel persistence.",
       "uses": [
+        "collapsible-panel",
+        "pane",
+        "row",
+        "list",
+        "grid",
         "list-header",
         "list-item",
+        "text",
         "toolbar",
         "toolbar-control-group",
-        "toolbar-text"
+        "toolbar-text",
+        "value-table",
+        "lucide-icon",
+        "layout"
       ],
       "useWhen": [
         "A rail or drawer must collapse and expand outside a full Workbench shell, keeping the app's collapsed signals, sizes, and content while the wire owns toggle, focus, the compact overlay, and persistence."