@kerfjs/ui 5.0.0-beta.4 → 5.0.0-beta.40

package/evaluator/report.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/evaluator/report.schema.json",
+  "title": "Kerf UI browser evaluation report",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "tool",
+    "target",
+    "recordedAt",
+    "profileFiles",
+    "contexts",
+    "diagnostics",
+    "summary",
+    "artifacts",
+    "subjectiveReview"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "tool": {
+      "type": "object",
+      "required": ["name", "reportVersion"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "const": "@kerfjs/ui/evaluator" },
+        "reportVersion": { "const": 1 }
+      }
+    },
+    "target": {
+      "type": "object",
+      "required": ["url"],
+      "additionalProperties": false,
+      "properties": { "url": { "type": "string", "minLength": 1 } }
+    },
+    "recordedAt": { "type": "string", "format": "date-time" },
+    "profileFiles": { "$ref": "#/$defs/stringList" },
+    "contexts": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/context" }
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/diagnostic" }
+    },
+    "summary": { "$ref": "#/$defs/summary" },
+    "artifacts": {
+      "type": "object",
+      "required": ["retention", "files"],
+      "additionalProperties": false,
+      "properties": {
+        "retention": { "enum": ["always", "on-failure", "never"] },
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "sha256"],
+            "additionalProperties": false,
+            "properties": {
+              "path": { "type": "string", "minLength": 1 },
+              "sha256": {
+                "type": "string",
+                "pattern": "^[a-f0-9]{64}$"
+              }
+            }
+          }
+        }
+      }
+    },
+    "subjectiveReview": {
+      "type": "object",
+      "required": ["status", "rubric", "ratings", "note"],
+      "additionalProperties": false,
+      "properties": {
+        "status": { "const": "not-recorded" },
+        "rubric": {
+          "type": "array",
+          "minItems": 6,
+          "items": {
+            "type": "object",
+            "required": ["id", "prompt"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "prompt": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "ratings": { "type": "array", "maxItems": 0 },
+        "note": { "type": "string", "minLength": 1 }
+      }
+    }
+  },
+  "$defs": {
+    "stringList": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "summary": {
+      "type": "object",
+      "required": ["errors", "warnings", "passed"],
+      "additionalProperties": false,
+      "properties": {
+        "errors": { "type": "integer", "minimum": 0 },
+        "warnings": { "type": "integer", "minimum": 0 },
+        "passed": { "type": "boolean" }
+      }
+    },
+    "context": {
+      "type": "object",
+      "required": [
+        "id",
+        "browser",
+        "width",
+        "height",
+        "zoom",
+        "colorScheme",
+        "reducedMotion",
+        "evidence",
+        "summary"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "browser": { "enum": ["chromium", "firefox", "webkit"] },
+        "width": { "type": "integer", "minimum": 1 },
+        "height": { "type": "integer", "minimum": 1 },
+        "zoom": { "type": "number", "minimum": 1 },
+        "colorScheme": { "enum": ["light", "dark"] },
+        "reducedMotion": { "enum": ["reduce", "no-preference"] },
+        "evidence": { "type": "object" },
+        "summary": { "$ref": "#/$defs/summary" }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "required": ["code", "severity", "context", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "code": { "type": "string", "pattern": "^KUI-B[0-9]{3}$" },
+        "severity": { "enum": ["error", "warning"] },
+        "context": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "repair": { "type": "string", "minLength": 1 },
+        "selector": { "type": "string", "minLength": 1 },
+        "evidence": {}
+      }
+    }
+  }
+}

package/llms.txt

@@ -1,45 +1,273 @@
 # @kerfjs/ui
 
-Accessible, production-backed UI primitives for kerf applications.
+> Accessible, production-backed UI primitives for [kerf](https://github.com/brianwestphal/kerf)
+> applications. Components are plain functions returning `SafeHtml`; the app owns
+> state and wires stable `data-action` hooks once. This file orients an LLM to
+> generate correct, good-looking kerf UI — it is not a catalog to browse.
 
-- [Package guide](./README.md)
-- [AI skill](./ai/skill.md)
-- [Machine-readable component catalog](./ai/component-catalog.json)
-- [Public API signature snapshot](./ai/public-api-signatures-v1.md)
-- [Web Awesome JSX signature snapshot](./ai/webawesome-jsx-signatures-v1.md)
-- [Need-first component selection matrix](./docs/component-selection.md)
-- [Production composition recipes](./docs/recipes.md)
-- [Component contract](./docs/component-contract.md)
-- [Web Awesome theme contract](./docs/webawesome-theme.md)
-- [Accessibility and keyboard contracts](./docs/accessibility.md)
-- [Design philosophy](./docs/design-philosophy.md)
-- [Apple HIG translation](./docs/apple-hig.md)
-- [UX catalog](./docs/ux-demo.md)
+```bash
+npm install kerfjs @kerfjs/ui # kerfjs is a peer; Web Awesome is an optional peer
+```
 
-The UX catalog is a category-grouped master/detail review surface with a focused route for every public visual component plus composition demos. Its collapsible ecosystem section also lists all 70 free Web Awesome 3.12 components, each with a focused themed route. Related entries use one grouped `Uses` / `Used by` selector across both sets; the shell, display preferences, and selected component share one semantic theme.
+Import each component from its own subpath (`@kerfjs/ui/list-item`, `@kerfjs/ui/toolbar`,
+…); the browser build pulls that component's reachable CSS automatically, so do not
+maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 
-Choose from the interface need: search the catalog, reuse a semantic match, compose existing primitives, add a thin application adapter for product concerns, and use custom markup only for a genuinely different contract. The selection matrix covers every public visual/helper export and the supported-but-not-preferred Web Awesome overlaps, including required wiring, application ownership, import subpaths, alternatives, and recipe links.
+## How to build a screen (retrieval order)
 
-There is no `@kerfjs/ui` command-palette runtime export or production recipe. The typed application-local example at `docs/examples/command-palette-adapter.tsx` demonstrates how a missing concept can reuse public layout vocabulary without inventing a package API. Ranking, history, permissions, availability, focus policy, actions, and copy stay in the app; propose recurring behavior upstream.
+1. **Pick the component from the interface need**, not by appearance — read
+   [component-selection.md](./docs/component-selection.md) (the problem→component
+   matrix, with imports, wiring, ownership, and alternatives).
+2. **Get exact signatures before emitting code** — read
+   [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) (real prop names,
+   callback shapes, disposer return types).
+3. **For exhaustive, structured facts** (ids, exports, variants, `publicClasses`,
+   relationships, side effects, and geometry ownership) load the
+   [Machine-readable component catalog](./ai/component-catalog.json) — the
+   canonical checked-in source; its schema is alongside it. Also load the
+   consuming application's catalog extension when present; generate one from the
+   [Consumer catalog extension schema](./ai/component-catalog-extension.schema.json)
+   when app-owned components must participate in selection or alignment.
+   Load the [Composition catalog v2](./ai/component-catalog-v2.json) to
+   mechanically evaluate parents, contexts, zones/cardinality, children, state,
+   wiring, responsive/layout/accessibility rules, and public boundaries. V1
+   remains compatible; v2 joins catalogs by `package:id`. Consumer v2 catalogs
+   use [the v2 extension schema](./ai/component-catalog-extension-v2.schema.json).
+   Load [compile-time contracts](./ai/compile-time-contracts-v1.json) for stable
+   `KUI-T###` ids, exact declaration symbols, and the boundary between rejected
+   source states and relationships that still require runtime/catalog checks.
+   Before generating application UI, discover `.kerf-ui-profile.json` with the
+   shipped [application profile API](./ai/application-ui-profile.mjs). Merge
+   package defaults, workspace policy, then parent-to-child directory policy;
+   honor its package-qualified preferences, approved theme/density, semantic
+   tokens, layout conventions, and narrow source-located exceptions. Validation
+   is catalog-aware per layer, including parent values later overridden by a
+   child; synchronous hosts use [application-ui-profile-sync.cjs](./ai/application-ui-profile-sync.cjs).
+   See the
+   [workspace profile example](./docs/examples/application-ui-profile.json).
+   A zone's optional `jsx.prop` is its only authoritative JSX binding; never
+   infer one from the zone id. Use `children` for one homogeneous primary
+   region and explicit named content prop slots for semantic positions or
+   replacement content. These slots use the recursive `KerfUiContent` type:
+   `SafeHtml`, runtime-empty boolean/nullish values, and readonly nested arrays.
+   Put conditionals and mapped component arrays directly in them; do not add a
+   `Fragment` only to satisfy types. Arbitrary strings, numbers, and signals are
+   rejected unless a component explicitly exposes a text position such as
+   `ListInsetText`. These are typed props, not native `<slot>` elements,
+   wrapper slot components, or a generic `slots` object. Leave unresolved
+   dynamic expressions unknown.
+4. **When authoring a component gallery**, load
+   [catalog-authoring.json](./ai/catalog-authoring.json), then follow its
+   authoritative [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract).
+5. **Apply the rules below and in** [skill.md](./ai/skill.md).
+6. **Before calling an integration complete**, run
+   [`kerf-ui-doctor`](./docs/ui-doctor.md). Its portable JSON report merges
+   profile/catalog, TypeScript, Kerf ESLint, and static analyzer diagnostics;
+   CSS-adjacent component props are checked from catalog `cssValueProps`, so
+   prefer its canonical shorthand or typed helper over raw CSS strings;
+   repair source-located errors until exit 0. Use full mode for release gates;
+   generated `dist`/`coverage`, dependency, cache, evidence, and nested-worktree
+   directories are excluded consistently from every static stage.
+   [`kerf-ui-analyze`](./docs/ui-analyzer.md) remains available when only static
+   layout diagnostics are wanted; its review findings are a bounded human/AI
+   review queue rather than an objective aesthetic score.
+7. **Evaluate the running application** by explicitly enabling the doctor's
+   browser stage or directly invoking
+   [`kerf-ui-evaluate`](./docs/ui-evaluator.md). Preserve its `KUI-B###`
+   browser evidence and screenshots; record hierarchy/rhythm/density/aesthetic
+   ratings separately with a named reviewer rather than presenting them as
+   objective assertions.
 
-AI tools that need exhaustive retrieval should load `@kerfjs/ui/ai/component-catalog.json`. It is the canonical checked-in source for stable ids, exports, purpose, selection guidance, relationships, delivery and side effects, wiring, application ownership, variants, accessibility, public CSS hooks, catalog routes, and current documentation/recipe links. Its adjacent JSON Schema describes the format.
+## Core rules (do the right thing)
 
-Prefer an equivalent component prop or `--kui-*` token for customization. When composition-specific layout needs CSS, the catalog's `publicClasses` arrays are the exact supported anatomy boundary: selectors may join documented public classes, but must not reach into a component by tag, id, attribute alone, or an unlisted class.
+- **Reach for the primitive, not for CSS.** The package is built to look right
+  _unstyled_. Before adding `padding`, `margin`, `width`, `height`, `border`,
+  `background`, a wrapper card, or a decoration, check whether the component, the
+  pane, or the content-item already owns it — it almost always does. Prefer a
+  component prop or a `--kui-*` token; write CSS only for genuinely new structure,
+  and then only join a component's documented `publicClasses` (never reach in by
+  tag/id/attribute or an unlisted class).
+- **Never double-inset.** A `.kui-pane` has no padding; its `.kui-content` children
+  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.
+- **Use `Row` for horizontal and `List` for vertical layout.** Both expose
+  physical `hAlign`/`vAlign` props and typed gaps. Row defaults to left/full,
+  an `xs` gap, and no wrapping; List retains full/top and zero-gap defaults.
+  Use canonical physical `textInsets` or `controlInsets` sides in
+  `t`/`r`/`b`/`l` order; text geometry wins on overlapping sides.
+  `ListInsetText` and `ListInsetControl` inset every side by default and accept
+  the same `sides` grammar for selective edges.
+  List additionally supplies
+  optional typed `gap`, `flex`, vertical scrolling, and canonical
+  `dividerSides` (`t`/`r`/`b`/`l` order). It adds no list semantics; children own
+  those, and only one bounded region should own scrolling. Pass a finite spacing
+  shorthand (`gap="xs"`, `gap="m"`) or a complete `CssLength` from the CSS-free
+  `@kerfjs/ui/css-values` builders; raw CSS strings are rejected. Use `flex()`
+  for List flex, typed lengths for Skeleton geometry, and
+  `uiColor()`/`colorVar()` for choice-icon colors. These brands are intentionally
+  not interchangeable; rows use classes/tokens/props rather than raw `style`.
+- **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. Dialog body and footer use
+  the surface (8px) and container (16px) tiers respectively, independent of the
+  dialog's shared `--spacing`. Override the tier at the narrowest useful scope
+  instead of restyling individual shadow parts.
+  When a dialog provides another dismissal affordance, add `hide-actions` to
+  the `wa-dialog` host; the theme hides its directly exported `header-actions`
+  part without an unsupported chained `::part()` selector.
+  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.
+- `Select` requires a visible `label` or an `ariaLabel` for a visually hidden
+  accessible name. The package names the internal combobox, including custom
+  selected content; consumers do not need shadow-DOM naming workarounds.
+  Import `select/register` once for the canonical animation lifecycle: stale
+  close/show completions cannot override a later request. Consumers must not
+  repair popup timing or anchor placement; raw Web Awesome selects stay native.
+  Use `hint` for supporting text below the control and `placeholderText` only
+  for the empty value inside it; loading placeholders retain the visible hint.
+- **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
+  or a stretched oval.
+- **Toolbars hold only `ToolbarText` and `ToolbarControlGroup`.** Never put a bare
+  button, input, link, or loose markup in a `leading`/`center`/`trailing` zone.
+  Wrap every control — `SegmentedControl`, `Select`, a collapsible
+  `TokenSearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. For an
+  ordinary icon/action control inside the group use a **plain `<button>`** (the
+  group styles it fully) — that is the default; reach for `wa-button` only when you
+  need a Web Awesome feature, chiefly the `slot="trigger"` button of a `wa-dropdown`
+  popup menu. A toolbar popup menu is a `single` `ToolbarControlGroup` around a
+  `wa-dropdown` (its `slot="trigger"` `wa-button` is the toolbar button, kept under
+  `data-morph-skip-children`). Compact mixed groups keep standard item padding
+  and raised selected chrome without an internal separator; the selected item
+  paints over the outer border. For an avatar control, set `content="avatar"` and
+  `avatarImage` on the group instead of inserting an `img`; a lone control paints
+  the group and a multi-button group paints only its pressed highlight.
+- **Use one direct toolbar composition for panel/dialog/page headings.** Put an
+  optional icon in a `ToolbarControlGroup`, an extra-large `ToolbarText` directly
+  in the leading zone, and actions in a trailing group. Supporting copy is
+  app-owned content below. Do not create a private heading wrapper or restyle the
+  toolbar.
+- **Use `Text` for ordinary semantic headings and paragraphs outside toolbar
+  title zones.** Pass a required `h1`–`h6` or `p` variant based on document
+  meaning. It passes native attributes through and owns the standard transparent
+  border plus item padding; keep toolbar titles on `ToolbarText` and list-aligned
+  bare prose on `ListInsetText`.
+- **Space by the five-step scale, by relationship not by eye.** `0`
+  `--kui-space-none`, `4px` `--kui-space-2xs`, `8px` `--kui-space-xs` (inside a
+  group), `16px` `--kui-space-m`, `24px` `--kui-space-l` (between major differing
+  regions). 12px/32px are off-scale exceptions. Prefer direct `Row.gap`/`List.gap`
+  shorthands for repeated rhythm; use `Spacer` for one typed empty width/height
+  or flexible main-axis gap. Use `space`, `px`, `rem`, `em`, `pct`, `lengthVar`, and
+  `calc(plus(...))` for typed runtime composition. `remify()` is source-CSS only.
+- **Keep nested highlight corners concentric.** Inset hover and selection surfaces
+  follow the owning control's pill or rounded shape; their radius is the outer
+  radius minus `--kui-layout-highlight-inset`. Do not give an inner highlight an
+  unrelated radius.
+- **Panes share one child-owned geometry.** Sidebars, main areas, inspectors, and
+  dialogs all use an unpadded `.kui-pane` (optional `.kui-pane__toolbar`, one
+  scrolling `.kui-pane__content`, optional `.kui-pane__footer`). A visible pane owns
+  its collapse control; a hidden pane's restore moves to the adjacent main
+  toolbar's matching edge — no icon-only rail. Keep one scroll owner per region.
+- **State and behavior live in the app.** Components take semantic `data-action`
+  strings and controlled values; wire them once with `delegate()`/`delegateActions()`
+  or the disposer-returning `wire…` helpers, and own domain copy, transport, and
+  policy in a thin adapter. Every element must earn its place — cut chrome, labels,
+  and readouts that do not help a person decide or act.
+- **App state is domain/persisted; helpers own only ephemeral mechanics.** Keep
+  navigation stacks, tab selection and order, pane sizes, and `collapsed`/`expanded`
+  disclosure flags in the app — they are data or persisted layout, and the app reads
+  them to render. The `wire…` helpers own the _ephemeral_ parts: `wireNavStack` the
+  content-slide, per-view top/bottom chrome cross-fade, and focus move/restore
+  (mark a preferred new-view target with `data-nav-focus`), `wireTabBars` the
+  overflow autoscroll, drag preview, and
+  replacement focus after controlled automatic tab activation,
+  `wireResizableRegions` the live drag preview; they report committed changes via
+  callbacks. Managed TokenSearchField clear also preserves open state and replacement
+  editor focus before the next input task, so shortcut-letter typing stays in search.
+  Select All deletion does the same; deletion
+  restoration finishes before the next keystroke rather than on a delayed frame.
+  Persist both query and remaining tokens read from an edited field. The one richer case is `wireTokenSearchFields`, which manages the
+  collapsible field's expand/collapse/focus by default (on, per-behavior opt-out) and
+  exposes the `expanded` signal on its handle — bind it in render or hand in your own
+  via `collapsible.signals`. Do not hand-roll open/collapse/focus that helper
+  provides; but do keep a plain disclosure toggle (a one-line boolean the app already
+  renders from) in the app. For real-app composition it also offers a focusout
+  keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn`,
+  so a sibling suggestions/date popover does not collapse an empty field), opt-in
+  atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via
+  `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an
+  `onEdit({id, editor, event})` input callback (the `InputEvent` lets you gate on `inputType`/`data`) — so the app can drop its own keydown/input
+  boilerplate while still owning parsing and controlled token state.
+- **Placeholder loading state, don't rebuild it.** For a value or component that is
+  still loading, set `placeholder` on the component (`Select`, `ListHeader`,
+  `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`,
+  `AppTab`, `ToolbarText`, `ListActionRow`): it renders its real chrome with value
+  slots as subtle **unanimated** skeleton blocks and interactivity disabled, so a
+  parent composes a faithful loading view (e.g. an inspector) without hand-rebuilding
+  markup. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`
+  (the pure-Kerf primitives avoid Web Awesome), and never animate it — use
+  `LoadingSpinner` for known busy activity instead.
+- **Keep ListItem content inside the row.** The rounded `ListItem` root clips
+  overflowing label, status, and dormant trailing content. Set `multiline` when
+  the primary label should wrap; use `ListActionRow` instead when trailing content
+  must be interactive.
+- **Dialog bodies are lists by default.** Compose rows and sections in `List`,
+  use `DialogSurface bodyInset="none"` when those children own their geometry,
+  and wrap bare prose in `ListInsetText` so it shares the standard list gutter
+  without stacking a second body inset.
+- **Use a StateBanner badge only for compact supporting status.** Pass the
+  optional string `badge` for a terse count or status beside the title. It
+  inherits the banner tone and is announced with the banner, so keep its text
+  meaningful and never rely on color alone.
 
-Before emitting code, load `@kerfjs/ui/ai/public-api-signatures-v1.md` for the exact declaration signatures used by the authoring corpus. It records accepted import paths, prop names, callback shapes, and disposer return types from emitted declarations rather than prose examples.
+## Public exports
 
-Public components: `LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `ToolbarText`, `SegmentedControl`, `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret`, `wireTokenSearchFields`, `MenuItem`, `MenuActionRow`, `MenuHeader`, `ResizableRegion`, `wireResizableRegions`, `AppTab`, `TabBar`, `wireTabBars`, `reorderTabs`, `PageHeader`, `LoadingSpinner`, `Select`, `StateBanner`, `EmptyState`, `DialogHeader`, `ValueTable`, and `ValueTableRow`. `MenuItem`, `MenuActionRow`, `MenuHeader`, and `AppTab` accept typed, runtime-filtered application `data-*` metadata through `rootAttributes`; MenuActionRow `trailingActionAttributes` and MenuHeader `triggerAttributes` additionally support native popover target/action and `aria-controls`/`aria-haspopup`, while component-owned action, identity, selection, disclosure, naming, disabled, icon, and role semantics stay protected. `MenuHeader` uses the mutually exclusive `count` plus required localized `countLabel` pair for non-negative safe-integer section quantities, including zero; it renders the shared neutral pill and joins the spoken phrase to the owning heading or disclosure button. Never concatenate a count into `label` or put numeric content in the legacy non-count `badge` SafeHtml slot. In real toggle mode, omitting `actionIcon` supplies one production 18px `DisclosureArrow` driven by `expanded`; a custom icon replaces it, and the app must reveal matching content. Ordinary navigation must not borrow a disclosure chevron. `AppTab.closeIcon` and `ResizableRegion.handleIcon` replace decorative dormant glyphs without taking control ownership. `MenuItem.trailing` is dormant; use `MenuActionRow` for sibling primary/trailing native buttons, keeping its `label`, `icon`, and `trailingActionIcon` SafeHtml dormant too. `ValueTableRow` owns semantic `dt`/`dd` markup, 8px of root-scaled top and bottom padding, and an optional 24px leading icon; its separator begins 8px from the left without an icon or 40px with one and ends 8px from the right. `DisclosureArrow` is a decorative, controlled open/closed indicator with configurable directions, shortest-path rotation (counterclockwise for a 180-degree closed-to-open tie), replaceable right-oriented icon content, an 18px root-scaled default, and a scoped `--kui-disclosure-arrow-size` override; the owning control retains interaction and expanded-state semantics. `SegmentedControl` is controlled and supports toolbar, rounded-rectangle, and pill presentations with native pressed buttons in sequential Tab order. `Select` preserves icon-bearing option slots across Kerf rerenders, keys custom selected content by the controlled value, and separately keeps its intrinsic Web Awesome expand glyph at `--kui-disclosure-icon-scale: .5`. `TokenSearchField` controls tokens while keeping editable text DOM-owned between token changes, combining free text with ordered atomic filter chips while leaving query parsing and results to the application; its leading icon, first text line, clear action, and trailing slot stay aligned to one fixed row when text wraps. Its optional `collapsible` mode animates between an empty iconic action and the complete field, works standalone or inside `ToolbarControlGroup`, and keeps populated searches expanded while the app controls transient focus/open state. Call `wireTokenSearchFields` once to make Enter submit without inserting a contenteditable line break and to preserve focus plus the text-relative caret across controlled keyboard chip deletion; visual wrapping remains available. Semantic state palettes are opinionated, Web Awesome-compatible, and overridable globally, by tone, or per instance.
+`LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `FloatingToolbar`, `ToolbarText`, `Text`,
+`ListItem`, `ListActionRow`, `ListHeader`, `ListInsetControl`,
+`ListInsetText`, `SegmentedControl`,
+`Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
+`wireTokenSearchFields`), `AppTab`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
+`ResizableRegion` (+ `wireResizableRegions`), `StateBanner`, `EmptyState`,
+`LoadingSpinner`, `Skeleton`, `ValueTable`, `ValueTableRow`. Whole-screen layouts (opt-in,
+tree-shakeable, declarative with `wire…` helpers, each with a companion CSS import):
+`NavStack`, `SplitView`, `Workbench`, `TabScaffold`, driven by `deviceClass()` from
+`@kerfjs/ui/device-class`. For a standalone collapsible rail/drawer outside a full
+shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelToggle`)
 
