@kerfjs/ui 5.0.0-beta.15 → 5.0.0-beta.17

package/dist/index.js

@@ -1,18 +1,18 @@
 export { wireResizableRegions } from './chunk-AQNKJRFH.js';
 export { reorderTabs, wireTabBars } from './chunk-XXMOARTH.js';
-export { wireTokenSearchFields } from './chunk-LCOBDOCC.js';
+export { wireTokenSearchFields } from './chunk-6NLRBSVX.js';
 export { TabBar } from './chunk-AVZHJN6C.js';
 export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-7LDCTU7D.js';
 export { ValueTable, ValueTableRow } from './chunk-37T3VNIZ.js';
-export { PanelHeader } from './chunk-XE5ZLPCC.js';
+export { PanelHeader } from './chunk-ZQQ6P4SV.js';
 export { SegmentedControl } from './chunk-YGN7OMLT.js';
 export { Select } from './chunk-CH4SQ6H5.js';
 export { ResizableRegion, clampRegionSize, resizeRegionFromPointer } from './chunk-M5JRI6MN.js';
 export { StateBanner } from './chunk-I7INRJO4.js';
 export { ListActionRow } from './chunk-7JB7VPRI.js';
 export { ListInsetControl } from './chunk-VPCTCUED.js';
-export { ListInsetText } from './chunk-XE4OX6AZ.js';
-export { ToolbarText } from './chunk-RUNWEPR4.js';
+export { ListInsetText } from './chunk-AHQI52QO.js';
+export { ToolbarText } from './chunk-WXMGNX2Y.js';
 export { AppTab } from './chunk-2Z5TWHKQ.js';
 export { ToolbarControlGroup } from './chunk-RNPGFQ33.js';
 export { Toolbar } from './chunk-DAFFDO33.js';

package/dist/list-inset-text.d.ts

@@ -3,6 +3,13 @@ import { SafeHtml } from 'kerfjs';
 interface ListInsetTextProps {
     /** Text (or inline content) that carries no margin, border, or padding of its own. */
     children: SafeHtml | SafeHtml[] | string;
+    /**
+     * Keep only the horizontal geometry (inline margin, left/right border, and
+     * left/right padding) and drop the vertical margin, border, and padding. Use it
+     * when the text edge must still align with bordered items but the line should not
+     * add its own vertical box space — tight text layout inside a content region.
+     */
+    horizontalOnly?: boolean;
     className?: string;
 }
 /**
@@ -10,7 +17,9 @@ interface ListInsetTextProps {
  * transparent border, and 8px padding — so a plain string lines up with
  * bordered `.kui-content` items (its text edge lands at the same 17px inset).
  * Use it for text elements that have no margin, border, or padding of their own.
+ * Pass `horizontalOnly` to keep the horizontal inset but drop the vertical box
+ * space for tight text layout.
  */
-declare function ListInsetText({ children, className }: ListInsetTextProps): SafeHtml;
+declare function ListInsetText({ children, horizontalOnly, className }: ListInsetTextProps): SafeHtml;
 
 export { ListInsetText, type ListInsetTextProps };

package/dist/list-inset-text.js

@@ -1,3 +1,3 @@
-export { ListInsetText } from './chunk-XE4OX6AZ.js';
+export { ListInsetText } from './chunk-AHQI52QO.js';
 
 //# sourceMappingURL=list-inset-text.js.map

package/dist/nav-stack.js

@@ -1,4 +1,4 @@
-export { NavStack } from './chunk-BLK3UEEI.js';
+export { NavStack } from './chunk-WRTAQ7BZ.js';
 
 
 

package/dist/panel-header.js

@@ -1,4 +1,4 @@
-export { PanelHeader } from './chunk-XE5ZLPCC.js';
+export { PanelHeader } from './chunk-ZQQ6P4SV.js';
 
 
 

package/dist/split-view.js

@@ -1,4 +1,4 @@
-import { NavStack } from './chunk-BLK3UEEI.js';
+import { NavStack } from './chunk-WRTAQ7BZ.js';
 import { ResizableRegion } from './chunk-M5JRI6MN.js';
 
 

package/dist/styles/catalog.css

