bitboss-ui 3.0.0-beta.21 → 3.0.0-beta.23

package/bin/bitboss-ui.mjs

@@ -22,15 +22,23 @@
  *             `bitboss-ui.allowComponents`) exempts an app-owned component
  *             whose name happens to start with `Bb`.
  *
+ *             `--manifest <path>` judges against ANOTHER version's
+ *             components.json instead of the installed one — answers "what
+ *             breaks if I upgrade" BEFORE upgrading. A path, not a version:
+ *             no network call inside a CI validator.
+ *
  *             SCOPE: `check` knows the INSTALLED v3 API and nothing about v2.
  *             "was removed from X" is a recorded v2→v3 break; "is not in X's
  *             API" only says the prop is not a v3 prop of that component —
  *             it may never have been one anywhere. `printFindingLegend` says
  *             so in the output, because two migrating fleets each spent real
  *             time discovering it the hard way.
+ *   changelog Breaking changes between two releases — `--since <version>`
+ *             answers "what breaks if I bump", without MCP. Reads the
+ *             installed `dist/ai/changelog.json`.
  *   mcp       Start a stdio MCP server exposing the dist/ai knowledge base
- *             (search_components, get_component, list_recipes, get_recipe,
- *             validate) to MCP-capable agent harnesses.
+ *             (search_components, get_component, list_changes, list_recipes,
+ *             get_recipe, validate) to MCP-capable agent harnesses.
  *
  * Plain ESM JavaScript on purpose: shipped as-is in the package, no build.
  */
@@ -44,13 +52,18 @@ import {
 	statSync,
 	writeFileSync,
 } from 'node:fs';
-import { findHandRollHints } from '../scripts/lib/hand-roll-hints.mjs';
-import { dirname, isAbsolute, join, relative } from 'node:path';
+import {
+	findHandRollHints,
+	loadKnownTokens,
+} from '../scripts/lib/hand-roll-hints.mjs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import {
 	ensureMcpConfigs,
 	missingMcpPeers,
