bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.41

package/dist/ai/guides/migration/v2-to-v3.md

@@ -39,6 +39,33 @@ explicitly (section 8).
 
 ## 0. Upgrade strategy — do it in this order
 
+> **Already on v3, bumping between prereleases?** This guide is the v2 → v3
+> move; you want the much shorter answer instead:
+>
+> ```bash
+> npx bitboss-ui changelog --since 3.0.0-beta.20   # what BREAKS in the bump
+> ```
+>
+> Then turn that list into **your** files, before you install anything:
+>
+> ```bash
+> npm pack bitboss-ui@3.0.0-beta.21 && tar -xzf bitboss-ui-3.0.0-beta.21.tgz
+> npx bitboss-ui check --manifest package/dist/ai/components.json
+> ```
+>
+> `check` normally judges the INSTALLED version, which can only tell you what
+> an upgrade broke after you took it. `--manifest` points it at the version you
+> are moving to, so the damage is visible first. Agents with the MCP server get
+> the same answer from `list_changes({ since })`.
+>
+> Once installed, `npx bitboss-ui check --fix` applies every registered
+> prop migration (renames, polarity flips, value remaps) to your `.vue` files
+> and reports what still needs a hand.
+>
+> After installing, restart the dev server and delete `node_modules/.vite`
+> (inside the container, under Docker or Sail): a server started before the
+> install keeps serving the old pre-bundled JS next to the new CSS.
+
 1. **Swap the setup** (section 1): install the build plugin and the runtime
    plugin. Nothing renders correctly until this is done.
 2. **Move your config** (section 2): everything you passed to
@@ -52,6 +79,13 @@ explicitly (section 8).
    fail loudly. Fix them component by component with the per-component guides.
 5. **Audit what the compiler cannot find** (section 8): untyped templates,
    `v-bind` objects, and behavioral flips are silent. Run the grep playbook.
+   **Your stylesheets are the silent half.** `vue-tsc` never reads CSS, so a
+   rule targeting a renamed or deleted class simply stops matching — no error,
+   no warning, and the page often still looks close enough to pass review. A
+   v2-era theme file can carry hundreds of lines that have done nothing since
+   the upgrade. Section 5.6 has the rename table and the grep that finds them;
+   run it before you conclude a component "has no token for this", because a
+   dead override and a missing affordance look identical from the browser.
 6. **Convert class overrides to variants** (section 7): userland
    `class="bb-button--outline"`-style overrides keep _working_ but are now the
    wrong pattern — the variant prop exists, is typed, and is the only form the
@@ -62,8 +96,12 @@ explicitly (section 8).
 ### What v2 looked like
 
 v2 was a plain ESM library: named exports, one manual CSS import, optional
