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

package/dist/ai/composables/useConfirm.md

@@ -17,8 +17,11 @@ Per the design language, every `destructive` action must pass through a confirm.
 **Requires exactly one `<BbConfirm />` host, mounted at the app root** (`App.vue`
 under Vue, `app.vue` under Nuxt, the `createInertiaApp` render root under
 Inertia) — never one per page or per component. With no host, `await confirm(...)`
-never settles and the caller hangs silently. With two hosts, every dialog renders
-twice. See [Agent Contract § Global Host Rule](../guides/agent-contract.md).
+never settles and the caller hangs; with two, every dialog renders twice. Both
+warn in DEV, including when the only host has unmounted. The no-host warning is
+deferred by a second, because a late-mounting host renders the pending dialog
+and settles the promise. See
+[Agent Contract § Global Host Rule](../guides/agent-contract.md).
 
 ## Import
 

package/dist/ai/composables/useToast.md

@@ -16,8 +16,10 @@ per viewport corner and disappear on their own (default **4000 ms**).
 under Vue, `app.vue` under Nuxt, the `createInertiaApp` render root under
 Inertia) — never one per page or per component. With no host, messages are
 enqueued but never rendered _and never expire_, because the dismiss timer lives
-inside the host. With two hosts, every message renders once per host. See
-[Agent Contract § Global Host Rule](../guides/agent-contract.md).
+inside the host. With two hosts, every message renders once per host. Both warn
+in DEV, including when the only host has unmounted. The no-host warning is
+deferred by a second, because a late-mounting host renders the queued message.
+See [Agent Contract § Global Host Rule](../guides/agent-contract.md).
 
 Rule of thumb: `useToast` for _what just happened_ ("Saved", "Upload complete"),
 `BbAlert` for the _current state of the page_ (a form error summary, a banner).

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

@@ -12,6 +12,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
 
@@ -113,7 +115,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
 
@@ -154,8 +156,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.
 
@@ -168,7 +171,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
 

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

@@ -37,7 +37,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
@@ -51,16 +52,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
@@ -70,17 +82,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                                                                                                                                                       |
 
 ---
 

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

@@ -231,24 +231,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

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

@@ -14,8 +14,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
@@ -25,23 +30,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
 
@@ -51,6 +100,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                                                                                                                           |
@@ -106,9 +162,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
 
@@ -155,6 +213,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

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

@@ -295,12 +295,34 @@ Rules:
    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
+instance (`<BbTree style="--indent: 14px">`) or a whole page scope. They are
 just not global namespace.
 
 ### Overriding one from a consumer app
 
-Three rules, in order of how often they are broken.
+Four rules, in order of how often they are broken.
+
+**0. Set it on the element that declares it.** Sealing (rule 2 above) is what
+makes an inline style on the component root work — and it is also what makes
+the same style _silently do nothing_ when the token lives on an inner element.
+The inner declaration is not overridden by an inherited value; it replaces it.
+`BbTabs` declares `--list-h` on `.bb-tabs-list`, not on `.bb-tabs`:
+
+```css
+/* works — the list is the element that declares it */
+.bb-tabs-list {
+	--list-h: 40px;
+}
+```
+
+```vue
+<!-- does nothing — .bb-tabs-list re-declares --list-h and masks this -->
+<BbTabs style="--list-h: 40px" />
+```
+
+Grep the component's CSS in `dist/ai/source/<Name>.md` for the declaration
+before choosing a selector. A masked token produces no warning and no visual
+change.
 
 **1. Override only what you actually render.** Several components expose a
 per-size lookup table (`--icon-size-xs … --icon-size-2xl`, `--h-xs … --h-2xl`)
@@ -334,7 +356,10 @@ silently does nothing on every `size="sm"` one — the confusing half-failure th
 sends people to the shotgun in rule 1. The per-size entry has no competing
 declaration, so it always wins. (A scope selector of equal-or-greater
 specificity also works, but you have to keep winning that race; overriding the
-entry does not.)
+entry does not. If your app is on Tailwind v4 or otherwise layered, the race
+has a structural answer: `cssLayers` in the build plugin puts the library in a
+layer below your utilities, and a utility then wins without any specificity at
+all — see the install guide § Cascade layers.)
 
 **3. Scope it to the component, never `:root`.** Short names are deliberately
 reused across components — `--icon-size` is read by `BbButton`, `BbBadge` and
@@ -656,7 +681,7 @@ 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
+  which is also what makes `style="--indent: 14px"` 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.

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

@@ -16,12 +16,16 @@ Mandatory for AI-generated code.
 2. **`local:*` is for brand-specific art only** — logos, custom marks, one-off
    illustrations. They are SVG files in the configured `iconDir`.
 3. **Never invent icon names.** Use only names that exist in an installed