+	MCP_BIN_PATH,
+	MCP_PEERS,
 } from '../scripts/lib/mcp-config.mjs';
 import {
 	loadManifest,
@@ -88,7 +101,7 @@ function coreRules(version) {
 5. **Icons**: discover names first; never invent them (\`${KNOWLEDGE_BASE}/guides/icons-policy.md\`).
 6. **Item-driven components**: declarative \`items\` / \`item-text\` / \`item-value\`, \`dependencies\`, \`enforce-coherence\` — no manual watchers for coherence.
 7. **Whole pages**: one recipe under \`${KNOWLEDGE_BASE}/recipes/{vue|nuxt|inertia}/\` (see the router table).
-8. **CSS near components**: \`${KNOWLEDGE_BASE}/guides/design-language.md\` — \`--bb-*\` tokens only; one primary action per view region.
+8. **CSS near components**: \`${KNOWLEDGE_BASE}/guides/design-language.md\`. Two token tiers, and reaching for the wrong one is why apps end up re-skinning by class: \`--bb-*\` is the small GLOBAL theme tier (brand knobs, ~90 names, no numeric ramp — there is no \`--bb-primary-800\`), while each component declares its own **unprefixed** \`--*\` tokens for its look (\`.bb-table { --cell-h: 32px }\`). A missing \`--bb-*\` name is not a gap in the library — it means the knob you want is a component token. Set it on the element that DECLARES it (grep \`${KNOWLEDGE_BASE}/source/<ComponentName>.md\`); a value set further out is masked, not inherited. Never override \`.bb-*__*\` internals, and never target \`.bb-base-*\` / \`.bb-common-*\` at all. **A Tailwind utility on a \`Bb*\` component that does nothing** is not a library bug: Tailwind v4 emits layered CSS and unlayered CSS outranks it, whatever the specificity. The fix is in the BUILD plugin, not in CSS — \`cssLayers: TAILWIND_V4_LAYERS\` (imported from \`bitboss-ui/vite\`) in \`vite.config.*\` / \`nuxt.config.*\`; see \`${KNOWLEDGE_BASE}/guides/installation-and-plugin-setup.md\` § Cascade layers. One primary action per view region.
 9. **Variants are yours to add**: the shipped \`variant\` names are a floor, not a ceiling. When the design needs a colour the library doesn't ship (soft status badges, a brand button tone), **register the name** in the build plugin's \`badgeVariants\`/\`buttonVariants\`/\`alertVariants\`/… and **style \`.bb-badge--<name>\`** (etc.) in a project stylesheet loaded after \`bitboss-ui/styles.css\`. Do both halves — a registered name with no CSS ships an unstyled pill, and CSS with no registration fails \`vue-tsc\`. Never write an unregistered name, and never downgrade the design to a neutral shipped variant to avoid registering. Canonical palette + snippet: \`${KNOWLEDGE_BASE}/guides/design-language.md\` § Getting soft semantic badges.
 10. **After writing bitboss-ui markup**, run \`npx bitboss-ui check\` — validates \`Bb*\` usage against the installed \`components.json\` and catches invented/removed props before review.
 
@@ -519,6 +532,29 @@ function printFindingLegend(findings) {
 				'                         "restoring" anything: the second case needs deleting,\n' +
 				'                         not porting.'
 		);
+	// A type written as a tag is its own category: the name IS ours, so neither
+	// "check the spelling" nor the allowlist applies, and a reader who skims the
+	// message alone would reach for one of them.
+	if (
+		findings.some((f) => / is a type export, not a component$/.test(f.message))
+	)
+		rows.push(
+			'  "is a type export"     a real export, but a TYPE — it types a prop, it does not\n' +
+				'                         render. Import it (`import type { … }`) and pass the\n' +
+				'                         value; never allowlist it, which would only silence\n' +
+				'                         every other check on that tag.'
+		);
+	if (findings.some((f) => f.fallthrough))
+		rows.push(
+			'  ⚠ (vs ✗)               markup that is not a typo and may work today: an\n' +
+				'                         undeclared listener Vue binds to the root ELEMENT,\n' +
+				'                         so whether it fires depends on what that root is —\n' +
+				"                         an internal detail, on the component's schedule or\n" +
+				"                         the element's. `<BbDialog @close>` runs (that root is\n" +
+				'                         a native <dialog>); `<BbAlert @close>` does not.\n' +
+				'                         Still reported, because neither is the contract. In\n' +
+				'                         ESLint this is `no-unknown-event`, a warning.'
+		);
 	if (rows.length === 0) return;
 	console.error('\nReading these findings:');
 	for (const row of rows) console.error(row);
@@ -532,13 +568,156 @@ function printFindingLegend(findings) {
  * v-models, and `<template #slot>` names) in `.vue` and `.md` files against
  * the installed components.json manifest.
  */
-function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
+/**
+ * The version a components.json describes. `loadManifest` returns the indexed
+ * component map, not the envelope, so read the field straight off the file.
+ */
+/**
+ * `changelog [--since <v>] [--until <v>] [--json]` — what breaks between two
+ * releases, for anyone not driving the MCP server (a human at a terminal, CI,
+ * or an agent whose harness has no MCP). Same data and same range rules as the
+ * `list_changes` tool; this is the transport-free path to it.
+ */
+function changelogCommand({ since, until, json: jsonMode }) {
+	const path = join(PACKAGE_ROOT, 'dist', 'ai', 'changelog.json');
+	if (!existsSync(path)) {
+		console.error(
+			`[bitboss-ui] changelog: not found at ${path} — reinstall bitboss-ui (or run \`npm run build\` when working in the library repo).`
+		);
+		process.exit(1);
+	}
+	const doc = JSON.parse(readFileSync(path, 'utf-8'));
+	const releases = doc.releases ?? [];
+
+	for (const [label, value] of [
+		['--since', since],
+		['--until', until],
+	]) {
+		if (value != null && !releases.includes(value)) {
+			console.error(
+				`[bitboss-ui] changelog: unknown ${label} version '${value}'.\n` +
+					`Known releases: ${releases.join(', ')}`
+			);
+			process.exit(1);
+		}
+	}
+
+	const ranged = since != null || until != null;
+	const rows = (doc.breaking ?? []).filter((entry) => {
+		if (!ranged) return true;
+		const at = entry.firstReleasedIn;
+		if (at == null) return until == null;
+		if (since != null && compareReleaseVersions(at, since) <= 0) return false;
+		if (until != null && compareReleaseVersions(at, until) > 0) return false;
+		return true;
+	});
+
+	if (jsonMode) {
+		console.log(
+			JSON.stringify(
+				{
+					version: doc.version,
+					since: since ?? null,
+					until: until ?? doc.version,
+					count: rows.length,
+					breaking: rows,
+					guide: doc.guide,
+				},
+				null,
+				2
+			)
+		);
+		return;
+	}
+
+	const range = ranged
+		? `${since ?? 'the start of v3'} → ${until ?? doc.version}`
+		: `the whole v2 → v3 upgrade`;
+	if (rows.length === 0) {
+		// "Nothing breaks" and "I could not tell you" must not look alike.
+		console.log(
+			`[bitboss-ui] changelog: no BREAKING changes in ${range}.\n` +
+				'            Features and fixes are deliberately not tracked here, so this\n' +
+				'            means nothing breaks — not that nothing changed.'
+		);
+		return;
+	}
+	console.log(
+		`[bitboss-ui] changelog: ${rows.length} breaking change(s), ${range}\n`
+	);
+	for (const entry of rows) {
+		const at = entry.firstReleasedIn ?? 'unreleased';
+		if (entry.kind === 'rename') {
+			console.log(
+				`  [${at}] ${entry.components.join(', ')}: \`${entry.from}\` → \`${entry.to}\``
+			);
+		} else {
+			console.log(`  [${at}] ${entry.description}`);
+		}
+		if (entry.guide) console.log(`           ${entry.guide}`);
+	}
+	console.log(`\nFull migration guide: ${doc.guide}`);
+}
+
+/** Numeric, prerelease-aware ordering; the twin of the MCP server's copy. */
+function compareReleaseVersions(a, b) {
+	const parse = (v) => {
+		const [core, pre = ''] = String(v).split('-');
+		const nums = core.split('.').map((n) => Number.parseInt(n, 10) || 0);
+		const [tag = '', n = ''] = pre.split('.');
+		return { nums, tag, n: Number.parseInt(n, 10) || 0 };
+	};
+	const x = parse(a);
+	const y = parse(b);
+	for (let i = 0; i < 3; i += 1) {
+		if ((x.nums[i] ?? 0) !== (y.nums[i] ?? 0))
+			return (x.nums[i] ?? 0) - (y.nums[i] ?? 0);
+	}
+	if (!x.tag && y.tag) return 1;
+	if (x.tag && !y.tag) return -1;
+	if (x.tag !== y.tag) return x.tag < y.tag ? -1 : 1;
+	return x.n - y.n;
+}
+
+function manifestVersionOf(manifestPath) {
+	try {
+		return JSON.parse(readFileSync(manifestPath, 'utf-8')).version ?? 'unknown';
+	} catch {
+		return 'unknown';
+	}
+}
+
+function checkCommand(
+	globs,
+	{ json: jsonMode, allowEmpty, allowComponents, manifest: manifestOverride }
+) {
 	const projectRoot = process.cwd();
 
-	const manifestPath = join(PACKAGE_ROOT, 'dist', 'ai', 'components.json');
+	/*
+	 * `--manifest` answers the question `check` could not: "which of my files
+	 * break in the version I am about to move to?" (reported 2026-09-09). By
+	 * default the manifest is the INSTALLED one, so the only way to see an
+	 * upgrade's damage was to perform the upgrade first — exactly backwards for
+	 * the one moment the answer is worth having.
+	 *
+	 * Deliberately a PATH, not a version: fetching a version would put a network
+	 * call inside a validator that consumers run in CI, with a registry outage
+	 * as a new failure mode. Getting the file is one documented command
+	 * (`npm pack bitboss-ui@<version>`, or the public CDN copy), and pointing at
+	 * it keeps this offline and reproducible.
+	 */
+	const installedManifest = join(PACKAGE_ROOT, 'dist', 'ai', 'components.json');
+	const manifestPath = manifestOverride
+		? resolve(projectRoot, manifestOverride)
+		: installedManifest;
 	if (!existsSync(manifestPath)) {
 		console.error(
-			`[bitboss-ui] Manifest not found at ${manifestPath} — reinstall bitboss-ui (or run \`npm run build\` when working in the library repo).`
+			manifestOverride
+				? `[bitboss-ui] --manifest: no file at ${manifestPath}.\n` +
+						'Point it at a components.json from the version you are moving to:\n' +
+						'  npm pack bitboss-ui@<version> && tar -xzf bitboss-ui-<version>.tgz\n' +
+						'  npx bitboss-ui check --manifest package/dist/ai/components.json'
+				: `[bitboss-ui] Manifest not found at ${manifestPath} — reinstall bitboss-ui (or run \`npm run build\` when working in the library repo).`
 		);
 		process.exit(1);
 	}
@@ -551,16 +730,14 @@ function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
 	 * Absent stylesheet → an empty set → the unknown-token hint stays silent,
 	 * which is the right failure: no data, no accusation.
 	 */
-	const stylesPath = join(PACKAGE_ROOT, 'dist', 'styles.css');
-	const knownTokens = existsSync(stylesPath)
-		? new Set(
-				[
-					...readFileSync(stylesPath, 'utf-8').matchAll(
-						/(--bb-[a-z0-9-]+)\s*:/gi
-					),
-				].map((m) => m[1].toLowerCase())
-			)
-		: new Set();
+	// Under `--manifest`, take the sheet from beside THAT manifest
+	// (`<pkg>/dist/ai/components.json` → `<pkg>/dist/styles.css`). Reading the
+	// installed sheet while judging props against another version would mix two
+	// releases in one verdict — the exact confusion this flag exists to end.
+	const stylesPath = manifestOverride
+		? join(dirname(dirname(manifestPath)), 'styles.css')
+		: join(PACKAGE_ROOT, 'dist', 'styles.css');
+	const knownTokens = loadKnownTokens(stylesPath);
 	const files = resolveCheckFiles(projectRoot, globs);
 
 	// CHK-ALLOWCOMPONENTS: `Bb` is a naming convention, not proof of ownership.
@@ -613,9 +790,37 @@ function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
 		);
 	};
 
+	/*
+	 * Which API the verdict is against. Silent when it is the installed one —
+	 * that is the assumption, and a banner on every run trains people to skip
+	 * it. Loud under `--manifest`, because "12 findings" means something
+	 * completely different when it describes a version you have not installed
+	 * yet, and a scrollback with no marker is indistinguishable from a normal
+	 * run.
+	 */
+	const judgedAgainst = manifestOverride
+		? manifestVersionOf(manifestPath)
+		: packageVersion();
+	if (manifestOverride && !jsonMode) {
+		console.log(
+			`[bitboss-ui] check: judging against bitboss-ui ${judgedAgainst} (--manifest), NOT the installed ${packageVersion()}.\n` +
+				'            Findings describe the version you are moving TO.'
+		);
+	}
+
 	if (jsonMode) {
 		console.log(
-			JSON.stringify({ findings, hints, files: files.length }, null, 2)
+			JSON.stringify(
+				{
+					findings,
+					hints,
+					files: files.length,
+					manifestVersion: judgedAgainst,
+					installedVersion: packageVersion(),
+				},
+				null,
+				2
+			)
 		);
 		if (findings.length > 0) process.exit(1);
 		if (files.length === 0 && globs.length > 0 && !allowEmpty) process.exit(1);
@@ -668,8 +873,13 @@ function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
 		// were indistinguishable, so every automated fix had to re-parse the
 		// file to place them. The line comes straight off the template AST.
 		const at = finding.line != null ? `line ${finding.line}: ` : '';
+		// A `fallthrough` finding is not a typo and may be doing something
+		// today — a native listener reaching the root element. It still counts,
+		// but marking it `✗` alongside a genuinely broken prop is what let one
+		// migration report read a live `<BbDialog @close>` as dead code.
+		const mark = finding.fallthrough ? '⚠' : '✗';
 		console.error(
-			`    ✗ ${at}${where ? `[${where.trim()}] ` : ''}${finding.message}`
+			`    ${mark} ${at}${where ? `[${where.trim()}] ` : ''}${finding.message}`
 		);
 		if (finding.hint) console.error(`      hint: ${finding.hint}`);
 	}
@@ -697,7 +907,7 @@ Commands:
                       VS Code/Copilot (.vscode/mcp.json), and Windsurf (~/.codeium
                       global) — merges, never overwrites other servers.
   check [glob…] [--json] [--allow-empty] [--allow-component <Name>]
-                      [--no-hints]
+                      [--no-hints] [--manifest <path>]
                       Validate \`Bb*\` markup in .vue/.md files against the
                       installed components.json manifest (unknown/removed props,
                       bad v-models, unknown \`<template #slot>\` names,
@@ -710,6 +920,17 @@ Commands:
                       nothing (a typo'd CI path validates zero files silently) —
                       pass \`--allow-empty\` when an empty match is expected.
 
+                      \`--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
+                      upgrade. The banner names both versions so a findings list
+                      is never mistaken for one about your current install.
+                        npm pack bitboss-ui@3.0.0-beta.21
+                        tar -xzf bitboss-ui-3.0.0-beta.21.tgz
+                        npx bitboss-ui check --manifest package/dist/ai/components.json
+                      A path, not a version, on purpose: fetching one would put
+                      a registry call inside a validator people run in CI.
+
                       \`--allow-component <Name>\` (repeatable) exempts a
                       component your APP owns whose name starts with \`Bb\` —
                       the prefix is a convention, not proof of provenance.
@@ -730,6 +951,16 @@ Commands:
                       \`no-default-slot\`, \`inert-nav-attr\`,
                       \`missing-partner-prop\`, \`partner-prop\`,
                       \`validated-only-prop\`.
+  changelog [--since <version>] [--until <version>] [--json]
+                      Breaking changes between two releases — "what breaks if I
+                      bump". \`--since\` is the version you are ON, and is
+                      exclusive. With no range, every break in the v2 → v3
+                      upgrade. Only BREAKING changes are tracked, so an empty
+                      result means nothing breaks, not that nothing changed.
+                        npx bitboss-ui changelog --since 3.0.0-beta.20
+                      Pair it with \`check --manifest\` to turn the list into the
+                      files in YOUR app that break.
+
   mcp                 Start a stdio MCP server exposing the dist/ai knowledge
                       base (search_components, get_component, list_recipes,
                       get_recipe, validate) to MCP-capable agent harnesses.
@@ -776,6 +1007,7 @@ switch (command) {
 				json: { type: 'boolean' },
 				'allow-empty': { type: 'boolean' },
 				'allow-component': { type: 'string', multiple: true },
+				manifest: { type: 'string' },
 				// Accepted and ignored here — read straight off argv inside
 				// checkCommand, but parseArgs is strict, so it must be declared.
 				'no-hints': { type: 'boolean' },
@@ -786,6 +1018,20 @@ switch (command) {
 			json: values.json ?? false,
 			allowEmpty: values['allow-empty'] ?? false,
 			allowComponents: values['allow-component'] ?? [],
+			manifest: values.manifest,
+		});
+		break;
+	}
+	case 'changelog': {
+		const { values } = parseCommandArgs(command, commandArgs, {
+			since: { type: 'string' },
+			until: { type: 'string' },
+			json: { type: 'boolean' },
+		});
+		changelogCommand({
+			since: values.since,
+			until: values.until,
+			json: values.json ?? false,
 		});
 		break;
 	}
@@ -802,9 +1048,34 @@ switch (command) {
 			({ main } = await import('./bitboss-ui-mcp.mjs'));
 		} catch (error) {
 			if (error?.code !== 'ERR_MODULE_NOT_FOUND') throw error;
+			// Running from an npx cache is a DIFFERENT failure wearing the same
+			// error: the peers resolve relative to the package we were launched
+			// from, so a cached copy can never see the project's node_modules no
+			// matter what is installed there. Telling that user to install peers
+			// they already have is what sent a consumer down a dead end
+			// (2026-09-09). `ai-init --mcp` now writes the local binary instead
+			// of `npx`, so the fix is to rewrite the config.
+			const fromNpxCache = /[/\\]_npx[/\\]/.test(
+				fileURLToPath(import.meta.url)
+			);
+			const projectHasPeers = missingMcpPeers(process.cwd()).length === 0;
+			if (fromNpxCache && projectHasPeers) {
+				console.error(
+					'bitboss-ui mcp was launched through `npx`, which runs it from the npx cache —\n' +
+						'its optional peers resolve there, not in your project, so the server cannot start\n' +
+						`even though this project has them installed (${MCP_PEERS.join(', ')}).\n\n` +
+						'Fix the harness config to invoke the installed binary:\n\n' +
+						'  npx bitboss-ui ai-init --mcp\n\n' +
+						`which writes \`node ${MCP_BIN_PATH} mcp\`. To run it right now:\n\n` +
+						`  node ${MCP_BIN_PATH} mcp\n\n` +
+						`Resolution failed with: ${error.message}`
+				);
+				process.exitCode = 1;
+				break;
+			}
 			console.error(
 				'bitboss-ui mcp needs two optional peer dependencies that are not installed:\n' +
-					'\n  npm i -D @modelcontextprotocol/sdk zod\n\n' +
+					`\n  npm i -D ${MCP_PEERS.join(' ')}\n\n` +
 					'They are optional because they are ~12 MB and only this subcommand uses them.\n' +
 					`Resolution failed with: ${error.message}`
 			);

