shelving 1.285.7 → 1.286.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.285.7",
+	"version": "1.286.1",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -9,12 +9,12 @@
 	"main": "./index.js",
 	"module": "./index.js",
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.14",
+		"@biomejs/biome": "^2.5.15",
 		"@heroicons/react": "^2.2.0",
 		"@types/bun": "^1.4.2",
 		"@types/react": "^19.3.0",
 		"@types/react-dom": "^19.3.0",
-		"stylelint": "^17.15.0",
+		"stylelint": "^17.16.0",
 		"stylelint-config-standard": "^40.0.0",
 		"typescript": "^7.0.2"
 	},

package/ui/block/Details.d.ts

@@ -1,22 +1,27 @@
 import type { ReactElement, ReactNode } from "react";
 import { type BlockVariants } from "../style/Block.js";
 import type { ClassProps } from "../util/props.js";
-/** Props for `DetailsItem` — a single collapsible disclosure. */
+/**
+ * Props for `<Details>` — the summary title, the revealed content, and the open state.
+ *
+ * @see https://shelving.cc/ui/DetailsProps
+ */
 export interface DetailsProps extends BlockVariants, ClassProps {
     /** Content of the always-visible summary (e.g. a question). */
     title: ReactNode;
-    /** Whether the item starts expanded. */
+    /** Whether the panel starts expanded. */
     open?: boolean | undefined;
-    /** Shared group name — items with the same `name` open exclusively (only one at a time). */
+    /** Shared group name — panels with the same `name` open exclusively (only one at a time). */
     name?: string | undefined;
-    /** Content revealed when the item is expanded. */
+    /** Content revealed when the panel is expanded. */
     children: ReactNode;
 }
 /**
- * A single collapsible panel within an `Details`, built on native `<details>` and `<summary>`
- * - Panel animates to its true height (where `interpolate-size` + `::details-content` are supported),
- * - Give sibling items a shared `name` to make them open exclusively.
+ * A collapsible panel with a title that is always visible, built on native `<details>` and `<summary>`.
+ * - The panel animates to its true height (where `interpolate-size` and `::details-content` are supported).
+ * - Give sibling panels a shared `name` to make them open exclusively.
  *
  * @kind component
+ * @see https://shelving.cc/ui/Details
  */
 export declare function Details({ title, open, name, children, className, ...props }: DetailsProps): ReactElement;

package/ui/block/Details.js

@@ -1,16 +1,18 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { ChevronUpIcon } from "@heroicons/react/24/outline";
+import { ChevronUpIcon } from "@heroicons/react/24/solid";
 import { getBlockClass } from "../style/Block.js";
-import { getClass } from "../util/css.js";
+import { getFlexClass } from "../style/Flex.js";
+import { getClass, getModuleClass } from "../util/css.js";
 import DETAILS_CSS from "./Details.module.css";
