@keenmate/web-components-devkit 1.0.0-rc07 → 1.0.0-rc09

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## [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
+
+- **Doctor: hard-coded colours in page CSS** (warning). A colour literal (`#hex`, `rgb()` / `hsl()` /
+  `oklch()`, a named colour) on a colour property in a page `<style>`, a `style="…"` or
+  `examples-local.css` stays the same when the theme switch flips the kit to dark. web-treeview's
+  migration kept 10 pages' own `<style>` blocks, and 8 of them had search bars, status bars, badges and
+  panels that didn't follow dark mode. rc07 only flagged rules that restyle a kit class, so nothing
+  reported them. `var()` fallbacks and `light-dark()` pairs pass. A block that shows fixed colours on
+  purpose (a theme gallery, an iOS mockup) opts out with `<style data-kmwc-fixed-colors>`, or one
+  rule with a `/* kmwc-fixed-colors: why */` comment before it (the playground's e2e fixture red).
+- **Doctor: the loader class matches the installed core** (error). Core 6d6b768 renamed the 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 an unstyled
+  loader. No rulebook check sees that, and a VALIDATION-NOTES `## C-NC-8` hides a leftover `.x-loader`
+  (drp has one for other classes). Doctor reads which class the installed core's `render-loader.js`
+  draws and fails on a `src/**/*.css` selector for the other one.
+
+### Fixed
+
+- **Inline `<code>` in dark mode** was the accent colour on a neutral `#2b2b2b` chip: about 3:1, and
+  web-treeview's `#059669` green read dim in prose and tables. The chip is now a step up from the main
+  surface (`oklch(from --kmwc-main-bg calc(l + 0.07) …)`, slate on slate), and the text is a new
+  `--kmwc-inline-code-color`: the accent hue at a lightness of at least 0.8 in dark, the accent as-is in
+  light. An e2e spec checks 4.5:1 for the default, green, navy and amber accents.
+
 ## [1.0.0-rc07] - 2026-11-03 [PUBLISHED]
 
 Found migrating web-treeview — each item is something doctor missed or got wrong there.

package/README.md

@@ -19,20 +19,15 @@ 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-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.
 
-## What's New in v1.0.0-rc06
+## What's New in v1.0.0-rc08
 
-- **Example pages — `<kbd>`, `<mark>`, field widths and `.push-end`** — Every component documents a keyboard map and most highlight search matches. Pages either left `<kbd>` in the browser's look (core's Interaction page had 18 bare keys) or styled `<mark>` themselves. A `<kbd>` now looks like the spotlight's key hints and a `<mark>` like its match highlight. Native fields are about 20 characters wide, so pages set inline widths; core had 14. A number field is now 7rem by default. `.w-xs` / `.w-sm` / `.w-md` / `.w-lg` (4 / 6 / 9 / 12rem) size a short field, and a `.form-group` still stretches it to the row. `.push-end` moves an item to the end of a `.controls` row. See the playground's WG08 and FC12.
-- **Example pages — phone and contrast fixes** — Inline `<code>` now breaks anywhere. Before, a long identifier such as `resolvePresentation(mode, env, map)` in a heading made a page 350px wide on a 320px screen; code inside a `<pre>` keeps its lines. Muted log text on the light `.log-panel` (`--muted` lines, the seq / time / source cells, the empty placeholder) measured 2.83:1 in the light theme. It now uses `--kmwc-text-color-2`, and a spec checks every tone on both panels in both themes against WCAG AA's 4.5:1. Timeline rows wrap, so on a phone or with a long source name the detail drops under the cells instead of showing one letter per line. `.css-readout` gets a top margin after the demo it measures.
-- **CLI — `kmwc <command> --help` no longer runs the command** — Only a top-level `--help` was handled, and unknown flags were silently ignored, so `kmwc sync --help` did a full sync and overwrote core's hand-written Makefile. Every command now lists the flags it accepts. `--help` / `-h` after any command prints that command's usage and exits 0, and an unknown option is an error (exit 2). A boolean flag no longer takes the next word as its value.
-- **Libraries — `library: false`, `cssVariables: false`, and a doctor that knows the kind** — A repo like web-components-core builds its package with `tsc`. A plain `vite build` (the devkit's library mode) would empty its `dist/`, so `"kmwc": { "library": false }` now makes it refuse to run, while `vite build --mode examples` still builds the site. `"cssVariables": false` turns off the variables-manifest check, so sync stops re-adding `check:vars`. Doctor reads the registry kind (or `kmwc.kind`): a `library` runs only naming-conventions, readme-structure, publish-command and example-pages. On core that drops 12 errors and 4 "suite could not run" warnings that didn't apply to a library.
+- **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.
 
 ## Catalogue
 
@@ -367,7 +362,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)
@@ -416,10 +411,24 @@ generated files:
   selector (`.kbd`, `kbd`, `mark`, `.pill`, `.card` …) and single-declaration
   inline styles a kit class covers (`width` on a field → `.w-*`,
   `margin-left: auto` → `.push-end`, `margin-top: 1rem` → `.mt-1`) are warnings.
