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

package/README.md

@@ -78,7 +78,7 @@ Product-ready components with labels, hints, errors, and consistent styling:
 
 - **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbSelectPopover`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbColorPalette`, `BbDatePicker`, `BbDatePickerInput`, `BbTimePicker`, `BbTimePickerInput`, `BbButton`, `BbBadge`, `BbBadgeButton`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownGroup`, `BbDropdownButton`, `BbAsterisk`
 - **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbToastPortal`, `BbTooltip`
-- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTabs` (+ `BbTabsRoot`, `BbTabsList`, `BbTabsPanes`), `BbBreadcrumbs`, `BbPagination`, `BbSmoothHeight`
+- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTabs` (+ `BbTabsRoot`, `BbTabsList`, `BbTabsPanels`), `BbBreadcrumbs`, `BbPagination`, `BbSmoothHeight`
 - **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
@@ -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-mcp.mjs

@@ -316,6 +316,8 @@ function searchComponents({ query, limit, includeReferenceOnly } = {}) {
 			...(type.deprecated ? { deprecated: true } : {}),
 			...(type.replacedBy ? { replacedBy: type.replacedBy } : {}),
 			usedBy: type.usedBy ?? [],
+			// The short answer only; get_component(name) has the definition.
+			...(type.values ? { values: type.values } : {}),
 			import: `import type { ${type.replacedBy ?? type.name} } from 'bitboss-ui';`,
 		}));
 
@@ -425,9 +427,16 @@ function getComponent({ name, maxChars } = {}) {
 				...(type.replacedBy ? { replacedBy: type.replacedBy } : {}),
 				component: type.component,
 				usedBy: type.usedBy ?? [],
+				// What it is (Q50.2): the declaration, the accepted values when
+				// finite (open when `extensibleVia` names a registry), and the
+				// resolved fields when the declaration leans on a private type.
+				...(type.definition ? { definition: type.definition } : {}),
+				...(type.values ? { values: type.values } : {}),
+				...(type.extensibleVia ? { extensibleVia: type.extensibleVia } : {}),
+				...(type.fields ? { fields: type.fields } : {}),
 				import: `import type { ${type.replacedBy ?? name} } from 'bitboss-ui';`,
 				hint: use
-					? `A type, not a component: it types ${possessive(use.component)} \`${use.name}\` ${use.surface}. Call get_component('${use.component}') for the contract that documents its fields.`
+					? `A type, not a component: it types ${possessive(use.component)} \`${use.name}\` ${use.surface}. \`definition\` above is the type itself; call get_component('${use.component}') to see it in use.`
 					: 'A type, not a component — import it for the value you pass, never write it as a tag.',
 			};
 		}