-const DETAILS_CLASS = DETAILS_CSS.details;
-const DETAILS_SUMMARY_CLASS = DETAILS_CSS.summary;
+const DETAILS_CLASS = getModuleClass(DETAILS_CSS, "details");
+const DETAILS_SUMMARY_CLASS = getClass(getModuleClass(DETAILS_CSS, "summary"), getFlexClass({ between: true, gap: "normal" }));
 /**
- * A single collapsible panel within an `Details`, built on native `<details>` and `<summary>`
- * - Panel animates to its true height (where `interpolate-size` + `::details-content` are supported),
- * - Give sibling items a shared `name` to make them open exclusively.
+ * A collapsible panel with a title that is always visible, built on native `<details>` and `<summary>`.
+ * - The panel animates to its true height (where `interpolate-size` and `::details-content` are supported).
+ * - Give sibling panels a shared `name` to make them open exclusively.
  *
  * @kind component
+ * @see https://shelving.cc/ui/Details
  */
 export function Details({ title, open = false, name, children, className, ...props }) {
     return (_jsxs("details", { className: getClass(DETAILS_CLASS, getBlockClass(props), className), open: open, name: name, children: [_jsxs("summary", { className: DETAILS_SUMMARY_CLASS, children: [_jsx("span", { children: title }), _jsx(ChevronUpIcon, {})] }), children] }));

package/ui/block/Details.md

@@ -0,0 +1,63 @@
+# Details
+
+A collapsible panel. The title is always visible. The content shows when the user opens the panel. Built on the native `<details>` and `<summary>` elements, so it works with the keyboard and without JavaScript.
+
+**Things to know:**
+
+- A chevron on the right of the title points down when the panel is closed and up when it is open.
+- The panel animates to its true height where the browser supports `interpolate-size` and `::details-content`. Other browsers open it at once.
+- Give sibling panels the same `name` to make them open exclusively: when one opens, the others close.
+- Two or more panels next to each other get a divider line between them.
+- A raw `<details>` inside `.prose` gets the same spacing and divider, but it keeps the browser's own marker in place of the chevron.
+
+## Usage
+
+### Single panel
+
+```tsx
+import { Details, Paragraph } from "shelving/ui";
+
+<Details title="What is shelving?">
+  <Paragraph>A TypeScript data toolkit.</Paragraph>
+</Details>
+```
+
+### Open by default
+
+```tsx
+import { Details, Paragraph } from "shelving/ui";
+
+<Details title="Release notes" open>
+  <Paragraph>Bug fixes and small improvements.</Paragraph>
+</Details>
+```
+
+### Exclusive group (FAQ)
+
+```tsx
+import { Details, Paragraph } from "shelving/ui";
+
+// Only one answer is open at a time.
+<Details name="faq" title="Is it free?">
+  <Paragraph>Yes.</Paragraph>
+</Details>
+<Details name="faq" title="Does it work with React?">
+  <Paragraph>Yes, through `shelving/ui`.</Paragraph>
+</Details>
+```
+
+## Styling
+
+`Details` paints from the [tint ladder](/ui/TINT_CLASS). Override these hooks at `:root` (or any ancestor scope) to retheme. Apply `color=` / `status=` to an ancestor scope to recolour the chevron and divider together.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--details-space` | Outer block margin, and the padding above a divider | `var(--space-paragraph)` (16px) |
+| `--details-border` | Divider between panels next to each other | `var(--stroke-normal) solid var(--tint-90)` |
+| `--details-marker-color` | Colour of the browser's marker on a raw `<details>` in `.prose` | `var(--tint-80)` |
+| `--details-radius` | Corner radius of the title's focus ring | `var(--radius-xsmall)` (8px) |
+| `--details-icon-color` | Chevron colour | `var(--tint-50)` |
+| `--details-transition` | Open/close animation and chevron turn | `all var(--duration-fast)` (150ms) |
+| `--details-gap` | Space between the title and the content | `var(--space-paragraph)` (16px) |
+
+**Global tokens it reads:** the tint ladder `--tint-50` / `--tint-80` / `--tint-90`, plus `--space-paragraph`, `--space-normal`, `--radius-xsmall`, `--stroke-normal`, `--stroke-focus`, `--color-focus`, `--duration-fast` and `--size-icon` (chevron size, from `getFlexClass`).

package/ui/block/Details.module.css

@@ -48,26 +48,11 @@
 			}
 		}
 
-		/* Title (with chevron icon) */
-		.summary {
-			/* Box */
-			display: flex;
-
-			/* Contents */
-			align-items: center;
-			justify-content: space-between;
-			gap: var(--space-normal);
-
-			/* Children */
-			[data-slot="icon"] {
-				width: var(--size-icon);
-				height: var(--size-icon);
-				color: var(--color-gray);
-				transform: rotate(180deg);
-				transition: var(--details-transition, all var(--duration-fast));
-				border-radius: var(--radius-xxsmall);
-				flex: none;
-			}
+		/* Title chevron (the summary's flex class sets its size). Points down while closed. */
+		.summary [data-slot="icon"] {
+			color: var(--details-icon-color, var(--tint-50));
+			transform: rotate(180deg);
+			transition: var(--details-transition, all var(--duration-fast));
 		}
 
 		/* Content */
@@ -96,10 +81,8 @@
 
 		/* States */
 		&[open] {
-			.summary {
-				[data-slot="icon"] {
-					transform: rotate(0deg);
-				}
+			.summary [data-slot="icon"] {
+				transform: rotate(0deg);
 			}
 
 			&::details-content {

package/ui/block/Details.tsx

@@ -1,31 +1,37 @@
-import { ChevronUpIcon } from "@heroicons/react/24/outline";
+import { ChevronUpIcon } from "@heroicons/react/24/solid";
 import type { ReactElement, ReactNode } from "react";
 import { type BlockVariants, getBlockClass } from "../style/Block.js";
-import { getClass } from "../util/css.js";
+import { getFlexClass } from "../style/Flex.js";
+import { getClass, getModuleClass } from "../util/css.js";
 import type { ClassProps } from "../util/props.js";
 import DETAILS_CSS from "./Details.module.css";
 
-const DETAILS_CLASS = DETAILS_CSS.details;
-const DETAILS_SUMMARY_CLASS = DETAILS_CSS.summary;
+const DETAILS_CLASS = getModuleClass(DETAILS_CSS, "details");
+const DETAILS_SUMMARY_CLASS = getClass(getModuleClass(DETAILS_CSS, "summary"), getFlexClass({ between: true, gap: "normal" }));
 
-/** Props for `DetailsItem` — a single collapsible disclosure. */
+/**
+ * Props for `<Details>` — the summary title, the revealed content, and the open state.
+ *
+ * @see https://shelving.cc/ui/DetailsProps
+ */
 export interface DetailsProps extends BlockVariants, ClassProps {
 	/** Content of the always-visible summary (e.g. a question). */
 	title: ReactNode;
-	/** Whether the item starts expanded. */
+	/** Whether the panel starts expanded. */
 	open?: boolean | undefined;
-	/** Shared group name — items with the same `name` open exclusively (only one at a time). */
+	/** Shared group name — panels with the same `name` open exclusively (only one at a time). */
 	name?: string | undefined;
-	/** Content revealed when the item is expanded. */
+	/** Content revealed when the panel is expanded. */
 	children: ReactNode;
 }
 
 /**
- * A single collapsible panel within an `Details`, built on native `<details>` and `<summary>`
- * - Panel animates to its true height (where `interpolate-size` + `::details-content` are supported),
- * - Give sibling items a shared `name` to make them open exclusively.
+ * A collapsible panel with a title that is always visible, built on native `<details>` and `<summary>`.
+ * - The panel animates to its true height (where `interpolate-size` and `::details-content` are supported).
+ * - Give sibling panels a shared `name` to make them open exclusively.
  *
  * @kind component
+ * @see https://shelving.cc/ui/Details
  */
 export function Details({ title, open = false, name, children, className, ...props }: DetailsProps): ReactElement {
 	return (

package/ui/button/FullscreenButton.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { ArrowsPointingInIcon, ArrowsPointingOutIcon } from "@heroicons/react/16/solid";
+import { ArrowsPointingInIcon, ArrowsPointingOutIcon } from "@heroicons/react/24/solid";
 import { useEffect, useState } from "react";
 import { Button } from "./Button.js";
 /**

package/ui/button/FullscreenButton.tsx

@@ -1,4 +1,4 @@
-import { ArrowsPointingInIcon, ArrowsPointingOutIcon } from "@heroicons/react/16/solid";
+import { ArrowsPointingInIcon, ArrowsPointingOutIcon } from "@heroicons/react/24/solid";
 import { type ReactElement, useEffect, useState } from "react";
 import type { ClassProps } from "../util/props.js";
 import { Button, type ButtonVariants } from "./Button.js";

package/ui/button/RetryButton.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { ArrowPathIcon } from "@heroicons/react/16/solid";
+import { ArrowPathIcon } from "@heroicons/react/24/solid";
 import { createContext, use } from "react";
 import { Button } from "./Button.js";
 /**

package/ui/button/RetryButton.tsx

@@ -1,4 +1,4 @@
-import { ArrowPathIcon } from "@heroicons/react/16/solid";
+import { ArrowPathIcon } from "@heroicons/react/24/solid";
 import { createContext, type ReactElement, use } from "react";
 import type { Callback } from "../../util/function.js";
 import type { ClassProps, OptionalChildProps } from "../util/index.js";

package/ui/dialog/Dialog.d.ts

@@ -2,18 +2,23 @@ import { type ReactElement } from "react";
 import type { Callback } from "../../util/function.js";
 import { type ButtonVariants } from "../button/Button.js";
 import type { ClassProps, OptionalChildProps } from "../util/props.js";
+import "../transition/FadeTransition.css";
 /**
  * Props for `<Dialog>` — optional `children` content and an `onClose` callback.
  *
  * @see https://shelving.cc/ui/DialogProps
  */
 export interface DialogProps extends OptionalChildProps {
+    /** Called when the user closes the dialog. It must unmount the `<Dialog>`, and it runs inside `startTransition()` so the dialog animates out. */
     onClose?: Callback;
 }
 /**
  * Modal `<dialog>` element that opens on mount and includes a close button.
  *
- * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, or the close button.
+ * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, the close button, or the Escape key.
+ * - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
+ * - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
+ * - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
  * - Wraps content in `<Suspense>` so lazy children can stream in.
  *
  * @kind component

package/ui/dialog/Dialog.js

@@ -1,13 +1,17 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { XMarkIcon } from "@heroicons/react/24/solid";
-import { memo, Suspense, useEffect, useRef } from "react";
+import { memo, Suspense, startTransition, useLayoutEffect, useRef, ViewTransition } from "react";
 import { getButtonClass } from "../button/Button.js";
 import { getClass, getModuleClass } from "../util/css.js";
+import "../transition/FadeTransition.css";
 import styles from "./Dialog.module.css";
 /**
  * Modal `<dialog>` element that opens on mount and includes a close button.
  *
- * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, or the close button.
+ * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, the close button, or the Escape key.
+ * - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
+ * - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
+ * - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
  * - Wraps content in `<Suspense>` so lazy children can stream in.
  *
  * @kind component
@@ -15,19 +19,33 @@ import styles from "./Dialog.module.css";
  */
 export const Dialog = memo(({ children, onClose, ...props }) => {
     const ref = useRef(null);
-    useEffect(() => {
+    // Open in a layout effect, not a passive effect. React runs layout effects inside the view transition's update, so the new snapshot shows the open dialog.
+    useLayoutEffect(() => {
         ref.current?.showModal();
     }, []);
-    return (_jsx(Suspense, { fallback: null, children: _jsxs("dialog", { ref: ref, className: getModuleClass(styles, "dialog"), onClick: _closeOnBackdropClick, onClose: onClose, ...props, children: [children, _jsx("div", { className: getModuleClass(styles, "close"), children: _jsx(DialogCloseButton, {}) })] }) }));
+    return (_jsx(Suspense, { fallback: null, children: _jsx(ViewTransition, { enter: "fade", exit: "fade", children: _jsxs("dialog", { ref: ref, className: getModuleClass(styles, "dialog"), onClick: _closeOnBackdropClick, onCancel: e => {
+                    // Keep the dialog open and let the parent unmount it in a transition. An uncancelable request closes natively and fires `onClose` from the `close` event.
+                    if (!onClose || !e.cancelable)
+                        return;
+                    e.preventDefault();
+                    startTransition(() => onClose());
+                }, onClose: onClose, ...props, children: [_jsx("div", { className: getModuleClass(styles, "content"), children: children }), _jsx("div", { className: getModuleClass(styles, "close"), children: _jsx(DialogCloseButton, {}) })] }) }) }));
 });
 /** When the user clicks anywhere on a `<dialog>` element (and the click isn't on a link etc), then close the dialog. */
 function _closeOnBackdropClick({ currentTarget, target }) {
     // Close the dialog when clicking on the dialog itself (but not its children).
     if (currentTarget === target)
-        currentTarget.close();
+        _requestClose(currentTarget);
     // Close the dialog when clicking on links or buttons in a `<nav>` element.
     if (target instanceof Element && target.closest("a:any-link, nav button:enabled"))
-        currentTarget.close();
+        _requestClose(currentTarget);
+}
+/** Ask a `<dialog>` to close. `requestClose()` fires a cancelable `cancel` event, so `<Dialog>` can run `onClose` in a transition. Older browsers close at once. */
+function _requestClose(dialog) {
+    if (typeof dialog.requestClose === "function")
+        dialog.requestClose();
+    else
+        dialog.close();
 }
 /**
  * Button that closes its wrapping `<dialog>`, showing an X icon by default.
@@ -41,5 +59,7 @@ export function DialogCloseButton({ children = _jsx(XMarkIcon, {}), plain = true
     return (_jsx("button", { type: "button", title: "Close", className: getClass(getButtonClass({ plain, ...variants }), className), onClick: _closeOnButtonClick, children: children }));
 }
 function _closeOnButtonClick({ currentTarget }) {
-    currentTarget.closest("dialog")?.close();
+    const dialog = currentTarget.closest("dialog");
+    if (dialog)
+        _requestClose(dialog);
 }

package/ui/dialog/Dialog.md

@@ -4,10 +4,16 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
 
 **Things to know:**
 
-- Closes on a backdrop click, on any link or `<nav>` button clicked inside it, or via the built-in `<DialogCloseButton>` (an X icon, top-right).
+- Closes on a backdrop click, the Escape key, any link or `<nav>` button clicked inside it, or the built-in `<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`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app. For a non-blocking persistent overlay, reach for `<Modal>` instead.
+- Children sit in one wrapper in normal block layout, so several children stack as they would on the page. The wrapper is `--dialog-width` wide (never wider than the screen) and centred on the screen. A centred `<Modal>` fills it. Content taller than the screen starts at the top, and the dialog scrolls.
+- While a dialog is open, the page behind it does not scroll. A scroll inside the dialog never passes on to the page.
+- `Dialog` only dims the page. Its text is white (`--tint-100`) so it reads on the dark overlay. Wrap the content in `<Modal>` to give it a panel with dark text on a light surface.
+- `onClose` fires when the user closes the dialog. It must unmount the `Dialog`: clear the React state that mounts it, or (when pushed via a store) remove it from the list. `Dialog` calls `onClose` inside `startTransition()`, and the dialog stays open until it unmounts.
+- The dialog animates with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). The whole dialog fades in and out as one layer. A `<Modal>` pinned to an edge takes its own layer and slides.
+- A view transition only runs for a React transition update. `DialogsStore` and `onClose` do this for you. To animate a declarative `Dialog` as it opens, set the state that mounts it inside `startTransition()`.
+- A browser without view transitions shows and hides the dialog at once.
+- Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
 
 ## Usage
 
@@ -16,19 +22,21 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
 Mount `<Dialog>` directly when its lifetime matches a React state variable.
 
 ```tsx
-import { Dialog, DialogCloseButton } from "shelving/ui";
+import { Dialog, Modal } 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 />
+      <Modal>
+        <p>Delete this item?</p>
+        <button type="button" onClick={onConfirm}>Delete</button>
+      </Modal>
     </Dialog>
   );
 }
 
