@kerfjs/ui 5.0.0-beta.8 → 5.0.0-beta.80

package/docs/ui-analyzer.md

@@ -0,0 +1,404 @@
+# 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).     |
+| `KUI-L023` | error  | A source module renders another component's public class as its own markup.           |
+
+For `KUI-L004` and `KUI-L007`, scroll and inset declarations belong to the
+subject of each CSS selector. An ancestor class used only to qualify a
+descendant selector is not treated as a scroll owner or inset source.
+
+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-L023`)
+
+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.
+
+A component may freely style raw HTML and Web Awesome elements it renders and
+controls in its own stylesheet. A nested Kerf or application component remains
+a separate owner. A thin composition that only connects children should
+normally have no stylesheet; if it owns raw wrapper markup or layout, its CSS
+may style that markup while these diagnostics continue to reject child
+overrides. “Thin composition” is architectural guidance rather than a static
+classification, so Doctor reports concrete ownership violations instead of
+rejecting every stylesheet attached to a `kind: composition` catalog entry.
+
+- **`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. It also catches a raw descendant of
+  cataloged component anatomy, such as `.kui-app-tab__select > svg`, even when
+  the component class is not the final compound. A component root used only as
+  context (`.kui-toolbar > .my-widget`) and app-named descendants remain
+  available for app-owned content. In component mode, classless element subjects
+  are also reported below a hook class placed on an imported component, below
+  another entry's root in the same package, or at a direct child root whose
+  JSX parent composes only a component with that cataloged `rootElement` type.
+  Descendant selectors also see a composed child's cataloged root and
+  `descendantElements` below an own wrapper. `LucideIcon` publishes `svg` and
+  its Lucide SVG child tags, so `.wrapper > svg`, `.wrapper svg`, and
+  `.wrapper path` can name the composed icon. Ambiguous evidence from multiple
+  different child components is discarded. For arbitrary custom `IconNode`
+  child tags outside the cataloged SVG tag list, a selector rooted at
+  `svg[data-lucide]` identifies the descendant as
+  LucideIcon-owned (for example `svg[data-lucide] filter`). Without that root
+  marker, an unknown tag beneath a wrapper remains ambiguous and is not
+  attributed to LucideIcon or to unrelated HTML.
+  The scan follows returned JSX from
+  same-module function and arrow-function components at their call sites,
+  recursively with a cycle guard; their intrinsic elements remain app-owned.
+  The finding names the composing
+  class and component. 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. This also checks components nested in JSX prop values
+  (such as `Toolbar.leading`) and application-owned classes placed on another
+  component's root. The evidence names the stylesheet, line, and selector.
+  For cataloged application components, the import may be direct and relative
+  or use an exact or wildcard TypeScript `paths` alias from the nearest
+  `tsconfig.json` inside the analyzed root (including inherited options).
+  Unresolved aliases remain unclassified; the analyzer does not execute code.
+- **`KUI-L023` — borrowed component markup.** An intrinsic JSX element, raw
+  HTML class attribute, `classList.add`/`toggle`/`replace`, `className`
+  assignment, or `setAttribute('class', …)` writes another cataloged
+  component's public class. The package boundary applies by default;
+  component mode also protects sibling modules through `componentSource`.
+  A component's own source and its `placeableClasses` remain allowed. Findings
+  name the class, owner, write site, and configuration route. This diagnostic
+  scans raw HTML in plain strings and the static segments of interpolated
+  template literals. When a substitution interrupts a class value, only
+  complete literal tokens are reported; split tokens are not guessed. It
+  skips test modules (`*.test.*`, `*.spec.*`, and files under `__tests__/`),
+  where HTML literals commonly assert on output rather than render markup.
+
+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.
+
+Pass `ownership: 'component'` to `analyzeUiProject` to enforce the boundary
+between components in one package. Selection entries with `source` participate
+even without a composition entry. Each entry owns its declared `styleSources`
+for CSS and its selection `source` module for JSX; when `styleSources` is absent,
+direct relative CSS imports from that source are used. The analyzer also derives
+literal JSX `class` and `className` values whose BEM block is styled in those
+stylesheets. A root or styled literal establishes ownership of the whole BEM
+block: `block`, `block__*`, and `block--*`, including dynamically constructed
+element and modifier names. The boundary applies to selectors and markup class
+writes, including a class prop on an imported component. Modules that share a
+stylesheet co-own its classes, whether the stylesheet was declared or directly
+imported; a source that imports none of an owner's stylesheets remains foreign.
+When several entries infer the same class from a shared stylesheet, the
+analyzer does not arbitrarily assign that class to one of them for `KUI-L019`.
+It reports one `KUI-L019` for a rule whose subject is that class or a dynamic
+member of its BEM block when the stylesheet is foreign to every co-owner. The
+finding names the co-owner set in `evidence.components`; their shared
+stylesheet remains allowed.
+Other sibling files are foreign.
+Paths are relative to the entry's package root. Set
+`implicitComponentOwnership: true` to apply the same source and stylesheet
+inference to modules with direct CSS imports that have no catalog entry.
+For a shell stylesheet imported once but used by style-less modules, pass
+`ownershipGroups: [{ styleSources: ['src/style.css'], sources: ['src/main.tsx', 'src/app/'] }]`.
+The paths are relative to the analyzed package root. A source ending in `/`
+matches every module below that directory; other source paths match exactly.
+Each group owns the subject classes in its stylesheets for `KUI-L019` and
+`KUI-L023`. Its stylesheet and listed source modules share one owner, while
+sibling stylesheets and modules remain foreign. This option applies only with
+`ownership: 'component'`.
+Set `ownershipContext: 'any'` alongside component ownership when one sibling
+component must not mention another sibling's class anywhere in a CSS selector.
+The default, `'subject'`, checks the styled subject. Strict findings use
+`KUI-L019` with `evidence.via: 'context'` and a `position` of `ancestor`,
+`sibling`, `has`, `is`, `where`, or `not`. Set
+`ownershipContext: 'any-package'` to apply the same context rule to components
+from other packages, including their public classes and `[data-component]`
+roots. The `'any'` mode continues to allow cross-package context.
+
+### 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.
+
+`KUI-C101` was likewise retired when Toolbar zones were aligned with their
+`KerfUiContent` props. Direct content is valid; `ToolbarControlGroup` remains a
+presentation choice for shared control chrome. The id stays in the registry so
+existing profile exceptions still load, but new profiles should not use it.
+
+## 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`, `KUI-L022`, or `KUI-L023`:
+those indicate a
+definite boundary or parsing failure rather than an aesthetic judgment.