-manual directive registration. There was no Vite plugin, no Nuxt module, and
-no `app.use`.
+manual directive registration. There was no Vite plugin and no `app.use`.
+
+Nuxt apps were the exception: they installed a **separate companion package**,
+`@bitboss-dev/bitboss-ui-nuxt`, which wrapped v2 in a Nuxt module. v3 absorbs
+that package — the module now ships inside the library as `bitboss-ui/nuxt`.
+See [Nuxt](#nuxt) below for the option-by-option move.
 
 ```ts
 // v2 main.ts
@@ -173,8 +211,7 @@ nothing else about the plugin changes.
 
 ### Nuxt
 
-v2 had no Nuxt story. v3 ships a module that does both halves — do **not**
-also call `app.use`:
+v3 ships a module that does both halves — do **not** also call `app.use`:
 
 ```ts
 // v3 nuxt.config.ts
@@ -186,6 +223,57 @@ export default defineNuxtConfig({
 });
 ```
 
+#### Coming from `@bitboss-dev/bitboss-ui-nuxt`
+
+That package was the v2 Nuxt story. It is superseded: **uninstall it** and
+delete it from `modules`. Everything it did is now inside `bitboss-ui/nuxt`,
+under the same `bitboss` config key — so the migration is mostly renaming keys,
+not rewriting setup.
+
+| `@bitboss-dev/bitboss-ui-nuxt` option | v3 `bitboss-ui/nuxt`                                                                                                                                                    |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `icons.path`                          | `iconDir`. Same job, one level up.                                                                                                                                      |
+| `icons.enabled: false`                | **Gone** — the icon pipeline is not optional in v3; components import the virtual icon module. Point `iconDir` at an empty folder if you ship no local art.             |
+| `styles.enabled`                      | `injectStyles` (still defaults `true`).                                                                                                                                 |
+| `styles.index`                        | **Gone**, and nothing replaces it — see the ordering note below.                                                                                                        |
+| `link.name`                           | `nuxtLinkName` (still defaults `'NuxtLink'`).                                                                                                                           |
+| `link.enabled: false`                 | **Gone.** The runtime plugin only registers the configured name when the app has not already claimed it, so there is nothing to switch off.                             |
+| `components.enabled`                  | `autoImport` — see below. Note the **default flipped**: v2's module auto-imported components, v3 does not.                                                              |
+| `components.validation: true`         | `autoImport: { validated: true }`, or explicit imports from `bitboss-ui/validated`. The wrappers moved into the library and gained `BbForm` + `useValidatedField`.      |
+| `components.requiredAsterisk`         | `requiredAsterisk`, same meaning, one level up.                                                                                                                         |
+| `composables`                         | Folded into `autoImport`. `useBroadcastChannelInstance`, `useQueue` and `useWizard` are **not exported by v3** — the module registered names the library no longer has. |
+| `logLevel`                            | **Gone.** The v3 module has nothing to log at setup; build-plugin diagnostics go through Vite.                                                                          |
+
+**⚠ silent — auto-imports are off by default.** The v2 module registered every
+`Bb*` component with Nuxt, so templates used them with no import line. v3 does
+not: an unmigrated template compiles, and each unresolved `<BbButton>` renders
+as an empty unknown element with no error anywhere. Either add explicit imports,
+or opt back in:
+
+```ts
+// v3 nuxt.config.ts — the closest equivalent of the v2 module's defaults
+export default defineNuxtConfig({
+	modules: ['bitboss-ui/nuxt'],
+	bitboss: {
+		iconDir: './assets/icons',
+		autoImport: { validated: true }, // drop `validated` if you had no vee-validate
+	},
+});
+```
+
+Set `"vueCompilerOptions": { "checkUnknownComponents": true }` in `tsconfig.json`
+before you start either way — it is what turns that silent empty element into a
+`vue-tsc` error naming the file and line.
+
+**Style ordering.** `styles.index` let you splice `bitboss-ui/styles.css`
+anywhere in Nuxt's `css` array. v3 injects the sheet at runtime and always puts
+it **first** in `<head>`, ahead of every other stylesheet — so your own CSS is
+always later and always wins, which is the order `styles.index` was normally
+used to obtain. If you need the opposite (library rules winning over yours),
+raise specificity in your own sheet rather than reordering; if you genuinely
+need the library sheet elsewhere in the cascade, set `injectStyles: false` and
+import `bitboss-ui/styles.css` yourself at the position you want.
+
 ### Inertia
 
 Inertia apps configure `bitboss-ui/vite` exactly like plain Vite, install
@@ -210,7 +298,7 @@ Full option reference:
 
 In v2 all configuration was runtime and mutable:
 
-```ts
+```ts no-check
 // v2 — anywhere, usually App.vue setup
 import { useBbConfig } from 'bitboss-ui';
 
@@ -238,6 +326,23 @@ bitbossUi({
 useBbConfig().setConfig({ locale: 'en' });
 ```
 
+**Under SSR, set the locale where the app is created.** The runtime config is
+held **per Vue app** (3.0.0-beta.15), and SSR builds one app per request, so
+this is per-visitor and correct on the first paint — which is what crawlers
+index and what a JS-disabled reader keeps:
+
+```ts
+const app = createSSRApp(App);
+app.use(bitbossUiPlugin, { locale: localeFor(request) });
+```
+
+`setConfig` still works for runtime switching. During a server render, call it
+from a component's `setup` so it can resolve the current app; from module scope
+there is no app to address, the write lands on the build-time defaults shared
+by the whole process, and it warns in dev. (Before beta.15 the config was a
+single process-global object, so a per-visitor locale was not possible at all —
+if you carried a workaround for that, you can drop it.)
+
 | v2 `setConfig` key                            | Where it goes in v3                                                            |
 | --------------------------------------------- | ------------------------------------------------------------------------------ |
 | `locale`                                      | stays runtime (`setConfig`) — the only survivor                                |
@@ -287,8 +392,9 @@ two tiers:
 
 Dark mode is no longer a parallel token set: `.dark` re-declares only the
 knobs that change, and derived tokens follow automatically. Delete every
-`--x-light`/`--x-dark` override; re-express as `.light { … }` / `.dark { … }`
-blocks. Note: overriding a knob on an arbitrary selector does **not**
+`--x-light`/`--x-dark` override; re-express as `.light { … }` / `:root .dark,
+:root.dark { … }` blocks (a bare `.dark` loses to the library's own dark block
+unless you use `cssLayers`: design-tokens.md § Dark mode). Note: overriding a knob on an arbitrary selector does **not**
 re-derive dependent tokens — re-apply the `.light`/`.dark` block on that
 scope instead.
 
@@ -314,19 +420,30 @@ to the rename map and to every grep below — see
 | `--bb-hint`, `--bb-icon-color`, `--bb-placeholder`, `--bb-prefix-color`, `--bb-muted-color`                                                                            | `--bb-text-muted`                                                                                                                                                                                                                                                                                                                                          |
 | `--bb-input-color`, `--bb-input-bg`                                                                                                                                    | `--bb-text`, `--bb-panel`                                                                                                                                                                                                                                                                                                                                  |
 | `--bb-input-font-size`, `--bb-input-mobile-font-size`                                                                                                                  | `--bb-input-fs`, `--bb-input-fs-mobile`                                                                                                                                                                                                                                                                                                                    |
+| `--bb-label-size`                                                                                                                                                      | `--bb-label-fs`                                                                                                                                                                                                                                                                                                                                            |
+| `--bb-label-compact-spacing-y`                                                                                                                                         | `--bb-label-spacing-y-compact`                                                                                                                                                                                                                                                                                                                             |
+| `--bb-input-compact-h`, `--bb-input-compact-py`                                                                                                                        | `--bb-input-h-compact`, `--bb-input-py-compact` — the `compact` qualifier moved from infix to suffix                                                                                                                                                                                                                                                       |
+| `--bb-input-compact-px`, `--bb-input-compact-prefix-w`, `--bb-input-compact-floating-py`, `--bb-input-prefix`, `--bb-input-prefix-px`                                  | **deleted, no counterpart.** v3's compact mode re-points only height and vertical padding (the two tokens in the row above); horizontal padding and the prefix column keep their normal-size values, and the prefix's own font-size/padding knobs are gone.                                                                                                |
 | `--bb-overlay-color` + `--bb-overlay-opacity`                                                                                                                          | `--bb-overlay` (one color with alpha)                                                                                                                                                                                                                                                                                                                      |
 | `--bb-overlay-z-index`                                                                                                                                                 | `--bb-z-overlay`                                                                                                                                                                                                                                                                                                                                           |
 | _(no v2 equivalent)_                                                                                                                                                   | `--bb-ease` — new in v3. v2 hard-coded seven different `cubic-bezier()` curves and exposed no easing token, so there is nothing to rename; set `--bb-ease` once if you want a house curve.                                                                                                                                                                 |
-| `--bb-dialog-px`, `--bb-dialog-py`                                                                                                                                     | `--bb-panel-p` — **one value on both axes**, for dialogs and off-canvas alike. If your v2 px ≠ py, see "Asymmetric surface padding" below.                                                                                                                                                                                                                 |
+| `--bb-dialog-px`, `--bb-dialog-py`                                                                                                                                     | the local pair `--px` / `--py` on `.bb-dialog` / `.bb-offcanvas` — a direct map, set on the component's class (never `:root`). Both branch off `--bb-panel-p`, so if your v2 px = py, set `--bb-panel-p` alone. See "Asymmetric surface padding" below.                                                                                                    |
 | `--bb-dialog-close`                                                                                                                                                    | **delete it** — do not map it onto `.bb-close-button { --size }`; v3's default already reproduces the v2 control. See below.                                                                                                                                                                                                                               |
 | `--bb-dialog-title-size`                                                                                                                                               | the local `--dialog-title-fs` on `.bb-dialog` / `.bb-offcanvas` (default `calc(var(--bb-fs) + 2px)`)                                                                                                                                                                                                                                                       |
-| `--bb-dialog-title-weight`                                                                                                                                             | **no knob** — the title is hardcoded `font-weight: 500`. Override with a CSS rule, see below.                                                                                                                                                                                                                                                              |
+| `--bb-dialog-title-weight`                                                                                                                                             | `--dialog-title-fw` on `.bb-dialog` / the sheet (default `500`) — `.bb-theme { --dialog-title-fw: 600 }` restores v2.                                                                                                                                                                                                                                      |
 | `--bb-button-h`, `--bb-button-icon`, `--bb-checkbox-*`, `--bb-radio-*`, `--bb-switch-*`, `--bb-rating-*`, `--bb-slider-*`, `--bb-table-cell-h`, `--bb-select-option-*` | **no longer global.** Component dimensions hang off `--bb-control-h`, `--bb-fs`, `--bb-radius`; anything finer is an unprefixed local on the component's own class — with one exception: `--bb-select-option-px/-py` have **no** v3 local, the listbox option's inline padding is a literal (`.bb-listbox__option { padding-inline: … }` in your own CSS). |
 
-**`--bb-input-*` and `--bb-label-*` are NOT in the row above.** They are still
-global v3 theme tokens, declared in `variables.css` and read across the whole
-form family — do not delete them. Several changed their default value; the
-drift table below lists which.
+**Most `--bb-input-*` and `--bb-label-*` tokens survive — but only these
+exact names:** `--bb-input-h`, `--bb-input-px`, `--bb-input-py`,
+`--bb-input-spacing`, `--bb-input-icon`, `--bb-input-prefix-w`,
+`--bb-label-spacing-x`, `--bb-label-spacing-y`, `--bb-label-weight`,
+`--bb-leading`. Those are still global v3 theme tokens, declared in
+`variables.css` and read across the whole form family — do not delete them
+(several changed default value; the drift table below lists which). Everything
+else in the two families either renamed (`--bb-label-size` → `--bb-label-fs`,
+the compact pair — rows above) or is deleted outright, so a declaration that
+is not in this list and not in the rename map is inert: it looks correct and
+does nothing. §8's retired-token grep catches every deleted name.
 
 **When a v2 global becomes a component token, resize only what you use.** That
 last row is the trap: a v2 global like `--bb-button-icon` had ONE value for
@@ -347,50 +464,64 @@ doctrine in `design-tokens.md` § "Overriding one from a consumer app". And chec
 first whether the v2 value was a real customisation: if it merely restated v2's
 default, the migration is to **delete it** and inherit the v3 scale.
 
-**Asymmetric surface padding.** `--bb-panel-p` is a single value used on both
-axes. If your v2 theme set `--bb-dialog-px` ≠ `--bb-dialog-py`, set
-`--bb-panel-p` to the **horizontal** value (it also positions the close button)
-and override the vertical with a normal `padding` rule on the part classes.
-There is no `--bb-panel-px` / `--bb-panel-py` pair.
+**Asymmetric surface padding.** v3 splits the axes with the local pair
+`--px` / `--py`, declared on both surface roots (`.bb-dialog`,
+`.bb-offcanvas`) and each branching off `var(--bb-panel-p)`. Like every
+unprefixed component token, you override them _on the component's class_,
+never `:root`. v2's `--bb-dialog-px` / `--bb-dialog-py` map onto them
+directly:
 
 ```css
-/* v2: --bb-dialog-px: 24px; header --bb-dialog-py: 10px; body --bb-dialog-py: 20px */
+/* v2: --bb-dialog-px: 24px; --bb-dialog-py: 10px */
 .my-dialog {
-	--bb-panel-p: 24px; /* horizontal + close-button inset */
+	--px: 24px; /* horizontal padding + the close button's inline inset */
+	--py: 10px; /* vertical padding + the close button's block inset */
 }
+```
+
+Setting only `--bb-panel-p` still moves both axes together (the pair defaults
+to it, resolved on the component root, so a scoped `--bb-panel-p` override
+keeps working too). Per-**part** asymmetry (header `py: 10px`, body
+`py: 20px`) works by scoping the token to the part class — the padding rules
+resolve it on the part elements and the pair inherits:
+
+```css
 .my-dialog .bb-dialog__header {
-	padding-block: 10px 5px;
+	--py: 10px; /* header block padding (bottom is py/2); × inset follows */
 }
-.my-dialog .bb-dialog__body .bb-dialog__body-content {
-	padding-block: 0 20px;
-}
-.my-dialog .bb-dialog__body:first-child .bb-dialog__body-content {
-	padding-top: 20px;
-}
-.my-dialog .bb-dialog__footer {
-	padding-block: 20px;
+.my-dialog .bb-dialog__content {
+	--py: 20px; /* body bottom padding, and its top in the headerless case */
 }
 ```
 
-Use `padding-block`, not the `padding` shorthand, so the horizontal half keeps
-tracking `--bb-panel-p`. Specificity: the library rules are
-`.bb-dialog .bb-dialog__header` (0,2,0), `.bb-dialog__body-content` (0,1,0) and
-`.bb-dialog__body:first-child .bb-dialog__body-content` (0,2,1) — the
-three-class app selectors above beat all of them. `BbOffCanvas` is identical
-with `.bb-offcanvas__*`.
-
-**`--px` and `--pt` are not dialog knobs.** `.bb-dialog` declares them, but
-nothing in the dialog or off-canvas CSS reads them, and every component that
-_does_ read `--px` (`BbButton`, `BbAlert`, `BbTooltip`, `BbBaseSlider`)
-re-declares it on its own root class, so an ancestor value never reaches those
-either. Setting `--px` on a dialog part is inert — it silently leaves the
-horizontal padding at whatever `--bb-panel-p` resolves to.
+The body padding lives on `.bb-dialog__content`, the node `pt:content` lands on,
+so `pt:content="[--py:20px]"` or `pt:content="px-8"` does it without a
+stylesheet (until 3.0.0-beta.29 it sat on the inner `__body-content`).
+
+Derived spacings scale with it — the header's bottom padding is `py / 2` and
+the close button's block inset tracks the header's `py`. If you need exact
+literals instead of those ratios, a `padding-block` rule on the part class
+still works (use `padding-block`, not the `padding` shorthand, so the
+horizontal half keeps tracking `--px`; the library part selectors are
+at most (0,2,1) specific, so a three-class app selector beats them all).
+`BbOffCanvas` is identical with `.bb-offcanvas__*` and the same `--px` /
+`--py` names.
+
+**Scope the pair to the surface, and it stays the surface's.** `--px` is also
+a local on other components (`BbButton`, `BbAlert`, `BbTooltip`,
+`BbSlider`), but each of those re-declares it on its own element (the slider on
+`.bb-slider__body`), so a
+dialog-scoped `--px` never leaks into the buttons or alerts inside the dialog
+— and, symmetrically, never set the pair on `:root` or an arbitrary ancestor:
+the surface roots' own defaults mask it there, and you would be reaching into
+every other `--px`-reading component anyway. (`--pt` remains dead — nothing
+reads it.)
 
 If only the **vertical rhythm between parts** differs, the local `--dialog-gap`
-(default `--bb-panel-p`) already does it without a padding rule: it drives the
-gap below the body content and the footer's block padding on `.bb-dialog` and
+(default `--py`) already does it without a padding rule: it drives the gap
+below the body content and the footer's block padding on `.bb-dialog` and
 `.bb-offcanvas`. It does **not** cover the header's top padding, or the body's
-top padding in the headerless case — those still take `--bb-panel-p`.
+top padding in the headerless case — those still take `--py`.
 
 **`--bb-dialog-close` maps to nothing — delete it.** In v2 it was the close
 **icon** width (`12px`) and the button around it added `8px` of padding, so the
@@ -412,15 +543,9 @@ the box:
 That selector needs at least three classes to beat the library's
 `.bb-dialog .bb-dialog__header > .bb-close-button` (0,3,0).
 
-**`--bb-dialog-title-weight` has no v3 home.** The title is `font-weight: 500`,
-hardcoded. Restore v2's `600` with a rule that outweighs the library's
-`.bb-dialog .bb-dialog__header .bb-dialog__title` (0,3,0):
-
-```css
-.my-dialog .bb-dialog__header .bb-dialog__title {
-	font-weight: 600;
-}
-```
+**`--bb-dialog-title-weight` → `--dialog-title-fw`** (default `500`, read by the
+dialog and by the phone sheet). Restore v2's `600` with
+`.bb-theme { --dialog-title-fw: 600 }`; no selector into the header is needed.
 
 A complete v3 theme is typically two small blocks of ~10 declarations
 (`--bb-primary`, `--bb-radius`, `--bb-control-h`, `--bb-panel`, `--bb-text`,
@@ -454,15 +579,25 @@ and delete only the declarations that merely restated a **v2** default.
 **A type that narrowed.** `--bb-ring-opacity` survives by name but v3 registers
 it with `@property … syntax: '<percentage>'`:
 
-| token               | v2 form                                                  | v3 form                          | symptom                                                                                                                                                                                              |
-| ------------------- | -------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--bb-ring-opacity` | unitless `0.25` / `0.4`, multiplied by `100%` internally | `25%` / `40%` — a `<percentage>` | ⚠ silent: a unitless override is invalid at computed-value time, so it is discarded and the token falls back to the registered `initial-value: 25%`. v3's own defaults are `15%` light / `40%` dark. |
+| token               | v2 form                                                  | v3 form                          | symptom                                                                                                                                                                                                                                                                                    |
+| ------------------- | -------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--bb-ring-opacity` | unitless `0.25` / `0.4`, multiplied by `100%` internally | `25%` / `40%` — a `<percentage>` | ⚠ silent: a unitless override is invalid at computed-value time, so it is discarded and the token falls back to the registered `initial-value: 15%` — v3's own light default, so a light page silently renders the stock ring, while a dark page lands on `15%` against the shipped `40%`. |
 
 Nothing reports this — not `vue-tsc`, not the eslint plugin, not
 `npx bitboss-ui check` (none of them read CSS), and not the browser console:
 an invalid registered-property value is not a parse error, so it logs nothing.
-Grep your stylesheets for `--bb-ring-opacity` and confirm every value carries a
-`%`.
+Grep your stylesheets for `--bb-ring-opacity` and check **both directions of
+every hit**:
+
+- every **write** must carry a `%` (`0.15` → `15%`), and
+- every **read** must stop multiplying by `100%`. The v2 idiom for consuming
+  the unitless form was exactly that —
+  `calc(100% - var(--bb-ring-opacity) * 100%)` — and under v3 it multiplies a
+  percentage by a percentage, which is invalid in `calc()`. The invalid math
+  takes the whole declaration down (typically a `color-mix()` ring), so the
+  failure is _worse_ than the write side: a stale write still produces a ring
+  at the fallback strength, a stale read produces **no ring at all**, equally
+  silently. Delete the `* 100%`.
 
 Nine tokens are `@property`-registered in v3 — the eight color knobs
 (`syntax: '<color>'`) plus `--bb-ring-opacity`. Each rejects values outside its
@@ -485,18 +620,25 @@ theme tokens. In v2 a skin was four locals set on your own modifier class:
 }
 ```
 
-v3 reads none of those — the old locals are inert, so a skin ported verbatim
-silently reverts to the library defaults. Each variant has its own `--bb-*`
-family, declared in `variables.css` and overridable globally or on any scope:
-
-| v2 local on `.bb-button`                     | v3 token family (per variant)       |
-| -------------------------------------------- | ----------------------------------- |
-| `--color` (fill)                             | `--bb-<variant>`                    |
-| `--text-color`                               | `--bb-<variant>-fg`                 |
-| `--border-color`                             | `--bb-<variant>-border`             |
-| `--ring-color`                               | `--bb-<variant>-ring`               |
-| _derived_ `mix(--color 90%, black)` on hover | `--bb-<variant>-hover` (explicit)   |
-| _derived_ `mix(--color 80%, black)` on press | `--bb-<variant>-pressed` (explicit) |
+**Three of those four are inert in v3; `--border-color` is not.** A skin
+ported verbatim therefore half-applies: the fill and the text revert to the
+library defaults while your border keeps painting, which looks like a styling
+bug rather than a dead override. Convert the **whole** rule, or delete it.
+
+`.bb-button` reads `--bg`, `--fg`, `--border-color`, `--ring-color`, `--bg-hover`
+and `--bg-pressed` as **per-instance** locals, and each variant's default for
+them comes from a `--bb-<variant>-*` family declared in `variables.css`. So a
+v2 local maps two ways — to the theme token if you want every button to
+follow, or to the paint local if you want this one class to:
+
+| v2 local on `.bb-button`                     | v3 theme token (everywhere)         | v3 paint local (this class)                    |
+| -------------------------------------------- | ----------------------------------- | ---------------------------------------------- |
+| `--color` (fill)                             | `--bb-<variant>`                    | `--bg`                                         |
+| `--text-color`                               | `--bb-<variant>-fg`                 | `--fg`                                         |
+| `--border-color`                             | `--bb-<variant>-border`             | `--border-color` — ⚠ same name, and it is LIVE |
+| `--ring-color`                               | `--bb-<variant>-ring`               | `--ring-color`                                 |
+| _derived_ `mix(--color 90%, black)` on hover | `--bb-<variant>-hover` (explicit)   | `--bg-hover`                                   |
+| _derived_ `mix(--color 80%, black)` on press | `--bb-<variant>-pressed` (explicit) | `--bg-pressed`                                 |
 
 `<variant>` is one of `primary`, `secondary`, `outline`, `ghost`,
 `destructive`, `link`. Note the last two rows: v2 _derived_ hover and pressed
@@ -551,10 +693,12 @@ Built-in sets and the class each name maps to:
 | `alertVariants`        | `outline, primary, destructive, warning`                                      | `bb-alert--<name>`                  |
 | `badgeVariants`        | `primary, secondary, destructive, outline`                                    | `bb-badge--<name>`                  |
 | `indicatorVariants`    | `default, success, info, warning, destructive`                                | `bb-indicator--<name>`              |
-| `toastVariants`        | `default, success, info, warning, destructive`                                | `bb-toast-message--<name>`          |
+| `toastVariants`        | `default, success, info, warning, destructive`                                | `bb-toast__panel--<name>`           |
 | `confirmVariants`      | `default, destructive`                                                        | `bb-confirm--<name>`                |
 | `dropdownItemVariants` | `default, destructive`                                                        | `bb-dropdown__item--variant-<name>` |
 | `tooltipVariants`      | `default, destructive`                                                        | `bb-tooltip--<name>`                |
+| `inputVariants`        | `outline, secondary, ghost`                                                   | `bb-field-input--<name>`            |
+| `tabsVariants`         | `pill, line, none`                                                            | `bb-tabs-list--<name>`              |
 
 ### Picking a v3 name for a v2 `theme` value
 
@@ -565,9 +709,27 @@ this order:
 1. **Name is in the table, and your app never styled it** → use the built-in
    `variant`. This is the only genuinely free conversion.
 2. **Name is in the table, but your app styled it itself** → v3's built-in now
-   paints underneath your rules. Decide explicitly: accept v3's look and delete
-   your CSS, or register the name (`alertVariants: ['warning']`) so your CSS
-   stays the sole styling source.
+   paints underneath your rules, and **registering the name does not stop it**.
+   The registries feed the type-checker only: `alertVariants: ['warning']`
+   regenerates the typed union and nothing else — no CSS is generated and none
+   is suppressed; the built-in `.bb-alert--warning` skin ships unconditionally
+   in `styles.css` and still applies, so every property your CSS does not
+   explicitly set shows through as the library's. Decide explicitly: accept
+   v3's look and delete your CSS, or keep your look — which requires your rules
+   to **win the cascade** over the library's. Every paint variant compiles
+   single-class — `.bb-alert--warning`, `.bb-toast__panel--*`,
+   `.bb-button--outline`, `.bb-badge--*`, `.bb-indicator--*`,
+   `.bb-tooltip--*`, all (0,1,0). A flat `.bb-x--name` therefore ties them and
+   wins on order, provided you load your sheet after `styles.css` — which is
+   the documented order. Authoring at block+modifier
+   (`.bb-alert.bb-alert--warning`) still works and is order-proof, so it is
+   the safer habit if your bundler's CSS order is not under your control.
+   Size modifiers are NOT single-class (`.bb-button.bb-button--sm`), so a flat
+   size override still loses. Or sidestep the collision by renaming to a name
+   not in the table, which moves you to case 3, where your CSS genuinely is
+   the sole source. Whichever you pick,
+   still register the name: that part is required for the type-check either
+   way.
 3. **Name is not in the table** → register it and keep your CSS. **Do not remap
    onto the "nearest" built-in.** `error → destructive`, `danger →
 destructive`, `info → primary` all compile, all look plausible in review,
@@ -575,8 +737,12 @@ destructive`, `info → primary` all compile, all look plausible in review,
    deliberate redesign decision, never as a mechanical migration step.
 4. **Name was never styled by anyone** → see the next subsection.
 
-Registering is cheap — one array entry per name — and it is the
-behaviour-preserving default. Prefer it whenever you are not sure.
+Registering is cheap — one array entry per name — and for a name **not** in
+the table it is the behaviour-preserving default: the library has no rule for
+an unknown name, so your CSS is the sole styling source. For a name that **is**
+in the table, registering buys the type-check and nothing else — behaviour
+preservation there is a cascade question (case 2 above). When unsure, prefer a
+non-colliding name.
 
 ### ⚠ silent — a `theme` value that did nothing in v2 may do something in v3
 
@@ -645,22 +811,23 @@ every occurrence; this section explains each pattern once.
 
 ### 5.1 Components renamed, split, or removed
 
-| v2                                                                            | v3                                                                        | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BbBadge` (floating count/dot anchored to an element)                         | **`BbIndicator`**                                                         | `content` → `text`, `color` → `variant`, `floating` removed. New `max` prop renders `${max}+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `BbChip`                                                                      | **removed** — use `BbBadge`                                               | v3 `BbBadge` is the inline pill/token: same `click:clear` event and `clearableLabel`, but `clearable` is now **opt-in** (v2 chips defaulted clearable).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| —                                                                             | **`BbBadge`** (repurposed)                                                | The v3 badge is a new component in an old name: inline label with `variant`, `icon`, `loading`, `clearable`. Any v2 `<BbBadge>` you have is an _indicator_ — rename it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `BbTab`                                                                       | **`BbTabs`**                                                              | Component and types renamed (`BbTabProps` → `BbTabsProps`; deprecated type aliases remain, the component name does not).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `Base*` internals (`BaseButton`, `BaseDialog`, `BaseCheckbox`, `BaseTag`, …)  | **`BbBase*`**                                                             | If you imported any base primitive or targeted its BEM block in CSS (`.base-btn` → `.bb-base-button`), rename. `BbBaseButton` is now a supported public export.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `BbCheckboxIcon` / `BbRadioIcon` / `BbSwitchIcon`                             | **`BbBaseCheckboxIcon`** / **`BbBaseRadioIcon`** / **`BbBaseSwitchIcon`** | Rename import + BEM block (`.bb-base-checkbox-container__icon` → `.bb-base-checkbox-icon`; see §5.6).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `BbBase*` input controls + `CommonInputWrapper` / `CommonInputOuterContainer` | **no longer exported** — use the full public component                    | v2 exposed the styled base inputs (`BbBaseTextInput`, `BbBaseSelect`, `BbBaseSwitch`, `BbBaseDatePickerInput`, …) and the input-chrome wrappers because a few full inputs were missing. v3 ships a full public component for every input, so these are internal now. Use `BbTextInput` / `BbSelect` / `BbSwitch` / … ; for a bare/inline control with no label gap, pass **`hideLabel`**. Still exported: `BbBaseButton` and the glyphs (`BbBaseCheckboxIcon` / `BbBaseRadioIcon` / `BbBaseSwitchIcon`).<br><br>**These primitives were also restructured, not just un-exported.** The outer+inner pair merged into one `CommonInputWrapper` (`.common-input-wrapper` / `__inner`), `BbBaseInputContainer` gained an inner `__layout` element that now carries the orientation modifiers, and `__input` became `__control`. Anything anchored to the old DOM — app CSS, test selectors, JS positioning a floating panel off `.bb-base-input-container__input` — fails silently: nothing throws, the element is simply never found. See §5.6.<br><br>**Built a custom control on the chrome?** If your app composed `BaseInputContainer` + `CommonInputOuterContainer` + `CommonInputInnerContainer` around an element the library does not ship (a highlight-overlay textarea, a field with a bespoke floating panel), there is no public v3 component to swap in — those wrappers exist in v3 but are internal. The sanctioned fallback is to **copy** the chrome into your app from the implementation source that ships with the package: `node_modules/bitboss-ui/dist/ai/source/BbBaseInputContainer.md` and `dist/ai/source/CommonInputWrapper.md` carry the complete `.vue` template, `types.ts` and `index.css` for each (89 components have one). Those files are banner-marked "Reference Only - Internal" — that bans _importing_ the internal component, not copying its template and CSS into a component of your own, which is the supported route here. The class names a copied template emits are styled by the public `bitboss-ui/styles.css`, so it inherits library chrome for free. Check first whether v3 already ships what you built — `BbTimePickerInput` and `BbTimePicker` are new in v3. |
-| `useWizard` (+ `Step`, `WizardState`, `wizardInjectionKey`)                   | **removed**                                                               | No replacement — it was unused scaffolding. Copy the v2 implementation into your app if you depended on it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `BbIntersection` (+ `BbIntersectionProps` / `BbIntersectionEvents`)           | **removed**                                                               | No replacement — it wrapped `IntersectionObserver` in ~40 lines and carried no styling. Use `@vueuse/core`'s `useIntersectionObserver`, or copy the v2 component. Full mapping of the `shown`/`hidden`/`intersected` events and the slot props: [components/bb-intersection.md](./components/bb-intersection.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `useBroadcastChannelInstance`                                                 | **removed**                                                               | Same reasoning: a typed wrapper over a browser API, no markup, no styling, used by no component here. Cross-tab messaging is app architecture. Use `useBroadcastChannel` from `@vueuse/core` — already in your tree, since this library depends on it. **Two behaviours do not carry over** (handler auto-removal on unmount, and the refcount the v2 docs described but never had): [components/use-broadcast-channel-instance.md](./components/use-broadcast-channel-instance.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `BbRatio` (+ `BbRatioProps`, `.bb-ratio`)                                     | **removed**                                                               | No replacement — it was a one-rule wrapper. Use the `aspect-ratio` CSS property, or copy the v2 component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `useQueue`, `useQuery`                                                        | **removed**                                                               | Both were public v2 exports and neither has a v3 equivalent; the import fails at build. Copy the v2 implementations out of the 2.1.135 tarball (`dist/composables/useQueue.d.ts`, `useQuery.d.ts`) into your app, or replace them with `@vueuse/core` equivalents.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `BbToastMessage` type export                                                  | **removed**                                                               | Use `BbToastOptions` (the `toast()` options shape).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `IconRegistry` / `IconNameFromRegistry` exports                               | **removed**                                                               | Icon names are plain strings now. Local art goes in `iconDir` as `local:<name>`; delete your `IconRegistry` augmentation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| v2                                                                            | v3                                                                        | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbBadge` (floating count/dot anchored to an element)                         | **`BbIndicator`**                                                         | `content` → `text`, `color` → `variant`, `floating` removed. New `max` prop renders `${max}+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `BbChip`                                                                      | **removed** — use `BbBadge`                                               | v3 `BbBadge` is the inline pill/token: same `click:clear` event and `clearableLabel`, but `clearable` is now **opt-in** (v2 chips defaulted clearable).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| —                                                                             | **`BbBadge`** (repurposed)                                                | The v3 badge is a new component in an old name: inline label with `variant`, `icon`, `loading`, `clearable`. Any v2 `<BbBadge>` you have is an _indicator_ — rename it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| —                                                                             | **`BbCalendar`** (new)                                                    | New in v3, no v2 equivalent: the calendar grid that v2 only had inside the date picker input's popover, now a component of its own that renders **always visible**, in place — no activator, no popover, no `label` / `hint` / `errors` chrome (name it with `aria-label`). Nothing to migrate; reach for it where a v2 app kept a date popover pinned open, or rebuilt a month grid by hand, to fake an inline calendar (a booking step, a dashboard date panel, a range under From / To fields in a filter sheet). A date _field_ stays `BbDatePickerInput`. `BbDatePicker` and `BbDatePickerInput` render this same component, so its grid classes are `.bb-calendar__*` (§8).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `BbTab`                                                                       | **`BbTabs`**                                                              | Component and types renamed (`BbTabProps` → `BbTabsProps`; deprecated type aliases remain, the component name does not).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `Base*` internals (`BaseButton`, `BaseDialog`, `BaseCheckbox`, `BaseTag`, …)  | **`BbBase*`**                                                             | If you imported any base primitive or targeted its BEM block in CSS (`.base-btn` → `.bb-base-button`), rename. `BbBaseButton` is now a supported public export.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `BbCheckboxIcon` / `BbRadioIcon` / `BbSwitchIcon`                             | **`BbBaseCheckboxIcon`** / **`BbBaseRadioIcon`** / **`BbBaseSwitchIcon`** | Rename import + BEM block (`.bb-base-checkbox-container__icon` → `.bb-base-checkbox-icon`; see §5.6).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `BbBase*` input controls + `CommonInputWrapper` / `CommonInputOuterContainer` | **no longer exported** — use the full public component                    | v2 exposed the styled base inputs (`BbBaseTextInput`, `BbBaseSelect`, `BbBaseSwitch`, `BbBaseDatePickerInput`, …) and the input-chrome wrappers because a few full inputs were missing. v3 ships a full public component for every input, and the private field layers are **deleted**, not hidden: there is no `BbBaseTextInput` / `BbBaseSelect` / `BbBaseSwitch` in v3 at all (the flatten, Queue 30). Use `BbTextInput` / `BbSelect` / `BbSwitch` / … ; for a bare/inline control with no label gap, pass **`hideLabel`**. Still exported: `BbBaseButton` and the glyphs (`BbBaseCheckboxIcon` / `BbBaseRadioIcon` / `BbBaseSwitchIcon`).<br><br>**The shared chrome was also restructured, not just un-exported.** The outer+inner pair merged into one `CommonFieldInput` (`.bb-field-input` / `__box`), `CommonField` gained an inner `__layout` element that now carries the orientation modifiers, and `__input` became `__input-wrapper`. Anything anchored to the old DOM — app CSS, test selectors, JS positioning a floating panel off `.bb-base-input-container__input` — fails silently: nothing throws, the element is simply never found. See §5.6.<br><br>**Built a custom control on the chrome?** If your app composed `BbBaseInputContainer` + `CommonInputOuterContainer` + `CommonInputInnerContainer` around an element the library does not ship (a highlight-overlay textarea, a field with a bespoke floating panel), there is no public v3 component to swap in — the chrome is the reference-only `CommonField` / `CommonFieldInput` pair. The sanctioned fallback is to **copy** the chrome into your app from the implementation source that ships with the package: `node_modules/bitboss-ui/dist/ai/source/CommonField.md` and `dist/ai/source/CommonFieldInput.md` carry the complete `.vue` template, `types.ts` and `index.css` for each (72 components have one). Those files are banner-marked "Reference Only - Internal" — that bans _importing_ the internal component, not copying its template and CSS into a component of your own, which is the supported route here. The class names a copied template emits are styled by the public `bitboss-ui/styles.css`, so it inherits library chrome for free. Check first whether v3 already ships what you built — `BbTimePickerInput`, `BbTimePicker` and `BbCalendar` (the calendar grid on its own, always visible) are new in v3. |
+| `useWizard` (+ `Step`, `WizardState`, `wizardInjectionKey`)                   | **removed**                                                               | No replacement — it was unused scaffolding. Copy the v2 implementation into your app if you depended on it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `BbIntersection` (+ `BbIntersectionProps` / `BbIntersectionEvents`)           | **removed**                                                               | No replacement — it wrapped `IntersectionObserver` in ~40 lines and carried no styling. Use `@vueuse/core`'s `useIntersectionObserver`, or copy the v2 component. Full mapping of the `shown`/`hidden`/`intersected` events and the slot props: [components/bb-intersection.md](./components/bb-intersection.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `useBroadcastChannelInstance`                                                 | **removed**                                                               | Same reasoning: a typed wrapper over a browser API, no markup, no styling, used by no component here. Cross-tab messaging is app architecture. Use `useBroadcastChannel` from `@vueuse/core` — already in your tree, since this library depends on it. **Two behaviours do not carry over** (handler auto-removal on unmount, and the refcount the v2 docs described but never had): [components/use-broadcast-channel-instance.md](./components/use-broadcast-channel-instance.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `BbRatio` (+ `BbRatioProps`, `.bb-ratio`)                                     | **removed**                                                               | No replacement — it was a one-rule wrapper. Use the `aspect-ratio` CSS property, or copy the v2 component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `useQueue`, `useQuery`                                                        | **removed**                                                               | Both were public v2 exports and neither has a v3 equivalent; the import fails at build. Copy the v2 implementations out of the 2.1.135 tarball (`dist/composables/useQueue.d.ts`, `useQuery.d.ts`) into your app, or replace them with `@vueuse/core` equivalents.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `BbToastMessage` type export                                                  | **removed**                                                               | Use `BbToastOptions` (the `toast()` options shape).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `IconRegistry` / `IconNameFromRegistry` exports                               | **removed**                                                               | Icon names are plain strings now. Local art goes in `iconDir` as `local:<name>`; delete your `IconRegistry` augmentation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 ### 5.2 The polarity wave: booleans now read as opt-in
 
@@ -680,35 +847,39 @@ to the new name (`hide-close`).
 > applies to **`BbAlert`, `BbDialog` and `BbOffCanvas` only**. See §5.4 and the
 > per-component files. `npx bitboss-ui check` catches both spellings if you slip.
 
-| Component(s)                                       | v2 prop (default)                                         | v3 prop (default)                                                                                                                                                                                                               |
-| -------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BbAlert`, `BbDialog`, `BbOffCanvas`               | `showClose` (`true`)                                      | `hideClose` (`false`) — also on `toast()` options, where v2 had `showClose` too and the same inversion applies (`showClose: false` → `hideClose: true`, `showClose: true` → delete). Genuinely **new** on `confirm()` options.  |
-| `BbTable`                                          | `allowSelectAll` (`true`)                                 | `disableSelectAll` (`false`)                                                                                                                                                                                                    |
-| `BbTabs`                                           | `animateX` / `animateY` (`true`)                          | `disableAnimateX` / `disableAnimateY` (`false`)                                                                                                                                                                                 |
-| `BbButton`                                         | `autoLoading` (`false`)                                   | `disableAutoLoading` (`false`) — **⚠ silent behavior flip:** async `@click` handlers now show the loading spinner and disable the button automatically. Pass `disable-auto-loading` to keep v2 behavior.                        |
-| `BbDropdownButton`                                 | `autoLoading` (`true`)                                    | `disableAutoLoading` (`false`)                                                                                                                                                                                                  |
-| `BbDropdownButton`                                 | `disabledWhileLoading` (`true`)                           | **removed** — always disabled while loading now                                                                                                                                                                                 |
-| `BbSlider`                                         | `thumbTranslate` (`true`)                                 | `disableThumbTranslate` (`false`)                                                                                                                                                                                               |
-| `BbColorPalette`, `BbSelectPopover`                | `flip` (`true`)                                           | `disableFlip` (`false`)                                                                                                                                                                                                         |
-| `BbSelect`, `BbSelectPopover`, `BbDatePickerInput` | `allowWriting` (`true`, tokens `boolean \| 'not-mobile'`) | `disableWriting` (`false`, tokens `boolean \| 'mobile' \| 'desktop'`) — `allow-writing="not-mobile"` becomes `disable-writing="mobile"`                                                                                         |
-| `BbCheckbox`, `BbRadio`, `BbSwitch`                | `reverse` (`true`)                                        | `reverse` (`false`, **meaning inverted**) — unset renders identically, but explicit values flip: v2 `:reverse="false"` → v3 `reverse`; v2 `reverse` → delete. **⚠ silent** — see [bb-checkbox.md](./components/bb-checkbox.md). |
-| `BbAlert`                                          | `ariaAtomic` (`true`)                                     | **removed** — correct live-region behavior is hardcoded                                                                                                                                                                         |
-| `BbChip`                                           | `clearable` (`true`)                                      | **removed with the component** — `BbBadge.clearable` defaults `false`                                                                                                                                                           |
+| Component(s)                         | v2 prop (default)                                         | v3 prop (default)                                                                                                                                                                                                               |
+| ------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbAlert`, `BbDialog`, `BbOffCanvas` | `showClose` (`true`)                                      | `hideClose` (`false`) — also on `toast()` options, where v2 had `showClose` too and the same inversion applies (`showClose: false` → `hideClose: true`, `showClose: true` → delete). Genuinely **new** on `confirm()` options.  |
+| `BbTable`                            | `allowSelectAll` (`true`)                                 | `disableSelectAll` (`false`)                                                                                                                                                                                                    |
+| `BbTabs`                             | `animateX` / `animateY` (`true`)                          | `disableAnimateX` / `disableAnimateY` (`false`)                                                                                                                                                                                 |
+| `BbButton`                           | `autoLoading` (`false`)                                   | `disableAutoLoading` (`false`) — **⚠ silent behavior flip:** async `@click` handlers now show the loading spinner and disable the button automatically. Pass `disable-auto-loading` to keep v2 behavior.                        |
+| `BbDropdownButton`                   | `autoLoading` (`true`)                                    | `disableAutoLoading` (`false`)                                                                                                                                                                                                  |
+| `BbDropdownButton`                   | `disabledWhileLoading` (`true`)                           | **removed** — always disabled while loading now                                                                                                                                                                                 |
+| `BbSlider`                           | `thumbTranslate` (`true`)                                 | `disableThumbTranslate` (`false`)                                                                                                                                                                                               |
+| `BbColorPalette`, `BbSelectPopover`  | `flip` (`true`)                                           | `disableFlip` (`false`)                                                                                                                                                                                                         |
+| `BbSelect`, `BbSelectPopover`        | `allowWriting` (`true`, tokens `boolean \| 'not-mobile'`) | `disableWriting` (`'auto'`, tokens `boolean \| 'mobile' \| 'desktop' \| 'auto'`) — `allow-writing="not-mobile"` becomes `disable-writing="mobile"`; unset hides the search field on short array lists (see §6)                  |
+| `BbDatePickerInput`                  | `allowWriting` (`true`, tokens `boolean \| 'not-mobile'`) | `disableWriting` (`false`, tokens `boolean \| 'mobile' \| 'desktop'`) — `allow-writing="not-mobile"` becomes `disable-writing="mobile"`                                                                                         |
+| `BbCheckbox`, `BbRadio`, `BbSwitch`  | `reverse` (`true`)                                        | `reverse` (`false`, **meaning inverted**) — unset renders identically, but explicit values flip: v2 `:reverse="false"` → v3 `reverse`; v2 `reverse` → delete. **⚠ silent** — see [bb-checkbox.md](./components/bb-checkbox.md). |
+| `BbAlert`                            | `ariaAtomic` (`true`)                                     | **removed** — correct live-region behavior is hardcoded                                                                                                                                                                         |
+| `BbChip`                             | `clearable` (`true`)                                      | **removed with the component** — `BbBadge.clearable` defaults `false`                                                                                                                                                           |
 
 ### 5.3 Straight renames
 
-| Component                                          | v2                                | v3                                                                                                                                                                             |
-| -------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `BbPagination`, `BbTabs`                           | `querykey`                        | `queryKey` — **⚠ silent**: a leftover `querykey` falls through to the DOM and the component uses the default key (`'page'` / `'tab'`), quietly moving your URL params.         |
-| `BbTooltip`                                        | `timeout`                         | `delay`                                                                                                                                                                        |
-| `toast()`, `confirm()` options                     | `timeout`                         | `duration` — same meaning (ms before auto-dismiss). `toast()` throws on `duration <= 0`; on `confirm()` it resolves the promise `false` quietly and implies `autoClose: true`. |
-| `useToast()`                                       | `dismissAll()`                    | `dismiss()` with **no argument**. The v3 return shape is `{ toast, dismiss, update }`.                                                                                         |
-| `BbIcon`                                           | `type` (required)                 | `icon`                                                                                                                                                                         |
-| `BbColorPalette`, `BbColorInput`                   | `picker`                          | `eyeDropper`                                                                                                                                                                   |
-| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup` | `labelPosition`                   | `legendPosition`                                                                                                                                                               |
-| `BbSelect`                                         | `prefill: 'focus'`                | `prefill: 'interaction'` (value rename; same default)                                                                                                                          |
-| `BbToast` (host)                                   | `placement` (e.g. `bottom-start`) | `position` (corner set: `top-left` … `bottom-right`)                                                                                                                           |
-| `BbAlert`, `BbTooltip`, `toast()`, `confirm()`     | `theme`                           | `variant` (typed — see section 4). On `confirm()` the v2 type was a free-form `theme?: string`; v3's is `ConfirmVariantType` (`default`, `destructive`).                       |
+| Component                                                                                                                                                                                                                                                                                                                                                                                              | v2                                       | v3                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbPagination`, `BbTabs`                                                                                                                                                                                                                                                                                                                                                                               | `querykey`                               | `queryKey` — **⚠ silent**: a leftover `querykey` falls through to the DOM and the component uses the default key (`'page'` / `'tab'`), quietly moving your URL params.                                                                                                                                                                                                                                                                                         |
+| `BbTooltip`                                                                                                                                                                                                                                                                                                                                                                                            | `timeout`                                | `delay`                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `toast()`, `confirm()` options                                                                                                                                                                                                                                                                                                                                                                         | `timeout`                                | `duration` — same meaning (ms before auto-dismiss). `toast()` throws on `duration <= 0`; on `confirm()` it resolves the promise `false` quietly and implies `autoClose: true`.                                                                                                                                                                                                                                                                                 |
+| `useToast()`                                                                                                                                                                                                                                                                                                                                                                                           | `dismissAll()`                           | `dismiss()` with **no argument**. The v3 return shape is `{ toast, dismiss, update }`.                                                                                                                                                                                                                                                                                                                                                                         |
+| `BbIcon`                                                                                                                                                                                                                                                                                                                                                                                               | `type` (required)                        | `icon`                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `BbColorPalette`, `BbColorInput`                                                                                                                                                                                                                                                                                                                                                                       | `picker`                                 | `eyeDropper`                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`                                                                                                                                                                                                                                                                                                                                                     | `labelPosition`                          | `legendPosition`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Every form control — `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbColorInput`, `BbSelect`, `BbDatePickerInput`, `BbTimePickerInput`, `BbTag`, `BbCheckbox`, `BbRadio`, `BbSwitch`, `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`, `BbRating`, `BbSlider`                                                                                                                                      | `direction`                              | `layout` — same values (`'auto'`, `'horizontal'`, `'vertical'`, a `'xx xxxxxx'` ratio), plus `'label-fill'` (the label takes the free space, the input keeps its size — with `reverse`, the settings row) and `'input-fill'`. **⚠ silent**: a leftover `direction` falls through to the root as an HTML attribute and the field keeps its default layout. The ESLint plugin's `--fix` renames it.                                                              |
+| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`                                                                                                                                                                                                                                                                                                                                                     | `inputDirection`                         | `listLayout` — `'horizontal'` (default) / `'vertical'` / `'vertical-stretch'` / `'tiles'`. **⚠ silent**: v2 `'vertical'` rows spanned the list; v3 `'vertical'` rows keep their own width, and `'vertical-stretch'` is the v2 look — the ESLint plugin's `--fix` maps a static `'vertical'` to `'vertical-stretch'`, a bound value is only renamed. New beside it: `itemLayout` (each row's input against its label, the `layout` keywords) and `itemReverse`. |
+| `BbSelect`                                                                                                                                                                                                                                                                                                                                                                                             | `prefill: 'focus'`                       | `prefill: 'interaction'` (value rename; same default)                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `BbToast` (host)                                                                                                                                                                                                                                                                                                                                                                                       | `placement` (e.g. `bottom-start`)        | `position` (corner set: `top-left` … `bottom-right`)                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `BbAlert`, `BbTooltip`, `toast()`, `confirm()`                                                                                                                                                                                                                                                                                                                                                         | `theme`                                  | `variant` (typed — see section 4). On `confirm()` the v2 type was a free-form `theme?: string`; v3's is `ConfirmVariantType` (`default`, `destructive`).                                                                                                                                                                                                                                                                                                       |
+| Every form control with a warning state — `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbColorInput`, `BbSelect`, `BbSelectPopover`, `BbDatePickerInput`, `BbTimePickerInput`, `BbTag`, `BbCheckbox`, `BbRadio`, `BbSwitch`, `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`, `BbRating`, `BbSlider`, `BbDropzone` — and the `BbBaseCheckboxIcon` / `BbBaseRadioIcon` / `BbBaseSwitchIcon` glyphs | `hasWarning` _(v3 ≤ beta.24; not in v2)_ | `hasWarnings` — plural, matching `hasErrors` and the `warnings` prop. **⚠ silent**: a leftover `has-warning` falls through to the root as an HTML attribute and the warning chrome never shows. The ESLint plugin's `--fix` renames it. Slot props that carried it (`#input`, `#label`) are renamed the same way.                                                                                                                                              |
 
 ### 5.4 Removed props (no replacement needed — behavior became default or moved)
 
