bitboss-ui 3.0.0-beta.3 → 3.0.0-beta.30

package/dist/ai/BbTabs.md

@@ -4,7 +4,7 @@
 
 - Safety level: **Consumer API**
 - Group: **Navigation**
-- Description: Switches between tabbed content views (shadcn-like strip; BbTabRoot enables split layouts).
+- Description: Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbTabs.md](./source/BbTabs.md)
 
@@ -45,12 +45,10 @@ in one component.
 
 ```vue
 <template>
-	<div
-		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
-	>
+	<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
 		<div class="mb-3 flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Acme Checkout</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Project · last deploy 14m ago
 			</p>
 		</div>
@@ -58,34 +56,34 @@ in one component.
 			<template #overview>
 				<div class="grid gap-1.5 pt-3 text-sm">
 					<p class="font-medium">Health: stable</p>
-					<p class="text-xs text-[color:var(--bb-text-muted)]">
+					<p class="text-xs text-(--bb-text-muted)">
 						Error rate 0.12% · p95 180ms · 3 open incidents
 					</p>
 				</div>
 			</template>
 			<template #activity>
-				<ul class="divide-y divide-[color:var(--bb-border)] pt-3">
+				<ul class="divide-y divide-(--bb-border) pt-3">
 					<li
 						v-for="event in activity"
 						:key="event.id"
 						class="flex flex-col gap-0.5 py-2"
 					>
 						<p class="text-sm">{{ event.text }}</p>
-						<p class="text-xs text-[color:var(--bb-text-muted)]">
+						<p class="text-xs text-(--bb-text-muted)">
 							{{ event.when }}
 						</p>
 					</li>
 				</ul>
 			</template>
 			<template #members>
-				<ul class="divide-y divide-[color:var(--bb-border)] pt-3">
+				<ul class="divide-y divide-(--bb-border) pt-3">
 					<li
 						v-for="member in members"
 						:key="member.email"
 						class="flex items-center justify-between gap-2 py-2 text-sm"
 					>
 						<span class="truncate">{{ member.name }}</span>
-						<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
+						<span class="shrink-0 text-xs text-(--bb-text-muted)">{{
 							member.role
 						}}</span>
 					</li>
@@ -136,23 +134,21 @@ dynamic-name slot instead of writing one block per key:
 **Dynamic pane slots from generated items**
 
 ```vue
-<div
-	class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
->
+<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
 	<BbTabs
 		compact
 		:items="[
 			{ key: 'draft', label: 'Draft' },
-			{ key: 'in-review', label: 'In review' },
+			{ key: 'review', label: 'In review' },
 			{ key: 'published', label: 'Published' },
 		]"
 	>
 		<template
-			v-for="stage in ['draft', 'in-review', 'published']"
+			v-for="stage in ['draft', 'review', 'published']"
 			:key="stage"
 			#[stage]
 		>
-			<p class="pt-3 text-sm capitalize text-[color:var(--bb-text-muted)]">{{ stage }} documents.</p>
+			<p class="pt-3 text-sm capitalize text-(--bb-text-muted)">{{ stage }} documents.</p>
 		</template>
 	</BbTabs>
 </div>
@@ -172,9 +168,7 @@ button or link inside a label — the trigger is already the control).
 
 ```vue
 <template>
-	<div
-		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
-	>
+	<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
 		<BbTabs v-model="active" compact :items="tabs">
 			<template #label:inbox="{ text }">
 				<span class="inline-flex items-center gap-1.5">
@@ -183,26 +177,26 @@ button or link inside a label — the trigger is already the control).
 				</span>
 			</template>
 			<template #inbox>
-				<ul class="divide-y divide-[color:var(--bb-border)] pt-3">
+				<ul class="divide-y divide-(--bb-border) pt-3">
 					<li
 						v-for="thread in inbox"
 						:key="thread.id"
 						class="flex flex-col gap-0.5 py-2"
 					>
 						<p class="text-sm font-medium">{{ thread.subject }}</p>
-						<p class="text-xs text-[color:var(--bb-text-muted)]">
+						<p class="text-xs text-(--bb-text-muted)">
 							{{ thread.from }} · {{ thread.when }}
 						</p>
 					</li>
 				</ul>
 			</template>
 			<template #sent>
-				<p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">
+				<p class="pt-3 text-sm text-(--bb-text-muted)">
 					12 messages sent this week.
 				</p>
 			</template>
 			<template #spam>
-				<p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">
+				<p class="pt-3 text-sm text-(--bb-text-muted)">
 					3 filtered messages · last scan 2h ago.
 				</p>
 			</template>
@@ -255,7 +249,7 @@ const inbox = [
 .bb-badge.bb-badge--soft-blue {
 	--accent: #2563eb;
 	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
-	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+	--fg: 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);
@@ -290,12 +284,10 @@ the Audience and Schedule tabs:
 
 ```vue
 <template>
-	<div
-		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
-	>
+	<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
 		<div class="mb-3 flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Product announcement</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Draft · scheduled for Tue 09:00 local
 			</p>
 		</div>
@@ -320,7 +312,7 @@ the Audience and Schedule tabs:
 				</div>
 			</template>
 			<template #audience>
