@keenmate/web-components-devkit 1.0.0-rc08 → 1.0.0-rc10

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## [1.0.0-rc10] - 2026-11-05 [PUBLISHED]
+
+### Added
+
+- **Doctor runs the variable-manifest check.** `kmwc check-vars` only ran inside `npm run build`, so a
+  red manifest went unseen until a build: web-treeview's `check:vars` failed on core's
+  non-contract `--base-accent-color` while doctor passed. Doctor now reports the same verdict
+  (`vars`): missing / dead `--base-*` and dead `--<prefix>-*` entries are errors, undocumented
+  `--<prefix>-*` a warning. `loadManifestVerdict()` is shared by both.
+- **Opt-outs for markup that is right on purpose:**
+  - an element whose own `style="…"` sets fixed colours carries `data-kmwc-fixed-colors` (doctor's
+    colour check). Markup a render callback draws inside a shadow root can't be styled by page CSS,
+    so inline is the only way there (web-treeview's context-menu role chips);
+  - `data-kmwc-undefined` on an element a demo leaves undefined on purpose — check-pages no longer
+    reports it (core's PG01 registers its element on a button press). The "never defined" problem
+    names the attribute;
+  - `<!-- kmwc-other-ports: why -->` in a doc that names other repos' ports on purpose (a dated
+    plan, a cross-repo review) — doctor's port scan skips it.
+
+### Changed
+
+- **Doctor: the loader check tells a collision from a rename.** On a core that still draws
+  `<prefix>-loader`, CSS that styles both classes has its own element called `<prefix>__loader`
+  (web-multiselect's loading-state row). That was reported as a rename done too early (error); it is
+  now a warning that core's loader takes the name — and those rules — with the bump, so rename the
+  component's element in the same change.
+
+### Fixed
+
+- **Fragment pages: `<link>` / `<style>` text inside an attribute value stayed put.** The composer
+  moved a `<link>` it found in a tooltip (`title="…the <link> in <head>"`) into `<head>` as an empty
+  element, and the tooltip lost its text (web-multiselect). It now reads whole start tags, quoted
+  attribute values included, and moves only real `<link>` / `<style>` elements.
+- **Inline code in light mode** read at ~3.3:1 — the raw accent on the pale chip. The text keeps the
+  accent hue at most 0.5 lightness (≥ 4.5:1 for every accent the spec tries, light and dark).
+- **Doctor: a rulebook suite that never ran counted as a pass.** Only exit 2 was read as "could
+  not run"; any other exit without `FAIL` lines passed. On Windows a bare `bash` can be WSL's, which
+  can't read `C:/…` paths — every suite exited 127 and doctor reported the rulebook green (found when
+  `make publish-rc` ran the tests from PowerShell). Doctor now runs Git for Windows' bash (from PATH
+  or the install root; `KMWC_BASH` overrides) and warns on any exit but 0, or 1 with `FAIL` lines.
+
+### Internal
+
+- **Tests on the critical paths.** Doctor end to end on fixture repos (a healthy repo is clean, each
+  broken one gets its finding; `doctor.js` 26% → 98% of lines); a real `vite build` of the playground
+  must emit exactly what doctor checks package.json against, with the UMD global and every export
+  `index.d.ts` declares; `kmwc new` (full and `--minimal`) scaffolds a repo doctor finds clean;
+  `kmwc sync` rewrites only what it owns and `--check` writes nothing; `check-release` keeps an rc off
+  `latest`. Composer cases for single-quoted values, `<style>` text and a `>` inside an attribute.
+- **`npm run test:e2e:coverage`** (maintainer) — the dev-server e2e run with line coverage of the
+  kit's browser code (`src/examples/*.js`, 84%), snapshot before every navigation.
+- **README:** a sentence about `data-kmwc-undefined` had landed inside the rc09 What's New bullet;
+  it's back in the check-pages docs.
+
+## [1.0.0-rc09] - 2026-11-04 [PUBLISHED]
+
+### Added
+
+- **check-pages: page CSS that only matches inside a shadow root.** A page's own rules (its `<style>`
+  blocks and `examples-local.css`) are matched against the loaded page. A rule whose element (the last
+  compound, pseudo-classes dropped) exists nowhere in the document but inside a component's shadow root
+  never applies — page CSS stops at the shadow boundary. web-treeview styled the rows its
+  `renderNodeCallback` draws that way (custom-layout: `.file-icon`, `.node-badge`, `.badge-new` …;
+  responsive: `.isco-row`, `.dev-badge` …, 18 rules); against its pre-fix pages the check reports
+  exactly those. Checked once per page (first width).
+
+### Fixed
+
+- **The grey secondary button in dark mode** (`button.secondary` / `.btn-secondary`) had white text on
+  `#9ca3af` at 2.54:1. That grey sits just under the on-colour formula's 0.34 luminance switch, so the
+  formula picked white. It showed on 9 web-treeview pages ("Clear", "Reset", "Move up" …) and on every
+  other site's grey buttons. The button now has its own fill, `--kmwc-neutral-fill-color`
+  (`#6b7280` light / `#4b5563` dark, white text ≥ 4.5:1 in both, hovered too), and
+  `--kmwc-neutral-fill-color-hover`. Muted dots and pills keep the light `--kmwc-neutral-color`.
+
 ## [1.0.0-rc08] - 2026-11-04 [PUBLISHED]
 
 ### Added

package/README.md

@@ -19,18 +19,19 @@ them in the same shape: `@keenmate/web-components-devkit`.
 > positioning) lives in [`@keenmate/web-components-core`](../web-components-core).
 > Nothing here ships inside a component's bundle.
 
-## What's New in v1.0.0-rc08
+## What's New in v1.0.0-rc10
 
-- **Doctor — hard-coded colours in example pages** — web-treeview's devkit migration kept each page's own `<style>` block, and on 8 of its 14 pages the search bars, status bars, badges and panels kept their light colours when the theme switch went dark. rc07 only flagged page CSS that restyles a kit class, so nothing reported them. Doctor now warns about a colour literal (`#hex`, `rgb()` / `hsl()` / `oklch()`, a named colour) on any colour property in a page `<style>`, a `style="…"` attribute or `examples-local.css`. `var()` fallbacks, `light-dark()` pairs, custom properties and `rgb(from var(…))` pass, because they follow the theme. A block that shows fixed colours on purpose, such as a theme gallery or a mockup, opts out with `<style data-kmwc-fixed-colors>`, and a single rule with a `/* kmwc-fixed-colors: why */` comment before it.
-- **Doctor — the loader class matches the installed core** — Core 6d6b768 renamed its default loader's class from `<prefix>-loader` to `<prefix>__loader`, with no release that emits both. A component that renames its selector before the core bump, or forgets to after it, ships a loader with no styles. No rulebook check sees that, and a `## C-NC-8` heading in VALIDATION-NOTES.md would hide a leftover `.x-loader` from the BEM check. Doctor reads which class the installed core's `dist/dom/render-loader.js` draws and fails on any selector in the component's `src/**/*.css` that styles the other one. The error names the file and says which side should change.
+- **Doctor — runs the variable-manifest check** — `kmwc check-vars` only ran inside `npm run build`, so a red manifest stayed invisible until someone built. During the devkit pass, web-treeview's `check:vars` failed on core's `--base-accent-color` (a name outside the base-variables contract) while `kmwc doctor` reported nothing. Doctor now reports the same verdict under `vars`: `--base-*` reads missing from the manifest, manifest entries the CSS no longer reads, and dead `--<prefix>-*` entries are errors; undocumented `--<prefix>-*` variables are a warning. Both commands share one function, `loadManifestVerdict()`, so they can't disagree.
+- **Doctor and check-pages — opt-outs for markup that is right on purpose** — The migrations of web-treeview, web-multiselect and web-components-core hit three findings that could never pass. Markup a render callback draws inside a shadow root can only be coloured inline, so an element whose `style="…"` sets fixed colours on purpose now carries `data-kmwc-fixed-colors` (treeview's context-menu role chips). An element a demo leaves undefined on purpose carries `data-kmwc-undefined`, and check-pages skips it (core's PG01 registers its element on a button press); the "never defined" message names the attribute. A doc that names other repos' ports on purpose, such as a dated plan or a cross-repo review, carries `<!-- kmwc-other-ports: why -->`, and doctor's port scan skips it.
+- **Doctor — the loader check tells a collision from a rename** — web-multiselect has its own loading-state element called `.ms__loader`, next to core rc17's `.ms-loader`. Doctor read it as a rename done before the core bump and reported an error. On a core that still draws `<prefix>-loader`, CSS that styles both classes now gets a warning instead: from core 6d6b768 on, core's default loader takes that class name and picks up the component's rules. The fix is to rename the component's own element in the same change as the core bump.
+- **Fragment pages — text inside attribute values stays put** — The page composer moves a page's `<link>` and `<style>` elements into `<head>`, but it also matched them inside attribute values. web-multiselect's tooltip `title="…the <link> in <head>"` turned into an empty `<link>` in the head, and the tooltip lost its text; a `<style>` written inside an attribute would even have been applied to the whole page. The composer now reads whole start tags, quoted values included, and moves only real elements.
+- **Examples kit — inline code readable in light mode** — Inline `code` used the raw accent colour on its pale chip, which read at about 3.3:1 for the default accent. The text keeps the accent's hue at no more than 0.5 lightness. The e2e spec checks five accents in both themes for at least 4.5:1.
+- **Devkit tests — the critical paths** — The suite now runs a real library build of the playground and checks that the emitted files, the UMD global and every export `index.d.ts` declares are exactly what package.json and doctor expect. It also checks that `kmwc new` scaffolds a repo doctor finds clean, that `kmwc sync` never rewrites a local file or an existing script, and that `check-release` keeps an rc off `latest`. Doctor itself is tested end to end on fixture repos.
 
