bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbBadge.md

@@ -1,243 +1,715 @@
 # BbBadge
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Feedback**
+- Description: Displays compact status counters or labels, the floating mode acts as notification dot.
+- 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)
+
+## Usage & Guidelines
+
+### When to use
+
+`BbBadge` is a small inline pill. Use it for a status label ("Active", "Beta"),
+a short count, a removable token (`clearable`), a clickable chip (slot a
+`BbBadgeButton`), or all three at once. The label always goes in the **default
+slot**; there is no `text`/`content` prop.
+
+Pick a sibling when the marker should do more:
+
+- It's pinned over another element (an unread count on a bell, a presence dot on
+  an avatar) → `BbIndicator`.
+- The token is an _input_ for entering free-form values → `BbTag`.
+- A standalone action that looks like a button → `BbButton`. Reach for
+  `BbBadgeButton` only when the control should look like a **pill**.
+
+### Status labels
+
+Drive the look with the `variant` ladder; put the copy in the default slot.
+
+**The variant ladder**
+
+```vue
+<div class="flex flex-wrap items-center gap-2">
+	<BbBadge variant="primary">New</BbBadge>
+	<BbBadge variant="secondary">Draft</BbBadge>
+	<BbBadge variant="outline">v2.4.0</BbBadge>
+	<BbBadge variant="destructive">Overdue</BbBadge>
+</div>
+```
+
+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
+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`
+inline (see One-off colors).
+
+#### Soft status pills
+
+For a small, closed status set (paid / pending / overdue, plan tiers), register
+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.
+
+**Invoice status pills + plan tiers**
 
 ```vue
 <template>
-	<span :class="classes">
-		<span class="bb-badge__wrapper">
-			<slot></slot>
-			<span class="bb-badge__content-container" v-bind="contentAttributes">
-				<span v-if="!props.dot" class="bb-badge__content-inner"
-					><slot name="content">{{ content }}</slot></span
-				>
-			</span>
-		</span>
-	</span>
+	<div
+		class="flex max-w-md flex-col gap-3 rounded-[var(--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)]">
+				Soft accents for a small, fixed status set — not every row color.
+			</p>
+		</div>
+
+		<ul class="flex flex-col gap-2 text-sm">
+			<li
+				v-for="row in invoices"
+				:key="row.id"
+				class="flex items-center justify-between gap-3"
+			>
+				<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>
+				<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>
+			<BbBadge size="sm" variant="soft-gray">Free</BbBadge>
+			<BbBadge size="sm" variant="soft-blue">Pro</BbBadge>
+			<BbBadge size="sm" variant="soft-amber">Enterprise</BbBadge>
+		</div>
+	</div>
 </template>
 
 <script setup lang="ts">
-import { computed, useSlots } from 'vue';
-import { isCssColor } from '@/utilities/functions/isCssColor';
-import { isNil } from '@/utilities/functions/isNil';
-import type { BbBadgeProps, BbBadgeSlots } from './types';
-
-const slots = useSlots();
-
-const props = withDefaults(defineProps<BbBadgeProps>(), {});
-
-defineSlots<BbBadgeSlots>();
-
-const classes = computed(() => {
-	return {
-		'bb-badge': true,
-		'bb-badge--bottom': props.bottom,
-		'bb-badge--left': props.left,
-		'bb-badge--positioned': slots.default,
-		'bb-badge--floating': props.floating,
-		'bb-badge--dot': props.dot,
-		'bb-badge--empty': !props.dot && isNil(props.content),
-		[`bb-badge--${props.color}`]: props.color && !isCssColor(props.color),
-	};
-});
-
-const contentAttributes = computed(() => {
-	let style: Record<string, string> = {};
-	if (props.color && isCssColor(props.color)) {
-		style.backgroundColor = props.color;
-	}
-
-	let accessibilityAttributes: Record<string, string | boolean> = {};
-	if ('wrap' in slots && slots.wrap) {
-		accessibilityAttributes['aria-atomic'] = true;
-		accessibilityAttributes['aria-live'] = 'polite';
-		accessibilityAttributes['role'] = 'status';
-	}
-	return {
-		style,
-		...accessibilityAttributes,
-	};
-});
+import { BbBadge } from 'bitboss-ui';
+import type { BadgeVariantType } from 'bitboss-ui';
+
+type InvoiceRow = {
+	id: string;
+	number: string;
+	client: string;
+	status: string;
+	variant: BadgeVariantType;
+};
+
+const invoices: InvoiceRow[] = [
+	{
+		id: 'inv-1041',
+		number: 'INV-1041',
+		client: 'Northwind',
+		status: 'Paid',
+		variant: 'soft-green',
+	},
+	{
+		id: 'inv-1042',
+		number: 'INV-1042',
+		client: 'Globex',
+		status: 'Pending',
+		variant: 'soft-amber',
+	},
+	{
+		id: 'inv-1043',
+		number: 'INV-1043',
+		client: 'Initech',
+		status: 'Overdue',
+		variant: 'soft-red',
+	},
+	{
+		id: 'inv-1044',
+		number: 'INV-1044',
+		client: 'Umbrella',
+		status: 'Draft',
+		variant: 'soft-gray',
+	},
+];
 </script>
