bitboss-ui 3.0.0-beta.64 → 3.0.0-beta.66

package/dist/ai/BbBreadcrumbs.md

@@ -735,6 +735,14 @@ States are listed in precedence order: when two are on at once and their entries
 - `#<value>:prepend` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — The glyph before one crumb's label; beats `item:prepend`, which beats its `prepend:icon`.
 - `#<value>:append` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — The glyph after one crumb's label; beats `item:append`, which beats its `append:icon`.
 
+## CSS custom properties
+
+Set these on the element, or on a class you put on it, to retune this component alone — the sanctioned alternative to reaching past the API with `:deep()`. They are this component's own locals — a **Set on** of `pt:<part>` means the local lives on that part's element, so set it through that entry (`pt:box="[--border-color:var(--color-green-500)]"`); the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
+
+| Property | Default | What it is |
+| --- | --- | --- |
+| `--ring-t` | `var(--bb-transition-medium)` |  |
+
 ## Component tree
 
 `BbBreadcrumbs` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbBreadcrumbs`, and before concluding a part, a token or a behaviour does not exist** — it may live on a component further down. How to read it:

package/dist/ai/BbButton.md

@@ -104,6 +104,10 @@ bitbossUi({ buttonVariants: ['upgrade'] });
 export default defineNuxtConfig({ bitboss: { buttonVariants: ['upgrade'] } });
 ```
 
+Retint through these locals, never colour utilities on the button
+(`bg-* text-* border-*`): a utility paints one colour over every state, so
+hover, pressed, disabled and focus all look the same.
+
 The library ships **no CSS for registered variants**: style
 `.bb-button--upgrade` yourself by re-pointing the same locals the built-ins
 use. The root paints rest, hover, press and focus from these, so you never
@@ -160,7 +164,11 @@ primary has no room left, as the default black in light and white in dark
 do: hover is always visible and never sinks into the surface. Pressed takes
 the same move with a larger 1.6:1 step, so it is always the strongest state
 and never equals rest, and a pressed toggle keeps its pressed fill under
-keyboard focus, with the focus ring still showing. The built-in primary
+keyboard focus, with the focus ring still showing. Any BbButton carrying
+`aria-expanded="true"` (menus, popovers, collapsible triggers, row
+expanders) takes the pressed paint while open, since focus has usually moved
+into what it opened; a BbButton without the attribute never does. The
+built-in primary
 moves its frame with the hover and pressed fills and,
 where `contrast-color()` exists, picks each state's label for its own fill
 (a white label on a mid blue can turn dark on the lighter dark-scheme
@@ -278,6 +286,10 @@ no wrapper of your own (`<BbButton>Synced <span class="dot" /></BbButton>`).
 A plain text label is untouched. Wrap rich text in one element
 (`<span>Save <b>all</b></span>`) to keep it one sentence; unwrapped, the `<b>`
 is a child of its own and sits the gap away.
+The label stays on one line: a button with too little room (a full toolbar, a
+narrow card) shrinks and ends its label in "…", the icons kept whole. Several
+children are clipped at the end, not ellipsed, so put a count or a shortcut
+that must stay visible in `append:icon` or next to the button.
 `type` defaults to `'button'`, so a `BbButton` inside a form never submits by
 accident; set `type="submit"` for the one that should, and let the form's
 `@submit` handler own the logic:
@@ -321,6 +333,17 @@ fields — and being the default, you simply omit the `size` prop. Use
 bulk-action bars) and `lg`+ only for a rare hero action. `block` stretches
 the button to its container's width (e.g. mobile CTAs, dialog footers).
 
+Which button sits flush with which field (measured in the default theme; fields
+and choice strips have no `size`, only `compact`):
+
+| Beside                                                                  | Height | Flush button       |
+| ----------------------------------------------------------------------- | ------ | ------------------ |
+| A field (text, number, select, date…) or a `pill` / `line` choice strip | 32px   | `lg`               |
+| The same, `compact`                                                     | 28px   | `md` (the default) |
+
+A strip to match a smaller button is retuned with its own locals (`--list-h`,
+`--fs`, `--p`, …: BbRadioGroup § Segmented control).
+
 **Stretch ≠ `block`.** A flex-column parent (`flex flex-col`) stretches its
 children on the cross axis by default, so a bare `BbButton` dropped into one
 looks exactly as wide as a `block` button even though `block` was never set —
