shelving 1.236.2 → 1.237.0

package/ui/block/Section.md

@@ -0,0 +1,56 @@
+# Section
+
+A landmark content region — renders a `<section>` with block-level spacing and a constrained content width. `Section.tsx` exports the whole family of semantic landmarks (`Section`, `Header`, `Footer`, `Nav`, `Aside`, `Figure`) — they share `SectionProps` and differ only in the HTML element they render.
+
+**Things to know:**
+
+- Pick the component whose HTML element matches the semantic meaning rather than reaching for a generic [`Block`](/ui/Block). `<Section>` is a `<section>`, `<Nav>` a `<nav>`, `<Figure>` a `<figure>`, and so on.
+- Every section centres its content and caps the line length so text never touches the viewport edges. Nested sections relax that cap so they can fill their parent.
+- Pass `narrow` / `wide` / `full` to constrain or unconstrain the width, and the usual `color` / `space` / typography variants to retint and respace.
+- Pair [`Figure`](/ui/Section) with [`Caption`](/ui/Caption) for a `<figure>` / `<figcaption>` pair.
+
+## Usage
+
+### Structured page section
+
+```tsx
+import { Section, Heading, Definitions } from "shelving/ui";
+
+<Section narrow>
+  <Heading>Account details</Heading>
+  <Definitions>
+    <dt>Name</dt><dd>Alice Smith</dd>
+    <dt>Email</dt><dd>alice@example.com</dd>
+    <dt>Plan</dt><dd>Pro</dd>
+  </Definitions>
+</Section>
+```
+
+### Landmark elements
+
+```tsx
+import { Header, Nav, Footer } from "shelving/ui";
+
+<Header><Title>Welcome</Title></Header>
+<Nav><Link href="/">Home</Link></Nav>
+<Footer><Small>© 2026</Small></Footer>
+```
+
+## Styling
+
+`Section` exposes hooks for its width and rhythm; it paints no colour of its own, so it inherits the surrounding tint.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--section-width` | Content width | `100%` |
+| `--section-indent` | Inline gutter kept on each side so text doesn't touch the edges | `var(--space-normal)` (16px) |
+| `--section-space` | Outer block margin (top + bottom) | `var(--space-section)` (2rem) |
+
+**Global tokens it reads:** `--space-normal` and `--space-section`. The `narrow` / `wide` / `full` width variants come from the shared [`ui`](/ui) styling system.
+
+## See also
+
+- [`Block`](/ui/Block) — the unstyled `<div>` equivalent when no landmark semantics are needed.
+- [`Panel`](/ui/Panel) — a full-width band that paints the surface; sections sit inside the inner block.
+- [`Caption`](/ui/Caption) — the `<figcaption>` that pairs with `Figure`.
+- [`ui`](/ui) — the styling system: width variants, tint ladder, and theming.

package/ui/block/Section.tsx

@@ -60,6 +60,7 @@ function renderSection(
  * `<section>` block with block-level spacing.
  * - Pass `as` to render a different semantic element.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<section>` element.
  * @example <Section><Heading>About</Heading></Section>