-<style lang="postcss">
-@import './index.css';
+
+<!-- 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-gray {
+	--accent: #64748b;
+}
+.bb-badge.bb-badge--soft-blue {
+	--accent: #2563eb;
+}
+.bb-badge.bb-badge--soft-green {
+	--accent: #16a34a;
+}
+.bb-badge.bb-badge--soft-amber {
+	--accent: #d97706;
+}
+.bb-badge.bb-badge--soft-red {
+	--accent: #dc2626;
+}
+
+.bb-badge.bb-badge--soft-gray,
+.bb-badge.bb-badge--soft-blue,
+.bb-badge.bb-badge--soft-green,
+.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;
+	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
+	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+}
 </style>
 ```
 
-## Types
-
-```ts
-import type { CommonProps } from '@/types/CommonProps';
-
-export type BbBadgeProps = Pick<CommonProps, 'color'> & {
-	/**
-	 * Displays the badge on the bottom of the wrapped component.
-	 */
-	bottom?: boolean;
-	/**
-	 * Text content of the badge.
-	 */
-	content?: string | number | null;
-	/**
-	 * Renders a small dot with no content instead of the full badge.
-	 */
-	dot?: boolean;
-	/**
-	 * Renders the badge a little further from the wrapped component,
-	 * making it look like it's floating and not stacked.
-	 */
-	floating?: boolean;
-	/**
-	 * Displays the badge on the left of the wrapped component.
-	 */
-	left?: boolean;
+#### Counts on nav items
+
+A count in a sidebar row is a standalone badge, right-aligned inside the row.
+The row's `<a>` owns the navigation; the badge stays inert. Format overflow
+yourself (`99+`) — there is no `max` prop.
+
+**Unread counts in a mail sidebar**
+
+```vue
+<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"
+	>
+		<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="
+				folder.active
+					? 'bg-[color:var(--bb-muted)] font-medium'
+					: 'text-[color:var(--bb-text)]'
+			"
+			:href="folder.href"
+		>
+			<span class="truncate">{{ folder.label }}</span>
+			<BbBadge
+				v-if="folder.count"
+				size="sm"
+				:variant="folder.active ? 'primary' : 'secondary'"
+				>{{ folder.count }}</BbBadge
+			>
+		</a>
+	</nav>
+</template>
+
+<script setup lang="ts">
+import { BbBadge } from 'bitboss-ui';
+
+type Folder = {
+	label: string;
+	href: string;
+	count?: number;
+	active?: boolean;
+};
+
+const folders: Folder[] = [
+	{ label: 'Inbox', href: '#inbox', count: 24, active: true },
+	{ label: 'Starred', href: '#starred', count: 3 },
+	{ label: 'Drafts', href: '#drafts', count: 2 },
+	{ label: 'Sent', href: '#sent' },
+	{ label: 'Spam', href: '#spam', count: 11 },
+];
+</script>
+```
+
+### Icons and icon-only badges
+
+Add `prepend:icon` / `append:icon` to a labelled badge, or `icon` for an
+icon-only badge. `icon` takes precedence: when set, `prepend:icon` /
+`append:icon` are ignored, and the default slot becomes the badge's visually
+hidden accessible label — always supply it.
+
+**Leading icon, trailing icon, and icon-only**
+
+```vue
+<div class="flex flex-wrap items-center gap-2">
+	<BbBadge variant="primary" prepend:icon="lucide:credit-card">Paid</BbBadge>
+	<BbBadge variant="outline" append:icon="lucide:arrow-right">Continue</BbBadge>
+	<BbBadge variant="secondary" icon="lucide:badge-check">Verified</BbBadge>
+</div>
+```
+
+### Loading state
+
+Add `loading` to show a spinner on the badge. It takes the place of the
+leftmost icon, the same convention as `BbButton`: it replaces the icon-only
+glyph or the `prepend:icon`; when the `append:icon` is the _sole_ icon it
+replaces that instead; and with no icons at all it occupies the leading slot.
+Whichever slot it lands in, the swap is same-size, so nothing shifts. A
+visually hidden loading announcement is added for screen readers.
+
+The chevron swap is the signature use: a badge acting as a select activator
+(e.g. an inline-editable table cell) shows the chevron at rest and the spinner
+while the picked value saves.
+
+**Where the spinner lands**
+
+```vue
+<div class="flex flex-wrap items-center gap-2">
+	<BbBadge append:icon="lucide:chevron-down" variant="secondary">
+		In progress
+	</BbBadge>
+	<BbBadge append:icon="lucide:chevron-down" loading variant="secondary">
+		In progress
+	</BbBadge>
+	<BbBadge loading prepend:icon="lucide:credit-card" variant="outline">
+		Paying
+	</BbBadge>
+	<BbBadge
+		append:icon="lucide:chevron-down"
+		loading
+		prepend:icon="lucide:user"
+		variant="secondary"
+	>
+		Both icons
+	</BbBadge>
+	<BbBadge loading variant="outline">Syncing</BbBadge>
+	<BbBadge icon="lucide:badge-check" loading variant="secondary">
+		Verifying
+	</BbBadge>
+</div>
+```
+
+### Removable tokens (`clearable`)
+
+Add `clearable` to render a trailing clear button; the badge emits `click:clear`
+when it's pressed. This is the dismissible-token pattern (an applied filter, a
+selected value) — the badge is controlled, so remove the item from your own
+state in the handler. Prefer `secondary` / `outline` for filter chips; reserve
+`destructive` for tokens that already mean danger.
+
+**Clearable badges across the variants**
+
+```vue
+<div class="flex flex-wrap items-center gap-2">
+	<BbBadge clearable variant="primary">Primary</BbBadge>
+	<BbBadge clearable variant="secondary">Secondary</BbBadge>
+	<BbBadge clearable variant="destructive">Destructive</BbBadge>
+	<BbBadge clearable variant="outline">Outline</BbBadge>
+</div>
+```
+
+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`).
+
+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
+shows at rest and the clear button reveals over it on **hover/focus** (the same
+swap the inputs use); and **`icon`** (icon-only) becomes a removable glyph.
+
+**Clearable with icons (hover the middle one)**
+
+```vue
+<div class="flex flex-wrap items-center gap-2">
+	<BbBadge clearable prepend:icon="lucide:tag" variant="secondary">Frontend</BbBadge>
+	<BbBadge clearable append:icon="lucide:chevron-down" variant="secondary">Priority</BbBadge>
+	<BbBadge clearable icon="lucide:user" variant="secondary">Ada Lovelace</BbBadge>
+</div>
+```
+
+Active filters are the classic product shape: a chip row, each badge owned by
+your state, cleared one-by-one or all at once.
+
+**A removable filter bar**
+
+```vue
+<template>
+	<div
+		class="flex max-w-md flex-col gap-2 rounded-[var(--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>
+		</div>
+
+		<div class="flex flex-wrap items-center gap-1.5">
+			<span class="text-xs text-[color:var(--bb-text-muted)]">Filtered by</span>
+			<BbBadge
+				v-for="filter in filters"
+				:key="filter.id"
+				clearable
+				:clearable-label="`Remove ${filter.label}`"
+				:prepend:icon="filter.icon"
+				size="sm"
+				variant="secondary"
+				@click:clear="onClear(filter.id)"
+				>{{ filter.label }}</BbBadge
+			>
+			<BbButton
+				v-if="filters.length"
+				size="sm"
+				variant="ghost"
+				@click="onClearAll"
+			>
+				Clear all
+			</BbButton>
+			<BbButton v-else size="sm" variant="outline" @click="onReset">
+				Restore filters
+			</BbButton>
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbBadge, BbButton } from 'bitboss-ui';
+import type { IconType } from 'bitboss-ui';
+
+type FilterChip = {
+	id: string;
+	label: string;
+	icon: IconType;
+};
+
+const initial: FilterChip[] = [
+	{ id: 'status', label: 'Status: Open', icon: 'lucide:circle-dot' },
+	{ id: 'assignee', label: 'Assignee: Me', icon: 'lucide:user' },
+	{ id: 'priority', label: 'Priority: High', icon: 'lucide:flag' },
+];
+
+const filters = ref<FilterChip[]>([...initial]);
+
+const resultLabel = computed(() =>
+	filters.value.length
+		? `${filters.value.length} active filter${filters.value.length === 1 ? '' : 's'}`
+		: 'Showing all invoices'
+);
+
+/** Drop one chip; the badge is controlled, so state lives here. */
+const onClear = (id: string) => {
+	filters.value = filters.value.filter((filter) => filter.id !== id);
+};
+
+const onClearAll = () => {
+	filters.value = [];
 };
 
