@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/docs/ui-analyzer.md

@@ -13,8 +13,28 @@ 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 TSX/JSX class usage and CSS,
-and reports portable repository-relative locations.
+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
@@ -35,17 +55,35 @@ 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` | review | Consumer CSS forces a public component's dimensions.              |
-| `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.                                    |
+| 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
@@ -53,6 +91,285 @@ findings are deliberately heuristic and do not fail by default; pass
 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` (each array item's member) and
+`iconTile.color` (an object-valued prop's member, skipped when the prop is a
+tone string); 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`.
 
@@ -82,5 +399,8 @@ validator.
 ```
 
 Review findings remain visible until explicitly suppressed. Avoid suppressing
-`KUI-L001`, `KUI-L002`, `KUI-L003`, `KUI-L007`, or `KUI-L009`: those indicate a
+`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

@@ -7,6 +7,7 @@ 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`.
@@ -15,24 +16,216 @@ The default terminal output is short and repair-oriented. `--format json` emits
 
 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. Inline directives for consumer-owned 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.
+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, messages, and severities, so each finding
+merges into one diagnostic and the normalized report can be consumed as one
+repair loop without tool-specific translations. ESLint has no `review`
+severity: the presets configure `ui-exceptional-shorthands` (`KUI-L017`) as
+`warn`, and the doctor reads an ESLint warning for a code the analyzer
+classifies as `review` as that review finding.
+
+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.
 
+## Interface copy capitalization
+
+The analyzer stage also checks visible label copy against the package
+capitalization rule in [Writing interface copy](./writing.md#capitalization).
+Names of commands, controls, views, and fields use title style, following
+Apple's guidance. `KUI-D040` (warning) reports a string or template literal
+passed to a known title-style prop that leaves a word lowercase where title style
+capitalizes it. For example, `<wa-button>Save draft</wa-button>` should be
+"Save Draft", and `<ListHeader label="Needs attention" />` should be "Needs
+Attention". The action names the repaired label.
+
+The check reads `.tsx` and `.jsx` source text only and skips test modules.
+Fixture components that tests render (for example
+`tests/browser/fixtures/*.tsx`) are not test modules and are checked: they
+stand in for application screens, so their copy follows the same rule. It
+covers these string literals:
+
+- `ToolbarText` titles: text with `headingLevel`, a large size, or in a
+  toolbar or panel `title`, `header`, or (unless small) `leading` slot;
+- `ListHeader`, `ListActionRow`, `SplitButton`, and `Combobox` labels;
+- `CatalogExample` and `CatalogExampleStack` labels, which render as a
+  `ListHeader` heading (their `note` stays sentence style and is not read);
+- `EmptyState` and `StateBanner` titles;
+- `PopupMenu` trigger text and item and heading labels, including submenus
+  declared in the same file;
+- `SegmentedControl`, `Select`, and `TabNavigator` choice and tab labels;
+- `NavStack` view titles and `backText`, and `SplitView` `backLabel`;
+- `FieldLabel` text and the static text of a `button` or `wa-button`;
+- the `name` of a panel toolbar's `toggle: { action, name }` object literal
+  (Workbench panels, `CollapsiblePanel`), which names the toggle group and
+  completes its "Show …" / "Hide …" label;
+- region and landmark names: the `label` of `Pane`, `Workbench`, `Toolbar`,
+  `ToolbarControlGroup`, `TabBar`, `NavStack`, `CollapsiblePanel`,
+  `FloatingToolbar`, and `ResizableRegion`; the `ariaLabel` of `SunkenPanel`
+  and `List`; a `Pane`'s `contentLabel`; the panel, toolbar, and pane labels
+  in `Workbench` (`leftRail`, `rightRail`, `bottomDrawer`, `mainToolbar`,
+  `mainBottomToolbar`, `mainPane`), `CollapsiblePanel` (`toolbar`,
+  `bottomToolbar`, `pane`), and `NavStack` (`views`, `bottomToolbar`)
+  configuration declared in the same file; and the `aria-label` of a
+  `section`, `nav`, `aside`, `main`, `header`, `footer`, `form`, or `search`
+  element or an element with a landmark `role`;
+- the `label` of a raw `wa-input`, `wa-select`, `wa-textarea`, or
+  `wa-radio-group`, which is a field or group label;
+- the accessible names of icon-only controls, which the rule also gives title
+  style: `IconButton` and `IconToggleButton` `label`, `PopupMenu` `label`,
+  `SplitButton` `optionsLabel`, `TokenSearchField` `clearLabel`, and the
+  `aria-label` of a `button` or `wa-button` whose only content is an icon. A
+  button with visible text is judged by that text, never by its `aria-label`.
+
+The check is deliberately one-directional, to keep false positives rare:
+
+- It reports only lowercase words. It never reports a capitalized short word,
+  because Apple capitalizes a phrasal verb's particle ("Log In to the
+  Server").
+- It leaves text ending in `.`, `!`, or `?` to sentence style.
+- It judges only a template literal's static words, so
+  `` `Edit ${name} shortcut` `` is reported and the interpolated value never
+  is. A word joined to an interpolation (`` `${count}s` ``) is skipped.
+- It ignores other dynamic values and every sentence-style surface: descriptions,
+  details, placeholders, tooltips, status text, and option text, including
+  `wa-checkbox`, `wa-switch`, and `wa-radio` labels. It does not read
+  `LoadingSpinner` or `Skeleton` labels, which announce a status.
+- It skips tokens containing digits, code, paths, or URLs, and lowercase-led
+  brands such as iOS and macOS.
+- It keeps a minor word inside a longer hyphenated compound lowercase, as
+  between separate words ("Edge-to-Edge", "Up-to-Date").
+- It does not read `ContentItem` `title`, which is a native tooltip.
+
+Suppress `KUI-D040` for a file whose copy is a lowercase brand or product
+name.
+
 ## 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.
+`node_modules`, `.git`, `.kerf-cache`, `kerf-ui-evidence`, Playwright's
+`playwright-report`, `test-results`, and `blob-report`, and nested
+`.claude/worktrees` checkouts) as outside application source. Inside a Git work
+tree it also skips every path the project's ignore rules (`.gitignore`,
+`.git/info/exclude`, and the global excludes file) ignore, so a local test run
+that writes gitignored reports or caches never changes the doctor result.
+These files are excluded consistently from TypeScript, the isolated ESLint
+pass, analyzer discovery, and cache inputs, even when one lives below another
+application directory; a `.gitignore` change invalidates the cache.
 
-TypeScript constructs the selected package's program so compiler options retain their real meaning, while its root inputs are narrowed to changed source files. Use `--full` for release gates.
+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
 
@@ -43,8 +236,12 @@ Place `.kerf-ui-doctor.json` at the workspace root:
   "$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",
@@ -68,14 +265,14 @@ Reports replace the workspace's absolute path with `<repo-root>` and express in-
 
 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:
+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 error diagnostics;
+- `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 but do not fail unless their originating preset promotes them to errors. A cached report keeps its original exit code and labels previously run stages `cached`.
+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