@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/breadcrumb-item.md

@@ -0,0 +1,121 @@
+# li[bfBreadcrumbItem]
+
+One level of a breadcrumb trail: a link, or the current page as text
+
+`BfBreadcrumbItemComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+
+/**
+ * The li[bfBreadcrumbItem] overview.
+ *
+ * Three levels of a `bf-breadcrumb`: two ancestor pages as router links, each followed by a
+ * chevron, and the current page as plain text, marked `aria-current="page"`.
+ */
+@Component({
+  selector: 'app-example-breadcrumb-item-overview',
+  imports: [RouterLink, BfBreadcrumbComponent, BfBreadcrumbItemComponent],
+  template: `
+    <bf-breadcrumb label="Component breadcrumb">
+      <li bfBreadcrumbItem><a routerLink="/components">Components</a></li>
+      <li bfBreadcrumbItem><a routerLink="/components/breadcrumb">Breadcrumb</a></li>
+      <li bfBreadcrumbItem>Breadcrumb item</li>
+    </bf-breadcrumb>
+  `,
+})
+export class BreadcrumbItemOverviewExampleComponent {}
+```
+
+## Overview
+
+One level of a `bf-breadcrumb` trail, on the consumer's own `<li>` so the list stays `ol > li`.
+Project an `<a routerLink>` for an ancestor page, or plain text for the current page; the last
+item is the current page (`aria-current="page"`, no link look, no separator), every other one is
+followed by a chevron.
+
+One level of a [`bf-breadcrumb`](https://bitforge-ui.web.app/components/breadcrumb) trail, as an attribute on the app's own `<li>`. It styles the link projected into it, adds the chevron after it and, on the last level, marks the current page. An item lives only inside a `bf-breadcrumb`, which decides which level is current and which ones a collapsed trail hides.
+
+## When to use
+
+Use `li[bfBreadcrumbItem]` for each level of a [bf-breadcrumb](https://bitforge-ui.web.app/components/breadcrumb), and only there. On mobile, in the Capacitor shell, use [bf-back-button](https://bitforge-ui.web.app/components/back-button) in [bf-header](https://bitforge-ui.web.app/components/header) instead.
+
+## Links and the current page
+
+Put an `<a routerLink>` (or `href`) straight inside the `li` for a page above the current one: as a direct child it takes the link look, the hover underline and the focus ring. Put plain text in the last item, the current page: it is wrapped in a span with `aria-current="page"` and shown semibold, and no chevron follows it.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+
+/**
+ * A breadcrumb trail.
+ *
+ * Each level is the app's own `<li bfBreadcrumbItem>` holding a router link; the last one is the
+ * current page as plain text. `label` names the `nav`; this one is not the page's only breadcrumb
+ * (the docs site has its own), so it gets a name of its own.
+ */
+@Component({
+  selector: 'app-example-breadcrumb-basic',
+  imports: [RouterLink, BfBreadcrumbComponent, BfBreadcrumbItemComponent],
+  template: `
+    <bf-breadcrumb label="Docs breadcrumb">
+      <li bfBreadcrumbItem><a routerLink="/">Docs</a></li>
+      <li bfBreadcrumbItem><a routerLink="/components">Components</a></li>
+      <li bfBreadcrumbItem>Breadcrumb</li>
+    </bf-breadcrumb>
+  `,
+})
+export class BreadcrumbBasicExampleComponent {}
+```
+
+## Desktop
+
+A linked level turns from `text-muted` to `text` and is underlined on hover, with the pointer cursor; the ring shows on keyboard focus only. A link is at least 24 px tall under a fine pointer and 44 px under a coarse one (`pointer-coarse:min-h-hit`), through a min height rather than an `::after`, because it is your content. See the [bf-breadcrumb](https://bitforge-ui.web.app/components/breadcrumb) page for collapsing.
+
+## Theming
+
+- Ancestor level: `text-muted`, `text` on hover with an underline (`underline-offset-4`); `rounded-tile` with the `ring` focus ring.
+- Current page: `text`, semibold.
+- Separator: a 1.5 px CSS chevron in `text-subtle`, pointing to the inline end and mirrored under `dir="rtl"`.
+
+## Accessibility
+
+The host is your native `<li>`, so the trail stays an ordered list. Only the last item carries `aria-current="page"`. The chevron is an empty `aria-hidden` element, never announced. A level a collapsed trail hides carries `hidden`; when the ellipsis shows it and it has no link, the item takes focus itself (`tabindex="-1"`).
+
+### Keyboard
+
+| Key              | Action                    |
+| ---------------- | ------------------------- |
+| <kbd>Tab</kbd>   | Moves to the level's link |
+| <kbd>Enter</kbd> | Follows the focused link  |
+
+## Slots
+
+- `default`: The level: an `<a>` link to the page, or plain text for the current page.
+
+## Notes
+
+### Do
+
+- Project the link as the direct child of the `li`, so it takes the link look.
+- Keep the current page plain text.
+
+### Don't
+
+- Don't use `li[bfBreadcrumbItem]` outside a `bf-breadcrumb`.
+- Don't put more than one link, or a control, in one level.
+
+## Migration notes
+
+### 0.3.1
+
+New `li[bfBreadcrumbItem]` in `@bitforgehq/ui`: one level of a `bf-breadcrumb` on the app's own
+`<li>`. A projected link takes the muted link look, the hover underline and the focus ring (at
+least 24 px tall, 44 px under a coarse pointer); the last level is the current page, wrapped in
+`aria-current="page"` with no chevron.

package/ai/components/breadcrumb.md

@@ -0,0 +1,277 @@
+# bf-breadcrumb
+
+Desktop breadcrumb trail of links to the current page, with optional collapsing
+
+`BfBreadcrumbComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-breadcrumb overview.
+ *
+ * Live demo of `bf-breadcrumb`: a five-level trail collapsed to three with `maxItems`; the ellipsis
+ * shows the hidden levels in place and moves focus to the first one, which the result line
+ * reports. The demo's links stay on this page (a fragment per level); an app links each level to
+ * its route.
+ */
+@Component({
+  selector: 'app-example-breadcrumb-overview',
+  imports: [RouterLink, BfBreadcrumbComponent, BfBreadcrumbItemComponent],
+  template: `
+    <div class="flex flex-col gap-3" (focusin)="onFocus($event)">
+      <bf-breadcrumb label="Release breadcrumb" [maxItems]="3">
+        @for (level of trail; track level.id) {
+          <li bfBreadcrumbItem>
+            <a routerLink="." [fragment]="level.id">{{ level.label }}</a>
+          </li>
+        }
+        <li bfBreadcrumbItem>Release 2.4</li>
+      </bf-breadcrumb>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class BreadcrumbOverviewExampleComponent {
+  readonly status = signal('Two levels are hidden.');
+  readonly trail: readonly { id: string; label: string }[] = [
+    { id: 'workspace', label: 'Workspace' },
+    { id: 'projects', label: 'Projects' },
+    { id: 'atlas', label: 'Atlas' },
+    { id: 'releases', label: 'Releases' },
+  ];
+
+  onFocus(event: FocusEvent): void {
+    if (event.target instanceof HTMLAnchorElement) {
+      this.status.set(`Focus on ${event.target.text.trim()}.`);
+    }
+  }
+}
+```
+
+## Overview
+
+Desktop breadcrumb trail: a `nav` named "Breadcrumb" around an ordered list of
+`li[bfBreadcrumbItem]` levels, the last one the current page, a CSS chevron between them. With
+`maxItems` set and a longer trail it keeps the first level and the last `maxItems - 1`, and hides
+the middle ones behind an ellipsis button that shows them in place, or behind the consumer's own
+`bfSlot="overflow"` content (a menu button of the hidden levels).
+
+A breadcrumb trail for desktop web apps: a `nav` named "Breadcrumb" around an ordered list of the pages above the current one, each a link, with the current page last. Every level is the app's own `<li bfBreadcrumbItem>`, so the list stays `ol > li` and the links stay the app's `routerLink`s; the widget draws the chevrons between them, marks the current page and, with `maxItems`, collapses a long trail behind an ellipsis.
+
+## When to use
+
+Use `bf-breadcrumb` on a desktop page that sits deep in a hierarchy (a client's billing settings, a file in a folder), so the user sees where they are and can go up any number of levels. Don't use it for a flat app with one level, where the sidebar or the top nav already says where the user is. On mobile, in the Capacitor shell, use [bf-back-button](https://bitforge-ui.web.app/components/back-button) in [bf-header](https://bitforge-ui.web.app/components/header) instead.
+
+## Basic usage
+
+Put one `li[bfBreadcrumbItem]` per level inside `bf-breadcrumb`, from the root down: an `<a routerLink>` for each page above, plain text for the current page. The last item is always the current page; it gets `aria-current="page"` and no chevron. Import `BfBreadcrumbComponent` and `BfBreadcrumbItemComponent` from `@bitforgehq/ui`. The `nav` is named "Breadcrumb"; when a page shows more than one breadcrumb (as this page does, beside the site's own), give each a distinct `label`.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+
+/**
+ * A breadcrumb trail.
+ *
+ * Each level is the app's own `<li bfBreadcrumbItem>` holding a router link; the last one is the
+ * current page as plain text. `label` names the `nav`; this one is not the page's only breadcrumb
+ * (the docs site has its own), so it gets a name of its own.
+ */
+@Component({
+  selector: 'app-example-breadcrumb-basic',
+  imports: [RouterLink, BfBreadcrumbComponent, BfBreadcrumbItemComponent],
+  template: `
+    <bf-breadcrumb label="Docs breadcrumb">
+      <li bfBreadcrumbItem><a routerLink="/">Docs</a></li>
+      <li bfBreadcrumbItem><a routerLink="/components">Components</a></li>
+      <li bfBreadcrumbItem>Breadcrumb</li>
+    </bf-breadcrumb>
+  `,
+})
+export class BreadcrumbBasicExampleComponent {}
+```
+
+## Collapsing a long trail
+
+Set `maxItems` to collapse a trail with more levels than that: the first level and the last `maxItems - 1` stay, and the middle ones are hidden behind an ellipsis button ("Show 2 more levels", `provideBfLabels()`'s `breadcrumbExpand`). Pressing it shows every level in place and moves focus to the first one it revealed, so a keyboard user carries on from there. The trail collapses again when its levels change (on the next page). `0`, the default, never collapses; a value below 2 acts as 2, so the first level and the current page always stay.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+
+/**
+ * A long trail collapsed in place.
+ *
+ * `maxItems="4"` keeps the first level and the last three; the ellipsis button shows the two
+ * hidden ones in place and moves focus to the first of them. The demo's links stay on this page.
+ */
+@Component({
+  selector: 'app-example-breadcrumb-collapsed',
+  imports: [RouterLink, BfBreadcrumbComponent, BfBreadcrumbItemComponent],
+  template: `
+    <bf-breadcrumb label="Invoice breadcrumb" maxItems="4">
+      @for (level of trail; track level.id) {
+        <li bfBreadcrumbItem>
+          <a routerLink="." [fragment]="level.id">{{ level.label }}</a>
+        </li>
+      }
+      <li bfBreadcrumbItem>Invoice INV-204</li>
+    </bf-breadcrumb>
+  `,
+})
+export class BreadcrumbCollapsedExampleComponent {
+  readonly trail: readonly { id: string; label: string }[] = [
+    { id: 'home', label: 'Home' },
+    { id: 'clients', label: 'Clients' },
+    { id: 'meadow', label: 'Meadow Studio' },
+    { id: 'billing', label: 'Billing' },
+    { id: 'invoices', label: 'Invoices' },
+  ];
+}
+```
+
+## A menu of the hidden levels
+
+To keep the trail on one line, project your own control in `bfSlot="overflow"`: it takes the ellipsis button's place, after the first level. A `bf-menu-button` from `@bitforgehq/ui/overlay` with an `a[bfMenuItem]` link per hidden level is the usual one (a root widget cannot open a menu itself). The hidden levels are a slice of the array you already render: `trail.slice(1, count - maxItems + 1)`, where `count` includes the current page. Name the menu button with its `label`.
+
+```ts
+import { Component, computed } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+import { Ellipsis } from 'lucide';
+
+/**
+ * A long trail collapsed behind a menu.
+ *
+ * A `bf-menu-button` in `bfSlot="overflow"` replaces the ellipsis button: its menu links to the
+ * levels the trail hides, the same slice of the app's own array (`maxItems` 3 keeps the first
+ * level and the last two). The demo's links stay on this page.
+ */
+@Component({
+  selector: 'app-example-breadcrumb-collapsed-menu',
+  imports: [
+    RouterLink,
+    BfBreadcrumbComponent,
+    BfBreadcrumbItemComponent,
+    BfIconComponent,
+    BfMenuButtonComponent,
+    BfMenuComponent,
+    BfMenuItemDirective,
+  ],
+  template: `
+    <bf-breadcrumb label="Client breadcrumb" [maxItems]="maxItems">
+      <bf-menu-button
+        bfSlot="overflow"
+        [menu]="hiddenLevels"
+        iconOnly
+        label="Hidden levels"
+        variant="text"
+        size="sm"
+      >
+        <bf-icon [icon]="ellipsis" />
+      </bf-menu-button>
+      @for (level of trail; track level.id) {
+        <li bfBreadcrumbItem>
+          <a routerLink="." [fragment]="level.id">{{ level.label }}</a>
+        </li>
+      }
+      <li bfBreadcrumbItem>Invoice INV-204</li>
+    </bf-breadcrumb>
+
+    <ng-template #hiddenLevels>
+      <bf-menu>
+        @for (level of hidden(); track level.id) {
+          <a bfMenuItem routerLink="." [fragment]="level.id">{{ level.label }}</a>
+        }
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class BreadcrumbCollapsedMenuExampleComponent {
+  readonly ellipsis = Ellipsis;
+  readonly maxItems = 3;
+  readonly trail: readonly { id: string; label: string }[] = [
+    { id: 'home', label: 'Home' },
+    { id: 'clients', label: 'Clients' },
+    { id: 'meadow', label: 'Meadow Studio' },
+    { id: 'billing', label: 'Billing' },
+    { id: 'invoices', label: 'Invoices' },
+  ];
+  /** The levels between the first and the last `maxItems - 1` (the current page counts as one). */
+  readonly hidden = computed(() =>
+    this.trail.slice(1, this.trail.length + 1 - (this.maxItems - 1)),
+  );
+}
+```
+
+## Desktop
+
+`bf-breadcrumb` is a desktop pattern. A link turns from `text-muted` to `text` and is underlined on hover, with the pointer cursor; the ellipsis button takes a `surface-muted` fill on hover. The focus ring shows on keyboard focus only. Links keep the browser's behaviour: Ctrl/Cmd-click and a middle click open a level in a new tab. Under a coarse pointer (a touch laptop) every link is at least 44 px tall (`pointer-coarse:min-h-hit`) and the ellipsis button's hit area extends to 44 px. The trail wraps onto more lines when it does not fit; collapse it with `maxItems` to keep it short.
+
+## Theming
+
+- Text: `text-label-sm`; ancestor levels `text-muted`, `text` on hover; the current page `text`, semibold.
+- Separators: a 1.5 px CSS chevron in `text-subtle`, mirrored under `dir="rtl"`.
+- Links and the ellipsis button: `rounded-tile` and the `ring` focus ring; the ellipsis button's hover fill is `surface-muted`, its pressed fill `surface-pressed`.
+
+## Accessibility
+
+The host renders a `nav` landmark named by `label` (default "Breadcrumb", `provideBfLabels()`'s `breadcrumb`) around an `ol`, so a screen reader announces the number of levels; give a second breadcrumb on the same page another `label`. The current page is wrapped in a span with `aria-current="page"`. The chevrons are empty, `aria-hidden` elements, so the trail reads as its level names only. Hidden levels carry `hidden`, so they leave the accessibility tree until the ellipsis shows them; the ellipsis is a native `<button>` named "Show N more levels", and pressing it moves focus to the first revealed level's link (a level without a link takes focus itself). Content in `bfSlot="overflow"` brings its own name and keyboard handling.
+
+### Keyboard
+
+| Key                                 | Action                                                                        |
+| ----------------------------------- | ----------------------------------------------------------------------------- |
+| <kbd>Tab</kbd>                      | Moves through the links of the visible levels and the ellipsis button         |
+| <kbd>Enter</kbd>                    | Follows the focused link                                                      |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | On the ellipsis button: shows the hidden levels and focuses the first of them |
+
+## Inputs
+
+| Name       | Type     | Default | Description                                                                                                                                                                                                      |
+| ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`    | `string` | `''`    | Accessible name of the navigation; empty falls back to `provideBfLabels()`'s `breadcrumb` ("Breadcrumb").                                                                                                        |
+| `maxItems` | `number` | `0`     | Collapse a trail longer than this: keep the first level and the last `maxItems - 1` and hide the middle ones behind an ellipsis. `0` never collapses; values below 2 act as 2, so the current page always stays. |
+
+## Slots
+
+- `overflow`: Replaces the ellipsis button of a collapsed trail, e.g. a menu of the hidden levels.
+- `default`: The levels, each a `li[bfBreadcrumbItem]`, the current page last.
+
+## Notes
+
+### Do
+
+- Keep the labels short, the page titles users know, and the current page last as plain text.
+- Collapse a trail deeper than four or five levels with `maxItems`.
+
+### Don't
+
+- Don't link the current page, and don't put anything but `li[bfBreadcrumbItem]` levels (and the `overflow` slot) inside `bf-breadcrumb`.
+- Don't use a breadcrumb as the app's main navigation, and don't show it in the Capacitor shell.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-breadcrumb` in `@bitforgehq/ui`, the desktop breadcrumb trail: a `nav` (named by
+`label`, default `provideBfLabels()`'s new `breadcrumb` key, "Breadcrumb") around an `ol` of
+`li[bfBreadcrumbItem]` levels, with CSS chevrons between them that are never announced.
+`maxItems` collapses a longer trail to the first level and the last `maxItems - 1`, behind an
+ellipsis button (the new `breadcrumbExpand` label, "Show 2 more levels") that shows the hidden
+levels in place and focuses the first one; `bfSlot="overflow"` replaces that button with the app's
+own control, such as a `bf-menu-button` of the hidden levels. It replaces the hand-built
+breadcrumb the back-button docs showed.

package/ai/components/button.md

@@ -95,12 +95,12 @@ export class ButtonOverviewExampleComponent {
 
 Also matches: `a[bfButton]`
 
-Pill-shaped action button with five variants, three sizes, a loading state and icon slots. Put
+Pill-shaped action button with six variants, three sizes, a loading state and icon slots. Put
 the label in the default slot and icons in the `icon-start` / `icon-end` slots; never place a
 `bf-button` inside another interactive element. For navigation, put `bfButton` on your own `<a>`
 (with `href` or `routerLink`): it renders as a real link that looks like the button.
 
-Buttons trigger an action or move the user forward. The shape is a pill in every variant; the variant encodes emphasis, so a screen reads correctly at a glance: one `primary`, `tonal` beside it, `text` for low-emphasis actions inside cards and rows.
+Buttons trigger an action or move the user forward. The shape is a pill in every variant; the variant encodes emphasis, so a screen reads correctly at a glance: one `primary`, `tonal` beside it, `text` for low-emphasis actions inside cards and rows, `ghost` for quiet neutral actions and navigation.
 
 ## When to use
 
@@ -140,13 +140,13 @@ export class ButtonBasicExampleComponent {
 
 ## Variants
 
-`primary` (filled sage), `tonal` (soft tint), `outline`, `text` and `danger`.
+`primary` (filled), `tonal` (soft tint), `outline`, `text`, `danger` and `ghost`. `ghost` is the quiet neutral one: muted text with no fill at rest and a neutral surface on hover, with the `text` variant's padding. Use it for secondary toolbar actions and navigation rows, where a row of `text` buttons would read as a row of coloured links and `tonal` would tint every one. `variant` takes a `BfButtonAppearance` (the five `BfButtonVariant` styles plus `ghost`).
 
 ```ts
 import { Component } from '@angular/core';
 import { BfButtonComponent } from '@bitforgehq/ui';
 
-/** The five button variants. */
+/** The six button variants. */
 @Component({
   selector: 'app-example-button-variants',
   imports: [BfButtonComponent],
@@ -157,6 +157,7 @@ import { BfButtonComponent } from '@bitforgehq/ui';
       <bf-button variant="outline">Outline</bf-button>
       <bf-button variant="text">Text</bf-button>
       <bf-button variant="danger">Delete</bf-button>
+      <bf-button variant="ghost">Ghost</bf-button>
     </div>
   `,
 })
@@ -300,9 +301,57 @@ export class ButtonLinkExampleComponent {
 }
 ```
 
+## Navigation
+
+A row of `a[bfButton variant="ghost"]` is a top navigation or a sidebar. The link of the current page shows it: `ghost` and `text` links with `aria-current="page"` take the tonal fill (`outline` draws its border in primary), so the template needs no `[variant]` switch. With the router, add `routerLinkActive` and `ariaCurrentWhenActive="page"` to each link and the router sets `aria-current` for you. Put the links in a `<nav>` with an `aria-label`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+
+interface NavLink {
+  readonly id: string;
+  readonly label: string;
+}
+
+/**
+ * A top navigation of ghost links.
+ *
+ * The current page carries `aria-current="page"` and shows it; with the router,
+ * `routerLinkActive` and `ariaCurrentWhenActive="page"` set it instead of the click handler.
+ */
+@Component({
+  selector: 'app-example-button-nav',
+  imports: [BfButtonComponent],
+  template: `
+    <nav aria-label="Main" class="flex flex-wrap items-center gap-1">
+      @for (link of links; track link.id) {
+        <a
+          bfButton
+          variant="ghost"
+          [href]="'#' + link.id"
+          [attr.aria-current]="link.id === current() ? 'page' : null"
+          (click)="$event.preventDefault(); current.set(link.id)"
+          >{{ link.label }}</a
+        >
+      }
+    </nav>
+  `,
+})
+export class ButtonNavExampleComponent {
+  protected readonly links: readonly NavLink[] = [
+    { id: 'overview', label: 'Overview' },
+    { id: 'projects', label: 'Projects' },
+    { id: 'team', label: 'Team' },
+    { id: 'settings', label: 'Settings' },
+  ];
+  protected readonly current = signal('overview');
+}
+```
+
 ## Desktop
 
-Hover darkens the fill (`primary`, `tonal`, `danger`), the border (`outline`) or the text (`text`), with the pointer cursor; a disabled button shows `not-allowed`. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The focus ring shows on keyboard focus only (`focus-visible`), never after a mouse click. Under a fine pointer the visible box is the hit area, so `sm` (32 px) buttons sit side by side in toolbars and table rows without overlapping hit areas. Desktop density is the default `md` step; `provideBfDefaults({ size: 'sm' })`, or `{ size: 'sm' }` in a component's `providers`, makes a dense toolbar, table or sidebar ([density guide](https://bitforge-ui.web.app/density)).
+Hover darkens the fill (`primary`, `tonal`, `danger`), the border (`outline`) or the text (`text`), or lays a neutral surface under `ghost`, with the pointer cursor; a disabled button shows `not-allowed`. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The focus ring shows on keyboard focus only (`focus-visible`), never after a mouse click. Under a fine pointer the visible box is the hit area, so `sm` (32 px) buttons sit side by side in toolbars and table rows without overlapping hit areas. Desktop density is the default `md` step; `provideBfDefaults({ size: 'sm' })`, or `{ size: 'sm' }` in a component's `providers`, makes a dense toolbar, table or sidebar ([density guide](https://bitforge-ui.web.app/density)).
 
 ## Theming
 
@@ -313,10 +362,16 @@ Consumes tokens by variant, rest → hover:
 - `outline`: `surface` / `text` / `border-strong` (the control boundary, ≥ 3:1) → `text-muted` border; focus swaps the border to `primary`
 - `text`: `primary-text` (primary as text, ≥ 4.5:1 on `bg` and `surface`) → `primary-strong`
 - `danger`: `danger-soft` / `danger` → `danger` / `danger-soft`
+- `ghost`: transparent / `text-muted` → `surface-muted` / `text`
+
+Current page (`a[bfButton]` with `aria-current="page"`): `ghost` and `text` take `primary-soft` /
+`primary-strong` (→ `primary-soft-hover` on hover, `primary-soft-pressed` while pressed), `outline` a `primary` border with
+`primary-strong` text; under forced colours a `LinkText` outline marks it instead.
 
 Pressed (while the mouse button, a touch or the Space key holds it down): `primary` →
 `primary-pressed`; `tonal`, `outline` and `text` → `primary-soft-pressed` (the `text` label turns
-`primary-strong`); `danger` → `danger-pressed` with `danger-soft` text. `a[bfButton]` presses the
+`primary-strong`); `danger` → `danger-pressed` with `danger-soft` text; `ghost` →
+`surface-pressed` with `text`. `a[bfButton]` presses the
 same way. A disabled or loading button has no pressed state, and under forced colours the system
 colours win.
 
@@ -328,7 +383,7 @@ Icon and label sit 8 px apart. A label longer than its container truncates with
 
 `bf-button` renders a native `<button>`; its `type` reflects the `type` input. Native `disabled` is set only by `disabled`. While `loading`, the button stays focusable and in the tab order with `aria-disabled="true"` and `aria-busy="true"`, so focus does not fall to `<body>` when an action starts; a click or Enter/Space is cancelled (`preventDefault`) and emits nothing. The spinner inside is `decorative`, so it adds no second status announcement; announce the outcome in your own message. Being a real button, it gets keyboard activation (Enter/Space) and the button role for free — no ARIA role is added. The focus-visible ring uses the `ring` token.
 
-`a[bfButton]` is your own `<a>`, so it keeps the link role and link keyboard behaviour ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)): it is exposed as `link`, is in the tab order while it has an `href` (in Safari and iOS WKWebView, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise); VoiceOver and Full Keyboard Access are unaffected), activates with Enter only, and opens in a new tab with Ctrl/Cmd-click. Use it whenever activation navigates to a URL, and `bf-button` whenever it performs an action on the page ([APG button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)). No ARIA is added, and none of `disabled`, `loading` or `type` applies.
+`a[bfButton]` is your own `<a>`, so it keeps the link role and link keyboard behaviour ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)): it is exposed as `link`, is in the tab order while it has an `href` (in Safari and iOS WKWebView, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise); VoiceOver and Full Keyboard Access are unaffected), activates with Enter only, and opens in a new tab with Ctrl/Cmd-click. Use it whenever activation navigates to a URL, and `bf-button` whenever it performs an action on the page ([APG button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)). No ARIA is added, and none of `disabled`, `loading` or `type` applies. The current page is the `aria-current="page"` you (or `routerLinkActive` with `ariaCurrentWhenActive`) set: screen readers announce it ("current page"), and the fill only mirrors it.
 
 ### Keyboard
 
