@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/tabs.md

@@ -79,7 +79,7 @@ else the current tab route), the bar hides while the soft keyboard is open, and
 
 ## When to use
 
-Use `bf-tabs` for the tab root of a Capacitor app: one navigation stack per tab behind a floating [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar). Use [bf-stack-outlet](https://bitforge-ui.web.app/components/stack-outlet) instead for an app with one stack and no tabs, and a sidebar of links on desktop.
+Use `bf-tabs` for the tab root of a Capacitor app: one navigation stack per tab behind a floating [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar). Use [bf-stack-outlet](https://bitforge-ui.web.app/components/stack-outlet) instead for an app with one stack and no tabs, and on desktop a [bf-sidebar](https://bitforge-ui.web.app/components/sidebar) or a [bf-top-nav](https://bitforge-ui.web.app/components/top-nav) of `a[bfNavItem]` links over a plain `router-outlet`.
 
 ## Basic usage
 
@@ -194,7 +194,41 @@ fires no keyboard event).
 
 ## Desktop
 
-`bf-tabs` is part of the Capacitor shell (`provideBfShell()`). On a desktop web app put the top-level destinations in a sidebar or a top `nav` of links with `routerLinkActive`, and a plain `router-outlet`. Inside the shell under a mouse, the tab links take the `bf-tab` hover and focus styles.
+`bf-tabs` is part of the Capacitor shell (`provideBfShell()`). On a desktop web app, put the top-level destinations in a [bf-top-nav](https://bitforge-ui.web.app/components/top-nav) (a few sections) or a [bf-sidebar](https://bitforge-ui.web.app/components/sidebar) (more, in groups, collapsible to an icon rail) of `a[bfNavItem]` links, each with `routerLink`, `routerLinkActive` and `ariaCurrentWhenActive="page"`, above a plain `router-outlet`. The router sets `aria-current="page"` on the link of the current route and the item shows it. Drive both from one array of destinations: inside the shell the same array feeds the `bf-tab`s of a [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar), and below a breakpoint a [bf-menu-button](https://bitforge-ui.web.app/components/menu-button) of `a[bfMenuItem]` links (see bf-sidebar, Responsive). Wrap the desktop app in a [bf-app-frame](https://bitforge-ui.web.app/components/app-frame): it holds the sidebar from `md` up and, below it, a header bar with that menu button. Inside the shell under a mouse, the tab links take the `bf-tab` hover and focus styles.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavItemComponent, BfTopNavComponent } from '@bitforgehq/ui';
+
+/**
+ * The desktop replacement for tabs: a bf-top-nav.
+ *
+ * `a[bfNavItem]` links with `routerLinkActive` and `ariaCurrentWhenActive="page"`: the router marks
+ * the current page and the item shows it; a plain `router-outlet` below renders the page. With
+ * more sections, the same links go in a `bf-sidebar`.
+ */
+@Component({
+  selector: 'app-example-tabs-desktop-nav',
+  imports: [RouterLink, RouterLinkActive, BfNavItemComponent, BfTopNavComponent],
+  template: `
+    <bf-top-nav label="Navigation components">
+      @for (link of links; track link.path) {
+        <a bfNavItem [routerLink]="link.path" routerLinkActive ariaCurrentWhenActive="page">{{
+          link.label
+        }}</a>
+      }
+    </bf-top-nav>
+  `,
+})
+export class TabsDesktopNavExampleComponent {
+  protected readonly links: readonly { path: string; label: string }[] = [
+    { path: '/components/tabs', label: 'Tabs' },
+    { path: '/components/tab-bar', label: 'Tab bar' },
+    { path: '/components/stack-outlet', label: 'Stack outlet' },
+  ];
+}
+```
 
 ## Theming
 
@@ -331,6 +365,16 @@ content to the top.
 
 ## Migration notes
 
+### 0.3.2
+
+The `## Desktop` docs point at `bf-app-frame` for the frame around the desktop navigation.
+
+### 0.3.1
+
+The `## Desktop` docs name the desktop replacement: a `bf-top-nav` or `bf-sidebar` of
+`a[bfNavItem]` links with `routerLinkActive` and `ariaCurrentWhenActive="page"`, driven by the
+same destinations array as the shell's `bf-tab-bar`, with an example. No code change.
+
 ### 0.3.0
 
 **Breaking:** (ARIA contract) `bf-tabs` provides `BF_TAB_LINKS`, so the `bf-tab-bar` projected

package/ai/components/theme-menu-button.md

@@ -0,0 +1,182 @@
+# bf-theme-menu-button
+
+Menu button with System, Light and Dark radio items bound to the colour scheme
+
+`BfThemeMenuButtonComponent` from `@bitforgehq/ui/overlay` · Overlays · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { type BfColorScheme } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfThemeMenuButtonComponent } from '@bitforgehq/ui/overlay';
+import { Moon, Sun, SunMoon } from 'lucide';
+
+/**
+ * The bf-theme-menu-button overview.
+ *
+ * Live demo of `bf-theme-menu-button`: an outline "Theme" button and an icon-only text button
+ * share one choice; the icon follows it (sun, moon, or both for System) and the status line
+ * reports it. The demo binds a local signal, so the docs site keeps its own theme; an app binds
+ * `BfColorSchemeService.scheme` instead.
+ */
+@Component({
+  selector: 'app-example-theme-menu-button-overview',
+  imports: [BfIconComponent, BfThemeMenuButtonComponent],
+  template: `
+    <div class="flex flex-col gap-4">
+      <div class="flex flex-wrap items-center gap-2">
+        <bf-theme-menu-button placement="below-start" [(value)]="scheme">
+          <bf-icon bfSlot="icon" [icon]="icon()" />
+        </bf-theme-menu-button>
+        <bf-theme-menu-button iconOnly variant="text" [(value)]="scheme">
+          <bf-icon bfSlot="icon" [icon]="icon()" />
+        </bf-theme-menu-button>
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">
+        Theme: {{ scheme() }}
+      </p>
+    </div>
+  `,
+})
+export class ThemeMenuButtonOverviewExampleComponent {
+  /** Stands in for `BfColorSchemeService.scheme`. */
+  readonly scheme = signal<BfColorScheme>('system');
+  /** Sun for light, moon for dark, both while the choice follows the system. */
+  readonly icon = computed(() => ({ system: SunMoon, light: Sun, dark: Moon })[this.scheme()]);
+}
+```
+
+## Overview
+
+The colour scheme switch as a menu button, for a crowded top bar: a `bf-menu-button` whose menu
+holds System, Light and Dark as radio items, the current one marked with a dot. It holds a
+`BfColorScheme` and injects no service, so the app binds its own state, usually
+`BfColorSchemeService.scheme` (`BfPlatformService.theme` in a Capacitor app). The button shows
+`label` ("Theme") next to an optional icon, or only the icon with `iconOnly`.
+
+A theme menu button lets the user pick the app's colour scheme from a menu, from `@bitforgehq/ui/overlay` (needs `@angular/cdk`, no Capacitor). It is a `bf-menu-button` whose `bf-menu` holds System, Light and Dark as radio items, the current one marked with a dot. It holds a `BfColorScheme` and injects no service: the app binds its own state, normally `BfColorSchemeService.scheme`, with `[(value)]`. It works in both shells. Import `BfThemeMenuButtonComponent` from `@bitforgehq/ui/overlay`.
+
+## When to use
+
+Use `bf-theme-menu-button` in a crowded top bar or toolbar, where one button fits and three segments do not. Use [bf-theme-switch](https://bitforge-ui.web.app/components/theme-switch) instead on a settings page or in a header row with room, where the choice should stay visible. For a menu of other actions use [bf-menu-button](https://bitforge-ui.web.app/components/menu-button).
+
+## Icon only in a top bar
+
+`iconOnly` renders a round button holding only the icon, like `bf-icon-button`; `label` (else the `theme` label, "Theme") is then its accessible name. Project the icon in the `icon` slot: the component never picks one. Show the current look, a sun or a moon from `BfColorSchemeService.dark()`, so under System the icon says what the OS chose. Bind `[(value)]` to `BfColorSchemeService.scheme`: on desktop with `provideBfColorScheme()` in the app's providers, in a Capacitor app through `provideBfShell()` (where `BfPlatformService.theme` is the same signal). `changed` emits the new choice after a user pick; picking the current item again changes nothing.
+
+```ts
+import { Component, computed, inject } from '@angular/core';
+import { BfColorSchemeService } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfThemeMenuButtonComponent } from '@bitforgehq/ui/overlay';
+import { Moon, Sun } from 'lucide';
+
+/**
+ * An icon-only theme menu in a top bar, bound to the app's colour scheme.
+ *
+ * `[(value)]` binds `BfColorSchemeService.scheme`: with `provideBfColorScheme()` in the app's
+ * providers (desktop) or `provideBfShell()` (Capacitor), a pick sets the `dark` class on `<html>`
+ * and is stored. The icon follows `dark()`, so under System it shows what the OS chose.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-theme-menu-button-top-bar',
+  imports: [BfIconComponent, BfThemeMenuButtonComponent],
+  template: `
+    <header class="border-border flex items-center gap-2 border-b px-4 py-2">
+      <span class="text-heading me-auto">Grove</span>
+      <bf-theme-menu-button iconOnly variant="text" [(value)]="colorScheme.scheme">
+        <bf-icon bfSlot="icon" [icon]="icon()" />
+      </bf-theme-menu-button>
+    </header>
+  `,
+})
+export class ThemeMenuButtonTopBarExampleComponent {
+  // app.config.ts: providers: [provideBfColorScheme()]
+  protected readonly colorScheme = inject(BfColorSchemeService);
+  protected readonly icon = computed(() => (this.colorScheme.dark() ? Moon : Sun));
+}
+```
+
+## Label and variants
+
+Without `iconOnly` the button shows `label` (else "Theme") after the optional icon, with the menu-button caret. It shows the name, not the current choice: the choice is the checked item in the menu (and the icon, when you project one), and a fixed text keeps the button's width and accessible name steady. `variant` is `outline` (default), `text` or `tonal`; `size` is `sm` 32, `md` 40 or `lg` 48 px, unset following `provideBfDefaults()`'s `controlSize`. `placement` defaults to `'below-end'`, since the button usually sits at the end of a bar.
+
+## Labels
+
+The items read `themeSystem`, `themeLight` and `themeDark`; the button reads `theme`. Translate them with `provideBfLabels()`.
+
+## Testing
+
+The component renders a `bf-menu-button`, so `BfMenuButtonHarness` from `@bitforgehq/ui/testing` drives it: filter it by `label: 'Theme'`, open it with `getMenu()`, then pick with `clickItem('Dark')`; `isChecked()` on a `BfMenuItemHarness` reads the dot.
+
+## Desktop
+
+The button hovers, presses and shows the focus ring like `bf-menu-button` (and `bf-icon-button` with `iconOnly`): a darker fill or text on hover with the pointer cursor, the ring on keyboard focus only. A click opens the menu; menu rows take the muted fill on hover. Under a fine pointer the visible box is the hit area. In a dense top bar set `size="sm"`, or `provideBfDefaults({ size: 'sm' })` in a component's `providers` ([density guide](https://bitforge-ui.web.app/density)). Add `provideBfColorScheme()` to the desktop app's providers; the Capacitor shell needs nothing more than `provideBfShell()`.
+
+## Theming
+
+The button consumes `bf-menu-button`'s tokens (`bf-button`'s, or `bf-icon-button`'s with `iconOnly`); the menu consumes `bf-menu`'s: `surface` with a `border` and `shadow-floating`, rows `text` with a `surface-muted` hover and focus, and the radio dot in the row's text colour.
+
+## Accessibility
+
+- The button is a native `<button type="button">` with `aria-haspopup="menu"` and `aria-expanded`; its name is the visible label, or `label` (`aria-label`) with `iconOnly`. The menu it opens is named by it.
+- The three items are `role="menuitemradio"` with `aria-checked`, so a screen reader announces the current choice. The dot is drawn in CSS and adds nothing to the name.
+- Choosing an item closes the menu and returns focus to the button.
+- Hit area: at least 32 px, 44 px under a coarse pointer, as `bf-menu-button`.
+
+### Keyboard
+
+The keys inside the open menu are on the [bf-menu](https://bitforge-ui.web.app/components/menu#keyboard) page.
+
+| Key                                                        | Action                                                         |
+| ---------------------------------------------------------- | -------------------------------------------------------------- |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> / <kbd>ArrowDown</kbd> | Opens the menu and focuses System                              |
+| <kbd>ArrowUp</kbd>                                         | Opens the menu and focuses Dark                                |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>                        | In the open menu: picks the focused choice, closes the menu    |
+| <kbd>Escape</kbd>                                          | In the open menu: closes it without a change and returns focus |
+
+## Inputs
+
+| Name        | Type                                                                               | Default       | Description                                                                                                |
+| ----------- | ---------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
+| `label`     | `string`                                                                           | `''`          | The button's text, and its accessible name with `iconOnly`; empty falls back to the `theme` label.         |
+| `iconOnly`  | `boolean`                                                                          | `false`       | Square button holding only the projected icon, like `bf-icon-button`.                                      |
+| `variant`   | `BfMenuButtonVariant` (`'outline' \| 'text' \| 'tonal'`)                           | `'outline'`   | Visual style: outline (default), text, tonal.                                                              |
+| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)                        | `undefined`   | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default). |
+| `placement` | `BfMenuPlacement` (`'below-start' \| 'below-end' \| 'above-start' \| 'above-end'`) | `'below-end'` | Where the menu opens against the button; it flips when it would overflow.                                  |
+| `value`     | `BfColorScheme` (`'system' \| 'light' \| 'dark'`)                                  | `'system'`    | The colour scheme choice; bind it two-way, usually to `BfColorSchemeService.scheme`. Two-way: `[(value)]`. |
+
+## Outputs
+
+| Name      | Payload                                           | Description                                                          |
+| --------- | ------------------------------------------------- | -------------------------------------------------------------------- |
+| `changed` | `BfColorScheme` (`'system' \| 'light' \| 'dark'`) | Emitted with the new choice right after the user picks another item. |
+
+## Slots
+
+- `icon`: The icon before the label, or the whole button with `iconOnly` (a sun or a moon).
+
+## Notes
+
+### Do
+
+- Project a sun or moon icon that follows `BfColorSchemeService.dark()`.
+- Bind `[(value)]` to `BfColorSchemeService.scheme` (or `BfPlatformService.theme` in the shell).
+
+### Don't
+
+- Don't use it where there is room for three segments; use `bf-theme-switch`, which shows the choice without a click.
+- Don't import it into a root-entry widget; it lives in `@bitforgehq/ui/overlay` because it opens a `bf-menu`.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-theme-menu-button` in `@bitforgehq/ui/overlay`: a `bf-menu-button` whose menu holds
+System, Light and Dark as radio items, for a crowded top bar. Same `value` / `changed` / `label`
+as `bf-theme-switch`, plus `iconOnly`, `variant`, `size`, `placement` (default `'below-end'`) and
+an `icon` slot for the consumer's sun or moon.

package/ai/components/theme-switch.md

@@ -0,0 +1,170 @@
+# bf-theme-switch
+
+Segmented System, Light and Dark switch bound two-way to the app colour scheme
+
+`BfThemeSwitchComponent` from `@bitforgehq/ui` · Forms · since 0.3.1
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfThemeSwitchComponent, type BfColorScheme } from '@bitforgehq/ui';
+
+/**
+ * The bf-theme-switch overview.
+ *
+ * Live demo of `bf-theme-switch`: the default switch and a `sm` one share one choice, and the
+ * status line reports it. The demo binds a local signal, so the docs site keeps its own theme; an
+ * app binds `BfColorSchemeService.scheme` instead.
+ */
+@Component({
+  selector: 'app-example-theme-switch-overview',
+  imports: [BfThemeSwitchComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-theme-switch [(value)]="scheme" />
+      <bf-theme-switch size="sm" label="Theme (small)" [(value)]="scheme" />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">
+        Theme: {{ scheme() }}
+      </p>
+    </div>
+  `,
+})
+export class ThemeSwitchOverviewExampleComponent {
+  /** Stands in for `BfColorSchemeService.scheme`. */
+  readonly scheme = signal<BfColorScheme>('system');
+}
+```
+
+## Overview
+
+The colour scheme switch: System, Light and Dark as a three-option segmented control. It holds
+a `BfColorScheme` and injects no service, so the app binds its own state, usually
+`BfColorSchemeService.scheme` (`provideBfColorScheme()` on desktop, `provideBfShell()` in a
+Capacitor app, where `BfPlatformService.theme` is the same signal).
+
+A theme switch lets the user pick the app's colour scheme: System, Light or Dark, as a three-option `bf-segmented`. It holds a `BfColorScheme` and injects no service: the app binds its own state, normally `BfColorSchemeService.scheme`, with `[(value)]`. It works in both shells.
+
+## When to use
+
+Use `bf-theme-switch` on a settings page, or in a header row with room for three segments, so the choice stays visible. Use [bf-theme-menu-button](https://bitforge-ui.web.app/components/theme-menu-button) instead in a crowded top bar, where only one button fits. For a general view switch use [bf-segmented](https://bitforge-ui.web.app/components/segmented) itself.
+
+## Bind the colour scheme
+
+Bind `[(value)]` to `BfColorSchemeService.scheme` (from `@bitforgehq/ui`). On desktop, `provideBfColorScheme()` in the app's providers makes the service set the `dark` class on `<html>`, follow `prefers-color-scheme` under System and store the choice under `bf-theme`. In a Capacitor app `provideBfShell()` already does this, and `BfPlatformService.theme` (`@bitforgehq/ui/mobile`) is the same signal, so `[(value)]="platform.theme"` works too. `changed` emits the new choice after a user pick, never for a programmatic write.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfColorSchemeService, BfThemeSwitchComponent } from '@bitforgehq/ui';
+
+/**
+ * A theme switch bound to the app's colour scheme.
+ *
+ * `[(value)]` binds `BfColorSchemeService.scheme` itself: with `provideBfColorScheme()` in the
+ * app's providers (desktop) or `provideBfShell()` (Capacitor), a pick sets the `dark` class on
+ * `<html>` and is stored for the next visit.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-theme-switch-color-scheme',
+  imports: [BfThemeSwitchComponent],
+  template: `<bf-theme-switch [(value)]="colorScheme.scheme" />`,
+})
+export class ThemeSwitchColorSchemeExampleComponent {
+  // app.config.ts: providers: [provideBfColorScheme()]
+  protected readonly colorScheme = inject(BfColorSchemeService);
+}
+```
+
+## Full width
+
+`fullWidth` stretches the switch and shares the width between the segments, as on a phone settings screen. `size` sets the height step (`sm` 32, `md` 40, `lg` 48 px; unset follows `provideBfDefaults()`'s `controlSize`).
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfThemeSwitchComponent, type BfColorScheme } from '@bitforgehq/ui';
+
+/** A full-width theme switch under a visible caption, as on a phone settings screen. */
+@Component({
+  selector: 'app-example-theme-switch-full-width',
+  imports: [BfThemeSwitchComponent],
+  template: `
+    <div class="flex max-w-sm flex-col gap-2">
+      <!-- The group's own name repeats the caption, so the caption is hidden from readers. -->
+      <p aria-hidden="true" class="text-caption text-text-muted">Appearance</p>
+      <bf-theme-switch fullWidth label="Appearance" [(value)]="scheme" />
+    </div>
+  `,
+})
+export class ThemeSwitchFullWidthExampleComponent {
+  protected readonly scheme = signal<BfColorScheme>('light');
+}
+```
+
+## Labels
+
+The segments read `themeSystem`, `themeLight` and `themeDark`, and the group's accessible name is `label`, else `theme` ("Theme"); translate them with `provideBfLabels()`. The name is not shown: put a visible caption beside it when the page needs one.
+
+## Testing
+
+The switch renders a `bf-segmented`, so `BfSegmentedHarness` from `@bitforgehq/ui/testing` drives it: filter it by `label: 'Theme'`, pick with `select('Dark')` and read the choice with `getSelectedLabel()`.
+
+## Desktop
+
+The segments hover, press and show the focus ring like `bf-segmented`'s: a darker label on hover with the pointer cursor, the ring on keyboard focus only. Under a fine pointer each segment is its own hit area. In a dense header row set `size="sm"`, or `provideBfDefaults({ size: 'sm' })` in a component's `providers` ([density guide](https://bitforge-ui.web.app/density)). Add `provideBfColorScheme()` to the desktop app's providers; the Capacitor shell needs nothing more than `provideBfShell()`.
+
+## Theming
+
+The switch is a `bf-segmented` and consumes its tokens: track `surface-sunken`, active segment `surface` / `text` with `shadow-segment` and a 1.5 px inset `primary-strong` outline, inactive `text-muted`, focus `ring`, shape `rounded-control`.
+
+## Accessibility
+
+A `bf-segmented`: `role="radiogroup"` named by `label` (else the `theme` label), each choice a `<button role="radio">` with `aria-checked`, one tab stop on the selected segment. A visible caption next to it should repeat the name or carry `aria-hidden="true"`, so readers do not hear it twice. Under a coarse pointer each segment's hit area reaches 44 px.
+
+### Keyboard
+
+| Key                                              | Action                                                   |
+| ------------------------------------------------ | -------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves focus into and out of the switch (one tab stop)    |
+| <kbd>ArrowRight</kbd> / <kbd>ArrowDown</kbd>     | Selects and focuses the next choice, wrapping at the end |
+| <kbd>ArrowLeft</kbd> / <kbd>ArrowUp</kbd>        | Selects and focuses the previous choice, wrapping        |
+| <kbd>Home</kbd> / <kbd>End</kbd>                 | Selects System / Dark                                    |
+| <kbd>Space</kbd> / <kbd>Enter</kbd>              | Selects the focused choice                               |
+
+## Inputs
+
+| Name        | Type                                                        | Default     | Description                                                                                                                       |
+| ----------- | ----------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `label`     | `string`                                                    | `''`        | Accessible name of the switch (not shown); empty falls back to the `theme` label.                                                 |
+| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                        |
+| `fullWidth` | `boolean`                                                   | `false`     | Stretch the switch and share the width between the three segments.                                                                |
+| `value`     | `BfColorScheme` (`'system' \| 'light' \| 'dark'`)           | `'system'`  | The colour scheme choice; bind it two-way, usually to `BfColorSchemeService.scheme`, or with `[formField]`. Two-way: `[(value)]`. |
+
+## Outputs
+
+| Name      | Payload                                           | Description                                                             |
+| --------- | ------------------------------------------------- | ----------------------------------------------------------------------- |
+| `changed` | `BfColorScheme` (`'system' \| 'light' \| 'dark'`) | Emitted with the new choice right after the user picks another segment. |
+
+## Notes
+
+### Do
+
+- Bind `[(value)]` to `BfColorSchemeService.scheme` (or `BfPlatformService.theme` in the shell), so the switch and the page agree.
+- Keep System as an option: it follows the OS until the user decides.
+
+### Don't
+
+- Don't call `scheme.set()` from `(changed)` as well as binding `[(value)]`; the two-way binding already writes it.
+- Don't squeeze the switch into a crowded top bar; use `bf-theme-menu-button` there.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-theme-switch` in `@bitforgehq/ui`: System, Light and Dark as a three-option
+`bf-segmented`, holding a `BfColorScheme` in `value` (`[(value)]`, `changed`), with `label`,
+`size` and `fullWidth`. It injects no service; bind it to `BfColorSchemeService.scheme`
+(`BfPlatformService.theme` in the shell). New `BfLabels` keys `theme`, `themeSystem`, `themeLight`
+and `themeDark`.