bitboss-ui 3.0.0-alpha.6 → 3.0.0-beta.0

package/bin/bitboss-ui.mjs

@@ -13,7 +13,6 @@
  *             - .windsurf/rules/bitboss-ui.md (Windsurf)
  *             Accepts an optional --mcp flag (combinable with --update) to also
  *             register the `bitboss-ui mcp` server in .mcp.json.
- *   locale    Generate a custom locale blueprint (.locale.ts)
  *   check     Validate Bb* markup in .vue/.md files against the installed
  *             components.json manifest (unknown props, removed props, bad
  *             v-models, unknown `<template #slot>` names, `href`/`to`/
@@ -36,7 +35,6 @@ import {
 	writeFileSync,
 } from 'node:fs';
 import { findHandRollHints } from '../scripts/lib/hand-roll-hints.mjs';
-import { createRequire } from 'node:module';
 import { dirname, isAbsolute, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
@@ -285,112 +283,6 @@ function aiInit({ mcp = false } = {}) {
 	}
 }
 
-/**
- * Serialize the blueprint dictionary as a readable TS object literal
- * (single-quoted, tab-indented, matching the library's own locale files).
- */
-function localeObjectLiteral(dictionary) {
-	const quote = (s) =>
-		`'${String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
-	const sections = Object.entries(dictionary)
-		.map(([section, entries]) => {
-			const lines = Object.entries(entries)
-				.map(([key, value]) => `\t\t${key}: ${quote(value)},`)
-				.join('\n');
-			return `\t${section}: {\n${lines}\n\t},`;
-		})
-		.join('\n');
-	return `{\n${sections}\n}`;
-}
-
-function localeBlueprint(key) {
-	const projectRoot = process.cwd();
-
-	if (!key) {
-		console.error(
-			'[bitboss-ui] Usage: npx bitboss-ui locale <key>   (e.g. `npx bitboss-ui locale nl`)'
-		);
-		process.exit(1);
-	}
-	// Keys double as dayjs module names (`dayjs/locale/<key>`) — keep them tame.
-	if (!/^[a-z0-9-]+$/.test(key)) {
-		console.error(
-			`[bitboss-ui] Invalid locale key '${key}' — use lowercase letters, digits and dashes (it doubles as the dayjs locale name, e.g. 'nl', 'ja', 'zh-cn').`
-		);
-		process.exit(1);
-	}
-
-	const blueprintPath = join(PACKAGE_ROOT, 'dist', 'locale-blueprint.json');
-	if (!existsSync(blueprintPath)) {
-		console.error(
-			'[bitboss-ui] dist/locale-blueprint.json not found in the installed package — reinstall bitboss-ui (or run `npm run build` when working in the library repo).'
-		);
-		process.exit(1);
-	}
-	const { builtins, template } = JSON.parse(
-		readFileSync(blueprintPath, 'utf-8')
-	);
-
-	if (builtins.includes(key)) {
-		console.error(
-			`[bitboss-ui] '${key}' is a built-in locale — built-ins cannot be overridden; the \`additionalLocales\` option only adds new ones. Just set \`locale: '${key}'\`.`
-		);
-		process.exit(1);
-	}
-
-	const outPath = join(projectRoot, `${key}.locale.ts`);
-	if (existsSync(outPath)) {
-		console.error(
-			`[bitboss-ui] ${key}.locale.ts already exists — delete it first if you want a fresh blueprint.`
-		);
-		process.exit(1);
-	}
-
-	// Same check the vite plugin performs at build time — surface it here too,
-	// while the consumer is still choosing the key.
-	let dayjsHint = `Calendar (dayjs) locale '${key}' found — calendars will follow automatically.`;
-	try {
-		// Consumer's own resolution first; fall back to the installed package's
-		// (dayjs is a bitboss-ui dependency, so it's always reachable from here).
-		try {
-			createRequire(join(projectRoot, 'package.json')).resolve(
-				`dayjs/locale/${key}.js`
-			);
-		} catch {
-			createRequire(join(PACKAGE_ROOT, 'package.json')).resolve(
-				`dayjs/locale/${key}.js`
-			);
-		}
-	} catch {
-		dayjsHint = `⚠ dayjs ships no locale named '${key}' — calendars will fall back to English (the vite plugin repeats this warning at build time). If a nearby dayjs name exists (e.g. 'zh-cn', 'pt-br'), prefer it as your key: https://github.com/iamkun/dayjs/tree/dev/src/locale`;
-	}
-
-	writeFileSync(
-		outPath,
-		`import type { LocaleOverrides } from 'bitboss-ui';
-
-/**
- * bitboss-ui locale blueprint for '${key}' — generated by \`npx bitboss-ui locale ${key}\`.
- *
- * Translate the English strings below ({0}/{1} placeholders are interpolated
- * arguments — keep them). Keys you delete fall back per-key to the library's
- * default locale. Register it in your vite config:
- *
- *   import ${key.replace(/-/g, '_')} from './${key}.locale';
- *   bitbossUi({ iconDir: '...', locale: '${key}', additionalLocales: { '${key}': ${key.replace(/-/g, '_')} } })
- *
- * The plugin regenerates \`locale-registry.d.ts\` on build start, making
- * '${key}' a valid \`locale\` value everywhere (run dev once after adding it).
- */
-export default ${localeObjectLiteral(template)} satisfies LocaleOverrides;
-`,
-		'utf-8'
-	);
-
-	console.log(`[bitboss-ui] Wrote ${key}.locale.ts (English blueprint).`);
-	console.log(`  ${dayjsHint}`);
-}
-
 // SNT-007: a bare-segment skip list of `node_modules`/`dist`/`.git` let a
 // default (no-glob) `check` sweep straight through a Laravel-style consumer's
 // `vendor/`, `storage/`, and `public/` trees — hundreds of vendored