@@ -72,6 +73,7 @@ export function Section(props: SectionProps): ReactElement {
 /**
  * `<header>` block with block-level spacing.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<header>` element.
  * @example <Header><Title>Welcome</Title></Header>
@@ -84,6 +86,7 @@ export function Header(props: SectionProps): ReactElement {
 /**
  * `<footer>` block with block-level spacing.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<footer>` element.
  * @example <Footer><Small>© 2026</Small></Footer>
@@ -96,6 +99,7 @@ export function Footer(props: SectionProps): ReactElement {
 /**
  * `<nav>` block with block-level spacing.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<nav>` element.
  * @example <Nav><Link href="/">Home</Link></Nav>
@@ -108,6 +112,7 @@ export function Nav(props: SectionProps): ReactElement {
 /**
  * `<aside>` block with block-level spacing.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<aside>` element.
  * @example <Aside narrow><Paragraph>Sidebar</Paragraph></Aside>
@@ -120,6 +125,7 @@ export function Aside(props: SectionProps): ReactElement {
 /**
  * `<figure>` block with block-level spacing. Pair with `<Caption>` for `<figcaption>` content.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<figure>` element.
  * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>

package/ui/block/Subheading.d.ts

@@ -22,6 +22,7 @@ export type SubheadingProps = HeadingProps;
  * Subsection heading — renders an `<h3>`.
  * - Only marginally larger than body text; its bold weight is the main differentiator.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
  * @returns Rendered `<h3>` heading element.
  * @example <Subheading>Details</Subheading>

package/ui/block/Subheading.js

@@ -20,6 +20,7 @@ export const SUBHEADING_PROSE_CLASS = getModuleClass(SUBHEADING_CSS, "prose");
  * Subsection heading — renders an `<h3>`.
  * - Only marginally larger than body text; its bold weight is the main differentiator.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
  * @returns Rendered `<h3>` heading element.
  * @example <Subheading>Details</Subheading>

package/ui/block/Subheading.md

@@ -0,0 +1,58 @@
+# Subheading
+
+A subsection heading — renders an `<h3>`. It is the smallest member of the three-level heading family: [`Title`](/ui/Title) (`<h1>`), [`Heading`](/ui/Heading) (`<h2>`), `Subheading` (`<h3>`). Use it for card titles, in-section labels, and panel titles.
+
+**Things to know:**
+
+- Only marginally larger than body text; its bold weight is the main differentiator.
+- Pick the component that matches the level rather than overriding `level` — that keeps the visual size and the document outline in step.
+- The `level` prop (`1`–`6`) is an escape hatch for the rare case where the outline level must differ from the visual size — avoid it in normal use.
+- Inherits text colour by default so it picks up the surrounding tint; accepts `color=` and the typography variants.
+- Inside [`Prose`](/ui/Prose) raw `<h3>`–`<h6>` are styled by the same rules, so Markdown-rendered subheadings match component ones.
+
+## Usage
+
+### Card title
+
+```tsx
+import { Card, Subheading, Paragraph } from "shelving/ui";
+
+<Card>
+  <Subheading>Storage</Subheading>
+  <Paragraph>1.2 GB of 5 GB used.</Paragraph>
+</Card>
+```
+
+### The heading family together
+
+```tsx
+import { Title, Heading, Subheading } from "shelving/ui";
+
+<Title>Account</Title>            {/* <h1> */}
+<Heading>Security</Heading>       {/* <h2> */}
+<Subheading>Sessions</Subheading> {/* <h3> */}
+```
+
+## Styling
+
+`Subheading` exposes hooks for its rhythm and type. It inherits text colour by default; set `--subheading-color` only to override that.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--subheading-tint` | Tint anchor for the subheading scope | `inherit` (flows from `color=` / parent) |
+| `--subheading-color` | Text colour | `inherit` |
+| `--subheading-space-before` | Top margin | `var(--space-section)` (2rem) |
+| `--subheading-space` | Bottom margin | `var(--space-paragraph)` (16px) |
+| `--subheading-font` | Font family | `var(--font-title)` |
+| `--subheading-weight` | Font weight | `var(--weight-strong)` (700) |
+| `--subheading-size` | Font size | `var(--size-large)` |
+| `--subheading-leading` | Line height | `var(--leading)` |
+
+**Global tokens it reads:** `--space-section`, `--space-paragraph`, `--font-title`, `--weight-strong`, `--size-large`, and `--leading`.
+
+## See also
+
+- [`Heading`](/ui/Heading) — the `<h2>` section heading one level up.
+- [`Title`](/ui/Title) — the top-level page `<h1>`.
+- [`Card`](/ui/Card) — a boxed surface whose title is usually a `Subheading`.
+- [`ui`](/ui) — the styling system: tint ladder, typography variants, and theming.

package/ui/block/Subheading.tsx

@@ -31,6 +31,7 @@ export type SubheadingProps = HeadingProps;
  * Subsection heading — renders an `<h3>`.
  * - Only marginally larger than body text; its bold weight is the main differentiator.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
  * @returns Rendered `<h3>` heading element.
  * @example <Subheading>Details</Subheading>

package/ui/block/Table.d.ts

@@ -27,6 +27,7 @@ export interface TableProps extends ColorVariants, SpaceVariants, TypographyVari
  * - Wrap in a `<Scroll horizontal>` if the table may exceed the container width on small screens.
  * - `<th>` / `<td>` cells draw the borders (the `<table>` element itself has none); override their weight via the `--table-border` / `--table-stroke` hooks.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus `children`.
  * @returns Rendered `<table>` element.
  * @example <Table><tbody><tr><td>Cell</td></tr></tbody></Table>