+  So is a hard-coded colour (`#hex`, `rgb()`, `white` …) in page CSS or a `style="…"`:
+  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.
+- **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.
 
 `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`).
 
 **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/web-components-devkit",
-  "version": "1.0.0-rc07",
+  "version": "1.0.0-rc09",
   "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",

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

@@ -1,24 +1,28 @@
 /**
  * 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';
 // Requests a page doesn't control (favicon probes, analytics in a built site).
 const IGNORED_REQUEST_PATTERN = /favicon\.ico|stats\.keenmate\.services|plausible/;
 
@@ -30,12 +34,68 @@ 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];
+  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('>, <')}>`);
   if (pageReport.scrollWidth > pageReport.clientWidth) {
     const offenderText = pageReport.offenders.length ? ` — widest: ${pageReport.offenders.join(', ')}` : '';
@@ -106,7 +166,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]}`));
@@ -123,7 +183,8 @@ async function loadPageReport(browser, pageUrl, width) {
     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 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 +215,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 +234,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/doctor.js

@@ -34,6 +34,11 @@ import {
   loadSharedPlausibleSiteIds,
   loadKitClassNames,
   getKitDuplicates,
+  FIXED_COLORS_ATTRIBUTE,
+  FIXED_COLORS_MARKER,
+  getHardcodedColors,
+  loadCoreLoader,
+  loadStyledLoaderClasses,
 } from '../repo-checks.js';
 
 const DEVKIT_PACKAGE_NAME = '@keenmate/web-components-devkit';
@@ -197,6 +202,23 @@ export function checkComponent(config, doctorConfig = {}) {
   }
   if (pageFiles.length && !kitDuplicateSources.length) addPass('pages', 'no page CSS re-implements the kit');
 
+  // Page CSS colours that stay put when the theme switch flips the kit to dark.
+  const hardcodedColorSources = [
+    ...pageFiles.map((pageFile) => ({ file: pageFile, hardcodedColors: getHardcodedColors(readFileSync(join(config.root, pageFile), 'utf8')) })),
+    ...(existsSync(localStylesheetPath)
+      ? [{ file: LOCAL_STYLESHEET_FILE, hardcodedColors: getHardcodedColors(readFileSync(localStylesheetPath, 'utf8'), { isStylesheet: true }) }]
+      : []),
+  ].filter((source) => source.hardcodedColors.length);
+  for (const { file, hardcodedColors } of hardcodedColorSources) {
+    const shownColors = hardcodedColors.slice(0, 3).map(({ found }) => found).join('; ');
+    addWarning(
+      'pages',
+      `${file}: ${hardcodedColors.length} hard-coded colour(s) that don't follow dark mode — ${shownColors}${hardcodedColors.length > 3 ? ' …' : ''}`,
+      `use the kit's --kmwc-* tokens or light-dark(); fixed colours on purpose: <style ${FIXED_COLORS_ATTRIBUTE}>, or /* ${FIXED_COLORS_MARKER} */ before one rule`
+    );
+  }
+  if (pageFiles.length && !hardcodedColorSources.length) addPass('pages', 'page CSS colours follow the theme');
+
   // ── generated files ──────────────────────────────────────────────────────
   if (config.hasPackageConfig) {
     for (const planItem of getSyncPlan(config)) {
@@ -252,6 +274,9 @@ export function checkComponent(config, doctorConfig = {}) {
     if (!outputMismatches.length) addPass('library', 'package.json targets match the library build outputs');
   }
 
+  // ── core's default loader class ──────────────────────────────────────────
+  if (config.prefix && config.kind !== LIBRARY_KIND) checkLoaderClass(config, { addPass, addWarning, addError });
+
   // ── analytics ────────────────────────────────────────────────────────────
   const plausibleSiteId = loadPlausibleSiteId(config.root);
   const sharingRepoIds = loadSharedPlausibleSiteIds(config, getRegistry(), plausibleSiteId);
@@ -299,6 +324,30 @@ function checkPorts(config, portBlock, { addPass, addWarning, addError }) {
   }
 }
 
+/**
+ * The CSS styles the loader class the INSTALLED core draws. Core 6d6b768 renamed
+ * `<prefix>-loader` → `<prefix>__loader` with no overlap release; renaming the CSS
+ * 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 }) {
+  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) {
+    addError(
+      'loader',
+      `${file} styles .${className}, but core ${coreLoader.version} draws the default loader as <span class="${coreClassName}"> — it renders unstyled`,
+      coreLoader.separator === '__'
+        ? `rename .${className} → .${coreClassName} (CSS, tests, docs; keep the --${config.prefix}-loader-* tokens)`
+        : `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`);
+}
+
 /** Packed paths that break PACKAGE_LEAK_RULES → [{ path, label }]. Pure — exported for tests. */
 export function getPackageLeaks(packedPaths) {
   return packedPaths

package/src/cli/repo-checks.js

@@ -247,3 +247,120 @@ export function getKitDuplicates(pageText, kitClassNames, { isStylesheet = false
   }
   return duplicates;
 }
+
+// ── hard-coded colours in page CSS ───────────────────────────────────────────
+
+/**
+ * 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.
+ */
+export const FIXED_COLORS_ATTRIBUTE = 'data-kmwc-fixed-colors';
+export const FIXED_COLORS_MARKER = 'kmwc-fixed-colors';
+const MARKED_RULE_PATTERN = new RegExp(`/\\*[^*]*${FIXED_COLORS_MARKER}[\\s\\S]*?\\*/\\s*[^{}]*\\{[^{}]*\\}`, 'g');
+const COLOR_PROPERTY_PATTERN = /color|background|border|outline|shadow|fill|stroke|text-decoration/i;
+const COLOR_LITERAL_PATTERN =
+  /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch)\(\s*(?!from\b)|\b(?:white|black|red|green|blue|gray|grey|silver|orange|yellow|purple|pink|navy|teal|maroon|olive|lime|aqua|fuchsia|gold|crimson)\b/i;
+
+/** A declaration value with every `var(…)` collapsed — a literal fallback never shows while the kit token exists. */
+function mapWithoutVarFallbacks(value) {
+  let previous;
+  let current = value;
+  do {
+    previous = current;
+    current = current.replace(/var\([^()]*\)/gi, 'var()');
+  } while (current !== previous);
+  return current;
+}
+
+/** True when a colour declaration's value is a literal that ignores dark mode. Pure. */
+export function checkIsHardcodedColor(property, value) {
+  if (!COLOR_PROPERTY_PATTERN.test(property) || property.startsWith('--')) return false;
+  const plainValue = mapWithoutVarFallbacks(value);
+  return !/light-dark\(/i.test(plainValue) && COLOR_LITERAL_PATTERN.test(plainValue);
+}
+
+/**
+ * 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.
+ */
+export function getHardcodedColors(pageText, { isStylesheet = false } = {}) {
+  const styleText = isStylesheet
+    ? pageText
+    : [...pageText.matchAll(/<style\b([^>]*)>([\s\S]*?)<\/style>/gi)]
+        .filter((match) => !match[1].includes(FIXED_COLORS_ATTRIBUTE))
+        .map((match) => match[2])
+        .join('\n');
+  const hardcodedColors = [];
+  const checkedText = styleText.replace(MARKED_RULE_PATTERN, '').replace(/\/\*[\s\S]*?\*\//g, '');
+  for (const [, selector, body] of checkedText.matchAll(/([^{};@]+?)\s*\{([^{}]*)\}/g)) {
+    for (const declaration of body.split(';')) {
+      const [property, ...valueParts] = declaration.split(':');
+      const value = valueParts.join(':').trim();
+      if (value && checkIsHardcodedColor(property.trim(), value)) hardcodedColors.push({ found: `${selector.trim().replace(/\s+/g, ' ')} { ${property.trim()}: ${value} }` });
+    }
+  }
+  if (isStylesheet) return hardcodedColors;
+  for (const [, inlineStyle] of pageText.matchAll(/\sstyle="([^"]*)"/g)) {
+    for (const declaration of inlineStyle.split(';')) {
+      const [property, ...valueParts] = declaration.split(':');
+      const value = valueParts.join(':').trim();
+      if (value && checkIsHardcodedColor(property.trim(), value)) hardcodedColors.push({ found: `style="${property.trim()}: ${value}"` });
+    }
+  }
+  return hardcodedColors;
+}
+
+// ── core's default loader class ──────────────────────────────────────────────
+
+const CORE_PACKAGE_PATH = join('node_modules', '@keenmate', 'web-components-core');
+const CORE_RENDER_LOADER_FILE = join('dist', 'dom', 'render-loader.js');
+const SOURCE_DIR = 'src';
+const SKIPPED_SOURCE_DIRS = new Set(['node_modules', 'dist']);
+
+/**
+ * The separator in the class core's default loader gets: `'__'` (`<prefix>__loader`),
+ * `'-'` (`<prefix>-loader`, before core 6d6b768), or null when the build doesn't say. Pure.
+ */
+export function getCoreLoaderSeparator(renderLoaderText) {
+  const match =
+    renderLoaderText.match(/\$\{\s*[\w$.]+\s*\}(__|-)loader(?![\w-])/) || renderLoaderText.match(/\+\s*["'`](__|-)loader["'`]/);
+  return match ? match[1] : null;
+}
+
+/** The loader classes a stylesheet styles: [{ className, separator }]. Pure. */
+export function getStyledLoaderClasses(cssText, prefix) {
+  const pattern = new RegExp(`\.(${prefix}(__|-)loader)(?![\w-])`, 'g');
+  const plainText = cssText.replace(/\/\*[\s\S]*?\*\//g, '');
+  const classes = new Map([...plainText.matchAll(pattern)].map((match) => [match[1], match[2]]));
+  return [...classes].map(([className, separator]) => ({ className, separator }));
+}
+
+/** The installed core (walking up for hoisted installs): { version, separator } or null. */
+export function loadCoreLoader(root) {
+  for (let directory = resolve(root); ; directory = resolve(directory, '..')) {
+    const packageText = readText(join(directory, CORE_PACKAGE_PATH, 'package.json'));
+    if (packageText) {
+      const renderLoaderText = readText(join(directory, CORE_PACKAGE_PATH, CORE_RENDER_LOADER_FILE));
+      return { version: JSON.parse(packageText).version, separator: renderLoaderText ? getCoreLoaderSeparator(renderLoaderText) : null };
+    }
+    if (resolve(directory, '..') === directory) return null;
+  }
+}
+
+function getSourceStylesheets(directory, relativeDirectory = SOURCE_DIR) {
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const relativePath = `${relativeDirectory}/${entry.name}`;
+    if (entry.isDirectory()) return SKIPPED_SOURCE_DIRS.has(entry.name) ? [] : getSourceStylesheets(join(directory, entry.name), relativePath);
+    return entry.name.endsWith('.css') ? [relativePath] : [];
+  });
+}
+
+/** 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) =>
+    getStyledLoaderClasses(readFileSync(join(root, file), 'utf8'), prefix).map((styledClass) => ({ file, ...styledClass }))
+  );
+}

package/src/examples/css/content.css

@@ -118,7 +118,7 @@
         padding: 0.2rem 0.4rem;
         border-radius: 3px;
         font-size: 0.9em;
-        color: var(--kmwc-accent-color);
+        color: var(--kmwc-inline-code-color);
         font-family: var(--kmwc-mono-font-family);
         /* A long identifier has no break opportunity — break it anywhere
            rather than widen the page on a phone. */

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

@@ -118,7 +118,11 @@
         --kmwc-console-info-color: #7dd3fc;
         --kmwc-console-warn-color: #fcd34d;
         --kmwc-console-err-color: #fca5a5;
-        --kmwc-inline-code-bg: light-dark(#edf2f7, #2b2b2b);
+        /* 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. */
+        --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));
 
         /* ======================================================================
            COLORS — SEMANTIC
@@ -133,10 +137,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/templates/claude-block.md

@@ -28,7 +28,10 @@ locally — every local fork is how they drifted apart.
   element out. Log lines take the kit tones (`.log-line--ok|info|warn|err|muted`,
   `--action`, timeline cells `.log-line__time` …) — don't colour them per page.
   `<kbd>`, `<mark>`, field widths (`.w-xs` … `.w-lg`) and `.push-end` are kit
-  too — no inline styles for them.
+  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).
   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
@@ -51,4 +54,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).