@@ -724,9 +616,6 @@ Commands:
   mcp                 Start a stdio MCP server exposing the dist/ai knowledge
                       base (search_components, get_component, list_recipes,
                       get_recipe, validate) to MCP-capable agent harnesses.
-  locale <key>        Generate <key>.locale.ts at the project root — an English
-                      blueprint dictionary to translate and pass to the plugin's
-                      \`additionalLocales\` option (additions only; built-ins are refused).
   help                Show this help.
 `);
 }
@@ -804,18 +693,6 @@ switch (command) {
 		await main();
 		break;
 	}
-	case 'locale': {
-		const { positionals } = parseCommandArgs(
-			command,
-			commandArgs,
-			{},
-			{
-				allowPositionals: true,
-			}
-		);
-		localeBlueprint(positionals[0]);
-		break;
-	}
 	case 'help':
 	case '--help':
 	case '-h':

package/dist/ai/BbBaseRating.md

@@ -17,6 +17,7 @@
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this rating input for assistive technologies. |
+| `ariaLabelledby` | `string \| undefined` |  |  | Id(s) of the element(s) that NAME this rating group. Supplying one is what promotes the inner container to `role="radiogroup"` (Q4.5): an unnamed `radiogroup` announces as a bare "radio group" and is no better than the role-less `<span>` it… |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
 | `clearable` | `boolean \| undefined` | `false` |  | Allows clearing the selected rating by clicking the current value. |
 | `disabled` | `boolean \| undefined` |  |  | Disable all interactions with the rating. |

package/dist/ai/BbDatePickerInput.md

@@ -33,9 +33,13 @@ date (see _Time selection_). `label` is required.
 
 The shared surface applies:
 
-- **`label`** (required) doubles as the default `name`; **`hideLabel`** hides it
-  visually while keeping the accessible name; **`labelPosition`** aligns it; the
-  **`label` slot** replaces it with `{ text, hasErrors }`.
+- **`label`** (required) names the field for display and accessibility only —
+  it has **no** effect on the native `name` attribute of the segment inputs.
+  Leave `name` unset and the rendered segments carry none at all, so a plain
+  form post silently drops the value; pass `name` explicitly whenever it's
+  submitted via a native form or read from `FormData`. **`hideLabel`** hides
+  it visually while keeping the accessible name; **`labelPosition`** aligns
+  it; the **`label` slot** replaces it with `{ text, hasErrors }`.
 - **`labelMode`** — `outside` / `floating` / `inside`. When unset it falls back
   to the project-wide `config.defaultInputLabelMode` (library default:
   `outside`), the same resolution as `BbTextInput` and `BbNumberInput`.