package/ui/block/Table.js

@@ -21,6 +21,7 @@ export const TABLE_PROSE_CLASS = getModuleClass(TABLE_CSS, "prose");
  * - Wrap in a `<Scroll horizontal>` if the table may exceed the container width on small screens.
  * - `<th>` / `<td>` cells draw the borders (the `<table>` element itself has none); override their weight via the `--table-border` / `--table-stroke` hooks.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus `children`.
  * @returns Rendered `<table>` element.
  * @example <Table><tbody><tr><td>Cell</td></tr></tbody></Table>

package/ui/block/Table.md

@@ -0,0 +1,54 @@
+# Table
+
+A data table — renders a `<table>`. Compose the usual `<thead>` / `<tbody>` / `<tfoot>`, `<tr>`, `<th>`, and `<td>` markup inside it; the component supplies the spacing, borders, and label typography.
+
+**Things to know:**
+
+- The `<table>` element itself draws no borders — the `<th>` / `<td>` cells do. Header (`<thead>`) and footer (`<tfoot>`) cells render in the smaller, uppercase label style.
+- First and last cells in a row drop their outer inline padding so the table aligns flush with the surrounding text column.
+- Wrap a wide table in a horizontally scrollable container if it may exceed the content width on small screens.
+- Like the other block components it collapses its outer block margin when it is the first or last child.
+- Inside [`Prose`](/ui/Prose) a raw `<table>` picks up the same styling, so Markdown-rendered tables match component ones.
+
+## Usage
+
+### Basic table
+
+```tsx
+import { Table } from "shelving/ui";
+
+<Table>
+  <thead>
+    <tr><th>Name</th><th>Plan</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>Alice</td><td>Pro</td></tr>
+    <tr><td>Bob</td><td>Free</td></tr>
+  </tbody>
+</Table>
+```
+
+## Styling
+
+`Table` exposes hooks for its rhythm, cell padding, and border; it paints no surface of its own, so it inherits the surrounding tint.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--table-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
+| `--table-padding` | Cell padding (block + inline) | `var(--space-xsmall)` |
+| `--table-border` | Cell border shorthand | `var(--table-stroke)` |
+| `--table-stroke` | Cell border thickness/colour | `var(--stroke-normal) solid var(--tint-80)` |
+| `--table-header-weight` | Weight of `<thead>` / `<tfoot>` / `<tbody> <th>` cells | `var(--weight-strong)` |
+| `--table-label-font` | Label font for `<thead>` / `<tfoot>` `<th>` | `var(--font-label)` |
+| `--table-label-weight` | Label weight | `var(--weight-label)` |
+| `--table-label-size` | Label size | `var(--size-label)` |
+| `--table-label-case` | Label letter case | `var(--case-label)` |
+| `--table-label-color` | Label colour | `var(--tint-70)` |
+
+**Global tokens it reads:** `--space-paragraph`, `--space-xsmall`, `--stroke-normal`, the tint-ladder steps `--tint-70` / `--tint-80`, and the label tokens `--font-label` / `--weight-label` / `--size-label` / `--case-label` / `--weight-strong`.
+
+## See also
+
+- [`Definitions`](/ui/Definitions) — term/value pairs when a two-column key/value layout fits better than a grid.
+- [`Prose`](/ui/Prose) — styles raw `<table>` inside longform content.
+- [`ui`](/ui) — the styling system: tint ladder, label tokens, and theming.

package/ui/block/Table.tsx

@@ -32,6 +32,7 @@ export interface TableProps extends ColorVariants, SpaceVariants, TypographyVari
  * - Wrap in a `<Scroll horizontal>` if the table may exceed the container width on small screens.
  * - `<th>` / `<td>` cells draw the borders (the `<table>` element itself has none); override their weight via the `--table-border` / `--table-stroke` hooks.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus `children`.
  * @returns Rendered `<table>` element.
  * @example <Table><tbody><tr><td>Cell</td></tr></tbody></Table>

package/ui/block/Title.d.ts

@@ -22,6 +22,7 @@ export type TitleProps = HeadingProps;
  * Page title — renders an `<h1>`.
  * - The most prominent heading on a page; there should normally be exactly one.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
  * @returns Rendered `<h1>` heading element.
  * @example <Title>Welcome</Title>

package/ui/block/Title.js

