bitboss-ui 3.0.0-beta.21 → 3.0.0-beta.22

package/dist/llms-medium.txt

@@ -50,7 +50,8 @@ pinned to the prerelease channel rather than following it.
    `locale` explicitly if the app is not Italian** — the plugin defaults to
    `'it'` and there is no build-time warning for leaving it unset.
 3. **Choose intent:**
-   - Whole page / flow → hop to **Recipes** below (one platform file only).
+   - Whole page / flow → hop to **Recipes** below (one platform folder: the
+     layout scaffold plus your page recipe).
    - Single control → [Component picker](./component-picker.md), then open
      **one** `../<ComponentName>.md` contract (Usage & Guidelines first).
 4. **Never invent props.** Confirm names in that contract or in
@@ -64,16 +65,27 @@ Folders: `../recipes/vue/`, `../recipes/nuxt/`, `../recipes/inertia/`.
 
 Same page shapes on each platform; only the data/mutation layer differs.
 
-| Intent                               | Recipe file (kebab)                       |
-| ------------------------------------ | ----------------------------------------- |
-| Filterable listing + bulk/peek       | `records-workspace.md`                    |
-| Create/edit form                     | `record-form.md`                          |
-| Inline-edit table / backlog          | `inline-edit-workspace.md`                |
-| Hierarchy drill-down (nested tables) | `ownership-atlas.md` (Inertia only today) |
-| Approvals / triage inbox             | `approvals-inbox.md`                      |
-| Uploads + editable queue             | `upload-center.md`                        |
-| Multi-step wizard                    | `wizard-form.md`                          |
-| Onboarding checklist                 | `onboarding.md`                           |
+**`layout-scaffold.md` is a prerequisite, not an option.** It is the three
+app-owned chrome files — the peek-stack context, the `PageShell` frame and the
+`FloatingBottomPanel` selection dock — that every other recipe's
+`@/components/layout/*` imports resolve to. Open it **with** your page recipe;
+the pair counts as one hop.
+
+| Intent                                    | Recipe file (kebab)                       |
+| ----------------------------------------- | ----------------------------------------- |
+| App chrome every recipe imports (**1st**) | `layout-scaffold.md`                      |
+| Filterable listing + bulk/peek            | `records-workspace.md`                    |
+| Create/edit form                          | `record-form.md`                          |
+| Inline-edit table / backlog               | `inline-edit-workspace.md`                |
+| Hierarchy drill-down (nested tables)      | `ownership-atlas.md` (Inertia only today) |
+| Approvals / triage inbox                  | `approvals-inbox.md`                      |
+| Uploads + editable queue                  | `upload-center.md`                        |
+| Multi-step wizard                         | `wizard-form.md`                          |
+| Onboarding checklist                      | `onboarding.md`                           |
+| ⌘K / Ctrl+K global command palette        | `command-palette.md`                      |
+
+That table is the complete set — every file in each platform folder appears in
+it, so a directory listing (or the MCP `list_recipes`) can add nothing.
 
 No recipe for detail-with-tabs, settings, dashboards, or profile pages —
 compose those from the closest listing/form recipe plus the guides
@@ -83,17 +95,20 @@ compose those from the closest listing/form recipe plus the guides
 
 ## Playbooks (only when the pattern applies)
 
-| Need                                   | Guide                                                 |
-| -------------------------------------- | ----------------------------------------------------- |
-| Tied selects / stale model cleanup     | [coherence-playbook](./coherence-playbook.md)         |
-| Async `items` providers / prefill      | [fetch-items-playbook](./fetch-items-playbook.md)     |
-| `item-text` / `item-value` / disabled  | [options-items-playbook](./options-items-playbook.md) |
-| Table cell edit ownership              | [inline-edit-playbook](./inline-edit-playbook.md)     |
-| Table row → detail (identity cells)    | [agent-contract](./agent-contract.md) § Inline Links  |
-| Peek that drills into related records  | [agent-contract](./agent-contract.md) § Consult-Stack |
-| Icons (`lucide:*`, never invent names) | [icons-policy](./icons-policy.md)                     |
-| Tokens / styling around components     | [design-language](./design-language.md)               |
-| Upgrading from bitboss-ui 2.x          | [migration/v2-to-v3](./migration/v2-to-v3.md)         |
+| Need                                                                  | Guide                                                                                                                                                                                                                                                                              |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tied selects / stale model cleanup                                    | [coherence-playbook](./coherence-playbook.md)                                                                                                                                                                                                                                      |
+| Async `items` providers / prefill                                     | [fetch-items-playbook](./fetch-items-playbook.md)                                                                                                                                                                                                                                  |
+| `item-text` / `item-value` / disabled                                 | [options-items-playbook](./options-items-playbook.md)                                                                                                                                                                                                                              |
+| Table cell edit ownership                                             | [inline-edit-playbook](./inline-edit-playbook.md)                                                                                                                                                                                                                                  |
+| Table row → detail (identity cells)                                   | [agent-contract](./agent-contract.md) § Inline Links                                                                                                                                                                                                                               |
+| Peek that drills into related records                                 | [agent-contract](./agent-contract.md) § Consult-Stack                                                                                                                                                                                                                              |
+| Icons (`lucide:*`, never invent names)                                | [icons-policy](./icons-policy.md)                                                                                                                                                                                                                                                  |
+| Tokens / styling around components                                    | [design-language](./design-language.md)                                                                                                                                                                                                                                            |
+| Theming a whole app / retuning a component                            | [design-tokens](./design-tokens.md) — the two tiers, and why most restyling is a component token, not a `--bb-*` one                                                                                                                                                               |
+| A Tailwind utility on a `Bb*` component does nothing, or half-applies | [installation](./installation-and-plugin-setup.md) § Cascade layers — v4 is layered, we are not by default. It is per PROPERTY: a utility loses only where we declare the same one, and a shorthand like `p-4` can half-apply. `cssLayers: TAILWIND_V4_LAYERS` in the build plugin |
+| Upgrading from bitboss-ui 2.x                                         | [migration/v2-to-v3](./migration/v2-to-v3.md)                                                                                                                                                                                                                                      |
+| Bumping between two v3 prereleases                                    | `npx bitboss-ui changelog --since <your version>` — what BREAKS in the bump; then `check --manifest` for the files it breaks                                                                                                                                                       |
 
 ---
 
@@ -149,6 +164,8 @@ Use this contract before generating any UI code with `bitboss-ui`.
 1. Prefer `Bb*` components in consumer-facing code.
 2. Treat low-level primitives (`Base*`, `BbBase*`, `Common*`, listbox internals) as reference-only — **except `BbBaseButton`**, which is a first-class consumer component: the unstyled navigable primitive for any clickable surface (cards, rows, custom links) that isn't a variant-first `BbButton`.
 3. Use the other reference-only components only when the user explicitly asks for internal composition details.