@@ -661,7 +684,7 @@ Escape hatches, when the default isn't right:
   own: promise tracking (e.g. the handler opens a dialog and you don't want a
   spinner flash) and a `type="submit"` button's spin while its `BbForm` saves.
   Only an explicit `loading` shows the spinner then. A click that awaits a
-  dialog (`await useBbDialogContext(id).show()`, `await confirm()`) spins
+  dialog (`await useBbDialog(id).show()`, `await confirm()`) spins
   until the dialog settles, like any async click: that is where this prop
   goes.
 - `interactive-while-loading` — keeps the button clickable while it shows the
@@ -916,6 +939,35 @@ never arrived — offline, DNS, connection reset), are **`router.visit()` /
 does nothing. Reach for a form or an explicit visit when you need to tell those
 apart — see the Inertia helpers guide.
 
+**A spinner for a write that is not a form submit** (resend an invite): an
+`href` + `method` visit shows no loading state, and
+`@click="router.post(url)"` returns nothing to wait on. Return the visit as a
+promise from `@click` instead, and the button spins until the server answers,
+with no `loading` flag of your own: the Inertia helpers' `usePromiseRouter`
+(`usePromiseForm` for a form; Inertia helpers guide § usePromiseRouter):
+
+```ts
+const visits = usePromiseRouter();
+const { toast } = useToast();
+// Catch the rejection: the error bag itself, or an Error (a 500, offline).
+const resend = () =>
+	visits
+		.post(`/users/${id}/invite`)
+		.catch(() =>
+			toast({ title: 'Not sent. Try again.', variant: 'destructive' })
+		);
+// <BbButton @click="resend">Resend invite</BbButton>
+```
+
+**Laravel Wayfinder routes go in as they are.** `href` also takes Inertia's
+`{ url, method }`, what a Wayfinder route returns (the default in Laravel's
+starter kits), so there is no `.url` to split off and no wrapper:
+`<BbButton :href="destroy(user)">Delete</BbButton>` visits with `delete`. The
+pair's `method` wins over a `method` prop, as on Inertia's `<Link>`. The same
+holds for a breadcrumb item's or a dropdown row's `href`. Outside Inertia (a
+plain `<a>`, Nuxt) the link is the pair's `url`, and a method other than
+`get` is ignored, as the `method` prop is: a plain link cannot post.
+
 Every prop Inertia's own `<Link>` accepts is forwarded, and
 `npm run check:inertia-props` fails the build both when Inertia adds one we
 don't forward and when we declare a callback `<Link>` never accepted. The list
@@ -951,8 +1003,8 @@ object form, a style and attributes — optionally only while a state is on.
 Parts: `root` (the button), `icon` (every content icon the button renders:
 `icon`, `prepend:icon`, `append:icon` — a broadcast), `spinner`, `text` (the
 label span). Typography inherits from `root`, so reach for `text` only when a
-class must apply to the label ALONE — `truncate` on a long label that must not
-clip the icons beside it. That span also carries the margin the label slides by
+class must apply to the label ALONE — a mono font, say (it already ends a long
+label in "…" without clipping the icons beside it). That span also carries the margin the label slides by
 while the spinner is in, so a margin of your own fights the slide. States:
 `loading`, `disabled`, `pressed` (a `v-model` toggle that is on), and on a
 link `activeLink` / `exactActiveLink` (it points at the current page: see
@@ -1034,9 +1086,9 @@ utility wins. What works in every build:
 
 - `BbDropdownButton` — escalate to it when a primary action grows close
   alternates; it shares this component's `variant`/`size`/loading language.
-- `useConfirm` — gate every `destructive` button behind a confirm: mount the
-  `<BbHost />` once (app root), `await confirm(...)` in the handler and
-  act only on a yes. The dialog's own buttons are `BbButton` configs (see the
+- `useConfirm` — gate every `destructive` button behind a confirm:
+  `await confirm(...)` in the handler and act only on a yes (the plugin's
+  `<BbHost />` renders it, nothing to mount). The dialog's own buttons are `BbButton` configs (see the
   composable doc), so the confirm speaks the same `variant`/icon language:
 
 **Destructive action gated behind useConfirm**
