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

package/dist/ai/BbDropzone.md

@@ -73,7 +73,7 @@ The slot scope carries five things:
 					{{ dragging ? 'Drop to upload' : 'Drag a file here' }}
 				</p>
 				<BbButton variant="ghost" @click="open">or browse</BbButton>
-				<p v-if="file" class="text-xs text-[color:var(--bb-text-muted)]">
+				<p v-if="file" class="text-xs text-(--bb-text-muted)">
 					Selected: {{ file.name }}
 				</p>
 			</div>
@@ -151,7 +151,7 @@ from the model (revoke the stale one when it changes) handed to
 			</BbAvatar>
 			<div class="min-w-0 flex-1">
 				<p class="text-sm font-medium">Ada Moreau</p>
-				<p class="truncate text-xs text-[color:var(--bb-text-muted)]">
+				<p class="truncate text-xs text-(--bb-text-muted)">
 					ada.moreau@acme.dev
 				</p>
 			</div>
@@ -334,7 +334,7 @@ there is no separate "selected files" API. Removal is a plain
 					<p :id="labelId" class="text-sm font-medium">
 						{{ dragging ? 'Drop to attach' : 'Drag receipts here' }}
 					</p>
-					<p class="text-xs text-[color:var(--bb-text-muted)]">
+					<p class="text-xs text-(--bb-text-muted)">
 						PNG, JPG or PDF · up to 5 files · 5 MB each
 					</p>
 					<BbButton variant="outline" @click="open">Browse files</BbButton>
@@ -356,7 +356,7 @@ there is no separate "selected files" API. Removal is a plain
 				<span class="min-w-0 flex-1 truncate text-sm font-medium">{{
 					file.name
 				}}</span>
-				<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
+				<span class="shrink-0 text-xs text-(--bb-text-muted)">{{
 					formatSize(file.size)
 				}}</span>
 				<BbButton
@@ -526,7 +526,7 @@ from the validated model:
 	<div class="csv-import">
 		<div class="csv-import__header">
 			<p class="text-sm font-medium">Import contacts</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				CSV export from your previous CRM · a header row is required
 			</p>
 		</div>
@@ -554,9 +554,7 @@ from the validated model:
 					<p :id="labelId" class="text-sm font-medium">
 						{{ dragging ? 'Drop your CSV' : 'Drag a CSV export here' }}
 					</p>
-					<p class="text-xs text-[color:var(--bb-text-muted)]">
-						.csv only · up to 1 MB
-					</p>
+					<p class="text-xs text-(--bb-text-muted)">.csv only · up to 1 MB</p>
 					<BbButton variant="outline" @click="open">Choose file</BbButton>
 				</div>
 			</template>
@@ -570,7 +568,7 @@ from the validated model:
 				}}</span>
 				<span
 					v-if="columns.length"
-					class="shrink-0 text-xs text-[color:var(--bb-text-muted)]"
+					class="shrink-0 text-xs text-(--bb-text-muted)"
 				>
 					{{ columns.length }} columns detected
 				</span>
@@ -830,7 +828,7 @@ transfer is in flight.
 				<span class="min-w-0 truncate text-sm font-medium">{{
 					file.name
 				}}</span>
-				<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
+				<span class="shrink-0 text-xs text-(--bb-text-muted)">{{
 					statusLabel
 				}}</span>
 			</div>
@@ -1035,7 +1033,7 @@ form library can mark the field touched and run blur-time validation.
 					<p :id="labelId" class="text-sm font-medium">
 						{{ dragging ? 'Drop to attach' : 'Attach supporting PDFs' }}
 					</p>
-					<p class="text-xs text-[color:var(--bb-text-muted)]">
+					<p class="text-xs text-(--bb-text-muted)">
 						PDF only · up to 4 files · 10 MB each
 					</p>
 					<BbButton variant="outline" @click="open">Browse</BbButton>

package/dist/ai/BbIcon.md