-				<p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">
+				<p class="pt-3 text-sm text-(--bb-text-muted)">
 					Sending to
 					<span class="font-medium tabular-nums">{{
 						recipients.toLocaleString()
@@ -329,7 +321,7 @@ the Audience and Schedule tabs:
 				</p>
 			</template>
 			<template #schedule>
-				<p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">
+				<p class="pt-3 text-sm text-(--bb-text-muted)">
 					Queued for Tuesday 09:00 in each recipient's local timezone.
 				</p>
 			</template>
@@ -379,12 +371,10 @@ nothing when you flip back:
 
 ```vue
 <template>
-	<div
-		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
-	>
+	<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
 		<div class="mb-3 flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Release notes</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Markdown draft · preview before publishing.
 			</p>
 		</div>
@@ -405,14 +395,12 @@ nothing when you flip back:
 				</div>
 			</template>
 			<template #preview>
-				<div class="grid gap-1.5 whitespace-pre-line pt-3 text-sm">
+				<div class="grid gap-1.5 pt-3 text-sm whitespace-pre-line">
 					<template v-if="draft.trim()">
 						<p class="font-medium">{{ previewTitle }}</p>
-						<p class="text-[color:var(--bb-text-muted)]">{{ previewBody }}</p>
+						<p class="text-(--bb-text-muted)">{{ previewBody }}</p>
 					</template>
-					<p v-else class="text-[color:var(--bb-text-muted)]">
-						Nothing to preview.
-					</p>
+					<p v-else class="text-(--bb-text-muted)">Nothing to preview.</p>
 				</div>
 			</template>
 		</BbTabs>
@@ -470,12 +458,10 @@ active section stays in the URL without flooding Back history:
 
 ```vue
 <template>
-	<div
-		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
-	>
+	<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
 		<div class="mb-3 flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Workspace settings</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Northwind Billing · changes save per section.
 			</p>
 		</div>
@@ -511,7 +497,7 @@ active section stays in the URL without flooding Back history:
 				</div>
 			</template>
 			<template #members>
-				<ul class="divide-y divide-[color:var(--bb-border)] pt-3">
+				<ul class="divide-y divide-(--bb-border) pt-3">
 					<li
 						v-for="member in members"
 						:key="member.email"
@@ -519,11 +505,11 @@ active section stays in the URL without flooding Back history:
 					>
 						<span class="min-w-0 truncate">
 							<span class="font-medium">{{ member.name }}</span>
-							<span class="text-xs text-[color:var(--bb-text-muted)]">
+							<span class="text-xs text-(--bb-text-muted)">
 								· {{ member.email }}</span
 							>
 						</span>
-						<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
+						<span class="shrink-0 text-xs text-(--bb-text-muted)">{{
 							member.role
 						}}</span>
 					</li>
@@ -532,7 +518,7 @@ active section stays in the URL without flooding Back history:
 			<template #billing>
 				<div class="grid gap-1.5 pt-3">
 					<p class="text-sm font-medium">Pro · €49 / month</p>
-					<p class="text-xs text-[color:var(--bb-text-muted)]">
+					<p class="text-xs text-(--bb-text-muted)">
 						Next invoice Jul 28, 2026 · Visa ···· 4242
 					</p>
 					<div class="pt-1">
@@ -577,9 +563,7 @@ const onSaveGeneral = async () => {
 **Full-width strip with a disabled tab**
 
 ```vue
-<div
-	class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
->
+<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
 	<BbTabs
 		block
 		compact
@@ -589,9 +573,9 @@ const onSaveGeneral = async () => {
 			{ key: 'billing', label: 'Billing', disabled: true },
 		]"
 	>
-		<template #summary><p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">Environment status at a glance.</p></template>
-		<template #integrations><p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">Connected services.</p></template>
-		<template #billing><p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">Locked on this plan.</p></template>
+		<template #summary><p class="pt-3 text-sm text-(--bb-text-muted)">Environment status at a glance.</p></template>
+		<template #integrations><p class="pt-3 text-sm text-(--bb-text-muted)">Connected services.</p></template>
+		<template #billing><p class="pt-3 text-sm text-(--bb-text-muted)">Locked on this plan.</p></template>
 	</BbTabs>
 </div>
 ```
@@ -599,9 +583,7 @@ const onSaveGeneral = async () => {
 **Vertical, compact strip**
 
 ```vue
-<div
-	class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
->
+<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
 	<BbTabs
 		compact
 		direction="vertical"
@@ -611,9 +593,9 @@ const onSaveGeneral = async () => {
 			{ key: 'api', label: 'API keys' },
 		]"
 	>
-		<template #general><p class="px-3 text-sm text-[color:var(--bb-text-muted)]">Workspace basics.</p></template>
-		<template #security><p class="px-3 text-sm text-[color:var(--bb-text-muted)]">Sessions and 2FA.</p></template>
-		<template #api><p class="px-3 text-sm text-[color:var(--bb-text-muted)]">Personal access tokens.</p></template>
+		<template #general><p class="px-3 text-sm text-(--bb-text-muted)">Workspace basics.</p></template>
+		<template #security><p class="px-3 text-sm text-(--bb-text-muted)">Sessions and 2FA.</p></template>
+		<template #api><p class="px-3 text-sm text-(--bb-text-muted)">Personal access tokens.</p></template>
 	</BbTabs>
 </div>
 ```
@@ -623,7 +605,286 @@ width — set `style="--max-w: 160px"` on the list and long labels ellipse inste
 of widening the column. The strip never exceeds its container. Sizing otherwise
 follows the design tokens (`--bb-control-h`, `--bb-radius`, `--bb-fs`); there is
 no numeric size prop and no global tabs config to set — tokens and the `block` /
-`compact` / `direction` props are the whole surface.
+`compact` / `direction` / `variant` props are the whole surface.
+
+### Variants
+
+`variant` picks the strip's look and nothing else — items, `v-model`, keyboard
+navigation, panes, `block` / `compact` / `direction` all behave the same under
+every variant. Three ship:
+
+- **`pill`** (default) — the segmented strip: a muted rounded bar with a raised
+  pill sliding under the active trigger. Reach for it to switch _views of the
+  same content_ (Board / Table, Code / Preview).
+- **`line`** — triggers on a thin baseline, a sliding underline under the active
+  one (on the side edge when `direction="vertical"`), active label bold. Reach
+  for it to navigate _sections of a page_ (Overview / Activity / Settings).
+- **`none`** — behaviour and structure only, no chrome: no strip, no indicator
+  paint, labels inherit the host's colour and weight. Reach for it when the
+  design is yours, styled through `pt` and classes, like `BbButton`'s `none`.
+
+**pill — switching views of one list**
+
+```vue
+<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
+	<BbTabs
+		:items="[
+			{ key: 'board', label: 'Board' },
+			{ key: 'table', label: 'Table' },
+			{ key: 'calendar', label: 'Calendar' },
+		]"
+	>
+		<template #board><p class="pt-3 text-sm text-(--bb-text-muted)">Cards by status.</p></template>
+		<template #table><p class="pt-3 text-sm text-(--bb-text-muted)">One row per task.</p></template>
+		<template #calendar><p class="pt-3 text-sm text-(--bb-text-muted)">Due dates on a month grid.</p></template>
+	</BbTabs>
+</div>
+```
+
+**line — navigating the sections of a record**
+
+```vue
+<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
+	<BbTabs
+		:items="[
+			{ key: 'overview', label: 'Overview' },
+			{ key: 'activity', label: 'Activity' },
+			{ key: 'settings', label: 'Settings' },
+		]"
+		variant="line"
+	>
+		<template #overview><p class="pt-3 text-sm text-(--bb-text-muted)">Status, owner, next step.</p></template>
+		<template #activity><p class="pt-3 text-sm text-(--bb-text-muted)">Everything that happened, newest first.</p></template>
+		<template #settings><p class="pt-3 text-sm text-(--bb-text-muted)">Notifications and access.</p></template>
+	</BbTabs>
+</div>
+```
+
+`line` composes with everything else: `compact` drops the baseline strip to
+28px, `direction="vertical"` moves the bar to the side edge of a column strip,
+and the bar keeps sliding — it is the same measured element as the pill.
+
+**line, vertical and compact**
+
+```vue
+<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
+	<BbTabs
+		compact
+		direction="vertical"
+		:items="[
+			{ key: 'profile', label: 'Profile' },
+			{ key: 'sessions', label: 'Sessions' },
+			{ key: 'tokens', label: 'API tokens' },
+		]"
+		variant="line"
+	>
+		<template #profile><p class="px-3 text-sm text-(--bb-text-muted)">Name, avatar, locale.</p></template>
+		<template #sessions><p class="px-3 text-sm text-(--bb-text-muted)">Signed-in devices.</p></template>
+		<template #tokens><p class="px-3 text-sm text-(--bb-text-muted)">Personal access tokens.</p></template>
+	</BbTabs>
+</div>
+```
+
+`none` renders the same tablist with no paint of its own, so the look is
+whatever you put on the parts — here the trigger gets a bottom border while
+active through `pt:item:active`:
+
+**none — your own look through pt**
+
+```vue
+<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
+	<BbTabs
+		:items="[
+			{ key: 'week', label: 'This week' },
+			{ key: 'month', label: 'This month' },
+			{ key: 'year', label: 'This year' },
+		]"
+		pt:item="border-b-2 border-transparent text-(--bb-text-muted) uppercase tracking-wide text-xs"
+		pt:item:active="border-(--bb-text) text-(--bb-text)"
+		variant="none"
+	>
+		<template #week><p class="pt-3 text-sm text-(--bb-text-muted)">7 days of activity.</p></template>
+		<template #month><p class="pt-3 text-sm text-(--bb-text-muted)">30 days of activity.</p></template>
+		<template #year><p class="pt-3 text-sm text-(--bb-text-muted)">12 months of activity.</p></template>
+	</BbTabs>
+</div>
+```
+
+On the split layout `variant` set on `BbTabsRoot` is the default for every
+`BbTabsList` under it, and a list can take its own `variant` to differ.
+
+#### The token model
+
+Every variant — shipped or registered — is a preset of one set of custom
+properties declared on `.bb-tabs-list`. Set them on the strip (or on a class
+you put on it) to retune one instance; set them on a `.bb-tabs-list--<name>`
+class to define a variant. `pill` is the base values; `line` and `none` are the
+presets shown in the last two columns.
+
+| Custom property                                                         | What it paints                                                                                                                        | `line`                | `none`        |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------- |
+| **Strip** — `--list-bg`                                                 | the bar behind the triggers                                                                                                           | `transparent`         | `transparent` |
+| `--list-border`                                                         | the strip's edge line: a baseline under the triggers (beside them when vertical), `--bb-border-w` thick, painted inside the strip     | `var(--bb-border)`    | —             |
+| `--p`                                                                   | inner padding — the gutter the indicator sits in and the scroll inset                                                                 | `0px`                 | `0px`         |
+| `--list-r`, `--list-h`                                                  | corners, min height                                                                                                                   | `--list-r: 0px`       | `0px`         |
+| **Triggers** — `--trigger-gap`                                          | space between triggers                                                                                                                | —                     | —             |
+| `--trigger-px`, `--trigger-min-h`, `--trigger-r`, `--fs`                | side padding, min height (derived from `--list-h` and `--p`), corners (concentric inside `--list-r`), label size                      | `--trigger-r` small   | —             |
+| **Labels** — `--list-fg`, `--hover-fg`                                  | inactive and hovered label colour                                                                                                     | —                     | `inherit`     |
+| `--active-fg`, `--active-fw`                                            | active label colour and weight (inactive labels are `500`)                                                                            | `--active-fw: 600`    | `inherit`     |
+| **Indicator** — `--indicator-bg`, `--indicator-border`, `--indicator-r` | the sliding element's fill, edge and corners                                                                                          | primary fill, no edge | transparent   |
+| `--indicator-h`                                                         | its thickness: height (width when vertical). `initial` fills the whole trigger box — the pill; `2px` is a bar on the bottom/side edge | `2px`                 | —             |
+| `--indicator-inset`                                                     | inset from the trigger box — shrinks a pill; a bar keeps its thickness, shortens by it at both ends and floats it above the edge      | —                     | —             |
+| `--indicator-shadow`, `--elev`                                          | the indicator's own lift, and the theme's resting lift composed under it                                                              | `none`                | `none`        |
+
+A text-only look with no underline is `line` with `--indicator-h: 0px`; a
+thicker bar is `--indicator-h: 3px`; a bar the width of the label rather than
+the trigger is `--indicator-inset: var(--trigger-px)`. The generated contract
+lists every property with its default.
+
+#### Registered variants
+
+The two looks other libraries ship as `pills` and `outline` are a registered
+name and a token block away. Register the name in the build plugin so it
+type-checks —
+
+```ts
+// vite.config.ts (or the `bitboss` key of nuxt.config.ts)
+bitbossUi({ tabsVariants: ['soft', 'outline'] });
+```
+
+— then give the class hook `.bb-tabs-list--<name>` its tokens in a stylesheet
+loaded after the library's, and use `variant="<name>"`. **`soft`** — no strip,
+the active trigger is a filled tonal pill, the rest is plain text; the whole
+recipe is the `<style>` of the example:
+
+**soft — a registered tonal-pill variant**
+
+```vue
+<template>
+	<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
+		<p class="mb-2 text-xs text-(--bb-text-muted)">Inbox filters</p>
+		<!-- `soft` is a registered variant (`tabsVariants: ['soft']`); its look is
+		     the token block in this file's <style>. -->
+		<BbTabs v-model="filter" compact :items="filters" variant="soft">
+			<template #all>
+				<p class="pt-3 text-sm text-(--bb-text-muted)">
+					Every conversation, newest first.
+				</p>
+			</template>
+			<template #unread>
+				<p class="pt-3 text-sm text-(--bb-text-muted)">
+					12 conversations waiting for a reply.
+				</p>
+			</template>
+			<template #starred>
+				<p class="pt-3 text-sm text-(--bb-text-muted)">
+					Pinned threads you come back to.
+				</p>
+			</template>
+		</BbTabs>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTabs } from 'bitboss-ui';
+import type { BbTabsItem } from 'bitboss-ui';
+
+type Filter = 'all' | 'unread' | 'starred';
+
+const filters: Array<BbTabsItem<Filter>> = [
+	{ key: 'all', label: 'All' },
+	{ key: 'unread', label: 'Unread' },
+	{ key: 'starred', label: 'Starred' },
+];
+const filter = ref<Filter>('unread');
+</script>
+<style>
+/* `soft` — no strip, the active trigger is a filled tonal pill, the rest is
+   plain text. The whole recipe: the class hook plus the strip's own tokens. */
+.bb-tabs-list--soft {
+	--list-bg: transparent;
+	--trigger-gap: 4px;
+	--trigger-r: 999px;
+	--indicator-bg: color-mix(in oklab, var(--bb-primary) 15%, transparent);
+	--indicator-border: transparent;
+	--indicator-shadow: none;
+	--elev: none;
+	--active-fg: var(--bb-primary);
+	--active-fw: 600;
+}
+</style>
+```
+
+**`outline`** — a 1px-framed strip with no fill and an outlined indicator
+sliding inside it. The frame is the one thing the token model does not draw
+(`--list-border` is a baseline, not a box), so this recipe adds one rule on the
+tablist beside its tokens:
+
+**outline — a registered framed variant**
+
+```vue
+<template>
+	<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
+		<p class="mb-2 text-xs text-(--bb-text-muted)">Editor panel</p>
+		<!-- `outline` is a registered variant (`tabsVariants: ['outline']`); its
+		     look is the token block in this file's <style>. -->
+		<BbTabs v-model="panel" compact :items="panels" variant="outline">
+			<template #code>
+				<pre
+					class="mt-3 rounded-(--bb-radius) bg-(--bb-muted) p-2 text-xs"
+				><code>const total = lines.reduce((sum, l) => sum + l.amount, 0);</code></pre>
+			</template>
+			<template #preview>
+				<p class="pt-3 text-sm text-(--bb-text-muted)">
+					Total: <span class="font-medium text-(--bb-text)">€ 1,240.00</span>
+				</p>
+			</template>
+			<template #diff>
+				<p class="pt-3 text-sm text-(--bb-text-muted)">
+					2 lines changed since the last save.
+				</p>
+			</template>
+		</BbTabs>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTabs } from 'bitboss-ui';
+import type { BbTabsItem } from 'bitboss-ui';
+
+type Panel = 'code' | 'preview' | 'diff';
+
+const panels: Array<BbTabsItem<Panel>> = [
+	{ key: 'code', label: 'Code' },
+	{ key: 'preview', label: 'Preview' },
+	{ key: 'diff', label: 'Diff' },
+];
+const panel = ref<Panel>('code');
+</script>
+<style>
+/* `outline` — a 1px-framed strip with no fill, and an outlined indicator (a
+   border, no lift) sliding inside it. Tokens for the paint; one rule for the
+   frame, which the token model does not draw (`--list-border` is the
+   baseline of a `line` strip, not a box). */
+.bb-tabs-list--outline {
+	--list-bg: transparent;
+	--indicator-bg: transparent;
+	--indicator-border: var(--bb-text-muted);
+	--indicator-shadow: none;
+	--elev: none;
+	--active-fg: var(--bb-text);
+	--active-fw: 600;
+}
+.bb-tabs-list--outline .bb-tabs-list__tablist {
+	box-shadow: inset 0 0 0 var(--bb-border-w) var(--bb-border);
+}
+</style>
+```
+
+An unregistered name fails `vue-tsc`, like every other variant registry (see
+the [installation guide](./guides/installation-and-plugin-setup.md), _Variant
+registries_). The class is plain interpolation at runtime, so a one-off can be
+forced with a cast — register it instead.
 
 ### Overflowing strips and scroll affordances
 
@@ -640,12 +901,10 @@ ends.
 
 ```vue
 <template>
-	<div
-		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
-	>
+	<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
 		<div class="mb-3 flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Release timeline</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Monthly notes · scroll arrows when the strip overflows.
 			</p>
 		</div>
@@ -672,8 +931,19 @@ ends.
 					@click="scroll('right')"
 				/>
 			</template>
-			<template v-for="release in releases" :key="release.key" #[release.key]>
-				<p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">
+			<!--
+				`slotKey(...)`, never the raw key. A pane's slot name is the
+				NORMALIZED key: `v3.0` becomes `v3_0`, so `#[release.key]` would
+				name a slot that never matches and every pane would silently render
+				empty. The keys here carry a dot on purpose — with slug-safe keys
+				(`v1`…`v9`) the mistake is invisible.
+			-->
+			<template
+				v-for="release in releases"
+				:key="release.key"
+				#[slotKey(release.key)]
+			>
+				<p class="pt-3 text-sm text-(--bb-text-muted)">
 					{{ release.label }} shipped the design-token overhaul and the tabs
 					keyboard-navigation pass.
 				</p>
@@ -683,7 +953,7 @@ ends.
 </template>
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbButton, BbTabs } from 'bitboss-ui';
+import { BbButton, BbTabs, slotKey } from 'bitboss-ui';
 import type { BbTabsItem } from 'bitboss-ui';
 
 // A block strip with more triggers than fit: the pill and scroll-into-view keep
@@ -700,12 +970,14 @@ const months = [
 	'August',
 	'September',
 ];
+// Realistic release tags: `v3.0` … `v3.8`. The dot is what makes the
+// `slotKey` call in the template load-bearing (see the note there).
 const releases: BbTabsItem[] = months.map((label, index) => ({
-	key: `v${index + 1}`,
-	label: `${label} 2026`,
+	key: `v3.${index}`,
+	label: `${label} · v3.${index}`,
 }));
 
-const active = ref('v1');
+const active = ref('v3.0');
 </script>
 ```
 
@@ -732,12 +1004,10 @@ context; use nesting freely.
 
 ```vue
 <template>
-	<div
-		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
-	>
+	<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
 		<div class="mb-3 flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Acme Checkout</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Workspace · Prev/Next via root slot
 			</p>
 		</div>
@@ -764,21 +1034,21 @@ context; use nesting freely.
 						</BbButton>
 					</div>
 				</div>
-				<hr class="my-3 border-[color:var(--bb-border)]" />
+				<hr class="my-3 border-(--bb-border)" />
 				<BbTabsPanes>
 					<template #overview>
-						<p class="text-sm text-[color:var(--bb-text-muted)]">
+						<p class="text-sm text-(--bb-text-muted)">
 							Health stable · owners Alex + Sam · objective: cut checkout
 							latency 20%.
 						</p>
 					</template>
 					<template #activity>
-						<p class="text-sm text-[color:var(--bb-text-muted)]">
+						<p class="text-sm text-(--bb-text-muted)">
 							Shipped billing retries; fixed avatar upload timeout.
 						</p>
 					</template>
 					<template #members>
-						<p class="text-sm text-[color:var(--bb-text-muted)]">
+						<p class="text-sm text-(--bb-text-muted)">
 							14 editors, 23 viewers, 3 billing admins.
 						</p>
 					</template>
@@ -841,7 +1111,7 @@ the tabs jumps straight to the Security section:
 ```vue
 <template>
 	<div
-		class="max-w-md space-y-3 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
+		class="max-w-md space-y-3 rounded-(--bb-radius) border border-(--bb-border) p-3"
 	>
 		<div class="grid gap-2">
 			<BbAlert
@@ -888,7 +1158,7 @@ the tabs jumps straight to the Security section:
 			<template #security>
 				<div class="grid gap-1.5 pt-3 text-sm">
 					<p class="font-medium">Two-factor authentication</p>
-					<p class="text-xs text-[color:var(--bb-text-muted)]">
+					<p class="text-xs text-(--bb-text-muted)">
 						Off · last password change Mar 12, 2026 · 2 active sessions
 					</p>
 					<div class="pt-1">
@@ -899,15 +1169,12 @@ the tabs jumps straight to the Security section:
 				</div>
 			</template>
 			<template #notifications>
-				<p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">
+				<p class="pt-3 text-sm text-(--bb-text-muted)">
 					Email digests and mention alerts for alex@northwind.io.
 				</p>
 			</template>
 		</BbTabs>
-		<p
-			class="text-xs text-[color:var(--bb-text-muted)]"
-			data-test="active-section"
-		>
+		<p class="text-xs text-(--bb-text-muted)" data-test="active-section">
 			Active section: {{ current }}
 		</p>
 	</div>
@@ -1067,6 +1334,134 @@ route, so it is SSR-safe and shareable:
 <BbTabs :items="items" navigation replace query-key="section" />
 ```
 
+### Restyling with passthrough
+
+On the split layout the same `pt` props live on `BbTabsRoot` (it owns the
+context the list and the panes render from); `BbTabsList` and `BbTabsPanes`
+declare no `pt` of their own.
+
+`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`,
+`item` (one tab trigger, a broadcast) and `panel` (one pane, a broadcast).
+States, per tab: `active` (the current trigger / the shown pane) and
+`disabled`. Tabs do not "open", so there is no `open`; the sliding indicator
+is not a part — its paint is the strip's tokens (see _Variants_).
+
+The workspace settings above, restyled through those parts: type on
+`pt:item`, weight on `pt:item:active`, pane padding on `pt:panel`. A look
+that depends on the TAB'S OWN DATA — a tab flagged by a count you put on its
+descriptor — is a per-item function on `pt:item`:
+`:pt:item="({ item, states }) => item.badge && 'text-red-600'"`, called with
+the element of `items` and the states on for that tab, merged after
+`pt:item:active`. `panel` takes no function.
+
+**pt:item and pt:panel — settings sections**
+
+```vue
+<template>
+	<div class="max-w-md rounded-(--bb-radius) border border-(--bb-border) p-3">
+		<div class="mb-3 flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Workspace settings</p>
+			<p class="text-xs text-(--bb-text-muted)">
+				Northwind Billing · changes save per section.
+			</p>
+		</div>
+		<BbTabs
+			v-model="section"
+			block
+			:items="tabs"
+			pt:item="text-sm"
+			pt:item:active="font-semibold"
+			pt:panel="pt-3 text-sm"
+		>
+			<template #general>
+				<div class="grid gap-3">
+					<BbTextInput
+						v-model="org.name"
+						compact
+						label="Workspace name"
+						name="workspace-name"
+					/>
+					<BbTextInput
+						v-model="org.slug"
+						compact
+						label="URL slug"
+						name="workspace-slug"
+						prepend:icon="lucide:link"
+					/>
+					<div class="flex justify-end">
+						<BbButton variant="primary" @click="onSaveGeneral">
+							Save general
+						</BbButton>
+					</div>
+				</div>
+			</template>
+			<template #members>
+				<ul class="divide-y divide-(--bb-border)">
+					<li
+						v-for="member in members"
+						:key="member.email"
+						class="flex items-center justify-between gap-2 py-2 text-sm"
+					>
+						<span class="min-w-0 truncate">
+							<span class="font-medium">{{ member.name }}</span>
+							<span class="text-xs text-(--bb-text-muted)">
+								· {{ member.email }}</span
+							>
+						</span>
+						<span class="shrink-0 text-xs text-(--bb-text-muted)">{{
+							member.role
+						}}</span>
+					</li>
+				</ul>
+			</template>
+			<template #billing>
+				<div class="grid gap-1.5">
+					<p class="font-medium">Pro · €49 / month</p>
+					<p class="text-xs text-(--bb-text-muted)">
+						Next invoice Jul 28, 2026 · Visa ···· 4242
+					</p>
+					<div class="pt-1">
+						<BbButton prepend:icon="lucide:credit-card" variant="outline">
+							Manage billing
+						</BbButton>
+					</div>
+				</div>
+			</template>
+		</BbTabs>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { reactive, ref } from 'vue';
+import { BbButton, BbTabs, BbTextInput } from 'bitboss-ui';
+import type { BbTabsItem } from 'bitboss-ui';
+
+type Section = 'general' | 'members' | 'billing';
+
+const tabs: Array<BbTabsItem<Section>> = [
+	{ key: 'general', label: 'General' },
+	{ key: 'members', label: 'Members' },
+	{ key: 'billing', label: 'Billing' },
+];
+
+const section = ref<Section>('general');
+const org = reactive({ name: 'Northwind Billing', slug: 'northwind' });
+const members = [
+	{ name: 'Alex Rivera', email: 'alex@northwind.io', role: 'Owner' },
+	{ name: 'Sam Chen', email: 'sam@northwind.io', role: 'Admin' },
+	{ name: 'Jordan Lee', email: 'jordan@northwind.io', role: 'Editor' },
+];
+
+const onSaveGeneral = async () => {
+	await new Promise((resolve) => setTimeout(resolve, 400));
+};
+</script>
+```
+
+The full grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
 ### Works well with
 
 - **`BbBadge` / count pills in `label` slots** — status dots and unread counts
@@ -1082,11 +1477,15 @@ route, so it is SSR-safe and shareable:
 
 ### Gotchas and anti-patterns
 
-- **The sliding pill is measured from layout.** It reads the active trigger's
-  `offsetLeft`/`offsetTop`, so render tabs in a visible, normally-positioned
-  container. It settles itself on mount, resize, and font load, and paints a
-  static pill until the first measurement lands — nothing to configure, and
-  nothing to fight in demos.
+- **The sliding indicator is measured from layout.** It reads the active
+  trigger's `offsetLeft`/`offsetTop`, so render tabs in a visible,
+  normally-positioned container. It settles itself on mount, resize, and font
+  load, and paints a static pill (or bar) until the first measurement lands —
+  nothing to configure, and nothing to fight in demos.
+- **Do not fake a variant with `pt`.** An underline built from
+  `pt:item:active="border-b-2 …"` on a `pill` strip fights the pill; use
+  `variant="line"` (or a registered token preset) and keep `pt` for what is
+  genuinely per-call-site.
 - **Vertical strips answer Up/Down _and_ Left/Right arrows.** Up/Down is the
   primary pair (matching the vertical `aria-orientation`, per the ARIA APG);
   Left/Right keeps working as a forgiving extra. Horizontal strips answer
@@ -1105,8 +1504,11 @@ route, so it is SSR-safe and shareable:
 - **Don't reach for `BbTabsRoot` by default.** If you only need a strip over its
   panes, `BbTabs` is less markup and identical behavior; split only for markup
   between them.
-- **Every tab disabled throws.** With no `modelValue` and no valid first tab the
-  group has nothing to select — always leave at least one enabled tab.
+- **Every tab disabled renders an inert tablist** — it does not throw. With no
+  `modelValue` and no enabled tab there is nothing to select, so the strip
+  renders with no active tab and no pane (`useBbTabsContext.ts:200-206` handles
+  this deliberately). Nothing warns, so an all-disabled group looks like a
+  rendering bug; leave at least one tab enabled, or hide the strip.
 
 ### Accessibility
 
@@ -1139,18 +1541,19 @@ route, so it is SSR-safe and shareable:
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `block` | `boolean \| undefined` |  |  | Displays the component as full width. |
-| `compact` | `boolean \| undefined` |  |  | Adds a CSS class that applies a compact style to the component. |
+| `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: `item`, `panel`, `root`. States: `active`, `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`. |
+| `block` | `boolean \| undefined` | `false` |  | Displays the component as full width. |
+| `compact` | `boolean \| undefined` | `false` |  | Adds a CSS class that applies a compact style to the component. |
 | `direction` | `"horizontal" \| "vertical" \| undefined` | `"horizontal"` |  | Direction of the tabs component. |
-| `disableAnimateX` | `boolean \| undefined` |  |  | Disables the horizontal slide transition between tab panels (enabled by default). |
-| `disableAnimateY` | `boolean \| undefined` |  |  | Disables the smooth height animation when switching between tab panels (enabled by default). |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component |
-| `eager` | `boolean \| undefined` |  |  | Prevents rendering content before it's made visible. |
+| `disableAnimateX` | `boolean \| undefined` | `false` |  | Disables the horizontal slide transition between tab panels (enabled by default). |
+| `disableAnimateY` | `boolean \| undefined` | `false` |  | Disables the smooth height animation when switching between tab panels (enabled by default). |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
+| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
 | `headers` | `Record<string, string> \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigation is triggered. Only meaningful in an Inertia context. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
 | `items` | `BbTabsItem<K>[]` |  | yes | Array of items that define the tabs in the component. |
 | `modelValue` | `K \| null \| undefined` |  |  | The current tab key. Used by v-model. |
-| `navigation` | `boolean \| undefined` |  |  | Synchronizes the current tab with the URL query parameter. Pair it with `replace` unless a tab is genuinely a separate destination — see the `replace` prop. |
+| `navigation` | `boolean \| undefined` | `false` |  | Synchronizes the current tab with the URL query parameter. Pair it with `replace` unless a tab is genuinely a separate destination — see the `replace` prop. |
 | `onBefore` | `(() => boolean \| void) \| undefined` |  |  | Inertia lifecycle hook — fired just before the request is sent. Return `false` to cancel the visit. |
 | `onCancel` | `(() => void) \| undefined` |  |  | Inertia lifecycle hook — fired when the request is cancelled. |
 | `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Inertia lifecycle hook — fired when the server returns validation errors. |
@@ -1162,8 +1565,26 @@ route, so it is SSR-safe and shareable:
 | `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  | Controls whether Inertia preserves the scroll position after navigation. Only meaningful in an Inertia context. |
 | `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  | Controls whether Inertia preserves the current component state after navigation. Only meaningful in an Inertia context. |
 | `queryKey` | `string \| undefined` | `"tab"` |  | Defines the query key used for URL-based navigation. |
-| `replace` | `boolean \| undefined` |  |  | Uses history replacement instead of push navigation. Prefer `replace` whenever `navigation` is on: the URL still carries the active tab (deep-linkable, survives reload), but switching tabs does not stack a history entry per click, so Back l… |
-| `server` | `boolean \| undefined` |  |  | When true and in an Inertia context, triggers a real server-side Inertia visit instead of a client-only `history.pushState`. |
+| `replace` | `boolean \| undefined` | `false` |  | Replaces history rather than pushing it when changing tab. Recommended default whenever `navigation` is on: the query keeps the active tab (deep-linkable, survives reload) while Back still returns to the page the user came from, instead of … |
+| `server` | `boolean \| undefined` | `false` |  | When true and in an Inertia context, triggers a real server-side Inertia visit instead of a client-only `history.pushState`. |
+| `variant` | `keyof TabsVariantRegistry \| undefined` | `"pill"` |  | Look of the tab strip. `pill` is the segmented strip — a muted rounded bar with a raised pill sliding under the active trigger; `line` puts the triggers on a thin baseline with a sliding underline (on the side edge when `direction="vertical… |
+
+## 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`.
+
+| Part | What it is |
+| --- | --- |
+| `root` | The tabs' outer element. The strip and the sliding pill are not parts. |
+| `item` | One tab trigger — a broadcast resolved per tab with its own `active` / `disabled`. Also takes a per-item function, called with the tab's descriptor. |
+| `panel` | One tab pane — a broadcast; `panel:active` is the pane on show. Takes no function. |
+
+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` | Per node, on `item` only: a tab that is disabled. |
+| `active` | Per node, on `item` and `panel`: the selected tab's trigger and its shown pane. |
 
 ## Events
 
@@ -1175,6 +1596,52 @@ route, so it is SSR-safe and shareable:
 - `header:prepend` — scope: `BbTabsScrollSlotProps` — Content rendered before the scrollable tab label list (e.g. a left scroll arrow).
 - `label` — scope: `BbTabsSlotProps<K>` — Fallback slot used for all tab labels when no per-tab `label:{key}` slot is provided.
 
+## 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 |
+| --- | --- | --- | --- |
+| `--gap` | `.bb-tabs` | `8px` |  |
+| `--list-bg` | `.bb-tabs-list` | `color-mix(in oklab, var(--bb-text) 8%, transparent)` | The strip behind the triggers |
+| `--list-border` | `.bb-tabs-list` | `transparent` | The strip's edge line: a baseline under the triggers (beside them when vertical), --bb-border-w thick, painted inside the strip. `pill` draws none; `line` sets it to --bb-border |
+| `--p` | `.bb-tabs-list` | `3px` | strip inner padding — the gutter the indicator sits in, and the scroll inset |
+| `--list-r` | `.bb-tabs-list` | `var(--bb-radius)` | strip corners |
+| `--list-h` | `.bb-tabs-list` | `var(--bb-control-h)` | strip min height |
+| `--fs` | `.bb-tabs-list` | `var(--bb-fs)` | trigger label size |
+| `--trigger-gap` | `.bb-tabs-list` | `0px` | space between triggers |
+| `--trigger-px` | `.bb-tabs-list` | `10px` | trigger side padding |
+| `--trigger-r` | `.bb-tabs-list` | `calc(var(--list-r) - var(--p))` | Trigger corners, concentric inside --list-r |
+| `--trigger-min-h` | `.bb-tabs-list` | `calc(var(--list-h) - var(--p) * 2)` | Trigger height inside the padded strip |
+| `--list-fg` | `.bb-tabs-list` | `var(--bb-text-muted)` | inactive trigger label |
+| `--hover-fg` | `.bb-tabs-list` | `var(--bb-text)` | hovered trigger label |
+| `--active-fg` | `.bb-tabs-list` | `var(--bb-text)` | active trigger label |
+| `--active-fw` | `.bb-tabs-list` | `500` | active trigger label weight (inactive labels are 500) |
+| `--indicator-bg` | `.bb-tabs-list` | `var(--bb-panel)` | the indicator's fill |
+| `--indicator-border` | `.bb-tabs-list` | `color-mix(in oklab, var(--bb-text) 8%, transparent)` | The indicator's edge |
+| `--indicator-r` | `.bb-tabs-list` | `var(--trigger-r)` | The indicator's corners — the pill's, concentric inside --list-r |
+| `--indicator-h` | `.bb-tabs-list` | `initial` | The indicator's thickness: its height, its width on a vertical strip. `initial` fills the whole trigger box — the pill; a bar is `2px`, on the trigger's bottom edge (side edge when vertical) |
+| `--indicator-inset` | `.bb-tabs-list` | `0px` | Inset of the indicator from the trigger box — shrinks the pill; a bar keeps its thickness, shortens by it at both ends and floats it above the edge |
+| `--elev` | `.bb-tabs-list` | `var(--bb-elev)` | The theme's resting lift, composed UNDER the indicator's own shadow. Two names because they are two decisions: `--elev` is what the language lifts every plate by, `--indicator-shadow` is this component's own. |
+| `--indicator-shadow` | `.bb-tabs-list` | `0 1px 2px 0 rgb(0 0 0 / 0.06), 0 1px 3px 0 rgb(0 0 0 / 0.08)` | Indicator lift, painted on top of --elev |
+| `--transition-duration` | `.bb-tabs-panes` | `var(--bb-transition-slow)` |  |
+| `--gap` | `.bb-tabs-panes` | `30px` |  |
+| `--max-w` | `.bb-tabs-panes` | `initial` | The strip-width knob must not percolate into pane content: nested tabs rendered inside a pane start with a clean slate |
+
+## Component tree
+
+`BbTabs` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbTabs`, 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 `BbTabs`. A pt part listed as landing there is set on `BbTabs` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbTabs` 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 `BbTabs`'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 `BbTabs`'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 `BbTabs`'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`.
+
+- `BbTabs` _(this component)_
+  - `BbTabsList` _(public — [contract](./BbTabsList.md))_
+    - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
+  - Also mounts `BbTabsPanes`
+
 ## See Also
 
 - [BbAccordion](./BbAccordion.md) — Expands and collapses a content panel.