package/dist/ai/BbIcon.md

@@ -135,7 +135,12 @@ The `icon` prop takes a name in one of three forms:
 - **`local:name`** — an SVG in the configured `iconDir` (brand marks, custom
   illustrations). Each `.svg` file becomes `local:<basename>`.
 - **bare `name`** — an unprefixed name **normalizes to `local:`**; it never
-  searches provider sets.
+  searches provider sets. Prefer writing the prefix anyway: the Iconify editor
+  extension keys off `prefix:name`, so `local:user-circle` gets an inline
+  preview and name autocomplete in the template while a bare `user-circle`
+  reads as an ordinary string and gets neither. It also puts your own art in
+  the same shape as `mdi:home` / `lucide:check`, so the source of every icon is
+  legible without inferring it from a missing prefix.
 
 Discovery-first: **only use names you have verified exist** — a missing icon
 **throws at mount** (dev shows an actionable Vite overlay with the exact

package/dist/ai/BbNumberInput.md

@@ -36,8 +36,11 @@ and locale-separator quirks of native number inputs don't apply here.
 
 ### Label & label modes
 
-`label` is required and doubles as the default `name`. The shared label controls
-apply:
+`label` is required, but it names the field for display and accessibility
+only — it has **no** effect on the native `name` attribute. Leave `name`
+unset and the rendered `<input>` carries none at all, so a plain form post
+silently drops the value; pass `name` explicitly whenever it's submitted via
+a native form or read from `FormData`. The shared label controls apply:
 
 - **`labelMode`** sets where the label sits: `outside` (default, above),
   `floating` (rests inside like a placeholder, lifts on focus/fill) or `inside`

package/dist/ai/BbTextInput.md

@@ -29,9 +29,11 @@ Pick a sibling when the shape of the data is different:
 
 ### Label & label modes
 
-`label` names the field and doubles as the default `name` (lowercased,
-accents stripped, spaces removed) — pass `name` explicitly when the value is
-posted to a server.
+`label` names the field for display and accessibility only — it has **no**
+effect on the native `name` attribute. Leave `name` unset and the rendered
+`<input>` carries none at all, so a plain form post silently drops the value.
+Pass `name` explicitly whenever the value is submitted via a native form or
+read from `FormData`.
 
 - **`labelMode`** sets where the label sits: `outside` (above the field),
   `floating` (rests inside like a placeholder at reduced opacity, lifts on

package/dist/ai/BbTextarea.md

@@ -30,9 +30,11 @@ Pick a sibling when the shape of the data is different:
 
 ### Label
 
-`label` names the field and doubles as the default `name` (lowercased, accents
-stripped, spaces removed) — pass `name` explicitly when the value is posted to a
-server.
+`label` names the field for display and accessibility only — it has **no**
+effect on the native `name` attribute. Leave `name` unset and the rendered
+`<textarea>` carries none at all, so a plain form post silently drops the
+value. Pass `name` explicitly whenever the value is submitted via a native
+form or read from `FormData`.
 
 - **`hideLabel`** keeps the label for screen readers but removes it visually.
 - **`labelPosition`** aligns the label text `left` / `center` / `right`.

package/dist/ai/BbToast.md

@@ -165,7 +165,9 @@ Three things worth internalising:
 - **Variants tint the icon and set announcement priority — nothing else.** A
   variant toast without an `icon` looks identical to a default one, so pass a
   matching icon (`lucide:circle-check` for success, `lucide:circle-x` for
-  destructive…) whenever the tone matters visually. No icon is ever implied.
+  destructive…) whenever the tone matters visually. No icon is ever implied —
+  dev builds warn when a built-in variant is used without one, since the tone
+  is otherwise dropped with no trace.
 - `toast(...)` returns the message `id`. Keep it to `update(...)` or
   `dismiss(...)` that toast later; `dismiss()` with no argument clears the
   whole stack.

package/dist/ai/changelog.json

@@ -1,7 +1,7 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-alpha.6",
+	"version": "3.0.0-beta.0",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"summary": {

package/dist/ai/components.json

@@ -1,8 +1,8 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-alpha.6",
-	"generatedAt": "2026-08-07T15:42:40.421Z",
+	"version": "3.0.0-beta.0",
+	"generatedAt": "2026-08-24T15:06:25.249Z",
 	"composables": [
 		{
 			"name": "useBbConfig",
@@ -24,11 +24,6 @@
 			"description": "Read and drive a BbTabs/BbTabsRoot group from anywhere by id — writable current tab, goTo/select, no template refs.",
 			"doc": "ai/composables/useBbTabsContext.md"
 		},
-		{
-			"name": "useBroadcastChannelInstance",
-			"description": "Typed cross-tab messaging via the BroadcastChannel API with per-component subscriber lifecycle.",
-			"doc": "ai/composables/useBroadcastChannelInstance.md"
-		},
 		{
 			"name": "useConfirm",
 			"description": "Promise-based confirm dialogs — await the user's yes/no, with yes/no button configs, async onClick busy states, and portal content. Requires exactly one <BbConfirm /> host, mounted at the app root.",
@@ -243,6 +238,16 @@
 					"fix": {
 						"kind": "invert"
 					}
+				},
+				{
+					"name": "theme",
+					"new": "variant",
+					"since": "3.0.0-unreleased",
+					"migration": "ai/guides/migration/components/bb-alert.md",
+					"silent": true,
+					"fix": {
+						"kind": "rename"
+					}
 				}
 			],
 			"renamed": [
@@ -254,6 +259,15 @@
 					"fix": {
 						"kind": "invert"
 					}
+				},
+				{
+					"from": "theme",
+					"to": "variant",
+					"since": "3.0.0-unreleased",
+					"migration": "ai/guides/migration/components/bb-alert.md",
+					"fix": {
+						"kind": "rename"
+					}
 				}
 			]
 		},