@@ -1074,18 +1126,11 @@ utility wins. What works in every build:
 		<p v-if="keys.length === 0" class="text-xs text-(--bb-text-muted)">
 			No active keys.
 		</p>
-
-		<!--
-			Standalone example: it mounts its own host because it has no app root.
-			A real app mounts exactly one <BbHost /> at the app root, and pages
-			mount none. See ai/guides/agent-contract.md § Global Host Rule.
-		-->
-		<BbHost />
 	</div>
 </template>
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbButton, BbHost, useConfirm } from 'bitboss-ui';
+import { BbButton, useConfirm } from 'bitboss-ui';
 
 type ApiKey = { id: string; label: string; masked: string; created: string };
 
@@ -1220,7 +1265,7 @@ Anti-patterns:
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `icon`, `root`, `spinner`, `text`. States: `activeLink`, `destructive`, `disabled`, `exactActiveLink`, `ghost`, `link`, `loading`, `outline`, `pressed`, `primary`, `secondary`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activeClass` | `string \| undefined` |  |  | Class to apply when the link is active. |
 | `append:icon` | `string \| undefined` |  |  | Icon to be added on the right of the text. |
-| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` | `'page'` |  | Value passed to the attribute `aria-current` when the link is exact active. |
+| `ariaCurrentValue` | `"time" \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| undefined` | `'page'` |  | Value passed to the attribute `aria-current` when the link is exact active. |
 | `async` | `boolean \| undefined` | `false` |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
 | `block` | `boolean \| undefined` | `false` |  | Displays the component as full width. |
 | `cacheFor` | `string \| number \| (string \| number)[] \| undefined` |  |  | Inertia: how long a prefetched response stays fresh before it is re-fetched. A single duration, or `[staleAfter, expiresAfter]`. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
@@ -1236,7 +1281,7 @@ Anti-patterns:
 | `falseValue` | `any` | `false` |  | Value emitted when the toggle is deactivated. |
 | `group` | `boolean \| undefined` | `false` |  | Identifies the button as part of a button group: adjacent `group` buttons fuse into one segment (shared borders and radius). Adjacent `group` toggles (each with a `v-model`) are also one Tab stop, with ArrowLeft / ArrowRight / Home / End moving between them. |
 | `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
-| `href` | `string \| undefined` |  |  | Returns the hyperlink's URL. Can be set, to change the URL. |
+| `href` | `string \| { url: string; method: "get" \| "post" \| "put" \| "patch" \| "delete"; } \| undefined` |  |  | The link target: renders an anchor (an Inertia `<Link>` under Inertia). Also takes Inertia's `{ url, method }`, a Wayfinder route: Inertia visits with its method; elsewhere the link is its `url`. |
 | `icon` | `string \| undefined` |  |  | Used when only an icon with no text should be displayed. |
 | `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
 | `interactiveWhileLoading` | `boolean \| undefined` | `false` |  | Keeps the button clickable while it is loading. Buttons are disabled while loading by default; this escape hatch exists for toggles that must stay interactive (e.g. the dropdown-button caret). |
@@ -1268,7 +1313,7 @@ Anti-patterns:
 | `text` | `string \| undefined` |  |  | Text content of the component. |
 | `to` | `string \| wt \| bt \| undefined` |  |  | Route Location the link should navigate to when clicked on. |
 | `trueValue` | `any` | `true` |  | Value emitted when the toggle is activated. |
-| `type` | `"button" \| "submit" \| "reset" \| undefined` |  |  | Gets the classification and default behavior of the button. |
+| `type` | `"button" \| "reset" \| "submit" \| undefined` |  |  | Gets the classification and default behavior of the button. |
 | `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'secondary'` \| `'none'` \| `'ghost'` \| `'link'` | `"primary"` |  | Visual variant of the button: colours and surface only, never spacing or size. `'none'` takes no look (you own hover, focus and disabled); register a real one with the plugin's `buttonVariants` and style `.bb-button--<name>` (no CSS ships for it). |
 | `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
 
@@ -1364,7 +1409,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--gap` | `var(--gap-md)` | between icon and label |
 | `--bg` | `transparent` | the plate |
 | `--bg-hover` | `var(--bg)` | also the focus-visible fill; no change by default |
