@bitforgehq/ui 0.3.3 → 0.5.0-next.3

package/ai/UI_GUIDE.md

@@ -72,7 +72,7 @@ In `src/index.html`, give `<body>` the theme background and text colour, so the
 
 ### 7. Switch to dark mode
 
-Add the `dark` class to `<html>` (and remove it for light mode). Every token is redefined under `.dark`, and the theme sets `color-scheme`, so scrollbars and native controls follow too. Components need no `dark:` classes. To let users choose System, Light or Dark, add `provideBfColorScheme()` to the app providers: it sets the class, follows the OS and remembers the choice.
+Add the `dark` class to `<html>` (and remove it for light mode). Every token is redefined under `.dark`, and the theme sets `color-scheme`, so scrollbars and native controls follow too. Components need no `dark:` classes. To let users choose System, Light or Dark, add `provideBfColorScheme()` to the app providers: it sets the class, follows the OS and remembers the choice. For a near-black dark mode, add `@import '@bitforgehq/ui/dark-ink.css';` right after the theme import: the Ink preset, which changes dark mode only.
 
 ```html
 <html lang="en" class="dark">
@@ -123,6 +123,10 @@ pressed, soft and strong steps, `on-primary`, `primary-text`, `selected`, `ring`
 and a `.dark` block with each contrast pair's ratio, and exits 1 naming the pairs below their
 minimum and a shade that passes; paste its output, never hand-pick the steps. Example (the
 Meadow Sage green): `bunx bf-ui theme '#238652' --dark '#5cc48a'`.
+For a near-black dark mode, import the opt-in Ink preset right after the theme,
+`@import '@bitforgehq/ui/dark-ink.css';`: it redefines every dark token but the brand set under
+`.dark` (light mode and the default dark stay as they are), so a brand `.dark` block goes after
+it. Never copy its values into `.dark` by hand, and never put `dark:` classes on widgets for it.
 `--radius-control` (`9999px`, pills) reshapes buttons, chips, badges, segmented, the tab bar, the
 action bar and toggles at once:
 
@@ -143,17 +147,17 @@ Render library components only in the browser, for example in a `@defer` block o
 route. Support will be decided before 1.0.
 
 The one server-side check is a render smoke, not a support test: the library repository's
-`tools/ssr-smoke.ts` renders 43 fixtures with `renderApplication()` (every root widget, `bf-icon`,
-`bf-number-input`, a `/charts` line chart, a `/mobile` page with `provideBfShell()`, `bf-page`,
-`bf-header` and `bf-content`, `bf-tabs` with `bf-stack-outlet` under the router, and an `/overlay`
-dialog), and all of them render without an error. 27 of them render identically twice. The other 16
-number their ids differently on every render, from a module-level counter, so they could not
-hydrate: `bf-app-frame`, `bf-calendar`, `bf-checkbox`, `bf-input`, `bf-radio-group`, `bf-segmented`,
-`bf-select`, `bf-sidebar`, `bf-tab-group`, `bf-table`, `bf-textarea`, `bf-theme-switch`,
-`bf-toggle`, `bf-line-chart`, `bf-number-input` and the `/overlay` dialog. Hydration itself is still
-not supported or tested, and more stands in its way: `/mobile` writes to `<html>` and adds a
-keyboard probe to `<body>`, and an `/overlay` dialog renders outside the app root and marks it
-inert.
+`tools/ssr-smoke.ts` renders 49 fixtures with `renderApplication()` (every root widget, `bf-icon`,
+`bf-number-input`, `bf-select` from `/overlay`, a `/charts` line chart, a `/mobile` page with
+`provideBfShell()`, `bf-page`, `bf-header` and `bf-content`, `bf-tabs` with `bf-stack-outlet` under
+the router, and an `/overlay` dialog), and all of them render without an error. 31 of them render
+identically twice. The other 18 number their ids differently on every render, from a module-level
+counter, so they could not hydrate: `bf-app-frame`, `bf-calendar`, `bf-checkbox`, `bf-file-input`, `bf-image-input`, `bf-input`,
+`bf-radio-group`, `bf-segmented`, `bf-select`, `bf-sidebar`, `bf-tab-group`, `bf-table`,
+`bf-textarea`, `bf-theme-switch`, `bf-toggle`, `bf-line-chart`, `bf-number-input` and the `/overlay`
+dialog. Hydration itself is still not supported or tested, and more stands in its way: `/mobile`
+writes to `<html>` and adds a keyboard probe to `<body>`, and an `/overlay` dialog renders outside
+the app root and marks it inert.
 
 ## Keeping this guide in sync
 
@@ -172,6 +176,10 @@ or out of date — wire it into CI so agent guidance never drifts from the insta
 - Number field: `import { BfNumberInputComponent } from '@bitforgehq/ui/number-input';`. It is
   the one widget in its own entry point, because it loads Angular Forms (`@angular/forms`, a
   required peer); `@bitforgehq/ui` itself loads no forms code, so an app without forms ships none.
+- Select: `import { BfSelectComponent } from '@bitforgehq/ui/overlay';` (needs `@angular/cdk`;
+  `BfSelectOption` is also exported from `@bitforgehq/ui`). Under a mouse it opens a styled list,
+  under touch it renders the native `<select>`. Add `provideBfSelect()` to the app's providers so a
+  stacked `bf-table`'s "Sort by" control is the styled select too (without it, the native one).
 - Charts: `import { BfLineChartComponent } from '@bitforgehq/ui/charts';` (also `BfBarChartComponent`,
   `BfDonutChartComponent`, `BfSparklineComponent`, `BfChartCardComponent`). Our own SVG charts,
   themed with the `--color-chart-1` … `--color-chart-8` tokens; pass `series` (`{ name, values }`) and
@@ -182,7 +190,7 @@ or out of date — wire it into CI so agent guidance never drifts from the insta
   `border-border`, `rounded-field`, `shadow-raised`, `text-body`). Never raw palette classes and
   never `dark:` variants; put `dark` on `<html>` and the theme re-colors everything.
 - Forms: `bf-input`, `bf-number-input`, `bf-textarea`, `bf-select`, `bf-checkbox`, `bf-toggle`,
-  `bf-radio-group` and `bf-segmented` expose `value` / `checked` as `model()` and implement
+  `bf-radio-group`, `bf-segmented`, `bf-file-input` and `bf-image-input` expose `value` / `checked` as `model()` and implement
   Signal Forms' `FormValueControl` / `FormCheckboxControl`. Bind either `[formField]="form.field"` or
   `[(value)]` / `[(checked)]`, never both. Import `FormField`, `FormRoot`, `form` and the
   validators from `@angular/forms/signals`. The first error shows once the field is touched: its
@@ -200,6 +208,14 @@ or out of date — wire it into CI so agent guidance never drifts from the insta
   (`number | null`, `null` while empty; `min()`/`max()` reach the native input; unreadable text is
   a `parse` error on the bound field, blocking `submit()`), never to a `string` model on
   `bf-input type="number"`.
+- Files: `bf-file-input` binds a `File[]` (`multiple` for several; `variant="dropzone"` for a drop
+  area) and `bf-image-input` a `File | null` (`[(src)]` shows the saved picture; Remove sets both
+  to null). Both only pick: upload from the form's `submission`. `accept`, `maxSize` and
+  `maxFiles` refuse a file without making the field invalid; read refusals from `(rejected)`
+  (`BfRejectedFile[]`). `required()` does not count an empty `File[]` as empty: add
+  `validate(p.files, ({ value }) => value().length === 0 ? requiredError() : undefined)`. For an
+  image with a `src`, give the marker with `metadata(p.avatar, REQUIRED, () => true)` and a
+  `validate()` that counts `src` too.
 - Reactive Forms work through Angular 22's built-in interop: `[formControl]` and
   `formControlName` bind every form widget above with no `ControlValueAccessor` (never add one).
   Value, touched, dirty, validity, pending, disabled, required and errors flow into the widget;
@@ -238,7 +254,7 @@ you can guess a binding without looking it up:
   spinner, tab bar, progress or icon); every component that renders a native input, select or
   textarea (checkbox and toggle included) also takes `ariaLabel` and `ariaLabelledby` for when no
   visible `label` is shown; a built-in sub-control's name is `<part>Label` (`dismissLabel`,
-  `closeLabel`, `actionLabel`); `alt` only on `bf-avatar`.
+  `closeLabel`, `actionLabel`); `alt` only on `bf-avatar` and `bf-media-card`.
 - Types: every union or object type of an input, model, output, `Bf…Options`/`Bf…Config` property
   or an interface they name is a named type exported from the same entry
   (`BfToggleLabelPosition`, `BfRefresherRefreshEvent`, `BfDialogRole`, …), so type your own state
@@ -260,7 +276,8 @@ toolbar or a German settings page); a key you leave out keeps the parent's value
 
 - `provideBfDefaults({ size, fieldSize, controlSize })` sets the height step (`BfSize`: `sm` 32,
   `md` 40, `lg` 48 px) a widget uses when its own `size` input is unset. `fieldSize` covers the
-  text fields (`bf-input`, `bf-number-input`, `bf-select`, `bf-textarea`), `controlSize` the
+  text fields (`bf-input`, `bf-number-input`, `bf-select`, `bf-textarea`, and the file pickers
+  `bf-file-input`, `bf-image-input`), `controlSize` the
   actions and choice controls (`bf-button`, `bf-icon-button`, `bf-chip`, `bf-segmented`,
   `bf-checkbox`, `bf-toggle`, `bf-radio-group`); `size` sets both, and an explicit
   `fieldSize`/`controlSize` wins over it. The library default is compact `md` for both (desktop
@@ -374,10 +391,31 @@ protected readonly colorScheme = inject(BfColorSchemeService);
   sorts the rows in a `computed()`, and a selection shows a `bf-action-bar`. `stack="narrow"`
   (below 36rem of its own width) or `stack="coarse"` turns each row into a label/value tile with
   a sort and select bar; in the Capacitor shell use `bf-list-item` rows instead.
+  A settings matrix puts a `bf-toggle` in each cell (`align: 'center'` columns, the row label
+  first, every toggle named `[ariaLabel]="column + ', ' + row"`).
 - **Details:** `bf-description-list` of `div[bfDescriptionItem]` label/value pairs, and `bf-stat`
   figure tiles in a grid; both work in both shells.
+- **History:** `<bf-timeline label="…">` of `<bf-timeline-event actor="…" [time]="iso" tone="…">`
+  (text with inline links in the content, a small action in `bfSlot="end"`) for a record's
+  history or an audit trail, in the order the app gives; times follow `LOCALE_ID` (`timeFormat`,
+  `timeText` for a relative time). Not for navigation or steps.
+- **Chat:** a `bf-chat-thread` (give it `class="flex-1"` or a height) of `bf-chat-message`
+  elements (`role` `user` or `assistant`, `author`, `streaming`, `status`) above a
+  `bf-chat-composer` from `/overlay` (`[(value)]="draft"`, `[running]="replying()"`,
+  `(sent)="ask($event)"`, `(stopped)="cancel()"`). A message's content is the app's rendered,
+  sanitised markdown, styled by the body's `bfProse`; cards and chips go in `bfSlot="content"`,
+  Retry in `bfSlot="action"`; the composer's icons go in `bfSlot="send-icon"` and
+  `bfSlot="stop-icon"`, extra controls in `start` and `end`. The thread follows new text, shows
+  "Jump to latest" when scrolled up and is `aria-busy` while a message streams; never scroll or
+  animate it yourself. Set `streaming` false when the reply ends, stops or fails.
 - **Cards in a grid:** the grid stretches each `bf-card` and its `bfSlot="footer"` sits on the
   bottom edge, so footers line up; put a footer's parts in one element.
+- **Pictures that are slow or can fail:** `bf-media-card` owns the picture (`[src]`, `alt`,
+  `[loading]`, `loadingLabel="Drawing…"`, `[failed]`): a skeleton while it loads (or while `src`
+  is empty and `loading`), a fade when it arrives, a message and `bfSlot="failed-action"` (Retry)
+  when it fails; retry with a changed `src`. Never project your own `<img>` for the main picture.
+  Clickable like `bf-card` (a `bfAction` in the title); `selectable` with `[(selected)]` and
+  `label` for a pick-several grid.
 - **Rows on a card:** `<bf-list [inset]="false" divided class="-mx-card">`, flush to the card's
   edges with lines between the rows.
 - **Theme switch:** `<bf-theme-switch [(value)]="colorScheme.scheme" />` (or
@@ -395,8 +433,8 @@ protected readonly colorScheme = inject(BfColorSchemeService);
   for the platform picker on touch). Values are ISO strings (`'2026-10-28'`, `'14:30'`,
   `'2026-10-28T14:30'`); month and day names come from `Intl` in the document's language.
 - **Picking from many options:** `bf-combobox` (`/overlay`) for one value with search, groups and
-  server search (`queried`, `loading`); `bf-multi-combobox` for tags. `bf-select` stays the choice
-  for a short fixed list.
+  server search (`queried`, `loading`); `bf-multi-combobox` for tags. `bf-select` (`/overlay`
+  too) stays the choice for a short fixed list.
 - **Dashboards:** `bf-stat` with `delta`, `trend` and `trendIntent` for a figure and its change;
   `@bitforgehq/ui/charts` for `bf-line-chart`, `bf-bar-chart`, `bf-donut-chart` and
   `bf-sparkline` inside a `bf-chart-card` (title, period slot, loading, empty and error states),
@@ -408,6 +446,13 @@ protected readonly colorScheme = inject(BfColorSchemeService);
 - **Empty pages:** a 404, "no access" or "nothing here yet" page is a `bf-empty-state` with
   `headingLevel` 1, centred in the content area, with the main action and an optional link.
 - **Toolbar on a phone:** `bf-toolbar` keeps its status and actions together on the last row.
+- **Severity:** soft `bf-badge` tones for most states; `emphasis="strong"` (a solid fill, also on
+  a count pill) only for the one that must stand out, such as `variant="danger"` "Critical".
+- **Inbox and notifications:** `bf-list-item [unread]="!item.read"` (dot, bolder title, "Unread"
+  read before the title, also in its `bfAction`'s name); clear it when the row is opened.
+- **Instructions in order:** `<bf-steps>` of `<bf-step title="Install the app">…details…</bf-step>`
+  (`start` to continue a list) for setup steps in both shells; not a wizard (a multi-page flow
+  with state is a set of pages).
 
 ## Overlays (`@bitforgehq/ui/overlay`)
 
@@ -445,6 +490,12 @@ injector? })` stacks up to three cards bottom-right (configurable with
 - **Side panel:** `BfSidePanelService.open(component | template, { width, modal, data })` slides a
   full-height `bf-side-panel` in from the inline end: a record's details or edit form beside the
   list. `modal: false` keeps the page usable. In the Capacitor shell use `bf-sheet`/`bf-modal`.
+- **Image viewer:** `BfImageViewerService.open(options)` with `images` (each
+  `{ src, label, caption? }`), `index`, `origin`, `actions` and `injector` shows one image full
+  screen over a dark scrim and steps through the set (buttons, arrow keys, Home/End, wrapping);
+  pass the clicked thumbnail as `origin` (or `(i) => thumbnails[i]`) so it zooms out of it and
+  back. Actions go in an `ng-template` (context `{ $implicit: image, index, ref }`). It returns a
+  `BfImageViewerRef` (`index()`, `next()`, `previous()`, `goTo()`, `close()`, `afterClosed`).
 - **`closeOnNavigation`:** every overlay (`BfDialogConfig`, `confirm()`, and the `/mobile` sheet,
   modal, action sheet and alert options) closes when the URL path changes by default (`true`);
   pass `closeOnNavigation: false` to keep one open across a navigation (e.g. a draft that must
@@ -976,7 +1027,7 @@ describe('bf-button in a consumer app (Vitest)', () => {
 
 ### 6. Drive a form widget through its harness
 
-The entry ships CDK harnesses for the widgets whose markup is not obvious to drive: `BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfMenuButtonHarness`, `BfDesktopToastHarness`, `BfTableHarness`, `BfPaginationHarness` `BfTabGroupHarness`, `BfCalendarHarness` and `BfChartHarness`. `with({ label })` finds a widget by its label. Load an in-page widget with `TestbedHarnessEnvironment.loader(fixture)`.
+The entry ships CDK harnesses for the widgets whose markup is not obvious to drive: `BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfMenuButtonHarness`, `BfDesktopToastHarness`, `BfTableHarness`, `BfToggleHarness`, `BfPaginationHarness` `BfTabGroupHarness`, `BfCalendarHarness`, `BfFileInputHarness`, `BfImageInputHarness`, `BfMediaCardHarness`, `BfChatComposerHarness` and `BfChartHarness`. `with({ label })` finds a widget by its label. Load an in-page widget with `TestbedHarnessEnvironment.loader(fixture)`. jsdom has no `URL.createObjectURL`, so after `addFile()` `BfImageInputHarness.hasPreview()` stays false: assert on the bound value, or stub `URL.createObjectURL` to read the preview.
 
 `select-harness.spec.ts`:
 
@@ -989,7 +1040,7 @@ import { Component, signal } from '@angular/core';
 import { TestBed } from '@angular/core/testing';
 import { TestbedHarnessEnvironment } from '@angular/cdk/testing/testbed';
 import { FormField, form, required } from '@angular/forms/signals';
-import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 import { BfSelectHarness, provideBfTesting } from '@bitforgehq/ui/testing';
 
 @Component({
@@ -1046,7 +1097,7 @@ describe('BfSelectHarness in a consumer app (Vitest)', () => {
 
 ### 7. Drive a dialog from the document root
 
-Dialogs, menus and toasts render in the CDK overlay container at the end of `<body>`, outside the fixture. Load their harnesses with `TestbedHarnessEnvironment.documentRootLoader(fixture)`.
+Dialogs, menus and toasts render in the CDK overlay container at the end of `<body>`, outside the fixture. Load their harnesses with `TestbedHarnessEnvironment.documentRootLoader(fixture)`; `BfImageViewerHarness` drives the image viewer the same way. jsdom never loads images: `BfMediaCardHarness` and `BfImageViewerHarness` fire the `load` and `error` events with `loadImage()` and `failImage()`.
 
 `dialog-harness.spec.ts`:
 
@@ -1203,6 +1254,7 @@ notes.
 | Component           | Entry point                   | Purpose                                                                                     |
 | ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
 | `bf-calendar`       | `@bitforgehq/ui`              | Inline month calendar for picking one date, with month and year jumps                       |
+| `bf-chat-composer`  | `@bitforgehq/ui/overlay`      | Chat input that grows with the text and sends on Enter, or stops a reply                    |
 | `bf-checkbox`       | `@bitforgehq/ui`              | Rounded checkbox with an optional label that binds to Signal Forms                          |
 | `bf-chip`           | `@bitforgehq/ui`              | Toggleable filter chip with a check mark when selected, in tonal or ink style               |
 | `bf-chip-group`     | `@bitforgehq/ui`              | Named row of chips that picks one like radios, or groups independent toggles                |
@@ -1210,12 +1262,14 @@ notes.
 | `bf-date-input`     | `@bitforgehq/ui/overlay`      | Typed date field with a calendar popover, valued as an ISO date string                      |
 | `bf-datetime-input` | `@bitforgehq/ui/overlay`      | Typed date and time field with a calendar and time list in one popover                      |
 | `bf-field`          | `@bitforgehq/ui`              | Label, help text and error text wrapper that wires ids for assistive tech                   |
+| `bf-file-input`     | `@bitforgehq/ui`              | File picker field that lists picked or dropped files and checks type, size and count        |
+| `bf-image-input`    | `@bitforgehq/ui`              | Single-image picker with a round or square preview tile and replace or remove               |
 | `bf-input`          | `@bitforgehq/ui`              | Single-line text field with label, help and error text, icon slots and Signal Forms binding |
 | `bf-multi-combobox` | `@bitforgehq/ui/overlay`      | Text field that filters options as you type and picks several as tags                       |
 | `bf-number-input`   | `@bitforgehq/ui/number-input` | Number field that binds number or null, with native min, max and step                       |
 | `bf-radio-group`    | `@bitforgehq/ui`              | Group of radio buttons for choosing one option, with optional per-option descriptions       |
 | `bf-segmented`      | `@bitforgehq/ui`              | Segmented control for switching between two to four views, keyboard-navigable like radios   |
-| `bf-select`         | `@bitforgehq/ui`              | Native single-choice dropdown styled like the text field, with Signal Forms binding         |
+| `bf-select`         | `@bitforgehq/ui/overlay`      | Single-choice dropdown with a styled list, native under touch, with Signal Forms binding    |
 | `bf-textarea`       | `@bitforgehq/ui`              | Multi-line text field with label, help and error text, and Signal Forms binding             |
 | `bf-theme-switch`   | `@bitforgehq/ui`              | Segmented System, Light and Dark switch bound two-way to the app colour scheme              |
 | `bf-time-input`     | `@bitforgehq/ui/overlay`      | Typed time-of-day field with a popover list of times, valued as an ISO string               |
@@ -1230,16 +1284,23 @@ notes.
 | `bf-bar-chart`           | `@bitforgehq/ui/charts` | Bar chart of series over categories, grouped or stacked, vertical or horizontal         |
 | `bf-card`                | `@bitforgehq/ui`        | Content surface with an optional header slot, in four visual styles from raised to flat |
 | `bf-chart-card`          | `@bitforgehq/ui/charts` | Card around one chart with a title, period control and loading, empty and error states  |
+| `bf-chat-message`        | `@bitforgehq/ui`        | One chat message, a user bubble or a full-width assistant reply that can stream         |
+| `bf-chat-thread`         | `@bitforgehq/ui`        | Scrolling chat message log that follows new text and offers a jump to latest            |
 | `div[bfDescriptionItem]` | `@bitforgehq/ui`        | One label and value pair of a description list, label as term, content as value         |
 | `bf-description-list`    | `@bitforgehq/ui`        | Native description list of label-value pairs, as divided rows or a tile grid            |
 | `bf-donut-chart`         | `@bitforgehq/ui/charts` | Donut chart of the parts of a whole, with a legend, tooltip and centre slot             |
 | `bf-line-chart`          | `@bitforgehq/ui/charts` | Line chart of series over categories, with tooltip, legend and data table               |
 | `bf-list`                | `@bitforgehq/ui`        | Container for list rows, inset by default with rounded corners on a warm background     |
 | `bf-list-item`           | `@bitforgehq/ui`        | List row with leading slot, title, subtitle, trailing slot and an optional chevron      |
+| `bf-media-card`          | `@bitforgehq/ui`        | Card with an image that loads, fades in or fails, plus a body and actions               |
 | `bf-progress`            | `@bitforgehq/ui`        | Progress bar in two sizes and four tones for completion, quotas and unknown waits       |
 | `bf-sparkline`           | `@bitforgehq/ui/charts` | Tiny trend line with no axes or legend, for stats and table cells                       |
 | `bf-stat`                | `@bitforgehq/ui`        | One labelled figure with an optional icon tile and a supporting line                    |
+| `bf-step`                | `@bitforgehq/ui`        | One numbered step of an instruction list, with a title and its details                  |
+| `bf-steps`               | `@bitforgehq/ui`        | Numbered instruction steps a user follows in order, with joined markers                 |
 | `bf-table`               | `@bitforgehq/ui`        | Desktop data table with sortable headers, row selection, custom cells and an empty slot |
+| `bf-timeline`            | `@bitforgehq/ui`        | Dated list of events with who did what and when, on a vertical line                     |
+| `bf-timeline-event`      | `@bitforgehq/ui`        | One timeline event with a coloured marker, its text, actor and time                     |
 
 ### Feedback
 
@@ -1284,6 +1345,7 @@ notes.
 | `bf-alert-dialog`      | `@bitforgehq/ui/mobile`  | Centred confirmation dialog with a title, message and a row of role-styled buttons            |
 | `bf-desktop-toast`     | `@bitforgehq/ui/overlay` | Desktop notification card in a bottom corner stack of up to three                             |
 | `bf-dialog`            | `@bitforgehq/ui/overlay` | Desktop modal dialog with a title, scrolling body, footer actions and focus trap              |
+| `bf-image-viewer`      | `@bitforgehq/ui/overlay` | Full-screen image viewer that zooms from a thumbnail and steps through a set                  |
 | `bf-menu`              | `@bitforgehq/ui/overlay` | Keyboard-operable menu panel with items, checkbox and radio items, groups and submenus        |
 | `bf-menu-button`       | `@bitforgehq/ui/overlay` | Styled button that opens a menu, with outline, text, tonal and icon-only looks                |
 | `bf-modal`             | `@bitforgehq/ui/mobile`  | Modal overlay shown as an inset card over the scaled-down page, or full screen                |

package/ai/components/app-frame.md

@@ -157,7 +157,7 @@ Use `bf-app-frame` once, at the root of a desktop web app whose top-level destin
 
 ## Slots and layout
 
-Put the `bf-sidebar` in `bfSlot="sidebar"`, the app's name or logo in `bfSlot="brand"`, the narrow-screen `bf-menu-button` of `a[bfMenuItem]` router links in `bfSlot="menu"` and end actions (the theme menu, the account) in `bfSlot="actions"`; everything else is the page. From the breakpoint up the sidebar column sits at the inline start, `sticky top-0` and `h-dvh` tall, and the `bf-sidebar` inside fills it and scrolls its own destinations; the header bar is hidden. Below it the sidebar column is hidden and the header bar (`surface`, a bottom border, sticky at the top) shows the menu at the inline start, then the brand, and the actions at the end: the top app bar convention, and the menu comes first in the tab order too. The order is fixed, whatever order the slots have in your template. Keep the brand in the sidebar's own `header` slot too, for the wide layout.
+Put the `bf-sidebar` in `bfSlot="sidebar"`, the app's name or logo in `bfSlot="brand"`, the narrow-screen `bf-menu-button` of `a[bfMenuItem]` router links in `bfSlot="menu"` and end actions (the theme menu, the account) in `bfSlot="actions"`; everything else is the page. From the breakpoint up the sidebar column sits at the inline start, `sticky top-0` and `h-dvh` tall, and the `bf-sidebar` inside fills it and scrolls its own destinations; the header bar is hidden. Below it the sidebar column is hidden and the header bar (`surface`, a bottom border, sticky at the top) shows the menu at the inline start, then the brand, and the actions at the end: the top app bar convention, and the menu comes first in the tab order too. The order is fixed, whatever order the slots have in your template. Keep the brand in the sidebar's own `header` slot too, for the wide layout. The sidebar column takes the sidebar's width, so when the sidebar collapses or expands the content column moves with its animation instead of jumping.
 
 ## Breakpoint and content width
 

package/ai/components/badge.md

@@ -66,6 +66,31 @@ import { BfBadgeComponent } from '@bitforgehq/ui';
 export class BadgeStatusExampleComponent {}
 ```
 
+## Emphasis
+
+`emphasis="strong"` turns the soft tint into a solid fill with contrasting text, for the one state that must stand out from the rest: a "Critical" finding among "High" and "Medium" ones. It takes every variant (`primary` uses the brand fill) and the count pill too: a strong count takes its fill from `variant`, so `variant="danger" emphasis="strong" [count]="3"` is a red pill, while a soft count stays the primary pill. `emphasis` takes a `BfBadgeEmphasis` (`soft`, the default, or `strong`).
+
+```ts
+import { Component } from '@angular/core';
+import { BfBadgeComponent } from '@bitforgehq/ui';
+
+/** A strong badge marks the one critical finding among soft status badges. */
+@Component({
+  selector: 'app-example-badge-strong',
+  imports: [BfBadgeComponent],
+  template: `
+    <div class="flex flex-wrap items-center gap-2">
+      <bf-badge variant="danger" emphasis="strong">Critical</bf-badge>
+      <bf-badge variant="danger">High</bf-badge>
+      <bf-badge variant="warning">Medium</bf-badge>
+      <bf-badge>Low</bf-badge>
+      <bf-badge variant="danger" emphasis="strong" [count]="3" countLabel="critical findings" />
+    </div>
+  `,
+})
+export class BadgeStrongExampleComponent {}
+```
+
 ## Count pill
 
 Setting `count` switches to the compact primary pill. Values above 99 render as "99+"; zero renders as "0".
@@ -128,17 +153,19 @@ Consumes tokens by variant, background then text:
 - `danger`: `danger-soft` / `danger`
 - `info`: `info-soft` / `info` (≥ 4.5:1 in both modes; it is not derived from the primary, so a custom brand colour leaves it unchanged)
 - Count pill (`count` set): `primary` / `on-primary`, ignoring `variant`
+- Strong (`emphasis="strong"`, label and count pill): `<variant>-strong` / `on-<variant>-strong` (`neutral-strong`, `success-strong`, `warning-strong`, `danger-strong`, `info-strong`, each with its `on-` text token; ≥ 4.5:1 in both modes and the fill ≥ 3:1 on `bg`, `surface` and `surface-sunken`); `primary` uses `primary` / `on-primary`. An app can retune `--color-danger-strong` and `--color-on-danger-strong` (and the others) in `@theme` and `.dark` like any status token
 - Shape (label and count pill): `rounded-control` (`--radius-control`, `9999px` by default).
 
 ## Accessibility
 
-A badge is a plain `<span>` with no role or ARIA attributes; its text is read as part of the surrounding content, so pair it with a label or context that says what it means rather than relying on color alone. A count pill with `countLabel` carries that context itself: a visually hidden (`sr-only`) span after the number, read as one phrase with it ("99+ unread messages").
+A badge is a plain `<span>` with no role or ARIA attributes; its text is read as part of the surrounding content, so pair it with a label or context that says what it means rather than relying on color alone. A count pill with `countLabel` carries that context itself: a visually hidden (`sr-only`) span after the number, read as one phrase with it ("99+ unread messages"). A strong badge is louder, not more meaningful: its text ("Critical", "Kritisch") still says the state. In forced colours (Windows High Contrast) the fills give way to the system colours, so a strong badge draws a `CanvasText` outline and still reads as a filled pill next to a soft one.
 
 ## Inputs
 
 | Name         | Type                                                                                           | Default     | Description                                                                                                                                          |
 | ------------ | ---------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `variant`    | `BfBadgeAppearance` (`'neutral' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'info'`) | `'neutral'` | Tint for the label style: neutral, primary, success, warning, danger or info. Ignored when `count` is set.                                           |
+| `variant`    | `BfBadgeAppearance` (`'neutral' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'info'`) | `'neutral'` | Tint for the label style: neutral, primary, success, warning, danger or info. Ignored by a soft count pill; a strong one takes its fill from it.     |
+| `emphasis`   | `BfBadgeEmphasis` (`'soft' \| 'strong'`)                                                       | `'soft'`    | `soft` (a pale tint, the default) or `strong` (a solid fill with contrasting text, also for the count pill).                                         |
 | `count`      | `number \| undefined`                                                                          | `undefined` | Switches to the count pill; values above 99 render as "99+".                                                                                         |
 | `countLabel` | `string`                                                                                       | `''`        | What the count counts ("unread messages"), read by assistive tech after the number ("99+ unread messages"); visually hidden. Only used with `count`. |
 
@@ -152,15 +179,25 @@ A badge is a plain `<span>` with no role or ARIA attributes; its text is read as
 
 - Keep labels to one or two words; badges are scanned, not read.
 - Pair a count pill with a label or icon that says what is being counted, and set `countLabel` so the number is not read alone.
+- Keep `emphasis="strong"` for the one state that must stand out on the screen, such as critical findings.
 
 ### Don't
 
 - Don't use a badge as a button; it has no interactive states.
 - Don't invent new colors on it; pick the variant that matches the meaning.
 - Don't use `primary` or `success` for a category; use `info`, so the status tones keep their meaning.
+- Don't make every badge strong: when all of them shout, none stands out.
 
 ## Migration notes
 
+### 0.4.0
+
+New `emphasis` input (`BfBadgeEmphasis`: `soft`, the default, or `strong`). `strong` is a solid
+fill with contrasting text in every variant, for the one state that must stand out ("Critical");
+`primary` uses the brand fill. A strong count pill takes its fill from `variant` (a soft count pill
+stays primary, as before). In forced colours a strong badge keeps a `CanvasText` outline. Opt-in:
+without `emphasis` nothing changes.
+
 ### 0.3.1
 
 New `info` tone for informational labels such as a category, on the new `info` / `info-soft`