@@ -20,6 +20,7 @@ export const TITLE_PROSE_CLASS = getModuleClass(TITLE_CSS, "prose");
  * Page title — renders an `<h1>`.
  * - The most prominent heading on a page; there should normally be exactly one.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
  * @returns Rendered `<h1>` heading element.
  * @example <Title>Welcome</Title>

package/ui/block/Title.md

@@ -0,0 +1,57 @@
+# Title
+
+The top-level page heading — renders an `<h1>`. It is the most prominent member of the three-level heading family: `Title` (`<h1>`), [`Heading`](/ui/Heading) (`<h2>`), [`Subheading`](/ui/Subheading) (`<h3>`). There should normally be exactly one `Title` per page.
+
+**Things to know:**
+
+- Pick the component that matches the level rather than overriding `level`. Choosing `Title` / `Heading` / `Subheading` keeps the visual size and the document outline in step.
+- The `level` prop (`1`–`6`) is an escape hatch for the rare case where the outline level must differ from the visual size — avoid it in normal use.
+- Inherits text colour by default so it picks up the surrounding tint; accepts `color=` and the typography variants.
+- Inside [`Prose`](/ui/Prose) a raw `<h1>` is styled by the same rules, so Markdown-rendered titles match component ones.
+
+## Usage
+
+### Page title
+
+```tsx
+import { Title, Paragraph } from "shelving/ui";
+
+<Title>Account</Title>
+<Paragraph>Manage your profile and settings.</Paragraph>
+```
+
+### Inside a panel header
+
+```tsx
+import { Panel, Block, Title } from "shelving/ui";
+
+<Panel as="header" color="primary">
+  <Block narrow>
+    <Title>Welcome</Title>
+  </Block>
+</Panel>
+```
+
+## Styling
+
+`Title` exposes hooks for its rhythm and type. It inherits text colour by default; set `--title-color` only to override that.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--title-tint` | Tint anchor for the title scope | `inherit` (flows from `color=` / parent) |
+| `--title-color` | Text colour | `inherit` |
+| `--title-space-before` | Top margin | `var(--space-section)` (2rem) |
+| `--title-space` | Bottom margin | `var(--space-paragraph)` (16px) |
+| `--title-font` | Font family | `var(--font-title)` |
+| `--title-weight` | Font weight | `var(--weight-strong)` (700) |
+| `--title-size` | Font size | `var(--size-xxxlarge)` |
+| `--title-leading` | Line height | `var(--leading)` |
+
+**Global tokens it reads:** `--space-section`, `--space-paragraph`, `--font-title`, `--weight-strong`, `--size-xxxlarge`, and `--leading`.
+
+## See also
+
+- [`Heading`](/ui/Heading) — the `<h2>` section heading that pairs with `Title`.
+- [`Subheading`](/ui/Subheading) — the `<h3>` subsection heading.
+- [`Section`](/ui/Section) — wraps a title and its content as a landmark region.
+- [`ui`](/ui) — the styling system: tint ladder, typography variants, and theming.

package/ui/block/Title.tsx

@@ -31,6 +31,7 @@ export type TitleProps = HeadingProps;
  * Page title — renders an `<h1>`.
  * - The most prominent heading on a page; there should normally be exactly one.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
  * @returns Rendered `<h1>` heading element.
  * @example <Title>Welcome</Title>

package/ui/dialog/Dialog.d.ts

@@ -16,6 +16,7 @@ export interface DialogProps extends OptionalChildProps {
  * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, or the close button.
  * - Wraps content in `<Suspense>` so lazy children can stream in.
  *
+ * @kind component
  * @example dialogs.show(<Dialog><p>Are you sure?</p></Dialog>);
  * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/Dialog
  */

package/ui/dialog/Dialog.js

@@ -9,6 +9,7 @@ import styles from "./Dialog.module.css";
  * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, or the close button.
  * - Wraps content in `<Suspense>` so lazy children can stream in.
  *
+ * @kind component
  * @example dialogs.show(<Dialog><p>Are you sure?</p></Dialog>);
  * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/Dialog
  */

package/ui/dialog/Dialog.md

@@ -0,0 +1,73 @@
+# Dialog
+
+A native `<dialog>` element opened in modal mode. It opens via `showModal()` when mounted and includes a built-in close button, so it works equally well mounted declaratively in the tree or pushed imperatively through a [`DialogsStore`](/ui/DialogsStore).
+
+**Things to know:**
+
+- Closes on a backdrop click, on any link or `<nav>` button clicked inside it, or via the built-in [`DialogCloseButton`](/ui/DialogCloseButton) (an X icon, top-right).
+- Children render inside a `<Suspense>` boundary, so lazy content can stream in.
+- `onClose` fires when the dialog closes — use it to clear the React state that mounts the dialog, or (when pushed via a store) to remove it from the list.
+- Pair with [`DialogsStore`](/ui/DialogsStore), [`DialogsContext`](/ui/DialogsContext), and [`Dialogs`](/ui/Dialogs) to open dialogs imperatively from anywhere in the app. For a non-blocking persistent overlay, reach for [`Modal`](/ui/Modal) instead.
+
+## Usage
+
+### Declarative
+
+Mount `<Dialog>` directly when its lifetime matches a React state variable.
+
+```tsx
+import { Dialog, DialogCloseButton } from "shelving/ui";
+
+function ConfirmDelete({ onConfirm, onClose }: { onConfirm: () => void; onClose: () => void }) {
+  return (
+    <Dialog onClose={onClose}>
+      <p>Delete this item?</p>
+      <button type="button" onClick={onConfirm}>Delete</button>
+      <DialogCloseButton />
+    </Dialog>
+  );
+}
+
+// In the parent:
+{showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => setShowConfirm(false)} />}
+```
+
+### Imperative
+
+Set up the context once near the app root (see [`DialogsContext`](/ui/DialogsContext) and [`Dialogs`](/ui/Dialogs)), then push a `<Dialog>` from anywhere with [`requireDialogs()`](/ui/requireDialogs).
+
+```tsx
+import { requireDialogs } from "shelving/ui";
+
+function DeleteButton({ id }: { id: string }) {
+  const dialogs = requireDialogs();
+  const open = () => dialogs.show(
+    <ConfirmDelete id={id} onConfirm={() => handleDelete(id)} />,
+  );
+  return <button type="button" onClick={open}>Delete</button>;
+}
+```
+
+`dialogs.show()` wraps the content in a `<Dialog>` for you, so you pass plain children rather than a `<Dialog>` element.
+
+## Styling
+
+`Dialog` paints the full-screen overlay; the inner panel is laid out by its children. Override these hooks at `:root` (or any ancestor scope) to retheme.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--dialog-padding` | Padding around the centred content | `var(--space-normal)` (16px) |
+| `--dialog-color-overlay` | Backdrop fill behind the content | `var(--color-shadow)` |
+| `--dialog-transition` | Open / close transition | `all var(--duration-fast)` (150ms) |
+| `--dialog-close-offset` | Inset of the close button from the top-right corner | `var(--space-small)` (8px) |
+
+**Global tokens it reads** — move these to retheme broadly: `--space-normal`, `--space-small`, `--color-shadow`, and `--duration-fast`.
+
+## See also
+
+- [`Modal`](/ui/Modal) — a non-blocking `<aside>` overlay for persistent panels.
+- [`DialogsStore`](/ui/DialogsStore) — push dialogs imperatively; `.show()` and `.hideAll()`.
+- [`DialogsContext`](/ui/DialogsContext) / [`Dialogs`](/ui/Dialogs) — provide a store and render its open dialogs.
+- [`notice`](/ui) — inline and global notices (toasts, banners).
+- [`form`](/ui) — form components to put inside dialogs.
+- [`transition`](/ui) — animate dialog enter / leave.