@@ -104,7 +104,28 @@
 }
 
 .kui-catalog__items .kui-list-item {
-  grid-template-columns: minmax(0, 1fr);
+  grid-template-columns: minmax(0, 1fr) auto;
+}
+
+.kui-catalog__tags {
+  display: inline-flex;
+  min-width: 0;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: var(--kui-space-2xs);
+}
+
+.kui-catalog__tag {
+  display: inline-flex;
+  padding: 0.125rem 0.375rem;
+  border: 1px solid var(--kui-color-warning-border-quiet);
+  border-radius: 999px;
+  color: var(--kui-color-warning-text);
+  background: var(--kui-color-warning);
+  font-size: var(--kui-font-2xs);
+  font-weight: 650;
+  line-height: 1.2;
+  white-space: nowrap;
 }
 
 .kui-catalog__group--secondary {

package/dist/styles/list-inset-text.css

@@ -3,3 +3,12 @@
   border: 1px solid transparent;
   padding: 0.5rem;
 }
+
+/* Horizontal-only: keep the inline inset (margin + left/right border + left/right
+   padding) so the text edge still aligns with bordered items, but drop the vertical
+   box space for tight text layout. */
+.kui-list-inset-text--horizontal {
+  margin-block: 0;
+  border-block: 0;
+  padding-block: 0;
+}

package/dist/styles/toolbar-text.css

@@ -9,11 +9,19 @@
   color: var(--kui-color-neutral-on-quiet);
   font-weight: 650;
   line-height: 1;
-  text-overflow: ellipsis;
-  white-space: nowrap;
   align-items: center;
 }
 