package/dist/ai/BbAccordion.md

@@ -47,13 +47,13 @@ collapsed state and strips padding/borders you put on the panel itself.
 ```vue
 <template>
 	<div
-		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbAccordion
 			v-for="(faq, index) in faqs"
 			:key="faq.question"
 			v-model="faq.open"
-			:class="index ? 'border-t border-[color:var(--bb-border)]' : ''"
+			:class="index ? 'border-t border-(--bb-border)' : ''"
 		>
 			<template #header="{ value }">
 				<div
@@ -61,7 +61,7 @@ collapsed state and strips padding/borders you put on the panel itself.
 				>
 					<span>{{ faq.question }}</span>
 					<span
-						class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform duration-200"
+						class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
 						:class="value ? 'rotate-180' : ''"
 					>
 						<BbIcon icon="lucide:chevron-down" size="sm" />
@@ -69,7 +69,7 @@ collapsed state and strips padding/borders you put on the panel itself.
 				</div>
 			</template>
 
-			<p class="px-3 pb-2.5 text-sm text-[color:var(--bb-text-muted)]">
+			<p class="px-3 pb-2.5 text-sm text-(--bb-text-muted)">
 				{{ faq.answer }}
 			</p>
 		</BbAccordion>
@@ -121,13 +121,13 @@ on the row, badge included, toggles the panel.
 ```vue
 <template>
 	<div