@@ -36,14 +36,10 @@ The full catalog of every icon-accepting surface lives in the **Icons Policy**
 
 ```vue
 <template>
-	<div
-		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-sm flex-col gap-2 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">API status</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
-				Last checked 2 minutes ago
-			</p>
+			<p class="text-xs text-(--bb-text-muted)">Last checked 2 minutes ago</p>
 		</div>
 		<ul class="flex flex-col gap-1.5 text-sm">
 			<li
@@ -142,10 +138,13 @@ The `icon` prop takes a name in one of three forms:
   the same shape as `mdi:home` / `lucide:check`, so the source of every icon is
   legible without inferring it from a missing prefix.
 
-Discovery-first: **only use names you have verified exist** — a missing icon
-**throws at mount** (dev shows an actionable Vite overlay with the exact
-`npm install` fix). Never guess a name. See the Icons Policy for the discovery
-workflow and the heroicons `-20-`/`-16-` size-variant caveat.
+Discovery-first: **only use names you have verified exist** — a name that does
+not resolve renders the **built-in placeholder** (a question mark in a circle,
+tagged `data-bb-icon-missing="<name>"`) and logs one `console.error` with the
+exact fix; dev also shows it as a Vite overlay. It never throws, so the tree
+around it stays mounted and the gap is visible where the icon should be. Never
+guess a name. See the Icons Policy for the discovery workflow and the heroicons
+`-20-`/`-16-` size-variant caveat.
 
 **The same glyph across collections, plus a local icon**
 
@@ -153,19 +152,19 @@ workflow and the heroicons `-20-`/`-16-` size-variant caveat.
 <div class="flex items-center gap-3">
 	<div class="flex flex-col items-center gap-1">
 		<BbIcon icon="lucide:heart" size="lg" />
-		<span class="text-xs text-[color:var(--bb-text-muted)]">lucide</span>
+		<span class="text-xs text-(--bb-text-muted)">lucide</span>
 	</div>
 	<div class="flex flex-col items-center gap-1">
 		<BbIcon icon="heroicons:heart" size="lg" />
-		<span class="text-xs text-[color:var(--bb-text-muted)]">heroicons</span>
+		<span class="text-xs text-(--bb-text-muted)">heroicons</span>
 	</div>
 	<div class="flex flex-col items-center gap-1">
 		<BbIcon icon="mdi:heart" size="lg" />
-		<span class="text-xs text-[color:var(--bb-text-muted)]">mdi</span>
+		<span class="text-xs text-(--bb-text-muted)">mdi</span>
 	</div>
 	<div class="flex flex-col items-center gap-1">
 		<BbIcon icon="local:sparkles" size="lg" />
-		<span class="text-xs text-[color:var(--bb-text-muted)]">local</span>
+		<span class="text-xs text-(--bb-text-muted)">local</span>
 	</div>
 </div>
 ```
@@ -176,18 +175,18 @@ with full `local:` literals from that folder — the canonical brand-mark demo.
 **Every `local:` name in this guide is one of _this repository's_ fixture SVGs**
 (`clock`, `loader`, `check_circle`, `alert_circle`, …). They are illustrative,
 not a shipped set: copy the pattern, not the names. In your project a
-`local:` name resolves only if `<name>.svg` exists in your own `iconDir`, and a
-missing one throws at mount.
+`local:` name resolves only if `<name>.svg` exists in your own `iconDir`; a
+missing one renders the placeholder and logs which file is absent.
 
 **Brand marks via local: — deploy stages**
 
 ```vue
 <template>
-	<div class="max-w-sm rounded-[var(--bb-radius)] border p-3">
+	<div class="max-w-sm rounded-(--bb-radius) border p-3">
 		<div class="flex items-center justify-between gap-3">
 			<div class="min-w-0">
 				<p class="truncate text-sm font-medium">acme/storefront</p>
-				<p class="text-xs text-[color:var(--bb-text-muted)]">
+				<p class="text-xs text-(--bb-text-muted)">
 					Deploy #482 · production · {{ index + 1 }}/{{ stages.length }}
 				</p>
 			</div>
@@ -216,6 +215,10 @@ type Stage = {
 // literal so the production scanner bundles it — never `local:${name}`. The
 // glyph is decorative beside the stage label, so no `label` prop.
 const stages: Stage[] = [
+	// `local:*` names resolve against YOUR `iconDir` — these four are this
+	// repository's fixture SVGs. Copied into another project, each one throws
+	// at mount until a `<name>.svg` of your own exists there (or swap them for
+	// `lucide:*` names, which need no files).
 	{ label: 'Queued', icon: 'local:clock', tone: 'stage--muted' },
 	{ label: 'Building', icon: 'local:loader', tone: 'stage--active' },
 	{ label: 'Deployed', icon: 'local:check_circle', tone: 'stage--active' },
@@ -245,16 +248,21 @@ const onAdvance = () => {
 </style>
 ```
 