-| `--bg-pressed` | `var(--bg)` | fill while [aria-pressed='true'] |
+| `--bg-pressed` | `var(--bg)` | fill while pressed, or open (aria-expanded) |
 | `--fg` | `initial` | label and icons (icons paint currentColor) |
 | `--border-color` | `transparent` | the frame; its width is --bw |
 | `--ring-color` | `transparent` | focus ring colour, per variant |
@@ -1372,12 +1417,13 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--bw` | `var(--bb-border-w)` | border width |
 | `--fg-hover` | `var(--fg)` | label and icons on hover (and focus-visible) |
 | `--border-hover` | `var(--border-color)` | the frame on hover (and focus-visible) |
-| `--fg-pressed` | `var(--fg)` | label and icons while [aria-pressed='true'] |
-| `--border-pressed` | `var(--border-color)` | the frame while [aria-pressed='true'] |
+| `--fg-pressed` | `var(--fg)` | label and icons while pressed or open |
+| `--border-pressed` | `var(--border-color)` | the frame while pressed or open |
 | `--bg-disabled` | `var(--bb-muted)` | the plate while disabled (not loading) |
 | `--fg-disabled` | `color-mix(in oklab, var(--bb-text) 45%, var(--bb-panel))` | label and icons while disabled |
 | `--border-disabled` | `var(--bb-muted)` | the frame while disabled |
 | `--opacity-disabled` | `1` | whole-button opacity while disabled — `.5` with the three above set to the resting tokens gives "fade instead of grey" |
+| `--ring-t` | `var(--bb-transition-medium)` |  |
 | `--elev-tier` | `var(--bb-elev)` | the shadow a plate variant may take |
 | `--elev` | `0 0 0 0 transparent` | the shadow painted; flat variants keep this |
 

package/dist/ai/BbCalendar.md

@@ -186,6 +186,54 @@ const onPick = (value: string | string[] | null) => {
 };
 ```
 
+### Several months side by side
+
+`:number-of-months="2"` shows two month grids next to each other, so a range
+that crosses the month line has both ends on screen. Any count renders as
+asked. Each month is its own labelled grid (its month and year), and the whole
+calendar is still one Tab stop. The arrows step a whole page (all the months on
+show), and the keyboard moves from the last day of one month into the next
+one. Past the last month on show, the view jumps a whole page. When there isn't
+room for all the months in one row, they wrap onto the next row. The month and
+year headings belong to the first month. Their panels replace it, and picking
+there moves the whole view. The day grids are the only ones with several
+months: `type="month"` and `type="year"` ignore the prop.
+
+**A stay across the month line — two months**
+
+```vue
+<template>
+	<div class="grid w-fit gap-3 rounded-(--bb-radius) border p-4">
+		<p class="m-0 text-sm font-medium">{{ summary }}</p>
+		<BbCalendar
+			v-model="stay"
+			aria-label="Stay"
+			floating
+			:number-of-months="2"
+			range
+		/>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbCalendar } from 'bitboss-ui';
+
+/** A stay that crosses the month line: both ends on screen at once. */
+const stay = ref<string[]>(['2026-10-29', '2026-11-03']);
+
+const summary = computed(() => {
+	const [from, to] = stay.value;
+	if (!from) return 'Pick a check-in day';
+	if (!to) return 'Now pick the check-out day';
+	return `${from} → ${to}`;
+});
+</script>
+```
+
+With more than one month, the days of the neighbouring months are left blank:
+a date belongs to one grid only.
+
 ### `type` — what you are picking
 
 One prop decides the grid and the shape of the emitted string:
@@ -528,6 +576,8 @@ The calendar is an ordinary control in the tab order: **one tab stop** lands
 on the day under the cursor (the value, or today), arrows move by day and
 week, Home / End jump to the ends of the grid's row, PageUp / PageDown page by month
 (with Shift, by year), typing a day number jumps to it, Enter or Space picks.