+4. **Not every `Bb*` export is a component.** `BbTableColumn`, `BbDropdownItem`, `BbTabsItem` and `BbBreadcrumbsItem` are TYPES: they describe the objects you pass to a prop (`columns`, `items`), and they never render. Import one with `import type { … } from 'bitboss-ui'`; writing `<BbTableColumn>` is always wrong. The `types` array in `components.json` lists every one with the prop it belongs to, and `npx bitboss-ui check` says so by name if you slip.
+5. **Two dozen of those types are the ones to reach for.** Each carries a `usage` tier: `api` means it appears in a component's own props or events, so it is what you annotate the value you build — `get_component` returns the list for the component you asked about. `wrapper` (`BbButtonProps` / `BbButtonEvents` / `BbButtonSlots` and siblings) is only for wrapping one of our components in one of yours, and `advanced` is everything left over — contexts, directive values, config shapes, the `…VariantType` unions. The tier is decided by that one rule and nothing else, so do not sort by what a name sounds like: `AlertVariantRegistry` reads like a registry but is `api`, because `BbAlert`'s `variant` prop is typed by it. Only `api` entries carry `usedBy`; if a type has one, it is `api`. Types the library does NOT export are that way on purpose: a size or a trigger is a string literal you write directly (`size="lg"`), so there is no name to import and none is missing.
 
 ## Setup-First Rule
 
@@ -250,7 +267,7 @@ For components accepting `items`:
 
 ## Icons Rule
 
-External-provider-first: prefer iconify provider icons — default set `lucide:*` — sourced from `@iconify-json/*` packages the consumer installs separately (`npm i -D @iconify-json/lucide`). Use `local:*` SVGs only for brand-specific art placed in the configured `iconDir`. Only reference icons from installed providers or existing local files — **never invent icon names**. Full workflow: [Icons Policy](./icons-policy.md).
+External-provider-first: prefer iconify provider icons — default set `lucide:*` — sourced from `@iconify-json/*` packages the consumer installs separately (`npm i -D @iconify-json/lucide`). Use `local:*` SVGs only for brand-specific art placed in the configured `iconDir`. Only reference icons from installed providers or existing local files — **never invent icon names**. Provider icons ship only when written as a `prefix:name` literal somewhere in the project (any file type, PHP included) or listed in the plugin's `iconWhitelist`; the same rule applies in dev, and a name that does not resolve renders a placeholder and logs an error instead of throwing. Full workflow: [Icons Policy](./icons-policy.md).
 
 ## Variants Rule
 
@@ -291,8 +308,9 @@ These overlays also return focus to their trigger element on close, by documente
 
 **Mount exactly one `<BbToast />` and one `<BbConfirm />` for the whole application, at the app root** — `App.vue` under Vue, `app.vue` under Nuxt, the `createInertiaApp` render root under Inertia. Never one per page, per route, per layout branch or per component; a page that calls `toast()` or `confirm()` mounts nothing.
 
-- **Zero hosts** — `toast(...)` enqueues silently and the message never expires (the dismiss timer lives inside the host); `await confirm(...)` never settles, so the caller hangs. Neither throws.
-- **Two hosts** — every toast and every dialog renders once per host: duplicated DOM, duplicated `role="status"` live regions, duplicated focus traps. `BbToast` warns in DEV; `BbConfirm` does not warn at all.
+- **Zero hosts** — `toast(...)` enqueues and the message never expires (the dismiss timer lives inside the host); `await confirm(...)` never settles, so the caller hangs. Neither throws. Both warn once per process in DEV.
+- **Two hosts** — every toast and every dialog renders once per host: duplicated DOM, duplicated `role="status"` live regions, duplicated focus traps. Both warn in DEV, naming the host count.
+- **A host that mounts and then unmounts also warns** (since 2026-09-09). This is the failure mode of mounting a host anywhere but the app root: one in a layout works right up until a route renders outside that layout, and the promise then hangs forever. The warning is **deferred by one second**, not immediate, because a late-mounting host renders the pending dialog and settles the promise normally — so a host that unmounts and remounts across a route change is not a failure and stays quiet. What the warning means is "one second later, still nothing to render this".
 
 Standalone examples in this repo (`src/components/*/examples/*.vue`, stories, dev showcases) mount a host inline **because each one is a self-contained root with no application around it**. That is a property of the example harness, not a pattern to copy — in a real app the host is already mounted at the root, and the page must not mount a second one.
 
@@ -305,7 +323,7 @@ Boolean props default to `false` so the bare `<Comp foo>` shorthand turns the fe
 
 These are the only intentional default-`true` booleans; anywhere else, `true` default is a bug (`check-api` flags it).
 
-**Arrows are tooltip-only in v3.** `hideArrow` / `showArrow` / `arrowPadding` were removed from `BbPopover`, `BbSelectPopover`, `BbColorPalette`, and `BbDropdown` (leftover bindings land silently in `$attrs`). Only `BbTooltip` keeps `hideArrow` (default `false` — arrow shown). See [bb-popover.md](./migration/components/bb-popover.md).
+**Arrows are tooltip-only in v3.** `hideArrow` / `showArrow` / `arrowPadding` were removed from `BbPopover`, `BbSelectPopover`, `BbColorPalette`, and `BbDropdown` (leftover bindings land silently in `$attrs`). `BbTooltip` keeps **both** — `hideArrow` (default `false`, so the arrow shows) and `arrowPadding` (default `10`). See [bb-popover.md](./migration/components/bb-popover.md).
 
 ## Testing Against bitboss-ui
 
@@ -616,7 +634,7 @@ Two runtime options control CSS:
 
 Guaranteed order when injected: **reset → library styles → all other stylesheets**, so app-local CSS can always override the library.
 
