@bitforgehq/ui 0.3.3 → 0.4.0

package/ai/REFERENCE.index.json

@@ -120,6 +120,13 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "Every badge tone, the five variants plus the informational info tone"
     },
+    {
+      "name": "BfBadgeEmphasis",
+      "slug": "bf-badge-emphasis",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "The two badge emphases, the soft tint or the solid strong fill"
+    },
     {
       "name": "BfBadgeVariant",
       "slug": "bf-badge-variant",
@@ -449,6 +456,13 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "The two stat surfaces, plain on its container or an outlined card tile"
     },
+    {
+      "name": "BfStepHeadingLevel",
+      "slug": "bf-step-heading-level",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "The heading level a step title can take, two, three or four"
+    },
     {
       "name": "BfTabBarController",
       "slug": "bf-tab-bar-controller",
@@ -491,6 +505,13 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "One table column with its row key, header label, sorting and alignment"
     },
+    {
+      "name": "BfTableColumnAlign",
+      "slug": "bf-table-column-align",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "The inline alignment of a table column: start, end, or centred for controls"
+    },
     {
       "name": "BfTableRowKey",
       "slug": "bf-table-row-key",
@@ -526,6 +547,13 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "The URLs a router-aware parent gives a tab bar to render its tabs as links"
     },
+    {
+      "name": "BfTimelineTone",
+      "slug": "bf-timeline-tone",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "The marker colour of a timeline event, neutral, primary or a status"
+    },
     {
       "name": "BfToggleLabelPosition",
       "slug": "bf-toggle-label-position",
@@ -1912,6 +1940,13 @@
       "entryPoint": "@bitforgehq/ui/testing",
       "summary": "Test harness for the time input: types a time or picks one from its list"
     },
+    {
+      "name": "BfToggleHarness",
+      "slug": "bf-toggle-harness",
+      "kind": "class",
+      "entryPoint": "@bitforgehq/ui/testing",
+      "summary": "Test harness for the toggle: reads its name and state and switches it"
+    },
     {
       "name": "BfTooltipHarness",
       "slug": "bf-tooltip-harness",

package/ai/REFERENCE.json

@@ -152,7 +152,7 @@
       "entryPoint": "@bitforgehq/ui",
       "file": "src/components/action/action.directive.ts",
       "summary": "Makes one link or button the click target of a whole card or list row",
-      "description": "The one interactive element of a `bf-card` or `bf-list-item` (the stretched-link pattern): put\nit on the `<a>` (navigation) or `<button>` (an action) that holds the card's heading text or the\nrow's title. Its `::after` stretches the hit area over the nearest positioned ancestor (the card\nbox, the row), so the whole surface is clickable while only the heading's link or button is\nexposed: the heading stays a heading and the accessible name is the title alone. It registers\nwith the nearest card or row, which then draws the pointer, the hover and, while the action has\nkeyboard focus, the focus ring; a card is never lit by the actions of rows nested in it. Give\nsecondary controls inside the surface `class=\"relative z-1\"` so they stay clickable above the\nstretched area.",
+      "description": "The one interactive element of a `bf-card` or `bf-list-item` (the stretched-link pattern): put\nit on the `<a>` (navigation) or `<button>` (an action) that holds the card's heading text or the\nrow's title. Its `::after` stretches the hit area over the nearest positioned ancestor (the card\nbox, the row), so the whole surface is clickable while only the heading's link or button is\nexposed: the heading stays a heading and the accessible name is the title alone. It registers\nwith the nearest card or row, which then draws the pointer, the hover and, while the action has\nkeyboard focus, the focus ring; a card is never lit by the actions of rows nested in it. Give\nsecondary controls inside the surface `class=\"relative z-1\"` so they stay clickable above the\nstretched area. When the surface marks a state that belongs in the name (an `unread` list\nrow), the directive names the element `aria-labelledby=\"<state id> <own id>\"`, so the link reads\n\"Unread, Account\", and restores the element's own `aria-labelledby` when the state goes.",
       "members": [],
       "methods": [],
       "slots": [],
@@ -280,6 +280,23 @@
       "signature": "type BfBadgeAppearance = BfBadgeVariant | 'info'",
       "values": ["neutral", "primary", "success", "warning", "danger", "info"]
     },