@@ -340,14 +395,14 @@ Icon and label sit 8 px apart. A label longer than its container truncates with
 
 ## Inputs
 
-| Name        | Type                                                                          | Default     | Description                                                                                                                                                                                                  |
-| ----------- | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `variant`   | `BfButtonVariant` (`'primary' \| 'tonal' \| 'outline' \| 'text' \| 'danger'`) | `'primary'` | Visual style: primary (filled), tonal (soft tint), outline, text, danger.                                                                                                                                    |
-| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)                   | `undefined` | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                                                                                                   |
-| `type`      | `BfButtonType` (`'button' \| 'submit' \| 'reset'`)                            | `'button'`  | Native button type. Use `submit` inside a form. Ignored on `a[bfButton]`.                                                                                                                                    |
-| `disabled`  | `boolean`                                                                     | `false`     | Disables the control and swallows clicks. Ignored on `a[bfButton]`: a link is never disabled; render a disabled `bf-button` instead.                                                                         |
-| `loading`   | `boolean`                                                                     | `false`     | Shows a spinner instead of the start icon and blocks activation. The button stays focusable (`aria-disabled` and `aria-busy`, never native `disabled`) and keeps its variant fill. Ignored on `a[bfButton]`. |
-| `fullWidth` | `boolean`                                                                     | `false`     | Stretches the button to its container's width.                                                                                                                                                               |
+| Name        | Type                                                                                        | Default     | Description                                                                                                                                                                                                  |
+| ----------- | ------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `variant`   | `BfButtonAppearance` (`'primary' \| 'tonal' \| 'outline' \| 'text' \| 'danger' \| 'ghost'`) | `'primary'` | Visual style: primary (filled), tonal (soft tint), outline, text, danger, or ghost (quiet neutral). On `a[bfButton]`, `ghost`, `text` and `outline` also show `aria-current="page"`.                         |
+| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)                                 | `undefined` | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                                                                                                   |
+| `type`      | `BfButtonType` (`'button' \| 'submit' \| 'reset'`)                                          | `'button'`  | Native button type. Use `submit` inside a form. Ignored on `a[bfButton]`.                                                                                                                                    |
+| `disabled`  | `boolean`                                                                                   | `false`     | Disables the control and swallows clicks. Ignored on `a[bfButton]`: a link is never disabled; render a disabled `bf-button` instead.                                                                         |
+| `loading`   | `boolean`                                                                                   | `false`     | Shows a spinner instead of the start icon and blocks activation. The button stays focusable (`aria-disabled` and `aria-busy`, never native `disabled`) and keeps its variant fill. Ignored on `a[bfButton]`. |
+| `fullWidth` | `boolean`                                                                                   | `false`     | Stretches the button to its container's width.                                                                                                                                                               |
 
 ## Outputs
 