@@ -719,15 +890,15 @@ to the new name (`hide-close`).
 - **`color` everywhere**: gone from `BbAvatar`, `BbIcon`, `BbSpinner`,
   `BbCheckbox`, `BbRadio`, `BbSwitch`, `BbSlider`, `BbRating` and all three
   groups. Components inherit `currentColor` / theme tokens; style via CSS or
-  the token knobs. `BbAvatar`'s knobs are named: set **both** `--bg-color` and
-  `--text-color` on `.bb-avatar` (plus `--default-icon-color` for the built-in
-  icon fallback) — setting only the background leaves the initials painted
-  `--bb-primary-fg` on top of it.
+  the token knobs. `BbAvatar`'s knobs are named: set **both** `--bg` and
+  `--fg` on `.bb-avatar` — setting only the background leaves the initials
+  painted `--bb-primary-fg` on top of it. The built-in person glyph mixes
+  `--fg` over `--bg`; there is no third local.
 
   ```css
   .team-avatar .bb-avatar {
-  	--bg-color: #7c3aed;
-  	--text-color: #fff;
+  	--bg: #7c3aed;
+  	--fg: #fff;
   }
   ```
 
@@ -744,6 +915,19 @@ to the new name (`hide-close`).
   emission (reading accepts both forms either way). Details in the
   [component page](./components/bb-date-picker-input.md).
 - **`BbTag`**: `multiple` removed (always an array input).
