@bitforgehq/ui 0.3.3 → 0.4.0

package/llms-full.txt

@@ -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,10 +147,10 @@ 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`,
+`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. 27 of them render identically twice. The other 16
+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`,
@@ -374,8 +378,14 @@ 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.
 - **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.
 - **Rows on a card:** `<bf-list [inset]="false" divided class="-mx-card">`, flush to the card's
@@ -408,6 +418,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`)
 
@@ -976,7 +993,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` and `BfChartHarness`. `with({ label })` finds a widget by its label. Load an in-page widget with `TestbedHarnessEnvironment.loader(fixture)`.
 
 `select-harness.spec.ts`:
 
@@ -1239,7 +1256,11 @@ notes.
 | `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
 
@@ -3830,6 +3851,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".
@@ -3892,17 +3938,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`. |
 
@@ -3916,15 +3964,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`
@@ -13342,6 +13400,7 @@ export class ListItemOverviewExampleComponent {
 One row of a list: leading slot (avatar, icon tile), title and subtitle, trailing slot
 (time, toggle, badge) and an optional chevron for rows that navigate. A navigation row puts a
 `bfAction` link in the `title` slot, so the row stays a list item and the link covers it.
+`unread` marks a row not yet opened with a dot and a bolder title.
 
 A row of a list: a leading slot (an avatar, an icon), the title and subtitle, a trailing slot (a time, a toggle, a chip) and an optional chevron. Place rows in a [`bf-list`](https://bitforge-ui.web.app/components/list), which gives them the list semantics and the inset container; a row can also stand alone. A row is static text, a navigation link or an action button, never more than one of them.
 
@@ -13472,6 +13531,87 @@ export class ListItemActionsExampleComponent {
 }
 ```
 
+## Unread rows
+
+`unread` marks a row the user has not opened yet, such as a new message or notification: a small `primary` dot at the row's inline start, on the title line, and the title in a bolder weight. It is not colour alone: the row also reads a visually hidden state before the title, from the `listItemUnread` label ("Unread"; set it with `provideBfLabels({ listItemUnread: 'Ungelesen' })` in a German app), so a screen reader says "Unread, Scan finished". The dot sits in the row's own inline-start padding (or the gap after a leading avatar or icon), so read and unread rows keep their text aligned and nothing moves when a row is marked read; without `unread` nothing changes. Clear `unread` when the row is opened.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfActionDirective, BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+
+interface Notice {
+  readonly id: string;
+  readonly title: string;
+  readonly subtitle: string;
+  readonly time: string;
+  readonly unread: boolean;
+}
+
+/**
+ * An inbox with unread rows.
+ *
+ * Each title is a stretched `<button bfAction>`; opening a row marks it read.
+ */
+@Component({
+  selector: 'app-example-list-item-unread',
+  imports: [BfActionDirective, BfListComponent, BfListItemComponent],
+  template: `
+    <bf-list>
+      @for (notice of notices(); track notice.id) {
+        <bf-list-item [unread]="notice.unread" [subtitle]="notice.subtitle">
+          <button bfSlot="title" bfAction type="button" class="text-start" (click)="open(notice)">
+            {{ notice.title }}
+          </button>
+          <span bfSlot="trailing" class="text-caption text-text-muted">{{ notice.time }}</span>
+        </bf-list-item>
+      }
+    </bf-list>
+    <p data-status aria-live="polite" class="text-caption text-text-muted mt-3">{{ status() }}</p>
+  `,
+})
+export class ListItemUnreadExampleComponent {
+  protected readonly notices = signal<readonly Notice[]>([
+    {
+      id: 'scan',
+      title: 'Scan finished',
+      subtitle: '3 new findings on api.example.com',
+      time: '9:41',
+      unread: true,
+    },
+    {
+      id: 'cert',
+      title: 'Certificate expires soon',
+      subtitle: 'shop.example.com, in 12 days',
+      time: '8:15',
+      unread: true,
+    },
+    {
+      id: 'report',
+      title: 'Weekly report',
+      subtitle: 'Ready to download',
+      time: 'Mon',
+      unread: false,
+    },
+  ]);
+  private readonly opened = signal('');
+
+  protected readonly status = computed(() => {
+    const unread = this.notices().filter((notice) => notice.unread).length;
+    const opened = this.opened();
+    return opened ? `${unread} unread · Opened: ${opened}` : `${unread} unread`;
+  });
+
+  protected open(notice: Notice): void {
+    this.opened.set(notice.title);
+    this.notices.update((list) =>
+      list.map((item) => (item.id === notice.id ? { ...item, unread: false } : item)),
+    );
+  }
+}
+```
+
+With a `bfAction` link or button in the `title` slot, the state becomes part of that element's accessible name: the directive sets `aria-labelledby` to the state text and the element itself (it gives the element an id if it has none, and keeps an `aria-labelledby` of its own after the state), so the link reads "Unread, Scan finished" when tabbed to or listed, and the state text is hidden from the tree so it is read once. An `interactive` row holds the state text inside its button, so its name starts with it too.
+
 ## Desktop
 
 An `interactive` row and a row holding a `bfAction` link take a `surface-muted` fill and the pointer cursor while hovered; a static row has none. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The ring is drawn around the row on keyboard focus only. A navigation row keeps the browser's link behaviour: Ctrl/Cmd-click and a middle click open it in a new tab. The trailing slot sits above the stretched link, so a toggle or button there takes its own click. Rows have one height; they do not follow `provideBfDefaults()`.
@@ -13482,10 +13622,11 @@ An `interactive` row and a row holding a `bfAction` link take a `surface-muted`
 - Text: the title, the title slot and the subtitle wrap (`wrap-anywhere`); with `truncate` each keeps one line (`truncate`).
 - `interactive` rows and rows holding a `bfAction` link add a pointer, a `surface-muted` hover, a `surface-pressed` fill while pressed (the row's action, for a `bfAction` row) and a `ring` focus ring; `interactive` rows dim to `text-disabled` when `disabled` and have no pressed state then.
 - The `chevron` mark uses `text-subtle`.
+- `unread`: the dot is `primary` (`CanvasText` in forced colours), `rounded-full` and 8 px (`size-2`); the title turns `font-extrabold`.
 
 ## Accessibility
 
-`bf-list-item` sets `role="listitem"` on its host only inside a `bf-list`; a standalone row has no role, so it never claims a list parent that is not there. A non-interactive row is a plain `<div>`, while `[interactive]="true"` renders it as a native `<button>` so it gets keyboard activation and the button role for free. A navigation row's `bfAction` link in the `title` slot is a real `<a>` inside the list item ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)): exposed as `link` with the title as its name, reached with Tab (in Safari and iOS WKWebView, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise); VoiceOver and Full Keyboard Access are unaffected), followed with Enter (not Space), opened in a new tab with Ctrl/Cmd-click; under forced colours a system-coloured outline around the whole row marks the focused link. Making the host itself a link would take the row out of the list's `listitem` structure, so the link lives inside it. `chevron` is a purely visual CSS mark (an `::after` pseudo-element), so it adds nothing to the accessibility tree.
+`bf-list-item` sets `role="listitem"` on its host only inside a `bf-list`; a standalone row has no role, so it never claims a list parent that is not there. A non-interactive row is a plain `<div>`, while `[interactive]="true"` renders it as a native `<button>` so it gets keyboard activation and the button role for free. A navigation row's `bfAction` link in the `title` slot is a real `<a>` inside the list item ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)): exposed as `link` with the title as its name, reached with Tab (in Safari and iOS WKWebView, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise); VoiceOver and Full Keyboard Access are unaffected), followed with Enter (not Space), opened in a new tab with Ctrl/Cmd-click; under forced colours a system-coloured outline around the whole row marks the focused link. Making the host itself a link would take the row out of the list's `listitem` structure, so the link lives inside it. `chevron` is a purely visual CSS mark (an `::after` pseudo-element), so it adds nothing to the accessibility tree. An `unread` row's dot carries a visually hidden (`sr-only`) state text from the `listItemUnread` label, read before the title ("Unread, Scan finished"); on a row with a `bfAction` the text is `aria-hidden` and the action names itself with `aria-labelledby` from it and its own content, so the state is part of the link's or button's name and is read once. The row stays a `listitem`.
 
 ### Keyboard
 
@@ -13505,6 +13646,7 @@ An `interactive` row and a row holding a `bfAction` link take a `surface-muted`
 | `chevron` | `boolean` | `false` | Show a trailing chevron (navigation rows). |
 | `disabled` | `boolean` | `false` | Disable an interactive row. |
 | `truncate` | `boolean` | `false` | Keep the title, the title slot and the subtitle on one line each, cut with an ellipsis. By default they wrap, so nothing is lost at large text sizes. |
+| `unread` | `boolean` | `false` | Mark the row as not yet opened: a dot at the inline start, a bolder title and a visually hidden state (the `listItemUnread` label) read before the title. |
 
 ## Outputs
 
@@ -13525,14 +13667,26 @@ An `interactive` row and a row holding a `bfAction` link take a `surface-muted`
 
 - Keep titles short; a long one wraps. Add `truncate` only where one line per row is the pattern (a mail list).
 - Make a row that navigates a `bfAction` link in the `title` slot, and a row that acts on the page `interactive`; put secondary actions in the trailing slot.
+- Set `unread` on rows not yet opened (messages, notifications) and clear it when the row is opened.
 
 ### Don't
 
 - Don't nest interactive controls inside an `interactive` row (it is one button); use a navigation row with a trailing control instead.
 - Don't wrap a `bf-list-item` in an `<a>`, and don't navigate from an `interactive` row's `(clicked)`.
+- Don't mark unread rows with a coloured title or a badge of your own; `unread` gives the dot, the weight and the screen-reader state together.
 
 ## Migration notes
 
+### 0.4.0
+
+New `unread` input (boolean, default false) for a row not yet opened: a `primary` dot at the
+row's inline start on the title line, a bolder title (`font-extrabold`) and a visually hidden
+state read before the title, from the new label key `listItemUnread` ("Unread"). A row's
+`bfAction` link or button then names itself `aria-labelledby="<state> <itself>"` ("Unread,
+Report"; an id is added if it has none, and its own `aria-labelledby` is kept after the state).
+The dot sits in the row's own inline-start padding, so read and unread rows stay aligned. Opt-in: without `unread` nothing
+changes.
+
 ### 0.3.0
 
 **Behaviour:** logical properties: text aligns to the inline start and the chevron sits at the
@@ -22974,6 +23128,248 @@ hidden word (new labels `statTrendUp`, `statTrendDown`, `statTrendFlat`). `trend
 
 ---
 
+# bf-step
+
+One numbered step of an instruction list, with a title and its details
+
+`BfStepComponent` from `@bitforgehq/ui` · Data display · since 0.4.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfStepComponent, BfStepsComponent } from '@bitforgehq/ui';
+
+/** Steps with a short instruction as the title and the details in the content. */
+@Component({
+  selector: 'app-example-step-overview',
+  imports: [BfStepComponent, BfStepsComponent],
+  template: `
+    <bf-steps>
+      <bf-step title="Export your contacts"
+        >In your old app, choose Export and save the file.</bf-step
+      >
+      <bf-step title="Import the file">
+        Pick the file you saved. Contacts that are already in your address book are merged, not
+        added twice.
+      </bf-step>
+      <bf-step title="Check the result" />
+    </bf-steps>
+  `,
+})
+export class StepOverviewExampleComponent {}
+```
+
+## Overview
+
+One step of a `bf-steps` list: a numbered marker, a short instruction as its title and the
+step's details in the content.
+
+One step of a [`bf-steps`](https://bitforge-ui.web.app/components/steps) list: `title` is the step's short instruction and the content holds its details (text, a code to type, an image or a button). The list numbers the steps by position; the step draws the numbered circle and the line to the next one. It works the same in both shells.
+
+## When to use
+
+Use `bf-step` for each instruction inside a `bf-steps` list. Use [bf-list-item](https://bitforge-ui.web.app/components/list-item) instead for a row the user opens or acts on, and [bf-description-list](https://bitforge-ui.web.app/components/description-list) for facts with no order.
+
+## Headings
+
+The title is text by default, which suits short steps. For a long guide whose steps hold screenshots or code, set `headingLevel` (`2`, `3` or `4`, a `BfStepHeadingLevel`) to the level that fits the page outline, so a screen-reader user can move from step to step by heading. The look does not change.
+
+```ts
+import { Component } from '@angular/core';
+import { BfStepComponent, BfStepsComponent } from '@bitforgehq/ui';
+
+/** Long steps with level 3 headings, so a screen-reader user can move between them. */
+@Component({
+  selector: 'app-example-step-headings',
+  imports: [BfStepComponent, BfStepsComponent],
+  template: `
+    <bf-steps>
+      <bf-step title="Create an API key" [headingLevel]="3">
+        In the console, open Settings, then API keys, and choose New key. Give it a name that says
+        where it is used, such as "CI pipeline", and copy it: it is shown only once.
+      </bf-step>
+      <bf-step title="Store the key as a secret" [headingLevel]="3">
+        Add it to your CI provider's secrets as BITFORGE_API_KEY. Never commit it to the repository.
+      </bf-step>
+    </bf-steps>
+  `,
+})
+export class StepHeadingsExampleComponent {}
+```
+
+## Desktop
+
+A step is not interactive: no hover, no pointer cursor, no focus stop; only a link or button in its content takes focus. It renders the same inside `provideBfShell()`.
+
+## Theming
+
+- Marker: `bg-primary-soft` / `text-primary-strong`, `text-label-sm` bold, a 24 px `rounded-full` circle; the line under it is `border-border`, hidden on the last step.
+- Title: `text-label` bold in `text`, wrapping anywhere; content: `text-body` in `text-secondary`.
+
+## Accessibility
+
+Inside `bf-steps` the host is a `role="listitem"`, so its position is announced ("2 of 3"); the visible number is `aria-hidden`. The title is a `p`, or an `h2`, `h3` or `h4` with `headingLevel`. Outside `bf-steps` the host claims no role.
+
+## Inputs
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | `''` | The step's short instruction ("Install the app"), shown next to the number. |
+| `headingLevel` | `BfStepHeadingLevel \| undefined` (`2 \| 3 \| 4 \| undefined`) | `undefined` | Renders the title as a heading of this level instead of text; leave it off for short steps. |
+
+## Slots
+
+- `default`: The step's details: text, a code snippet, an image or a button.
+
+## Notes
+
+### Do
+
+- Keep the title to one instruction and put everything else in the content.
+
+### Don't
+
+- Don't use `bf-step` outside a `bf-steps` list: it then has no number to show but 1.
+
+## Migration notes
+
+### 0.4.0
+
+New `bf-step`: one step of a `bf-steps` list, with `title` (the short instruction, text by
+default; `headingLevel` 2, 3 or 4, a `BfStepHeadingLevel`, makes it a heading) and the details
+in the default slot. Its number is drawn in a `primary-soft` circle and hidden from assistive
+technology, which reads the list position instead.
+
+---
+
+# bf-steps
+
+Numbered instruction steps a user follows in order, with joined markers
+
+`BfStepsComponent` from `@bitforgehq/ui` · Data display · since 0.4.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfStepComponent, BfStepsComponent } from '@bitforgehq/ui';
+
+/** Setting up the app on a phone, in four numbered steps with a code to type and a link. */
+@Component({
+  selector: 'app-example-steps-overview',
+  imports: [RouterLink, BfStepComponent, BfStepsComponent],
+  template: `
+    <bf-steps>
+      <bf-step title="Install the app">
+        Download Bitforge Guard from the App Store or Google Play.
+      </bf-step>
+      <bf-step title="Sign in">Use your work email address and the password you chose.</bf-step>
+      <bf-step title="Pair your phone">
+        Open Settings, then Devices, and enter this code:
+        <code
+          class="rounded-tile bg-surface-sunken text-label-sm text-text mt-2 block w-fit px-3 py-1.5 font-mono"
+          >K7F-29Q</code
+        >
+      </bf-step>
+      <bf-step title="Turn on notifications">
+        Allow them when the app asks, or later in
+        <a routerLink="/components/steps" class="text-primary-text underline"
+          >notification settings</a
+        >.
+      </bf-step>
+    </bf-steps>
+  `,
+})
+export class StepsOverviewExampleComponent {}
+```
+
+## Overview
+
+Numbered instructions a user follows in order, such as setting up an app on a phone: an
+ordered list of `bf-step` items, each with a numbered marker joined to the next by a line.
+
+Numbered instructions a user follows in order: a `bf-steps` list of `bf-step` items, each with a numbered circle, a short instruction as its title and the details under it, the circles joined by a thin line. It works the same in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-steps` for instructions the user carries out in order, outside the app or across it: "Set up the app on your phone", "Connect your domain". It is static content, not a wizard: a multi-page stepper that holds state and moves the user from step to step is a flow of pages (in the Capacitor shell, pages pushed in [bf-tabs](https://bitforge-ui.web.app/components/tabs) stacks), and a progress figure for such a flow is a [bf-progress](https://bitforge-ui.web.app/components/progress). Use [bf-list](https://bitforge-ui.web.app/components/list) instead for items that have no order.
+
+## Continued lists
+
+`start` sets the number of the first step, for a list continued after a paragraph or on another part of the page: `start="3"` numbers the steps 3, 4, 5. It takes a number or a plain attribute.
+
+```ts
+import { Component } from '@angular/core';
+import { BfStepComponent, BfStepsComponent } from '@bitforgehq/ui';
+
+/** A list continued after a paragraph: the second list starts at 3. */
+@Component({
+  selector: 'app-example-steps-continued',
+  imports: [BfStepComponent, BfStepsComponent],
+  template: `
+    <bf-steps>
+      <bf-step title="Open the admin console">Sign in with an administrator account.</bf-step>
+      <bf-step title="Add your domain">Enter it without https:// in front.</bf-step>
+    </bf-steps>
+    <p class="text-body text-text-muted my-4">The console now shows a TXT record for the domain.</p>
+    <bf-steps start="3">
+      <bf-step title="Add the TXT record">Paste it at your DNS provider.</bf-step>
+      <bf-step title="Verify the domain">Changes can take up to an hour to arrive.</bf-step>
+    </bf-steps>
+  `,
+})
+export class StepsContinuedExampleComponent {}
+```
+
+## Desktop
+
+Steps are not interactive: no hover, no pointer cursor and no focus stop of their own; only a link or button in a step's content takes focus, with its own focus ring. They render the same at every width: the marker column keeps its 24 px and the content wraps (a long word or URL breaks anywhere), so nothing scrolls sideways at 320 px. Put a code snippet that must not wrap in its own `overflow-x-auto` block.
+
+## Theming
+
+- Marker: `bg-primary-soft` / `text-primary-strong` (the tonal pair, ≥ 4.5:1 in both modes), `text-label-sm` bold in a 24 px circle (`size-6`, `rounded-full`); a `CanvasText` outline in forced colours.
+- Line: `border-border`, 1 px, hidden after the last step.
+- Title: `text-label` bold in `text`; content: `text-body` in `text-secondary`; `pb-6` between steps.
+
+## Accessibility
+
+`bf-steps` renders a `role="list"` container and each `bf-step` host is a `role="listitem"` directly inside it, so a screen reader announces the list and each step's position ("1 of 3"). The visible number is `aria-hidden`, so it is not read twice. A list with a `start` other than 1 also sets `aria-posinset` and `aria-setsize` on each step (the size counts the earlier steps too: steps 3 to 5 read "3 of 5"), so the announcement matches the number on screen. The title is text by default; give long steps `headingLevel` on `bf-step` so users can move between them by heading. A lone `bf-step` outside `bf-steps` claims no role.
+
+## Inputs
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `start` | `number` | `1` | The number of the first step, for a list continued from an earlier one. |
+
+## Slots
+
+- `default`: The steps, each a `bf-step`.
+
+## Notes
+
+### Do
+
+- Start each title with a verb and keep it to one instruction ("Install the app").
+- Put the details, a code to type or a link to open, in the step's content.
+
+### Don't
+
+- Don't use steps for a multi-page flow that tracks where the user is; that is a set of pages.
+- Don't number steps yourself in the title; the marker shows the number.
+
+## Migration notes
+
+### 0.4.0
+
+New `bf-steps`: numbered instructions a user follows in order ("Set up the app on your phone"),
+a `role="list"` of `bf-step` items whose markers are joined by a line. `start` (a number, 1 by
+default) continues a list; a continued list sets `aria-posinset` and `aria-setsize` on its steps
+so the announced position matches the visible number.
+
+---
+
 # bf-tab
 
 One tab bar destination with an icon, a label and an optional count badge
@@ -24213,7 +24609,7 @@ Use `bf-table` on a desktop page for records the user scans and compares column
 
 ## Columns and rows
 
-`columns` is an array of `BfTableColumn`: the row property `key`, the header `label`, `sortable` and `align`. A default cell shows the row's `key` property as text when it is a string, a number or a boolean, and is empty otherwise (`null`, `undefined`, an object): render a date or an object with a custom cell. `align: 'end'` lines the header and cells up at the inline end and sets tabular figures, for numbers and amounts.
+`columns` is an array of `BfTableColumn`: the row property `key`, the header `label`, `sortable` and `align`. A default cell shows the row's `key` property as text when it is a string, a number or a boolean, and is empty otherwise (`null`, `undefined`, an object): render a date or an object with a custom cell. `align: 'end'` lines the header and cells up at the inline end and sets tabular figures, for numbers and amounts; `align: 'center'` centres the header and each cell's control, for a column of toggles or checkboxes (see Toggle cells). `BfTableColumn.align` is a `BfTableColumnAlign`, the released `BfTableAlign` (`start`, `end`) plus `center`.
 
 `rowKey` returns the string that identifies a row in `selection` and keeps each row's DOM when the rows change. By default it reads the row's `id` (a string or a number), and falls back to the row's index when a row has none; pass `[rowKey]="byEmail"` when the key is another property.
 
@@ -24339,6 +24735,90 @@ export class TableCustomCellsExampleComponent {
 }
 ```
 
+## Toggle cells
+
+A settings matrix is a table of switches: rows are what the setting applies to (alert kinds), columns are the options (channels: Email, Push, Slack), and each cell is a `bf-toggle` from a `bfTableCell` template. Keep the row label as the first column, and give the toggle columns `align: 'center'`, which centres the header and the switch in each cell. A toggle in a cell shows no label of its own, so name each one after its column and row with `ariaLabel` (`[ariaLabel]="channel.label + ', ' + alert.label"`, "Push, New CVE"); a screen reader also announces the column header as it moves across. Write the change back from `(changed)` and save it right away, as for any toggle. With `stack="narrow"` (or `coarse` in the Capacitor shell) a phone shows each alert as a tile with the channel labels at the start and the toggles at the end, centred on their label line. In a test, `BfTableHarness.getCellHarness(row, 'Push', BfToggleHarness)` returns a cell's toggle.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfTableCellDirective,
+  BfTableComponent,
+  BfToggleComponent,
+  type BfTableColumn,
+} from '@bitforgehq/ui';
+
+type Channel = 'email' | 'push' | 'slack';
+
+interface AlertSetting {
+  id: string;
+  label: string;
+  email: boolean;
+  push: boolean;
+  slack: boolean;
+}
+
+const CHANNELS: readonly { key: Channel; label: string }[] = [
+  { key: 'email', label: 'Email' },
+  { key: 'push', label: 'Push' },
+  { key: 'slack', label: 'Slack' },
+];
+
+/**
+ * A settings matrix of toggle cells.
+ *
+ * Rows are alert kinds and columns are channels, each cell a `bf-toggle` named after its column
+ * and row ("Push, New CVE") with `ariaLabel`, in centred columns (`align: 'center'`). The row label
+ * stays the first column, and `stack="narrow"` turns each row into a tile with the toggles at its
+ * end in a narrow panel or on a phone.
+ */
+@Component({
+  selector: 'app-example-table-toggle-matrix',
+  imports: [BfTableComponent, BfTableCellDirective, BfToggleComponent],
+  template: `
+    <div class="flex w-152 max-w-full flex-col gap-3">
+      <bf-table label="Alert channels" stack="narrow" [rows]="alerts()" [columns]="columns">
+        @for (channel of channels; track channel.key) {
+          <ng-template [bfTableCell]="channel.key" [bfTableCellOf]="alerts()" let-alert>
+            <bf-toggle
+              [ariaLabel]="channel.label + ', ' + alert.label"
+              [checked]="alert[channel.key]"
+              (changed)="set(alert, channel.key, $event)"
+            />
+          </ng-template>
+        }
+      </bf-table>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TableToggleMatrixExampleComponent {
+  readonly channels = CHANNELS;
+  readonly columns: readonly BfTableColumn[] = [
+    { key: 'label', label: 'Alert' },
+    ...CHANNELS.map((channel): BfTableColumn => ({ ...channel, align: 'center' })),
+  ];
+  readonly alerts = signal<readonly AlertSetting[]>([
+    { id: 'critical', label: 'Critical finding', email: true, push: true, slack: true },
+    { id: 'cve', label: 'New CVE', email: true, push: false, slack: true },
+    { id: 'ci', label: 'Failed CI run', email: false, push: false, slack: true },
+    { id: 'digest', label: 'Weekly digest', email: true, push: false, slack: false },
+  ]);
+  readonly status = signal('No change yet.');
+
+  /** Writes one cell back; a real app saves the setting right away. */
+  set(alert: AlertSetting, channel: Channel, on: boolean): void {
+    this.alerts.update((rows) =>
+      rows.map((row) => (row.id === alert.id ? { ...row, [channel]: on } : row)),
+    );
+    const name = CHANNELS.find((c) => c.key === channel)?.label ?? channel;
+    this.status.set(`${name} for ${alert.label} turned ${on ? 'on' : 'off'}.`);
+  }
+}
+```
+
+Under a coarse pointer every toggle is a 44 px target inside its own cell (a row grows to fit it), and a cell's horizontal padding keeps neighbouring toggles apart, so no two hit areas overlap. A `sm` toggle (40 px wide) takes a 44 px width under touch as well. ArrowUp and ArrowDown move between the toggles of one column.
+
 ## Empty state
 
 While `rows` is empty the table shows one full-width row that holds the `empty` slot, such as a `bf-empty-state` with the action that creates the first record. The header stays, so the user still sees what the table holds.
@@ -24685,7 +25165,7 @@ Put the table on a `bf-card` (or another surface) yourself; it has no background
 
 ## Accessibility
 
-A native `table` with a visually hidden `caption` from `label`, `th scope="col"` headers and one `tr` per row. A sorted column's `th` carries `aria-sort="ascending"` or `"descending"`; the others carry none. A sortable header is a native `button` inside the `th`, so its name is the column label; the arrow is `aria-hidden`. The header checkbox is named by `selectAllLabel`, else `provideBfLabels()`'s `tableSelectAll` ("Select all rows"), and is mixed (`indeterminate`) while some rows are selected. Each row checkbox is named by the row's first data cell through `aria-labelledby`, so it reads as the row's title. The empty row's cell spans every column.
+A native `table` with a visually hidden `caption` from `label`, `th scope="col"` headers and one `tr` per row. A sorted column's `th` carries `aria-sort="ascending"` or `"descending"`; the others carry none. A sortable header is a native `button` inside the `th`, so its name is the column label; the arrow is `aria-hidden`. The header checkbox is named by `selectAllLabel`, else `provideBfLabels()`'s `tableSelectAll` ("Select all rows"), and is mixed (`indeterminate`) while some rows are selected. Each row checkbox is named by the row's first data cell through `aria-labelledby`, so it reads as the row's title. A control in a custom cell brings its own name: give a label-less one (a toggle in a settings matrix) `ariaLabel` from its column and row, such as "Email, Critical finding", so it is named the same in the table and in a stacked tile. The empty row's cell spans every column.
 
 A table that can stack (`stack` other than `never`) sets explicit `table`, `rowgroup`, `row`, `columnheader` and `cell` roles and names the table from its caption with `aria-labelledby`, because Safari and some screen readers drop a table's semantics once CSS changes its display; so a stacked table still reads as a table with its column headers. Stacked, the header row is visually hidden but stays in the accessibility tree; its sort buttons and checkbox are hidden (a plain label takes a sortable header's place), so no control is focusable where nobody can see it, and the bar's Select all checkbox and Sort by select replace them. A cell's visible label is CSS generated content with empty alternative text (`content: attr(data-label) / ""`, the `content-data-label` utility of `theme.css`), so a screen reader reads the column header once, not the label as well.
 
@@ -24754,6 +25234,7 @@ Selects or clears one row.
 ### Do
 
 - Give every table a `label`, and every sortable column a short header.
+- In a settings matrix, keep the row label as the first column, centre the toggle columns and name every toggle after its column and row.
 - Sort and filter the rows in a `computed()` from `sort` and your filters.
 - Use `stack="narrow"` for a table that may sit in a narrow column, or `stack="coarse"` in the Capacitor shell; otherwise render the rows as `bf-list-item`s below `md`.
 
@@ -24765,6 +25246,17 @@ Selects or clears one row.
 
 ## Migration notes
 
+### 0.4.0
+
+New: toggle cells for a settings matrix (rows of alert kinds, columns of channels, a `bf-toggle`
+in each cell), documented with the `table/toggle-matrix` example. `BfTableColumn.align` takes
+`'center'`: the header and each cell's control are centred, and while stacked the control sits at
+the tile's end, centred on its label line. New type `BfTableColumnAlign` (`BfTableAlign` plus
+`'center'`; `BfTableAlign` keeps its two members). A stacked cell of a start or end column keeps
+its baseline alignment. `@bitforgehq/ui/testing`: new `BfTableHarness.getCellHarness(row, column,
+query)` returns the harness of a control in one cell, and `selectRow()`, `getSelectedCount()`
+read only the selection column's checkboxes, never a checkbox or toggle in a custom cell.
+
 ### 0.3.3
 
 Fix: stacked rows (`stack="narrow"` and `stack="coarse"`) show their column labels again when the
@@ -26245,6 +26737,357 @@ New label keys `timeInputHour`, `timeInputMinute`, `timeInputSecond`, `timeInput
 
 ---
 
+# bf-timeline
+
+Dated list of events with who did what and when, on a vertical line
+
+`BfTimelineComponent` from `@bitforgehq/ui` · Data display · since 0.4.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfTimelineComponent, BfTimelineEventComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-timeline overview.
+ *
+ * Live demo of `bf-timeline`: the history of a security finding, newest first. A system event has
+ * no actor, the pull request is a link in the event text, the failed CI run is `danger` and the
+ * fix `success`.
+ */
+@Component({
+  selector: 'app-example-timeline-overview',
+  imports: [RouterLink, BfTimelineComponent, BfTimelineEventComponent],
+  template: `
+    <bf-timeline label="Finding history" class="max-w-xl">
+      <bf-timeline-event actor="Lena Meier" time="2026-10-28T15:40:00Z" tone="success">
+        Marked the finding as fixed
+      </bf-timeline-event>
+      <bf-timeline-event actor="CI" time="2026-10-28T13:05:00Z" tone="danger">
+        CI failed on the security scan
+      </bf-timeline-event>
+      <bf-timeline-event actor="Jonas Keller" time="2026-10-28T11:20:00Z" tone="primary">
+        Linked
+        <a routerLink="." fragment="links-in-events">PR #123</a>
+        to the finding
+      </bf-timeline-event>
+      <bf-timeline-event actor="Jonas Keller" time="2026-10-27T16:02:00Z">
+        Assigned the finding to Lena Meier
+      </bf-timeline-event>
+      <bf-timeline-event time="2026-10-27T08:14:00Z">
+        Created by the nightly dependency scan
+      </bf-timeline-event>
+    </bf-timeline>
+  `,
+})
+export class TimelineOverviewExampleComponent {}
+```
+
+## Overview
+
+A dated history of events, newest first or oldest first as the consumer orders them: who did
+what and when, each event a `bf-timeline-event` with a marker on a vertical line.
+
+A timeline shows the history of one thing as dated events: who did what, and when. Each event is a [`bf-timeline-event`](https://bitforge-ui.web.app/components/timeline-event) with a coloured marker on a vertical line, its text (which may link the objects it names), then the actor and the time. The timeline shows the events in the order you give them, newest first or oldest first; it never sorts. It works the same in a desktop web app, a narrow side panel and the Capacitor shell.
+
+## When to use
+
+Use `bf-timeline` for a record's history or an audit trail: a finding that was created, assigned, linked to a pull request and fixed; the changes in a CVE side panel; who changed a setting. Use [bf-list](https://bitforge-ui.web.app/components/list) instead for items the user opens or acts on, and for navigation; a timeline is not a stepper through a process either, nor a feed the user scrolls for new items. For the details of one record, use a [bf-description-list](https://bitforge-ui.web.app/components/description-list).
+
+## Events and tones
+
+`actor` names who did it (leave it empty for a system event), `time` says when (a `Date` or an ISO 8601 string), and the content is the event text. `tone` colours the marker: `neutral` (the default) for routine events, `primary` for the current or most important one, `success` (fixed, merged), `warning`, `danger` (CI failed, a regression) and `info`. The colour only supports the text, so say what happened in words ("CI failed"), never by the colour alone. The line runs from each marker to the next and ends at the last event.
+
+## Links in events
+
+The event text is the default slot, so the objects it names can be links: a pull request, a repository, a CVE. Put a plain `<a href>` (or `<a routerLink>`) inline in the text; the event styles every link in its text in `primary-text`, underlined, with a thicker underline on hover and the focus ring on keyboard focus. Keep the link text the object's name ("PR #123"), not "here".
+
+## Time format
+
+The time is formatted with `Intl.DateTimeFormat` in the app's `LOCALE_ID`: a medium date and a short time by default (`28 Oct 2026, 14:30` in `en-GB`, `28.10.2026, 14:30` in `de-CH`), in the browser's time zone. `timeFormat` on the timeline takes any `Intl.DateTimeFormatOptions` for all its events (`{ dateStyle: 'short' }`, or a `timeZone`), and `locale` overrides the language for one timeline. `timeText` on an event shows your own text in place of the formatted time, such as a relative "vor 2 Std."; the `time` element's `datetime` keeps the exact value. An empty or invalid `time` shows no time, and a locale or options the browser refuses fall back to the defaults, so a bad value never throws.
+
+## Audit trail
+
+An audit trail is actor-heavy: every event names a person or a bot. The `end` slot holds a small action for one event, such as a Show diff button: it sits at the inline end while the timeline is wide, and wraps under the text in a narrow side panel or on a phone (once the text would get narrower than 16rem). It takes no space while empty.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfTimelineComponent, BfTimelineEventComponent } from '@bitforgehq/ui';
+
+interface AuditEntry {
+  id: string;
+  actor: string;
+  action: string;
+  time: string;
+  ago: string;
+  diff: boolean;
+}
+
+const ENTRIES: readonly AuditEntry[] = [
+  {
+    id: 'severity',
+    actor: 'Lena Meier',
+    action: 'Raised the severity from Medium to High',
+    time: '2026-10-28T14:10:00Z',
+    ago: '2 hours ago',
+    diff: true,
+  },
+  {
+    id: 'policy',
+    actor: 'Policy bot',
+    action: 'Applied the "Critical CVEs block releases" policy',
+    time: '2026-10-28T09:30:00Z',
+    ago: '7 hours ago',
+    diff: true,
+  },
+  {
+    id: 'owner',
+    actor: 'Jonas Keller',
+    action: 'Set the owner to the Platform team',
+    time: '2026-10-27T16:45:00Z',
+    ago: 'Yesterday',
+    diff: false,
+  },
+];
+
+/**
+ * An audit trail with relative times and an action per event.
+ *
+ * Every event names its actor, `timeText` shows a relative time while `datetime` keeps the exact
+ * one, and the `end` slot holds a Show diff button: at the inline end while the timeline is wide,
+ * under the text in a narrow panel.
+ */
+@Component({
+  selector: 'app-example-timeline-audit',
+  imports: [BfButtonComponent, BfTimelineComponent, BfTimelineEventComponent],
+  template: `
+    <div class="flex max-w-xl flex-col gap-3">
+      <bf-timeline label="Audit trail">
+        @for (entry of entries; track entry.id) {
+          <bf-timeline-event [actor]="entry.actor" [time]="entry.time" [timeText]="entry.ago">
+            {{ entry.action }}
+            @if (entry.diff) {
+              <bf-button bfSlot="end" variant="outline" size="sm" (clicked)="showDiff(entry)">
+                Show diff
+              </bf-button>
+            }
+          </bf-timeline-event>
+        }
+      </bf-timeline>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TimelineAuditExampleComponent {
+  readonly entries = ENTRIES;
+  readonly status = signal('No diff open.');
+
+  /** A real app would open the change in a side panel. */
+  showDiff(entry: AuditEntry): void {
+    this.status.set(`Diff of "${entry.action}" by ${entry.actor}.`);
+  }
+}
+```
+
+## Desktop
+
+The timeline itself is not interactive: no hover, no pointer cursor, no focus stop. Only the links in the event text and the controls in an `end` slot take focus, with their own hover and focus ring. Its spacing does not follow `provideBfDefaults()`: the events keep one rhythm at every density, and it has no `size`. Inside `provideBfShell()` it renders and behaves the same; the `end` slot's buttons bring their own 44 px touch height.
+
+## Theming
+
+- Marker: a 10 px dot (`rounded-control`) in `text-subtle` (neutral), `primary`, `success`, `warning`, `danger` or `info`; `CanvasText` under forced colours.
+- Line: a 1 px `border` line from marker to marker.
+- Text: `text-body` in `text`; links `primary-text`, underlined, `ring` on keyboard focus. Meta line: `text-caption` in `text-muted`.
+- Spacing: 12 px between the marker and the text, 20 px between events.
+
+## Accessibility
+
+The timeline is a list (`role="list"`, named by `label` through `aria-label`) and each event inside it a `listitem`, so a screen reader announces the number of events and the position of each. An event outside a `bf-timeline` claims no role. The marker and the line are `aria-hidden`; the tone is decoration, so the text must say what happened. The time is a `time` element whose `datetime` is the ISO value, and the separator between actor and time is hidden from assistive technology. Links and `end` slot controls are native elements in reading order.
+
+## Inputs
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` | `''` | The list's accessible name, such as "History"; empty leaves the list unnamed (a visible heading above it already names the section). |
+| `timeFormat` | `Intl.DateTimeFormatOptions` | `TIMELINE_TIME_FORMAT` | `Intl.DateTimeFormat` options of every event's time; by default a medium date and a short time (`dateStyle: 'medium'`, `timeStyle: 'short'`). |
+| `locale` | `string` | `''` | BCP 47 locale of the times, such as `de-CH`; empty follows the app's `LOCALE_ID`. |
+
+## Slots
+
+- `default`: The events, each a `bf-timeline-event`, in the order to show them.
+
+## Notes
+
+### Do
+
+- Give the timeline a `label` when no visible heading names it, and keep one order (newest first) across the app.
+- Name the actor and the object in every event; link the object.
+
+### Don't
+
+- Don't use a timeline for navigation or for steps the user still has to take.
+- Don't carry meaning in the tone alone; say "CI failed", not just a red dot.
+
+## Migration notes
+
+### 0.4.0
+
+New: `bf-timeline`, a dated history of events (who did what, and when) for a record's history
+or an audit trail, in both shells. A `role="list"` named by `label`, in the order the consumer
+gives (it never sorts); each event's time is formatted with `Intl.DateTimeFormat` in the app's
+`LOCALE_ID` (`timeFormat`, default a medium date and a short time; `locale` overrides it).
+
+---
+
+# bf-timeline-event
+
+One timeline event with a coloured marker, its text, actor and time
+
+`BfTimelineEventComponent` from `@bitforgehq/ui` · Data display · since 0.4.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfTimelineComponent, BfTimelineEventComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-timeline-event overview.
+ *
+ * Live demo of `bf-timeline-event`: one event per tone in a `bf-timeline`, with and without an
+ * actor, one with a link in its text and one with a relative `timeText`.
+ */
+@Component({
+  selector: 'app-example-timeline-event-overview',
+  imports: [RouterLink, BfTimelineComponent, BfTimelineEventComponent],
+  template: `
+    <bf-timeline label="Event tones" class="max-w-xl">
+      <bf-timeline-event actor="Lena Meier" time="2026-10-28T15:40:00Z" tone="primary">
+        Opened
+        <a routerLink="/components/timeline" fragment="links-in-events">CVE-2026-1234</a>
+      </bf-timeline-event>
+      <bf-timeline-event actor="CI" time="2026-10-28T15:10:00Z" tone="success">
+        All checks passed
+      </bf-timeline-event>
+      <bf-timeline-event actor="Dependency bot" time="2026-10-28T14:00:00Z" tone="warning">
+        Found an outdated base image
+      </bf-timeline-event>
+      <bf-timeline-event actor="CI" time="2026-10-28T13:05:00Z" tone="danger">
+        CI failed on the security scan
+      </bf-timeline-event>
+      <bf-timeline-event time="2026-10-28T12:00:00Z" timeText="4 hours ago" tone="info">
+        A new advisory was published
+      </bf-timeline-event>
+      <bf-timeline-event actor="Jonas Keller" time="2026-10-27T16:02:00Z">
+        Assigned the finding to Lena Meier
+      </bf-timeline-event>
+    </bf-timeline>
+  `,
+})
+export class TimelineEventOverviewExampleComponent {}
+```
+
+## Overview
+
+One event of a `bf-timeline`: a marker coloured by `tone`, the event text (the default slot,
+which may hold links), then who did it (`actor`) and when (`time`, in a `time` element).
+
+One event of a [`bf-timeline`](https://bitforge-ui.web.app/components/timeline): a marker coloured by `tone`, the event text from the default slot, then a meta line with `actor` and `time`. Place events in a `bf-timeline`, which gives them the list semantics and the time format; the line between the markers ends at the last event.
+
+## When to use
+
+Use `bf-timeline-event` for each dated entry of a `bf-timeline`: a change, a comment, a CI run. Use [bf-list-item](https://bitforge-ui.web.app/components/list-item) instead for a row the user opens or acts on.
+
+## Basic usage
+
+`actor`, `time` (a `Date` or an ISO 8601 string) and `tone` are inputs; the text is the content and may hold links, which take the link style. `timeText` replaces the formatted time with your own text while the `datetime` keeps the exact value. `bfSlot="end"` holds a small action, at the inline end on a wide timeline and below the text on a narrow one.
+
+```ts
+import { Component } from '@angular/core';
+import { BfTimelineComponent, BfTimelineEventComponent } from '@bitforgehq/ui';
+
+/**
+ * An event's actor, time and tone.
+ *
+ * Two events of a CVE side panel: one by a person with an exact time, one by a bot with a relative
+ * `timeText` whose `datetime` keeps the exact value.
+ */
+@Component({
+  selector: 'app-example-timeline-event-basic',
+  imports: [BfTimelineComponent, BfTimelineEventComponent],
+  template: `
+    <bf-timeline label="CVE history" class="max-w-sm">
+      <bf-timeline-event actor="Lena Meier" time="2026-10-28T15:40:00Z" tone="warning">
+        Accepted the risk until the next release
+      </bf-timeline-event>
+      <bf-timeline-event
+        actor="Advisory bot"
+        time="2026-10-28T10:00:00Z"
+        timeText="6 hours ago"
+        tone="info"
+      >
+        Imported the advisory
+      </bf-timeline-event>
+    </bf-timeline>
+  `,
+})
+export class TimelineEventBasicExampleComponent {}
+```
+
+## Desktop
+
+An event has no hover and no focus stop of its own; only the links in its text and the controls in its `end` slot are interactive. It renders the same inside `provideBfShell()`.
+
+## Theming
+
+- Marker: `text-subtle`, `primary`, `success`, `warning`, `danger` or `info`; `CanvasText` under forced colours. Line: `border`.
+- Text `text-body` in `text`, links `primary-text`; meta line `text-caption` in `text-muted`.
+
+## Accessibility
+
+Inside a `bf-timeline` the event is a `listitem`; on its own it has no role. The marker is `aria-hidden`; the time is a `time` element with an ISO `datetime`, and the separator between actor and time is hidden from assistive technology.
+
+## Inputs
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `actor` | `string` | `''` | Who did it, such as a person or a bot; empty for a system event. |
+| `time` | `Date \| string \| null` | `null` | When it happened: a Date or an ISO 8601 string; empty or invalid shows no time. |
+| `timeText` | `string` | `''` | Shown in place of the formatted time, such as "vor 2 Std."; the `time` element's `datetime` keeps the exact value. |
+| `tone` | `BfTimelineTone` (`'neutral' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'info'`) | `'neutral'` | The marker's colour. |
+
+## Slots
+
+- `default`: The event text; links in it take the link style.
+- `end`: Content at the inline end on a wide timeline and below the text on a narrow one, such as a button.
+
+## Notes
+
+### Do
+
+- Write the text as what happened ("Assigned to Lena Meier"), and link the object it names.
+
+### Don't
+
+- Don't put more than one small action in the `end` slot; open the details elsewhere.
+
+## Migration notes
+
+### 0.4.0
+
+New: `bf-timeline-event`, one event of a `bf-timeline`: a 10 px marker coloured by `tone`
+(`neutral`, `primary`, `success`, `warning`, `danger`, `info`; new type `BfTimelineTone`) on a
+`border` line that ends at the last event, the event text in the default slot (links in it take
+the link style), then `actor` and `time` (a `Date` or an ISO 8601 string, in a `time` element;
+`timeText` shows a relative text while `datetime` keeps the exact value; an invalid time shows
+nothing). A `bfSlot="end"` action sits at the inline end, or under the text once the event is
+narrow.
+
+---
+
 # bf-toast
 
 Passive status pill with an optional action that never steals focus
@@ -26902,9 +27745,11 @@ export class ToggleListRowExampleComponent {
 }
 ```
 
+In a table of switches (a settings matrix: alert kinds by channel), each cell's toggle is named after its column and row with `ariaLabel`; see [bf-table](https://bitforge-ui.web.app/components/table)'s Toggle cells.
+
 ## Sizes
 
-`sm` (32 px row, 24×40 track), `md` (default, 40 px row, 28×48 track), `lg` (48 px row, 32×56 track). Unset, `size` follows `provideBfDefaults()`'s `controlSize`, `md` by default (`provideBfDefaults({ size: 'lg' })` enlarges every control of a Capacitor app; `{ size: 'sm' }` in a component's `providers` makes a dense sub-tree). Under a fine pointer the row is the hit area (32 px and up, above the 24 px of WCAG 2.5.8); under a coarse pointer (touch) `sm` and `md` rows grow to 44 px. The knob travels to the inline end, so it moves left under `dir="rtl"`.
+`sm` (32 px row, 24×40 track), `md` (default, 40 px row, 28×48 track), `lg` (48 px row, 32×56 track). Unset, `size` follows `provideBfDefaults()`'s `controlSize`, `md` by default (`provideBfDefaults({ size: 'lg' })` enlarges every control of a Capacitor app; `{ size: 'sm' }` in a component's `providers` makes a dense sub-tree). Under a fine pointer the row is the hit area (32 px and up, above the 24 px of WCAG 2.5.8); under a coarse pointer (touch) `sm` and `md` rows grow to 44 px, and a label-less `sm` switch (40 px wide) also takes a 44 px width, its track centred. The knob travels to the inline end, so it moves left under `dir="rtl"`.
 
 ```ts
 import { Component, signal } from '@angular/core';
@@ -27097,6 +27942,14 @@ Focuses the native switch; Signal Forms calls it from `focusBoundControl()`.
 
 ## Migration notes
 
+### 0.4.0
+
+A label-less `sm` toggle (a table cell) takes a 44 px min-width under a coarse pointer, its track
+centred, so its touch target is 44 × 44 px (it was 40 px wide). Nothing changes under a fine
+pointer or for `md` and `lg`. `@bitforgehq/ui/testing`: new `BfToggleHarness` (`with({ label })`
+by the switch's computed name, `getLabel()`, `isChecked()`, `isDisabled()`, `isReadonly()`,
+`toggle()`, `check()`, `uncheck()`, `getErrorText()`).
+
 ### 0.3.0
 
 New `ariaLabelledby` input: the id of the element that names the switch when no visible `label`
@@ -28140,7 +28993,9 @@ exposed: the heading stays a heading and the accessible name is the title alone.
 with the nearest card or row, which then draws the pointer, the hover and, while the action has
 keyboard focus, the focus ring; a card is never lit by the actions of rows nested in it. Give
 secondary controls inside the surface `class="relative z-1"` so they stay clickable above the
-stretched area.
+stretched area. When the surface marks a state that belongs in the name (an `unread` list
+row), the directive names the element `aria-labelledby="<state id> <own id>"`, so the link reads
+"Unread, Account", and restores the element's own `aria-labelledby` when the state goes.
 
 ```ts
 import { BfActionDirective } from '@bitforgehq/ui';
@@ -28376,6 +29231,36 @@ type BfBadgeAppearance = BfBadgeVariant | 'info'
 
 ---
 
+# BfBadgeEmphasis
+
+The two badge emphases, the soft tint or the solid strong fill
+
+Type from `@bitforgehq/ui` · since 0.4.0
+
+How loud a `bf-badge` is: `soft`, a pale tint with tinted text (the default), or `strong`, a
+solid fill with contrasting text for the one state that must stand out, such as "Critical".
+
+```ts
+import { type BfBadgeEmphasis } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfBadgeEmphasis = 'soft' | 'strong'
+```
+
+## Values
+
+- `soft`
+- `strong`
+
+## Used by
+
+- [bf-badge](../components/badge.md)
+
+---
+
 # BfBadgeVariant
 
 The five tones of a badge, from neutral counts to danger states
@@ -29421,6 +30306,7 @@ import { type BfLabels } from '@bitforgehq/ui';
 | `chartValue` | `string` | `'Value'` | The value column header of a bf-donut-chart's data table. |
 | `chartEmpty` | `string` | `'No data to show'` | bf-chart-card's text when it has no data and no `empty` slot. |
 | `chartError` | `string` | `'The data could not be loaded'` | bf-chart-card's text when its data failed to load and it has no `error` slot. |
+| `listItemUnread` | `string` | `'Unread'` | bf-list-item's visually hidden state text before the title of an `unread` row. |
 | `validation` | `BfValidationMessages` | required | Default error text per validator kind (see `BfValidationMessages`). |
 
 ## Uses
@@ -29982,6 +30868,37 @@ type BfStatVariant = 'plain' | 'card'
 
 ---
 
+# BfStepHeadingLevel
+
+The heading level a step title can take, two, three or four
+
+Type from `@bitforgehq/ui` · since 0.4.0
+
+The heading level of a `bf-step` title, for a guide whose steps hold enough content (screenshots,
+code) that a screen-reader user moves between them by heading.
+
+```ts
+import { type BfStepHeadingLevel } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfStepHeadingLevel = 2 | 3 | 4
+```
+
+## Values
+
+- `2`
+- `3`
+- `4`
+
+## Used by
+
+- [bf-step](../components/step.md)
+
+---
+
 # BfTabBarController
 
 The state a parent that drives a projected tab bar gives it to derive from
@@ -30116,7 +31033,7 @@ type BfTableAlign = 'start' | 'end'
 
 ## Used by
 
-- [BfTableColumn](bf-table-column.md)
+- [BfTableColumnAlign](bf-table-column-align.md)
 
 ---
 
@@ -30191,11 +31108,11 @@ import { type BfTableColumn } from '@bitforgehq/ui';
 | `key` | `string` | required | The row property the default cell shows; also the key a `bfTableCell` template names. |
 | `label` | `string` | required | The header text. |
 | `sortable` | `boolean` | `false` | Whether the header is a button that sets the table's `sort`. |
-| `align` | `BfTableAlign` (`'start' \| 'end'`) | `'start'` | The inline alignment of the header and cells; `end` also sets tabular figures. |
+| `align` | `BfTableColumnAlign` (`'start' \| 'end' \| 'center'`) | `'start'` | The inline alignment of the header and cells; `end` also sets tabular figures, `center` centres a cell's control (a toggle, a checkbox) in the column. |
 
 ## Uses
 
-- [BfTableAlign](bf-table-align.md)
+- [BfTableColumnAlign](bf-table-column-align.md)
 
 ## Used by
 
@@ -30203,6 +31120,42 @@ import { type BfTableColumn } from '@bitforgehq/ui';
 
 ---
 
+# BfTableColumnAlign
+
+The inline alignment of a table column: start, end, or centred for controls
+
+Type from `@bitforgehq/ui` · since 0.4.0
+
+Where a `bf-table` column lines up its header and cells: a `BfTableAlign`, or `center` for a
+column of controls such as the toggles of a settings matrix. A new type, so `Record`s over the
+released `BfTableAlign` keep compiling.
+
+```ts
+import { type BfTableColumnAlign } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfTableColumnAlign = BfTableAlign | 'center'
+```
+
+## Values
+
+- `start`
+- `end`
+- `center`
+
+## Uses
+
+- [BfTableAlign](bf-table-align.md)
+
+## Used by
+
+- [BfTableColumn](bf-table-column.md)
+
+---
+
 # BfTableRowKey
 
 Function that returns the unique string key of one table row
@@ -30358,6 +31311,40 @@ with signals.
 
 ---
 
+# BfTimelineTone
+
+The marker colour of a timeline event, neutral, primary or a status
+
+Type from `@bitforgehq/ui` · since 0.4.0
+
+The colour of a `bf-timeline-event`'s marker: `neutral` (the default), `primary`, or a status
+(`success`, `warning`, `danger`, `info`), such as danger for a failed CI run.
+
+```ts
+import { type BfTimelineTone } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfTimelineTone = 'neutral' | 'primary' | 'success' | 'warning' | 'danger' | 'info'
+```
+
+## Values
+
+- `neutral`
+- `primary`
+- `success`
+- `warning`
+- `danger`
+- `info`
+
+## Used by
+
+- [bf-timeline-event](../components/timeline-event.md)
+
+---
+
 # BfToggleLabelPosition
 
 Whether a toggle's label sits after or before its switch
@@ -30535,7 +31522,7 @@ every string. In a component's `providers` it covers that sub-tree's widgets and
 `dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,
 `timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,
 `chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,
-`chartValue`, `chartEmpty`, `chartError`, `validation`); the overlay services (`ok`, `cancel`,
+`chartValue`, `chartEmpty`, `chartError`, `listItemUnread`, `validation`); the overlay services (`ok`, `cancel`,
 `actions`, `sheet`, `modal`, `close`, `expand`, `collapse`, `sheetPosition`, `dialog`,
 `notifications`) are root singletons and pick it up only when the caller passes its injector:
 `open(…, { injector: inject(Injector) })`.
@@ -37477,6 +38464,18 @@ The text of one cell.
 | `row` | `number` | The row's position, from 0. |
 | `column` | `string` | The column's header text. |
 
+### `getCellHarness<T extends ComponentHarness>(row: number, column: string, query: HarnessQuery<T>): Promise<T>`
+
+A harness for a control in one cell, such as a `bf-toggle` of a settings matrix or a
+`bf-select` in a custom cell. Throws for an unknown row or column, or when the cell holds no
+matching control.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `row` | `number` | The row's position, from 0. |
+| `column` | `string` | The column's header text. |
+| `query` | `HarnessQuery<T>` | The harness type, or a predicate from its `with()`. |
+
 ### `sortBy(column: string): Promise<void>`
 
 Clicks a sortable column's header, as a user would: ascending first, then descending.
@@ -37620,6 +38619,64 @@ time, which closes it. Throws for a time the list does not hold (off the `step`)
 
 ---
 
+# BfToggleHarness
+
+Test harness for the toggle: reads its name and state and switches it
+
+Class from `@bitforgehq/ui/testing` · since 0.4.0
+
+Harness for `bf-toggle`. Its `label` filter matches the switch's name: the text of the elements
+`ariaLabelledby` names, else `ariaLabel`, else the visible label, so a label-less switch in a
+table cell or a list row is found the same way.
+
+```ts
+import { BfToggleHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfToggleHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The switch's name, as the browser computes it: the text of the elements `ariaLabelledby`
+names, else `ariaLabel`, else the visible label (the `label` text and the default slot).
+
+### `isChecked(): Promise<boolean>`
+
+Whether the switch is on.
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the switch is disabled.
+
+### `isReadonly(): Promise<boolean>`
+
+Whether the switch is read-only (`aria-readonly`): it shows its state but a click does nothing.
+
+### `toggle(): Promise<void>`
+
+Clicks the switch, as a user would, so it turns on or off. Throws while it is disabled (a
+user's click would do nothing); a read-only switch takes the click and stays as it is.
+
+### `check(): Promise<void>`
+
+Turns the switch on with a click; an on switch stays on. Throws while it is disabled.
+
+### `uncheck(): Promise<void>`
+
+Turns the switch off with a click; an off switch stays off. Throws while it is disabled.
+
+### `getErrorText(): Promise<string>`
+
+The error text under the switch.
+
+---
+
 # BfTooltipHarness
 
 Test harness for a tooltip: shows it, reads its text and whether it shows