bitboss-ui 3.0.0-beta.53 → 3.0.0-beta.56

package/dist/ai/BbAccordion.md

@@ -15,6 +15,13 @@
 | pt part | Lands on | In |
 | --- | --- | --- |
 | `pt:header` | the root of `BbBaseButton` | `BbBaseButton` ([contract](./BbBaseButton.md)) |
+| `pt:icon` | the root of `BbIcon` | `BbIcon` ([contract](./BbIcon.md)) |
+
+**CSS variables you can set through those parts** — declared deeper in the tree, so set one on the part that reads it (`pt:<part>="[--name:value]"`), never on `BbAccordion`'s root:
+
+| Variable | Set through | Declared by | What it is |
+| --- | --- | --- | --- |
+| `--w` | `pt:icon` | `BbIcon` | `--w` is set inline by BbIcon from the size prop. The `initial` default seals it: without it an ancestor's `--w` (e.g. a dropdown's width bridge) would inherit in and size the icon. The `--size` indirection stays so higher-specificity rules (e.g. `.bb-badge .bb-icon`) can re-point it. |
 
 ## Usage & Guidelines
 
@@ -38,47 +45,31 @@ Step down the ladder when the composed header doesn't fit:
 - You only need to animate a height change, with no hide/show state at all →
   **`BbSmoothHeight`** (`./BbSmoothHeight.md`).
 
-The public surface is small on purpose: `v-model` (boolean), `eager`,
-`transition-duration`, `id`, `heading-level`, two slots, and the
+The public surface is small on purpose: `v-model` (boolean), `title`,
+`eager`, `transition-duration`, `id`, `heading-level`, three slots, and the
 `update:modelValue` event.
 Everything else is composition.
 
 ### Composing an FAQ
 
 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>`. 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.
+Give each a `title`: the trigger is then ours — the text at the start, a
+chevron at the end that turns when the panel opens — in the default look:
+medium weight, vertical padding, a hairline under each item and bottom padding
+on the panel. Write no chevron, flex row or padding of your own.
 
 **A pricing-page FAQ of independent panels**
 
 ```vue
 <template>
-	<div
-		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
-	>
+	<div class="max-w-md">
 		<BbAccordion
-			v-for="(faq, index) in faqs"
+			v-for="faq in faqs"
 			:key="faq.question"
 			v-model="faq.open"
-			:class="index ? 'border-t border-(--bb-border)' : ''"
+			:title="faq.question"
 		>
-			<template #header="{ open }">
-				<div
-					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium"
-				>
-					<span>{{ faq.question }}</span>
-					<span
-						class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
-						:class="open ? 'rotate-180' : ''"
-					>
-						<BbIcon icon="lucide:chevron-down" size="sm" />
-					</span>
-				</div>
-			</template>
-
-			<p class="px-3 pb-2.5 text-sm text-(--bb-text-muted)">
+			<p class="text-(--bb-text-muted)">
 				{{ faq.answer }}
 			</p>
 		</BbAccordion>
@@ -87,7 +78,7 @@ through `pt:panel` or `.bb-accordion__panel` — collapses with the body.
 
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbAccordion, BbIcon } from 'bitboss-ui';
+import { BbAccordion } from 'bitboss-ui';
 
 type Faq = { question: string; answer: string; open: boolean };
 
