# bitboss-ui — core knowledge base (medium tier)

> Vue 3 component library by BitBoss. This single file is the mandatory
> reading before writing any bitboss-ui markup: the hard rules, setup,
> how to choose a component, and the design language — plus a catalogue
> of every public component.

Canonical URL: https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-medium.txt

Need more? Fetch the specific component contract you need — one hop, not
the whole catalogue: https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/<ComponentName>.md
Machine-readable API surface: https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/components.json

---

<!-- dist/ai/guides/ai-router.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/ai-router.md -->

# AI Router

Read this file first. Open **at most one** deeper file per hop. Do not load
every recipe or every component contract into context.

Knowledge base root (installed package):
`node_modules/bitboss-ui/dist/ai/`

Package export entry: `bitboss-ui/ai` → `dist/ai/index.md`.
Subpaths: `bitboss-ui/ai/components.json`, `bitboss-ui/ai/guides/…`, etc.

**Not installed, or can only fetch URLs?** The same files are served from the
published package at `https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/…`.
If you can make only one request, fetch
[`…@beta/dist/llms-medium.txt`](https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-medium.txt)
— this router plus the agent contract, setup, component picker, design language
and the full component catalogue, in ~110 KB.

---

## Mandatory order (every UI task)

1. **[Agent contract](./agent-contract.md)** — hard rules (Bb\* boundary,
   setup-first, `href`/`to` navigation, icons, coherence).
2. **Setup?** If the project may not have the plugin yet →
   [Installation & Plugin Setup](./installation-and-plugin-setup.md). **Set
   `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).
   - 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
   [`../components.json`](../components.json).

---

## Recipes (page-level — pick one platform)

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`                           |

No recipe for detail-with-tabs, settings, dashboards, or profile pages —
compose those from the closest listing/form recipe plus the guides
(page shell, tabs, inline-edit playbook) instead of inventing a new shape.

---

## 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)         |

---

## Full catalogue (last resort)

- [Component index](../index.md) — every consumer + reference-only entry
- [components.json](../components.json) — machine-readable API for validation
- Composables: `../composables/` (`useToast`, `useConfirm`, table/tabs context, …)

Reference-only (`BbBase*` form primitives, listbox internals, …) — **do not
import in consumer apps** unless the user explicitly asks for internals.
Exception documented in the agent contract: **`BbBaseButton` is consumer API**.

---

## Consumer kickstart

In the app repo (once), after installing `bitboss-ui`:

```bash
npx bitboss-ui ai-init
# optional: also register the MCP server (its peers are not installed with the library)
npm i -D @modelcontextprotocol/sdk zod
npx bitboss-ui ai-init --mcp
```

Writes harness-agnostic pointers (`AGENTS.md`) plus Cursor / Copilot / Claude /
Windsurf rules so agents find this router without being told.

After writing Bb\* markup, validate against the installed contract:

```bash
npx bitboss-ui check
# or: npx bitboss-ui check 'src/**/*.{vue,md}' --json
```

Optional MCP (`npx bitboss-ui mcp`): search/get components, list/get recipes,
validate snippets — version-matched to the installed package.
Needs the optional peers `@modelcontextprotocol/sdk` + `zod` (~12 MB, used by
nothing else); the command names them if they are missing.

---

<!-- dist/ai/guides/agent-contract.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/agent-contract.md -->

# Agent Contract

Use this contract before generating any UI code with `bitboss-ui`.

## Default API Boundary

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.

## Setup-First Rule

Before writing component usage code, verify:

- `bitboss-ui` is installed;
- the build plugin is configured (`bitboss-ui/vite` in Vite/Inertia apps, `bitboss-ui/nuxt` in Nuxt apps) — it serves the `virtual:bitboss-ui/icons` and `virtual:bitboss-ui/config` modules;
- the runtime plugin is installed (`app.use(bitbossUiPlugin)`; the Nuxt module does this for you), which injects `bitboss-ui/styles.css` unless `injectStyles: false`.
- **the plugin's `locale` option is set, if the app is not Italian.** It
  **defaults to `'it'`** — every built-in string (date formats and per-segment
  labels on the date/time pickers, select-all text, `useConfirm`'s OK/Annulla
  labels, and more) ships Italian until `locale` is set explicitly. There is
  no build-time warning for an unset `locale`, only for an unknown one, so
  this ships silently. Set `locale: 'en'` (or the target locale) in
  `vite.config.*` / `nuxt.config.*`, and if the app switches locale at
  runtime, list every locale it can switch to in `enabledLocales` up front —
  narrowing `locale` alone narrows the bundle and makes any other locale a
  compile error at `useBbConfig().setConfig({ locale })`. Details:
  [Installation and Plugin Setup](./installation-and-plugin-setup.md) §
  `locale`.

If setup is missing, provide setup code first ([Installation and Plugin Setup](./installation-and-plugin-setup.md)), then component examples.

## Knowledge Base: Router First, Then Curated Guides

Read the installed package knowledge base before recommending components:

1. **`dist/ai/guides/ai-router.md`** — tiny hop map (which file to open next).
2. **`dist/ai/index.md`** — full catalogue only when the router is not enough.

Every component doc (`dist/ai/<Name>.md`) **leads with a "Usage & Guidelines" section** — a curated, runtime-tested guide with live examples. Read it before the raw props/events/slots tables, and prefer its idioms over anything you would infer from the API surface alone. If a guide shows one way to do something, that is the idiomatic way.

Consumer projects should run `npx bitboss-ui ai-init` once so AGENTS.md / Cursor / Copilot / Claude / Windsurf all point at this corpus.

## Navigation Rule

Offload navigation to the component. The navigation engine lives in `BbBaseButton`, the primitive every button wraps — so `BbButton`, `BbDropdownButton`, `BbBaseButton` itself, and every item-driven surface built on the same core (dropdown items, breadcrumb items, tabs items, pagination in `navigation` mode) all navigate by themselves. Push _as much navigation as possible_ onto this surface — any click whose result is a destination belongs here, not in an `@click` handler:

- `href` — renders an anchor; in an Inertia app it becomes an Inertia visit and accepts `method`, `data`, `headers`, `preserveScroll`, `replace`, …;
- `to` — vue-router `RouteLocationRaw`, rendered as a router link (tabs items use `href`; pagination `navigation` builds per-page `to`/`href` links itself).

**NEVER** write `@click="router.push(...)"` (or `window.location = ...`) for something the component can navigate to itself. Click handlers are for actions; destinations go in `href`/`to`.

## Inline Links & Identity Cells Rule

`BbButton` is **not** an inline link. It is a full button with a box — height and
horizontal padding from the size scale — and `variant="link"` only **recolors**
that box (it does not remove the padding or let it flow inline). Dropped into
running text, a table cell, or a property grid, that button box **breaks the line
height and text flow** around it.

The inline link/button is **`BbBaseButton`**: zero chrome, the same
`href`/`to`/Inertia navigation engine, and its look is **owned by the project's
CSS** — e.g. a `.plain-link` class that adds only an underline. Use it for:

