bitboss-ui 3.0.0-beta.25 → 3.0.0-beta.26

package/README.md

@@ -60,11 +60,12 @@ Full detail: `ai/guides/installation-and-plugin-setup.md`.
 `Bb*DirectivePlugin` for each, for app-level registration. Prefer the directive
 over the component for simple no-slot cases.
 
-### Base\* primitives
+### Internal building blocks
 
-The styled `Base*` input controls and the input chrome (`BbBaseInputContainer`,
-`CommonInputWrapper` — label, prepend/append, prefix/suffix, clear button,
-spacing) are **internal composition layers and are not exported**. Use the full
+The shared field chrome (`CommonField`, `CommonFieldInput` — label,
+prepend/append, prefix/suffix, clear button, spacing) and the other `Common*`
+pieces are **internal and are not exported**; every form control renders them
+itself. Use the full
 public inputs (`BbTextInput`, `BbSelect`, …); pass `hideLabel` for a
 bare/inline control. The exported primitives are **`BbBaseButton`** and the
 presentational glyphs **`BbBaseCheckboxIcon`**, **`BbBaseRadioIcon`**,
@@ -81,6 +82,25 @@ Product-ready components with labels, hints, errors, and consistent styling:
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
 
+### Passthrough (`pt`)
+
+Every component names a short list of **parts** and **states**, and a
+`pt:<part>` / `pt:<part>:<state>` prop reaches that part with a class list —
+or, in the object form, a style and attributes — typed and linted in the
+attribute form, on top of any variant. Classes append to ours, attributes win, listeners run after the
+component's own handler. A build-time `pt` map in the Vite / Nuxt plugin seeds
+every instance. Grammar, merge rules and the per-component vocabulary:
+[`ai/guides/passthrough.md`](ai/guides/passthrough.md).
+
+```vue
+<BbButton
+	prepend:icon="lucide:save"
+	pt:icon="text-emerald-600"
+	pt:icon:loading="animate-pulse"
+>Save</BbButton>
+<BbTable :items="rows" pt:row:highlighted="bg-amber-50" />
+```
+
 ### Exported component types
 
 For the public **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BbTableEvents`), plus supporting shapes like `BbDropdownItem` and `DropdownGroupItemsGetter`. Use them for typed wrappers and design-system layers; the docs list the full set per component.
@@ -375,6 +395,50 @@ is left alone. For a bulk sweep of a v2 codebase, opt into the fix:
 `assumeV2` is off by default because the two readings produce opposite
 layouts — turn it on only for files you know came from v2, then turn it off.
 
+#### Glyph state colours: `no-state-text-color`
+
+`bitboss-ui/no-state-text-color` flags a colour-shade text utility —
+`text-red-800`, not `text-xs` — in a toggle glyph's state entry:
+`pt:icon:errors` / `warnings` / `disabled` on `BbCheckbox`, `BbRadio`,
+`BbSwitch` and their groups, or `pt:root:<state>` on their standalone glyphs. Those states paint
+from the glyph's own `--accent`, never from `color`, so the class lands and
+paints nothing. CSS cannot let a state entry's colour win while a resting
+`pt:icon` colour loses — both are just a `color` utility by then — so the rule
+says so where the class is written, and for errors and warnings offers the
+spelling that works:
+
+```vue
+<!-- warns: paints nothing -->
+<BbCheckbox pt:icon="text-blue-500" pt:icon:errors="text-red-800" />
+<!-- blue at rest, red-800 while erroring -->
+<BbCheckbox
+	pt:icon="text-blue-500"
+	pt:icon:errors="[--accent:var(--color-red-800)]"
+/>
+```
+
+It reads literal classes only (the attribute, a bound string or `{ class }`,
+and a literal `:pt` object); a dynamic value is not checked.
+
+#### Field box borders: `no-box-border-color`
+
+`bitboss-ui/no-box-border-color` flags a colour-shade border utility —
+`border-green-500`, not `border-2` — in the **base** `pt:box` of a text-like
+control. The box paints its errors / warnings frame over the resting border,
+but a border utility sets `border-color` itself and wins, so the field keeps
+looking valid. The rule suggests the resting-border token instead; a state
+entry is the state itself and is never reported:
+
+```vue
+<!-- errors: hides the error frame -->
+<BbTextInput pt:box="border-green-500" />
+<!-- green at rest, the error frame while erroring, red-800 as the error style -->
+<BbTextInput
+	pt:box="[--border-color:var(--color-green-500)]"
+	pt:box:errors="border-red-800"
+/>
+```
+
 #### The one rule that reads CSS: `no-unknown-token`
 
 `bitboss-ui/no-unknown-token` flags a bare `var(--bb-…)` naming a token the

package/bin/bitboss-ui.mjs

@@ -96,7 +96,7 @@ function coreRules(version) {
 
 1. **Start at the AI Router**: \`${ROUTER}\` — which file to open next (do not dump the full catalogue into context).
 2. **Obey the agent contract**: \`${CONTRACT}\`.
-3. **Prefer \`Bb*\` consumer components**; never use entries marked "Reference Only - Internal" unless the user explicitly asks for internals. (\`BbBaseButton\` is consumer API; most other \`BbBase*\` form primitives are not.)
+3. **Prefer \`Bb*\` consumer components**; never use entries marked "Reference Only - Internal" unless the user explicitly asks for internals. (\`BbBaseButton\` and the \`BbBase*Icon\` glyphs are consumer API; the \`Common*\` building blocks are not.)
 4. **Never invent prop/event/slot names** — open \`${KNOWLEDGE_BASE}/<ComponentName>.md\` (Usage & Guidelines first) or validate against \`${KNOWLEDGE_BASE}/components.json\`.
 5. **Icons**: discover names first; never invent them (\`${KNOWLEDGE_BASE}/guides/icons-policy.md\`).
 6. **Item-driven components**: declarative \`items\` / \`item-text\` / \`item-value\`, \`dependencies\`, \`enforce-coherence\` — no manual watchers for coherence.

package/dist/ai/BbAccordion.md

@@ -8,6 +8,14 @@
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbAccordion.md](./source/BbAccordion.md)
 
+## Reachable through `BbAccordion`
+
+`BbAccordion` mounts other components (all of them: _Component tree_, near the end). These are the parts of its API that land inside them. Use them — never `:deep()` on an inner class, never an import of an internal component.
+
+| pt part | Lands on | In |
+| --- | --- | --- |
+| `pt:header` | the root of `BbBaseButton` | `BbBaseButton` ([contract](./BbBaseButton.md)) |
+
 ## Usage & Guidelines
 
 ### When to use
@@ -38,9 +46,9 @@ Everything else is composition.
 
 The classic pricing-page FAQ is independent panels — each with its own boolean.
 The `header` slot is rendered **inside the header button** — so put text and an
-indicator there, never a nested `<button>`/`<a>`. Style the body on the slotted
-content, not the panel: the underlying collapsible forces a true zero-height
-collapsed state and strips padding/borders you put on the panel itself.
+indicator there, never a nested `<button>`/`<a>`. The panel is a block box
+inside the collapsing region, so padding, a border or a background on it —
+through `pt:panel` or `.bb-accordion__panel` — collapses with the body.
 
 **A pricing-page FAQ of independent panels**
 
@@ -481,6 +489,90 @@ references): the body region gets your id and the header gets `<id>_header`,
 already cross-wired via `aria-controls`/`aria-labelledby`. Omitted, a unique id
 is generated for you.
 
+### 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`,
+`header` (the trigger button) and `panel` (the region the header controls). State:
+`open`. There is no chevron of ours — the header is your slot markup — so there
+is no `icon`.
+
+The pricing-page FAQ above, restyled through those parts: layout, type and
+hover on `pt:header` (children are click-transparent, so hover belongs on the
+button), a heavier weight on `pt:header:open`, join lines on `pt:root`. Padding
+can go on `pt:panel`: the panel sits inside the collapsing region, so it
+collapses with the body.
+
+**pt:header — the FAQ trigger, a wash while open**
+
+```vue
+<template>
+	<div
+		class="max-w-2xl overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
+	>
+		<BbAccordion
+			v-for="(faq, index) in faqs"
+			:key="faq.question"
+			v-model="faq.open"
+			pt:header="flex items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium hover:underline"
+			pt:header:open="font-semibold"
+			pt:panel="text-sm"
+			:pt:root="index ? 'border-t border-(--bb-border)' : ''"
+		>
+			<template #header="{ value }">
+				<span>{{ faq.question }}</span>
+				<span
+					class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
+					:class="value ? 'rotate-180' : ''"
+				>
+					<BbIcon icon="lucide:chevron-down" size="sm" />
+				</span>
+			</template>
+
+			<p class="px-3 pb-2.5 text-(--bb-text-muted)">
+				{{ faq.answer }}
+			</p>
+		</BbAccordion>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbAccordion, BbIcon } from 'bitboss-ui';
+
+type Faq = { question: string; answer: string; open: boolean };
+
+// Same pricing-page FAQ as `FaqList.vue`, restyled through passthrough:
+// layout and hover on `pt:header`, a heavier weight on `pt:header:open`,
+// join lines on `pt:root`. Padding may go on `pt:panel` or the slotted body
+// alike: the panel is inside the collapsing region, so both collapse.
+const faqs = ref<Faq[]>([
+	{
+		question: 'Can I change plans mid-cycle?',
+		answer:
+			'Yes. Upgrades take effect immediately and are prorated; downgrades apply at the next renewal.',
+		open: true,
+	},
+	{
+		question: 'Do you offer annual billing?',
+		answer:
+			'Annual plans are billed once per year at a 20% discount versus monthly.',
+		open: false,
+	},
+	{
+		question: 'What happens when I exceed my seat limit?',
+		answer:
+			'New invites pause until you add seats or free an existing one. Usage never auto-charges.',
+		open: false,
+	},
+]);
+</script>
+```
+
+A listener on `pt:header` runs after the toggle, never instead of it. The full
+grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
 ### Works well with
 
 - `BbIcon` — a rotating chevron in the header, driven by the slot's `value` (see