-`resetCss` stays opt-in because Tailwind projects already ship Preflight — a second reset is usually unnecessary.
+`resetCss` stays opt-in because Tailwind projects already ship Preflight — a second reset is usually unnecessary. A reset of SOME kind is a prerequisite of the components, not a nicety: every size in the component sheets is written for `border-box`, and native controls and fieldsets are expected to arrive without their browser chrome. Preflight provides all of that; on a page with neither Preflight nor this file, a selectable table's fieldset grows a groove border and a 36px cell renders 49px. `reset.css` is optional only in the sense that you may bring your own — the component test suite runs against this file, with no Tailwind on the page.
 
 **Tailwind v4 cascade layers vs. scoped `<style>`:** Tailwind v4's `@import
 'tailwindcss'` puts every utility class in `@layer utilities`. A Vue SFC's
@@ -685,23 +703,193 @@ Leave `resetCss` at `false` here — Preflight already reset everything.
 Nothing else about the plugin changes; `injectStyles` controls only whether the
 library injects its own `<style>`.
 
-**Tailwind v4 apps do not need this** — source order does not decide their ties
-at all. `@import 'tailwindcss'` puts Preflight in a real `@layer base` and
-utilities in `@layer utilities`, and layered rules lose to unlayered rules of
-equal specificity **regardless of source order**. `dist/styles.css` declares no
-`@layer`, so the library wins those ties wherever it is injected: leave
-auto-injection on. The same mechanic bites the other way, and silently — a
-utility cannot re-size a Bb component either. `<BbButton class="h-12 px-6">`
-loses to the library's own `.bb-button { height: var(--h); padding-left:
-var(--px); padding-right: var(--px) }` (equal specificity, unlayered), with no
-warning from anything. Size Bb components through their props and tokens, never
-utilities. (Same trap as the scoped-`<style>` case above, one level up.)
+**Tailwind v4 apps do not need `injectStyles: false`** — source order does not
+decide their ties at all. `@import 'tailwindcss'` puts Preflight in a real
+`@layer base` and utilities in `@layer utilities`, and **a layered rule loses to
+an unlayered one regardless of source order**. Leave auto-injection on and use
+`cssLayers` below.
+
+### Cascade layers — the switch that decides who wins a tie
+
+The cascade weighs **layer before specificity**. Unlayered CSS beats every
+layered rule, however specific the layered one is. That one fact means there is
+no single correct default, so the option is opt-in and you tell the library
+where it sits:
+
+| your CSS                                     | `cssLayers`                         | who wins a tie                                 |
+| -------------------------------------------- | ----------------------------------- | ---------------------------------------------- |
+| no layers (plain CSS, Tailwind v3)           | unset (default)                     | source order — library first, so your CSS wins |
+| Tailwind v4, or any layered CSS              | your full order, ours in it (below) | exactly what your array says                   |
+| no layers, and you want to override anything | `['bitboss-ui']`                    | you do, always                                 |
+
+The value is always an array: your complete layer order with `bitboss-ui` in
+it, and `bitboss-ui-reset` immediately before it **when `resetCss` is on**.
+With the reset off you may list `bitboss-ui-reset` anyway — an unused layer is
+just empty — so the constant below works in every project, and you do not need
+to know that Tailwind carries a reset of its own to use it.
+
+**We do not ask you to add an `@layer` line to your stylesheet.** The plugin
+injects the declaration ahead of its own rules, and a layer's position is fixed
+by its first mention — so the order you configure is the order you get.
+
+#### Tailwind v4
+
+```ts
+// vite.config.ts — or the `bitboss` key in nuxt.config.ts
+import { bitbossUi, TAILWIND_V4_LAYERS } from 'bitboss-ui/vite';
+
+bitbossUi({
+	iconDir: './assets/icons',
+	cssLayers: TAILWIND_V4_LAYERS,
+});
+```
+
+`TAILWIND_V4_LAYERS` is
+`['theme', 'base', 'bitboss-ui-reset', 'bitboss-ui', 'components', 'utilities']`:
+Tailwind's own order with ours **after `base`**, so Preflight cannot outrank
+the components, and **before `utilities`**, so `<BbButton class="px-6">`
+works. Prefer the constant to the literal — a six-item array that has to be
+exactly right is the kind of thing a typo turns into a silent loss of every
+tie.
+
+#### Tailwind v3, or plain CSS
+
+Leave `cssLayers` unset. v3 emits unlayered CSS, and two unlayered stylesheets
+are decided by source order — which auto-injection already puts in your favour.
+
+#### Tailwind v3 — making utilities win anyway (opt-in)
+
+v3 has no native layers of its own, but you can put its output into real ones
+by wrapping the directives yourself. This is the shape PrimeVue documents, and
+it is the only way to get v4's behaviour on v3:
+
+```css
+/* your Tailwind entry, e.g. app.css */
+@layer tailwind-base, bitboss-ui-reset, bitboss-ui, tailwind-utilities;
+
+@layer tailwind-base {
+	@tailwind base;
+}
+
+@layer tailwind-utilities {
+	@tailwind components;
+	@tailwind utilities;
+}
+```
+
+```ts
+bitbossUi({
+	iconDir: './assets/icons',
+	cssLayers: [
+		'tailwind-base',
+		'bitboss-ui-reset',
+		'bitboss-ui',
+		'tailwind-utilities',
+	],
+});
+```
+
+Both halves are required and they must agree: the CSS puts Tailwind's expanded
+output INTO the layers, and `cssLayers` puts us between them. Verified against
+a real v3 build — `.p-4` on a `Bb*` component wins, and Preflight no longer
+outranks the components.
+
+This is the one case where you write an `@layer` line yourself, because the
+line has to wrap YOUR directives and we cannot reach them. Ours is emitted as
+usual; the two declarations name the same order, and a layer's position is
+fixed by its first mention, so they agree rather than fight.
+
+#### "I just want to override things and not think about it"
+
+```ts
+bitbossUi({
+	iconDir: './assets/icons',
+	cssLayers: ['bitboss-ui'], // ['bitboss-ui-reset', 'bitboss-ui'] with resetCss: true
+});
+```
+
+Declares our layer(s) and nothing else. All of your unlayered CSS then wins,
+whatever its specificity.
+
+> **Do not use this if your app loads a baseline stylesheet.** A reset is
+> unlayered CSS made of element selectors, which is the exact combination this
+> value inverts: `normalize.css`, your own `baseline.css`, or **Tailwind v3's
+> Preflight** stop losing to our components on specificity and start outranking
+> them outright. Measured on a real v3 build, a component rule of
+> `margin: 5px` renders as `0px` — Preflight's `margin: 0` wins. The library
+> does not look "overridable", it looks broken: controls lose their height,
+> padding and borders, and nothing warns. If you want utilities to win on v3,
+> use the layer hack above, which keeps the reset below us where it belongs.
+
+Two further consequences: your global element rules (`button {}`, `input {}`)
+now outrank component internals too — and this is the **wrong** value for a
+layered app, because your own layers are declared later and land above ours,
+Preflight included. A Tailwind v4 app uses the array above.
+
+#### What "the utility loses" actually means
+
+Not "utilities stop working on `Bb*` components". The cascade picks a winner
+**per property**, so a layered utility loses only where we declare that exact
+property on that element. Anything we leave alone is uncontested and simply
+applies. Measured against the shipped sheet, v4 with `cssLayers` unset:
+
+| on a `BbButton` | outcome          | why                                   |
+| --------------- | ---------------- | ------------------------------------- |
+| `w-20`          | applies          | we never declare `width`              |
+| `h-12`          | applies          | we declare `min-height`, not `height` |
+| `m-4`           | applies          | we never declare `margin`             |
+| `p-4`           | **half applies** | top/bottom land, left/right lose      |
+| `px-6`          | no effect        | we declare both padding longhands     |
+| `rounded-lg`    | no effect        | we declare `border-radius`            |
+| `text-lg`       | no effect        | we declare `font-size`                |
+| `gap-2`         | no effect        | we declare `gap`                      |
+
+**The shorthand row is the one that hurts.** A clean loss is legible: you write
+`px-6`, nothing moves, you go looking. `p-4` expands to four longhands, we
+declare only the horizontal two, so their vertical padding applies while our
+horizontal survives — a component nobody designed, with no signal that anything
+was overridden.
+
+So `cssLayers` does not turn utilities from broken into working. It turns them
+from a per-property lottery into "always wins". **Predictability is the
+feature, not capability** — and it is why the fix is worth taking even in an app
+where the handful of utilities you tried happened to land.
+
+#### Symptoms and what they mean
+
+| what you see                                                          | cause                                                                           | fix                                                 |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------- |
+| a Tailwind utility on a `Bb*` component does nothing, or half-applies | v4 utilities are layered, the library is not — see the per-property table above | `cssLayers: TAILWIND_V4_LAYERS`                     |
+| every component lost its background / border                          | you listed only our two layers in a layered (v4) app                            | `cssLayers: TAILWIND_V4_LAYERS`                     |
+| your global `button {}` reset suddenly restyles component internals   | you listed only our two layers in an unlayered app                              | that is what it does — use the full order, or unset |
+| components lost their height / padding / borders on **v3**            | you listed only our layers while a reset or Preflight is unlayered              | use the v3 layer hack, or leave `cssLayers` unset   |
+| nothing changed after setting `cssLayers`                             | the option lives in the **build plugin**, not in `app.use()`                    | set it in `vite.config.ts` / `nuxt.config.ts`       |
+| build fails naming a layer                                            | your array omits `bitboss-ui` (or the reset layer with `resetCss: true`)        | the error prints a working array — copy it          |
+
+A malformed value **fails the build**, never the browser: a wrong layer order is
+invisible at runtime, because the CSS still parses and merely loses every tie.
+
+#### The one thing layers do not fix
+
+Layers decide ties between rules. They do not help when a component's own
+inline `style` sets a property, because inline styles beat every layer. Where a
+component needs to be positioned or sized by its parent, it exposes a CSS
+variable, and that hook works in every configuration:
+
+```html
+<!-- takes the row's slack; works on v3, v4, layered or not -->
+<BbBreadcrumbs class="min-w-0" style="--flex-grow: 1" :items="crumbs" />
+```
+
+Reach for the documented variable before reaching for a utility.
 
 ## 6) Icons
 
-- `iconDir` (required) is scanned recursively for `.svg` files; each file becomes `local:<basename>`.
-- Provider icons (`lucide:pencil`, `mdi:home`, …) require the matching `@iconify-json/<prefix>` package installed in the consumer app. In dev, every `prefix:name` the registry does not know produces a Vite error overlay with the fix: a mistyped name inside an installed set gets a "did you mean …?" hint, and an uninstalled prefix gets the list of installed sets plus the `npm install -D @iconify-json/<prefix>` command (the optional `@iconify/collections` peer only sharpens that wording, see [Install](#1-install)). A missing `local:` icon is a missing file in `iconDir` and surfaces as `BbIcon`'s runtime error naming it. Production builds report none of this — the scan simply drops what does not resolve, so a wrong name fails at runtime there.
-- Production builds bundle **only statically referenced** provider icons — write icon names as literal strings (`icon="lucide:trash-2"`), never assemble them dynamically.
+- `iconDir` (required) is scanned recursively for `.svg` files; each file becomes `local:<basename>`. **`local:` ships everything.**
+- Provider icons (`lucide:pencil`, `mdi:home`, …) require the matching `@iconify-json/<prefix>` package installed in the consumer app. **Providers ship only what is scanned or whitelisted**: the plugin reads the whole project as bytes — every file under the Vite root, PHP and Blade and JSON and SQL included — for `<prefix>:<name>` literals of the installed sets, and emits one lazy chunk per name that resolves. Skipped: gitignored paths (every `.gitignore` level), `node_modules`, `vendor`, `storage`, the build `outDir`, hidden paths, binaries, and `iconsScanner.exclude` globs; `iconsScanner.include` adds locations. The scan is cached by content hash under `node_modules/.cache/bitboss-ui/`, runs on 2–4 worker threads once a project passes ~1500 files (a cold scan is disk-bound, and the threads let a slow disk serve reads in parallel — roughly 0.2 s for 10k files on a laptop), prints one line (file count, elapsed, threads) after a cold scan, and stays silent when warm.
+- **This holds in dev exactly as in prod.** Dev registers the same scanned-plus-whitelisted set, re-scans a file on every save, and hot-updates the registry — a new literal renders without a restart, and a name that is neither scanned nor whitelisted fails on first render in dev instead of after deploy.
+- **Names the scanner cannot see** — composed at runtime, stored in a database, chosen in an admin UI — go in `iconWhitelist` (exact names or globs). An entry that resolves in no installed set fails the build with the actionable message.
+- **A name that does not resolve renders the built-in placeholder** (a question mark in a circle, sized and coloured like the icon it replaces, with `data-bb-icon-missing="<name>"`) and logs one `console.error` per name per page load, in both environments; dev also raises the Vite error overlay. The message is the fix: a mistyped name inside an installed set gets a "did you mean …?" hint, a real icon nobody wrote as a literal is told to use `iconWhitelist`, and an uninstalled prefix gets the list of installed sets plus the `npm install -D @iconify-json/<prefix>` command (the optional `@iconify/collections` peer only sharpens that wording, see [Install](#1-install)). A missing `local:` icon names the `.svg` that is not in `iconDir`. `BbIcon` never throws for a missing name, so the surrounding tree stays mounted.
 - The plugin also writes `node_modules/.bitboss-ui/local-icons.json` and (in dev, unless `vscodeSettings: false`) wires `.vscode/settings.json` so the Iconify editor extension previews local icons.
 
 Policy for choosing icons: [Icons Policy](./icons-policy.md).
@@ -712,7 +900,37 @@ Options are the same for `bitboss-ui/vite` and the `bitboss` key in Nuxt.
 
 ### `iconDir: string` (required)
 
-Path to local SVG icons, absolute or relative to project root. Scanned recursively; file basename (without extension) becomes the icon name, addressable as `local:<name>`.
+Path to local SVG icons, absolute or relative to project root. Scanned recursively; file basename (without extension) becomes the icon name, addressable as `local:<name>`. Every file in it ships.
+
+### `iconsScanner?: { include?: string[]; exclude?: string[]; maxFileSize?: number }`
+
+Tunes the provider-icon source scan (see [Icons](#6-icons)). All three are optional and additive to the defaults; the root is always scanned.
+
+- `include` — extra paths or globs scanned **in addition** to the Vite root: a vendor package that carries icon names, a directory outside the root (`'../shared/ui'`, `'vendor/acme/ui-kit/**/*.php'`). Relative entries resolve against the root. An entry is explicit, so the built-in skips (`vendor`, hidden segments, `.gitignore` files above it) do not apply to the entry itself — only to what lies beneath it. The Nuxt module adds the project `rootDir` here automatically, because Nuxt roots Vite at `app/`.
+- `exclude` — globs removed from the scan on top of the defaults, in gitignore syntax, relative to the root (`['resources/legacy/**', '**/*.sql']`).
+- `maxFileSize` — bytes. Exists only so a database dump is not read into memory; the default is 256 MiB, so a real source file is never skipped for its size.
+
+```ts
+bitbossUi({
+	iconDir: './resources/icons',
+	iconsScanner: {
+		include: ['vendor/acme/ui-kit/src'],
+		exclude: ['database/dumps/**'],
+	},
+});
+```
+
+### `iconWhitelist?: string[]`
+
+Provider icons that **always** ship, scanned or not — exact names (`'tabler:crown'`) and globs (`'tabler:calendar-*'`, expanded against the installed set). This is the home of every name the scanner cannot see as a literal: composed at runtime, read from a database, picked by an admin. An entry that resolves in no installed set — a typo, an uninstalled prefix, a glob matching nothing — **fails the build** with the same actionable message the dev overlay shows for a missing icon. `local:` names never belong here (they all ship already).
+
+```ts
+bitbossUi({
+	iconDir: './resources/icons',
+	// `icon` is stored per category in the database; the admin picks from these.
+	iconWhitelist: ['tabler:category', 'tabler:tag', 'tabler:calendar-*'],
+});
+```
 
 ### `injectStyles?: boolean` (default: `true`)
 
@@ -722,6 +940,28 @@ Auto-inject the library stylesheet at runtime. If `false`, you must `import 'bit
 
 Inject the reset stylesheet (always ordered before the library stylesheet). Keep `false` and import `bitboss-ui/reset.css` if you prefer explicit control.
 