+With `number-of-months`, every key crosses from one month on show into the
+next, and leaving the last (or first) one moves the view a whole page.
 The grid is a `role="grid"` of `role="row"` / `gridcell` nodes; a picked day
 carries `aria-selected` and says "selected" in its name, a pending range
 announces "select an end date", and the month / year headings are buttons
@@ -614,8 +664,9 @@ the page is `BbDatePicker`.
 | `max` | `string \| undefined` |  |  | Maximum selectable value, in this `type`'s shape. A finer bound is accepted and ceiled to the unit, with a warning. With `datetime`, on its own day the time rail disables the times after it. |
 | `min` | `string \| undefined` |  |  | Minimum selectable value in this `type`'s shape (`YYYY-MM-DD`; `YYYY-MM-DDTHH:mm` with `datetime`, `YYYY-MM` with `month`, `YYYY` with `year`). A finer bound is floored to the unit, with a warning. With `datetime` the rail also disables the earlier times on its day. |
 | `modelValue` | `string \| string[] \| null` |  | yes | v-model: `null` when empty, a string, a `[start, end]` pair with `range`, or a sorted array with `multiple`. The string is `YYYY-MM-DD` when `floating` (`YYYY-MM` / `YYYY` for `month` / `year`), otherwise a zoned ISO instant (carrying the time under `datetime`). |
-| `multiple` | `boolean \| undefined` | `false` |  | Multi-selection: each pick toggles a value in a sorted array (days, months or years). Needs an array `modelValue` (`[]` when empty, never `null`). Throws with `range` or `type="datetime"`. |
-| `range` | `boolean \| undefined` | `false` |  | Enables range selection (`[start, end]`). |
+| `multiple` | `boolean` | `false` |  | Multi-selection: each pick toggles a value in a sorted array (days, months or years). Needs an array `modelValue` (`[]` when empty, never `null`). Throws with `range` or `type="datetime"`. |
+| `numberOfMonths` | `number \| undefined` | `1` |  | How many months show side by side (day grids only). The keyboard crosses from one month into the next, and the arrows page all of them at once. Too narrow for them all, the months wrap onto the next row. |
+| `range` | `boolean` | `false` |  | Enables range selection (`[start, end]`). |
 | `readonly` | `boolean \| undefined` | `false` |  | Shows the calendar and lets the user page through it, but no pick changes the value. |
 | `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds column (requires `type="datetime"`). |
 | `selectable` | `((date: string) => boolean) \| undefined` |  |  | Predicate invoked per candidate; return `false` to disable it. Receives the value in this `type`'s shape — `YYYY-MM` under `month`, `YYYY` under `year`. |
@@ -631,7 +682,7 @@ the page is `BbDatePicker`.
 | Part | What it is |
 | --- | --- |
 | `root` | The calendar's box: the grid and, with `type="datetime"`, the time rail beside it. A consumer `class` lands here. It carries the sizing tokens — `pt:root="[--cell:36px]"` widens the whole calendar, `pt:root="[--px:2px]"` tightens its padding — and the grid's width follows. |
-| `header` | The navigation bar: the previous / next arrows and the month / year headings. |
+| `header` | The navigation bar: the previous / next arrows and the month / year headings. With `number-of-months`, every month's header row (the later ones caption their month). |
 | `arrow` | The previous / next buttons — a broadcast. |
 | `month` | The month heading button; it opens the month panel. |
 | `year` | The year heading button; it opens the year panel. |
@@ -683,6 +734,8 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--py` | `.bb-calendar` | `8px` |  |
 | `--nav-button-h` | `.bb-calendar` | `24px` |  |
 | `--unit-row` | `.bb-calendar` | `calc(var(--cell) * 1.25)` | Row pitch for the coarse grids (month/year), where a "row" is one of four month rows rather than a week. Roomier than --cell because twelve months in a 4×3 grid have space the 6×7 day grid does not. |
+| `--ring-t` | `.bb-calendar__arrow` | `var(--bb-transition-medium)` |  |
+| `--ring-t` | `.bb-calendar__heading-btn` | `var(--bb-transition-medium)` |  |
 
 ## Component tree
 

package/dist/ai/BbCheckbox.md

@@ -587,7 +587,7 @@ no box.
 				:name="pref.name"
 				:persistent-hint="!!pref.hint"
 				pt:description="text-xs"
