@bitforgehq/ui 0.3.1 → 0.3.2

package/llms-full.txt

@@ -117,7 +117,12 @@ the widgets style their native controls themselves.
 Optional per-app overrides go after the import. A brand colour is a set: override
 `--color-primary` together with `--color-primary-text` (primary as text, ≥ 4.5:1 on `bg` and
 `surface`) and the rest of the `--color-primary-*` tokens, in `@theme` and in `.dark`; the docs
-site's theme configurator derives the whole contrast-checked set from one colour.
+site's theme configurator derives the whole contrast-checked set from one colour. From a
+terminal, `bunx bf-ui theme '<hex>' [--dark '<hex>']` prints the set (`primary`, its hover,
+pressed, soft and strong steps, `on-primary`, `primary-text`, `selected`, `ring`) as a `@theme`
+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'`.
 `--radius-control` (`9999px`, pills) reshapes buttons, chips, badges, segmented, the tab bar, the
 action bar and toggles at once:
 
@@ -138,16 +143,17 @@ Render library components only in the browser, for example in a `@defer` block o
 route. Support will be decided before 1.0.
 
 The one server-side check is a render smoke, not a support test: the library repository's
-`tools/ssr-smoke.ts` renders 42 fixtures with `renderApplication()` (every root widget, `bf-icon`,
+`tools/ssr-smoke.ts` renders 43 fixtures with `renderApplication()` (every root widget, `bf-icon`,
 `bf-number-input`, a `/charts` line chart, a `/mobile` page with `provideBfShell()`, `bf-page`,
 `bf-header` and `bf-content`, `bf-tabs` with `bf-stack-outlet` under the router, and an `/overlay`
-dialog), and all of them render without an error. 27 of them render identically twice. The other 15
+dialog), and all of them render without an error. 27 of them render identically twice. The other 16
 number their ids differently on every render, from a module-level counter, so they could not
-hydrate: `bf-calendar`, `bf-checkbox`, `bf-input`, `bf-radio-group`, `bf-segmented`, `bf-select`,
-`bf-sidebar`, `bf-tab-group`, `bf-table`, `bf-textarea`, `bf-theme-switch`, `bf-toggle`,
-`bf-line-chart`, `bf-number-input` and the `/overlay` dialog. Hydration itself is still not
-supported or tested, and more stands in its way: `/mobile` writes to `<html>` and adds a keyboard
-probe to `<body>`, and an `/overlay` dialog renders outside the app root and marks it inert.
+hydrate: `bf-app-frame`, `bf-calendar`, `bf-checkbox`, `bf-input`, `bf-radio-group`, `bf-segmented`,
+`bf-select`, `bf-sidebar`, `bf-tab-group`, `bf-table`, `bf-textarea`, `bf-theme-switch`,
+`bf-toggle`, `bf-line-chart`, `bf-number-input` and the `/overlay` dialog. Hydration itself is still
+not supported or tested, and more stands in its way: `/mobile` writes to `<html>` and adds a
+keyboard probe to `<body>`, and an `/overlay` dialog renders outside the app root and marks it
+inert.
 
 ## Keeping this guide in sync
 
@@ -335,8 +341,19 @@ protected readonly colorScheme = inject(BfColorSchemeService);
 `bf-tabs`, `bf-back-button` and `bf-header` are Capacitor shell parts. A desktop web app (no
 `provideBfShell()`) uses their desktop counterparts from `@bitforgehq/ui`:
 
-- **Navigation:** `bf-sidebar` (groups in `bf-nav-group`, `[(collapsed)]` for an icon rail; the
-  app owns the toggle button) or `bf-top-nav` for a few sections, holding
+- **App frame:** wrap the whole app in `<bf-app-frame>` (never build the frame by hand): the
+  `bf-sidebar` in `bfSlot="sidebar"` (sticky, full height, from `md` up), and below the
+  breakpoint a header bar with `bfSlot="brand"`, `bfSlot="menu"` (a `bf-menu-button` of
+  `a[bfMenuItem]` links from the same destinations array) and `bfSlot="actions"` (the theme
+  menu); the router outlet is the content. It brings the skip link and the focusable main
+  landmark; `breakpoint` and `contentWidth` adjust it. Desktop only: never inside
+  `provideBfShell()`.
+- **Sidebar collapse:** `<bf-sidebar-toggle>` (`/overlay`, icons in `bfSlot="collapse-icon"` and
+  `bfSlot="expand-icon"`) in the sidebar footer beside the icon-only theme menu; with
+  `provideBfSidebarState()` bind `[(collapsed)]="sidebarState.collapsed"`
+  (`BfSidebarStateService`) so the choice is remembered.
+- **Navigation:** `bf-sidebar` (groups in `bf-nav-group`, `[(collapsed)]` for an icon rail) or
+  `bf-top-nav` for a few sections, holding
   `<a bfNavItem routerLink="…" routerLinkActive ariaCurrentWhenActive="page">` links with an icon
   in `bfSlot="icon"` and an optional `[badge]` count. The router sets `aria-current="page"` and
   the item shows it. Drive the sidebar, a below-`md` `bf-menu-button` of `a[bfMenuItem]` links and,
@@ -354,8 +371,9 @@ protected readonly colorScheme = inject(BfColorSchemeService);
   controls default to `sm`, and `status` is a polite live region for the result count.
 - **Table:** `<bf-table [rows] [columns] [(sort)] selectable [(selection)]>` with
   `ng-template[bfTableCell]` for rich cells and `bfSlot="empty"` for the empty state; the app
-  sorts the rows in a `computed()`, and a selection shows a `bf-action-bar`. Below `md` or on a
-  coarse pointer render the same rows as `bf-list-item`s.
+  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.
 - **Details:** `bf-description-list` of `div[bfDescriptionItem]` label/value pairs, and `bf-stat`
   figure tiles in a grid; both work in both shells.
 - **Cards in a grid:** the grid stretches each `bf-card` and its `bfSlot="footer"` sits on the
@@ -384,6 +402,12 @@ protected readonly colorScheme = inject(BfColorSchemeService);
   `bf-sparkline` inside a `bf-chart-card` (title, period slot, loading, empty and error states),
   themed by the `chart-1`…`chart-8` tokens. Every chart takes a `label` and offers its data as a
   table.
+- **Surfaces:** one surface style per level. A raised `bf-card` holds sunken tiles
+  (`bf-stat variant="tile"`), never an outlined surface (`variant="card"` or a `flat` card) inside
+  a raised one; next to raised cards on a dashboard, use raised cards.
+- **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.
 
 ## Overlays (`@bitforgehq/ui/overlay`)
 
@@ -1230,6 +1254,7 @@ notes.
 
 | Component | Entry point | Purpose |
 | --- | --- | --- |
+| `bf-app-frame` | `@bitforgehq/ui` | Desktop app frame with skip link, sticky sidebar, narrow header and main content |
 | `bf-back-button` | `@bitforgehq/ui/mobile` | Header back button that pops the page stack or falls back to a default route |
 | `bf-breadcrumb` | `@bitforgehq/ui` | Desktop breadcrumb trail of links to the current page, with optional collapsing |
 | `li[bfBreadcrumbItem]` | `@bitforgehq/ui` | One level of a breadcrumb trail: a link, or the current page as text |
@@ -1242,6 +1267,7 @@ notes.
 | `bf-pagination` | `@bitforgehq/ui` | Previous, next and numbered page buttons for a long list or table |
 | `bf-refresher` | `@bitforgehq/ui/mobile` | Pull-to-refresh indicator with haptic feedback, native iOS bounce and an Android-style pull |
 | `bf-sidebar` | `@bitforgehq/ui` | Vertical app navigation with brand, grouped links, footer and an icon rail mode |
+| `bf-sidebar-toggle` | `@bitforgehq/ui/overlay` | Icon button inside a sidebar that collapses it to an icon rail and back |
 | `bf-stack-outlet` | `@bitforgehq/ui/mobile` | Router outlet keeping a live page stack with slide transitions and iOS swipe back |
 | `bf-tab` | `@bitforgehq/ui` | One tab bar destination with an icon, a label and an optional count badge |
 | `bf-tab-bar` | `@bitforgehq/ui` | Floating pill tab bar for mobile apps with arrow-key selection and count badges |
@@ -2920,6 +2946,337 @@ focusable content. `provideBfShell()` now also provides `BfAlertDialogService`.
 
 ---
 