@@ -115,6 +106,20 @@ const faqs = ref<Faq[]>([
 </script>
 ```
 
+Two slots change the trigger, the same rule as `BbDialog`'s header:
+
+- **`#title`** replaces the **text only**; the chevron and the default look
+  stay. Use it for rich, passive content: a badge, a code path, a price.
+- **`#header`** replaces the **whole trigger content** — no chevron, no
+  default look, your markup as it is. Reach for it only when the chevron or the
+  layout must go; an accordion written with `#header` before this keeps
+  rendering exactly as it did.
+
+Both render inside the header button, so never put a nested `<button>`/`<a>`
+there. 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.
+
 The header button spans the full width and is the only click target: any
 non-interactive element you slot into it is made click-transparent
 (`pointer-events: none`), so wrappers, icons and badges never swallow the toggle
@@ -122,38 +127,29 @@ click.
 
 That click-transparency is what lets headers carry rich, passive metadata. An
 API-reference disclosure list leans on it: a soft method `BbBadge` and a
-`<code>` path in the header, parameter details in the body — clicking anywhere
-on the row, badge included, toggles the panel.
+`<code>` path in `#title`, parameter details in the body — clicking anywhere
+on the row, badge included, toggles the panel, and the chevron stays.
 
 **An API reference disclosure list**
 
 ```vue
 <template>
-	<div
-		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
-	>
+	<div class="max-w-md">
 		<BbAccordion
-			v-for="(endpoint, index) in endpoints"
+			v-for="endpoint in endpoints"
 			:key="`${endpoint.method}:${endpoint.path}`"
 			v-model="endpoint.open"
-			:class="index ? 'border-t border-(--bb-border)' : ''"
 		>
-			<template #header="{ open }">
-				<div class="flex w-full items-center gap-2 px-3 py-2 text-left">
+			<template #title>
+				<span class="flex items-center gap-2">
 					<BbBadge size="xs" :variant="METHOD_VARIANT[endpoint.method]">{{
 						endpoint.method
 					}}</BbBadge>
 					<code class="truncate font-mono text-xs">{{ endpoint.path }}</code>
-					<span
-						class="ml-auto shrink-0 text-(--bb-text-muted) transition-transform duration-200"
-						:class="open ? 'rotate-180' : ''"
-					>
-						<BbIcon icon="lucide:chevron-down" size="sm" />
-					</span>
-				</div>
+				</span>
 			</template>
 
-			<div class="flex flex-col gap-1.5 px-3 pb-2.5">
+			<div class="flex flex-col gap-1.5">
 				<p class="text-xs text-(--bb-text-muted)">
 					{{ endpoint.summary }}
 				</p>
@@ -176,7 +172,7 @@ on the row, badge included, toggles the panel.
 
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbAccordion, BbBadge, BbIcon } from 'bitboss-ui';
+import { BbAccordion, BbBadge } from 'bitboss-ui';
 import type { BbBadgeProps } from 'bitboss-ui';
 
 type Endpoint = {
@@ -257,11 +253,11 @@ const endpoints = ref<Endpoint[]>([
 
 ### Slot scope: the open flag and the toggle handle
 
-Both slots — `header` and the default (body) slot — receive the same scope,
-`{ open, toggle }`:
+Every slot — `title`, `header` and the default (body) slot — receives the same
+scope, `{ open, toggle }`:
 
 - `open` mirrors the open state (one-way — assigning to it does nothing). Use
-  it to spin a chevron or swap header copy.
+  it to swap header copy (the default chevron turns by itself).
 - `toggle()` flips the panel. In the header it is redundant (the button already
   toggles); its real use is in the **body**, for a "Show less" affordance that
   collapses the panel without reaching back to the header. Writing to your own
@@ -271,25 +267,10 @@ Both slots — `header` and the default (body) slot — receive the same scope,
 
 ```vue
 <template>
-	<div
-		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
-	>
-		<BbAccordion v-model="notes">
-			<template #header="{ open }">
-				<div
-					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium"
-				>
-					<span>Release notes</span>
-					<span
-						class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
-						:class="open ? 'rotate-180' : ''"
-					>
-						<BbIcon icon="lucide:chevron-down" size="sm" />
-					</span>
-				</div>
-			</template>
+	<div class="max-w-md">
+		<BbAccordion v-model="notes" title="Release notes">
 			<template #default="{ toggle }">
-				<div class="flex flex-col items-start gap-1.5 px-3 pb-2.5">
+				<div class="flex flex-col items-start gap-1.5">
 					<p class="text-sm text-(--bb-text-muted)">
 						Dropdown keyboard navigation, smoother select popovers, and a new
 						color picker.
@@ -303,7 +284,7 @@ Both slots — `header` and the default (body) slot — receive the same scope,
 
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbAccordion, BbButton, BbIcon } from 'bitboss-ui';
+import { BbAccordion, BbButton } from 'bitboss-ui';
 
 // Panel starts open so the in-body "Show less" affordance is visible.
 const notes = ref(true);
@@ -325,36 +306,23 @@ to `null`). Prefer a stable key over an index when the list can reorder.
 
 ```vue
 <template>
-	<div
-		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
-	>
+	<div class="max-w-md">
 		<BbAccordion
 			v-for="(plan, index) in plans"
 			:key="plan.name"
-			:class="index ? 'border-t border-(--bb-border)' : ''"
 			:model-value="openIndex === index"
 			@update:model-value="openIndex = $event ? index : null"
 		>
-			<template #header="{ open }">
-				<div
-					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm"
-				>
-					<span class="font-medium">{{ plan.name }}</span>
-					<span class="flex items-center gap-1.5 text-(--bb-text-muted)">
-						{{ plan.price }}
-						<span
-							class="shrink-0 transition-transform duration-200"
-							:class="open ? 'rotate-180' : ''"
-						>
-							<BbIcon icon="lucide:chevron-down" size="sm" />
-						</span>
-					</span>
-				</div>
+			<template #title>
+				<span class="flex items-center justify-between gap-2">
+					{{ plan.name }}
+					<span class="font-normal text-(--bb-text-muted)">{{
+						plan.price
+					}}</span>
+				</span>
 			</template>
 
-			<ul
-				class="flex flex-col gap-1 px-3 pb-2.5 text-sm text-(--bb-text-muted)"
-			>
+			<ul class="flex flex-col gap-1 text-(--bb-text-muted)">
 				<li v-for="feature in plan.features" :key="feature">{{ feature }}</li>
 			</ul>
 		</BbAccordion>
@@ -363,7 +331,7 @@ to `null`). Prefer a stable key over an index when the list can reorder.
 
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbAccordion, BbIcon } from 'bitboss-ui';
+import { BbAccordion } from 'bitboss-ui';
 
 type Plan = { name: string; price: string; features: string[] };
 
@@ -393,50 +361,21 @@ const openIndex = ref<number | null>(0);
 ### Nesting accordions
 
 Panels nest without extra wiring: the body animates with CSS grid rows, so an
-inner panel opening simply grows the outer one. Keep the hierarchy readable with
-padding on the nested body content.
+inner panel opening simply grows the outer one. Each accordion's default look
+and chevron follow its own panel only, and a nested `#header` accordion keeps
+its own markup.
 
 **A settings section with a nested advanced panel**
 
 ```vue
 <template>
-	<div
-		class="max-w-md overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
-	>
-		<BbAccordion v-model="notifications">
-			<template #header="{ open }">
-				<div
-					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium"
-				>
-					<span>Notifications</span>
-					<span
-						class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
-						:class="open ? 'rotate-180' : ''"
-					>
-						<BbIcon icon="lucide:chevron-down" size="sm" />
-					</span>
-				</div>
-			</template>
-			<div class="flex flex-col gap-2 px-3 pb-2.5 text-sm">
+	<div class="max-w-md">
+		<BbAccordion v-model="notifications" title="Notifications">
+			<div class="flex flex-col gap-2">
 				<BbCheckbox v-model="mentions" label="Mentions" />
 				<BbCheckbox v-model="digests" label="Weekly digest" />
-				<BbAccordion v-model="advanced">
-					<template #header="{ open }">
-						<div
-							class="flex w-full items-center justify-between gap-2 py-1 text-left text-sm text-(--bb-text-muted)"
-						>
-							<span>Advanced</span>
-							<span
-								class="shrink-0 transition-transform duration-200"
-								:class="open ? 'rotate-180' : ''"
-							>
-								<BbIcon icon="lucide:chevron-down" size="sm" />
-							</span>
-						</div>
-					</template>
-					<div class="pt-1 pb-1">
-						<BbCheckbox v-model="quiet" label="Quiet hours (22:00–08:00)" />
-					</div>
+				<BbAccordion v-model="advanced" title="Advanced">
+					<BbCheckbox v-model="quiet" label="Quiet hours (22:00–08:00)" />
 				</BbAccordion>
 			</div>
 		</BbAccordion>
@@ -445,7 +384,7 @@ padding on the nested body content.
 
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbAccordion, BbCheckbox, BbIcon } from 'bitboss-ui';
+import { BbAccordion, BbCheckbox } from 'bitboss-ui';
 
 const notifications = ref(true);
 const mentions = ref(true);
@@ -473,11 +412,13 @@ get a near-instant transition automatically.
 **Eager body with a slower transition**
 
 ```vue