+    {
+      "name": "BfBadgeEmphasis",
+      "slug": "bf-badge-emphasis",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/badge/badge.component.ts",
+      "summary": "The two badge emphases, the soft tint or the solid strong fill",
+      "description": "How loud a `bf-badge` is: `soft`, a pale tint with tinted text (the default), or `strong`, a\nsolid fill with contrasting text for the one state that must stand out, such as \"Critical\".",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": [],
+      "usedBy": ["bf-badge-component"],
+      "since": "0.4.0",
+      "signature": "type BfBadgeEmphasis = 'soft' | 'strong'",
+      "values": ["soft", "strong"]
+    },
     {
       "name": "BfBadgeVariant",
       "slug": "bf-badge-variant",
@@ -1543,6 +1560,15 @@
           "readonly": true,
           "default": "'The data could not be loaded'"
         },
+        {
+          "name": "listItemUnread",
+          "kind": "property",
+          "type": "string",
+          "required": true,
+          "doc": "bf-list-item's visually hidden state text before the title of an `unread` row.",
+          "readonly": true,
+          "default": "'Unread'"
+        },
         {
           "name": "validation",
           "kind": "property",
@@ -1961,6 +1987,23 @@
       "signature": "type BfStatVariant = 'plain' | 'card'",
       "values": ["plain", "card"]
     },
+    {
+      "name": "BfStepHeadingLevel",
+      "slug": "bf-step-heading-level",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/steps/step.component.ts",
+      "summary": "The heading level a step title can take, two, three or four",
+      "description": "The heading level of a `bf-step` title, for a guide whose steps hold enough content (screenshots,\ncode) that a screen-reader user moves between them by heading.",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": [],
+      "usedBy": ["bf-step-component"],
+      "since": "0.4.0",
+      "signature": "type BfStepHeadingLevel = 2 | 3 | 4",
+      "values": ["2", "3", "4"]
+    },
     {
       "name": "BfTabBarController",
       "slug": "bf-tab-bar-controller",
@@ -2135,7 +2178,7 @@
       "methods": [],
       "slots": [],
       "references": [],
-      "usedBy": ["bf-table-column"],
+      "usedBy": ["bf-table-column-align"],
       "since": "0.3.1",
       "signature": "type BfTableAlign = 'start' | 'end'",
       "values": ["start", "end"]
@@ -2238,20 +2281,37 @@
         {
           "name": "align",
           "kind": "property",
-          "type": "BfTableAlign",
+          "type": "BfTableColumnAlign",
           "required": false,
-          "doc": "The inline alignment of the header and cells; `end` also sets tabular figures.",
+          "doc": "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.",
           "optional": true,
           "default": "'start'",
-          "expandedType": "'start' | 'end'"
+          "expandedType": "'start' | 'end' | 'center'"
         }
       ],
       "methods": [],
       "slots": [],
-      "references": ["bf-table-align"],
+      "references": ["bf-table-column-align"],
       "usedBy": ["bf-table-component"],
       "since": "0.3.1"
     },
+    {
+      "name": "BfTableColumnAlign",
+      "slug": "bf-table-column-align",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/table/table.component.ts",
+      "summary": "The inline alignment of a table column: start, end, or centred for controls",
+      "description": "Where a `bf-table` column lines up its header and cells: a `BfTableAlign`, or `center` for a\ncolumn of controls such as the toggles of a settings matrix. A new type, so `Record`s over the\nreleased `BfTableAlign` keep compiling.",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": ["bf-table-align"],
+      "usedBy": ["bf-table-column"],
+      "since": "0.4.0",
+      "signature": "type BfTableColumnAlign = BfTableAlign | 'center'",
+      "values": ["start", "end", "center"]
+    },
     {
       "name": "BfTableRowKey",
       "slug": "bf-table-row-key",
@@ -2377,6 +2437,23 @@
       "usedBy": ["bf-tab-bar-controller", "bf_tab_links"],
       "since": "0.3.0"
     },