-   `@iconify-json/*` set or as files in `iconDir`. A missing icon throws at
-   mount (dev shows a Vite error overlay with the exact fix).
-4. **Icon names must be static string literals.** Production builds scan source
-   for `provider:name` literals and bundle only those — a name assembled at
-   runtime (`` `lucide:${kind}` ``) will be missing in production. Map dynamic
-   state to literals instead (e.g. a lookup object of full names).
+   `@iconify-json/*` set or as files in `iconDir`. A name that does not
+   resolve renders the built-in placeholder (a question mark in a circle,
+   tagged `data-bb-icon-missing="<name>"`) and logs one `console.error` with
+   the fix — in dev also as a Vite error overlay. It never throws.
+4. **Write icon names as literals, anywhere in the project.** The plugin
+   scans the whole project (PHP included) for `provider:name` literals and
+   bundles only those; `local:` ships everything. A name the scanner cannot
+   see as a literal — composed at runtime (`` `lucide:${kind}` ``), stored in a
+   database, chosen in an admin panel — goes in the plugin's `iconWhitelist`.
+   This holds in dev exactly as in production: dev registers the same set.
 5. **Never hand-place `BbIcon` where a component already accepts an icon** via
    a prop, item field, or dedicated slot (catalog below).
 
@@ -35,19 +39,38 @@ The `bitbossUi` Vite plugin (`iconDir` option) — or the Nuxt module (config ke
   auto-discovered. Installing `@iconify-json/lucide` makes every valid
   `lucide:<name>` available; removing it makes them all errors. Nothing to
   configure.
-- **Dev**: all icons of installed sets are registered. Referencing an
-  uninstalled prefix or a non-existent name fails loudly in the Vite error
-  overlay with an actionable message. A typo inside an installed set reads
-  "does not exist in the lucide icon set — did you mean `lucide:…`?"; a set
-  that is not installed reads "no installed icon set has the prefix `mdi`
-  (installed sets: lucide) … run: `npm install -D @iconify-json/mdi`". Read
-  the message: a typo wants a different name, a missing set wants an install,
-  never a guess.
-- **Build**: source files (`.vue`/`.ts`/`.js`/`.tsx`/`.jsx`; tests and stories
-  excluded) are scanned for static `provider:name` literals; each referenced
-  icon is emitted as its own lazy chunk. This is why rule 4 exists — and why an
-  icon used only in a `.stories.ts`/`.test.ts` file must also appear as a
-  literal in a scanned source file.
+- **What ships — `local:` everything, providers only what is scanned or
+  whitelisted.** Every SVG in `iconDir` is bundled. For provider sets the
+  plugin reads the **whole project** as bytes — every file under the Vite
+  root, PHP, Blade, JSON, SQL seeders and Markdown included — looking for
+  `<prefix>:<name>` where `<prefix>` is an installed set; what resolves in the
+  set's `icons.json` (icons and aliases) becomes a lazy chunk. Skipped:
+  whatever `.gitignore` ignores (every level), `node_modules`, `vendor`,
+  `storage`, the build `outDir`, every hidden path (`.something`), binary
+  files, and paths listed in `iconsScanner.exclude`. Extra locations
+  (`iconsScanner.include`) are additive. No language is parsed, so a Laravel
+  enum returning `'tabler:user-share'` counts as a literal.
+- **Dev is prod.** The same scan runs on dev start (once, cached by content
+  hash under `node_modules/.cache/bitboss-ui/`) and again per file on every
+  save, so the registry in dev is exactly the set the build emits. Typing a
+  new literal into a template renders it without a restart. An icon that is
+  neither scanned nor whitelisted therefore shows the placeholder and the
+  error on first render in dev — not after deploy.
+- **Names the scanner cannot see** — composed at runtime, persisted in a
+  database, picked by an admin — go in `iconWhitelist`: exact names
+  (`'tabler:crown'`) or globs (`'tabler:calendar-*'`). An entry that resolves
+  in no installed set fails the build with the same message the overlay shows.
+- **A missing name is loud, in both environments.** `BbIcon` renders the
+  built-in placeholder glyph with `data-bb-icon-missing="<requested name>"`
+  and logs one `console.error` per name per page load; dev adds the Vite
+  error overlay. A typo inside an installed set reads "does not exist in the
+  lucide icon set — did you mean `lucide:…`?"; a real icon nobody wrote as a
+  literal reads "exists in the lucide icon set but is not bundled … add it to
+  `iconWhitelist`"; a set that is not installed reads "no installed icon set
+  has the prefix `mdi` (installed sets: lucide) … run:
+  `npm install -D @iconify-json/mdi`". Read the message: a typo wants a
+  different name, an unscanned name wants the whitelist, a missing set wants
+  an install, never a guess.
 - **Local icons**: `iconDir` is scanned recursively; each `.svg` becomes
   `local:<basename-without-extension>`. A bare, unprefixed name normalizes to
   `local:`. Adding/removing files is picked up live in dev, and the plugin
@@ -256,8 +279,10 @@ markup) yourself:
   (slot content or `text`; `aria-label` only to override).
 - Inventing or guessing icon names; assuming a set is installed without
   checking `package.json`.
-- Runtime-composed icon names (template strings / concatenation) — invisible to
-  the build scanner, broken in production.
+- Runtime-composed icon names (template strings / concatenation) without a
+  matching `iconWhitelist` entry — invisible to the scanner, so they render the
+  placeholder (in dev too). Prefer a lookup of full literals; whitelist what
+  must stay dynamic.
 - Setting `color`/`fill` on the icon element instead of the parent.
 - Falling back to random provider sets when a needed `local:` asset is missing —
   ask for the SVG (or approval to substitute) instead.