bitboss-ui 3.0.0-beta.63 → 3.0.0-beta.65

package/dist/ai/composables/useBbConfig.md

@@ -16,13 +16,14 @@ plugin (`bitbossUi({ ... })`) and cannot be changed at runtime.
 
 Use it for exactly one job: switching the locale of locale-aware components
 (built-in labels, close buttons, table/pagination strings) while the app runs.
+`locale` reads the current setting back, read-only.
 
 ## Import
 
 ```ts
 import { useBbConfig } from 'bitboss-ui';
 
-const { setConfig } = useBbConfig();
+const { setConfig, locale } = useBbConfig();
 ```
 
 ## API
@@ -37,6 +38,12 @@ declare function setConfig(patch: Partial<DynamicConfig>): void;
 Merges the patch into **this app's** config. The change is immediate and
 reactive — every mounted component in that app which reads the key updates.
 
+### `locale`
+
+A read-only `ComputedRef` of this app's locale exactly as it was set (`'it'`,
+`'it-IT'`), following every `setConfig`. Read it to pick your own words in the
+same language as the library's (the Inertia helpers' `messages.ts` does).
+
 ### Per-request locale under SSR
 
 The config is held **per Vue app**, and SSR gives every request its own app,

package/dist/ai/composables/useConfirm.md

