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

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [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,6 +19,11 @@ 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
+
+- **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.
+
 ## What's New in v1.0.0-rc07
 
 - **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.
@@ -27,13 +32,6 @@ them in the same shape: `@keenmate/web-components-devkit`.
 - **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.
 
-## What's New in v1.0.0-rc06
-
-- **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.
-
 ## Catalogue
 
 <!-- kmwc:catalogue:start — generated by `npm run readme`, do not edit inside -->
@@ -416,6 +414,16 @@ 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

package/package.json

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

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