@bitforgehq/ui 0.3.1 → 0.3.3

package/ai/UI_GUIDE.md

@@ -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`)
 
@@ -1228,27 +1252,29 @@ notes.
 
 ### Navigation
 
-| Component              | Entry point             | Purpose                                                                                     |
-| ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
-| `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                        |
-| `bf-content`           | `@bitforgehq/ui/mobile` | Page's single scroll container that keeps focused fields clear of the soft keyboard         |
-| `bf-header`            | `@bitforgehq/ui/mobile` | Page header toolbar with a large title that collapses into the toolbar on scroll            |
-| `bf-nav-group`         | `@bitforgehq/ui`        | A titled group of sidebar links with a small heading that names it                          |
-| `a[bfNavItem]`         | `@bitforgehq/ui`        | Navigation link for a sidebar or top nav, with icon, label and count                        |
-| `bf-page`              | `@bitforgehq/ui/mobile` | Frame for one stacked mobile screen that supplies lifecycle events and shared page state    |
-| `bf-page-header`       | `@bitforgehq/ui`        | Desktop page header with breadcrumb, title, subtitle, badges and a row of actions           |
-| `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-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             |
-| `bf-tab-group`         | `@bitforgehq/ui`        | In-page tabs that switch between content panels, with keyboard navigation and badges        |
-| `bf-tab-panel`         | `@bitforgehq/ui`        | One tab of a tab group with its label, badge, icon and lazy content                         |
-| `bf-tabs`              | `@bitforgehq/ui/mobile` | Tabs page with one navigation stack per tab, wiring the tab bar to the router               |
-| `bf-top-nav`           | `@bitforgehq/ui`        | Horizontal app navigation, a wrapping row of links for apps with few sections               |
+| 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                        |
+| `bf-content`           | `@bitforgehq/ui/mobile`  | Page's single scroll container that keeps focused fields clear of the soft keyboard         |
+| `bf-header`            | `@bitforgehq/ui/mobile`  | Page header toolbar with a large title that collapses into the toolbar on scroll            |
+| `bf-nav-group`         | `@bitforgehq/ui`         | A titled group of sidebar links with a small heading that names it                          |
+| `a[bfNavItem]`         | `@bitforgehq/ui`         | Navigation link for a sidebar or top nav, with icon, label and count                        |
+| `bf-page`              | `@bitforgehq/ui/mobile`  | Frame for one stacked mobile screen that supplies lifecycle events and shared page state    |
+| `bf-page-header`       | `@bitforgehq/ui`         | Desktop page header with breadcrumb, title, subtitle, badges and a row of actions           |
+| `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             |
+| `bf-tab-group`         | `@bitforgehq/ui`         | In-page tabs that switch between content panels, with keyboard navigation and badges        |
+| `bf-tab-panel`         | `@bitforgehq/ui`         | One tab of a tab group with its label, badge, icon and lazy content                         |
+| `bf-tabs`              | `@bitforgehq/ui/mobile`  | Tabs page with one navigation stack per tab, wiring the tab bar to the router               |
+| `bf-top-nav`           | `@bitforgehq/ui`         | Horizontal app navigation, a wrapping row of links for apps with few sections               |
 
 ### Overlays
 

package/ai/components/app-frame.md

@@ -0,0 +1,335 @@
+# 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`, at the header's inline
+ * start; the brand follows it, and a notifications action sits at the end. 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>
+
+        <bf-menu-button bfSlot="menu" variant="text" [menu]="navMenu">
+          <bf-icon bfSlot="icon-start" [icon]="menu" />
+          Sections
+        </bf-menu-button>
+        <span bfSlot="brand" class="text-heading">Atlas</span>
+        <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 narrow-screen menu, the brand 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 menu at the inline start, then the brand, and the actions at the end: the top app bar convention, and the menu comes first in the tab order too. The order is fixed, whatever order the slots have in your template. Keep the brand in the sidebar's own `header` slot too, for the wide layout.
+
+## 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.
+- `menu`: The narrow-screen navigation: a `bf-menu-button` of `a[bfMenuItem]` links, at the header bar's inline start.
+- `brand`: The app's name or logo in the narrow header bar, after the menu.
+- `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.3
+
+Fix: the narrow header bar puts the `menu` slot at the inline start, before the `brand` (0.3.2 put
+it after the brand), with the actions at the end as before: the top app bar convention. The menu
+also comes first in the tab order. No API change; an app needs no change unless it relied on the
+brand coming first.
+
+### 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`.

package/ai/components/card.md

@@ -95,7 +95,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
 
@@ -148,6 +148,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.
@@ -319,13 +366,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