-// In the parent:
+// In the parent. Open inside `startTransition()` so the dialog animates in.
+<button type="button" onClick={() => startTransition(() => setShowConfirm(true))}>Delete</button>
 {showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => setShowConfirm(false)} />}
 ```
 
@@ -37,28 +45,35 @@ function ConfirmDelete({ onConfirm, onClose }: { onConfirm: () => void; onClose:
 Set up the context once near the app root (see `<DialogsContext>` and `<Dialogs>`), then push a `<Dialog>` from anywhere with `requireDialogs()`.
 
 ```tsx
-import { requireDialogs } from "shelving/ui";
+import { Modal, requireDialogs } from "shelving/ui";
 
-function DeleteButton({ id }: { id: string }) {
+function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
   const dialogs = requireDialogs();
-  const open = () => dialogs.show(
-    <ConfirmDelete id={id} onConfirm={() => handleDelete(id)} />,
-  );
+  const open = () =>
+    dialogs.show(
+      <Modal>
+        <p>Delete this item?</p>
+        <button type="button" onClick={onConfirm}>Delete</button>
+      </Modal>,
+    );
   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.
+`dialogs.show()` wraps the content in a `<Dialog>` for you, so you pass plain children rather than a `<Dialog>` element. It does not add a `<Modal>`; include one in the content if you want a panel.
 
 ## 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.
+`Dialog` paints the full-screen overlay and resets the browser's default `<dialog>` border, size limits, and `::backdrop`. The inner panel comes from its children, usually `<Modal>`. 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 (a fixed discrete `display` transition runs alongside it so the fade animates across the show / hide toggle) | `all var(--duration-fast)` (150ms) |
-| `--dialog-close-offset` | Inset of the close button from the top-right corner | `var(--space-small)` (8px) |
+| `--dialog-width` | Width of the centred content, and so of a centred `<Modal>` | `var(--width-narrow)` (36rem) |
+| `--dialog-background` | Overlay fill behind the content | `var(--shadow-color)` |
+| `--dialog-color` | Text colour directly on the overlay | `var(--tint-100)` (white) |
+| `--dialog-close-offset` | Inset of the close button from the top-right corner | `var(--space-small)` (12px) |
+
+The fade uses the `fade` class from `<FadeTransition>`, so `--fade-transition-duration` sets its length. It runs only as the dialog opens and closes; an open dialog stays still while other dialogs open and close.
 
-**Global tokens it reads** — move these to retheme broadly: `--space-normal`, `--space-small`, `--color-shadow`, and `--duration-fast`.
+**Global tokens it reads** — move these to retheme broadly: `--tint-100`, `--width-narrow`, `--space-normal`, `--space-small`, `--shadow-color`, and `--duration-fast` (through `<FadeTransition>`).

package/ui/dialog/Dialog.module.css

@@ -1,8 +1,9 @@
 @import url("../style/layers.css");
 @import url("../style/Color.module.css");
-@import url("../style/Duration.module.css");
 @import url("../style/Space.module.css");
 @import url("../style/Shadow.module.css");
+@import url("../style/Tint.module.css");
+@import url("../style/Width.module.css");
 
 @layer components {
 	.dialog {
@@ -12,29 +13,52 @@
 		inset: 0;
 		z-index: 1000;
 		margin: 0;
-		width: 100vw;
-		height: 100vh;
-		align-items: center;
-		justify-content: center;
+		width: auto;
+		height: auto;
+		max-width: none;
+		max-height: none;
+		overflow: auto;
+
+		/* A scroll that reaches the top or bottom of the dialog stops there, and does not pass on to the page. */
+		overscroll-behavior: contain;
 		padding: var(--dialog-padding, var(--space-normal));
+		border: none;
 
 		/* Style */
-		background: var(--dialog-color-overlay, var(--shadow-color));
-		opacity: 0;
-		transition:
-			var(--dialog-transition, all var(--duration-fast)),
-			display var(--duration-fast) allow-discrete;
+		color: var(--dialog-color, var(--tint-100));
+		background: var(--dialog-background, var(--shadow-color));
 
+		/* Flex only to centre `.content`, its one in-flow child. */
 		&[open] {
 			display: flex;
-			opacity: 1;
 		}
 
-		@starting-style {
-			opacity: 0;
+		/* `.dialog` paints the overlay itself, so the browser's own backdrop must not add a second shade. */
+		&::backdrop {
+			background: transparent;
 		}
 	}
 
+	/*
+	 * Lock the page while a dialog is open, so the page behind never scrolls, even when the dialog itself has nothing to scroll.
+	 * - No `scrollbar-gutter: stable` here: fixed elements stop at the root gutter, so the overlay would leave a bare strip at the side.
+	 */
+	:root:has(.dialog[open]) {
+		overflow: hidden;
+	}
+
+	/*
+	 * The children, in normal block layout, `--dialog-width` wide.
+	 * - `margin: auto` centres it on both axes. When it is taller than the screen, the margins drop to 0, so it starts at the top and the dialog scrolls. (`align-items: center` would push the top out of reach.)
+	 * - A pinned `<Modal>` and the close button are `position: fixed`, so this wrapper does not affect them.
+	 */
+	.content {
+		margin: auto;
+		width: var(--dialog-width, var(--width-narrow));
+		min-width: 0;
+		max-width: 100%;
+	}
+
 	.close {
 		position: fixed;
 		top: var(--dialog-close-offset, var(--space-small));