@@ -69,7 +69,8 @@ declare function close(): void;
 Hides the newest open dialog opened through the same `useConfirm()` (never
 another component's) without resolving anything. Its purpose is multi-step
 flows: with `autoClose: false` the dialog stays open after the promise resolves,
-and you call `close()` when your flow is done. Don't use it as a substitute for
+and you call `close()` when your flow is done. Server work is not such a flow:
+it goes in `yes.onClick` (see **Async work before the dialog closes**). Don't use it as a substitute for
 the buttons — a `confirm()` closed this way before any button ran leaves its
 promise pending.
 
@@ -166,6 +167,43 @@ const post = await confirm({
 // post is the api result, or false when the user declined
 ```
 
+An Inertia visit goes in `onClick` too. It returns no promise, so wrap it (the
+same wrapper as BbDialog's `save()`): Yes spins for the whole visit, and the
+dialog closes when it settles. A failed visit rejects `confirm()` and still
+closes the dialog.
+
+```ts
+import { router } from '@inertiajs/vue3';
+import { useConfirm } from 'bitboss-ui';
+
+const { confirm } = useConfirm();
+
+const destroy = (url: string) =>
+	new Promise<void>((resolve, reject) => {
+		router.delete(url, {
+			onSuccess: () => resolve(),
+			onError: (errors) => reject({ errors }),
+			// Cut short by another visit: resolve. Ended unsettled (a 500, a
+			// network error): reject. Both are no-ops after onSuccess / onError.
+			onFinish: (visit) =>
+				visit.cancelled || visit.interrupted
+					? resolve()
+					: reject(new Error('The delete failed')),
+		});
+	});
+
+const remove = (id: number) =>
+	confirm({
+		title: 'Delete invoice?',
+		variant: 'destructive',
+		yes: { text: 'Delete', onClick: () => destroy(`/invoices/${id}`) },
+	});
+```
+
+Not `autoClose: false` with `close()` called from the visit callbacks: Yes
+never shows busy, and a missed callback leaves the dialog up or closes it
+mid-visit.
+
 ### Custom footer actions — more than yes/no
 
 Pass an `actions` array to replace the Yes/No footer with your own buttons.

package/dist/ai/design-tokens.json

@@ -456,18 +456,18 @@
 				"dark": "#00000080"
 			}
 		},
-		"--bb-overlay-blur": {
-			"css": "--bb-overlay-blur",
-			"light": "2px"
-		},
-		"--bb-overlay-stacked": {
-			"css": "--bb-overlay-stacked",
+		"--bb-overlay-above": {
+			"css": "--bb-overlay-above",
 			"derived": "var(--bb-overlay)",
 			"resolved": {
 				"light": "#0000001a",
 				"dark": "#00000080"
 			}
 		},
+		"--bb-overlay-blur": {
+			"css": "--bb-overlay-blur",
+			"light": "2px"
+		},
 		"--bb-panel": {
 			"css": "--bb-panel",
 			"light": "rgb(255 255 255)",

package/dist/ai/guides/agent-contract.md

@@ -240,8 +240,8 @@ semantic status badges, a brand button tone — **add it, in both halves**:
 
 1. **Register the name** in the build plugin: `badgeVariants`, `buttonVariants`,
    `alertVariants`, `confirmVariants`, `dropdownItemVariants`, `tooltipVariants`,
-   `toastVariants`, `indicatorVariants`, `inputVariants`, `tabsVariants`
-   (`bitboss-ui/vite` or `bitboss-ui/nuxt`).
+   `toastVariants`, `indicatorVariants`, `inputVariants`, `tabsVariants`,
+   `radioVariants`, `checkboxVariants` (`bitboss-ui/vite` or `bitboss-ui/nuxt`).
    The plugin regenerates the typed registry, so the name type-checks.
 2. **Style the class** — `.bb-badge--<name>`, `.bb-button--<name>`, … —
    in a project stylesheet loaded **after** `bitboss-ui/styles.css`. The library

package/dist/ai/guides/ai-router.md

@@ -98,29 +98,30 @@ inline-edit playbook) instead of inventing a new shape.
 
 ## Playbooks (only when the pattern applies)
 
-| Need                                                                                                                 | Guide                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ⌘K / Ctrl+K global command palette                                                                                   | [BbSelectPopover](../BbSelectPopover.md#a-k-command-palette) § A ⌘K command palette                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Tied selects / stale model cleanup                                                                                   | [coherence-playbook](./coherence-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| Async `items` providers / prefill                                                                                    | [fetch-items-playbook](./fetch-items-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `item-text` / `item-value` / the default `label` / `value` keys / disabled                                           | [options-items-playbook](./options-items-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| Table cell edit ownership                                                                                            | [inline-edit-playbook](./inline-edit-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Table row → detail (identity cells)                                                                                  | [agent-contract](./agent-contract.md) § Inline Links                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| Peek that drills into related records                                                                                | [agent-contract](./agent-contract.md) § Consult-Stack                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| Icons (`lucide:*`, never invent names)                                                                               | [icons-policy](./icons-policy.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Tokens / styling around components                                                                                   | [design-language](./design-language.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Inertia app-side helpers (`useProp`, `useQuery`, `useQueryObject`, `useTableContext`, …) the Inertia recipes import  | [inertia-helpers](./inertia-helpers.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Theming a whole app / retuning a component                                                                           | [design-tokens](./design-tokens.md) — the two tiers, and why most restyling is a component token, not a `--bb-*` one                                                                                                                                                                                                                                                                                                                                                                                              |
-| Paint as data (DESIGN.md, impeccable, design-taste)                                                                  | [design-tokens.json](../design-tokens.json) and [design-tokens.manifest.yaml](../design-tokens.manifest.yaml), generated from `variables.css`. Grep `--bb-*`, not `--color-*` or `--radius-*`. Root `DESIGN.md` is the Inertia fixture, not this library.                                                                                                                                                                                                                                                         |
-| A Tailwind utility on a `Bb*` component does nothing, or half-applies                                                | [installation](./installation-and-plugin-setup.md) § Cascade layers — v4 is layered, we are not by default. It is per PROPERTY: a utility loses only where we declare the same one, and a shorthand like `p-4` can half-apply. `cssLayers: TAILWIND_V4_LAYERS` in the build plugin                                                                                                                                                                                                                                |
-| Restyling ONE part of a component (its icon, its spinner, its field box) — or a `:deep()` you are about to write     | [passthrough](./passthrough.md) — the first choice: `pt:<part>` / `pt:<part>:<state>`, typed and linted; classes append, attributes win, listeners concatenate. A look many places need is a **variant**, not `pt`. No part for it? A CSS override on the internal class is allowed but can break in any release (a part's class is stable within 3.x) — [design-language](./design-language.md) § Hard Rules                                                                                                     |
-| Styling the SELECTED option, the HIGHLIGHTED row, the CURRENT tab — a state a modifier class used to carry           | [passthrough](./passthrough.md) § Parts that resolve per node — `pt:option:selected`, `pt:row:highlighted`, `pt:item:active`; every component's parts and states are in its table                                                                                                                                                                                                                                                                                                                                 |
-| Typing a `pt` value in `<script>` (a const, a preset, a wrapper's `pt` prop, a global map split across files)        | [passthrough](./passthrough.md) § Typing `pt` in `<script>` — `<Component>Props<Row>['pt']` with `satisfies`, `definePt` for map fragments. `PtValue` / `PtMap` are not exported                                                                                                                                                                                                                                                                                                                                  |
-| `InstanceType<typeof BbSelect>` fails, a Storybook `Meta` or `findComponent` won't type, a `ref('')` on a text field | [typescript-generic-components](./typescript-generic-components.md) — the generic components and their four script-side differences                                                                                                                                                                                                                                                                                                                                                                               |
-| Wrapping a `Bb*` component in your own (`MemberSelect`, `PriceListSelect`)                                           | A preset (fixed items, label, option row): [preset-components](./preset-components.md), one `definePreset` call. With its own logic: [options-items-playbook](./options-items-playbook.md) § Wrapping BbSelect in your own component                                                                                                                                                                                                                                                                              |
-| Forms with validation (`BbForm`)                                                                                     | [validated-forms](./validated-forms.md); the schema library (Zod, Valibot, ArkType, Yup, Joi, Effect, string rules) and switching between them: [validation-libraries](./validation-libraries.md); server errors from Inertia, a Laravel 422, Precognition, vee-validate or Nuxt UI into `setErrors`: [validation-providers](./validation-providers.md); porting an Element Plus / Naive UI / Ant Design Vue form (`rules` objects, async-validator): [from-async-validator](./migration/from-async-validator.md) |
-| Upgrading from bitboss-ui 2.x                                                                                        | [migration/v2-to-v3](./migration/v2-to-v3.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| Bumping between two v3 prereleases                                                                                   | `npx bitboss-ui changelog --since <your version>` (MCP `list_changes`) — what BREAKS in the bump, and in which release each break first shipped (`firstReleasedIn`); then `check --manifest` for the files it breaks                                                                                                                                                                                                                                                                                              |
+| Need                                                                                                                    | Guide                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ⌘K / Ctrl+K global command palette                                                                                      | [BbSelectPopover](../BbSelectPopover.md#a-k-command-palette) § A ⌘K command palette                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Tied selects / stale model cleanup                                                                                      | [coherence-playbook](./coherence-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Async `items` providers / prefill                                                                                       | [fetch-items-playbook](./fetch-items-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `item-text` / `item-value` / the default `label` / `value` keys / disabled                                              | [options-items-playbook](./options-items-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Table cell edit ownership                                                                                               | [inline-edit-playbook](./inline-edit-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Table row → detail (identity cells)                                                                                     | [agent-contract](./agent-contract.md) § Inline Links                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Peek that drills into related records                                                                                   | [agent-contract](./agent-contract.md) § Consult-Stack                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Icons (`lucide:*`, never invent names)                                                                                  | [icons-policy](./icons-policy.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Tokens / styling around components                                                                                      | [design-language](./design-language.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Inertia app-side helpers (`useProp`, `useQuery`, `useQueryObject`, `useTableContext`, …) the Inertia recipes import     | [inertia-helpers](./inertia-helpers.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Theming a whole app / retuning a component                                                                              | [design-tokens](./design-tokens.md) — the two tiers, and why most restyling is a component token, not a `--bb-*` one                                                                                                                                                                                                                                                                                                                                                                                              |
+| Paint as data (DESIGN.md, impeccable, design-taste)                                                                     | [design-tokens.json](../design-tokens.json) and [design-tokens.manifest.yaml](../design-tokens.manifest.yaml), generated from `variables.css`. Grep `--bb-*`, not `--color-*` or `--radius-*`. Root `DESIGN.md` is the Inertia fixture, not this library.                                                                                                                                                                                                                                                         |
+| A Tailwind utility on a `Bb*` component does nothing, or half-applies                                                   | [installation](./installation-and-plugin-setup.md) § Cascade layers — v4 is layered, we are not by default. It is per PROPERTY: a utility loses only where we declare the same one, and a shorthand like `p-4` can half-apply. `cssLayers: TAILWIND_V4_LAYERS` in the build plugin                                                                                                                                                                                                                                |
+| Restyling ONE part of a component (its icon, its spinner, its field box) — or a `:deep()` you are about to write        | [passthrough](./passthrough.md) — the first choice: `pt:<part>` / `pt:<part>:<state>`, typed and linted; classes append, attributes win, listeners concatenate. A look many places need is a **variant**, not `pt`. No part for it? A CSS override on the internal class is allowed but can break in any release (a part's class is stable within 3.x) — [design-language](./design-language.md) § Hard Rules                                                                                                     |
+| Styling the SELECTED option, the HIGHLIGHTED row, the CURRENT tab — a state a modifier class used to carry              | [passthrough](./passthrough.md) § Parts that resolve per node — `pt:option:selected`, `pt:row:highlighted`, `pt:item:active`; every component's parts and states are in its table                                                                                                                                                                                                                                                                                                                                 |
+| Typing a `pt` value in `<script>` (a const, a preset, a wrapper's `pt` prop, a global map split across files)           | [passthrough](./passthrough.md) § Typing `pt` in `<script>` — `<Component>Props<Row>['pt']` with `satisfies`, `definePt` for map fragments. `PtValue` / `PtMap` are not exported                                                                                                                                                                                                                                                                                                                                  |
+| `InstanceType<typeof BbSelect>` fails, a Storybook `Meta` or `findComponent` won't type, a `ref('')` on a text field    | [typescript-generic-components](./typescript-generic-components.md) — the generic components and their four script-side differences                                                                                                                                                                                                                                                                                                                                                                               |
+| Wrapping a `Bb*` component in your own (`MemberSelect`, `PriceListSelect`)                                              | A preset (fixed items, label, option row): [preset-components](./preset-components.md), one `definePreset` call. With its own logic: [options-items-playbook](./options-items-playbook.md) § Wrapping BbSelect in your own component                                                                                                                                                                                                                                                                              |
+| Forms with validation (`BbForm`)                                                                                        | [validated-forms](./validated-forms.md); the schema library (Zod, Valibot, ArkType, Yup, Joi, Effect, string rules) and switching between them: [validation-libraries](./validation-libraries.md); server errors from Inertia, a Laravel 422, Precognition, vee-validate or Nuxt UI into `setErrors`: [validation-providers](./validation-providers.md); porting an Element Plus / Naive UI / Ant Design Vue form (`rules` objects, async-validator): [from-async-validator](./migration/from-async-validator.md) |
+| Finishing a migration (from v2 or another library): the hand-rolled controls to move onto the library, `check --idioms` | [migration/adoption-checklist](./migration/adoption-checklist.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Upgrading from bitboss-ui 2.x                                                                                           | [migration/v2-to-v3](./migration/v2-to-v3.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Bumping between two v3 prereleases                                                                                      | `npx bitboss-ui changelog --since <your version>` (MCP `list_changes`) — what BREAKS in the bump, and in which release each break first shipped (`firstReleasedIn`); then `check --manifest` for the files it breaks                                                                                                                                                                                                                                                                                              |
 
 ---
 

package/dist/ai/guides/app-layout.md

@@ -242,6 +242,11 @@ const footer = [
 	background: color-mix(in oklab, var(--bb-text) 6%, transparent);
 }
 
+/* BbBaseButton drops the native ring: the keyboard focus is drawn here. */
+.layout__nav-item:focus-visible {
+	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
+}
+
 .layout__nav-item--active {
 	background: color-mix(in oklab, var(--bb-text) 9%, transparent);
 	font-weight: 500;

package/dist/ai/guides/component-picker.md

@@ -40,6 +40,12 @@ logo — on every `.vue` file it scans. That is the backstop: it fires without
 anyone thinking to ask. The badge case is not decidable from markup (a tinted
 pill is as often decoration as status), so it has no hint and stays your job.
 
+Migrating an app that already built these? The
+[adoption checklist](./migration/adoption-checklist.md) is the same question
+asked of existing code: every hand-rolled pattern the library ships, how to
+find it, and the replacement. `npx bitboss-ui check --idioms` runs its patterns
+over the app (report-only).
+
 ---
 
 ## Text Input
@@ -81,6 +87,7 @@ pill is as often decoration as status), so it has no hint and stays your job.
 - Small static multi-choice submitted with a form → `BbCheckboxGroup`.
 - Each option is a live setting that applies the moment it flips → `BbSwitchGroup`.
 - The trigger is a status pill, avatar stack, or table-cell chip rather than a form field → `BbSelectPopover` (same search/options engine as `BbSelect`, you own the trigger).
+- A segmented control: **switch views → `BbTabs`** (default `pill`), **pick a value → `BbRadioGroup` `variant="pill"`** (or `"line"`; several values → `BbCheckboxGroup` `variant="pill"`): BbTabs' look on a radiogroup ([§ Segmented control](../BbRadioGroup.md#segmented-control)). Decide by the job, not the look: a value a form or a filter submits is a radio group; what the page shows is a tab.
 
 Never hand-assemble a row of `BbCheckbox`/`BbRadio` — the groups give you fieldset semantics, item mapping, and validation for free.
 
@@ -192,7 +199,7 @@ There are also **`v-bb-color`**, **`v-bb-date`**, and **`v-bb-time`** directives
 
 **Offload navigation to the component.** `BbButton`, dropdown items, and breadcrumb items accept `href` (anchor, or Inertia visit with `method`/`data`/`preserveScroll`/…) and `to` (vue-router); tabs items accept `href`; `BbPagination` with `navigation` builds per-page links itself. Never wire `@click="router.push(...)"` for a plain destination.
 
-**Picking the pattern:** `BbTabs` switches peer sections of _one_ subject (Overview / Activity / Settings) — not steps in a flow, not hierarchy. A look the shipped variants don't have (a side nav, a filter row) starts from `variant="none"` plus the strip's tokens in `pt.wrapper.style` (inline, so no stylesheet and no scoped-style trap); the library does not add a variant per need. `BbBreadcrumbs` answers "where am I and how do I get back up". `BbPagination` steps through a paged result set — prefer it over infinite scroll when users need to find their place again.
+**Picking the pattern:** `BbTabs` switches peer sections of _one_ subject (Overview / Activity / Settings) — not steps in a flow, not hierarchy, and not a value: a segmented strip that picks a value a form or a filter submits is a `BbRadioGroup` `variant="pill"` / `"line"`, the same look ([§ Segmented control](../BbRadioGroup.md#segmented-control)). A look the shipped variants don't have (a side nav, a filter row) starts from `variant="none"` plus the strip's tokens in `pt.wrapper.style` (inline, so no stylesheet and no scoped-style trap); the library does not add a variant per need. `BbBreadcrumbs` answers "where am I and how do I get back up". `BbPagination` steps through a paged result set — prefer it over infinite scroll when users need to find their place again.
 
 **Disclosure ladder (BbAccordion vs BbCollapsible vs BbSmoothHeight):**
 
@@ -247,7 +254,7 @@ compose it or write it yourself.
 | `BbModal`                                                                                        | It is [BbDialog](../BbDialog.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `BbDrawer` / `BbSheet`                                                                           | It is [BbOffCanvas](../BbOffCanvas.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `BbCombobox` / `BbAutocomplete`                                                                  | It is [BbSelect](../BbSelect.md) / [BbSelectPopover](../BbSelectPopover.md) — search is built in, see `disable-writing`.                                                                                                                                                                                                                                                                                                                                                               |
-| `BbToggle` / `BbToggleGroup`                                                                     | It is [BbButton](../BbButton.md) with `v-model` (+ `true-value` / `false-value`), which owns `aria-pressed` and the active class. A group is several buttons: a boolean per button for independent toggles, one shared `v-model` with `:false-value="null"` for an optional choice, `group` to fuse them ([BbButton § Toggle buttons](../BbButton.md#toggle-buttons)); exactly one always active is a `BbRadioGroup` segmented control or `BbTabs`.                                    |
+| `BbToggle` / `BbToggleGroup`                                                                     | It is [BbButton](../BbButton.md) with `v-model` (+ `true-value` / `false-value`), which owns `aria-pressed` and the active class. A group is several buttons: a boolean per button for independent toggles, one shared `v-model` with `:false-value="null"` for an optional choice, `group` to fuse them ([BbButton § Toggle buttons](../BbButton.md#toggle-buttons)); exactly one always active is a `BbRadioGroup` `variant="pill"` or `BbTabs`.                                     |
 | `TagChip` / colored, read-only tag chip                                                          | It is [BbBadge](../BbBadge.md) — [BbTag](../BbTag.md) is a tags-_input_ only, not a display component. Use `BbBadge` with a registered `soft-*` variant for a fixed palette, or a one-off `--bg`/`--fg` override per row for arbitrary/data-driven colors (BbBadge.md § One-off colors) — not a registered variant per distinct color.                                                                                                                                                 |
 | `BbTab` (singular)                                                                               | The consumer API is [BbTabs](../BbTabs.md) / `BbTabsRoot`. `BbTab` appears only as the **v2 "before" side** of the migration diffs.                                                                                                                                                                                                                                                                                                                                                    |
 | `BbCard`                                                                                         | Does not exist — a card is a `<div>` with tokens. See [design-language](./design-language.md).                                                                                                                                                                                                                                                                                                                                                                                         |

package/dist/ai/guides/design-language.md

@@ -132,28 +132,28 @@ one renders with no value at all rather than erroring.
 
 ### Surfaces & structure
 
-| Token                  | Meaning                                                                                                                                       |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--bb-panel`           | Surface/background color of panels, popovers, dialogs                                                                                         |
-| `--bb-muted`           | Subtle/disabled surface (derived, neutral)                                                                                                    |
-| `--bb-hover`           | Hover fill for **affordances** (buttons, links, controls)                                                                                     |
-| `--bb-surface-hover`   | Hover fill for **passive surfaces** (rows, cells, days) — fainter                                                                             |
-| `--bb-pressed`         | Neutral pressed/active fill                                                                                                                   |
-| `--bb-border`          | Border color; pair with `--bb-border-w` (1px)                                                                                                 |
-| `--bb-field-border`    | Resting border of every form field (the default input box and the group / rating / slider shells); follows `--bb-border` until set            |
-| `--bb-border-w`        | Hairline thickness — plates **and** internal dividers (dialog/off-canvas footers, menu rules, popover headers)                                |
-| `--bb-border-w-sm`     | Nested / small hairline (xs/sm buttons, badges, glyphs) — half of `--bb-border-w`, floored at 1px and capped by it                            |
-| `--bb-radius`          | Corner radius of controls (8px)                                                                                                               |
-| `--bb-radius-surface`  | Corner radius of large surfaces (derived, ×1.8)                                                                                               |
-| `--bb-radius-sm`       | Corner radius of small nested elements (derived)                                                                                              |
-| `--bb-shadow`          | Overlay elevation (dialogs, popovers, menus, toasts)                                                                                          |
-| `--bb-elev`            | Resting lift on controls — a full `box-shadow`, default a transparent layer. Covers a soft lift and a hard offset alike                       |
-| `--bb-elev-sm`         | The same lift on small chrome (badges, glyphs, xs/sm buttons); inherits `--bb-elev` unless a hard-offset theme splits it                      |
-| `--bb-panel-p`         | Content padding of large surfaces (dialog, off-canvas); axis split via the locals `--px`/`--py` on `.bb-dialog` / `.bb-offcanvas`             |
-| `--bb-overlay-blur`    | Backdrop dim blur (2px) — on the bottom-most open panel's backdrop only                                                                       |
-| `--bb-overlay-stacked` | Dim painted by a panel stacked over another open one (derived, equal to `--bb-overlay`; `transparent` = one dim under the pile)               |
-| `--bb-surface-filter`  | Frost on raised plates — dialog, off-canvas, popover bubble, toast, input shell, alert, table. A full `backdrop-filter` value, default `none` |
-| `--bb-z-overlay`       | Z-index for overlays (10)                                                                                                                     |
+| Token                 | Meaning                                                                                                                                                                                 |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--bb-panel`          | Surface/background color of panels, popovers, dialogs                                                                                                                                   |
+| `--bb-muted`          | Subtle/disabled surface (derived, neutral)                                                                                                                                              |
+| `--bb-hover`          | Hover fill for **affordances** (buttons, links, controls)                                                                                                                               |
+| `--bb-surface-hover`  | Hover fill for **passive surfaces** (rows, cells, days) — fainter                                                                                                                       |
+| `--bb-pressed`        | Neutral pressed/active fill                                                                                                                                                             |
+| `--bb-border`         | Border color; pair with `--bb-border-w` (1px)                                                                                                                                           |
+| `--bb-field-border`   | Resting border of every form field (the default input box and the group / rating / slider shells); follows `--bb-border` until set                                                      |
+| `--bb-border-w`       | Hairline thickness — plates **and** internal dividers (dialog/off-canvas footers, menu rules, popover headers)                                                                          |
+| `--bb-border-w-sm`    | Nested / small hairline (xs/sm buttons, badges, glyphs) — half of `--bb-border-w`, floored at 1px and capped by it                                                                      |
+| `--bb-radius`         | Corner radius of controls (8px)                                                                                                                                                         |
+| `--bb-radius-surface` | Corner radius of large surfaces (derived, ×1.8)                                                                                                                                         |
+| `--bb-radius-sm`      | Corner radius of small nested elements (derived)                                                                                                                                        |
+| `--bb-shadow`         | Overlay elevation (dialogs, popovers, menus, toasts)                                                                                                                                    |
+| `--bb-elev`           | Resting lift on controls — a full `box-shadow`, default a transparent layer. Covers a soft lift and a hard offset alike                                                                 |
+| `--bb-elev-sm`        | The same lift on small chrome (badges, glyphs, xs/sm buttons); inherits `--bb-elev` unless a hard-offset theme splits it                                                                |
+| `--bb-panel-p`        | Content padding of large surfaces (dialog, off-canvas); axis split via the locals `--px`/`--py` on `.bb-dialog` / `.bb-offcanvas`                                                       |
+| `--bb-overlay-blur`   | Backdrop dim blur (2px) — on the bottom-most open panel's backdrop only                                                                                                                 |
+| `--bb-overlay-above`  | Dim painted by a panel stacked over another open one (derived, equal to `--bb-overlay`; `transparent` = one dim under the pile); none on a dialog replacing a member of its own `stack` |
+| `--bb-surface-filter` | Frost on raised plates — dialog, off-canvas, popover bubble, toast, input shell, alert, table. A full `backdrop-filter` value, default `none`                                           |
+| `--bb-z-overlay`      | Z-index for overlays (10)                                                                                                                                                               |
 
 ### Color semantics
 
@@ -240,8 +240,8 @@ What the shared names mean (shadcn-style vocabulary):
 
 Projects can register extra variants through the Vite/Nuxt plugin
 (`buttonVariants`, `badgeVariants`, `alertVariants`, `confirmVariants`,
-`dropdownItemVariants`, `tooltipVariants`, `toastVariants`, `inputVariants`
-options).
+`dropdownItemVariants`, `tooltipVariants`, `toastVariants`, `inputVariants`,
+`tabsVariants`, `radioVariants`, `checkboxVariants` options).
 Registered names become typed values, but the library ships no CSS for them —
 the project styles `.bb-button--<name>` (etc.) itself, following the state
 recipe in [design-tokens.md](./design-tokens.md).

package/dist/ai/guides/design-tokens.md

@@ -373,6 +373,13 @@ ladder formulas instead of these tokens, so a state name never lies.
 | `--bb-elev`           | `0 0 0 0 transparent`             | Resting lift on **controls** (buttons, inputs, badges, alerts, checkbox, slider thumb, tab pill). A full `box-shadow`, composed under the focus ring, so one knob covers a soft lift (`0 1px 2px rgb(0 0 0 / 0.05)`) and a hard offset (`4px 4px 0 0 #111`) alike. The default is a transparent layer, not `none`, so the shadow list keeps a constant length and stays interpolable. `--bb-shadow` is the overlay lift; this is the resting one. Ghost / link / none buttons stay flat whatever the theme sets. Avatar and the Indicator bubble carry it via `--bb-elev-sm`; BbDropzone (no plate of its own — the surface is your content) and BbProgress (a recessed track, not a raised plate) deliberately do not. |
 | `--bb-elev-sm`        | `var(--bb-elev)`                  | The same lift on **small chrome** — badges, checkbox and radio glyphs, the slider thumb, the colour swatch, xs/sm buttons, the active pagination chip. It inherits `--bb-elev`, so a soft shadow needs one knob; only a hard offset needs the second value, because a hard offset has no falloff and its weight is purely relative to the box (a 4px offset is 11% of an xl button and 25% of a 16px glyph). It cannot be derived — CSS cannot halve the offsets inside a shadow string.                                                                                                                                                                                                                                |
 
+**Turn a shadow knob off with `0 0 0 0 transparent`, not `none`.** `--bb-elev`,
+`--bb-elev-sm` and `--bb-shadow-sm` are composed into `box-shadow` lists (the
+tab indicator stacks `--bb-elev` and `--bb-shadow-sm`), and `none` inside a list
+invalidates the whole declaration, taking the other layers with it. The
+transparent layer draws nothing and keeps the list valid. `--bb-shadow` stands
+alone wherever it is used, so `none` works there too.
+
 A four-knob chrome shift is `border-w` + `elev` + `shadow` + `radius`, and
 both nested tiers follow from the first and last, so there is no second pin
 to remember. Loud fills also pin `--bb-primary-border` and `--bb-link-fg`
@@ -476,14 +483,14 @@ to hardcode past it.
 
 ### Overlays
 
-| Token                  | Default                 | Notes                                                                                                                                                                                                                                                      |
-| ---------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--bb-overlay`         | `rgb(0 0 0 / 0.1)`      | Backdrop dim color+opacity in one — the bottom-most open panel's backdrop                                                                                                                                                                                  |
-| `--bb-overlay-stacked` | derived: `--bb-overlay` | Dim painted by a dialog or off-canvas stacked over another open one, on top of everything beneath it (the parent included). Derived, so a theme that only sets `--bb-overlay` gets a matching value; `transparent` gives a single dim under the whole pile |
-| `--bb-overlay-blur`    | `2px`                   | Backdrop blur — only the bottom-most open panel's backdrop carries it, whatever the depth                                                                                                                                                                  |
-| `--bb-surface-filter`  | `none`                  | Frost on raised plates (dialog, sheet, bubble, toast, alert, table, input shell). A full `backdrop-filter` value — `blur(22px) saturate(1.8)` — not a length. Glass themes set it and give `--bb-panel` an alpha.                                          |
-| `--bb-z-overlay`       | `10`                    | Overlay z-index                                                                                                                                                                                                                                            |
-| `--bb-arrow`           | `1`                     | Popover arrows on (`1`) / off (`0`)                                                                                                                                                                                                                        |
+| Token                 | Default                 | Notes                                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--bb-overlay`        | `rgb(0 0 0 / 0.1)`      | Backdrop dim color+opacity in one — the bottom-most open panel's backdrop                                                                                                                                                                                                                                                                                                    |
+| `--bb-overlay-above`  | derived: `--bb-overlay` | Dim painted by a dialog or off-canvas stacked over another open one, on top of everything beneath it (the parent included). A dialog that replaces a member of its own `stack` paints none: the covered member's backdrop stays the only one. Derived, so a theme that only sets `--bb-overlay` gets a matching value; `transparent` gives a single dim under the whole pile |
+| `--bb-overlay-blur`   | `2px`                   | Backdrop blur — only the bottom-most open panel's backdrop carries it, whatever the depth                                                                                                                                                                                                                                                                                    |
+| `--bb-surface-filter` | `none`                  | Frost on raised plates (dialog, sheet, bubble, toast, alert, table, input shell). A full `backdrop-filter` value — `blur(22px) saturate(1.8)` — not a length. Glass themes set it and give `--bb-panel` an alpha.                                                                                                                                                            |
+| `--bb-z-overlay`      | `10`                    | Overlay z-index                                                                                                                                                                                                                                                                                                                                                              |
+| `--bb-arrow`          | `1`                     | Popover arrows on (`1`) / off (`0`)                                                                                                                                                                                                                                                                                                                                          |
 
 ### Input family
 

package/dist/ai/guides/icons-policy.md

@@ -262,8 +262,15 @@ markup) yourself:
   duplicate.
 - Meaningful standalone icon: give `BbIcon` a `label` — it adds `role="img"`
   and `aria-label`. Deliberately **no `title`**: that renders a native browser
-  tooltip, which double-tooltips any icon also carrying `v-bb-tooltip` (owner
-  ruling 2026-07-30, `BbIcon.vue:200`). For a visible tip, add `v-bb-tooltip`.
+  tooltip (owner ruling 2026-07-30). `BbIcon` is never focusable.
+- An info icon with a tip: make it an icon-only ghost `BbButton`, so keyboard
+  focus reaches it and opens the tip; the slot text is its name, the tip its
+  description:
+  `<BbButton variant="ghost" icon="lucide:info" v-bb-tooltip="'Prices include VAT'">About prices</BbButton>`.
+  When the text must be readable on touch, make it a `BbPopover` toggletip
+  (the same button as its activator; see the BbPopover guide, "Inline field
+  help"). `v-bb-tooltip` on a bare `BbIcon` or `<span>` is a pointer-only
+  hint: keyboard and touch never open it.
 - Icon-only `BbButton` (the `icon` prop): supply the accessible name through the
   label (default slot, or `text`) — it renders `sr-only` but is still announced.
   `aria-label` is only an override; the one hard rule is that the button must