@@ -499,8 +591,6 @@ is generated for you.
   belong in the body.
 - **Don't build a group wrapper** with watchers that force-close siblings —
   derive `model-value` from one active key instead (single-open above).
-- **Don't put padding/borders on the panel itself** expecting them to collapse —
-  the collapsed state zeroes them; style the slotted content.
 - **Don't add `v-if`/`v-show` around the body** to "optimize" — deferred
   mounting is already the default; `eager` is the explicit opt-out.
 - **Hover styles on non-interactive header children won't fire** (they are
@@ -527,6 +617,7 @@ is generated for you.
 
 | 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: `header`, `panel`, `root`. States: `open`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
 | `id` | `string \| undefined` |  |  | The identifier of the component. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. An accordion with no `v-model` starts closed. |
@@ -541,6 +632,19 @@ is generated for you.
 - `default` — scope: `BbAccordionToggleSlotProps` — The collapsible body content shown when the accordion is open.
 - `header` — scope: `BbAccordionToggleSlotProps` — Content rendered inside the accordion header button.
 
+## Component tree
+
+`BbAccordion` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbAccordion`, 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 `BbAccordion`. A pt part listed as landing there is set on `BbAccordion` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbAccordion` 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 `BbAccordion`'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 `BbAccordion`'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 `BbAccordion`'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`.
+
+- `BbAccordion` _(this component)_ — its own template binds: `header` → `BbBaseButton`, `panel` → `div.bb-accordion__panel`
+  - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
+  - `BbCollapsible` _(public — [contract](./BbCollapsible.md))_ — its own pt parts (`BbCollapsible`): `content` → `component.bb-collapsible__content`
+
 ## See Also
 
 - [BbCollapsible](./BbCollapsible.md) — Toggles visibility of collapsible content blocks.