+### `cssLayers?: string[]` (default: unset)
+
+Wraps the library's stylesheets in CSS cascade layers and declares where they
+sit. Opt-in. Full guide with copy-paste blocks in §5 → _Cascade layers_.
+
+The value is your app's **complete** layer order with `bitboss-ui` in it, and
+`bitboss-ui-reset` before it when `resetCss` is on (listing it anyway is fine).
+Unset means unlayered, today's behaviour, right for plain CSS and Tailwind v3.
+
+```ts
+import { bitbossUi, TAILWIND_V4_LAYERS } from 'bitboss-ui/vite';
+
+// Tailwind v4 — ['theme', 'base', 'bitboss-ui-reset', 'bitboss-ui', 'components', 'utilities']
+cssLayers: TAILWIND_V4_LAYERS;
+// no layers of your own, and you want to override anything
+cssLayers: ['bitboss-ui']; // ['bitboss-ui-reset', 'bitboss-ui'] with resetCss: true
+```
+
+You do not add an `@layer` line to your own CSS — the plugin emits the
+declaration ahead of its rules. An invalid array, or a boolean, fails the build
+with a message containing a working replacement.
+
 ### `injectDirectives?: boolean` (default: `true`)
 
 Registers the global `v-bb-tooltip`, `v-bb-dropdown`, `v-bb-color`, `v-bb-date` and `v-bb-time` directives when the runtime plugin installs — all five, on both the Vue and the Nuxt runtime. Each registration is skipped if the app already declared a directive under that name, so disable the option only if you want none of them.