- a clickable **record-identity cell** (a row's name/title column) that must
  truncate and flow inline at the cell's width;
- any **in-text link** inside a table, peek panel, or property grid;
- a link whose appearance is a plain text link, not a button.

Rule: **inline text link → `BbBaseButton` + your own link class; never `BbButton`
(including `variant="link"`).** Reserve `BbButton variant="link"` for a
standalone, button-spaced navigation control sitting among other buttons ("See
pricing", "Forgot password?"). See [BbButton](../BbButton.md) § Choosing a
variant and [design-language](./design-language.md) § the `.plain-link` helper.

## Consult-Stack Rule (records listings)

A listing screen with a peek sidebar is for **consulting** — invoice → its
account → another invoice on that account → back — without leaving the list.
The shell's stack exists for exactly that, and it is opt-in, so agents keep
shipping listings where every row opens one reset peek and every related name
inside it is dead text. Each follow-up question then costs a full-page
navigation, which is the thing the shell was supposed to remove.

Rule: **on any records/approvals/ownership listing, related names are
navigable and the peek stacks.** Concretely:

1. `PeekItem` is one discriminated union covering every related type the rows
   and the peeks expose — not a second shell per type.
2. Row click → `peek(item)` (fresh top-level). Related name → `stackItem(item)`
   (drills, keeps the back arrow). Prefer these named intents over
   `push(item, true)`, whose boolean is what people get backwards.
3. Every related name is a `BbBaseButton` + `.plain-link` (see the rule above),
   in table cells **and** inside peek bodies.
4. `#sidebar-title` follows the top of the stack; the row highlight follows its
   root, so drilling does not un-highlight the row the consult started from.

See [page-shell](./page-shell.md) § The consult stack and the records-workspace
recipe's conformance checklist.

## Item-Driven Components Rule

For components accepting `items`:

- prefer declarative mapping with `item-text` and `item-value`;
- use `dependencies` and `deps-debounce-time` for tied fields;
- use `enforce-coherence` instead of custom watchers for stale model cleanup.

## 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).

## Variants Rule

Unlike icons, variants are **not** a fixed vocabulary you must stay inside. The
shipped names (`primary`, `secondary`, `destructive`, `outline`, …) are the
**floor**; the registries are open on purpose so an app can add the tones its
design needs. When a design calls for a colour the library does not ship — soft
semantic status badges, a brand button tone — **add it, in both halves**:

1. **Register the name** in the build plugin: `badgeVariants`, `buttonVariants`,
   `alertVariants`, `confirmVariants`, `dropdownItemVariants`, `tooltipVariants`,
   `toastVariants`, `indicatorVariants` (`bitboss-ui/vite` or `bitboss-ui/nuxt`).
   The plugin regenerates the typed registry, so the name type-checks.
2. **Style the class** — `.bb-badge.bb-badge--<name>`, `.bb-button--<name>`, … —
   in a project stylesheet loaded **after** `bitboss-ui/styles.css`. The library
   ships no CSS for names it does not own.

Half the job is a bug in both directions: a registered name with no CSS renders
an unstyled pill (the original "warning badge" hallucination), and CSS with no
registration fails `vue-tsc`. Equally, **do not downgrade the design** — falling
back to `secondary`/`outline` because a status palette "isn't available" is the
wrong fix; registering it is a two-file change you are expected to make.

Never write a variant name that is neither shipped nor registered. Canonical
soft status palette (accents, the shared treatment, and why the selectors are
doubled): [Design Language](./design-language.md) § Getting soft semantic badges.
Where the option goes: [Installation and Plugin Setup](./installation-and-plugin-setup.md).

## Overlay Open-State Rule

Overlay visibility is controlled by the component's **primary `v-model`** — never a separate `v-model:open`. The standalone overlays (`BbDialog`, `BbOffCanvas`, `BbPopover`, `BbTooltip`) expose a boolean `v-model` for open state. The popover-embedded surfaces (`BbDropdown`, `BbSelectPopover`, `BbColorPalette`) keep open state **internal** — drive them through their trigger/activator, not a bound open flag. There is no `v-model:open` anywhere in the library, by design; do not reach for one.

These overlays also return focus to their trigger element on close, by documented default — a consumer `@focus`-reopen handler on that trigger will fight the restore and can loop.

## Global Host Rule

`useToast()` and `useConfirm()` write to **module-level singleton state**, not to a component instance. `<BbToast />` and `<BbConfirm />` are the only things that render that state, and each mounted host renders _all_ of it.

**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.

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.

## Boolean Prop Defaults Rule

Boolean props default to `false` so the bare `<Comp foo>` shorthand turns the feature **on**. A few props deliberately default to `true` for cross-library keyword clarity — pass `:prop="false"` to opt out:

- `multiple` on `BbTable`, `BbCheckboxGroup`, `BbSwitchGroup` — multi-select is the expected default; `:multiple="false"` forces single-select.
- `selectable` on the option components (`BbSelect`, `BbSelectPopover`, `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`) — options are selectable by default; pass a predicate or `false` to restrict. **Not `BbTable`**: there `selectable` is unset by default and is what renders the selection column at all, so leaving it off means "no checkboxes", not "every row selectable".

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).

## Testing Against bitboss-ui

Two DOM realities of this library trip up headless-browser tests written
against otherwise-correct selectors:

- **Closed floating panels stay in the DOM, not hidden.** Every floating
  panel — `BbPopover`, `BbDropdown`, `BbSelectPopover`, and the select family
  built on it (`BbSelect`) — stays mounted and off-screen when closed
  (`position: fixed; top: -2000px; width: max-content`) rather than being
  removed or `display: none`d — a closed panel is parked, not absent. Two
  consequences: (1) a bare text/role query can match content inside a closed
  panel elsewhere on the page — scope queries to a known open root; (2)
  because these panels are `position: fixed` and can be as wide as their
  longest option, they inflate `document.documentElement.scrollWidth` by
  however wide the _widest ever rendered_ panel is, with zero visible effect
  on the page. **Measure page overflow with `document.body.scrollWidth`,
  never `document.documentElement.scrollWidth`.**
  **Which closed-state signal to await differs by component.**
  `BbPopover` and `BbDropdown` wrap their whole panel in `inert` when closed —
  wait for `.bb-popover__panel[inert]` / `.bb-dropdown__panel[inert]` (not
  `hidden`/detached) to assert closed, and scope open-panel queries to
  `:not([inert])`. The select engine (`BbSelectPopover`, and therefore
  `BbSelect`, which is built on it — the two behave identically) never puts
  `inert` on its listbox; only its optional header/footer chrome goes `inert`.
  Its listbox closes via `opacity: 0` + `grid-template-rows: 0fr` on
  `.bb-listbox__outer-container` (the `bb-listbox--open` class drops). Don't
  wait for `[inert]` there — it never comes; assert on the collapsed state
  (`grid-template-rows`/`opacity`/`bb-listbox--open`) or on option visibility
  instead.
  **`BbDialog` and `BbOffCanvas` are the trap: they DO carry `inert`, but it
  does not mean "closed".** Both render `:inert="(!model && !isVisible) || isCovered"`,
  so a panel is ALSO inert while it is open and merely **covered by another
  modal stacked on top of it** — assert closed with `[inert]` there and the test
  starts passing for the wrong reason the moment two overlays stack. They are
  native `<dialog>` elements driven by `showModal()`/`close()`, so use the
  element's own `open` property (or the `bb-dialog--open` class) as the
  closed-state signal. Mind the transition window too: `inert` only lands once
  `isVisible` has gone false as well, which is after the closing animation, not
  at the click.
- **Segmented date/time inputs are not one field.** `BbDatePickerInput` /
  `BbTimePickerInput` render one native input per segment (day/month/year,
  hour/minute/second/period); the field's own `label` is wired via `for` to
  only the first segment, and every segment additionally carries its own,
  localized `aria-label` ("Month"/"Day"/"Year", or "Mese"/"Giorno"/"Anno"
  under `locale: 'it'`), which wins the accessible-name computation. So
  `getByLabel('<the field's label>')` matches nothing — query each segment by
  its own accessible name (`getByLabel('Month')`, etc., which is
  locale-coupled: it breaks if the app under test switches locale) or by its
  role/position within the field. `aria-valuetext` is **not** emitted by the
  date/time picker family — that signal exists only on `BbSelectPopover`'s
  activator; don't expect it on a segmented input.

## Rebuild Check (before you ship a screen)

Re-read what you hand-wrote and ask whether the library already ships it. This is
the failure with no error message: the component exists, is exported, is in the
picker, and the picker is open — but a picker gets opened to answer _archetype_
questions ("is there a Calendar?"), never "am I about to reinvent something
small?". A pilot builder read the picker four times and hand-rolled an avatar
twice.

Symptoms that mean stop: an `<img>` with an initials/icon fallback →
`BbAvatar` (**circle-only** — a rounded-square avatar really is yours to build);
a hand-written spin animation → `BbSpinner`; a tinted `<span>` pill standing for
a status → `BbBadge` with a registered `soft-*` variant. Full symptom index:
[Component Picker](./component-picker.md) § Am I about to rebuild one of ours?

`npx bitboss-ui check` prints the avatar and spinner shapes
as **advisory hints** — never a build failure, because a round `<img>` is
sometimes a logo — so that much backstops itself on files it scans. The badge
case is not decidable from markup and has no hint.

## Safety Checklist

- [ ] Started from the AI Router (or already knows the next hop).
- [ ] Recommends `Bb*` components by default.
- [ ] Uses only existing props/events/slots from library types.
- [ ] Read the component's "Usage & Guidelines" section before writing usage code.
- [ ] Navigation goes through `href`/`to` on buttons and items — no `router.push` click handlers for plain destinations.
- [ ] Uses only icons from installed `@iconify-json/*` providers or existing `local:*` files.
- [ ] Avoids reference-only imports unless explicitly requested.
- [ ] Uses declarative coherence/dependencies before manual watchers.
- [ ] Mounts exactly one `<BbToast />` and one `<BbConfirm />` host, at the app root — never inside a page or component.
- [ ] Confirmed the plugin's `locale` is set explicitly if the app isn't Italian (default is `'it'`) — see Setup-First Rule.
- [ ] Ran the Rebuild Check over the hand-written markup — nothing reimplements `BbAvatar`, `BbSpinner` or `BbBadge`.

---

<!-- dist/ai/guides/installation-and-plugin-setup.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/installation-and-plugin-setup.md -->

# Installation and Plugin Setup

Source of truth for integrating `bitboss-ui`. Two pieces are always required:

1. a **build plugin** (`bitboss-ui/vite` or `bitboss-ui/nuxt`) that serves the `virtual:bitboss-ui/icons` and `virtual:bitboss-ui/config` modules, scans local SVG icons, and generates typed variant registries;
2. the **runtime plugin** (`bitbossUiPlugin` — installed automatically by the Nuxt module) that injects styles, provides the icon registry, and registers the `v-bb-tooltip`, `v-bb-dropdown`, `v-bb-color`, `v-bb-date` and `v-bb-time` directives.

## 1) Install

```bash
# v3 is a prerelease — a dist-tag is REQUIRED.
# A bare `npm install bitboss-ui` still resolves to v2, which has no build
# plugin and no `dist/ai` knowledge base, so everything below silently fails.
npm install bitboss-ui@beta
# recommended default icon set (any @iconify-json/* works)
npm install -D @iconify-json/lucide
```

Confirm you got v3 before continuing — `npm ls bitboss-ui` must report a
`3.0.0-*` version. If it reports `2.x`, nothing in this guide applies.

**`@beta` is the current v3 channel.** `@alpha` still resolves, but it is
frozen at the last alpha and does not receive fixes — it is not simply an older
copy of the same line. `@latest` is the **v2** line and always will be until v3
goes stable, so never reach for it here.

Peer dependency: `vue ^3.5.12` — the only required one. `@inertiajs/vue3` is an **optional** peer, needed only in Inertia apps.

`@iconify/collections` is an **optional** peer too, and npm never installs
optional peers automatically — install it yourself if you want the dev-time
provider-icon diagnostics:

```bash
npm install -D @iconify/collections
```

Without it the plugin has no list of valid Iconify prefixes, so the dev-overlay
errors below (the "install `@iconify-json/<prefix>`" hint and the "did you
mean …?" suggestion for a mistyped icon name) never fire — a wrong provider
icon then surfaces only as `BbIcon`'s generic runtime `Icon "…" does not exist.`
Nothing else changes: icons that resolve still render, in dev and in production.

**Known-good toolchain:** TypeScript **5.x or 6.x** if your build gate runs
`vue-tsc`. Both type-check cleanly against the shipped `.d.ts`; the library
itself builds on TypeScript 6 with `vue-tsc` 3. TypeScript **7** is the one to
avoid for now — it changed its package layout in a way `vue-tsc` (not a peer of
this library, but the typical `--noEmit` gate) cannot load, failing with
`ERR_PACKAGE_PATH_NOT_EXPORTED` on `./lib/tsc`. This library doesn't pin
TypeScript for you (it isn't `vue-tsc`'s maintainer), but a bare
`npm i -D typescript` in a fresh project can resolve to 7.x today — pin
`typescript: ^5` or `^6` yourself if `vue-tsc` is part of your gate.

**`vue-tsc` must be 3.x — 2.x is not "an older version that still works", it
is a gate that reports success while checking less than you think.** The
library's declarations are emitted by Vue Language Tools 3, and every component
declared with `generic="T"` emits as a generic _function_ (`declare const
__VLS_export: <T = any>(__VLS_props …) => VNode`) rather than the
`DefineComponent<…>` object non-generic components get. Vue Language Tools 2
does not read props out of that shape, so under `vue-tsc` 2 the template
type-checker silently type-checks **nothing** about the props of these nine
public components:

`BbSelect` · `BbSelectPopover` · `BbTable` · `BbTabs` · `BbTabsRoot` ·
`BbTree` · `BbRadioGroup` · `BbCheckboxGroup` · `BbSwitchGroup`

(and their `BbBase*` primitives). Missing required props, misspelled props,
wrong value types — all pass. The trap is that the failure is partial and
invisible: unknown-**component** checking still fires, non-generic components
like `BbButton` and `BbTextInput` still reject bad props, so the gate is
visibly working and you conclude the generic nine are covered too. A real
consumer shipped `<BbRadioGroup label="…">` (the prop is `legend`) through six
release slices on `vue-tsc@^2.2.12` with a green `--noEmit`; the same file under
`vue-tsc` 3.2.8 fails immediately with TS2345 + TS2322.

There is no runtime symptom to catch it later either — an unknown prop just
lands in `$attrs`. Upgrade the gate, don't work around it:

```bash
npm i -D vue-tsc@^3
```

### Browser support

The library targets **evergreen browsers** and ships **no polyfills**. The
floor is set by the native [Popover API](https://developer.mozilla.org/docs/Web/API/Popover_API),
which every floating surface (selects, dropdowns, popovers, tooltips, color
palette) renders through:

| Engine        | Minimum            |
| ------------- | ------------------ |
| Chrome / Edge | **114** (May 2023) |
| Safari        | **17** (Sep 2023)  |
| Firefox       | **125** (Apr 2024) |

Also relied on, all older than that floor: `<dialog>`, the `inert` attribute,
`ResizeObserver`, and CSS `grid-template-rows` transitions. On older engines
the floating surfaces simply don't render — there is no degraded mode — so if
your fleet includes browsers below the floor, this library is not a fit
without your own polyfill strategy (untested, unsupported).

## 2) Vite + Vue

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { bitbossUi } from 'bitboss-ui/vite';

export default defineConfig({
	plugins: [
		vue(),
		bitbossUi({
			iconDir: './src/assets/icons',
		}),
	],
});
```

```ts
// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import { bitbossUiPlugin } from 'bitboss-ui';

const app = createApp(App);
app.use(bitbossUiPlugin);
app.mount('#app');
```

If the icon folder does not exist yet, create it (`mkdir -p src/assets/icons`) and keep the path aligned with `iconDir`.

## 3) Nuxt

The Nuxt module wraps the same Vite plugin and auto-registers the runtime plugin — no `app.use` needed:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
	modules: ['bitboss-ui/nuxt'],
	bitboss: {
		iconDir: './assets/icons', // module default
	},
});
```

All options below go under the `bitboss` config key. `nuxtLinkName` controls which globally registered component renders router links (default `'NuxtLink'`).

This module supersedes the standalone `@bitboss-dev/bitboss-ui-nuxt` package, which was the v2 Nuxt integration — uninstall it (see [Migration v2 → v3](./migration/v2-to-v3.md)).

### `autoImport?: boolean | { components?: boolean; composables?: boolean; validated?: boolean }` (default: `false`, Nuxt only)

Registers the library's components and composables with Nuxt's auto-import system, so templates write `<BbButton>` and `useToast()` with no import line:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
	modules: ['bitboss-ui/nuxt'],
	bitboss: {
		iconDir: './assets/icons',
		autoImport: true,
	},
});
```

`true` means `{ components: true, composables: true }`. Pass the object form to
narrow it, or to add `validated: true` — which resolves the form controls from
[`bitboss-ui/validated`](./validated-forms.md) instead of `bitboss-ui`, so
`<BbTextInput>` is the vee-validate-bound wrapper and takes `rules`, and adds
`BbForm`, `BbAsterisk`, `useBbFormContext` and `useValidatedField`. It needs the
`vee-validate` peer installed.

**It is off by default on purpose, and leaving it off is the better setup.**
Explicit imports are what make `vueCompilerOptions.checkUnknownComponents` (see
section 9) able to fail the build on a mistyped or unimported `Bb*` tag; with
auto-imports on, every `Bb*` tag resolves and that gate goes quiet. Reach for it
when you are moving an app off `@bitboss-dev/bitboss-ui-nuxt`, whose templates
were written against auto-imported components, and adding the imports is a
separate commit from the upgrade.

Two things it deliberately does not do. It never overrides your own components:
a `~/components/BbButton.vue` in the app keeps winning, and the library only
fills names the app has not claimed. And it never registers the library's
`useId` — Nuxt already auto-imports Vue's, and shadowing it would silently
redirect every existing `useId()` call in the app; import that one explicitly if
you want it.

## 4) Inertia

Inertia apps are Vite apps: configure `bitboss-ui/vite` exactly as in section 2, install `@inertiajs/vue3`, then install the runtime plugin in `createInertiaApp`:

```ts
createInertiaApp({
	// ...resolve/setup
	setup({ el, App, props, plugin }) {
		createApp({ render: () => h(App, props) })
			.use(plugin)
			.use(bitbossUiPlugin)
			.mount(el);
	},
});
```

That is the whole setup — **you do not need to register a link component**. When
the build plugin sees `@inertiajs/vue3` in your app, it imports Inertia's `Link`
on your behalf, so `href` on buttons/items performs Inertia visits (`method`,
`data`, `headers`, `preserveScroll`, …) out of the box.

If your app registers its **own** link wrapper globally — one with baked-in
defaults, analytics, whatever — that keeps winning: a component registered under
`inertiaLinkName` (default `'Link'`) is always preferred over the imported one.
Register it under a different name and point `inertiaLinkName` at it.

## 5) Styling

Two runtime options control CSS:

- `injectStyles` (default `true`) — auto-injects the library stylesheet (equivalent to `bitboss-ui/styles.css`: base styles + design tokens);
- `resetCss` (default `false`) — opt-in injection of the reset stylesheet.

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.

**Tailwind v4 cascade layers vs. scoped `<style>`:** Tailwind v4's `@import
'tailwindcss'` puts every utility class in `@layer utilities`. A Vue SFC's
`<style scoped>` block is **unlayered** CSS, and per the cascade, unlayered
rules always beat layered rules of equal specificity — regardless of source
order. So a component with its own scoped layout-affecting rule silently
defeats a Tailwind utility applied to it from outside, with no warning from
`bitboss-ui check`, `eslint`, or `vue-tsc`:

```vue
<!-- Parent -->
<CategoryTree class="hidden lg:block" />

<!-- CategoryTree.vue -->
<style scoped>
.category-tree {
	display: flex; /* unlayered — always wins over the layered `hidden` utility */
}
</style>
```

`CategoryTree` never actually hides. Prefer `v-if`/JS conditionals over
utility classes for hide/show behavior on components (yours or ones built on
top of `bitboss-ui`) that carry their own layout-affecting scoped styles:

```vue
<CategoryTree v-if="showSidebar" />
```

Manual alternatives:

```ts
// with injectStyles: false — import once, before your own CSS
import 'bitboss-ui/styles.css';
// explicit reset instead of resetCss: true
import 'bitboss-ui/reset.css';
```

**Exception — an app that needs its own CSS to load _before_ the library.**
Auto-injection is library-first and not configurable: the runtime plugin
inserts its `<style>` **before the first** `style`/`link[rel="stylesheet"]`
already in `<head>` (`src/utils/injectLibraryStyles.ts`), so the guaranteed
order above is exactly what you get and every app stylesheet — your Tailwind
entry included — lands after the library. There is no option to inject later.

That is the order most apps want. It is the wrong order if you need library
rules to beat Tailwind's Preflight **by source order**, which is the case on
**Tailwind v3**: `@tailwind base` compiles to ordinary unlayered CSS, so under
auto-injection Preflight sits after the library sheet and its element resets
(`button`, `input`, `h1`, …) win every equal-specificity tie. `injectStyles:
false` + `resetCss: false` (the default) disables injection entirely and hands
you the order:

```ts
// vite.config.ts / the `bitboss` key in nuxt.config.ts
bitbossUi({ iconDir: '…', injectStyles: false, resetCss: false });
```

```ts
// app entry — order is yours now
import './app.css'; // your Tailwind entry
import 'bitboss-ui/styles.css'; // after Tailwind, so library rules win the ties
```

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.)

## 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. Missing packages/icons produce actionable dev-overlay errors **only when the optional `@iconify/collections` peer is installed** (see [Install](#1-install)); otherwise you get `BbIcon`'s generic runtime error instead. Production builds report neither — this is a dev-time aid.
- Production builds bundle **only statically referenced** provider icons — write icon names as literal strings (`icon="lucide:trash-2"`), never assemble them dynamically.
- 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).

## 7) Complete Option Reference

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>`.

### `injectStyles?: boolean` (default: `true`)

Auto-inject the library stylesheet at runtime. If `false`, you must `import 'bitboss-ui/styles.css'` manually.

### `resetCss?: boolean` (default: `false`)

Inject the reset stylesheet (always ordered before the library stylesheet). Keep `false` and import `bitboss-ui/reset.css` if you prefer explicit control.

### `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.

### `adaptive?: boolean` (default: `true`)

Default for the `adaptive` prop of surface components (BbDialog, BbPopover, BbDropdown, BbSelect): when true they open as a bottom sheet on mobile (below `mobileMaxWidth`) instead of their floating surface. An explicit per-component `adaptive` prop always wins.

### `vscodeSettings?: boolean` (default: `true`)

When `true`, the **dev server** adds `./node_modules/.bitboss-ui/local-icons.json` to `"iconify.customCollectionJsonPaths"` in the project's `.vscode/settings.json` on boot, so the Iconify IntelliSense extension previews your local icons. The write is idempotent (it happens at most once) and splice-based — comments, formatting, and key order in a hand-written JSONC file all survive — and the plugin logs exactly what it changed the one time it does. Set to `false` if the plugin should never touch `.vscode/settings.json`; in that case add the entry manually to keep the previews.

### `mcp?: boolean` (default: `false`)

When `true`, the **dev server** registers the bitboss-ui MCP server in each project-scoped agent-harness config on boot — `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), and `.vscode/mcp.json` (VS Code / Copilot) — so agents can query the knowledge base with no manual setup. The write is merge-safe (leaves other servers alone) and idempotent (only logs when it actually changes a file). Windsurf is intentionally **not** written here: its config is global (`~/.codeium`), and silently editing a home-dir file that affects every project on the machine from a dev-server boot would be surprising — run `npx bitboss-ui ai-init --mcp` to register Windsurf too. This flag is the zero-command equivalent of that command's project-scoped writes. The MCP server's own runtime — `@modelcontextprotocol/sdk` and `zod` — ships as **optional peer dependencies** (~12 MB, more than every runtime dependency of the library combined, and loaded by nothing else), so install them with `npm i -D @modelcontextprotocol/sdk zod` before the harness first launches the server; both this flag and `ai-init --mcp` warn when they are missing.

**MCP is a convenience, not a requirement, and skipping it costs no
knowledge.** The server is a reader over files the install already put on disk
— every tool `readFileSync`s out of `node_modules/bitboss-ui/dist/ai/` (plus
`dist/styles.css` for the token lookup). An agent that opens that directory
itself has the identical knowledge base, `npx bitboss-ui check` runs without the
peers, and `ai-init` (no `--mcp`) still writes the harness pointers. If you are
migrating under a "no new dependencies" constraint, leave `mcp` at `false`,
skip `--mcp`, and point your agent at `dist/ai/guides/ai-router.md`.

### `inertiaLinkName?: string` (default: `'Link'`)

Global component name used for Inertia links. **Optional** — when nothing is
registered under this name, the library falls back to the `Link` the build
plugin imported from your `@inertiajs/vue3` install. Set it only when you want a
wrapper of your own to be used instead.

### `nuxtLinkName?: string` (default: `'NuxtLink'`)

Global component name used for Nuxt link rendering.

### `linkActiveClass?: string` (default: `'router-link-active'`)

### `linkExactActiveClass?: string` (default: `'router-link-exact-active'`)

Class names applied to active / exact-active links in router-aware components. Align them with your router configuration.

### `mobileMaxWidth?: number` (default: `768`)

Pixel breakpoint for the library's mobile behavior (including `adaptive` surfaces).

### `ssrViewportWidth?: number` (default: `1024`)

The viewport width the library assumes while rendering **on the server**, where
the real screen size is unknowable. The default `1024` is a desktop width, so
server output is desktop-first. On the client the real `window.innerWidth` is
used from the first paint.

**Client-only SPA?** Ignore this — the real width is known from the first paint,
so `adaptive` surfaces are correct immediately.

**Server-rendering (Nuxt / Inertia SSR)?** By default the server renders
desktop-shaped; a mobile visitor's first paint is desktop-shaped and adjusts
once the client measures the real width (for closed overlays this is invisible —
they're not on screen yet; a Vue hydration warning may appear in dev). Set this
to a different width if your app is primarily consumed on a known form factor:

```ts
// vite.config.ts — build-time, applied to every server render.
bitbossUi({
	// ...other options,
	ssrViewportWidth: 768,
});
```

This is a **single global default baked in at build time** (it comes from the
Vite plugin config), so it is the same for every request — it is _not_ a
per-request value. There is no per-request/per-visitor override: the viewport
signal is a process-wide singleton, so a mobile layout that must be correct on
the server's first paint (e.g. a modal already open on load) needs a client
adjustment after hydration, or a fixed `ssrViewportWidth` matching your
audience. (Unlike `locale`, which **is** per-request — see below. A width
cannot be derived from a request without UA sniffing; a locale can.)

### `defaultInputLabelMode?: 'outside' | 'floating' | 'inside'` (default: `'outside'`)

Default label rendering mode for input-like components; set globally instead of repeating per field.

### `requiredAsterisk?: boolean` (default: `false`)

Marks required fields with a red asterisk beside the label/legend. Presentational only — it keys off the standard `required` prop and changes neither validation nor native `required` semantics. The marker is applied by the [`bitboss-ui/validated`](./validated-forms.md) controls — a field that is `required`, or whose `rules` contain a `required` rule; other rules never raise it, because they only apply once a value exists. Core controls ignore the flag, so on a hand-wired form render the exported `BbAsterisk` in your own label content.

### `locale?: LocaleKey` (default: `'it'`)

Global locale for the library's built-in strings (empty states, close/clear
labels, screen-reader announcements, confirm buttons, …). The library ships
**22 built-in dictionaries** — it, en, es, fr, de, pt (Brazilian-leaning), nl,
pl, tr, ru, uk, cs, ro, hu, el, sv, da, nb, fi, ja, ko, zh-cn — but shipping ≠
bundling: only the **enabled** locales enter your build (next option). Runtime
switching: `useBbConfig().setConfig({ locale })` — to a locale you enabled.

**Per-request locale under SSR** is supported as of 3.0.0-beta.15: the config
is held per Vue app, and SSR builds one app per request, so pass it where you
create the app — `app.use(bitbossUiPlugin, { locale: localeFor(request) })`.
That is correct on the server's first paint, which is what crawlers index and
what a JS-disabled reader keeps. `setConfig` still works for runtime switching;
during a server render call it from a component's `setup`, where it can resolve
the current app. From module scope there is no app to address, the write lands
on the build-time defaults, and it leaks between concurrent visitors — it warns
in dev when it sees that.

Note this is a **different rule** from `ssrViewportWidth` above, which really
is a build-time global: a width cannot be known per request without sniffing,
a locale can.

### `enabledLocales?: BuiltinLocaleKey[]` (default: your `locale` + `'en'`)

Which built-in dictionaries (and their dayjs calendar packs) actually ship in
the bundle. The unset default is the minimal set — the `locale` you configured
plus `en` (the per-key fallback anchor) — roughly 4KB of strings, so a
single-language app pays for exactly what it uses without configuring
anything. Apps that switch locales at runtime list what they offer:

```ts
bitbossUi({
	iconDir: './src/assets/icons',
	locale: 'it',
	enabledLocales: ['it', 'en', 'de', 'fr'], // ~4 dictionaries + 4 dayjs packs
});
```

Your `locale` and `'en'` are always auto-included, so the list never needs to
repeat them.
There is deliberately **no catch-all** ("all") value — it would hide the
bundle cost. Wanting every built-in means writing the list, so the cost is
visible in your config where reviewers can see it.

**Selecting a non-enabled locale is a compile error**, not a silent runtime
fallback: the generated `locale-registry.d.ts` registers only the enabled
built-ins, so `setConfig({ locale: 'ja' })` fails to type-check until `'ja'` is
enabled. Run dev once after changing the list.

### Custom locales are not a supported surface

The library ships **22 dictionaries** and that is the whole set:

```
cs da de el en es fi fr hu it ja ko nb nl pl pt ro ru sv tr uk zh-cn
```

There is no `additionalLocales` option and no `npx bitboss-ui locale` blueprint
generator — both were removed deliberately (owner ruling, 2026-08-08). If your
language is not on that list, the supported answer is to ask for it to be
added upstream rather than to author a dictionary in your app.

Locale selection is **build-time**: `enabledLocales` decides what ships, and
only the active `locale` switches at runtime, among what the build enabled.

### `toastPosition?: BbToastPosition` (default: `'bottom-right'`)

Default viewport corner for toasts when neither the toast nor the `<BbToast>` host specify one. One of `'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'`.

### `iconDefaultSizes?: Partial<Sizes>`

Default icon size scale used by `BbIcon` and avatar dimensions. Partial overrides merge onto:

`{ xs: 12, sm: 16, md: 24, lg: 28, xl: 36, '2xl': 40 }`

### `dialogDefaultSizes?: Partial<Sizes>`

### `offCanvasDefaultSizes?: Partial<Sizes>`

Global size maps (pixels) for BbDialog / BbOffCanvas. Both default to:

`{ xs: 320, sm: 384, md: 448, lg: 512, xl: 576, '2xl': 672 }`

Provide only the keys you want to override, e.g. `dialogDefaultSizes: { md: 500, xl: 680 }`.

### Variant registries

Each option **appends** custom names to the default set (trimmed, deduplicated) and regenerates a typed union (`*-variants.d.ts`) on build start. Unstyled custom variants only add a class hook — supply their CSS yourself.

**The generated `*-variants.d.ts` files are per-project output, not a portable
variant list.** They mirror the plugin config of the project that last ran the
plugin in that folder, and are rewritten by every build/dev/test process. Your
project's registry is what **your** plugin config declares — never trust names
read out of another checkout's copy (e.g. the library repo's own tracked seeds
list variants that exist only in its dev showcase). Each generated file now
says this in its header.

| Option                 | Defaults                                                | Class hook for custom entries       |
| ---------------------- | ------------------------------------------------------- | ----------------------------------- |
| `buttonVariants`       | `primary, outline, secondary, ghost, destructive, link` | `bb-button--<name>`                 |
| `alertVariants`        | `outline, primary, destructive, warning`                | `bb-alert--<name>`                  |
| `badgeVariants`        | `primary, secondary, destructive, outline`              | `bb-badge--<name>`                  |
| `indicatorVariants`    | `default, success, info, warning, destructive`          | `bb-indicator--<name>`              |
| `confirmVariants`      | `default, destructive`                                  | `bb-confirm--<name>`                |
| `dropdownItemVariants` | `default, destructive`                                  | `bb-dropdown__item--variant-<name>` |
| `tooltipVariants`      | `default, destructive`                                  | `bb-tooltip--<name>`                |
| `toastVariants`        | `default, success, info, warning, destructive`          | `bb-toast-message--<name>`          |

Variant props are locked to the registered set (`keyof <X>VariantRegistry`):
an unregistered name is a compile error, not a silently unstyled render.
Register custom names here (typed, autocompleted), or force a one-off with an
explicit cast — the runtime class is still plain interpolation, so its CSS
applies either way.

**Adding a variant is a normal, expected consumer change** — the defaults are a
floor, not a vocabulary you must stay inside. A page that needs a tone the
library doesn't ship registers it here **and** styles its class hook in a
project stylesheet loaded after `bitboss-ui/styles.css`; both halves, or you get
an unstyled pill (CSS missing) or a compile error (registration missing). If the
design calls for semantic status colors, take the canonical palette from
[Design Language](./design-language.md) § Getting soft semantic badges rather
than inventing hues.

## 8) AI Knowledge Base

The package ships its agent docs in `node_modules/bitboss-ui/dist/ai/`. **Start at** `guides/ai-router.md`, then the catalogue `index.md`. Run `npx bitboss-ui ai-init` in the consumer project to inject harness-agnostic pointers (AGENTS.md, Cursor rules, Copilot instructions, Claude skill, Windsurf rules) so coding agents discover them without a vendor lock-in. After generating Bb\* markup, run `npx bitboss-ui check` (supports `--json`) so unknown props fail before review.

**Three tiers ship under `dist/ai/`**, and the third one is easy to miss:
`guides/` + `recipes/` are the authored prose; `<Name>.md` at the root is the
generated typed contract for each component (props, slots, events, examples);
`source/<Name>.md` is that same component's **complete implementation** —
`.vue` template, `types.ts` and `index.css` in one file, one per component
including the internal ones the package does not export. Read the source tier
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).

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.

**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
source checkout with no build, or an explicit `manifestPath` pointing at
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.

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.

## 9) Setup Verification Checklist

- [ ] package installed (plus `@iconify-json/*` packages for every provider prefix used);
- [ ] build plugin configured: `bitboss-ui/vite` plugin or `bitboss-ui/nuxt` module (`bitboss` config key);
- [ ] `iconDir` points at an existing SVG folder;
- [ ] runtime plugin installed: `app.use(bitbossUiPlugin)` (automatic in Nuxt);
- [ ] style strategy chosen: auto injection (default) or `injectStyles: false` + `import 'bitboss-ui/styles.css'` — auto injection is always library-first, so a Tailwind **v3** app that needs Preflight to load before the library must take the second option (§5);
- [ ] if a reset is required: `resetCss: true` or `import 'bitboss-ui/reset.css'`;
- [ ] Inertia apps: `@inertiajs/vue3` installed (no link registration needed; set `inertiaLinkName` only if you register your own link wrapper).
- [ ] building the [Layout Scaffold](../recipes/vue/layout-scaffold.md)? `npm i @vueuse/core` — `usePageShellContext.ts` imports `injectLocal`/`provideLocal` from it. This library depends on it too, so it can resolve via hoisting without being declared — don't rely on that; declare it in your own `package.json` or a strict installer (pnpm, Yarn PnP) will fail to resolve it.
- [ ] `vite.config.ts` (and any other build config, e.g. `eslint.config.js`) is inside your project's type-check scope — a `tsconfig.node.json` project reference is the conventional shape. Otherwise `bitbossUi(...)`'s typed options (`locale`, the `*Variants` registries, `iconDefaultSizes`, …) are never checked by `vue-tsc --noEmit`, silently defeating the compile-time guarantees this guide documents (e.g. "selecting a non-enabled locale is a compile error").
- [ ] `vue-tsc` is **3.x** (`npx vue-tsc --version`). On 2.x the template type-checker cannot read props off the generic-function declarations this library emits for `BbSelect`, `BbSelectPopover`, `BbTable`, `BbTabs`, `BbTree`, `BbRadioGroup`, `BbCheckboxGroup` and `BbSwitchGroup`, so their props go **entirely unchecked** — missing, misspelled and wrongly-typed props all pass — while unknown-component checking and every non-generic component keep erroring normally, which is exactly why a 2.x gate reads as healthy. See "Known-good toolchain" in [1) Install](#1-install).
- [ ] `tsconfig.json` sets `"vueCompilerOptions": { "checkUnknownComponents": true }`. Vue Language Tools 3 (`vue-tsc`) treats unknown-component checking as **opt-in** — without this flag, a `<BbTabs>` used without its import (or after a typo, or dropped by a bad auto-import config) type-checks clean, lints clean, and passes `bitboss-ui check` (none of the three gates resolve component tags), then renders as a silent unregistered custom element in the browser: no error anywhere, just a missing widget in production. With the flag, `vue-tsc --noEmit` names the exact tag and line (`Property 'BbTabs' does not exist on type '{}'.`) on the offending file, with no false positives from the library itself — nothing in `bitboss-ui`'s runtime plugin globally registers `Bb*` components (only the `v-bb-*` directives are global), so every `Bb*` tag in your templates is expected to resolve through an explicit import.

If one of the checks fails, fix setup before creating component examples.

---

<!-- dist/ai/guides/component-picker.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/component-picker.md -->

# Component Picker

Use this guide to map a UI requirement to the correct `bitboss-ui` component before writing any code.

## Rule

Always pick from the **Consumer API** (`Bb*`) components first. Only fall back to base primitives when the user explicitly requests internal composition. Each linked doc leads with a "Usage & Guidelines" section — read it before the API tables.

---

## Am I about to rebuild one of ours?

The rest of this guide is indexed by _need_, which only answers the question you
thought to ask ("is there a Calendar? a Chart?"). The components that get
reinvented are the small ones nobody thinks to look up — a pilot builder opened
this picker four times and hand-rolled an avatar twice while `BbAvatar` sat in
the Data Display table below. So this section is indexed by **symptom**: match it
against the markup you are about to write, not against a need.

| You are about to write                                                                      | Stop — use                                                                                                   |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| An `<img>` with an initials/icon fallback branch, `border-radius: 50%`, `object-fit: cover` | [BbAvatar](../BbAvatar.md) — `src`/`alt`/size, initials slot, icon fallback, load-error handling             |
| `@keyframes spin` / `animation: … spin` on an element that means "waiting"                  | [BbSpinner](../BbSpinner.md) — sized off the control scale, honours `prefers-reduced-motion`                 |
| A `<span>` pill with a tinted background standing for a status                              | [BbBadge](../BbBadge.md) with a registered `soft-*` variant (design-language § Getting soft semantic badges) |

**`BbAvatar` is circle-only.** Its `border-radius: 50%` is in the component's own
CSS and no prop changes it, so a rounded-**square** avatar genuinely has no answer
here — build that one yourself. Everything else about it (fallbacks, load errors,
sizing) still applies, so the honest options are "use it and accept a circle" or
"hand-roll the square one knowingly", not "hand-roll it because you never saw it".

`npx bitboss-ui check` prints the avatar and spinner rows as
**advisory hints** — never a build failure, since a round `<img>` is sometimes a
logo — on every `.vue` file it scans. That is the backstop: it fires without
anyone thinking to ask. The badge case is not decidable from markup (a tinted
pill is as often decoration as status), so it has no hint and stays your job.

---

## Text Input

| Need                                    | Component                                                                        |
| --------------------------------------- | -------------------------------------------------------------------------------- |
| Single-line text                        | [BbTextInput](../BbTextInput.md)                                                 |
| Multi-line text                         | [BbTextarea](../BbTextarea.md)                                                   |
| Numeric value with clamping/stepping    | [BbNumberInput](../BbNumberInput.md)                                             |
| Color value in a form                   | [BbColorInput](../BbColorInput.md)                                               |
| Calendar date or date range             | [BbDatePickerInput](../BbDatePickerInput.md)                                     |
| Month or year (a reporting period)      | [BbDatePickerInput](../BbDatePickerInput.md) with `type="month"` / `type="year"` |
| Time or time range                      | [BbTimePickerInput](../BbTimePickerInput.md)                                     |
| Free-form tags / tokens typed by user   | [BbTag](../BbTag.md)                                                             |
| File selection via drag-and-drop/picker | [BbDropzone](../BbDropzone.md)                                                   |

- `BbTag` is for **open vocabularies** (skills, keywords, recipients the user invents). If values come from a known set, use `BbSelect` in multiple mode instead.
- `BbDropzone` captures and validates files; it does **not** upload — pair it with your request layer plus `BbProgress`/`useToast`.

---

## Selection from a List of Options

| Need                                                | Component                                |
| --------------------------------------------------- | ---------------------------------------- |
| Dropdown search, single or multi-select             | [BbSelect](../BbSelect.md)               |
| Picker on a custom trigger (no inline form input)   | [BbSelectPopover](../BbSelectPopover.md) |
| Few exclusive options (radio semantics)             | [BbRadioGroup](../BbRadioGroup.md)       |
| Multiple non-exclusive options (checkbox semantics) | [BbCheckboxGroup](../BbCheckboxGroup.md) |
| Multiple options as live on/off settings            | [BbSwitchGroup](../BbSwitchGroup.md)     |
| Approximate value or range from a bounded interval  | [BbSlider](../BbSlider.md)               |
| Whole-number score out of N (stars, rating)         | [BbRating](../BbRating.md)               |

**Choosing between BbSelect, BbRadioGroup, BbCheckboxGroup, BbSwitchGroup:**

- Large, dynamic, or searchable option sets → `BbSelect` (search and async fetch baked in).
- Small static exclusive choice (≤6 items, worth showing in full) → `BbRadioGroup`.
- Small static multi-choice submitted with a form → `BbCheckboxGroup`.
- Each option is a live setting that applies the moment it flips → `BbSwitchGroup`.
- The trigger is a status pill, avatar stack, or table-cell chip rather than a form field → `BbSelectPopover` (same search/options engine as `BbSelect`, you own the trigger).

Never hand-assemble a row of `BbCheckbox`/`BbRadio` — the groups give you fieldset semantics, item mapping, and validation for free.

---

## Single Toggle

| Need                                              | Component                      |
| ------------------------------------------------- | ------------------------------ |
| An answer or an agreement (accept terms, opt in)  | [BbCheckbox](../BbCheckbox.md) |
| The on/off state of a thing (notifications, sync) | [BbSwitch](../BbSwitch.md)     |
| One option interleaved with other markup          | [BbRadio](../BbRadio.md)       |

**BbCheckbox vs BbSwitch — choose on what the control _means_, not on when it commits.** A switch is the on/off **state of a thing**: "Email notifications", "Anyone with the link can view", "Auto-renew". A checkbox is an **answer or a selection**: "I accept the terms", "Also send me a copy", a selected row.

**A switch inside a submit-gated form is correct** — it commits with the form, exactly like every other field. This library ships `BbSwitch` from `bitboss-ui/validated` for that case, its own fixtures put one inside `<BbForm>`, and its wizard recipes put one behind a Next button. Do not downgrade a state toggle to a checkbox just because a Save button exists.

The one thing to avoid is **mixing commit models on one surface**: switches that already took effect the moment they were flipped, sitting under a Save button that implies they had not. Pick one — either the whole panel is live, or the whole form commits on submit.

A lone `BbRadio` is an escape hatch only — for a plain stacked group use `BbRadioGroup`.

---

## Buttons and Actions

| Need                                                                                      | Component                                                                 |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| A single action (or link-shaped button)                                                   | [BbButton](../BbButton.md)                                                |
| A clickable/navigable surface that is not a variant button (card, row, tile, custom link) | [BbBaseButton](../BbBaseButton.md)                                        |
| One dominant action + close alternates                                                    | [BbDropdownButton](../BbDropdownButton.md)                                |
| Menu of actions with no dominant one                                                      | [BbDropdown](../BbDropdown.md)                                            |
| Dangerous action requiring confirmation                                                   | [BbConfirm](../BbConfirm.md) + [useConfirm](../composables/useConfirm.md) |

**Choosing by intent:**

- `BbButton` — a single action, nothing else. Also a navigation trigger via `href`/`to` (see Navigation below). It is variant-first: use it when you want something that looks like a button. It is **not an inline link** — even `variant="link"` keeps the full button box (height + padding) and only recolors it, so it breaks the line height and text flow of a table cell, sentence, or property-grid value. For an inline text link, use `BbBaseButton` (next row).
- `BbBaseButton` — any clickable/navigable surface that is _not_ a variant button: a whole card or list row that links somewhere, an inline **record-identity cell** (a row's name that must truncate and flow at cell width), an in-text link, or a control styled entirely by your own CSS. It carries the same navigation engine as `BbButton` (`href`/`to`/Inertia/active classes) with **zero chrome — the project owns its look** (e.g. a `.plain-link` underline class). Prefer it over hand-rolling `@click="router.push(...)"` on a `<div>`/`<a>`, and over `BbButton variant="link"` for anything inline.
- `BbDropdownButton` — _Save / Save as draft / Save as template_: the primary action is one tap away, alternates behind a chevron. If the "alternates" are unrelated commands, it's a plain menu.
- `BbDropdown` — overflow "…" menus, account menus, context menus. Declare rows through `items`; never rebuild rows, dividers, or keyboard handling in markup. When the menu is just an `items` array with no header/footer/per-item slots, attach the `v-bb-dropdown` directive to the trigger instead of importing the component (see the directive note under Overlays).
- Every destructive action must pass through `useConfirm` first.

---

## Feedback and Status

| Need                                | Component                                                         |
| ----------------------------------- | ----------------------------------------------------------------- |
| Inline persistent status message    | [BbAlert](../BbAlert.md)                                          |
| Transient notification (toast)      | [BbToast](../BbToast.md) + [useToast](../composables/useToast.md) |
| Passive status pill, count, or dot  | [BbBadge](../BbBadge.md)                                          |
| Removable token (filter, selection) | [BbBadge](../BbBadge.md) (with `clearable`)                       |
| Clickable pill / filter chip        | [BbBadge](../BbBadge.md) + `BbBadgeButton` in its default slot    |
| Determinate progress bar            | [BbProgress](../BbProgress.md)                                    |
| Indeterminate loading spinner       | [BbSpinner](../BbSpinner.md)                                      |

**BbAlert vs BbToast:** `BbToast` for _what just happened_ (saved, copied, uploaded — transient, floating, self-dismissing, fired via `useToast`); `BbAlert` for _the current state of the page_ (form error summary, quota banner — in normal document flow, stays until read or dismissed).

**BbAlert takes its body from the default slot**, like the rest of the `text`-prop family: `<BbAlert>Something went wrong</BbAlert>`. `text` as a prop is for when a string is all you have; `#text` wins over both. (Before 2026-08-07 children rendered nothing at all — if you are reading older code that passes `text=` everywhere, that is why.)

**BbBadge vs BbTag vs BbIndicator:** `BbTag` _creates_ tokens (an input); `BbBadge` _displays_ tokens — passive by default, removable with `clearable` (renders a clear button), and interactive when a `BbBadgeButton` is slotted into it (the body becomes a real button/link; combine with `clearable` for the press-to-edit / ×-to-remove filter chip); `BbIndicator` pins a count/dot _over_ another element.

**BbBadgeButton vs BbButton:** both are real buttons — pick by the shape the user should see. `BbButton` looks like a button (variant chrome, button sizing); `BbBadgeButton` makes a **pill** clickable, and only exists inside a `BbBadge`.

**BbProgress vs BbSpinner:** `BbProgress` is for measurable completion (`min`→`max`); passing `null` renders an empty bar, not an indeterminate animation — use `BbSpinner` for waits with no measurable end.

---

## Overlays

| Need                                      | Component                                                              |
| ----------------------------------------- | ---------------------------------------------------------------------- |
| Modal dialog (one focused task)           | [BbDialog](../BbDialog.md)                                             |
| Side panel / drawer                       | [BbOffCanvas](../BbOffCanvas.md)                                       |
| Yes/No confirmation dialog                | [BbConfirm](../BbConfirm.md)                                           |
| Anchored floating interactive content     | [BbPopover](../BbPopover.md)                                           |
| Hover/focus label                         | [BbTooltip](../BbTooltip.md)                                           |
| Color picker on a trigger you own         | [BbColorPalette](../BbColorPalette.md)                                 |
| Date/calendar picker on a trigger you own | [BbDatePicker](../BbDatePicker.md)                                     |
| Month/year picker on a trigger you own    | [BbDatePicker](../BbDatePicker.md) with `type="month"` / `type="year"` |
| Time picker on a trigger you own          | [BbTimePicker](../BbTimePicker.md)                                     |

**BbDialog vs BbOffCanvas:** `BbDialog` for one focused task the user must finish (a form, a blocking announcement) — centred, takes focus. `BbOffCanvas` for supplementary content beside the main task (filters, a record's detail panel, settings). They share the same API (v-model, `title`, `header`/`default`/`footer` slots, `size`, `persistent`), so moving between them is mostly a tag swap. A plain yes/no is `BbConfirm`, not a hand-built dialog.

**BbPopover vs BbTooltip:** `BbTooltip` is a short, non-interactive label on hover/focus — never put links, buttons, or fields in it. `BbPopover` opens on click, stays open, and supports interactive content. A standard list of actions is `BbDropdown`, not a popover.

**Prefer the directive over the component for tooltips and dropdowns.** For the common case — plain-text tooltips and menus declared from an `items` array — attach `v-bb-tooltip` / `v-bb-dropdown` directly to the element instead of importing `BbTooltip`/`BbDropdown` and wiring an `activator`. The directives are registered globally by the plugin (`injectDirectives`, on by default), so no import is needed, and they render no wrapper element. Reach for the **component** only when you need something the directive can't express: for tooltips, a markup label (default slot) or the `activator` slot's scope; for dropdowns, `header`/`footer` or per-item slots, or `<BbDropdownGroup>` companions. When you already hold an element/ref, `BbDropdown`'s `activator` **prop** gives the same no-wrapper wiring without a slot. See [BbTooltip](../BbTooltip.md) and [BbDropdown](../BbDropdown.md).

There are also **`v-bb-color`**, **`v-bb-date`**, and **`v-bb-time`** directives for the narrower case of a value picker on a bare trigger in a table cell — a color dot, a date cell, or a schedule cell — attach the directive instead of wrapping each cell in `BbColorPalette` / `BbDatePicker` / `BbTimePicker`. Unlike tooltip/dropdown this is _not_ a blanket "prefer the directive": these components (and `BbColorInput` / `BbDatePickerInput` / `BbTimePickerInput`) have a real `v-model`, so use the component for form fields; the directive is only for bare per-row triggers. A directive can't two-way bind, so write-back rides an `onUpdate:modelValue` callback in the binding value (plus `onUpdate:time` for a datetime picker). See [BbColorPalette](../BbColorPalette.md), [BbDatePicker](../BbDatePicker.md), and [BbTimePicker](../BbTimePicker.md).

---

## Navigation

| Need                                  | Component                            |
| ------------------------------------- | ------------------------------------ |
| Peer views of the same screen (tabs)  | [BbTabs](../BbTabs.md)               |
| Collapsible section (accordion style) | [BbAccordion](../BbAccordion.md)     |
| Togglable region, custom trigger      | [BbCollapsible](../BbCollapsible.md) |
| Breadcrumb path (where am I)          | [BbBreadcrumbs](../BbBreadcrumbs.md) |
| Pagination controls                   | [BbPagination](../BbPagination.md)   |
| Hierarchical tree                     | [BbTree](../BbTree.md)               |

**Offload navigation to the component.** `BbButton`, dropdown items, and breadcrumb items accept `href` (anchor, or Inertia visit with `method`/`data`/`preserveScroll`/…) and `to` (vue-router); tabs items accept `href`; `BbPagination` with `navigation` builds per-page links itself. Never wire `@click="router.push(...)"` for a plain destination.

**Picking the pattern:** `BbTabs` switches peer sections of _one_ subject (Overview / Activity / Settings) — not steps in a flow, not hierarchy. `BbBreadcrumbs` answers "where am I and how do I get back up". `BbPagination` steps through a paged result set — prefer it over infinite scroll when users need to find their place again.

**Disclosure ladder (BbAccordion vs BbCollapsible vs BbSmoothHeight):**

- `BbAccordion` — composed header button + collapsible body, ARIA wired for you. The default for FAQ/settings sections.
- `BbCollapsible` — v-model region with **no header**; you bring the trigger (inline "read more" link, toolbar toggle).
- `BbSmoothHeight` — no hide/show at all; only animates height changes (wizard steps, growing lists).

---

## Data Display

| Need                          | Component                  |
| ----------------------------- | -------------------------- |
| Rows of records with columns  | [BbTable](../BbTable.md)   |
| Hierarchical expandable nodes | [BbTree](../BbTree.md)     |
| User or entity avatar         | [BbAvatar](../BbAvatar.md) |
| Standalone SVG icon           | [BbIcon](../BbIcon.md)     |

**BbTable vs BbTree:** flat rows with one level of detail → `BbTable` with its `#expand` slot; genuinely recursive data of unbounded depth (file browser, nested categories) → `BbTree`. For a select-a-value list in a form, use the Selection components — not a selectable table.

**A list of records _without_ columns is not a component here** — it is a `<ul>`/`<dl>` styled with tokens ([design-language](./design-language.md) § Layout), with `BbBaseButton` making the whole row navigable. Reach back for `BbTable` with one or two columns when you want what it owns beyond layout: sorting, skeletons, the empty state, selection.

Whatever you put _inside_ those rows, check the symptom index at the top of this guide first — `BbAvatar` is on this page and still gets rebuilt by hand more often than any other component.

Prefer icon **props** (`icon`, `prepend:icon`, item `icon`) on components over standalone `BbIcon`; reach for `BbIcon` only for iconography the design owns (status glyphs, empty states).

---

## Layout and Utility

| Need                       | Component                              |
| -------------------------- | -------------------------------------- |
| Animated height transition | [BbSmoothHeight](../BbSmoothHeight.md) |

---

## Not in this library

The 58 public `Bb*` components plus the exported `use*` composables are the whole
surface. Everything below is a name agents routinely assume exists, invent, and
then work around — usually by hand-rolling something the library already covers
under a different name. **If a component you want is not in the tables above — or
a composable you want is not in this corpus's `composables/` folder — it is not
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 still filtering `columns` — the hidden key keeps its slot in the order. 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.                                                                                                                                                                                                                                                                     |

App chrome — an app shell, sidebar, page header, selection dock — is
deliberately **not** a component: it is yours to own. The per-platform
[Layout Scaffold](../recipes/inertia/layout-scaffold.md) recipe ships the source
to copy.

---

## Item-Driven Components

The following components accept an `items` prop (array or async provider function) with `item-text`/`item-value` mapping. Consult the items playbooks before wiring them:

- [BbSelect](../BbSelect.md), [BbSelectPopover](../BbSelectPopover.md)
- [BbCheckboxGroup](../BbCheckboxGroup.md), [BbRadioGroup](../BbRadioGroup.md), [BbSwitchGroup](../BbSwitchGroup.md)
- [BbTable](../BbTable.md)

`BbDropdown`, `BbBreadcrumbs`, `BbTabs`, and `BbTree` are also declared through `items`, but with typed item objects (label/key/href/…) rather than arbitrary domain objects.

See:

- [Options and Items Playbook](./options-items-playbook.md)
- [Fetch Data Items Playbook](./fetch-items-playbook.md)
- [Coherence Playbook](./coherence-playbook.md)

---

<!-- dist/ai/guides/design-language.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/design-language.md -->

# Design Language

How to make anything built with `bitboss-ui` look like it belongs to the same
product. Follow these rules whenever you write custom CSS next to the
components or choose component variants.

## Hard Rules

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.
3. **One primary action per view region.** Everything else is `secondary`,
   `outline`, or `ghost`.
4. **`destructive` is only for irreversible actions**, and destructive flows
   must go through `useConfirm` first.
5. **Respect the radius**: use `var(--bb-radius)` for any custom container that
   sits next to components; do not invent new corner radii.

## How to style around the library

Three lanes, in order of preference:

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
   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.

## Token Vocabulary

All theme tokens are CSS custom properties defined on `:root` (imported via
`bitboss-ui/styles.css`). One name per token — `.dark` re-declares the knobs
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.

### Surfaces & structure

| Token                 | Meaning                                                                                                                           |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--bb-panel`          | Surface/background color of panels, popovers, dialogs                                                                             |
| `--bb-muted`          | Subtle/disabled surface (derived, neutral)                                                                                        |
| `--bb-hover`          | Hover fill for **affordances** (buttons, links, controls)                                                                         |
| `--bb-surface-hover`  | Hover fill for **passive surfaces** (rows, cells, days) — fainter                                                                 |
| `--bb-pressed`        | Neutral pressed/active fill                                                                                                       |
| `--bb-border`         | Border color; pair with `--bb-border-w` (1px)                                                                                     |
| `--bb-radius`         | Corner radius of controls (8px)                                                                                                   |
| `--bb-radius-surface` | Corner radius of large surfaces (derived, ×1.8)                                                                                   |
| `--bb-radius-sm`      | Corner radius of small nested elements (derived)                                                                                  |
| `--bb-shadow`         | Global elevation shadow                                                                                                           |
| `--bb-panel-p`        | Content padding of large surfaces (dialog, off-canvas); axis split via the locals `--px`/`--py` on `.bb-dialog` / `.bb-offcanvas` |
| `--bb-z-overlay`      | Z-index for overlays (10)                                                                                                         |

### Color semantics

| Token              | Meaning                                                            |
| ------------------ | ------------------------------------------------------------------ |
| `--bb-primary`     | Brand/primary accent (black in light, white in dark by default)    |
| `--bb-primary-fg`  | Foreground on primary surfaces                                     |
| `--bb-danger`      | Errors and destructive intent                                      |
| `--bb-warn`        | Warning **chrome/icons** (`hasWarning`) — warm, ranks below danger |
| `--bb-text-warn`   | Warning **message text** — deeper amber (knob, not derived)        |
| `--bb-text`        | Global text color                                                  |
| `--bb-text-muted`  | Secondary text, hints, placeholders, icons (derived)               |
| `--bb-text-faint`  | Disabled foregrounds (derived)                                     |
| `--bb-ring`        | Focus ring color (derived from primary)                            |
| `--bb-ring-danger` | Focus ring in error states (derived from danger)                   |
| `--bb-ring-warn`   | Focus ring in the warning input state (derived from `--bb-warn`)   |

Rule of thumb: **hover/pressed chrome is neutral; primary tint means
selected.** Never build a hover state from `--bb-primary` — use `--bb-hover`
so themes with loud brand colors keep gray chrome.

### Scale

| Token            | Meaning                                                  |
| ---------------- | -------------------------------------------------------- |
| `--bb-control-h` | Master control height (32px); inputs/buttons/tabs derive |
| `--bb-fs`        | Master font size (14px); component sizes derive          |

### Motion

| Token                    | Meaning                                       |
| ------------------------ | --------------------------------------------- |
| `--bb-transition-fast`   | 150ms — micro-interactions                    |
| `--bb-transition-medium` | 250ms — overlays, most components             |
| `--bb-transition-slow`   | 350ms — large consumer surfaces               |
| `--bb-ease`              | The single easing curve; do not invent others |

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.

## Dark Mode

Adding the `dark` class on `<html>` or any ancestor flips every token. There
is no JS involved. Custom consumer CSS that uses tokens gets dark mode for
free; custom CSS with hardcoded colors breaks it — which is why Hard Rule 1
exists.

To crossfade instead of switching instantly, add `theme-animated` to the
**same element** that carries the scheme class
(`<html class="dark theme-animated">`) — the color knobs are typed with
`@property`, so they interpolate and everything derived follows.

## Variants

Variant names are typed per family. Built-in sets:

| Family                                               | Built-in variants                                                                             |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `BbButton` / `BbDropdownButton`                      | `primary` `secondary` `outline` `ghost` `destructive` `link` (+ `none` unstyled escape hatch) |
| `BbBadge`                                            | `primary` `secondary` `outline` `ghost` `destructive`                                         |
| `BbAlert`                                            | `primary` `outline` `destructive` `warning`                                                   |
| `BbToast` / `useToast`                               | `default` `success` `info` `warning` `destructive`                                            |
| `BbConfirm` / `useConfirm`, dropdown items, tooltips | `default` `destructive`                                                                       |

What the shared names mean (shadcn-style vocabulary):

| Variant       | Use for                                        |
| ------------- | ---------------------------------------------- |
| `primary`     | The single main action of a view region        |
| `secondary`   | Supporting actions                             |
| `outline`     | Neutral actions on busy surfaces               |
| `ghost`       | Low-emphasis, inline, or icon-only actions     |
| `destructive` | Irreversible/dangerous actions (confirm first) |
| `link`        | Navigation disguised as text (buttons only)    |
| `none`        | Unstyled escape hatch — avoid                  |

Projects can register extra variants through the Vite/Nuxt plugin
(`buttonVariants`, `badgeVariants`, `alertVariants`, `confirmVariants`,
`dropdownItemVariants`, `tooltipVariants`, `toastVariants` options).
Registered names become typed values, but the library ships no CSS for them —
the project styles `.bb-button--<name>` (etc.) itself, following the state
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.

## Using color

**Reach for color more than the monochrome default suggests — but make it mean
something.** A calm, mostly-neutral surface with a few deliberate spots of color
reads as modern and confident; color sprinkled for decoration reads as noise.
Add color for one of three reasons, never for prettiness:

1. **Semantic status** — `info`, `success`, `warning`, `error/danger`. A build
   passed, a payment failed, a token is low.
2. **State** — selected / active / dirty / pending / just-changed. Color is a
   fast, pre-verbal "this updated."
3. **Differentiating a small, closed set** — a few statuses, priorities, or
   categories the eye should tell apart at a glance. Only when the set is small
   and fixed; a per-row rainbow of unique colors is noise, not signal.

Keep it **soft and calm**:

- **Chrome stays neutral.** Hover, pressed, and focus chrome use
  `--bb-hover`/`--bb-pressed`/`--bb-ring`; selection uses the primary tint (the
  existing rule). Semantic color goes on the **content** — a status dot, a soft
  badge, a tinted alert — not on interactive chrome. This is what keeps color
  from feeling jarring.
- **Prefer soft tints over saturated fills** on anything bigger than a dot. The
  library's own recipe is `color-mix(in oklab, <hue> ~10–15%, var(--bb-panel))`
  for the fill with the hue itself as text — exactly how `--bb-destructive` is
  built. Mixing toward `--bb-panel` keeps it theme- and dark-mode-aware. Small
  dots may be saturated.
- **One primary action per region still holds.** Semantic color is not a licence
  for five loud buttons.
- **Never color as the _only_ signal.** Pair it with text or an icon — color
  alone fails color-blind users and Hard Rule territory.

### What carries semantic color today (use these first)

| Need                                                | Reach for                                                                             |
| --------------------------------------------------- | ------------------------------------------------------------------------------------- |
| A status marker next to a label/row                 | **BbIndicator** dot — `default` / `success` / `info` / `warning` / `destructive`      |
| A persistent message                                | **BbAlert** — `primary` / `outline` / `warning` / `destructive` (soft tints)          |
| Transient feedback                                  | **BbToast** / `useToast` — `default` / `success` / `info` / `warning` / `destructive` |
| A removable/error tag                               | **BbBadge** `destructive` (soft); neutral tags use `secondary` / `outline`            |
| A form field that needs attention but isn't invalid | any form control's **`warnings`** / **`hasWarning`** props — see below                |

### Meters, ramps, gauges — the project owns every hue (ruled 2026-07-30)

The library ships **no** status-color vocabulary beyond `--bb-danger`,
`--bb-warn`, and `--bb-text-warn` (which exist for its own error/warning
states), and it never will —
no `--bb-success`, no `--bb-good`, no graded ramps. So when a design needs
multi-step color — a password-strength meter, a health score, an SLA bar, a
capacity gauge — the palette is **project CSS, minted by you**, exactly like
the soft badge palette below: local custom properties (`--accent`-style hues,
mixed toward theme tokens with `color-mix(in oklab, …)` so they stay
dark-mode-aware), applied through the component's CSS hooks — e.g.
`BbProgress`'s `--fill`. Reusing `--bb-danger` / `--bb-warn` /
`--bb-text-warn` for the low end of
a ramp is fine if the project chooses to — they are ordinary custom properties —
but that choice, and its contrast, belongs to the project. Do not wait for, or
invent, a library token for the positive end: there isn't one, by ruling.

### Warning input state

Every form control (`BbTextInput`, `BbTextarea`, `BbSelect`, `BbNumberInput`,
`BbColorInput`, the date/time pickers, `BbSlider`, `BbRating`, `BbTag`,
`BbCheckbox`/`BbRadio`/their groups, `BbDropzone`, …) exposes a warning state
that mirrors the error state exactly — two props, parallel to `errors` /
`hasErrors`:

- **`warnings`** (string | string[]) — one or more messages rendered below the
  field in their own `aria-live="polite"` region, in amber (`--bb-text-warn`),
  and referenced from
  the control's `aria-describedby` while displayed (after any `errors`). A non-empty
  `warnings` **implies the warning state** (just as `errors` implies the error
  state), so you rarely set `hasWarning` by hand.
- **`hasWarning`** (boolean) — forces the warning chrome without a message, to
  pre-style a field.

Either way the field gets the **same chrome as the error state** — tinted border
and focus ring, a warning icon in the append stack — but in amber (`--bb-warn` /
`--bb-ring-warn`) instead of danger red. Chrome and icons ride `--bb-warn`
(non-text, ≥3:1); the message copy rides the deeper `--bb-text-warn` (≥4.5:1)
— one token cannot hold both budgets without browning the borders.

Use it for a field that is valid but deserves a second look — a value that is
unusual, near a limit, or soft-flagged — where a hard error (which also sets
`aria-invalid` and blocks submit-shaped flows) would overstate the problem.

- **Errors win when both are set** — a field is never amber and red at once. The
  error chrome takes over and the warning **messages are suppressed** (the
  `warnings` region collapses to zero height); show `errors` and `warnings`
  together and the user sees only the errors.
- Unlike `errors`, `warnings` do **not** set `aria-invalid` — it's a soft "needs
  a second look" state, not an invalid one.
- It is a **field state**, not the badge/button `warning` _variant_ (those stay
  locked — see [the sanctioned custom-variant path](#getting-soft-semantic-badges-the-sanctioned-custom-variant-path)).
- Prefer `warnings` (which carries its own text) over bare `hasWarning` + a
  `hint` — color alone is never the only signal. `warnings` are announced the
  moment they appear (live region) **and** re-read on focus (`aria-describedby`,
  ahead of the hint); a `hint` only ever reads as static description.

```vue
<!-- valid, but worth flagging — amber message, no aria-invalid, no submit block -->
<BbTextInput
	v-model="rate"
	label="Discount"
	:warnings="rate > 50 ? 'That is an unusually large discount.' : undefined"
/>
```

### Badges label state; buttons are actions

A **badge is the right affordance for a status/state marker** — not a `BbButton`,
which is a distinct affordance (an action to perform). When a status marker must
also be **clickable** (opens an editor, filters a list), slot a
**`BbBadgeButton`** into the badge. The badge body becomes a real button in
place, so the pill _is_ the control:

```vue
<BbBadge variant="soft-green" append:icon="lucide:chevron-down">
  <BbBadgeButton v-bind="activatorProps">Done</BbBadgeButton>
</BbBadge>
```

Do **not** wrap the badge in an outer `BbBaseButton` to achieve this (the v2
habit). It nests the interactive element outside the pill, so the hit area and
the focus ring disagree with the visual boundary, and on a `clearable` badge it
nests a button inside a button — invalid markup. `BbBadgeButton` has full
`BbBaseButton` parity (`href`/`to`, Inertia, `disabled`, …), so nothing is lost
by moving the interaction inside.

The badge owns the color, meaning and chrome; the companion owns the
interaction and the focus ring is drawn on the whole pill for you — no
`.my-trigger` class needed. Signal changeability with an **internal** trailing chevron
(`append:icon` on the badge itself) — not a prepend icon and not a separate caret
sitting outside the badge. Make the editable badge a **self-contained component**
with an `editable` prop that hosts its own picker — don't split "button" and
"badge" into two components at the call site. While the picked value saves, set
the badge's `loading` prop: the spinner takes the chevron's place (same size,
nothing shifts) — and in button mode it lands inside the hit target, so the
control never changes shape. Shipped references: the BbTable guide's
inline-editing example ([BbTable](../BbTable.md)) and the
[Inline Edit Playbook](./inline-edit-playbook.md); in-repo live reference:
`src/dev/inline-edit/` — `StatusBadge.vue`, `PriorityBadge.vue`, `AssigneeBadge.vue`
(each a plain badge when not `editable`, a clickable picker when it is). Those
three still use the older wrap-in-`BbBaseButton` form and predate
`BbBadgeButton`; follow the snippet above, not their activator markup.

### Getting soft semantic badges (the sanctioned custom-variant path)

`BbButton` and `BbBadge` ship **no** `success` / `info` / `warning` variants.
The shared status tokens besides `--bb-danger` are `--bb-warn` /
`--bb-text-warn`, and they are
**not** a variant vocabulary — they color the [warning input state](#warning-input-state)
(the `hasWarning` prop and `warnings` messages) and nothing else. There is still **no `--bb-success` /
`--bb-info` token**, and BbIndicator hardcodes its status hues. So:

- **Do not** write `variant="success"` on a badge or button, or invent
  `bb-badge--warning`, **without registering it first** — an unregistered name
  type-errors now, and before the registries existed it shipped no CSS at all
  (the real "warning badge" hallucination that rendered an unstyled pill).
- **Do** register the name via the plugin (`badgeVariants` / `buttonVariants`),
  then style `.bb-badge--<name>` in a **project stylesheet kept separate from the
  library defaults** — the plugin makes the name type-check; you own its CSS.
  Follow the soft recipe above. That is the permanent path — a first-class
  semantic set (`success`/`info`/`warning` variants) was considered and
  rejected (DECISIONS §C 18b): shadcn carries no such vocabulary, and neither
  do we.

**"Locked" means typed, not closed — and registering is part of the job.** The
registries are open by design so each app owns its own tones. If the page you
are writing needs a status palette and the project has not registered one yet,
**add it**: the plugin option and the stylesheet block below are the whole
change, and both belong in the answer. Do not settle for `secondary`/`outline`
because the palette "isn't available" — that silently drops the design intent
(three statuses that must be told apart at a glance become three grey pills).
Just don't do half of it: a registered name with no CSS is the unstyled-pill
bug, and CSS with no registration fails `vue-tsc`.

#### The soft status palette (canonical)

This is the palette to reach for when a design needs semantic status colors on
badges — in examples, recipes, and real apps alike. Five accents, one shared
soft treatment. It mirrors `BbIndicator`'s built-in status hues, plus a slate
neutral the indicator doesn't have:

| Variant      | Accent    | Means                       | Mirrors                             |
| ------------ | --------- | --------------------------- | ----------------------------------- |
| `soft-gray`  | `#64748b` | neutral / idle / paused     | — (slate; no indicator counterpart) |
| `soft-blue`  | `#2563eb` | active / in progress / info | `BbIndicator` `info`                |
| `soft-green` | `#16a34a` | success / done              | `BbIndicator` `success`             |
| `soft-amber` | `#d97706` | attention / high / pending  | `BbIndicator` `warning`             |
| `soft-red`   | `#dc2626` | danger / blocked / failed   | `BbIndicator` `destructive`         |

Register the names in the plugin config, then drop this block into your project
stylesheet (this section is the canonical source — copies elsewhere point back
here):

```css
/* Per-variant accent — the one project-chosen hue each soft variant mixes from.
   Only the library mints `--bb-*` tokens, so the hue lives in a local
   `--accent`; everything derived mixes toward theme tokens, which keeps every
   variant dark-mode-aware with no `.dark` overrides. */
.bb-badge.bb-badge--soft-gray {
	--accent: #64748b;
}
.bb-badge.bb-badge--soft-blue {
	--accent: #2563eb;
}
.bb-badge.bb-badge--soft-green {
	--accent: #16a34a;
}
.bb-badge.bb-badge--soft-amber {
	--accent: #d97706;
}
.bb-badge.bb-badge--soft-red {
	--accent: #dc2626;
}

/* Shared soft treatment — reads the local --accent set above. Percentages sit
   on the emphasis ladder (see design-tokens.md). */
.bb-badge.bb-badge--soft-gray,
.bb-badge.bb-badge--soft-blue,
.bb-badge.bb-badge--soft-green,
.bb-badge.bb-badge--soft-amber,
.bb-badge.bb-badge--soft-red {
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
```

Two gotchas the block already encodes:

- **Selectors are doubled (`.bb-badge.bb-badge--x`) on purpose.** The built-in
  variants compile to 2-class specificity (they're nested under `.bb-badge`), so
  a flat `.bb-badge--x` would tie the base `.bb-badge { --bg }` rule and lose on
  injection order. Match their specificity and this layer wins.
- **The accent hex is the project's own hue, held in a local `--accent`** — it
  is not a `--bb-*` token and must not become one (Hard Rule 1: only the library
  mints those). Everything derived mixes toward `--bb-panel` / `--bb-text`, so
  themes and dark mode keep working for free.

## Sizing

The named scale is `xs | sm | md | lg | xl | 2xl`. It applies to `BbButton` /
`BbDropdownButton`, `BbBadge`, `BbIndicator`, `BbDialog`, and `BbOffCanvas`
(off-canvas adds `'auto'`; dialog and off-canvas also accept a CSS length
string or pixel number as escape hatch). Buttons, dialogs, and off-canvas
also accept a responsive record keyed by breakpoint, e.g.
`:size="{ default: 'sm', lg: 'md' }"`. Rules:

- Stay on the named scale; use numeric/custom CSS sizes only when a named
  preset genuinely cannot work.
- **Buttons prefer `md`** — the default (28px, one step under the 32px
  input height). `md` is exactly the height of a `compact` input, so an
  `md` button sits flush beside compact fields in a filter bar or inline
  form. Since it's the default, idiomatic code omits the `size` prop.
  Reach for `sm`/`xs` only inside genuinely dense surfaces — table row
  actions, toolbars, bulk-action bars — and for `lg`+ only on a rare hero
  action.
- Keep pages compact through **density, not button shrinking**: tight gaps
  and the `compact` boolean, not `size="sm"` everywhere.
- Form controls have no `size` prop — they all share `--bb-control-h`. Density
  is the `compact` boolean, shared by the whole input family plus `BbTable`
  and `BbTabs`; use it together across a whole view, not on single
  components.

## Adaptive Behavior

Surface components (`BbDialog`, `BbPopover`, `BbDropdown`, `BbSelect`,
`BbSelectPopover`, the date/time pickers, `BbColorInput`/`BbColorPalette`…)
accept an `adaptive` prop: on mobile viewports the surface
renders as a bottom sheet (`BbOffCanvas`) instead of a floating
popover/dialog. The global default comes from the plugin config
(`config.adaptive`); the prop overrides it per component. Guidance:

- Leave `adaptive` unset unless the user asks otherwise — the project default
  is usually right.
- If you set it, set it deliberately per surface, not globally in a page.

## Layout

The library deliberately ships **no layout primitives** (no grid, container,
or stack components). Compose pages with plain CSS flex/grid in consumer code,
using tokens for anything visual:

```css
.page__filters {
	display: flex;
	gap: 12px;
	flex-wrap: wrap;
	align-items: flex-end;
}

.page__card {
	background: var(--bb-panel);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	box-shadow: var(--bb-shadow);
}
```

### A trend's colour is its valence, not its direction

"Up is green" is wrong for half the metrics on an ops dashboard. Critical
alerts +12, overdue returns +8, failed jobs +3 — all rising, none good. Paint
the **meaning**, never the arrow:

```ts
// The metric declares which direction is good; the delta only picks the sign.
const kpiDeltaVariant = (metric: Metric, delta: number) => {
	if (delta === 0) return 'soft-gray';
	const rising = delta > 0;
	return rising === metric.risingIsGood ? 'soft-green' : 'soft-red';
};
```

Risk metrics (alerts, overdue, failures, churn) invert: `risingIsGood: false`.
Keep the arrow glyph tied to direction and the colour tied to valence, so a
falling-and-good metric still reads as a down arrow in green. And per the
colour rules above, never let colour carry it alone — the arrow plus the label
have to survive a greyscale print.

### Row tint: a wash the row keeps, orthogonal to selection

A listing row can carry three different states at once — it _is_ something
(overdue, blocked), it is **highlighted** (its peek is open), and it is
**selected** (a bulk action will hit it). Painting all three with the same
primary tint makes them indistinguishable, and painting the semantic one with
the selection colour makes an overdue row look selected.

Keep the axes separate:

- **Row state = a soft semantic wash**, project CSS on the row:
  `background: color-mix(in oklab, var(--bb-danger) 6%, var(--bb-panel))` for
  `.row-danger`, the same recipe over `--bb-warn` for `.row-warn`. Hover
  deepens the same hue (≈10%) rather than switching to the neutral hover, so
  the row does not lose its meaning under the cursor.
- **Selection and highlight stay the library's own chrome** — the checkbox and
  the highlight ring/tint. Never re-tint the row for them.
- **The wash is a background, not a border.** A left border competes with the
  nested-table lead-in and the identity cell's toggle.

Because they are orthogonal, an overdue row that is also selected shows both,
and neither reading is lost:

```css
.row-danger {
	background: color-mix(in oklab, var(--bb-danger) 6%, var(--bb-panel));
}
.row-danger:hover {
	background: color-mix(in oklab, var(--bb-danger) 10%, var(--bb-panel));
}
.row-warn {
	background: color-mix(in oklab, var(--bb-warn) 6%, var(--bb-panel));
}
.row-warn:hover {
	background: color-mix(in oklab, var(--bb-warn) 10%, var(--bb-panel));
}
```

Mix toward `--bb-panel`, not toward transparent, so the wash survives dark mode
and does not stack with the striping.

### Guide helper: `.plain-link`

Define a project-owned `.plain-link` class (not a library variant) for inline
text links in tables, peeks, and property grids — entity-identity cells (a
record's name, number, or title column) above all. Pair it with `BbBaseButton`
so there is no button chrome — faint underline at rest, `currentColor`
underline on hover/focus:

```vue
<BbBaseButton class="plain-link" @click="peekInvoice(item.id)">
	{{ item.number }}
</BbBaseButton>
```

```css
.plain-link {
	color: inherit;
	text-decoration: underline;
	text-underline-offset: 2px;
	text-decoration-color: color-mix(in oklab, var(--bb-text) 25%, transparent);
	transition: text-decoration-color var(--bb-transition-fast) var(--bb-ease);
}
.plain-link:hover,
.plain-link:focus-visible {
	outline: none;
	text-decoration-color: currentColor;
}
```

Do not use `BbButton` `ghost`/`link` for those cells; reserve those variants for
real actions and chrome buttons. `link` in particular keeps button height and
padding, so it never flows or truncates like inline text — wrong for a name
column at cell width (see [BbButton](../BbButton.md) § Choosing a variant).

Spacing convention: use multiples of 4px, favoring 8/12/16/24 gaps. Form
fields stack with 16px gaps; sections separate with 24px.

## Typography

### Display type is for guest surfaces; the workspace inherits

Marketing, auth and other **guest** surfaces may carry a display face on their
titles — that is where a product gets to have a voice. **Workspace** surfaces
(the app behind the login: listings, peeks, forms, dialogs) inherit `--bb-fs`
and the system stack, and get their hierarchy from **weight and colour**, not
from a second family or a jump in size.

The reason is density: an ops screen shows fifty rows of the same shape, and a
display face at 15px costs legibility for nothing. A title that needs to stand
out in the workspace goes to `font-weight: 600` and `--bb-text`, with
supporting text at `--bb-text-muted` — the same two-step the components already
use internally.

So: one display face, scoped to the guest layout's headings. Never on a table,
a peek title, a dialog title, or a field label.

Component typography is token-driven (`--bb-fs`: 14px, from which
`--bb-label-fs` and `--bb-input-fs` derive). For consumer text next to
components: 14px body in data-dense UIs, `--bb-text-muted` for secondary
text, `--bb-label-weight`
(500) for emphasis. Don't introduce new font sizes below 12px.

---

## Component catalogue

Every public component. Open one contract at `https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/<Name>.md` before using it — never guess a prop name.

- **BbAccordion** — Expands and collapses a content panel.
- **BbAlert** — Shows contextual status messages.
- **BbAsterisk** — Presentational required-field marker (red "*"). No props/slots/events; placed in custom label content.
- **BbAvatar** — Displays an avatar and has a fallback content slot.
- **BbBadge** — Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
- **BbBadgeButton** — Makes a badge's body interactive: slotted as a direct child of BbBadge it renders the badge body as a real button/link with full BbBaseButton parity, leaving `clearable` free to remain a separate control.
- **BbBaseButton** — Unstyled button/link primitive: element resolution (button/anchor/router link) and the full navigation engine, with no visual chrome. Use for any clickable or navigable surface that is not a variant-first BbButton — cards, list rows, custom links.
- **BbBaseCheckboxIcon** — Standalone checkbox glyph (box + checkmark SVG). Presentational only — no input, no events. Compose it into a fully custom checkbox design, or let BbCheckbox/BbBaseCheckbox render it.
- **BbBaseRadioIcon** — Standalone radio glyph (ring + dot). Presentational only — no input, no events. Compose it into a fully custom radio design, or let BbRadio/BbBaseRadio render it.
- **BbBaseSwitchIcon** — Standalone switch glyph (track + thumb). Presentational only — no input, no events. Compose it into a fully custom switch design, or let BbSwitch/BbBaseSwitch render it.
- **BbBreadcrumbs** — Renders hierarchical navigation paths.
- **BbButton** — Button with loading state, tooltip, and icon support.
- **BbCheckbox** — Toggles a single boolean option.
- **BbCheckboxGroup** — Manages multiple checkbox options as a group.
- **BbCollapsible** — Toggles visibility of collapsible content blocks.
- **BbColorInput** — Captures color values through input controls.
- **BbColorPalette** — Opens an anchored popover color palette for color picking interactions.
- **BbConfirm** — Prompts users to confirm or cancel critical actions (includes co-located BbConfirmPortal export).
- **BbConfirmPortal** — Registers named slot content that confirm() renders via `portal`.
- **BbDatePicker** — Opens an anchored calendar (and optional time rail) popover on a trigger you own — the date analog of BbColorPalette; also the v-bb-date directive.
- **BbDatePickerInput** — Combines date selection with text input behavior.
- **BbDialog** — Presents modal dialogs for focused user interactions.
- **BbDropdown** — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).
- **BbDropdownButton** — A button with primary action and all other actions collected in a dropdown.
- **BbDropdownGroup** — Renderless v-model companion for a group declared in BbDropdown.items, bound by id.
- **BbDropzone** — Supports drag-and-drop file input flows.
- **BbForm** — Form host for `bitboss-ui/validated`: owns the vee-validate form (useForm), validates every field on submit, and emits `submit` with the collected values only when the form is valid.
- **BbIcon** — Renders an icon either from the local icon folder or from a provider.
- **BbIndicator** — Anchors a notification bubble (count/short text) or a dot over a wrapped element.
- **BbNumberInput** — Captures and validates numeric form values, emits a number value.
- **BbOffCanvas** — Shows side-panel overlay content outside normal layout flow.
- **BbPagination** — Navigates paginated data sets by page index.
- **BbPopover** — Anchors floating content to reference elements.
- **BbProgress** — Visualizes task or operation progress state.
- **BbRadio** — Represents a single choice in exclusive options.
- **BbRadioGroup** — Coordinates exclusive selection among radio options.
- **BbRating** — Collects scalar ratings through interactive icons.
- **BbSelect** — Selects one or many options from structured data.
- **BbSelectPopover** — Provides popover-driven option selection and search.
- **BbSlider** — Selects numeric values across a bounded range.
- **BbSmoothHeight** — Animates height transitions for dynamic content.
- **BbSpinner** — Indicates ongoing loading or pending operations.
- **BbSwitch** — Toggles two-state values with switch semantics.
- **BbSwitchGroup** — Manages grouped switch options with shared behavior.
- **BbTable** — Displays tabular data, configurable columns and data mapper.
- **BbTabs** — Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).
- **BbTabsList** — The trigger strip of a split BbTabsRoot layout (renders the tab buttons only).
- **BbTabsPanes** — The pane host of a split BbTabsRoot layout (renders the tab content only).
- **BbTabsRoot** — Provide/inject root that lets BbTabsList and BbTabsPanes live in separate layout slots.
- **BbTag** — Captures and displays tag-like token values.
- **BbTextarea** — Captures multi-line text values.
- **BbTextInput** — Captures single-line text values.
- **BbTimePicker** — Opens hour/minute(/second) columns in a popover on a trigger you own — the time analog of BbDatePicker; also the v-bb-time directive.
- **BbTimePickerInput** — Segmented time field with hour/minute columns; 24-hour string model.
- **BbToast** — Shows transient notification messages (includes the co-located BbToastPortal export).
- **BbToastPortal** — Registers named slot content that toast() renders via `portal`.
- **BbTooltip** — Displays contextual helper text on interaction.
- **BbTree** — Renders hierarchical expandable tree structures.