-export type BbBadgeSlots = {
-	/**
-	 * The element the badge is anchored to. When provided, the badge is positioned relative to it.
-	 */
-	default?: (props: object) => any;
-	/**
-	 * Replaces the default badge indicator content. Falls back to the `content` prop value.
-	 */
-	content?: (props: object) => any;
+const onReset = () => {
+	filters.value = [...initial];
 };
+</script>
 ```
 
-## Styles
-
-```css
-.bb-badge {
-	/* ── Configurable tokens ─────────────────────────────────── */
-	--bb-badge-bg: var(--bb-primary);
-	--bb-badge-color: var(--bb-contrasting);
-	--bb-badge-radius: 999px;
-	--bb-badge-font-size: 0.75rem;
-	--bb-badge-min-size: 1.375rem;
-	--bb-badge-dot-size: 0.625rem;
-	--bb-badge-border-width: 0px;
-	--bb-badge-border-color: transparent;
-	--bb-badge-offset: 0.625rem;
-	--bb-badge-float-offset: 1.25rem;
-	--bb-badge-dot-offset: 0.125rem;
-	--bb-badge-dot-float-offset: 0.5rem;
-
-	display: inline-flex;
-
-	/* ── Positioned mode ─────────────────────────────────────── */
-	&--positioned {
-		position: relative;
-
-		.bb-badge__content-container {
-			position: absolute;
-			top: calc(0% - var(--bb-badge-offset));
-			right: calc(0% - var(--bb-badge-offset));
-			bottom: auto;
-			left: auto;
-		}
-
-		&.bb-badge--left .bb-badge__content-container {
-			right: auto;
-			left: calc(0% - var(--bb-badge-offset));
-		}
-
-		&.bb-badge--bottom .bb-badge__content-container {
-			top: auto;
-			bottom: calc(0% - var(--bb-badge-offset));
-		}
-
-		&.bb-badge--empty .bb-badge__content-container {
-			transform: scale(0);
-		}
-
-		/* Dot: smaller so it needs a tighter offset */
-		&.bb-badge--dot .bb-badge__content-container {
-			top: calc(0% - var(--bb-badge-dot-offset));
-			right: calc(0% - var(--bb-badge-dot-offset));
-		}
-
-		&.bb-badge--dot.bb-badge--left .bb-badge__content-container {
-			right: auto;
-			left: calc(0% - var(--bb-badge-dot-offset));
-		}
-
-		&.bb-badge--dot.bb-badge--bottom .bb-badge__content-container {
-			top: auto;
-			bottom: calc(0% - var(--bb-badge-dot-offset));
-		}
-
-		/* Floating */
-		&.bb-badge--floating .bb-badge__content-container {
-			top: calc(0% - var(--bb-badge-float-offset));
-			right: calc(0% - var(--bb-badge-float-offset));
-			bottom: auto;
-			left: auto;
-		}
-
-		&.bb-badge--floating.bb-badge--left .bb-badge__content-container {
-			right: auto;
-			left: calc(0% - var(--bb-badge-float-offset));
-		}
-
-		&.bb-badge--floating.bb-badge--bottom .bb-badge__content-container {
-			top: auto;
-			bottom: calc(0% - var(--bb-badge-float-offset));
-		}
-
-		/* Floating dot */
-		&.bb-badge--floating.bb-badge--dot .bb-badge__content-container {
-			top: calc(0% - var(--bb-badge-dot-float-offset));
-			right: calc(0% - var(--bb-badge-dot-float-offset));
-			bottom: auto;
-			left: auto;
-		}
-
-		&.bb-badge--floating.bb-badge--dot.bb-badge--left
-			.bb-badge__content-container {
-			right: auto;
-			left: calc(0% - var(--bb-badge-dot-float-offset));
-		}
-
-		&.bb-badge--floating.bb-badge--dot.bb-badge--bottom
-			.bb-badge__content-container {
-			top: auto;
-			bottom: calc(0% - var(--bb-badge-dot-float-offset));
-		}
-	}
-
-	/* ── Badge bubble ────────────────────────────────────────── */
-	&__content-container {
-		align-items: center;
-		background-color: var(--bb-badge-bg);
-		border: var(--bb-badge-border-width) solid var(--bb-badge-border-color);
-		border-radius: var(--bb-badge-radius);
-		color: var(--bb-badge-color);
-		display: inline-flex;
-		font-size: var(--bb-badge-font-size);
-		font-weight: 600;
-		justify-content: center;
-		line-height: 1;
-		min-height: var(--bb-badge-min-size);
-		min-width: var(--bb-badge-min-size);
-		padding-block: 0.1875rem;
-		padding-inline: 0.375rem;
-		transition:
-			color 0.2s,
-			background-color 0.2s,
-			transform 0.15s;
-		white-space: nowrap;
-	}
-
-	/* ── Dot mode ────────────────────────────────────────────── */
-	&--dot .bb-badge__content-container {
-		min-height: var(--bb-badge-dot-size);
-		min-width: var(--bb-badge-dot-size);
-		padding: 0;
-	}
-
-	&__wrapper {
-		display: inline-flex;
-	}
-}
+### Interactive badges (`BbBadgeButton`)
+
+A plain badge is inert. To make the badge itself clickable, slot a
+**`BbBadgeButton`** as a **direct child** — it takes over the badge's body and
+renders it as a real `<button>`:
+
+**A clickable pill**
+
+```vue
+<div class="flex flex-wrap items-center gap-2">
+	<BbBadge variant="secondary">
+		<BbBadgeButton @click="() => {}">Assign reviewer</BbBadgeButton>
+	</BbBadge>
+	<BbBadge prepend:icon="lucide:filter" variant="outline">
+		<BbBadgeButton @click="() => {}">Status: open</BbBadgeButton>
+	</BbBadge>
+</div>
+```
+
+The companion owns the element, so **everything binds where you'd expect**:
+attributes and listeners (`@click`, `disabled`, `aria-pressed`, `data-*`) land
+on the button, a template `ref` resolves to it (so it works directly as a
+popover/tooltip anchor), and directives apply to it.
+
+Three structural rules follow from the takeover:
+
+- **The badge's icons move inside the button.** `prepend:icon`, `icon` and the
+  `loading` spinner render within the hit target, so clicking the icon fires the
+  action — they are part of the control, not decoration beside it.
+- **The label is the companion's slot**, not the badge's. Write
+  `<BbBadge><BbBadgeButton>Text</BbBadgeButton></BbBadge>`, not both.
+- **`append:icon` and the clear button stay outside** it, on the badge's
+  trailing side. That is what keeps `clearable` compatible (below).
+
+#### Full `BbBaseButton` parity
+
+`BbBadgeButton` composes `BbBaseButton`, so the badge body accepts that
+component's whole prop surface: `href` / `to` (rendering an `<a>` or
+router-link), the Inertia visit options, `target` / `rel` / `download`,
+`active-class`, `disabled`, `type`, and `tag`. Only `block` (meaningless on an
+inline pill) and `text` (the label comes from the slot) are excluded.
+
+**Badges that navigate**
+
+```vue
+<div class="flex flex-wrap items-center gap-2">
+	<BbBadge prepend:icon="lucide:external-link" variant="outline">
+		<BbBadgeButton href="https://example.com" target="_blank" rel="noopener">
+			Docs
+		</BbBadgeButton>
+	</BbBadge>
+	<BbBadge prepend:icon="lucide:link" variant="secondary">
+		<BbBadgeButton href="#anchor">Jump to section</BbBadgeButton>
+	</BbBadge>
+	<BbBadge variant="secondary">
+		<BbBadgeButton disabled href="https://example.com">Unavailable</BbBadgeButton>
+	</BbBadge>
+</div>
+```
+
+A `disabled` link renders the `<a>` without an `href`, so it can't be
+activated — the same rule `BbBaseButton` applies everywhere.
+
+#### Clickable **and** removable
+
+Because the clear control is a sibling of the body rather than nested inside
+it, the two compose — this is the classic filter chip: press the body to edit,
+press the × to remove. The two actions are two tab stops, which is correct.
+
+**The filter-chip pattern**
+
+```vue
+<div class="flex flex-wrap items-center gap-2">
+	<BbBadge clearable prepend:icon="lucide:tag" variant="secondary">
+		<BbBadgeButton @click="() => {}">Label: frontend</BbBadgeButton>
+	</BbBadge>
+	<BbBadge clearable append:icon="lucide:chevron-down" variant="secondary">
+		<BbBadgeButton @click="() => {}">Priority: high</BbBadgeButton>
+	</BbBadge>
+</div>
+```
+
+Clicking the clear button never fires the body's `@click`.
+
+#### Icon-only, interactive
+
+With `icon`, the glyph and the visually hidden label both move inside the
+button — so the slot text becomes the button's accessible name. Never leave it
+empty here: an icon-only interactive badge with no label is an unnamed control.
+
+**An icon-only action pill**
+
+```vue
+<BbBadge icon="lucide:bell" variant="outline">
+	<BbBadgeButton @click="() => {}">Notification settings</BbBadgeButton>
+</BbBadge>
 ```
