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

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.74` and `kerfjs@5.0.0-beta.74`. 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.76` and `kerfjs@5.0.0-beta.76`. 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`
@@ -142,9 +147,9 @@ export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { PaneSeparatorSide } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as Sides } from './sides-BPSWde0A.js';
+import { PaneSeparatorSide } from './pane.js';
 
 type ToolbarPosition = 'header' | 'footer';
 interface ToolbarProps {
@@ -358,8 +363,8 @@ export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, ty
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { CssLength } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
 
 /** Where a {@link FloatingToolbar} floats within its positioned container. */
 type FloatingToolbarPosition = 'bottom' | 'bottom-start' | 'bottom-end' | 'top' | 'top-start' | 'top-end';
@@ -626,11 +631,11 @@ export { ListHeader, type ListHeaderProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { H as HorizontalAlignment, L as ListVerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 export { V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
-import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as Sides } from './sides-BPSWde0A.js';
+import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
 
 type ListRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -893,7 +898,10 @@ export { ListInsetText, type ListInsetTextProps, Sides };
 ```ts
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
 
+/** Base surface treatment or semantic status colors. */
+type ContentItemAppearance = 'transparent' | 'surface' | SemanticTone;
 /** Whether the item's always-reserved 1px border is transparent or visible. */
 type ContentItemFrame = 'none' | 'framed';
 /** Corner shape: the 12px rounded rectangle or the 22px pill. */
@@ -902,9 +910,11 @@ type ContentItemShape = 'rounded' | 'pill';
 type ContentItemSelectionMode = 'none' | 'single' | 'multiple' | 'toggle';
 type ContentItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
+    'data-appearance'?: never;
 }>;
 type ContentItemInteractiveRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
+    'data-appearance'?: never;
     'data-action'?: never;
     'data-item-id'?: never;
     'data-interactive'?: never;