-#### The static-literal production constraint
-
-Icon names **must be static string literals**. Production builds scan source for
-`provider:name` literals and bundle only those — a name assembled at runtime
-(`` `lucide:${kind}` ``) is invisible to the scanner and **missing in
-production**. Map dynamic state to full literals instead — a lookup object of
-complete names, exactly as the deploy-stages companion does (`stages[i].icon`
-holds `'local:clock'`, not a concatenation). An icon used only in a
-`.stories.ts` / `.test.ts` must also appear as a literal in a scanned source
-file, since those are excluded from the scan.
+#### The literal-or-whitelist constraint
+
+Provider icons ship only when the plugin can see them. It reads the **whole
+project** as bytes — every file under the Vite root, PHP and JSON and SQL
+included, minus gitignored, hidden, binary, `node_modules`/`vendor` and
+excluded paths — for `provider:name` literals, and bundles exactly those (plus
+`iconWhitelist`). `local:` ships everything. **Dev registers the same set**, so
+a name assembled at runtime (`` `lucide:${kind}` ``) renders the placeholder
+on first render in dev, not after deploy. Map dynamic state to full literals —
+a lookup object of complete names, exactly as the deploy-stages companion does
+(`stages[i].icon` holds `'local:clock'`, not a concatenation) — or, when the
+name really is composed at runtime or comes from a database, list it in the
+plugin's `iconWhitelist` (`'lucide:circle-check'`, or a glob such as
+`'lucide:calendar-*'`). An icon used only in a `.stories.ts` / `.test.ts` file
+is scanned like any other file.
 
 ```vue
 <script setup lang="ts">
@@ -264,7 +272,8 @@ const STATUS_ICON = {
 	pending: 'lucide:clock',
 	failed: 'lucide:circle-x',
 } as const;
-// Wrong: `lucide:${status}` — never bundled, broken in production.
+// Wrong: `lucide:${status}` — never scanned; placeholder in dev AND prod
+// (unless every value is in the plugin's `iconWhitelist`).
 </script>
 
 <template>
@@ -289,13 +298,13 @@ behave exactly as with registry icons.
 ```vue
 <template>
 	<div
-		class="flex max-w-sm flex-col items-center gap-2 rounded-[var(--bb-radius)] border p-4 text-center"
+		class="flex max-w-sm flex-col items-center gap-2 rounded-(--bb-radius) border p-4 text-center"
 	>
-		<span class="text-[color:var(--bb-text-muted)]">
+		<span class="text-(--bb-text-muted)">
 			<BbIcon :icon="memberMark" size="2xl" />
 		</span>
 		<p class="text-sm font-medium">No members yet</p>
-		<p class="text-xs text-[color:var(--bb-text-muted)]">
+		<p class="text-xs text-(--bb-text-muted)">
 			Invite your team to start assigning issues on Northwind.
 		</p>
 		<BbButton variant="primary">Invite member</BbButton>
@@ -349,7 +358,9 @@ deploy-stages companions both color the row wrapper; the icon tracks it.
   scale library-wide; the defaults above apply when unset.
 - **Plugin required** — `BbIcon` resolves names through the
   `virtual:bitboss-ui/icons` module the platform plugin provides; without the
-  Vue/Nuxt/Inertia plugin installed it throws a "Failed to load icons" error.
+  Vue/Nuxt/Inertia plugin installed it throws a "Failed to load icons" error
+  (a setup fault — a merely missing NAME never throws, it renders the
+  placeholder).
   Provider sets (`@iconify-json/*`) are auto-discovered from `node_modules`;
   `local:*` comes from `iconDir` (default `./assets/icons` on Nuxt).
 - **SSR / Nuxt** — icons resolve during `onServerPrefetch`, so server-rendered

package/dist/ai/BbIndicator.md