+    {
+      "name": "BfTimelineTone",
+      "slug": "bf-timeline-tone",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/timeline/timeline-event.component.ts",
+      "summary": "The marker colour of a timeline event, neutral, primary or a status",
+      "description": "The colour of a `bf-timeline-event`'s marker: `neutral` (the default), `primary`, or a status\n(`success`, `warning`, `danger`, `info`), such as danger for a failed CI run.",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": [],
+      "usedBy": ["bf-timeline-event-component"],
+      "since": "0.4.0",
+      "signature": "type BfTimelineTone = 'neutral' | 'primary' | 'success' | 'warning' | 'danger' | 'info'",
+      "values": ["neutral", "primary", "success", "warning", "danger", "info"]
+    },
     {
       "name": "BfToggleLabelPosition",
       "slug": "bf-toggle-label-position",
@@ -2608,7 +2685,7 @@
       "entryPoint": "@bitforgehq/ui",
       "file": "src/config/labels.ts",
       "summary": "Replaces built-in strings for an app or a sub-tree, such as a translation",
-      "description": "Replaces built-in strings, merged over the parent's (validation merged key by key); a key left\nout or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers\nevery string. In a component's `providers` it covers that sub-tree's widgets and form controls\n(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,\n`tableSortNone`, `tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,\n`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,\n`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,\n`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,\n`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,\n`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,\n`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,\n`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,\n`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,\n`chartValue`, `chartEmpty`, `chartError`, `validation`); the overlay services (`ok`, `cancel`,\n`actions`, `sheet`, `modal`, `close`, `expand`, `collapse`, `sheetPosition`, `dialog`,\n`notifications`) are root singletons and pick it up only when the caller passes its injector:\n`open(…, { injector: inject(Injector) })`.",
+      "description": "Replaces built-in strings, merged over the parent's (validation merged key by key); a key left\nout or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers\nevery string. In a component's `providers` it covers that sub-tree's widgets and form controls\n(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,\n`tableSortNone`, `tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,\n`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,\n`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,\n`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,\n`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,\n`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,\n`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,\n`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,\n`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,\n`chartValue`, `chartEmpty`, `chartError`, `listItemUnread`, `validation`); the overlay services (`ok`, `cancel`,\n`actions`, `sheet`, `modal`, `close`, `expand`, `collapse`, `sheetPosition`, `dialog`,\n`notifications`) are root singletons and pick it up only when the caller passes its injector:\n`open(…, { injector: inject(Injector) })`.",
       "members": [],
       "methods": [
         {
@@ -2623,7 +2700,7 @@
             }
           ],
           "returns": "Provider",
-          "doc": "Replaces built-in strings, merged over the parent's (validation merged key by key); a key left\nout or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers\nevery string. In a component's `providers` it covers that sub-tree's widgets and form controls\n(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,\n`tableSortNone`, `tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,\n`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,\n`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,\n`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,\n`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,\n`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,\n`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,\n`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,\n`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,\n`chartValue`, `chartEmpty`, `chartError`, `validation`); the overlay services (`ok`, `cancel`,\n`actions`, `sheet`, `modal`, `close`, `expand`, `collapse`, `sheetPosition`, `dialog`,\n`notifications`) are root singletons and pick it up only when the caller passes its injector:\n`open(…, { injector: inject(Injector) })`."
+          "doc": "Replaces built-in strings, merged over the parent's (validation merged key by key); a key left\nout or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers\nevery string. In a component's `providers` it covers that sub-tree's widgets and form controls\n(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,\n`tableSortNone`, `tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,\n`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,\n`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,\n`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,\n`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,\n`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,\n`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,\n`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,\n`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,\n`chartValue`, `chartEmpty`, `chartError`, `listItemUnread`, `validation`); the overlay services (`ok`, `cancel`,\n`actions`, `sheet`, `modal`, `close`, `expand`, `collapse`, `sheetPosition`, `dialog`,\n`notifications`) are root singletons and pick it up only when the caller passes its injector:\n`open(…, { injector: inject(Injector) })`."
         }
       ],
       "slots": [],
@@ -9827,6 +9904,32 @@
           "returns": "Promise<string>",
           "doc": "The text of one cell."
         },
+        {
+          "name": "getCellHarness",
+          "signature": "getCellHarness<T extends ComponentHarness>(row: number, column: string, query: HarnessQuery<T>): Promise<T>",
+          "params": [
+            {
+              "name": "row",
+              "type": "number",
+              "optional": false,
+              "doc": "The row's position, from 0."
+            },
+            {
+              "name": "column",
+              "type": "string",
+              "optional": false,
+              "doc": "The column's header text."
+            },
+            {
+              "name": "query",
+              "type": "HarnessQuery<T>",
+              "optional": false,
+              "doc": "The harness type, or a predicate from its `with()`."
+            }
+          ],
+          "returns": "Promise<T>",
+          "doc": "A harness for a control in one cell, such as a `bf-toggle` of a settings matrix or a\n`bf-select` in a custom cell. Throws for an unknown row or column, or when the cell holds no\nmatching control."
+        },
         {
           "name": "sortBy",
           "signature": "sortBy(column: string): Promise<void>",
@@ -10016,6 +10119,79 @@
       "since": "0.3.1",
       "signature": "class BfTimeInputHarness extends ComponentHarness"
     },
