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

package/README.md

@@ -17,9 +17,10 @@ Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheet
 ### TypeScript: use `vue-tsc` 3
 
 Use **`vue-tsc` 3 or newer**. Under `vue-tsc` 2 the template type-checker
-silently checks **nothing** about the props of the nine components declared with
-`generic="T"` — `BbSelect`, `BbSelectPopover`, `BbTable`, `BbTabs`,
-`BbTabsRoot`, `BbTree`, `BbRadioGroup`, `BbCheckboxGroup`, `BbSwitchGroup` —
+silently checks **nothing** about the props of the nine public components that
+use `<script setup generic="…">` — `BbSelect`, `BbSelectPopover`, `BbTable`,
+`BbTabs`, `BbTabsRoot`, `BbTree`, `BbRadioGroup`, `BbCheckboxGroup`,
+`BbSwitchGroup` —
 because they emit as generic functions rather than `DefineComponent<…>`, a shape
 Vue Language Tools 2 cannot read props out of.
 
@@ -39,7 +40,7 @@ Full detail: `ai/guides/installation-and-plugin-setup.md`.
 
 | Composable             | Role                                                                  |
 | ---------------------- | --------------------------------------------------------------------- |
-| `useBbConfig`          | Global options for the kit (locale, defaults, etc.).                  |
+| `useBbConfig`          | `setConfig()` patches the one runtime-editable kit option: `locale`.  |
 | `useBbDropdownContext` | Read a `BbDropdown`'s resolved groups/selections from anywhere by id. |
 | `useBbTableContext`    | Imperative handle onto a `BbTable` by id.                             |
 | `useBbTabsContext`     | Programmatic tab selection for a `BbTabs` by id.                      |
@@ -116,15 +117,15 @@ For the public **Bb\*** components, the package exports matching **props**, **ev
 **For AI coding agents:**
 
 The same knowledge base the npm package ships is served publicly over a CDN, so
-an agent can read it before anything is installed. `@alpha` tracks the latest
-v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-alpha.5`) for stable
+an agent can read it before anything is installed. `@beta` tracks the latest
+v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-beta.32`) for stable
 links. Sizes grow with the catalogue — treat them as the current order of
 magnitude, not a contract.
 