@@ -959,10 +1199,12 @@ when the contract cannot answer the question — the usual case is rebuilding
 chrome around a control the library does not ship, since the class names such a
 template emits are already styled by the public `bitboss-ui/styles.css`.
 
-Add `--mcp` to also register a live MCP server (`npx bitboss-ui@<installed version> mcp`, pinned so npx can never fetch a different version from the registry) the harness launches on demand — it merges the entry (never overwriting other servers) into `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (VS Code / Copilot), and `~/.codeium/windsurf/mcp_config.json` (Windsurf). **Windsurf's config is global** — it has no per-project scope, so registering it affects every project on the machine; that is why only the explicit `ai-init --mcp` command writes it, while the plugin's `mcp: true` dev-server flag (§7) auto-registers the project-scoped harnesses only. Install the server's optional peers first — `npm i -D @modelcontextprotocol/sdk zod` — they are not dependencies of the library (~12 MB used only by the MCP server); the command warns if they are absent. **`--mcp` is optional and skipping it loses you nothing but the transport** — the server only reads the `dist/ai/` files listed above, so run plain `ai-init` and let the agent read that directory if you cannot add the peers (see `mcp?: boolean` in §7).
+Add `--mcp` to also register a live MCP server (`node node_modules/bitboss-ui/bin/bitboss-ui.mjs mcp` — the installed binary, not `npx`, so it can never fetch from the registry, its optional peers resolve in your project rather than in an npx cache, and it cannot drift behind an upgrade) the harness launches on demand — it merges the entry (never overwriting other servers) into `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (VS Code / Copilot), and `~/.codeium/windsurf/mcp_config.json` (Windsurf). **Windsurf's config is global** — it has no per-project scope, so registering it affects every project on the machine; that is why only the explicit `ai-init --mcp` command writes it, while the plugin's `mcp: true` dev-server flag (§7) auto-registers the project-scoped harnesses only. Install the server's optional peers first — `npm i -D @modelcontextprotocol/sdk zod` — they are not dependencies of the library (~12 MB used only by the MCP server); the command warns if they are absent. **`--mcp` is optional and skipping it loses you nothing but the transport** — the server only reads the `dist/ai/` files listed above, so run plain `ai-init` and let the agent read that directory if you cannot add the peers (see `mcp?: boolean` in §7).
 
 For a human-in-the-loop (and agent) safety net, add the `bitboss-ui/eslint-plugin` flat-config plugin (`...bitbossUi.configs.recommended`) so unknown/removed `Bb*` props surface as ESLint errors in the editor and CI — the same manifest checks as `bitboss-ui check`, reusing your `eslint-plugin-vue` parser. Real HTML attributes fall through untouched; escape hatches are the standard `<!-- eslint-disable-next-line bitboss-ui/no-unknown-attributes -->` and the rule's `allowAttributes` / `allowComponents` options. **`eslint --fix` also auto-migrates deprecated v2 props** (renames, boolean-polarity inversions like `allowWriting`→`disableWriting`, value remaps like BbToast `placement`→`position`, and deletion of inert removed props); structural migrations that need a slot/directive/CSS are reported but left by hand. One deliberate boundary: the rule's "did you mean `<prop>`?" hints for a mistyped/unknown attribute are advisory message text, not fixes — `eslint --fix` (including an unattended run in a pre-commit hook) never applies them; only the registered v2→v3 migrations above are auto-fixed. A guess applied blind across a codebase would be a silent behavior change, so acting on a hint is always a per-site decision. **This library is TS-first (recipes ship `<script setup lang="ts">`, some with `generic="T"`), so wire `@typescript-eslint/parser` for both `.ts` and `.vue` files** — without it `vue-eslint-parser` throws a `Parsing error` on those files, which means no rule (including `no-unknown-attributes`) runs on them at all. See the README "ESLint plugin" section for the full config snippet (both parser blocks + the `npm i -D @typescript-eslint/parser` line) and the fix table. `recommended` also enables `bitboss-ui/no-active-class-on-root-link`: `active-class` on a link-capable `Bb*` component (`BbButton`/`BbBaseButton`/`BbBadgeButton`) matches by path PREFIX, so a link whose target is the literal root (`href="/"` / `to="/"`) reads as "active" on every URL — the rule flags that combination and points you at `exact-active-class` instead.
 
+Two rules in `recommended` are `warn` rather than `error`, because each describes markup that may be deliberate. `bitboss-ui/no-unknown-event` flags an `@event` the component does not emit (it falls through to the root element, so it may be a considered native listener). `bitboss-ui/no-unknown-token` flags a bare `var(--bb-…)` naming a token the installed package does not declare, in a `<style>` block or a static `style="…"` attribute — an undefined custom property is invalid-at-computed-value-time, so CSS discards the **entire declaration** and the rule silently does nothing at runtime. Supplying a fallback (`var(--bb-canvas, #f8fafc)`) is defined behaviour and is never reported; `allowTokens` exempts names you define yourself. The token list is read from the `dist/styles.css` you installed, so it cannot claim a token is invented when your version declares it, and with no stylesheet present the rule stays silent. Before reaching for a `--bb-*` name at all, re-read the two tiers above: a name the library does not declare usually means the knob you want is a **component** token, not a gap in the global set. `bitboss-ui check` carries two further advisory hints that are deliberately not ESLint rules — the hand-rolled avatar and spinner detectors — because both are guesses, and a lint rule that fires on correct code teaches people to ignore all of them.
+
 **The manifest ships with the package** — `dist/ai/components.json` is inside
 the tarball, and the rules resolve it relative to their own file, so a normal
 install needs no configuration. If it ever cannot be read (a broken install, a
@@ -971,6 +1213,18 @@ nothing), the rules cannot check anything: they now **warn once** saying they
 are inactive rather than passing silently. Pass `failClosed: true` to a rule's
 options if you would rather CI stop than under-check.
 