-## What's New in v1.0.0-rc07
+## What's New in v1.0.0-rc09
 
-- **CLI — `kmwc check-pages` finds what only a browser can see** — Migrating web-treeview turned up pages that pushed a phone sideways: an iOS-Files mockup 420px wide and a theme gallery built on `minmax(500px, 1fr)`. No static check could have caught that. `kmwc check-pages` loads every example page in Chromium at 1440, 390 and 320px. It reports page and console errors, failed requests, custom elements that never get defined, and pages wider than the viewport, naming the widest elements. It looks inside shadow roots and at long words that overflow their box. It ignores layers that can't widen a page: scrolling code blocks, hidden or fixed layers, a closed chapter-nav panel. It starts the repo's dev server, or `--url` points it at one already running (for example the built site on the preview port), and `--widths` changes the widths. `kmwc sync` adds a `check:pages` script and a `make check-pages` target.
-- **Doctor — catches what the treeview and daterangepicker migrations got wrong** — Doctor now checks that every `./dist/…` target in package.json is a file the library build actually emits, and that the old UMD name matches `kmwc.library.globalName`. Without that, the preset's defaults would quietly have renamed treeview's global (`WebTreeView` → `WebTreeview`) and its CSS (`web-treeview.css` → `style.css`). Doctor also reports scripts that pin their own `--port`, config, Makefile and doc ports outside the repo's registry block, and sibling repos that listen inside it. This found web-daterangepicker on treeview's 12300 and web-multiselect / web-dropzone on daterangepicker's 12200. A Plausible site id that another repo also uses is an error, because treeview's traffic was being counted as web-multiselect's. Page CSS that duplicates kit classes (`.kbd`, `mark`, inline field widths, `margin-left: auto`) is a warning.
-- **Doctor — `VALIDATION-NOTES.md` records accepted deviations** — The rulebook lets a component record an architectural decision instead of following a rule. Doctor still reported those as errors (treeview's C-CST-4, C-CSS-1 and C-NC-6). A rulebook check id used as a `##` heading in `VALIDATION-NOTES.md` (`## C-CST-4 / C-CST-10 — …`) now counts as a pass, and `--verbose` lists them. A mention in plain prose doesn't count.
-- **check-vars — input variables are not dead** — Some component variables are public knobs that are read with a fallback and never declared. Treeview forwards `--wtv-context-menu-*` to core's private `--_km-menu-*` so a page-wide `--km-menu-*` still applies, and declaring them would break that chain. check-vars called all 26 of them dead. In the default mode a variable now counts as present when it is declared or read, and a read-with-fallback missing from the manifest is reported as undocumented. `cssVariables.sources` also takes a package path (`@keenmate/web-components-core/dist/menu/styles.js`) for the `--base-*` reads of a core module the component renders.
-- **Example pages — fit a 320px phone, and injected scripts land in the right place** — A chapter heading that names an API outside `<code>` now breaks instead of widening the page. On a phone the index title is 2rem. Below 400px, body, card and demo padding shrink, so a 250px inline calendar fits inside a card. `mark` no longer splits a word. The Vite plugin now puts its head block after the real `<head>` tag (not `<header>` or the text "<head>"). It puts the kit script before the last `</body>`, so it can no longer land inside a page's inline script and break it. That's the failure web-multiselect's sed-based Dockerfile caused on its live action-buttons page.
+- **check-pages — page CSS that can't reach into a shadow root** — web-treeview's custom-layout and responsive pages styled the rows their `renderNodeCallback` draws with page CSS (`.file-icon`, `.node-badge`, `.isco-row`, `.dev-badge` …, 18 rules). Those rows live in the tree's shadow root, and page CSS stops at the shadow boundary, so none of the rules ever applied. Nothing in the source shows where a render callback's output ends up, so this needs the loaded page. `kmwc check-pages` now reads the page's own rules (its `<style>` blocks and `examples-local.css`) and finds what each one styles: the last part of the selector, without pseudo-classes. It reports a rule when that element exists nowhere in the document but does exist inside a component's shadow root, and names the component. Run against treeview's pages from before its fix, it lists exactly those 18 rules. The fix is a CSS variable, `::part`, or the component's styles hook (`getCustomStylesCallback`).
+- **Examples kit — the grey secondary button in dark mode** — `button.secondary` / `.btn-secondary` had white text on `#9ca3af` in dark mode, at 2.54:1. That grey sits just under the 0.34 luminance switch in the formula that picks a button's text colour, so the formula chose white. It showed on 9 web-treeview pages ("Clear", "Reset", "Move up" …) and on every other component site's grey buttons. The button now has its own fill, `--kmwc-neutral-fill-color` (`#6b7280` light / `#4b5563` dark), plus a hover token, so white text stays at 4.5:1 or better in both themes, hovered too. Muted status dots and pills keep the lighter `--kmwc-neutral-color`. An e2e spec checks the contrast in both themes.
 
 ## Catalogue
 
@@ -39,7 +40,7 @@ them in the same shape: `@keenmate/web-components-devkit`.
 
 | Component | Package | Prefix | Dev port | Links | Devkit | About |
 |---|---|---|---:|---|:---:|---|
-| **web-multiselect** | `@keenmate/web-multiselect` | `ms` | 12100 | [repo](https://github.com/keenmate/web-multiselect) · [examples](https://examples.web-multiselect.keenmate.dev) · [docs](https://web-multiselect.keenmate.dev) · `web-multiselect-showcase` · `web-multiselect-docs` | — | Lightweight multiselect web component with typeahead search, rich content support, and excellent keyboard… |
+| **web-multiselect** | `@keenmate/web-multiselect` | `ms` | 12100 | [repo](https://github.com/keenmate/web-multiselect) · [examples](https://examples.web-multiselect.keenmate.dev) · [docs](https://web-multiselect.keenmate.dev) · `web-multiselect-showcase` · `web-multiselect-docs` | ✅ | Lightweight multiselect web component with typeahead search, rich content support, and excellent keyboard… |
 | **web-daterangepicker** | `@keenmate/web-daterangepicker` | `drp` | 12200 | [repo](https://github.com/keenmate/web-daterangepicker) · [docs](https://web-daterangepicker.keenmate.dev) · `web-daterangepicker-showcase` | ✅ | Lightweight date picker web component with excellent keyboard navigation and range selection |
 | **web-treeview** | `@keenmate/web-treeview` | `wtv` | 12300 | [repo](https://github.com/keenmate/web-treeview) · `web-treeview-showcase` | ✅ | Lightweight treeview web component with hierarchical data display, search, expand/collapse, drag-drop, and… |
 | **web-commandpalette** | `@keenmate/web-commandpalette` | `cp` | 12400 | [repo](https://github.com/keenmate/web-commandpalette) · [examples](https://examples.web-commandpalette.keenmate.dev) | ✅ | Framework-agnostic command-palette web component — modes, multi-step commands, scoped + global search,… |
@@ -365,7 +366,7 @@ kmwc doctor [--json]          devkit checks + package contents + the rulebook's
 kmwc check-vars [--strict]    component-variables.manifest.json ⇔ CSS
 kmwc check-pages [--url u]    every example page in Chromium at 1440 / 390 / 320px: page and console
                               errors, failed requests, never-defined elements, a page wider than the
-                              viewport. Starts the dev server unless --url (e.g. the built site);
+                              viewport, page CSS that only matches inside a shadow root. Starts the dev server unless --url (e.g. the built site);
                               --widths 1440,390,320
 kmwc check-release --tag t    latest ⇔ release version, rc ⇔ -rcN, version not yet on npm
 kmwc new web-<name>           scaffold a component (--prefix, --title, --tag, --dir, --port, --minimal, --register)
@@ -388,6 +389,9 @@ and the e2e suite before building and publishing.
 base-variables, color-scheme, readme-structure, custom-elements-manifest,
 responsive-overlay, publish-command, example-pages) with `bash`, passing `kmwc.prefix`, and
 reports each `FAIL` as an error pointing at the matching `.checks.md` entry.
+On Windows that is Git for Windows' bash (a bare `bash` may be WSL's, which can't
+read `C:/` paths); `KMWC_BASH` overrides it. A suite that exits with anything but 0,
+or 1 with `FAIL` lines, never ran — a warning, never a pass.
 A `library` runs only naming-conventions, readme-structure, publish-command
 and example-pages; the others check what a custom element ships (its CSS,
 manifest, overlay).
@@ -408,7 +412,9 @@ generated files:
   silently.
 - **Ports** — no script pins a `--port` of its own, the repo's configs, Makefile
   and docs stay inside its registry block, and no sibling checkout (a registry
-  entry at `../<id>`) listens on a port inside it.
+  entry at `../<id>`) listens on a port inside it. A doc that names other repos'
+  ports on purpose (a dated plan, a cross-repo review) carries
+  `<!-- kmwc-other-ports: why -->` and isn't scanned.
 - **Analytics** — no other repo uses the same Plausible site id.
 - **Page CSS** — a page `<style>` or `examples-local.css` rule on a kit-owned
   selector (`.kbd`, `kbd`, `mark`, `.pill`, `.card` …) and single-declaration
@@ -418,16 +424,28 @@ generated files:
   it stays put when the theme switch flips the kit to dark. `var()` fallbacks and
   `light-dark()` pairs follow the theme. Fixed colours on purpose (a theme gallery, a
   mockup, a test fixture) go in a `<style data-kmwc-fixed-colors>` block, or one rule
-  gets a `/* kmwc-fixed-colors: why */` comment right before it.
+  gets a `/* kmwc-fixed-colors: why */` comment right before it. An element whose
+  `style="…"` sets them on purpose carries the same attribute — markup a render
+  callback draws inside a shadow root can't be reached by page CSS at all.
 - **Loader class** — the component CSS styles the class the *installed* core gives
   its default loader (`<prefix>__loader` from core 6d6b768 on, `<prefix>-loader`
   before). Renaming the selector on one side of the core bump leaves the loader
   unstyled, and a VALIDATION-NOTES `## C-NC-8` would hide the old class from the
-  rulebook.
+  rulebook. On a core that still draws `<prefix>-loader`, CSS that styles both
+  classes has an element of its own called `<prefix>__loader`: a warning, because
+  core's loader takes that name (and those rules) with the bump.
+- **Variable manifest** — the same verdict as `kmwc check-vars`, which otherwise
+  only runs inside `npm run build`: `--base-*` reads and the manifest agree, no
+  dead `--<prefix>-*` entries (errors), no undocumented ones (warning).
 
 `kmwc check-pages` is the browser half: it loads every example page and reports
 what doctor can't see in the source — a script error, a 404, a fixed width that
-pushes a phone sideways.
+pushes a phone sideways, and page CSS that can never apply: a rule (in the page's
+`<style>` or `examples-local.css`) whose element exists only inside a component's
+shadow root, such as the rows a `renderNodeCallback` draws. Page CSS stops at the
+shadow boundary — style those through a CSS variable, `::part` or the component's
+styles hook (`getCustomStylesCallback`). An element a demo leaves undefined on
+purpose (registered on a button press) carries `data-kmwc-undefined`.
 
 **Package contents.** Doctor runs `npm pack --dry-run` and fails on anything
 dev-only that would reach a consumer's `node_modules`: `CLAUDE.md` at any
@@ -523,6 +541,7 @@ registry edits), and move the component's own code into that layout with
 npm install
 npm test                 # unit tests (config, registry, templates, sync, checks, intake, plugin, kit)
 npm run test:e2e         # playground: the kit + scaffold in a real browser, dev server AND built site
+npm run test:e2e:coverage   # the same specs on the dev server + line coverage of the kit's browser code
 npm run readme           # regenerate the catalogue
 npm run check:spotlight-mirror   # what changed in web-commandpalette since the spotlight was aligned
 make dev                 # the playground's dev server

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/web-components-devkit",
-  "version": "1.0.0-rc08",
+  "version": "1.0.0-rc10",
   "description": "Shared dev, example-site and build infrastructure for Keenmate web components: Vite preset, examples kit (chapter nav, copy-link, controls store, shared styles), Playwright preset and the `kmwc` CLI (sync, doctor, check-vars, new, readme).",
   "type": "module",
   "license": "MIT",
@@ -47,6 +47,7 @@
     "readme:check": "node src/cli/kmwc.js readme --check",
     "test": "node --test \"test/**/*.test.js\"",
     "test:e2e": "cd playground && npx playwright test",
+    "test:e2e:coverage": "node scripts/e2e-coverage.js",
     "check:contract": "base-contract-check src templates playground",
     "check:spotlight-mirror": "node scripts/check-spotlight-mirror.js",
     "playground": "cd playground && vite",

package/src/cli/commands/check-pages.js

@@ -1,24 +1,30 @@
 /**
  * kmwc check-pages — load every example page in a real browser and report what
  * a reader would hit: page errors, console errors, failed requests, custom
- * elements that never get defined, and a page wider than the viewport (a fixed
- * width or a long word that pushes a phone sideways).
+ * elements that never get defined, a page wider than the viewport (a fixed
+ * width or a long word that pushes a phone sideways), and page CSS that can
+ * never apply because what it targets lives only inside a shadow root (classes
+ * a render callback puts into the component).
  *
  * Runs against the repo's own dev server (started here on kmwc.ports.dev), or a
  * server you already have (--url, e.g. the built site on the preview port).
  * Widths default to desktop + two phones. Uses the component's own
  * @playwright/test (see getPeerModule) — `npx playwright install chromium` once.
  */
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getKmwcConfig, getPeerModule, loadPeerModule } from '../../config.js';
 import { getExamplePages } from '../../vite/index.js';
+import { getRuleSelectors } from '../repo-checks.js';
 
 export const DEFAULT_WIDTHS = [1440, 390, 320];
 const VIEWPORT_HEIGHT = 900;
 const SETTLE_MS = 600;
 const VITE_CONFIG_FILES = ['vite.config.ts', 'vite.config.mts', 'vite.config.mjs', 'vite.config.js'];
 const MAX_OFFENDERS = 3;
+const LOCAL_STYLESHEET_FILE = 'examples-local.css';
+// An element a demo leaves undefined on purpose (registered on a button press) opts out.
+export const UNDEFINED_ON_PURPOSE_ATTRIBUTE = 'data-kmwc-undefined';
 // Requests a page doesn't control (favicon probes, analytics in a built site).
 const IGNORED_REQUEST_PATTERN = /favicon\.ico|stats\.keenmate\.services|plausible/;
 
@@ -30,13 +36,69 @@ export function parseWidths(widthsText) {
   return widths;
 }
 
+/**
+ * The element a selector styles, as a selector of its own: the last compound with
+ * pseudo-classes / -elements dropped (`.tree .badge:hover::after` → `.badge`), or
+ * null when there's no class / id / attribute to look for (`:root`, `div`, `from`). Pure.
+ */
+export function getSelectorSubject(selector) {
+  let depth = 0;
+  let start = 0;
+  for (let index = 0; index < selector.length; index++) {
+    const character = selector[index];
+    if (character === '(' || character === '[') depth++;
+    else if (character === ')' || character === ']') depth--;
+    else if (depth === 0 && /[\s>+~]/.test(character)) start = index + 1;
+  }
+  const subject = selector.slice(start).replace(/::?[\w-]+(\([^()]*\))?/g, '').trim();
+  return /[.#[]/.test(subject) ? subject : null;
+}
+
+/** A page's own CSS rules (its `<style>` blocks + examples-local.css) → [{ selector, subject }]. */
+export function loadPageRules(root, pagePath) {
+  const pageText = readFileSync(pagePath, 'utf8');
+  const localStylesheetPath = join(root, LOCAL_STYLESHEET_FILE);
+  const styleText = [
+    ...[...pageText.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map((match) => match[1]),
+    existsSync(localStylesheetPath) ? readFileSync(localStylesheetPath, 'utf8') : '',
+  ].join('\n');
+  const selectors = [...new Set(getRuleSelectors(styleText))];
+  return selectors.map((selector) => ({ selector, subject: getSelectorSubject(selector) })).filter((rule) => rule.subject);
+}
+
+/**
+ * Runs in the page: page rules whose subject matches nothing in the document but
+ * something inside a shadow root → [{ selector, host }]. Page CSS stops at the
+ * shadow boundary, so such a rule never applies.
+ */
+export function findShadowOnlyRules(rules) {
+  const getShadowRoots = (root) =>
+    [...root.querySelectorAll('*')].filter((element) => element.shadowRoot).flatMap((element) => [element.shadowRoot, ...getShadowRoots(element.shadowRoot)]);
+  const shadowRoots = getShadowRoots(document);
+  const safeQuery = (root, selector) => {
+    try {
+      return root.querySelector(selector);
+    } catch {
+      return null;
+    }
+  };
+  return rules.flatMap(({ selector, subject }) => {
+    if (safeQuery(document, subject)) return [];
+    const shadowRoot = shadowRoots.find((root) => safeQuery(root, subject));
+    return shadowRoot ? [{ selector, host: shadowRoot.host.localName }] : [];
+  });
+}
+
 /**
  * Problems in one page load's report → [string]. Pure — exported for tests.
- * @param {{ width: number, errors: string[], undefinedElements: string[], scrollWidth: number, clientWidth: number, offenders: string[] }} pageReport
+ * @param {{ width: number, errors: string[], undefinedElements: string[], scrollWidth: number, clientWidth: number, offenders: string[], shadowOnlyRules?: { selector: string, host: string }[] }} pageReport
  */
 export function getPageProblems(pageReport) {
   const problems = [...pageReport.errors];
-  if (pageReport.undefinedElements.length) problems.push(`never defined: <${pageReport.undefinedElements.join('>, <')}>`);
+  for (const { selector, host } of pageReport.shadowOnlyRules || []) {
+    problems.push(`page CSS "${selector}" only matches inside <${host}>'s shadow root — page styles can't reach it (use a CSS variable, ::part or the component's styles hook)`);
+  }
+  if (pageReport.undefinedElements.length) problems.push(`never defined: <${pageReport.undefinedElements.join('>, <')}> (left undefined on purpose? add ${UNDEFINED_ON_PURPOSE_ATTRIBUTE})`);
   if (pageReport.scrollWidth > pageReport.clientWidth) {
     const offenderText = pageReport.offenders.length ? ` — widest: ${pageReport.offenders.join(', ')}` : '';
     problems.push(`page is ${pageReport.scrollWidth}px wide in a ${pageReport.clientWidth}px viewport${offenderText}`);
@@ -48,9 +110,10 @@ export function getPageProblems(pageReport) {
  * Runs in the page: overflow, undefined custom elements. A culprit is the deepest
  * element — or the text — past the right edge, outside anything that scrolls or
  * clips on purpose (a code block, a table wrapper) and outside hidden or fixed
- * layers (a closed nav panel, a toast), which don't widen the page.
+ * layers (a closed nav panel, a toast), which don't widen the page. Undefined elements
+ * carrying `undefinedAttribute` are left undefined on purpose and don't count.
  */
-function inspectPage(maxOffenders) {
+function inspectPage({ maxOffenders, undefinedAttribute }) {
   const viewportWidth = document.documentElement.clientWidth;
   // Shadow roots count: a component's own internals can widen the page too.
   const getParent = (element) => element.parentElement || element.getRootNode().host || null;
@@ -97,7 +160,7 @@ function inspectPage(maxOffenders) {
       offenders.push(`${describe(parent)} "${textNode.textContent.trim().slice(0, 40)}"`);
     }
   }
-  const undefinedElements = [...new Set([...document.querySelectorAll(':not(:defined)')].map((element) => element.localName).filter((name) => name.includes('-')))];
+  const undefinedElements = [...new Set([...document.querySelectorAll(`:not(:defined):not([${undefinedAttribute}])`)].map((element) => element.localName).filter((name) => name.includes('-')))];
   return {
     scrollWidth: document.documentElement.scrollWidth,
     clientWidth: viewportWidth,
@@ -106,7 +169,7 @@ function inspectPage(maxOffenders) {
   };
 }
 
-async function loadPageReport(browser, pageUrl, width) {
+async function loadPageReport(browser, pageUrl, width, pageRules = []) {
   const page = await browser.newPage({ viewport: { width, height: VIEWPORT_HEIGHT } });
   const errors = [];
   page.on('pageerror', (error) => errors.push(`page error: ${error.message.split('\n')[0]}`));
@@ -122,8 +185,9 @@ async function loadPageReport(browser, pageUrl, width) {
   try {
     await page.goto(pageUrl, { waitUntil: 'networkidle', timeout: 30_000 });
     await page.waitForTimeout(SETTLE_MS);
-    const inspection = await page.evaluate(inspectPage, MAX_OFFENDERS);
-    return { width, errors: [...new Set(errors)], ...inspection };
+    const inspection = await page.evaluate(inspectPage, { maxOffenders: MAX_OFFENDERS, undefinedAttribute: UNDEFINED_ON_PURPOSE_ATTRIBUTE });
+    const shadowOnlyRules = pageRules.length ? await page.evaluate(findShadowOnlyRules, pageRules) : [];
+    return { width, errors: [...new Set(errors)], ...inspection, shadowOnlyRules };
   } catch (error) {
     return { width, errors: [...new Set([...errors, `load failed: ${error.message.split('\n')[0]}`])], scrollWidth: 0, clientWidth: 0, offenders: [], undefinedElements: [] };
   } finally {
@@ -154,7 +218,8 @@ async function startDevServer(config) {
 export async function run(args) {
   const config = getKmwcConfig(args.root);
   const widths = parseWidths(args.widths);
-  const pageFiles = Object.values(getExamplePages(config)).map((pagePath) => pagePath.replace(/\\/g, '/').split('/').pop());
+  const pagePaths = Object.values(getExamplePages(config));
+  const pageFiles = pagePaths.map((pagePath) => pagePath.replace(/\\/g, '/').split('/').pop());
   if (!pageFiles.length) {
     console.log('kmwc check-pages: no example pages — nothing to check.');
     return 0;
@@ -172,10 +237,13 @@ export async function run(args) {
   let problemCount = 0;
   try {
     console.log(`kmwc check-pages — ${pageFiles.length} page(s) × ${widths.join(' / ')}px on ${baseUrl}\n`);
-    for (const pageFile of pageFiles) {
+    for (const [pageIndex, pageFile] of pageFiles.entries()) {
       const pageProblems = [];
-      for (const width of widths) {
-        for (const problem of getPageProblems(await loadPageReport(browser, `${baseUrl}/${pageFile}`, width))) pageProblems.push(`@${width}px ${problem}`);
+      const pageRules = loadPageRules(config.root, pagePaths[pageIndex]);
+      for (const [widthIndex, width] of widths.entries()) {
+        // Shadow-only rules don't depend on the width: check them on the first load only.
+        const report = await loadPageReport(browser, `${baseUrl}/${pageFile}`, width, widthIndex === 0 ? pageRules : []);
+        for (const problem of getPageProblems(report)) pageProblems.push(`@${width}px ${problem}`);
       }
       problemCount += pageProblems.length;
       console.log(`${pageProblems.length ? '✗' : '✓'} ${pageFile}${pageProblems.map((problem) => `\n    ${problem}`).join('')}`);

package/src/cli/commands/check-vars.js

@@ -77,18 +77,14 @@ export function checkManifestVariables({ cssText, manifest, prefix, internalVari
   };
 }
 
-export async function run(args) {
-  const config = getKmwcConfig(args.root);
-  const isStrict = !!args.strict;
-  if (!config.cssVariables.isEnabled) {
-    console.log('kmwc check-vars: off (kmwc.cssVariables is false) — nothing to check.');
-    return 0;
-  }
+/**
+ * The repo's manifest checked against its CSS sources → { verdict, prefix }, or { skippedReason }
+ * when there's nothing to check. Shared by `kmwc check-vars` and doctor.
+ */
+export function loadManifestVerdict(config) {
+  if (!config.cssVariables.isEnabled) return { skippedReason: 'off (kmwc.cssVariables is false)' };
   const manifestPath = resolve(config.root, config.cssVariables.manifest);
-  if (!existsSync(manifestPath)) {
-    console.log(`kmwc check-vars: no ${config.cssVariables.manifest} — nothing to check.`);
-    return 0;
-  }
+  if (!existsSync(manifestPath)) return { skippedReason: `no ${config.cssVariables.manifest}` };
   const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
   const prefix = config.prefix || manifest.prefix;
   if (!prefix) throw new Error('no variable prefix — set kmwc.prefix or "prefix" in the manifest');
@@ -101,6 +97,17 @@ export async function run(args) {
     internalVariables: config.cssVariables.internalVariables,
     checkMode: config.cssVariables.checkMode,
   });
+  return { verdict, prefix };
+}
+
+export async function run(args) {
+  const config = getKmwcConfig(args.root);
+  const isStrict = !!args.strict;
+  const { verdict, prefix, skippedReason } = loadManifestVerdict(config);
+  if (skippedReason) {
+    console.log(`kmwc check-vars: ${skippedReason} — nothing to check.`);
+    return 0;
+  }
 
   const presenceWord = config.cssVariables.checkMode === 'consumed' ? 'consumed via var()' : 'declared or read';
   const renderSection = (title, names) => `${title} (${names.length}):\n` + names.map((name) => `  --${name}`).join('\n');

package/src/cli/commands/doctor.js

@@ -19,6 +19,7 @@ import { spawnSync } from 'node:child_process';
 import { getKmwcConfig, getPortsForBlock, getRegistry, LEGACY_FILES, NON_PAGE_HTML_FILES, PACKAGE_LEAK_RULES, PACKAGE_FILES_EXCLUSIONS } from '../../config.js';
 import { getSyncPlan, getScriptsPlan, CLAUDE_BLOCK_START } from '../sync-plan.js';
 import { checkIsFragment } from '../../vite/page-composer.js';
+import { loadManifestVerdict } from './check-vars.js';
 import {
   VALIDATION_NOTES_FILE,
   loadAcceptedCheckIds,
@@ -28,6 +29,7 @@ import {
   getPortBlockRange,
   getScriptPortMismatches,
   loadStalePortMentions,
+  OTHER_PORTS_MARKER,
   loadSiblingPortCollisions,
   loadOwnPortsOutsideBlock,
   loadPlausibleSiteId,
@@ -38,6 +40,7 @@ import {
   FIXED_COLORS_MARKER,
   getHardcodedColors,
   loadCoreLoader,
+  getLoaderClassVerdict,
   loadStyledLoaderClasses,
 } from '../repo-checks.js';
 
@@ -98,15 +101,40 @@ export function getSuiteFailures(suiteOutput) {
     .map((match) => ({ checkId: match[1], reason: match[2].trim() }));
 }
 
+const GIT_BASH_RELATIVE_PATH = join('bin', 'bash.exe');
+// PATH entries Git for Windows adds — each sits one or two levels under the install root.
+const GIT_PATH_ENTRY_PATTERN = /^(.*[\\/]Git)[\\/](?:cmd|bin|usr[\\/]bin|mingw64[\\/]bin)[\\/]?$/i;
+
+/**
+ * The bash that runs the rulebook scripts. On Windows a bare `bash` can resolve to WSL's
+ * (`System32\bash.exe`, `WindowsApps\bash.exe`), which can't read `C:/…` paths: every suite
+ * exits 127 and the rulebook never runs. So: KMWC_BASH when set, else Git for Windows'
+ * bash (found from PATH or the usual install roots), else `bash`. Exported for tests.
+ */
+export function getBashPath({ platform = process.platform, env = process.env, checkExists = existsSync } = {}) {
+  if (env.KMWC_BASH) return env.KMWC_BASH;
+  if (platform !== 'win32') return 'bash';
+  const pathEntries = (env.PATH || env.Path || '').split(';').filter(Boolean);
+  const gitRoots = [
+    ...pathEntries.map((entry) => entry.match(GIT_PATH_ENTRY_PATTERN)?.[1]).filter(Boolean),
+    ...[env.ProgramFiles, env.ProgramW6432, env.LOCALAPPDATA && join(env.LOCALAPPDATA, 'Programs')].filter(Boolean).map((directory) => join(directory, 'Git')),
+  ];
+  return gitRoots.map((gitRoot) => join(gitRoot, GIT_BASH_RELATIVE_PATH)).find((bashPath) => checkExists(bashPath)) || 'bash';
+}
+
 function runRulebookSuite(config, suite) {
   const scriptPath = join(config.rulebook.path, `${suite.name}.checks.sh`).replace(/\\/g, '/');
   const scriptArgs = [scriptPath, config.root.replace(/\\/g, '/')];
   if (suite.isPrefixed && config.prefix) scriptArgs.push(config.prefix);
-  return spawnSync('bash', scriptArgs, { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
+  return spawnSync(getBashPath(), scriptArgs, { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
 }
 
-/** Run every check; returns [{ level: 'pass'|'warning'|'error', checkName, message, fixHint? }]. */
+/**
+ * Run every check; returns [{ level: 'pass'|'warning'|'error', checkName, message, fixHint? }].
+ * `doctorConfig.registry` replaces components.json (tests use a registry of fixture repos).
+ */
 export function checkComponent(config, doctorConfig = {}) {
+  const registry = doctorConfig.registry || getRegistry();
   const results = [];
   const addPass = (checkName, message) => results.push({ level: 'pass', checkName, message });
   const addWarning = (checkName, message, fixHint) => results.push({ level: 'warning', checkName, message, fixHint });
@@ -240,7 +268,7 @@ export function checkComponent(config, doctorConfig = {}) {
   }
 
   // ── registry cross-check ─────────────────────────────────────────────────
-  const registryEntry = getRegistry().components.find((component) => component.id === config.id);
+  const registryEntry = registry.components.find((component) => component.id === config.id);
   if (!registryEntry) {
     addWarning('registry', `"${config.id}" is not in the devkit components.json`, 'add an entry (README catalogue + port allocation)');
   } else {
@@ -254,7 +282,7 @@ export function checkComponent(config, doctorConfig = {}) {
           `set package.json#kmwc.ports to { "dev": ${registryPorts.dev}, "image": ${registryPorts.image} } (components.json port block ${registryEntry.port})`
         );
       } else addPass('registry', `ports match the registry (dev ${config.ports.dev}, image ${config.ports.image})`);
-      checkPorts(config, registryEntry.port, { addPass, addWarning, addError });
+      checkPorts(config, registryEntry.port, registry, { addPass, addWarning, addError });
     }
     if (registryEntry.prefix && config.prefix && registryEntry.prefix !== config.prefix) {
       addError('registry', `kmwc.prefix "${config.prefix}" ≠ registry prefix "${registryEntry.prefix}"`, 'use the reserved prefix');
@@ -277,9 +305,12 @@ export function checkComponent(config, doctorConfig = {}) {
   // ── core's default loader class ──────────────────────────────────────────
   if (config.prefix && config.kind !== LIBRARY_KIND) checkLoaderClass(config, { addPass, addWarning, addError });
 
+  // ── variable manifest (what `kmwc check-vars` checks; it only runs in the build) ──
+  if (config.hasPackageConfig) checkVariableManifest(config, { addPass, addWarning, addError });
+
   // ── analytics ────────────────────────────────────────────────────────────
   const plausibleSiteId = loadPlausibleSiteId(config.root);
-  const sharingRepoIds = loadSharedPlausibleSiteIds(config, getRegistry(), plausibleSiteId);
+  const sharingRepoIds = loadSharedPlausibleSiteIds(config, registry, plausibleSiteId);
   if (sharingRepoIds.length) {
     addError(
       'analytics',
@@ -298,7 +329,7 @@ export function checkComponent(config, doctorConfig = {}) {
 }
 
 /** Ports: script --port flags, own configs and docs outside the block, siblings inside it. */
-function checkPorts(config, portBlock, { addPass, addWarning, addError }) {
+function checkPorts(config, portBlock, registry, { addPass, addWarning, addError }) {
   const [firstPort, lastPort] = getPortBlockRange(portBlock);
   const blockLabel = `${firstPort}–${lastPort}`;
   const scriptPortMismatches = getScriptPortMismatches(config.packageJson.scripts, config.ports);
@@ -307,7 +338,7 @@ function checkPorts(config, portBlock, { addPass, addWarning, addError }) {
   }
   const ownStrayPorts = loadOwnPortsOutsideBlock(config, portBlock).filter(({ file }) => !file.startsWith('package.json#scripts.'));
   for (const { port, file } of ownStrayPorts) addError('ports', `${file} uses port ${port}, outside this repo's block ${blockLabel}`, 'take ports from kmwc.ports (the devkit presets do)');
-  const siblingCollisions = loadSiblingPortCollisions(config, getRegistry());
+  const siblingCollisions = loadSiblingPortCollisions(config, registry);
   for (const { id, port, file } of siblingCollisions) {
     addError('ports', `${id} uses port ${port} (${file}) — inside this repo's block ${blockLabel}`, `move ${id} to its own components.json block`);
   }
@@ -316,7 +347,7 @@ function checkPorts(config, portBlock, { addPass, addWarning, addError }) {
     addWarning(
       'ports',
       `docs mention ports outside ${blockLabel}: ${stalePortMentions.map(({ file, port }) => `${file} ${port}`).join(', ')}`,
-      `update them to ${getPortsForBlock(portBlock).dev} (dev) / ${getPortsForBlock(portBlock).image} (image)`
+      `update them to ${getPortsForBlock(portBlock).dev} (dev) / ${getPortsForBlock(portBlock).image} (image); a doc that names other repos' ports on purpose gets <!-- ${OTHER_PORTS_MARKER}: why -->`
     );
   }
   if (!scriptPortMismatches.length && !ownStrayPorts.length && !siblingCollisions.length && !stalePortMentions.length) {
@@ -330,13 +361,19 @@ function checkPorts(config, portBlock, { addPass, addWarning, addError }) {
  * before (or after) the core bump leaves the default loader unstyled, and no rulebook
  * check sees that (a VALIDATION-NOTES `## C-NC-8` even hides a leftover old class).
  */
-function checkLoaderClass(config, { addPass, addError }) {
+function checkLoaderClass(config, { addPass, addWarning, addError }) {
   const coreLoader = loadCoreLoader(config.root);
   if (!coreLoader?.separator) return;
   const coreClassName = `${config.prefix}${coreLoader.separator}loader`;
-  const styledLoaderClasses = loadStyledLoaderClasses(config.root, config.prefix);
-  const mismatchedClasses = styledLoaderClasses.filter(({ separator }) => separator !== coreLoader.separator);
-  for (const { file, className } of mismatchedClasses) {
+  const { isCoreClassStyled, renamedClasses, collidingClasses } = getLoaderClassVerdict(coreLoader.separator, loadStyledLoaderClasses(config.root, config.prefix));
+  for (const { file, className } of collidingClasses) {
+    addWarning(
+      'loader',
+      `${file} styles .${className} next to core's .${coreClassName} — from core 6d6b768 on, core draws its default loader as <span class="${className}"> and it picks up these rules`,
+      `rename the component's own .${className} element (e.g. .${config.prefix}__loading) in the same change as the core bump`
+    );
+  }
+  for (const { file, className } of renamedClasses) {
     addError(
       'loader',
       `${file} styles .${className}, but core ${coreLoader.version} draws the default loader as <span class="${coreClassName}"> — it renders unstyled`,
@@ -345,7 +382,30 @@ function checkLoaderClass(config, { addPass, addError }) {
         : `keep .${coreClassName} until the component builds on a core that draws <prefix>__loader, then rename in the same change`
     );
   }
-  if (styledLoaderClasses.length && !mismatchedClasses.length) addPass('loader', `CSS styles .${coreClassName}, the class core ${coreLoader.version} draws`);
+  if (isCoreClassStyled && !renamedClasses.length) addPass('loader', `CSS styles .${coreClassName}, the class core ${coreLoader.version} draws`);
+}
+
+/** The variable manifest matches the CSS — the same verdict as `kmwc check-vars` (undocumented = warning). */
+function checkVariableManifest(config, { addPass, addWarning, addError }) {
+  let manifestVerdict;
+  try {
+    manifestVerdict = loadManifestVerdict(config);
+  } catch (error) {
+    addError('vars', `kmwc check-vars can't run: ${error.message}`, 'fix kmwc.cssVariables (sources / manifest / prefix)');
+    return;
+  }
+  const { verdict, prefix, skippedReason } = manifestVerdict;
+  if (skippedReason) return;
+  const fixHint = 'edit the manifest to match the CSS (npm run check:vars lists every name)';
+  const listNames = (names) => names.map((name) => `--${name}`).join(', ');
+  if (verdict.missingBaseVariables.length) addError('vars', `--base-* read in CSS but missing from the manifest: ${listNames(verdict.missingBaseVariables)}`, fixHint);
+  if (verdict.unusedBaseVariables.length) addError('vars', `--base-* in the manifest but not read in CSS: ${listNames(verdict.unusedBaseVariables)}`, fixHint);
+  if (verdict.unusedComponentVariables.length) addError('vars', `--${prefix}-* in the manifest but not in CSS: ${listNames(verdict.unusedComponentVariables)}`, fixHint);
+  if (verdict.undocumentedComponentVariables.length) {
+    addWarning('vars', `--${prefix}-* in CSS but missing from the manifest: ${listNames(verdict.undocumentedComponentVariables)}`, `${fixHint}; runtime internals go in kmwc.cssVariables.internalVariables`);
+  }
+  const isInSync = !['missingBaseVariables', 'unusedBaseVariables', 'unusedComponentVariables', 'undocumentedComponentVariables'].some((key) => verdict[key].length);
+  if (isInSync) addPass('vars', `variable manifest in sync — ${verdict.counts.base} base, ${verdict.counts.component} component vars`);
 }
 
 /** Packed paths that break PACKAGE_LEAK_RULES → [{ path, label }]. Pure — exported for tests. */
@@ -413,24 +473,29 @@ function checkRulebook(config, { addPass, addWarning, addError }) {
       return;
     }
     const checkName = `rulebook:${suite.name}`;
-    if (suiteResult.status === 2) {
-      const reason = mapToPlainText(suiteResult.stderr || suiteResult.stdout).trim().split(/\r?\n/)[0];
-      addWarning(checkName, `suite could not run: ${reason}`);
+    const failures = getSuiteFailures(suiteResult.stdout);
+    // A suite passes with exit 0 and fails with exit 1 + FAIL lines. Anything else (2 = usage,
+    // 127 = the script wasn't found — WSL's bash on a C:/ path) means it never ran: say so,
+    // never count it as a pass.
+    const hasRun = suiteResult.status === 0 || (suiteResult.status === 1 && failures.length > 0);
+    if (!hasRun) {
+      const reason = mapToPlainText(suiteResult.stderr || suiteResult.stdout).trim().split(/\r?\n/)[0] || 'no output';
+      addWarning(checkName, `suite could not run (exit ${suiteResult.status}): ${reason}`, `bash used: ${getBashPath()} — set KMWC_BASH to Git for Windows' bash.exe if this is WSL's`);
       continue;
     }
-    const failures = getSuiteFailures(suiteResult.stdout);
     for (const failure of failures) {
       // An architectural decision recorded in VALIDATION-NOTES.md (the rulebook's accepted-deviation file).
       if (acceptedCheckIds.has(failure.checkId)) addPass(checkName, `${failure.checkId} accepted deviation (${VALIDATION_NOTES_FILE}): ${failure.reason}`);
       else addError(checkName, `${failure.checkId} ${failure.reason}`, `see ${suite.name}.checks.md → ${failure.checkId}`);
     }
-    if (!failures.length) addPass(checkName, suiteResult.status === 0 ? 'all auto checks pass' : `exit ${suiteResult.status}`);
+    if (!failures.length) addPass(checkName, 'all auto checks pass');
   }
 }
 
-export async function run(args) {
+/** `registry` is for tests (fixture repos); the CLI always uses components.json. */
+export async function run(args, { registry } = {}) {
   const config = getKmwcConfig(args.root);
-  const results = checkComponent(config, { shouldRunRulebook: !args['no-rulebook'], shouldCheckPackage: !args['no-pack'] });
+  const results = checkComponent(config, { shouldRunRulebook: !args['no-rulebook'], shouldCheckPackage: !args['no-pack'], registry });
   const errorCount = results.filter((result) => result.level === 'error').length;
   const warningCount = results.filter((result) => result.level === 'warning').length;
 

package/src/cli/repo-checks.js

@@ -109,6 +109,12 @@ export function getMentionedPorts(text) {
   return getUniqueSorted(patterns.flatMap((pattern) => [...text.matchAll(pattern)].map((match) => Number(match[1]))));
 }
 
+/**
+ * A doc that names other repos' ports on purpose (a dated plan, a cross-repo review) carries
+ * `<!-- kmwc-other-ports: why -->` and isn't scanned.
+ */
+export const OTHER_PORTS_MARKER = 'kmwc-other-ports';
+
 /** Mentions in README.md / CLAUDE.md / docs/*.md of ports outside the repo's block → [{ file, port }]. */
 export function loadStalePortMentions(root, portBlock) {
   const blockRange = getPortBlockRange(portBlock);
@@ -116,7 +122,7 @@ export function loadStalePortMentions(root, portBlock) {
   const docFiles = [...DOC_FILES, ...(existsSync(docsDir) ? readdirSync(docsDir).filter((name) => name.endsWith('.md')).map((name) => `${DOCS_DIR}/${name}`) : [])];
   return docFiles.flatMap((file) => {
     const text = readText(join(root, file));
-    return text ? getMentionedPorts(text).filter((port) => !checkIsInRange(port, blockRange)).map((port) => ({ file, port })) : [];
+    return text && !text.includes(OTHER_PORTS_MARKER) ? getMentionedPorts(text).filter((port) => !checkIsInRange(port, blockRange)).map((port) => ({ file, port })) : [];
   });
 }
 
@@ -252,7 +258,8 @@ export function getKitDuplicates(pageText, kitClassNames, { isStylesheet = false
 
 /**
  * Fixed colours on purpose (a theme gallery, a mockup, a test fixture): a page `<style>`
- * block with the attribute, or one rule right after a `/* kmwc-fixed-colors *\/` comment.
+ * block or an element with a `style="…"` that carries the attribute, or one rule right
+ * after a `/* kmwc-fixed-colors *\/` comment.
  */
 export const FIXED_COLORS_ATTRIBUTE = 'data-kmwc-fixed-colors';
 export const FIXED_COLORS_MARKER = 'kmwc-fixed-colors';
@@ -283,7 +290,7 @@ export function checkIsHardcodedColor(property, value) {
  * Hard-coded colours in one page's `<style>` blocks and `style="…"` attributes (or in
  * examples-local.css): they stay the same in dark mode while the kit around them flips.
  * `var()` fallbacks and `light-dark()` pairs follow the theme; a `<style data-kmwc-fixed-colors>`
- * block and a rule marked `/* kmwc-fixed-colors *\/` are skipped. Returns [{ found }]. Pure.
+ * block, an element carrying the attribute and a rule marked `/* kmwc-fixed-colors *\/` are skipped. Returns [{ found }]. Pure.
  */
 export function getHardcodedColors(pageText, { isStylesheet = false } = {}) {
   const styleText = isStylesheet
@@ -302,7 +309,12 @@ export function getHardcodedColors(pageText, { isStylesheet = false } = {}) {
     }
   }
   if (isStylesheet) return hardcodedColors;
-  for (const [, inlineStyle] of pageText.matchAll(/\sstyle="([^"]*)"/g)) {
+  for (const match of pageText.matchAll(/\sstyle="([^"]*)"/g)) {
+    // The element's own attribute opts its style="…" out: markup a render callback draws
+    // inside a shadow root can't be reached by page CSS, so inline is the only way there.
+    const tagText = pageText.slice(pageText.lastIndexOf('<', match.index), pageText.indexOf('>', match.index + match[0].length) + 1);
+    if (tagText.includes(FIXED_COLORS_ATTRIBUTE)) continue;
+    const inlineStyle = match[1];
     for (const declaration of inlineStyle.split(';')) {
       const [property, ...valueParts] = declaration.split(':');
       const value = valueParts.join(':').trim();
@@ -358,6 +370,24 @@ function getSourceStylesheets(directory, relativeDirectory = SOURCE_DIR) {
   });
 }
 
+/**
+ * Styled loader classes vs the separator core draws → { isCoreClassStyled, renamedClasses,
+ * collidingClasses }. A class with the other separator is a rename done too early / too late —
+ * unless core is still on `-` and its class is styled too: then the `__loader` is the
+ * component's own element (web-multiselect's loading-state row), which collides once core
+ * draws `<prefix>__loader`. Pure.
+ */
+export function getLoaderClassVerdict(coreSeparator, styledLoaderClasses) {
+  const isCoreClassStyled = styledLoaderClasses.some(({ separator }) => separator === coreSeparator);
+  const otherClasses = styledLoaderClasses.filter(({ separator }) => separator !== coreSeparator);
+  const isOwnLoaderElement = coreSeparator === '-' && isCoreClassStyled;
+  return {
+    isCoreClassStyled,
+    renamedClasses: isOwnLoaderElement ? [] : otherClasses,
+    collidingClasses: isOwnLoaderElement ? otherClasses : [],
+  };
+}
+
 /** Loader classes styled in the component's src CSS: [{ file, className, separator }]. */
 export function loadStyledLoaderClasses(root, prefix) {
   return getSourceStylesheets(join(root, SOURCE_DIR)).flatMap((file) =>

package/src/examples/css/controls.css

@@ -213,13 +213,13 @@
 
     button.secondary,
     button.btn-secondary {
-        background: var(--kmwc-neutral-color);
+        background: var(--kmwc-neutral-fill-color);
         color: var(--kmwc-text-color-on-neutral);
     }
 
     button.secondary:hover,
     button.btn-secondary:hover {
-        background: color-mix(in srgb, var(--kmwc-neutral-color) 80%, black);
+        background: var(--kmwc-neutral-fill-color-hover);
     }
 
     button.btn-outline {

package/src/examples/css/tokens.css

@@ -120,9 +120,10 @@
         --kmwc-console-err-color: #fca5a5;
         /* Dark: the chip is a step up from the main surface (slate on a slate page, not a
            neutral grey), and the text keeps the accent hue but at least 0.8 lightness, so a
-           mid-dark accent (treeview's #059669) stays readable on it. */
+           mid-dark accent (treeview's #059669) stays readable on it. Light: the same hue at
+           most 0.5 lightness — the raw accent read at ~3.3:1 on the pale chip. */
         --kmwc-inline-code-bg: light-dark(#edf2f7, oklch(from var(--kmwc-main-bg) calc(l + 0.07) c h));
-        --kmwc-inline-code-color: light-dark(var(--kmwc-accent-color), oklch(from var(--kmwc-accent-color) max(l, 0.8) c h));
+        --kmwc-inline-code-color: light-dark(oklch(from var(--kmwc-accent-color) min(l, 0.5) c h), oklch(from var(--kmwc-accent-color) max(l, 0.8) c h));
 
         /* ======================================================================
            COLORS — SEMANTIC
@@ -137,10 +138,15 @@
         --kmwc-danger-fill-color-hover: var(--base-danger-color-hover, light-dark(color-mix(in srgb, black 15%, var(--kmwc-danger-fill-color)), color-mix(in srgb, white 15%, var(--kmwc-danger-fill-color))));
         --kmwc-text-color-on-danger: var(--base-on-danger-text-color, color(from color(from var(--kmwc-danger-fill-color) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1)));
         --kmwc-neutral-color: light-dark(#6b7280, #9ca3af);
+        /* A grey button needs its own fill: the dark-mode neutral (#9ca3af) sits just under the
+           on-colour formula's 0.34 switch, so it got white text at 2.5:1. Dots and pills keep the
+           light grey; the button takes a dark one (white text ≥ 4.5:1 in both themes). */
+        --kmwc-neutral-fill-color: light-dark(#6b7280, #4b5563);
+        --kmwc-neutral-fill-color-hover: light-dark(color-mix(in srgb, black 15%, var(--kmwc-neutral-fill-color)), color-mix(in srgb, white 12%, var(--kmwc-neutral-fill-color)));
         --kmwc-badge-new-bg: light-dark(#e53e3e, #f56565);
         /* Text on the neutral / badge fills: the contract's on-colour formula on
            their own background, not on the accent (a light primary would turn it black). */
-        --kmwc-text-color-on-neutral: color(from color(from var(--kmwc-neutral-color) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1));
+        --kmwc-text-color-on-neutral: color(from color(from var(--kmwc-neutral-fill-color) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1));
         --kmwc-text-color-on-badge-new: color(from color(from var(--kmwc-badge-new-bg) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1));
 
         /* ======================================================================

package/src/vite/page-composer.js

@@ -39,7 +39,11 @@ const INCLUDE_PATTERN = /<kmwc-include\b([^>]*?)(?:\/>|>([\s\S]*?)<\/kmwc-includ
 const DEMO_PATTERN = /<kmwc-demo\b([^>]*)>([\s\S]*?)<\/kmwc-demo>/g;
 const SHOWN_SCRIPT_PATTERN = /<script\b([^>]*\bdata-kmwc-show\b[^>]*)>([\s\S]*?)<\/script>/g;
 const PAGE_META_PATTERN = /<meta\s+name="kmwc:([a-z-]+)"\s+content="([^"]*)"\s*\/?>\s*/g;
-const HEAD_ELEMENT_PATTERN = /<link\b[^>]*>\s*|<style\b[^>]*>[\s\S]*?<\/style>\s*/g;
+// A <style> element, or ANY start tag (quoted attribute values may hold `>` and `<link>`):
+// matching whole tags left to right means the text `<link>` inside a tooltip's title=""
+// is consumed with its tag and never read as an element. Only <style> and <link> move.
+const HEAD_ELEMENT_PATTERN = /<style(?=[\s>])(?:"[^"]*"|'[^']*'|[^>"'])*>[\s\S]*?<\/style>\s*|<([a-zA-Z][\w-]*)(?:"[^"]*"|'[^']*'|[^>"'])*>\s*/g;
+const HEAD_ELEMENT_TAGS = ['style', 'link'];
 const ATTRIBUTE_PATTERN = /([a-zA-Z][\w-]*)(?:\s*=\s*"([^"]*)")?/g;
 
 const HTML_COMMENT_PATTERN = /<!--[\s\S]*?-->/g;
@@ -201,7 +205,8 @@ export function renderLayout(fragmentHtml, { config, pagePath }) {
   const bodyContent = mapOutsideComments(
     htmlWithoutMeta,
     (text) =>
-      text.replace(HEAD_ELEMENT_PATTERN, (element) => {
+      text.replace(HEAD_ELEMENT_PATTERN, (element, tagName = 'style') => {
+        if (!HEAD_ELEMENT_TAGS.includes(tagName.toLowerCase())) return element;
         headElements.push(`    ${element.trim()}`);
         return '';
       }),

package/templates/claude-block.md

@@ -31,7 +31,8 @@ locally — every local fork is how they drifted apart.
   too — no inline styles for them. Page colours come from the kit's `--kmwc-*`
   tokens or `light-dark()` — a literal doesn't follow dark mode (doctor warns);
   a demo that shows fixed colours on purpose goes in `<style data-kmwc-fixed-colors>`
-  (one rule: a `/* kmwc-fixed-colors: why */` comment before it).
+  (one rule: a `/* kmwc-fixed-colors: why */` comment before it; an element's own
+  `style="…"`: the attribute on the element).
   If a second component needs a pattern, it belongs in the devkit.
 - **Example pages are fragments:** no `<html>`/`<head>`/`<header>` — start with
   `<meta name="kmwc:title" content="…">`, the devkit layout adds the rest. Shared text
@@ -54,4 +55,6 @@ locally — every local fork is how they drifted apart.
   `*.checks.sh` suites. A rulebook failure that is a real architectural decision
   goes into `VALIDATION-NOTES.md` under a `## C-XX-N — …` heading (deferrals
   don't count). After changing a page, `npx kmwc check-pages` loads every page at
-  desktop and phone widths and reports errors and horizontal overflow.
+  desktop and phone widths and reports errors, horizontal overflow and page CSS
+  that only matches inside a shadow root (markup a render callback draws there is
+  out of page CSS's reach — style it through the component's styles hook).