@bitforgehq/ui 0.3.0 → 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/back-button.md

@@ -81,7 +81,7 @@ and its anatomy follows the shell mode (`provideBfShell({ mode })`, the platform
 
 ## When to use
 
-Use `bf-back-button` in the `start` slot of a pushed page's [bf-header](https://bitforge-ui.web.app/components/header) in the Capacitor shell. Use the browser's own back button and a breadcrumb instead on a desktop web page, and a [bf-button](https://bitforge-ui.web.app/components/button) link (`a[bfButton]`) for a named way back.
+Use `bf-back-button` in the `start` slot of a pushed page's [bf-header](https://bitforge-ui.web.app/components/header) in the Capacitor shell. Use the browser's own back button and a [bf-breadcrumb](https://bitforge-ui.web.app/components/breadcrumb) instead on a desktop web page, and a [bf-button](https://bitforge-ui.web.app/components/button) link (`a[bfButton]`) for a named way back.
 
 ## Basic usage
 
@@ -171,7 +171,42 @@ export class BackButtonLabelExampleComponent {}
 
 ## Desktop
 
-`bf-back-button` is part of the Capacitor shell (`provideBfShell()`). On a desktop web page the browser's back button and history already go back; add a breadcrumb or a named link instead. Inside the shell under a mouse, the iOS form darkens to `primary-strong` on hover and the Material form is a `text` icon button; both show the pointer cursor and a focus ring on keyboard focus only.
+`bf-back-button` is part of the Capacitor shell (`provideBfShell()`). On a desktop web page the browser's back button and history already go back; show where the page sits with a [bf-breadcrumb](https://bitforge-ui.web.app/components/breadcrumb) instead, or give a named way back with `a[bfButton]` (or an icon-only `a[bfIconButton]`, [bf-icon-button](https://bitforge-ui.web.app/components/icon-button)). Each level up is a `li[bfBreadcrumbItem]` holding the app's own `routerLink`; the breadcrumb draws the separators (never announced), marks the last item, the current page, with `aria-current="page"`, and collapses a long trail with `maxItems`. Put it in the `breadcrumb` slot of a [bf-page-header](https://bitforge-ui.web.app/components/page-header).
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+
+/**
+ * The desktop replacement for a back button: a bf-breadcrumb.
+ *
+ * Every level up is the app's own `routerLink`; the last item is the current page, which the
+ * breadcrumb marks with `aria-current="page"`.
+ */
+@Component({
+  selector: 'app-example-back-button-breadcrumb',
+  imports: [RouterLink, BfBreadcrumbComponent, BfBreadcrumbItemComponent],
+  template: `
+    <bf-breadcrumb label="Back button breadcrumb">
+      @for (crumb of trail; track crumb.path) {
+        <li bfBreadcrumbItem>
+          <a [routerLink]="crumb.path">{{ crumb.label }}</a>
+        </li>
+      }
+      <li bfBreadcrumbItem>Back button</li>
+    </bf-breadcrumb>
+  `,
+})
+export class BackButtonBreadcrumbExampleComponent {
+  protected readonly trail: readonly { path: string; label: string }[] = [
+    { path: '/', label: 'Docs' },
+    { path: '/components', label: 'Components' },
+  ];
+}
+```
+
+Inside the shell under a mouse, the iOS form darkens to `primary-strong` on hover and the Material form is a `text` icon button; both show the pointer cursor and a focus ring on keyboard focus only.
 
 ## Theming
 
@@ -232,6 +267,11 @@ Goes back one page, or to `defaultHref` when the stack has none to go back to.
 
 ## Migration notes
 
+### 0.3.1
+
+The `## Desktop` docs and When to use name the desktop replacement, `bf-breadcrumb`, with an
+example. No code change.
+
 ### 0.3.0
 
 **Behaviour:** `label` defaults to `''` and falls back to `provideBfLabels()`'s `back` ("Back"),

package/ai/components/badge.md

@@ -43,13 +43,13 @@ Use `bf-badge` for a read-only status or count next to what it describes: "At ri
 
 ## Status labels
 
-The variant carries the meaning: `success`, `warning`, `danger`, `primary` or the default `neutral`.
+The variant carries the meaning: `success`, `warning`, `danger`, `primary`, `info` or the default `neutral`. `info` is for an informational label that is not a status, such as a category ("Design", "Billing"); it is a calm blue, distinct from the brand `primary`, so a category never reads as the selected or main thing. `variant` takes a `BfBadgeAppearance` (the five `BfBadgeVariant` tones plus `info`).
 
 ```ts
 import { Component } from '@angular/core';
 import { BfBadgeComponent } from '@bitforgehq/ui';
 
-/** Status badges in the four tones. */
+/** Status badges in the four status tones, and an informational info label. */
 @Component({
   selector: 'app-example-badge-status',
   imports: [BfBadgeComponent],
@@ -59,6 +59,7 @@ import { BfBadgeComponent } from '@bitforgehq/ui';
       <bf-badge variant="warning">At risk</bf-badge>
       <bf-badge variant="danger">Blocked</bf-badge>
       <bf-badge>Draft</bf-badge>
+      <bf-badge variant="info">Design</bf-badge>
     </div>
   `,
 })
@@ -125,6 +126,7 @@ Consumes tokens by variant, background then text:
 - `success`: `success-soft` / `success`
 - `warning`: `warning-soft` / `warning`
 - `danger`: `danger-soft` / `danger`
+- `info`: `info-soft` / `info` (≥ 4.5:1 in both modes; it is not derived from the primary, so a custom brand colour leaves it unchanged)
 - Count pill (`count` set): `primary` / `on-primary`, ignoring `variant`
 - Shape (label and count pill): `rounded-control` (`--radius-control`, `9999px` by default).
 
@@ -134,11 +136,11 @@ A badge is a plain `<span>` with no role or ARIA attributes; its text is read as
 
 ## Inputs
 
-| Name         | Type                                                                              | Default     | Description                                                                                                                                          |
-| ------------ | --------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `variant`    | `BfBadgeVariant` (`'neutral' \| 'primary' \| 'success' \| 'warning' \| 'danger'`) | `'neutral'` | Tint for the label style. Ignored when `count` is set.                                                                                               |
-| `count`      | `number \| undefined`                                                             | `undefined` | Switches to the count pill; values above 99 render as "99+".                                                                                         |
-| `countLabel` | `string`                                                                          | `''`        | What the count counts ("unread messages"), read by assistive tech after the number ("99+ unread messages"); visually hidden. Only used with `count`. |
+| Name         | Type                                                                                           | Default     | Description                                                                                                                                          |
+| ------------ | ---------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`    | `BfBadgeAppearance` (`'neutral' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'info'`) | `'neutral'` | Tint for the label style: neutral, primary, success, warning, danger or info. Ignored when `count` is set.                                           |
+| `count`      | `number \| undefined`                                                                          | `undefined` | Switches to the count pill; values above 99 render as "99+".                                                                                         |
+| `countLabel` | `string`                                                                                       | `''`        | What the count counts ("unread messages"), read by assistive tech after the number ("99+ unread messages"); visually hidden. Only used with `count`. |
 
 ## Slots
 
@@ -155,9 +157,17 @@ A badge is a plain `<span>` with no role or ARIA attributes; its text is read as
 
 - Don't use a badge as a button; it has no interactive states.
 - Don't invent new colors on it; pick the variant that matches the meaning.
+- Don't use `primary` or `success` for a category; use `info`, so the status tones keep their meaning.
 
 ## Migration notes
 
+### 0.3.1
+
+New `info` tone for informational labels such as a category, on the new `info` / `info-soft`
+tokens (7.7:1 in light, 7.2:1 in dark; not derived from the primary). `variant` is now typed
+`BfBadgeAppearance` (the five `BfBadgeVariant` tones plus `info`); `BfBadgeVariant` keeps its five
+members, so code that maps over it keeps compiling.
+
 ### 0.3.0
 
 **Behaviour:** the label and the count pill use `rounded-control` (`--radius-control`, `9999px` by

package/ai/components/bar-chart.md

@@ -0,0 +1,188 @@
+# bf-bar-chart
+
+Bar chart of series over categories, grouped or stacked, vertical or horizontal
+
+`BfBarChartComponent` from `@bitforgehq/ui/charts` · Data display · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfBarChartComponent, type BfChartSeries } from '@bitforgehq/ui/charts';
+
+/**
+ * The bf-bar-chart overview.
+ *
+ * Live demo of `bf-bar-chart`: support tickets opened and closed per weekday, side by side.
+ * Hover a day, or focus the plot and use the arrow keys; hide a series in the legend; open Show
+ * data for the table.
+ */
+@Component({
+  selector: 'app-example-bar-chart-overview',
+  imports: [BfBarChartComponent],
+  template: `
+    <bf-bar-chart label="Support tickets this week" [series]="series" [categories]="days" />
+  `,
+})
+export class BarChartOverviewExampleComponent {
+  readonly days = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'];
+  readonly series: readonly BfChartSeries[] = [
+    { name: 'Opened', values: [14, 9, 12, 17, 8] },
+    { name: 'Closed', values: [11, 12, 8, 15, 13] },
+  ];
+}
+```
+
+## Overview
+
+A bar chart of one or more series over shared categories, drawn in SVG with the chart palette:
+bars side by side per category (or `stacked`), up from the baseline (or `horizontal`, along
+from it), with a value axis of nice ticks, a legend that shows and hides series, a tooltip on
+hover and on keyboard focus (Arrow keys move between the categories and a polite live region
+reads each one) and a Show data table. Bars grow in on the first render and on every data
+change, still under reduced motion; under `dir="rtl"` the horizontal axis runs from the right.
+
+A bar chart compares amounts between categories: tickets opened and closed per weekday, revenue per region, hours per project. `bf-bar-chart` draws it in SVG from `series` (each a `name` and one value per category) and `categories`, side by side or `stacked`, as vertical columns or `horizontal` bars, with a value axis of nice ticks from zero, a legend that shows and hides series, a tooltip on hover and on keyboard focus, and a Show data table. It lives in `@bitforgehq/ui/charts` (`import { BfBarChartComponent } from '@bitforgehq/ui/charts'`) and works the same in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-bar-chart` to compare amounts between categories, or the parts of each category with `stacked`. Our charts are themed with the `--color-chart-*` tokens, follow dark mode and `dir="rtl"`, and bring their own legend, tooltip, keyboard reading and data table; bring a chart library (themed with the same tokens) only for a form they do not draw. Use [bf-line-chart](https://bitforge-ui.web.app/components/line-chart) instead for a trend over time, [bf-donut-chart](https://bitforge-ui.web.app/components/donut-chart) for the shares of one whole, and [bf-table](https://bitforge-ui.web.app/components/table) when readers look up exact values more than they compare them.
+
+## Stacked
+
+`stacked` puts the series of each category into one bar, one segment per series with a 2 px gap between them, so the bar's length is the category's total. Positive values stack up from zero and negative ones down. Use it when the total matters as much as its parts; compare the parts across categories with grouped bars instead (the default), which share one baseline.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBarChartComponent, type BfChartSeries } from '@bitforgehq/ui/charts';
+
+/**
+ * A stacked bar chart.
+ *
+ * `stacked` puts the series of each month into one bar, so its length is the month's total:
+ * hours logged per month, split by kind of work.
+ */
+@Component({
+  selector: 'app-example-bar-chart-stacked',
+  imports: [BfBarChartComponent],
+  template: `
+    <bf-bar-chart
+      label="Hours logged by kind of work"
+      stacked
+      legend="top"
+      [series]="series"
+      [categories]="months"
+      [valueFormat]="hours"
+    />
+  `,
+})
+export class BarChartStackedExampleComponent {
+  readonly months = ['Jun', 'Jul', 'Aug', 'Sep', 'Oct'];
+  readonly series: readonly BfChartSeries[] = [
+    { name: 'Design', values: [42, 38, 24, 51, 47] },
+    { name: 'Build', values: [88, 96, 61, 102, 110] },
+    { name: 'Review', values: [16, 20, 12, 24, 22] },
+  ];
+  readonly hours = (value: number): string => `${value} h`;
+}
+```
+
+## Horizontal
+
+`orientation="horizontal"` runs the bars along from a vertical baseline, the category names down the start side: for long names (projects, countries) or many categories. The categories run top to bottom, and <kbd>ArrowUp</kbd> and <kbd>ArrowDown</kbd> move between them too.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBarChartComponent, type BfChartSeries } from '@bitforgehq/ui/charts';
+
+/**
+ * A horizontal bar chart.
+ *
+ * `orientation="horizontal"` runs the bars along from the start side, with room for long
+ * category names: open tasks per project, sorted from most to fewest.
+ */
+@Component({
+  selector: 'app-example-bar-chart-horizontal',
+  imports: [BfBarChartComponent],
+  template: `
+    <bf-bar-chart
+      label="Open tasks per project"
+      orientation="horizontal"
+      [height]="200"
+      [series]="series"
+      [categories]="projects"
+    />
+  `,
+})
+export class BarChartHorizontalExampleComponent {
+  readonly projects = ['Atlas relaunch', 'Billing', 'Mobile app', 'Docs site'];
+  readonly series: readonly BfChartSeries[] = [{ name: 'Open tasks', values: [23, 17, 12, 6] }];
+}
+```
+
+## Data and formatting
+
+The value axis always includes zero, so every bar's length is honest; values below zero draw below (or before) the baseline. A `null` value draws no bar. `valueFormat` formats the values on the axis, in the tooltip, the announcement and the table; unset, values use `Intl.NumberFormat` in the document's language. Each series keeps its colour (`--color-chart-1` for the first) when another is hidden. Bars grow from the baseline on the first render and whenever the data change. `height` sets the plot's height in px (240 by default); the width follows the container.
+
+## Desktop
+
+Under a mouse, hovering a category highlights its band in `surface-muted` and shows its tooltip; leaving the plot hides them. The legend's buttons take a `surface-muted` fill on hover. The plot is one stop in the tab order, with the focus ring on keyboard focus: focusing it shows the first category. Under a coarse pointer (touch) a tap shows a category's tooltip, and the legend buttons and the Show data button are at least 44 px tall. Inside `provideBfShell()` it renders and behaves the same.
+
+## Theming
+
+- Bars: `--color-chart-1` … `--color-chart-8` by series (`fill-chart-n`), 2 px corner radius, at most 40 px thick.
+- Grid lines: `chart-grid`; the zero baseline: `chart-axis`; axis text: `text-micro` in `text-muted`.
+- Active category band: `surface-muted`.
+- Tooltip, legend and data table: as in [bf-line-chart](https://bitforge-ui.web.app/components/line-chart).
+- Motion: `--animate-chart-grow-y` (columns) or `--animate-chart-grow-x` (horizontal bars); none under `prefers-reduced-motion`.
+
+## Accessibility
+
+The chart is a native `figure` named by `label` (else the `bf-chart-card` title, else the `chart` label); the SVG is hidden from assistive technology. The plot is a focusable `role="group"` named by the `chartValues` label: the arrow keys move between the categories and a polite live region reads each one ("Tue: Opened 9, Closed 12"). The legend is a group of toggle buttons (`aria-pressed`); the Show data button (`aria-expanded`) shows the data as a native `table` with a caption and row headers. Every series is ≥ 3:1 against `surface` and `bg` in both modes, and the legend names each colour.
+
+### Keyboard
+
+| Key                                              | Action                                                                                |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves through the plot, the legend buttons and the Show data button                   |
+| <kbd>ArrowRight</kbd>                            | Moves to the next category and reads it (the previous one under `dir="rtl"`)          |
+| <kbd>ArrowLeft</kbd>                             | Moves to the previous category and reads it (the next one under `dir="rtl"`)          |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>        | With `orientation="horizontal"`, moves to the next / previous category                |
+| <kbd>Home</kbd> / <kbd>End</kbd>                 | Moves to the first / last category                                                    |
+| <kbd>Escape</kbd>                                | Hides the tooltip                                                                     |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | On a legend button, shows or hides its series; on Show data, shows or hides the table |
+
+## Inputs
+
+| Name          | Type                                                                              | Default      | Description                                                                                                                                     |
+| ------------- | --------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `series`      | `readonly BfChartSeries[]`                                                        | required     | The series to draw, each with one value per category.                                                                                           |
+| `categories`  | `readonly string[]`                                                               | required     | The category names along the category axis, in order.                                                                                           |
+| `label`       | `string`                                                                          | `''`         | The chart's accessible name; empty falls back to the `bf-chart-card` title, then to `provideBfLabels()`'s `chart` ("Chart").                    |
+| `height`      | `number`                                                                          | `240`        | The plot's height in px; the width follows the container.                                                                                       |
+| `orientation` | `BfBarChartOrientation` (`'vertical' \| 'horizontal'`)                            | `'vertical'` | `vertical` (default) bars rise from a horizontal baseline; `horizontal` bars run along from a vertical one, the categories down the start side. |
+| `stacked`     | `boolean`                                                                         | `false`      | Stacks the series of a category into one bar instead of side by side.                                                                           |
+| `valueFormat` | `BfChartValueFormat \| undefined`                                                 | `undefined`  | Formats the values on the axis, in the tooltip and in the table; unset uses `Intl.NumberFormat` in the document's language.                     |
+| `legend`      | `BfChartLegendPosition \| undefined` (`'top' \| 'bottom' \| 'none' \| undefined`) | `undefined`  | Where the legend goes; unset follows the `bf-chart-card`, else `bottom`. A single series draws no legend.                                       |
+
+## Notes
+
+### Do
+
+- Sort the categories by value when they have no order of their own, so the bars read as a ranking.
+- Use `horizontal` when the category names are long, rather than abbreviating them.
+
+### Don't
+
+- Don't stack series that do not add up to a meaningful total.
+- Don't draw more than eight series; fold the smallest into "Other".
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-bar-chart` in `@bitforgehq/ui/charts`: series over categories as bars from a zero
+baseline, side by side or `stacked`, vertical or `orientation="horizontal"`
+(`BfBarChartOrientation`), with the line chart's value axis, legend, tooltip, keyboard reading and
+data table. Bars grow from the baseline on the first render and on every data change, not under
+reduced motion; `dir="rtl"` mirrors the horizontal axis.