bitboss-ui 3.0.0-beta.33 → 3.0.0-beta.35

package/README.md

@@ -440,6 +440,27 @@ entry is the state itself and is never reported:
 />
 ```
 
+#### Rating star colours: `no-star-color`
+
+`bitboss-ui/no-star-color` flags any colour utility in `BbRating`'s `pt:item`,
+in the base entry or any state: `text-*`, `fill-*` and `stroke-*`, whether a
+shade (`text-amber-500`), a keyword (`fill-current`), a variable
+(`text-(--bb-text-faint)`) or an arbitrary colour (`text-[#f59e0b]`). Sizes and
+widths (`text-sm`, `stroke-2`) are never reported. The rating paints each
+star's colour per state (filled, the hover preview, the error tint), and a
+colour utility beats those rules, so it looks right at rest and freezes the
+stars. The fix lives on another attribute, so the rule explains it rather
+than rewriting:
+
+```vue
+<!-- errors: no hover preview, no error tint -->
+<BbRating pt:item="text-(--bb-text-faint)" pt:item:selected="text-amber-500" />
+<!-- same look, the preview and the states keep working -->
+<BbRating
+	pt:root="[--empty:var(--bb-text-faint)] [--accent:var(--color-amber-500)]"
+/>
+```
+
 #### The one rule that reads CSS: `no-unknown-token`
 
 `bitboss-ui/no-unknown-token` flags a bare `var(--bb-…)` naming a token the

package/bin/bitboss-ui.mjs

@@ -46,9 +46,13 @@
  */
 
 import { spawnSync } from 'node:child_process';
+// `globSync` is read off the namespace, not imported by name: it only exists
+// from Node 22, and a named import of a missing builtin export is a
+// SyntaxError at load time, which killed every command on Node 20 (Sail
+// images still ship it). Only quoted glob arguments need it (Q46.4).
+import * as fs from 'node:fs';
 import {
 	existsSync,
-	globSync,
 	mkdirSync,
 	readdirSync,
 	readFileSync,
@@ -59,6 +63,11 @@ import {
 	findHandRollHints,
 	loadKnownTokens,
 } from '../scripts/lib/hand-roll-hints.mjs';
+import {
+	disabledChecker,
+	ruleForFinding,
+} from '../scripts/lib/eslint-disable.mjs';
+import { applyBitbossFixes } from '../scripts/lib/check-fix.mjs';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
@@ -437,7 +446,13 @@ function resolveCheckFiles(cwd, patterns) {
 				continue;
 			}
 		}
-		const dirents = globSync(pattern, {
+		if (typeof fs.globSync !== 'function') {
+			console.error(
+				`[bitboss-ui] quoted glob patterns need Node >= 22 (this is ${process.version}): "${pattern}". Pass the directory, or leave the pattern unquoted so the shell expands it.`
+			);
+			process.exit(1);
+		}
+		const dirents = fs.globSync(pattern, {
 			cwd,
 			withFileTypes: true,
 			// Pruning is a traversal shortcut; the inSkippedDir filter below is
@@ -710,9 +725,15 @@ function manifestVersionOf(manifestPath) {
 	}
 }
 
-function checkCommand(
+async function checkCommand(
 	globs,
-	{ json: jsonMode, allowEmpty, allowComponents, manifest: manifestOverride }
+	{
+		json: jsonMode,
+		allowEmpty,
+		allowComponents,
+		manifest: manifestOverride,
+		fix,
+	}
 ) {
 	const projectRoot = process.cwd();
 
@@ -770,9 +791,40 @@ function checkCommand(
 		...configuredAllowComponents(projectRoot),
 		...allowComponents,
 	];
+
+	// Q46.8: `--fix` applies the ESLint plugin's fixes (the registered v2→v3
+	// migrations) with ONLY the bitboss rules, then the check below reports
+	// what is left, so one command migrates and verifies.
+	if (fix) {
+		const outcome = await applyBitbossFixes({
+			projectRoot,
+			files,
+			manifestPath: manifestOverride ? manifestPath : undefined,
+			allowComponents: allowedComponents,
+		});
+		if ('error' in outcome) {
+			console.error(`[bitboss-ui] ${outcome.error}`);
+			process.exit(1);
+		}
+		const log = jsonMode ? console.error : console.log;
+		log(
+			outcome.fixed.length
+				? `[bitboss-ui] check --fix: fixed ${outcome.fixed.length} file(s):\n${outcome.fixed
+						.map((file) => `  ${relative(projectRoot, file)}`)
+						.join('\n')}`
+				: '[bitboss-ui] check --fix: nothing to fix.'
+		);
+		if (outcome.skipped?.length)
+			log(
+				`[bitboss-ui] check --fix: ESLint ignored ${outcome.skipped.length} file(s), not fixed:\n${outcome.skipped
+					.map((file) => `  ${relative(projectRoot, file)}`)
+					.join('\n')}`
+			);
+	}
 	const validateOptions = { allowComponents: allowedComponents };
 
 	const findings = [];
+	let suppressed = 0;
 	/*
 	 * Advisory only — see scripts/lib/hand-roll-hints.mjs. Hints never touch the
 	 * exit code, so a guess can never fail a consumer's build. `--no-hints`
@@ -786,7 +838,18 @@ function checkCommand(
 		const { findings: fileFindings } = file.endsWith('.md')
 			? validateMarkdown(content, manifest, validateOptions)
 			: validateVueSnippet(content, manifest, validateOptions);
+		// Q46.9: a finding the author silenced for ESLint (`eslint-disable*`,
+		// usually with a reason) is silenced here too, or `check` cannot gate
+		// CI next to a lint step that passes. `.md` lines are fence-relative,
+		// and docs carry no directives, so only `.vue` files are filtered.
+		const isDisabled = file.endsWith('.vue')
+			? disabledChecker(content)
+			: () => false;
 		for (const finding of fileFindings) {
+			if (isDisabled(finding.line, ruleForFinding(finding))) {
+				suppressed++;
+				continue;
+			}
 			findings.push({ file: relPath, ...finding });
 		}
 		// .md files are documentation ABOUT components; a round <img> in a doc
@@ -798,6 +861,14 @@ function checkCommand(
 		}
 	}
 
+	/** One line, so a silenced finding is never invisible. */
+	const printSuppressed = () => {
+		if (suppressed === 0) return;
+		console.log(
+			`[bitboss-ui] ${suppressed} finding(s) silenced by eslint-disable comments.`
+		);
+	};
+
 	/** Advisory block, printed on success and on failure alike. Never fatal. */
 	const printHints = () => {
 		if (hints.length === 0) return;
@@ -837,6 +908,7 @@ function checkCommand(
 				{
 					findings,
 					hints,
+					suppressed,
 					files: files.length,
 					manifestVersion: judgedAgainst,
 					installedVersion: packageVersion(),
@@ -874,10 +946,12 @@ function checkCommand(
 		console.log(
 			`[bitboss-ui] check OK — ${summarizeFileCounts(files)} file(s), zero unknown Bb* props/v-models/slots/nav-attrs.`
 		);
+		printSuppressed();
 		printHints();
 		return;
 	}
 
+	printSuppressed();
 	const fileCount = new Set(findings.map((f) => f.file)).size;
 	console.error(
 		`[bitboss-ui] check FAILED — ${findings.length} finding(s) across ${fileCount} file(s):`
@@ -932,7 +1006,7 @@ Commands:
                       \`--no-mcp\` skips the server and the install. Idempotent —
                       safe to re-run after upgrades.
   check [glob…] [--json] [--allow-empty] [--allow-component <Name>]
-                      [--no-hints] [--manifest <path>]
+                      [--no-hints] [--manifest <path>] [--fix]
                       Validate \`Bb*\` markup in .vue/.md files against the
                       installed components.json manifest (unknown/removed props,
                       bad v-models, unknown \`<template #slot>\` names,
@@ -945,6 +1019,18 @@ Commands:
                       nothing (a typo'd CI path validates zero files silently) —
                       pass \`--allow-empty\` when an empty match is expected.
 
+                      \`--fix\` first applies the ESLint plugin's fixes (the
+                      registered v2→v3 renames, polarity flips and value
+                      remaps) to the matched .vue files with ONLY the
+                      bitboss-ui rules — your own ESLint config is not used —
+                      then reports what is left. Needs \`eslint\` and
+                      \`vue-eslint-parser\` in the project.
+
+                      Honours ESLint disable comments in .vue files: a finding
+                      silenced for the matching \`bitboss-ui/*\` rule (or by a
+                      bare \`eslint-disable\`) is not reported, only counted:
+                        <!-- eslint-disable-next-line bitboss-ui/require-table-slot-prop -- why -->
+
                       \`--manifest <path>\` judges against another version's
                       components.json instead of the installed one — the answer
                       to "which of my files break if I upgrade", BEFORE you
@@ -1034,6 +1120,7 @@ switch (command) {
 				json: { type: 'boolean' },
 				'allow-empty': { type: 'boolean' },
 				'allow-component': { type: 'string', multiple: true },
+				fix: { type: 'boolean' },
 				manifest: { type: 'string' },
 				// Accepted and ignored here — read straight off argv inside
 				// checkCommand, but parseArgs is strict, so it must be declared.
@@ -1041,7 +1128,8 @@ switch (command) {
 			},
 			{ allowPositionals: true }
 		);
-		checkCommand(positionals, {
+		await checkCommand(positionals, {
+			fix: values.fix ?? false,
 			json: values.json ?? false,
 			allowEmpty: values['allow-empty'] ?? false,
 			allowComponents: values['allow-component'] ?? [],

package/dist/ai/BbAccordion.md

@@ -63,14 +63,14 @@ through `pt:panel` or `.bb-accordion__panel` — collapses with the body.
 			v-model="faq.open"
 			:class="index ? 'border-t border-(--bb-border)' : ''"
 		>
-			<template #header="{ value }">
+			<template #header="{ open }">
 				<div
 					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium"
 				>
 					<span>{{ faq.question }}</span>
 					<span
 						class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
-						:class="value ? 'rotate-180' : ''"
+						:class="open ? 'rotate-180' : ''"
 					>
 						<BbIcon icon="lucide:chevron-down" size="sm" />
 					</span>
@@ -137,7 +137,7 @@ on the row, badge included, toggles the panel.
 			v-model="endpoint.open"
 			:class="index ? 'border-t border-(--bb-border)' : ''"
 		>
-			<template #header="{ value }">
+			<template #header="{ open }">
 				<div class="flex w-full items-center gap-2 px-3 py-2 text-left">
 					<BbBadge size="xs" :variant="METHOD_VARIANT[endpoint.method]">{{
 						endpoint.method
@@ -145,7 +145,7 @@ on the row, badge included, toggles the panel.
 					<code class="truncate font-mono text-xs">{{ endpoint.path }}</code>
 					<span
 						class="ml-auto shrink-0 text-(--bb-text-muted) transition-transform duration-200"
-						:class="value ? 'rotate-180' : ''"
+						:class="open ? 'rotate-180' : ''"
 					>
 						<BbIcon icon="lucide:chevron-down" size="sm" />
 					</span>
@@ -247,9 +247,9 @@ const endpoints = ref<Endpoint[]>([
 .bb-badge.bb-badge--soft-red {
 	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
 	--fg: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
-	--border-width: 1px;
+	--bw: 1px;
 	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
-	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+	--ring-color: color-mix(in oklab, var(--accent) 45%, transparent);
 }
 </style>
 ```
@@ -257,9 +257,9 @@ const endpoints = ref<Endpoint[]>([
 ### Slot scope: the open flag and the toggle handle
 
 Both slots — `header` and the default (body) slot — receive the same scope,
-`{ value, toggle }`:
+`{ open, toggle }`:
 
-- `value` mirrors the open state (one-way — assigning to it does nothing). Use
+- `open` mirrors the open state (one-way — assigning to it does nothing). Use
   it to spin a chevron or swap header copy.
 - `toggle()` flips the panel. In the header it is redundant (the button already
   toggles); its real use is in the **body**, for a "Show less" affordance that
@@ -274,14 +274,14 @@ Both slots — `header` and the default (body) slot — receive the same scope,
 		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbAccordion v-model="notes">
-			<template #header="{ value }">
+			<template #header="{ open }">
 				<div
 					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium"
 				>
 					<span>Release notes</span>
 					<span
 						class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
-						:class="value ? 'rotate-180' : ''"
+						:class="open ? 'rotate-180' : ''"
 					>
 						<BbIcon icon="lucide:chevron-down" size="sm" />
 					</span>
@@ -334,7 +334,7 @@ to `null`). Prefer a stable key over an index when the list can reorder.
 			:model-value="openIndex === index"
 			@update:model-value="openIndex = $event ? index : null"
 		>
-			<template #header="{ value }">
+			<template #header="{ open }">
 				<div
 					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm"
 				>
@@ -343,7 +343,7 @@ to `null`). Prefer a stable key over an index when the list can reorder.
 						{{ plan.price }}
 						<span
 							class="shrink-0 transition-transform duration-200"
-							:class="value ? 'rotate-180' : ''"
+							:class="open ? 'rotate-180' : ''"
 						>
 							<BbIcon icon="lucide:chevron-down" size="sm" />
 						</span>
@@ -403,14 +403,14 @@ padding on the nested body content.
 		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbAccordion v-model="notifications">
-			<template #header="{ value }">
+			<template #header="{ open }">
 				<div
 					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium"
 				>
 					<span>Notifications</span>
 					<span
 						class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
-						:class="value ? 'rotate-180' : ''"
+						:class="open ? 'rotate-180' : ''"
 					>
 						<BbIcon icon="lucide:chevron-down" size="sm" />
 					</span>
@@ -420,14 +420,14 @@ padding on the nested body content.
 				<BbCheckbox v-model="mentions" label="Mentions" />
 				<BbCheckbox v-model="digests" label="Weekly digest" />
 				<BbAccordion v-model="advanced">
-					<template #header="{ value }">
+					<template #header="{ open }">
 						<div
 							class="flex w-full items-center justify-between gap-2 py-1 text-left text-sm text-(--bb-text-muted)"
 						>
 							<span>Advanced</span>
 							<span
 								class="shrink-0 transition-transform duration-200"
-								:class="value ? 'rotate-180' : ''"
+								:class="open ? 'rotate-180' : ''"
 							>
 								<BbIcon icon="lucide:chevron-down" size="sm" />
 							</span>
@@ -519,11 +519,11 @@ collapses with the body.
 			pt:panel="text-sm"
 			:pt:root="index ? 'border-t border-(--bb-border)' : ''"
 		>
-			<template #header="{ value }">
+			<template #header="{ open }">
 				<span>{{ faq.question }}</span>
 				<span
 					class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
-					:class="value ? 'rotate-180' : ''"
+					:class="open ? 'rotate-180' : ''"
 				>
 					<BbIcon icon="lucide:chevron-down" size="sm" />
 				</span>
@@ -575,7 +575,7 @@ grammar, the merge rules and the global map are in the
 
 ### Works well with
 
-- `BbIcon` — a rotating chevron in the header, driven by the slot's `value` (see
+- `BbIcon` — a rotating chevron in the header, driven by the slot's `open` (see
   the FAQ example).
 - `BbBadge` — counts or soft method/status pills in the header (see the API
   reference example); non-interactive content stays click-transparent.

package/dist/ai/BbBadge.md

@@ -183,9 +183,9 @@ const invoices: InvoiceRow[] = [
 .bb-badge.bb-badge--soft-red {
 	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
 	--fg: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
-	--border-width: 1px;
+	--bw: 1px;
 	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
-	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+	--ring-color: color-mix(in oklab, var(--accent) 45%, transparent);
 }
 </style>
 ```
@@ -779,10 +779,10 @@ const endpoints: Endpoint[] = [
 .bb-badge.bb-badge--soft-green,
 .bb-badge.bb-badge--soft-red {
 	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
-	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
-	--border-width: 1px;
+	--fg: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+	--bw: 1px;
 	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
-	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+	--ring-color: color-mix(in oklab, var(--accent) 45%, transparent);
 }
 </style>
 ```
@@ -888,20 +888,21 @@ Set these on the element, or on a class you put on it, to retune this component
 | --- | --- | --- | --- |
 | `--bg` | `.bb-badge` | `var(--bb-primary)` | pill fill |
 | `--fg` | `.bb-badge` | `var(--bb-primary-fg)` | label, icons and the clear glyph |
-| `--border-width` | `.bb-badge` | `0px` | Pill border. The `border` shorthand is always present, so the width is what turns it on — the filled variants leave it at 0 and the bordered ones (secondary/destructive/outline) step up to `--bb-border-w-sm`. Nothing compensates for it: the… |
+| `--bw` | `.bb-badge` | `0px` | Pill border. The `border` shorthand is always present, so the width is what turns it on — the filled variants leave it at 0 and the bordered ones (secondary/destructive/outline) step up to `--bb-border-w-sm`. Nothing compensates for it: the… |
 | `--border-color` | `.bb-badge` | `transparent` |  |
-| `--ring` | `.bb-badge` | `var(--bb-primary-ring)` | focus ring, per variant |
+| `--ring-color` | `.bb-badge` | `var(--bb-primary-ring)` | focus ring colour, per variant |
+| `--ring-size` | `.bb-badge` | `var(--bb-ring-size)` | focus ring width |
 | `--min-size-md` | `.bb-badge` | `calc(var(--bb-control-h) - 16px)` | 16px at the default |
 | `--min-size` | `.bb-badge` | `var(--min-size-md)` | pill min height and min width |
 | `--elev` | `.bb-badge` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
 | `--r` | `.bb-badge` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
-| `--font-size` | `.bb-badge` | `calc(var(--bb-fs) - 4px)` | Label. Sizes are offsets from the density masters (--bb-fs, --bb-control-h), like BbButton's, so a denser theme scales the pill. |
+| `--fs` | `.bb-badge` | `calc(var(--bb-fs) - 4px)` | Label. Sizes are offsets from the density masters (--bb-fs, --bb-control-h), like BbButton's, so a denser theme scales the pill. |
 | `--icon-size` | `.bb-badge` | `12px` | leading/append icons (passed to BbIcon as --size) |
 | `--gap` | `.bb-badge` | `3px` | space between label, icons and the trailing side |
-| `--padding-inline` | `.bb-badge` | `6px` | base side padding; the modifiers below scale it per side |
+| `--px` | `.bb-badge` | `6px` | base side padding; the modifiers below scale it per side |
 | `--clear-size` | `.bb-badge` | `12px` | clear button's glyph box (the circle painted on hover is 2px smaller) |
-| `--pad-left` | `.bb-badge` | `var(--padding-inline)` | Side-owned padding: the body and trailing wrappers carry the pill's inline padding (and its radius) so their hit areas run flush to the border. The modifiers below retune these vars instead of the pill's own padding. |
-| `--pad-right` | `.bb-badge` | `var(--padding-inline)` |  |
+| `--pad-left` | `.bb-badge` | `var(--px)` | Side-owned padding: the body and trailing wrappers carry the pill's inline padding (and its radius) so their hit areas run flush to the border. The modifiers below retune these vars instead of the pill's own padding. |
+| `--pad-right` | `.bb-badge` | `var(--px)` |  |
 | `--size` | `.bb-badge__icon` | `var(--icon-size)` |  |
 
 ## Component tree

package/dist/ai/BbBadgeButton.md

@@ -84,20 +84,21 @@ Set these on the element, or on a class you put on it, to retune this component
 | --- | --- | --- | --- |
 | `--bg` | `.bb-badge` | `var(--bb-primary)` | pill fill |
 | `--fg` | `.bb-badge` | `var(--bb-primary-fg)` | label, icons and the clear glyph |
-| `--border-width` | `.bb-badge` | `0px` | Pill border. The `border` shorthand is always present, so the width is what turns it on — the filled variants leave it at 0 and the bordered ones (secondary/destructive/outline) step up to `--bb-border-w-sm`. Nothing compensates for it: the… |
+| `--bw` | `.bb-badge` | `0px` | Pill border. The `border` shorthand is always present, so the width is what turns it on — the filled variants leave it at 0 and the bordered ones (secondary/destructive/outline) step up to `--bb-border-w-sm`. Nothing compensates for it: the… |
 | `--border-color` | `.bb-badge` | `transparent` |  |
-| `--ring` | `.bb-badge` | `var(--bb-primary-ring)` | focus ring, per variant |
+| `--ring-color` | `.bb-badge` | `var(--bb-primary-ring)` | focus ring colour, per variant |
+| `--ring-size` | `.bb-badge` | `var(--bb-ring-size)` | focus ring width |
 | `--min-size-md` | `.bb-badge` | `calc(var(--bb-control-h) - 16px)` | 16px at the default |
 | `--min-size` | `.bb-badge` | `var(--min-size-md)` | pill min height and min width |
 | `--elev` | `.bb-badge` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
 | `--r` | `.bb-badge` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
-| `--font-size` | `.bb-badge` | `calc(var(--bb-fs) - 4px)` | Label. Sizes are offsets from the density masters (--bb-fs, --bb-control-h), like BbButton's, so a denser theme scales the pill. |
+| `--fs` | `.bb-badge` | `calc(var(--bb-fs) - 4px)` | Label. Sizes are offsets from the density masters (--bb-fs, --bb-control-h), like BbButton's, so a denser theme scales the pill. |
 | `--icon-size` | `.bb-badge` | `12px` | leading/append icons (passed to BbIcon as --size) |
 | `--gap` | `.bb-badge` | `3px` | space between label, icons and the trailing side |
-| `--padding-inline` | `.bb-badge` | `6px` | base side padding; the modifiers below scale it per side |
+| `--px` | `.bb-badge` | `6px` | base side padding; the modifiers below scale it per side |
 | `--clear-size` | `.bb-badge` | `12px` | clear button's glyph box (the circle painted on hover is 2px smaller) |
-| `--pad-left` | `.bb-badge` | `var(--padding-inline)` | Side-owned padding: the body and trailing wrappers carry the pill's inline padding (and its radius) so their hit areas run flush to the border. The modifiers below retune these vars instead of the pill's own padding. |
-| `--pad-right` | `.bb-badge` | `var(--padding-inline)` |  |
+| `--pad-left` | `.bb-badge` | `var(--px)` | Side-owned padding: the body and trailing wrappers carry the pill's inline padding (and its radius) so their hit areas run flush to the border. The modifiers below retune these vars instead of the pill's own padding. |
+| `--pad-right` | `.bb-badge` | `var(--px)` |  |
 | `--size` | `.bb-badge__icon` | `var(--icon-size)` |  |
 
 ## Component tree

package/dist/ai/BbBreadcrumbs.md

@@ -724,11 +724,11 @@ States are listed in precedence order: when two are on at once and their entries
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
   - `BbDropdown` _(public — [contract](./BbDropdown.md))_ — its own pt parts (`BbDropdown`): `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-dropdown__header`, `list` → `span.bb-dropdown__items-container`, `footer` → `div.bb-dropdown__footer`; documented CSS variables: `--menu-inset`; also mounts `CommonPopover`, `DropdownPipelineResolver`
     - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbBaseButton`, `BbIcon`, `CommonPopover`, `BbDropdownList`
-      - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear-button`; documented CSS variables: `--bg`, `--fg`, `--border-width`, `--ring`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--font-size`, `--icon-size`, `--gap`, `--padding-inline`, `--clear-size`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
+      - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear-button`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
     - `AdaptiveDropdown` _(internal — not importable, reach it through `BbDropdown`)_ — hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', panel: 'root', sheet: 'root' }` (ours → theirs); also mounts `BbSmoothHeight`, `BbDropdownList`
       - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__body`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`
         - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`
-      - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__content`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbBaseButton`, `BbSpinner`
+      - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__content`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbBaseButton`, `BbSpinner`
   - Also mounts `BbIcon`
 
 ## See Also

package/dist/ai/BbButton.md

@@ -109,7 +109,7 @@ restate a state:
 	--bg-hover: color-mix(in oklab, var(--bb-primary) 90%, black);
 	--bg-pressed: color-mix(in oklab, var(--bb-primary) 80%, black);
 	--fg: var(--bb-primary-fg);
-	--ring: var(--bb-ring);
+	--ring-color: var(--bb-ring);
 }
 ```
 
@@ -156,10 +156,10 @@ design and never reads the disabled trio — see _Loading and async actions_.)
 Never use a variant name that is neither built-in nor registered in the
 project's `vite.config.*` / `nuxt.config.*`. Unsure what's currently legal in
 a given project (built-ins plus whatever it has registered)? Don't guess from
-an example — the plugin regenerates
-`node_modules/bitboss-ui/button-variants.d.ts` on every build; that file
-**is** the closed, machine-readable list of every legal `variant` value for
-that project, registrations included (see
+an example: the built-ins are `primary`, `outline`, `secondary`, `ghost`,
+`destructive` and `link`, and the project's own names are the
+`ButtonVariantRegistry` entries in its committed `bitboss-ui.d.ts` (the file
+the plugin writes from `buttonVariants`; see
 [Installation and Plugin Setup](./guides/installation-and-plugin-setup.md) §
 variants).
 
@@ -1183,7 +1183,8 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--bg-pressed` | `var(--bg)` | fill while [aria-pressed='true'] |
 | `--fg` | `initial` | label and icons (icons paint currentColor) |
 | `--border-color` | `transparent` | the frame; its width is --bw |
-| `--ring` | `transparent` | focus ring, drawn --bb-ring-size outside the border |
+| `--ring-color` | `transparent` | focus ring colour, per variant |
+| `--ring-size` | `var(--bb-ring-size)` | focus ring width, outside the border |
 | `--bw` | `var(--bb-border-w)` | border width |
 | `--fg-hover` | `var(--fg)` | label and icons on hover (and focus-visible) |
 | `--border-hover` | `var(--border-color)` | the frame on hover (and focus-visible) |

package/dist/ai/BbCalendar.md

@@ -468,7 +468,7 @@ box carries no role of its own and only the grid inside is announced.
 `pt` reaches a named part with a class list — or, in the object form, a style
 and attributes — optionally only while a state is on. Parts: `root` (the
 calendar's box, where a consumer `class` lands too; it carries the sizing
-tokens, so `pt:root="[--pad-x:2px]"` tightens the padding and the grid width
+tokens, so `pt:root="[--px:2px]"` tightens the padding and the grid width
 follows), `header` (the navigation bar), `arrow` (the previous / next
 buttons), `month` and `year` (the heading buttons), `columnHeader` (each
 weekday letter), `day` (one whole day cell) and `dayButton` (the button
@@ -547,7 +547,7 @@ the page is `BbDatePicker`.
 
 | Part | What it is |
 | --- | --- |
-| `root` | The calendar's box: the grid and, with `type="datetime"`, the time rail beside it. A consumer `class` lands here. It carries the sizing tokens — `pt:root="[--cell:36px]"` widens the whole calendar, `pt:root="[--pad-x:2px]"` tightens its padding — and the grid's width follows. |
+| `root` | The calendar's box: the grid and, with `type="datetime"`, the time rail beside it. A consumer `class` lands here. It carries the sizing tokens — `pt:root="[--cell:36px]"` widens the whole calendar, `pt:root="[--px:2px]"` tightens its padding — and the grid's width follows. |
 | `header` | The navigation bar: the previous / next arrows and the month / year headings. |
 | `arrow` | The previous / next buttons — a broadcast. |
 | `month` | The month heading button; it opens the month panel. |
@@ -593,9 +593,10 @@ Set these on the element, or on a class you put on it, to retune this component
 
 | Property | Set on | Default | What it is |
 | --- | --- | --- | --- |
+| `--bg` | `.bb-calendar__button-menu` | `var(--bb-panel)` |  |
 | `--cell` | `.bb-calendar` | `28px` | Cell size drives all grid math: 224px ÷ 7 = 32px exactly |
-| `--pad-x` | `.bb-calendar` | `6px` |  |
-| `--pad-y` | `.bb-calendar` | `8px` |  |
+| `--px` | `.bb-calendar` | `6px` |  |
+| `--py` | `.bb-calendar` | `8px` |  |
 | `--nav-button-h` | `.bb-calendar` | `24px` |  |
 | `--day-slot-allowance` | `.bb-calendar` | `0px` | Allowance for the day slot append area - needed for the slot to be visible |
 | `--unit-row` | `.bb-calendar` | `calc(var(--cell) * 1.25)` | Row pitch for the coarse grids (month/year), where a "row" is one of four month rows rather than a week. Roomier than --cell because twelve months in a 4×3 grid have space the 6×7 day grid does not. |

package/dist/ai/BbCheckboxGroup.md

@@ -943,7 +943,7 @@ and the global map are in the [passthrough guide](./guides/passthrough.md).
 | --- | --- | --- | --- | --- |
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `description`, `hint`, `icon`, `item`, `itemDescription`, `label`, `legend`, `list`, `message`, `root`. States: `disabled`, `errors`, `hasValue`, `loading`, `readonly`, `warnings`, `checked`, `focused`, `focusVisible`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
-| `compact` | `boolean \| undefined` | `false` |  | Displays the component in a compact version. |
+| `compact` | `boolean \| undefined` | `false` |  | Compact density. Swaps `--bb-label-spacing-y` for `--bb-label-spacing-y-compact`, so tune a compact group's label gap with the `-compact` token, not the base one. |
 | `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
 | `depsDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to dependencies. |
 | `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |

package/dist/ai/BbColorInput.md

@@ -671,7 +671,7 @@ of it. The full grammar, the merge rules and the global map are in the
 | `autocomplete` | `string \| undefined` | `"off"` |  | Guides the browser as to the type of information expected in the field. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
 | `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
-| `compact` | `boolean \| undefined` | `false` |  | Displays the component in a compact version. |
+| `compact` | `boolean \| undefined` | `false` |  | Compact density. Swaps `--bb-input-h`, `--bb-input-py` and `--bb-label-spacing-y` for their `-compact` twins on the field, so a `--bb-input-h` you set on the component is ignored while `compact` is on: size a compact field with `--bb-input-… |
 | `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |

package/dist/ai/BbConfirm.md

@@ -32,7 +32,8 @@
 | `--bg-pressed` | `pt:action` | `BbButton` | fill while [aria-pressed='true'] |
 | `--fg` | `pt:action` | `BbButton` | label and icons (icons paint currentColor) |
 | `--border-color` | `pt:action` | `BbButton` | the frame; its width is --bw |
-| `--ring` | `pt:action` | `BbButton` | focus ring, drawn --bb-ring-size outside the border |
+| `--ring-color` | `pt:action` | `BbButton` | focus ring colour, per variant |
+| `--ring-size` | `pt:action` | `BbButton` | focus ring width, outside the border |
 | `--bw` | `pt:action` | `BbButton` | border width |
 | `--fg-hover` | `pt:action` | `BbButton` | label and icons on hover (and focus-visible) |
 | `--border-hover` | `pt:action` | `BbButton` | the frame on hover (and focus-visible) |
@@ -835,7 +836,7 @@ States are listed in precedence order: when two are on at once and their entries
   - `BbDialog` _(public — [contract](./BbDialog.md))_ — its own pt parts (`BbDialog`): `header` → `div.bb-dialog__header`, `title` → `span.bb-dialog__title`, `description` → `p.bb-dialog__description`, `close` → `CloseButton`, `content` → `div.bb-dialog__body`, `footer` → `div.bb-dialog__footer`; hands `BbOffCanvas` the pt map `{ root: 'root', header: 'header', title: 'title', description: 'description', content: 'content', footer: 'footer', close: 'close', sheet: 'root', }` (ours → theirs); documented CSS variables: `--px`, `--close-size`
     - `CloseButton` _(internal — not importable, reach it through `BbDialog`)_ — documented CSS variables: `--size`, `--p`
     - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__body`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`; also mounts `CloseButton`
-  - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__content`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbSpinner`
+  - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__content`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbSpinner`
     - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
 
 ## See Also

package/dist/ai/BbDatePicker.md

@@ -296,7 +296,7 @@ style and attributes — optionally only while a state is on. Parts: `root`
 (the floating element — an invisible positioning wrapper, no node on a
 phone), `panel` (the calendar surface you see: the popover's painted bubble on
 desktop, the sheet itself on a phone — it also carries the sizing tokens, so
-`pt:panel="[--pad-x:2px]"` tightens the padding and the grid width follows), `sheet` (the
+`pt:panel="[--px:2px]"` tightens the padding and the grid width follows), `sheet` (the
 bottom sheet on a phone only, applied after `panel`), `header` (the
 navigation bar), `arrow` (the previous / next buttons), `month` and `year`
 (the heading buttons), `columnHeader` (each weekday letter), `day` (one whole
@@ -448,7 +448,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | `dayButton` | The button inside a day cell — the mark that shows selection. A broadcast resolved per day. |
 | `monthItem` | One month button of the month panel (the home grid of `type="month"`) — a broadcast resolved per month. |
 | `yearItem` | One year button of the year list — a broadcast resolved per year. |
-| `panel` | The calendar surface you see — the popover's painted bubble on desktop, the sheet itself on a phone. It carries the sizing tokens: `pt:panel="[--cell:36px]"` widens the calendar, `[--pad-x:2px]` tightens. |
+| `panel` | The calendar surface you see — the popover's painted bubble on desktop, the sheet itself on a phone. It carries the sizing tokens: `pt:panel="[--cell:36px]"` widens the calendar, `[--px:2px]` tightens. |
 | `sheet` | The bottom sheet on a phone only (the `BbOffCanvas` root). Applied after `panel`, so it wins a conflict there. |
 
 States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
@@ -493,22 +493,22 @@ Set these on the element, or on a class you put on it, to retune this component
 | Property | Set on | Default | What it is |
 | --- | --- | --- | --- |
 | `--cell` | `.bb-date-picker__panel` | `28px` | Cell size drives all grid math: 224px ÷ 7 = 32px exactly |
-| `--pad-x` | `.bb-date-picker__panel` | `6px` |  |
-| `--pad-y` | `.bb-date-picker__panel` | `8px` |  |
+| `--px` | `.bb-date-picker__panel` | `6px` |  |
+| `--py` | `.bb-date-picker__panel` | `8px` |  |
 | `--nav-button-h` | `.bb-date-picker__panel` | `24px` |  |
 | `--day-slot-allowance` | `.bb-date-picker__panel` | `0px` | Allowance for the day slot append area - needed for the slot to be visible |
 | `--unit-row` | `.bb-date-picker__panel` | `calc(var(--cell) * 1.25)` | Row pitch for the coarse grids (month/year), where a "row" is one of four month rows rather than a week. Roomier than --cell because twelve months in a 4×3 grid have space the 6×7 day grid does not. |
 | `--sheet-cell` | `.bb-date-picker-offcanvas` | `40px` |  |
 | `--cell` | `.bb-date-picker-offcanvas` | `var(--sheet-cell)` |  |
-| `--pad-x` | `.bb-date-picker-offcanvas` | `6px` |  |
-| `--pad-y` | `.bb-date-picker-offcanvas` | `8px` |  |
+| `--px` | `.bb-date-picker-offcanvas` | `6px` |  |
+| `--py` | `.bb-date-picker-offcanvas` | `8px` |  |
 | `--nav-button-h` | `.bb-date-picker-offcanvas` | `40px` |  |
 | `--day-slot-allowance` | `.bb-date-picker-offcanvas` | `0px` |  |
 | `--unit-row` | `.bb-date-picker-offcanvas` | `calc(var(--cell) * 1.25)` |  |
 | `--sheet-cell` | `.bb-date-picker__panel--sheet` | `inherit` |  |
 | `--cell` | `.bb-date-picker__panel--sheet` | `inherit` |  |
-| `--pad-x` | `.bb-date-picker__panel--sheet` | `inherit` |  |
-| `--pad-y` | `.bb-date-picker__panel--sheet` | `inherit` |  |
+| `--px` | `.bb-date-picker__panel--sheet` | `inherit` |  |
+| `--py` | `.bb-date-picker__panel--sheet` | `inherit` |  |
 | `--nav-button-h` | `.bb-date-picker__panel--sheet` | `inherit` |  |
 | `--day-slot-allowance` | `.bb-date-picker__panel--sheet` | `inherit` |  |
 | `--unit-row` | `.bb-date-picker__panel--sheet` | `inherit` |  |