-<BbAccordion v-model="state.shipping" eager :transition-duration="350">
-	<template #header>
-		<span class="px-3 py-2 text-sm font-medium">Shipping details</span>
-	</template>
-	<p class="px-3 pb-3 text-sm text-(--bb-text-muted)">
+<BbAccordion
+	v-model="state.shipping"
+	eager
+	title="Shipping details"
+	:transition-duration="350"
+>
+	<p class="text-(--bb-text-muted)">
 		Rendered up front so its text is present even while collapsed.
 	</p>
 </BbAccordion>
@@ -503,8 +444,7 @@ controls, not titles.
 
 ```vue
 <h2>Billing questions</h2>
-<BbAccordion v-model="open" :heading-level="3">
-	<template #header>Can I change plans?</template>
+<BbAccordion v-model="open" :heading-level="3" title="Can I change plans?">
 	Yes, at any time.
 </BbAccordion>
 ```
@@ -513,59 +453,48 @@ controls, not titles.
 
 `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.
+`header` (the trigger button), `title` (its text), `icon` (the chevron) and
+`panel` (the region the header controls). State: `open`. `title` and `icon`
+exist only without a `#header` slot. The default look is one class deep, so a
+`pt:*` utility overrides it.
+
+The pricing-page FAQ above, restyled through those parts: a tighter trigger
+and a hover underline on `pt:header` (children are click-transparent, so hover
+belongs on the button), a brand chevron on `pt:icon`, a heavier title while
+open on `pt:title:open`, and the answer's colour and padding on `pt:panel`
+(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)"
-	>
+	<div class="max-w-2xl">
 		<BbAccordion