package/dist/ai/BbAlert.md

@@ -8,6 +8,21 @@
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbAlert.md](./source/BbAlert.md)
 
+## Reachable through `BbAlert`
+
+`BbAlert` mounts other components (all of them: _Component tree_, near the end). These are the parts of its API that land inside them. Use them — never `:deep()` on an inner class, never an import of an internal component.
+
+| pt part | Lands on | In |
+| --- | --- | --- |
+| `pt:icon` | the root of `BbIcon` | `BbIcon` ([contract](./BbIcon.md)) |
+| `pt:close` | the root of `ClearableButton` | `ClearableButton` _(internal)_ |
+
+**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 `BbAlert`'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` indir… |
+
 ## Usage & Guidelines
 
 ### When to use
@@ -344,6 +359,51 @@ const publish = () => {
 </script>
 ```
 
+### Restyling with passthrough
+
+`pt` reaches a named part with a class list — or, in the object form, a
+style and attributes. Parts: `root` (the box), `icon` (the leading glyph),
+`title` (the heading), `text` (the body copy), `close` (the ✕). The column
+that wraps title and text is layout, not a part. No states — an alert is
+either mounted or gone.
+
+An overdue invoice banner, restyled through those parts: a hair of top offset
+on `pt:icon` so the glyph sits with wrapped copy, `text-sm` on `pt:text`, a
+tighter tracking on `pt:title`.
+`hide-close` — this is page state until the invoice is paid, not a snooze.
+
+**pt:icon / pt:title / pt:text — invoice overdue**
+
+```vue
+<template>
+	<div class="max-w-2xl">
+		<BbAlert
+			hide-close
+			icon="lucide:triangle-alert"
+			pt:icon="mt-0.5"
+			pt:text="text-sm"
+			pt:title="tracking-tight"
+			text="Globex · €2,400 due 4 Sep. Record a payment or send a reminder — dunning is paused while this stays open."
+			title="INV-1043 is 7 days overdue"
+			variant="warning"
+		/>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbAlert } from 'bitboss-ui';
+
+// Invoice-record overdue banner, restyled through passthrough: a hair of
+// top offset on `pt:icon` so the glyph sits with wrapped copy, `text-sm` on
+// `pt:text` and a tighter tracking on `pt:title`. `hide-close` — this is page state,
+// not a snooze; the ✕ is a different part, taught with a listener.
+</script>
+```
+
+A listener on `pt:close` runs after the alert closes, never instead of it. The
+full grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
 ### Works well with
 
 - `BbToast` — pair them: the toast confirms _the action_ ("Saved"), the alert
@@ -388,6 +448,7 @@ const publish = () => {
 
 | 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: `close`, `icon`, `root`, `text`, `title`. States: . `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `ariaLive` | `"off" \| "polite" \| "assertive" \| undefined` |  |  | ARIA live region politeness. Defaults to `'assertive'` for destructive/warning variants, otherwise `'polite'`. |
 | `closeLabel` | `string \| undefined` |  |  | Visually hidden string used to label the close button. |
 | `hideClose` | `boolean \| undefined` | `false` |  | Defines whether to hide the close button. |