+- **`vid` on every validated field** (`bitboss-ui/validated`, 3.0.0-beta.41)
+  is gone, and what replaces it depends on what YOU used it for, so read the
+  value. **From v2**, `vid` was the field's name in messages (almost always
+  a display name like `vid="Email address"`): write
+  `validation-label="Email address"`. **From a 3.0 beta**, `vid` was the
+  field's path (`vid="email"`, `vid="address.city"`): write `name` with the
+  same value; brackets work too (`name="address[city]"`), and are what a
+  native form post needs (PHP turns dots in a posted name into `_`).
+  `npx bitboss-ui check --fix` does this by value: words (a space or a
+  capital) → `validation-label`, a key (lowercase, digits, `_`, `-`, dots,
+  brackets) → `name`; anything else it reports with both options. **⚠
+  silent**: a leftover `vid` renders as an HTML attribute and the field falls
+  back to its label-derived path. See § 6 item 18 for what `name` now does.
 - **Built-in tooltip on `BbButton`** (`tooltip`, `tooltipPlacement`,
   `tooltipTimeout`): use the `v-bb-tooltip` directive or wrap in `BbTooltip`.
 - **Arrow props on non-tooltip surfaces**: `hideArrow`
@@ -753,16 +937,16 @@ to the new name (`hide-close`).
   warns.
 - **`BbPopover`**: `showClose`, `closeLabel`, `restoreFocus`, `block` removed —
   render your own close affordance in the content (`#default="{ close }"`).
-- **`BbDialog`**: `description`, `hideHeader`, `compact`, `overlayClasses`,
-  `panelClasses` removed (use the `header` slot and normal classes). The
-  `#description` and `#close` **slots** are gone too — v3's slot set is
-  `header | title | default | footer`, and a custom close control goes inside
-  `#header`, which replaces the whole default header including the ✕ (so
-  `hide-close` is not needed alongside it).
-- **`BbOffCanvas`**: the same `description` prop and the same `#description` /
-  `#close` slots were removed, with the same replacements. The
-  `aria-describedby` wiring `description` used to provide is gone — put the
-  copy in the default slot.
+- **`BbDialog`**: `hideHeader`, `compact`, `overlayClasses`, `panelClasses`
+  removed (use the `header` slot and normal classes). The `#close` **slot** is
+  gone too — v3's slot set is `header | title | description | default | footer`,
+  and a custom close control goes inside `#header`, which replaces the whole
+  default header including the ✕ (so `hide-close` is not needed alongside it).
+  **`description` and `#description` survive**: they were dropped in early v3
+  and restored in 3.0.0-beta.19, unchanged from v2 and with `aria-describedby`
+  wired again.
+- **`BbOffCanvas`**: the same — `#close` removed, `description` /
+  `#description` kept (restored in 3.0.0-beta.19).
 - **`BbBreadcrumbs`**: string `divider` removed (slot-driven now);
   `dividerWidth` default changed `5` → `16`.
 - **`BbPagination`**: `loading` removed.
@@ -796,8 +980,11 @@ to the new name (`hide-close`).
   the items you pass instead.
 - **Models**: `BbTag.modelValue` is `string[]`; `BbDropzone.modelValue` is
   `File | File[] | null`; `BbSlider.modelValue` drops its `string` member.
-- **`direction`** on inputs: the exported `InputDirection` union — keyword
-  typos now fail to compile; two-word ratio strings (`'1 2'`) still work.
+- **`layout`** (v2 `direction`) on inputs: the exported `FieldLayout` union —
+  keyword typos now fail to compile; two-word ratio strings (`'x xx'`) still
+  work. The v3 prereleases up to beta.32 exported this union as
+  `InputDirection`; that type export is gone — import `FieldLayout` (for
+  `layout` / `itemLayout`) or `ListLayout` (for `listLayout`) instead.
 
 ### 5.5b Fields added to public object types
 
@@ -832,27 +1019,123 @@ short.
 
 ### 5.6 Renamed CSS blocks
 
