bitboss-ui 3.0.0-beta.0 → 3.0.0-beta.2

package/dist/ai/guides/migration/components/bb-button.md

@@ -53,3 +53,67 @@ The `v-bb-tooltip` directive is registered by the runtime plugin (see the
 `<BbButton class="bb-button--outline">` → `<BbButton variant="outline">`.
 See [main guide §7](../v2-to-v3.md) for the full pattern and how to register
 custom variant names.
+
+## Skin colors: four locals became six theme tokens per variant
+
+v2 shipped **no** variant CSS — `.bb-button--outline`, `--secondary`, `--ghost`
+and friends had zero rules in the library sheet. If your app has buttons that
+look like anything but the primary fill, your stylesheet built the skin, by
+setting locals that `.bb-button` read:
+
+```css
+/* v2 theming.css — you wrote this, and it was the whole variant */
+.bb-button--outline {
+	--color: #fff;
+	--border-color: #d1d5db;
+	--text-color: #111827;
+	/* hover / pressed / focus were DERIVED from --color automatically */
+}
+```
+
+v3 reads none of those four names. Each variant paints from its own `--bb-*`
+family, declared in `variables.css` and overridable globally or on any scope:
+
+| v2 local on `.bb-button`                   | v3                       |
+| ------------------------------------------ | ------------------------ |
+| `--color` (fill)                           | `--bb-<variant>`         |
+| `--text-color`                             | `--bb-<variant>-fg`      |
+| `--border-color`                           | `--bb-<variant>-border`  |
+| `--ring-color`                             | `--bb-<variant>-ring`    |
+| _derived_ `mix(--color 90%, black)`, hover | `--bb-<variant>-hover`   |
+| _derived_ `mix(--color 80%, black)`, press | `--bb-<variant>-pressed` |
+
+`<variant>` is `primary`, `secondary`, `outline`, `ghost`, `destructive` or
+`link`.
+
+⚠ Note the last two rows. v2 **derived** hover and pressed from the fill; v3
+**states** them. Port only `--bb-outline` and the button keeps the library's
+default hover, which will not be a shade of your color.
+
+```css
+/* v3 equivalent of the v2 block above */
+:root {
+	--bb-outline: #fff;
+	--bb-outline-border: #d1d5db;
+	--bb-outline-fg: #111827;
+	--bb-outline-hover: #f3f4f6;
+	--bb-outline-pressed: #e5e7eb;
+}
+```
+
+Silent by construction: a rule setting `--color` on `.bb-button` still parses,
+still applies, and is read by nothing. `rg -n -- '--color|--text-color|--border-color|--ring-color'`
+across your CSS and find the ones scoped to a button.
+
+Don't confuse this with the `--bb-button-*` row in
+[main guide §3](../v2-to-v3.md): the button's **dimensions** went down into
+component locals, its **colors** went up into global theme tokens. Opposite
+directions, same component.
+
+## `loading-text` was never a BbButton prop
+
+Not in v2, not in v3. If you find `loading-text` on a v2 button it was landing
+in `$attrs` and rendering nothing — delete it rather than looking for the
+replacement. The prop is real on the list and group surfaces — `BbSelect`,
+`BbCheckboxGroup`, `BbRadioGroup`, `BbTable`, `BbSelectPopover` — where it
+carries over to v3 under the same name.

package/dist/ai/guides/migration/components/bb-checkbox-group.md

@@ -1,6 +1,6 @@
 ---
 title: 'Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup'
-summary: labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, BbRadioGroup's name no longer required.
+summary: labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, BbRadioGroup's name no longer required, and the shared bb-cr-container CSS block split into one per group.
 ---
 
 # BbCheckboxGroup / BbRadioGroup / BbSwitchGroup — v2 → v3
@@ -53,3 +53,57 @@ unchanged.
 The `item.disabled` change is the dangerous one: nothing errors, options that
 used to render disabled simply become selectable. Grep item-building code for
 `disabled:` near these groups.
+
+## DOM: the shared `bb-cr-container` block split three ways
+
+v2 rendered one prefix for all three groups — `bb-cr-container` ("checkbox /
+radio") — so a rule written for one group hit all of them. v3 gives each group
+its own block; the suffixes are otherwise identical.
+
+| v2                                    | v3 (`{checkbox,radio,switch}`)            |
+| ------------------------------------- | ----------------------------------------- |
+| `.bb-cr-container`                    | `.bb-base-{checkbox,radio,switch}-group`  |
+| `.bb-cr-container--horizontal`        | `.bb-base-…-group--horizontal`            |
+| `.bb-cr-container--vertical`          | `.bb-base-…-group--vertical`              |
+| `.bb-cr-container--errors`            | `.bb-base-…-group--errors`                |
+| `.bb-cr-container__container`         | `.bb-base-…-group__container`             |
+| `.bb-cr-container__loading-container` | `.bb-base-…-group__loading-container`     |
+| `.bb-cr-container__no-data-container` | `.bb-base-…-group__no-data-container`     |
+| `.bb-cr-container-option`             | `.bb-base-…-group-option`                 |
+| `.bb-cr-container-option__text`       | `.bb-base-…-group-option__text`           |
+| —                                     | `.bb-base-…-group--warnings` (new)        |
+| —                                     | `.bb-base-…-group-option--selected` (new) |
+
+Nothing in v3 renders any `bb-cr-container` class, and nothing warns — the rules
+simply stop matching. **Grep your CSS and test selectors for `bb-cr-container`.**
+
+One rule that used to cover three components is now three rules. If you were
+relying on the shared prefix, group the selectors:
+
+```css
+.bb-base-checkbox-group-option__text,
+.bb-base-radio-group-option__text,
+.bb-base-switch-group-option__text {
+	font-weight: 500;
+}
+```
+
+**`BbRating` is not in this family.** v2's stylesheet carried
+`.bb-rating … .bb-cr-container__container` rules, but the component never
+rendered those classes on either version — it has always used
+`.bb-base-rating__inner-container` / `.bb-base-rating__option`. See
+[bb-rating.md](./bb-rating.md).
+
+## `legend` is required — and always was
+
+`legend: string` is a required prop on `BbCheckboxGroup`, `BbRadioGroup` and
+`BbSwitchGroup` in **v2 and v3 alike** (v2 `dist/components/BbCheckboxGroup/types.d.ts`
+declares `legend: string`, not `legend?`). If the upgrade surfaced missing-legend
+errors across your app, that is a pre-existing bug the stricter v3 build made
+visible — not a v3 break, and not something to "fix" as part of the upgrade.
+
+Treat it as its own change, separately from the migration. One migration team
+added `legend` to six groups mid-upgrade; supplying it let the generic `T`
+resolve properly, which unblocked type inference on the whole subtree and
+surfaced a cascade of unrelated downstream type errors. They reverted the lot.
+Land the migration first, then add legends one component at a time.

package/dist/ai/guides/migration/components/bb-date-picker-input.md

@@ -133,8 +133,15 @@ friends, rename it:
 | `…__calendar-btn--active`                                                                   | `.bb-segmented-field__trigger-btn--active`              |
 | `.bb-base-date-picker-input__calendar-icon`                                                 | `.bb-segmented-field__trigger-icon`                     |
 | `…__calendar--sheet`                                                                        | `.bb-base-time-picker-input__panel--sheet` (time input) |
-| `…__calendar`, `…__calendar--shown`                                                         | removed — they were styled nowhere                      |
-| `.bb-base-time-picker-input__clock-btn`                                                     | removed — use `.bb-segmented-field__trigger-btn`        |
+| `.bb-base-date-picker-input__inner-wrapper`                                                 | **removed** — see below                                 |
+
+`__inner-wrapper` has no v3 counterpart. It was a bare layout box
+(`flex: auto; display: block`) between the input chrome and the fields; v3
+drops the element and `.bb-segmented-field__fields` carries the layout. A rule
+hanging off it stops matching with nothing to rename it to — delete it, and if
+it was doing real work, move the declarations onto `__fields`.
+| `…__calendar`, `…__calendar--shown` | removed — they were styled nowhere |
+| `.bb-base-time-picker-input__clock-btn` | removed — use `.bb-segmented-field__trigger-btn` |
 
 **The block names are unchanged.** `.bb-base-date-picker-input` and
 `.bb-base-time-picker-input` are still the roots, so a rule that has to reach

package/dist/ai/guides/migration/components/bb-dialog.md

@@ -1,6 +1,6 @@
 ---
 title: 'Migration v2→v3: BbDialog'
-summary: showClose inverted to hideClose, several presentation props removed, default widths changed, adaptive bottom sheet on mobile by default.
+summary: 'showClose inverted to hideClose, several presentation props and the #close/#description slots removed, default widths changed, adaptive bottom sheet on mobile by default, --bb-dialog-* tokens replaced by --bb-panel-p plus locals.'
 ---
 
 # BbDialog — v2 → v3
@@ -10,16 +10,18 @@ v2's `BbDialog` was a re-export of `BaseDialog`; v3 makes it first-class
 
 ## Changes
 
-| v2                                                  | v3                                                                                                                                  | Kind                                                            |
-| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| `showClose?: boolean` (default `true`)              | `hideClose?: boolean` (default `false`)                                                                                             | rename, polarity inverted                                       |
-| `description`                                       | removed                                                                                                                             | put it in the default slot / `header` slot                      |
-| `hideHeader`                                        | removed                                                                                                                             | omit `title` and the header collapses; or use the `header` slot |
-| `compact`                                           | removed                                                                                                                             | spacing is token-driven now (`--bb-panel-p`)                    |
-| `overlayClasses`, `panelClasses` (deprecated in v2) | removed                                                                                                                             | use normal `class` / CSS on `.bb-dialog*`                       |
-| `size?: 'sm' \| 'md' \| 'lg'`                       | `size?: Responsive<'xs'…'2xl' \| CSS length>`                                                                                       | widened — **but defaults changed, see below**                   |
-| `transitionDuration` default `300`                  | default `250`                                                                                                                       | visual                                                          |
-| —                                                   | `adaptive` (default from config, **on**), `offCanvasProps`, `stack`, `fullscreen`, `persistent`, `disabled`, `focusTarget`, `eager` | additive                                                        |
+| v2                                                  | v3                                                                                                                                  | Kind                                                                                                      |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `showClose?: boolean` (default `true`)              | `hideClose?: boolean` (default `false`)                                                                                             | rename, polarity inverted                                                                                 |
+| `description`                                       | removed                                                                                                                             | put it in the default slot / `header` slot                                                                |
+| `#description` slot                                 | removed                                                                                                                             | same — and the `aria-describedby` wiring goes with it                                                     |
+| `#close` slot                                       | removed                                                                                                                             | a custom close control goes inside `#header`, which replaces the default ✕ — no `hide-close` alongside it |
+| `hideHeader`                                        | removed                                                                                                                             | omit `title` and the header collapses; or use the `header` slot                                           |
+| `compact`                                           | removed                                                                                                                             | spacing is token-driven now (`--bb-panel-p`)                                                              |
+| `overlayClasses`, `panelClasses` (deprecated in v2) | removed                                                                                                                             | use normal `class` / CSS on `.bb-dialog*`                                                                 |
+| `size?: 'sm' \| 'md' \| 'lg'`                       | `size?: Responsive<'xs'…'2xl' \| CSS length>`                                                                                       | widened — **but defaults changed, see below**                                                             |
+| `transitionDuration` default `300`                  | default `250`                                                                                                                       | visual                                                                                                    |
+| —                                                   | `adaptive` (default from config, **on**), `offCanvasProps`, `stack`, `fullscreen`, `persistent`, `disabled`, `focusTarget`, `eager` | additive                                                                                                  |
 
 ## ⚠ The two silent ones
 
@@ -44,3 +46,111 @@ v2's `BbDialog` was a re-export of `BaseDialog`; v3 makes it first-class
     …
   </BbDialog>
 ```
+
+## CSS and tokens
+
+The `--bb-dialog-*` family is gone. Padding comes from the shared
+`--bb-panel-p`; the rest are unprefixed locals on `.bb-dialog` or plain CSS
+rules. `BbOffCanvas` is identical throughout with `.bb-offcanvas__*` parts.
+
+| v2 token                                     | v3                                                                                     |
+| -------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `--bb-dialog-px` / `--bb-dialog-py` (`24px`) | `--bb-panel-p` (`16px`) — **one** value on both axes; asymmetry needs a CSS rule       |
+| `--bb-dialog-close` (`12px`)                 | **delete it** — v3's default already reproduces v2's control size                      |
+| `--bb-dialog-title-size` (`18px`)            | local `--dialog-title-fs` on `.bb-dialog`, default `calc(var(--bb-fs) + 2px)` = `16px` |
+| `--bb-dialog-title-weight` (`600`)           | no knob — `500` is hard-coded; override with a CSS rule                                |
+| —                                            | local `--dialog-gap`, default `--bb-panel-p` — the body↔footer vertical rhythm         |
+
+### `--bb-dialog-close` → delete it
+
+v2's `--bb-dialog-close` was the close **icon** width; the button around it
+added `padding: 8px`, so the control measured `12 + 16 = 28px`. v3 inverts the
+relationship: `.bb-close-button { --size }` is the whole control box and the
+glyph is derived — `max(--size - 2 × --p, 10px)`. Inside a dialog v3 already
+ships `--size: 28px; --p: 7px`, a 14px glyph in the same 28px control v2's
+default produced.
+
+So carrying the old number across shrinks the target: `--size: 12px` gives a
+12×12px control, well under the 24px WCAG 2.5.8 minimum. To get the old 12px
+glyph back, widen the padding — never shrink the box:
+
+```css
+/* 12px glyph, still a 28px control */
+.my-dialog .bb-dialog__header > .bb-close-button {
+	--p: 8px;
+}
+```
+
+The library rule is `.bb-dialog .bb-dialog__header > .bb-close-button` (0,3,0),
+so your selector needs three classes to win. A headerless dialog puts the ✕ at
+`.bb-dialog__body:first-child .bb-dialog__body-content > .bb-close-button`.
+
+### The title
+
+```css
+.my-dialog {
+	--dialog-title-fs: 18px; /* v2 --bb-dialog-title-size; drives line-height too */
+}
+.my-dialog .bb-dialog__header .bb-dialog__title {
+	font-weight: 600; /* v2 --bb-dialog-title-weight */
+}
+```
+
+There is no weight token in v3. `500` is hard-coded on
+`.bb-dialog .bb-dialog__header .bb-dialog__title` (0,3,0), so match that
+specificity — a two-class `.my-dialog .bb-dialog__title` loses.
+
+### Asymmetric padding
+
+`--bb-panel-p` is a single value used on both axes; there is no
+`--bb-panel-px`/`--bb-panel-py` pair. 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 `padding-block`
+rule on the part classes.
+
+```css
+/* v2: --bb-dialog-px: 24px; header --bb-dialog-py: 10px; body --bb-dialog-py: 20px */
+.my-dialog {
+	--bb-panel-p: 24px; /* horizontal + close-button inset */
+}
+.my-dialog .bb-dialog__header {
+	padding-block: 10px 5px; /* the library halves the header's bottom padding */
+}
+.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;
+}
+```
+
+Use `padding-block`, not the `padding` shorthand, so the horizontal half keeps
+tracking `--bb-panel-p`. Library selectors are `.bb-dialog .bb-dialog__header`
+(0,2,0), `.bb-dialog__body-content` (0,1,0),
+`.bb-dialog__body:first-child .bb-dialog__body-content` (0,2,1) and
+`.bb-dialog .bb-dialog__footer` (0,2,0) — the three-class app rules above beat
+all four.
+
+### `--dialog-gap`
+
+If only the vertical rhythm _between parts_ differs, `--dialog-gap` does it
+without a padding rule — it replaces `--bb-panel-p` in the body's bottom padding
+and the footer's block padding:
+
+```css
+.my-dialog {
+	--dialog-gap: 8px;
+}
+```
+
+It does **not** reach the header's top padding, any horizontal padding, or the
+body's top padding in the headerless case; those still read `--bb-panel-p`.
+
+### `.bb-confirm`
+
+`confirm()` renders through the same `.bb-dialog__*` parts, so everything above
+reaches it. Its own button hooks changed — see
+[use-confirm.md](./use-confirm.md).

package/dist/ai/guides/migration/components/bb-icon.md

@@ -26,6 +26,48 @@ Provider prefixes now require the matching `@iconify-json/<prefix>` dev
 dependency, and names must be **literal strings** (the build scans statically;
 dynamically assembled names won't be bundled).
 
+## Your own icon plugin is probably redundant now
+
+Most v2 apps hand-rolled one, because v2 shipped no registry:
+
+```ts
+// resources/js/plugins/icons.ts — the v2 shape: glob the SVG folder yourself,
+// build a name → loader map, hand it to BbIcon under the string key.
+const icons = import.meta.glob('../../assets/icons/*.svg', { as: 'raw' });
+app.provide('icons', toRegistry(icons));
+```
+
+v3 does both halves itself. The **build** plugin scans `iconDir` recursively
+and turns every `.svg` into `local:<basename>`; the **runtime** plugin provides
+that registry to `BbIcon`. If your plugin scanned the same folder and provided
+it under `'icons'`, it is now duplicating both.
+
+⚠ It is not merely duplicate — it is **inert for `BbIcon`, silently**.
+`bitbossUiPlugin` provides the registry under a Symbol
+(`bitboss-ui:icons`) _and_ under the legacy string key `'icons'`, and `BbIcon`
+reads `inject(Symbol.for('bitboss-ui:icons')) ?? inject('icons')`. The Symbol wins,
+so your map is shadowed rather than merged. Any glyph that exists only in your
+map stops rendering and nothing warns.
+
+Check before you delete — the plugin is dead only if both hold:
+
+1. **Every SVG it registers also lives under `iconDir`.** Diff the two folders.
+   If the plugin globbed a different directory (`resources/js/icons`,
+   a package's `assets/`), move those files into `iconDir` first — otherwise
+   deletion and non-deletion both leave you with missing icons.
+2. **Nothing else injects `'icons'`.** `rg -n "inject\(['\"]icons['\"]\)"` — an
+   app component reading the map to render `<img>` or to enumerate names is
+   real usage, not `BbIcon` usage. It now receives whichever provide ran last
+   (yours, if you `app.use()` your plugin after `bitbossUiPlugin`), which is a
+   coin-flip you do not want to keep. Rewrite those call sites to import your
+   map as a plain module export — or, if what they want is the library's
+   registry, `inject(Symbol.for('bitboss-ui:icons'))`. The key is not exported
+   from the package, but it is a `Symbol.for`, so recreating it resolves the
+   same symbol.
+
+The string key `'icons'` is a compatibility shim kept for one release. Do not
+build on it.
+
 ## Prefix your own icons with `local:` while you are in there
 
 A v2 `type` naming an icon from your own `iconDir` was bare — `type="user-circle"`.

package/dist/ai/guides/migration/components/bb-offcanvas.md

@@ -1,6 +1,6 @@
 ---
 title: 'Migration v2→v3: BbOffCanvas'
-summary: direction→side; showClose→hideClose; size defaults change; adaptive drawer configs unify on offCanvasProps.
+summary: 'direction→side; showClose→hideClose; description and the #close/#description slots removed; size defaults change; adaptive drawer configs unify on offCanvasProps.'
 ---
 
 # BbOffCanvas — v2 → v3
@@ -11,6 +11,9 @@ summary: direction→side; showClose→hideClose; size defaults change; adaptive
 | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `direction?: 'left' \| 'top' \| 'right' \| 'bottom'` (default `'left'`) | `side?: 'left' \| 'top' \| 'right' \| 'bottom'` (default `'left'`)                                         | **⚠ silent** — a leftover `direction` is ignored and the panel falls back to `'left'`                                                                                                                    |
 | `showClose?: boolean` (default `true`)                                  | `hideClose?: boolean` (default `false`)                                                                    | rename, polarity inverted                                                                                                                                                                                |
+| `description?: string`                                                  | removed                                                                                                    | put the copy in the default slot or own the header via `#header`; the `aria-describedby` wiring goes with it                                                                                             |
+| `#description` slot                                                     | removed                                                                                                    | same — nothing links body copy to the panel automatically now                                                                                                                                            |
+| `#close` slot                                                           | removed                                                                                                    | a custom close control goes inside `#header`, see below                                                                                                                                                  |
 | `size?: 'sm' \| 'md' \| 'lg'`                                           | `size?: Responsive<'xs'…'2xl' \| 'auto' \| CSS length>`                                                    | widened — **defaults changed**, same trap as BbDialog: v2 `{ sm: 384, md: 652, lg: 896 }` → v3 `{ xs: 320, sm: 384, md: 448, lg: 512, xl: 576, '2xl': 672 }`. Pin via `offCanvasDefaultSizes` if needed. |
 | —                                                                       | `draggable`, `stack` / `stackGap`, `persistent`, `disabled`, `fullscreen`, `eager`, `focusTarget`, `title` | additive                                                                                                                                                                                                 |
 
@@ -61,3 +64,34 @@ Pure rename — the `Partial<BbOffCanvasProps>` object is unchanged.
 ```
 
 Also silent on upgrade; `eslint --fix` auto-renames it.
+
+## `description` and `#close` are gone
+
+v3's slot set is `header | title | default | footer` — no `#close`, no
+`#description`, and no `description` prop. Same removal as
+[BbDialog](./bb-dialog.md).
+
+`description` copy moves into the default slot. Nothing wires
+`aria-describedby` for you any more; add it yourself if a screen reader needs
+the panel described rather than just labelled.
+
+**`#header` replaces the ✕, so `hide-close` is redundant beside it.** The
+default header renders `#title` + a `CloseButton`; providing `#header` replaces
+both, which is why a custom close control belongs inside it. The slot receives
+`{ titleId, close, title }` — put `titleId` on your title element to keep
+`aria-labelledby` intact, and call `close` from your own control.
+
+```diff
+- <BbOffCanvas v-model="open" title="Edit" :show-close="true">
+-   <template #close><SaveGuardIcon /></template>
+- </BbOffCanvas>
++ <BbOffCanvas v-model="open" title="Edit">
++   <template #header="{ titleId, close, title }">
++     <span :id="titleId" class="bb-offcanvas__title">{{ title }}</span>
++     <button @click="guardUnsaved(close)"><SaveGuardIcon /></button>
++   </template>
++ </BbOffCanvas>
+```
+
+A header renders when `title` is set **or** `#header` is provided, so the slot
+alone is enough — you do not also need a `title`.

package/dist/ai/guides/migration/components/bb-rating.md

@@ -1,6 +1,6 @@
 ---
 title: 'Migration v2→v3: BbRating'
-summary: color removed; name no longer required.
+summary: color removed; name no longer required; the star state modifier renamed --highlighted to --filled/--empty; --bb-rating-size demoted to a local --size; input-position finally works.
 ---
 
 # BbRating — v2 → v3
@@ -22,3 +22,54 @@ summary: color removed; name no longer required.
 
 Adding `clearable` is recommended: the old "re-click to clear" folklore is
 now a visible affordance.
+
+`legend` is required here too, in v2 as in v3 — see the note in
+[bb-checkbox-group.md](./bb-checkbox-group.md); a missing one is a pre-existing
+bug, not an upgrade break.
+
+## DOM
+
+The block name is unchanged; the star's state modifier is not.
+
+| v2                                     | v3                                                      |
+| -------------------------------------- | ------------------------------------------------------- |
+| `.bb-base-rating__option--highlighted` | `.bb-base-rating__option--filled` / `--empty`           |
+| —                                      | `.bb-base-rating__option--disabled`, `--readonly` (new) |
+| —                                      | `.bb-base-rating--warnings`, `--forced-clear` (new)     |
+
+v2 styled unfilled stars with `:not(--highlighted)`; v3 gives them a positive
+name. Everything else survives unchanged: `.bb-base-rating`, `--disabled`,
+`--errors`, `--readonly`, `--has-value`, `__inner-container`, `__option`,
+`__label-text`. Nothing warns — a `--highlighted` rule just stops matching.
+
+`BbRating` is not part of the checkbox/radio/switch `bb-cr-container` tree, and
+was not in v2 either despite v2 shipping rules that said otherwise (below).
+Target `.bb-base-rating__inner-container` and `.bb-base-rating__option`.
+
+## `input-position="right"` / `"center"` now does something
+
+v2 shipped the alignment rules under `.bb-rating … .bb-cr-container__container`
+— a class `BbRating` never rendered (its container was already
+`.bb-base-rating__inner-container`). So the prop was accepted and typed on both
+versions but was a **no-op in v2**. v3 repoints the rules at the element the
+component actually renders.
+
+If your app worked around the dead prop with a hand-rolled alignment rule, that
+rule now fights the library's. Delete the workaround and keep the prop.
+
+## Tokens
+
+`--bb-rating-size` was a `:root` global in v2, read as
+`.bb-base-rating { --size: var(--bb-rating-size) }`. v3 drops the global and
+hard-defaults the local:
+
+```diff
+- :root { --bb-rating-size: 32px; }
++ .bb-base-rating { --size: 32px; }
+```
+
+Set it on `.bb-base-rating` itself (or on a rule that also matches it) — the
+local is declared on that block, so a value inherited from an ancestor is
+overridden before it is read. `--spacing` (star gap) is the companion local;
+v2's `--bb-base-rating-spacing` was referenced but never declared anywhere in
+the shipped sheet, so it never worked.

package/dist/ai/guides/migration/components/bb-select.md

@@ -93,3 +93,51 @@ Applies to every surface built on the select engine — `BbSelect`,
 `BbSelectPopover`, and the flat/grouped listboxes. **Grep for
 `autocomplete-option` in your CSS and test selectors**; nothing warns, the rules
 simply stop matching.
+
+## Tokens: `--bb-select-option-px` / `--bb-select-option-py` are gone
+
+v2 declared both on `:root` (`16px` / `8px`) and read them in the option row, the
+group header and the no-results row. v3 declares neither, and — unlike most of
+the retired component globals — **nothing replaced them with a local**.
+`.bb-listbox__option` hard-codes its inline padding:
+
+```css
+/* src/components/BbSelectPopover/index.css */
+.bb-listbox__option {
+	height: var(--option-h);
+	padding-left: 0.5rem;
+	padding-right: 0.5rem;
+}
+```
+
+So `--bb-select-option-px`, and the `--px` local you might expect by analogy with
+`BbButton` or `BbDialog`, are both silent no-ops — no rule in the select tree
+reads either. Override with a plain declaration instead. The library's rule is
+six classes deep, so a two-class app rule loses the cascade; match the chain or
+force it:
+
+```css
+/* specificity-matched — needs your sheet to load after the library's */
+.bb-select-popover
+	.bb-listbox
+	.bb-listbox__outer-container
+	.bb-listbox__inner-container
+	span[role='listbox']
+	.bb-listbox__option {
+	padding-inline: 1rem;
+}
+
+/* or, order-independent */
+.bb-listbox__option {
+	padding-inline: 1rem !important;
+}
+```
+
+Row **height** is not yours to set in CSS. `--option-h` reads `--option-height`,
+which the component writes inline because the same number feeds the
+virtualizer's `estimateSize`; a CSS override desynchronises the paint from the
+scroll math and the list mispositions. Use `item-height` / `header-height` (or
+`compact`) instead — they move both halves together.
+
+The panel is teleported, so a wrapper class on your `<BbSelect>` does not reach
+it — scope on `.bb-select-popover` or on the surrounding page/theme class.