+    {
+      "name": "BfToggleHarness",
+      "slug": "bf-toggle-harness",
+      "kind": "class",
+      "entryPoint": "@bitforgehq/ui/testing",
+      "file": "testing/harnesses/toggle.harness.ts",
+      "summary": "Test harness for the toggle: reads its name and state and switches it",
+      "description": "Harness for `bf-toggle`. Its `label` filter matches the switch's name: the text of the elements\n`ariaLabelledby` names, else `ariaLabel`, else the visible label, so a label-less switch in a\ntable cell or a list row is found the same way.",
+      "members": [],
+      "methods": [
+        {
+          "name": "getLabel",
+          "signature": "getLabel(): Promise<string>",
+          "params": [],
+          "returns": "Promise<string>",
+          "doc": "The switch's name, as the browser computes it: the text of the elements `ariaLabelledby`\nnames, else `ariaLabel`, else the visible label (the `label` text and the default slot)."
+        },
+        {
+          "name": "isChecked",
+          "signature": "isChecked(): Promise<boolean>",
+          "params": [],
+          "returns": "Promise<boolean>",
+          "doc": "Whether the switch is on."
+        },
+        {
+          "name": "isDisabled",
+          "signature": "isDisabled(): Promise<boolean>",
+          "params": [],
+          "returns": "Promise<boolean>",
+          "doc": "Whether the switch is disabled."
+        },
+        {
+          "name": "isReadonly",
+          "signature": "isReadonly(): Promise<boolean>",
+          "params": [],
+          "returns": "Promise<boolean>",
+          "doc": "Whether the switch is read-only (`aria-readonly`): it shows its state but a click does nothing."
+        },
+        {
+          "name": "toggle",
+          "signature": "toggle(): Promise<void>",
+          "params": [],
+          "returns": "Promise<void>",
+          "doc": "Clicks the switch, as a user would, so it turns on or off. Throws while it is disabled (a\nuser's click would do nothing); a read-only switch takes the click and stays as it is."
+        },
+        {
+          "name": "check",
+          "signature": "check(): Promise<void>",
+          "params": [],
+          "returns": "Promise<void>",
+          "doc": "Turns the switch on with a click; an on switch stays on. Throws while it is disabled."
+        },
+        {
+          "name": "uncheck",
+          "signature": "uncheck(): Promise<void>",
+          "params": [],
+          "returns": "Promise<void>",
+          "doc": "Turns the switch off with a click; an off switch stays off. Throws while it is disabled."
+        },
+        {
+          "name": "getErrorText",
+          "signature": "getErrorText(): Promise<string>",
+          "params": [],
+          "returns": "Promise<string>",
+          "doc": "The error text under the switch."
+        }
+      ],
+      "slots": [],
+      "references": [],
+      "usedBy": [],
+      "since": "0.4.0",
+      "signature": "class BfToggleHarness extends ComponentHarness"
+    },
     {
       "name": "BfTooltipHarness",
       "slug": "bf-tooltip-harness",

package/ai/UI_GUIDE.md

@@ -72,7 +72,7 @@ In `src/index.html`, give `<body>` the theme background and text colour, so the
 
 ### 7. Switch to dark mode
 
-Add the `dark` class to `<html>` (and remove it for light mode). Every token is redefined under `.dark`, and the theme sets `color-scheme`, so scrollbars and native controls follow too. Components need no `dark:` classes. To let users choose System, Light or Dark, add `provideBfColorScheme()` to the app providers: it sets the class, follows the OS and remembers the choice.
+Add the `dark` class to `<html>` (and remove it for light mode). Every token is redefined under `.dark`, and the theme sets `color-scheme`, so scrollbars and native controls follow too. Components need no `dark:` classes. To let users choose System, Light or Dark, add `provideBfColorScheme()` to the app providers: it sets the class, follows the OS and remembers the choice. For a near-black dark mode, add `@import '@bitforgehq/ui/dark-ink.css';` right after the theme import: the Ink preset, which changes dark mode only.
 
 ```html
 <html lang="en" class="dark">
@@ -123,6 +123,10 @@ pressed, soft and strong steps, `on-primary`, `primary-text`, `selected`, `ring`
 and a `.dark` block with each contrast pair's ratio, and exits 1 naming the pairs below their
 minimum and a shade that passes; paste its output, never hand-pick the steps. Example (the
 Meadow Sage green): `bunx bf-ui theme '#238652' --dark '#5cc48a'`.
+For a near-black dark mode, import the opt-in Ink preset right after the theme,
+`@import '@bitforgehq/ui/dark-ink.css';`: it redefines every dark token but the brand set under
+`.dark` (light mode and the default dark stay as they are), so a brand `.dark` block goes after
+it. Never copy its values into `.dark` by hand, and never put `dark:` classes on widgets for it.
 `--radius-control` (`9999px`, pills) reshapes buttons, chips, badges, segmented, the tab bar, the
 action bar and toggles at once:
 
@@ -143,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
 

package/ai/components/badge.md

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