+> **On a 3.0 beta already?** Use [the beta class guide](./v3-beta-css-classes.md)
+> instead: it lists every class 3.0.0-beta.36 renamed so each `pt` part has a
+> class of the same name, and has a find-and-replace script.
+
+**v2 classes that kept their name until 3.0.0-beta.36.** These went through
+the first v3 betas unchanged, then were renamed with the rest of the class
+surface. A v2 app uses the right-hand name directly. The
+[beta class guide](./v3-beta-css-classes.md#every-renamed-class) explains
+each one.
+
+<!-- generated:v2rows -->
+
+| v2 (and 3.0 ≤ beta.35)              | v3                              |
+| ----------------------------------- | ------------------------------- |
+| `.bb-chipsbox-item`                 | `.bb-tag__badge`                |
+| `.bb-commabox-item`                 | `.bb-tag__comma`                |
+| `.bb-select-popover__search-input`  | `.bb-select-popover__input`     |
+| `.bb-button__content`               | `.bb-button__text`              |
+| `.bb-dropdown__items-container`     | `.bb-dropdown__list`            |
+| `.bb-pagination__page-chevron`      | `.bb-pagination__icon`          |
+| `.bb-tooltip__content`              | `.bb-tooltip__panel`            |
+| `.bb-table-caption`                 | `.bb-table__caption`            |
+| `.bb-table-header-row`              | `.bb-table__header-row`         |
+| `.bb-table-header`                  | `.bb-table__cell-column-header` |
+| `.bb-table-data__row`               | `.bb-table__row`                |
+| `.bb-table-data__cell`              | `.bb-table__cell`               |
+| `.bb-toast-message`                 | `.bb-toast__panel`              |
+| `.bb-toast-message__icon`           | `.bb-toast__icon`               |
+| `.bb-toast-message__content`        | `.bb-toast__content`            |
+| `.bb-toast-message__title`          | `.bb-toast__title`              |
+| `.bb-toast-message__text`           | `.bb-toast__text`               |
+| `.bb-toast-message__close`          | `.bb-toast__close`              |
+| `.bb-offcanvas__body`               | `.bb-offcanvas__content`        |
+| `.bb-color-palette__popover`        | `.bb-color-palette`             |
+| `.bb-commabox-item--focused`        | `.bb-tag__comma--highlighted`   |
+| `.bb-dropdown-button__main-btn`     | `.bb-dropdown-button__main`     |
+| `.bb-dropdown-button__dropdown-btn` | `.bb-dropdown-button__toggle`   |
+
+<!-- /generated:v2rows -->
+
 If app CSS or test selectors target library internals, these blocks moved. This
 is the complete set — a class-by-class diff of the v2 stylesheet against v3
 leaves nothing else orphaned. All of it is **silent**: a selector on a class
 nobody emits matches nothing and throws nothing.
 
+One caution when auditing on your own: absence from `styles.css` answers _"is
+it styled"_, not _"is it emitted"_. Some classes carry no library rule but are
+still rendered as styling hooks for you (`.bb-field__hint`
+is one: its wrapper `__hint-wrap` carries the rules, the inner text node is
+bare) — those are correct targets and correctly
+absent from this table, which maps only classes that moved or died. Before
+filing a class as removed, check the component's markup, not just the
+stylesheet.
+
 **Input chrome**
 
-| v2                                                                                                                                | v3                                                                                                                                                                                                                                                                                                                                       |
-| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.bb-common-input-inner-container` (+ `--clearable`, `__prefix`, `__suffix`, `__prepend-icon`, `__append-icon`)                   | `.common-input-wrapper` (+ the same suffixes) — modifiers `--active --compact --disabled --errors --loading --readonly --clearable --warnings` (note: no `bb-` prefix)                                                                                                                                                                   |
-| `.bb-common-input-outer-container`                                                                                                | merged away — the v2 outer/inner pair is one `.common-input-wrapper`, whose inner span is `.common-input-wrapper__inner`                                                                                                                                                                                                                 |
-| `.bb-base-input-outer-container` (+ `--compact`)                                                                                  | merged into `.bb-base-input-container` (+ `--compact`)                                                                                                                                                                                                                                                                                   |
-| `.bb-base-input-container__input` (+ `--left --center --right`)                                                                   | `.bb-base-input-container__control` (+ the same modifiers)                                                                                                                                                                                                                                                                               |
-| `.bb-base-input-container--horizontal` / `--vertical` / `--reverse` (on the root)                                                 | `.bb-base-input-container__layout--horizontal` / `--vertical` / `--reverse` — v3 inserts an inner `__layout` element and the orientation modifiers moved onto it; the root keeps only state modifiers (`--disabled --errors --warnings --loading --readonly --compact --floating-label --inside-label` …)                                |
-| `.bb-base-input-container--label-mode-floating`                                                                                   | `.bb-base-input-container--floating-label`                                                                                                                                                                                                                                                                                               |
-| `.bb-base-input-container__errors-outer`                                                                                          | `.bb-base-input-container__errors-wrap`                                                                                                                                                                                                                                                                                                  |
-| `.bb-base-input-container__hint-container`                                                                                        | `.bb-base-input-container__hint-wrap`                                                                                                                                                                                                                                                                                                    |
-| `.base-btn`, `.base-btn--block`, …                                                                                                | `.bb-base-button*`                                                                                                                                                                                                                                                                                                                       |
-| `.bb-base-checkbox-container` / `.bb-base-radio-container` / `.bb-base-switch-container`                                          | `.bb-base-checkbox` / `.bb-base-radio` / `.bb-base-switch` (the `--disabled` modifier survives)                                                                                                                                                                                                                                          |
-| `.bb-base-checkbox-container__icon` / `.bb-base-radio-container__icon` / `.bb-base-switch-container__icon` (+ `__icon-thumb`)     | `.bb-base-checkbox-icon` / `.bb-base-radio-icon` / `.bb-base-switch-icon` (+ `.bb-base-switch-icon__thumb`)                                                                                                                                                                                                                              |
-| `.bb-cr-container*` — the shared checkbox/radio/switch group tree (root, `--vertical`, `__container`, `-option`, `-option__text`) | split into per-control blocks: `.bb-base-checkbox-group*` / `.bb-base-radio-group*` / `.bb-base-switch-group*`, same suffixes (`--warnings`, `__loading-container`, `__no-data-container`, `-option--selected` are new). **`BbRating` no longer shares the block** — use `.bb-base-rating__inner-container` / `.bb-base-rating__option`. |
+| v2                                                                                                                                                                              | v3                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.bb-common-input-inner-container` (+ `--clearable`, `__prefix`, `__suffix`, `__prepend-icon`, `__append-icon`)                                                                 | `.bb-field-input` (+ the same suffixes) — modifiers `--active --compact --disabled --errors --loading --readonly --clearable --warnings`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `.bb-common-input-outer-container`                                                                                                                                              | merged away — the v2 outer/inner pair is one `.bb-field-input`, whose inner span is `.bb-field-input__box`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `.bb-base-input-container` (the field frame: root, `__label`, `__label-text`, `__description`, `__control`, `__hint-*`, `__error*`, `__warning*` and every `--` state modifier) | `.bb-field` (+ the same suffixes), renamed in the v3 flatten (Queue 30), **except `__control`, which is now `__input-wrapper`** (Queue 45; no `bb-field__control` is emitted)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `.bb-base-input-outer-container` (+ `--compact`)                                                                                                                                | merged into `.bb-field` (+ `--compact`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `.bb-base-input-container__input` (+ `--left --center --right`)                                                                                                                 | `.bb-field__input-wrapper` (+ the same modifiers)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `.bb-base-input-container--horizontal` / `--vertical` / `--reverse` (on the root)                                                                                               | `.bb-field__layout--horizontal` / `--vertical` / `--reverse`, plus one `--<layout>` keyword modifier (`--auto --ratio --label-fill --input-fill`; `--horizontal` names every side-by-side layout) — v3 inserts an inner `__layout` element and the orientation modifiers moved onto it; the root keeps only state modifiers (`--disabled --errors --warnings --loading --readonly --compact --floating-label --inside-label` …)                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `.bb-base-input-container--label-mode-floating`                                                                                                                                 | `.bb-field--floating-label`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `.bb-base-input-container__errors-outer`                                                                                                                                        | `.bb-field__errors-wrap`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `.bb-base-input-container__hint-container`                                                                                                                                      | `.bb-field__hint-wrap`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `.base-btn`, `.base-btn--block`, …                                                                                                                                              | `.bb-base-button*`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `.bb-base-checkbox-container` / `.bb-base-radio-container` / `.bb-base-switch-container`                                                                                        | removed — the v3 flatten folds the toggle's wrapper away; style the glyph `.bb-base-checkbox-icon` / `.bb-base-radio-icon` / `.bb-base-switch-icon` and its `--*` modifiers (or `pt:icon:<state>`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `.bb-base-checkbox-container__icon` / `.bb-base-radio-container__icon` / `.bb-base-switch-container__icon` (+ `__icon-thumb`)                                                   | `.bb-base-checkbox-icon` / `.bb-base-radio-icon` / `.bb-base-switch-icon` (+ `.bb-base-switch-icon__thumb`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `.bb-cr-container*` — the shared checkbox/radio/switch group tree (root, `--vertical`, `__container`, `-option`, `-option__text`)                                               | split into per-control blocks: root `.bb-{checkbox,radio,switch}-group__list` (+ `--horizontal --vertical --vertical-stretch --tiles --errors --warnings`, one per `list-layout`), `__loading` / `__empty` (`__container` merged into `__list`, which is the `pt:list` node), rows `.bb-…-group-item` (+ `__label`, the v2 `__text`; `--selected --description --focused --focus-visible --disabled`, one `--<item-layout>` and `--reverse`; `__description` is new; the glyph is itself the row's input cell, with no wrapper, styled with `pt:icon` — `--disabled` is emitted and unstyled, a hook). **⚠ silent**: v2 `--vertical` rows spanned the list; v3 `list-layout="vertical"` rows keep their own width — `vertical-stretch` is the v2 look. **`BbRating` no longer shares the block** — use `.bb-rating__options` / `.bb-rating__item`. |
+
+**Form controls — the field layers folded into each component**
+
+Each control's private base layer is folded into the public component
+(v3 flatten, Queue 30): its classes take the public block, and the box row
+it used to put its own name on is the shared `.bb-field-input`. Rows are
+added per control; a control not listed kept its v2 classes.
+
+| v2                                                                                                                                                                                                                                                                                                                           | v3                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.bb-base-text-input` (on the box row, + `--compact --disabled --errors --has-value --loading --readonly`)                                                                                                                                                                                                                   | removed — target `.bb-text-input .bb-field-input` and its `--compact --disabled --errors --loading --readonly` modifiers; `hasValue` is `.bb-field--has-value` on the root                                                                                                                                                                                                                                                                                                |
+| `.bb-base-text-input__input`                                                                                                                                                                                                                                                                                                 | `.bb-text-input__input`                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `.bb-base-select` (on the box row, + `--shown --disabled --readonly`)                                                                                                                                                                                                                                                        | `.bb-select__field` (+ the same modifiers); v2's `--errors --loading --compact` are the box row's `.bb-field-input--*` modifiers                                                                                                                                                                                                                                                                                                                                          |
+| `.bb-base-select__max-reached`                                                                                                                                                                                                                                                                                               | `.bb-select__max-reached`                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `.bb-base-select__activator`, `__value`, `__chips-row`, `__chip`, `__placeholder`                                                                                                                                                                                                                                            | `.bb-select__activator`, `__value`, `__chips-row`, `__chip`, `__placeholder` — same suffixes on the public block                                                                                                                                                                                                                                                                                                                                                          |
+| `.bb-base-rating` (+ `--disabled --errors --has-value --readonly`)                                                                                                                                                                                                                                                           | `.bb-rating__stars` (+ the same modifiers; `--warnings`, `--forced-clear` are new) — the `--size` / `--space` tokens are declared here                                                                                                                                                                                                                                                                                                                                    |
+| `.bb-base-rating__inner-container`                                                                                                                                                                                                                                                                                           | `.bb-rating__options`                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `.bb-base-rating__option`, `.bb-base-rating__label-text`                                                                                                                                                                                                                                                                     | `.bb-rating__item`, `.bb-rating__label-text` (`--highlighted` → `--filled` / `--empty`, see components/bb-rating.md)                                                                                                                                                                                                                                                                                                                                                      |
+| `.bb-base-slider` (+ `--disabled --errors --readonly`)                                                                                                                                                                                                                                                                       | `.bb-slider__body` (+ the same modifiers; `--compact`, `--warnings` are new) — the slider tokens (`--thumb`, `--track`, `--accent`, and the box's field look locals `--bg`, `--bw`, `--border-color`, `--border-focus`, `--elev`, `--ring-size`, `--px`, `--py`; `--shell-*` up to beta.33) are declared here                                                                                                                                                             |
+| `.bb-base-slider__slider-container`, `__ticks-container`, `__tick`, `__track-container`, `__track-fill`, `__track-background`, `__thumb-container`, `__thumb` (+ `--lower --higher --focused`)                                                                                                                               | `.bb-slider__box` (was `__slider-container`), `__ticks` (was `__ticks-container`), `__tick` (+ new `--in-range`), `__track` (the rail itself: was `__track-container` + the grey `__track-fill`, now one node), `__bar` (the coloured bar, was `__track-background`; BbProgress's word), `__thumb-container`, `__thumb` (+ the same modifiers). Prefer the `pt` parts of the same names: `box`, `track`, `bar`, `ticks`, `tick`, `thumb`                                  |
+| `.bb-base-textarea` (on the box row, + `--disabled --errors --loading --readonly`)                                                                                                                                                                                                                                           | `.bb-textarea__field` (the box row; tokens `--min-height --inner-h --floating-py`) — state modifiers are `.bb-field-input--disabled --errors --loading --readonly` on the same node                                                                                                                                                                                                                                                                                       |
+| `.bb-base-textarea--auto-grow`                                                                                                                                                                                                                                                                                               | `.bb-textarea__field--auto-grow`                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `.bb-base-textarea__input`                                                                                                                                                                                                                                                                                                   | `.bb-textarea__input`                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `.bb-base-number-input` (on the box row, + `--compact --disabled --errors --loading --readonly`)                                                                                                                                                                                                                             | removed — target `.bb-number-input .bb-field-input` and its `--compact --disabled --errors --loading --readonly` modifiers                                                                                                                                                                                                                                                                                                                                                |
+| `.bb-base-number-input__input`                                                                                                                                                                                                                                                                                               | `.bb-number-input__input`                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `.bb-base-tag` (on the box row, + `--disabled --errors --loading --readonly`)                                                                                                                                                                                                                                                | `.bb-tag__field` (the box row) — state modifiers are `.bb-field-input--disabled --errors --loading --readonly` on the same node                                                                                                                                                                                                                                                                                                                                           |
+| `.bb-base-tag--active` / `--compact`                                                                                                                                                                                                                                                                                         | `.bb-tag__field--active` / `.bb-tag__field--compact`                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `.bb-base-tag__input-container` / `__text-input`                                                                                                                                                                                                                                                                             | `.bb-tag__input-container` / `.bb-tag__input`                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `.bb-base-tag__selected--focused`                                                                                                                                                                                                                                                                                            | removed (had no rules in v2) — the highlighted chip is `.bb-tag__badge.bb-badge--highlighted`, the comma item `.bb-tag__comma--highlighted` (prefer `pt:badge:highlighted` / `pt:comma:highlighted`)                                                                                                                                                                                                                                                                      |
+| `.bb-base-color-input` (on the box row, + `--active --compact --disabled --errors --loading --readonly`)                                                                                                                                                                                                                     | `.bb-color-input__field`; the modifiers are the box row's `.bb-field-input--compact --disabled --errors --loading --readonly`; `--active` (palette open) has no class — the indicator carries `aria-expanded="true"`                                                                                                                                                                                                                                                      |
+| `.bb-base-color-input__input` / `__indicator`                                                                                                                                                                                                                                                                                | `.bb-color-input__input` / `.bb-color-input__indicator`                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `.bb-base-date-picker-input` (on the box row, + `--active --compact --disabled --errors --loading --readonly --range`)                                                                                                                                                                                                       | `.bb-date-picker-input__field` (+ `--range`); v2's `--active --compact --disabled --errors --loading --readonly` are the box row's `.bb-field-input--*` modifiers                                                                                                                                                                                                                                                                                                         |
+| `.bb-base-date-picker-input__accessible-description`                                                                                                                                                                                                                                                                         | `.bb-date-picker-input__accessible-description`                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `.bb-base-time-picker-input` (on the box row, + `--range` and the state modifiers)                                                                                                                                                                                                                                           | `.bb-time-picker-input__field` (+ `--range`); the state modifiers are the box row's `.bb-field-input--*`                                                                                                                                                                                                                                                                                                                                                                  |
+| `.bb-base-time-picker-input__*`, `.bb-base-time-picker-input-offcanvas`                                                                                                                                                                                                                                                      | `.bb-time-picker-input__*`, `.bb-time-picker-input__sheet` — same suffixes                                                                                                                                                                                                                                                                                                                                                                                                |
+| `.bb-base-time-selector*` (the time columns, shared by the time input and picker)                                                                                                                                                                                                                                            | `.bb-time-selector*` (CommonTimeSelector) — same suffixes                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `.bb-base-date-picker` (the calendar grid)                                                                                                                                                                                                                                                                                   | `.bb-calendar__grid` (+ `--unit-month` / `--unit-year`, new in v3)                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `.bb-base-date-picker__body`, `__button-menu`, `__content`, `__controls`, `__date` (+ `--current --disabled --first --highlighted --last --middle --selected --today`), `__date-button`, `__days-selector` (+ `--hidden`), `__header-cell`, `__header-container`, `__month`, `__month-selector`, `__week`, `__year-selector` | `.bb-calendar__*`, same element and modifier names — except `--current` (now `--highlighted`) and `--highlighted` (now its inverse, `--outside`); see the day-cell row below                                                                                                                                                                                                                                                                                              |
+| `.content` / `.content__btn` (+ `--selected`) — the month / year panels                                                                                                                                                                                                                                                      | `.bb-calendar__menu-grid` / `.bb-calendar__menu-btn` (+ `--selected`); the rows between them are `.bb-calendar__menu-row`                                                                                                                                                                                                                                                                                                                                                 |
+| `.bb-base-checkbox` / `.bb-base-radio` / `.bb-base-switch` (+ `--disabled --errors --indeterminate --readonly`)                                                                                                                                                                                                              | removed — BbCheckbox / BbRadio / BbSwitch render the native input and the glyph with no wrapper; the glyph `.bb-base-{checkbox,radio,switch}-icon` carries `--checked --disabled --errors --warnings --focused --focus-visible --indeterminate --readonly`; in a group row the glyph is itself the row's input cell (no wrapper — beta ≤ 35 had `.bb-{…}-group-item__input-wrapper`), styled with `pt:icon`; in BbTable the span is `.bb-table-check` / `.bb-table-radio` |
+| `.bb-base-checkbox-group` / `.bb-base-radio-group` / `.bb-base-switch-group`                                                                                                                                                                                                                                                 | `.bb-checkbox-group__list` / `.bb-radio-group__list` / `.bb-switch-group__list`                                                                                                                                                                                                                                                                                                                                                                                           |
+
+The date input's built-in strings moved with it: the `Locale` type's
+`baseDatePickerInput` namespace is `datePickerInput` (v3's new time input
+uses `timePickerInput`). Only code that reads the `Locale` type by key is
+affected; the dictionaries themselves ship with the library.
 
 **Dialogs, off-canvas, popovers**
 
@@ -866,45 +1149,66 @@ nobody emits matches nothing and throws nothing.
 **Tabs** — the whole tree was renamed, and v2's block name was `bb-tab`, not
 `bb-tabs`, so nothing of a v2 tab theme survives untouched:
 
-| v2                                               | v3                                                                                                                                                                                                                                           |
-| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.bb-tab`                                        | `.bb-tabs`                                                                                                                                                                                                                                   |
-| `.bb-tab--vertical` / `--horizontal`             | `.bb-tabs--vertical` / `--horizontal` (+ `.bb-tabs-list--vertical` / `--horizontal` on the strip)                                                                                                                                            |
-| `.bb-tab__label-boundary`                        | `.bb-tabs-list`                                                                                                                                                                                                                              |
-| `.bb-tab__label-container` (+ `--no-transition`) | `.bb-tabs-list__tablist` (+ `--no-transition`) — the sliding active pill is still this element's `::before`, so a v2 `.bb-tab__label-boundary .bb-tab__label-container:before` rule becomes the single-class `.bb-tabs-list__tablist:before` |
-| `.bb-tab__btn` (+ `--active`)                    | `.bb-tabs__trigger` (+ `--active`), with new inner `.bb-tabs__trigger-content` / `.bb-tabs__trigger-label`                                                                                                                                   |
-| `.bb-tab__pane` (+ `--shown`)                    | `.bb-tabs__pane` (+ `--shown`)                                                                                                                                                                                                               |
-| `.bb-tab__panes-container`                       | `.bb-tabs-panes`                                                                                                                                                                                                                             |
+| v2                                               | v3                                                                                                                                                                                                                                                                            |
+| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.bb-tab`                                        | `.bb-tabs`                                                                                                                                                                                                                                                                    |
+| `.bb-tab--vertical` / `--horizontal`             | `.bb-tabs--vertical` / `--horizontal` (+ `.bb-tabs-list--vertical` / `--horizontal` on the strip)                                                                                                                                                                             |
+| `.bb-tab__label-boundary`                        | `.bb-tabs-list`                                                                                                                                                                                                                                                               |
+| `.bb-tab__label-container` (+ `--no-transition`) | `.bb-tabs-list__list` (+ `--no-transition`) — the sliding active pill is no longer its `::before` but its first child, `.bb-tabs-list__indicator` (`pt:indicator`), so a v2 `.bb-tab__label-boundary .bb-tab__label-container:before` rule becomes `.bb-tabs-list__indicator` |
+| `.bb-tab__btn` (+ `--active`)                    | `.bb-tabs-list__item` (+ `--active`), with new inner `.bb-tabs__trigger-content` / `.bb-tabs__trigger-label`                                                                                                                                                                  |
+| `.bb-tab__pane` (+ `--shown`)                    | `.bb-tabs__panel` (+ `--shown`)                                                                                                                                                                                                                                               |
+| `.bb-tab__panes-container`                       | `.bb-tabs-panels`                                                                                                                                                                                                                                                             |
 
 v2 had no full-width tab strip, so apps hand-rolled one (commonly a
 `bb-tabs--full-width` class). v3 ships it: `<BbTabs block>` sets
 `.bb-tabs--block` / `.bb-tabs-list--block` and gives the triggers equal widths.
 Delete the hand-rolled modifier rather than porting it.
 
+**BbTable** — no class was renamed, but the markup under `.bb-table` is no
+longer a `<table>`: it is a CSS grid of `<div>`s carrying ARIA roles. Every
+**element** selector on it (`table`, `thead`, `tbody`, `tfoot`, `caption`,
+`tr`, `th`, `td`, `colgroup`/`col`) matches nothing in v3 — silently. The
+classes all survive; four containers and the roles are the translation:
+
+| v2 element                            | v3 selector                                                                                  |
+| ------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `table` / `thead` / `tbody` / `tfoot` | `.bb-table__table` / `.bb-table__head` / `.bb-table__body` / `.bb-table__foot`               |
+| `caption`                             | `.bb-table__caption`                                                                         |
+| `tr` / `th` / `td`                    | `[role=row]` / `[role=columnheader]` / `[role=cell]` (or the `.bb-table-*` row/cell classes) |
+| `colgroup` / `col`                    | gone — `columns[].width`                                                                     |
+
+Full table, the `.table-flush` idiom rewrite, the `#thead`/`#tbody`/`#tfoot`
+markup contract and the layout drift that comes with the substrate:
+[bb-table.md](./components/bb-table.md#the-table-is-a-css-grid-not-a-table-v3-beta-2026-08-26).
+
 **Everything else**
 
-| v2                                                                                                                                                                                                                                            | v3                                                                                                                                                                                                                            |
-| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.bb-chip*`                                                                                                                                                                                                                                   | `.bb-badge*` (component replaced)                                                                                                                                                                                             |
-| `.bb-badge*` used as a floating count/dot (`--dot --floating --positioned --left --bottom --empty`, `__wrapper`, `__content-container`)                                                                                                       | `.bb-indicator*` (component renamed)                                                                                                                                                                                          |
-| `.bb-color-palette__*` (canvas, canvas-thumb, canvas-wrap, controls, eyedropper, preview, preview--alpha, preview-wrap, slider-thumb, slider-track, slider-wrap, slider-wrap--alpha, sliders, swatch, swatch--active, swatch-group, swatches) | `.bb-base-color-palette__*` — 1:1 on every one                                                                                                                                                                                |
-| `.bb-toast--top-start` / `--top` / `--top-end` / `--bottom-start` / `--bottom` / `--bottom-end`                                                                                                                                               | `.bb-toast--top-left` / `--top-center` / `--top-right` / `--bottom-left` / `--bottom-center` / `--bottom-right` (matching the `position` prop's corner set)                                                                   |
-| `.bb-toast-message__icon-container`                                                                                                                                                                                                           | **removed** — style `.bb-toast-message__icon` directly                                                                                                                                                                        |
-| `.bb-tree--open`                                                                                                                                                                                                                              | `.bb-tree__node--expanded`                                                                                                                                                                                                    |
-| `.bb-tree-row`                                                                                                                                                                                                                                | `.bb-tree__row`                                                                                                                                                                                                               |
-| `.bb-tree-main-content`                                                                                                                                                                                                                       | `.bb-tree__content`                                                                                                                                                                                                           |
-| `.bb-dropdown-button__dropdown-chevron`                                                                                                                                                                                                       | `.bb-dropdown-button__chevron`                                                                                                                                                                                                |
-| `.bb-dropdown-button--loading` / `__content` / `__icon` / `__prepend-icon` / `__append-icon`                                                                                                                                                  | **removed** — the split button delegates to `BbButton`'s internals; target `.bb-button__*` inside it                                                                                                                          |
-| `.bb-dropdown__wrapper`                                                                                                                                                                                                                       | **removed** — the extra wrapper element is gone                                                                                                                                                                               |
-| `.bb-select-popover__search-spinner`                                                                                                                                                                                                          | `.bb-select-popover__search-icon` (one element, spinner state included)                                                                                                                                                       |
-| `.bb-base-date-picker__header` (the tinted banner holding the month/year controls)                                                                                                                                                            | `.bb-base-date-picker__controls` (+ the inner `__nav-center`) — the banner is gone; the controls sit on the calendar surface. `__header-container` and `__header-cell` are unrelated and unchanged: they are the weekday row. |
-| `.bb-base-date-picker__control` / `__year-control`                                                                                                                                                                                            | `.bb-base-date-picker__nav-btn`                                                                                                                                                                                               |
-| `.bb-base-date-picker__month-button` / `__year-button`                                                                                                                                                                                        | `.bb-base-date-picker__heading-btn` (+ `--active`)                                                                                                                                                                            |
-| `.bb-base-date-picker__weekday`                                                                                                                                                                                                               | `.bb-base-date-picker__header-cell`                                                                                                                                                                                           |
-| `.bb-base-date-picker__monthday`                                                                                                                                                                                                              | `.bb-base-date-picker__date` (+ the inner `__date-button`)                                                                                                                                                                    |
-| `.bb-base-date-picker__year-container`                                                                                                                                                                                                        | `.bb-base-date-picker__year-selector`                                                                                                                                                                                         |
-| `.bb-base-date-picker__header--hidden`, `__selected-day-label`                                                                                                                                                                                | **removed**                                                                                                                                                                                                                   |
-| `.bb-commabox-item--has-comma`                                                                                                                                                                                                                | the select's comma list renders `.bb-base-select__comma-item` (`.bb-commabox-item` itself survives; `--has-comma` and `.bb-chipsbox-item--focused` do not)                                                                    |
+| v2                                                                                                                                      | v3                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.bb-chip*`                                                                                                                             | `.bb-badge*` (component replaced)                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `.bb-badge*` used as a floating count/dot (`--dot --floating --positioned --left --bottom --empty`, `__wrapper`, `__content-container`) | `.bb-indicator*` (component renamed)                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `.bb-color-palette` (the picker root: canvas, sliders, swatches)                                                                        | `.bb-color-palette__panel` (the painted box: the popover's bubble, or the box inside the sheet; `pt:panel` on desktop — on a phone `pt:panel` is the sheet) — the element classes `.bb-color-palette__*` (canvas, canvas-thumb, canvas-wrap, controls, eyedropper, preview, preview--alpha, preview-wrap, slider-thumb, slider-track, slider-wrap, slider-wrap--alpha, sliders, swatch, swatch--active, swatch-group, swatches) keep their v2 names |
+| `.bb-toast--top-start` / `--top` / `--top-end` / `--bottom-start` / `--bottom` / `--bottom-end`                                         | `.bb-toast--top-left` / `--top-center` / `--top-right` / `--bottom-left` / `--bottom-center` / `--bottom-right` (matching the `position` prop's corner set)                                                                                                                                                                                                                                                                                         |
+| `.bb-toast-message__icon-container`                                                                                                     | **removed** — style `.bb-toast__icon` directly                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `.bb-tree--open`                                                                                                                        | `.bb-tree__item--expanded`                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `.bb-tree-row`                                                                                                                          | `.bb-tree__row`                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `.bb-tree-main-content`                                                                                                                 | `.bb-tree__content`                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `.bb-progress-bar` (the filled bar inside `.bb-progress`)                                                                               | `.bb-progress__bar`                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `.bb-dropdown-button__dropdown-chevron`                                                                                                 | `.bb-dropdown-button__chevron`                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `.bb-dropdown-button--loading` / `__content` / `__icon` / `__prepend-icon` / `__append-icon`                                            | **removed** — the split button delegates to `BbButton`'s internals; target `.bb-button__*` inside it                                                                                                                                                                                                                                                                                                                                                |
+| `.bb-dropdown__wrapper`                                                                                                                 | **removed** — the extra wrapper element is gone                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `.bb-select-popover__search-spinner`                                                                                                    | `.bb-select-popover__search-icon` (one element, spinner state included)                                                                                                                                                                                                                                                                                                                                                                             |
+| `.bb-base-date-picker__header` (the tinted banner holding the month/year controls)                                                      | `.bb-calendar__header` (+ the inner `__nav-center`) — the banner is gone; the controls sit on the calendar surface. `__header-container` and `__header-cell` are unrelated and unchanged: they are the weekday row.                                                                                                                                                                                                                                 |
+| `.bb-base-date-picker__control` / `__year-control`                                                                                      | `.bb-calendar__arrow`                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `.bb-base-date-picker__month-button` / `__year-button`                                                                                  | `.bb-calendar__heading-btn` (+ `--active`)                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `.bb-base-date-picker__weekday`                                                                                                         | `.bb-calendar__cell-column-header`                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `.bb-base-date-picker__monthday`                                                                                                        | `.bb-calendar__day` (+ the inner `__date-button`)                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `.bb-base-date-picker__year-container`                                                                                                  | `.bb-calendar__year-selector`                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `.bb-base-date-picker__header--hidden`, `__selected-day-label`                                                                          | **removed**                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `.bb-commabox-item--has-comma`                                                                                                          | the select's comma list renders `.bb-select__comma`; BbTag's entry is `.bb-tag__comma` (was `.bb-commabox-item`); `--has-comma` is gone, and the chip cursor `.bb-chipsbox-item--focused` is `.bb-badge--highlighted`                                                                                                                                                                                                                               |
+| `.sr-only` — the visually-hidden helper every component uses for accessible names and status text (it shared Tailwind's class name)     | `.bb-sr-only`. Only a selector reaching **into** a component (`.bb-table .sr-only`) breaks; your own Tailwind `sr-only` in your markup is untouched — which is why this one is deliberately **not** in the §8 grep: a hit there would be your code, not ours                                                                                                                                                                                        |
+| `.bb-base-date-picker__date--current` / `__date--highlighted` (the cursor day / a day of the displayed month)                           | `.bb-calendar__day--highlighted` is now the cursor day; the previous / next month's days carry `.bb-calendar__day--outside` instead — select the displayed month as `.bb-calendar__day:not(.bb-calendar__day--outside)`                                                                                                                                                                                                                             |
+| `#day` / `#append:day` slot scope `highlighted` (a day of the displayed month)                                                          | `outside`, inverted — `true` for a day of the previous / next month: `highlighted` → `!outside`                                                                                                                                                                                                                                                                                                                                                     |
 
 The date **input**'s own field tree (`.bb-base-date-picker-input__field`,
 `__fields`, `__placeholder`, `__separator`, `__calendar-btn`) moved to a shared
@@ -913,12 +1217,16 @@ The date **input**'s own field tree (`.bb-base-date-picker-input__field`,
 
 **Removed with no counterpart:** `.bb-base-dialog--compact`,
 `.bb-offcanvas--compact`, `.bb-base-textarea--compact` (compact now lives on
-`.common-input-wrapper--compact`), `.bb-base-select--active` / `--compact` /
-`__inner-wrapper` / `__input-container` (the select activator was rebuilt —
-nearest hooks are `.bb-base-select__activator`, `__value`, `__display-value`;
-`--shown` survives), `.bb-base-rating__option--highlighted` (v3 uses
-`--filled` / `--empty`), `.bb-progress--horizontal` (`.bb-progress` /
-`.bb-progress-bar` are the blocks), `.bb-ratio` (component removed).
+`.bb-field-input--compact`), `.bb-base-select--active` / `--compact` /
+`__inner-wrapper` / `__input-container` / `__text-input` (the select activator
+was rebuilt — nearest hooks are `.bb-select__activator`, `__value`,
+`__display-value`; `--shown` survives as `.bb-select__field--shown`. `__text-input` was v2's combobox typing
+field inside the activator; v3's activator is a `type="button"` overlay with no
+typable field, and typing moved into the panel's
+`.bb-select-popover__input` — restyle that instead, knowing it now sits
+in the popover, not the field), `.bb-base-rating__option--highlighted` (v3 uses
+`--filled` / `--empty`), `.bb-progress--horizontal` (`.bb-progress` and its
+`.bb-progress__bar` are the classes), `.bb-ratio` (component removed).
 
 ### 5.7 Renamed custom properties the library WRITES
 
@@ -928,23 +1236,27 @@ nested-table column alignment. They all dropped the `bb-` prefix, and every one
 of them is consumed through `var(name, fallback)`, so a v2 name silently
 resolves to the fallback instead of failing.
 
-| v2                                                    | v3                                                                         |
-| ----------------------------------------------------- | -------------------------------------------------------------------------- |
-| `--bb-table-{id}-track-{key}`                         | `--table-{id}-track-{key}`                                                 |
-| `--bb-table-offset-start` / `-end`                    | `--offset-start` / `--offset-end`                                          |
-| `--bb-table-offset-internal-start` / `-end`           | `--offset-internal-start` / `--offset-internal-end`                        |
-| `--bb-table-fill`                                     | `--fill`                                                                   |
-| `--bb-table-natural-width`                            | `--natural-width`                                                          |
-| `--bb-select-popover-width` (on `.bb-select-popover`) | `--w` — and the supported path is now the `width` prop, not a CSS override |
-| `--bb-icon-dimensions-w` (on `.bb-icon`)              | `--w`                                                                      |
-| `--bb-breadcrumbs-flex-basis` / `-flex-grow`          | `--flex-basis` / `--flex-grow`                                             |
-| `--bb-picker-preview-color`                           | `--picker-preview-color`                                                   |
+| v2                                                    | v3                                                                                        |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `--bb-table-{id}-track-{key}`                         | `--table-{id}-track-{key}`                                                                |
+| `--bb-table-offset-start` / `-end`                    | `--offset-start` / `--offset-end`                                                         |
+| `--bb-table-offset-internal-start` / `-end`           | `--offset-internal-start` / `--offset-internal-end`                                       |
+| `--bb-table-fill`                                     | **removed in 3.0.0** (briefly `--fill` in the betas; the grid substrate has no fill loop) |
+| `--bb-table-natural-width`                            | **removed in 3.0.0** (briefly `--natural-width` in the betas)                             |
+| `--bb-select-popover-width` (on `.bb-select-popover`) | `--w` — and the supported path is now the `width` prop, not a CSS override                |
+| `--bb-icon-dimensions-w` (on `.bb-icon`)              | `--w`                                                                                     |
+| `--bb-breadcrumbs-flex-basis` / `-flex-grow`          | `--flex-basis` / `--flex-grow`                                                            |
+| `--bb-picker-preview-color`                           | `--picker-preview-color`                                                                  |
 
 A regex matching the old shape (`/--bb-table-[\w-]+-track/`) matches nothing in
 v3. Search your app for `--bb-table-`, `--bb-select-popover-`,
 `--bb-icon-dimensions-`, `--bb-breadcrumbs-` and `--bb-picker-` — none of those
 names exist in v3 and all of them fail quietly. `--available-height`,
-`--inner-width` and `--overlay-min-height` were dropped outright.
+`--inner-width`, `--overlay-min-height`, `--bb-table-fill` and
+`--bb-table-natural-width` were dropped outright — the last two because
+`BbTable` is a CSS grid in 3.0.0 and the fixed-layout self-correction they fed
+no longer exists (see
+[bb-table.md](./components/bb-table.md#--fill-and---natural-width-are-removed-not-renamed)).
 
 If you re-published track variables by hand to align a deeply nested table,
 delete that code: `inherit-column-widths` takes a **table id**
@@ -962,7 +1274,11 @@ Nothing here fails to compile — these change what existing code does.
    (`BbSelect`, `BbSelectPopover`): re-clicking the selected option re-picks
    and closes; it used to emit `null` and empty the field. If your UX relied on
    click-to-clear, add `clearable` (or the `clear` slot callback). Multiple
-   mode still toggles.
+   mode still toggles. **`BbDropdown` single selectable groups** follow the
+   same rule since 3.0.0-beta.35: re-clicking the selected row keeps it (no
+   `item:unselected`, the row's `onClick` still runs, a sole top-level group
+   still closes). Put `clearable: true` on the group to get click-to-clear
+   back.
 3. **`enforce-coherence` prunes on mount.** A seeded-but-invalid model value is
    now cleared on the first load, not on the next change. If "my value clears
    on load" appears after upgrading, your provider isn't resolving the current
@@ -986,15 +1302,32 @@ Nothing here fails to compile — these change what existing code does.
    a controlled model (`v-model:sort`), so nothing reorders on its own; the
    button appears and emits. Strip or rename the field at the `BbTable`
    boundary. The compile-time half of the same collision is in §5.5b.
-7. **Dynamic slot names are normalized** via
-   `slotKey(key) = key.split(/\W+/g).join('_').toLowerCase()` in
-   `BbBreadcrumbs`, `BbTree`, `BbTabs`, and the date-picker day slots.
-   `#Order History` → `#order_history`. **⚠ silent**: a stale raw-key slot
-   simply renders fallback content. `BbTabs` goes further: the label slot is
-   renamed (`#label-<key>` → `#label:<slotKey>`), the URL query value is the
-   normalized slug (`?tab=In%20Review` → `?tab=in_review` — update deep links
-   and server code), and tab/panel DOM ids are normalized. Only `v-model` /
-   item `key` stay raw.
+7. **Dynamic slot names are kebab-case** via `slotKey(key)` (lodash
+   `kebabCase` rules: words split at separators, camelCase humps and digits,
+   lowercased, joined by `-`) in `BbTable`, `BbDropdown`, `BbBreadcrumbs`,
+   `BbTree`, `BbTabs` and the date-picker day slots. v2's BbTable and
+   BbDropdown folded non-word runs to `_` and squashed camelCase, so:
+   `#order_history` → `#order-history`, `#placedat` (key `placedAt`) →
+   `#placed-at`, `#address2` → `#address-2`. The day slots are named by the
+   day's date as written (`#2024-03-15`), where v2 used its ISO timestamp.
+   **⚠ silent**: a stale slot simply renders fallback content — run
+   `npx bitboss-ui check`: where the keys are in the same file it names every
+   rename (and `--fix` rewrites them); elsewhere it warns on squashed-looking
+   names (`#createdat`). For keys with accents or other scripts, write
+   `#[slotKey('…')]`. Three fixed slots were renamed as well, and `check --fix`
+   rewrites them: `#no-data` → `#empty` (with the `noDataText` prop →
+   `emptyText`), `#prepend-outer` / `#append-outer` → `#prepend:outer` /
+   `#append:outer`, and BbTree's `#<value>-children` → `#<value>:children`.
+   In development the components also say so in the console, once per name
+   (`` `#no-data` was renamed to `#empty` on BbSelect (3.0.0-beta.41) ``), and
+   BbTable / BbTabs name a key's old spelling (`#createdat` → `#created-at`);
+   production builds carry none of it.
+   `BbTabs` goes further: the label slot is `#label:<key>` (v2 `#label-<key>`),
+   the URL query value is the kebab slug (`?tab=In%20Review` →
+   `?tab=in-review`; old `?tab=in_review` links from a v3 beta still land and
+   are rewritten in place — update deep links and server code, see the BbTabs
+   guide § URL values changed in 3.0.0-beta.41), and tab/panel DOM ids follow.
+   Only `v-model` / item `key` stay raw.
 8. **Dialogs, popovers, dropdowns and selects open as bottom sheets on mobile**
    by default (`adaptive`, default `true`). Set `adaptive: false` in the
    plugin, or per component, for v2-like floating behavior.
@@ -1013,6 +1346,172 @@ Nothing here fails to compile — these change what existing code does.
     branch's children are now `inert` (out of the Tab order). Tests or CSS
     keyed on the removed roles match nothing — see
     [bb-tree.md](./components/bb-tree.md).
+13. **`BbTable` is a CSS grid, not a `<table>`.** Column widths hold their
+    overflow threshold, wrap floor and frozen widths exactly, but leftover
+    space is shared equally between auto columns rather than proportionally
+    to content, and a few table-only tricks stop working (`max-width: 0` for
+    ellipsis collapses the cell). Copying rows into a spreadsheet pastes one
+    value per line, and a printed table no longer repeats its header on each
+    page. `#thead`/`#tbody`/`#tfoot` take `<div role="row">` rows, never
+    `<tr>`. Requires subgrid (Chrome/Edge 117, Firefox 71, Safari 16) — no
+    fallback. Full detail and the selector translation in
+    [bb-table.md](./components/bb-table.md#the-table-is-a-css-grid-not-a-table-v3-beta-2026-08-26).
+14. **Short selects open without a search field.** The select family
+    (`BbSelect` / `BbSelectPopover`) hides the search field under
+    `autoDisableWritingThreshold` (`6`) options by default: an unset
+    `disable-writing` means `'auto'`, and an **array** `items` with fewer
+    options than the threshold opens with no field — decided at open, held
+    while open. Provider `items` and a select that listens to `option:add`
+    keep the field; an explicit `disable-writing` (any value) still wins.
+    ⚠ silent: nothing fails, the field is just gone from five-option selects.
+    Set `autoDisableWritingThreshold: 0` in the plugin to keep every search
+    field, and delete any `:disable-writing="items.length < 6"` you wrote to
+    get this by hand.
+15. **A failed `BbForm` submit moves focus** (`bitboss-ui/validated`, since
+    3.0.0-beta.41): to the first invalid field that is on screen, in page
+    order, and the form emits `invalid` with `{ errors, values }`. It used to
+    leave focus where it was, usually on the submit button. If your
+    `@submit`-adjacent code focused the first error itself, delete it; if a
+    page moved focus somewhere else on failure (an error summary), do it in
+    `@invalid`: a handler that moves focus itself keeps it. See
+    `BbForm.guide.md` § A failed submit focuses the first invalid field.
+16. **`bitboss-ui/validated` needs vee-validate `>=4.10.0 <5`** (since
+    3.0.0-beta.41; it was `>=4.0.0`). `schema` needs 4.8 and
+    `keep-values-on-unmount` as a ref needs 4.10; on an older 4.x they
+    silently did nothing. vee-validate 5 is not tested yet. npm now reports
+    an older vee-validate at install time: upgrade it to the latest 4.x
+    (`npm i vee-validate@^4.15`). Apps that don't use `bitboss-ui/validated`
+    are not affected (the peer is optional).
+17. **A picker's activator is named by the label AND what it shows**
+    (`BbDatePicker`, `BbTimePicker`, `BbColorPalette`, since 3.0.0-beta.41):
+    the `label` used to become the activator's `aria-label`, which hid the
+    visible value ("Due date" for a button showing "12 Sep"). Now the
+    activator gets `aria-labelledby` = a hidden label span, then itself, so it
+    reads "Due date 12 Sep". The `activator` slot's `props` carry
+    `aria-labelledby` instead of `aria-label`: keep `v-bind="props"`; code
+    that read `props['aria-label']` reads the `label` you passed instead.
+    Tests that asserted the activator's `aria-label` should query by role and
+    name.
+18. **A validated field's path is its `name`** (`bitboss-ui/validated`,
+    since 3.0.0-beta.41). A field that has a `name` now validates, submits
+    and receives schema errors under it, read as a path: `address[city]` is
+    `address.city`, `users[0][name]` is `users.0.name`, `tags[]` is `tags`.
+    Before, a field without `vid` used its slugged label even when it had a
+    `name`, so **⚠ silent**: `@submit` keys, `useBbFormContext(id).values` /
+    `errors` and schema paths move from `fullname` to whatever `name` says.
+    Without a `name` nothing changes (the slugged label). A field with
+    neither a `label` nor a `name` throws "give the field a `label` or a
+    `name`". Messages name the field by `validation-label`, else its label,
+    else "This field", never the path. `npx bitboss-ui check` flags two
+    fields in one `<BbForm>` that land on the same path.
+19. **`useBbFormContext(id).errors` holds every message, as an array**
+    (`bitboss-ui/validated`, since 3.0.0-beta.41): `{ email: ['Taken.'] }`,
+    where it was `{ email: 'Taken.' }`. Read the first one as
+    `errors.email?.[0]`. It lists only fields the form knows (`fields`); a
+    server path with no field is in the new `unmatchedErrors` instead, never
+    in both, so `{ ...errors, ...unmatchedErrors }` is every error. **⚠
+    silent** in a template: `{{ errors.email }}` now prints the array. The
+    `invalid` event (new in this beta) carries the same array shape.
+20. **The built-in strings are English by default** (since 3.0.0-beta.41;
+    the default `locale` was `'it'`). Italian apps: set `locale: 'it'` in the
+    build plugin, `bitbossUi({ locale: 'it' })` or, in Nuxt,
+    `bitboss: { locale: 'it' }`. Without it, confirm buttons, empty and
+    loading text, close and clear labels, the select-all text and the date
+    pickers' field order (month first) and labels are English, and the bundle
+    carries only the `en` dictionary. Your own Italian copy (labels,
+    placeholders, titles) is not affected.
+21. **`bitboss-ui/validated` slot props are typed** (since 3.0.0-beta.41;
+    they were `any`). Every validated component's slots now have the same
+    prop types as its core twin, so `vue-tsc` rejects code that misused
+    them. Two real cases:
+    - `<button type="submit" @click="validate">` inside `<BbForm>`: the
+      click's `PointerEvent` is passed to `validate(opts?)` as its options
+      (TS2345). Write `@click="validate()"`, or let `type="submit"` submit
+      the form.
+    - `<template #default="{ isSubmitting, setFieldError }">`: `setFieldError`
+      is not a `BbForm` slot prop, so it was always `undefined` (TS2339). Use
+      the slot's `setErrors` instead, or drop the name.
+
+    Runtime behaviour does not change: only compile errors that were hidden
+    appear.
+
+22. **A `keyboard-navigation` `BbTable` is an ARIA grid** (since
+    3.0.0-beta.41). It was a `role="table"` whose rows took arrow keys, which
+    promised assistive tech nothing. Now the root is `role="grid"` (or
+    `role="treegrid"` when an `#expand` slot is present), the body cells are
+    `role="gridcell"`, and focus moves over CELLS (the APG data grid): the whole
+    table is one tab stop, ←/→ move between cells, Home/End go to the row's
+    ends, Ctrl+Home/End to the corners, ↑ from the first row reaches the header.
+    Enter/Space still activate the row (highlight + `click:row`). Links and
+    buttons inside cells leave the Tab order (Enter or F2 reaches them, Escape
+    comes back). A treegrid's rows take focus too (→ expands, ← collapses).
+    Selectable rows carry `aria-selected`. **⚠ silent** for CSS and tests:
+    `[role=cell]` no longer matches those tables' body cells — write
+    `:is([role=cell], [role=gridcell])` or use `.bb-table__cell`; a focus ring
+    styled on `.bb-table__row:focus-visible` now shows only on a treegrid (a
+    grid focuses cells: `.bb-table__cell:focus-visible`); tests that pressed
+    arrows on a row or asserted `getByRole('table')` / `document.activeElement`
+    = the row query `getByRole('grid')` and the focused cell. Tables without
+    `keyboard-navigation` are unchanged. See `BbTable.guide.md` § Keyboard
+    navigation and row events.
+23. **`setErrors` moves focus** (since 3.0.0-beta.41). A server's errors now
+    focus the first failing field on screen, as a failed client submit
+    already did, while focus is still the form's (inside it, or on the page
+    after a submit). A page that moved focus itself right after `setErrors`
+    keeps its own; pass `setErrors(map, { focus: false })` to opt out. See
+    `BbForm.guide.md` § A failed submit focuses the first invalid field.
+
+24. **`validateOn` is now `validation-mode`** (`bitboss-ui/validated`, since
+    3.0.0-beta.41). The array of events became one mode: `aggressive` (every
+    change), `balanced` (on leave, then every change while the field shows an
+    error), `lazy` (on leave only), `submit-only` or `submit-live`. The old
+    defaults (`['blur']`, `['inactive']`, a checkbox's or switch's
+    `['update:modelValue', 'change', 'blur']`) all behave as `balanced`, the new
+    default, so delete them; `['update:modelValue']` on a text field is
+    `validation-mode="aggressive"`. **⚠ silent**: a leftover `:validate-on`
+    falls through as an unknown attribute and does nothing. Set the mode once
+    on `<BbForm validation-mode="…">`, or app-wide with
+    `formControls: { validationMode }`; a field's own still wins. See
+    `ai/guides/validated-forms.md` § `validationMode`.
+
+25. **`v-for` rows follow your array; `removeField` runs after the render**
+    (`bitboss-ui/validated`, since 3.0.0-beta.41). A row keyed by id that
+    moved up after a delete used to show, submit and **write into your
+    `v-model`** the value of the row it replaced; now every row keeps its own
+    value and `@submit` gets exactly the rows on the page. `removeField(path)`
+    applies after the re-render: pass the row you deleted
+    (``form.removeField(`lines.${i}`)`` right after your `splice`, or later).
+    A path a field on the page still owns is left alone (it used to be
+    cleared). The old "index that fell off the end" call still works: that
+    path is unowned, so it goes. A `useFieldArray` workaround can go. See
+    `BbForm.guide.md` § Rows (`v-for`).
+
+26. **`bitboss-ui/validated` is retired** (since 3.0.0-beta.41). `BbForm`,
+    `useBbFormContext`, the form types and the form controls come from
+    `bitboss-ui`. `npx bitboss-ui check --fix` rewrites the imports in `.vue`
+    files (other files: change `'bitboss-ui/validated'` to `'bitboss-ui'`).
+    `useValidatedField` is gone: for a control of your own, use
+    `useBbFormField(formId, { name, validationLabel, rules })`.
+27. **Form controls join the `BbForm` they are inside** (since
+    3.0.0-beta.41), keyed by `name`, else their label: their values are
+    submitted, reset, count toward `dirty`, and are validated if they have
+    rules. **⚠ silent**: a plain control you had inside a form (a filter, a
+    "show advanced" switch) is now submitted too; give it `formless`. A form
+    control with neither `name` nor label inside a form throws (a
+    `BbDropzone` needs a `name`). Rows in a `v-for` need a per-row `:name`
+    (`check` reports `row-without-name`).
+28. **Outside a `BbForm` a form control is plain** (since 3.0.0-beta.41): a
+    `bitboss-ui/validated` field used to validate its `rules` on its own; now
+    rules run only inside a form. Wrap the fields in `<BbForm>`.
+29. **Nuxt `autoImport.validated` is removed** (since 3.0.0-beta.41):
+    `autoImport` already registers `BbForm`, `useBbFormContext` and
+    `useBbFormField`. Delete the option.
+30. **`ValidatedFieldProps` is renamed `FormFieldProps`** (since
+    3.0.0-beta.41): the form props (`rules`, `validationMode`,
+    `validationLabel`, `formless`) are part of each control's own props type
+    (`BbTextInputProps` has them), and `modelValue` is optional on the 16
+    form controls (inside a `BbForm` the form holds the value). Rename the
+    import; there is no wrapper component in between any more.
 
 ## 7. Class overrides → variants
 
@@ -1046,8 +1545,12 @@ screenshot; do not assume. Two consequences before you start:
   `variant="none"`; it is the one value that emits no variant class.
 - **A name that collides with a v3 built-in is the dangerous case, not the easy
   one.** If your app owned the look of `warning` / `destructive` / `secondary`,
-  converting to the same-named `variant` hands that look to the library.
-  Register the name as a custom variant (§4) to keep your CSS the only source.
+  converting to the same-named `variant` hands that look to the library — and
+  registering the name does **not** take it back: registration is type-only
+  (§4), the built-in skin stays in `styles.css`. Keep your look by winning the
+  cascade over the library's skin rules — author at block+modifier and load
+  after `styles.css` (§4 case 2 has the specificity detail) — or convert to a
+  non-colliding custom name.
 
 ### Finding them
 
@@ -1067,17 +1570,17 @@ rg -n 'class="bb-(button|badge|alert|toast-message|tooltip|indicator)\b' --type
 
 ### Correcting them
 
-| Found                                                                                               | Rewrite as                                                                                                                                                                                                                                                                                                 |
-| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `<BbButton class="bb-button--outline">`                                                             | `<BbButton variant="outline">` (same for `secondary`, `ghost`, `destructive`, `link`)                                                                                                                                                                                                                      |
-| `<BbAlert class="bb-alert--warning">` / v2 `theme="warning"`                                        | `<BbAlert variant="warning">`                                                                                                                                                                                                                                                                              |
-| `class="bb-badge bb-badge--secondary"` on a `<span>`                                                | `<BbBadge variant="secondary">` — the real component, not markup cosplay                                                                                                                                                                                                                                   |
-| `bb-toast-message--success` styling / v2 `theme` on toasts                                          | `toast({ variant: 'success' })`                                                                                                                                                                                                                                                                            |
-| `bb-tooltip--destructive`                                                                           | `<BbTooltip variant="destructive">` / `v-bb-tooltip="{ text, variant: 'destructive' }"`                                                                                                                                                                                                                    |
-| A **custom** modifier (`bb-button--brand`, any name not in section 4's table)                       | Register it: `buttonVariants: ['brand']` in the plugin, keep your CSS, pass `variant="brand"`.                                                                                                                                                                                                             |
-| A modifier your app **styled itself**, whatever its name                                            | Decide before you convert: accept v3's built-in look and delete your CSS, or register the name (§4) so your CSS stays the sole styling source. Converting silently does the former.                                                                                                                        |
-| A **state** modifier that stacks on a variant (`bb-button--pressed` alongside `bb-button--outline`) | Not convertible — `variant` holds exactly one value. Keep it a class and rename it out of `bb-*` (`app-button--pressed`). If it marks a real toggle, `v-model` on `BbButton` owns the state: it sets `aria-pressed` and emits `bb-button--active`, which the library deliberately leaves unstyled for you. |
-| A class that overrides _layout_, not look (widths, margins)                                         | Leave it — classes remain the right tool for layout; variants own _appearance semantics_.                                                                                                                                                                                                                  |
+| Found                                                                                               | Rewrite as                                                                                                                                                                                                                                                                                                                                                                      |
+| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<BbButton class="bb-button--outline">`                                                             | `<BbButton variant="outline">` (same for `secondary`, `ghost`, `destructive`, `link`)                                                                                                                                                                                                                                                                                           |
+| `<BbAlert class="bb-alert--warning">` / v2 `theme="warning"`                                        | `<BbAlert variant="warning">`                                                                                                                                                                                                                                                                                                                                                   |
+| `class="bb-badge bb-badge--secondary"` on a `<span>`                                                | `<BbBadge variant="secondary">` — the real component, not markup cosplay                                                                                                                                                                                                                                                                                                        |
+| `bb-toast-message--success` styling / v2 `theme` on toasts                                          | `toast({ variant: 'success', icon: 'lucide:circle-check' })`                                                                                                                                                                                                                                                                                                                    |
+| `bb-tooltip--destructive`                                                                           | `<BbTooltip variant="destructive">` / `v-bb-tooltip="{ text, variant: 'destructive' }"`                                                                                                                                                                                                                                                                                         |
+| A **custom** modifier (`bb-button--brand`, any name not in section 4's table)                       | Register it: `buttonVariants: ['brand']` in the plugin, keep your CSS, pass `variant="brand"`.                                                                                                                                                                                                                                                                                  |
+| A modifier your app **styled itself**, whatever its name                                            | Decide before you convert: accept v3's built-in look and delete your CSS, or keep yours. Keeping it is free for a non-built-in name (register it, done — there is no library rule to fight); for a built-in name registering only satisfies the type-check, and your rules must also win the cascade over the library's skin (§4, case 2). Converting silently does the former. |
+| A **state** modifier that stacks on a variant (`bb-button--pressed` alongside `bb-button--outline`) | Not convertible — `variant` holds exactly one value. Keep it a class and rename it out of `bb-*` (`app-button--pressed`). If it marks a real toggle, `v-model` on `BbButton` owns the state: it sets `aria-pressed` and emits `bb-button--active`, which the library deliberately leaves unstyled for you.                                                                      |
+| A class that overrides _layout_, not look (widths, margins)                                         | Leave it — classes remain the right tool for layout; variants own _appearance semantics_.                                                                                                                                                                                                                                                                                       |
 
 Rule of thumb: if the class name encodes a **meaning** (state, emphasis,
 severity), it should be a variant; if it encodes **geometry**, it stays a
@@ -1113,11 +1616,13 @@ rg -n 'disabled-while-loading|disabledWhileLoading'  # removed
 rg -n 'animate-x|animate-y|animateX|animateY'        # → disableAnimate*, now default-on
 rg -n 'thumb-translate|thumbTranslate'    # → disable-thumb-translate
 rg -n ':flip=|flip="'                     # → disable-flip on palette/select-popover
-rg -n 'hide-arrow|show-arrow|arrow-padding|hideArrow|showArrow|arrowPadding'  # removed off tooltips
+rg -n 'hide-arrow|show-arrow|arrow-padding|hideArrow|showArrow|arrowPadding'  # removed EVERYWHERE EXCEPT BbTooltip, which keeps hide-arrow + arrow-padding — hits on a tooltip are fine
 rg -n '<BbChip'                           # component removed → BbBadge clearable
 rg -n '<BbBadge'                          # v2 badges are v3 indicators — review each
 rg -n '<BbTab\b'                          # → BbTabs (\b so a tag name alone on its line still matches, and <BbTabs does not)
 rg -n '#label-'                           # BbTabs label slot → #label:<slotKey>
+rg -n '#no-data|#(prepend|append)-outer|#[a-z0-9_-]+-children'  # → #empty, #prepend:outer / #append:outer, #<value>:children (check --fix rewrites them)
+rg -n '#[a-z]+_[a-z0-9_]+|\?tab=[a-z0-9]+_'   # underscore slot names / tab slugs → kebab-case (`npx bitboss-ui check` names each)
 rg -n 'reverse' --type ts --type js       # BbRadio/BbSwitch default flipped
 rg -n 'timeout' --type vue                # BbTooltip → delay (BbAvatar keeps timeout); no ':' so static attrs match too
 rg -nU '<BbIcon[^>]*type='                # → icon=, and prefix your own icons `local:` (bb-icon.md). -U so a multi-line tag matches
@@ -1154,11 +1659,94 @@ rg -n 'setConfig'                         # only locale survives at runtime
 ```bash
 rg -n -- '--bb-(contrasting|hint|icon-color|primary-(base|dark)|panel-(light|dark|disabled)|border-(light|dark|hover)|text-(light|dark|secondary|tertiary)|input-(color|compact-|font-size|inner-h|prefix(-px)?([^-a-zA-Z0-9]|$))|label-(size|compact-spacing-y)|overlay-(color|opacity|z-index)|dialog-|button-|badge-|checkbox-w|radio-space|switch-|rating-size|base-rating-spacing|slider-|table-|select-option-|select-popover-|progress-track|toast-m|breadcrumbs-|picker-|icon-dimensions-)'  # every retired v2 token — v3 declares none of them (sections 3 and 5.7)
 rg -n -- '--bb-ring-opacity'              # survives by name; every value must now carry a % (section 3)
-rg -n 'bb-base-dialog|bb-tab__|bb-tab--|bb-cr-container|bb-common-input-outer-container|bb-common-input-inner-container|bb-base-input-container__input|bb-base-(checkbox|radio|switch)-container|bb-tree-row|bb-tree-main-content|bb-confirm__no|bb-dropdown__wrapper|bb-offcanvas__close|bb-popover__close|bb-ratio'  # renamed or deleted CSS blocks — nothing in v3 emits any of these (§5.6)
-rg -n 'bb-color-palette__'                # → .bb-base-color-palette__*; only __popover survives under the old name
+rg -n 'bb-base-dialog|bb-tab__|bb-tab--|bb-cr-container|bb-common-input-outer-container|bb-common-input-inner-container|common-input-wrapper|bb-base-input-container|bb-base-(checkbox|radio|switch)-container|bb-base-(checkbox|radio|switch)([^-]|$)|bb-base-(text-input|textarea|number-input|select|tag|rating|slider|color-input|color-palette|date-picker-input)|bb-base-date-picker|bb-base-time-picker-input|bb-base-time-selector|bb-base-(checkbox|radio|switch)-group|content__btn|bb-tree-row|bb-tree-main-content|bb-confirm__no|bb-dropdown__wrapper|bb-offcanvas__close|bb-popover__close|bb-ratio'  # renamed or deleted CSS blocks — nothing in v3 emits any of these (§5.6); every bb-base-* field block went in the flatten, only bb-base-button and the three -icon glyphs remain
+rg -n 'bb-color-palette([^_-]|$)'          # the v2 picker root → .bb-color-palette__panel; every .bb-color-palette__* element kept its v2 name
+rg -n 'bb-progress-bar'                  # the v2 progress bar → .bb-progress__bar (section 5.6)
+rg -n 'bb-date-picker__(grid|body|controls|nav-|heading-btn|content|days-selector|month|header-|week|date|button-menu|menu-|year-selector)'  # INERT since the calendar became BbCalendar (after 3.0.0-beta.28): the month grid, its panels and its day cells are `.bb-calendar__*` now — same element names, new block. Only `.bb-date-picker__panel` (+ `--sheet` / `--datetime`) and `.bb-date-picker` are still the picker's. Prefer `pt:day` / `pt:day-button` / `pt:header` / `pt:arrow` / `pt:month` / `pt:year` / `pt:cell-column-header` over any of these classes
+rg -n '\b(table|thead|tbody|tfoot|caption|colgroup|col|tr|th|td)\b' --type css --type vue  # element selectors aimed at BbTable (`.bb-table table`, `:deep(> table > tbody …)`, a global `td { padding }`, `.prose table`) — BbTable is a div grid in v3, none of them reach it; translate per bb-table.md § Selector translation. Expect noise from `<table>` markup of your own and from words in comments — judge each hit
 rg -n 'bb-tabs--'                         # v3's own modifiers are --horizontal --vertical --block --compact --disabled; anything else is app-minted, and a hand-rolled full-width tab list is now <BbTabs block>
+rg -n -- '--(text-color|bg-color|default-icon-color|surface-bg|surface-text|surface-border|main-color|muted-color)'  # INERT paint locals — renamed. Valid CSS that nothing reads, so the component silently reverts to its library default. Mapping table below
+rg -n -- '--pill-(bg|border|shadow)'      # INERT on .bb-tabs-list — the sliding pill is the INDICATOR now: --indicator-bg / --indicator-border / --indicator-shadow (renamed after 3.0.0-beta.28). A hand-built underline (transparent pill + inset shadow) is `variant="line"`
+rg -n -- '--color'                        # INERT everywhere — the name is retired. On a surface (.bb-badge / .bb-indicator / .bb-alert / .bb-toast__panel / .bb-avatar) it is now --fg; on a glyph (.bb-base-checkbox-icon / -radio-icon / -switch-icon, .bb-slider__body, .bb-rating__stars, .bb-error-icon, .bb-warning-icon) it is --accent
+rg -n -- '--(border-width|font-size|padding-inline|pad-[xy]|padding-[xy]|page-radius|ring|shell-[a-z-]+|padding)\s*:'  # INERT after 3.0.0-beta.33 — one short spelling per local: --bw --fs --px --py --page-r; the ring is --ring-color + --ring-size; BbSlider's --shell-* became --bg --bg-disabled --bw --border-color --border-focus --r --elev --ring-size --px (table below). A hit on YOUR OWN element (not a .bb-* root) is not affected
+rg -n -- '--radius\s*:' --type css --type vue  # a `--radius` set ON a component root (.bb-badge / .bb-indicator / .bb-base-switch-icon / .bb-toast__panel / .bb-slider__body) is INERT — the radius local is --r on all five, as on .bb-button. Your app's own --radius (shadcn's global) is not a hit: it never was a library token, and it is exactly why the local moved (a `--radius: var(--radius)` on the component was a self-reference — invalid, corners at 0)
 ```
 
+**Paint-local mapping.** Every surface component names its paint the same way
+now: `--bg` is the background and `--fg` is the text on it. These are the
+per-element overrides you set on the component's own class — not `--bb-*`
+theme tokens.
+
+| Component                                                                                                                                       | v2 / early-v3 local    | v3                                                                                                  |
+| ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------- |
+| `.bb-badge`, `.bb-indicator`                                                                                                                    | `--color`              | `--fg`                                                                                              |
+| `.bb-avatar`                                                                                                                                    | `--bg-color`           | `--bg`                                                                                              |
+| `.bb-avatar`                                                                                                                                    | `--text-color`         | `--fg`                                                                                              |
+| `.bb-avatar`                                                                                                                                    | `--default-icon-color` | removed — the glyph mixes `--fg`/`--bg`                                                             |
+| `.bb-alert`                                                                                                                                     | `--main-color`         | `--fg`                                                                                              |
+| `.bb-alert`                                                                                                                                     | `--muted-color`        | `--fg-muted`                                                                                        |
+| `.bb-toast-message` (now `.bb-toast__panel`)                                                                                                    | `--surface-bg`         | `--bg`                                                                                              |
+| `.bb-toast-message` (now `.bb-toast__panel`)                                                                                                    | `--surface-text`       | `--fg`                                                                                              |
+| `.bb-toast-message` (now `.bb-toast__panel`)                                                                                                    | `--surface-border`     | `--border-color`                                                                                    |
+| `.bb-base-switch-icon`                                                                                                                          | `--bg-color`           | `--bg`                                                                                              |
+| the glyph components                                                                                                                            | `--color`              | `--accent`                                                                                          |
+| `.bb-badge` (and its size modifiers), `.bb-indicator`, `.bb-base-switch-icon`, `.bb-toast-message` (now `.bb-toast__panel`), `.bb-slider__body` | `--radius`             | `--r` — the corner radius, named as on `.bb-button` and `.bb-base-checkbox-icon` (2026-09-17, beta) |
+| `.bb-tabs-list`                                                                                                                                 | `--pill-bg`            | `--indicator-bg`                                                                                    |
+| `.bb-tabs-list`                                                                                                                                 | `--pill-border`        | `--indicator-border`                                                                                |
+| `.bb-tabs-list`                                                                                                                                 | `--pill-shadow`        | `--indicator-shadow`                                                                                |
+
+**Why `--radius` went.** A component local shadows a custom property of the
+same name for the component's whole subtree, and `--radius` is the global
+radius in every shadcn theme. The natural alignment,
+`.bb-toast__panel { --radius: var(--radius) }`, is a self-reference on the
+declaring element — a cycle, so the value is invalid and the corners collapse
+to 0. Write `.bb-toast__panel { --r: var(--radius) }` instead; the two names
+differ, so the app's `--radius` resolves normally. The same trap holds for
+`--accent`, which keeps its name (it is a documented family name): map it from
+a differently named app variable, never from one of the same name. The ring
+left that list after 3.0.0-beta.33: its locals are `--ring-color` +
+`--ring-size`, so shadcn's `--ring` is safe to read
+(`.bb-button { --ring-color: var(--ring) }`).
+
+**Short spellings (after 3.0.0-beta.33).** Every component local now uses one
+short spelling per concept, the one `.bb-button` always used: `--bw`, `--fs`,
+`--px`, `--py`, `--r`. The long spellings below are inert. BbSlider's
+`--shell-*` set became the field look locals the input shells use.
+
+| Component                                                                | beta.33 and earlier                                                      | now                                                                                   |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| `.bb-badge`, `.bb-indicator`                                             | `--border-width`                                                         | `--bw`                                                                                |
+| `.bb-badge`, `.bb-indicator`                                             | `--font-size`                                                            | `--fs`                                                                                |
+| `.bb-badge`, `.bb-indicator`, `.bb-dropdown__*`, `.bb-select-popover__*` | `--padding-inline`                                                       | `--px`                                                                                |
+| BbCalendar / BbDatePicker panels                                         | `--pad-x` / `--pad-y`                                                    | `--px` / `--py`                                                                       |
+| CommonTimeSelector (time picker columns)                                 | `--pad-y`                                                                | `--py`                                                                                |
+| `.bb-table`                                                              | `--padding-x` / `--padding-y` (v2 too)                                   | `--px` / `--py`                                                                       |
+| `.bb-pagination`                                                         | `--page-radius`                                                          | `--page-r`                                                                            |
+| `.bb-button`, `.bb-badge`                                                | `--ring` (a colour)                                                      | `--ring-color`, plus `--ring-size`                                                    |
+| `.bb-slider__body`                                                       | `--shell-bg` / `--shell-disabled-bg`                                     | `--bg` / `--bg-disabled`                                                              |
+| `.bb-slider__body`                                                       | `--shell-border-width` / `--shell-border-color` / `--shell-focus-border` | `--bw` / `--border-color` / `--border-focus`                                          |
+| `.bb-slider__body`                                                       | `--shell-radius`                                                         | `--r` (shared with the rail)                                                          |
+| `.bb-slider__body`                                                       | `--shell-shadow` / `--shell-focus-ring`                                  | `--elev` + `--ring-size` / `--ring-color`                                             |
+| `.bb-slider__body`                                                       | `--shell-px` / `--padding`                                               | `--px` / `--py`                                                                       |
+| `.bb-progress`                                                           | `--fill` (the bar colour)                                                | `--accent`, the slider's word; new `--track-color` (the track) and `--r` (both radii) |
+
+The tab strip's rows are a beta-to-beta rename (shipped ≤ 3.0.0-beta.28, renamed in the next prerelease):
+the sliding pill became the **indicator** when `variant` arrived, because the
+same element is a 2px bar under `variant="line"`. If you built an underline by
+hand — `--pill-bg: transparent` plus an inset `--pill-shadow` — replace the
+whole block with `variant="line"` and the label tokens (`--active-fg`,
+`--active-fw`); see bb-tabs.md.
+
+`.bb-button` gained the same vocabulary rather than renaming into it: it now
+reads `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color` and
+`--ring-color`, which is what makes a one-line re-skin possible (section 3).
+
+The glyph components — the checkbox, radio and switch icons, the slider, the
+rating, and the error and warning icons — are not surfaces: their local is the
+**accent** on a mark, not the text on a background. They name it `--accent`, so
+`--color` means nothing anywhere in the library now and the grep above is a
+blind rename.
+
 ⚠ That first pattern is exact on purpose, and the near-misses are the point: a
 looser one (`input-`, `overlay-`, `dialog-p`) sweeps up tokens that are still
 live globals, and deleting those overrides shifts the layout silently. All of
@@ -1188,17 +1776,17 @@ blocks all moved), so check your stylesheet even for these three.
 to `'div' | 'span'`, so anything else is now a compile error — see
 [BbSmoothHeight](./components/bb-smooth-height.md).
 
-| Area              | Guides                                                                                                                                                                                                                                                    |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Actions           | [BbButton](./components/bb-button.md) · [BbDropdownButton](./components/bb-dropdown-button.md)                                                                                                                                                            |
-| Badges & status   | [BbBadge / BbIndicator](./components/bb-badge.md) · [BbChip (removed)](./components/bb-chip.md)                                                                                                                                                           |
-| Feedback          | [BbAlert](./components/bb-alert.md) · [BbToast / toast()](./components/bb-toast.md) · [confirm()](./components/use-confirm.md) · [BbSpinner](./components/bb-spinner.md)                                                                                  |
-| Surfaces          | [BbDialog](./components/bb-dialog.md) · [BbOffCanvas](./components/bb-offcanvas.md) · [BbPopover](./components/bb-popover.md) · [BbTooltip](./components/bb-tooltip.md) · [BbCollapsible](./components/bb-collapsible.md)                                 |
-| Navigation & data | [BbDropdown](./components/bb-dropdown.md) · [BbTabs](./components/bb-tabs.md) · [BbTable](./components/bb-table.md) · [BbTree](./components/bb-tree.md) · [BbBreadcrumbs](./components/bb-breadcrumbs.md) · [BbPagination](./components/bb-pagination.md) |
-| Media             | [BbAvatar](./components/bb-avatar.md) · [BbIcon](./components/bb-icon.md)                                                                                                                                                                                 |
-| Layout            | [BbSmoothHeight](./components/bb-smooth-height.md)                                                                                                                                                                                                        |
-| Text-ish inputs   | [BbTextInput](./components/bb-text-input.md) · [BbColorInput](./components/bb-color-input.md) · [BbDatePickerInput](./components/bb-date-picker-input.md) · [BbColorPalette](./components/bb-color-palette.md)                                            |
-| Selects           | [BbSelect](./components/bb-select.md) · [BbSelectPopover](./components/bb-select-popover.md)                                                                                                                                                              |
-| Choice controls   | [BbCheckbox / BbRadio / BbSwitch](./components/bb-checkbox.md) · [the three groups](./components/bb-checkbox-group.md)                                                                                                                                    |
-| Other inputs      | [BbSlider](./components/bb-slider.md) · [BbRating](./components/bb-rating.md) · [BbTag](./components/bb-tag.md) · [BbDropzone](./components/bb-dropzone.md)                                                                                               |
-| Removed           | [BbIntersection](./components/bb-intersection.md) · [useBroadcastChannelInstance](./components/use-broadcast-channel-instance.md)                                                                                                                         |
+| Area              | Guides                                                                                                                                                                                                                                                                  |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Actions           | [BbButton](./components/bb-button.md) · [BbDropdownButton](./components/bb-dropdown-button.md)                                                                                                                                                                          |
+| Badges & status   | [BbBadge / BbIndicator](./components/bb-badge.md) · [BbChip (removed)](./components/bb-chip.md)                                                                                                                                                                         |
+| Feedback          | [BbAlert](./components/bb-alert.md) · [BbToast / toast()](./components/bb-toast.md) · [confirm()](./components/use-confirm.md) · [BbSpinner](./components/bb-spinner.md)                                                                                                |
+| Surfaces          | [BbDialog](./components/bb-dialog.md) · [BbOffCanvas](./components/bb-offcanvas.md) · [BbPopover](./components/bb-popover.md) · [BbTooltip](./components/bb-tooltip.md) · [BbCollapsible](./components/bb-collapsible.md) · [BbAccordion](./components/bb-accordion.md) |
+| Navigation & data | [BbDropdown](./components/bb-dropdown.md) · [BbTabs](./components/bb-tabs.md) · [BbTable](./components/bb-table.md) · [BbTree](./components/bb-tree.md) · [BbBreadcrumbs](./components/bb-breadcrumbs.md) · [BbPagination](./components/bb-pagination.md)               |
+| Media             | [BbAvatar](./components/bb-avatar.md) · [BbIcon](./components/bb-icon.md)                                                                                                                                                                                               |
+| Layout            | [BbSmoothHeight](./components/bb-smooth-height.md)                                                                                                                                                                                                                      |
+| Text-ish inputs   | [BbTextInput](./components/bb-text-input.md) · [BbColorInput](./components/bb-color-input.md) · [BbDatePickerInput](./components/bb-date-picker-input.md) · [BbColorPalette](./components/bb-color-palette.md)                                                          |
+| Selects           | [BbSelect](./components/bb-select.md) · [BbSelectPopover](./components/bb-select-popover.md)                                                                                                                                                                            |
+| Choice controls   | [BbCheckbox / BbRadio / BbSwitch](./components/bb-checkbox.md) · [the three groups](./components/bb-checkbox-group.md)                                                                                                                                                  |
+| Other inputs      | [BbSlider](./components/bb-slider.md) · [BbRating](./components/bb-rating.md) · [BbTag](./components/bb-tag.md) · [BbDropzone](./components/bb-dropzone.md)                                                                                                             |
+| Removed           | [BbIntersection](./components/bb-intersection.md) · [useBroadcastChannelInstance](./components/use-broadcast-channel-instance.md)                                                                                                                                       |