bitboss-ui 2.1.134 → 3.0.0-alpha.1

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

@@ -0,0 +1,424 @@
+---
+title: Design Tokens
+summary: The token architecture of bitboss-ui — tiers, naming rules, the emphasis ladder, and the theming contract.
+---
+
+# Design Tokens
+
+This is the spec for how every visual value in the library is expressed. It is
+deliberately small: we are not shipping a design system, we are shipping
+**affordances**. A token earns its place only when overriding it is a decision
+a real consumer would make. Everything else is a formula.
+
+## Principles
+
+1. **Cheap by default.** Reuse an existing token (possibly through `calc()` /
+   `color-mix()`) before minting a new one. The `:root` block is the public
+   API surface _and_ what crowds the devtools console — it must stay readable
+   in one screen.
+2. **Elastic derivation.** Secondary values derive from primary knobs
+   (`calc(var(--bb-radius) - var(--p))`, `calc(var(--bb-control-h) - 4px)`).
+   Turning one knob retunes the whole library coherently — this is the theme
+   builder contract.
+3. **Two names, two tiers.**
+   - `--bb-*` — theme tokens. Global, defined in `variables.css`, themable.
+   - `--*` (no prefix) — component tokens. Defined on the component's root
+     class, in the component's own CSS file. Never in `:root`.
+     `--bb-tab-card-radius-md` must never exist.
+4. **One accent at a time.** A component resolves _which_ color it is using
+   (primary, danger, a variant color) into a local token once, then every
+   state derives from that local via the emphasis ladder.
+5. **Grays stay gray: primary tint means _selected_.** Neutral chrome —
+   hovers, pressed fills, secondary buttons, scrollbars — derives from
+   text/panel, never from primary. Primary appears only where the state is
+   genuinely brand-selected (solid primary buttons, links, rings, calendar
+   selected day/range, focused chips, today marker). This is what makes a
+   yellow theme produce gray hovers and yellow selections instead of a
+   yellow-washed UI.
+6. **Mixes interpolate in `oklab`.** Perceptually even steps; srgb muddies
+   saturated brand colors. Enforced by the checker.
+
+## Tier 1 — theme tokens (`--bb-*`)
+
+The complete inventory. If a value is not here, it is not globally themable —
+that is a feature.
+
+### Brand knobs (what a theme builder sets)
+
+| Token               | Default (light)    | Dark               | Meaning                                                               |
+| ------------------- | ------------------ | ------------------ | --------------------------------------------------------------------- |
+| `--bb-primary`      | `rgb(0 0 0)`       | `white`            | Brand accent                                                          |
+| `--bb-primary-fg`   | `white` (fallback) | `black` (fallback) | Text/icons **on** primary — **auto-contrasts** (see note)             |
+| `--bb-danger`       | `rgb(217 59 48)`   | same               | Errors, destructive intent                                            |
+| `--bb-warn`         | `rgb(240 131 88)`  | same               | Warning **input state** (`hasWarning`) — amber, ranks below danger    |
+| `--bb-panel`        | `rgb(255 255 255)` | `#313638`          | Raised surfaces (cards, inputs, popovers, dialogs)                    |
+| `--bb-text`         | `rgb(0 0 0)`       | `white`            | Foreground                                                            |
+| `--bb-border`       | zinc-300           | zinc-600           | Hairlines; pair with `--bb-border-w`                                  |
+| `--bb-ring-opacity` | `25%`              | `40%`              | Ring strength; `--bb-ring`/`--bb-ring-danger`/`--bb-ring-warn` follow |
+
+**`--bb-warn` is the only shared status token besides `--bb-danger`.** It exists
+solely to color the **warning input state** — every form control takes `warnings`
+(amber messages in an `aria-live` region) and `hasWarning` (force the chrome),
+mirroring `errors`/`hasErrors` but in amber; `errors` win and suppress warnings
+when both are set. It is deliberately **not** a badge/button `warning` _variant_
+(those stay locked — see design-language.md); there is still no
+`--bb-success`/`--bb-info`. Same value in both themes, like `--bb-danger`.
+
+**`--bb-primary-fg` auto-contrasts.** Where the browser supports CSS
+`contrast-color()`, `--bb-primary-fg` is derived to black or white — whichever
+reads on `--bb-primary` — so setting only `--bb-primary` still yields legible
+text/icons on primary fills. The light/dark values in the table are the
+**fallback** used when `contrast-color()` is unsupported; a theme that targets
+those browsers should set a matching fallback for its brand color. Setting
+`--bb-primary-fg` explicitly always wins over both (normal cascade), so a theme
+can pin an exact foreground.
+
+### Derived colors (follow the knobs automatically; still overridable)
+
+| Token                | Formula (all `in oklab`)                                     | Used for                                                                                                                                                                        |
+| -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--bb-muted`         | `mix(var(--bb-text) 6%, var(--bb-panel))`                    | Static subtle fills: disabled surfaces                                                                                                                                          |
+| `--bb-track`         | `mix(var(--bb-text) 15%, var(--bb-panel))`                   | Recessed control-track surface (switch/slider rails, input wells) — a distinct surface that must contrast a panel-coloured thumb, so it sits **above** the 2/4/6/8 chrome fills |
+| `--bb-hover`         | `mix(var(--bb-text) 4%, var(--bb-panel))`                    | Hover fill for **affordances** — ghost/outline buttons, pagination, nav links                                                                                                   |
+| `--bb-surface-hover` | `mix(var(--bb-text) 2%, var(--bb-panel))`                    | Hover fill for **passive surfaces** — table rows, list items, picker day cells (fainter)                                                                                        |
+| `--bb-pressed`       | `mix(var(--bb-text) 8%, var(--bb-panel))`                    | Neutral pressed/active fill                                                                                                                                                     |
+| `--bb-text-muted`    | `mix(var(--bb-text) 60%, transparent)`                       | Secondary text, icons, placeholders, hints                                                                                                                                      |
+| `--bb-text-faint`    | `mix(var(--bb-text) 45%, transparent)`                       | Disabled foregrounds                                                                                                                                                            |
+| `--bb-ring`          | `mix(var(--bb-primary) var(--bb-ring-opacity), transparent)` | Focus ring — primary & link variants                                                                                                                                            |
+| `--bb-ring-danger`   | same formula over `--bb-danger`                              | Focus ring in error states (destructive)                                                                                                                                        |
+| `--bb-ring-warn`     | same formula over `--bb-warn`                                | Focus ring in the warning input state (`hasWarning`)                                                                                                                            |
+| `--bb-ring-neutral`  | same formula over `--bb-text`                                | Focus ring for the neutral variants (secondary/outline/ghost) — grey, never primary-tinted                                                                                      |
+
+These neutral-chrome percentages (2/4/6/8) are deliberately off the emphasis
+ladder: they live only in `variables.css`, which the checker exempts as the
+home of the sanctioned derivation formulas.
+
+A theme builder normally never touches these — they track the knobs. They are
+tokens (not inlined formulas) because they are consumed in dozens of places,
+and because each is a **pinnable scale step**: a theme that wants
+Radix-precision grays can override any of them with a hand-tuned value while
+cheap themes keep the derivation. Components with a multi-step neutral
+progression (e.g. the secondary button's rest→hover→pressed) write the raw
+ladder formulas instead of these tokens, so a state name never lies.
+
+### Shape & elevation
+
+| Token                 | Default                                  | Notes                                                               |
+| --------------------- | ---------------------------------------- | ------------------------------------------------------------------- |
+| `--bb-radius`         | `8px`                                    | THE knob — controls tier: buttons, inputs, tab strips               |
+| `--bb-radius-surface` | `calc(var(--bb-radius) * 1.8)`           | Surfaces tier: dialogs, off-canvas sheets                           |
+| `--bb-radius-sm`      | `max(4px, calc(var(--bb-radius) * 0.6))` | Nested-bits tier: table controls, toast close, calendar footer btns |
+| `--bb-border-w`       | `1px`                                    |                                                                     |
+| `--bb-ring-size`      | `2px`                                    | Focus ring thickness                                                |
+| `--bb-shadow`         | soft 2-layer                             | The single elevation shadow                                         |
+
+Radius is tiered **by role, not by size**; both extra tiers derive from the
+one knob (still individually pinnable). Two more radius rules: concentric
+nesting is always `outer radius − padding` (the tabs pill), and per-size
+ramps inside a component (badge, chip) derive from `--bb-radius` with
+multipliers — never literals.
+
+### Scale
+
+| Token            | Default | Notes                                                                                                             |
+| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `--bb-control-h` | `32px`  | Master control height. Inputs are exactly this; buttons/tabs derive their size scale from it via `calc()` offsets |
+| `--bb-fs`        | `14px`  | Master font size. Component font sizes derive via `calc()` offsets                                                |
+| `--bb-panel-p`   | `16px`  | Content padding of large surfaces (dialog, off-canvas; header/footer paddings derive from it)                     |
+
+### Motion
+
+| Token                    | Default                                                |
+| ------------------------ | ------------------------------------------------------ |
+| `--bb-transition-fast`   | `150ms` — micro-interactions                           |
+| `--bb-transition-medium` | `250ms` — overlays, most moves                         |
+| `--bb-ease`              | `cubic-bezier(0.4, 0, 0.2, 1)` — the only easing curve |
+
+(`--bb-transition-slow`: `350ms`, for large-surface consumer animations —
+the library itself uses `medium` for those.)
+
+### Overlays
+
+| Token               | Default            | Notes                               |
+| ------------------- | ------------------ | ----------------------------------- |
+| `--bb-overlay`      | `rgb(0 0 0 / 0.1)` | Backdrop dim color+opacity in one   |
+| `--bb-overlay-blur` | `2px`              | Backdrop blur                       |
+| `--bb-z-overlay`    | `10`               | Overlay z-index                     |
+| `--bb-arrow`        | `1`                | Popover arrows on (`1`) / off (`0`) |
+
+### Input family
+
+Form controls are ~half the library and must agree with each other, so their
+shared metrics are global — but they derive from the scale knobs:
+
+```css
+--bb-input-h: var(--bb-control-h);
+--bb-input-h-compact: calc(var(--bb-control-h) - 4px);
+--bb-input-px: 8px;
+--bb-input-py: 3px;
+--bb-input-py-compact: 2px;
+--bb-input-spacing: 8px; /* gap between the parts of an input */
+--bb-input-icon: 20px; /* prepend/append icon box */
+--bb-input-prefix-w: 20px; /* prefix/suffix column */
+--bb-input-fs: var(--bb-fs);
+--bb-input-fs-mobile: max(var(--bb-input-fs), 16px); /* defeats iOS zoom */
+--bb-leading: calc(var(--bb-input-fs) * 1.5);
+--bb-label-fs: var(--bb-fs);
+--bb-label-fs-sm: calc(var(--bb-fs) - 2px); /* inside & floating labels */
+--bb-label-weight: 500;
+--bb-label-spacing-y: 6px; /* compact derives: - 2px */
+--bb-label-spacing-x: 8px;
+--bb-label-lh: calc(var(--bb-label-fs) + 4px);
+--bb-label-lh-sm: max(16px, calc(var(--bb-label-fs-sm) * 1.5));
+```
+
+The theme layer stays small — **89 `--bb-*` tokens** today (the number
+`npm run check:tokens` prints; the canonical, complete list is
+`src/assets/css/variables.css`), down from ~140 in v2. The blocks above show the
+representative groups, not every token.
+
+## Tier 2 — component tokens (`--*`)
+
+Defined on the component's **root class** in the component's own CSS file.
+Rules:
+
+1. **No `--bb-` prefix.** Ever.
+2. **A token must be defined in the same file that consumes it** (usually on
+   the root class). Since custom properties inherit, this is what prevents a
+   `--gap` set by an outer component from leaking into an inner one — every
+   component seals itself.
+3. **Short names are for self-consumption only.** `--h`, `--px`, `--gap`,
+   `--fs`, `--r` are fine while the rules using them target the component's
+   own boxes. If a value must be read _inside a nested foreign component_
+   (e.g. dialog padding positioning the close button, which is itself a
+   button defining `--px`), the token gets a distinctive name (`--dialog-px`)
+   or — better — the formula moves to an element the component owns.
+4. **Mint only what varies.** A size variant that overrides four locals is
+   four tokens, not four × six sizes. Per-size lookup tables
+   (`--h-xs … --h-2xl`) are allowed only when a responsive matrix genuinely
+   needs to re-point them.
+5. **JS bridges use the same short names.** A value measured/parsed in JS and
+   set as an inline style (dropdown width, popover max height, icon size)
+   is just another component token: `--w`, `--max-h` — never
+   `--dropdown-width`. The component-name prefix bought nothing (a nested
+   dropdown inherits `--dropdown-max-height` exactly as easily as `--max-h`);
+   what actually protects the name is sealing — consume it with a fallback
+   (`var(--max-h, none)`) or declare a default on the root class
+   (`--w: initial` on `.bb-icon`), so an ancestor's value can never inherit
+   in. Cross-component bridges (ListBox publishing `--option-height` for
+   SelectPopover to read) keep a distinctive name per rule 3.
+
+Component tokens are still real affordances: a consumer can retune one
+instance (`<BbTabs style="--list-h: 40px">`) or a whole page scope. They are
+just not global namespace.
+
+## The emphasis ladder
+
+All translucency/tinting goes through **one ladder** of `color-mix()`
+percentages. No other percentages are allowed in a `color-mix()` with a
+semantic color:
+
+| Stop  | Meaning                               | Example                            |
+| ----- | ------------------------------------- | ---------------------------------- |
+| `8%`  | Resting tint fill                     | secondary button bg, tab strip     |
+| `15%` | Hover tint fill                       | secondary/destructive button hover |
+| `25%` | Pressed/selected tint, tinted borders | `aria-pressed` bg, danger border   |
+| `45%` | Disabled foreground, placeholder-ish  | disabled button text               |
+| `60%` | Muted text (= `--bb-text-muted`)      | secondary copy, icons              |
+| `75%` | Strong-but-secondary foreground       | toast icon, alert secondary copy   |
+
+Two composition modes, chosen by context:
+
+```css
+/* Opaque fill — when the element owns its background */
+background: color-mix(in oklab, var(--accent) 8%, var(--bb-panel));
+
+/* Translucent fill — when it must sit on an unknown background */
+background: color-mix(in oklab, var(--accent) 8%, transparent);
+```
+
+Solid (non-tinted) interactive surfaces darken instead:
+
+```css
+&:hover {
+	background: color-mix(in oklab, var(--accent) 90%, black);
+}
+&:active {
+	background: color-mix(in oklab, var(--accent) 80%, black);
+}
+```
+
+### The state recipe
+
+Every interactive component follows the same four-state progression:
+
+| State    | Neutral chrome (default)                 | Tinted variants (danger, selected) | Solid variants | Plus                                                   |
+| -------- | ---------------------------------------- | ---------------------------------- | -------------- | ------------------------------------------------------ |
+| rest     | transparent (or `8%` if filled)          | `8%`                               | `100%`         |                                                        |
+| hover    | `var(--bb-hover)`                        | `15%`                              | `90% + black`  |                                                        |
+| pressed  | `var(--bb-pressed)`                      | `25%`                              | `80% + black`  |                                                        |
+| focused  | hover/pressed values                     | hover values                       | hover values   | `box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring)` |
+| disabled | bg `var(--bb-muted)`, fg at the 45% stop | same                               | same           | `cursor: not-allowed`                                  |
+
+Per principle 5, the tinted column applies only to states that _mean_
+something — danger variants and brand-selected states — never to plain
+interaction chrome. Error variants swap the accent
+(`--accent: var(--bb-danger)`) and the ring (`--bb-ring-danger`) — nothing
+else changes.
+
+## Dark mode
+
+One name per token. `:root`/`.light` declares light values; `.dark`
+re-declares **only the knobs that change** (primary, primary-fg, panel, text,
+border, ring opacity). Component tokens and ladder formulas follow
+automatically because they are declared on the components themselves. The
+old `--x-light`/`--x-dark`/`--x` triple is gone.
+
+One CSS mechanic to respect: **a custom property resolves its `var()`
+references on the element where it is declared, not where it is consumed.**
+That is why the derived color tokens (`--bb-hover`, `--bb-ring`…) are
+declared on _both_ scheme scopes in variables.css — declared only on
+`:root` they would bake in the light knobs and `.dark` would inherit stale
+values. The same applies to consumers: overriding a knob on an arbitrary
+scope (`.brand { --bb-primary: … }`) does not re-derive them — re-apply the
+`light`/`dark` class on that scope, or override the derived tokens directly.
+Root-level theming (what the theme builder emits) is unaffected.
+
+### Animated themes
+
+The color knobs (and `--bb-ring-opacity`) are registered with `@property`
+(typed `<color>`, `inherits: true`), which makes them **animatable** and
+fail-soft (an invalid `--bb-panel` falls back to the registered initial
+value instead of detonating every derivation). Add `.theme-animated`
+(main.css) to the element that carries the scheme class or theme overrides:
+
+```html
+<html class="theme-animated dark"></html>
+```
+
+Scheme toggles and theme-builder changes then crossfade over
+`--bb-transition-medium`; every derived mix re-derives per interpolated
+frame. The class must sit on the same element as the toggle (a transition
+only runs where the property changes), it owns that element's `transition`,
+and the whole subtree repaints while it runs — a deliberate cost for
+toggles/previews, so it stays opt-in. Browsers without `@property` simply
+switch instantly. Component tokens stay unregistered (see "Why not
+`@property`").
+
+This is also the theme-builder contract: a theme is _two small blocks of the
+same ~10 declarations_. Changing `--bb-primary`, `--bb-radius`,
+`--bb-control-h`, `--bb-panel`, `--bb-danger` overhauls the entire library
+with no other edits.
+
+## Safe areas (occupied edges)
+
+Toasts avoid open off-canvas panels: a bottom sheet pushes bottom toasts up,
+a right panel pushes right-anchored toasts left, and so on per edge — in
+step with the panel's slide. The model (implemented in
+`src/composables/useSafeArea.ts`, read by `BbToastRegion`):
+
+- **Claims are "occupied up to X px from this screen edge"**, derived from
+  the off-canvas stack registry (direction + measured size + stack peeks),
+  and composed by `max`, never sum — a claim measures from the screen edge,
+  so nothing double-counts.
+- **Priority is one-directional: sheets claim, toasts yield.** A
+  deliberately-opened surface never moves for an unsolicited notification.
+- **Last-ditch rule, per axis:** when a claim leaves the stack no room
+  (claim + stack extent + margins > viewport), the toast stops yielding on
+  that axis and overlaps the sheet instead.
+- **Settle, not per-frame:** claims update on open/close/resize; a live drag
+  rides on `transform` and never touches the registry.
+- **Edge scalars, not corner lanes:** a bottom claim spans the whole bottom
+  edge. Corner-aware lanes were considered and deferred (every OS insets
+  system ships edge scalars; the over-yielding failure mode is mild).
+- Centered dialogs claim nothing. Adaptive picker sheets currently claim
+  like any off-canvas — revisit if toasts jumping under open selects proves
+  more distracting than overlap.
+
+**The rejected public half (recorded so it isn't re-litigated blind):** an
+earlier design published composed totals as `--bb-safe-*` tokens so consumer
+floating UI (a FAB) could dodge sheets and be "gently pushed" by toasts.
+Dropped because every surface here is _modal_ — the backdrop covers and
+inerts the page, so consumer UI can't be interacted with while a claim
+exists; helping it dodge is pointless. Reopen if either lands: non-modal /
+inline docked panels, or persistent floating consumer UI that should dodge
+_toasts_ (Material's snackbar-pushes-FAB rule — toast claims do interact
+with live UI). The public shape would be `--bb-safe-top/right/bottom/left`
+on `:root` defaulting to `env(safe-area-inset-*)`, with explicit claim
+priorities. The mobile keyboard can join as another bottom claimant with no
+API change.
+
+Top-layer & inertness note: a modal (`showModal()`) makes everything outside
+itself **inert** — and inertness follows DOM ancestry, not paint order, so a
+body-hosted toast region can render above a modal yet be frozen to input.
+BbToast therefore teleports its regions _into_ the top-most open modal
+(BbDialog and BbOffCanvas register with `useTopLayer`), and each region
+re-shows its popover after the move (a DOM move auto-hides popovers; the
+re-promotion also keeps toasts painted above the host). Regions re-home to
+`<body>` when the last modal starts closing. Being top-layer popovers, they
+escape the host dialog's `overflow: hidden` and centering transform.
+
+## Migration from the old tokens
+
+| Old                                                                                                                                                              | New                                                                          |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| primary-tinted hovers/pressed fills (`mix(--bb-primary 8-25%, --bb-panel)`)                                                                                      | `--bb-hover` / `--bb-pressed` (neutral, text-derived)                        |
+| `color-mix(in srgb, …)`                                                                                                                                          | `color-mix(in oklab, …)` everywhere                                          |
+| dialog/offcanvas `--radius-multiplier` ×1.8, literal `6px`/`8px`/`0.375rem` radii                                                                                | `--bb-radius-surface` / `--bb-radius-sm`                                     |
+| `--bb-contrasting`                                                                                                                                               | `--bb-primary-fg`                                                            |
+| `--bb-easing-bezier`                                                                                                                                             | `--bb-ease`                                                                  |
+| `--bb-panel-disabled`, `--bb-input-bg-secondary`                                                                                                                 | `--bb-muted`                                                                 |
+| `--bb-muted-color`, `--bb-hint`, `--bb-placeholder`, `--bb-icon-color`, `--bb-prefix-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-input-compact-h` / `--bb-input-compact-py`                                                                                                                 | `--bb-input-h-compact` / `--bb-input-py-compact`                             |
+| `--bb-label-size` / `--bb-label-inside-size` / `--bb-label-floating-size`                                                                                        | `--bb-label-fs` / `--bb-label-fs-sm` (merged)                                |
+| `--bb-label-line-height` / `--bb-label-inside-line-height`                                                                                                       | `--bb-label-lh` / `--bb-label-lh-sm`                                         |
+| `--bb-overlay-color` + `--bb-overlay-opacity`                                                                                                                    | `--bb-overlay` (one color with alpha)                                        |
+| `--bb-overlay-z-index`                                                                                                                                           | `--bb-z-overlay`                                                             |
+| inline ring `color-mix()` formulas                                                                                                                               | `--bb-ring` / `--bb-ring-danger` (strength knob: `--bb-ring-opacity`)        |
+| `--bb-dialog-px/pt/pb/gap/…`                                                                                                                                     | `--bb-panel-p` (+ local derivations)                                         |
+| `--bb-button-*`, `--bb-tabs-*`, `--bb-checkbox-*`, `--bb-radio-*`, `--bb-switch-*`, `--bb-rating-*`, `--bb-slider-*`, `--bb-table-cell-h`, `--bb-progress-track` | unprefixed locals in each component's CSS                                    |
+| `--bb-table-offset-*`, `--bb-table-fill`, `--bb-table-natural-width` (JS plumbing)                                                                               | unprefixed locals on `.bb-table` (`--offset-*`, `--fill`, `--natural-width`) |
+| `--bb-table-{id}-track-{key}` (parent→nested width bridge)                                                                                                       | `--table-{id}-track-{key}` (distinctive cross-component name, rule 3)        |
+| `--bb-select-option-*`, `--bb-primary-base`, all `--x-light`/`--x-dark` shadows                                                                                  | deleted (dead)                                                               |
+
+## Enforcement
+
+`npm run check:tokens` (see `scripts/check-tokens.mjs`) fails the build when:
+
+- a file _introduces_ a `--bb-*` name outside `variables.css` (re-declaring a
+  known theme token at a scope is fine — that's theming);
+- a `--bb-*` token is consumed but not declared in `variables.css`;
+- a component CSS file consumes an unprefixed token it never declares and
+  without a `var()` fallback (seal-rule violation; tokens that are JS-set or
+  inherited by design are annotated with an `/* @inherit --name */` note);
+- a `color-mix()` over a token is not `in oklab`, or uses a percentage off
+  the ladder (8/15/25/45/60/75 + 80/90; 0/100 anchors allowed).
+  `variables.css` itself is exempt — it hosts the sanctioned derivation
+  formulas (`--bb-muted` at 6%, `--bb-hover` at 2%).
+
+### Why not `@property`?
+
+Registering component tokens (`@property --w { inherits: false; … }`) looks
+like it would replace the seal rule structurally, but it breaks the system:
+
+- `inherits: false` stops the root→descendant flow _inside_ a component
+  (declare on `.bb-base-switch`, consume on `__icon` — that is inheritance),
+  which is also what makes `style="--list-h: 40px"` overrides work. CSS
+  cannot express "inherit within my subtree but not into nested components".
+- A registered property always has a value, so `var(--max-h, none)`
+  fallbacks never fire again — our sealing pattern dies.
+- Registrations are page-global, one meaning per name per document. Short
+  names are deliberate local homonyms here (`--w` is icon width, dropdown
+  width, switch width; one must inherit, one must not), and a library
+  registering `--w`/`--gap`/`--size` tramples the host page's names.
+
+## Open questions (iterate here)
+
+- Should `--bb-danger-fg` exist for a future solid-danger button, or is the
+  tinted destructive variant the only sanctioned form?
+- Is `--bb-control-h` the right master, or should it be `--bb-density` with
+  controls deriving both height and paddings from it?
+- Should `--bb-bg` (page background) exist as a third neutral anchor, so
+  page↔panel contrast is a managed relationship? Currently no consumers.

package/dist/ai/guides/fetch-items-playbook.md

@@ -0,0 +1,161 @@
+---
+title: Fetch Data Items Playbook
+summary: Item-provider signatures as actually invoked per component family, prefill semantics, dependencies-driven refetching, and canonical API request patterns.
+---
+
+# Fetch Data Items Playbook
+
+Use this playbook when `items` is dynamic: pass a **function** instead of an array and the component runs it, tracks loading, and discards stale responses. Static arrays bypass the provider entirely.
+
+Companions: [Options and Items](./options-items-playbook.md) (mapping, seeding), [Coherence](./coherence-playbook.md) (what happens to `modelValue` when fetched options change).
+
+## Provider signatures (as implemented)
+
+### Query-aware — `BbSelect`, `BbSelectPopover`
+
+```ts
+type QueryItemsProvider<T> = (
+	query: string,
+	prefill: boolean,
+	modelValue: any // your v-model: array when `multiple`, single value otherwise
+) => T[] | Promise<T[]>;
+```
+
+`modelValue` is your v-model passed as-is, and the prop declares it `any`: an array in `multiple` mode, the raw model value (possibly `null`) in single mode. Annotate it `any` (or your own model type) and branch on the shape you know you passed.
+
+### Non-query — `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`, `BbTable`
+
+```ts
+type ItemsProvider<T> = (
+	prefill: boolean,
+	modelValue?: any // groups: the v-model; BbTable: the current selection
+) => T[] | Promise<T[]>;
+```
+
+### `BbDropdown` pipeline groups
+
+```ts
+type DropdownGroupItemsGetter = (
+	prefill: boolean,
+	modelValue?: any // the group's selection: array when `multiple`, single value otherwise
+) => any[] | Promise<any[]>;
+```
+
+The same non-query shape as groups and `BbTable`. `modelValue` is the group's current selection — the `<BbDropdownGroup>` `v-model` when there is a companion. Read anything else the request needs (filters, the parent record) from your own refs.
+
+## When each provider runs (verified call matrix)
+
+| Trigger                            | `BbSelect` / `BbSelectPopover`                                                                         | Groups                                      | `BbTable`                     | Dropdown pipeline group            |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------- | ----------------------------- | ---------------------------------- |
+| Initial load                       | `(query, true, modelValue)` — see `prefill` prop below                                                 | `(true, modelValue)` on mount               | `(true, selected)` on mount   | `(true, modelValue)` on first open |
+| User types in the search field     | `(query, false, modelValue)`, debounced `query-debounce-time` (default 500ms)                          | —                                           | —                             | —                                  |
+| `dependencies` (or `items`) change | `(query, true, modelValue)`, debounced `deps-debounce-time`                                            | `(true, modelValue)`, debounced             | `(true, selected)`, debounced | `(true, modelValue)`, debounced    |
+| External `modelValue` change       | `(query, true, modelValue)` — only when the value is incoherent, debounced `model-value-debounce-time` | `(true, modelValue)` — only when incoherent | —                             | —                                  |
+
+**`prefill === false` means exactly one thing, everywhere: _the user typed_.** Every fetch a component starts itself — mount/first-open load, dependency change, coherence refetch — passes `true`, and expects the current selection to stay resolvable in the response. Components without a search field (groups, `BbTable`, dropdown groups) therefore always pass `true`; the argument is in their signature so one provider can be shared with a `BbSelect` and branch identically.
+
+The corollary: **`prefill` cannot tell you an initial load from a dependency refetch.** If a provider must reconcile the selection against a new result set, do it on every call (your provider closes over the filter, so it already knows what it is fetching) — see the `BbTable` pattern below. A dropdown group the user never opens still never fetches.
+
+### The `prefill` prop (`BbSelect` / `BbSelectPopover`)
+
+`prefill` controls **when** the initial load happens: `'interaction'` (default) waits for the first user interaction, `true` loads on mount (SSR-friendly — it also runs in `onServerPrefetch`), `false` is **search-first** — nothing loads until the user types, so opening the panel fetches nothing and the list shows a "search to begin" hint until the first query. Groups and tables always load on mount.
+
+Reach for `false` when the result set is too large or expensive to browse and the query is the only sensible entry point. Note that `false` and `'interaction'` differ **only** on this point: both skip the mount load, but `'interaction'` fetches on open and `false` waits for a query.
+
+Four cases ignore `prefill` and load anyway, because deferring would buy nothing or break a promise you made:
+
+- **`items` is an array** — there is no request to defer, so the selection resolves on mount and coherence can run immediately.
+- **`enforce-coherence` over a non-empty model** — validating a value is impossible without options. An empty model stays lazy (empty is always coherent).
+- **`false` + writing disabled** — `disable-writing` hides the search field, so a search-first load could never be triggered. Falls back to loading on open.
+- **`false` + a non-empty model** — the selection's text has to resolve to render. Falls back to loading (on mount for `BbSelect`, per the upgrade below).
+
+`BbSelect` additionally upgrades any non-empty model to an immediate prefill so the in-field selection can render its text. A standalone `BbSelectPopover` does **not**: with a _provider_ and no `enforce-coherence`, a seeded model stays lazy and resolves on first open. Don't reach for `prefill: true` to fix that — the trigger is yours, so label it from your own state ([BbSelectPopover guide](../BbSelectPopover.md)).
+
+## Runtime guarantees
+
+- **Race protection**: out-of-order responses are discarded — only the latest request may write `items`.
+- **Loading**: the component tracks in-flight requests itself; don't add your own `loading` ref for option fetching.
+- **Errors**: a rejected provider is logged (`console.error`) and the previous items are kept. Surface fetch failures yourself (e.g. `useToast`) if the user must know.
+- **Dependency comparison is value-based** (hashed), not reference-based — `:dependencies="[filters]"` re-fetches only when the content actually changes, no matter how often the array identity does.
+
+## Canonical provider patterns
+
+Query components — branch explicitly and return the **same item shape** from every path:
+
+```ts
+const searchMembers = async (
+	query: string,
+	prefill: boolean,
+	modelValue: string[]
+): Promise<Member[]> => {
+	// Component-initiated: keep the current selection resolvable.
+	if (prefill && modelValue.length) {
+		return api.members.byIds(modelValue);
+	}
+	if (!query.trim()) return []; // project-defined idle behavior
+	return api.members.search({ query });
+};
+```
+
+Non-query components (groups, `BbTable`, dropdown groups) — same shape minus `query`, selection-aware. `prefill` is always `true` here; it exists so the provider can be shared with a select:
+
+```ts
+const fetchRoles = (_prefill: boolean, selected?: string[]) =>
+	api.roles.list({ selectedIds: selected });
+```
+
+`BbTable` has no `enforce-coherence`, so reconciling a selection against a refetched result set is the provider's job. Do it unconditionally — `prefill` won't tell you a refetch from the initial load, and the provider already closes over the filter that changed:
+
+```ts
+const fetchMembers = async (_prefill: boolean, selectedIds?: string[]) => {
+	const rows = await api.members.list({ role: role.value });
+	if (selectedIds?.length) {
+		selected.value = selectedIds.filter((id) => rows.some((r) => r.id === id));
+	}
+	return rows;
+};
+// <BbTable v-model="selected" :items="fetchMembers" :dependencies="[role]" ... />
+```
+
+`BbTable` on a server-driven screen — forward the page state and refetch via `dependencies` (never a manual `watch`):
+
+```ts
+const fetchInvoices = async (): Promise<Invoice[]> => {
+	const res = await api.invoices.list({
+		search: search.value,
+		status: status.value,
+		orderBy: sort.value, // the v-model:sort array, forwarded as-is
+		page: page.value,
+	});
+	totalItems.value = res.total;
+	return res.data;
+};
+// <BbTable :items="fetchInvoices" :dependencies="[search, status, sort, page]" ... />
+```
+
+## Idle-state decisions (query components)
+
+- **Empty query, nothing selected**: return `[]` (explicit empty state) or a default/sample list (guided discovery). Pick one per app and keep it deterministic.
+- **Empty query, values selected**: return at least the selected items (alone or merged with a default list) so the selection is never orphaned. Enabling `stash` on the select keeps already-picked options resolvable across searches without re-including them in every response.
+- Fill the panel states with `loading-text` / `no-data-text` (or the `#loading` / `#no-data` slots).
+
+## What's idiomatic now
+
+- The `prefill` flag means the same thing in every family: `false` only when the user typed. It is **not** "initial load" — a dependency refetch also passes `true`, so never use it to detect one (see the call matrix).
+- Seed multiple-mode `v-model`s with arrays before wiring a provider — multiple components throw on non-array models ([details](./options-items-playbook.md)).
+- Coherence work belongs to `dependencies` + `enforce-coherence`, not to defensive code inside the provider. Coherence is **lazy**: a component that has not loaded once (an untouched `prefill: 'interaction'` select, an un-searched `prefill: false` one, a never-opened dropdown group) ignores dependency changes until it does — don't duplicate it with eager watchers ([details](./coherence-playbook.md)). Any first load ends the quiet period, including a user's first search.
+
+## Anti-patterns
+
+- Ad-hoc `watch(filter, refetch)` when `dependencies` already covers it.
+- Different item shapes across the prefill/search/idle branches.
+- Side effects in the provider beyond the fetch itself (navigation, toasts on success, state writes other than pagination totals).
+- Hand-rolled debouncing around the provider — use `query-debounce-time` / `deps-debounce-time` / `model-value-debounce-time`.
+
+## Validation checklist
+
+- [ ] Provider signature matches the component family (query vs non-query vs dropdown).
+- [ ] `prefill` and the empty query are handled explicitly, with the family's semantics.
+- [ ] All branches return the same item shape.
+- [ ] Field-tied fetching uses `dependencies` (+ `deps-debounce-time`), no manual watchers.
+- [ ] Selected values stay resolvable on component-initiated calls (or `stash` is enabled on selects).