+Alongside `components` the manifest carries a `types` array: the public TYPE
+exports (`BbTableColumn`, `BbDropdownItem`, …), each with the component and prop
+it is written on. That is how `check`, the ESLint rules and the MCP server tell
+a type used as a tag from a typo and from a component your app owns — three
+cases that used to share one message and one (usually wrong) remedy.
+
+**`allowComponents` is a per-tag off switch, not the suppression of one
+message.** An allowlisted name is skipped whole: no unknown-component finding,
+and no prop, event, v-model or slot check on that tag, permanently. Right for an
+app-owned `<BbRichEditor>`; wrong for everything else — never reach for it to
+quieten a `Bb*` name the library itself exports.
+
 `recommended` also enables **`bitboss-ui/no-reverse-false`**, which covers the one v2 break a rename table cannot: `reverse` on `BbCheckbox` / `BbRadio` / `BbSwitch` kept its NAME and inverted its MEANING in v3, so the v2 spelling `:reverse="false"` (control on the right) is now a no-op that renders the control on the LEFT. Nothing else catches it — it is a declared prop, correctly typed, holding its own default value — and it cannot be expressed as a rename, because a rename entry is keyed by prop name and would rewrite the legitimate v3 spellings too. The rule flags only a LITERAL `:reverse="false"` (a dynamic `:reverse="isRtl"` that evaluates false is left alone) and offers both corrections as editor suggestions; pass `{ assumeV2: true }` to promote the v2-intent rewrite to a real `--fix` for a bulk sweep, then remove it — the two readings produce opposite layouts, so it must never be on by default. See [the migration guide](../guides/migration/components/bb-checkbox.md).
 
 It also enables `bitboss-ui/require-partner-prop`: an opt-in prop set without its documented required partner — BbTable `keyboard-navigation` / `v-model:highlighted` without `row-class` (the shipped tint says "current row"; `row-class` says why, and is how you override it), or `loading-text` without `:loading` bound — compiles and mounts clean and just does nothing; the rule names the missing partner and quotes why.
@@ -1224,24 +1478,29 @@ a composable you want is not in this corpus's `composables/` folder — it is no
 here.** Check this list before inventing a name; if the need is genuinely absent,
 compose it or write it yourself.
 
