@bitforgehq/ui 0.3.0 → 0.3.1

package/ai/components/sidebar.md

@@ -0,0 +1,363 @@
+# bf-sidebar
+
+Vertical app navigation with brand, grouped links, footer and an icon rail mode
+
+`BfSidebarComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import {
+  BfIconButtonComponent,
+  BfNavGroupComponent,
+  BfNavItemComponent,
+  BfSidebarComponent,
+} from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BookOpen,
+  Layers,
+  type IconNode,
+  PanelLeftClose,
+  PanelLeftOpen,
+  PanelTop,
+  Rows3,
+  Settings,
+  Smartphone,
+} from 'lucide';
+
+interface NavLink {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+  readonly badge?: number;
+}
+
+/**
+ * The bf-sidebar overview.
+ *
+ * Live demo of `bf-sidebar`: a brand and a collapse toggle in the header, two `bf-nav-group`s of
+ * `a[bfNavItem]` router links (this page is the current one, one item has a count badge) and a
+ * footer link. The toggle binds `[(collapsed)]`; collapsed, the items show their icon only and
+ * name themselves in a tooltip. The result line reports the state.
+ */
+@Component({
+  selector: 'app-example-sidebar-overview',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfIconComponent,
+    BfIconButtonComponent,
+    BfNavGroupComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+  ],
+  template: `
+    <div class="border-border bg-bg rounded-card flex h-96 overflow-hidden border">
+      <bf-sidebar label="Docs" [(collapsed)]="collapsed">
+        <div bfSlot="header" class="flex items-center justify-between gap-2">
+          @if (!collapsed()) {
+            <span class="text-heading text-text ps-3">Atlas</span>
+          }
+          <bf-icon-button
+            variant="text"
+            [label]="collapsed() ? 'Expand sidebar' : 'Collapse sidebar'"
+            (clicked)="collapsed.set(!collapsed())"
+          >
+            <bf-icon [icon]="collapsed() ? panelOpen : panelClose" />
+          </bf-icon-button>
+        </div>
+        <bf-nav-group label="Desktop">
+          @for (link of desktop; track link.path) {
+            <a
+              bfNavItem
+              [routerLink]="link.path"
+              routerLinkActive
+              ariaCurrentWhenActive="page"
+              [badge]="link.badge ?? null"
+            >
+              <bf-icon bfSlot="icon" [icon]="link.icon" />
+              {{ link.label }}
+            </a>
+          }
+        </bf-nav-group>
+        <bf-nav-group label="Shell">
+          @for (link of shell; track link.path) {
+            <a
+              bfNavItem
+              [routerLink]="link.path"
+              routerLinkActive
+              ariaCurrentWhenActive="page"
+              [badge]="link.badge ?? null"
+            >
+              <bf-icon bfSlot="icon" [icon]="link.icon" />
+              {{ link.label }}
+            </a>
+          }
+        </bf-nav-group>
+        <a
+          bfSlot="footer"
+          bfNavItem
+          routerLink="/theming"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+        >
+          <bf-icon bfSlot="icon" [icon]="settings" />
+          Theming
+        </a>
+      </bf-sidebar>
+      <div class="min-w-0 flex-1 p-4">
+        <p data-status aria-live="polite" class="text-caption text-text-muted wrap-anywhere">
+          {{ status() }}
+        </p>
+      </div>
+    </div>
+  `,
+})
+export class SidebarOverviewExampleComponent {
+  readonly collapsed = signal(false);
+  readonly status = computed(() =>
+    this.collapsed() ? 'Sidebar collapsed to an icon rail.' : 'Sidebar expanded.',
+  );
+
+  protected readonly desktop: readonly NavLink[] = [
+    { path: '/components/sidebar', label: 'Sidebar', icon: PanelTop },
+    { path: '/components/top-nav', label: 'Top nav', icon: Rows3 },
+    { path: '/components/nav-group', label: 'Nav group', icon: Layers },
+  ];
+  protected readonly shell: readonly NavLink[] = [
+    { path: '/components/tabs', label: 'Tabs', icon: Smartphone, badge: 3 },
+    { path: '/mobile', label: 'Mobile guide', icon: BookOpen },
+  ];
+  protected readonly settings = Settings;
+  protected readonly panelOpen = PanelLeftOpen;
+  protected readonly panelClose = PanelLeftClose;
+}
+```
+
+## Overview
+
+The vertical navigation of a desktop app: a `nav` landmark with a `header` slot (the brand),
+the destinations (`a[bfNavItem]` links, optionally in `bf-nav-group`s) and a `footer` slot.
+`collapsed` turns it into an icon rail; the consumer owns the toggle button and binds
+`[(collapsed)]`. Below a breakpoint hide it (`class="hidden md:flex"`) and drive a
+`bf-menu-button` from the same routes.
+
+The vertical navigation of a desktop web app: a `nav` landmark down the inline-start edge with a `header` slot for the brand, the destinations as [`a[bfNavItem]`](https://bitforge-ui.web.app/components/nav-item) links (optionally in titled [`bf-nav-group`](https://bitforge-ui.web.app/components/nav-group)s) and a `footer` slot for settings or the account. `collapsed` turns it into an icon rail. Its horizontal sibling for apps with few sections is [`bf-top-nav`](https://bitforge-ui.web.app/components/top-nav); both share the same item, so the current page, the badge and the focus ring look the same in either.
+
+## When to use
+
+Use `bf-sidebar` for the top-level destinations of a desktop web app with more than four or five sections, or with sections that fall into groups. Use [bf-top-nav](https://bitforge-ui.web.app/components/top-nav) instead for an app with a handful of sections, and [bf-segmented](https://bitforge-ui.web.app/components/segmented) to switch a view in place. In the Capacitor shell use [bf-tabs](https://bitforge-ui.web.app/components/tabs) with [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar) instead.
+
+## Basic usage
+
+Put `bfNavItem` on your own `<a routerLink routerLinkActive ariaCurrentWhenActive="page">`: the router sets `aria-current="page"` on the current page's link and the item shows it in the tonal fill. The widget never imports the router. Group the links with `bf-nav-group`, put the brand in `bfSlot="header"` and secondary links in `bfSlot="footer"`. Name the landmark with `label` (it falls back to `provideBfLabels()`'s `navigation`, "Main").
+
+## Collapsing to an icon rail
+
+`collapsed` is a model: bind `[(collapsed)]` to your own toggle button, such as a text `bf-icon-button` in the header whose label says what the next press does ("Collapse sidebar", "Expand sidebar"). The widget has no toggle of its own, because the button needs an icon and a widget never imports one. Collapsed, every item shows only its icon, centred in a square; its label stays in the DOM as screen-reader text, so its accessible name does not change, and becomes the link's `title`, the tooltip a pointer user sees on hover. A count badge becomes a small dot that is still announced, and the group headings are hidden visually but still name their groups. The width follows the rail (`w-auto`); expanded the sidebar is `w-60` (240 px).
+
+## Responsive layouts
+
+Below a breakpoint the sidebar does not turn itself into a menu: a root widget cannot render `bf-menu`. Keep one array of destinations (ideally derived from your route config) and drive every surface from it: the sidebar from `md` up (`class="hidden md:flex"` on `bf-sidebar`; its own `flex` loses to your `hidden`), and below it a [`bf-menu-button`](https://bitforge-ui.web.app/components/menu-button) of `a[bfMenuItem]` router links (`class="md:hidden"`, from `@bitforgehq/ui/overlay`). Each surface keeps the router's `routerLinkActive`.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+import { type IconNode, Layers, Menu, PanelTop, Rows3 } from 'lucide';
+
+/** One top-level destination of the app. */
+interface Destination {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+}
+
+/**
+ * One route array, two surfaces.
+ *
+ * The same destinations drive the sidebar from the `md` breakpoint up (`hidden md:flex`) and a
+ * `bf-menu-button` of `a[bfMenuItem]` router links below it (`md:hidden`). Each surface keeps
+ * the router's `routerLinkActive`; resize the window to switch between them.
+ */
+@Component({
+  selector: 'app-example-sidebar-responsive',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfIconComponent,
+    BfMenuButtonComponent,
+    BfMenuComponent,
+    BfMenuItemDirective,
+    BfNavItemComponent,
+    BfSidebarComponent,
+  ],
+  template: `
+    <div class="flex flex-col gap-3 md:flex-row">
+      <bf-sidebar label="Desktop components" class="hidden md:flex">
+        @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 class="md:hidden" [menu]="navMenu">
+        <bf-icon bfSlot="icon-start" [icon]="menu" />
+        Sections
+      </bf-menu-button>
+      <p class="text-caption text-text-muted min-w-0 flex-1">
+        The page content sits here, beside the sidebar or under the menu button.
+      </p>
+    </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 SidebarResponsiveExampleComponent {
+  /** In an app, derive this from the route config, so a new route appears on every surface. */
+  protected readonly destinations: readonly Destination[] = [
+    { path: '/components/sidebar', label: 'Sidebar', icon: PanelTop },
+    { path: '/components/top-nav', label: 'Top nav', icon: Rows3 },
+    { path: '/components/nav-group', label: 'Nav group', icon: Layers },
+  ];
+  protected readonly menu = Menu;
+}
+```
+
+Inside the Capacitor shell the same array drives the `bf-tab`s of a `bf-tab-bar` in `bf-tabs`; each destination's path is a tab id and a child route of the tabs.
+
+```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 inside the Capacitor shell.
+ *
+ * In the shell the destinations array that drives the desktop sidebar drives a `bf-tab-bar`
+ * inside `bf-tabs` instead: each destination's `path` is a child route of `app` and the tab's id.
+ * On desktop the same array feeds `a[bfNavItem]` links (`routerLink="/app/{path}"`).
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-sidebar-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 SidebarShellExampleComponent {
+  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 sidebar is a desktop pattern. Its items take a `surface-muted` fill and the pointer on hover, a `surface-pressed` fill while pressed and the focus ring on keyboard focus only (`focus-visible`); the current page keeps its tonal fill with its own hover and pressed steps. The destinations scroll on their own when they outgrow the height, while the header and footer stay put; a 4 px inset keeps the focus ring inside the scroll box. Item height follows `provideBfDefaults()` (`controlSize`); under a coarse pointer (a touchscreen laptop) every item is at least 44 px tall. Collapsed, the `title` tooltip names each item on hover. A link keeps the browser's behaviour: Ctrl/Cmd-click and a middle click open it in a new tab.
+
+## Theming
+
+- Surface: `surface` with a `border` line on its inline-end edge (`border-e`); 12 px padding and 24 px between the header, the groups and the footer.
+- Width: `w-60` (240 px) expanded, the icon rail's own width collapsed.
+- The items' and the groups' tokens are on the [nav item](https://bitforge-ui.web.app/components/nav-item#theming) and [nav group](https://bitforge-ui.web.app/components/nav-group#theming) pages.
+
+## Accessibility
+
+`bf-sidebar` renders a native `<nav>` landmark named by `label`, else `provideBfLabels()`'s `navigation` ("Main"); give each landmark on a page a different name. The header, the destinations and the footer all sit inside it, in that DOM order. The current page is the link the router marks with `aria-current="page"`; the tonal fill is never the only cue under forced colours, where an outline marks it. Collapsing changes only what is visible: every item keeps its label as screen-reader text and each group its name, so the accessible names stay the same. The consumer's toggle button is a native button; name it by what it does ("Collapse sidebar") or give it `aria-pressed`, and keep it in the sidebar or right before it.
+
+### Keyboard
+
+| Key                                              | Action                                             |
+| ------------------------------------------------ | -------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves through the header, the links and the footer |
+| <kbd>Enter</kbd>                                 | Follows the focused link                           |
+
+## Inputs
+
+| Name        | Type      | Default | Description                                                                                                                                                                    |
+| ----------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `label`     | `string`  | `''`    | Accessible name of the navigation; empty falls back to `provideBfLabels()`'s `navigation` ("Main"). Name each landmark differently when a page has more than one.              |
+| `collapsed` | `boolean` | `false` | Collapses the sidebar to an icon rail: items show their icon only, their label stays for screen readers and becomes a tooltip. Bind `[(collapsed)]` to your own toggle button. |
+
+## Slots
+
+- `header`: The brand or app switcher above the destinations.
+- `default`: The destinations: `a[bfNavItem]` links and `bf-nav-group`s.
+- `footer`: Content under the destinations, such as settings or the account.
+
+## Notes
+
+### Do
+
+- Mark the current page with `routerLinkActive` and `ariaCurrentWhenActive="page"` on every link.
+- Drive the sidebar, the small-screen menu and the shell's tab bar from one array of destinations.
+
+### Don't
+
+- Don't put actions (Create, Log out) among the destinations; a sidebar is for places, so put an action in the header or footer as a button.
+- Don't use `bf-sidebar` inside the Capacitor shell; use `bf-tabs` with a `bf-tab-bar` there.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-sidebar`: the vertical navigation of a desktop app, a `nav` landmark with `header`,
+default and `footer` slots, named by `label` (else the new `navigation` label, "Main").
+`collapsed` (a model the app binds to its own toggle button) turns it into an icon rail. Below a
+breakpoint, hide it with `hidden md:flex` and drive a `bf-menu-button` from the same routes.

package/ai/components/skeleton.md

@@ -0,0 +1,215 @@
+# bf-skeleton
+
+Loading placeholder shaped as text lines, a rectangle or a circle, with a shimmer
+
+`BfSkeletonComponent` from `@bitforgehq/ui` · Feedback · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfSkeletonComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-skeleton overview.
+ *
+ * Live demo of `bf-skeleton`: the three shapes (a circle for an avatar, text lines with a shorter
+ * last line, a rect for an image) inside a region marked `aria-busy="true"` while it loads.
+ */
+@Component({
+  selector: 'app-example-skeleton-overview',
+  imports: [BfSkeletonComponent],
+  template: `
+    <div aria-busy="true" class="flex max-w-md flex-col gap-4">
+      <div class="flex items-center gap-3">
+        <bf-skeleton shape="circle" />
+        <div class="flex min-w-0 flex-1 flex-col gap-2">
+          <bf-skeleton width="40%" height="0.875rem" />
+          <bf-skeleton width="25%" />
+        </div>
+      </div>
+      <bf-skeleton [lines]="3" height="0.875rem" />
+      <bf-skeleton shape="rect" height="8rem" />
+    </div>
+  `,
+})
+export class SkeletonOverviewExampleComponent {}
+```
+
+## Overview
+
+Loading placeholder in the shape of the content to come: text lines, a rectangle or a circle,
+on the sunken surface with a shimmer. It is hidden from assistive technology; mark the region it
+stands in for with `aria-busy="true"` while it loads.
+
+A skeleton is a placeholder in the shape of the content that is still loading: a few text lines, a rectangle for an image or a chart, a circle for an avatar. It sits on the `surface-sunken` fill with a soft shimmer, so the page keeps its layout while the data arrives and nothing jumps when it does. `bf-skeleton` is hidden from assistive technology; the region it stands in for says that it is busy. It works the same in both shells: in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-skeleton` while a screen or a section loads content whose shape you know: a card, a list, the rows of a table. Use [bf-spinner](https://bitforge-ui.web.app/components/spinner) instead for a short wait with no known shape, or inside a button, and [bf-progress](https://bitforge-ui.web.app/components/progress) when you can say how far the work is. Once loading has failed, replace the skeletons with a [bf-alert](https://bitforge-ui.web.app/components/alert); when it returned nothing, with a [bf-empty-state](https://bitforge-ui.web.app/components/empty-state).
+
+## Shapes and sizes
+
+`shape` picks the placeholder. `text` (the default) draws one line, fully rounded; `lines` draws several, the last one shorter, as a paragraph's last line is. `rect` is one bar with the field radius, for an image, a chart or a field. `circle` is a disc for an avatar.
+
+`width` and `height` take CSS lengths (`12rem`, `60%`, `48px`). Without a `width` a text or rect skeleton fills its container and a circle is 40 px; a circle's height always follows its width. `height` is the height of each text line (default `0.75rem`) or of the rect (default `6rem`); a circle ignores it. Match the size of the content to come, such as `0.875rem` lines for `text-body`, so the page does not move when it arrives.
+
+## A card while it loads
+
+Build the placeholder from the same layout as the loaded card: the same `bf-card`, the same gaps, a skeleton where each piece of content goes. Mark the region the skeletons stand in for with `aria-busy="true"` while it loads, and drop the attribute (or set it to `false`) when the content is in.
+
+```ts
+import { Component } from '@angular/core';
+import { BfAvatarComponent, BfCardComponent, BfSkeletonComponent } from '@bitforgehq/ui';
+
+/**
+ * A card while it loads, beside the loaded card.
+ *
+ * The loading card has the loaded one's layout, with a skeleton where each piece of content goes:
+ * a 40 px circle for the avatar, two short lines for the name and the role, three lines of text.
+ * Only the loading card carries `aria-busy="true"`.
+ */
+@Component({
+  selector: 'app-example-skeleton-card',
+  imports: [BfCardComponent, BfAvatarComponent, BfSkeletonComponent],
+  template: `
+    <div class="grid grid-cols-[repeat(auto-fit,minmax(15rem,1fr))] gap-4">
+      <bf-card aria-busy="true">
+        <div class="flex flex-col gap-4">
+          <div class="flex items-center gap-3">
+            <bf-skeleton shape="circle" />
+            <div class="flex min-w-0 flex-1 flex-col gap-2">
+              <bf-skeleton width="55%" height="1rem" />
+              <bf-skeleton width="35%" height="0.75rem" />
+            </div>
+          </div>
+          <bf-skeleton [lines]="3" height="0.875rem" />
+        </div>
+      </bf-card>
+      <bf-card>
+        <div class="flex flex-col gap-4">
+          <div class="flex items-center gap-3">
+            <bf-avatar initials="MK" />
+            <div class="flex min-w-0 flex-col">
+              <p class="text-label text-text">Mara Keller</p>
+              <p class="text-caption text-text-muted">Design lead</p>
+            </div>
+          </div>
+          <p class="text-body text-text-muted">
+            Runs the Atlas rebrand and the design reviews on Thursdays. Ask her about the type
+            scale.
+          </p>
+        </div>
+      </bf-card>
+    </div>
+  `,
+})
+export class SkeletonCardExampleComponent {}
+```
+
+## Table rows
+
+A loading `bf-table` keeps its real header and shows skeleton rows: pass a few placeholder rows and render a `bf-skeleton` in each column through `bfTableCell` templates, with widths that differ from row to row. The header tells the user what is coming; the table's wrapper carries `aria-busy="true"`. In a list, render a few `bf-list-item`s with a circle and two lines the same way.
+
+```ts
+import { Component } from '@angular/core';
+import {
+  BfSkeletonComponent,
+  BfTableCellDirective,
+  BfTableComponent,
+  type BfTableColumn,
+} from '@bitforgehq/ui';
+
+interface PlaceholderRow {
+  id: string;
+  /** The width of each column's skeleton in this row, so the rows do not look stamped. */
+  widths: Readonly<Record<'title' | 'client' | 'amount', string>>;
+}
+
+/**
+ * Skeleton rows in a bf-table.
+ *
+ * The table keeps its real header while the rows load: four placeholder rows render a
+ * `bf-skeleton` in every column through `bfTableCell` templates, at widths that differ from row to
+ * row, and the wrapper carries `aria-busy="true"`.
+ */
+@Component({
+  selector: 'app-example-skeleton-table',
+  imports: [BfTableComponent, BfTableCellDirective, BfSkeletonComponent],
+  template: `
+    <div aria-busy="true">
+      <bf-table label="Invoices" [rows]="rows" [columns]="columns">
+        <ng-template bfTableCell="title" [bfTableCellOf]="rows" let-row>
+          <bf-skeleton [width]="row.widths.title" height="0.875rem" />
+        </ng-template>
+        <ng-template bfTableCell="client" [bfTableCellOf]="rows" let-row>
+          <bf-skeleton [width]="row.widths.client" height="0.875rem" />
+        </ng-template>
+        <ng-template bfTableCell="amount" [bfTableCellOf]="rows" let-row>
+          <bf-skeleton class="ms-auto" [width]="row.widths.amount" height="0.875rem" />
+        </ng-template>
+      </bf-table>
+    </div>
+  `,
+})
+export class SkeletonTableExampleComponent {
+  readonly columns: readonly BfTableColumn[] = [
+    { key: 'title', label: 'Invoice' },
+    { key: 'client', label: 'Client' },
+    { key: 'amount', label: 'Amount', align: 'end' },
+  ];
+  readonly rows: readonly PlaceholderRow[] = [
+    { id: 'a', widths: { title: '70%', client: '55%', amount: '4rem' } },
+    { id: 'b', widths: { title: '55%', client: '70%', amount: '3rem' } },
+    { id: 'c', widths: { title: '80%', client: '45%', amount: '4.5rem' } },
+    { id: 'd', widths: { title: '60%', client: '60%', amount: '3.5rem' } },
+  ];
+}
+```
+
+## Desktop
+
+A skeleton is not interactive: no hover, no pointer cursor, no focus stop, and its size does not follow `provideBfDefaults()`. On desktop and in the Capacitor shell it looks and behaves the same. Show skeletons only for a wait that lasts: when a load usually finishes in a few hundred milliseconds, start showing them after a short delay (a timer in the state service), so a fast connection never sees a flash of placeholders.
+
+## Theming
+
+- Fill: `surface-sunken`. Shimmer: a `surface` highlight at 70 % opacity that sweeps across from the inline start, with `--animate-skeleton-shimmer` (1.6 s, ease-in-out, endless) and `--animate-skeleton-shimmer-rtl` under `dir="rtl"`.
+- Radius: text lines and the circle `rounded-full`; the rect `rounded-field`.
+- Under `prefers-reduced-motion: reduce` the shimmer is hidden and the placeholder stays still. Under forced colours a `GrayText` border draws the shape, as backgrounds are dropped there.
+
+## Accessibility
+
+Every `bf-skeleton` carries `aria-hidden="true"`: a placeholder has nothing to say, and a screen reader that read out a row of shapes would only make noise. Say that the content is loading on the region it stands in for instead: `aria-busy="true"` on that element tells assistive technology the region is being updated, and dropping it lets the finished content be read. For a load the user started and waits for (a search), also put a short polite status in the page, such as "Loading results", from a `role="status"` element or a `bf-spinner`, which announces its `label` (default "Loading"). The skeleton takes no focus, so keyboard focus stays where the user left it.
+
+## Inputs
+
+| Name     | Type                                               | Default  | Description                                                                                                                |
+| -------- | -------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `shape`  | `BfSkeletonShape` (`'text' \| 'rect' \| 'circle'`) | `'text'` | What it stands in for: `text` lines (default), a `rect` (an image, a chart) or a `circle` (an avatar).                     |
+| `lines`  | `number`                                           | `1`      | How many lines a `text` skeleton draws, the last one shorter when there are several; ignored by the other shapes.          |
+| `width`  | `string`                                           | `''`     | Width as a CSS length (`12rem`, `60%`); empty fills the container, a circle is 40 px. A circle's height follows its width. |
+| `height` | `string`                                           | `''`     | Height as a CSS length: of each line of `text` (default `0.75rem`) or of the `rect` (default `6rem`); a circle ignores it. |
+
+## Notes
+
+### Do
+
+- Shape the skeleton like the content to come, at its size, so nothing jumps when it loads.
+- Put `aria-busy="true"` on the loading region, and remove it once the content is there.
+- Show a few rows or cards, not a whole page of them.
+
+### Don't
+
+- Don't show a skeleton for a wait that has no known shape; use a `bf-spinner`.
+- Don't leave skeletons up after a load fails or returns nothing; show the error or the empty state.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-skeleton` in `@bitforgehq/ui`, a loading placeholder for both shells: `shape` (the new
+`BfSkeletonShape`: `text` lines, a `rect` or a `circle`), `lines` for several text lines with a
+shorter last one, and `width` / `height` as CSS lengths. It draws the `surface-sunken` fill with a
+`surface` shimmer that sweeps from the inline start (hidden under reduced motion) and carries
+`aria-hidden="true"`; the docs mark the loading region with `aria-busy="true"` and show a card and
+a table of skeleton rows.