@@ -189,11 +189,11 @@ when the inbox clears.
 ```vue
 <template>
 	<div
-		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
+		class="flex max-w-sm items-center justify-between gap-3 rounded-(--bb-radius) border p-3"
 	>
 		<div class="min-w-0">
 			<p class="truncate text-sm font-medium">Northwind</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">{{ statusLine }}</p>
+			<p class="text-xs text-(--bb-text-muted)">{{ statusLine }}</p>
 		</div>
 		<div class="flex items-center gap-1.5">
 			<BbIndicator :text="count || undefined" variant="destructive">

package/dist/ai/BbNumberInput.md

@@ -58,10 +58,10 @@ project can go all-floating without touching call sites.
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-sm gap-3 rounded-(--bb-radius) border p-4">
 		<div>
 			<p class="text-sm font-medium">Inventory counts</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Same field, three label placements — pick one per product.
 			</p>
 		</div>
@@ -131,10 +131,10 @@ The same messaging surface as the rest of the family:
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-sm gap-3 rounded-(--bb-radius) border p-4">
 		<div>
 			<p class="text-sm font-medium">Team seats · Pro plan</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Hint states the range; business caps surface as errors.
 			</p>
 		</div>
@@ -183,10 +183,10 @@ keyboards work without configuration.
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-sm gap-3 rounded-(--bb-radius) border p-4">
 		<div>
 			<p class="text-sm font-medium">Office climate · Floor 3</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Clamped 16–28 °C · whole degrees only.
 			</p>
 		</div>
@@ -235,12 +235,10 @@ stays free while the buttons move in fixed increments.
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
+	<div class="grid max-w-sm gap-2 rounded-(--bb-radius) border p-3">
 		<div>
 			<p class="text-sm font-medium">USB-C Cable (2 m)</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
-				$12.50 each · 10 in stock
-			</p>
+			<p class="text-xs text-(--bb-text-muted)">$12.50 each · 10 in stock</p>
 		</div>
 		<BbNumberInput
 			v-model="quantity"
@@ -299,10 +297,10 @@ model stays a clean number.
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-sm gap-3 rounded-(--bb-radius) border p-4">
 		<div>
 			<p class="text-sm font-medium">Line item · INV-2048</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Currency stays in the chrome; the model is a clean number.
 			</p>
 		</div>
@@ -354,10 +352,10 @@ yourself if an async check must settle first.
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-sm gap-3 rounded-(--bb-radius) border p-4">
 		<div>
 			<p class="text-sm font-medium">Invoice credit</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Clear the budget anytime; coupon check is visual-only loading.
 			</p>
 		</div>
@@ -433,10 +431,10 @@ watch(coupon, (value) => {
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-sm gap-3 rounded-(--bb-radius) border p-4">
 		<div>
 			<p class="text-sm font-medium">Seat allocation</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Error, disabled, and readonly — same chrome, different affordances.
 			</p>
 		</div>
@@ -490,10 +488,10 @@ the label is embedded in the field, so the layout is forced vertical and
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+	<div class="grid max-w-sm gap-3 rounded-(--bb-radius) border p-3">
 		<div>
 			<p class="text-sm font-medium">Package · BOX-4412</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Shipping dimensions · compact density throughout.
 			</p>
 		</div>
@@ -534,10 +532,10 @@ quota screens do it.
 
 ```vue
 <template>
-	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4">
+	<div class="grid max-w-md gap-3 rounded-(--bb-radius) border p-4">
 		<div>
 			<p class="text-sm font-medium">API rate limits</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Applied per key. Changes take effect immediately.
 			</p>
 		</div>

package/dist/ai/BbOffCanvas.md

@@ -44,11 +44,11 @@ for buttons inside the body, and footer buttons simply set the model back to
 ```vue
 <template>
 	<div
-		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
+		class="flex max-w-sm items-center justify-between gap-3 rounded-(--bb-radius) border p-3"
 	>
 		<div class="min-w-0">
 			<p class="m-0 text-sm font-medium">Workspace</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				3 updates since yesterday
 			</p>
 		</div>
@@ -59,7 +59,7 @@ for buttons inside the body, and footer buttons simply set the model back to
 			<div class="grid gap-3 text-sm">
 				<div v-for="entry in activity" :key="entry.id" class="grid gap-0.5">
 					<p class="m-0">{{ entry.text }}</p>
-					<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+					<p class="m-0 text-xs text-(--bb-text-muted)">
 						{{ entry.when }}
 					</p>
 				</div>
@@ -114,9 +114,7 @@ dimension `size` controls.
 
 ```vue
 <template>
-	<div
-		class="flex max-w-md flex-wrap gap-2 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-md flex-wrap gap-2 rounded-(--bb-radius) border p-3">
 		<BbButton
 			v-for="edge in edges"
 			:key="edge"