-				pt:icon:focused="ring-2 ring-(--bb-primary) ring-offset-2"
+				pt:icon:focused="outline-(--bb-primary) outline-offset-2"
 				pt:label="font-medium"
 			/>
 		</div>

package/dist/ai/BbCheckboxGroup.md

@@ -510,7 +510,7 @@ checked day painted, the hint reading the choice back:
 			pt:icon="hidden"
 			pt:item="justify-items-center rounded-(--bb-radius) border py-2 hover:bg-(--bb-muted)"
 			pt:item:checked="border-(--bb-primary) bg-(--bb-primary) hover:bg-(--bb-primary-hover)"
-			pt:item:focus-visible="ring-2 ring-(--bb-primary-ring)"
+			pt:item:focus-visible="ring-2 ring-(--bb-ring)"
 			pt:label="text-sm font-medium"
 			pt:label:checked="text-(--bb-primary-fg)"
 			pt:list="[--gap:6px] [--tile-min-width:0px]"
@@ -664,8 +664,11 @@ never wraps (it scrolls); `list-layout="vertical"` stacks it into a column
 (runs stack on the Y axis), `"vertical-stretch"` spans the field, and the
 other layouts and `item-layout` do not apply. `pt:indicator` reaches every
 pill or bar, and `pt:<part>:pill` / `pt:<part>:line` style a part in one look
-only. The strip's tokens are its own, named and valued as a tab strip's; a
-registered `checkboxVariants: ['brand']` sets them on
+only. The strip's tokens are its own, named and valued as a tab strip's. A
+strip has no `size`: it is `--bb-control-h` tall like a field (`compact` drops
+it to 28px), and you size it with `--list-h`, `--list-r`, `--fs`, `--p` and
+`--trigger-px` on `.bb-checkbox-group__list--strip`; beside an `sm` button that
+is `pt:list="[--list-h:24px] [--fs:12px] [--p:2px]"`. A registered `checkboxVariants: ['brand']` sets them on
 `.bb-checkbox-group__list--brand` and draws pills per run, as `pill` does.
 
 **Pick values with the tabs look**
@@ -1179,11 +1182,44 @@ States are listed in precedence order: when two are on at once and their entries
 
 Set these on the element, or on a class you put on it, to retune this component alone — the sanctioned alternative to reaching past the API with `:deep()`. They are this component's own locals — a **Set on** of `pt:<part>` means the local lives on that part's element, so set it through that entry (`pt:box="[--border-color:var(--color-green-500)]"`); the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
 