-		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbAccordion
 			v-for="(endpoint, index) in endpoints"
 			:key="`${endpoint.method}:${endpoint.path}`"
 			v-model="endpoint.open"
-			:class="index ? 'border-t border-[color:var(--bb-border)]' : ''"
+			:class="index ? 'border-t border-(--bb-border)' : ''"
 		>
 			<template #header="{ value }">
 				<div class="flex w-full items-center gap-2 px-3 py-2 text-left">
@@ -136,7 +136,7 @@ on the row, badge included, toggles the panel.
 					}}</BbBadge>
 					<code class="truncate font-mono text-xs">{{ endpoint.path }}</code>
 					<span
-						class="ml-auto shrink-0 text-[color:var(--bb-text-muted)] transition-transform duration-200"
+						class="ml-auto shrink-0 text-(--bb-text-muted) transition-transform duration-200"
 						:class="value ? 'rotate-180' : ''"
 					>
 						<BbIcon icon="lucide:chevron-down" size="sm" />
@@ -145,7 +145,7 @@ on the row, badge included, toggles the panel.
 			</template>
 
 			<div class="flex flex-col gap-1.5 px-3 pb-2.5">
-				<p class="text-xs text-[color:var(--bb-text-muted)]">
+				<p class="text-xs text-(--bb-text-muted)">
 					{{ endpoint.summary }}
 				</p>
 				<dl class="flex flex-col gap-1 text-xs">
