bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.41

package/dist/ai/BbBadge.md

@@ -4,10 +4,25 @@
 
 - Safety level: **Consumer API**
 - Group: **Feedback**
-- Description: Displays compact status counters or labels, the floating mode acts as notification dot.
+- Description: Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbBadge.md](./source/BbBadge.md)
 
+## Reachable through `BbBadge`
+
+`BbBadge` mounts other components (all of them: _Component tree_, near the end). These are the parts of its API that land inside them. Prefer these over `:deep()` on an inner class (allowed, unsupported: it can break on upgrade) — and never an import of an internal component.
+
+| pt part | Lands on | In |
+| --- | --- | --- |
+| `pt:spinner` | the root of `BbSpinner` | `BbSpinner` ([contract](./BbSpinner.md)) |
+| `pt:icon` | the root of `BbIcon` | `BbIcon` ([contract](./BbIcon.md)) |
+
+**CSS variables you can set through those parts** — declared deeper in the tree, so set one on the part that reads it (`pt:<part>="[--name:value]"`), never on `BbBadge`'s root:
+
+| Variable | Set through | Declared by | What it is |
+| --- | --- | --- | --- |
+| `--w` | `pt:icon` | `BbIcon` | `--w` is set inline by BbIcon from the size prop. The `initial` default seals it: without it an ancestor's `--w` (e.g. a dropdown's width bridge) would inherit in and size the icon. The `--size` indirection stays so higher-specificity rules (e.g. `.bb-badge .bb-icon`) can re-point it. |
+
 ## Usage & Guidelines
 
 ### When to use
@@ -43,7 +58,7 @@ Drive the look with the `variant` ladder; put the copy in the default slot.
 The built-ins are `primary`, `secondary`, `destructive`, and `outline` — a floor,
 not the whole vocabulary. Projects register extra tones via the plugin's
 `badgeVariants` option; registration extends the TypeScript union and yields a