package/ui/dialog/Dialog.tsx

@@ -21,6 +21,7 @@ export interface DialogProps extends OptionalChildProps {
  * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, or the close button.
  * - Wraps content in `<Suspense>` so lazy children can stream in.
  *
+ * @kind component
  * @example dialogs.show(<Dialog><p>Are you sure?</p></Dialog>);
  * @see https://dhoulb.github.io/shelving/ui/dialog/Dialog/Dialog
  */

package/ui/dialog/Modal.d.ts

@@ -10,6 +10,7 @@ export interface ModalProps extends OptionalChildProps {
 /**
  * Styled `<aside>` overlay container for modal content.
  *
+ * @kind component
  * @param children The modal content.
  * @returns The modal container element.
  * @example <Modal><p>Modal content</p></Modal>

package/ui/dialog/Modal.js

@@ -3,6 +3,7 @@ import styles from "./Modal.module.css";
 /**
  * Styled `<aside>` overlay container for modal content.
  *
+ * @kind component
  * @param children The modal content.
  * @returns The modal container element.
  * @example <Modal><p>Modal content</p></Modal>

package/ui/dialog/Modal.md

@@ -0,0 +1,40 @@
+# Modal
+
+A non-blocking `<aside>` overlay for persistent panels — drawers, toasts, and side-sheets that coexist with the page rather than blocking interaction with it. Unlike [`Dialog`](/ui/Dialog), it is not a native `<dialog>` and does not trap focus or dim the page.
+
+**Things to know:**
+
+- Reach for `Modal` when the overlay should sit alongside the page (a notification panel, a side drawer); reach for [`Dialog`](/ui/Dialog) when it should block interaction until dismissed.
+- It only styles the box — lay out its contents with the usual block components.
+
+## Usage
+
+```tsx
+import { Modal } from "shelving/ui";
+
+<Modal>
+  <NotificationPanel />
+</Modal>
+```
+
+## Styling
+
+`Modal` paints a bordered, shadowed surface. Override these hooks at `:root` (or any ancestor scope) to retheme.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--modal-width` | Box width | `var(--width-narrow)` |
+| `--modal-border` | Border shorthand | `var(--stroke-normal)` solid, 50% of `--tint-50` |
+| `--modal-radius` | Corner radius | `var(--radius-normal)` (16px) |
+| `--modal-color-bg` | Surface fill | `var(--tint-100)` |
+| `--modal-padding` | Inner padding | `var(--space-normal)` (16px) |
+| `--modal-color-text` | Text colour | `var(--tint-00)` |
+| `--modal-transition` | Transition | `all var(--duration-fast)` (150ms) |
+| `--modal-shadow` | Drop shadow | `var(--shadow-normal)` |
+
+**Global tokens it reads** — move these to retheme broadly: the tint ladder `--tint-00` / `--tint-50` / `--tint-100`, plus `--width-narrow`, `--space-normal`, `--radius-normal`, `--stroke-normal`, `--shadow-normal`, and `--duration-fast`.
+
+## See also
+
+- [`Dialog`](/ui/Dialog) — a blocking modal `<dialog>` with backdrop and close button.
+- [`Dialogs`](/ui/Dialogs) — render imperatively-pushed dialogs near the app root.

package/ui/dialog/Modal.tsx

@@ -12,6 +12,7 @@ export interface ModalProps extends OptionalChildProps {}
 /**
  * Styled `<aside>` overlay container for modal content.
  *
+ * @kind component
  * @param children The modal content.
  * @returns The modal container element.
  * @example <Modal><p>Modal content</p></Modal>

package/ui/docs/DocumentationButtons.d.ts

@@ -15,5 +15,7 @@ export interface DocumentationButtonsProps extends Pick<DocumentationElementProp
  * - The target is a `<DocumentationButton>`, so it links to the referenced page when it exists in the tree and stays a plain label otherwise.
  * - Block spacing defaults to paragraph spacing (via `PARAGRAPH_CLASS`); pass `space` to override. Inner spacing is the flex gap.
  * - Renders nothing when the symbol has no relations.
+ *
+ * @kind component
  */
 export declare function DocumentationButtons({ wrap, left, gap, ...props }: DocumentationButtonsProps): ReactElement | null;

package/ui/docs/DocumentationButtons.js

@@ -20,6 +20,8 @@ function* _relations({ class: className, extends: extendsName, implements: imple
  * - The target is a `<DocumentationButton>`, so it links to the referenced page when it exists in the tree and stays a plain label otherwise.
  * - Block spacing defaults to paragraph spacing (via `PARAGRAPH_CLASS`); pass `space` to override. Inner spacing is the flex gap.
  * - Renders nothing when the symbol has no relations.
+ *
+ * @kind component
  */
 export function DocumentationButtons({ wrap = true, left = true, gap = "none", ...props }) {
     const relations = Array.from(_relations(props));

package/ui/docs/DocumentationButtons.md

@@ -0,0 +1,38 @@
+# DocumentationButtons
+
+Renders a documented symbol's relational metadata as a `<nav>` column of labelled links — `extends AbstractStore`, `implements Serializable`, `member of Store`. Used by both [`DocumentationPage`](/ui/DocumentationPage) (below the title) and [`DocumentationCard`](/ui/DocumentationCard).
+
+**Things to know:**
+
+- Each relation reads as `"{label} {Target}"`. The target is a [`TreeButton`](/ui/TreeButton), so it resolves the reference against the flattened tree map from [`TreeProvider`](/ui/TreeProvider): a hit becomes a link, a miss (e.g. a builtin like `Serializable`) renders as a plain non-linking label so the text still reads.
+- Relations come from the raw metadata the extractor records — `extends` and `implements` first, then the broader `member of` (the `class` relation) last.
+- It renders nothing when the symbol has no relations.
+- Block spacing defaults to paragraph spacing (it composes `PARAGRAPH_CLASS`); pass `space` to override. Inner spacing is the flex gap.
+- Exported (plural) from `docs/DocumentationButtons.tsx`.
+
+## Usage
+
+Used automatically by [`DocumentationPage`](/ui/DocumentationPage) and [`DocumentationCard`](/ui/DocumentationCard). To render relations directly, pass the symbol's relational props.
+
+```tsx
+import { DocumentationButtons } from "shelving/ui";
+
+<DocumentationButtons class="Store" extends="AbstractStore" implements={["Serializable"]} />
+```
+
+Drop a relation by omitting it, or tighten spacing with `space`.
+
+```tsx
+<DocumentationButtons extends="AbstractStore" space="none" />
+```
+
+## Styling
+
+`DocumentationButtons` has no own CSS hooks — it composes `PARAGRAPH_CLASS` for block spacing and the flex utilities for layout, and renders its links as [`TreeButton`](/ui/TreeButton)s. Retheme through those.
+
+## See also
+
+- [`DocumentationPage`](/ui/DocumentationPage) — renders these relations below the title.
+- [`DocumentationCard`](/ui/DocumentationCard) — renders these relations inside the card (minus `member of`).
+- [`TreeButton`](/ui/TreeButton) — resolves each reference to a link or plain label.
+- [`TreeProvider`](/ui/TreeProvider) — provides the flattened tree map references are resolved against.

package/ui/docs/DocumentationButtons.tsx

@@ -34,6 +34,8 @@ function* _relations({
  * - The target is a `<DocumentationButton>`, so it links to the referenced page when it exists in the tree and stays a plain label otherwise.
  * - Block spacing defaults to paragraph spacing (via `PARAGRAPH_CLASS`); pass `space` to override. Inner spacing is the flex gap.
  * - Renders nothing when the symbol has no relations.
+ *
+ * @kind component
  */
 export function DocumentationButtons({ wrap = true, left = true, gap = "none", ...props }: DocumentationButtonsProps): ReactElement | null {
 	const relations = Array.from(_relations(props));

package/ui/docs/DocumentationCard.d.ts

@@ -5,6 +5,7 @@ import type { DocumentationElementProps } from "../../util/tree.js";
  * - Leads with the symbol's signature(s) as calm code blocks (`<DocumentationSignatures>`, same as the detail page), which already carry the name; falls back to the bare name for symbols with no signature (classes, interfaces, modules).
  * - The card is tinted by `kind` (colour carries the method/property/etc. distinction — no separate tag).
  *
+ * @kind component
  * @param props The documentation element's flattened props (`path`, `title`, `name`, `kind`, `description`, `signatures`, plus relational metadata); the `class` relation is dropped so member cards omit the redundant "member of" link.
  * @returns A `<Card>` linking to the symbol's own page.
  * @example <DocumentationCard {...element.props} />

package/ui/docs/DocumentationCard.js

@@ -11,6 +11,7 @@ import { DocumentationSignatures } from "./DocumentationSignatures.js";
  * - Leads with the symbol's signature(s) as calm code blocks (`<DocumentationSignatures>`, same as the detail page), which already carry the name; falls back to the bare name for symbols with no signature (classes, interfaces, modules).
  * - The card is tinted by `kind` (colour carries the method/property/etc. distinction — no separate tag).
  *
+ * @kind component
  * @param props The documentation element's flattened props (`path`, `title`, `name`, `kind`, `description`, `signatures`, plus relational metadata); the `class` relation is dropped so member cards omit the redundant "member of" link.
  * @returns A `<Card>` linking to the symbol's own page.
  * @example <DocumentationCard {...element.props} />