@@ -412,7 +473,7 @@ const publish = () => {
 
 ## 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; the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
+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 | Default | What it is |
 | --- | --- | --- |
@@ -430,6 +491,18 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--border-color` | `color-mix(in oklab, var(--bb-text) 15%, transparent)` | Plate border |
 | `--elev` | `var(--bb-elev)` | Resting lift. A local, so a page that already sits on a card can flatten one alert (`<BbAlert style="--elev: none">`) without unsetting the theme's lift everywhere. |
 
+## Component tree
+
+`BbAlert` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbAlert`, 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 `BbAlert`. A pt part listed as landing there is set on `BbAlert` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbAlert` 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 `BbAlert`'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 `BbAlert`'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 `BbAlert`'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`.
+
+- `BbAlert` _(this component)_ — its own template binds: `icon` → `BbIcon`, `close` → `ClearableButton`, `title` → `div.bb-alert__title`, `text` → `div.bb-alert__text`
+  - Also mounts `BbIcon`, `ClearableButton`
+
 ## See Also
 
 - [BbToast](./BbToast.md) — Shows transient notification messages (includes the co-located BbToastPortal export).

package/dist/ai/BbAsterisk.md

@@ -50,9 +50,36 @@ perceive), and never assume the asterisk is doing accessibility work.
 with `requiredAsterisk: false` there is no way to render the marker through
 them at all — placing `BbAsterisk` by hand is then the only route.
 
+### Restyling with passthrough
+
+`pt` reaches the one part with a class list — or, in the object form, a
+style and attributes. Part: `root` (the marker span — its only props are the passthrough ones). No states — nothing it paints is a
+state.
+
+With one part, `pt:root` is plain `class` with extra letters: write `class`
+/ `style` on the tag, as on any element. `pt:root` stays for uniformity —
+the global map, the object form and a wrapper that spreads props address
+every component the same way.
+
+The default paint is `--bb-danger`; `class` is how you retint it. The
+control's `required` still carries the requirement.
+
+**class — a softened required marker**
+
+```vue
+<span
+	class="text-sm font-medium"
+>Workspace name<BbAsterisk class="text-(--bb-warn)" /></span>
+```
+
+The full grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
 ## Props
 
-- None.
+| 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: `root`. States: . `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 
 ## Events
 

package/dist/ai/BbAvatar.md

@@ -8,6 +8,20 @@
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbAvatar.md](./source/BbAvatar.md)
 
+## Reachable through `BbAvatar`
+
+`BbAvatar` mounts other components (all of them: _Component tree_, near the end). These are the parts of its API that land inside them. Use them — never `:deep()` on an inner class, never an import of an internal component.
+
+| pt part | Lands on | In |
+| --- | --- | --- |
+| `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 `BbAvatar`'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` indir… |
+
 ## Usage & Guidelines
 
 ### When to use