-`DialogHeader` composes a real top `Toolbar`: its borderless identity group keeps the optional 24px icon in a 34px circular background and the first title line centered against an automatic action `ToolbarControlGroup`. Pass action children directly and add a localized `actionsLabel` when that group needs a name. The optional `summary`/`summaryId` row remains below the title; the application owns modal focus, dismissal, commands, and action handling.
+- `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence).
+  `@kerfjs/ui/catalog` is another opt-in shell — a
+  `Catalog` component + `wireCatalog` helper for building a component-gallery catalog
+  (collapsible category sidebar + preview stage + resources footer, with an opt-in
+  transparent-bound and margin geometry overlay plus focus-preserving active-row
+  reveal for long desktop sidebars) from your own
+  entries; controlled/stateless like the layouts. For any Catalog demo, follow
+  the [authoritative authoring contract](./docs/catalog.md#catalog-demo-authoring-contract)
+  rather than inferring structure from the shell or private CSS.
+  `@kerfjs/ui/webawesome` is a
+  type-only boundary for `wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the
+  declared side effects.
 
-Pane and navigation composition: import `@kerfjs/ui/layout.css` and use an unpadded `.kui-pane` with optional `.kui-pane__toolbar`, one scrolling `.kui-pane__content`, and optional `.kui-pane__footer`. Add `.kui-content` for 24px major vertical gaps. Use `.kui-content-item` for children that own 8px inline margin, 1px transparent-or-visible border, 8px padding, and 12px rounded corners; the pill modifier uses 22px. This vocabulary applies equally to sidebars, main areas, inspectors, and dialogs. A visible collapsible pane owns collapse in its own toolbar. When hidden, move restore into the adjacent main toolbar on the same logical edge—leading for an inline-start pane, trailing for inline-end—and remove the pane instead of leaving an icon-only rail.
+## Reference
 