@@ -234,11 +232,11 @@ This companion seeds typed filter state and resets it in place.
 ```vue
 <template>
 	<div
-		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
+		class="flex max-w-sm items-center justify-between gap-3 rounded-(--bb-radius) border p-3"
 	>
 		<div class="min-w-0">
 			<p class="m-0 text-sm font-medium">Invoices</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				{{ matchingLabel }}
 			</p>
 		</div>
@@ -321,10 +319,8 @@ record" action to `BbButton`'s `href` rather than a click handler.
 
 ```vue
 <template>
-	<div class="grid max-w-sm gap-1 rounded-[var(--bb-radius)] border p-1">
-		<p
-			class="m-0 px-2 pt-1.5 text-xs font-medium text-[color:var(--bb-text-muted)]"
-		>
+	<div class="grid max-w-sm gap-1 rounded-(--bb-radius) border p-1">
+		<p class="m-0 px-2 pt-1.5 text-xs font-medium text-(--bb-text-muted)">
 			Members
 		</p>
 		<BbButton
@@ -340,7 +336,7 @@ record" action to `BbButton`'s `href` rather than a click handler.
 					:alt="member.name"
 					size="32"
 					:src="member.src"
-					:timeout="demoAvatarTimeout"
+					:timeout="avatarTimeout"
 				>
 					{{ member.initials }}
 				</BbAvatar>
@@ -355,7 +351,7 @@ record" action to `BbButton`'s `href` rather than a click handler.
 					:alt="selected.name"
 					size="56"
 					:src="selected.src"
-					:timeout="demoAvatarTimeout"
+					:timeout="avatarTimeout"
 				>
 					{{ selected.initials }}
 				</BbAvatar>
@@ -372,7 +368,7 @@ record" action to `BbButton`'s `href` rather than a click handler.
 					:key="row.label"
 					class="flex items-baseline justify-between gap-3"
 				>
-					<dt class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">
+					<dt class="shrink-0 text-xs text-(--bb-text-muted)">
 						{{ row.label }}
 					</dt>
 					<dd class="m-0 truncate text-right">{{ row.value }}</dd>
@@ -396,10 +392,19 @@ record" action to `BbButton`'s `href` rather than a click handler.
 <script setup lang="ts">
 import { computed, ref } from 'vue';
 import { BbAvatar, BbBadge, BbButton, BbOffCanvas } from 'bitboss-ui';
-import {
-	demoAvatarTimeout,
-	demoFaces,
-} from '@/components/BbAvatar/examples/demoAvatars';
+
+// Self-contained demo data. Any image URL works here — these are stock
+// portraits; swap in your own. `timeout` is BbAvatar's deadline before the
+// fallback shows (default 400ms, meant for SSR/slow networks): a remote demo
+// origin needs headroom or the initials flash in first. See the guide §
+// "Slow networks, SSR and the timeout prop".
+const avatarTimeout = 4000;
+const face = (photoId: string) =>
+	`https://images.unsplash.com/${photoId}?w=256&h=256&fit=crop&crop=faces&auto=format`;
+const faces = {
+	ada: face('photo-1494790108377-be9c29b29330'),
+	grace: face('photo-1438761681033-6461ffad8d80'),
+};
 
 type MemberStatus = 'Active' | 'Away';
 
@@ -427,7 +432,7 @@ const members: Member[] = [
 		team: 'Platform',
 		status: 'Active',
 		statusVariant: 'soft-green',
-		src: demoFaces.ada,
+		src: faces.ada,
 	},
 	{
 		id: 2,
@@ -439,7 +444,7 @@ const members: Member[] = [
 		team: 'Billing',
 		status: 'Away',
 		statusVariant: 'soft-amber',
-		src: demoFaces.grace,
+		src: faces.grace,
 	},
 ];
 
