@keenmate/web-components-devkit 1.0.0-rc05 → 1.0.0-rc06

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## [1.0.0-rc06] - 2026-11-01 [PUBLISHED]
+
+### Added
+
+- **`<kbd>` and `<mark>`** — every component documents a keyboard map and most highlight
+  search matches, and pages either left them in the browser's look (core's Interaction page:
+  18 bare `<kbd>`s) or styled them locally (core's Search page). A `<kbd>` now looks like the
+  spotlight's key hints and a `<mark>` like its match highlight. Widgets page WG08.
+- **Field widths** — a native field is ~20 characters wide, so pages set inline widths (core:
+  14). A number field is now 7rem (six digits and the spin buttons; a `.form-group` still
+  stretches it), and `.w-xs` / `.w-sm` / `.w-md` / `.w-lg` (4 / 6 / 9 / 12rem) size a short
+  field. `.push-end` moves an item to the end of a `.controls` row. Form controls page FC12.
+- **`kmwc.library: false`** — for a repo that builds its package itself (core: `tsc`) or ships
+  none. Plain `vite build`, the devkit's library mode, refuses to run instead of emptying
+  `dist/`; `vite build --mode examples` still builds the site, and sync no longer proposes a
+  `build: vite build` script. `{ "shouldBuild": false, "entry": … }` keeps the pages' entry.
+- **`kmwc.cssVariables: false`** (or `checkMode: "off"`) — sync stopped re-adding `check:vars`
+  only when there was no manifest; now it can be switched off (core builds its variable names
+  by interpolation, which the checker can't see). `kmwc check-vars` then skips.
+- **Doctor knows libraries** — a repo whose registry entry (or `kmwc.kind`) is `library` runs
+  only the rulebook suites that apply to it: naming-conventions, readme-structure,
+  publish-command, example-pages. The CSS, Custom Elements Manifest, overlay and
+  component-structure suites check what a custom element ships; on core they gave 12 errors
+  and 4 "suite could not run" warnings. No prefix warning for a library.
+
+### Fixed
+
+- **`kmwc <command> --help` ran the command** — only a top-level `--help` was handled and
+  unknown flags were ignored, so `kmwc sync --help` did a full sync (it overwrote core's
+  Makefile). `--help` / `-h` after any command now prints that command's usage and exits 0,
+  and an unknown option is an error (exit 2). Every command declares its flags; a boolean
+  flag no longer swallows the next word as its value.
+- **Inline `<code>` widened a phone page** — a long identifier has no break opportunity, so
+  `resolvePresentation(mode, env, map)` in a heading made core's page 350px wide at 320px.
+  Inline code now breaks anywhere; code in a `<pre>` keeps its lines.
+- **Muted log text failed contrast on the light panel** — `--muted` lines, the seq / time /
+  source cells and the empty placeholder used `--kmwc-text-color-3`: 2.83:1 on the light
+  `.log-panel` in the light theme (WCAG AA wants 4.5:1). They now use `--kmwc-text-color-2`.
+  A spec checks every tone on both panels in both themes.
+- **`.css-readout` sat on the demo above it** — it had no top margin (core carried 8 inline
+  margins); it now has 0.75rem.
+
+- **Timeline log lines on a phone** — the cells (`.log-line__seq`, `__time`, `__source`,
+  `__name`) never shrink and the row never wrapped, so on a narrow panel, or with a long
+  source name, the detail got the few pixels left over: one letter per line. The row now
+  wraps, and the detail wants ~14rem beside the cells; with less room it drops under them at
+  full width. Wide panels are unchanged. A cell is capped at the panel width.
+
 ## [1.0.0-rc05] - 2026-11-01 [PUBLISHED]
 
 ### Changed

package/README.md

@@ -19,6 +19,13 @@ 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-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.
+
 ## What's New in v1.0.0-rc05
 
 - **Log panels — one tone set for every log line** — web-components-core's example pages each coloured their log lines with their own classes (`.warn`, `.lv-error`, `data-kind="hook"` …), four schemes mixing severity with "what happened". A `.log-line` now takes one of five tones — `--ok`, `--info`, `--warn`, `--err`, `--muted`, the same names as `.pill` and `.status-dot` (which gain `--info` / `--muted`) — and `--action` marks a "▶ you clicked X" line. Kinds such as hook or callback map onto those tones; the kind itself goes in a cell as text. On `.log-panel--dark` the tones switch to fixed light tints (`--kmwc-console-ok|info|warn|err-color`), so they stay readable on the console in both themes, while a light `.log-panel` follows the page theme. Every line keeps its line breaks and indentation.
@@ -26,12 +33,6 @@ them in the same shape: `@keenmate/web-components-devkit`.
 - **`.event-log` — the legacy console now renders as `.log-panel--dark`** — Many component pages (web-grid, web-dropzone, web-treeview, the showcases) still use `.event-log` / `.event-entry` / `.event-time` / `.event-name`, which differed slightly from the newer panel (grey base text, 0.8rem, a 200px cap, no columns). It is now the same panel, and an `.event-entry` holding `.event-time` / `.event-name` is a timeline row with an aligned time column and tones, so old and new logs look the same. Other `.event-log` markup — lines without `.event-entry`, page-own classes — only gets the panel look, so existing layouts don't break.
 - **Small helpers — `.mono`, `td.is-highlight`, `.check-list`** — `.mono` sets the monospace font without the code chip, and `textarea.mono` makes a JSON or config editor. `td.is-highlight` (or `th`) tints one table cell, where only whole rows could be highlighted before. `.check-list` stacks checkbox / radio options one per line, a long label wrapping beside its box, with room for a trailing `.pill`. The playground shows everything on the Widgets (WG01–WG07), Form controls (FC11) and Tables (TB06) pages.
 
-## What's New in v1.0.0-rc04
-
-- **Example-page grids — wide content scrolls instead of widening the page** — A `<pre>` or table inside a `.grid`, `.grid-2` or `.card-grid` item still pushed the page wider than a phone: grid items default to `min-width: auto` (their min-content), so the single `1fr` column at ≤ 768 px grew to fit the content instead of letting it scroll. Every item of the three grids now gets `min-width: 0`, the same rule pure-css puts on its `.pc-col-*` columns. Found by two agents migrating web-components-core's example pages, which drop their page-local workaround with this release.
-- **`.controls` — long `<code>` in a button wraps on a phone** — rc03 wrapped `<code>` only inside `.controls` labels, so a button whose label was an unbroken API name (`setAttribute("…")`) still overflowed the row. The wrap rule (`overflow-wrap: anywhere`) now covers any `<code>` in a `.controls` row, and a `.controls` button is capped at the row width. An e2e spec injects both cases at 390 px and checks that the page stays inside the screen.
-- **Playground — a Widgets page for the kit's opt-in helpers** — `.log-panel` (light and `--dark`), the legacy `.event-log`, `.pill` / `.status-dot` tones, `.display-sliders` and `.css-readout` had no demo, so their look was only checked on component pages. The new `examples-widgets.html` (WG01–WG04) shows them as they are today, including the gaps the coming log-tone work fixes (no line tones, leading spaces collapsing in a log line), and gets its own e2e spec.
-
 ## Catalogue
 
 <!-- kmwc:catalogue:start — generated by `npm run readme`, do not edit inside -->
@@ -142,7 +143,8 @@ Every field is optional. Defaults are derived from the package.
   "tagline": "Feature-rich multiselect …",       // default: package.json description
   "tag": "web-multiselect",
   "prefix": "ms",                                // reserved CSS prefix (rulebook base-variables.md)
-  "library": {
+  "kind": "component",                           // default: the components.json entry's kind
+  "library": {                                   // false: no library build (see below)
     "entry": "src/index.ts",                     // default
     "globalName": "MultiSelect",                 // UMD global
     "fileName": "multiselect",                   // → dist/multiselect.js + .umd.js
@@ -165,7 +167,7 @@ Every field is optional. Defaults are derived from the package.
     "runner": "podman",
     "packageJsonPaths": ["package.json"]         // monorepos: list workspace package.jsons too
   },
-  "cssVariables": {
+  "cssVariables": {                              // false: no variables manifest, no check:vars
     "sources": ["src/css"],                      // dirs (stylesheets) or explicit files (any type)
     "internalVariables": ["ms-input-current-width"], // runtime internals, not theming knobs
     "checkMode": "declared"                      // or "consumed" (var() reads)
@@ -179,6 +181,16 @@ Every field is optional. Defaults are derived from the package.
 }
 ```
 
+**A library** (registry `kind: "library"`, e.g. web-components-core) builds its
+package itself (`tsc`) or ships none. `"library": false` (or `{ "shouldBuild":
+false, "entry": … }` to keep the pages' entry script) makes plain `vite build`
+refuse to run — it is the devkit's library mode and would empty `dist/` — while
+`vite build --mode examples` still builds the site, and `kmwc sync` no longer
+proposes a `build: vite build` script. `"cssVariables": false` turns off the
+manifest check (no `check:vars` script, `kmwc check-vars` skips), for variables
+the checker can't see, such as names built by string interpolation. Doctor runs
+only the rulebook suites that apply to a library (see below).
+
 ### Vite preset
 
 ```ts
@@ -265,7 +277,8 @@ doctor` lists the ones still repeating the head/header boilerplate.
   `.demo-area`, `.demo-card`, `.code-block`, `.note(.warning|.info|.success|.error)`,
   `.grid`/`.card-grid`, `.reference-table` (+ `.table-*` modifiers), `.log-panel`, `.pill`,
   `.status-dot`, `.control-group`, buttons (`.btn-secondary`, `.btn-outline`,
-  `.btn-danger`) — while everything the kit **generates** is prefixed BEM
+  `.btn-danger`), `<kbd>` keys and `<mark>` search matches (the spotlight's look),
+  `.push-end` (to the end of a flex row) — while everything the kit **generates** is prefixed BEM
   (`kmwc-chapter-nav__item--active`, `kmwc-copy-link--copied`, …).
 - **Form controls** look the same on every page without a class: text fields,
   selects and list boxes (`multiple` / `size`), textareas, checkboxes, radios,
@@ -275,7 +288,9 @@ doctor` lists the ones still repeating the head/header boilerplate.
   selects and buttons share `--kmwc-control-height`, so a row of them lines up
   in any container, not only `.controls`. The rules are zero-specificity
   (`:where()`); `kmwc-native` on an element or an ancestor keeps the browser's
-  own controls (a light-DOM component that draws its own inputs). The
+  own controls (a light-DOM component that draws its own inputs). A number field
+  is 7rem wide; `.w-xs` / `.w-sm` / `.w-md` / `.w-lg` (4 / 6 / 9 / 12rem) size a
+  short field without an inline style. The
   playground's `examples-forms.html` shows them all.
 - **Tables:** any `<table>` gets a header fill, row lines and a hover tint;
   `.reference-table` is the full-width, fully bordered API table. Modifiers
@@ -351,8 +366,12 @@ kmwc check-release --tag t    latest ⇔ release version, rc ⇔ -rcN, version n
 kmwc new web-<name>           scaffold a component (--prefix, --title, --tag, --dir, --port, --minimal, --register)
                               --adopt: scaffold an ALREADY registered component (its port/prefix) to migrate into
 kmwc readme [--check]         regenerate this README's catalogue (devkit repo only)
+kmwc <command> --help         that command's usage — never runs the command
 ```
 
+An unknown option is an error (exit 2), never ignored — a typo can't run a
+command with its defaults.
+
 Generated files start with a `GENERATED by kmwc sync` header. Repo-specific
 make targets go in `Makefile.local`, which the generated Makefile includes at
 the end. Per-developer overrides (`DOCKER_RUNNER`, `IMAGE_PORT`) go in
@@ -364,6 +383,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.
+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).
 When the rulebook isn't checked out (or there's no bash) the suites are
 skipped with a warning — the rulebook stays the single source of truth; the
 devkit never copies its rules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/web-components-devkit",
-  "version": "1.0.0-rc05",
+  "version": "1.0.0-rc06",
   "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/args.js

@@ -1,16 +1,39 @@
-/** Tiny flag parser: --flag, --key value, --key=value, positionals. */
-export function parseArgs(args) {
+/**
+ * Flag parser: --flag, --key value, --key=value, positionals. `flagSpec` names
+ * every flag a command takes — `booleans` never take a value, `values` always
+ * do. Anything else is an error: an ignored typo (or `--help` before it was
+ * handled) used to run the command for real.
+ *
+ * @param {string[]} args
+ * @param {{ booleans?: string[], values?: string[] }} [flagSpec]
+ */
+export function parseArgs(args, flagSpec = {}) {
+  const booleanFlags = new Set(flagSpec.booleans || []);
+  const valueFlags = new Set(['root', ...(flagSpec.values || [])]);
   const out = { _: [] };
   for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (!a.startsWith('--')) {
-      out._.push(a);
+    const arg = args[i];
+    if (!arg.startsWith('-') || arg === '-') {
+      out._.push(arg);
       continue;
     }
-    const [key, inline] = a.slice(2).split(/=(.*)/s);
-    if (inline !== undefined) out[key] = inline;
-    else if (args[i + 1] && !args[i + 1].startsWith('--')) out[key] = args[++i];
-    else out[key] = true;
+    if (!arg.startsWith('--')) throw new Error(`unknown option "${arg}"`);
+    const [key, inline] = arg.slice(2).split(/=(.*)/s);
+    if (booleanFlags.has(key)) {
+      if (inline !== undefined) throw new Error(`--${key} takes no value`);
+      out[key] = true;
+    } else if (valueFlags.has(key)) {
+      if (inline !== undefined) out[key] = inline;
+      else if (args[i + 1] !== undefined && !args[i + 1].startsWith('--')) out[key] = args[++i];
+      else throw new Error(`--${key} needs a value`);
+    } else {
+      throw new Error(`unknown option "--${key}"`);
+    }
   }
   return out;
 }
+
+/** True when the arguments ask for help (`--help` or `-h` anywhere). */
+export function checkIsHelpRequested(args) {
+  return args.some((arg) => arg === '--help' || arg === '-h');
+}

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

@@ -68,6 +68,10 @@ 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;
+  }
   const manifestPath = resolve(config.root, config.cssVariables.manifest);
   if (!existsSync(manifestPath)) {
     console.log(`kmwc check-vars: no ${config.cssVariables.manifest} — nothing to check.`);

package/src/cli/commands/doctor.js

@@ -25,21 +25,33 @@ const LEGACY_PAGE_REFERENCES = ['examples-shared.css', 'examples-chapter-nav.js'
 const VITE_CONFIG_FILES = ['vite.config.ts', 'vite.config.mjs', 'vite.config.js'];
 const PLAYWRIGHT_CONFIG_FILES = ['playwright.config.ts', 'playwright.config.mjs', 'playwright.config.js'];
 
-/** Rulebook suites in the rulebook's canonical reading order; the prefix is passed where the script takes one. */
+/**
+ * Rulebook suites in the rulebook's canonical reading order; the prefix is
+ * passed where the script takes one. `isComponentOnly` suites check what a
+ * custom element ships (its CSS, manifest, overlay) — a `library` (registry
+ * kind, or kmwc.kind) skips them.
+ */
 export const RULEBOOK_SUITES = [
-  { name: 'component-structure', isPrefixed: false },
-  { name: 'naming-conventions', isPrefixed: true },
-  { name: 'css-structure', isPrefixed: true },
-  { name: 'theme-container', isPrefixed: true },
-  { name: 'base-variables', isPrefixed: true },
-  { name: 'color-scheme', isPrefixed: true },
-  { name: 'readme-structure', isPrefixed: false },
-  { name: 'custom-elements-manifest', isPrefixed: false },
-  { name: 'responsive-overlay', isPrefixed: true },
-  { name: 'publish-command', isPrefixed: false },
-  { name: 'example-pages', isPrefixed: false },
+  { name: 'component-structure', isPrefixed: false, isComponentOnly: true },
+  { name: 'naming-conventions', isPrefixed: true, isComponentOnly: false },
+  { name: 'css-structure', isPrefixed: true, isComponentOnly: true },
+  { name: 'theme-container', isPrefixed: true, isComponentOnly: true },
+  { name: 'base-variables', isPrefixed: true, isComponentOnly: true },
+  { name: 'color-scheme', isPrefixed: true, isComponentOnly: true },
+  { name: 'readme-structure', isPrefixed: false, isComponentOnly: false },
+  { name: 'custom-elements-manifest', isPrefixed: false, isComponentOnly: true },
+  { name: 'responsive-overlay', isPrefixed: true, isComponentOnly: true },
+  { name: 'publish-command', isPrefixed: false, isComponentOnly: false },
+  { name: 'example-pages', isPrefixed: false, isComponentOnly: false },
 ];
 
+const LIBRARY_KIND = 'library';
+
+/** The suites that apply to a repo of `kind`. Pure — exported for tests. */
+export function getRulebookSuites(kind) {
+  return RULEBOOK_SUITES.filter((suite) => kind !== LIBRARY_KIND || !suite.isComponentOnly);
+}
+
 function getMajorVersion(versionRange) {
   const match = String(versionRange || '').match(/(\d+)/);
   return match ? Number(match[1]) : null;
@@ -85,7 +97,7 @@ export function checkComponent(config, doctorConfig = {}) {
   } else {
     addPass('config', 'package.json#kmwc present');
     if (!config.packageJson.kmwc.title) addWarning('config', 'kmwc.title not set (falls back to a title-cased id)', 'set kmwc.title');
-    if (!config.prefix) addWarning('config', 'kmwc.prefix not set — rulebook suites run without a CSS prefix', 'set kmwc.prefix to the prefix reserved in base-variables.md');
+    if (!config.prefix && config.kind !== LIBRARY_KIND) addWarning('config', 'kmwc.prefix not set — rulebook suites run without a CSS prefix', 'set kmwc.prefix to the prefix reserved in base-variables.md');
     if (!config.packageJson.kmwc.ports?.dev) addWarning('config', 'kmwc.ports.dev not set (falls back to 5173)', 'take the port from the devkit components.json');
   }
 
@@ -248,7 +260,12 @@ function checkRulebook(config, { addPass, addWarning, addError }) {
     return;
   }
   const skippedSuites = new Set(config.rulebook.skippedChecks);
-  for (const suite of RULEBOOK_SUITES) {
+  const suites = getRulebookSuites(config.kind);
+  if (suites.length < RULEBOOK_SUITES.length) {
+    const componentOnlySuiteNames = RULEBOOK_SUITES.filter((suite) => !suites.includes(suite)).map((suite) => suite.name);
+    addPass('rulebook', `${config.kind}: component-only suites not run (${componentOnlySuiteNames.join(', ')})`);
+  }
+  for (const suite of suites) {
     if (skippedSuites.has(suite.name)) continue;
     if (!existsSync(join(config.rulebook.path, `${suite.name}.checks.sh`))) continue;
     const suiteResult = runRulebookSuite(config, suite);
@@ -280,7 +297,7 @@ export async function run(args) {
   }
 
   const LEVEL_ICONS = { pass: '✓', warning: '⚠', error: '✗' };
-  console.log(`kmwc doctor — ${config.packageName} (${config.root})\n`);
+  console.log(`kmwc doctor — ${config.packageName}${config.kind === 'component' ? '' : ` [${config.kind}]`} (${config.root})\n`);
   for (const result of results) {
     if (result.level === 'pass' && !args.verbose) continue;
     console.log(`${LEVEL_ICONS[result.level]} [${result.checkName}] ${result.message}${result.fixHint ? `\n    → ${result.fixHint}` : ''}`);

package/src/cli/kmwc.js

@@ -8,59 +8,97 @@
  *   kmwc check-release --tag <tag>    gate a publish (version ⇔ dist-tag, not yet on npm)
  *   kmwc new <name> [options]         scaffold a new component repo next to the devkit
  *   kmwc readme [--check]             regenerate the devkit README catalogue (devkit repo only)
+ *   kmwc <command> --help             that command's usage (never runs it)
  *
  * All commands act on the current directory (override with --root <dir>).
- * Each command module exports `run(args)` returning the process exit code.
+ * Each command module exports `run(args)` returning the process exit code; an
+ * unknown option is an error (exit 2), never ignored.
  */
 import { argv, exit } from 'node:process';
-import { parseArgs } from './args.js';
+import { parseArgs, checkIsHelpRequested } from './args.js';
 
-const COMMAND_LOADERS = {
-  sync: () => import('./commands/sync.js'),
-  doctor: () => import('./commands/doctor.js'),
-  'check-vars': () => import('./commands/check-vars.js'),
-  'check-release': () => import('./commands/check-release.js'),
-  new: () => import('./commands/new.js'),
-  readme: () => import('./commands/readme.js'),
-};
-
-function renderUsage() {
-  console.log(`kmwc — Keenmate web-components devkit
-
-Usage: kmwc <command> [options]
-
-  sync [--check]            Regenerate Dockerfile, nginx.conf, Makefile, .dockerignore,
+/** Every command: its module, the flags it takes and its usage text. */
+const COMMANDS = {
+  sync: {
+    load: () => import('./commands/sync.js'),
+    flags: { booleans: ['check'] },
+    usage: `sync [--check]            Regenerate Dockerfile, nginx.conf, Makefile, .dockerignore,
                             the CLAUDE.md devkit block, .gitignore entries and missing
-                            standard scripts. --check: report drift, write nothing.
-  doctor [--json]           Check this repo against the devkit standard and the
+                            standard scripts. --check: report drift, write nothing.`,
+  },
+  doctor: {
+    load: () => import('./commands/doctor.js'),
+    flags: { booleans: ['json', 'verbose', 'no-rulebook', 'no-pack'] },
+    usage: `doctor [--json]           Check this repo against the devkit standard and the
                             BlissFramework rulebook (*.checks.sh), and that npm pack ships no
-                            dev-only files. --verbose, --no-rulebook, --no-pack.
-  check-vars [--strict]     Validate component-variables.manifest.json against the CSS.
-  check-release --tag <t>   Gate a publish: latest ⇔ release version, rc ⇔ -rcN,
-                            version not on npm yet. --offline skips the npm lookup.
-  new <name>                Scaffold a new component (e.g. \`kmwc new web-colorpicker --prefix cpk\`).
-                            --title "…" --tag … --prefix … --dir … --port … --register
+                            dev-only files. --verbose, --no-rulebook, --no-pack.`,
+  },
+  'check-vars': {
+    load: () => import('./commands/check-vars.js'),
+    flags: { booleans: ['strict'] },
+    usage: `check-vars [--strict]     Validate component-variables.manifest.json against the CSS.`,
+  },
+  'check-release': {
+    load: () => import('./commands/check-release.js'),
+    flags: { booleans: ['offline'], values: ['tag'] },
+    usage: `check-release --tag <t>   Gate a publish: latest ⇔ release version, rc ⇔ -rcN,
+                            version not on npm yet. --offline skips the npm lookup.`,
+  },
+  new: {
+    load: () => import('./commands/new.js'),
+    flags: { booleans: ['register', 'minimal', 'adopt', 'offline'], values: ['title', 'tagline', 'tag', 'prefix', 'dir', 'port'] },
+    usage: `new <name>                Scaffold a new component (e.g. \`kmwc new web-colorpicker --prefix cpk\`).
+                            --title "…" --tagline "…" --tag … --prefix … --dir … --port …
+                            --register --offline
                             --minimal: empty skeleton (no inputs/events) instead of the sample
-                            --adopt: an already registered component (migration scratch scaffold)
-  readme [--check]          Regenerate the README catalogue from components.json (devkit repo).
+                            --adopt: an already registered component (migration scratch scaffold)`,
+  },
+  readme: {
+    load: () => import('./commands/readme.js'),
+    flags: { booleans: ['check'] },
+    usage: `readme [--check]          Regenerate the README catalogue from components.json (devkit repo).`,
+  },
+};
+
+const GLOBAL_USAGE = `Global: --root <dir>        Act on <dir> instead of the current directory.
+        --help, -h          Show the usage (of one command: kmwc <command> --help).`;
 
-Global: --root <dir>        Act on <dir> instead of the current directory.`);
+function renderUsage(commandName) {
+  if (commandName) {
+    console.log(`Usage: kmwc ${COMMANDS[commandName].usage}\n\n${GLOBAL_USAGE}`);
+    return;
+  }
+  const commandLines = Object.values(COMMANDS).map((command) => `  ${command.usage}`).join('\n');
+  console.log(`kmwc — Keenmate web-components devkit\n\nUsage: kmwc <command> [options]\n\n${commandLines}\n\n${GLOBAL_USAGE}`);
 }
 
 async function main() {
   const [commandName, ...commandArgs] = argv.slice(2);
   if (!commandName || ['help', '--help', '-h'].includes(commandName)) {
-    renderUsage();
+    renderUsage(COMMANDS[commandArgs[0]] ? commandArgs[0] : undefined);
     return 0;
   }
-  const loadCommand = COMMAND_LOADERS[commandName];
-  if (!loadCommand) {
+  const command = COMMANDS[commandName];
+  if (!command) {
     console.error(`kmwc: unknown command "${commandName}"\n`);
     renderUsage();
     return 2;
   }
-  const command = await loadCommand();
-  return (await command.run(parseArgs(commandArgs))) ?? 0;
+  // Help never runs the command (`kmwc sync --help` once overwrote a Makefile).
+  if (checkIsHelpRequested(commandArgs)) {
+    renderUsage(commandName);
+    return 0;
+  }
+  let args;
+  try {
+    args = parseArgs(commandArgs, command.flags);
+  } catch (error) {
+    console.error(`kmwc ${commandName}: ${error.message}\n`);
+    renderUsage(commandName);
+    return 2;
+  }
+  const commandModule = await command.load();
+  return (await commandModule.run(args)) ?? 0;
 }
 
 main().then(

package/src/cli/sync-plan.js

@@ -69,14 +69,14 @@ const hasAnyFile = (root, fileNames) => fileNames.some((fileName) => existsSync(
 export function getStandardScripts(config) {
   const scripts = {
     dev: 'vite',
-    build: 'vite build',
+    ...(config.library.shouldBuild ? { build: 'vite build' } : {}),
     'build:examples': 'vite build --mode examples',
     'preview:examples': 'vite preview --mode examples',
     'clean:dist': generateRemoveCommand(['dist']),
     clean: generateRemoveCommand(['dist', config.examples.outDir]),
     doctor: 'kmwc doctor',
   };
-  if (existsSync(join(config.root, config.cssVariables.manifest))) scripts['check:vars'] = 'kmwc check-vars';
+  if (config.cssVariables.isEnabled && existsSync(join(config.root, config.cssVariables.manifest))) scripts['check:vars'] = 'kmwc check-vars';
   if (existsSync(join(config.root, CEM_CONFIG_FILE))) scripts.analyze = 'cem analyze';
   if (hasAnyFile(config.root, PLAYWRIGHT_CONFIG_FILES)) {
     Object.assign(scripts, {

package/src/config.d.ts

@@ -10,7 +10,12 @@ export interface KmwcPackageConfig {
   tag?: string;
   /** Reserved CSS prefix (base-variables.md "Existing prefixes"), e.g. `ms`. */
   prefix?: string;
-  library?: {
+  /** Registry kind; defaults to the components.json entry's kind (else `component`). A `library` runs only the doctor checks that apply to it. */
+  kind?: 'component' | 'library' | 'showcase' | 'docs' | 'test';
+  /** The library build (`vite build`). `false` = the repo builds its package itself or ships none: plain `vite build` refuses to run, only `--mode examples` builds. */
+  library?: false | {
+    /** `false` = same as `library: false`, keeping `entry` for the example pages. */
+    shouldBuild?: boolean;
     entry?: string;
     /** UMD global name. */
     globalName?: string;
@@ -51,14 +56,15 @@ export interface KmwcPackageConfig {
     packageJsonPaths?: string[];
     installCommand?: string;
   };
-  cssVariables?: {
+  /** `false` (or `checkMode: 'off'`): no variables manifest check — sync adds no `check:vars`, `kmwc check-vars` skips. */
+  cssVariables?: false | {
     manifest?: string;
     /** Directories (stylesheets scanned) or explicit files (any type, e.g. a built bundle). */
     sources?: string[];
     /** Prefixed names (without `--`) that are runtime internals, not theming knobs. */
     internalVariables?: string[];
     /** `declared`: manifest ⇔ `--x:` declarations; `consumed`: manifest ⇔ `var(--x)` reads. */
-    checkMode?: 'declared' | 'consumed';
+    checkMode?: 'declared' | 'consumed' | 'off';
   };
   rulebook?: {
     /** Path to BlissFramework `guidelines/web-components` (env KMWC_RULEBOOK_PATH wins). */
@@ -75,6 +81,7 @@ export interface KmwcConfig {
   packageJson: Record<string, any>;
   id: string;
   packageName: string;
+  kind: string;
   version: string;
   title: string;
   tagline: string;
@@ -85,6 +92,7 @@ export interface KmwcConfig {
   author: string;
   license: string;
   library: {
+    shouldBuild: boolean;
     entry: string;
     globalName: string;
     fileName: string;
@@ -118,7 +126,8 @@ export interface KmwcConfig {
     manifest: string;
     sources: string[];
     internalVariables: string[];
-    checkMode: 'declared' | 'consumed';
+    checkMode: 'declared' | 'consumed' | 'off';
+    isEnabled: boolean;
   };
   rulebook: { path: string; skippedChecks: string[] };
   sync: { skippedFiles: string[] };
@@ -137,6 +146,7 @@ export const PORT_RANGES: Array<{ kinds: string[]; firstBlock: number; lastBlock
 export const PREVIEW_PORT_OFFSET: number;
 export const IMAGE_PORT_OFFSET: number;
 export function getPortsForBlock(portBlock: number): { dev: number; preview: number; image: number };
+export function getRegistryKind(id: string, registry?: { components: Array<{ id: string; kind: string }> }): string;
 export function getPortRange(kind: string): { kinds: string[]; firstBlock: number; lastBlock: number };
 export function getNextPortBlock(registry?: { components: Array<Record<string, any>> }, kind?: string): number;
 export function getPeerModule(root: string, moduleId: string): any;

package/src/config.js

@@ -139,6 +139,11 @@ export function getRegistry() {
   return getJsonFile(join(DEVKIT_ROOT, 'components.json'));
 }
 
+/** The registry kind of `id` (`component`, `library` …); `component` when it isn't registered. */
+export function getRegistryKind(id, registry = getRegistry()) {
+  return registry.components.find((entry) => entry.id === id)?.kind || 'component';
+}
+
 /** Strip the npm scope: `@keenmate/web-multiselect` → `web-multiselect`. */
 export function getUnscopedName(packageName) {
   return String(packageName || '').replace(/^@[^/]+\//, '');
@@ -182,13 +187,16 @@ export function getKmwcConfig(root = process.cwd()) {
 export function mapKmwcConfig(packageJson, root = process.cwd()) {
   const packageConfig = packageJson.kmwc || {};
   const id = packageConfig.id || getUnscopedName(packageJson.name) || 'component';
-  const library = packageConfig.library || {};
+  // `library: false` — the repo builds its package itself (tsc …) or ships none;
+  // Vite serves and builds only the examples site.
+  const library = packageConfig.library === false ? { shouldBuild: false } : packageConfig.library || {};
   const examples = packageConfig.examples || {};
   const ports = packageConfig.ports || {};
   const image = packageConfig.image || {};
   const theme = packageConfig.theme || {};
   const analytics = packageConfig.analytics || {};
-  const cssVariables = packageConfig.cssVariables || {};
+  // `cssVariables: false` — no variables manifest to check (no check:vars script).
+  const cssVariables = packageConfig.cssVariables === false ? { checkMode: 'off' } : packageConfig.cssVariables || {};
   const rulebook = packageConfig.rulebook || {};
   const devPort = ports.dev ?? 5173;
 
@@ -198,6 +206,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
     packageJson,
     id,
     packageName: packageJson.name || id,
+    kind: packageConfig.kind || getRegistryKind(id),
     version: packageJson.version || '0.1.0',
     title: packageConfig.title || mapToTitleCase(id),
     tagline: packageConfig.tagline || packageJson.description || '',
@@ -208,6 +217,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
     author: typeof packageJson.author === 'string' ? packageJson.author : packageJson.author?.name || 'Keenmate s.r.o.',
     license: packageJson.license || 'MIT',
     library: {
+      shouldBuild: library.shouldBuild ?? true,
       entry: library.entry || 'src/index.ts',
       globalName: library.globalName || mapToPascalCase(id),
       fileName: library.fileName || id,
@@ -254,6 +264,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
       sources: cssVariables.sources || ['src/css'],
       internalVariables: cssVariables.internalVariables || [],
       checkMode: cssVariables.checkMode || 'declared',
+      isEnabled: cssVariables.checkMode !== 'off',
     },
     rulebook: {
       path:

package/src/examples/css/content.css

@@ -120,6 +120,9 @@
         font-size: 0.9em;
         color: var(--kmwc-accent-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. */
+        overflow-wrap: anywhere;
     }
 
     pre code,
@@ -130,6 +133,32 @@
         border-radius: 0;
         color: inherit;
         font-size: inherit;
+        overflow-wrap: inherit;
+    }
+
+    /* A key in a keyboard map — the spotlight's key-hint look. */
+    kbd {
+        display: inline-block;
+        padding: 0.1rem 0.35rem;
+        background-color: var(--kmwc-elevated-bg);
+        color: var(--kmwc-text-color-1);
+        border: 1px solid var(--kmwc-border-color);
+        border-bottom-width: 2px;
+        border-radius: var(--kmwc-radius-sm);
+        font-family: var(--kmwc-font-family);
+        font-weight: 600;
+        font-size: 0.8em;
+        line-height: 1.2;
+        white-space: nowrap;
+    }
+
+    /* A search match — the spotlight's match highlight. */
+    mark {
+        background-color: var(--kmwc-accent-light-bg-hover);
+        color: var(--kmwc-accent-color);
+        font-weight: 600;
+        padding: 0 2px;
+        border-radius: var(--kmwc-radius-sm);
     }
 
     /* ==========================================================================
@@ -228,6 +257,18 @@
         margin-top: 1rem;
     }
 
+    /* Push an item to the end of a flex row (`.controls`, `.btn-group` …). */
+    .push-end {
+        margin-inline-start: auto;
+    }
+
+    /* Field widths: a native field is ~20 characters wide; these size a short
+       one (a page size, a caption) without an inline style. */
+    .w-xs { width: 4rem; max-width: 100%; }
+    .w-sm { width: 6rem; max-width: 100%; }
+    .w-md { width: 9rem; max-width: 100%; }
+    .w-lg { width: 12rem; max-width: 100%; }
+
     @media (max-width: 768px) {
         .grid,
         .grid-2,

package/src/examples/css/form-controls.css

@@ -74,7 +74,11 @@
         cursor: not-allowed;
     }
 
+    /* A number is short: 7rem holds six digits and the spin buttons (a
+       .form-group still stretches it to the row; .w-* sizes it). */
     :where(input[type="number"]):not(:where(.kmwc-native, .kmwc-native *)) {
+        width: 7rem;
+        max-width: 100%;
         padding-inline-end: 0.25rem;  /* room for the spin buttons */
     }
 

package/src/examples/css/widgets.css

@@ -29,7 +29,8 @@
         --kmwc-log-info-color: var(--kmwc-info-color);
         --kmwc-log-warn-color: var(--kmwc-warning-color);
         --kmwc-log-err-color: var(--kmwc-danger-color);
-        --kmwc-log-muted-color: var(--kmwc-text-color-3);
+        /* text-color-3 is 2.8:1 on the light panel — under WCAG AA's 4.5. */
+        --kmwc-log-muted-color: var(--kmwc-text-color-2);
         --kmwc-log-name-color: var(--kmwc-accent-color);
         --kmwc-log-rule-color: var(--kmwc-border-color);
         font-family: var(--kmwc-mono-font-family);
@@ -94,7 +95,9 @@
     }
 
     /* Timeline: a line with cells is a row; the cells keep their width and the
-       detail after them wraps in its own column. */
+       detail after them wraps in its own column. When the cells leave the detail
+       less than ~14rem (a phone, a long source name) it drops under them at full
+       width instead of being squeezed to a letter per line. */
     .log-line:has(> :is(.log-line__seq, .log-line__time, .log-line__source, .log-line__name)),
     .event-entry:has(> :is(.event-time, .event-name)) {
         display: flex;
@@ -103,8 +106,12 @@
         border-bottom: 1px solid var(--kmwc-log-rule-color);
     }
 
+    .log-line:has(> :is(.log-line__seq, .log-line__time, .log-line__source, .log-line__name)) {
+        flex-wrap: wrap;
+    }
+
     .log-line:has(> :is(.log-line__seq, .log-line__time, .log-line__source, .log-line__name)) > :last-child:not(.log-line__name) {
-        flex: 1 1 0;
+        flex: 1 1 14rem;
         min-width: 0;
     }
 
@@ -115,6 +122,7 @@
     .event-time,
     .event-name {
         flex: none;
+        max-width: 100%;
     }
 
     .log-line__seq,
@@ -179,7 +187,7 @@
         display: flex;
         flex-wrap: wrap;
         gap: 0.4rem;
-        margin: 0.25rem 0 1rem;
+        margin: 0.75rem 0 1rem;  /* it follows the demo it measures */
     }
 
     .css-readout code { font-size: 0.78rem; }

package/src/vite/index.js

@@ -199,9 +199,16 @@ export function defineComponentConfig(presetConfig = {}) {
     const config = getKmwcConfig(presetConfig.root);
     // The component's own vite — the one running this config (see loadPeerModule).
     const { mergeConfig, searchForWorkspaceRoot } = await loadPeerModule(config.root, 'vite');
-    const library = { ...config.library, ...(presetConfig.library || {}) };
+    const library = { ...config.library, ...(presetConfig.library === false ? { shouldBuild: false } : presetConfig.library || {}) };
     const isExamplesMode = env.mode === EXAMPLES_MODE;
     const isLibraryBuild = env.command === 'build' && !isExamplesMode;
+    if (isLibraryBuild && !library.shouldBuild) {
+      // The library build empties dist/ — it would wipe a package the repo builds itself.
+      throw new Error(
+        `${config.id}: kmwc.library is false — plain \`vite build\` has nothing to build. ` +
+          'Build the package with its own script (npm run build), the examples site with `vite build --mode examples`.'
+      );
+    }
 
     const plugins = [createExamplesPlugin({ root: config.root }), ...(presetConfig.plugins || [])];
 

package/templates/claude-block.md

@@ -27,6 +27,8 @@ locally — every local fork is how they drifted apart.
   `.table-compact`, …) — don't restyle them per page; `kmwc-native` opts an
   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.
   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