-`bb-badge--<name>` class hook — you own the CSS (`--bg` and `--color` are the
+`bb-badge--<name>` class hook — you own the CSS (`--bg` and `--fg` are the
 tokens to set). **If your page needs a tone that isn't in the list, register it
 and style it** — that is the sanctioned path, not a reason to force the design
 into `secondary`/`outline`. For a genuinely one-off accent, override `--bg`
@@ -56,18 +71,23 @@ the soft palette from
 [design language guide](./guides/design-language.md) § Using color
 (`soft-gray` / `soft-blue` / `soft-green` / `soft-amber` / `soft-red`) and style
 `.bb-badge--<name>` in your project stylesheet. Never invent `variant="success"`
-— that name is not built-in and ships no CSS.
+— that name is not built-in and ships no CSS. The example below uses the soft
+names: in your app it type-checks only after the `badgeVariants` registration
+and renders styled only with that CSS — both are in the linked section.
+
+`variant="none"` renders the badge with no variant class at all — the base
+tokens stay until you set `--bg` / `--fg` on it. It is the same escape hatch
+`BbButton` has; prefer a registered variant or a one-off `--bg` / `--fg`
+override on a normal variant.
 
 **Invoice status pills + plan tiers**
 
 ```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">Invoice status</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Soft accents for a small, fixed status set — not every row color.
 			</p>
 		</div>
@@ -80,16 +100,14 @@ the soft palette from
 			>
 				<span class="min-w-0 truncate">
 					<span class="font-medium">{{ row.number }}</span>
-					<span class="text-[color:var(--bb-text-muted)]">
-						· {{ row.client }}</span
-					>
+					<span class="text-(--bb-text-muted)"> · {{ row.client }}</span>
 				</span>
 				<BbBadge size="sm" :variant="row.variant">{{ row.status }}</BbBadge>
 			</li>
 		</ul>
 
 		<div class="flex flex-wrap items-center gap-1.5 border-t pt-3">
-			<span class="mr-1 text-xs text-[color:var(--bb-text-muted)]">Plan</span>
+			<span class="mr-1 text-xs text-(--bb-text-muted)">Plan</span>
 			<BbBadge size="sm" variant="soft-gray">Free</BbBadge>
 			<BbBadge size="sm" variant="soft-blue">Pro</BbBadge>
 			<BbBadge size="sm" variant="soft-amber">Enterprise</BbBadge>
@@ -145,19 +163,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,
@@ -166,10 +184,10 @@ const invoices: InvoiceRow[] = [
 .bb-badge.bb-badge--soft-amber,
 .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>
 ```
@@ -186,17 +204,15 @@ yourself (`99+`) — there is no `max` prop.
 <template>
 	<nav
 		aria-label="Mail folders"
-		class="flex max-w-56 flex-col gap-0.5 rounded-[var(--bb-radius)] border p-1.5 text-sm"
+		class="flex max-w-56 flex-col gap-0.5 rounded-(--bb-radius) border p-1.5 text-sm"
 	>
 		<a
 			v-for="folder in folders"
 			:key="folder.href"
 			:aria-current="folder.active ? 'page' : undefined"
-			class="flex items-center justify-between gap-2 rounded-[var(--bb-radius-sm)] px-2 py-1"
+			class="flex items-center justify-between gap-2 rounded-(--bb-radius-sm) px-2 py-1"
 			:class="
-				folder.active
-					? 'bg-[color:var(--bb-muted)] font-medium'
-					: 'text-[color:var(--bb-text)]'
+				folder.active ? 'bg-(--bb-muted) font-medium' : 'text-(--bb-text)'
 			"
 			:href="folder.href"
 		>
@@ -309,9 +325,12 @@ state in the handler. Prefer `secondary` / `outline` for filter chips; reserve
 ```
 
 The clear button inherits the variant's foreground, so it reads on every surface
-— light on a filled `primary`, dark on a `secondary`/`outline`. Set
-`clearable-label` for the button's accessible name (defaults to the localized
-`badge.clearLabel`).
+— light on a filled `primary`, dark on a `secondary`/`outline`. By default its
+accessible name composes the localized verb with the badge's own text — a chip
+reading "Italy" announces "Remove Italy", with no per-chip wiring. Set
+`clearable-label` only when that composition is wrong for the context (it
+replaces the whole name). With a `BbBadgeButton` body the composition is
+skipped and the button falls back to the bare localized `badge.clearLabel`.
 
 Icons combine with `clearable`: a **`prepend:icon`** stays (it leads the label);
 an **`append:icon`** shares the trailing slot with the clear button — the icon
@@ -352,16 +371,14 @@ button. Reserve `sm` for dense in-table status pills, and omit `size`
 
 ```vue
 <template>
-	<div
-		class="flex max-w-md flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-md flex-col gap-2 rounded-(--bb-radius) border p-3">
 		<div class="flex items-center justify-between gap-2">
 			<p class="text-sm font-medium">Invoices</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">{{ resultLabel }}</p>
+			<p class="text-xs text-(--bb-text-muted)">{{ resultLabel }}</p>
 		</div>
 
 		<div class="flex flex-wrap items-center gap-1.5">
-			<span class="text-xs text-[color:var(--bb-text-muted)]">Filtered by</span>
+			<span class="text-xs text-(--bb-text-muted)">Filtered by</span>
 			<BbBadge
 				v-for="filter in filters"
 				:key="filter.id"
@@ -536,9 +553,9 @@ anchor an overlay directly — no wrapper element, no `defineExpose`:
 ```vue
 <template>
 	<div
-		class="flex max-w-sm flex-wrap items-center gap-2 rounded-[var(--bb-radius)] border p-3"
+		class="flex max-w-sm flex-wrap items-center gap-2 rounded-(--bb-radius) border p-3"
 	>
-		<span class="text-xs text-[color:var(--bb-text-muted)]">Filters</span>
+		<span class="text-xs text-(--bb-text-muted)">Filters</span>
 
 		<BbBadge
 			append:icon="lucide:chevron-down"
@@ -549,7 +566,7 @@ anchor an overlay directly — no wrapper element, no `defineExpose`:
 			variant="secondary"
 			@click:clear="status = 'Open'"
 		>
-			<BbBadgeButton ref="statusChip">Status: {{ status }}</BbBadgeButton>
+			<BbBadgeButton ref="status-chip">Status: {{ status }}</BbBadgeButton>
 		</BbBadge>
 
 		<!-- The ref resolves to the rendered button element, so it anchors the
@@ -578,7 +595,7 @@ type Status = (typeof options)[number];
 
 const status = ref<Status>('Open');
 const open = ref(false);
-const statusChip = useTemplateRef('statusChip');
+const statusChip = useTemplateRef('status-chip');
 
 const onPick = (option: Status) => {
 	status.value = option;
@@ -609,7 +626,7 @@ in dev and falls back to `md`). Keep one size per cluster.
 
 There is no `color` prop. To paint a single badge outside the variant system,
 override the CSS custom properties the variants drive — `--bg` for the
-background, `--color` for the text — inline:
+background, `--fg` for the text — inline:
 
 **A one-off accent via the --bg token**
 
@@ -621,7 +638,7 @@ background, `--color` for the text — inline:
 ```
 
 Pair a dark custom `--bg` with a light-text variant (`primary`), or set
-`--color` too, and check contrast yourself. For anything recurring, register a
+`--fg` too, and check contrast yourself. For anything recurring, register a
 variant instead so the styling stays in the design system.
 
 ### Anatomy and CSS hooks
@@ -635,12 +652,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>
 ```
@@ -654,7 +671,130 @@ 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
+
+`pt` reaches a named part with a class list — or, in the object form, a
+style and attributes — optionally only while a state is on. Parts: `root`,
+`icon` (every content glyph — the `icon`-mode glyph, `prepend:icon`,
+`append:icon`; a broadcast), `spinner` (the loading glyph, which stands in
+for whichever icon it replaces), `text` (the label span, which owns the
+truncation) and `clear` (the ✕ that removes the badge). The `__body` wrapper
+is layout, not a part. State: `loading`.
+
+Invoice API method pills, restyled through those parts: `pt:icon` is a
+broadcast (prepend, append, and the loading spinner all recede),
+`pt:text` is the method label in mono. Soft method hues are status — see
+[design language](./guides/design-language.md) § Using color — not a pt
+costume.
+
+**pt:icon — method badges, a broadcast**
+
+```vue
+<template>
+	<div class="max-w-2xl">
+		<ul class="flex flex-col gap-1.5 text-sm">
+			<li
+				v-for="endpoint in endpoints"
+				:key="`${endpoint.method}:${endpoint.path}`"
+				class="flex min-w-0 items-center gap-2"
+			>
+				<BbBadge
+					:append:icon="endpoint.append"
+					:prepend:icon="endpoint.icon"
+					pt:icon="opacity-70"
+					pt:text="font-mono"
+					size="lg"
+					:variant="METHOD_VARIANT[endpoint.method]"
+					>{{ endpoint.method }}</BbBadge
+				>
+				<code class="truncate font-mono text-xs">{{ endpoint.path }}</code>
+			</li>
+		</ul>
+		<div class="mt-3 flex items-center gap-2 text-xs text-(--bb-text-muted)">
+			<BbBadge
+				loading
+				prepend:icon="lucide:plus"
+				pt:icon="opacity-40"
+				pt:text="font-mono"
+				size="lg"
+				variant="soft-green"
+				>POST</BbBadge
+			>
+			<span>
+				Saving a draft — the spinner takes the prepend slot, same
+				<code>pt:icon</code>.
+			</span>
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbBadge } from 'bitboss-ui';
+import type { BbBadgeProps, IconType } from 'bitboss-ui';
+
+type Method = 'GET' | 'POST' | 'DELETE';
+
+type Endpoint = {
+	method: Method;
+	path: string;
+	icon: IconType;
+	append?: IconType;
+};
+
+// Soft status palette — method hue, not action intent (no primary/destructive).
+const METHOD_VARIANT: Record<Method, BbBadgeProps['variant']> = {
+	GET: 'soft-blue',
+	POST: 'soft-green',
+	DELETE: 'soft-red',
+};
+
+// Invoice API methods, restyled through passthrough: `pt:icon` is a broadcast
+// (prepend, append, and the loading spinner all recede), `pt:text` is the
+// method label in mono. The ✕ of a clearable badge is its own part, `clear`.
+const endpoints: Endpoint[] = [
+	{ method: 'GET', path: '/v1/invoices', icon: 'lucide:download' },
+	{
+		method: 'POST',
+		path: '/v1/invoices',
+		icon: 'lucide:plus',
+		append: 'lucide:arrow-right',
+	},
+	{ method: 'DELETE', path: '/v1/invoices/:id', icon: 'lucide:trash-2' },
+];
+</script>
+
+<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color.
+     Non-scoped so variant classes on the child badge receive the accents. -->
+<style>
+.bb-badge.bb-badge--soft-blue {
+	--accent: var(--bb-info);
+}
+.bb-badge.bb-badge--soft-green {
+	--accent: var(--bb-success);
+}
+.bb-badge.bb-badge--soft-red {
+	--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));
+	--bw: 1px;
+	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
+	--ring-color: color-mix(in oklab, var(--accent) 45%, transparent);
+}
+</style>
+```
+
+The full grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
+A `pt` value written in `<script>` (a constant, a preset, a wrapper's
+`pt` prop) is typed as `BbBadgeProps['pt']`, never an imported `PtValue`: see
+[passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
 
 ### Works well with
 
@@ -695,8 +835,12 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 - An icon-only badge (`icon`) has no visible text; the default slot is rendered
   as a screen-reader-only label — never leave it empty. In button mode that
   label is also the **button's accessible name**, so it is doubly required.
-- The `clearable` button has an accessible name from `clearable-label` (or the
-  localized `badge.clearLabel`).
+  `bitboss-ui check` and the ESLint rule `bitboss-ui/require-accessible-name`
+  report an empty one as an error.
+- The `clearable` button's accessible name is composed by default: the
+  localized `badge.clearLabel` verb plus the badge body's text ("Remove
+  Italy"). `clearable-label` replaces the whole name; with a `BbBadgeButton`
+  body the composition is skipped (bare verb only).
 - A clickable **and** clearable badge is two tab stops (body, then clear). That
   is intended: two actions, two controls.
 - Keyboard focus on either control rings the whole pill, so the focused target
@@ -708,25 +852,81 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
+| `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: `clear`, `icon`, `root`, `spinner`, `text`. States: `loading`. 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`. In `<script>` a `pt` value is typed `BbBadgeProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `append:icon` | `string \| undefined` |  |  | Icon rendered after the label. On a `clearable` badge it shares the trailing slot with the clear button: the icon shows at rest and the clear button reveals over it on hover/focus. |
-| `clearable` | `boolean \| undefined` |  |  | Renders a trailing clear button and emits `click:clear` when pressed — turns the badge into a dismissible token (the pattern formerly served by `BbChip`). |
-| `clearableLabel` | `string \| undefined` |  |  | Accessible label for the clear button. Falls back to the localized `badge.clearLabel` key. |
+| `clearable` | `boolean \| undefined` | `false` |  | Renders a trailing clear button and emits `click:clear` when pressed — turns the badge into a dismissible token (the pattern formerly served by `BbChip`). |
+| `clearableLabel` | `string \| undefined` |  |  | Accessible label for the clear button. Rarely needed: unset, the name is **composed** from the localized `badge.clearLabel` verb and the badge's own text — "Remove Italy", not a bare "Remove" — which is already the right name in almost every case. Composition is skipped when a `BbBadgeButton` owns the body (the verb then stands alone, so the two controls do not both announce the label). Set this only to override that composed name outright. |
 | `icon` | `string \| undefined` |  |  | Renders an icon-only badge. When set, `prepend:icon` / `append:icon` are ignored and the default slot becomes the badge's visually hidden accessible label — always provide it. |