@@ -155,7 +155,7 @@ on the row, badge included, toggles the panel.
 						class="flex items-baseline gap-2"
 					>
 						<dt class="shrink-0 font-mono">{{ param.name }}</dt>
-						<dd class="text-[color:var(--bb-text-muted)]">
+						<dd class="text-(--bb-text-muted)">
 							{{ param.type }} · {{ param.description }}
 						</dd>
 					</div>
@@ -263,7 +263,7 @@ Both slots — `header` and the default (body) slot — receive the same scope,
 ```vue
 <template>
 	<div
-		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbAccordion v-model="notes">
 			<template #header="{ value }">
@@ -272,7 +272,7 @@ Both slots — `header` and the default (body) slot — receive the same scope,
 				>
 					<span>Release notes</span>
 					<span
-						class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform duration-200"
+						class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
 						:class="value ? 'rotate-180' : ''"
 					>
 						<BbIcon icon="lucide:chevron-down" size="sm" />
@@ -281,7 +281,7 @@ Both slots — `header` and the default (body) slot — receive the same scope,
 			</template>
 			<template #default="{ toggle }">
 				<div class="flex flex-col items-start gap-1.5 px-3 pb-2.5">
-					<p class="text-sm text-[color:var(--bb-text-muted)]">
+					<p class="text-sm text-(--bb-text-muted)">
 						Dropdown keyboard navigation, smoother select popovers, and a new
 						color picker.
 					</p>
@@ -317,12 +317,12 @@ to `null`). Prefer a stable key over an index when the list can reorder.
 ```vue
 <template>
 	<div
