@kerfjs/ui 5.0.0-beta.6 → 5.0.0-beta.61

package/docs/tab-scaffold.md

@@ -7,11 +7,16 @@ opt-in app layouts (see [`../../docs/23-app-layouts.md`](../../docs/23-app-layou
 It is distinct from `TabBar` (document-oriented, reorderable strips).
 
 ```ts
-import { TabScaffold } from '@kerfjs/ui/tab-scaffold';
-import { wireTabScaffold } from '@kerfjs/ui/wire-tab-scaffold';
-import '@kerfjs/ui/tab-scaffold.css';
+import { TabScaffold } from "@kerfjs/ui/tab-scaffold";
+import { wireTabScaffold } from "@kerfjs/ui/wire-tab-scaffold";
 ```
 
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads TabScaffold's stylesheet and those of the components it renders internally
+(the tab `Badge`). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/tab-scaffold.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
 ## Controlled selection
 
 The app owns the active tab (a signal); `TabScaffold` renders every tab's scene
@@ -19,23 +24,102 @@ The app owns the active tab (a signal); `TabScaffold` renders every tab's scene
 clicks.
 
 ```tsx
-const active = signal('home');
+const active = signal("home");
 
 <TabScaffold
   id="app"
   label="Sections"
   active={active.value}
   tabs={[
-    { id: 'home', label: 'Home', icon: <HomeIcon />, content: <HomeStack /> },
-    { id: 'search', label: 'Search', icon: <SearchIcon />, content: <SearchStack /> },
+    { id: "home", label: "Home", icon: <HomeIcon />, content: <HomeStack /> },
+    {
+      id: "search",
+      label: "Search",
+      icon: <SearchIcon />,
+      content: <SearchStack />,
+    },
   ]}
 />;
 
 // once, after first render:
-const dispose = wireTabScaffold(root, { onSelect: (id) => { active.value = id; } });
+const dispose = wireTabScaffold(root, {
+  onSelect: (id) => {
+    active.value = id;
+  },
+});
 ```
 
-Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, and `content`. The
-bottom bar respects the home-indicator safe area (`env(safe-area-inset-bottom)`)
-and keeps 44px targets. On larger device classes, promote the tab set to a
+Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, optional `badge`
+and `badgeLabel` (see [Tab badges](#tab-badges)), and `content`. The
+bottom bar paints through the home-indicator safe area and pads for it and for
+the side insets, while each scene pads for the top and side insets (a scene
+whose only child is a `NavStack` or `Pane` lets that child own them; see
+[Choosing an app layout › Safe areas](app-layouts.md#safe-areas)). The bar keeps 44px targets. Its single-line labels preserve their full line box and
+truncate horizontally with an ellipsis when a destination name exceeds its
+share of the bar. On larger device classes, promote the tab set to a
 `Workbench` rail or a persistent sidebar instead of a bottom bar.
+
+## Scroll divider
+
+The bar has no permanent top border. With `wireScrollDividers(appRoot)`
+installed (see [Layout › Scroll dividers](layout.md#scroll-dividers)), it shows
+a line along its top edge only while the active scene's content continues below
+it — not at the scroll end and not when the content fits. The line keys on
+whatever actually scrolls in the scene: the scene itself or, through a sole
+child, a `NavStack`'s active view or a `Pane`'s content. A `NavStack` with its
+own bottom toolbar sits between them, so that toolbar's line applies instead.
+The line is the bar's always-present 1px top border, colored only while shown,
+so it never moves the bar or a tab.
+
+`chromeDividers` configures it, with the same values as a `Pane`'s: `scroll`
+(the default) follows the scroll state and draws nothing until the wiring runs;
+`always` keeps the line, with or without the wiring; `none` drops it even when
+the wiring reports content below.
+
+## Tab badges
+
+Give a tab a `badge` (a count or short string such as `3`, `"99+"`, or
+`"New"`) to show the iOS tab-bar badge: a compact, solid `danger` `Badge` at the
+top-trailing corner of the tab's icon, growing outward as the text lengthens
+(without an icon it sits above the label). The badge is decorative
+(`aria-hidden`); its meaning reaches assistive technology through `badgeLabel`,
+which the tab folds into its accessible name as `"<label>, <badgeLabel>"`:
+
+```tsx
+{
+  id: "inbox",
+  label: "Inbox",
+  icon: <LucideIcon icon={Inbox} name="inbox" />,
+  badge: unread.value,
+  badgeLabel: `${unread.value} unread`,
+  content: <InboxStack />,
+}
+```
+
+`badgeLabel` defaults to the badge text itself, so supply a localized phrase
+whenever the bare text would be ambiguous. Omitting `badge` (or passing an
+empty string or a non-finite number) renders no badge and leaves the tab's name
+as its label; `0` renders, so pass `undefined` when a count should disappear.
+Keep the text short — clamp large counts (`"99+"`) in the app. The tone follows
+the platform convention and is fixed; do not restyle the badge.
+
+### Dot badges
+
+For new content without a count, pass `badge: true`. The tab shows the iOS
+tab-bar dot — an 8px solid `danger` `Badge` (`size="dot"`) centered on the
+icon's top-trailing corner (above the label without an icon). A dot has no
+text to fall back on, so `badgeLabel` is required by the types:
+
+```tsx
+{
+  id: "feed",
+  label: "Feed",
+  icon: <LucideIcon icon={Rss} name="rss" />,
+  badge: hasNewPosts.value ? true : undefined,
+  badgeLabel: "New activity",
+  content: <FeedStack />,
+}
+```
+
+The tab's accessible name becomes `"Feed, New activity"`. Pass `undefined` to
+clear the dot; `false` is not a badge value.

package/docs/type-contracts.md

@@ -0,0 +1,134 @@
+# Compile-time contracts
+
+Kerf UI rejects invalid integrations at compile time only when TypeScript can
+prove the relationship from one call. The versioned
+[`compile-time-contracts-v1.json`](../ai/compile-time-contracts-v1.json)
+artifact names those guarantees with stable `KUI-T###` ids. Its source fixture
+is compiled twice: against `src/` and against declarations extracted from the
+actual `npm pack` tarball. `npm run check:catalog` also verifies that every
+contract still points to a real catalog entry/import and a symbol in the emitted
+public-signature artifact.
+
+## Strengthened contracts
+
+| ID         | Compile-time guarantee                                                                                                                                                                                                                                                                                                                  |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `KUI-T001` | `ListHeader` is a passive heading, a fully named/icon-bearing trailing action, or a controlled disclosure with `action` + `expanded`. Props ignored by the selected mode are rejected.                                                                                                                                                  |
+| `KUI-T002` | `Select` has a visible `label` or an `ariaLabel`.                                                                                                                                                                                                                                                                                       |
+| `KUI-T003` | A literal `Select.value` belongs to its literal `choices`.                                                                                                                                                                                                                                                                              |
+| `KUI-T004` | A literal `SegmentedControl.value` belongs to its literal `choices`.                                                                                                                                                                                                                                                                    |
+| `KUI-T005` | `expanded`, `expandAction`, and `expandLabel` exist only on `TokenSearchField({ collapsible: true })`.                                                                                                                                                                                                                                  |
+| `KUI-T006` | `TokenSearchEditorAttributes` accepts application `data-*` metadata but rejects component-owned identity, morph, count, and placeholder attributes.                                                                                                                                                                                     |
+| `KUI-T007` | `ToolbarText.maxLines` requires `wrap: true`; it is never silently ignored in typed code.                                                                                                                                                                                                                                               |
+| `KUI-T008` | A literal `TabScaffold.active` id belongs to its literal `tabs`.                                                                                                                                                                                                                                                                        |
+| `KUI-T009` | Adjacent-token keyboard removal requires `onRemoveToken`; disabling removal rejects the now-meaningless callback.                                                                                                                                                                                                                       |
+| `KUI-T010` | Finite public variants have named exported union types, including divider sides, tab activation, banner urgency, and all AppTab, TabBar, ToolbarControlGroup, and Select presentation axes; the convenience root barrel re-exports them.                                                                                                |
+| `KUI-T011` | Semantic component zones use the recursive `KerfUiContent` type: `SafeHtml`, runtime-empty booleans/nullish values, and readonly nested arrays are valid; arbitrary strings, numbers, and signals are rejected. Explicit text positions such as `ListInsetText` retain their text exception.                                            |
+| `KUI-T012` | `List.gap` accepts finite `UiSpaceName` shorthands or a complete branded `CssLength`; raw strings and non-standalone `CssLengthExpression` arithmetic are rejected. `calc(plus(...))` promotes a typed expression to a complete value.                                                                                                  |
+| `KUI-T013` | CSS-valued props preserve property grammar: `List.flex` uses `CssFlex`, `Skeleton` dimensions use `CssSize`/`CssLength`, and choice icons use `CssForegroundColor` (foreground tokens via `uiColor()` or `foregroundColorVar()`; fill tokens such as `uiColor('success-fill-quiet')` are rejected); row declaration strings are absent. |
+| `KUI-T014` | Stable single-root visual components accept the explicit native `slot` attribute. Multi-root `ResizableRegion` and `CollapsiblePanel` remain excluded because no single returned element can own the assignment, and other arbitrary native attributes remain rejected.                                                                 |
+
+`KerfUiContent` lets conditionals and mapped component collections be direct
+siblings without an otherwise-unnecessary `Fragment`:
+
+```tsx
+<List>
+  {intro ? <ListInsetText>{intro}</ListInsetText> : null}
+  {rows.map((row) => (
+    <ListItem label={row.label} />
+  ))}
+</List>
+```
+
+The type is intentionally narrower than core JSX children. Wrap prose in a
+semantic text component, and read signals into components or structural
+conditionals rather than passing signal objects as content.
+
+Literal identity inference is intentionally additive for dynamic applications.
+When choices or ids arrive at runtime and the state signal is correctly typed as
+`string`, widen the component explicitly:
+
+```tsx
+<Select<string> value={loadedValue.value} choices={loadedChoices.value} ... />
+<SegmentedControl<string> value={mode.value} choices={loadedModes.value} ... />
+<TabScaffold<string> active={active.value} tabs={loadedTabs.value} ... />
+```
+
+The widening is an honest statement that TypeScript cannot know the runtime
+dataset. Do not cast a known literal typo merely to bypass the relationship.
+
+## Complete public-surface audit
+
+The following existing contracts were already exact and remain covered by the
+ordinary source/type gates:
+
+- required identity or accessible-name inputs on `AppTab`, `FloatingToolbar`,
+  `NavStack`, `SplitView`, `Workbench`, `TabBar`, `ResizableRegion`,
+  `SegmentedControl`, `TokenSearchField`, and `ValueTable`;
+- finite variants exported or represented as literal props on `DisclosureArrow`,
+  `FloatingToolbar`, `Pane`, `ResizableRegion`, `SegmentedControl`, `StateBanner`,
+  `SunkenPanel`, `ToolbarText`, `CollapsiblePanel`, `Catalog`, and the wire helpers;
+- required controlled-state callbacks on `wireResizableRegions`, `wireTabBars`,
+  and `wireTabScaffold`, and the required app-owned size signals on
+  `wireWorkbench`;
+- mutually exclusive count/badge metadata on `ListHeader`; and
+- protected application metadata boundaries on `AppTab`, `ListItem`,
+  `ListActionRow`, `ListHeader`, `Pane`, `CatalogExample`, and
+  `CatalogExampleStack`.
+
+The remaining components (`LucideIcon`, `DisclosureArrow`, `Toolbar`,
+`ToolbarControlGroup`, `ListInsetControl`, `ListInsetText`, `LoadingSpinner`,
+`Skeleton`, `EmptyState`, `StateBanner`, `ValueTableRow`, and the
+pure helpers) have independent props with no further conditional invalid state
+that TypeScript can truthfully remove. Optional labels on decorative icons and
+unnamed non-landmark surfaces are intentional variants, not missing contracts.
+
+## Boundaries TypeScript cannot prove
+
+Types do not claim to validate:
+
+- the contents of `SafeHtml` slots (for example, “only AppTab children” or “no
+  interactive descendants”);
+- nonempty arrays, unique ids, numeric min/max ordering, or a controlled value
+  loaded from dynamic data;
+- equality between ids rendered in separate calls, elements discovered later in
+  the DOM, or an ARIA relationship's live target;
+- that a caller retained and invoked a wiring disposer; or
+- CSS class/token use inside arbitrary strings.
+
+Those remain catalog `KUI-C###` diagnostics, runtime filtering/guards, lint or
+browser assertions. Encoding them as permissive-looking TypeScript brands would
+move errors into casts without making the integration safer.
+
+## Migration from the earlier declarations
+
+- Add `actionLabel` and `actionIcon` to a non-toggle `ListHeader` action. For a
+  disclosure, set literal `toggle: true`, provide `action` and controlled
+  `expanded`, and remove trailing-action-only props.
+- Give every `Select` either `label` or `ariaLabel`. Use an explicit `<string>`
+  generic only for genuinely dynamic choice data.
+- Put `expanded`/expand-action props behind `collapsible: true`.
+- Replace `wireTokenSearchFields({ keyboard: true })` with either
+  `{ keyboard: { onRemoveToken } }` or
+  `{ keyboard: { removeAdjacentToken: false } }` when only caret navigation is
+  wanted.
+- Add `wrap: true` anywhere `ToolbarText.maxLines` is used.
+- Replace `Toolbar({ divider: false })` with `dividerSides: ''`, which is now
+  the default (a toolbar pinned over scrolling content gets its divider from
+  `wireScrollDividers` through its `Pane`); canonical combinations such as `b`,
+  `tr`, and `trbl` select permanent physical edges.
+- Replace raw `List.gap` strings with a direct spacing shorthand (`"xs"`,
+  `"m"`) or a complete value from `@kerfjs/ui/css-values`. Replace
+  `gap="0.25rem"` with `gap={rem(0.25)}` and wrap sums with `calc(plus(...))`.
+- Replace raw `List.flex` shorthands with `flex(grow, shrink, basis)` or a finite
+  keyword; replace raw Skeleton dimensions with `px`/`rem`/`em`/`pct` builders;
+  and replace raw choice colors with a foreground token such as
+  `uiColor('success-on-quiet')` or an app-owned `foregroundColorVar()`.
+  `SelectChoice.color` rejects fill tokens (`uiColor('success-fill-quiet')`) and
+  unqualified `colorVar()` values because a fill paints a nearly invisible
+  icon.
+- Remove `style` from `ListItem` and `ListActionRow`; use `className`, public
+  tokens, and cataloged props. These breaking cleanups land before 5.0 stable.
+
+JavaScript runtime behavior remains defensive for previously emitted calls, but
+new TypeScript builds report these invalid or ignored combinations.

package/docs/ui-analyzer.md

@@ -0,0 +1,306 @@
+# Static CSS and layout ownership analyzer
+
+`kerf-ui-analyze` checks integration facts that TypeScript and an individual
+ESLint file cannot see across component markup, stylesheets, the component
+catalog, and the application UI profile.
+
+```sh
+npx kerf-ui-analyze --root . --format text src
+npx kerf-ui-analyze --root . --format json --output artifacts/kerf-ui.json
+npx kerf-ui-analyze --root . --format sarif --output artifacts/kerf-ui.sarif
+```
+
+The analyzer is opt-in. Add a project script such as
+`"check:kerf-ui-layout": "kerf-ui-analyze --root . src"`; it never executes
+application code. It discovers `.kerf-ui-profile.json`, joins every declared
+composition catalog by `package:id`, parses literal JavaScript/TypeScript
+component calls, TSX/JSX, and CSS, and reports portable repository-relative
+locations.
+
+An imported component name is resolved to a catalog entry by `package:id`, not
+by display name: several entries share one (the Kerf `Select` and the Web
+Awesome `wa-select` are both "Select"), so the analyzer joins each composition
+entry to its selection-catalog public exports and import subpaths and picks
+the entry that the import actually names. That keeps the Kerf component's
+CSS-value contracts (`KUI-L013`–`KUI-L017`) in force for `Select` and
+`Skeleton`.
+
+Only component exports resolve to an entry. A selection-catalog
+`publicExports` list also carries the helpers a component's props consume
+(`Select` ships `uiColor`, `List` ships `px`, `rem`, and `flex`), and a helper
+never inherits its entry's contracts, so `uiColor({ choices: [...] })` is not
+checked as a `Select` call. A component export is one whose name starts with
+an uppercase letter, the same rule JSX uses to tell a component tag from an
+intrinsic element; `eslint-plugin-kerfjs` applies the identical rule, and the
+package's catalog check fails if a cataloged render function (a value
+returning `SafeHtml`) is lowercase or any other runtime value is uppercase.
+Third-party catalogs should follow the same naming convention.
+
+Analysis is scoped per source file. Each TSX/JSX file resolves package,
+workspace, and parent-to-child directory profiles from its own location, then
+follows its relative CSS imports (including nested CSS `@import`s). Stylesheet
+facts are never pooled across unrelated files or sibling packages, and a shared
+stylesheet's diagnostics are evaluated against every importing source profile.
+A violation stays active when any consumer has not narrowly excepted it;
+duplicate source findings collapse to one result. Directly targeted or orphaned
+CSS uses its own directory profile. A direct changed-file target still brings
+its reachable project-local styles into the report, including quoted or
+unquoted `url()` imports; external package styles remain outside the consumer
+boundary.
+
+Recursive discovery excludes generated and tool-owned trees, including any
+nested `.claude/worktrees` checkout. Those checkouts are separate repositories,
+not application source, and cannot contribute files, diagnostics, profile
+policy, or analysis inputs to the containing application.
+
+## Diagnostics and exit behavior
+
+| Rule       | Kind   | Meaning                                                                               |
+| ---------- | ------ | ------------------------------------------------------------------------------------- |
+| `KUI-L001` | error  | A stylesheet reaches into a private or unknown `.kui-*` selector.                     |
+| `KUI-L002` | error  | A stylesheet references an unknown or private `--kui-*` token.                        |
+| `KUI-L003` | error  | One element combines public classes that claim the same geometry.                     |
+| `KUI-L004` | review | Nested literal classes both add a content inset.                                      |
+| `KUI-L005` | —      | Retired; folded into `KUI-L019` (see below).                                          |
+| `KUI-L006` | review | Literal spacing falls outside Kerf's approved scale.                                  |
+| `KUI-L007` | error  | A declared scroll owner is nested inside another scroll owner.                        |
+| `KUI-L008` | review | A dynamic class expression cannot be classified soundly.                              |
+| `KUI-L009` | error  | A stylesheet cannot be parsed.                                                        |
+| `KUI-L010` | error  | A selector reaches a private Kerf descendant from a public root.                      |
+| `KUI-L011` | error  | A `::part()` target is not cataloged as a public extension point.                     |
+| `KUI-L012` | error  | CSS assigns a Kerf token without a public configuration contract.                     |
+| `KUI-L013` | error  | A CSS-adjacent prop uses an unknown shorthand or raw literal.                         |
+| `KUI-L014` | error  | A typed helper produces the wrong property grammar.                                   |
+| `KUI-L015` | error  | An expression-only helper is passed without a composer.                               |
+| `KUI-L016` | error  | A removed declaration-list escape hatch is used.                                      |
+| `KUI-L017` | review | A valid but exceptional off-scale shorthand needs justification.                      |
+| `KUI-L018` | review | A loud fill override lacks a governing `on-loud`, or the literal pair is below 4.5:1. |
+| `KUI-L019` | error  | A rule's subject is another package's component (class, `data-component`, or tag).    |
+| `KUI-L020` | error  | CSS reads or writes another component's private `--_*` variable.                      |
+| `KUI-L021` | error  | CSS overrides a component token that a typed prop sets.                               |
+| `KUI-L022` | error  | A class placed on a component's root is styled by the application (a hook class).     |
+
+Errors are provable contract violations and make the command exit 1. Review
+findings are deliberately heuristic and do not fail by default; pass
+`--fail-on-review` when a project has reviewed its baseline and wants them to
+gate CI. Text, versioned JSON, and SARIF carry the same stable rule ids,
+source locations, evidence, and ownership chain.
+
+For staged adoption, pass `--adoption`. Ownership-boundary diagnostics are
+reported as review findings so a team can inventory and migrate its baseline;
+combine it with the exact file-and-rule exceptions below for intentional legacy
+integrations. Remove `--adoption` to make unsupported overrides blocking.
+
+Catalog `boundaries.publicClasses` and `boundaries.publicTokens` are explicit
+CSS extension points. A component catalog may additionally list shadow-part
+names in `boundaries.publicParts`; all other `::part()` targets are private.
+Part names are scoped to that entry's `boundaries.rootClass`, so an extension
+point on one component does not authorize the same-named part on another.
+Selectors for application-owned content remain allowed, including in a
+component's context (`.kui-pane > .my-content`): a public class is an
+extension point for naming a context, not for restyling the component itself,
+which `KUI-L019` reports.
+
+Catalog entries may also publish `cssValueProps`. Each path names its grammar,
+finite shorthands, canonical and exceptional scale steps, accepted typed
+helpers, expression-only helpers, raw escape policy, and examples. The analyzer
+uses that same metadata for direct component calls and JSX, including nested
+paths such as `choices[].color`; consumer catalogs receive identical checks.
+Dynamic values remain a type-system responsibility rather than being guessed.
+
+## Component ownership (`KUI-L019`–`KUI-L022`)
+
+Components own their styles and are configured, never overridden. These
+diagnostics apply the package's own `check:css-ownership` rules to
+applications and component packages; the selector parsing is the same module
+(`analyzer/selectors.mjs`), so the package rule and the consumer rule agree on
+which element a selector styles.
+
+- **`KUI-L019` — a rule restyles a cataloged component.** The rule's subject
+  (the rightmost compound of each selector, ignoring `:has()` and `:not()`
+  arguments) names a public class of a cataloged component (`.kui-toolbar`,
+  `.kui-list-item__label`, `.acme-meter`), its `[data-component="…"]` root, or
+  a Web Awesome tag the package themes (`wa-button`, `wa-select`), and the rule
+  sets at least one ordinary property. A `::part()` subject is left to
+  `KUI-L011`; a rule that only sets custom properties is configuration, judged
+  by the token rules. Forcing a component's dimensions is one such restyle
+  and reports here once: `.kui-pane { width: 300px }`.
+- **`KUI-L020` — another component's private variable.** CSS reads or writes a
+  `--_<root>-*` variable of a cataloged component (`--_kui-list-gap`), or any
+  `--_kui-*` variable.
+- **`KUI-L021` — a token a typed prop sets.** CSS assigns `--<root>-<prop>`
+  where the component has that typed prop (`--kui-list-gap` is `List gap`,
+  `--kui-floating-toolbar-inset` is `FloatingToolbar inset`). The message
+  quotes the prop's cataloged example.
+- **`KUI-L022` — a hook class on a component's root.** A literal class on an
+  imported component's JSX (`<Toolbar className="header" />`) is the subject
+  of a rule in a stylesheet that file imports, so the application restyles the
+  component through it. The evidence names the stylesheet, line, and selector.
+
+Every message names the configuration to use (the component's typed props,
+public tokens, and variants from its catalog entry) and ends with the same
+route for a real need that has none: report the component gap to the owning
+package (open a feature request) instead of overriding it.
+
+What stays allowed mirrors the package rule, where a child styles itself in a
+parent's context:
+
+```css
+/* Your own element in a component's context. */
+.kui-toolbar > .my-widget {
+  margin-inline-start: auto;
+}
+/* Keying your own element on a component's state. */
+.shell:has(.kui-select[open]) .my-status {
+  opacity: 0.5;
+}
+/* Configuring a component through a public token with no typed prop. */
+.kui-list {
+  --kui-list-divider-color: var(--kui-color-neutral-border-quiet);
+}
+
+/* KUI-L019, KUI-L020, KUI-L021. */
+.kui-toolbar {
+  padding: 0;
+}
+.app {
+  --_kui-list-gap: 2px;
+  --kui-list-gap: 4px;
+}
+```
+
+Ownership is decided per package: a stylesheet belongs to the package whose
+`package.json` is nearest it, and only other packages' catalog entries are
+foreign to it. A component package built on Kerf UI therefore styles its own
+cataloged components (including `.kui-toolbar > .acme-meter` from its own
+stylesheet) without findings, while an application that restyles
+`.acme-meter` is reported against `@acme/widgets`. All four ids are
+ownership-boundary diagnostics, so `--adoption` reports them as review
+findings. `eslint-plugin-kerfjs`'s `ui-component-ownership` rule reports
+`KUI-L020` and `KUI-L021` in JavaScript and TypeScript (style strings, style
+objects, and `style.setProperty()`), where this analyzer reads only CSS.
+
+### Retired: `KUI-L005` (forced component dimension)
+
+`KUI-L005` used to report, as a review finding, any `width`/`height`/`min-*`/
+`max-*` declaration in a rule that mentioned a public component class
+anywhere in its selector. `KUI-L019` now reports every restyle whose subject is
+a cataloged component — dimensions included — so the subject case was
+double-reported (an error and a review finding for one declaration). Its only
+other shape, a public class as an ancestor
+(`.kui-pane .app-sidebar { width: 240px }`), sizes the application's own
+element in the component's context, which the ownership rules explicitly
+allow. With no unique true positive left,
+the rule was retired rather than narrowed. The analyzer no longer emits it;
+the id stays in `ai/application-ui-diagnostic-ids-v1.json` (listed under
+`retired`) so a profile exception that already names it still loads. Remove
+such exceptions at your convenience.
+
+## Loud fill / on-loud pairing (`KUI-L018`)
+
+The shipped Web Awesome theme pairs every `--wa-color-{tone}-fill-loud` with a
+`--wa-color-{tone}-on-loud` foreground that clears WCAG AA (4.5:1), for the
+`neutral`, `brand`, `success`, `warning`, `danger`, and `pop` tones. A
+stylesheet that overrides a loud fill without also setting that tone's
+`on-loud` keeps the theme's foreground on an unknown fill, so the guarantee no
+longer holds. `KUI-L018` reports such a fill and names each scope that lacks a
+pair, and it reports a pair that is present but measurably fails.
+
+**Which `on-loud` governs a fill.** Each individual selector of the fill
+(after resolving CSS nesting and splitting selector lists) inside its chain of
+at-rules is one scope. An `on-loud` of the same tone governs it when declared:
+
+- in the same scope, in the same or a separate rule, in either order; or
+- in an ancestor scope: a document-root selector (`:root`, `html`, `:host`,
+  `*`), or the leading part of a descendant or child chain (`.shell` governs
+  `.shell .panel` and `.frame > .tile`, but not `.shell-alt .panel` or
+  `.shell.dense`); and
+- under no at-rule, or the same at-rule chain (an unconditional `on-loud`
+  applies inside `@media`, but one under `@media` or `@supports` is not proven
+  to apply to an unconditional fill).
+
+That `on-loud` may live in the same stylesheet or in another one the same
+entry loads: a source module that imports both stylesheets, or a stylesheet
+that reaches both through `@import`. A stylesheet no entry loads with the fill
+does not count. When several candidates apply, the same scope wins (this
+stylesheet first), then the nearest ancestor.
+
+**Contrast, when it can be proven.** When the fill and its governing `on-loud`
+are both literal opaque colors (hex, `rgb()`/`rgba()`, `hsl()`/`hsla()`,
+`white`/`black`, or a `light-dark()` of two of them), the analyzer computes the
+WCAG contrast ratio in each color scheme and reports a pair below 4.5:1, with
+the ratio and scheme in its evidence. An unpaired literal fill is accepted when
+it clears 4.5:1 in both schemes against the theme's default `on-loud` for its
+tone (`light-dark(#fff, #111113)` for `brand` and `danger`, `#1d1d1f` for
+`success` and `warning`); `neutral` follows a surface token and `pop` has no
+Web Awesome default, so their unpaired fills are always reported. Values it
+cannot prove (`var()`, `color-mix()`, translucent colors, keywords) are not
+measured: a present pair is accepted, and an unpaired fill is reported.
+
+```css
+/* KUI-L018: brand fill moves, its foreground does not. */
+.billing {
+  --wa-color-brand-fill-loud: #7540a8;
+}
+
+/* Paired: both in the same scope. */
+.billing {
+  --wa-color-brand-fill-loud: #7540a8;
+  --wa-color-brand-on-loud: #ffffff;
+}
+
+/* Paired through an ancestor scope (6.87:1). */
+:root {
+  --wa-color-brand-on-loud: #ffffff;
+}
+.billing {
+  --wa-color-brand-fill-loud: #7540a8;
+}
+
+/* KUI-L018: present, but white on this fill measures 2.14:1. */
+.billing {
+  --wa-color-brand-fill-loud: #7fb3ff;
+  --wa-color-brand-on-loud: #ffffff;
+}
+```
+
+It is a review finding rather than an error because the analyzer cannot see
+every cascade: an `on-loud` set inline, by script, or by a stylesheet it does
+not analyze may still govern the fill. Set the `on-loud` explicitly beside the
+fill, which also documents the pair; use `--fail-on-review` to gate it in CI.
+See [the Web Awesome theme customization notes](./webawesome-theme.md#customization).
+
+The JSON report schema is exported as
+`@kerfjs/ui/analyzer/report.schema.json`.
+
+Profile discovery, parsing, catalog-loading, and validation diagnostics retain
+their stable `KUI-P###` ids in every output format and count as errors. The
+analyzer therefore cannot silently pass with stale or unreadable policy input.
+
+The analyzer is conservative about dynamic class expressions: it emits one
+review finding and does not guess which selectors, tokens, or owners the value
+might contain. CSS values expressed through public variables or `calc()` are
+also left to their owning token contract rather than reverse-engineered.
+
+## Narrow exceptions
+
+Use the application profile's `exceptions` only for an exact rule and exact
+repository-relative file. Every exception requires an id and rationale; broad
+directories, globs, absolute paths, and traversal are rejected by the profile
+validator.
+
+```json
+{
+  "id": "legacy-inspector-spacing",
+  "rules": ["KUI-L006"],
+  "target": "src/legacy/inspector.css",
+  "rationale": "The legacy inspector retains its measured spacing until migration."
+}
+```
+
+Review findings remain visible until explicitly suppressed. Avoid suppressing
+`KUI-L001`, `KUI-L002`, `KUI-L003`, `KUI-L007`, `KUI-L009`, `KUI-L010`,
+`KUI-L011`, `KUI-L012`, `KUI-L013`, `KUI-L014`, `KUI-L015`, `KUI-L016`,
+`KUI-L019`, `KUI-L020`, `KUI-L021`, or `KUI-L022`:
+those indicate a
+definite boundary or parsing failure rather than an aesthetic judgment.