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

package/bin/bitboss-ui-mcp.mjs

@@ -490,16 +490,53 @@ const STYLES_CSS = join(PACKAGE_ROOT, 'dist', 'styles.css');
  * every comma-part is built solely from these — `:root`, `.light`, `:root.dark`
  * and `html.dark` are theme roots; `.bb-tooltip .bb-common-popover__bubble` is
  * not, however many `--bb-*` it redeclares.
+ *
+ * `.bb-theme` is a theme root too: it is the island boundary the derived block
+ * re-specifies its formulas on (design-tokens.md § the CSS mechanic).
+ */
+const THEME_ROOT_PART = /^(?::root|html|body|\.light|\.dark|\.bb-theme)+$/;
+
+/**
+ * Unwrap the `:where(…)` / `:is(…)` a selector list may be wrapped in. The
+ * derived-token block ships as `:where(:root,.light,.dark,.bb-theme)`, and
+ * splitting THAT on commas yields `:where(:root` and `.bb-theme)` — neither of
+ * which is a theme root, so without this every derived token is misreported as
+ * a component rebind with no value. That is not a cosmetic slip: `localRebinds`
+ * is documented to agents as "not something to copy".
  */
-const THEME_ROOT_PART = /^(?::root|html|body|\.light|\.dark)+$/;
+function unwrapSelectorList(selector) {
+	const trimmed = selector.trim();
+	const match = /^:(?:where|is)\((.*)\)$/s.exec(trimmed);
+	return match ? match[1] : trimmed;
+}
+
 function isThemeSelector(selector) {
-	return selector
+	return unwrapSelectorList(selector)
 		.split(',')
 		.every((part) =>
 			THEME_ROOT_PART.test(part.replace(/[\s>+~]+/g, '').trim())
 		);
 }
 