@@ -467,6 +476,8 @@ function getComponent({ name, maxChars } = {}) {
 			name: type.name,
 			usage: type.usage,
 			usedBy: (type.usedBy ?? []).filter((use) => use.component === entry.name),
+			...(type.values ? { values: type.values } : {}),
+			...(type.extensibleVia ? { extensibleVia: type.extensibleVia } : {}),
 			import: `import type { ${type.name} } from 'bitboss-ui';`,
 		}));
 

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>
@@ -234,22 +234,22 @@ const endpoints = ref<Endpoint[]>([
      Non-scoped so variant classes on the child badge receive the accents. -->
 <style>
 .bb-badge.bb-badge--soft-blue {
-	--accent: #2563eb;
+	--accent: var(--bb-info);
 }
 .bb-badge.bb-badge--soft-green {
-	--accent: #16a34a;
+	--accent: var(--bb-success);
 }
 .bb-badge.bb-badge--soft-red {
-	--accent: #dc2626;
+	--accent: var(--bb-danger);
 }
 .bb-badge.bb-badge--soft-blue,
 .bb-badge.bb-badge--soft-green,
 .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.
@@ -619,7 +619,7 @@ grammar, the merge rules and the global map are in the
 | --- | --- | --- | --- | --- |
 | `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: `header`, `panel`, `root`. States: `open`. 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`. |
 | `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
-| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `id` | `string \| undefined` |  |  | The root's `id`; the header button's id (`<id>_header`) derives from it. Generated when omitted. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. An accordion with no `v-model` starts closed. |
 | `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |
 
@@ -641,7 +641,7 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Events
 
-- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`
+- `update:modelValue` — `(value: boolean): void` — Emitted with the new value whenever `v-model` changes.
 
 ## Slots
 
@@ -664,4 +664,4 @@ States are listed in precedence order: when two are on at once and their entries
 ## See Also
 
 - [BbCollapsible](./BbCollapsible.md) — Toggles visibility of collapsible content blocks.
-- [BbTabs](./BbTabs.md) — Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).
+- [BbTabs](./BbTabs.md) — Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanels exports enable split layouts).

package/dist/ai/BbAlert.md

@@ -53,6 +53,11 @@ the user should attend to; `destructive` reports a failure or dangerous state.
 An alert reads far better with a matching leading `icon`, so treat variant and
 icon as a pair.
 
+There is no `success` or `info` alert, on purpose (the built-in ramps stay
+closed): a confirmation is usually a toast, and a neutral note is `outline`
+with an icon. When an app needs one anyway, register it with the plugin's
+`alertVariants` option and colour it from `--bb-success` / `--bb-info`.
+
 **Semantic variants, each with a fitting icon**
 
 ```vue
@@ -475,7 +480,7 @@ full grammar, the merge rules and the global map are in the
 
 ## Events
 
-- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`
+- `update:modelValue` — `(value: boolean): void` — Emitted with the new value whenever `v-model` changes.
 
 ## Slots
 

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. |
+| `--fs` | `.bb-avatar` | `max(8px, calc(var(--size) * 0.4))` | Initials: 40% of the avatar, floored at 8px |
 | `--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)` |  |
 

package/dist/ai/BbBadge.md

@@ -161,19 +161,19 @@ const invoices: InvoiceRow[] = [
      Non-scoped so variant classes on the child badge receive the accents. -->
 <style>
 .bb-badge.bb-badge--soft-gray {
-	--accent: #64748b;
+	--accent: var(--bb-text-muted);
 }
 .bb-badge.bb-badge--soft-blue {
-	--accent: #2563eb;
+	--accent: var(--bb-info);
 }
 .bb-badge.bb-badge--soft-green {
-	--accent: #16a34a;
+	--accent: var(--bb-success);
 }
 .bb-badge.bb-badge--soft-amber {
-	--accent: #d97706;
+	--accent: var(--bb-warn);
 }
 .bb-badge.bb-badge--soft-red {
-	--accent: #dc2626;
+	--accent: var(--bb-danger);
 }
 
 .bb-badge.bb-badge--soft-gray,
@@ -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>
 ```
@@ -650,12 +650,12 @@ and the clear control be independent controls:
 		<!-- <button>/<a> in button mode -->
 		<svg class="bb-badge__prepend-icon" />
 		<!-- or __icon / BbSpinner -->
-		<span class="bb-badge__content">label</span>
+		<span class="bb-badge__text">label</span>
 	</span>
 	<span class="bb-badge__trailing">
 		<!-- only when needed -->
 		<svg class="bb-badge__append-icon" />
-		<button class="bb-badge__clear-button">…</button>
+		<button class="bb-badge__clear">…</button>
 	</span>
 </span>
 ```
@@ -669,7 +669,7 @@ Focus is always ringed on the **whole pill** (never on the inner control), for
 the body and the clear button alike; the clear button additionally lights its
 glyph. The class hooks above are the supported styling surface —
 `.bb-badge__body` and `.bb-badge__trailing` are new, so avoid direct-child
-selectors like `.bb-badge > .bb-badge__content`, which no longer match.
+selectors like `.bb-badge > .bb-badge__text`, which no longer match.
 
 ### Restyling with passthrough
 
@@ -767,22 +767,22 @@ const endpoints: Endpoint[] = [
      Non-scoped so variant classes on the child badge receive the accents. -->
 <style>
 .bb-badge.bb-badge--soft-blue {
-	--accent: #2563eb;
+	--accent: var(--bb-info);
 }
 .bb-badge.bb-badge--soft-green {
-	--accent: #16a34a;
+	--accent: var(--bb-success);
 }
 .bb-badge.bb-badge--soft-red {
-	--accent: #dc2626;
+	--accent: var(--bb-danger);
 }
 .bb-badge.bb-badge--soft-blue,
 .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>
 ```
@@ -874,7 +874,7 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Events
 
-- `click:clear` — `(event: "click:clear", event: MouseEvent): void`
+- `click:clear` — `(event: MouseEvent): void` — Emitted when the clear button is pressed (only rendered when `clearable`).
 
 ## Slots
 
@@ -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` | `calc(var(--bb-control-h) - 16px)` | 16px at the default |
+| `--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) - 14px)` | 18px 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) - 2px)` | 12px at the default (Q49.25) |
 | `--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
@@ -913,7 +914,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbBadge`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
 - Listed nodes are the ones `BbBadge`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
 
-- `BbBadge` _(this component)_ — its own template binds: `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear-button`
+- `BbBadge` _(this component)_ — its own template binds: `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`
   - Also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
 
 ## See Also

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` | `calc(var(--bb-control-h) - 16px)` | 16px at the default |
+| `--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) - 14px)` | 18px 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) - 2px)` | 12px at the default (Q49.25) |
 | `--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