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

package/ai/component-catalog.json

@@ -155,7 +155,8 @@
       ],
       "appOwns": [
         "icon choice",
-        "meaningful label"
+        "meaningful label",
+        "optional foreground color"
       ],
       "variants": [
         "decorative",
@@ -168,6 +169,11 @@
           "title": "Solid selected glyph",
           "description": "The solid appearance fills a compatible Lucide glyph with currentColor while retaining its stroke and accessible name policy.",
           "code": "<LucideIcon icon={Star} name=\"star\" appearance=\"solid\" />"
+        },
+        {
+          "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')} />"
         }
       ],
       "accessibility": [
@@ -342,6 +348,7 @@
         "--kui-font-s",
         "--kui-font-m",
         "--kui-font-l",
+        "--kui-font-xl",
         "--kui-font-2xl",
         "--kui-font-weight-semibold",
         "--kui-space-none",
@@ -2706,6 +2713,17 @@
         "calc",
         "flex"
       ],
+      "publicExportImports": {
+        "px": "@kerfjs/ui/css-values",
+        "rem": "@kerfjs/ui/css-values",
+        "em": "@kerfjs/ui/css-values",
+        "pct": "@kerfjs/ui/css-values",
+        "space": "@kerfjs/ui/css-values",
+        "lengthVar": "@kerfjs/ui/css-values",
+        "plus": "@kerfjs/ui/css-values",
+        "calc": "@kerfjs/ui/css-values",
+        "flex": "@kerfjs/ui/css-values"
+      },
       "cssValueProps": [
         {
           "path": "gap",
@@ -2869,7 +2887,7 @@
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Configurable section headings with full-width or shrink-wrapped inline presentation, semantic count/status indicators, density, group dividers, a logical-end action, disclosure states, and protected native-popover trigger metadata.",
+      "description": "Configurable section headings with five independent label sizes, full-width or shrink-wrapped inline presentation, semantic count/status indicators, density, group dividers, a logical-end action, disclosure states, and protected native-popover trigger metadata.",
       "uses": [
         "badge",
         "lucide-icon",
@@ -2904,6 +2922,7 @@
       ],
       "variants": [
         "heading",
+        "label sizes xs, sm (default), m, l, xl",
         "count",
         "badge",
         "action",
@@ -4169,15 +4188,23 @@
         "Select",
         "uiColor",
         "colorVar",
-        "foregroundColorVar"
+        "foregroundColorVar",
+        "foregroundColor"
       ],
+      "publicExportImports": {
+        "uiColor": "@kerfjs/ui/css-values",
+        "colorVar": "@kerfjs/ui/css-values",
+        "foregroundColorVar": "@kerfjs/ui/css-values",
+        "foregroundColor": "@kerfjs/ui/css-values"
+      },
       "cssValueProps": [
         {
           "path": "choices[].color",
           "grammar": "color",
           "helpers": [
             "uiColor",
-            "foregroundColorVar"
+            "foregroundColorVar",
+            "foregroundColor"
           ],
           "shorthands": [],
           "canonicalShorthands": [],
@@ -4185,13 +4212,14 @@
           "rawPolicy": "forbid",
           "examples": [
             "color: uiColor(\"success-on-quiet\")",
-            "color: foregroundColorVar(\"--app-choice-color\")"
+            "color: foregroundColorVar(\"--app-choice-color\")",
+            "color: foregroundColor(\"rebeccapurple\")"
           ]
         }
       ],
       "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, 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."
+        "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."
       ],
       "avoidWhen": [
         "Do not use for commands or a small choice set that should stay visible."

package/ai/component-composition.json

@@ -126,7 +126,12 @@
       "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
       "state": [
         { "id": "icon choice", "owner": "application", "required": false },
-        { "id": "meaningful label", "owner": "application", "required": false }
+        { "id": "meaningful label", "owner": "application", "required": false },
+        {
+          "id": "optional foreground color",
+          "owner": "application",
+          "required": false
+        }
       ],
       "wiring": {
         "required": false,
@@ -282,6 +287,7 @@
           "--kui-font-s",
           "--kui-font-m",
           "--kui-font-l",
+          "--kui-font-xl",
           "--kui-font-2xl",
           "--kui-font-weight-semibold",
           "--kui-space-none",
@@ -3493,14 +3499,15 @@
         {
           "path": "choices[].color",
           "grammar": "color",
-          "helpers": ["uiColor", "foregroundColorVar"],
+          "helpers": ["uiColor", "foregroundColorVar", "foregroundColor"],
           "shorthands": [],
           "canonicalShorthands": [],
           "exceptionalShorthands": [],
           "rawPolicy": "forbid",
           "examples": [
             "color: uiColor(\"success-on-quiet\")",
-            "color: foregroundColorVar(\"--app-choice-color\")"
+            "color: foregroundColorVar(\"--app-choice-color\")",
+            "color: foregroundColor(\"rebeccapurple\")"
           ]
         }
       ],

package/ai/components/foundation.md

@@ -55,7 +55,7 @@ Margin: none · border: none · padding: none (layout role: foundation). `self`
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.
 
-Public tokens it reads: `--kui-font-sans`, `--kui-font-mono`, `--kui-font-2xs`, `--kui-font-xs`, `--kui-font-s`, `--kui-font-m`, `--kui-font-l`, `--kui-font-2xl`, `--kui-font-weight-semibold`, `--kui-space-none`, `--kui-space-2xs`, `--kui-space-xs`, `--kui-space-s`, `--kui-space-m`, `--kui-space-l`, `--kui-space-xl`, `--kui-bp-mobile`, `--kui-bp-tablet`, `--kui-bp-desktop`, `--kui-bp-xl-desktop`, `--kui-layout-inline-margin`, `--kui-layout-item-border-width`, `--kui-layout-item-padding`, `--kui-layout-item-gap`, `--kui-layout-content-gap`, `--kui-layout-control-gap`, `--kui-layout-metadata-gap`, `--kui-layout-highlight-inset`, `--kui-layout-rounded-radius`, `--kui-layout-pill-radius`, `--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`, `--kui-radius-circle`, `--kui-radius-pill`, `--kui-disclosure-icon-scale`, `--kui-color-surface`, `--kui-color-surface-raised`, `--kui-color-surface-lowered`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-text-link`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-border-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-border-loud`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-loud`, `--kui-color-brand-fill-loud`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-brand-border-quiet`, `--kui-color-brand-border-normal`, `--kui-color-brand-border-loud`, `--kui-color-brand-on-quiet`, `--kui-color-brand-on-normal`, `--kui-color-brand-on-loud`, `--kui-color-brand-on-fill`, `--kui-color-pop-fill-loud`, `--kui-color-pop-fill-quiet`, `--kui-color-pop-fill-normal`, `--kui-color-pop-border-quiet`, `--kui-color-pop-border-normal`, `--kui-color-pop-border-loud`, `--kui-color-pop-on-quiet`, `--kui-color-pop-on-normal`, `--kui-color-pop-on-loud`, `--kui-color-pop-on-fill`, `--kui-color-success-fill-loud`, `--kui-color-success-fill-quiet`, `--kui-color-success-fill-normal`, `--kui-color-success-border-quiet`, `--kui-color-success-border-normal`, `--kui-color-success-border-loud`, `--kui-color-success-on-quiet`, `--kui-color-success-on-normal`, `--kui-color-success-on-loud`, `--kui-color-success-on-fill`, `--kui-color-warning-fill-loud`, `--kui-color-warning-fill-quiet`, `--kui-color-warning-fill-normal`, `--kui-color-warning-border-quiet`, `--kui-color-warning-border-normal`, `--kui-color-warning-border-loud`, `--kui-color-warning-on-quiet`, `--kui-color-warning-on-normal`, `--kui-color-warning-on-loud`, `--kui-color-warning-on-fill`, `--kui-color-danger-fill-loud`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-fill-normal`, `--kui-color-danger-border-quiet`, `--kui-color-danger-border-normal`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-color-danger-on-normal`, `--kui-color-danger-on-loud`, `--kui-color-danger-on-fill`, `--kui-focus-ring`, `--kui-shadow-s`, `--kui-shadow-l`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-font-sans`, `--kui-font-mono`, `--kui-font-2xs`, `--kui-font-xs`, `--kui-font-s`, `--kui-font-m`, `--kui-font-l`, `--kui-font-xl`, `--kui-font-2xl`, `--kui-font-weight-semibold`, `--kui-space-none`, `--kui-space-2xs`, `--kui-space-xs`, `--kui-space-s`, `--kui-space-m`, `--kui-space-l`, `--kui-space-xl`, `--kui-bp-mobile`, `--kui-bp-tablet`, `--kui-bp-desktop`, `--kui-bp-xl-desktop`, `--kui-layout-inline-margin`, `--kui-layout-item-border-width`, `--kui-layout-item-padding`, `--kui-layout-item-gap`, `--kui-layout-content-gap`, `--kui-layout-control-gap`, `--kui-layout-metadata-gap`, `--kui-layout-highlight-inset`, `--kui-layout-rounded-radius`, `--kui-layout-pill-radius`, `--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`, `--kui-radius-circle`, `--kui-radius-pill`, `--kui-disclosure-icon-scale`, `--kui-color-surface`, `--kui-color-surface-raised`, `--kui-color-surface-lowered`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-text-link`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-border-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-border-loud`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-loud`, `--kui-color-brand-fill-loud`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-brand-border-quiet`, `--kui-color-brand-border-normal`, `--kui-color-brand-border-loud`, `--kui-color-brand-on-quiet`, `--kui-color-brand-on-normal`, `--kui-color-brand-on-loud`, `--kui-color-brand-on-fill`, `--kui-color-pop-fill-loud`, `--kui-color-pop-fill-quiet`, `--kui-color-pop-fill-normal`, `--kui-color-pop-border-quiet`, `--kui-color-pop-border-normal`, `--kui-color-pop-border-loud`, `--kui-color-pop-on-quiet`, `--kui-color-pop-on-normal`, `--kui-color-pop-on-loud`, `--kui-color-pop-on-fill`, `--kui-color-success-fill-loud`, `--kui-color-success-fill-quiet`, `--kui-color-success-fill-normal`, `--kui-color-success-border-quiet`, `--kui-color-success-border-normal`, `--kui-color-success-border-loud`, `--kui-color-success-on-quiet`, `--kui-color-success-on-normal`, `--kui-color-success-on-loud`, `--kui-color-success-on-fill`, `--kui-color-warning-fill-loud`, `--kui-color-warning-fill-quiet`, `--kui-color-warning-fill-normal`, `--kui-color-warning-border-quiet`, `--kui-color-warning-border-normal`, `--kui-color-warning-border-loud`, `--kui-color-warning-on-quiet`, `--kui-color-warning-on-normal`, `--kui-color-warning-on-loud`, `--kui-color-warning-on-fill`, `--kui-color-danger-fill-loud`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-fill-normal`, `--kui-color-danger-border-quiet`, `--kui-color-danger-border-normal`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-color-danger-on-normal`, `--kui-color-danger-on-loud`, `--kui-color-danger-on-fill`, `--kui-focus-ring`, `--kui-shadow-s`, `--kui-shadow-l`. Set a token only where its public contract allows; prefer a prop.
 
 Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
 

package/ai/components/list-header.md

@@ -4,7 +4,7 @@
 
 `@kerfjs/ui:list-header` · Kerf UI · component · Navigation
 
-Configurable section headings with full-width or shrink-wrapped inline presentation, semantic count/status indicators, density, group dividers, a logical-end action, disclosure states, and protected native-popover trigger metadata.
+Configurable section headings with five independent label sizes, full-width or shrink-wrapped inline presentation, semantic count/status indicators, density, group dividers, a logical-end action, disclosure states, and protected native-popover trigger metadata.
 
 ## When to use
 
@@ -34,6 +34,7 @@ Exact prop names and types: [`@kerfjs/ui/list-header`](../public-api-signatures-
 **Variants (configure, do not restyle):**
 
 - heading
+- label sizes xs, sm (default), m, l, xl
 - count
 - badge
 - action

package/ai/components/list.md

@@ -26,14 +26,15 @@ Standardize vertical component layout, optional physical-side text/control inset
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/list` — exports `List`, `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `plus`, `calc`, `flex`.
+- JavaScript: `@kerfjs/ui/list` — exports `List`.
+- JavaScript: `@kerfjs/ui/css-values` — exports `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `plus`, `calc`, `flex`.
 - CSS: the browser build of `@kerfjs/ui/list` pulls its CSS automatically; import `@kerfjs/ui/list.css` manually only without the `browser` export condition.
 - Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
 - Declared side effects: browser-condition-css.
 
 ## Props
 
-Exact prop names and types: [`@kerfjs/ui/list`](../public-api-signatures-v1.md#kerfjsuilist), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+Exact prop names and types: [`@kerfjs/ui/list`](../public-api-signatures-v1.md#kerfjsuilist), [`@kerfjs/ui/css-values`](../public-api-signatures-v1.md#kerfjsuicss-values), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
 
 **Variants (configure, do not restyle):**
 

package/ai/components/lucide-icon.md

@@ -43,7 +43,7 @@ Exact prop names and types: [`@kerfjs/ui/lucide-icon`](../public-api-signatures-
 
 ## State and wiring
 
-**The app owns:** icon choice; meaningful label.
+**The app owns:** icon choice; meaningful label; optional foreground color.
 
 No wiring helper.
 
@@ -65,6 +65,14 @@ The solid appearance fills a compatible Lucide glyph with currentColor while ret
 <LucideIcon icon={Star} name="star" appearance="solid" />
 ```
 
+### Semantic icon color
+
+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.
+
+```tsx
+<LucideIcon icon={Bell} name="alert" color={uiColor('warning-on-quiet')} />
+```
+
 ## Styling boundary
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.

package/ai/components/select.md

@@ -11,7 +11,7 @@ Controlled Web Awesome select with typed single or multiple values, disabled cho
 Choose one or more controlled values, keep unavailable choices visible, and optionally select all enabled choices or clear a multiple selection.
 
 - 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, 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.
+- 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.
 
 **Not when:**
 
@@ -25,14 +25,15 @@ Choose one or more controlled values, keep unavailable choices visible, and opti
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/select` — exports `Select`, `uiColor`, `colorVar`, `foregroundColorVar`.
+- JavaScript: `@kerfjs/ui/select` — exports `Select`.
+- JavaScript: `@kerfjs/ui/css-values` — exports `uiColor`, `colorVar`, `foregroundColorVar`, `foregroundColor`.
 - CSS: the browser build of `@kerfjs/ui/select` pulls its CSS automatically; import `@kerfjs/ui/select.css` manually only without the `browser` export condition.
 - Registration: import `@kerfjs/ui/select/register` once (a side effect).
 - Declared side effects: custom-element-registration.
 
 ## Props
 
-Exact prop names and types: [`@kerfjs/ui/select`](../public-api-signatures-v1.md#kerfjsuiselect) in `public-api-signatures-v1.md`. Do not infer props from examples.
+Exact prop names and types: [`@kerfjs/ui/select`](../public-api-signatures-v1.md#kerfjsuiselect), [`@kerfjs/ui/css-values`](../public-api-signatures-v1.md#kerfjsuicss-values) in `public-api-signatures-v1.md`. Do not infer props from examples.
 
 **Variants (configure, do not restyle):**
 
@@ -58,7 +59,7 @@ Exact prop names and types: [`@kerfjs/ui/select`](../public-api-signatures-v1.md
 
 **CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
 
-- `choices[].color`: color grammar; raw values: forbid; helpers `uiColor`, `foregroundColorVar` — e.g. `color: uiColor("success-on-quiet")`
+- `choices[].color`: color grammar; raw values: forbid; helpers `uiColor`, `foregroundColorVar`, `foregroundColor` — e.g. `color: uiColor("success-on-quiet")`
 
 ## Composition
 

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.73` and `kerfjs@5.0.0-beta.73`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.75` and `kerfjs@5.0.0-beta.75`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 
@@ -110,8 +110,13 @@ declare function colorVar(name: `--${string}`, fallback?: CssColor): CssColor;
  * accepts only {@link CssForegroundColor}, such as `SelectChoice.color`.
  */
 declare function foregroundColorVar(name: `--${string}`, fallback?: CssForegroundColor): CssForegroundColor;
+/**
+ * Use an application-chosen CSS color for foreground content. The browser
+ * resolves the color syntax; this checks only that it is one declaration value.
+ */
+declare function foregroundColor(value: string): CssForegroundColor;
 
-export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssForegroundColor, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColor, type UiColorName, type UiForegroundColorName, type UiSpaceName, calc, colorVar, em, flex, foregroundColorVar, lengthVar, pct, plus, px, rem, remify, space, uiColor };
+export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssForegroundColor, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColor, type UiColorName, type UiForegroundColorName, type UiSpaceName, calc, colorVar, em, flex, foregroundColor, foregroundColorVar, lengthVar, pct, plus, px, rem, remify, space, uiColor };
 ```
 
 ## `@kerfjs/ui/disclosure-arrow`
@@ -527,6 +532,7 @@ type ListHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undef
     'data-has-badge'?: never;
     'data-has-count'?: never;
     'data-density'?: never;
+    'data-size'?: never;
     'data-divider'?: never;
     'data-inline'?: never;
     'data-width'?: never;
@@ -543,6 +549,8 @@ type ListHeaderTriggerAttributes = Readonly<Record<`data-${string}`, string | un
 }>;
 interface ListHeaderBaseProps {
     label: string;
+    /** Visual label size, independent of the native heading level. Default `sm`. */
+    size?: 'xs' | 'sm' | 'm' | 'l' | 'xl';
     density?: 'standard' | 'compact';
     divider?: 'none' | 'before' | 'after' | 'both';
     /** Shrink-wrap the header without its default outer margin, border, or padding. */
@@ -614,7 +622,7 @@ type ListHeaderIndicatorProps = {
     status?: SafeHtml;
 };
 type ListHeaderProps = ListHeaderBaseProps & ListHeaderIndicatorProps & ListHeaderModeProps;
-declare function ListHeader({ label, headingLevel, count, countLabel, badge, status, density, divider, inline, width, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, slot, }: ListHeaderProps): SafeHtml;
+declare function ListHeader({ label, size, headingLevel, count, countLabel, badge, status, density, divider, inline, width, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, slot, }: ListHeaderProps): SafeHtml;
 
 export { ListHeader, type ListHeaderProps };
 ```
@@ -2868,6 +2876,7 @@ export { EmptyState, type EmptyStateProps };
 import * as kerfjs from 'kerfjs';
 import { LucideIconSize } from './lucide-icon.js';
 import 'lucide';
+import './css-values.js';
 
 type LoadingSpinnerSize = LucideIconSize;
 interface LoadingSpinnerProps {
@@ -3259,6 +3268,7 @@ export { Chip, type ChipProps };
 ```ts
 import * as kerfjs from 'kerfjs';
 import { IconNode } from 'lucide';
+import { CssForegroundColor } from './css-values.js';
 
 type LucideNode = IconNode;
 type LucideIconSize = 'xs' | 's' | 'm' | 'l' | 'xl' | number;
@@ -3268,6 +3278,8 @@ interface LucideIconProps {
     /** Outline by default; solid fills compatible glyphs with the current text color. */
     appearance?: 'outline' | 'solid';
     className?: string;
+    /** Foreground color; omit to inherit the surrounding text color. */
+    color?: CssForegroundColor;
     label?: string;
     /** Named icon scale or positive pixel size, converted to rem. Omit for 1em. */
     size?: LucideIconSize;
@@ -3275,7 +3287,7 @@ interface LucideIconProps {
     slot?: string;
 }
 /** Render a Lucide-compatible icon node without copying icon SVG strings. */
-declare function LucideIcon({ icon, name, appearance, className, label, size, slot, }: LucideIconProps): kerfjs.SafeHtml;
+declare function LucideIcon({ icon, name, appearance, className, color, label, size, slot, }: LucideIconProps): kerfjs.SafeHtml;
 
 export { LucideIcon, type LucideIconProps, type LucideIconSize, type LucideNode };
 ```

package/ai/skill.md

@@ -253,6 +253,8 @@ Use `--kui-resizable-region-background` for a region surface and `contentOverflo
 
 Use `ListItem density="spacious"` for larger option rows, `multiline` plus `multilineIconAlign="center"` when its icon should center on wrapped copy, `divider` for row separators, and `state="drag-target"` for the drop target treatment. Public `--kui-list-item-*` tokens adjust row, icon, label, and trailing geometry and color; ListHeader height, title padding, and border tokens adjust section density.
 
+Set `ListHeader.size` to `xs`, `sm`, `m`, `l`, or `xl` for label scale. The default `sm` remains the small uppercase style shared with `FieldLabel`; `xs` is 2xs and capitalized, while `m`/`l`/`xl` match themed h5/h4/h3 typography. Choose `headingLevel` separately from the document outline.
+
 For a filled command list, scope `--kui-list-item-background`, `--kui-list-item-color`, `--kui-list-item-border`, `--kui-list-item-hover-background`, `--kui-list-item-hover-border`, `--kui-list-item-selected-background`, `--kui-list-item-selected-color`, and `--kui-list-item-selected-border` at the List or ListItem boundary. Keep global neutral and brand border colors semantic.
 
 Use `Toolbar responsive="trailing-priority"` when an expanded trailing search needs a full second row below its heading at `responsiveAt`. Configure a leading minimum width, trailing gap and justification, or zone inline padding with the public `--kui-toolbar-*` tokens rather than selectors into toolbar zones.
@@ -307,6 +309,8 @@ For prominent content text, use `Text size="large"`; use `size="xlarge"` for dis
 
 For removable tags use `Chip`, with `removeAction` for delegated handling and a specific `removeLabel` for the native button. `itemId` identifies the tag; the app owns removal. `size="compact"` and `disabled` replace app styling of raw `wa-tag` internals. Use `Badge` for non-interactive metadata.
 
+For an icon with a specific meaning, set `LucideIcon.color` using `uiColor('warning-on-quiet')` or another foreground token. Use `foregroundColorVar('--app-icon-color')` for an app-owned property or `foregroundColor('#8b5cf6')` for a direct custom CSS color. Omit the prop to inherit text color. Outline stroke and solid fill both follow the chosen color; size, appearance, label, and slot remain separate props. Avoid pale fill tokens as foregrounds.
+
 For `Select`, mark an unavailable choice with `disabled` and optionally `disabledReason`. In a multiple Select, `selectAllLabel` and `clearLabel` opt in to localized footer actions that select enabled choices or clear the selection through normal input/change events; the app still owns the controlled `value`.
 
 For nested action menus, use `PopupMenuItem.submenu` with item, heading, and divider entries; headings and dividers do not enter keyboard navigation. Items support `checked`, `icon`, `details`, `disabledReason`, and `tone`. The app owns choice state. For a right-click menu, use `PopupMenu` with `context: true` and call `openPopupMenuAt` from the app's `contextmenu` handler; the package positions and opens the menu. Call `closePopupMenu` for programmatic dismissal.

package/ai/webawesome-jsx-signatures-v1.md

@@ -1,6 +1,6 @@
 # Web Awesome JSX signatures for the UI authoring corpus
 
-Generated from the emitted `@kerfjs/ui@5.0.0-beta.73` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.75` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
 
 ```ts
 import { KerfCustomElement } from 'kerfjs/jsx-runtime';

package/dist/app-tab.js

@@ -1,4 +1,4 @@
-export { AppTab } from './chunk-7KHKLG5C.js';
+export { AppTab } from './chunk-V4GAQ74C.js';
 
 
 

package/dist/catalog.js

@@ -1,14 +1,14 @@
-import { Workbench } from './chunk-33EOFAUN.js';
+import { Workbench } from './chunk-O5GM2JAM.js';
 
 
 import { PopupMenu } from './chunk-4NG4Y2Q6.js';
 
-import { Row } from './chunk-VZOFZPSO.js';
-import { ListHeader } from './chunk-HFBI4ZGP.js';
+import { Row } from './chunk-SX7FJXPJ.js';
+import { ListHeader } from './chunk-PL26TKNK.js';
 import { Text } from './chunk-YDGNU2OD.js';
 import { ListInsetText } from './chunk-DG6G5EPF.js';
-import { ListItem } from './chunk-6LAQWWEX.js';
-import { ToolbarText } from './chunk-IJNYCPAU.js';
+import { ListItem } from './chunk-HXTAPIHQ.js';
+import { ToolbarText } from './chunk-HKVJ5MW3.js';
 
 
 
@@ -16,11 +16,11 @@ import { ToolbarText } from './chunk-IJNYCPAU.js';
 
 
 
-import { List } from './chunk-W2AC6Q2A.js';
+import { List } from './chunk-4FEVHE7C.js';
 
-import { ToolbarControlGroup, ToolbarActionLink } from './chunk-BGD7EHUE.js';
+import { ToolbarControlGroup, ToolbarActionLink } from './chunk-TOICTHR2.js';
 import { Toolbar } from './chunk-RGS4WX2M.js';
-import { LucideIcon } from './chunk-WTSNV5RG.js';
+import { LucideIcon } from './chunk-DUBUXJA3.js';
 
 import { filterDataAttributes } from './chunk-SRSJO5QE.js';
 
@@ -136,7 +136,8 @@ function CatalogSectionEntries({
         status: entry.tags?.join(" \xB7 "),
         selected: active === entry.id,
         title: entry.description,
-        multiline: true
+        multiline: true,
+        rootAttributes: { "data-catalog-entry-name": entry.name }
       }
     )) })
   ] });
@@ -148,25 +149,43 @@ function CatalogSecondarySections({
   toggleAction
 }) {
   const open = !group.collapsible || Boolean(group.expanded);
-  return /* @__PURE__ */ jsxs(List, { dividerSides: "t", controlInsets: "t", children: [
-    group.collapsible ? /* @__PURE__ */ jsx(
-      ListHeader,
-      {
-        label: group.label,
-        toggle: true,
-        expanded: open,
-        action: toggleAction
-      }
-    ) : /* @__PURE__ */ jsx(ListHeader, { label: group.label }),
-    open ? /* @__PURE__ */ jsx(List, { gap: "m", rootAttributes: { "data-catalog-secondary": "" }, children: group.sections.map((section) => /* @__PURE__ */ jsx(
-      CatalogSectionEntries,
-      {
-        section,
-        active,
-        selectAction
-      }
-    )) }) : null
-  ] });
+  return /* @__PURE__ */ jsxs(
+    List,
+    {
+      dividerSides: "t",
+      controlInsets: "t",
+      rootAttributes: { "data-catalog-secondary-group": group.label },
+      children: [
+        group.collapsible ? /* @__PURE__ */ jsx(
+          ListHeader,
+          {
+            label: group.label,
+            toggle: true,
+            expanded: open,
+            action: toggleAction
+          }
+        ) : /* @__PURE__ */ jsx(ListHeader, { label: group.label }),
+        /* @__PURE__ */ jsx(
+          List,
+          {
+            gap: "m",
+            rootAttributes: {
+              "data-catalog-secondary": "",
+              "data-catalog-secondary-collapsed": String(!open)
+            },
+            children: group.sections.map((section) => /* @__PURE__ */ jsx(
+              CatalogSectionEntries,
+              {
+                section,
+                active,
+                selectAction
+              }
+            ))
+          }
+        )
+      ]
+    }
+  );
 }
 function CatalogSectionList({
   sections,
@@ -193,6 +212,17 @@ function CatalogSidebar({
 }) {
   return /* @__PURE__ */ jsx("nav", { "aria-label": `${brand.title} components`, children: /* @__PURE__ */ jsxs(List, { gap: "m", controlInsets: "b", children: [
     brand.subtitle ? /* @__PURE__ */ jsx(ListInsetText, { sides: "rl", children: /* @__PURE__ */ jsx(Text, { variant: "span", size: "compact", tone: "quiet", children: brand.subtitle }) }) : null,
+    /* @__PURE__ */ jsx(ListInsetText, { sides: "rl", children: /* @__PURE__ */ jsx(
+      "input",
+      {
+        class: "kui-catalog__filter",
+        type: "search",
+        "aria-label": "Filter catalog",
+        placeholder: "Filter items or headings",
+        autocomplete: "off",
+        "data-catalog-filter": true
+      }
+    ) }),
     /* @__PURE__ */ jsx(
       CatalogSectionList,
       {
@@ -210,6 +240,14 @@ function CatalogSidebar({
         toggleAction: toggleSecondaryAction
       }
     ) : null,
+    /* @__PURE__ */ jsx(
+      ListInsetText,
+      {
+        sides: "rl",
+        rootAttributes: { "data-catalog-filter-empty": "" },
+        children: /* @__PURE__ */ jsx(Text, { variant: "span", tone: "quiet", children: "No matching items" })
+      }
+    ),
     footer
   ] }) });
 }