-		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbAccordion
 			v-for="(plan, index) in plans"
 			:key="plan.name"
-			:class="index ? 'border-t border-[color:var(--bb-border)]' : ''"
+			:class="index ? 'border-t border-(--bb-border)' : ''"
 			:model-value="openIndex === index"
 			@update:model-value="openIndex = $event ? index : null"
 		>
@@ -331,9 +331,7 @@ to `null`). Prefer a stable key over an index when the list can reorder.
 					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm"
 				>
 					<span class="font-medium">{{ plan.name }}</span>
-					<span
-						class="flex items-center gap-1.5 text-[color:var(--bb-text-muted)]"
-					>
+					<span class="flex items-center gap-1.5 text-(--bb-text-muted)">
 						{{ plan.price }}
 						<span
 							class="shrink-0 transition-transform duration-200"
@@ -346,7 +344,7 @@ to `null`). Prefer a stable key over an index when the list can reorder.
 			</template>
 
 			<ul
-				class="flex flex-col gap-1 px-3 pb-2.5 text-sm text-[color:var(--bb-text-muted)]"
+				class="flex flex-col gap-1 px-3 pb-2.5 text-sm text-(--bb-text-muted)"
 			>
 				<li v-for="feature in plan.features" :key="feature">{{ feature }}</li>
 			</ul>