-| Assumed component or composable                                | Reality                                                                                                                                                                                                                                                                                                                                                                                                       |
-| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BbColumnManager` — show/hide/reorder columns                  | Does not exist as a component. Order is `v-model:order` on `BbTable` (an array of keys any panel can write; `reorderable` adds the built-in header drag + keyboard handle); visibility is `hidden: true` on the column definition (the column stays declared and keeps its slot in the order; header slots get a `hideColumn()` that fires `hide:column`). Compose the panel from `BbPopover` + `BbCheckbox`. |
-| `BbKanban` / drag-and-drop board                               | Does not exist. There is no reusable DnD primitive in the library (`BbTable`'s header drag is internal to the table) — compose the board from `BbTable` (a table/list view of the same data) or hand-roll the drag-and-drop interaction yourself.                                                                                                                                                             |
-| `BbModal`                                                      | It is [BbDialog](../BbDialog.md).                                                                                                                                                                                                                                                                                                                                                                             |
-| `BbDrawer` / `BbSheet`                                         | It is [BbOffCanvas](../BbOffCanvas.md).                                                                                                                                                                                                                                                                                                                                                                       |
-| `BbCombobox` / `BbAutocomplete`                                | It is [BbSelect](../BbSelect.md) / [BbSelectPopover](../BbSelectPopover.md) — search is built in, see `disable-writing`.                                                                                                                                                                                                                                                                                      |
-| `BbToggle` / `BbToggleGroup`                                   | It is [BbButton](../BbButton.md) with `v-model` (+ `true-value` / `false-value`), which owns `aria-pressed` and the active class.                                                                                                                                                                                                                                                                             |
-| `TagChip` / colored, read-only tag chip                        | It is [BbBadge](../BbBadge.md) — [BbTag](../BbTag.md) is a tags-_input_ only, not a display component. Use `BbBadge` with a registered `soft-*` variant for a fixed palette, or a one-off `--bg`/`--color` override per row for arbitrary/data-driven colors (BbBadge.md § One-off colors) — not a registered variant per distinct color.                                                                     |
-| `BbTab` (singular)                                             | The consumer API is [BbTabs](../BbTabs.md) / `BbTabsRoot`. `BbTab` appears only as the **v2 "before" side** of the migration diffs.                                                                                                                                                                                                                                                                           |
-| `BbCard`                                                       | Does not exist — a card is a `<div>` with tokens. See [design-language](./design-language.md).                                                                                                                                                                                                                                                                                                                |
-| `BbList` / `BbListItem` / `BbDescriptionList`                  | Do not exist — a list row is an `<li>` with tokens, and [BbBaseButton](../BbBaseButton.md) makes the whole row navigable. See the note under Data Display.                                                                                                                                                                                                                                                    |
-| `useLiveFeed` / any polling or cross-tab feed helper           | Does not exist, and neither does a cross-tab helper — `useBroadcastChannelInstance` was removed (cross-tab messaging is not a UI concern). Use `useBroadcastChannel` from `@vueuse/core`; the polling and the merge are yours.                                                                                                                                                                                |
-| `BbStepper` / `BbWizard`                                       | Does not exist as a component; the wizard-form recipe composes one.                                                                                                                                                                                                                                                                                                                                           |
-| `BbSkeleton` (standalone)                                      | Only `BbTable` ships skeletons, via the column `skeleton` field.                                                                                                                                                                                                                                                                                                                                              |
-| `BbCommand` / command palette                                  | Does not exist. Compose `BbDialog` + `BbSelectPopover`.                                                                                                                                                                                                                                                                                                                                                       |
-| `BbCalendar` (month / scheduling view)                         | Does not exist. [BbDatePicker](../BbDatePicker.md) is a picker, not a calendar surface.                                                                                                                                                                                                                                                                                                                       |
-| `BbChart` / `BbGraph`, `BbCarousel`, `BbTimeline`, `BbDivider` | Do not exist. No charting, carousel or timeline primitive ships here.                                                                                                                                                                                                                                                                                                                                         |
+| Assumed component or composable                                | Reality                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbColumnManager` — show/hide/reorder columns                  | Does not exist as a component. Order is `v-model:order` on `BbTable` (an array of keys any panel can write; `reorderable` adds the built-in header drag + keyboard handle); visibility is `hidden: true` on the column definition (the column stays declared and keeps its slot in the order; header slots get a `hideColumn()` that fires `hide:column`). Compose the panel from `BbPopover` + `BbCheckbox`.                                                                          |
+| `BbKanban` / drag-and-drop board                               | Does not exist. There is no reusable DnD primitive in the library (`BbTable`'s header drag is internal to the table) — compose the board from `BbTable` (a table/list view of the same data) or hand-roll the drag-and-drop interaction yourself.                                                                                                                                                                                                                                      |
+| `BbModal`                                                      | It is [BbDialog](../BbDialog.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `BbDrawer` / `BbSheet`                                         | It is [BbOffCanvas](../BbOffCanvas.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `BbCombobox` / `BbAutocomplete`                                | It is [BbSelect](../BbSelect.md) / [BbSelectPopover](../BbSelectPopover.md) — search is built in, see `disable-writing`.                                                                                                                                                                                                                                                                                                                                                               |
+| `BbToggle` / `BbToggleGroup`                                   | It is [BbButton](../BbButton.md) with `v-model` (+ `true-value` / `false-value`), which owns `aria-pressed` and the active class.                                                                                                                                                                                                                                                                                                                                                      |
+| `TagChip` / colored, read-only tag chip                        | It is [BbBadge](../BbBadge.md) — [BbTag](../BbTag.md) is a tags-_input_ only, not a display component. Use `BbBadge` with a registered `soft-*` variant for a fixed palette, or a one-off `--bg`/`--color` override per row for arbitrary/data-driven colors (BbBadge.md § One-off colors) — not a registered variant per distinct color.                                                                                                                                              |
+| `BbTab` (singular)                                             | The consumer API is [BbTabs](../BbTabs.md) / `BbTabsRoot`. `BbTab` appears only as the **v2 "before" side** of the migration diffs.                                                                                                                                                                                                                                                                                                                                                    |
+| `BbCard`                                                       | Does not exist — a card is a `<div>` with tokens. See [design-language](./design-language.md).                                                                                                                                                                                                                                                                                                                                                                                         |
+| `BbList` / `BbListItem` / `BbDescriptionList`                  | Do not exist — a list row is an `<li>` with tokens, and [BbBaseButton](../BbBaseButton.md) makes the whole row navigable. See the note under Data Display.                                                                                                                                                                                                                                                                                                                             |
+| `useLiveFeed` / any polling or cross-tab feed helper           | Does not exist, and neither does a cross-tab helper — `useBroadcastChannelInstance` was removed (cross-tab messaging is not a UI concern). Use `useBroadcastChannel` from `@vueuse/core`; the polling and the merge are yours.                                                                                                                                                                                                                                                         |
+| `BbStepper` / `BbWizard`                                       | Does not exist as a component; the [wizard-form recipe](../recipes/inertia/wizard-form.md) (also under `vue/`, `nuxt/`) composes one.                                                                                                                                                                                                                                                                                                                                                  |
+| `BbSkeleton` (standalone)                                      | Only `BbTable` ships skeletons, via the column `skeleton` field.                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `BbCommand` / command palette                                  | Does not exist. Compose `BbDialog` + `BbSelectPopover` — do not hand-roll the search: the [command-palette recipe](../recipes/inertia/command-palette.md) (also under `vue/`, `nuxt/`) already wires debouncing, race protection, grouping and keyboard nav.                                                                                                                                                                                                                           |
+| `BbCalendar` (month / scheduling view)                         | Does not exist. [BbDatePicker](../BbDatePicker.md) is a picker, not a calendar surface.                                                                                                                                                                                                                                                                                                                                                                                                |
+| `BbDataTable` / `BbDataGrid` / data grid                       | It is [BbTable](../BbTable.md) — sorting, selection, column order/resize, virtual scrolling and inline edit all live there.                                                                                                                                                                                                                                                                                                                                                            |
+| `filter` / `filter-method` prop on BbTable, column filters     | No `filter` prop, and its absence is not a missing feature. A filter is an input to the FETCH: put your filter state in `dependencies` and the provider refetches (debounced, value-hashed, races discarded). Per-column filter UI goes in `#header:<key>:append`, which keeps the built-in sort button. A whole filtered listing is the records-workspace recipe. Client-side over a plain array, use a computed: `:items="filteredItems"`. See [BbTable](../BbTable.md) § Filtering. |
+| `BbSnackbar` / `BbNotification` / flash message                | It is [BbToast](../BbToast.md), raised through the `useToast` composable.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `BbRichTextEditor` / `BbEditor` / WYSIWYG                      | Does not exist, and no rich-text or markdown editor ships here. [BbTextarea](../BbTextarea.md) is plain text only; bring your own editor.                                                                                                                                                                                                                                                                                                                                              |
+| `BbEmptyState` / `BbPlaceholder` / no-results panel            | Does not exist as a component. [BbTable](../BbTable.md) has a `#no-data` slot; elsewhere an empty state is your own markup with tokens.                                                                                                                                                                                                                                                                                                                                                |
+| `BbChart` / `BbGraph`, `BbCarousel`, `BbTimeline`, `BbDivider` | Do not exist. No charting, carousel or timeline primitive ships here.                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 App chrome — an app shell, sidebar, page header, selection dock — is
 deliberately **not** a component: it is yours to own. The per-platform
@@ -1282,8 +1541,13 @@ components or choose component variants.
 1. **Never hardcode colors** in custom CSS around components. Use the `--bb-*`
    custom properties below so your surfaces follow theme and dark mode.
 2. **Never override component internals** (`.bb-*__*` element classes) from
-   consumer code. Restyle via tokens, variants, or documented props — the only
-   exceptions are extension points a component's own doc sanctions.
+   consumer code, and never target the reference-only families at all
+   (`.bb-base-*`, `.bb-common-*`, listbox internals) — they are the CSS twin of
+   the `BbBase*` / `Common*` import boundary and they get restructured without
+   a rename table. Restyle via tokens, variants, or documented props. A
+   component's **root** class (`.bb-table`, `.bb-badge`) is a legitimate target
+   for setting that component's own tokens — see "How to style around the
+   library" below.
 3. **One primary action per view region.** Everything else is `secondary`,
    `outline`, or `ghost`.
 4. **`destructive` is only for irreversible actions**, and destructive flows
@@ -1293,23 +1557,67 @@ components or choose component variants.
 
 ## How to style around the library
 
-Three lanes, in order of preference:
+Four lanes, in order of preference. Do not skip to a later lane because an
+earlier one has no obvious knob — check the lane first.
 
 1. **Component look → props.** Pick a variant, `size`, `compact`. Never write
    CSS to make a component look different.
 2. **Page layout & spacing → Tailwind utilities** (or your project's
    equivalent) on your own wrapper elements — `flex items-end gap-3`,
    `grid gap-6`, `max-w-3xl`. Components size themselves; you only place them.
-3. **Genuinely custom visuals → `--bb-*` tokens.** The few CSS rules that
+3. **Retuning one component → its own component tokens.** Every component
+   declares unprefixed `--*` tokens: cell height, padding, badge fill, tab
+   strip height. **Set the token on the element that declares it** — that is
+   usually the component's root class, and an inline style on the component
+   then works too:
+
+   ```css
+   .bb-table {
+   	--cell-h: 32px;
+   	--padding-x: 8px;
+   }
+   ```
+
+   ```vue
+   <BbTree style="--indent: 14px" />
+   ```
+
+   ⚠ **silent** — a component made of several elements declares some tokens on
+   an inner one, and a value you set further out is _masked_, not inherited:
+   the inner element's own declaration wins. `BbTabs` keeps `--list-h` on
+   `.bb-tabs-list`, so `<BbTabs style="--list-h: 40px">` does nothing and
+   `.bb-tabs-list { --list-h: 40px }` is the working form. Check which selector
+   declares the token before you set it.
+
+4. **Genuinely custom visuals → `--bb-*` tokens.** The few CSS rules that
    remain (a custom panel, a status dot) use theme tokens so they follow
    theming and dark mode automatically.
 
-Treat everything inside a component as private API. Where a component is
-designed to be extended visually, its own doc names the extension point —
-[BbTree](../BbTree.md) has you draw connector lines in consumer CSS anchored
-to its `--indent`/`--gap` tokens; [BbTabs](../BbTabs.md) exposes `--list-h`.
-Read the per-component doc before writing any CSS that mentions a `.bb-`
-class.
+**Finding a component's tokens.** They are not in the `--bb-*` inventory below
+— that tier is the brand knobs only, and it is deliberately small. Component
+tokens live in the component's own CSS, on whichever element consumes them.
+Read `dist/ai/source/<Name>.md`, which carries that CSS verbatim, and grep it
+for the declaration rather than assuming the root. Some components also call
+theirs out in the contract, as [BbTree](../BbTree.md) does for the
+`--indent`/`--gap` pair you anchor connector lines to.
+
+**A missing `--bb-*` token is not a gap in the library.** If you want a shorter
+table row and there is no `--bb-table-row-h`, that is lane 3 telling you to set
+`--cell-h` on `.bb-table`, not an invitation to write element-class overrides.
+The full rules, including how per-size lookup tables interact with specificity,
+are in [design-tokens.md](./design-tokens.md) § "Overriding one from a consumer
+app".
+
+**A utility class on a component that does nothing is a layer problem, not a
+token problem.** Tailwind v4 puts its utilities in `@layer utilities`, and the
+cascade ranks any unlayered rule above any layered one regardless of
+specificity — so `<BbButton class="px-6">` loses to the library's own padding
+until the library is layered too. That is a build-plugin setting, not CSS:
+`cssLayers: TAILWIND_V4_LAYERS` (exported from `bitboss-ui/vite`) places the
+library after Preflight and before the utilities, and the utility wins. Opt-in,
+and the whole story is in
+[installation-and-plugin-setup](./installation-and-plugin-setup.md) § Cascade
+layers.
 
 ## Token Vocabulary
 
@@ -1319,6 +1627,13 @@ that change and everything derived follows. The full architecture (tiers,
 naming rules, the emphasis ladder) lives in
 [design-tokens.md](./design-tokens.md); this is the consumer summary.
 
+**This list is closed.** There is no Tailwind-style numeric ramp — no
+`--bb-primary-800`, no `--bb-gray-100`. Emphasis comes from the derived tokens
+below (`--bb-muted`, `--bb-text-muted`, `--bb-surface-hover`) and from
+`color-mix()` against a knob, not from a shade number. A `--bb-*` name that is
+not in these tables resolves to nothing and fails silently, so a rule built on
+one renders with no value at all rather than erroring.
+
 ### Surfaces & structure
 
 | Token                 | Meaning                                                                                                                           |
@@ -1374,9 +1689,11 @@ so themes with loud brand colors keep gray chrome.
 
 Input-family tokens also exist (`--bb-input-h`, `--bb-input-px`,
 `--bb-label-fs`…) — see design-tokens.md. Component-specific tokens are
-**unprefixed** and defined on each component's root class (e.g. BbTabs'
-`--list-h`); override them per instance or at a scope to retune a whole area
-coherently instead of styling individual components.
+**unprefixed** and defined on the element that consumes them, usually the
+component's root class (e.g. BbTree's `--indent`). Override them per instance
+or at a scope to retune a whole area coherently instead of styling individual
+components, and set them on the declaring element — see lane 3 above for the
+masking trap.
 
 ## Dark Mode
 
@@ -1423,6 +1740,76 @@ recipe in [design-tokens.md](./design-tokens.md).
 Never invent a variant name that is not built-in or registered in the
 project's plugin config — check `vite.config.*` / `nuxt.config.*` first.
 
+### Re-skinning a variant the library already ships
+
+Registering a variant covers a name we do **not** ship. Changing how an
+existing one looks is a different job, and the first question is not "which
+CSS" but **how far the change should reach**:
+
+1. **The colour itself is wrong for this brand** (primary is blue, not black) →
+   override the **theme knobs**, not any component. `--bb-primary` and its
+   family feed every surface, and every derived value and dark-mode variant
+   follows. This is the theme builder's path and the only one that stays
+   coherent.
+2. **One area should look different** (a toolbar, a marketing header) →
+   re-point the same knobs **on a scope**. Custom properties inherit, so this
+   reaches every component in the subtree, whatever shape its variant block
+   has:
+
+   ```css
+   .toolbar {
+   	--bb-primary: #2563eb;
+   	--bb-primary-hover: #1d4ed8;
+   	--bb-primary-fg: #fff;
+   }
+   ```
+
+   Prefer this to per-component rules. It cannot desynchronise states, and it
+   survives dark mode.
+
+3. **One component's take on one variant is wrong** (badges too loud, buttons
+   fine) → you have to read that component's variant block first, because
+   **they are not built the same way**:
+
+| Family                 | Its variant block sets                                                    | So a re-skin is…                                                         |
+| ---------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `BbBadge`, `BbTooltip` | component tokens (`--bg`, `--color` / `--fg`, `--border-color`, `--ring`) | re-point those tokens                                                    |
+| `BbButton`             | CSS properties directly (`background-color`, `border-color`, `color`)     | **no token to re-point** — scope the knobs (2), or restate _every_ state |
+| `BbAlert`              | both (`--main-color` / `--muted-color`, plus `background-color`)          | read the block; half of it is tokens                                     |
+| `BbToast`              | only `--icon-color` — the variant tints the icon, nothing else            | there is no fill to re-skin                                              |
+
+Read the block in `dist/ai/source/<Name>.md` before writing the rule. Assuming
+the badge recipe works on a button is the single most common way this goes
+wrong: `.bb-button--primary { --bg: … }` is silently inert, because the button
+never reads a `--bg`.
+
+**Three traps, all of which fail quietly.**
+
+**1. A variant is not one declaration.** `primary` on a button sets the rest
+state, `:hover`, `[aria-pressed]`, the `:focus-visible` ring, _and_ an adjacent
+group border. Override `background-color` alone and the old brand survives in
+hover and focus — visible only on interaction, which is why this one reaches
+production. Overriding the knobs (1 or 2) changes every state at once; that is
+the argument for doing it there.
+
+**2. Variant blocks are two classes deep.** They are nested under the root, so
+they compile to `.bb-button.bb-button--primary` — more specific than the
+single-class rule you are about to write:
+
+```css
+.bb-button--primary {
+	background-color: red;
+} /* 0,1,0 — loses, renders nothing */
+.bb-button.bb-button--primary {
+	background-color: red;
+} /* 0,2,0 — wins */
+```
+
+**3. Override the knob, not the derived value.** Values built with
+`color-mix()` off a knob re-derive per theme. Replacing the derived value
+hardcodes it for both schemes, and the bug surfaces as "dark mode looks wrong"
+months later.
+
 ## Using color
 
 **Reach for color more than the monochrome default suggests — but make it mean