-Composer form recipe: keep the form as one visible surface, use `DialogHeader` title/summary ids to label and describe it, and align field and action control edges on the shared 8px inline gutter without a second content-item padding inset. Retain 24px major rhythm. A conditional `StateBanner` is the only nested semantic surface. Do not make every form section another card. When resetting controlled upgraded Web Awesome fields, synchronize their live `value` properties as well as the rendered value attributes.
-
-Toolbar and split-item geometry: wrap every toolbar item, including dormant text, in `ToolbarControlGroup`. Groups stay 44px outside (`calc(2px + remify(42px))`) even when their border and background are transparent, with 8px between groups and inside items. `MenuHeader` fills the available inline width and separates its dormant title/count-or-badge cluster from its optional logical-end 44px action; the visible action glyph defaults to 18px through `--kui-menu-header-action-icon-size`, while disclosure mode makes the title cluster the action. `MenuActionRow` keeps primary and trailing 44px actions as sibling native buttons inside a noninteractive row. Multiline `MenuItem` and `MenuActionRow` leading icons stay centered on the first text line while later lines extend below. Do not pad pane shells or add competing wrapper insets. See `docs/layout.md`.
-
-Import visual components from explicit JavaScript subpaths. A CSS-aware browser bundler selects generated wrappers that bring in the foundation, the component CSS, and styles for reachable UI subcomponents; unrelated CSS stays out. The root barrel and `@kerfjs/ui/unstyled` are CSS-free; use `styles.css` with the root barrel only when the complete layer is intentional. Manual CSS exports remain available for custom pipelines, and application overrides follow package styles in the cascade. Direct `wa-*` JSX uses `import type {} from '@kerfjs/ui/webawesome'`, the side-effect-free declaration boundary synchronized with all 70 catalog-supported elements. `@kerfjs/ui/webawesome.css` is the optional CSS-only theme; it includes Web Awesome's base stylesheet, registers no elements, and remains overridable through public `--wa-*` tokens. CSS, its generated browser wrappers, and `@kerfjs/ui/select/register` are the declared side effects. `kerfjs` is an external peer. The Web Awesome peer is optional and needed for its components. `wireTabBars` includes proximity-based horizontal edge autoscroll during same-bar drag reordering.
-
-The Web Awesome theme renders Tooltip and Popover without pointer arrows by default. Restore them only when the anchor relationship needs the pointer, using `--wa-tooltip-arrow-size`, `--kui-wa-popover-arrow-size`, or one popover's public `--arrow-size`; `without-arrow` remains available for explicit local intent.
-
-Web Awesome catalog coverage means themed and inspectable, not preferred. Consider Popup when it replaces custom anchored positioning. Prefer Kerf Select over direct Dropdown/Dropdown Item/Select/Option composition, SegmentedControl over Button Group, TabBar or SegmentedControl over Web Awesome Tabs, LucideIcon over Web Awesome Icon, and ResizableRegion over Split Panel. ResizableRegion carries Hot Sheet 2's 1px separator plus hover/focus grip. Use Tree/Tree Item, Animated Image, and Comparison only for a specific required behavior; avoid Zoomable Frame.
+- [skill.md](./ai/skill.md): the full rule set + a common-mistakes table (the shipped AI skill).
+- [design-philosophy.md](./docs/design-philosophy.md): why kerf UI is shaped this way — the decision principles behind the rules above.
+- [layout.md](./docs/layout.md): the pane/content-item geometry, public roles/tokens, and the spacing scale.
+- [component-contract.md](./docs/component-contract.md): what a component owns vs. what the app owns.
+- [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). 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) + [component-catalog-extension.schema.json](./ai/component-catalog-extension.schema.json) + [catalog-authoring.json](./ai/catalog-authoring.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 selection facts, a reusable app-component extension contract, Catalog authoring discovery, and exact signatures.
+- [compile-time-contracts-v1.json](./ai/compile-time-contracts-v1.json) + [type-contracts.md](./docs/type-contracts.md): stable compile diagnostics, packed-declaration proof, migrations, and explicit non-goals.
+- [README.md](./README.md): package overview and the component subpath table.