@@ -3020,6 +3034,12 @@
 					"required": false,
 					"description": "Id(s) of elements describing this rating input for assistive technologies."
 				},
+				{
+					"name": "ariaLabelledby",
+					"type": "string | undefined",
+					"required": false,
+					"description": "Id(s) of the element(s) that NAME this rating group. Supplying one is what\npromotes the inner container to `role=\"radiogroup\"` (Q4.5): an unnamed\n`radiogroup` announces as a bare \"radio group\" and is no better than the\nrole-less `<span>` it replaces, so the role is withheld until a name\nsource exists. `BbRating` wires this to its `<legend>`."
+				},
 				{
 					"name": "autofocus",
 					"type": "Booleanish | undefined",
@@ -15246,6 +15266,36 @@
 				}
 			],
 			"removed": [
+				{
+					"name": "block",
+					"new": null,
+					"since": "3.0.0-unreleased",
+					"migration": "ai/guides/migration/components/bb-tooltip.md",
+					"silent": true,
+					"fix": {
+						"kind": "remove"
+					}
+				},
+				{
+					"name": "showClose",
+					"new": null,
+					"since": "3.0.0-unreleased",
+					"migration": "ai/guides/migration/components/bb-tooltip.md",
+					"silent": true,
+					"fix": {
+						"kind": "remove"
+					}
+				},
+				{
+					"name": "theme",
+					"new": "variant",
+					"since": "3.0.0-unreleased",
+					"migration": "ai/guides/migration/components/bb-tooltip.md",
+					"silent": true,
+					"fix": {
+						"kind": "rename"
+					}
+				},
 				{
 					"name": "timeout",
 					"new": "delay",
@@ -15258,6 +15308,15 @@
 				}
 			],
 			"renamed": [
+				{
+					"from": "theme",
+					"to": "variant",
+					"since": "3.0.0-unreleased",
+					"migration": "ai/guides/migration/components/bb-tooltip.md",
+					"fix": {
+						"kind": "rename"
+					}
+				},
 				{
 					"from": "timeout",
 					"to": "delay",

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

@@ -234,11 +234,10 @@ 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; a raw
-`new BroadcastChannel(…)` → `useBroadcastChannelInstance`. Full symptom index:
+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, spinner and `BroadcastChannel` shapes
+`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.
@@ -255,4 +254,4 @@ case is not decidable from markup and has no hint.
 - [ ] 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`, `BbBadge` or `useBroadcastChannelInstance`.
+- [ ] Ran the Rebuild Check over the hand-written markup — nothing reimplements `BbAvatar`, `BbSpinner` or `BbBadge`.

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

@@ -22,12 +22,11 @@ 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)                                                         |
-| `new BroadcastChannel('…')` for cross-tab sync                                              | [useBroadcastChannelInstance](../composables/useBroadcastChannelInstance.md) — a typed wrapper: each call opens its own channel and removes its listeners on unmount |
+| 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
@@ -35,7 +34,7 @@ here — build that one yourself. Everything else about it (fallbacks, load erro
 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, spinner and `BroadcastChannel` rows as
+`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
@@ -244,7 +243,7 @@ compose it or write it yourself.
 | `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. The cross-tab half is [useBroadcastChannelInstance](../composables/useBroadcastChannelInstance.md) (one shared channel per name); the polling and the merge are yours.                                                                                                                                                    |
+| `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`.                                                                                                                                                                                                                                                                                   |

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

@@ -295,6 +295,51 @@ Component tokens are still real affordances: a consumer can retune one
 instance (`<BbTabs style="--list-h: 40px">`) or a whole page scope. They are
 just not global namespace.
 
+### Overriding one from a consumer app
+
+Three rules, in order of how often they are broken.
+
+**1. Override only what you actually render.** Several components expose a
+per-size lookup table (`--icon-size-xs … --icon-size-2xl`, `--h-xs … --h-2xl`)
+plus an _active_ token the size class re-points. Setting the whole family
+because you want one value is not "thorough" — it silently opts you out of the
+size scale for variants you may start using later, and it buries the one line
+that mattered. Retune the sizes you use:
+
+```css
+/* we render sm and md buttons; leave the rest on the library's scale */
+.bb-button {
+	--icon-size-sm: 12px;
+	--icon-size-md: 12px;
+}
+```
+
+**2. Override the per-size entry, not the active token.** The active token is
+re-resolved by the size class, which is _more specific_ than the root class:
+
+```css
+.bb-button {
+	--icon-size: var(--icon-size-md);
+} /* 0,1,0 */
+.bb-button--sm {
+	--icon-size: var(--icon-size-sm);
+} /* 0,2,0 — nested */
+```
+
+So `.bb-button { --icon-size: 12px }` appears to work on default buttons and
+silently does nothing on every `size="sm"` one — the confusing half-failure that
+sends people to the shotgun in rule 1. The per-size entry has no competing
+declaration, so it always wins. (A scope selector of equal-or-greater
+specificity also works, but you have to keep winning that race; overriding the
+entry does not.)
+
+**3. Scope it to the component, never `:root`.** Short names are deliberately
+reused across components — `--icon-size` is read by `BbButton`, `BbBadge` and
+`CloseIcon`; `--gap`, `--px`, `--h` are everywhere. Hoisting one to `:root`
+retunes every component that happens to share the name, which is exactly what
+tier-2's sealing rule exists to prevent. Put it on the component's class, a page
+scope, or the instance's `style=`.
+
 ## The emphasis ladder
 
 All translucency/tinting goes through **one ladder** of `color-mix()`

package/dist/ai/guides/installation-and-plugin-setup.md

@@ -319,7 +319,7 @@ Default label rendering mode for input-like components; set globally instead of
 
 ### `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 (any field that is `required` or carries `rules`); core controls ignore the flag, so on a hand-wired form render the exported `BbAsterisk` in your own label content.
+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'`)
 
@@ -350,70 +350,31 @@ bitbossUi({
 ```
 
 Your `locale` and `'en'` are always auto-included, so the list never needs to
-repeat them; custom `additionalLocales` keys are always enabled and don't
-belong here.
+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 enabled
-built-ins + custom keys, so `setConfig({ locale: 'ja' })` fails to type-check
-until `'ja'` is enabled. Run dev once after changing the list.
+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.
 
-### `additionalLocales?: CustomLocales` (default: `{}`)
+### Custom locales are not a supported surface
 
-**Additional** locale dictionaries, keyed by locale. Strictly additive:
-built-in locales cannot be overridden — a built-in key here is a type error,
-and one smuggled past the compiler is ignored with a build-time warning.
+The library ships **22 dictionaries** and that is the whole set:
 
-The full flow for adding a locale (using Georgian, which the library doesn't
-ship):
-
-```bash
-# 1. Generate a translation blueprint (English strings) at the project root
-npx bitboss-ui locale ka
 ```
-
-```ts
-// 2. Translate ka.locale.ts, then register it
-import ka from './ka.locale';
-
-bitbossUi({
-	iconDir: './src/assets/icons',
-	locale: 'ka',
-	additionalLocales: { ka },
-});
+cs da de el en es fi fr hu it ja ko nb nl pl pt ro ru sv tr uk zh-cn
 ```
 
-That's the whole setup — on build start the plugin:
-
-- **verifies the dictionary against the library's English template** and warns
-  about `missing` keys (strings the library requires that your translation
-  doesn't cover — this is how a library upgrade that adds new strings alerts
-  you instead of silently falling back to the default locale forever) and
-  `unknown` keys (typos, or strings an upgrade removed).
-
-- **regenerates `locale-registry.d.ts`**, augmenting `LocaleRegistry` with
-  your keys (exactly like the variant registries), so `'ka'` is a valid
-  `locale` value everywhere — the plugin option and `setConfig({ locale })`
-  alike. Run dev once after adding a key so the file exists.
-- **wires the matching dayjs locale** (`dayjs/locale/ka`) so calendars follow
-  your locale's month/day names and week start. Any dayjs-shipped name works.
-  If dayjs has no locale under your key, the plugin **warns at build time**
-  and calendars fall back to English (there is no runtime warning) — when a
-  nearby dayjs name exists (`zh-cn`, `pt-br`, …), prefer it as your key.
-
-Keys you delete from the blueprint fall back per-key to the default locale
-(your `locale` when it's a built-in, otherwise `en` — always bundled, always
-complete) — and are reported by the completeness warning above, which is the
-point: partial is allowed, silent-partial is not.
-
-Locale dictionaries are **build-time only**: `setConfig` accepts `locale` but
-deliberately not `additionalLocales` — a runtime path would bypass every check
-the plugin performs (built-in collision, completeness verification, dayjs
-wiring, registry typing). Only the active `locale` switches at runtime, among
-what the build enabled.
+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'`)
 

package/dist/ai/guides/migration/components/bb-icon.md

@@ -25,3 +25,29 @@ summary: The required prop is renamed type→icon, color is removed, and the xxl
 Provider prefixes now require the matching `@iconify-json/<prefix>` dev
 dependency, and names must be **literal strings** (the build scans statically;
 dynamically assembled names won't be bundled).
+
+## Prefix your own icons with `local:` while you are in there
+
+A v2 `type` naming an icon from your own `iconDir` was bare — `type="user-circle"`.
+Carry it over **with the prefix**:
+
+```diff
+- <BbIcon type="user-circle" />
++ <BbIcon icon="local:user-circle" />
+```
+
+This is not a functional change: `BbIcon` already resolves a name with no `:`
+as `local:<name>`, so both spellings render the same icon. It is a **tooling**
+change, and worth doing across the whole app in one pass:
+
+- The Iconify editor extension keys off `prefix:name`. Spelled `local:user-circle`
+  it renders an inline preview and autocompletes the name in the template; spelled
+  `user-circle` it sees an ordinary string and shows nothing.
+- It reads unambiguously next to `mdi:home` / `lucide:check` — same shape, and the
+  source of every icon is legible at a glance instead of inferred from absence.
+
+Apply it wherever the name is written **literally in a template**. Leave names that
+arrive through a variable, a map, or props alone — the prefix buys nothing there
+(no extension preview to gain), and rewriting data is out of scope for a rename.
+The same goes for any component prop that takes an icon (`prepend:icon`,
+`append:icon`, `icon` on buttons, dropdown items, toasts…), not just `<BbIcon>`.