+# bf-app-frame
+
+Desktop app frame with skip link, sticky sidebar, narrow header and main content
+
+`BfAppFrameComponent` from `@bitforgehq/ui` · Navigation · since 0.3.2
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import {
+  BfAppFrameComponent,
+  BfIconButtonComponent,
+  BfNavItemComponent,
+  BfSidebarComponent,
+} from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+import { Bell, type IconNode, Layers, Menu, PanelLeft, PanelTop } from 'lucide';
+
+/** One top-level destination of the app, shared by the sidebar and the narrow-screen menu. */
+interface Destination {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+}
+
+/**
+ * The bf-app-frame overview.
+ *
+ * Live demo of `bf-app-frame` in a box of fixed height: one destinations array drives the
+ * `bf-sidebar` (from `md` up) and the narrow header's `bf-menu-button`; the header also holds the
+ * brand and a notifications action. Tab into the frame to reveal its skip link; Enter moves focus
+ * to the content. The result line reports it.
+ */
+@Component({
+  selector: 'app-example-app-frame-overview',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfAppFrameComponent,
+    BfIconButtonComponent,
+    BfIconComponent,
+    BfMenuButtonComponent,
+    BfMenuComponent,
+    BfMenuItemDirective,
+    BfNavItemComponent,
+    BfSidebarComponent,
+  ],
+  template: `
+    <!-- In an app the frame is the root of the page; here a fixed height stands in for the
+         viewport, so the sidebar and the header bar stick inside the box. -->
+    <div (focusin)="onFocus($event)">
+      <bf-app-frame
+        mainId="app-frame-demo-content"
+        class="border-border rounded-card h-96 overflow-auto border"
+      >
+        <bf-sidebar bfSlot="sidebar" label="App frame demo">
+          <span bfSlot="header" class="text-heading ps-3">Atlas</span>
+          @for (destination of destinations; track destination.path) {
+            <a
+              bfNavItem
+              [routerLink]="destination.path"
+              routerLinkActive
+              ariaCurrentWhenActive="page"
+            >
+              <bf-icon bfSlot="icon" [icon]="destination.icon" />
+              {{ destination.label }}
+            </a>
+          }
+        </bf-sidebar>
+
+        <span bfSlot="brand" class="text-heading">Atlas</span>
+        <bf-menu-button bfSlot="menu" variant="text" [menu]="navMenu">
+          <bf-icon bfSlot="icon-start" [icon]="menu" />
+          Sections
+        </bf-menu-button>
+        <bf-icon-button
+          bfSlot="actions"
+          variant="text"
+          label="Notifications"
+          (clicked)="status.set('Notifications opened.')"
+        >
+          <bf-icon [icon]="bell" />
+        </bf-icon-button>
+
+        <div class="flex flex-col gap-3">
+          <h2 class="text-title">Inbox</h2>
+          <p class="text-body text-text-muted max-w-prose">
+            The page sits in the content column, beside the sidebar from the md breakpoint up and
+            under the header bar below it.
+          </p>
+          <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+          @for (row of rows; track row) {
+            <div class="bg-surface rounded-tile text-body p-4">{{ row }}</div>
+          }
+        </div>
+      </bf-app-frame>
+    </div>
+
+    <ng-template #navMenu>
+      <bf-menu>
+        @for (destination of destinations; track destination.path) {
+          <a
+            bfMenuItem
+            [routerLink]="destination.path"
+            routerLinkActive
+            ariaCurrentWhenActive="page"
+            >{{ destination.label }}</a
+          >
+        }
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class AppFrameOverviewExampleComponent {
+  /** In an app, derive this from the route config, so a new route appears on every surface. */
+  protected readonly destinations: readonly Destination[] = [
+    { path: '/components/app-frame', label: 'App frame', icon: PanelLeft },
+    { path: '/components/sidebar', label: 'Sidebar', icon: PanelTop },
+    { path: '/components/menu-button', label: 'Menu button', icon: Layers },
+  ];
+  protected readonly rows = [
+    'Review the brand brief',
+    'Plan the launch',
+    'Write the release notes',
+  ];
+  protected readonly bell = Bell;
+  protected readonly menu = Menu;
+  readonly status = signal('Tab into the frame to reveal the skip link.');
+
+  /** Reports when focus lands on the content, as the skip link moves it there. */
+  protected onFocus(event: FocusEvent): void {
+    if (event.target instanceof HTMLElement && event.target.id === 'app-frame-demo-content') {
+      this.status.set('Skipped to the content.');
+    }
+  }
+}
+```
+
+## Overview
+
+The frame of a desktop web app: a skip link, a sticky full-height sidebar column from the
+breakpoint up, a header bar with the brand, the narrow-screen menu and actions below it, and
+the `main` landmark with a content column of a set maximum width.
+
+The frame around a desktop web app's pages: a skip link, a [`bf-sidebar`](https://bitforge-ui.web.app/components/sidebar) column that sticks to the viewport at its full height from a breakpoint up, a header bar below the breakpoint with the brand, the narrow-screen [`bf-menu-button`](https://bitforge-ui.web.app/components/menu-button) and end actions, and the `main` landmark with a content column of a set maximum width. It replaces the `hidden md:flex` sidebar, the `md:hidden` menu button and the padded `main` an app would otherwise build by hand. The frame imports no overlay and never reads the router: the menu is your own `bf-menu-button`, projected into a slot.
+
+## When to use
+
+Use `bf-app-frame` once, at the root of a desktop web app whose top-level destinations live in a `bf-sidebar`, with your `router-outlet` as its content. Use [bf-top-nav](https://bitforge-ui.web.app/components/top-nav) in your own header instead for an app with a handful of sections and no sidebar. In the Capacitor shell use [bf-tabs](https://bitforge-ui.web.app/components/tabs) with a [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar), and a [bf-page](https://bitforge-ui.web.app/components/page) with a [bf-header](https://bitforge-ui.web.app/components/header) per page, instead; never put the frame inside [`provideBfShell()`](https://bitforge-ui.web.app/api/provide-bf-shell).
+
+## Slots and layout
+
+Put the `bf-sidebar` in `bfSlot="sidebar"`, the app's name or logo in `bfSlot="brand"`, the narrow-screen `bf-menu-button` of `a[bfMenuItem]` router links in `bfSlot="menu"` and end actions (the theme menu, the account) in `bfSlot="actions"`; everything else is the page. From the breakpoint up the sidebar column sits at the inline start, `sticky top-0` and `h-dvh` tall, and the `bf-sidebar` inside fills it and scrolls its own destinations; the header bar is hidden. Below it the sidebar column is hidden and the header bar (`surface`, a bottom border, sticky at the top) shows the brand at the start, then the menu, and the actions at the end. Keep the brand in the sidebar's own `header` slot too, for the wide layout.
+
+## Breakpoint and content width
+
+`breakpoint` (`BfAppFrameBreakpoint`) is the viewport width from which the sidebar shows: `md` (768 px, the default) or `lg` (1024 px) for a wide sidebar that would crowd a tablet. `contentWidth` (`BfAppFrameContentWidth`) caps the content column, centred in the space beside the sidebar: `md` 48rem, `lg` 64rem, `xl` 80rem (the default) and `full` for no limit. The content is padded 16 px below the breakpoint and 32 px from it up.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterOutlet } from '@angular/router';
+import { BfAppFrameComponent, BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+
+/**
+ * A narrow reading column, with the sidebar from lg up.
+ *
+ * A settings or reading app keeps its lines short: `contentWidth="md"` caps the content column at
+ * 48rem (`lg` 64rem, the default `xl` 80rem, `full` no limit), and `breakpoint="lg"` keeps the
+ * header bar up to 1024 px, for a sidebar that would crowd a tablet. `mainId` names the main
+ * landmark, the skip link's target.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-app-frame-content-width',
+  imports: [RouterOutlet, BfAppFrameComponent, BfNavItemComponent, BfSidebarComponent],
+  template: `
+    <bf-app-frame contentWidth="md" breakpoint="lg" mainId="content">
+      <bf-sidebar bfSlot="sidebar" label="Settings">
+        <a bfNavItem href="/account">Account</a>
+        <a bfNavItem href="/billing">Billing</a>
+      </bf-sidebar>
+      <span bfSlot="brand" class="text-heading">Settings</span>
+      <router-outlet />
+    </bf-app-frame>
+  `,
+})
+export class AppFrameContentWidthExampleComponent {}
+```
+
+## Skip link and the main landmark
+
+The first element in the tab order is a "Skip to main content" link (`provideBfLabels()`'s `skipToContent`), visually hidden until it has focus, then shown as a pill at the top inline-start corner. Activating it moves focus to the frame's main landmark (`tabindex="-1"`, its id from `mainId`, generated when left out) by script and cancels the link's navigation. That interception matters: under `<base href="/">`, which every Angular app has, a bare `#id` link resolves against the base, so following it would load the root URL instead of moving focus. The href stays for the link's semantics. Nested inside another `main` landmark (a docs preview, as on this page) the content drops its `main` role, so the document keeps exactly one.
+
+## One array of destinations
+
+Keep one array of destinations, ideally derived from your route config, and drive every surface from it: the sidebar's `a[bfNavItem]` links, the narrow menu's `a[bfMenuItem]` links and, in the Capacitor shell, the `bf-tab`s of a `bf-tab-bar` (where each destination's path is a child route of the tabs and the tab's id). The overview at the top of this page drives the sidebar and the menu from one array; the shell keeps `bf-tabs` and has no frame:
+
+```ts
+import { Component } from '@angular/core';
+import { BfTabBarComponent, BfTabComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfStackOutletComponent, BfTabsComponent } from '@bitforgehq/ui/mobile';
+import { Folder, type IconNode, Inbox, Settings } from 'lucide';
+
+/** One top-level destination: `path` is the route under the tabs, and the tab's id. */
+interface Destination {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+}
+
+/**
+ * The same destinations in the Capacitor shell.
+ *
+ * Inside `provideBfShell()` there is no `bf-app-frame`: the array that feeds the frame's sidebar
+ * and narrow menu drives the `bf-tab`s of a `bf-tab-bar` in `bf-tabs` instead, and each page
+ * brings its own `bf-page` with a `bf-header`. Each destination's `path` is a child route of
+ * `app` and the tab's id; on desktop the same array feeds `a[bfNavItem]` and `a[bfMenuItem]`
+ * links (`routerLink="/app/{path}"`).
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-app-frame-shell',
+  imports: [
+    BfIconComponent,
+    BfStackOutletComponent,
+    BfTabBarComponent,
+    BfTabComponent,
+    BfTabsComponent,
+  ],
+  template: `
+    <bf-tabs tabsPath="app">
+      <bf-stack-outlet />
+      <bf-tab-bar>
+        @for (destination of destinations; track destination.path) {
+          <bf-tab [id]="destination.path" [label]="destination.label"
+            ><bf-icon [icon]="destination.icon"
+          /></bf-tab>
+        }
+      </bf-tab-bar>
+    </bf-tabs>
+  `,
+})
+export class AppFrameShellExampleComponent {
+  protected readonly destinations: readonly Destination[] = [
+    { path: 'inbox', label: 'Inbox', icon: Inbox },
+    { path: 'projects', label: 'Projects', icon: Folder },
+    { path: 'settings', label: 'Settings', icon: Settings },
+  ];
+}
+```
+
+## Desktop
+
+The frame is a desktop pattern. The skip link shows its focus ring on keyboard focus only (`focus-visible`); it stays out of sight for pointer users, who never focus it. The sidebar column keeps its height while the page scrolls under the pointer, and the narrow header bar stays at the top. The breakpoint follows the viewport, not a container, so a frame inside a smaller box (as in the preview above) still switches at the viewport's width. Under a coarse pointer (a touchscreen laptop) the sidebar's items and the projected controls take their own touch heights; the frame adds none.
+
+## Theming
+
+- Frame: `bg` background, `text` colour.
+- Narrow header bar: `surface` with a `border` line at the bottom, at least 56 px tall.
+- Skip link: `surface` background, `text`, `shadow-floating`, the `control` (pill) radius and the `ring` focus ring.
+- Content: 16 px padding below the breakpoint, 32 px from it up; `max-w-3xl`, `max-w-5xl`, `max-w-7xl` or no cap by `contentWidth`.
+- The sidebar's own tokens are on the [sidebar](https://bitforge-ui.web.app/components/sidebar#theming) page.
+
+## Accessibility
+
+The skip link is a native `<a>` with an href to the main landmark and is the first focusable element, so a keyboard user reaches the content in one step; it moves focus by script (see above). The content is a `role="main"` landmark with `tabindex="-1"`, so it takes focus without joining the tab order, and drops the role inside another `main`. The narrow header bar is a native `header` (the banner landmark at the root of a page). Name the `bf-sidebar` by `label` and the menu button by its text; the frame names nothing else itself. Hidden regions use `display: none`, so the sidebar below the breakpoint and the header bar from it up are out of the accessibility tree too.
+
+### Keyboard
+
+| Key                                              | Action                                                                    |
+| ------------------------------------------------ | ------------------------------------------------------------------------- |
+| <kbd>Tab</kbd>                                   | From the top of the page, focuses the skip link first and reveals it      |
+| <kbd>Enter</kbd>                                 | On the skip link, moves focus to the main content                         |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves through the sidebar or the header bar, then the page, in that order |
+
+## Inputs
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `breakpoint` | `BfAppFrameBreakpoint` (`'md' \| 'lg'`) | `'md'` | The viewport width from which the sidebar column replaces the narrow header bar. |
+| `contentWidth` | `BfAppFrameContentWidth` (`'md' \| 'lg' \| 'xl' \| 'full'`) | `'xl'` | The maximum width of the content column (`md` 48rem, `lg` 64rem, `xl` 80rem, `full`). |
+| `mainId` | `string` | `generated` | The id of the `main` landmark, the skip link's target; generated when left out. |
+
+## Slots
+
+- `sidebar`: The `bf-sidebar`, shown from the breakpoint up; it fills the column's height.
+- `brand`: The app's name or logo in the narrow header bar.
+- `menu`: The narrow-screen navigation: a `bf-menu-button` of `a[bfMenuItem]` links.
+- `actions`: End actions of the narrow header bar, such as the theme menu.
+- `default`: The page: what the router shows, inside the `main` landmark.
+
+## Notes
+
+### Do
+
+- Put the frame at the root of the app, with the `router-outlet` as its content, so the sidebar stays put between pages.
+- Drive the sidebar, the narrow menu and the shell's tab bar from one array of destinations.
+- Keep one `h1` per page in the content; the frame renders no heading.
+
+### Don't
+
+- Don't use `bf-app-frame` inside the Capacitor shell; use `bf-tabs` with a `bf-tab-bar` and `bf-page` there.
+- Don't add your own skip link or hide the `bf-sidebar` with `hidden md:flex` inside the frame; the frame does both.
+
+## Migration notes
+
+### 0.3.2
+
+New `bf-app-frame` in `@bitforgehq/ui`: the frame of a desktop web app. Slots `sidebar` (a
+`bf-sidebar`, in a column that sticks to the viewport at full height from the breakpoint up),
+`brand`, `menu` (the narrow-screen `bf-menu-button`) and `actions` (the header bar shown below
+the breakpoint) and the default slot (the page, in the `main` landmark). `breakpoint`
+(`BfAppFrameBreakpoint`: `'md'` default, `'lg'`), `contentWidth` (`BfAppFrameContentWidth`:
+`'md'` 48rem, `'lg'` 64rem, `'xl'` 80rem default, `'full'`) and `mainId`. A skip link, first in
+the tab order and hidden until focused, moves focus to the main landmark by script, so it works
+under `<base href="/">`; new label key `skipToContent` ("Skip to main content"). Inside another
+`main` landmark the content drops its `main` role. Desktop only: the Capacitor shell keeps
+`bf-tabs`.
+
+---
+
 # bf-avatar
 
 Round avatar showing a photo or initials, in three sizes and four color variants
@@ -5078,7 +5435,7 @@ Surface for a piece of content: a project summary, a stat, a focus prompt. Four
 the design: raised (default), tint, ink and flat. To make the whole card clickable, put a
 `bfAction` link or button in its heading (the stretched-link pattern).
 
-Cards group a piece of content on the canvas. The raised card is the workhorse; tint highlights a stat or a callout; ink is the dark focus card; flat sits inside another surface.
+Cards group a piece of content on the canvas. The raised card is the workhorse; tint highlights a stat or a callout; ink is the dark focus card; flat is the outlined card for a page level that should stay quiet, such as a dense grid of cards.
 
 ## When to use
 
@@ -5131,6 +5488,53 @@ import { BfCardComponent } from '@bitforgehq/ui';
 export class CardVariantsExampleComponent {}
 ```
 
+## Nesting surfaces
+
+Each level of a page takes one surface style, and a level inside a card steps down, never up:
+
+- **Raised card, then sunken tile.** Inside a raised card, group figures or blocks on sunken, borderless tiles: [bf-stat](https://bitforge-ui.web.app/components/stat) `variant="tile"`, or your own block on `bg-surface-sunken` with the `card` radius.
+- **Never an outlined surface inside a raised one.** A `flat` card or a `card` stat inside a raised card draws a border on top of a shadow, two edges for one level; use a tile instead. Don't nest raised cards either.
+- **One surface style per level of a dashboard.** All cards on the page are raised (or all flat), and all tiles in them are sunken; mixing raised and flat cards side by side, or tiles and outlined stats in one card, reads as different kinds of content. The [bf-stat dashboard example](https://bitforge-ui.web.app/components/stat) puts raised cards on the page and sunken tiles in each.
+
+```ts
+import { Component } from '@angular/core';
+import { BfCardComponent, BfStatComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { CircleCheck, Clock, ListTodo } from 'lucide';
+
+/**
+ * A raised card holding a row of sunken tiles.
+ *
+ * One surface per level: the card is raised on the page, and the stats inside it are sunken,
+ * borderless tiles (`bf-stat variant="tile"`), never outlined surfaces.
+ */
+@Component({
+  selector: 'app-example-card-nesting',
+  imports: [BfCardComponent, BfIconComponent, BfStatComponent],
+  template: `
+    <bf-card padding="lg">
+      <h3 class="text-heading">This week</h3>
+      <div class="grid grid-cols-[repeat(auto-fit,minmax(9rem,1fr))] gap-3">
+        <bf-stat label="Open tasks" value="14" variant="tile">
+          <bf-icon bfSlot="icon" [icon]="listTodo" />
+        </bf-stat>
+        <bf-stat label="Done" value="23" variant="tile">
+          <bf-icon bfSlot="icon" [icon]="circleCheck" />
+        </bf-stat>
+        <bf-stat label="Time logged" value="31 h" variant="tile">
+          <bf-icon bfSlot="icon" [icon]="clock" />
+        </bf-stat>
+      </div>
+    </bf-card>
+  `,
+})
+export class CardNestingExampleComponent {
+  protected readonly listTodo = ListTodo;
+  protected readonly circleCheck = CircleCheck;
+  protected readonly clock = Clock;
+}
+```
+
 ## Footer
 
 Content in `bfSlot="footer"` sits on the card's bottom edge: it takes the free space above it, so in a grid of cards (a `bf-card` fills its grid cell, `h-full`) every footer lines up, however differently the descriptions wrap, and the body keeps its 12 px gap above the footer. Put the footer's parts in one element (`<div bfSlot="footer" class="flex …">`), so they move together.
@@ -5302,13 +5706,20 @@ The card renders a plain `<div>` with no role. A clickable card follows the stre
 
 ### Don't
 
-- Don't nest raised cards; use `flat` inside.
+- Don't nest raised cards, and don't put an outlined surface (`flat`, a `card` stat) inside a raised one; use sunken tiles (`bf-stat variant="tile"`) inside.
+- Don't mix surface styles on one level of a dashboard; keep one per level.
 - Don't use `interactive` (deprecated) or wrap a card in an `<a>`; both hide the heading and nest interactive content.
 - Don't put more than one `bfAction` in a card.
 - Don't put a `text` button on an ink card — its primary colour fails contrast on ink; use `tonal` or `outline`.
 
 ## Migration notes
 
+### 0.3.2
+
+New "Nesting surfaces" docs section: a raised card holds sunken tiles, never an outlined
+surface (`flat`, a `card` stat), and each level of a dashboard keeps one surface style. New
+`card/nesting` example. No code change.
+
 ### 0.3.1
 
 The footer (`bfSlot="footer"`) sits on the card's bottom edge (`mt-auto`), so in a grid of cards
@@ -10011,6 +10422,89 @@ export class EmptyStateActionExampleComponent {
 
 Set `headingLevel` to `3` when the empty state sits inside a section that already opened with an `h2`, so the page outline stays in order.
 
+## As the page
+
+When the empty state is the whole page (a not-found page, a no-access page, an app's first run), its title is the page's heading: set `headingLevel` to `1` so it renders the `h1`, and give the page no other `h1`. Centre it in the content area: a column with a minimum height (`min-h-[60vh]`) and `justify-center`. Put the primary action first in the `actions` slot (a `bfButton` link home) and an optional secondary link after it (a `text` `bfButton`, such as "Contact support").
+
+The preview below sits inside this docs page, which already has its `h1`, so it keeps `headingLevel` 2 in a shorter area; a real page uses `1`, as in the code-only example after it.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfButtonComponent, BfEmptyStateComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { FileQuestionMark } from 'lucide';
+
+/**
+ * An empty state as a whole page.
+ *
+ * Centred in a tall content area, with a primary action and a secondary link. This preview sits
+ * inside a docs page that has its own `h1`, so it uses `headingLevel` 2; on a real not-found page
+ * the empty state is the page, so set it to 1 (see the next example).
+ */
+@Component({
+  selector: 'app-example-empty-state-page',
+  imports: [RouterLink, BfButtonComponent, BfEmptyStateComponent, BfIconComponent],
+  template: `
+    <div class="flex min-h-96 flex-col justify-center">
+      <bf-empty-state
+        title="Page not found"
+        description="The page may have moved, or the link has a typo."
+        [headingLevel]="2"
+      >
+        <bf-icon bfSlot="icon" [icon]="fileQuestion" size="lg" />
+        <a bfSlot="actions" bfButton routerLink="/">Go to the home page</a>
+        <a bfSlot="actions" bfButton variant="text" href="mailto:support@example.com">
+          Contact support
+        </a>
+      </bf-empty-state>
+    </div>
+  `,
+})
+export class EmptyStatePageExampleComponent {
+  protected readonly fileQuestion = FileQuestionMark;
+}
+```
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfButtonComponent, BfEmptyStateComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { FileQuestionMark } from 'lucide';
+
+/**
+ * A not-found page whose empty state is the page heading.
+ *
+ * The route's whole content: `headingLevel` 1 renders the title as the page's `h1`, and the
+ * `min-h-[60vh]` area centres the empty state vertically in the content column.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-empty-state-not-found-page',
+  imports: [RouterLink, BfButtonComponent, BfEmptyStateComponent, BfIconComponent],
+  template: `
+    <div class="flex min-h-[60vh] flex-col justify-center">
+      <bf-empty-state
+        title="Page not found"
+        description="The page may have moved, or the link has a typo."
+        [headingLevel]="1"
+      >
+        <bf-icon bfSlot="icon" [icon]="fileQuestion" size="lg" />
+        <a bfSlot="actions" bfButton routerLink="/">Go to the home page</a>
+        <a bfSlot="actions" bfButton variant="text" href="mailto:support@example.com">
+          Contact support
+        </a>
+      </bf-empty-state>
+    </div>
+  `,
+})
+export class EmptyStateNotFoundPageExampleComponent {
+  protected readonly fileQuestion = FileQuestionMark;
+}
+```
+
 ## Theming
 
 - Icon tile: `surface-sunken` background, `text-muted` icon color, `tile` radius.
@@ -10018,7 +10512,7 @@ Set `headingLevel` to `3` when the empty state sits inside a section that alread
 
 ## Accessibility
 
-The title renders as an `<h2>` by default and an `<h3>` when `headingLevel` is `3`, so it slots into the surrounding page outline instead of always claiming the top level. The icon and action slots carry their own accessibility — an icon should stay decorative, and the action needs its own accessible name.
+The title renders as an `<h2>` by default, an `<h3>` when `headingLevel` is `3` and an `<h1>` when it is `1` (only when the empty state is the page and the page has no other `h1`), so it slots into the surrounding page outline instead of always claiming the top level. The icon and action slots carry their own accessibility — an icon should stay decorative, and the action needs its own accessible name.
 
 ## Inputs
 
@@ -10026,7 +10520,7 @@ The title renders as an `<h2>` by default and an `<h3>` when `headingLevel` is `
 | --- | --- | --- | --- |
 | `title` | `string` | required | What is missing, as a short title. |
 | `description` | `string` | `''` | One sentence on how to fill it. |
-| `headingLevel` | `BfEmptyStateHeadingLevel` (`2 \| 3`) | `2` | Heading level of the title so the empty state fits the page outline. |
+| `headingLevel` | `BfEmptyStateHeading` (`2 \| 3 \| 1`) | `2` | Heading level of the title so the empty state fits the page outline; 1 when it is the page. |
 
 ## Slots
 
@@ -10042,10 +10536,20 @@ The title renders as an `<h2>` by default and an `<h3>` when `headingLevel` is `
 
 ### Don't
 
+- Don't set `headingLevel` to `1` on an empty state inside a page that already has its own `h1`.
 - Don't use `bf-empty-state` for a loading screen; that is `bf-spinner`.
 
 ## Migration notes
 
+### 0.3.2
+
+`headingLevel` now takes the new named type `BfEmptyStateHeading` (`BfEmptyStateHeadingLevel |
+1`): `1` renders the title as the page's `h1`, for an empty state that is the page (a not-found
+or no-access page). The released `BfEmptyStateHeadingLevel` keeps its two members, so `Record`s
+over it keep compiling. New "As the page" docs section with the `empty-state/page` example
+(centred in a tall area, a primary action and a secondary link) and the code-only
+`empty-state/not-found-page`.
+
 ### 0.3.0
 
 New exported `BfEmptyStateHeadingLevel` (`2 | 3`), the type of `headingLevel` (was an inline union
@@ -10992,7 +11496,7 @@ inside one.
 
 ## Desktop
 
-`bf-header` is part of the Capacitor shell (`provideBfShell()`), shaped like an iOS or Material app bar. On a desktop web page use [bf-page-header](https://bitforge-ui.web.app/components/page-header): the page's one `h1` (`title`) with an optional `subtitle`, badges in `meta`, and the actions in `actions` (the main action as a primary [bf-button](https://bitforge-ui.web.app/components/button), secondary ones as `ghost` or `outline` buttons, the rest in an icon-only [bf-menu-button](https://bitforge-ui.web.app/components/menu-button) labelled "More actions"); the actions wrap under the title in a narrow window. On a nested page, put a [bf-breadcrumb](https://bitforge-ui.web.app/components/breadcrumb) in its `breadcrumb` slot, and a [bf-toolbar](https://bitforge-ui.web.app/components/toolbar) under it for search and filters. The two are siblings rather than one shell-aware widget: the large title and the scroll-under surface are phone patterns that depend on `bf-content`.
+`bf-header` is part of the Capacitor shell (`provideBfShell()`), shaped like an iOS or Material app bar. On a desktop web page use [bf-page-header](https://bitforge-ui.web.app/components/page-header): the page's one `h1` (`title`) with an optional `subtitle`, badges in `meta`, and the actions in `actions` (the main action as a primary [bf-button](https://bitforge-ui.web.app/components/button), secondary ones as `ghost` or `outline` buttons, the rest in an icon-only [bf-menu-button](https://bitforge-ui.web.app/components/menu-button) labelled "More actions"); the actions wrap under the title in a narrow window. On a nested page, put a [bf-breadcrumb](https://bitforge-ui.web.app/components/breadcrumb) in its `breadcrumb` slot, and a [bf-toolbar](https://bitforge-ui.web.app/components/toolbar) under it for search and filters. Below the breakpoint, [bf-app-frame](https://bitforge-ui.web.app/components/app-frame) supplies the app-level header bar (brand, navigation menu, actions) above the page header. The two are siblings rather than one shell-aware widget: the large title and the scroll-under surface are phone patterns that depend on `bf-content`.
 
 ```ts
 import { Component, signal } from '@angular/core';
@@ -11132,6 +11636,10 @@ The title is not in the tab order; after a push, `bf-stack-outlet` focuses it wi
 
 ## Migration notes
 
+### 0.3.2
+
+The `## Desktop` docs say `bf-app-frame` supplies the app-level header bar below its breakpoint.
+
 ### 0.3.1
 
 The `## Desktop` docs and When to use name the desktop replacement, `bf-page-header` (with
@@ -20212,9 +20720,9 @@ export class SidebarOverviewExampleComponent {
 
 The vertical navigation of a desktop app: a `nav` landmark with a `header` slot (the brand),
 the destinations (`a[bfNavItem]` links, optionally in `bf-nav-group`s) and a `footer` slot.
-`collapsed` turns it into an icon rail; the consumer owns the toggle button and binds
-`[(collapsed)]`. Below a breakpoint hide it (`class="hidden md:flex"`) and drive a
-`bf-menu-button` from the same routes.
+`collapsed` turns it into an icon rail: put a `bf-sidebar-toggle` (`@bitforgehq/ui/overlay`) in
+it, or bind `[(collapsed)]` to your own button. Below a breakpoint hide it
+(`class="hidden md:flex"`) and drive a `bf-menu-button` from the same routes.
 
 The vertical navigation of a desktop web app: a `nav` landmark down the inline-start edge with a `header` slot for the brand, the destinations as [`a[bfNavItem]`](https://bitforge-ui.web.app/components/nav-item) links (optionally in titled [`bf-nav-group`](https://bitforge-ui.web.app/components/nav-group)s) and a `footer` slot for settings or the account. `collapsed` turns it into an icon rail. Its horizontal sibling for apps with few sections is [`bf-top-nav`](https://bitforge-ui.web.app/components/top-nav); both share the same item, so the current page, the badge and the focus ring look the same in either.
 
@@ -20228,11 +20736,178 @@ Put `bfNavItem` on your own `<a routerLink routerLinkActive ariaCurrentWhenActiv
 
 ## Collapsing to an icon rail
 
-`collapsed` is a model: bind `[(collapsed)]` to your own toggle button, such as a text `bf-icon-button` in the header whose label says what the next press does ("Collapse sidebar", "Expand sidebar"). The widget has no toggle of its own, because the button needs an icon and a widget never imports one. Collapsed, every item shows only its icon, centred in a square; its label stays in the DOM as screen-reader text, so its accessible name does not change, and becomes the link's `title`, the tooltip a pointer user sees on hover. A count badge becomes a small dot that is still announced, and the group headings are hidden visually but still name their groups. The width follows the rail (`w-auto`); expanded the sidebar is `w-60` (240 px).
+`collapsed` is a model. Put a [`bf-sidebar-toggle`](https://bitforge-ui.web.app/components/sidebar-toggle) (`@bitforgehq/ui/overlay`) in the header or footer: it flips the model, names itself by what the next press does ("Collapse sidebar", "Expand sidebar") and takes its two icons as slots, since a widget never imports one. Bind `[(collapsed)]` to keep the state in your own signal, or bind it to your own button outside the sidebar. Collapsed, every item shows only its icon, centred in a square; its label stays in the DOM as screen-reader text, so its accessible name does not change, and becomes the link's `title`, the tooltip a pointer user sees on hover. A count badge becomes a small dot that is still announced, and the group headings are hidden visually but still name their groups. The width follows the rail (`w-auto`); expanded the sidebar is `w-60` (240 px).
+
+## Remember the collapsed sidebar
+
+`BfSidebarStateService` (from `@bitforgehq/ui`) holds a `collapsed` signal: bind the sidebar's `[(collapsed)]` to it (`sidebarState.collapsed`) and add `provideBfSidebarState()` to the app's providers, and every change is stored under `bf-sidebar-collapsed` (`localStorage` in the browser, `BF_SIDEBAR_STATE_STORAGE` to keep it elsewhere) and read back at the next start, so the app opens as the user left it. Without the provider the signal still holds the state but nothing is stored; on the server it starts expanded and reads nothing. The widget itself injects no service.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { RouterLink, RouterLinkActive, RouterOutlet } from '@angular/router';
+import { BfNavItemComponent, BfSidebarComponent, BfSidebarStateService } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfSidebarToggleComponent } from '@bitforgehq/ui/overlay';
+import { Inbox, PanelLeftClose, PanelLeftOpen } from 'lucide';
+
+/**
+ * A sidebar that opens collapsed or expanded, as the user left it.
+ *
+ * `[(collapsed)]` binds `BfSidebarStateService.collapsed`; with `provideBfSidebarState()` in the
+ * app's providers every change is stored under `bf-sidebar-collapsed` (`localStorage` in the
+ * browser) and read back at the next start.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-sidebar-remembered',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    RouterOutlet,
+    BfIconComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+    BfSidebarToggleComponent,
+  ],
+  template: `
+    <div class="flex min-h-dvh">
+      <bf-sidebar [(collapsed)]="sidebarState.collapsed" class="sticky top-0 h-dvh">
+        <a bfNavItem routerLink="/inbox" routerLinkActive ariaCurrentWhenActive="page">
+          <bf-icon bfSlot="icon" [icon]="inbox" />
+          Inbox
+        </a>
+        <bf-sidebar-toggle bfSlot="footer">
+          <bf-icon bfSlot="collapse-icon" [icon]="panelClose" />
+          <bf-icon bfSlot="expand-icon" [icon]="panelOpen" />
+        </bf-sidebar-toggle>
+      </bf-sidebar>
+      <main class="min-w-0 flex-1 p-6"><router-outlet /></main>
+    </div>
+  `,
+})
+export class SidebarRememberedExampleComponent {
+  // app.config.ts: providers: [provideBfSidebarState()]
+  protected readonly sidebarState = inject(BfSidebarStateService);
+  protected readonly inbox = Inbox;
+  protected readonly panelOpen = PanelLeftOpen;
+  protected readonly panelClose = PanelLeftClose;
+}
+```
+
+## Footer
+
+The footer slot takes several elements, stacked with a 4 px gap: a Settings link as an `a[bfNavItem]`, a row holding an icon-only text [`bf-theme-menu-button`](https://bitforge-ui.web.app/components/theme-menu-button) and the `bf-sidebar-toggle`, and an optional version line in `text-caption text-text-muted`. Expanded, the row puts the two buttons at either end (`flex items-center justify-between`). As an icon rail every footer element is centred: switch the row to a column (`flex flex-col items-center gap-1`) so both buttons fit the rail, and hide the version line (`[class.hidden]="collapsed()"`), which has no icon to shrink to. Open the theme menu upwards (`placement="above-start"`), since the footer sits at the bottom of the screen.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { type BfColorScheme, BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfSidebarToggleComponent, BfThemeMenuButtonComponent } from '@bitforgehq/ui/overlay';
+import {
+  Inbox,
+  type IconNode,
+  Moon,
+  PanelLeftClose,
+  PanelLeftOpen,
+  Settings,
+  Sun,
+  SunMoon,
+  Users,
+} from 'lucide';
+
+interface NavLink {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+}
+
+/**
+ * A sidebar footer: settings, theme, toggle and version.
+ *
+ * The footer slot holds a Settings link (`a[bfNavItem]`), a row with an icon-only
+ * `bf-theme-menu-button` and the `bf-sidebar-toggle`, and a version line. Expanded, the two
+ * buttons sit at either end of the row; as an icon rail the row stacks vertically and the version
+ * line hides. The theme binds a local signal so the docs site keeps its theme; an app binds
+ * `BfColorSchemeService.scheme`.
+ */
+@Component({
+  selector: 'app-example-sidebar-footer',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfIconComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+    BfSidebarToggleComponent,
+    BfThemeMenuButtonComponent,
+  ],
+  template: `
+    <div class="border-border bg-bg rounded-card flex h-[26rem] overflow-hidden border">
+      <bf-sidebar label="Footer demo" [(collapsed)]="collapsed">
+        @for (link of links; track link.path) {
+          <a bfNavItem [routerLink]="link.path" routerLinkActive ariaCurrentWhenActive="page">
+            <bf-icon bfSlot="icon" [icon]="link.icon" />
+            {{ link.label }}
+          </a>
+        }
+        <a
+          bfSlot="footer"
+          bfNavItem
+          routerLink="/theming"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+        >
+          <bf-icon bfSlot="icon" [icon]="settings" />
+          Settings
+        </a>
+        <div bfSlot="footer" [class]="rowClasses()">
+          <bf-theme-menu-button iconOnly variant="text" placement="above-start" [(value)]="scheme">
+            <bf-icon bfSlot="icon" [icon]="themeIcon()" />
+          </bf-theme-menu-button>
+          <bf-sidebar-toggle>
+            <bf-icon bfSlot="collapse-icon" [icon]="panelClose" />
+            <bf-icon bfSlot="expand-icon" [icon]="panelOpen" />
+          </bf-sidebar-toggle>
+        </div>
+        <p bfSlot="footer" class="text-caption text-text-muted ps-3" [class.hidden]="collapsed()">
+          Version 0.3.2
+        </p>
+      </bf-sidebar>
+      <div class="min-w-0 flex-1 p-4">
+        <p data-status aria-live="polite" class="text-caption text-text-muted wrap-anywhere">
+          {{ collapsed() ? 'Icon rail' : 'Expanded' }}, theme {{ scheme() }}.
+        </p>
+      </div>
+    </div>
+  `,
+})
+export class SidebarFooterExampleComponent {
+  readonly collapsed = signal(false);
+  /** Stands in for `BfColorSchemeService.scheme`. */
+  readonly scheme = signal<BfColorScheme>('system');
+
+  /** Expanded: one row, the buttons at either end. Collapsed: a column in the rail. */
+  protected readonly rowClasses = computed(() =>
+    this.collapsed() ? 'flex flex-col items-center gap-1' : 'flex items-center justify-between',
+  );
+  protected readonly themeIcon = computed(
+    () => ({ system: SunMoon, light: Sun, dark: Moon })[this.scheme()],
+  );
+  protected readonly links: readonly NavLink[] = [
+    { path: '/components/nav-item', label: 'Inbox', icon: Inbox },
+    { path: '/components/nav-group', label: 'Team', icon: Users },
+  ];
+  protected readonly settings = Settings;
+  protected readonly panelOpen = PanelLeftOpen;
+  protected readonly panelClose = PanelLeftClose;
+}
+```
 
 ## Responsive layouts
 
-Below a breakpoint the sidebar does not turn itself into a menu: a root widget cannot render `bf-menu`. Keep one array of destinations (ideally derived from your route config) and drive every surface from it: the sidebar from `md` up (`class="hidden md:flex"` on `bf-sidebar`; its own `flex` loses to your `hidden`), and below it a [`bf-menu-button`](https://bitforge-ui.web.app/components/menu-button) of `a[bfMenuItem]` router links (`class="md:hidden"`, from `@bitforgehq/ui/overlay`). Each surface keeps the router's `routerLinkActive`.
+Below a breakpoint the sidebar does not turn itself into a menu: a root widget cannot render `bf-menu`. Keep one array of destinations (ideally derived from your route config) and drive every surface from it: the sidebar from `md` up (`class="hidden md:flex"` on `bf-sidebar`; its own `flex` loses to your `hidden`), and below it a [`bf-menu-button`](https://bitforge-ui.web.app/components/menu-button) of `a[bfMenuItem]` router links (`class="md:hidden"`, from `@bitforgehq/ui/overlay`). Each surface keeps the router's `routerLinkActive`. [`bf-app-frame`](https://bitforge-ui.web.app/components/app-frame) does this layout for you: it shows the sidebar in a sticky column from the breakpoint up and the menu button in a header bar below it.
 
 ```ts
 import { Component } from '@angular/core';
@@ -20390,7 +21065,7 @@ The sidebar is a desktop pattern. Its items take a `surface-muted` fill and the
 
 ## Accessibility
 
-`bf-sidebar` renders a native `<nav>` landmark named by `label`, else `provideBfLabels()`'s `navigation` ("Main"); give each landmark on a page a different name. The header, the destinations and the footer all sit inside it, in that DOM order. The current page is the link the router marks with `aria-current="page"`; the tonal fill is never the only cue under forced colours, where an outline marks it. Collapsing changes only what is visible: every item keeps its label as screen-reader text and each group its name, so the accessible names stay the same. The consumer's toggle button is a native button; name it by what it does ("Collapse sidebar") or give it `aria-pressed`, and keep it in the sidebar or right before it.
+`bf-sidebar` renders a native `<nav>` landmark named by `label`, else `provideBfLabels()`'s `navigation` ("Main"); give each landmark on a page a different name. The header, the destinations and the footer all sit inside it, in that DOM order. The current page is the link the router marks with `aria-current="page"`; the tonal fill is never the only cue under forced colours, where an outline marks it. Collapsing changes only what is visible: every item keeps its label as screen-reader text and each group its name, so the accessible names stay the same. `bf-sidebar-toggle` is a native button named by what it does ("Collapse sidebar"), with `aria-expanded` and `aria-controls` on the `nav`; your own toggle should do the same, and sit in the sidebar or right before it.
 
 ### Keyboard
 
@@ -20404,7 +21079,7 @@ The sidebar is a desktop pattern. Its items take a `surface-muted` fill and the
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `label` | `string` | `''` | Accessible name of the navigation; empty falls back to `provideBfLabels()`'s `navigation` ("Main"). Name each landmark differently when a page has more than one. |
-| `collapsed` | `boolean` | `false` | Collapses the sidebar to an icon rail: items show their icon only, their label stays for screen readers and becomes a tooltip. Bind `[(collapsed)]` to your own toggle button. |
+| `collapsed` | `boolean` | `false` | Collapses the sidebar to an icon rail: items show their icon only, their label stays for screen readers and becomes a tooltip. A `bf-sidebar-toggle` inside flips it; bind `[(collapsed)]` to keep it in your state. |
 
 ## Slots
 
@@ -20418,6 +21093,7 @@ The sidebar is a desktop pattern. Its items take a `surface-muted` fill and the
 
 - Mark the current page with `routerLinkActive` and `ariaCurrentWhenActive="page"` on every link.
 - Drive the sidebar, the small-screen menu and the shell's tab bar from one array of destinations.
+- Remember the collapsed state with `BfSidebarStateService` and `provideBfSidebarState()`.
 
 ### Don't
 
@@ -20426,6 +21102,16 @@ The sidebar is a desktop pattern. Its items take a `surface-muted` fill and the
 
 ## Migration notes
 
+### 0.3.2
+
+New `BfSidebarStateService` (a `collapsed` signal) and `provideBfSidebarState()` in
+`@bitforgehq/ui`: bind the sidebar's `[(collapsed)]` to `sidebarState.collapsed` and the provider
+stores every change under `bf-sidebar-collapsed` in `BF_SIDEBAR_STATE_STORAGE` (`localStorage` in
+the browser, memory elsewhere), read back at the next start; without the provider nothing is
+written, and on the server nothing is read. The sidebar's `nav` now has an id, for a toggle's
+`aria-controls`. The docs gain "Remember the collapsed sidebar" and a "Footer" composition
+(Settings link, theme menu, toggle, version line) that works expanded and as an icon rail.
+
 ### 0.3.1
 
 New `bf-sidebar`: the vertical navigation of a desktop app, a `nav` landmark with `header`,
@@ -20435,6 +21121,296 @@ breakpoint, hide it with `hidden md:flex` and drive a `bf-menu-button` from the
 
 ---
 
+# bf-sidebar-toggle
+
+Icon button inside a sidebar that collapses it to an icon rail and back
+
+`BfSidebarToggleComponent` from `@bitforgehq/ui/overlay` · Navigation · since 0.3.2
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfSidebarToggleComponent } from '@bitforgehq/ui/overlay';
+import { type IconNode, Layers, PanelLeftClose, PanelLeftOpen, PanelTop } from 'lucide';
+
+interface NavLink {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+}
+
+/**
+ * The bf-sidebar-toggle overview.
+ *
+ * Live demo of `bf-sidebar-toggle` in the header of a `bf-sidebar`: a press collapses the
+ * sidebar to an icon rail and the next one expands it again. Its name and tooltip say what the
+ * next press does, and only the matching icon slot shows. The sidebar's `[(collapsed)]` keeps
+ * the state in a signal, and the result line reports it.
+ */
+@Component({
+  selector: 'app-example-sidebar-toggle-overview',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfIconComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+    BfSidebarToggleComponent,
+  ],
+  template: `
+    <div class="border-border bg-bg rounded-card flex h-72 overflow-hidden border">
+      <bf-sidebar label="Toggle demo" [(collapsed)]="collapsed">
+        <div bfSlot="header" class="flex items-center justify-between gap-2">
+          @if (!collapsed()) {
+            <span class="text-heading text-text ps-3">Atlas</span>
+          }
+          <bf-sidebar-toggle>
+            <bf-icon bfSlot="collapse-icon" [icon]="panelClose" />
+            <bf-icon bfSlot="expand-icon" [icon]="panelOpen" />
+          </bf-sidebar-toggle>
+        </div>
+        @for (link of links; track link.path) {
+          <a bfNavItem [routerLink]="link.path" routerLinkActive ariaCurrentWhenActive="page">
+            <bf-icon bfSlot="icon" [icon]="link.icon" />
+            {{ link.label }}
+          </a>
+        }
+      </bf-sidebar>
+      <div class="min-w-0 flex-1 p-4">
+        <p data-status aria-live="polite" class="text-caption text-text-muted wrap-anywhere">
+          {{ status() }}
+        </p>
+      </div>
+    </div>
+  `,
+})
+export class SidebarToggleOverviewExampleComponent {
+  readonly collapsed = signal(false);
+  readonly status = computed(() =>
+    this.collapsed() ? 'Sidebar collapsed to an icon rail.' : 'Sidebar expanded.',
+  );
+
+  protected readonly links: readonly NavLink[] = [
+    { path: '/components/sidebar-toggle', label: 'Sidebar toggle', icon: PanelTop },
+    { path: '/components/sidebar', label: 'Sidebar', icon: Layers },
+  ];
+  protected readonly panelOpen = PanelLeftOpen;
+  protected readonly panelClose = PanelLeftClose;
+}
+```
+
+## Overview
+
+The collapse button of a `bf-sidebar`: a text icon button placed inside the sidebar (usually in
+its header or footer) that flips the sidebar between full width and an icon rail. Its name and
+tooltip say what the next press does ("Collapse sidebar", "Expand sidebar"), `aria-expanded`
+follows the sidebar and `aria-controls` points at its `nav`. It shows the `collapse-icon` slot
+while expanded and the `expand-icon` slot while collapsed. It reads and writes the sidebar's
+`collapsed` model, so `[(collapsed)]` on the sidebar sees every press. Outside a `bf-sidebar`
+(in a `bf-top-nav`, or on its own) it renders nothing.
+
+The sidebar toggle collapses a [`bf-sidebar`](https://bitforge-ui.web.app/components/sidebar) to an icon rail and expands it again, from `@bitforgehq/ui/overlay` (it shows a `bfTooltip`, so it needs `@angular/cdk`; no Capacitor). Put it inside the sidebar, in its header or footer: it reads and writes the sidebar's `collapsed` model, so the sidebar's `[(collapsed)]` sees every press and the toggle needs no binding of its own. It is a text icon button whose name and tooltip say what the next press does. Import `BfSidebarToggleComponent` from `@bitforgehq/ui/overlay`.
+
+## When to use
+
+Use `bf-sidebar-toggle` for the collapse button of a desktop app's `bf-sidebar`. Bind your own [bf-icon-button](https://bitforge-ui.web.app/components/icon-button) to the sidebar's `[(collapsed)]` instead when the button must sit outside the sidebar, in a top bar. In the Capacitor shell there is no sidebar: use [bf-tabs](https://bitforge-ui.web.app/components/tabs) with a `bf-tab-bar` instead.
+
+## Icons
+
+The toggle never picks an icon. Project two, `bfSlot="collapse-icon"` (shown while the sidebar is expanded, such as Lucide's `PanelLeftClose`) and `bfSlot="expand-icon"` (shown while it is an icon rail, `PanelLeftOpen`); only the one that matches the state shows. Under a right-to-left layout pick the mirrored icons (`PanelRightClose`, `PanelRightOpen`), since the sidebar then sits at the right.
+
+## Placement
+
+The toggle renders only inside a `bf-sidebar`. In a `bf-top-nav`, which never collapses, or on its own it renders nothing and takes no space, so a misplaced toggle never shows a button that does nothing. In the header, put it after the brand and show the brand only while expanded; in the footer, put it beside the theme menu ([footer composition](https://bitforge-ui.web.app/components/sidebar#footer)). It keeps its place in the tab order either way, so a keyboard user finds it where they left it.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { type BfColorScheme, BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfSidebarToggleComponent, BfThemeMenuButtonComponent } from '@bitforgehq/ui/overlay';
+import {
+  Inbox,
+  type IconNode,
+  Moon,
+  PanelLeftClose,
+  PanelLeftOpen,
+  Settings,
+  Sun,
+  SunMoon,
+  Users,
+} from 'lucide';
+
+interface NavLink {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+}
+
+/**
+ * A sidebar footer: settings, theme, toggle and version.
+ *
+ * The footer slot holds a Settings link (`a[bfNavItem]`), a row with an icon-only
+ * `bf-theme-menu-button` and the `bf-sidebar-toggle`, and a version line. Expanded, the two
+ * buttons sit at either end of the row; as an icon rail the row stacks vertically and the version
+ * line hides. The theme binds a local signal so the docs site keeps its theme; an app binds
+ * `BfColorSchemeService.scheme`.
+ */
+@Component({
+  selector: 'app-example-sidebar-footer',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfIconComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+    BfSidebarToggleComponent,
+    BfThemeMenuButtonComponent,
+  ],
+  template: `
+    <div class="border-border bg-bg rounded-card flex h-[26rem] overflow-hidden border">
+      <bf-sidebar label="Footer demo" [(collapsed)]="collapsed">
+        @for (link of links; track link.path) {
+          <a bfNavItem [routerLink]="link.path" routerLinkActive ariaCurrentWhenActive="page">
+            <bf-icon bfSlot="icon" [icon]="link.icon" />
+            {{ link.label }}
+          </a>
+        }
+        <a
+          bfSlot="footer"
+          bfNavItem
+          routerLink="/theming"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+        >
+          <bf-icon bfSlot="icon" [icon]="settings" />
+          Settings
+        </a>
+        <div bfSlot="footer" [class]="rowClasses()">
+          <bf-theme-menu-button iconOnly variant="text" placement="above-start" [(value)]="scheme">
+            <bf-icon bfSlot="icon" [icon]="themeIcon()" />
+          </bf-theme-menu-button>
+          <bf-sidebar-toggle>
+            <bf-icon bfSlot="collapse-icon" [icon]="panelClose" />
+            <bf-icon bfSlot="expand-icon" [icon]="panelOpen" />
+          </bf-sidebar-toggle>
+        </div>
+        <p bfSlot="footer" class="text-caption text-text-muted ps-3" [class.hidden]="collapsed()">
+          Version 0.3.2
+        </p>
+      </bf-sidebar>
+      <div class="min-w-0 flex-1 p-4">
+        <p data-status aria-live="polite" class="text-caption text-text-muted wrap-anywhere">
+          {{ collapsed() ? 'Icon rail' : 'Expanded' }}, theme {{ scheme() }}.
+        </p>
+      </div>
+    </div>
+  `,
+})
+export class SidebarFooterExampleComponent {
+  readonly collapsed = signal(false);
+  /** Stands in for `BfColorSchemeService.scheme`. */
+  readonly scheme = signal<BfColorScheme>('system');
+
+  /** Expanded: one row, the buttons at either end. Collapsed: a column in the rail. */
+  protected readonly rowClasses = computed(() =>
+    this.collapsed() ? 'flex flex-col items-center gap-1' : 'flex items-center justify-between',
+  );
+  protected readonly themeIcon = computed(
+    () => ({ system: SunMoon, light: Sun, dark: Moon })[this.scheme()],
+  );
+  protected readonly links: readonly NavLink[] = [
+    { path: '/components/nav-item', label: 'Inbox', icon: Inbox },
+    { path: '/components/nav-group', label: 'Team', icon: Users },
+  ];
+  protected readonly settings = Settings;
+  protected readonly panelOpen = PanelLeftOpen;
+  protected readonly panelClose = PanelLeftClose;
+}
+```
+
+## Remembering the state
+
+The toggle holds no state. To open the app with the sidebar as the user left it, bind the sidebar to `BfSidebarStateService` from `@bitforgehq/ui` and add `provideBfSidebarState()` to the app's providers ([remember the collapsed sidebar](https://bitforge-ui.web.app/components/sidebar#remember-the-collapsed-sidebar)).
+
+## Sizes
+
+`size` is `sm` 32, `md` 40 or `lg` 48 px, square; unset it follows `provideBfDefaults()`'s `controlSize`, as `bf-icon-button` does.
+
+## Labels
+
+The name and tooltip read `sidebarCollapse` ("Collapse sidebar") while the sidebar is expanded and `sidebarExpand` ("Expand sidebar") while it is an icon rail. Translate them with `provideBfLabels()`.
+
+## Testing
+
+`BfSidebarToggleHarness` from `@bitforgehq/ui/testing` reads the name with `getLabel()`, the state with `isExpanded()` and presses it with `toggle()`; filter it with `label: 'Collapse sidebar'`.
+
+## Desktop
+
+The toggle looks and behaves like a text `bf-icon-button`: the muted text colour, a `surface-muted` fill and the pointer cursor on hover, a pressed tint while pressed, and the focus ring on keyboard focus only (`focus-visible`). Its tooltip shows after a 500 ms rest of a fine pointer and at once on keyboard focus: above the button while expanded, at the inline end of the rail while collapsed. Under a fine pointer the visible box is the hit area; under a coarse pointer (a touchscreen laptop) a `sm` or `md` toggle extends vertically to 44 px, and no tooltip shows.
+
+## Theming
+
+The toggle consumes `bf-icon-button`'s text variant: `text-muted` at rest, `text` and `surface-muted` on hover, `primary-soft-pressed` while pressed, and the `ring` token for focus. The tooltip consumes `bf-tooltip`'s tokens.
+
+## Accessibility
+
+- A native `<button type="button">` named by `aria-label`: "Collapse sidebar" while expanded, "Expand sidebar" while collapsed, so the name says what a press does. The tooltip shows the same text and describes the button while it shows.
+- `aria-expanded` is `true` while the sidebar is at full width and `false` as an icon rail; `aria-controls` points at the sidebar's `nav`.
+- The projected icons add nothing to the name (`bf-icon` is `aria-hidden`).
+- Collapsing keeps focus on the toggle, and every nav item keeps its accessible name, so nothing a screen reader user relies on moves.
+
+### Keyboard
+
+| Key                                 | Action                                           |
+| ----------------------------------- | ------------------------------------------------ |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Collapses or expands the sidebar                 |
+| <kbd>Escape</kbd>                   | Hides the tooltip while it shows                 |
+| <kbd>Tab</kbd>                      | Moves on to the next control, hiding the tooltip |
+
+## Inputs
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Height step: sm 32, md 40, lg 48 px (square); unset follows `provideBfDefaults()` (`controlSize`, `md` by default). |
+
+## Slots
+
+- `collapse-icon`: The icon shown while the sidebar is expanded (a panel closing).
+- `expand-icon`: The icon shown while the sidebar is an icon rail (a panel opening).
+
+## Notes
+
+### Do
+
+- Put the toggle inside the `bf-sidebar` it collapses, in its header or footer.
+- Project both icon slots, a panel closing and a panel opening.
+- Bind the sidebar to `BfSidebarStateService.collapsed` with `provideBfSidebarState()`, so the choice survives a reload.
+
+### Don't
+
+- Don't put it outside a `bf-sidebar`; it renders nothing there. Use a `bf-icon-button` bound to `[(collapsed)]` instead.
+- Don't add your own `aria-label` or tooltip; the toggle names itself by what the next press does.
+
+## Migration notes
+
+### 0.3.2
+
+New `bf-sidebar-toggle` in `@bitforgehq/ui/overlay`: a text icon button placed inside a
+`bf-sidebar` (header or footer) that flips the sidebar between full width and an icon rail by
+writing its `collapsed` model, so `[(collapsed)]` sees every press. Its name and `bfTooltip` say
+what the next press does (new label keys `sidebarCollapse` "Collapse sidebar" and `sidebarExpand`
+"Expand sidebar"); `aria-expanded` follows the sidebar and `aria-controls` points at its `nav`.
+Icons are the `collapse-icon` and `expand-icon` slots, only the matching one shown; `size` as
+`bf-icon-button`. Outside a sidebar (in a `bf-top-nav`, or alone) it renders nothing. A
+`BfSidebarToggleHarness` in `@bitforgehq/ui/testing` (`getLabel()`, `isExpanded()`, `toggle()`).
+
+---
+
 # bf-skeleton
 
 Loading placeholder shaped as text lines, a rectangle or a circle, with a shimmer