+
+#### As a popover activator
+
+A template ref on `BbBadgeButton` resolves to the rendered element, so it can
+anchor an overlay directly — no wrapper element, no `defineExpose`:
+
+**A badge that opens a popover**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-wrap items-center gap-2 rounded-[var(--bb-radius)] border p-3"
+	>
+		<span class="text-xs text-[color:var(--bb-text-muted)]">Filters</span>
+
+		<BbBadge
+			append:icon="lucide:chevron-down"
+			clearable
+			clearable-label="Remove status filter"
+			prepend:icon="lucide:circle-dot"
+			size="sm"
+			variant="secondary"
+			@click:clear="status = 'Open'"
+		>
+			<BbBadgeButton ref="statusChip">Status: {{ status }}</BbBadgeButton>
+		</BbBadge>
+
+		<!-- The ref resolves to the rendered button element, so it anchors the
+		popover directly — no wrapper, no imperative handle. -->
+		<BbPopover v-model="open" :activator="statusChip" placement="bottom-start">
+			<div class="flex min-w-36 flex-col p-1">
+				<BbButton
+					v-for="option in options"
+					:key="option"
+					size="sm"
+					variant="ghost"
+					@click="onPick(option)"
+					>{{ option }}</BbButton
+				>
+			</div>
+		</BbPopover>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref, useTemplateRef } from 'vue';
+import { BbBadge, BbBadgeButton, BbButton, BbPopover } from 'bitboss-ui';
+
+const options = ['Open', 'In review', 'Done'] as const;
+type Status = (typeof options)[number];
+
+const status = ref<Status>('Open');
+const open = ref(false);
+const statusChip = useTemplateRef('statusChip');
+
+const onPick = (option: Status) => {
+	status.value = option;
+	open.value = false;
+};
+</script>
+```
+
+### Sizes
+
+Badges follow the shared `xs → 2xl` scale (default `md`; an invalid size warns
+in dev and falls back to `md`). Keep one size per cluster.
+
+**The size scale**
+
+```vue
+<div class="flex flex-wrap items-center gap-3">
+	<BbBadge size="xs" variant="destructive">9</BbBadge>
+	<BbBadge size="sm" variant="destructive">9</BbBadge>
+	<BbBadge size="md" variant="destructive">9</BbBadge>
+	<BbBadge size="lg" variant="destructive">9</BbBadge>
+	<BbBadge size="xl" variant="destructive">9</BbBadge>
+	<BbBadge size="2xl" variant="destructive">9</BbBadge>
+</div>
+```
+
+### One-off colors
+
+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:
+
+**A one-off accent via the --bg token**
+
+```vue
+<div class="flex flex-wrap items-center gap-2">
+	<BbBadge variant="primary" :style="{ '--bg': '#16a34a' }">Sales</BbBadge>
+	<BbBadge variant="primary" :style="{ '--bg': '#7c3aed' }">Design</BbBadge>
+</div>
+```
+
+Pair a dark custom `--bg` with a light-text variant (`primary`), or set
+`--color` too, and check contrast yourself. For anything recurring, register a
+variant instead so the styling stays in the design system.
+
+### Anatomy and CSS hooks
+
+A badge renders two sides inside the pill wrapper, which is what lets the body
+and the clear control be independent controls:
+
+```html
+<span class="bb-badge bb-badge--md bb-badge--secondary">
+	<span class="bb-badge__body">
+		<!-- <button>/<a> in button mode -->
+		<svg class="bb-badge__prepend-icon" />
+		<!-- or __icon / BbSpinner -->
+		<span class="bb-badge__content">label</span>
+	</span>
+	<span class="bb-badge__trailing">
+		<!-- only when needed -->
+		<svg class="bb-badge__append-icon" />
+		<button class="bb-badge__clear-button">…</button>
+	</span>
+</span>
+```
+
+Both sides carry the pill's radius and inline padding, so each hit area runs
+**flush to the border** — clicking the extreme left edge presses the body, the
+extreme right edge presses the clear. The clear button's hit region spans the
+full pill height even though only the glyph's circle looks interactive.
+
+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.
+
+### Works well with
+
+- `BbBadgeButton` — the companion that makes the badge body a real button/link.
+- `BbIndicator` — the anchored sibling: counts and dots pinned over a bell,
+  button, or avatar.
+- `BbTable` / `BbTabs` — standalone badges as status pills in cells and tab
+  labels.
+- `BbSelect` / `ChipsBox` — a `clearable` `secondary` badge is exactly how
+  multi-selects render their removable selections.
+- `BbPopover` / `BbDropdown` — a `BbBadgeButton` ref is a ready-made activator
+  for an inline-edit chip.
+
+### Gotchas & anti-patterns
+
+- The label lives in the **default slot** — there is no `text`/`content` prop.
+  In button mode it moves to `BbBadgeButton`'s slot; don't write both.
+- **`BbBadgeButton` must be a direct child** of the badge's default slot.
+  Wrapping it in another element or component is undefined behavior — the badge
+  won't hand over its body, and you'll get a duplicated label. Outside a badge
+  entirely, it throws.
+- One `BbBadgeButton` per badge. There is only one body to take over.
+- A badge **without** the companion stays inert: no events, no `href`. Only
+  `clearable` adds behavior (the clear button + `click:clear`).
+- Don't nest your own `<button>`/`<a>` in a badge's default slot to make it
+  clickable — with `clearable` that's invalid markup (a `<button>` may not
+  contain interactive content). That's precisely what `BbBadgeButton` exists to
+  solve.
+- To pin a marker over another element (notification dot/count), use
+  `BbIndicator`, not a badge.
+- No `max`/overflow prop: format big counts yourself (`99+`).
+
+### Accessibility
+
+- A plain badge is inline text to assistive tech (no live region) — fine for
+  static pills. For an announced dynamic count pinned to a control, use
+  `BbIndicator` (which is a `role="status"` live region).
+- 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`).
+- 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
+  is visible at pill scale rather than as a ring around a 12px glyph.
+- Prefer a registered `variant` over a one-off inline `--bg`; a bare color
+  carries no semantic meaning and no guaranteed contrast.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `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. |
+| `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… |
+| `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`). |
+
+## Events
+
+- `click:clear` — `(event: "click:clear", event: MouseEvent): void`
+
+## 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>`).
+
+## 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.
+- [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.