+/* The text lives in a block child, not directly in the flex box, so
+   `text-overflow: ellipsis` actually applies (it is a no-op on a flex item). */
+.kui-toolbar-text__text {
+  min-width: 0;
+  max-width: 100%;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
 .kui-toolbar-text[data-size="xlarge"] {
   /* Matches the page/panel title: the same responsive clamp so a PanelHeader
      title reads at the page-title scale without a bespoke override. Height grows
@@ -38,3 +46,47 @@
   font-family: var(--kui-font-mono);
   font-size: var(--kui-font-xs);
 }
+
+/* Single line, no ellipsis: hard-clip the overflow instead of showing …. */
+.kui-toolbar-text[data-ellipsis="false"] .kui-toolbar-text__text {
+  text-overflow: clip;
+}
+
+/* Wrap onto multiple lines. The box grows to fit and switches from the centered
+   single-line row to a top-aligned block with readable leading; a min-height keeps
+   a one-line label at the toolbar row height. */
+.kui-toolbar-text[data-wrap="true"] {
+  align-items: flex-start;
+  height: auto;
+  min-height: 2.5rem;
+}
+
+.kui-toolbar-text[data-size="xlarge"][data-wrap="true"] {
+  min-height: 2.75rem;
+}
+
+.kui-toolbar-text[data-wrap="true"] .kui-toolbar-text__text {
+  white-space: normal;
+  line-height: 1.25;
+}
+
+/* Wrap capped to N lines with an ellipsis at the cut. `-webkit-line-clamp` needs
+   the box display and emits the … itself; the unprefixed `line-clamp` follows for
+   engines that ship it. */
+.kui-toolbar-text[data-wrap="true"][data-max-lines] .kui-toolbar-text__text {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: var(--kui-toolbar-text-max-lines);
+  line-clamp: var(--kui-toolbar-text-max-lines);
+  overflow: hidden;
+}
+
+/* Wrap capped to N lines without an ellipsis: clip at a max-height instead of
+   line-clamp (which always ellipsizes). */
+.kui-toolbar-text[data-wrap="true"][data-max-lines][data-ellipsis="false"]
+  .kui-toolbar-text__text {
+  display: block;
+  -webkit-line-clamp: none;
+  line-clamp: none;
+  max-height: calc(var(--kui-toolbar-text-max-lines) * 1.25em);
+}

package/dist/styles/webawesome.css

@@ -175,6 +175,19 @@
     --wa-form-control-border-color: var(--wa-color-neutral-border-normal);
     --wa-form-control-border-radius: var(--wa-border-radius-m);
     --wa-form-control-activated-color: var(--wa-color-brand-fill-loud);
+    /* Field inset: a 1px border with 8px inside it, the same content-item
+       geometry the Kerf primitives use (docs/layout.md). WA's defaults are a
+       larger 0.75em/1em pad; this brings every form field onto our 8px rhythm
+       (and a ~40px single-line control height). */
+    --wa-form-control-border-width: var(--kui-layout-item-border-width, 1px);
+    --wa-form-control-padding-block: var(
+      --kui-layout-item-padding,
+      0.5rem
+    );
+    --wa-form-control-padding-inline: var(
+      --kui-layout-item-padding,
+      0.5rem
+    );
     --wa-panel-border-radius: var(--wa-border-radius-l);
     --wa-tooltip-background-color: var(--wa-color-neutral-fill-loud);
     --wa-tooltip-content-color: var(--wa-color-neutral-on-loud);
@@ -184,6 +197,13 @@
     --kui-wa-carousel-dot-hit-size: 20px;
     --kui-wa-carousel-control-size: 28px;
     --kui-wa-carousel-icon-size: 16px;
+    /* Non-field chrome uses Kerf's control, surface, and container spacing:
+       8px inside controls/surfaces, 8px around bordered surfaces, and 16px
+       inside the remaining content containers. */
+    --kui-wa-control-inset: var(--kui-layout-item-padding, 0.5rem);
+    --kui-wa-surface-inset: var(--kui-layout-item-padding, 0.5rem);
+    --kui-wa-surface-margin: var(--kui-layout-inline-margin, 0.5rem);
+    --kui-wa-container-inset: var(--kui-space-m, 1rem);
     --kui-disclosure-icon-scale: 0.5;
     --wa-shadow-s: 0 1px 3px rgb(0 0 0 / 0.14);
     --wa-shadow-m: 0 0.35rem 1rem rgb(0 0 0 / 0.11);
@@ -248,9 +268,120 @@
     transform: scale(var(--kui-disclosure-icon-scale));
   }
 
+  /* Bordered/fill surfaces follow the same 8px outer margin + 8px inner
+     padding contract as a Kerf content item. Accordion owns one outer margin
+     for the group; its items retain connected borders. */
+  :is(wa-accordion, wa-card, wa-details, wa-callout, wa-include) {
+    margin-inline: var(--kui-wa-surface-margin);
+  }
+
+  wa-card,
+  wa-details,
+  wa-accordion-item {
+    /* WA declares this custom property on :host inside each shadow root. The
+       important flag is required for a public host override to cross that
+       encapsulation boundary. */
+    --spacing: var(--kui-wa-surface-inset) !important;
+  }
+
+  /* Card halves --spacing for its header block padding upstream, so pin the
+     public part to the same full surface inset as its body and footer. */
+  wa-card::part(header) {
+    padding: var(--kui-wa-surface-inset);
+  }
+
+  wa-callout {
+    padding: var(--kui-wa-surface-inset) !important;
+  }
+
+  wa-include {
+    padding: var(--kui-wa-surface-inset);
+  }
+
+  /* Interactive and item chrome follows the content-item 8px inset. */
+  wa-tab::part(tab) {
+    padding: var(--kui-wa-control-inset);
+  }
+
+  wa-tab-panel {
+    --padding: var(--kui-wa-container-inset) 0 !important;
+  }
+
+  wa-tree-item::part(item) {
+    margin-inline: var(--kui-layout-inline-margin, 0.5rem);
+    padding-inline-end: var(--kui-wa-control-inset);
+    border-radius: var(--kui-layout-rounded-radius, calc(1px + 0.6875rem));
+  }
+
+  wa-tag {
+    padding-inline: var(--kui-wa-control-inset) !important;
+  }
+
+  wa-dropdown-item {
+    padding-inline: var(--kui-wa-control-inset) !important;
+  }
+
   wa-popover {
     --arrow-size: var(--kui-wa-popover-arrow-size);
   }
+
+  /* A form field's top label is inset by the field's own border + inline padding
+     (1px + 8px = 9px) so the label text lines up with the value inside the field,
+     and it is styled exactly like a ListHeader label: uppercase, xs, quiet. */
+  :is(
+    wa-checkbox-group,
+    wa-color-picker,
+    wa-input,
+    wa-known-date,
+    wa-number-input,
+    wa-radio-group,
+    wa-select,
+    wa-textarea,
+    wa-time-input
+  )::part(form-control-label),
+  wa-otp-input::part(label),
+  wa-slider::part(label) {
+    padding-inline: calc(
+      var(--wa-form-control-border-width) +
+        var(--wa-form-control-padding-inline)
+    );
+    color: var(--kui-color-neutral-on-quiet, var(--wa-color-text-quiet));
+    font-size: var(--kui-font-xs, var(--wa-font-size-xs));
+    font-weight: 650;
+    letter-spacing: 0.04em;
+    line-height: var(--wa-line-height-condensed);
+    text-transform: uppercase;
+  }
+
+  /* Checkbox/radio groups and the color picker have no bordered field shell,
+     so their control regions need the content-item's 8px inline outer inset. */
+  :is(wa-checkbox-group, wa-color-picker, wa-radio-group)::part(
+    form-control-input
+  ) {
+    margin-inline: var(--kui-layout-inline-margin, 0.5rem);
+  }
+
+  wa-slider::part(slider) {
+    margin-inline: var(--kui-layout-inline-margin, 0.5rem);
+  }
+
+  /* Secondary captions and hints align with the value inside bordered fields:
+     1px border + 8px field padding = a 9px logical inset. */
+  wa-known-date::part(field-label),
+  :is(
+    wa-input,
+    wa-known-date,
+    wa-number-input,
+    wa-otp-input,
+    wa-select,
+    wa-textarea,
+    wa-time-input
+  )::part(hint) {
+    padding-inline: calc(
+      var(--wa-form-control-border-width) +
+        var(--wa-form-control-padding-inline)
+    );
+  }
 }
 
 @media (prefers-contrast: more) {

package/dist/toolbar-text.d.ts

@@ -17,7 +17,23 @@ interface ToolbarTextProps {
     headingLevel?: HeadingLevel;
     /** Render the text as an unanimated loading skeleton instead of its value. */
     placeholder?: boolean;
+    /**
+     * Wrap onto multiple lines when the text does not fit, instead of the default
+     * single line. Combine with `maxLines` to cap the number of lines. Default false.
+     */
+    wrap?: boolean;
+    /**
+     * Show a trailing ellipsis (…) where the text is truncated — on the single line
+     * (default), or at the `maxLines` boundary when wrapping. Set false to hard-clip
+     * instead. Default true.
+     */
+    ellipsis?: boolean;
+    /**
+     * Cap wrapped text to this many lines, truncating past it. Only takes effect with
+     * `wrap`; ignored on a single line. `null`/omitted wraps without a line cap. Default null.
+     */
+    maxLines?: number | null;
 }
-declare function ToolbarText({ text, size, className, id, headingLevel, placeholder }: ToolbarTextProps): kerfjs.SafeHtml;
+declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, }: ToolbarTextProps): kerfjs.SafeHtml;
 
 export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize };

package/dist/toolbar-text.js

@@ -1,4 +1,4 @@
-export { ToolbarText } from './chunk-RUNWEPR4.js';
+export { ToolbarText } from './chunk-WXMGNX2Y.js';
 
 
 //# sourceMappingURL=toolbar-text.js.map

package/dist/wire-token-search-fields.js

@@ -1,4 +1,4 @@
-export { wireTokenSearchFields } from './chunk-LCOBDOCC.js';
+export { wireTokenSearchFields } from './chunk-6NLRBSVX.js';
 
 
 

package/docs/catalog.md

@@ -22,8 +22,9 @@ npm install @kerfjs/ui   # kerfjs is a peer; @kerfjs/ui/select/register is neede
 ## What you supply
 
 - **`sections`** — category-grouped entries: `{ category, entries: [{ id, name,
-  description?, resources?, related? }] }`. Each entry becomes a sidebar `ListItem`
-  under a `ListHeader` for its category.
+  description?, tags?, resources?, related? }] }`. Each entry becomes a sidebar
+  `ListItem` under a `ListHeader` for its category. Short `tags` render as quiet
+  trailing pills for decision metadata such as `Discouraged`.
 - **`content`** — the rendered preview for the active entry. Keep a map of `id →
   () => SafeHtml` in your app and call `renderers[active]()` in your render.
 - **`brand`** — `{ title, subtitle?, logoUrl? }` for the sidebar header.
@@ -86,7 +87,7 @@ const sections: CatalogSection[] = [
     entries: [
       { id: 'button', name: 'Button', description: 'A pressable control.',
         resources: [{ label: 'Source', href: '/src/button.tsx', detail: 'src/button.tsx' }] },
-      { id: 'field', name: 'Field', description: 'A labeled input.',
+      { id: 'field', name: 'Field', description: 'A labeled input.', tags: ['Discouraged'],
         related: [{ id: 'button', name: 'Button', group: 'Used with' }] },
     ],
   },

package/docs/component-selection.md

@@ -65,12 +65,12 @@ an upstream component or recipe request.
 | Application toolbar — `Toolbar` | Leading identity, optional centered content, and trailing controls form one horizontal app bar. | Do not use it for a page, panel, or dialog heading; use `PanelHeader`. | Compose `ToolbarText` and `ToolbarControlGroup` where their contracts fit. | Actions, command availability, responsive relocation, and state. | `@kerfjs/ui/toolbar` | [Toolbar composition](../README.md#component-subpaths) |
 | Toolbar control cluster — `ToolbarControlGroup` | Related toolbar controls need contained, borderless, pressed, or single-control treatment. | Do not use it merely to align unrelated buttons; use toolbar slots or ordinary layout. Web Awesome `wa-button-group` is only for an exceptional grouped-action contract. | Delegate child actions; use `SegmentedControl` for an exclusive choice. | Actions, pressed/expanded state, and policy. | `@kerfjs/ui/toolbar-control-group` | [Component ownership](./component-contract.md#ownership-boundaries) |
 | Floating controls over content — `FloatingToolbar` | A small cluster of controls (e.g. a drawer restore) must float over scrolling content — distinct and forced-dark — inside a positioned container. | Do not use it for a primary page or panel toolbar (use `Toolbar`), or for anything that must sit above dialogs/overlays — it is not top-layer. | Compose `ToolbarControlGroup`s and delegate their actions; the app owns visibility and position. | Controls, visibility, and position. | `@kerfjs/ui/floating-toolbar` | [Component subpaths](../README.md#component-subpaths) |
-| Toolbar identity text — `ToolbarText` | A toolbar needs extra-large (page/panel title), large, default, or compact textual identity. | Plain text is not a heading by default; when a title needs heading semantics pass `headingLevel` (or prefer `PanelHeader`, which forwards it). | Optional `headingLevel` for `role="heading"` + `aria-level`. | Text, heading level, and responsive priority. | `@kerfjs/ui/toolbar-text` | [Toolbar composition](../README.md#component-subpaths) |
+| Toolbar identity text — `ToolbarText` | A toolbar needs extra-large (page/panel title), large, default, or compact textual identity. | Plain text is not a heading by default; when a title needs heading semantics pass `headingLevel` (or prefer `PanelHeader`, which forwards it). | Optional `headingLevel` for `role="heading"` + `aria-level`. Defaults to one line, ellipsized when it does not fit; `wrap` flows onto multiple lines, `ellipsis` toggles the trailing …, and `maxLines` caps a wrap. | Text, heading level, overflow behavior, and responsive priority. | `@kerfjs/ui/toolbar-text` | [Toolbar composition](../README.md#component-subpaths) |
 | Navigation row — `ListItem` | A pane or navigation area needs a selectable, disabled, dormant-trailing, or multiline action row. | Do not put a control in `trailing`; use `ListActionRow` when the trailing region must be independently interactive. Use an `<a>` for navigation that must retain link behavior, a native `<button>` for an ordinary action, or implement the complete ARIA menu widget. | Delegate its `data-action`; compose inside a `.kui-content` section. Put domain event/drop metadata in `rootAttributes` rather than adding wrapper markup. | Routing, selection, permissions, copy, action handling, and domain `data-*` values. | `@kerfjs/ui/list-item` | [Pane geometry](../README.md#pane-and-content-geometry) |
 | Navigation row with trailing action — `ListActionRow` | A full-width row needs a selectable primary action and an independently focusable trailing action. | Use `ListItem` when trailing content is dormant metadata. Do not put controls inside the row's `label`, `icon`, or `trailingActionIcon` SafeHtml slots. Do not use `AppTab` outside tablist semantics or `ToolbarControlGroup` outside a toolbar. | Delegate both action strings; update controlled selection and any popover/context-menu state in the app. | Routing, selection, both action policies, domain metadata, and popover/context-menu behavior. | `@kerfjs/ui/list-action-row` | [Accessibility](./accessibility.md#listactionrow) |
 | Navigation section heading — `ListHeader` | A menu section needs a full-width label, semantic count, non-count badge, logical-end action, or real disclosure state. | Do not concatenate counts into `label` or put numeric content in `badge`; use `count` with the localized full phrase in `countLabel`. Do not add a disclosure arrow to navigation that reveals nothing. Do not shrink its 44px action target to the 18px visual. Do not use it as a page, panel, or dialog title; use `PanelHeader`. | Delegate its optional action; the app controls expanded state and revealed content. Toggle mode supplies `DisclosureArrow` unless `actionIcon` replaces it. Use `triggerAttributes` only for domain `data-*` or a native popover relationship. | Section organization, valid count and localized count label, disclosure state and content, non-count badge content, popover target behavior, and policy. | `@kerfjs/ui/list-header` | [Pane geometry](../README.md#pane-and-content-geometry) |
 | Inset self-bordered control — `ListInsetControl` | A control that owns its own border and padding but no outer margin (a search input, a `SegmentedControl`) must line up inside a `.kui-content` list with the standard 8px inline margins and stretch to fill the row. | Do not wrap a `.kui-content-item` or a `ListItem`/`ListHeader` that already owns its inline margin — that double-insets it. Do not add ad-hoc `margin`/`padding` around a bare control to align it; use this instead. | Place the self-bordered control(s) as children; they stretch to fill. It applies only the inline margin, flex stretch, and 8px gap — the child owns its own border and padding. | The control(s), their state, and action wiring. | `@kerfjs/ui/list-inset-control` | [Pane geometry](../README.md#component-subpaths) |
-| Inset bare text — `ListInsetText` | A plain string or inline content with no margin, border, or padding of its own must sit in a `.kui-content` list with its text edge aligned to the bordered items around it. | Do not use it to wrap a component that already owns content-item geometry (`ListItem`, `StateBanner`, a `.kui-content-item`) — that double-insets it. Do not hand-roll the 8px margin / 1px border / 8px padding. | Pass the text or inline `SafeHtml` as children; it supplies the 8px inline margin, 1px transparent border, and 8px padding so the text edge lands at the standard 17px inset. | The text, copy, and localization. | `@kerfjs/ui/list-inset-text` | [Pane geometry](../README.md#component-subpaths) |
+| Inset bare text — `ListInsetText` | A plain string or inline content with no margin, border, or padding of its own must sit in a `.kui-content` list with its text edge aligned to the bordered items around it. | Do not use it to wrap a component that already owns content-item geometry (`ListItem`, `StateBanner`, a `.kui-content-item`) — that double-insets it. Do not hand-roll the 8px margin / 1px border / 8px padding. | Pass the text or inline `SafeHtml` as children; it supplies the 8px inline margin, 1px transparent border, and 8px padding so the text edge lands at the standard 17px inset. Pass `horizontalOnly` to keep that horizontal inset but drop the vertical margin, border, and padding for tight text layout. | The text, copy, and localization. | `@kerfjs/ui/list-inset-text` | [Pane geometry](../README.md#component-subpaths) |
 | Application layout composition | A sidebar, main area, inspector, or dialog needs shared toolbar/content/footer and child geometry. | Do not pad the pane shell, wrap child-owned geometry in competing insets, invent unrelated centered measures, or leave an icon-only rail for a hidden pane. | Use `.kui-pane` and one `.kui-pane__content`; add `.kui-content` and `.kui-content-item` as needed. A visible pane owns collapse in its toolbar; move a hidden inline-start pane's restore control to the main toolbar leading edge and an inline-end pane's restore control to its trailing edge. | Layout hierarchy, reading width, scroll ownership, responsive relocation, and pane visibility state. | `@kerfjs/ui/layout.css` | [Pane anatomy](./layout.md#anatomy) |
 | Menu composition | Navigation sections need full-size rows and the same content-item geometry as every other pane. | Do not add sidebar-specific wrapper padding, shrink targets to icon size, nest an interactive trailing control in `ListItem`, or use a chevron on a row that does not disclose content. Use ordinary links for a different navigation contract. | Compose `ListHeader`, `ListItem`, and `ListActionRow` in `.kui-content`; use `ListHeader` toggle mode with real controlled content, and use `.kui-content-item` for other surfaces plus a pane footer for toolbar actions. | Information architecture, disclosure content and state, responsive drawer/shell behavior, and token overrides. | `@kerfjs/ui/layout.css` | [Pane geometry](../README.md#pane-and-content-geometry) |
 | Resizable application pane — `ResizableRegion`, `clampRegionSize`, `resizeRegionFromPointer` | A controlled split pane needs the Kerf separator, collapse state, pointer plus keyboard resizing, or a product-specific decorative grip. | Do not use it for a static two-column layout; use CSS grid. Prefer it over Web Awesome `wa-split-panel` unless that component's distinct API is required. Keep `handleIcon` noninteractive. | Call `wireResizableRegions` from `@kerfjs/ui/wire-resizable-regions` once and retain its disposer. | Size signal, min/max policy, collapse policy, persistence, and optional decorative handle icon. | `@kerfjs/ui/resizable-region` | [ResizableRegion contract](./accessibility.md#resizableregion) |
@@ -167,7 +167,10 @@ forks the package anatomy and spacing contract.
 
 Web Awesome catalog coverage means supported and themed, not preferred. Import
 `@kerfjs/ui/webawesome` for Kerf JSX types, individual component modules for
-registration, and the CSS-only `@kerfjs/ui/webawesome.css` theme.
+registration, and the CSS-only `@kerfjs/ui/webawesome.css` theme. The UX catalog
+marks the superseded or exceptional choices below with a visible `Discouraged`
+tag; Popup remains untagged because low-level anchored positioning can be the
+right primitive.
 
 | Web Awesome choice | Kerf decision |
 | --- | --- |

package/docs/ux-demo.md

@@ -10,9 +10,9 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - The `ListActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, first-line leading-icon alignment for wrapped labels, and an application-owned native popover relationship without nesting controls. The `ListItem` route demonstrates the same multiline leading-icon anchor alongside its single-control navigation contract.
 - The `AppTab` route demonstrates a runtime-filtered domain metadata slot and a decorative replacement close icon without changing TabBar selection, close, reorder, or focus ownership. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
 - Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, feedback, and theme scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component.
