@bitforgehq/ui 0.4.0 → 0.5.0-next.4

package/ai/UI_GUIDE.md

@@ -147,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 45 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. 29 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 50 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. 32 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
 
@@ -176,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
@@ -186,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
@@ -204,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;
@@ -242,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`, `bf-media-card` and `bf-image-tile`.
 - 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
@@ -264,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
@@ -386,8 +399,28 @@ protected readonly colorScheme = inject(BfColorSchemeService);
   (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.
+- **Thumbnail grids:** `bf-image-tile` (`[src]`, `alt`, `aspect`, `captionPlacement="overlay"`
+  for the title on a gradient over the picture), with a `bfAction` link or button in its title
+  heading, `bfSlot="meta"` for a date or count, `bfSlot="badge"` for a `bf-badge` and
+  `[selected]` for the current one. Put tiles straight into a CSS grid: they stretch to the row
+  and keep two title lines, so a row lines up; give every tile a meta line or none.
 - **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
@@ -399,14 +432,17 @@ protected readonly colorScheme = inject(BfColorSchemeService);
 - **Paging and loading:** `<bf-pagination [(page)]="page" [total]="count" [pageSize]="20">` under a
   `bf-table` (the app slices its rows); `bf-skeleton` (`shape` text/rect/circle, `lines`) as the
   placeholder while data loads, inside a region with `aria-busy="true"`.
+- **Stepping through versions:** a compact `bf-pagination` with `[pageCount]`,
+  `[positionLabel]="(page, count) => …"` ("v3 of 7") and `previousLabel`/`nextLabel`; past four
+  options it replaces a `bf-segmented`.
 - **Dates and times:** `<bf-calendar [(value)]="date">` for an inline month view;
   `bf-date-input`, `bf-time-input` and `bf-datetime-input` (`/overlay`) for a field: typed parts
   in locale order plus a calendar or time-list popover (`picker="none"` for typed only, `native`
   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),
@@ -462,6 +498,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
@@ -993,7 +1035,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`, `BfToggleHarness`, `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`, `BfImageTileHarness`, `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`:
 
@@ -1006,7 +1048,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({
@@ -1063,7 +1105,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`, `BfImageTileHarness` and `BfImageViewerHarness` fire the `load` and `error` events with `loadImage()` and `failImage()`.
 
 `dialog-harness.spec.ts`:
 
@@ -1220,6 +1262,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                |
@@ -1227,12 +1270,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               |
@@ -1247,12 +1292,16 @@ 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-image-tile`          | `@bitforgehq/ui`        | Small card for thumbnail grids: a picture and title that act as one target              |
 | `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                    |
@@ -1305,6 +1354,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

@@ -91,6 +91,37 @@ import { BfBadgeComponent } from '@bitforgehq/ui';
 export class BadgeStrongExampleComponent {}
 ```
 
+## Icon
+
+An icon in the `icon-start` slot sits before the text, at 12 px whatever the `bf-icon`'s own `size`, 4 px from the text, and the start padding tightens to match. Use it to repeat what the text says at a glance, a check on "Reference" or a cube on "3 versions", never instead of the text. A count pill does not show it.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBadgeComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Box, Check, Clock } from 'lucide';
+
+/** Badges with a leading icon: the icon repeats the meaning, the text still says it. */
+@Component({
+  selector: 'app-example-badge-icon',
+  imports: [BfBadgeComponent, BfIconComponent],
+  template: `
+    <div class="flex flex-wrap items-center gap-2">
+      <bf-badge variant="success"><bf-icon bfSlot="icon-start" [icon]="check" />Reference</bf-badge>
+      <bf-badge variant="info"><bf-icon bfSlot="icon-start" [icon]="box" />3 versions</bf-badge>
+      <bf-badge variant="warning" emphasis="strong"
+        ><bf-icon bfSlot="icon-start" [icon]="clock" />Queued</bf-badge
+      >
+    </div>
+  `,
+})
+export class BadgeIconExampleComponent {
+  protected readonly check = Check;
+  protected readonly box = Box;
+  protected readonly clock = Clock;
+}
+```
+
 ## Count pill
 
 Setting `count` switches to the compact primary pill. Values above 99 render as "99+"; zero renders as "0".
@@ -154,11 +185,12 @@ Consumes tokens by variant, background then text:
 - `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
+- Icon (`icon-start`): drawn in the text colour (`currentColor`), so it follows the variant and stays visible in forced colours
 - 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 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.
+A badge is a plain `<span>` with no role or ARIA attributes; a `bf-icon` in `icon-start` is decorative (`aria-hidden`) unless it has a `label`, so the text alone carries the meaning; 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
 
@@ -171,6 +203,7 @@ A badge is a plain `<span>` with no role or ARIA attributes; its text is read as
 
 ## Slots
 
+- `icon-start`: An icon before the text, drawn at 12 px; not shown on a count pill.
 - `default`: The badge text, shown when no `count` is set.
 
 ## Notes
@@ -190,6 +223,13 @@ A badge is a plain `<span>` with no role or ARIA attributes; its text is read as
 
 ## Migration notes
 
+### 0.5.0
+
+New `icon-start` slot: `<bf-icon bfSlot="icon-start" … />` before the label text, drawn at 12 px
+whatever the icon's `size`, 4 px from the text, with the start padding tightened to 8 px. It
+takes the text colour, so it follows the variant and forced colours. A count pill does not show
+it.
+
 ### 0.4.0
 
 New `emphasis` input (`BfBadgeEmphasis`: `soft`, the default, or `strong`). `strong` is a solid