@@ -914,6 +924,12 @@ type ContentItemInteractiveRootAttributes = Readonly<Record<`data-${string}`, st
     'data-kui-pressed'?: never;
 }>;
 interface ContentItemBaseProps {
+    /**
+     * Coordinated background, border, and foreground colors. `transparent`
+     * preserves the surrounding surface; `surface` paints the base surface;
+     * semantic values match StateBanner. Defaults to `transparent`.
+     */
+    appearance?: ContentItemAppearance;
     /** Item content; a plain string is allowed for bare copy. */
     children?: KerfUiContent | string;
     /**
@@ -969,9 +985,9 @@ type ContentItemProps = ContentItemBaseProps & ({
  * border (transparent unless `framed`), 8px padding, and a rounded or pill
  * radius. It owns that whole geometry, so wrappers must not add more.
  */
-declare function ContentItem({ children, frame, flush, shape, title, ariaLabel, focusTarget, interactive, action, itemId, selectionMode, selected, disabled, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
+declare function ContentItem({ appearance, children, frame, flush, shape, title, ariaLabel, focusTarget, interactive, action, itemId, selectionMode, selected, disabled, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
 
-export { ContentItem, type ContentItemFrame, type ContentItemProps, type ContentItemSelectionMode, type ContentItemShape };
+export { ContentItem, type ContentItemAppearance, type ContentItemFrame, type ContentItemProps, type ContentItemSelectionMode, type ContentItemShape, SemanticTone };
 ```
 
 ## `@kerfjs/ui/value-table`
@@ -1249,10 +1265,10 @@ export { type ScrollDividerTarget, type WireScrollDividersOptions, wireScrollDiv
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { PaneAppearance } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { ToolbarConfig } from './toolbar.js';
 import { ToolbarTextSize, HeadingLevel } from './toolbar-text.js';
+import { PaneAppearance } from './pane.js';
 import './sides-BPSWde0A.js';
 
 /**
@@ -1371,12 +1387,12 @@ export { type WireNavStackOptions, wireNavStack };
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { NavStackProps, NavStackView } from './nav-stack.js';
 import { ResizableRegionProps } from './resizable-region.js';
-import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import './pane.js';
 import './toolbar.js';
 import './sides-BPSWde0A.js';
+import './pane.js';
 import './toolbar-text.js';
 import './css-values.js';
 
@@ -1563,16 +1579,16 @@ export { Pane, type PaneAppearance, type PaneChromeDividers, type PaneChromePlac
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { ListConfig } from './list.js';
 import { NavStackProps } from './nav-stack.js';
 import { PaneConfig } from './pane.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
-import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-CL9tYOkh.js';
 import { ToolbarConfig } from './toolbar.js';
-import { a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-DDKh4uKd.js';
-import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './sides-BPSWde0A.js';
+import './css-values.js';
 import './toolbar-text.js';
 import './lucide-icon.js';
 import 'lucide';
@@ -1957,18 +1973,18 @@ export { type WireWorkbenchOptions, type WireWorkbenchPanel, type WorkbenchPanel
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { P as PanelSide, a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-CL9tYOkh.js';
+export { e as collapsiblePanelToggleIcon } from './panel-toolbar-CL9tYOkh.js';
 import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
-import { P as PanelSide, a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-DDKh4uKd.js';
-export { e as collapsiblePanelToggleIcon } from './panel-toolbar-DDKh4uKd.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
-import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import './css-values.js';
-import './flex-alignment-4ms8ZbV8.js';
+import './toolbar.js';
 import './sides-BPSWde0A.js';
 import './lucide-icon.js';
 import 'lucide';
-import './toolbar.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
 
 /** Which edge a {@link CollapsiblePanel} docks to. */
 type CollapsiblePanelSide = PanelSide;
@@ -2163,8 +2179,8 @@ export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wi
 
 ```ts
 import { SafeHtml } from 'kerfjs';
-import { PaneAppearance } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { PaneAppearance } from './pane.js';
 
 interface TabScaffoldTabBase<Id extends string> {
     id: Id;
@@ -2264,8 +2280,8 @@ export { type WireTabScaffoldOptions, wireTabScaffold };
 
 ```ts
 import { SafeHtml } from 'kerfjs';
-import { CssLength } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
 
 type ResizableRegionAxis = 'horizontal' | 'vertical';
 type ResizableRegionEdge = 'start' | 'end';
@@ -2410,20 +2426,20 @@ export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type Dev
 ```ts
 import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
-import { a as CatalogProps } from './types-BuHELdXR.js';
-export { b as CatalogBrand, c as CatalogEntry, d as CatalogRelated, C as CatalogResource, e as CatalogSecondaryGroup, f as CatalogSection, g as CatalogStageRootAttributes } from './types-BuHELdXR.js';
+import { a as CatalogProps } from './types-C9BubXfz.js';
+export { b as CatalogBrand, c as CatalogEntry, d as CatalogRelated, C as CatalogResource, e as CatalogSecondaryGroup, f as CatalogSection, g as CatalogStageRootAttributes } from './types-C9BubXfz.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import './toolbar.js';
-import './pane.js';
 import './sides-BPSWde0A.js';
+import './pane.js';
 import './workbench.js';
 import './list.js';
-import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
+import './css-values.js';
 import './nav-stack.js';
 import './toolbar-text.js';
 import './resizable-region.js';
-import './panel-toolbar-DDKh4uKd.js';
+import './panel-toolbar-CL9tYOkh.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -2505,20 +2521,20 @@ export { Catalog, CatalogExample, type CatalogExampleAlign, type CatalogExampleP
 ## `@kerfjs/ui/catalog-resources`
 
 ```ts
-import { C as CatalogResource } from './types-BuHELdXR.js';
-import './semantic-content-BbzjvSu9.js';
-import 'kerfjs';
+import { C as CatalogResource } from './types-C9BubXfz.js';
 import './toolbar.js';
-import './pane.js';
+import 'kerfjs';
+import './semantic-content-BbzjvSu9.js';
 import './sides-BPSWde0A.js';
+import './pane.js';
 import './workbench.js';
 import './list.js';
-import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
+import './css-values.js';
 import './nav-stack.js';
 import './toolbar-text.js';
 import './resizable-region.js';
-import './panel-toolbar-DDKh4uKd.js';
+import './panel-toolbar-CL9tYOkh.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -2684,9 +2700,9 @@ export { SegmentedControl, type SegmentedControlAppearance, type SegmentedContro
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { CssForegroundColor } from './css-values.js';
 import { LucideNode } from './lucide-icon.js';
-import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import 'lucide';
 
 interface SelectChoice<Value extends string = string> {
@@ -2815,8 +2831,10 @@ export { Select, type SelectChoice, type SelectFocusRingOwner, type SelectMultip
 ```ts
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
 
-type StateBannerTone = 'neutral' | 'info' | 'pop' | 'success' | 'warning' | 'danger';
+/** @deprecated Use SemanticTone. */
+type StateBannerTone = SemanticTone;
 type StateBannerUrgency = 'status' | 'alert';
 type StateBannerCopyLayout = 'inline' | 'stacked';
 type StateBannerActionPlacement = 'trailing' | 'below';
@@ -2827,7 +2845,7 @@ interface StateBannerProps {
     badge?: string;
     icon?: SafeHtml;
     action?: KerfUiContent;
-    tone?: StateBannerTone;
+    tone?: SemanticTone;
     urgency?: StateBannerUrgency;
     /** Keep the detail beside the title, or give it its own line. */
     copyLayout?: StateBannerCopyLayout;
@@ -2841,7 +2859,7 @@ interface StateBannerProps {
 }
 declare function StateBanner({ title, detail, badge, icon, action, tone, urgency, copyLayout, actionPlacement, className, placeholder, slot, }: StateBannerProps): SafeHtml;
 
-export { StateBanner, type StateBannerActionPlacement, type StateBannerCopyLayout, type StateBannerProps, type StateBannerTone, type StateBannerUrgency };
+export { SemanticTone, StateBanner, type StateBannerActionPlacement, type StateBannerCopyLayout, type StateBannerProps, type StateBannerTone, type StateBannerUrgency };
 ```
 
 ## `@kerfjs/ui/empty-state`
@@ -2869,12 +2887,15 @@ export { EmptyState, type EmptyStateProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { CssForegroundColor } from './css-values.js';
 import { LucideIconSize } from './lucide-icon.js';
 import 'lucide';
 
 type LoadingSpinnerSize = LucideIconSize;
 interface LoadingSpinnerProps {
     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?: LoadingSpinnerSize;
@@ -2882,7 +2903,7 @@ interface LoadingSpinnerProps {
     slot?: string;
 }
 /** Stable viewBox-centered progress ring based on svg-spinners' MIT-licensed 180-ring. */
-declare function LoadingSpinner({ className, label, size, slot, }: LoadingSpinnerProps): kerfjs.SafeHtml;
+declare function LoadingSpinner({ className, color, label, size, slot, }: LoadingSpinnerProps): kerfjs.SafeHtml;
 
 export { LoadingSpinner, type LoadingSpinnerProps, type LoadingSpinnerSize };
 ```
@@ -2927,8 +2948,8 @@ export { Skeleton, type SkeletonProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { CssFlexKeyword, CssFlex } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssFlexKeyword, CssFlex } from './css-values.js';
 
 type SunkenPanelShape = 'rounded' | 'square';
 interface SunkenPanelProps {
@@ -2958,16 +2979,16 @@ export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ## `@kerfjs/ui/token-search-field`
 
 ```ts
+export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, k as TokenSearchTrailingAction, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-model-DTcTXWMS.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
-export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, k as TokenSearchTrailingAction, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-field-CVGwDn2y.js';
 ```
 
 ## `@kerfjs/ui/wire-token-search-fields`
 
 ```ts
 import { Signal } from 'kerfjs';
-import { d as TokenSearchModel } from './token-search-field-CVGwDn2y.js';
+import { d as TokenSearchModel } from './token-search-model-DTcTXWMS.js';
 import './semantic-content-BbzjvSu9.js';
 
 interface TokenSearchSubmit {
@@ -3164,14 +3185,16 @@ export { type ActionHandler, type DelegateActionsOptions, action, delegateAction
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
 
-type BadgeTone = 'neutral' | 'brand' | 'pop' | 'success' | 'warning' | 'danger';
+/** @deprecated Use SemanticTone. */
+type BadgeTone = SemanticTone;
 type BadgeAppearance = 'quiet' | 'solid' | 'outline';
 type BadgeShape = 'pill' | 'rounded';
 /** Size of a text badge. A text-free dot is the separate `size: 'dot'` form. */
 type BadgeSize = 'compact' | 'default';
 interface BadgeCommonProps {
-    tone?: BadgeTone;
+    tone?: SemanticTone;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -3214,19 +3237,20 @@ type BadgeProps = BadgeTextProps | BadgeDotProps;
 /** Compact, non-interactive metadata whose tone, emphasis, and shape are configured by props. */
 declare function Badge(props: BadgeProps): SafeHtml;
 
-export { Badge, type BadgeAppearance, type BadgeDotProps, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeTextProps, type BadgeTone };
+export { Badge, type BadgeAppearance, type BadgeDotProps, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeTextProps, type BadgeTone, SemanticTone };
 ```
 
 ## `@kerfjs/ui/chip`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
-import { BadgeTone, BadgeAppearance, BadgeShape, BadgeSize } from './badge.js';
+import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
+import { BadgeAppearance, BadgeShape, BadgeSize } from './badge.js';
 
 interface ChipCommonProps {
     /** Decorative leading icon, normally an unsized LucideIcon. */
     icon?: SafeHtml;
-    tone?: BadgeTone;
+    tone?: SemanticTone;
     appearance?: BadgeAppearance;
     shape?: BadgeShape;
     size?: BadgeSize;
@@ -3262,6 +3286,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;
@@ -3271,6 +3296,10 @@ 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;
+    /** Flow with surrounding text instead of occupying a block. */
+    inline?: boolean;
     label?: string;
     /** Named icon scale or positive pixel size, converted to rem. Omit for 1em. */
     size?: LucideIconSize;
@@ -3278,7 +3307,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, inline, label, size, slot, }: LucideIconProps): kerfjs.SafeHtml;
 
 export { LucideIcon, type LucideIconProps, type LucideIconSize, type LucideNode };
 ```
@@ -3324,6 +3353,15 @@ export { DialogSurface, type DialogSurfacePresentation, type DialogSurfaceProps,
 import * as kerfjs from 'kerfjs';
 import { KerfBaseAttrs } from 'kerfjs/jsx-runtime';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssForegroundColor } from './css-values.js';
+
+type FieldLabelProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
+    children: string;
+    class?: string;
+    className?: string;
+};
+/** Visible field heading for a read-only preview; use its id with aria-labelledby on the preview group. */
+declare function FieldLabel({ children, class: classValue, className, ...attributes }: FieldLabelProps): kerfjs.SafeHtml;
 
 type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span';
 type TextTone = 'default' | 'quiet' | 'danger';
@@ -3333,18 +3371,13 @@ type TextBorder = 'transparent' | 'none';
 type TextLineHeight = 'default' | 'tight';
 type TextWrap = 'normal' | 'anywhere' | 'nowrap' | 'truncate';
 type TextContent = KerfUiContent | string | number | readonly TextContent[];
-type FieldLabelProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
-    children: string;
-    class?: string;
-    className?: string;
-};
-/** Visible field heading for a read-only preview; use its id with aria-labelledby on the preview group. */
-declare function FieldLabel({ children, class: classValue, className, ...attributes }: FieldLabelProps): kerfjs.SafeHtml;
 type TextCommonProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
     /** Native heading, paragraph, or inline span element to render. Defaults to `p`. */
     variant?: TextVariant;
     /** Semantic foreground treatment. Defaults to the inherited foreground. */
     tone?: TextTone;
+    /** Foreground color; overrides tone when supplied, or inherits when omitted. */
+    color?: CssForegroundColor;
     /** Text sizing independent of the native semantic element. */
     size?: TextSize;
     /** Font family independent of the native semantic element. */
@@ -3374,7 +3407,7 @@ type TextProps = TextCommonProps & ({
  * content-item padding; `span` adds no box geometry.
  * All ordinary native heading/paragraph attributes pass through to the element.
  */
-declare function Text({ variant: Variant, tone, size, font, border, flush, lineHeight, wrap, maxLines, children, class: classValue, className, ...attributes }: TextProps): kerfjs.SafeHtml;
+declare function Text({ variant: Variant, tone, color, size, font, border, flush, lineHeight, wrap, maxLines, children, class: classValue, className, style, ...attributes }: TextProps): kerfjs.SafeHtml;
 
 export { FieldLabel, type FieldLabelProps, Text, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextVariant, type TextWrap };
 ```
@@ -3383,10 +3416,10 @@ export { FieldLabel, type FieldLabelProps, Text, type TextBorder, type TextConte
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
-import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { S as Sides } from './sides-BPSWde0A.js';
+import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
 
 type RowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -3436,8 +3469,9 @@ export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowP
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
+import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
 
 type GridRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -3446,6 +3480,8 @@ type GridRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
     'data-auto-fill'?: never;
     'data-flex'?: never;
     'data-fill'?: never;
+    'data-text-insets'?: never;
+    'data-control-insets'?: never;
 }>;
 interface GridCommonProps {
     children?: KerfUiContent;
@@ -3463,6 +3499,10 @@ interface GridCommonProps {
      * flex layout use `flex` instead. Defaults to false.
      */
     fill?: boolean;
+    /** Physical sides that receive the standard 17px text inset. */
+    textInsets?: Sides;
+    /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
+    controlInsets?: Sides;
     className?: string;
     /** Safe `data-*` metadata; Grid-owned structural attributes remain protected. */
     rootAttributes?: GridRootAttributes;
@@ -3482,9 +3522,9 @@ type GridProps = GridCommonProps & ({
     autoFill?: boolean;
 });
 /** Render equal tracks with a fixed count or a responsive minimum width. */
-declare function Grid({ children, selectionMode, ariaLabel, columns, minColumnWidth, autoFill, gap, flex, fill, className, rootAttributes, slot, }: GridProps): kerfjs.SafeHtml;
+declare function Grid({ children, selectionMode, ariaLabel, columns, minColumnWidth, autoFill, gap, flex, fill, textInsets, controlInsets, className, rootAttributes, slot, }: GridProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, UiSpaceName };
+export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, Sides, UiSpaceName };
 ```
 
 ## `@kerfjs/ui/spacer`
@@ -3513,7 +3553,7 @@ export { CssLength, Spacer, type SpacerProps, UiSpaceName };
 ## `@kerfjs/ui/token-search-model`
 
 ```ts
+export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, l as createTokenSearchModel } from './token-search-model-DTcTXWMS.js';
 import 'kerfjs';
-export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, l as createTokenSearchModel } from './token-search-field-CVGwDn2y.js';
 import './semantic-content-BbzjvSu9.js';
 ```

package/ai/skill.md

@@ -1,7 +1,7 @@
 ---
 name: kerf-ui
 description: Build interfaces with kerfjs and the @kerfjs/ui production component package. Use whenever code imports @kerfjs/ui or a task asks for Kerf UI components.
-kerf-ui-skill-version: 1.50.0
+kerf-ui-skill-version: 1.51.0
 ---
 
 # Building with @kerfjs/ui
@@ -21,6 +21,16 @@ documented dynamic-data widening. Do not extend those diagnostics to child
 markup, live DOM relationships, disposer invocation, or other conditions that
 TypeScript cannot prove from one call.
 
+### Shared semantic tones
+
+`SemanticTone` is the shared color-role type for `Badge`, `Chip`, `StateBanner`,
+and semantic `ContentItem` appearances: `neutral`, `info`, `pop`, `success`,
+`warning`, and `danger`. Import it as a type from `@kerfjs/ui`,
+`@kerfjs/ui/badge`, `@kerfjs/ui/state-banner`, or `@kerfjs/ui/content-item`.
+Use `info` for the role backed by the existing `--kui-color-brand-*` tokens.
+Migrate Badge/Chip `tone="brand"` to `tone="info"`; `BadgeTone` and
+`StateBannerTone` remain deprecated aliases of `SemanticTone`.
+
 ## Components own their styles; configure, never override
 
 This is the rule every Kerf UI surface follows, and applications and
@@ -33,6 +43,11 @@ component packages built on Kerf UI must follow it too:
   selects a `.kui-*` class, a `[data-component]` root, a `wa-*` element a Kerf
   component renders, or its `::part()`s, and no hook class added to a
   component's root so that it can be restyled.
+- **Owned implementation details are available.** A component may render raw
+  HTML or Web Awesome elements and style those elements when it creates them,
+  controls their state, and keeps the selectors in its own stylesheet. That
+  permission stops at every nested Kerf or application component boundary;
+  ownership follows the child component, even when the parent rendered it.
 - **Configuration, not overrides.** Do not write another component's private
   `--_kui-*` variables or reach for its `--kui-*` tokens to change layout,
   size, padding, or framing when a prop exists. Theme tokens are for theming
@@ -49,6 +64,11 @@ wa-dropdown.kui-popup-menu { … }` lives with PopupMenu). A parent may key its
   you need, report it (open an upstream feature request) instead of
   overriding. Your own components follow the same rule: expose configuration,
   and let each component own its styles.
+- **Thin compositions usually need no CSS.** A component that only chooses and
+  connects other components should configure their props and slots without a
+  stylesheet. Add CSS only for raw elements or layout that the composition
+  itself owns; never use a composition stylesheet to normalize or override its
+  children.
 
 `kerf-ui-analyze` and `kerf-ui-doctor` enforce this downstream: `KUI-L019`
 (a rule whose subject is a cataloged component), `KUI-L020` (another
@@ -62,9 +82,12 @@ when none exists, report the component gap rather than suppressing the finding.
 For compact known activity, give `LoadingSpinner` its `size` prop (`xs` through
 `xl`, or a positive pixel number) instead of styling its SVG; omitted size is
 1em.
-For an application's own cataloged components, opt into Doctor's
-`"ownership": "component"` and declare each entry's `styleSources` so sibling
-components cannot style one another; package ownership remains the default.
+For an application's own components, configure Doctor with
+`"ownership": "component"`, `"implicitComponentOwnership": true`, and
+`"ownershipContext": "any-package"`; declare each catalog entry's
+`styleSources` so sibling components cannot style one another. Package
+ownership remains the compatibility default and does not establish those
+application-level boundaries.
 
 Read `../docs/webawesome-theme.md` when using Web Awesome components or changing
 shared theme tokens. When overriding a loud fill
@@ -172,6 +195,8 @@ For selectable document tiles, set `Grid selectionMode="multiple"` and
 `ariaLabel`, render `ContentItem selectionMode="multiple"` children, and wire
 `wireContentItems` for arrows, Home/End, and card activation. The app owns the
 selection set and each tile's nested controls.
+`textInsets` adds the standard 17px physical-side content inset; `controlInsets`
+adds 8px. Text insets win on any overlapping side, matching Row and List.
 
 For a complete shell, sidebar, workspace header, list-detail dialog, composer
 form, list-state lifecycle, or mixed-control toolbar, start from the runnable
@@ -262,6 +287,7 @@ Use `Toolbar responsive="trailing-priority"` when an expanded trailing search ne
 Set `--kui-toolbar-inset: 0px` on an embedded Toolbar to remove its outer padding while retaining `--kui-toolbar-gap` between zones. The same inset token controls the minimum-height allowance; safe-area padding still applies at claimed edges.
 
 For compact dialog copy, use `Text flush lineHeight="tight"`; for compact metadata, use `ValueTable density="compact"` and its public row columns/padding/gap tokens. `ToolbarText size="xsmall"` fits a dense rail heading. A `TokenSearchField` editor shrinks inside a narrow group by default; set `--kui-token-search-editor-min-width` when a minimum is needed. A full-height shell uses the one `.kui-app-root` mount container documented in `docs/document-baseline.md`.
+When importing the opt-in `@kerfjs/ui/document.css` baseline, native `th`, `td`, `button`, `input`, `select`, and `textarea` inherit the surrounding font family, size, and line height; table headers retain their native emphasis. Load application typography overrides after the baseline.
 
 For a read-only field preview that replaces a Web Awesome input, use `FieldLabel` from `@kerfjs/ui/text` above the preview. Put it in `ListInsetControl sides="trl"` beside a `ContentItem` value; give it an id and use `aria-labelledby` on the preview group. The app owns preview/edit state and hint copy.
 
@@ -309,6 +335,9 @@ 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.
+Set `LucideIcon.inline` when an icon belongs within `Text` or another sentence; the SVG flows as `inline-block` instead of its default block layout. It retains its inherited 1em size unless you set `size`.
+
 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.
@@ -320,3 +349,5 @@ lifecycle: the latest request wins through open/close reversals, canceled
 transitions, and removal. Native value, keyboard, dismissal, and anchor placement
 remain with Web Awesome. Do not add popup delays, position repairs, or animation
 completion handlers in consumers. Raw `wa-select` elements remain native.
+
+Neutral lowered surfaces and decorative neutral fills/borders are translucent theme colors; compose nested public components directly. Default/raised canvases, foregrounds, focus indicators, and loud contrast-bearing fills remain opaque. Do not assign depth-specific component tokens in demo wrappers.

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.74` 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.76` 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/analyzer/index.mjs

@@ -15,6 +15,7 @@ import ts from 'typescript';
 import { loadApplicationUiProfile } from '../ai/application-ui-profile.mjs';
 import { isUiTraversalExcluded } from '../traversal-exclusions.mjs';
 import {
+  classOwnerFor,
   componentLabel,
   componentName,
   componentOwnershipFacts,
@@ -1636,7 +1637,13 @@ function inspectTsx(
         );
       if (entry && isForeign(entry))
         for (const className of classes.values) {
-          if (ownsClassBlock(facts.ownership, className, componentMode))
+          // A class owned by the surrounding application is still a hook when
+          // placed on another component's root. Only the component's own
+          // public class is safe to style here.
+          if (
+            classOwnerFor(facts.ownership, className, componentMode)?.key ===
+            entry.key
+          )
             continue;
           const styled = cssFacts.get(className)?.styled;
           if (!styled) continue;
@@ -1717,6 +1724,9 @@ function inspectTsx(
         inset: inset || parent?.inset,
         label: entry?.key ?? tag,
       });
+      // JSX supplied through a prop (for example Toolbar.leading) is still
+      // rendered markup and must be checked like ordinary children.
+      ts.forEachChild(opening.attributes, visit);
       if (ts.isJsxElement(node))
         for (const child of node.children) visit(child);
       stack.pop();