@@ -499,6 +513,62 @@ Platform notes: the component is SSR-safe (Nuxt/Inertia) with no client-only
 markup; the only global config it reads is `iconDefaultSizes` for the size
 keys.
 
+### Restyling with passthrough
+
+`pt` reaches each part with a class list — or, in the object form, a
+style and attributes. Parts: `root` (the avatar frame) and `icon` (the default
+user glyph). No states — nothing it paints is a state.
+
+`icon` exists only while the fallback shows (no image, or it failed) and the
+default slot is not overridden; when a photo or your own initials render,
+`pt:icon` lands nowhere. For the frame, `pt:root` is plain `class` with extra
+letters: write `class` / `style` on the tag, as on any element. `pt:root`
+stays for uniformity — the global map, the object form and a wrapper that
+spreads props address every component the same way.
+
+A design-review stack, restyled with plain `class`: a panel-colored ring on
+`class` keeps overlapped edges readable, and every avatar after the first
+pulls in. The image and the fallback wrapper are not parts — don't reach for
+`:deep(.bb-avatar)`.
+
+**class — reviewer stack ring**
+
+```vue
+<template>
+	<div class="flex">
+		<BbAvatar
+			v-for="(reviewer, index) in reviewers"
+			:key="reviewer.name"
+			:alt="reviewer.name"
+			:pt:root="
+				index ? '-ml-3 ring-2 ring-(--bb-panel)' : 'ring-2 ring-(--bb-panel)'
+			"
+			size="40"
+			>{{ reviewer.initials }}</BbAvatar
+		>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbAvatar } from 'bitboss-ui';
+
+type Reviewer = { name: string; initials: string };
+
+// Design-review stack, restyled through passthrough: a panel-colored ring on
+// `pt:root` (the frame) so overlapped edges stay readable, pull-in on every
+// avatar after the first. The image and fallback are not parts.
+const reviewers: Reviewer[] = [
+	{ name: 'Ada Lovelace', initials: 'AL' },
+	{ name: 'Grace Hopper', initials: 'GH' },
+	{ name: 'Alan Turing', initials: 'AT' },
+	{ name: '2 more reviewers', initials: '+2' },
+];
+</script>
+```
+
+The full grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
 ### Works well with
 
 - [`BbIndicator`](./BbIndicator.md) — floating presence dots and counts (see above).
@@ -544,6 +614,7 @@ available in visible text or an adjacent label.
 
 | 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: `icon`, `root`. States: . `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `alt` | `string \| undefined` | `""` |  | Alternative text for the image, used for accessibility. |
 | `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"md"` |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size par… |
 | `sizes` | `string \| undefined` |  |  | Sizes attribute for the image, used with `srcset`. |
@@ -561,13 +632,26 @@ available in visible text or an adjacent label.
 
 ## 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; the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
+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 | Default | What it is |
-| --- | --- | --- |
-| `--bg` | `var(--bb-primary)` | fallback surface (an image covers it) |
-| `--fg` | `var(--bb-primary-fg)` | Initials; the built-in icon is an 80/20 mix of this toward --bg |
-| `--default-icon-size` | `clamp(14px, calc(var(--size) * 0.7), 48px)` | Built-in fallback icon: 70% of the avatar, floored at 14px and capped at 48px. `--size` is the avatar's own box, set inline from the `size` prop. |
+| Property | Set on | Default | What it is |
+| --- | --- | --- | --- |
+| `--bg` | `.bb-avatar` | `var(--bb-primary)` | fallback surface (an image covers it) |
+| `--fg` | `.bb-avatar` | `var(--bb-primary-fg)` | Initials; the built-in icon is an 80/20 mix of this toward --bg |
+| `--default-icon-size` | `.bb-avatar` | `clamp(14px, calc(var(--size) * 0.7), 48px)` | Built-in fallback icon: 70% of the avatar, floored at 14px and capped at 48px. `--size` is the avatar's own box, set inline from the `size` prop. |
+| `--size` | `.bb-avatar__default-icon` | `var(--default-icon-size)` |  |
+
+## Component tree
+
+`BbAvatar` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbAvatar`, 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 `BbAvatar`. A pt part listed as landing there is set on `BbAvatar` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbAvatar` 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 `BbAvatar`'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 `BbAvatar`'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 `BbAvatar`'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`.
+
+- `BbAvatar` _(this component)_ — its own template binds: `icon` → `BbIcon`
+  - Also mounts `BbIcon`
 
 ## See Also