-			v-for="(faq, index) in faqs"
+			v-for="faq 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)' : ''"
+			pt:header="py-3 hover:underline"
+			pt:icon="text-(--bb-primary)"
+			pt:panel="pb-3 text-(--bb-text-muted)"
+			pt:title:open="font-semibold"
+			:title="faq.question"
 		>
-			<template #header="{ open }">
-				<span>{{ faq.question }}</span>
-				<span
-					class="shrink-0 text-(--bb-text-muted) transition-transform duration-200"
-					:class="open ? '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>
+			{{ faq.answer }}
 		</BbAccordion>
 	</div>
 </template>
 
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbAccordion, BbIcon } from 'bitboss-ui';
+import { BbAccordion } 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.
+// Same pricing-page FAQ as `FaqList.vue`, restyled through passthrough: a
+// tighter trigger and a hover underline on `pt:header`, a brand chevron on
+// `pt:icon`, a heavier title while open on `pt:title:open`, and the answer's
+// colour and padding on `pt:panel` (inside the collapsing region, so it
+// collapses with the body).
 const faqs = ref<Faq[]>([
 	{
 		question: 'Can I change plans mid-cycle?',
@@ -599,8 +528,6 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 ### Works well with
 
-- `BbIcon` — a rotating chevron in the header, driven by the slot's `open` (see
-  the FAQ example).
 - `BbBadge` — counts or soft method/status pills in the header (see the API
   reference example); non-interactive content stays click-transparent.
 - `BbCollapsible` / `BbSmoothHeight` — the rungs to step down to when the
@@ -630,8 +557,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   the accordion in your own `<hN>` instead.
 - Keyboard comes free with the native button: Tab to the header, Enter/Space
   toggles. Closed content is `inert`, so it can never be tabbed into.
-- Provide a visible, meaningful header label; the chevron is decorative (mark
-  custom SVGs `aria-hidden`).
+- Provide a visible, meaningful header label (`title`); the built-in chevron
+  is decorative and hidden from assistive tech (mark your own SVGs in a
+  `#header` `aria-hidden`).
 - Honours `prefers-reduced-motion` via the underlying `BbCollapsible`.
 
 ## v-model
@@ -642,11 +570,12 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 | 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`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbAccordionProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `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`, `icon`, `panel`, `root`, `title`. States: `open`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbAccordionProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `eager` | `boolean \| undefined` | `false` |  | Renders the content at mount, while closed, instead of on the first open. Closed content is `inert` and `aria-hidden` either way. |
 | `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | Wraps the header button in a heading of this level (`<h1>`–`<h6>`, the APG accordion shape) so it joins the page outline: under an `<h2>`, pass `3`. Its margins and font are reset. Omitted, no heading. |
 | `id` | `string \| undefined` |  |  | The root's `id`; the header button's id (`<id>_header`) derives from it. Generated when omitted. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. An accordion with no `v-model` starts closed. |
+| `title` | `string \| undefined` |  |  | The trigger's text, with a chevron at its end that turns when open, in the default look (padding, a hairline under the item). `#title` replaces the text only; `#header` replaces the whole trigger (no chevron, no default look). |
 | `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |
 
 ## Passthrough parts and states
@@ -656,7 +585,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | Part | What it is |
 | --- | --- |
 | `root` | The accordion's outer element: the header and its panel. |
-| `header` | The trigger button that opens and closes the panel. Its content is your slot markup — there is no chevron of ours, so no `icon` part. |
+| `header` | The trigger button that opens and closes the panel. |
+| `title` | The trigger's text (`title` / `#title`). Absent under a `#header` slot, which replaces the whole trigger content. |
+| `icon` | The chevron at the trigger's end, turned when open. Absent under a `#header` slot. |
 | `panel` | The region the header controls (the ARIA accordion panel). |
 
 States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
@@ -672,7 +603,16 @@ States are listed in precedence order: when two are on at once and their entries
 ## Slots
 
 - `default` — scope: `BbAccordionToggleSlotProps` `{ open: boolean; toggle: () => void }` — The collapsible body content shown when the accordion is open.
-- `header` — scope: `BbAccordionToggleSlotProps` `{ open: boolean; toggle: () => void }` — Content rendered inside the accordion header button.
+- `header` — scope: `BbAccordionToggleSlotProps` `{ open: boolean; toggle: () => void }` — Replaces the whole trigger content: the text and the chevron, and the default look with them. The button, its ARIA and its focus ring stay.
+- `title` — scope: `BbAccordionToggleSlotProps` `{ open: boolean; toggle: () => void }` — Replaces the trigger's text only (the `title` prop); the chevron and the default look stay.
+
+## 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 | Default | What it is |
+| --- | --- | --- |
+| `--py` | `16px` | trigger padding, and the panel's bottom padding |
 
 ## Component tree
 
@@ -683,9 +623,10 @@ States are listed in precedence order: when two are on at once and their entries
 - **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 `manifest/components/BbAccordion.tree.json`.
 
-- `BbAccordion` _(this component)_ — its own template binds: `header` → `BbBaseButton`, `panel` → `div.bb-accordion__panel`
+- `BbAccordion` _(this component)_ — its own template binds: `header` → `BbBaseButton`, `title` → `span.bb-accordion__title`, `icon` → `BbIcon`, `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`
+  - Also mounts `BbIcon`
 
 ## See Also
 

package/dist/ai/BbAlert.md

@@ -51,7 +51,9 @@ Pick a variant by intent, not decoration. `outline` is the quietest (neutral
 info); `primary` carries a branded, actionable note; `warning` flags something
 the user should attend to; `destructive` reports a failure or dangerous state.
 An alert reads far better with a matching leading `icon`, so treat variant and
-icon as a pair.
+icon as a pair, and pair them once: the object form of the plugin's
+`alertVariants` sets each variant's icon for the whole app (see Variant icons
+below).
 
 There is no `success` or `info` alert, on purpose (the built-in ramps stay
 closed): a confirmation is usually a toast, and a neutral note is `outline`
@@ -96,13 +98,38 @@ with an icon. When an app needs one anyway, register it with the plugin's
 The default variant is `outline`. `warning` and `destructive` are treated as
 high-priority for accessibility (see below).
 
-There is no `success` (or `positive`) variant, and it will not be added — the
+There is no built-in `success` (or `positive`) variant, and none will be added — the
 shared status vocabulary is closed to `danger`/`warn` by ruling, see
 [Design Tokens § Brand knobs](./guides/design-tokens.md#brand-knobs-what-a-theme-builder-sets)
 ("state colors are project-owned"). Reach for `primary` for a positive
-confirmation, or register your own variant (below) if the project needs a
+confirmation, or register your own project variant (below) if you need a
 distinct success tone.
 
+#### Variant icons
+
+```ts
+// vite.config.ts (Nuxt: the `bitboss` key)
+bitbossUi({
+	alertVariants: {
+		warning: { icon: 'lucide:triangle-alert' },
+		destructive: { icon: 'lucide:circle-x' },
+		success: { icon: 'lucide:circle-check' }, // a project variant, with its icon
+	},
+});
+```
+
+An alert without its own `icon` shows its variant's; its own `icon` wins;
+`hide-icon` hides either, and does nothing when there is no icon:
+
+```vue
+<BbAlert variant="warning" title="Heads up" />
+<BbAlert variant="warning" icon="lucide:clock" title="Runs at midnight" />
+<BbAlert variant="warning" hide-icon title="Plain" />
+```
+
+A key registers its name (a built-in name only gets its icon); the array form
+still just registers names.
+
 #### Registering project variants
 
 Variants are an open registry, not a closed enum. The vite/nuxt plugin's
@@ -128,14 +155,14 @@ bitbossUi({
 		transparent
 	); /* body + close */
 	--bg: transparent;
-	border-color: var(--bb-border);
+	--border-color: var(--bb-border);
 }
 ```
 
 One a11y catch: only `warning` and `destructive` are hard-coded as
 high-priority. A custom variant — however alarming its name — announces as
-`role="status"` / `aria-live="polite"` unless you also pass `role="alert"` /
-`aria-live="assertive"` on urgent instances.
+`role="status"` / `aria-live="polite"` unless you pass `role="alert"` on
+urgent instances (the role brings `aria-live="assertive"` with it).
 
 ### Dismissal and v-model
 
@@ -447,7 +474,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   variant: `warning` / `destructive` announce as `role="alert"` /
   `aria-live="assertive"`; every other variant (built-in or custom) uses
   `role="status"` / `aria-live="polite"`. Override per instance with the
-  `role` / `aria-live` props only with a specific reason.
+  `role` / `aria-live` props only with a specific reason. A `role` alone
+  brings its politeness (`alert` → `assertive`, `status` → `polite`); an
+  explicit `aria-live` wins over it.
 - The alert is `aria-atomic`, so updating its text re-announces the whole
   message rather than a fragment.
 - The close button ships with a localised label (plugin `locale`); pass
@@ -464,10 +493,11 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | 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: —. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbAlertProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `ariaLive` | `"off" \| "polite" \| "assertive" \| undefined` |  |  | ARIA live region politeness. Defaults to `'assertive'` for destructive/warning variants, otherwise `'polite'`. |
+| `ariaLive` | `"off" \| "polite" \| "assertive" \| undefined` |  |  | ARIA live region politeness. Unset, it follows `role` when you set one (`'alert'` → `'assertive'`, `'status'` → `'polite'`), else the variant: `'assertive'` for destructive/warning, 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. |
-| `icon` | `string \| undefined` |  |  | Name of a registered icon to use, or a full raw `<svg>` string (e.g. an SVG file imported with `?raw`). |
+| `hideIcon` | `boolean \| undefined` | `false` |  | Hide the icon, its own or its variant's; with neither it does nothing. |
+| `icon` | `string \| undefined` |  |  | Name of a registered icon to use, or a full raw `<svg>` string (e.g. an SVG file imported with `?raw`). Without one, the variant's icon from the build plugin's `alertVariants` object form shows (none by default). |
 | `iconSize` | `number \| CssSize \| keyof Sizes \| undefined` | `"16"` |  | Size of the icon to use. |
 | `modelValue` | `boolean \| undefined` | `true` |  | Used by v-model. Alerts are visible on mount; the model dismisses them. |
 | `role` | `"alert" \| "status" \| undefined` |  |  | Accessibility role for the alert container. Defaults to `'alert'` for destructive/warning variants, otherwise `'status'`. |
@@ -483,7 +513,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | Part | What it is |
 | --- | --- |
 | `root` | The alert box. |
-| `icon` | The leading glyph — rendered only when an `icon` is set. |
+| `icon` | The leading glyph — its `icon`, else its variant's from the build config; never with `hide-icon`. |
 | `title` | The heading line. |
 | `text` | The body copy. |
 | `close` | The ✕ that dismisses the alert. |
@@ -507,10 +537,10 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--px` | `10px` | side padding of the plate |
 | `--py` | `6px` | top/bottom padding of the plate, and the close button's inset from those edges |
 | `--gap` | `4px` | icon column → content gap, reused between title parts and in the close button's reserved width |
-| `--title-size` | `14px` | icon column → content gap, reused between title parts and in the close button's reserved width |
+| `--title-size` | `14px` | title font size |
 | `--title-lh` | `18px` | title line box — the close button is centred on it |
-| `--text-size` | `14px` | title line box — the close button is centred on it |
-| `--text-lh` | `18px` |  |
+| `--text-size` | `14px` | body text font size |
+| `--text-lh` | `18px` | body text line height |
 | `--close-size` | `16px` | close glyph; also the width reserved at the end of the title |
 | `--bg` | `transparent` | plate fill |
 | `--fg` | `var(--bb-text)` | title and icon |
@@ -532,4 +562,4 @@ Set these on the element, or on a class you put on it, to retune this component
 
 ## See Also
 
-- [BbToast](./BbToast.md) — Shows transient notification messages (includes the co-located BbToastPortal export).
+- [useToast](./composables/useToast.md)