@@ -21745,7 +22721,7 @@ Use `bf-stat` for a few headline figures the reader should take in at a glance,
 
 ## Cards
 
-`variant="card"` gives each stat its own outlined tile, the `flat` card surface. In a grid the cards stretch to the row's height, so a row of stats lines up even when one has a supporting line and another has none. Put an icon in the `icon` slot (`bfSlot="icon"`, a `bf-icon`) to show what the figure is about.
+`variant="card"` gives each stat its own outlined tile, the `flat` card surface, for stats that sit on the page itself; inside a raised card use `tile` instead. In a grid the cards stretch to the row's height, so a row of stats lines up even when one has a supporting line and another has none. Put an icon in the `icon` slot (`bfSlot="icon"`, a `bf-icon`) to show what the figure is about.
 
 ```ts
 import { Component } from '@angular/core';
@@ -21787,6 +22763,60 @@ export class StatOverviewExampleComponent {
 }
 ```
 
+## Tiles
+
+`variant="tile"` is a sunken, borderless tile (`surface-sunken`, the `card` radius and padding) for a row of stats inside a raised [bf-card](https://bitforge-ui.web.app/components/card): a raised card holds sunken tiles, never outlined ones. On a tile the icon tile turns `surface`, so it still shows. Keep one surface style per level of a dashboard: raised cards on the page, tiles in each card.
+
+```ts
+import { Component } from '@angular/core';
+import { BfCardComponent, BfStatComponent } from '@bitforgehq/ui';
+
+/**
+ * A dashboard with one surface per level.
+ *
+ * The page holds raised cards, and every card holds sunken stat tiles: each level has one surface
+ * style, so the eye reads the cards as the groups and the tiles as their figures.
+ */
+@Component({
+  selector: 'app-example-stat-dashboard',
+  imports: [BfCardComponent, BfStatComponent],
+  template: `
+    <div class="grid gap-4 @lg:grid-cols-2">
+      <bf-card>
+        <h3 class="text-heading">Sales</h3>
+        <div class="grid grid-cols-[repeat(auto-fit,minmax(9rem,1fr))] gap-3">
+          <bf-stat label="Revenue" value="€48,200" variant="tile" delta="+12%" trend="up">
+            vs. last month
+          </bf-stat>
+          <bf-stat label="Orders" value="1,204" variant="tile" delta="+3%" trend="up">
+            vs. last month
+          </bf-stat>
+        </div>
+      </bf-card>
+      <bf-card>
+        <h3 class="text-heading">Support</h3>
+        <div class="grid grid-cols-[repeat(auto-fit,minmax(9rem,1fr))] gap-3">
+          <bf-stat
+            label="Open tickets"
+            value="18"
+            variant="tile"
+            delta="-4"
+            trend="down"
+            trendIntent="negative"
+          >
+            vs. last week
+          </bf-stat>
+          <bf-stat label="First reply" value="2 h" variant="tile" delta="0" trend="flat">
+            vs. last week
+          </bf-stat>
+        </div>
+      </bf-card>
+    </div>
+  `,
+})
+export class StatDashboardExampleComponent {}
+```
+
 ## Plain
 
 `variant="plain"` (the default) draws no surface, for stats that sit on a card or a page section of their own. The default slot is the supporting line under the value: a short trend ("+12% this week") or a `bf-badge`.
@@ -21866,8 +22896,9 @@ A stat is not interactive: no hover, no pointer cursor, no focus stop. Its size
 - Label (`dt`): `text-caption` in `text-muted`. Value (`dd`): `text-title` in `text`, with tabular figures (`tabular-nums`) so numbers line up across stats.
 - Supporting line: `text-caption` in `text-muted`.
 - Delta pill: the badge's label shape (`control` radius, `text-micro` bold, tabular figures); good changes `success-soft` with `success` text, bad ones `danger-soft` with `danger` text, flat or no trend `neutral-soft` with `neutral` text. The arrow mark is drawn with borders in `currentColor`, so it takes the pill's text colour.
-- Icon tile: `surface-sunken` background, `text-muted` icon, `tile` radius, 40 px.
+- Icon tile: `surface-sunken` background (`surface` on a `tile` stat), `text-muted` icon, `tile` radius, 40 px.
 - `card`: `surface`, the `card` radius, `--spacing-card` padding (`p-card`) and a 1.5 px `border-strong` edge, as the `flat` `bf-card`.
+- `tile`: `surface-sunken`, the `card` radius and `--spacing-card` padding, no border.
 
 ## Accessibility
 
@@ -21879,7 +22910,7 @@ A stat is not interactive: no hover, no pointer cursor, no focus stop. Its size
 | --- | --- | --- | --- |
 | `label` | `string` | required | What the figure measures, shown above it. |
 | `value` | `string` | required | The figure, already formatted (`45 min`, `1,204`, `98%`). |
-| `variant` | `BfStatVariant` (`'plain' \| 'card'`) | `'plain'` | Surface: plain (default) on its container, or card, an outlined tile of its own. |
+| `variant` | `BfStatAppearance` (`'plain' \| 'card' \| 'tile'`) | `'plain'` | Surface: plain (default) on its container, card (an outlined tile) or tile (sunken, no border). |
 | `delta` | `string` | `''` | A change shown in a pill beside the value, already formatted (`+12%`); empty shows none. |
 | `trend` | `BfStatTrend \| undefined` (`'up' \| 'down' \| 'flat' \| undefined`) | `undefined` | The delta's direction: an arrow mark and a hidden word; left unset, the pill is neutral. |
 | `trendIntent` | `BfStatTrendIntent` (`'positive' \| 'negative'`) | `'positive'` | Whether up is good (positive, default) or down is good (negative, such as costs). |
@@ -21899,12 +22930,21 @@ A stat is not interactive: no hover, no pointer cursor, no focus stop. Its size
 
 ### Don't
 
+- Don't put `card` stats (outlined) inside a raised `bf-card`; use `tile`.
 - Don't use a stat for a value the user edits or acts on; give it its own control.
 - Don't put long text in `value`; it is set at the `title` size for a short figure.
 - Don't put the comparison period in `delta`; keep it to the change (`+12%`) and say "vs. last month" in the supporting line.
 
 ## Migration notes
 
+### 0.3.2
+
+New `variant="tile"`: a sunken, borderless tile (`surface-sunken`, the `card` radius and
+padding) for a row of stats inside a raised `bf-card`; on it the icon tile turns `surface`.
+`variant` now takes the new named type `BfStatAppearance` (`BfStatVariant | 'tile'`); the
+released `BfStatVariant` keeps its two members, so `Record`s over it keep compiling. New
+`stat/dashboard` example with one surface per level.
+
 ### 0.3.1
 
 New: `bf-stat`, one labelled figure in its own `dl`, with the value at the `title` size in
@@ -23146,13 +24186,14 @@ export class TableOverviewExampleComponent {
 
 Data table for desktop: column headers that set a sort, optional row selection with
 checkboxes, custom cells from `bfTableCell` templates and an empty slot. It never sorts or
-filters itself; the consumer sorts the rows in a `computed()` from `sort`.
+filters itself; the consumer sorts the rows in a `computed()` from `sort`. With `stack` it
+renders each row as a tile of label/value pairs in a narrow space or under touch.
 
 A data table for desktop pages: rows of records the user compares across columns, with headers that sort, an optional checkbox column that selects rows, custom cells and an empty state. `bf-table` is data-driven: you pass `rows` and `columns`, and it never sorts or filters the rows itself. Its headers set the `sort` model and you sort the rows in a `computed()`, on the client or on the server.
 
 ## When to use
 
-Use `bf-table` on a desktop page for records the user scans and compares column by column: tasks, invoices, members. On a phone or in the Capacitor shell use [bf-list](https://bitforge-ui.web.app/components/list) rows instead. Use a [bf-list](https://bitforge-ui.web.app/components/list) on desktop too when each record is one line of text with a status, and a description list for the fields of a single record.
+Use `bf-table` on a desktop page for records the user scans and compares column by column: tasks, invoices, members. On a phone or in the Capacitor shell use [bf-list](https://bitforge-ui.web.app/components/list) rows instead, or let the table stack its rows into tiles with `stack` (see Stacked rows). Use a [bf-list](https://bitforge-ui.web.app/components/list) on desktop too when each record is one line of text with a status, and a description list for the fields of a single record.
 
 ## Columns and rows
 
@@ -23443,9 +24484,115 @@ export class TablePagedExampleComponent {
 
 `size` sets the row height: `sm` 40 px, `md` 48 px (default), `lg` 56 px, with a 32, 40 or 48 px header. Unset, it follows `provideBfDefaults()`'s `controlSize`, so `{ size: 'sm' }` in a page's `providers` makes a dense table. The checkboxes take the same step. Under a coarse pointer every row is at least 44 px tall, and the sortable header buttons are 44 px targets; a cell grows to fit its content and is never covered by a hit-area extension.
 
+## Stacked rows
+
+`stack` lets the table itself fit a narrow space. With `stack="narrow"` it stacks while the table is narrower than 36rem (576 px at the default root size, Tailwind's `xl` container size): a container query on the table's own width, so a table in a narrow column or a side panel stacks even on a wide screen. The host is then a size container (`container-type: inline-size`), so give the table its width from its parent (a block or `w-full` / `flex-1`), not from its columns. With `stack="coarse"` it stacks under a coarse pointer at any width (phones, tablets, the Capacitor shell). The default `never` keeps the table as it is.
+
+Stacked, each row is a sunken tile (`surface-sunken`, `rounded-tile`, the tile a raised card holds; a selected row keeps `primary-soft`). Its checkbox and first cell head the tile in bold; every other cell shows its column label at the start and its value at the end. The header row is visually hidden, and a bar above the tiles holds a labelled Select all checkbox (with `selectable`) and a Sort by select of every sortable column, ascending and descending (`tableSortBy`, `tableSortAscending`, `tableSortDescending` labels), since the hidden header's buttons are not shown. Choosing an option sets `sort`, as a header click does.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import {
+  BfBadgeComponent,
+  BfSegmentedComponent,
+  BfTableCellDirective,
+  BfTableComponent,
+  type BfSegmentOption,
+  type BfTableColumn,
+  type BfTableSort,
+} from '@bitforgehq/ui';
+
+interface Task {
+  id: string;
+  title: string;
+  project: string;
+  status: 'Open' | 'Done';
+  hours: number;
+}
+
+const TASKS: readonly Task[] = [
+  { id: 'brief', title: 'Write the brief', project: 'Atlas', status: 'Done', hours: 3 },
+  { id: 'moodboard', title: 'Bloom moodboard', project: 'Bloom', status: 'Open', hours: 6 },
+  { id: 'deck', title: 'Pitch deck', project: 'Atlas', status: 'Open', hours: 9 },
+];
+
+type Width = 'phone' | 'full';
+
+/**
+ * Stacked rows on a narrow table.
+ *
+ * `stack="narrow"` turns each row into a tile of label/value pairs while the table is narrower
+ * than 36rem: the selection checkbox and the first cell head the tile, and a bar above the tiles
+ * holds Select all and a Sort by select. Switch the box between phone width and full width.
+ */
+@Component({
+  selector: 'app-example-table-stacked',
+  imports: [BfTableComponent, BfTableCellDirective, BfBadgeComponent, BfSegmentedComponent],
+  template: `
+    <!-- A stacking table is a size container: its width comes from its parent, never its columns. -->
+    <div class="flex w-152 max-w-full flex-col gap-3">
+      <bf-segmented label="Box width" [options]="widths" [(value)]="width" />
+      <div [class]="width() === 'phone' ? 'w-full max-w-sm' : 'w-full'">
+        <bf-table
+          label="Stacked tasks"
+          stack="narrow"
+          selectable
+          [rows]="rows()"
+          [columns]="columns"
+          [(sort)]="sort"
+          [(selection)]="selection"
+        >
+          <ng-template bfTableCell="status" [bfTableCellOf]="rows()" let-task>
+            <bf-badge [variant]="task.status === 'Done' ? 'success' : 'neutral'">
+              {{ task.status }}
+            </bf-badge>
+          </ng-template>
+        </bf-table>
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TableStackedExampleComponent {
+  readonly widths: BfSegmentOption<Width>[] = [
+    { value: 'phone', label: 'Phone' },
+    { value: 'full', label: 'Full width' },
+  ];
+  readonly width = signal<Width | null>('phone');
+  readonly columns: readonly BfTableColumn[] = [
+    { key: 'title', label: 'Task', sortable: true },
+    { key: 'project', label: 'Project' },
+    { key: 'status', label: 'Status' },
+    { key: 'hours', label: 'Hours', sortable: true, align: 'end' },
+  ];
+  readonly sort = signal<BfTableSort | null>(null);
+  readonly selection = signal<readonly string[]>([]);
+
+  /** The table never sorts: the page sorts its rows from `sort`. */
+  readonly rows = computed(() => {
+    const sort = this.sort();
+    if (!sort) {
+      return TASKS;
+    }
+    const factor = sort.direction === 'ascending' ? 1 : -1;
+    return [...TASKS].sort((a, b) =>
+      sort.column === 'hours'
+        ? (a.hours - b.hours) * factor
+        : a.title.localeCompare(b.title) * factor,
+    );
+  });
+
+  readonly status = computed(() => {
+    const sort = this.sort();
+    const sorted = sort ? `Sorted by ${sort.column}, ${sort.direction}` : 'Unsorted';
+    return `${sorted} · ${this.selection().length} selected.`;
+  });
+}
+```
+
 ## Narrow screens and touch
 
-A table needs width. Below the `md` breakpoint, render the same rows as a divided `bf-list` of `bf-list-item`s (a `md:hidden` wrapper) and the table only from `md` up (a `hidden md:block` wrapper), from the one `rows` array. Inside the Capacitor shell use the list alone. The table's wrapper scrolls sideways when its columns cannot fit, but that is a last resort, not a layout for phones.
+A table needs width. When stacked tiles are not what a phone should show (long records, a summary per row), render the same rows as a divided `bf-list` of `bf-list-item`s below the `md` breakpoint (a `md:hidden` wrapper) and the table only from `md` up (a `hidden md:block` wrapper), from the one `rows` array. Inside the Capacitor shell use the list alone, or a table with `stack="coarse"`. The table's wrapper scrolls sideways when its columns cannot fit, but that is a last resort, not a layout for phones.
 
 ```ts
 import { Component } from '@angular/core';
@@ -23514,6 +24661,7 @@ A selectable table tints a row `surface-muted` while hovered (a selected row `pr
 - Rows: `text` on the page's surface, divided by `border` lines; hover (selectable only) `surface-muted`; selected `primary-soft`, hover `primary-soft-hover`.
 - Sort arrow: a 1.5 px CSS chevron in the header's text colour.
 - Focus ring: `ring`. Header buttons: `rounded-field`.
+- Stacked rows: tiles on `surface-sunken` with `rounded-tile`, labels `text-label-xs` bold in `text-muted`.
 - Text: `text-body` (`text-label-sm` at `sm`), `tabular-nums` in `end` columns.
 
 Put the table on a `bf-card` (or another surface) yourself; it has no background or border of its own.
@@ -23522,6 +24670,8 @@ Put the table on a `bf-card` (or another surface) yourself; it has no background
 
 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 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) / ""`), so a screen reader reads the column header once, not the label as well.
+
 ### Keyboard
 
 | Key                                              | Action                                                                                                                                                                      |
@@ -23532,6 +24682,8 @@ A native `table` with a visually hidden `caption` from `label`, `th scope="col"`
 | <kbd>Space</kbd>                                 | Toggles the focused checkbox, or sorts by the focused header                                                                                                                |
 | <kbd>Enter</kbd>                                 | Sorts by the focused header                                                                                                                                                 |
 
+A stacked table's Sort by select is a native select with its own keys.
+
 Text fields, selects and composite widgets (radios, comboboxes, sliders) in a cell keep their own arrow keys.
 
 ## Inputs
@@ -23545,6 +24697,7 @@ Text fields, selects and composite widgets (radios, comboboxes, sliders) in a ce
 | `selectable` | `boolean` | `false` | Adds a first column of checkboxes that select rows. |
 | `selectAllLabel` | `string` | `''` | Accessible name of the header checkbox; empty falls back to `provideBfLabels()`'s `tableSelectAll` ("Select all rows"). |
 | `size` | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Row height step: sm 40, md 48, lg 56 px (the header 32/40/48; at least 44 px under a coarse pointer); unset follows `provideBfDefaults()` (`controlSize`, `md` by default). |
+| `stack` | `BfTableStack` (`'never' \| 'narrow' \| 'coarse'`) | `'never'` | When the rows render as cards of label/value pairs: `never`, `narrow` (the table is narrower than 36rem) or `coarse` (under a coarse pointer, at any width). |
 | `sort` | `BfTableSort \| null` | `null` | The sorted column and direction, `null` while unsorted; two-way bindable. A sortable header sets it, and the consumer sorts `rows` from it. Two-way: `[(sort)]`. |
 | `selection` | `readonly string[]` | `[]` | The keys (`rowKey`) of the selected rows; two-way bindable. Two-way: `[(selection)]`. |
 
@@ -23585,15 +24738,31 @@ Selects or clears one row.
 
 - Give every table a `label`, and every sortable column a short header.
 - Sort and filter the rows in a `computed()` from `sort` and your filters.
-- Render the rows as `bf-list-item`s below `md` and inside the Capacitor shell.
+- 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`.
 
 ### Don't
 
-- Don't put a table on a phone screen that scrolls sideways; use the list.
+- Don't put a table on a phone screen that scrolls sideways; stack it or use the list.
+- Don't put a stacking table in a parent that sizes it from its content: the container query needs a width from outside.
 - Don't make a whole row clickable; put a link or button in a custom cell.
 
 ## Migration notes
 
+### 0.3.2
+
+New opt-in `stack` input (`BfTableStack`: `'never'` by default, so existing tables do not
+change, `'narrow'` or `'coarse'`): while the table is narrower than 36rem (a container query on
+the host, which then gets `@container`) or, for `'coarse'`, under a coarse pointer at any width,
+each body row renders as a sunken tile of label/value pairs. The markup stays a `table` with
+explicit `table`, `rowgroup`, `row`, `columnheader` and `cell` roles (some browsers drop a
+table's semantics once its display changes), the header row is visually hidden but still read,
+the selection checkbox and the first cell head each tile, and every other cell shows its column
+label (`data-label`, a `::before` with empty alternative text, so it is not read twice). A bar
+above the tiles holds a labelled Select all checkbox and a Sort by `bf-select`, since the hidden
+header's controls are not shown. New label keys `tableSortBy` ("Sort by"), `tableSortAscending`
+and `tableSortDescending` (`"Hours, ascending"`). `BfTableHarness` reads and drives a stacked
+table the same way. New `table/stacked` example and a Stacked rows docs section.
+
 ### 0.3.1
 
 New `bf-table` and `ng-template[bfTableCell]` (`BfTableCellDirective`) in `@bitforgehq/ui`, a
@@ -23808,7 +24977,7 @@ 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 [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). 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';
@@ -23979,6 +25148,10 @@ 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
@@ -26142,7 +27315,7 @@ export class ToolbarStatusExampleComponent {
 
 ## Wrapping
 
-The row is a wrapping flex row with an 8 px gap between items and between rows. In a narrow column the filters wrap onto new rows, and the actions wrap as one group, kept together at the inline end. Give a search field a width (`class="w-full sm:w-56"`) so it fills a phone-wide row and stays compact on a wide one.
+The row is a wrapping flex row with an 8 px gap between items and between rows. The status and the actions are one group that takes the rest of the last row: on a wide row the status follows the view switch and the actions sit at the inline end; when the group no longer fits beside the filters, it wraps onto a row of its own as a whole, with the status at the start and the actions at the end. So the actions never end up alone on a row, and they stay on the last filter row whenever the group fits there. Give a search field a width (`class="w-full sm:w-56"`) so it fills a phone-wide row and stays compact on a wide one.
 
 ```ts
 import { Component } from '@angular/core';
@@ -26157,8 +27330,8 @@ import {
 /**
  * A toolbar that wraps.
  *
- * In a narrow column the filters wrap onto new rows 8 px apart, and the actions move down
- * together, still at the inline end.
+ * In a narrow column the filters wrap onto new rows 8 px apart, and the status and the actions
+ * move down together: the count at the start of the last row, the actions at the inline end.
  */
 @Component({
   selector: 'app-example-toolbar-wrapping',
@@ -26187,6 +27360,63 @@ export class ToolbarWrappingExampleComponent {
 }
 ```
 
+## Phone width
+
+At phone width (in a desktop web app's narrow window or a narrow column) the search takes a row, the filters share the next, and the status and actions share the last row. A toolbar without actions keeps the status as a plain item after the filters.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfButtonComponent,
+  BfInputComponent,
+  BfSelectComponent,
+  BfToolbarComponent,
+  type BfSelectOption,
+} from '@bitforgehq/ui';
+
+/**
+ * A toolbar at phone width.
+ *
+ * In a phone-wide column the search fills its own row, the two filters share the next one, and
+ * the status and the Refresh action share the last row: the count at the start, the action at the
+ * end, never alone on a row of its own.
+ */
+@Component({
+  selector: 'app-example-toolbar-narrow',
+  imports: [BfButtonComponent, BfInputComponent, BfSelectComponent, BfToolbarComponent],
+  template: `
+    <div class="max-w-xs">
+      <bf-toolbar label="Order filters" [status]="count()">
+        <bf-input
+          type="search"
+          ariaLabel="Search orders"
+          placeholder="Search orders"
+          class="w-full"
+        />
+        <bf-select ariaLabel="Status" [options]="statuses" value="open" />
+        <bf-select ariaLabel="Period" [options]="periods" value="week" />
+        <bf-button bfSlot="actions" variant="outline" (clicked)="refresh()">Refresh</bf-button>
+      </bf-toolbar>
+    </div>
+  `,
+})
+export class ToolbarNarrowExampleComponent {
+  protected readonly count = signal('12 orders');
+  protected readonly statuses: BfSelectOption[] = [
+    { value: 'open', label: 'Open' },
+    { value: 'shipped', label: 'Shipped' },
+  ];
+  protected readonly periods: BfSelectOption[] = [
+    { value: 'week', label: 'This week' },
+    { value: 'month', label: 'This month' },
+  ];
+
+  protected refresh(): void {
+    this.count.set('12 orders, updated');
+  }
+}
+```
+
 ## Desktop
 
 `bf-toolbar` is a desktop pattern. Every control and field projected into it resolves its unset `size` to `sm` (32 px tall), because its `providers` set `provideBfDefaults({ size: 'sm' })` for its content; a control that sets `size` itself keeps it, and nothing outside the toolbar changes ([density guide](https://bitforge-ui.web.app/density)). Hover, the pointer cursor and the `focus-visible` ring come from each control; the row adds none of its own. Under a fine pointer each control's visual box is its hit area; under a coarse pointer the `sm` touch extensions reach up to 7.5 px past the visual edge, which the 8 px gap keeps off the neighbouring row.
@@ -26217,7 +27447,7 @@ The `status` element is `role="status"` (an `aria-live="polite"` region), always
 
 - `default`: The search field and the filters (bf-input, bf-select, bf-chip-group), in order.
 - `view`: A view switch after the filters, such as a bf-segmented of list and grid.
-- `actions`: The trailing actions, kept together at the inline end of the row.
+- `actions`: The trailing actions, kept together at the inline end of the row, beside the status.
 
 ## Notes
 
@@ -26233,6 +27463,14 @@ The `status` element is `role="status"` (an `aria-live="polite"` region), always
 
 ## Migration notes
 
+### 0.3.2
+
+On a narrow row the actions no longer end up alone on a row of their own: the status and the
+actions are now one group that takes the rest of the last row and wraps as a whole, with the
+status at the start and the actions at the inline end. The wide layout is unchanged, and a
+toolbar without actions keeps the status as a plain item of the row. New `toolbar/narrow`
+example at phone width.
+
 ### 0.3.1
 
 New `bf-toolbar` in `@bitforgehq/ui`: a wrapping `role="group"` row for the search field and
@@ -26759,6 +27997,29 @@ const BF_LABELS: InjectionToken<BfLabels>
 
 ---
 
+# BF_SIDEBAR_STATE_STORAGE
+
+Injection token for the store that keeps the collapsed sidebar between visits
+
+Injection token from `@bitforgehq/ui` · since 0.3.2
+
+Where `BfSidebarStateService` keeps whether the sidebar is collapsed (the key
+`bf-sidebar-collapsed`, `'true'` or `'false'`): `localStorage` when it is available, otherwise
+an in-memory map. Provide another store (`sessionStorage`, or an in-memory one in tests) to keep
+it elsewhere.
+
+```ts
+import { BF_SIDEBAR_STATE_STORAGE } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+const BF_SIDEBAR_STATE_STORAGE: InjectionToken<Pick<Storage, "getItem" | "setItem">>
+```
+
+---
+
 # BF_TAB_BAR
 
 Injection token through which each tab reaches its enclosing tab bar
@@ -26886,6 +28147,68 @@ type BfAlertVariant = 'neutral' | 'success' | 'warning' | 'danger'
 
 ---
 
+# BfAppFrameBreakpoint
+
+The breakpoint where an app frame switches from its header bar to the sidebar
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The viewport width from which `bf-app-frame` shows its sidebar column instead of the narrow
+header bar: Tailwind's `md` (768 px) or `lg` (1024 px).
+
+```ts
+import { type BfAppFrameBreakpoint } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfAppFrameBreakpoint = 'md' | 'lg'
+```
+
+## Values
+
+- `md`
+- `lg`
+
+## Used by
+
+- [bf-app-frame](../components/app-frame.md)
+
+---
+
+# BfAppFrameContentWidth
+
+The maximum width of an app frame's content column, from medium to full
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The maximum width of `bf-app-frame`'s content column: `md` 48rem, `lg` 64rem, `xl` 80rem, or
+`full` for no limit.
+
+```ts
+import { type BfAppFrameContentWidth } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfAppFrameContentWidth = 'md' | 'lg' | 'xl' | 'full'
+```
+
+## Values
+
+- `md`
+- `lg`
+- `xl`
+- `full`
+
+## Used by
+
+- [bf-app-frame](../components/app-frame.md)
+
+---
+
 # BfAutocapitalize
 
 How a phone keyboard capitalises the text typed into a field
@@ -27555,6 +28878,42 @@ type BfDescriptionListLayout = 'rows' | 'grid'
 
 ---
 
+# BfEmptyStateHeading
+
+The heading level of an empty state title, one for a whole page
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The heading level a `bf-empty-state` title takes: a `BfEmptyStateHeadingLevel`, or `1` when the
+empty state is the page itself (a not-found or no-access page). A new type, so `Record`s over
+the released `BfEmptyStateHeadingLevel` keep compiling.
+
+```ts
+import { type BfEmptyStateHeading } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfEmptyStateHeading = BfEmptyStateHeadingLevel | 1
+```
+
+## Values
+
+- `2`
+- `3`
+- `1`
+
+## Uses
+
+- [BfEmptyStateHeadingLevel](bf-empty-state-heading-level.md)
+
+## Used by
+
+- [bf-empty-state](../components/empty-state.md)
+
+---
+
 # BfEmptyStateHeadingLevel
 
 The heading level of an empty state title, two for a screen or three
@@ -27580,7 +28939,7 @@ type BfEmptyStateHeadingLevel = 2 | 3
 
 ## Used by
 
-- [bf-empty-state](../components/empty-state.md)
+- [BfEmptyStateHeading](bf-empty-state-heading.md)
 
 ---
 
@@ -27975,6 +29334,9 @@ import { type BfLabels } from '@bitforgehq/ui';
 | `dialog` | `string` | `'Dialog'` | A dialog's or side panel's name without an ariaLabel, a title or a heading. |
 | `notifications` | `string` | `'Notifications'` | The desktop toast stack's region name. |
 | `tableSelectAll` | `string` | `'Select all rows'` | bf-table's header checkbox, which selects or clears every row. |
+| `tableSortBy` | `string` | `'Sort by'` | The label of a stacked bf-table's sort select. |
+| `tableSortAscending` | `(column: string) => string` | `` (column) => `${column}, ascending` `` | A stacked bf-table's sort option for a column in ascending order. |
+| `tableSortDescending` | `(column: string) => string` | `` (column) => `${column}, descending` `` | A stacked bf-table's sort option for a column in descending order. |
 | `theme` | `string` | `'Theme'` | bf-theme-switch's and bf-theme-menu-button's name without a label. |
 | `themeSystem` | `string` | `'System'` | The theme choice that follows the system's colour scheme. |
 | `themeLight` | `string` | `'Light'` | The theme choice that forces the light colour scheme. |
@@ -27983,6 +29345,9 @@ import { type BfLabels } from '@bitforgehq/ui';
 | `breadcrumbExpand` | `(count: number) => string` | `` (count) => (count === 1 ? 'Show 1 more level' : `Show ${count} more levels`) `` | bf-breadcrumb's ellipsis button, which shows the levels a `maxItems` trail hides. |
 | `navigation` | `string` | `'Main'` | bf-sidebar's and bf-top-nav's navigation name. |
 | `navBadge` | `(count: number) => string` | `` (count) => `${count} new` `` | a[bfNavItem]'s announcement of its count badge. |
+| `sidebarCollapse` | `string` | `'Collapse sidebar'` | bf-sidebar-toggle's name and tooltip while the sidebar is expanded. |
+| `sidebarExpand` | `string` | `'Expand sidebar'` | bf-sidebar-toggle's name and tooltip while the sidebar is an icon rail. |
+| `skipToContent` | `string` | `'Skip to main content'` | bf-app-frame's skip link, the first stop of the tab order, which moves focus to the content. |
 | `pagination` | `string` | `'Pagination'` | bf-pagination's navigation name. |
 | `previousPage` | `string` | `'Previous page'` | bf-pagination's button to the previous page. |
 | `nextPage` | `string` | `'Next page'` | bf-pagination's button to the next page. |
@@ -28311,6 +29676,30 @@ interface BfSelectOption<T = string>
 
 ---
 
+# BfSidebarStateService
+
+The sidebar's collapsed state, kept in storage between visits of the app
+
+Service from `@bitforgehq/ui` · since 0.3.2
+
+Whether the app's `bf-sidebar` is collapsed to an icon rail, remembered between visits: the app
+binds the sidebar's `[(collapsed)]` to `sidebarState.collapsed`. With `provideBfSidebarState()`
+every change is stored in `BF_SIDEBAR_STATE_STORAGE` under `bf-sidebar-collapsed`; without it
+the signal still holds the state but nothing is written. Storage is read in the browser only, so a
+server render starts expanded and writes nothing. The widgets never inject it.
+
+```ts
+import { BfSidebarStateService } from '@bitforgehq/ui';
+```
+
+## Properties
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `collapsed` | `WritableSignal<boolean>` |  | Whether the sidebar is collapsed: the stored state in the browser, else false. Bind it two-way to `bf-sidebar`'s `collapsed`. |
+
+---
+
 # BfSize
 
 The three height steps every sized field and control shares
@@ -28361,6 +29750,7 @@ type BfSize = 'sm' | 'md' | 'lg'
 - [bf-segmented](../components/segmented.md)
 - [BfSegmentedSize](bf-segmented-size.md)
 - [bf-select](../components/select.md)
+- [bf-sidebar-toggle](../components/sidebar-toggle.md)
 - [bf-tab-group](../components/tab-group.md)
 - [bf-table](../components/table.md)
 - [bf-textarea](../components/textarea.md)
@@ -28432,6 +29822,42 @@ type BfSpinnerSize = 'sm' | 'md' | 'lg'
 
 ---
 
+# BfStatAppearance
+
+The three stat surfaces, plain, an outlined card or a sunken tile
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The surface of a `bf-stat`, as its `variant` input takes it: a `BfStatVariant` or tile (a
+sunken, borderless tile for a stats row inside a raised card). A new type, so `Record`s over
+the released `BfStatVariant` keep compiling.
+
+```ts
+import { type BfStatAppearance } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfStatAppearance = BfStatVariant | 'tile'
+```
+
+## Values
+
+- `plain`
+- `card`
+- `tile`
+
+## Uses
+
+- [BfStatVariant](bf-stat-variant.md)
+
+## Used by
+
+- [bf-stat](../components/stat.md)
+
+---
+
 # BfStatTrend
 
 The three directions of a stat's delta pill, up, down or no change
@@ -28517,7 +29943,7 @@ type BfStatVariant = 'plain' | 'card'
 
 ## Used by
 
-- [bf-stat](../components/stat.md)
+- [BfStatAppearance](bf-stat-appearance.md)
 
 ---
 
@@ -28825,6 +30251,38 @@ type BfTableSortDirection = 'ascending' | 'descending'
 
 ---
 
+# BfTableStack
+
+When a table stacks its rows into cards: never, when narrow, or under touch
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+When a `bf-table` renders each row as a card of label/value pairs: `never` (the default),
+`narrow` while the table is narrower than 36rem (a container query), or `coarse` under a coarse
+pointer at any width.
+
+```ts
+import { type BfTableStack } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfTableStack = 'never' | 'narrow' | 'coarse'
+```
+
+## Values
+
+- `never`
+- `narrow`
+- `coarse`
+
+## Used by
+
+- [bf-table](../components/table.md)
+
+---
+
 # BfTabLinks
 
 The URLs a router-aware parent gives a tab bar to render its tabs as links
@@ -29032,9 +30490,10 @@ Function from `@bitforgehq/ui` · since 0.3.0
 Replaces built-in strings, merged over the parent's (validation merged key by key); a key left
 out or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers
 every string. In a component's `providers` it covers that sub-tree's widgets and form controls
-(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `theme`,
-`themeSystem`, `themeLight`, `themeDark`, `breadcrumb`, `breadcrumbExpand`, `navigation`,
-`navBadge`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,
+(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,
+`tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,
+`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,
+`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,
 `calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,
 `statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,
 `dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,
@@ -29072,6 +30531,29 @@ function provideBfLabels(overrides: BfLabelsOverrides): Provider
 
 ---
 
+# provideBfSidebarState
+
+Remembers the collapsed sidebar between visits, for desktop web apps
+
+Function from `@bitforgehq/ui` · since 0.3.2
+
+Lets `BfSidebarStateService` remember the collapsed sidebar: it stores every change of its
+`collapsed` signal (key `bf-sidebar-collapsed`, `localStorage` in the browser), so the app opens
+with the sidebar as the user left it. Add it to `ApplicationConfig.providers` and bind the
+sidebar's `[(collapsed)]` to `sidebarState.collapsed`.
+
+```ts
+import { provideBfSidebarState } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+function provideBfSidebarState(): EnvironmentProviders
+```
+
+---
+
 # BF_DESKTOP_TOAST_DEFAULTS
 
 The library defaults of the desktop toast settings, bottom end with three visible
@@ -35794,6 +37276,41 @@ Blurs the native select, which marks a bound form field touched.
 
 ---
 
+# BfSidebarToggleHarness
+
+Test harness for a sidebar toggle: reads and flips the collapsed sidebar
+
+Class from `@bitforgehq/ui/testing` · since 0.3.2
+
+Harness for `bf-sidebar-toggle`, the button that collapses a `bf-sidebar` to an icon rail. Its
+`label` filter matches the button's name ("Collapse sidebar" or "Expand sidebar").
+
+```ts
+import { BfSidebarToggleHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfSidebarToggleHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The button's name, which says what the next press does.
+
+### `isExpanded(): Promise<boolean>`
+
+Whether the sidebar is at full width (`aria-expanded`).
+
+### `toggle(): Promise<void>`
+
+Flips the sidebar with a click.
+
+---
+
 # BfSidePanelHarness
 
 Test harness for a side panel: its title, its close button and its state
@@ -35886,7 +37403,7 @@ Class from `@bitforgehq/ui/testing` · since 0.3.1
 
 Harness for `bf-table`. It works by column header text and row position, so a test never needs
 the column keys or the row keys (except `getSort()`, which returns the column's `key`, as the
-`sort` model holds it).
+`sort` model holds it). It reads and drives a stacked table (`stack`) the same way.
 
 ```ts
 import { BfTableHarness } from '@bitforgehq/ui/testing';