-| `loading` | `boolean \| undefined` |  |  | Shows a spinner in place of the leftmost icon, mirroring `BbButton`: it replaces the `icon` glyph or the `prepend:icon` when one is set; when the `append:icon` is the sole icon it replaces that instead (e.g. a select-activator chevron while… |
+| `loading` | `boolean \| undefined` | `false` |  | Shows a spinner in place of the leftmost icon, mirroring `BbButton`: it replaces the `icon` glyph or the `prepend:icon` when one is set; when the `append:icon` is the sole icon it replaces that instead (e.g. a select-activator chevron while the value saves), and with no icons at all it takes the leading slot. Adds a visually hidden loading announcement for screen readers. |
 | `prepend:icon` | `string \| undefined` |  |  | Icon rendered before the label. |
-| `size` | `keyof Sizes \| undefined` | `"md"` |  | Preset size of the badge. |
-| `variant` | `keyof BadgeVariantRegistry \| undefined` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Register more via the vite plugin `badgeVariants` option and style `.bb-badge--<variant>` (set `--bg` / `--color`). |
+| `size` | `'xs'` \| `'sm'` \| `'md'` \| `'lg'` \| `'xl'` \| `'2xl'` | `"md"` |  | Preset size of the badge. |
+| `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'secondary'` \| `'none'` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Register more via the vite plugin `badgeVariants` option and style `.bb-badge--<variant>` (set `--bg` / `--fg`). `'none'` renders no variant class — an escape hatch for a one-off look set through `--bg` / `--fg` on the element. |
+
+## Passthrough parts and states
+
+`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`. In `<script>`, type a `pt` value as `<Component>Props['pt']` (`<Component>Props<Row>['pt']` on a generic component); `PtValue` is not exported: `guides/passthrough.md` § Typing `pt` in `<script>`.
+
+| Part | What it is |
+| --- | --- |
+| `root` | The badge. |
+| `icon` | Every content glyph — the `icon`-mode glyph, `prepend:icon`, `append:icon` — a broadcast. The clear ✕ is not in it. |
+| `spinner` | The loading glyph. It REPLACES an icon while `loading` (on a button it joins one instead). |
+| `text` | The label span; it owns the truncation. |
+| `clear` | The ✕ that removes the badge (`clearable`). |
+
+States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
+
+| State | When it is on |
+| --- | --- |
+| `loading` | Component-wide: `loading` is on; the spinner takes an icon's place. |
 
 ## 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
 
 - `default` — scope: `object` — The badge's label content. When `icon` is set this becomes the visually hidden accessible label. Render a `BbBadgeButton` here to make the badge body interactive (the wrapper stays a passive `<span>`).
 
+## CSS custom properties
+
+Set these on the element, or on a class you put on it, to retune this component alone — the sanctioned alternative to reaching past the API with `:deep()`. They are this component's own locals — a **Set on** of `pt:<part>` means the local lives on that part's element, so set it through that entry (`pt:box="[--border-color:var(--color-green-500)]"`); the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
+
+| Property | Set on | Default | What it is |
+| --- | --- | --- | --- |
+| `--bg` | `.bb-badge` | `var(--bb-primary)` | pill fill |
+| `--fg` | `.bb-badge` | `var(--bb-primary-fg)` | label, icons and the clear glyph |
+| `--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 stroke sits between the label and the pill edge. |
+| `--border-color` | `.bb-badge` | `transparent` |  |
+| `--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 |
+| `--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 |
+| `--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(--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
+
+`BbBadge` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbBadge`, and before concluding a part, a token or a behaviour does not exist** — it may live on a component further down. How to read it:
+
+- **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbBadge`. A pt part listed as landing there is set on `BbBadge` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbBadge` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbBadge`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
+- **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`
+  - Also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
+
 ## See Also
 
-- [BbIndicator](./BbIndicator.md) — Anchors a notification bubble (count/short text) or a dot over a wrapped element, with floating and corner-placement options.
+- [BbIndicator](./BbIndicator.md) — Anchors a notification bubble (count/short text) or a dot over a wrapped element.
 - [BbAvatar](./BbAvatar.md) — Displays an avatar and has a fallback content slot.
 - [BbBadgeButton](./BbBadgeButton.md) — Makes a badge's body interactive: slotted as a direct child of BbBadge it renders the badge body as a real button/link with full BbBaseButton parity, leaving `clearable` free to remain a separate control.

package/dist/ai/BbBadgeButton.md

@@ -12,26 +12,27 @@
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `activeClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially. Ported for Inertia compatibility. |
-| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` |  |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
-| `async` | `boolean \| undefined` |  |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
-| `cacheFor` | `string \| number \| (string \| number)[] \| undefined` |  |  | Inertia: how long a prefetched response stays fresh before it is re-fetched. A single duration, or `[staleAfter, expiresAfter]`. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be in… |
+| `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: `root`. States: `disabled`. 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`. In `<script>` a `pt` value is typed `BbBadgeButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `activeClass` | `string \| undefined` | `'router-link-active'` |  | CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially. Ported for Inertia compatibility. |
+| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` | `'page'` |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
+| `async` | `boolean \| undefined` | `false` |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
+| `cacheFor` | `string \| number \| (string \| number)[] \| undefined` |  |  | Inertia: how long a prefetched response stays fresh before it is re-fetched. A single duration, or `[staleAfter, expiresAfter]`. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
 | `cacheTags` | `string \| string[] \| undefined` |  |  | Inertia: tags to file this visit's prefetch cache under, so a later request can invalidate the whole tagged group. |
 | `component` | `string \| undefined` |  |  | Inertia: the page component this visit resolves to. Rarely set by hand — the server normally decides it. |
 | `data` | `object \| undefined` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
-| `disabled` | `boolean \| undefined` |  |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"`, and prevents navigation while keeping focusable semanti… |
-| `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download. Renders a plain `<a download>` doing a native navigation — never an Inertia/router visit — so file downloads (including same-origin, `blob:` and `data:` URLs) work. Pass a string to set the suggested file… |
-| `exactActiveClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"` and `tabindex="-1"`, and prevents navigation: the link stays announced as a link but leaves the tab order. |
+| `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download. Renders a plain `<a download>` doing a native navigation — never an Inertia/router visit — so file downloads (including same-origin, `blob:` and `data:` URLs) work. Pass a string to set the suggested filename. One of the native-anchor signals alongside `target` and `external`. |
+| `exactActiveClass` | `string \| undefined` | `'router-link-exact-active'` |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
 | `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
-| `external` | `boolean \| undefined` |  |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target… |
+| `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target` and `download`. |
 | `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
 | `href` | `string \| undefined` |  |  | Hyperlink reference used when rendering as an anchor (or as an Inertia link in Inertia-enabled apps). If provided and not disabled, the component renders as an anchor/Inertia link. |
-| `instant` | `boolean \| undefined` |  |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
-| `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  | HTTP method used for Inertia navigation when `href` is provided in an Inertia-enabled app. Ignored otherwise. |
+| `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
+| `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  | HTTP method used for Inertia navigation when `href` is provided in an Inertia-enabled app. Ignored otherwise: an Inertia POST visit is `href="/orders/5/archive" method="post"`, never `to` (a `to` link is a Vue Router link and sends no method). |
 | `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
 | `onCancel` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request is cancelled. |
 | `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  | Receives the Inertia cancel token source when a request is initiated. Can be used to cancel the request. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
-| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when the server responds with VALIDATION errors — the ordinary 422 path. This is the only failure callback Inertia's `Link` accepts. `onHttpException` (server answered 5xx) and `onNetworkError` (the request… |
+| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when the server responds with VALIDATION errors — the ordinary 422 path. This is the only failure callback Inertia's `Link` accepts. `onHttpException` (server answered 5xx) and `onNetworkError` (the request never arrived) are `router.visit()` / `useForm()` options, NOT Link props — declaring them here would only paste bogus listeners onto the anchor. Use a form or an explicit visit when you need to tell them apart. |
 | `onFinish` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia after the request has finished (regardless of success or error). |
 | `only` | `string[] \| undefined` |  |  | Limits the properties that are preserved in Inertia partial reloads. |
 | `onPrefetched` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link has completed and is cached. |
@@ -39,19 +40,33 @@
 | `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  | Progress callback invoked by Inertia with the upload/download percentage when available. |
 | `onStart` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request starts. |
 | `onSuccess` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request succeeds. |
-| `pageProps` | `Record<string, unknown> \| ((currentProps: Record<string, unknown>, sharedProps: Record<string, unknown>) => Record<string, unknown>) \| null \| undefined` |  |  | Inertia: props to merge into the next page optimistically, before the server responds. Either an object or a function of the current props. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue… |
+| `pageProps` | `Record<string, unknown> \| ((currentProps: Record<string, unknown>, sharedProps: Record<string, unknown>) => Record<string, unknown>) \| null \| undefined` |  |  | Inertia: props to merge into the next page optimistically, before the server responds. Either an object or a function of the current props. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
 | `prefetch` | `string \| boolean \| string[] \| undefined` |  |  | Inertia: fetch and cache this link's page ahead of the click. `true` uses the default trigger; a string or list of strings picks them (`'mount'`, `'hover'`, `'click'`). |
-| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
-| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
-| `preserveUrl` | `boolean \| undefined` |  |  | Inertia: keep the current URL in the address bar even though the page content changes. |
-| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` |  |  | Format to use when serializing array values into the query string for Inertia requests. |
+| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` | `false` |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` | `false` |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `preserveUrl` | `boolean \| undefined` | `false` |  | Inertia: keep the current URL in the address bar even though the page content changes. |
+| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` | `'brackets'` |  | Format to use when serializing array values into the query string for Inertia requests. |
 | `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
-| `replace` | `boolean \| undefined` |  |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
-| `tag` | `ButtonTag \| undefined` |  |  | Element to render for the plain (non-link, non-router) button: - `'button'` (default) — real button semantics and keyboard behavior - `'div'` / `'span'` — a clickable box nested inside another button or link, where a nested `<button>` would… |
+| `replace` | `boolean \| undefined` | `false` |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
+| `tag` | `'button'` \| `'div'` \| `'span'` \| `'label'` | `'button'` |  | Element to render for the plain (non-link, non-router) button: - `'button'` (default) — real button semantics and keyboard behavior - `'div'` / `'span'` — a clickable box nested inside another button or link, where a nested `<button>` would be invalid markup - `'label'` — a file-upload trigger wrapping a visually hidden `<input>` Ignored when the component renders as a link/router (`href`/`to`) — those always render `<a>`/router-link. When set to a non-`button` tag the native `type`/`disabled` attributes are dropped (they're invalid off a `<button>`); disabled state is still conveyed via the `bb-base-button--disabled` class. |
 | `target` | `string \| undefined` |  |  | Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`). Ignored when rendering as a native button. |
 | `to` | `string \| wt \| bt \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |
-| `type` | `"button" \| "submit" \| "reset" \| undefined` |  |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
-| `viewTransition` | `boolean \| undefined` |  |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
+| `type` | `"button" \| "submit" \| "reset" \| undefined` | `'button'` |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
+| `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
+
+## Passthrough parts and states
+
+`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`. In `<script>`, type a `pt` value as `<Component>Props['pt']` (`<Component>Props<Row>['pt']` on a generic component); `PtValue` is not exported: `guides/passthrough.md` § Typing `pt` in `<script>`.
+
+| Part | What it is |
+| --- | --- |
+| `root` | Whichever element renders — the `<button>`, the `<a>` or the router link. A `class` on the component lands here too. The label is your slot markup. |
+
+States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
+
+| State | When it is on |
+| --- | --- |
+| `disabled` | Component-wide: the button is `disabled`. |
 
 ## Events
 
@@ -61,7 +76,45 @@
 
 - `default` — scope: `object` — The action's label — what the badge displays as its body.
 
+## CSS custom properties
+
+Set these on the element, or on a class you put on it, to retune this component alone — the sanctioned alternative to reaching past the API with `:deep()`. They are this component's own locals — a **Set on** of `pt:<part>` means the local lives on that part's element, so set it through that entry (`pt:box="[--border-color:var(--color-green-500)]"`); the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
+
+| Property | Set on | Default | What it is |
+| --- | --- | --- | --- |
+| `--bg` | `.bb-badge` | `var(--bb-primary)` | pill fill |
+| `--fg` | `.bb-badge` | `var(--bb-primary-fg)` | label, icons and the clear glyph |
+| `--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 stroke sits between the label and the pill edge. |
+| `--border-color` | `.bb-badge` | `transparent` |  |
+| `--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 |
+| `--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 |
+| `--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(--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
+
+`BbBadgeButton` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbBadgeButton`, and before concluding a part, a token or a behaviour does not exist** — it may live on a component further down. How to read it:
+
+- **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbBadgeButton`. A pt part listed as landing there is set on `BbBadgeButton` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbBadgeButton` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbBadgeButton`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
+- **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 `BbBadgeButton`'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 `BbBadgeButton`'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`.
+
+- `BbBadgeButton` _(this component)_
+  - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
+  - Also mounts `BadgeBodyContent`
+
 ## See Also
 
-- [BbBadge](./BbBadge.md) — Displays compact status counters or labels, the floating mode acts as notification dot.
+- [BbBadge](./BbBadge.md) — Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
 - [BbBaseButton](./BbBaseButton.md) — Unstyled button/link primitive: element resolution (button/anchor/router link) and the full navigation engine, with no visual chrome. Use for any clickable or navigable surface that is not a variant-first BbButton — cards, list rows, custom links.