@@ -497,11 +502,11 @@ treatment in the list, and account/sign-out sit in the footer.
 ```vue
 <template>
 	<div
-		class="flex max-w-sm items-center justify-between gap-2 rounded-[var(--bb-radius)] border p-2"
+		class="flex max-w-sm items-center justify-between gap-2 rounded-(--bb-radius) border p-2"
 	>
 		<div class="min-w-0">
 			<p class="m-0 truncate text-sm font-medium">Acme Billing</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">Workspace</p>
+			<p class="m-0 text-xs text-(--bb-text-muted)">Workspace</p>
 		</div>
 		<BbButton
 			aria-label="Open navigation"
@@ -514,9 +519,7 @@ treatment in the list, and account/sign-out sit in the footer.
 	</div>
 	<BbOffCanvas v-model="open" side="left" size="xs" title="Acme Billing">
 		<nav aria-label="Primary" class="grid gap-1">
-			<p
-				class="m-0 px-1 pb-0.5 text-xs font-medium text-[color:var(--bb-text-muted)]"
-			>
+			<p class="m-0 px-1 pb-0.5 text-xs font-medium text-(--bb-text-muted)">
 				Navigate
 			</p>
 			<BbButton
@@ -668,12 +671,13 @@ dismiss with the same motion:
 
 Give panels the same `stack` name and they step back behind one another as you
 drill in: opening a child shifts the parent inward by `stack-gap` (default
-`60`px), leaving a peeking band of it visible so the hierarchy reads clearly.
+`60`px), leaving a peeking band of it visible so the hierarchy reads clearly. When the child closes, the parent steps forward again in the same motion, in lockstep with the child sliding out.
 Closing the child brings the parent forward. Panels with **different names (or
 none) are independent** and simply layer by open order.
 
-Only the top two open panels keep their dimmed/blurred backdrop; deeper ones go
-transparent, so a three-deep stack does not stack three backdrops. Use a stack
+Only the bottom-most open panel paints the dimmed/blurred backdrop; every panel
+above it renders a transparent one, so a three-deep stack does not stack three
+backdrops and a child closing never brightens or re-blurs what is behind. Use a stack
 for master → detail flows where the trail should stay visible; if the parent
 should be fully replaced instead, that is what `BbDialog`'s `stack` (which swaps
 rather than peeks) is for.
@@ -683,13 +687,11 @@ rather than peeks) is for.
 ```vue
 <template>
 	<div
-		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
+		class="flex max-w-sm items-center justify-between gap-3 rounded-(--bb-radius) border p-3"
 	>
 		<div class="min-w-0">
 			<p class="m-0 text-sm font-medium">Team</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
-				Drill into a member
-			</p>
+			<p class="m-0 text-xs text-(--bb-text-muted)">Drill into a member</p>
 		</div>
 		<BbButton variant="outline" @click="listOpen = true">
 			Team members
@@ -724,13 +726,11 @@ rather than peeks) is for.
 	>
 		<div v-if="selected" class="grid gap-2 text-sm">
 			<p class="m-0">
-				<span class="text-xs text-[color:var(--bb-text-muted)]">Role</span
-				><br />
+				<span class="text-xs text-(--bb-text-muted)">Role</span><br />
 				{{ selected.role }}
 			</p>
 			<p class="m-0">
-				<span class="text-xs text-[color:var(--bb-text-muted)]">Joined</span
-				><br />
+				<span class="text-xs text-(--bb-text-muted)">Joined</span><br />
 				{{ selected.joined }}
 			</p>
 		</div>
@@ -809,11 +809,11 @@ half-typed edits never survive a close.
 ```vue
 <template>
 	<div
-		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
+		class="flex max-w-sm items-center justify-between gap-3 rounded-(--bb-radius) border p-3"
 	>
 		<div class="min-w-0">
 			<p class="m-0 text-sm font-medium">INV-2043</p>
-			<p class="m-0 truncate text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 truncate text-xs text-(--bb-text-muted)">
 				{{ saved }}
 			</p>
 		</div>
@@ -880,11 +880,11 @@ genuine click that starts and ends on the backdrop (≤4px travel) does.
 ```vue
 <template>
 	<div
-		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
+		class="flex max-w-sm items-center justify-between gap-3 rounded-(--bb-radius) border p-3"
 	>
 		<div class="min-w-0">
 			<p class="m-0 text-sm font-medium">PR #1842</p>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				Needs a reviewer before merge
 			</p>
 		</div>
@@ -905,7 +905,7 @@ genuine click that starts and ends on the backdrop (≤4px travel) does.
 				label="Reviewer"
 				placeholder="Name or email"
 			/>
-			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+			<p class="m-0 text-xs text-(--bb-text-muted)">
 				Backdrop and Escape stay locked — resolve from the footer.
 			</p>
 		</div>