-| Property | Default | What it is |
-| --- | --- | --- |
-| `--gap` | `24px` | Space between rows on one line. |
-| `--row-gap` | `10px` | Space between wrapped lines. |
-| `--tile-min-width` | `96px` | How narrow a tile may get before the tiles wrap (`tiles` only). |
+| Property | Set on | Default | What it is |
+| --- | --- | --- | --- |
+| `--gap` | `.bb-checkbox-group__list` | `24px` | Space between rows on one line. |
+| `--row-gap` | `.bb-checkbox-group__list` | `10px` | Space between wrapped lines. |
+| `--tile-min-width` | `.bb-checkbox-group__list` | `96px` | How narrow a tile may get before the tiles wrap (`tiles` only). |
+| `--list-bg` | `.bb-checkbox-group__list--strip` | `color-mix(in oklab, var(--bb-text) 8%, transparent)` | The strip behind the triggers |
+| `--list-border` | `.bb-checkbox-group__list--strip` | `transparent` | The strip's edge line, --bb-border-w thick, painted inside the strip: under the triggers (beside them when vertical). `pill` draws none; `line` sets it to --bb-border |
+| `--p` | `.bb-checkbox-group__list--strip` | `3px` | strip inner padding — the gutter the indicator sits in, and the scroll inset |
+| `--list-r` | `.bb-checkbox-group__list--strip` | `var(--bb-radius)` | strip corners |
+| `--list-h` | `.bb-checkbox-group__list--strip` | `var(--bb-control-h)` | strip min height |
+| `--fs` | `.bb-checkbox-group__list--strip` | `var(--bb-fs)` | trigger label size |
+| `--trigger-gap` | `.bb-checkbox-group__list--strip` | `0px` | space between triggers |
+| `--trigger-px` | `.bb-checkbox-group__list--strip` | `10px` | trigger side padding |
+| `--trigger-r` | `.bb-checkbox-group__list--strip` | `calc(var(--list-r) - var(--p))` | Trigger corners, concentric inside --list-r |
+| `--trigger-min-h` | `.bb-checkbox-group__list--strip` | `calc(var(--list-h) - var(--p) * 2)` | Trigger height inside the padded strip |
+| `--list-fg` | `.bb-checkbox-group__list--strip` | `var(--bb-text-muted)` | unchecked trigger label |
+| `--hover-fg` | `.bb-checkbox-group__list--strip` | `var(--bb-text)` | hovered trigger label |
+| `--active-fg` | `.bb-checkbox-group__list--strip` | `var(--bb-text)` | checked trigger label |
+| `--active-fw` | `.bb-checkbox-group__list--strip` | `500` | checked trigger label weight (unchecked labels are 500) |
+| `--indicator-bg` | `.bb-checkbox-group__list--strip` | `var(--bb-panel)` | the indicator's fill |
+| `--indicator-border` | `.bb-checkbox-group__list--strip` | `color-mix(in oklab, var(--bb-text) 8%, transparent)` | The indicator's edge |
+| `--indicator-r` | `.bb-checkbox-group__list--strip` | `var(--trigger-r)` | The indicator's corners — the pill's, concentric inside --list-r |
+| `--indicator-h` | `.bb-checkbox-group__list--strip` | `initial` | The indicator's thickness: its height, its width on a vertical strip. `initial` fills the whole trigger box — the pill; a bar is `2px`, on the trigger's bottom edge (inline-end edge when vertical) |
+| `--indicator-inset` | `.bb-checkbox-group__list--strip` | `0px` | Inset of the indicator from the trigger box — shrinks the pill; a bar keeps its thickness, shortens by it at both ends and floats it above the edge |
+| `--elev` | `.bb-checkbox-group__list--strip` | `var(--bb-elev)` | The theme's resting lift, composed UNDER the indicator's own shadow |
+| `--indicator-shadow` | `.bb-checkbox-group__list--strip` | `var(--bb-shadow-sm)` | Indicator lift, painted on top of --elev |
+| `--list-bg` | `.bb-checkbox-group__list--line` | `transparent` |  |
+| `--list-border` | `.bb-checkbox-group__list--line` | `var(--bb-border)` |  |
+| `--p` | `.bb-checkbox-group__list--line` | `0px` |  |
+| `--list-r` | `.bb-checkbox-group__list--line` | `0px` |  |
+| `--trigger-r` | `.bb-checkbox-group__list--line` | `var(--bb-radius-sm)` |  |
+| `--active-fw` | `.bb-checkbox-group__list--line` | `600` |  |
+| `--indicator-bg` | `.bb-checkbox-group__list--line` | `var(--bb-primary)` |  |
+| `--indicator-border` | `.bb-checkbox-group__list--line` | `transparent` |  |
+| `--indicator-r` | `.bb-checkbox-group__list--line` | `0` |  |
+| `--indicator-h` | `.bb-checkbox-group__list--line` | `2px` |  |
+| `--indicator-shadow` | `.bb-checkbox-group__list--line` | `none` |  |
+| `--elev` | `.bb-checkbox-group__list--line` | `none` |  |
 
 ## Component tree
 

package/dist/ai/BbColorInput.md

@@ -43,7 +43,7 @@
 | `--border-focus` | `pt:box` | `CommonFieldInput` | frame while focused, or --active |
 | `--ring-size` | `pt:box` | `CommonFieldInput` | ring width; 0 is a variant declining the ring |
 | `--ring-color` | `pt:box` | `CommonFieldInput` | ring colour; state owns it, not variants |
