eslint-plugin-kerfjs 5.0.0-beta.8 → 6.0.0-beta.1

package/README.md

@@ -7,13 +7,13 @@ ESLint rules that enforce kerf's hard rules. Catches AI-shaped bugs at edit time
 
 This plugin sits alongside two other defense layers shipped by [`kerfjs`](https://brianwestphal.github.io/kerf/):
 
-| Layer | Catches | When |
-|---|---|---|
-| `tsc --noEmit` with strict typings | Hard Rules 8 (partial-set), most type errors | Build time |
-| Opt-in dev-warns (`KERF_DEV_WARN_*`) | Hard Rules 4 (rebuilt listeners), 7 (untracked signals), 8 (narrow set) | Runtime |
-| **This plugin** | Hard Rules 2, 5, 6, 10, 12 — AST-shaped antipatterns; plus rename-safety / `raw()`-audit nudges and a project-hygiene check for the bundled AI-assistant configs | **Edit time** |
+| Layer                                | Catches                                                                                                                                                          | When          |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `tsc --noEmit` with strict typings   | Hard Rules 8 (partial-set), most type errors                                                                                                                     | Build time    |
+| Opt-in dev-warns (`KERF_DEV_WARN_*`) | Hard Rules 4 (rebuilt listeners), 7 (untracked signals), 8 (narrow set)                                                                                          | Runtime       |
+| **This plugin**                      | Hard Rules 2, 5, 6, 10, 12 — AST-shaped antipatterns; plus rename-safety / `raw()`-audit nudges and a project-hygiene check for the bundled AI-assistant configs | **Edit time** |
 
-All but one rule are AST-only — no `@typescript-eslint/parser` *service* dependency is required by the plugin (consumers configure their own parser). The exception, `ai-assistant-configs`, reads the filesystem instead of the AST and runs once per lint pass.
+The core syntax rules analyze the AST without TypeScript parser services. `ai-assistant-configs` reads the filesystem, and the optional UI rules also resolve catalog and profile artifacts. Consumers configure their own parser; no `@typescript-eslint/parser` _service_ is required.
 
 ## Install
 
@@ -21,6 +21,9 @@ All but one rule are AST-only — no `@typescript-eslint/parser` *service* depen
 npm install --save-dev eslint-plugin-kerfjs
 ```
 
+Install `@kerfjs/ui` as well when using `recommended-ui` or `strict-ui`; the
+core `recommended` preset does not require it.
+
 ### Supported ESLint versions
 
 `peerDependencies` declares `^9.0.0 || ^10.0.0`, and that is a **tested** range rather than an optimistic one: the rule suite runs against the latest release of each of those majors in CI on every push. A major is added to the range only after the suite has passed on it.
@@ -33,12 +36,12 @@ A version outside the range is not "probably fine" — it is one nobody has run.
 
 ```js
 // eslint.config.js
-import kerfjs from 'eslint-plugin-kerfjs';
-import tsParser from '@typescript-eslint/parser';
+import kerfjs from "eslint-plugin-kerfjs";
+import tsParser from "@typescript-eslint/parser";
 
 export default [
   {
-    files: ['**/*.ts', '**/*.tsx'],
+    files: ["**/*.ts", "**/*.tsx"],
     languageOptions: {
       parser: tsParser,
       parserOptions: { ecmaFeatures: { jsx: true } },
@@ -48,25 +51,72 @@ export default [
 ];
 ```
 
+Applications using the UI catalog can select one of two additive flat configs:
+
+```js
+export default [
+  // parser/files configuration as above
+  kerfjs.configs['recommended-ui'], // preferences and wiring are warnings
+  // or kerfjs.configs['strict-ui']  // all UI contracts are errors
+];
+```
+
+The UI rules resolve the installed `@kerfjs/ui` selection catalog (`component-catalog.json`), composition catalog (`component-composition.json`), and application profile defaults. They then merge `.kerf-ui-profile.json` files from the workspace root toward the linted file. Package authors and monorepos can provide explicit artifacts without duplicating their facts:
+
+```js
+settings: {
+  kerfjs: {
+    ui: {
+      workspaceRoot: import.meta.dirname,
+      catalogPath: './vendor/component-composition.json',
+      selectionCatalogPath: './vendor/component-catalog.json',
+      profileDefaultsPath: './vendor/application-ui-profile.defaults.json',
+      profileContractPath: './vendor/application-ui-profile-sync.cjs',
+    },
+  },
+}
+```
+
+For deterministic generated configs, the same settings accept parsed `catalog`, `selectionCatalog`, and `profile` objects. File-based precedence is package defaults, then workspace profile, then root-to-leaf directory profiles. The rules load `application-ui-profile-sync.cjs` from the installed `@kerfjs/ui` package by default because ESLint rule creation is synchronous; `profileContractPath` is only needed when artifacts are vendored, and then its directory must also hold `application-ui-diagnostic-ids-v1.json` and `component-class-owners.cjs` (the class-to-component rule `KUI-L103` shares with `@kerfjs/ui`'s generated component pages) from the same `@kerfjs/ui` release. Every raw layer is schema- and catalog-reference-validated before merge, so a child cannot hide malformed or stale parent policy. Exceptions use exact `KUI-L*` diagnostic ids and repository-relative file or directory targets.
+
+`ui-css-values` consumes each catalog entry's property-specific grammar and
+emits `KUI-L013`–`KUI-L017` with a preferred shorthand or helper. It covers JSX,
+direct component calls, nested catalog paths, and explicitly configured
+third-party catalogs; dynamic values remain governed by TypeScript.
+
+`ui-component-ownership` keeps code out of another package's component
+internals: `KUI-L020` reports a reference to a component's private `--_*`
+variable and `KUI-L021` an assignment to a token a typed prop sets (use the
+prop). Each message ends by routing a real need with no prop to a component-gap
+report instead of an override. `kerf-ui-analyze` reports the same ids, plus the
+stylesheet-only `KUI-L019` / `KUI-L022`, for CSS files.
+
+`KUI-L090` is reserved for catalog/profile loading and configuration failures. The supported-ESLint matrix installs real packed `eslint-plugin-kerfjs` and `@kerfjs/ui` tarballs in a downstream flat-config fixture, ensuring these defaults resolve from the consumer rather than this repository's source tree.
+
 ## Legacy `.eslintrc` configs are not supported
 
-The package is ESM-only. ESLint's `.eslintrc` system loads plugins with `require()`, which cannot load an ESM package, so `extends: ["plugin:kerfjs/legacy-recommended"]` fails with *"couldn't find the config to extend from"* on ESLint 8 **and** on ESLint 9's legacy mode.
+The package is ESM-only. ESLint's `.eslintrc` system loads plugins with `require()`, which cannot load an ESM package, so `extends: ["plugin:kerfjs/legacy-recommended"]` fails with _"couldn't find the config to extend from"_ on ESLint 8 **and** on ESLint 9's legacy mode.
 
 Use flat config (`eslint.config.js`), shown above. The `legacy-recommended` export still exists in the package but is unreachable through any config system — treat it as deprecated.
 
-
 ## Rules
 
-| Rule | Hard Rule | Severity (recommended) |
-|---|---|---|
-| [`no-inline-jsx-event-handlers`](docs/rules/no-inline-jsx-event-handlers.md) | 10 — use `data-action` + `delegate()` | `error` |
-| [`require-data-key-in-each`](docs/rules/require-data-key-in-each.md) | 2 — `data-key` per item | `error` |
-| [`require-delegate-disposer`](docs/rules/require-delegate-disposer.md) | 5 — capture `delegate()` disposers when scope < page | `warn` |
-| [`no-nested-mount`](docs/rules/no-nested-mount.md) | 6 — one `mount()` per root | `error` |
-| [`prefer-module-jsx-augmentation`](docs/rules/prefer-module-jsx-augmentation.md) | 12 — augment `kerfjs/jsx-runtime`, not global | `error` |
-| [`prefer-attr-selector`](docs/rules/prefer-attr-selector.md) | — (rename-safety nudge for `delegate()` selectors) | `warn` |
-| [`no-raw-with-dynamic-arg`](docs/rules/no-raw-with-dynamic-arg.md) | — (XSS audit trail) | `warn` |
-| [`ai-assistant-configs`](docs/rules/ai-assistant-configs.md) | — (project hygiene) | `warn` |
+| Rule                                                                             | Hard Rule                                                       | Severity (recommended) |
+| -------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------- |
+| [`no-inline-jsx-event-handlers`](docs/rules/no-inline-jsx-event-handlers.md)     | 10 — use `data-action` + `delegate()`                           | `error`                |
+| [`require-data-key-in-each`](docs/rules/require-data-key-in-each.md)             | 2 — `data-key` per item                                         | `error`                |
+| [`require-delegate-disposer`](docs/rules/require-delegate-disposer.md)           | 5 — capture `delegate()` disposers when scope < page            | `warn`                 |
+| [`no-nested-mount`](docs/rules/no-nested-mount.md)                               | 6 — one `mount()` per root                                      | `error`                |
+| [`prefer-module-jsx-augmentation`](docs/rules/prefer-module-jsx-augmentation.md) | 12 — augment `kerfjs/jsx-runtime`, not global                   | `error`                |
+| [`prefer-attr-selector`](docs/rules/prefer-attr-selector.md)                     | — (rename-safety nudge for `delegate()` selectors)              | `warn`                 |
+| [`no-raw-with-dynamic-arg`](docs/rules/no-raw-with-dynamic-arg.md)               | — (XSS audit trail)                                             | `warn`                 |
+| [`ai-assistant-configs`](docs/rules/ai-assistant-configs.md)                     | — (project hygiene)                                             | `warn`                 |
+| [`ui-public-boundaries`](docs/rules/ui-public-boundaries.md)                     | — (cataloged classes/tokens; component anatomy on app elements) | `error`                |
+| [`ui-component-ownership`](docs/rules/ui-component-ownership.md)                 | — (configure components, never override them)                   | `error`                |
+| [`ui-composition`](docs/rules/ui-composition.md)                                 | — (cataloged parents and zones)                                 | `error`                |
+| [`ui-css-values`](docs/rules/ui-css-values.md)                                   | — (cataloged property-specific value grammar)                   | `error`                |
+| [`ui-preferences`](docs/rules/ui-preferences.md)                                 | — (application component choices)                               | `warn`                 |
+| [`ui-wiring`](docs/rules/ui-wiring.md)                                           | — (required setup and cleanup)                                  | `warn`                 |
 
 The "Hard Rule" column refers to the numbered rules in [`docs/ai/usage-guide.md`](../docs/ai/usage-guide.md) on the main kerf repo. `no-raw-with-dynamic-arg` and `ai-assistant-configs` don't map to numbered Hard Rules — the former creates an audit trail for every dynamic `raw()` call site (potential XSS); the latter checks that the bundled AI-assistant configs are installed and current. See [`docs/12-ai-assistant-configs.md`](../docs/12-ai-assistant-configs.md) on the main kerf repo for the AI-configs design.
 
@@ -81,6 +131,7 @@ When a real bug ships that the existing defense stack misses AND a new lint rule
 ```bash
 npm install
 npm test
+npm run test:eslint-matrix # real packed-plugin loading on every supported ESLint major
 ```
 
 The AST rules' test suites use ESLint's `RuleTester` with `@typescript-eslint/parser`. The `ai-assistant-configs` tests are filesystem-driven — they build temp project roots with fixture `node_modules/kerfjs/ai/` bundles, drive the classifier directly, and use the real ESLint API to prove plain lint is read-only while explicit `--fix` performs the external write.

package/docs/rules/ai-assistant-configs.md

@@ -10,10 +10,10 @@ Maps to design doc [`docs/12-ai-assistant-configs.md`](https://github.com/brianw
 
 The rule resolves `kerfjs/ai/manifest.json` from the consumer's installed `kerfjs` (silently no-ops if `kerfjs` isn't a dep). For each bundled file, it picks a trigger heuristic — "is this project using the tool this file is for?" — and only nudges the consumer when the trigger says yes:
 
-| Bundled file | Triggers when | Installed to |
-|---|---|---|
-| `ai/skill.md` (Claude Code) | `.claude/` directory exists at the project root | `.claude/skills/kerf-app/SKILL.md` |
-| `ai/cursorrules` (Cursor) | `.cursorrules` file or `.cursor/` directory exists | `.cursorrules` |
+| Bundled file                | Triggers when                                      | Installed to                       |
+| --------------------------- | -------------------------------------------------- | ---------------------------------- |
+| `ai/skill.md` (Claude Code) | `.claude/` directory exists at the project root    | `.claude/skills/kerf-app/SKILL.md` |
+| `ai/cursorrules` (Cursor)   | `.cursorrules` file or `.cursor/` directory exists | `.cursorrules`                     |
 
 A triggered file is then classified into one of three reported states (a fourth, "up-to-date," is silent):
 
@@ -78,4 +78,4 @@ Both `claude` and `cursor` default to `true`. Setting either to `false` makes th
 - It does not install the configs at `npm install` time — there are no postinstall scripts. The first lint pass after `npm install kerfjs` surfaces the recommendation.
 - It does not write to disk under plain `eslint` (no `--fix`). The warning is emitted; nothing changes on disk.
 - It does not push Claude Code or Cursor on consumers who haven't signalled they use them — no `.claude/` or `.cursor*` ⇒ silent.
-- It does not validate the *content* of the canonical files in the bundle. That's the kerf maintainer's responsibility (and the `check:ai-bundle-in-sync` gate in the kerf repo).
+- It does not validate the _content_ of the canonical files in the bundle. That's the kerf maintainer's responsibility (and the `check:ai-bundle-in-sync` gate in the kerf repo).

package/docs/rules/no-inline-jsx-event-handlers.md

@@ -40,8 +40,8 @@ delegate(rootEl, 'submit', ACTIONS.submit.selector,  submit);
 String literals still work for ad-hoc fixed selectors:
 
 ```tsx
-<button data-action="save">Save</button>
-delegate(rootEl, 'click', '[data-action="save"]', save);
+<button data-action="save">Save</button>;
+delegate(rootEl, "click", '[data-action="save"]', save);
 ```
 
 ## Why this rule is AST-only

package/docs/rules/no-nested-mount.md

@@ -24,7 +24,12 @@ mount(bodyRoot, () => <Body />);
 
 // Composition via plain functions:
 const Header = () => <h1>{title.value}</h1>;
-const Body = () => <main><Header /><div>{count.value}</div></main>;
+const Body = () => (
+  <main>
+    <Header />
+    <div>{count.value}</div>
+  </main>
+);
 mount(root, () => <Body />);
 ```
 

package/docs/rules/no-raw-with-dynamic-arg.md

@@ -9,21 +9,21 @@ Warn when `raw()` is called with a dynamic argument (any expression that is not
 ## ❌ Incorrect
 
 ```ts
-raw(userInput)                     // variable reference
-raw(fetchedHtml())                 // function call
-raw(`<b>${title}</b>`)             // template literal with expressions
-raw(isAdmin ? adminHtml : guestHtml)  // conditional expression
+raw(userInput); // variable reference
+raw(fetchedHtml()); // function call
+raw(`<b>${title}</b>`); // template literal with expressions
+raw(isAdmin ? adminHtml : guestHtml); // conditional expression
 ```
 
 ## ✅ Correct
 
 ```ts
-raw('<p>Static markup</p>')        // string literal — no warning
-raw(`<p>Static template</p>`)      // expression-free template literal — no warning
+raw("<p>Static markup</p>"); // string literal — no warning
+raw(`<p>Static template</p>`); // expression-free template literal — no warning
 
 // Dynamic but audited — suppress with eslint-disable
 // eslint-disable-next-line kerfjs/no-raw-with-dynamic-arg
-raw(DOMPurify.sanitize(marked(userMarkdown)))
+raw(DOMPurify.sanitize(marked(userMarkdown)));
 ```
 
 ## Why `warn` and not `error`

package/docs/rules/prefer-attr-selector.md

@@ -7,8 +7,8 @@ Prefer `attr('name', 'value').selector` over a literal `[name="value"]` selector
 ## ❌ Discouraged
 
 ```tsx
-<button data-action="toggle">Toggle</button>
-delegate(root, 'click', '[data-action="toggle"]', handler);
+<button data-action="toggle">Toggle</button>;
+delegate(root, "click", '[data-action="toggle"]', handler);
 ```
 
 The JSX attribute and the selector string are two independent literals; renaming the action key in JSX leaves the delegate selector unchanged, and the handler silently stops firing.
@@ -16,14 +16,14 @@ The JSX attribute and the selector string are two independent literals; renaming
 ## ✅ Recommended
 
 ```tsx
-import { attr, delegate, type AttrSpec } from 'kerfjs';
+import { attr, delegate, type AttrSpec } from "kerfjs";
 
 const ACTIONS = {
-  toggle: attr('data-action', 'toggle'),
-} as const satisfies Record<string, AttrSpec<'data-action'>>;
+  toggle: attr("data-action", "toggle"),
+} as const satisfies Record<string, AttrSpec<"data-action">>;
 
-<button {...ACTIONS.toggle.attrs}>Toggle</button>
-delegate(root, 'click', ACTIONS.toggle.selector, handler);
+<button {...ACTIONS.toggle.attrs}>Toggle</button>;
+delegate(root, "click", ACTIONS.toggle.selector, handler);
 ```
 
 Rename `'toggle'` to `'on'` in the `ACTIONS` map and both the rendered attribute and the delegate selector update — no string-grep migration required.

package/docs/rules/prefer-module-jsx-augmentation.md

@@ -10,7 +10,7 @@ Maps to **kerf Hard Rule 11** — kerf's JSX runtime looks up custom-element typ
 declare global {
   namespace JSX {
     interface IntrinsicElements {
-      'my-tag': { foo?: string };
+      "my-tag": { foo?: string };
     }
   }
 }
@@ -19,10 +19,10 @@ declare global {
 ## ✅ Correct
 
 ```ts
-declare module 'kerfjs/jsx-runtime' {
+declare module "kerfjs/jsx-runtime" {
   namespace JSX {
     interface IntrinsicElements {
-      'my-tag': KerfCustomElement & { foo?: string };
+      "my-tag": KerfCustomElement & { foo?: string };
     }
   }
 }
@@ -31,7 +31,11 @@ declare module 'kerfjs/jsx-runtime' {
 Import the building-block types from `kerfjs/jsx-runtime`:
 
 ```ts
-import type { KerfCustomElement, KerfBaseAttrs, AttrLike } from 'kerfjs/jsx-runtime';
+import type {
+  KerfCustomElement,
+  KerfBaseAttrs,
+  AttrLike,
+} from "kerfjs/jsx-runtime";
 ```
 
 ## What this rule does NOT catch

package/docs/rules/require-data-key-in-each.md

@@ -7,24 +7,24 @@ Maps to **kerf Hard Rule 2** — the keyed reconciler matches items by `id` firs
 ## ❌ Incorrect
 
 ```tsx
-each(items, (item) => <li>{item.name}</li>)
+each(items, (item) => <li>{item.name}</li>);
 
 each(items, (item) => {
   return <li class="row">{item.name}</li>;
-})
+});
 
-each(items, (item) => <>{item.name}</>)
+each(items, (item) => <>{item.name}</>);
 ```
 
 ## ✅ Correct
 
 ```tsx
-each(items, (item) => <li data-key={item.id}>{item.name}</li>)
+each(items, (item) => <li data-key={item.id}>{item.name}</li>);
 
-each(items, (item) => <li id={item.id}>{item.name}</li>)
+each(items, (item) => <li id={item.id}>{item.name}</li>);
 
 // Spread attributes are conservatively allowed — they may include the key.
-each(items, (item) => <li {...item.attrs}>{item.name}</li>)
+each(items, (item) => <li {...item.attrs}>{item.name}</li>);
 ```
 
 ## What this rule does NOT catch

package/docs/rules/require-delegate-disposer.md

@@ -2,7 +2,7 @@
 
 Require capturing the disposer returned by `delegate()` and `delegateCapture()`.
 
-Both helpers install a single listener on the root element and return a `() => void` disposer — the *only* way to remove the listener once it's attached. Discarding the return value is safe in exactly one case: the registration is genuinely page-lifetime (root is `document.body` or another never-torn-down element, attached once at startup, never re-registered). In every other case the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state) — so an undisposed delegate on a transient root leaks both the listener and the app graph it references, and re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you.
+Both helpers install a single listener on the root element and return a `() => void` disposer — the _only_ way to remove the listener once it's attached. Discarding the return value is safe in exactly one case: the registration is genuinely page-lifetime (root is `document.body` or another never-torn-down element, attached once at startup, never re-registered). In every other case the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state) — so an undisposed delegate on a transient root leaks both the listener and the app graph it references, and re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you.
 
 See [kerf docs §5.3 — Disposers](https://brianwestphal.github.io/kerf/docs/5-event-delegation/#53-disposers) for the full rationale.
 
@@ -49,8 +49,8 @@ Or collect into a disposer array:
 ```ts
 const disposers: Array<() => void> = [];
 disposers.push(mount(host, render));
-disposers.push(delegate(host, 'click', '[data-action]', onAction));
-disposers.push(delegate(host, 'keydown', '[data-edit]', onEdit));
+disposers.push(delegate(host, "click", "[data-action]", onAction));
+disposers.push(delegate(host, "keydown", "[data-edit]", onEdit));
 
 function teardown() {
   for (const off of disposers) off();
@@ -64,13 +64,18 @@ If the registration is attached once at module load and the root never tears dow
 
 ```ts
 // 1. The `void` operator as an explicit-discard sigil.
-void delegate(document.body, 'click', ACTIONS.inc.selector, () => count.value++);
+void delegate(
+  document.body,
+  "click",
+  ACTIONS.inc.selector,
+  () => count.value++,
+);
 ```
 
 ```ts
 // 2. Standard eslint-disable for one-off cases.
 // eslint-disable-next-line kerfjs/require-delegate-disposer
-delegate(document.body, 'click', ACTIONS.inc.selector, () => count.value++);
+delegate(document.body, "click", ACTIONS.inc.selector, () => count.value++);
 ```
 
 `void` is the lower-friction option when the file has many page-lifetime registrations clustered together; eslint-disable carries the rule name with it, which makes it easier to grep for.

package/docs/rules/ui-component-ownership.md

@@ -0,0 +1,43 @@
+# `ui-component-ownership`
+
+Components own their styles and are configured, never overridden. This rule
+keeps application and component-package code from reaching into another
+package's component through its variables:
+
+- `KUI-L020` — a string, template, object key, or `style` value references a
+  component's private `--_<root>-*` variable (`--_kui-list-gap`), or any
+  `--_kui-*` variable. Private variables are implementation; reading or writing
+  them breaks when the component changes.
+- `KUI-L021` — code assigns a component token that a typed prop sets, in a
+  `style` string (`style="--kui-list-gap: 4px"`), a style object key
+  (`style={{ '--kui-floating-toolbar-inset': '0' }}`), or
+  `style.setProperty('--kui-disclosure-arrow-size', …)`. Set the prop instead
+  (`<List gap="xs" />`).
+
+Both messages name the owning component and end with the same guidance: if no
+configuration covers the need, report the component gap to the owning package
+(open a feature request) instead of overriding it.
+
+```tsx
+// KUI-L020 / KUI-L021
+<div style="--_kui-list-gap: 2px; --kui-list-gap: 4px">…</div>;
+
+// Configure the component instead.
+<List gap="xs">…</List>;
+```
+
+Ownership comes from the loaded composition catalogs, so third-party component
+packages declared in `.kerf-ui-profile.json` get the same protection. A file
+inside the package that owns a component (the nearest `package.json` names the
+catalog entry's `package`) may use that component's own private variables and
+tokens. Reading a public token (`var(--kui-list-divider-color)`) and setting a
+theme token with no equivalent prop remain configuration and are not reported.
+
+CSS files are outside ESLint's reach: `kerf-ui-analyze` (and `kerf-ui-doctor`)
+report the same `KUI-L020` / `KUI-L021` ids in stylesheets, plus `KUI-L019`
+(a rule whose subject is a cataloged component) and `KUI-L022` (a hook class
+on a component's root). See `@kerfjs/ui/docs/ui-analyzer.md`.
+
+Exact profile exceptions may name either id. The rule reads
+`@kerfjs/ui/ai/component-composition.json` by default; see the plugin README for
+alternate catalog settings.

package/docs/rules/ui-composition.md

@@ -0,0 +1,60 @@
+# `ui-composition`
+
+Enforces composition facts published by the versioned UI catalog. `KUI-L201` reports a catalog component under a known, disallowed direct parent. `KUI-L202` reports a statically visible zone child—including an intrinsic or unknown JSX element—that is not one of the zone's cataloged `accepts` entries. `KUI-L203` reports a statically provable zone cardinality violation. A zone participates only when it declares an explicit `jsx.prop` binding, including `children`; the rule never guesses that a zone id is a JSX prop. Toolbar, Pane, TabBar, AppTab, feedback, search, and layout validation is therefore catalog-driven rather than duplicated in rule-local component cases.
+
+The parent check is intentionally conservative about the child: it runs only for a child that resolves to a cataloged entry (or a declared wrapper's roots) whose parents are `listed`. Its direct JSX parent may be any element the rule can see: a cataloged component, a declared wrapper (which counts as each of its roots), an intrinsic element such as `<div>`, or an unresolved component, and any parent that is not a listed parent reports `KUI-L201`. Bound zone checks understand aliases, namespace imports, fragments, arrays, and conditional/logical branches, but expressions whose content cannot be resolved statically remain runtime and accessibility work. Accepted concepts that do not identify a catalog entry remain machine-readable guidance while the rule enforces their statically provable cardinality only. No autofix is offered because wrapping or moving UI changes structure and behavior.
+Toolbar zones accept `KerfUiContent`, so the zone rule allows direct JSX
+controls and custom components there. Their own parent contracts still apply,
+including when a direct child is supplied through a zone prop.
+
+An additional JSX export from an entry can declare its own `jsxExports.<name>.parents` contract. It uses that placement instead of the entry's root placement and is opaque to zone matching, so an action link does not impersonate its enclosing control group.
+
+`KUI-L202` inspects JSX written directly in a bound zone prop, including its
+fragments, arrays, and conditional branches. It does not follow a local binding
+such as `const actions = <div />; <TabBar trailing={actions} />`. Review those
+bindings against the zone's catalog contract; an unknown expression produces
+no zone-child diagnostic.
+
+## Application and third-party wrappers
+
+Beyond `@kerfjs/ui`'s own catalog, the rule loads every composition catalog the
+resolved `.kerf-ui-profile.json` declares under `catalogs`. Their components
+resolve by package subpath (`import { GroupWrap } from '@acme/bits/group-wrap'`,
+matched to the entry's `publicExports`) or, for an application's own relative
+imports, by source file (matched to the entry's `source`, trying the TypeScript
+ESM extensions a `.js` specifier stands for). An export without a `subpath` (a
+private application's, which is never imported by package name) resolves only
+by source file.
+
+A relative import may also reach the source file through relative re-exports,
+the way apps import wrappers through a components barrel:
+`import { DemandSegmentsControl } from './components/index.js'` resolves when
+`index.ts` has `export { DemandSegmentsControl } from '../demand-segments-control.js'`,
+a renamed `export { X as Y } from …` (import `Y`), or `export * from …`, and
+through chains of them (a directory import tries its `index` file). Type-only
+and namespace (`export * as ns`) re-exports, a component defined in the barrel
+itself, and re-exports of anything the catalogs do not declare stay unresolved,
+and cycles stop without resolving.
+
+An entry that declares `rendersAs` (a wrapper that renders one of the listed
+cataloged roots, or nothing) is checked as those roots:
+
+- **Zones (`KUI-L202`):** the zone must accept every declared root.
+- **Parents (`KUI-L201`):** each root's listed parents apply where the wrapper
+  is placed, and a wrapper used as a parent counts as each of its roots. A
+  placement reports once, using the first violated root requirement before a
+  separate wrapper requirement if both apply.
+- **Cardinality (`KUI-L203`):** the wrapper counts as zero or one child, since
+  it may render nothing.
+
+```tsx
+import { Toolbar } from '@kerfjs/ui';
+import { DemandSegmentsControl } from './demand-segments-control.js';
+
+// Valid when the app's catalog declares
+// rendersAs: ["@kerfjs/ui:toolbar-control-group"].
+<Toolbar trailing={<DemandSegmentsControl />} />;
+```
+
+A wrapper without `rendersAs`, or one the profile's catalogs do not declare,
+is still an unknown element and reports `KUI-L202` in a cataloged zone.

package/docs/rules/ui-css-values.md

@@ -0,0 +1,24 @@
+# `ui-css-values`
+
+Checks literal JSX and direct component-function calls against each component's
+cataloged `cssValueProps` contracts. The catalog keeps length, size, flex,
+color, declaration-list, media-query, and numeric-pixel grammars distinct and
+names their accepted helpers, finite shorthands, and raw-value policy.
+
+Stable diagnostics are `KUI-L013` (raw or unknown shorthand), `KUI-L014`
+(wrong property helper), `KUI-L015` (non-standalone expression), `KUI-L016`
+(forbidden declaration list), and review-oriented `KUI-L017` (exceptional
+spacing shorthand). Messages name the preferred shorthand or helper. Dynamic
+values are left to TypeScript rather than guessed.
+
+Only component exports carry an entry's contracts. A catalog entry's
+`publicExports` also lists the helpers its props consume (`Select` ships
+`uiColor`, `List` ships `px`, `rem`, and `flex`); a helper call such as
+`flex({ gap: '12px' })` is not a `List` call and is never checked as one. A
+component export is one whose name starts with an uppercase letter, the rule
+JSX itself uses to tell a component tag from an intrinsic element; a default
+import keeps its subpath's entry. `@kerfjs/ui`'s catalog check enforces the
+convention for the package, and `kerf-ui-analyze` applies the same rule.
+
+Third-party component suites can provide the same contracts in a composition
+catalog through `settings.kerfjs.ui.catalog` and its matching selection catalog.

package/docs/rules/ui-preferences.md

@@ -0,0 +1,16 @@
+# `ui-preferences`
+
+Reports cataloged components listed in an application UI profile preference's `avoid` set and points to the package-qualified `preferred` component. The stable diagnostic is `KUI-L301`.
+
+A component matches whether it is rendered through an imported export (`<WaButtonGroup />`) or written directly as its custom-element tag (`<wa-dropdown>`), which resolves through the selection catalog's `customElement`. The `@kerfjs/ui` package defaults avoid every `Discouraged` Web Awesome element, so each of these reports and names the Kerf component to render instead:
+
+```tsx
+<wa-dropdown>…</wa-dropdown>        // KUI-L301: prefer @kerfjs/ui:popup-menu
+<wa-select>…</wa-select>            // KUI-L301: prefer @kerfjs/ui:select
+<wa-tab-group>…</wa-tab-group>      // KUI-L301: prefer @kerfjs/ui:tab-bar
+<wa-icon name="gear" />             // KUI-L301: prefer @kerfjs/ui:lucide-icon
+```
+
+Supported Web Awesome elements (`<wa-button>`, `<wa-dialog>`, the encouraged `<wa-popup>`) and unknown custom elements are not reported. The source file of a component declared in a profile catalog is exempt: that wrapper owns the element it renders, and the preference applies to its callers.
+
+`recommended-ui` treats the rule as a warning; `strict-ui` treats it as an error. Use a narrowly targeted `KUI-L301` profile exception when a documented application boundary cannot follow the preference. Component substitutions are not autofixed because their props and interaction contracts can differ.

package/docs/rules/ui-public-boundaries.md

@@ -0,0 +1,48 @@
+# `ui-public-boundaries`
+
+Rejects `kui-*` classes and `--kui-*` custom properties that are not listed in the versioned composition catalog, and cataloged component classes written onto elements the application owns. This keeps application code out of private component anatomy while allowing cataloged styling seams.
+
+Diagnostics are stable: `KUI-L101` identifies a private/unknown class, `KUI-L102` an unknown token, and `KUI-L103` a component's anatomy class placed on an application-owned element. Exact profile exceptions can name any of these ids. The rule deliberately does not rewrite selectors, tokens, or markup because there is no generally safe replacement.
+
+## Component anatomy on your own element (`KUI-L103`)
+
+A public class such as `kui-toolbar` or `kui-pane__content` is the rendered anatomy of a component. Writing it onto your own element recreates the component by class: the element inherits (and invites you to restyle) the component's CSS without its props, behavior, accessibility, or future fixes. Components own their styles; render and configure them instead.
+
+```tsx
+<div class="kui-toolbar">…</div>                        // KUI-L103: render `Toolbar`
+<aside class="kui-pane"><nav class="kui-pane__content"> // KUI-L103: render `Pane`
+<wa-dropdown class="kui-popup-menu">…</wa-dropdown>     // KUI-L103: render `PopupMenu`
+<Text class="kui-toolbar-text" />                       // KUI-L103: render `ToolbarText`
+<div class="kui-content-item">…</div>                   // KUI-L103: render `ContentItem`
+```
+
+The catalog marks the classes an application may place with `boundaries.placeableClasses`; these stay allowed:
+
+```tsx
+<div id="app" class="kui-app-root" />                   // document root
+<main class="kui-content kui-scroll-owner" />           // layout utilities
+<footer class="kui-control-cluster kui-content-item" /> // item geometry on a non-div carrier
+<Toolbar className="kui-toolbar" />                     // a component's own element
+```
+
+A placeable class can still be a component's own root. When a catalog entry names the `boundaries.rootElement` its component renders around its placeable classes, a plain element of that tag carrying them is the component recreated and is reported: `<div class="kui-content-item">` is exactly what `ContentItem` renders. The class stays placeable on any other carrier — a `<ul>`, a `Text`, or a control-cluster `<footer>` that must carry the geometry itself. `@kerfjs/ui`'s own `check:guidance` derives its repository check from the same catalog fields, so the two cannot disagree.
+
+The component a diagnostic names is the export named after the class's block, tried from the whole block down to its last word (`kui-toolbar-action-link` → `ToolbarActionLink`, `kui-pane__content` → `Pane`, `acme-meter__bar` → `Meter`), else the entry's own component, else every component the entry exports. That rule ships once, as `@kerfjs/ui/ai/component-class-owners.cjs`; the rule loads it beside `application-ui-profile-sync.cjs`, and `@kerfjs/ui`'s generated `ai/components/*.md` pages render their "render X instead" lines from the same file, so the lint message and the component reference always name the same component. An `@kerfjs/ui` too old to ship it fails the contract load (`KUI-L090`) rather than guessing.
+
+## Component packages
+
+`KUI-L103` is not limited to `kui-*` classes. Every application or third-party composition catalog your `.kerf-ui-profile.json` declares under `catalogs` contributes its entries' public classes the same way: an `acme-meter` class on your own `<div>` is reported with the package's component to render (`Meter`), its `boundaries.placeableClasses` stay allowed, and its `boundaries.rootElement` reports a placeable class on a plain element of the tag the component renders. Component packages declare these fields in `kerf.components.json`; see the component-packages guide (`docs/13-component-packages.md` §13.7). The first catalog to list a class owns it, so `@kerfjs/ui`'s catalog wins over a declared one. `KUI-L101` (private/unknown class) still applies only to `kui-*` names.
+
+String class values are inspected in `class` / `className` literals and in a template literal's static, whitespace-delimited names (``class={`kui-content-item ${extra}`}``); a name an interpolation completes (`` `kui-toolbar-${size}` ``) is not known and is skipped.
+
+The no-build `kerfjs/html` tagged template writes the same markup without JSX, so its `class` attributes carry the same `KUI-L101` / `KUI-L103` contract. The rule reads the template's static parts by the runtime's own rules: a complete static value (`class="kui-pane"`, `class='…'`, or unquoted) counts, tag and attribute names are case-insensitive, and the element is the tag the markup names, so a plain `<div class="kui-content-item">` is `ContentItem` recreated there too. A hole is a whole attribute value (`class=${cls}`), so the class it supplies is unknown and skipped; comments, text, and tags or attributes whose name is a hole are not inspected. Only the `html` tag imported from `kerfjs/html` (by name, alias, or namespace) is read.
+
+```ts
+import { html } from 'kerfjs/html';
+html`<aside class="kui-pane">…</aside>`;          // KUI-L103: render `Pane`
+html`<div class="kui-content-item">…</div>`;      // KUI-L103: render `ContentItem`
+html`<ul class="kui-content-item">…</ul>`;        // allowed: placeable on a <ul>
+html`<aside class=${paneClass}>…</aside>`;        // not inspected: the value is a hole
+```
+
+The rule reads `@kerfjs/ui/ai/component-composition.json` by default. See the plugin README for alternate catalog settings used by monorepos and package authors.

package/docs/rules/ui-wiring.md

@@ -0,0 +1,27 @@
+# `ui-wiring`
+
+Checks wiring obligations published by the versioned composition catalog. `KUI-L401` reports a used component whose required helper or side-effect registration import is absent. `KUI-L402` reports a helper call whose disposer is discarded.
+
+Declare application entry modules in the application UI profile to check root wiring once per entry:
+
+```json
+{ "schemaVersion": 1, "scope": "workspace", "wiring": { "entries": ["src/main.tsx"] } }
+```
+
+Entry paths are relative to the workspace root. The rule follows relative imports, re-exports, and literal dynamic imports from each entry. An application-scoped obligation is checked at the entry if any reachable module renders its component; a recognized helper call in any reachable module satisfies it. Reachable leaf modules need no duplicate wiring. A module outside every declared entry keeps the per-file check. A composition entry can set `wiring.scope` to `"module"` for a helper that must be installed beside its rendering code; omitted scope means `"application"`. Computed import paths and unresolved modules stay outside the static graph, so put them in a declared entry or check them separately. `KUI-L402` still checks the helper's call site.
+
+Consumer composition catalogs can name an application helper's defining file in `wiring.sources`:
+
+```json
+"wiring": {
+  "required": true,
+  "helpers": ["wireTicketSearch"],
+  "sources": [{ "export": "wireTicketSearch", "source": "src/interactions/ticket-search.ts" }]
+}
+```
+
+The source path is relative to the catalog package root. The rule resolves relative imports, aliases, and re-export barrels to that file, so another function with the same name does not satisfy the obligation.
+
+The selection catalog can declare a public wiring provider in `wiringProviders`, naming its export, import source, and the helpers it installs. A recognized `wireCatalog` call from `@kerfjs/ui/wire-catalog` provides `wireScrollDividers`, so the rule does not ask for a duplicate call on the same application entry. The provider's disposer still needs to be retained.
+
+Assign, return, or otherwise retain a disposer when the binding has a shorter lifetime than the page. A `void` call is accepted as an explicit page-lifetime choice. The rule derives valid helper sources from each component-catalog entry's `publicExports` and `wiring[].import` facts, so aliases, root named imports, root namespaces, wiring-subpath named imports, and wiring-subpath namespaces resolve without a second hard-coded export table. It does not attempt flow-sensitive cleanup proof and offers no autofix.