-- `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Demo paths resolve to `ui/ux-demo/main.tsx`, the matching `ui/ux-demo/recipes/*.tsx` file, or `ui/ux-demo/webawesome-demos.tsx` according to the canonical entry. First-party component entries additionally derive `ui/src/<browser-subpath>.tsx` from their canonical `delivery.browserImport`.
+- `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, recommendation, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Non-supported Web Awesome recommendations project to a visible `Discouraged` sidebar tag, with Popup as the deliberate conditional exception. Demo paths resolve to the matching `ui/ux-demo/demos/<id>.tsx` or `ui/ux-demo/recipes/*.tsx` file, or to `ui/ux-demo/webawesome-demos.tsx` for Web Awesome entries. `ui/ux-demo/main.tsx` owns only the catalog shell, shared state, routing, and interaction wiring. First-party component entries additionally derive `ui/src/<browser-subpath>.tsx` from their canonical `delivery.browserImport`.
 - Every detail footer groups compact `Demo source` and `Guidance` actions; first-party component details also expose `Component source`. Web Awesome details say `Integration guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.
-- The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
+- The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. Catalog entries can supply short reusable trailing tags; the Web Awesome projection uses them to label exactly the 15 discouraged choices. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
 - The shell itself uses `@kerfjs/ui/layout.css`: sidebars, details, previews, dialogs, and resize specimens share unpadded panes plus self-contained content items. Its sidebar identity uses the Kerf logo beside a vertically centered title, with the subtitle in its own aligned row like `PanelHeader`; the current-view heading is also a toolbar. Collapsing the catalog removes the pane completely and moves its restore action to the main toolbar's leading edge instead of leaving an icon-only rail. The selected view description remains inset below the page toolbar. The checkerboard belongs to the complete scrollable preview region rather than a nested card. A lightly separated footer keeps live status above compact source, guidance, and relationship groups. The focused `ResizableRegion` specimen stretches its surface through the available stage height and reports committed width in that shared status footer; narrow layouts retain local horizontal access when the pane is resized wider than the stage, and the split remains readable at 200% root scaling. Geometry coverage checks wide, intermediate, narrow, and 200% zoom layouts.
 - The composer-form recipe demonstrates one coherent visible form surface with `PanelHeader` title/summary hierarchy, fields and actions on the shared 8px control gutter, and 24px major rhythm. Its conditional error or success `StateBanner` is the only nested semantic surface. Reset synchronizes the upgraded Web Awesome fields' live value properties with their empty controlled attributes and announces `Draft reset`; browser coverage preserves behavior and verifies wide, narrow, dark, validation, success, reset, 200% zoom, and forced-colors states.
 - The list-detail dialog recipe places its header directly on the dialog edge while preserving the header's internal inset, gives the selected project title the complete outer-plus-inner content gutter, lets the value table fill the available detail column between the shared outer margins, and keeps record actions on one outer gutter without an extra content-item inset. Browser geometry coverage protects those relationships at wide and narrow widths.

package/docs/webawesome-theme.md

@@ -54,6 +54,71 @@ pointer targets. Override `--kui-wa-carousel-icon-size`,
 `--kui-wa-carousel-dot-hit-size` on a carousel or containing scope when a
 product needs different geometry.
 
+Form fields carry the same content-item inset as the Kerf primitives: a 1px
+border with 8px inside it (`--wa-form-control-border-width`,
+`--wa-form-control-padding-block`, and `--wa-form-control-padding-inline` are set
+to the `--kui-layout-item-border-width` / `--kui-layout-item-padding` values), so
+a single-line control lands at the standard ~40px height and the value sits 9px
+in from the field edge. Each field's top label is inset by that same border +
+padding (9px) so it lines up with the value inside the field, and is styled
+exactly like a `ListHeader` label — uppercase, `--kui-font-xs`, weight 650, quiet
+foreground. This applies to every free field that exposes a top label
+(`::part(form-control-label)` plus the Slider's `::part(label)`). OTP Input
+exposes `label` instead of `form-control-label`; the theme gives it the same
+uppercase 12px/650 treatment. Inline control labels (Checkbox, Switch) keep
+their natural sentence case.
+
+Known Date's field captions and bordered text-like field hints use the same 9px
+inline inset, keeping secondary text aligned with the value rather than the
+field's outer border. This covers Input, Known Date, Number Input, OTP Input,
+Select, Textarea, and Time Input hints; unbordered group hints retain their own
+natural geometry. OTP Input's label and hint both use the 9px field-text inset.
+
+Checkbox Group and Radio Group option regions receive the shared 8px inline
+outer inset through `::part(form-control-input)`. Unlike bordered fields, these
+groups have no shell of their own, so the explicit margin places their controls
+on the same content-item geometry without adding padding to each option. The
+Color Picker trigger receives the same 8px inline outer inset because it also
+has no bordered field shell. Slider's complete interactive region receives the
+shared 8px logical inline outer inset through `::part(slider)`, keeping its
+track, markers, references, and hint together without moving the label.
+
+Non-field chrome follows explicit, overridable control, surface, and container
+tiers:
+
+- `--kui-wa-control-inset` defaults to the 8px content-item padding. It applies
+  to tabs, tree-item trailing content, tags, and dropdown items. Tree selection
+  also uses Kerf's 8px inline outer margin, so its background reads as an inset
+  list item instead of an edge-to-edge stripe. Buttons already consume the same
+  `--wa-form-control-padding-inline` 8px value at every size, so no extra part
+  override is needed.
+- `--kui-wa-surface-margin` and `--kui-wa-surface-inset` default to 8px.
+  Accordion, Card, Details, Callout, and Include use the margin around their
+  complete surface and the inset within it. Accordion applies the outer margin
+  once to the group rather than separating connected items; Card's header,
+  body, and footer all receive the full inset.
+- `--kui-wa-container-inset` defaults to the 16px homogeneous-group step. Tab
+  Panel retains this roomier tier for unframed panel content.
+
+Badge remains intentionally compact at Web Awesome's intrinsic `0.375em` block /
+`0.625em` inline padding (4.5px / 7.5px at its default 12px text size): it is a
+short status or count, not a content item. Breadcrumb has no bordered or filled
+container, and Scroller delegates item chrome to its slotted children, so both
+retain their upstream geometry. Web Awesome 3.12's free catalog has
+`wa-dropdown-item`, but no `wa-menu-item`; the theme therefore styles the
+supported dropdown item rather than carrying a dead selector.
+
+Override a tier for a product scope after importing the theme:
+
+```css
+.roomy-editor {
+  --kui-wa-control-inset: 0.75rem;
+  --kui-wa-surface-margin: 0.75rem;
+  --kui-wa-surface-inset: 0.75rem;
+  --kui-wa-container-inset: 1.5rem;
+}
+```
+
 Accordion, Details, Breadcrumb, and Kerf Select share
 `--kui-disclosure-icon-scale` (default `.5`) so disclosure and traversal
 chevrons keep the same visual weight. The Accordion and Details components

package/llms.txt

@@ -40,6 +40,21 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   own the geometry (8px inline margin + 1px border + 8px padding). Do not add a
   container padding on top of a content-item's own margin — pick one owner. Use
   `.kui-content` for 24px major vertical rhythm.
+- **Keep Web Awesome on the shared inset tiers.** `webawesome.css` uses
+  `--kui-wa-control-inset` (8px controls/items) and
+  `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside
+  Accordion, Card, Details, Callout, and Include), while
+  `--kui-wa-container-inset` keeps Tab Panel at 16px. Override the tier at the
+  narrowest useful scope instead of restyling individual shadow parts.
+  Checkbox and Radio Group option regions also receive the shared 8px inline
+  outer inset because those groups have no bordered field shell. The Color
+  Picker trigger receives the same inset for the same unbordered geometry.
+  Slider's complete interactive region uses the shared 8px logical inline outer
+  inset without shifting its already-aligned label.
+  Known Date's Month/Day/Year captions and bordered text-like field hints align
+  with field values at the shared 9px border-plus-padding inset. OTP Input's
+  label uses the same uppercase xs/650 treatment and its label and hint share
+  that 9px alignment.
 - **Trust the defaults.** Render a control at its natural size and color (a
   `LucideIcon` is 24px); if it looks wrong, fix the surrounding layout, not the
   control. Never force a component's width/height to size it — that leaves a halo
@@ -130,6 +145,6 @@ declared side effects.
 - [accessibility.md](./docs/accessibility.md): keyboard and ARIA contracts per component.
 - [recipes.md](./docs/recipes.md): production compositions (app shell, list-detail dialog, composer form, …) as copyable references.
 - [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation.
-- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists).
+- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists). The UX sidebar visibly tags superseded and exceptional Web Awesome choices as `Discouraged`; Popup remains an available conditional positioning primitive.
 - [component-catalog.json](./ai/component-catalog.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable facts and exact signatures.
 - [README.md](./README.md): package overview and the component subpath table.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.15",
+  "version": "5.0.0-beta.17",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",