-| `--elev` | `pt:box` | `CommonFieldInput` | Resting lift, composed UNDER the ring at every box-shadow site below. `0 0 0 0 transparent` and not `none`, so the shadow list keeps a constant length and stays interpolable whatever a variant assigns — the same reason `--bb-elev` itself ships that value. |
+| `--elev` | `pt:box` | `CommonFieldInput` | Resting lift, alone in `box-shadow`: the ring is the box's outline (Q81.6), so a theme's `--elev: none` never takes the ring with it. |
 | `--frost` | `pt:box` | `CommonFieldInput` | Plate frost — a full `backdrop-filter` value (see --bb-surface-filter). Routed through a local rather than read from the token directly, so a chrome-less variant can decline it: frosting a ghost field gives it the plate it is contractually not supposed to have. |
 | `--inside-label-clearance` | `pt:box`, `pt:prefix`, `pt:suffix` | `CommonFieldInput` | Height and top padding added above the text for a label rendered inside the box. Zero here; the `--inside-label` rules at the bottom of this file raise it to one label line, or two with a description. |
 | `--w` | `pt:icon` | `BbIcon` | `--w` is set inline by BbIcon from the size prop. The `initial` default seals it: without it an ancestor's `--w` (e.g. a dropdown's width bridge) would inherit in and size the icon. The `--size` indirection stays so higher-specificity rules (e.g. `.bb-badge .bb-icon`) can re-point it. |
@@ -697,7 +697,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `formless` | `boolean \| undefined` | `false` |  | Keep this control out of the enclosing `BbForm` entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch). |
 | `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
 | `hasWarnings` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
-| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
+| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. Pair it with a `placeholder`: an empty field otherwise shows nothing saying what it is for. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
 | `id` | `string \| undefined` |  |  | The `id` of the native control; the label's `for` and the description and message ids derive from it. Generated when omitted. |
 | `inputAlign` | `FieldCrossAlign \| undefined` |  |  | Vertical position of the control in a side-by-side row; not `inputPosition`, the horizontal one. Omitted, the control's first line meets the label's. |
@@ -799,6 +799,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | Property | Set on | Default | What it is |
 | --- | --- | --- | --- |
 | `--elev` | `.bb-color-input__indicator` | `var(--bb-elev-sm)` | Small-chrome resting lift, DECLARED here so it is sealed: an ancestor that sets `--elev` for its own plate must not reach in and lift this. Same tier and same name as the checkbox and radio glyphs. |
+| `--ring-t` | `.bb-color-input__indicator` | `var(--bb-transition-medium)` |  |
 | `--border-color` | `pt:box` | `per variant` | The resting border, at the fixed --bb-border-w. Errors and warnings paint their frame over it, so `pt:box="[--border-color:…]"` recolours the rest without hiding the state; a plain `border-*` utility on the base pt:box would hide it (ESLint `no-box-border-color`). |
 
 ## Component tree

package/dist/ai/BbColorPalette.md

@@ -808,9 +808,13 @@ States are listed in precedence order: when two are on at once and their entries
 
 Set these on the element, or on a class you put on it, to retune this component alone — the sanctioned alternative to reaching past the API with `:deep()`. They are this component's own locals — a **Set on** of `pt:<part>` means the local lives on that part's element, so set it through that entry (`pt:box="[--border-color:var(--color-green-500)]"`); the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
 
-| Property | Default | What it is |
-| --- | --- | --- |
-| `--edge` | `color-mix(in oklab, var(--bb-text) 8%, transparent)` | The swatch's own edge: a text-tone hairline, so a pale swatch reads on a light panel AND a deep one (green-900, indigo-900) on a dark panel — a fixed black 8% vanished there. |
+| Property | Set on | Default | What it is |
+| --- | --- | --- | --- |
+| `--ring-t` | `.bb-color-palette__canvas-wrap` | `var(--bb-transition-medium)` |  |
+| `--ring-t` | `.bb-color-palette__eyedropper` | `var(--bb-transition-medium)` |  |
+| `--ring-t` | `.bb-color-palette__slider-wrap` | `var(--bb-transition-medium)` |  |
+| `--edge` | `.bb-color-palette__swatch` | `color-mix(in oklab, var(--bb-text) 8%, transparent)` | The swatch's own edge: a text-tone hairline, so a pale swatch reads on a light panel AND a deep one (green-900, indigo-900) on a dark panel — a fixed black 8% vanished there. |
+| `--ring-t` | `.bb-color-palette__swatch` | `var(--bb-transition-medium)` |  |
 
 ## Component tree