-- [Core knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt) (~110 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
-- [Index](https://llms-bitboss-ui.bitboss.it/llms.txt) (~19 KB) — link index into every document.
+- [Core knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt) (~190 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
+- [Index](https://llms-bitboss-ui.bitboss.it/llms.txt) (~22 KB) — link index into every document.
 - [components.json](https://llms-bitboss-ui.bitboss.it/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
-- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt) (~3.2 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
+- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt) (~4.3 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
 
 Already installed? Prefer the local copy under `node_modules/bitboss-ui/dist/ai/`,
 run `npx bitboss-ui ai-init` to write agent pointers, and
@@ -142,24 +143,24 @@ This package is developed and maintained by [BitBoss](https://www.bitboss.it/),
 
 ## Installation
 
-**v3 is a prerelease: the `@alpha` tag is required.** A bare
+**v3 is a prerelease: the `@beta` tag is required.** A bare
 `npm install bitboss-ui` resolves to the v2 line, which has no build plugin and
 no `dist/ai` knowledge base — if you are following the v3 docs, that install
 will not work.
 
 ```bash
-npm install bitboss-ui@alpha
+npm install bitboss-ui@beta
 ```
 
 ```bash
-pnpm add bitboss-ui@alpha
+pnpm add bitboss-ui@beta
 ```
 
 ```bash
-yarn add bitboss-ui@alpha
+yarn add bitboss-ui@beta
 ```
 
-Verify with `npm ls bitboss-ui` — it must report `3.0.0-alpha.*`.
+Verify with `npm ls bitboss-ui` — it must report `3.0.0-beta.*`.
 
 ---
 
@@ -439,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
@@ -501,17 +523,17 @@ A standard `llms.txt` discovery file is also published at:
 
 ### Knowledge-base layout
 
-| Path                                  | Contents                                  |
-| ------------------------------------- | ----------------------------------------- |
-| `dist/ai/guides/ai-router.md`         | **Start here** — which file to open next  |
-| `dist/ai/index.md`                    | Full catalogue + agent rules              |
-| `dist/ai/components.json`             | Machine-readable API (props/events/slots) |
-| `dist/ai/<ComponentName>.md`          | Guide-first contract per component        |
-| `dist/ai/composables/<name>.md`       | Composable docs                           |
-| `dist/ai/guides/agent-contract.md`    | Mandatory agent rules                     |
-| `dist/ai/guides/*-playbook.md`        | Coherence / fetch / options / inline-edit |
-| `dist/ai/guides/migration/`           | v2 → v3 upgrade corpus                    |
-| `dist/ai/recipes/{vue,nuxt,inertia}/` | Page-level assemblies (11 × 3)            |
+| Path                                  | Contents                                                                             |
+| ------------------------------------- | ------------------------------------------------------------------------------------ |
+| `dist/ai/guides/ai-router.md`         | **Start here** — which file to open next                                             |
+| `dist/ai/index.md`                    | Full catalogue + agent rules                                                         |
+| `dist/ai/components.json`             | Machine-readable API (props/events/slots)                                            |
+| `dist/ai/<ComponentName>.md`          | Guide-first contract per component                                                   |
+| `dist/ai/composables/<name>.md`       | Composable docs                                                                      |
+| `dist/ai/guides/agent-contract.md`    | Mandatory agent rules                                                                |
+| `dist/ai/guides/*-playbook.md`        | Coherence / fetch / options / inline-edit                                            |
+| `dist/ai/guides/migration/`           | v2 → v3 upgrade corpus                                                               |
+| `dist/ai/recipes/{vue,nuxt,inertia}/` | Page-level assemblies (9 vue / 9 nuxt / 10 inertia; Ownership Atlas is inertia-only) |
 
 ### Package exports
 
@@ -571,8 +593,8 @@ To make a report actionable, include:
 - whether it reproduces in dev, in a production build, or only under SSR
 - the smallest component snippet that shows it
 
-v3 ships as a prerelease (`npm i bitboss-ui@alpha`). Expect breaking changes
-between alphas; each one is recorded in the migration guides under
+v3 ships as a prerelease (`npm i bitboss-ui@beta`). Expect breaking changes
+between prereleases; each one is recorded in the migration guides under
 [`ai/guides/migration/`](ai/guides/migration/).
 
 ---

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/BbAsterisk.md

@@ -4,7 +4,7 @@
 
 - Safety level: **Consumer API**
 - Group: **Other**
-- Description: Presentational required-field marker (red "*"). No props/slots/events; placed in custom label content.
+- Description: Presentational required-field marker (red "*"). No behaviour props/slots/events (only `pt`); placed in custom label content.
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbAsterisk.md](./source/BbAsterisk.md)
 
@@ -13,7 +13,8 @@
 ### When to use
 
 `BbAsterisk` is the small red `*` that marks a field as required. It is purely
-presentational — it has no props, slots, or events, and it does not read
+presentational — it has no behaviour props, slots, or events (only `pt` to
+restyle its root), and it does not read
 `required` or drive validation. You render it yourself wherever you build custom
 label content, so the marker matches the library's styling (`--bb-danger`).
 

package/dist/ai/BbAvatar.md

@@ -648,6 +648,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--bg` | `.bb-avatar` | `var(--bb-primary)` | fallback surface (an image covers it) |
 | `--fg` | `.bb-avatar` | `var(--bb-primary-fg)` | Initials; the built-in icon is an 80/20 mix of this toward --bg |
 | `--default-icon-size` | `.bb-avatar` | `clamp(14px, calc(var(--size) * 0.7), 48px)` | Built-in fallback icon: 70% of the avatar, floored at 14px and capped at 48px. `--size` is the avatar's own box, set inline from the `size` prop. |
+| `--elev` | `.bb-avatar` | `var(--bb-elev-sm)` | The theme's resting lift on small chrome (Q44.15), declared here so an ancestor's `--elev` cannot reach in; `--elev: none` flattens one. |
 | `--size` | `.bb-avatar__default-icon` | `var(--default-icon-size)` |  |
 
 ## Component tree

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 |
-| `--min-size-md` | `.bb-badge` | `16px` | The md value. Only the default --min-size below reads it; the size modifiers set --min-size directly. |
+| `--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` | `10px` | label |
+| `--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 |
-| `--min-size-md` | `.bb-badge` | `16px` | The md value. Only the default --min-size below reads it; the size modifiers set --min-size directly. |
+| `--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` | `10px` | label |
+| `--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`, `--close-size`
+      - `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