+/**
+ * A theme token is a KNOB (the consumer sets it) or DERIVED (a formula the
+ * library recomputes at every theme boundary). Setting a derived value is the
+ * documented trap — it stops tracking the knob it was computed from.
+ *
+ * The split is structural in the shipped sheet, so it needs no curated list to
+ * drift: knobs are declared on the plain scheme roots, formulas inside the
+ * `:where(…)` boundary block. A name in BOTH is a knob that TRACKS another one
+ * until pinned — and because the boundary block re-specifies it, a pin has to
+ * be repeated at every boundary it is used on, `.dark` included.
+ */
+const isDerivedBlock = (selector) => /^:(?:where|is)\(/.test(selector.trim());
+const tokenKind = (inKnobBlock, inDerivedBlock) =>
+	inKnobBlock && inDerivedBlock
+		? 'knob-tracking'
+		: inDerivedBlock
+			? 'derived'
+			: 'knob';
+
 /**
  * Walk a stylesheet and yield every `--bb-*` declaration WITH the selector that
  * owns it. A flat regex cannot do this: it sees a declaration but not its
@@ -552,7 +589,8 @@ function* eachTokenDeclaration(css) {
  * different components and is only meaningful inside that component's scope.
  * Serving them as one flat list would invite exactly the wrong move — an agent
  * writing `:root { --gap: … }` and wondering why nothing changed. They are
- * documented per component, which `get_component` already serves.
+ * documented per component: `get_component` carries them as `cssProps`, each
+ * with the root class to set it on, its default, and what it is.
  *
  * WHY `dist/styles.css` AND NOT `src/assets/css/variables.css`: `src/` is not
  * in the published package, so the source file does not exist for the consumer
@@ -573,8 +611,15 @@ function listTokens({ filter } = {}) {
 	const css = readFileSync(STYLES_CSS, 'utf-8');
 	const byName = new Map();
 	for (const { name, value, selector } of eachTokenDeclaration(css)) {
-		const entry = byName.get(name) ?? { theme: [], local: [] };
+		const entry = byName.get(name) ?? {
+			theme: [],
+			local: [],
+			knobBlock: false,
+			derivedBlock: false,
+		};
 		if (isThemeSelector(selector)) {
+			if (isDerivedBlock(selector)) entry.derivedBlock = true;
+			else entry.knobBlock = true;
 			// Light first, dark after: report both rather than let one win.
 			if (!entry.theme.includes(value)) entry.theme.push(value);
 		} else if (!entry.local.some((r) => r.selector === selector)) {
@@ -591,8 +636,9 @@ function listTokens({ filter } = {}) {
 	const tokens = [...byName.entries()]
 		.filter(([name]) => !needle || name.toLowerCase().includes(needle))
 		.sort(([a], [b]) => a.localeCompare(b))
-		.map(([name, { theme, local }]) => ({
+		.map(([name, { theme, local, knobBlock, derivedBlock }]) => ({
 			name,
+			kind: tokenKind(knobBlock, derivedBlock),
 			value: theme[0],
 			...(theme.length > 1 ? { themeOverrides: theme.slice(1) } : {}),
 			...(local.length > 0 ? { localRebinds: local } : {}),
@@ -604,7 +650,7 @@ function listTokens({ filter } = {}) {
 		hint:
 			needle && tokens.length === 0
 				? `No token name contains '${needle}'. Call list_tokens with no filter for all ${byName.size} — the names are semantic (primary/danger/panel/text/border/radius/…), not literal colours.`
-				: 'Theme tokens are set by the consumer app (e.g. on :root / .dark); `themeOverrides` is the dark-theme value. `localRebinds` is a component rebinding the token inside its own subtree — not something to copy. Component-level unprefixed tokens are documented per component; see the design-tokens guide via get_guide.',
+				: 'Theme tokens are set by the consumer app (e.g. on :root / .dark); `themeOverrides` is the dark-theme value. `localRebinds` is a component rebinding the token inside its own subtree — not something to copy. `kind` says what you may set: "knob" is yours; "derived" is a formula recomputed at every theme boundary, so setting it stops it tracking the knob it came from — set that knob instead; "knob-tracking" is a knob that follows another until you pin it, and the pin must be repeated at every boundary you use, .dark included. Component-level unprefixed tokens are documented per component; see the design-tokens guide via get_guide.',
 	};
 }
 

package/bin/bitboss-ui.mjs

@@ -108,11 +108,17 @@ function coreRules(version) {
 After upgrading bitboss-ui, re-run: \`npx bitboss-ui ai-init\``;
 }
 
+// A blank line after the start marker and before the end marker: an HTML
+// comment butting against a heading or a paragraph is not Prettier-stable
+// markdown, and a consumer running `prettier --check` on their AGENTS.md
+// (as our own fixture does in CI) would fail on text we wrote.
 function agentsFragment(version) {
 	return `${START_MARKER}
+
 ## bitboss-ui (v${version})
 
 ${coreRules(version)}
+
 ${END_MARKER}`;
 }
 

package/dist/ai/BbAccordion.md

@@ -238,7 +238,7 @@ const endpoints = ref<Endpoint[]>([
 .bb-badge.bb-badge--soft-green,
 .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));
+	--fg: 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);

package/dist/ai/BbAlert.md

@@ -101,13 +101,13 @@ bitbossUi({
 
 ```css
 .bb-alert--success {
-	--main-color: #15803d; /* title + icon */
-	--muted-color: color-mix(
+	--fg: #15803d; /* title + icon */
+	--fg-muted: color-mix(
 		in oklab,
-		var(--main-color) 75%,
+		var(--fg) 75%,
 		transparent
 	); /* body + close */
-	background-color: transparent;
+	--bg: transparent;
 	border-color: var(--bb-border);
 }
 ```
@@ -410,6 +410,26 @@ const publish = () => {
 - `text` — scope: `BbAlertTextSlotProps` — Replaces the default alert body text. Wins over children and `text`.
 - `title` — scope: `BbAlertTitleSlotProps` — Replaces the default alert title text.
 
+## 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; 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 |
+| --- | --- | --- |
+| `--px` | `10px` | side padding of the plate |
+| `--py` | `6px` | top/bottom padding of the plate, and the close button's inset from those edges |
+| `--gap` | `4px` | icon column → content gap, reused between title parts and in the close button's reserved width |
+| `--title-size` | `14px` | icon column → content gap, reused between title parts and in the close button's reserved width |
+| `--title-lh` | `18px` | title line box — the close button is centred on it |
+| `--text-size` | `14px` | title line box — the close button is centred on it |
+| `--text-lh` | `18px` |  |
+| `--close-size` | `16px` | close glyph; also the width reserved at the end of the title |
+| `--bg` | `transparent` | plate fill |
+| `--fg` | `var(--bb-text)` | title and icon |
+| `--fg-muted` | `color-mix(in oklab, var(--fg) 75%, transparent)` | Body text and the close glyph (the destructive variant points it back at --fg) |
+| `--border-color` | `color-mix(in oklab, var(--bb-text) 15%, transparent)` | Plate border |
+| `--elev` | `var(--bb-elev)` | Resting lift. A local, so a page that already sits on a card can flatten one alert (`<BbAlert style="--elev: none">`) without unsetting the theme's lift everywhere. |
+
 ## See Also
 
 - [BbToast](./BbToast.md) — Shows transient notification messages (includes the co-located BbToastPortal export).

package/dist/ai/BbAvatar.md

@@ -89,14 +89,18 @@ The fallback surface is **always painted with the primary design token** —
 pairing as a primary button — so initials stay legible in light and dark and
 every avatar matches your theme automatically.
 
-There is no tinting **prop**, but there are three component locals on
+There is no tinting **prop**, but there are two component locals on
 `.bb-avatar` for the cases the theme cannot cover — a per-tenant or
-per-user colour: `--bg-color` (fallback surface, defaults to `--bb-primary`),
-`--text-color` (initials, `--bb-primary-fg`) and `--default-icon-color` (the
-placeholder glyph). Set them on the avatar or on a class you put on it:
+per-user colour: `--bg` (fallback surface, defaults to `--bb-primary`) and
+`--fg` (initials and slotted fallback, `--bb-primary-fg`). The built-in person
+glyph mixes `--fg` over `--bg`, so there is no third local. Set both on the
+avatar or on a class you put on it:
 
 ```vue
-<BbAvatar text="Acme Studio" :style="{ '--bg-color': tenant.color }" />
+<BbAvatar
+	text="Acme Studio"
+	:style="{ '--bg': tenant.color, '--fg': tenant.fg }"
+/>
 ```
 
 **The size scale**
@@ -555,6 +559,16 @@ available in visible text or an adjacent label.
 
 - `default` — scope: `Record<string, never>` — Fallback content shown when no image source is provided or when the image fails to load. Typically used to render initials or a placeholder 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; 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 |
+| --- | --- | --- |
+| `--bg` | `var(--bb-primary)` | fallback surface (an image covers it) |
+| `--fg` | `var(--bb-primary-fg)` | Initials; the built-in icon is an 80/20 mix of this toward --bg |
+| `--default-icon-size` | `clamp(14px, calc(var(--size) * 0.7), 48px)` | Built-in fallback icon: 70% of the avatar, floored at 14px and capped at 48px. `--size` is the avatar's own box, set inline from the `size` prop. |
+
 ## See Also
 
 - [BbBadge](./BbBadge.md) — 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).

package/dist/ai/BbBadge.md

@@ -43,7 +43,7 @@ Drive the look with the `variant` ladder; put the copy in the default slot.
 The built-ins are `primary`, `secondary`, `destructive`, and `outline` — a floor,
 not the whole vocabulary. Projects register extra tones via the plugin's
 `badgeVariants` option; registration extends the TypeScript union and yields a
-`bb-badge--<name>` class hook — you own the CSS (`--bg` and `--color` are the
+`bb-badge--<name>` class hook — you own the CSS (`--bg` and `--fg` are the
 tokens to set). **If your page needs a tone that isn't in the list, register it
 and style it** — that is the sanctioned path, not a reason to force the design
 into `secondary`/`outline`. For a genuinely one-off accent, override `--bg`
@@ -162,7 +162,7 @@ const invoices: InvoiceRow[] = [
 .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));
+	--fg: 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);
@@ -604,7 +604,7 @@ in dev and falls back to `md`). Keep one size per cluster.
 
 There is no `color` prop. To paint a single badge outside the variant system,
 override the CSS custom properties the variants drive — `--bg` for the
-background, `--color` for the text — inline:
+background, `--fg` for the text — inline:
 
 **A one-off accent via the --bg token**
 
@@ -616,7 +616,7 @@ background, `--color` for the text — inline:
 ```
 
 Pair a dark custom `--bg` with a light-text variant (`primary`), or set
-`--color` too, and check contrast yourself. For anything recurring, register a
+`--fg` too, and check contrast yourself. For anything recurring, register a
 variant instead so the styling stays in the design system.
 
 ### Anatomy and CSS hooks
@@ -712,7 +712,7 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 | `loading` | `boolean \| undefined` | `false` |  | Shows a spinner in place of the leftmost icon, mirroring `BbButton`: it replaces the `icon` glyph or the `prepend:icon` when one is set; when the `append:icon` is the sole icon it replaces that instead (e.g. a select-activator chevron while… |
 | `prepend:icon` | `string \| undefined` |  |  | Icon rendered before the label. |
 | `size` | `keyof Sizes \| undefined` | `"md"` |  | Preset size of the badge. |
-| `variant` | `keyof BadgeVariantRegistry \| undefined` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Register more via the vite plugin `badgeVariants` option and style `.bb-badge--<variant>` (set `--bg` / `--color`). |
+| `variant` | `keyof BadgeVariantRegistry \| undefined` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Register more via the vite plugin `badgeVariants` option and style `.bb-badge--<variant>` (set `--bg` / `--fg`). |
 
 ## Events
 
@@ -722,6 +722,29 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 
 - `default` — scope: `object` — The badge's label content. When `icon` is set this becomes the visually hidden accessible label. Render a `BbBadgeButton` here to make the badge body interactive (the wrapper stays a passive `<span>`).
 
+## 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; 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 |
+| --- | --- | --- |
+| `--bg` | `var(--bb-primary)` | pill fill |
+| `--fg` | `var(--bb-primary-fg)` | label, icons and the clear glyph |
+| `--border-width` | `0px` | Pill border. The `border` shorthand is always present, so the width is what turns it on — the filled variants leave it at 0 and the bordered ones (secondary/destructive/outline) step up to `--bb-border-w-sm`. Nothing compensates for it: the… |
+| `--border-color` | `transparent` |  |
+| `--ring` | `var(--bb-primary-ring)` | focus ring, per variant |
+| `--min-size-md` | `16px` | The md value. Only the default --min-size below reads it; the size modifiers set --min-size directly. |
+| `--min-size` | `var(--min-size-md)` | pill min height and min width |
+| `--elev` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
+| `--radius` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
+| `--font-size` | `10px` | label |
+| `--icon-size` | `12px` | leading/append icons (passed to BbIcon as --size) |
+| `--gap` | `3px` | space between label, icons and the trailing side |
+| `--padding-inline` | `6px` | base side padding; the modifiers below scale it per side |
+| `--clear-size` | `12px` | clear button's glyph box (the circle painted on hover is 2px smaller) |
+| `--pad-left` | `var(--padding-inline)` | Side-owned padding: the body and trailing wrappers carry the pill's inline padding (and its radius) so their hit areas run flush to the border. The modifiers below retune these vars instead of the pill's own padding. |
+| `--pad-right` | `var(--padding-inline)` |  |
+
 ## See Also
 
 - [BbIndicator](./BbIndicator.md) — Anchors a notification bubble (count/short text) or a dot over a wrapped element.

package/dist/ai/BbBadgeButton.md

@@ -61,6 +61,29 @@
 
 - `default` — scope: `object` — The action's label — what the badge displays as its body.
 
+## 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; 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 |
+| --- | --- | --- |
+| `--bg` | `var(--bb-primary)` | pill fill |
+| `--fg` | `var(--bb-primary-fg)` | label, icons and the clear glyph |
+| `--border-width` | `0px` | Pill border. The `border` shorthand is always present, so the width is what turns it on — the filled variants leave it at 0 and the bordered ones (secondary/destructive/outline) step up to `--bb-border-w-sm`. Nothing compensates for it: the… |
+| `--border-color` | `transparent` |  |
+| `--ring` | `var(--bb-primary-ring)` | focus ring, per variant |
+| `--min-size-md` | `16px` | The md value. Only the default --min-size below reads it; the size modifiers set --min-size directly. |
+| `--min-size` | `var(--min-size-md)` | pill min height and min width |
+| `--elev` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
+| `--radius` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
+| `--font-size` | `10px` | label |
+| `--icon-size` | `12px` | leading/append icons (passed to BbIcon as --size) |
+| `--gap` | `3px` | space between label, icons and the trailing side |
+| `--padding-inline` | `6px` | base side padding; the modifiers below scale it per side |
+| `--clear-size` | `12px` | clear button's glyph box (the circle painted on hover is 2px smaller) |
+| `--pad-left` | `var(--padding-inline)` | Side-owned padding: the body and trailing wrappers carry the pill's inline padding (and its radius) so their hit areas run flush to the border. The modifiers below retune these vars instead of the pill's own padding. |
+| `--pad-right` | `var(--padding-inline)` |  |
+
 ## See Also
 
 - [BbBadge](./BbBadge.md) — 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).

package/dist/ai/BbBaseCheckboxIcon.md

@@ -111,7 +111,7 @@ properties on it:
 
 - `--size` — box edge length (default `16px`)
 - `--r` — corner radius (default `4px`)
-- `--color` — fill + border when checked/indeterminate (default `--bb-primary`)
+- `--accent` — fill + border when checked/indeterminate (default `--bb-primary`)
 - `--check-color` — checkmark stroke (default `--bb-primary-fg`)
 - `--ring-color` — focus ring color
 
@@ -137,7 +137,7 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 ```vue
 <BbBaseCheckboxIcon
 	:checked="true"
-	style="--size: 28px; --r: 999px; --color: #16a34a"
+	style="--size: 28px; --r: 999px; --accent: #16a34a"
 />
 ```
 
@@ -181,6 +181,21 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 
 - None.
 
+## 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; 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 |
+| --- | --- | --- |
+| `--accent` | `var(--bb-primary)` |  |
+| `--check-color` | `var(--bb-primary-fg)` |  |
+| `--size` | `16px` |  |
+| `--r` | `min(4px, var(--bb-radius))` | The checkbox corner, capped by the master radius so a zero- or small-radius theme reaches it. Not `--bb-radius-sm`: that tier is 4.8px at the shipped radius and this glyph ships at 4px. |
+| `--ring-color` | `var(--bb-ring)` |  |
+| `--elev` | `var(--bb-elev-sm)` | Resting lift; a no-op until a theme pins `--bb-elev`. |
+| `--bg` | `var(--bb-panel)` | The glyph plate. DECLARED here, not consumed bare, because this glyph renders inside surfaces that declare `--bg` themselves — a table row or header cell, a dialog, an off-canvas sheet. Without the declaration it would inherit that surface'… |
+| `--border-color` | `var(--bb-border)` |  |
+
 ## See Also
 
 - [BbCheckbox](./BbCheckbox.md) — Toggles a single boolean option.

package/dist/ai/BbBaseColorInput.md

@@ -38,6 +38,7 @@
 | `required` | `boolean \| undefined` | `false` |  | Mark the input as required. |
 | `swatches` | `boolean \| string[][] \| undefined` |  |  | Controls swatches display in the picker: - `true` — show the built-in Material-palette swatches - `string[][]` — show custom swatches (each inner array = a column of shades) - `false` / omitted — no swatches section |
 | `transitionDuration` | `number \| undefined` | `250` |  | Transition duration (ms) of the palette popover. Forwarded to `BbColorPalette`, which supplies the default. |
+| `variant` | `InputVariantType \| undefined` |  |  | Visual variant of the field box, forwarded to `CommonInputWrapper`. |
 
 ## Events
 

package/dist/ai/BbBaseDatePicker.md

@@ -41,3 +41,17 @@
 ## Exposed (template ref)
 
 - `resetStatus`: `() => void`
+
+## 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; 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 |
+| --- | --- | --- |
+| `--cell` | `28px` | Cell size drives all grid math: 224px ÷ 7 = 32px exactly |
+| `--pad-x` | `6px` |  |
+| `--pad-y` | `8px` |  |
+| `--nav-button-h` | `24px` |  |
+| `--weeks` | `6` |  |
+| `--day-slot-allowance` | `0px` | Allowance for the day slot append area - needed for the slot to be visible |
+| `--unit-row` | `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. |

package/dist/ai/BbBaseDatePickerInput.md

@@ -51,6 +51,7 @@
 | `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
 | `type` | `DatePickerType \| undefined` | `"date"` |  | What the field edits, and therefore its segments and emitted shape. - `date` (default) — `DD/MM/YYYY`. - `datetime` — adds the time segments and the calendar's time rail. - `month` — `MM/YYYY`, emitting `YYYY-MM`. - `year` — `YYYY`, emittin… |
 | `utc` | `boolean \| undefined` | `false` |  | Emits values as UTC ISO strings (`...Z`) instead of ISO strings carrying the local offset (`...+01:00`). Emission-only: incoming values are parsed identically either way, so the prop can be added or removed without touching stored values. F… |
+| `variant` | `InputVariantType \| undefined` |  |  | Visual variant of the field box, forwarded to `CommonInputWrapper`. |
 
 ## Events
 
@@ -71,3 +72,13 @@
 - `prepend` — scope: `object` — Content rendered before the date fields, at the start of the inner container.
 - `prepend-outer` — scope: `object` — Content rendered before the entire input control, outside the input chrome.
 - `suffix` — scope: `object` — Inline content rendered at the end of the input field area, after the date fields.
+
+## 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; 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 |
+| --- | --- | --- |
+| `--time-row-h` | `28px` |  |
+| `--time-col-w` | `44px` |  |
+| `--time-mark` | `24px` | Visible mark = the day-cell mark (--cell - 4). Hit area stays the full row; only the painted knob matches the calendar's. |

package/dist/ai/BbBaseNumberInput.md

@@ -37,6 +37,7 @@
 | `readonly` | `boolean \| undefined` | `false` |  | Make the input read-only while keeping its value visible. |
 | `required` | `boolean \| undefined` | `false` |  | Mark the input as required for form validation. |
 | `step` | `number \| undefined` | `1` |  | Increment used by the `increase`/`decrease` helpers. Manual typing is never forced to this step. |
+| `variant` | `InputVariantType \| undefined` |  |  | Visual variant of the field box, forwarded to `CommonInputWrapper`. |
 
 ## Events
 

package/dist/ai/BbBaseRadioIcon.md

@@ -130,7 +130,7 @@ Restyle by overriding the glyph's CSS custom properties on it:
 
 - `--size` — ring diameter (default `16px`)
 - `--space` — gap between ring and dot when checked (default `2px`)
-- `--color` — dot color (default `--bb-primary`)
+- `--accent` — dot color (default `--bb-primary`)
 - `--ring-color` — focus ring color
 
 **On the element itself, not an ancestor.** Each of these is declared on the
@@ -153,7 +153,7 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 **Bigger and recolored**
 
 ```vue
-<BbBaseRadioIcon :checked="true" style="--size: 24px; --color: #16a34a" />
+<BbBaseRadioIcon :checked="true" style="--size: 24px; --accent: #16a34a" />
 ```
 
 ### Gotchas & anti-patterns
@@ -195,6 +195,20 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 
 - None.
 
+## 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; 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 |
+| --- | --- | --- |
+| `--accent` | `var(--bb-primary)` |  |
+| `--size` | `16px` |  |
+| `--space` | `2px` |  |
+| `--ring-color` | `var(--bb-ring)` |  |
+| `--elev` | `var(--bb-elev-sm)` | Same resting lift as the checkbox glyph — see BbBaseCheckboxIcon. |
+| `--bg` | `var(--bb-panel)` | The glyph plate. DECLARED here, not consumed bare, because this glyph renders inside surfaces that declare `--bg` themselves — a table row or header cell, a dialog, an off-canvas sheet. Without the declaration it would inherit that surface'… |
+| `--border-color` | `var(--bb-border)` |  |
+
 ## See Also
 
 - [BbRadio](./BbRadio.md) — Represents a single choice in exclusive options.

package/dist/ai/BbBaseRating.md

@@ -50,3 +50,14 @@
 - `append` — scope: `object` — Content rendered after the row of rating stars.
 - `icon` — scope: `BaseRatingIconSlotProps` — Replaces the default star SVG for each rating option.
 - `prepend` — scope: `object` — Content rendered before the row of rating stars.
+
+## 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; 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 |
+| --- | --- | --- |
+| `--accent` | `var(--bb-primary)` | Fill of a filled (or hover-previewed) star. An unfilled one is --bb-panel with a --bb-border stroke. |
+| `--ring-color` | `var(--bb-ring)` | focus ring around the focused star |
+| `--size` | `24px` | one star's box; overridden inline from the `size` prop |
+| `--space` | `0px` | Gap between stars. Named `--space`, not `--spacing`: Tailwind v4 builds its whole spacing scale on a variable of that name, and a local of the same name zeroed every spacing utility used inside the slots. |

package/dist/ai/BbBaseSelect.md

@@ -59,6 +59,7 @@
 | `selectedLabelsFn` | `((count: number) => string) \| undefined` |  |  | Function to generate a summary label when selected items exceed `maxSelectedLabels` or overflow the control width. |
 | `stash` | `boolean \| undefined` | `false` |  | Accumulate selected items across searches. |
 | `transitionDuration` | `number \| undefined` | `250` |  | Transition duration (ms) for dropdown animations. Forwarded to `BbSelectPopover`, which supplies the default. |
+| `variant` | `InputVariantType \| undefined` |  |  | Visual variant of the field box, forwarded to `CommonInputWrapper`. |
 
 ## Events
 
@@ -87,3 +88,11 @@
 - `prepend` — scope: `BaseSelectActivatorSlotProps`
 - `prepend-outer` — scope: `BaseSelectOuterSlotProps`
 - `suffix` — scope: `object`
+
+## 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; 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 |
+| --- | --- | --- |
+| `--compensation-multiplier` | `0.3` | Fraction of the shell's inner padding the chips row is pulled back by when no prepend icon precedes it (see the negative margin below). |

package/dist/ai/BbBaseSlider.md

@@ -54,3 +54,31 @@
 - `thumb:higher` — scope: `BaseSliderThumbSlotProps` — Replaces the default higher-value thumb in range mode (`range: true`).
 - `thumb:lower` — scope: `BaseSliderThumbSlotProps` — Replaces the default lower-value thumb in range mode (`range: true`).
 - `tick` — scope: `BaseSliderTickSlotProps` — Replaces the default tick mark rendered at each step when ticks are enabled.
+
+## 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; 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 |
+| --- | --- | --- |
+| `--thumb` | `12px` | thumb diameter (square, then `border-radius: 50%`) |
+| `--track` | `4px` | rail thickness |
+| `--track-color` | `var(--bb-track)` | The recessed rail surface — the same token the switch track reads, which is what design-tokens.md has always documented it as ("switch/slider rails"). It was `--bb-muted` (6% of text), a chrome wash so faint the unfilled rail barely read, a… |
+| `--padding` | `calc((var(--thumb) - var(--track)) / 2)` | Room above and below the rail for the thumb's overhang. |
+| `--control-h` | `var(--bb-input-h)` | Row height; --compact swaps in the compact input height. |
+| `--px` | `var(--bb-input-px)` | Horizontal inset for the shell below. Declared here and read by BbSlider (nothing in this file consumes it). |
+| `--shell-px` | `0px` | inner left/right padding of the box |
+| `--track-inset` | `0px` | How far the rail and the tick row are held off both ends. |
+| `--inside-label-clearance` | `0px` | height added for the label line |
+| `--inside-label-track-offset` | `0px` | How far rail and thumbs drop from centre to clear that line. |
+| `--shell-bg` | `transparent` |  |
+| `--shell-border-width` | `0px` |  |
+| `--shell-border-color` | `var(--bb-border)` |  |
+| `--shell-radius` | `0px` |  |
+| `--shell-focus-border` | `var(--bb-border)` | Border while a thumb is focused or held; the errors and warnings blocks below paint the resting border with it too. |
+| `--shell-focus-ring` | `0px 0px 0px 0px transparent` | The box-shadow that replaces --shell-shadow in that state. |
+| `--shell-shadow` | `0px 0px 0px 0px var(--bb-ring)` | resting box-shadow |
+| `--shell-disabled-bg` | `transparent` | resting box-shadow |
+| `--accent` | `var(--bb-primary)` | The selected span of the rail (`__track-background`, sized from JS), and the base of --ring-color below. |
+| `--ring-color` | `color-mix( in oklab, var(--accent) var(--bb-ring-opacity), transparent )` | Halo around the thumb on hover and focus; errors and warnings re-point it. |
+| `--radius` | `var(--bb-radius)` | Rail rounding: all four corners of the rail, the leading pair on the selected span. |

package/dist/ai/BbBaseSwitchIcon.md

@@ -120,8 +120,8 @@ Restyle by overriding the glyph's CSS custom properties on it:
 
 - `--w` / `--h` — track width / height (default `32px` / `18px`)
 - `--thumb` — thumb diameter (default `16px`)
-- `--color` — track fill when checked (default `--bb-primary`)
-- `--bg-color` — track fill when off (default `--bb-track`)
+- `--accent` — track fill when checked (default `--bb-primary`)
+- `--bg` — track fill when off (default `--bb-track`)
 - `--radius` — track/thumb rounding (default `999px`)
 
 **On the element itself, not an ancestor.** Each of these is declared on the
@@ -148,7 +148,7 @@ from an ancestor — so `--w` set on a wrapper `div` is simply ignored
 ```vue
 <BbBaseSwitchIcon
 	:checked="true"
-	style="--w: 48px; --h: 26px; --thumb: 22px; --color: #16a34a"
+	style="--w: 48px; --h: 26px; --thumb: 22px; --accent: #16a34a"
 />
 ```
 
@@ -192,6 +192,23 @@ from an ancestor — so `--w` set on a wrapper `div` is simply ignored
 
 - None.
 
+## 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; 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 |
+| --- | --- | --- |
+| `--accent` | `var(--bb-primary)` | Track fill and border once checked or indeterminate; --errors, --warnings and --disabled re-point it. |
+| `--bg` | `var(--bb-track)` | track fill while off |
+| `--ring-color` | `color-mix( in oklab, var(--accent) var(--bb-ring-opacity), transparent )` | focus ring; follows --accent, so the status modifiers tint it too |
+| `--radius` | `999px` | track corners; the thumb rounds to 80% of it |
+| `--bw` | `var(--bb-border-w-sm)` | Geometry — change --h / --w / --thumb freely: everything else is derived, so the thumb stays vertically centred and travels flush-to-flush at any size. --bw is the track border; the box is border-box, so the border eats into the inner track… |
+| `--h` | `18px` | track height, border included (border-box) |
+| `--w` | `32px` | track width, border included |
+| `--thumb` | `min(16px, calc(var(--h) - 2 * var(--bw)))` | Capped by the track's inner height, so a thick-hairline theme shrinks the thumb instead of overflowing it. Unclamped, a 6px plate hairline leaves a 12px inner track carrying a 16px thumb; `--inset` then goes negative and the thumb paints ov… |
+| `--inset` | `calc((var(--h) - 2 * var(--bw) - var(--thumb)) / 2)` | Equal gap around the thumb — centres it vertically by construction, and is reused as the resting left/right inset. |
+| `--travel` | `calc(var(--w) - 2 * var(--bw) - var(--thumb) - 2 * var(--inset))` | How far the thumb slides between off and on (inset ↔ inset). |
+
 ## See Also
 
 - [BbSwitch](./BbSwitch.md) — Toggles two-state values with switch semantics.

package/dist/ai/BbBaseTag.md

@@ -37,6 +37,7 @@
 | `prepend:icon` | `string \| undefined` |  |  | Name of the icon to render at the left hand side of the input. |
 | `readonly` | `boolean \| undefined` | `false` |  | Make the input read-only while keeping tags visible. |
 | `required` | `boolean \| undefined` | `false` |  | Mark the input as required for form validation. |
+| `variant` | `InputVariantType \| undefined` |  |  | Visual variant of the field box, forwarded to `CommonInputWrapper`. |
 
 ## Events
 
@@ -66,3 +67,13 @@
 - `prepend` — scope: `Record<string, never>` — Content rendered before the tag input, at the start of the inner container.
 - `prepend-outer` — scope: `Record<string, never>` — Content rendered before the entire tag input control, outside the input chrome.
 - `suffix` — scope: `Record<string, never>` — Inline content rendered at the end of the input field area, after the typed text.
+
+## 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; 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 |
+| --- | --- | --- |
+| `--compensation-multiplier` | `0.3` | Fraction of the shell's inner padding the chip row is pulled back by when no prepend icon precedes it (see the negative margin below). |
+| `--inner-h` | `max( calc(var(--bb-leading) + var(--bb-input-py) * 2), calc(var(--bb-input-h) - …` | The first chip row's height: the tallest of one line plus its vertical padding, the input height less its borders, and the icon box. Feeds `--floating-py` and nothing else. |
+| `--floating-py` | `calc((var(--inner-h) - var(--bb-input-icon)) / 2)` | Top offset for centring icons and affixes on that first row — the same value BbBaseTextarea uses for that. Nothing in the library reads it, so this and the compact override below are currently inert. |

package/dist/ai/BbBaseTextInput.md

@@ -27,7 +27,7 @@
 | `hasErrors` | `boolean \| undefined` | `false` |  | Apply error styling to the input and set `aria-invalid`. |
 | `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
 | `id` | `string \| undefined` |  |  | Explicit id for the input element. |
-| `inputMode` | `"text" \| "search" \| "email" \| "url" \| "tel" \| "none" \| "numeric" \| "decimal" \| undefined` |  |  | Input mode hint for mobile keyboards. |
+| `inputMode` | `"text" \| "none" \| "search" \| "email" \| "url" \| "tel" \| "numeric" \| "decimal" \| undefined` |  |  | Input mode hint for mobile keyboards. |
 | `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode, forwarded by wrapper components. |
 | `loading` | `boolean \| undefined` | `false` |  | Display the loading state styles. |
 | `mask` | `MaskInputOptions \| undefined` |  |  | Input mask configuration. When provided, enables formatted input with validation. |
@@ -42,6 +42,7 @@
 | `required` | `boolean \| undefined` | `false` |  | Mark the input as required for form validation. |
 | `step` | `string \| undefined` |  |  | Stepping interval for numeric and date inputs. |
 | `type` | `"text" \| "search" \| "email" \| "url" \| "tel" \| "password" \| undefined` | `"text"` |  | HTML input type attribute. Restricted to the textual input types this component supports — use `BbNumberInput` for numbers and `BbDatePickerInput` for dates. |
+| `variant` | `InputVariantType \| undefined` |  |  | Visual variant of the field box, forwarded to `CommonInputWrapper`. |
 
 ## Events