package/docs/ui-doctor.md

@@ -0,0 +1,202 @@
+# Kerf UI doctor
+
+`kerf-ui-doctor` is the supported repair-loop entry point for a Kerf application. It produces one versioned report from application-profile and catalog validation, TypeScript, the Kerf UI ESLint preset, static layout analysis, and an explicitly enabled browser evaluation.
+
+```sh
+npx kerf-ui-doctor --full
+npx kerf-ui-doctor --changed
+npx kerf-ui-doctor --package @acme/admin --changed
+npx kerf-ui-doctor --full --browser-url http://127.0.0.1:4173
+npx kerf-ui-doctor --full --fail-on warning
+```
+
+The default terminal output is short and repair-oriented. `--format json` emits the schema-version-1 report; `--output report.json` writes the same representation. The package exports its contract from `@kerfjs/ui/doctor`, its configuration schema from `@kerfjs/ui/doctor/config.schema.json`, and its report schema from `@kerfjs/ui/doctor/report.schema.json`.
+
+## Stages and trust boundary
+
+The catalog stage discovers the package-default application UI profile and workspace/root-to-leaf directory layers. It validates referenced selection/composition catalogs and, when a workspace declares `package.json#kerfComponentCatalog`, invokes the installed `create-kerf-component` catalog checker to validate metadata, source exports, schema conformance, and generated-output drift. This checker reads source text; it does not import application modules.
+
+TypeScript uses the compiler API with `noEmit`. ESLint loads the installed `eslint-plugin-kerfjs` `recommended-ui` preset (`--eslint strict-ui` opts into advisory rules as errors). This is deliberately an isolated Kerf lint pass rather than the consumer's complete ESLint configuration. For each file, the doctor projects the applicable core ESLint rules and `linterOptions` from the consumer configuration so core-rule suppression directives retain the same used/unused semantics as the application's normal lint command. Consumer plugin rules are not executed, and inline directives for plugins such as `@typescript-eslint` therefore do not produce false "rule definition not found" diagnostics; the consumer's normal ESLint command remains authoritative for those rules. Unknown `kerfjs/*` directives still fail the doctor pass. Stable KUI identifiers come from the packaged `application-ui-diagnostic-ids-v1.json` registry; the doctor also reads installed ESLint message metadata for semantic conflict detection instead of duplicating rule definitions. The analyzer calls the public `@kerfjs/ui/analyzer` contract. None of these stages executes generated application code.
+
+Property-specific CSS values are evaluated from each first- or third-party
+catalog entry's `cssValueProps`. `KUI-L013`–`KUI-L016` are blocking grammar
+violations and name a preferred shorthand/helper; `KUI-L017` keeps an
+exceptional but valid spacing choice in the review queue. The ESLint and
+analyzer stages share these ids, so the normalized report can be consumed as
+one repair loop without tool-specific translations.
+
+The analyzer stage also reads consumer stylesheets for theme overrides:
+`KUI-L018` is a review finding for a `--wa-color-{tone}-fill-loud` override
+that lacks a governing `--wa-color-{tone}-on-loud` (in the same or an ancestor
+scope, in any stylesheet the same entry loads), or whose literal pair measures
+below 4.5:1 (see [the analyzer rule](./ui-analyzer.md#loud-fill--on-loud-pairing-kui-l018)).
+
+Component ownership is part of the same loop. The analyzer stage reports
+application or third-party CSS that restyles another package's component
+(`KUI-L019`), touches its private `--_*` variables (`KUI-L020`), overrides a
+token a typed prop sets (`KUI-L021`), or styles it through a hook class on its
+root (`KUI-L022`), including components nested in JSX prop values and hooks
+owned by the surrounding application. It also reports source modules that render another
+component's public classes as their own markup (`KUI-L023`), including raw HTML
+and DOM class writes. Raw HTML checks include complete static class tokens in
+interpolated template literals. `KUI-L023` skips `*.test.*`, `*.spec.*`, and `__tests__/`
+modules so output assertions are not mistaken for rendered markup. The ESLint
+stage's `ui-component-ownership` rule reports
+`KUI-L020` / `KUI-L021` in script. Each finding's `action` points at the
+component's configuration, and its message routes a need with no prop to a
+component-gap report instead of an override (see
+[the analyzer rule](./ui-analyzer.md#component-ownership-kui-l019kui-l023)).
+In component mode, `KUI-L019` also follows an owned wrapper to a composed
+child's cataloged root and descendant element types. For example, a wrapper
+around `LucideIcon` cannot size its `svg` or `path` with an element selector;
+use the icon's props or style an app-owned element. The same check follows
+local function components returned from the owner module and treats their
+intrinsic markup as app-owned.
+Unknown custom `IconNode` tags are identified when a selector explicitly
+passes through the icon's `svg[data-lucide]` root; unrelated HTML descendants
+without that marker remain app-owned.
+The analyzer resolves a cataloged application component imported through an
+exact or wildcard TypeScript `paths` alias from the nearest consumer tsconfig,
+so the same root hook-class check applies in those files.
+
+## Component style naming
+
+The analyzer stage also checks colocated JSX/TSX components and stylesheets.
+When a stylesheet has a same-basename component module, or exactly one
+component module imports it, Doctor checks that the stylesheet filename is
+the component's kebab-case name (`KUI-D031`). A component whose returned root
+is its own HTML element must put that kebab-case class on rendered markup
+(`KUI-D030`). Static base tokens in template, concatenated, and conditional
+class expressions count only when every path contains the token.
+An opaque class expression stays unclassified instead of producing a missing
+root-class error.
+For example, `WorkspaceHeader` pairs with `workspace-header.css` and renders
+`.workspace-header`. A local composition catalog can explicitly declare a
+different `boundaries.rootClass` or `publicClasses` and list its stylesheet
+under the selection entry's `styleSources`; Doctor honors that declared alias
+for both checks. The catalog stage remains responsible for validating the
+metadata. Thin components that return another component need no root class,
+even when they render nested HTML as children. Helpers declared in the same
+module share that module's CSS ownership; a module exporting several visual
+components can use a shared stylesheet name. Shared stylesheets declared in
+`ownershipGroups` are exempt from the naming check.
+
+Doctor reports `KUI-D032` when a paired stylesheet selects another module's
+local component class or its BEM descendants or modifiers. Move that
+rule to the owning component's stylesheet or use the component's public
+configuration. This check uses source declarations and CSS selectors; it does
+not execute component code. In changed mode, it reads other component sources
+to resolve ownership but reports only pairs containing a selected path. For
+broader cross-component ownership, including
+cataloged package components and hook classes, enable `ownership: "component"`
+with `implicitComponentOwnership: true` as described above.
+
+Set `"ownership": "component"` in `.kerf-ui-doctor.json` to enforce the same
+boundary between a consumer package's own cataloged components. The default is
+`"package"`. Selection-only entries participate too. A component owns its
+`styleSources` (relative to its package root), or its direct relative CSS
+imports when that list is absent, and its selection catalog `source` module.
+Literal rendered BEM classes are inferred when those stylesheets style their
+block. An owned root or styled literal owns its whole `block__*` and `block--*`
+family, including dynamic names and classes placed on imported components.
+Modules sharing one of those stylesheets co-own its classes, so their
+own markup does not borrow from one another. A class inferred by several
+co-owners has no arbitrary single owner for CSS subject diagnostics. A
+stylesheet foreign to all co-owners receives one `KUI-L019` per subject rule,
+including dynamic BEM modifiers; `evidence.components` names the co-owner set.
+Set `"implicitComponentOwnership": true` to include uncataloged modules
+that directly import CSS. Component mode reports sibling CSS and hook-class
+restyles while allowing a component's own stylesheet and module.
+For an application with reusable or app-level components, the recommended
+policy is `"ownership": "component"`, `"implicitComponentOwnership": true`,
+and `"ownershipContext": "any-package"`. This lets components style raw HTML
+and Web Awesome elements they own while blocking overrides of nested Kerf and
+application components. Thin glue compositions should normally omit CSS; when
+they own wrapper markup or layout, Doctor permits that own CSS and reports any
+selector that crosses into a child component.
+For an entry stylesheet shared by modules without direct CSS imports, configure
+`"ownershipGroups": [{ "styleSources": ["src/style.css"], "sources": ["src/main.tsx", "src/app/"] }]`.
+These package-relative paths define one owner: its stylesheet and every listed
+source file or directory prefix. Doctor reports sibling CSS restyles and markup
+class use as `KUI-L019` and `KUI-L023`. Source paths ending in `/` match a
+directory subtree; other paths match exactly. When implicit ownership is also
+enabled, the group takes precedence over listed source modules and any direct
+import of its stylesheet. An unrelated importer still borrows the group's
+classes; its other stylesheets can retain their own implicit ownership.
+
+Set `"ownershipContext": "any"` to also report a same-package sibling's class
+used as ancestor or sibling context or within `:has()`, `:is()`, `:where()`, or
+`:not()`. The default `"subject"` keeps subject-only context policy; classes
+from another package may still provide context. Set
+`"ownershipContext": "any-package"` to include cross-package component
+classes and `[data-component]` roots in the same selector-context checks.
+
+The browser evaluator is different: it runs the application and is disabled by default. It only runs when configuration supplies `browser.url` or the command receives `--browser-url`. Start and authorize the target application separately.
+
+An unavailable or failed stage does not prevent independent stages from reporting. Its final exit is still a configuration failure, so a partial run cannot appear clean.
+
+## Full and changed modes
+
+`--full` is the default and analyzes the selected package. `--changed` reads tracked and untracked paths from Git unless one or more `--path` values are supplied. An empty changed set is a configuration error instead of a false-clean success. With `--package`, workspace-relative Git paths are converted to package-relative paths before TypeScript, ESLint, and analyzer selection; paths outside the selected package are ignored.
+
+Full traversal treats generated/tool-owned directories (`dist`, `coverage`,
+`node_modules`, `.git`, `.kerf-cache`, `kerf-ui-evidence`, and nested
+`.claude/worktrees` checkouts) as outside application source. Their files are
+excluded consistently from TypeScript, the isolated ESLint pass, analyzer
+discovery, and cache inputs, even when one lives below another application
+directory.
+
+TypeScript constructs the selected package's program so compiler options retain their real meaning. In changed mode, its root inputs are narrowed to changed source files plus the tsconfig's declaration roots, so ambient globals still participate; reported source diagnostics stay scoped to the changed files. Use `--full` for release gates.
+
+## Configuration and suppressions
+
+Place `.kerf-ui-doctor.json` at the workspace root:
+
+```json
+{
+  "$schema": "./node_modules/@kerfjs/ui/doctor/config.schema.json",
+  "schemaVersion": 1,
+  "mode": "full",
+  "ownership": "component",
+  "ownershipContext": "any-package",
+  "implicitComponentOwnership": true,
+  "stages": { "browser": false },
+  "cache": true,
+  "failOn": "warning",
+  "suppressions": [
+    {
+      "id": "legacy-toolbar",
+      "rules": ["KUI-L006"],
+      "target": "src/legacy-toolbar.css",
+      "rationale": "Removed with the toolbar migration in the next release."
+    }
+  ]
+}
+```
+
+A suppression requires a stable id, one or more exact diagnostic ids, an exact portable source path or browser selector, and a substantive rationale. Wildcards, absolute paths, and parent traversal are rejected. Suppressed diagnostics remain in `report.suppressions` with their rationale and do not affect the exit code.
+
+KUI suppression ids are checked against the analyzer, evaluator, doctor, installed ESLint-rule metadata, and diagnostics emitted by available tools. An unknown or stale id is a configuration error rather than a silent no-op. TypeScript `TS####` and namespaced `eslint:*` ids remain valid even when that particular run does not emit them.
+
+The content-addressed cache lives at `.kerf-cache/ui-doctor-v1.json`. Its key covers selected source/config/catalog JSON, package manifests, root and package lockfiles, mode, paths, and configuration. Browser results are never cached. Use `--no-cache` when investigating tool installation changes not yet reflected in a lockfile.
+
+Reports replace the workspace's absolute path with `<repo-root>` and express in-workspace files as portable relative paths. External paths are reduced to `<external>/<basename>`. URLs are excluded from the cache key. Tool messages and evidence receive the same root redaction before output or caching.
+
+## Report and exit contract
+
+Every diagnostic has a stable `id`, `severity`, `stage`, message, and—when applicable—an exact source location with JSON path or DOM context/selector. Analyzer evidence, catalog facts, documentation links, and safe next actions are preserved when the source tool provides them. Identical findings merge with their source stages; same identifiers with conflicting severities remain separate and add `KUI-D003`.
+
+Exit codes are deterministic. `failOn` defaults to `error`; `--fail-on error|review|warning` overrides the config for a run. `review` fails on errors or review findings; `warning` also fails on warnings. Suppressed diagnostics never count. The effective threshold is part of the cache key.
+
+- `0`: no active diagnostics at or above the selected threshold;
+- `1`: repairable application findings;
+- `2`: malformed configuration, unavailable required tooling, or a failed stage;
+- `130`: cancellation.
+
+Warnings and review findings remain visible at every threshold. A cached report keeps its original exit code and labels previously run stages `cached`.
+
+## Monorepos and repair loops
+
+`--package` accepts either a workspace package name or a workspace-relative package path. The doctor uses the selected package for compiler, lint, profile-discovery start, and analyzer scope, while workspace profile precedence and root lockfiles remain authoritative.
+
+A repair agent should run JSON mode, apply only source-located safe changes, and rerun until exit `0`. Do not treat exit `2`, a skipped required stage, or an empty changed selection as clean. Browser evidence is objective input; the evaluator's named subjective rubric still requires human review.