@@ -394,7 +392,7 @@ padding on the nested body content.
 ```vue
 <template>
 	<div
-		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 	>
 		<BbAccordion v-model="notifications">
 			<template #header="{ value }">
@@ -403,7 +401,7 @@ padding on the nested body content.
 				>
 					<span>Notifications</span>
 					<span
-						class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform duration-200"
+						class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
 						:class="value ? 'rotate-180' : ''"
 					>
 						<BbIcon icon="lucide:chevron-down" size="sm" />
@@ -416,7 +414,7 @@ padding on the nested body content.
 				<BbAccordion v-model="advanced">
 					<template #header="{ value }">
 						<div
-							class="flex w-full items-center justify-between gap-2 py-1 text-left text-sm text-[color:var(--bb-text-muted)]"
+							class="flex w-full items-center justify-between gap-2 py-1 text-left text-sm text-(--bb-text-muted)"
 						>
 							<span>Advanced</span>
 							<span
@@ -427,7 +425,7 @@ padding on the nested body content.
 							</span>
 						</div>
 					</template>
-					<div class="pb-1 pt-1">
+					<div class="pt-1 pb-1">
 						<BbCheckbox v-model="quiet" label="Quiet hours (22:00–08:00)" />
 					</div>
 				</BbAccordion>
@@ -470,7 +468,7 @@ get a near-instant transition automatically.
 	<template #header>
 		<span class="px-3 py-2 text-sm font-medium">Shipping details</span>
 	</template>
-	<p class="px-3 pb-3 text-sm text-[color:var(--bb-text-muted)]">
+	<p class="px-3 pb-3 text-sm text-(--bb-text-muted)">
 		Rendered up front so its text is present even while collapsed.
 	</p>
 </BbAccordion>

package/dist/ai/BbAlert.md

@@ -129,12 +129,10 @@ Bind `v-model` when the visibility matters to you:
 
 ```vue
 <template>
-	<div
-		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-md flex-col gap-3 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Account</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Confirm your email to invite teammates and manage billing.
 			</p>
 		</div>
@@ -233,12 +231,10 @@ genuine brand art; everything semantic stays a provider icon.
 
 ```vue
 <template>
-	<div
-		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-md flex-col gap-3 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Integrations</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Connected payment providers for Northwind Billing.
 			</p>
 		</div>
@@ -279,12 +275,10 @@ list of problems changes.
 
 ```vue
 <template>
-	<div
-		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-md flex-col gap-3 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Publish checklist</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Northwind Q3 release notes — blocked until both items are done.
 			</p>
 		</div>