@bitforgehq/ui 0.3.1 → 0.3.2

package/ai/components/app-frame.md

@@ -0,0 +1,328 @@
+# 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`.

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

package/ai/components/empty-state.md

@@ -98,6 +98,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.
@@ -105,15 +188,15 @@ 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
 
-| Name           | Type                                  | Default  | Description                                                          |
-| -------------- | ------------------------------------- | -------- | -------------------------------------------------------------------- |
-| `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. |
+| Name           | Type                                  | Default  | Description                                                                                 |
+| -------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------- |
+| `title`        | `string`                              | required | What is missing, as a short title.                                                          |
+| `description`  | `string`                              | `''`     | One sentence on how to fill it.                                                             |
+| `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
 
@@ -129,10 +212,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

package/ai/components/header.md

@@ -608,7 +608,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';
@@ -748,6 +748,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