@@ -368,10 +423,12 @@ Icon and label sit 8 px apart. A label longer than its container truncates with
 - Use `primary` once per screen for the main action; `tonal` for secondary actions next to it; `text` for low-emphasis actions inside cards and lists.
 - Bind `[loading]` to the pending state of the action so the user gets feedback and cannot double-submit.
 - Use `type="submit"` inside a `<form>` so Enter submits.
+- Build a top nav or a sidebar from `a[bfButton variant="ghost"]` with `routerLinkActive` and `ariaCurrentWhenActive="page"`.
 
 ### Don't
 
 - Don't nest `bf-button` in an `<a>` or another button, and don't navigate from `(clicked)`; put `bfButton` on the `<a>` itself (`<a bfButton routerLink="…">`).
+- Don't switch `[variant]` to mark the current page; set `aria-current="page"` and the link shows it.
 - Don't disable a link; render a disabled `bf-button` while the destination is unavailable.
 - Don't add `dark:` classes or colors on the element; the theme handles both.
 - Don't put a `bf-icon` in the default slot; use the `icon-start` / `icon-end` slots so spacing stays right.
@@ -379,6 +436,16 @@ Icon and label sit 8 px apart. A label longer than its container truncates with
 
 ## Migration notes
 
+### 0.3.1
+
+New `ghost` variant: quiet and neutral (`text-muted` label, no fill at rest, `surface-muted` on
+hover, `surface-pressed` on press), with the `text` variant's sizes, padding and disabled state,
+for secondary toolbar actions and navigation rows. `a[bfButton]` with `aria-current="page"` shows
+the current page: `ghost` and `text` links take the tonal fill, `outline` a primary border, so a
+top nav built with `routerLinkActive` and `ariaCurrentWhenActive="page"` needs no `[variant]`
+switch. `variant` is now typed `BfButtonAppearance` (the five `BfButtonVariant` styles plus
+`ghost`); `BfButtonVariant` keeps its five members, so code that maps over it keeps compiling.
+
 ### 0.3.0
 
 **Behaviour:** `size` is a `BfSize` and, unset, follows `provideBfDefaults()`'s `controlSize`