@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/docs/catalog.md

@@ -6,127 +6,524 @@ footer that the kerf UI catalog itself uses. Point it at your own components and
 you get the same shell without rebuilding it. Like the app layouts, it is a
 subpath-only, tree-shakeable module that adds nothing to the main barrel.
 
+The shell is a [`Workbench`](workbench.md) built entirely from `@kerfjs/ui`
+components: the sidebar is its left rail and the active entry its work area. So
+the sidebar behaves like any Workbench rail — its standard toggle moves into the
+entry toolbar while it is collapsed, and on a small screen (a Workbench narrower
+than 704px) it overlays the stage, one tap from the entry toolbar, filling the
+width less a 44px strip that closes it, instead of squeezing the stage. Pass the
+app's `collapsed` signal to `wireCatalog` so that overlay closes on Escape, on a
+press outside, and when an entry is chosen from it.
+
 ```bash
-npm install @kerfjs/ui   # kerfjs is a peer; @kerfjs/ui/select/register is needed only if entries use `related`
+npm install @kerfjs/ui # kerfjs is a peer; @kerfjs/ui/select/register is needed only if entries use `related`
 ```
 
 - `Catalog(props)` returns the shell as `SafeHtml` (a `<main class="kui-catalog">`).
-  It is **controlled and stateless**: your app owns the `active`, `collapsed`, and
-  `theme` signals and computes the preview `content` from `active` in its own
+  It is **controlled and stateless**: your app owns the `active`, `collapsed`,
+  `theme`, and optional display-preference signals and computes the preview `content` from `active` in its own
   `mount()` render.
 - `wireCatalog(root, options)` wires the interactions (sidebar selection, the
-  related-entry popup menu, and the collapse/theme toggles) with one delegated
-  listener set and returns a disposer; it can also mirror the active id into the
-  URL.
+  related-entry popup menu, the built-in sidebar filter, and the collapse/display
+  toggles and background chooser) with one delegated listener set and returns a disposer; it can also
+  mirror the active id into the URL and reveal the active sidebar row after a
+  controlled render.
 
 ## What you supply
 
 - **`sections`** — category-grouped entries: `{ category, entries: [{ id, name,
-  description?, resources?, related? }] }`. Each entry becomes a sidebar `ListItem`
-  under a `ListHeader` for its category.
+description?, tags?, resources?, related? }] }`. Each entry becomes a sidebar
+  `ListItem` under a `ListHeader` for its category. Short `tags` render through
+  the row's quiet status treatment for decision metadata such as `Discouraged`.
 - **`content`** — the rendered preview for the active entry. Keep a map of `id →
-  () => SafeHtml` in your app and call `renderers[active]()` in your render.
-- **`brand`** — `{ title, subtitle?, logoUrl? }` for the sidebar header.
+() => SafeHtml` in your app and call `renderers[active]()` in your render.
+- **`backgroundStyle`** — the preview stage backdrop: `checkerboard` (default,
+  8px squares),
+  `vertical-stripes` (alternating 8px bands), `layout-guide` (single-pixel
+  vertical rules at 15px, 23px, and 32px from the stage edge), `surface`, or `sunken`. The
+  patterned choices share the main Pane's sunken surface and reveal transparent
+  specimen edges; `surface` paints an
+  opaque backdrop. `sunken` leaves the stage
+  transparent so the main Pane's semitransparent sunken surface paints only once.
+  A controlled app may pass its current choice on each render.
+- **Display controls** — `increasedContrast` and `reducedMotion` each show a
+  pressed-state toggle when their boolean value is supplied. `backgroundControl`
+  shows a `PopupMenu` for the five preview backdrops, marking the current
+  `backgroundStyle` as checked. These controls share the entry toolbar's compact,
+  wrapping display group with the optional theme toggle. Pass callbacks through
+  `wireCatalog`'s `onToggleContrast`, `onToggleMotion`, and `onSelectBackground`;
+  update your own signals, apply contrast/motion preferences to your app, and
+  persist them there if needed. `Catalog` does not change the document theme,
+  classes, or storage. Register `@kerfjs/ui/popup-menu/register` when showing the
+  background chooser.
+- **`brand`** — `{ title, subtitle?, logoUrl? }` for the sidebar header. The
+  optional logo paints through `ToolbarControlGroup.avatarImage`.
 - **`secondarySections`** — an optional secondary "ecosystem" group shown below the
   primary sections with a quieter treatment: `{ label, sections, collapsible?,
-  expanded? }`. When `collapsible`, the label is a disclosure toggle controlling
+expanded? }`. When `collapsible`, the label is a disclosure toggle controlling
   `expanded` (the app owns it; wire it with `wireCatalog`'s `onToggleSecondary`).
+  An optional `tagFilter: { tag, label, show }` adds a compact `Switch` at the
+  top of the open group that leaves out every entry carrying `tag` (and any
+  section it empties) until `show` is true. The active entry is always listed,
+  so a direct route still shows where it is. The app owns `show`; wire it with
+  `wireCatalog`'s `onToggleSecondaryFilter(show)` (action
+  `catalog-toggle-secondary-filter`, configurable through
+  `toggleSecondaryFilterAction`). Hidden entries are not rendered, so the
+  sidebar filter does not search them. The UX catalog uses it to hide
+  `Discouraged` Web Awesome entries by default.
 - Optional slots: `headerActions` (extra header controls), `sidebarFooter` (extra
   sidebar content), and `status` (a footer status line).
+- **`settings`** — the active entry's settings (variant and state controls for
+  its preview). When supplied, the Catalog renders a **Settings** pane beside the
+  stage (its Workbench right rail) with the standard collapse toggle: in the
+  pane's header while it is open, at the end of the entry toolbar while it is
+  collapsed. Omit it (or pass `null`) for an entry with no settings; neither the
+  pane nor its toggle renders. Supply only the controls — compose them from
+  `ListInsetControl` + `Select` (or other form components) so they share the
+  pane's text column; the Catalog owns the pane, its title, and its toggle.
+
+The sidebar includes a `SearchField` in its fixed header for every Catalog
+consumer, so the filter remains visible while the entries scroll. `wireCatalog`
+filters entry names and section headings as text is typed,
+ignoring case. A heading match shows all its entries; a matching secondary
+group heading searches its sections too, even while that group is collapsed.
+Empty sections disappear and an empty-result message appears when nothing
+matches. The query survives controlled Catalog rerenders, with the field's
+placeholder hidden while text remains, and clears through the field's clear
+action. Filtering does not change the selected
+entry or its preview.
 
 Per-entry `resources` render as "open in new tab" links in the footer, and
-`related` renders a "Related entries" popup menu — a `single` `ToolbarControlGroup`
-around a `wa-dropdown` (grouped by each entry's `group`), so register its elements
-with `@kerfjs/ui/select/register` when you use it.
+`related` renders a "Related Entries" `PopupMenu` in a `single`
+`ToolbarControlGroup` (grouped by each entry's `group`), so register its elements
+with `@kerfjs/ui/popup-menu/register` when you use it.
+
+## Catalog demo authoring contract
+
+This section is the single authoritative contract for tools and people that
+author Catalog previews. The machine-readable discovery entry is
+[`catalog-authoring.json`](../ai/catalog-authoring.json); exact props remain in
+[`public-api-signatures-v1.md`](../ai/public-api-signatures-v1.md#kerfjsuicatalog).
+The component catalog deliberately does not duplicate these rules: it describes
+which component to choose, while this contract describes how to present the
+chosen component.
+
+### Choose the demo mode
 
-## Preview examples
+Classify every entry before rendering it:
 
-Compose each entry's `content` from `CatalogExample` (and `CatalogExampleStack`)
-instead of hand-rolled example markup, so labels, notes, and left-edge alignment
-stay consistent:
+| Entry kind      | Preview purpose                                                                                         |
+| --------------- | ------------------------------------------------------------------------------------------------------- |
+| **Component**   | Show one public component, its meaningful variants, and adverse states.                                 |
+| **Composition** | Show components commonly used together in one focused container or surface.                             |
+| **Recipe**      | Teach the recommended production approach to a specific task, including ownership and application glue. |
+
+These three kinds are exhaustive. Theme/foundation showcases use a functional
+category, third-party specimens use source metadata, and state galleries retain
+the kind of the thing they demonstrate; none needs another demo kind.
+
+Organize the catalog by functional group, with groups in descending product
+importance. Within every group, list all component demos before all composition
+demos. Order each kind by descending importance where a meaningful distinction
+exists, then alphabetically by display name to break ties. Put recipes after all
+component/composition groups, ordered by the same importance-then-alphabetical
+rule. Treat source order as the authored importance order when no explicit rank
+field exists. Show a `Composition` tag rather than repeating the word in a
+composition's display name; the generic `Catalog` accepts that through the
+entry's `tags` array.
+
+### Required structure
+
+- `Catalog` is the one shell. The app owns active-entry state and passes one
+  active preview through `content`.
+- `CatalogExampleStack` is the group for one preview's rows. Put route/test
+  metadata such as `data-demo` on its rendered root through `rootAttributes`.
+  Pass `label` when the stack needs an accessible name: the rendered `section`
+  is then exposed as a named region. An unlabeled stack remains an ordinary
+  grouping rather than adding an unnecessary landmark.
+  A stack holds a 736px reading measure by default; pass `width="full"` for
+  application-width compositions (boards, app shells, drawers, split views) so
+  the stack spans the stage like a `viewport.width: "full"` row instead of
+  clipping them.
+- `CatalogExample` is one row: optional generated `ListHeader` label, optional
+  generated note, then one specimen or one intentionally coupled specimen
+  cluster. Use one row per variant/state; do not hand-author the helper's private
+  classes. A supplied `label` also names the row's `section`, so each specimen
+  is a named region that assistive technology and
+  `getByRole("region", { name })` can address.
+- Example and stack labels are headings, so they use title style ("Heading
+  Identity Stays Whole", "Icon Trigger in a Toolbar Group"); the `note` that
+  explains a specimen stays sentence style. Write a label as a name, not a
+  sentence. See [Writing interface copy](./writing.md#capitalization);
+  `kerf-ui-doctor` reports a sentence-case label as `KUI-D040`.
+- Focused demos do not import local stylesheets, use inline `style`, or invent
+  styling-only `demo-*` classes. Prefer a public Kerf component, then a Web
+  Awesome surface when Kerf has no equivalent, then ordinary semantic HTML.
+  Use `CatalogExample.viewport` for bounded specimen width, height, frame,
+  surface, overflow, responsive visibility, and public custom-property values;
+  keep those constraints catalog-owned instead of recreating a demo stylesheet.
+  Widths run `sidebar` (272px, a production rail, for sidebar-pane content),
+  `compact` (440px), `medium` (640px), and `wide` (864px), each capped at the
+  stage, plus `full`; `text` and `control` size a single label or control.
+  Component heights run `short` (220px) through `tall` (360px); frame an app
+  shell, whole-screen layout, or other application-sized recipe with
+  `height: "app"` (592px), and give its root `fill` rather than a frame `Pane`.
+  An app frame stands in for the screen: it is the containing block for
+  screen-fixed chrome, so a compact `CollapsiblePanel` overlay, its backdrop,
+  and restore controls dock to the frame's edges rather than the page's.
+  `minHeight` (`short`, `medium`, or `app` at 592px) is a floor the frame
+  may grow past rather than a definite height.
+- A top-layer specimen (a `popover`, a modal) that production anchors to a
+  named region with CSS anchor positioning anchors to the frame instead when
+  the frame takes that name: `viewport.anchorName` is a CSS dashed-ident
+  (`"--app-shell-main"`, validated; anything else throws) that becomes the
+  frame's `anchor-name`, so the specimen's own `position-anchor` rule resolves
+  to the frame. Do not wrap the specimen in a stage element to name it. Anchor
+  names are document-wide, so give each frame on a page its own. The frame
+  only names the anchor: the specimen keeps owning its placement, and as a
+  top-layer element it is not clipped by the frame or the stage. Chromium,
+  Firefox, and WebKit with CSS anchor positioning place it against the frame;
+  an engine without anchor positioning ignores the name, and the specimen
+  falls back to whatever placement its own CSS gives it there.
+- For a centered reading column inside a wider frame, set
+  `viewport.contentWidth` (`compact` 440px, `medium` 640px, or `wide` 864px,
+  each capped at the frame) and `contentAlign: "center"` (the default is
+  `start`). Each in-flow child fills that column; `[popover]` children keep
+  their own geometry. The column applies to block, `grid`, and `flex-column`
+  frames, and `contentAlign` does nothing without `contentWidth`.
 
 ```tsx
-import { CatalogExample, CatalogExampleStack } from '@kerfjs/ui/catalog';
+<CatalogExample
+  label="Request Docked to the Main Column"
+  viewport={{
+    layout: "flex-column",
+    width: "full",
+    minHeight: "app",
+    anchorName: "--app-shell-main",
+    contentWidth: "medium",
+    contentAlign: "center",
+  }}
+>
+  <Transcript />
+  <PermissionRequestPopup /> {/* its CSS: position-anchor: --app-shell-main */}
+</CatalogExample>
+```
+
+- The specimen is an immediate child of `CatalogExample`. A focused component
+  row should place the component root there, without a decorative card or
+  spacing wrapper. A composition row may place the composition root there.
+
+Use `align="glyph"` for a bare glyph/text specimen, `align="inline-control"`
+for a control whose own inline padding contributes about 8px, and
+`align="text-trigger"` for a text menu trigger whose visible label needs an
+8px inset (such as a plain `PopupMenu` trigger), so its text lines up with the
+example label past the trigger's own padding and border. Use
+`align="none"` (the default) for a content item or composition that owns its
+geometry. Every form field specimen (TextField, Select, ColorField, TagField,
+Slider, Switch, Checkbox, RadioGroup, CheckboxGroup, ColorSwatches) uses
+`inline-control`, so field borders and label text share one column across the
+catalog; a field that already insets itself by 8px (Combobox) stays at `none`.
+A field is a control a person fills in or picks a value with inline, swatch
+pickers included. A field composition (fields in a `Grid` or a form `List`)
+uses `inline-control` too. A width-sized content specimen — one that fills a
+sized `viewport` or its container rather than its content, such as a
+ProgressBar, a group-title `Text`, or Web Awesome's Progress Bar and Skeleton —
+joins the same column with `inline-control`, so a bar's label lines up with the
+example label and note text. Web Awesome integration specimens follow their
+Kerf counterpart's demo: controls and control compositions (Button, Button
+Group, Dropdown, Dropdown Item, the Tab family, Badge, Tag, Avatar, Progress
+Ring, Toast and Toast Item, the dialog, drawer, popover, and tooltip triggers,
+Animation, and the intersection, mutation, and resize observer compositions)
+use `inline-control`, as the Kerf Button demo does, so the control box sits on
+the 8px column; a specimen led by bare text or a bare glyph (Copy Button,
+Breadcrumb and Breadcrumb Item, Divider, Markdown, Relative Time, Pagination's
+summary, Stepper and Step markers, Spinner, Icon) uses `glyph`, as Kerf's flush
+`Text`, `LoadingSpinner`, and `LucideIcon` demos do, so its text lands on the
+text column instead of flush at the example's edge. A panel — a multi-part picker or
+a drop zone such as ColorPicker and FilePicker, or a framed specimen such as
+Web Awesome's Zoomable Frame — owns its geometry and stays flush at `none`, as
+does an edge-to-edge composition (a toolbar, tab bar, or pane). A sized
+`viewport` takes the alignment offset out of its width, so it still ends at the
+example's inline-end edge.
+
+```tsx
+import { CatalogExample, CatalogExampleStack } from "@kerfjs/ui/catalog";
 
 const buttonPreview = (
-  <CatalogExampleStack label="Button variants">
+  <CatalogExampleStack
+    label="Button Variants"
+    rootAttributes={{ "data-demo": "button" }}
+  >
     <CatalogExample label="Icon" note="A bare glyph." align="glyph">
       <LucideIcon icon={Plus} name="plus" />
     </CatalogExample>
     <CatalogExample label="Control" align="inline-control">
       <SegmentedControl id="view" label="View" value="list" choices={choices} />
     </CatalogExample>
-    <CatalogExample label="In composition">
-      <ValueTable label="Metadata">{rows}</ValueTable>
+    <CatalogExample label="Authoring Note" note="Explain the specimen below.">
+      <p>Use the public helper contract.</p>
     </CatalogExample>
   </CatalogExampleStack>
 );
 ```
 
-`label` is optional — omit it for a bare specimen with no `ListHeader`. `align`
-lines a specimen's visible left edge up with its label text: `'glyph'`
-(16px) for a bare glyph/text specimen, `'inline-control'` (8px) for a control that
-already carries ~8px of its own inline padding, and `'none'` (the default) for a
-content-item/composition that already owns its geometry. The inset is published as
-the `--kui-catalog-example-align` custom property so a debug overlay can exclude it
-from a specimen's measured margin.
+### Metadata ownership
+
+Use `rootAttributes` on either helper for authoring metadata such as `data-demo`;
+the metadata lands on that helper's
+rendered root. The slot accepts only `data-*` strings. Structural
+`data-catalog-example`, `data-catalog-example-stack`, and `data-align` semantics
+remain helper-owned and are rejected case-insensitively at runtime, including
+from structurally widened or JavaScript objects. Do not copy the helpers'
+private `kui-catalog-*` classes into preview markup.
+
+The app owns entry ids, `kind`, routing, sources, relationships, and test hooks.
+`Catalog.stageRootAttributes` places app-owned `data-*` state on the
+catalog-owned preview stage without an extra wrapper; `data-catalog-stage`
+remains protected.
+The stage is the main Pane's direct scrolling content and fills its available
+scroller height for short specimens, so every backdrop reaches the pane's bottom.
+It grows with tall specimens and scrolls without clipping. The canvas owns the
+16px inset; the main Pane keeps its sunken appearance without a deep inset. The
+Catalog's shipped CSS supplies this behavior in this package's UX demo and in
+other packages' demos. Consumers should import `@kerfjs/ui/catalog` with its
+browser styles (or the companion CSS subpath for manual CSS pipelines) rather
+than styling Pane or stage internals.
+The helpers own their structural markers, label/note anatomy, alignment marker,
+and private classes. Component metadata such as margin/border/padding ownership
+lives in `component-catalog.json`.
+
+### Component metadata
+
+Machine-readable geometry ownership metadata identifies whether the component,
+its parent, or its children are responsible for margin, border, and padding.
+Keep that metadata in `component-catalog.json` and use the rendered specimen to
+review the actual appearance.
+
+Catalogs for downstream components should conform to the
+[`component-catalog-extension.schema.json`](../ai/component-catalog-extension.schema.json)
+contract and can start from the checked
+[`component-catalog-extension.json`](./examples/component-catalog-extension.json)
+example; provide those entries beside Kerf's shipped catalog to AI tools.
+Packages that keep a `kerf.components.json` can generate this file instead of
+hand-maintaining it: set `kerfComponentCatalog.selectionOutput` and run
+`kerf-component-catalog` (see `create-kerf-component`'s README).
+An extension entry may declare `uses` with direct Kerf or extension entry ids,
+plus repository-relative `source` and `demoSource` paths. Keep the ids unique
+and resolvable across both catalogs; paths use `/` separators and cannot
+traverse outside the repository. These fields let consumer demos derive source
+links and composition relationships from the catalog.
+
+For a consumer UX demo, `@kerfjs/ui/catalog-projection` exports
+`projectConsumerCatalog(extension, kerfCatalog, options)` and
+`projectCatalogEntries(entries, options)`. The projection maps `purpose` to
+`description`, `uses` to related-entry ids, `source` to `componentSource`, and
+`demoSource` to the demo source link. It defaults the source identity to
+`consumer` and category to `Application`. Explicit paths in an extension entry
+take precedence over templates. Template placeholders are `{id}`, `{name}`,
+`{kind}`, and `{package}`. Design templates are omitted unless configured.
+
+The package also ships `kerf-catalog-demo` for a committed TypeScript module:
+
+```sh
+kerf-catalog-demo --extension ai/component-catalog-extension.json \
+  --out ux-demo/catalog.generated.ts \
+  --repo-base https://github.com/acme/app/blob/main/ \
+  --source-template 'src/{id}.tsx' \
+  --demo-template 'ux-demo/demos/{id}.tsx' --write
+kerf-catalog-demo --extension ai/component-catalog-extension.json \
+  --out ux-demo/catalog.generated.ts \
+  --repo-base https://github.com/acme/app/blob/main/ \
+  --source-template 'src/{id}.tsx' \
+  --demo-template 'ux-demo/demos/{id}.tsx' --check
+```
+
+The command uses the Kerf catalog shipped with the package to resolve `uses`;
+`--kerf-catalog` selects another catalog file. `--category`,
+`--documentation-template`, and `--design-template` configure optional row
+fields. `--check` fails if the generated file is missing or stale. The output
+exports `generatedConsumerCatalog` and `catalogRepositoryBlobUrl`; the latter
+is normalized to a trailing slash for source and documentation links.
+
+### Automated conformance and reviewed exceptions
+
+Run `npm run check:demo-conformance` after changing a first-party demo, its
+catalog kind, or the shell's overlay logic. The TypeScript-AST gate verifies
+facts that source can prove without guessing at rendered intent:
+
+- focused component routes import and use `CatalogExampleStack` and
+  `CatalogExample` from the public package;
+- focused route metadata uses the helpers' `rootAttributes` slot and example rows
+  are not empty;
+- every `@kerfjs/ui` import is a published package export and relative imports
+  do not reach into `ui/src`;
+- focused demos have no relative stylesheet imports, inline style attributes,
+  or styling-only `demo-*`, `wa-demo-*`, and search-field class names;
+- demo JSX does not copy private `kui-catalog-*` structural classes;
+- recipe sources (checked by `npm run check:recipes` with the same shared
+  analyzer) import no stylesheet other than public `@kerfjs/ui` CSS, set no
+  inline style, and name only published layout and Web Awesome classes; each
+  recipe declares its catalog frame through an exported `presentation`; and
+- the shell derives the documented demo mode from the active entry's kind.
+
+The gate deliberately does not infer component ownership from arbitrary class
+names, margins, borders, or nested descendants. Runtime appearance remains the
+browser suite's job.
+
+A focused route may bypass the two public layout helpers only when the route's
+stage geometry is itself the reviewed specimen. Add the narrow waiver to
+[`catalog-conformance-exceptions.json`](../ux-demo/catalog-conformance-exceptions.json)
+with the exact route, source file, stable diagnostic ids, a substantive reason,
+and the reviewing `KF-*` ticket. Only helper/metadata rules are waivable;
+private imports, local styling, private markup, empty examples, and shell-mode
+drift always fail. The gate rejects duplicate, malformed, unused,
+and stale exceptions, so delete a waiver when its route adopts the standard
+helpers.
+
+## Selection reveal
+
+Set `revealSelection: true` on `wireCatalog` for a long desktop sidebar. After
+`onSelect` updates controlled state, the helper waits one animation frame, finds
+the exact matching `data-item-id`, and scrolls it into view without changing
+focus. A newer selection or disposal cancels the pending reveal. The default
+media guard follows the Workbench's inline sidebar (`min-width: 44.01rem`), so a
+closed phone overlay is never scrolled behind the user's back.
+
+Pass an options object instead of `true` to customize `block`, `inline`,
+`behavior`, or `media`; `media: false` deliberately enables the behavior at all
+sizes. For an initial deep link that did not come through `wireCatalog`, call
+`revealCatalogEntry(app, initialId, { block: "center" })` after the first mount.
 
 ## Complete example
 
 ```tsx
-import { mount, signal } from 'kerfjs';
-import { Catalog, type CatalogSection } from '@kerfjs/ui/catalog';
-import { wireCatalog } from '@kerfjs/ui/wire-catalog';
-import '@kerfjs/ui/styles.css'; // or import each primitive's CSS + @kerfjs/ui/catalog.css
+import { mount, signal, type SafeHtml } from "kerfjs";
+import {
+  Catalog,
+  CatalogExample,
+  CatalogExampleStack,
+  type CatalogBackgroundStyle,
+  type CatalogSection,
+} from "@kerfjs/ui/catalog";
+import {
+  revealCatalogEntry,
+  wireCatalog,
+} from "@kerfjs/ui/wire-catalog";
+import "@kerfjs/ui/popup-menu/register"; // for the background chooser
+// A CSS-aware (browser-condition) bundler loads the Catalog's CSS with its import.
 
-// 1. Describe your components once.
-const sections: CatalogSection[] = [
+type DemoKind = "component" | "composition";
+type DemoEntry = CatalogSection["entries"][number] & { kind: DemoKind };
+
+// 1. Describe selection and overlay mode once.
+const entries: DemoEntry[] = [
   {
-    category: 'Controls',
-    entries: [
-      { id: 'button', name: 'Button', description: 'A pressable control.',
-        resources: [{ label: 'Source', href: '/src/button.tsx', detail: 'src/button.tsx' }] },
-      { id: 'field', name: 'Field', description: 'A labeled input.',
-        related: [{ id: 'button', name: 'Button', group: 'Used with' }] },
+    id: "button",
+    name: "Button",
+    kind: "component",
+    description: "A pressable control.",
+    resources: [
+      { label: "Source", href: "/src/button.tsx", detail: "src/button.tsx" },
     ],
   },
-  { category: 'Feedback', entries: [{ id: 'toast', name: 'Toast', description: 'A transient message.' }] },
+  {
+    id: "profile-form",
+    name: "Profile form",
+    kind: "composition",
+    description: "A labeled field and save action working together.",
+  },
+];
+const sections: CatalogSection[] = [
+  {
+    category: "Examples",
+    entries: entries.map(({ kind, ...entry }) => ({
+      ...entry,
+      tags: kind === "composition" ? ["Composition"] : undefined,
+    })),
+  },
 ];
 
-// 2. One preview render per entry id.
-const renderers: Record<string, () => ReturnType<typeof Button>> = {
-  button: () => <Button label="Save" />,
-  field: () => <Field label="Name" />,
-  toast: () => <Toast>Saved</Toast>,
+// 2. Every preview uses one public group and public example rows.
+const renderers: Record<string, () => SafeHtml> = {
+  button: () => (
+    <CatalogExampleStack
+      label="Button States"
+      rootAttributes={{ "data-demo": "button" }}
+    >
+      <CatalogExample label="Default" align="inline-control">
+        <Button label="Save" />
+      </CatalogExample>
+      <CatalogExample label="Authoring Note" note="Explain the specimen below.">
+        <p>The application owns product copy and actions.</p>
+      </CatalogExample>
+    </CatalogExampleStack>
+  ),
+  "profile-form": () => (
+    <CatalogExampleStack
+      label="Profile Form Composition"
+      rootAttributes={{ "data-demo": "profile-form" }}
+    >
+      <CatalogExample label="Complete Composition">
+        <ProfileForm />
+      </CatalogExample>
+    </CatalogExampleStack>
+  ),
 };
 
-// 3. App-owned state (domain: which entry; transient: collapsed; global: theme).
-const initial = new URLSearchParams(location.search).get('c') ?? sections[0].entries[0].id;
+// 3. App-owned state (domain: which entry; transient: collapsed; display preferences).
+const initial =
+  new URLSearchParams(location.search).get("c") ?? sections[0].entries[0].id;
 const active = signal(initial);
 const collapsed = signal(false);
-const theme = signal<'light' | 'dark'>('light');
+const theme = signal<"light" | "dark">("light");
+const increasedContrast = signal(false);
+const reducedMotion = signal(false);
+const backgroundStyle = signal<CatalogBackgroundStyle>("checkerboard");
 
-const app = document.getElementById('app')!;
+const app = document.getElementById("app")!;
 mount(app, () => (
   <Catalog
-    brand={{ title: 'Acme UI', subtitle: 'Design system' }}
+    brand={{ title: "Acme UI", subtitle: "Design system" }}
     sections={sections}
     active={active.value}
     content={renderers[active.value]?.() ?? <></>}
     collapsed={collapsed.value}
     theme={theme.value}
+    increasedContrast={increasedContrast.value}
+    reducedMotion={reducedMotion.value}
+    backgroundControl
+    backgroundStyle={backgroundStyle.value}
   />
 ));
 
 wireCatalog(app, {
-  onSelect: (id) => { active.value = id; },
-  onToggleSidebar: () => { collapsed.value = !collapsed.value; },
+  onSelect: (id) => {
+    active.value = id;
+  },
+  onToggleSidebar: () => {
+    collapsed.value = !collapsed.value;
+  },
   onToggleTheme: () => {
-    theme.value = theme.value === 'dark' ? 'light' : 'dark';
+    theme.value = theme.value === "dark" ? "light" : "dark";
     document.documentElement.dataset.theme = theme.value; // apply your theme however you like
   },
-  urlParam: 'c', // mirror the active id into ?c=<id>
+  onToggleContrast: () => {
+    increasedContrast.value = !increasedContrast.value;
+    document.documentElement.classList.toggle("increased-contrast", increasedContrast.value);
+  },
+  onToggleMotion: () => {
+    reducedMotion.value = !reducedMotion.value;
+    document.documentElement.classList.toggle("reduced-motion", reducedMotion.value);
+  },
+  onSelectBackground: (style) => {
+    backgroundStyle.value = style;
+  },
+  urlParam: "c", // mirror the active id into ?c=<id>
+  revealSelection: true, // reveal long desktop sidebars without moving focus
 });
+
+// Optional for an initial deep link whose row may start outside the viewport.
+revealCatalogEntry(app, initial, { block: "center" });
 ```
 
 ## Ownership boundary
@@ -136,20 +533,159 @@ wireCatalog(app, {
 - **`active`** is domain state (which entry is shown) — the app's signal, updated in
   `onSelect`, read to compute `content`.
 - **`collapsed`** is transient UI — the app's signal, flipped in `onToggleSidebar`.
+  Pass the same signal as `wireCatalog`'s `collapsed` option so the sidebar is
+  wired as a Workbench rail (transient on small screens, focus handed to the
+  relocated toggle).
+- **`headerPlacement` / `footerPlacement`** choose whether the entry toolbar and
+  description, and the status + resource footer, stay pinned (`fixed`), scroll with
+  the preview (`scroll`), or stay pinned while the entry pane is tall enough and
+  scroll with the preview when it is short (`auto`, the default) — so a short
+  window or large text never squeezes the preview out.
+  The resource footer uses `ToolbarControlGroup overflow="wrap"`: whole links
+  move to another row when they do not fit, keeping Guidance and source labels
+  readable without horizontal scrolling.
+- **`sidebar`** configures the sidebar rail — it forwards to the Workbench's left
+  rail: `size` (default 288px), `resizable` (`true` or `{ min, max }`),
+  `separator`, `collapseMotion`, `presentation`, `responsiveOverlayAt` (default
+  `narrow`), `compactOverlay` (default `inset`), and `toolbar` (the sidebar
+  header's `ToolbarConfig`). A resizable sidebar's width is app state like
+  `collapsed`: render your size signal as `sidebar.size` and pass the same signal
+  as `wireCatalog`'s `sidebarSize` (plus `sidebarStorageKey` to remember it).
+- **`settingsCollapsed`** is transient UI like `collapsed`: render your signal as
+  `settingsCollapsed` and pass the same signal as `wireCatalog`'s
+  `settingsCollapsed`. `wireCatalog` then flips it from the toggle (report it
+  with `onToggleSettings`, which runs after the flip) and wires the pane as a
+  Workbench rail: below the `narrow` breakpoint it starts collapsed and opens as
+  an overlay over the stage that Escape or a press outside closes, handing focus
+  back to the toggle. The sidebar and settings overlays are exclusive. Without
+  the signal, `onToggleSettings` alone reports the press and the app flips its
+  own state.
+- **`settingsPanel`** configures the settings pane like `sidebar` configures the
+  sidebar: `title` (default `Settings`; it also names the toggle), `size`
+  (default 288px), `resizable`, `separator`, `collapseMotion`, `presentation`,
+  `responsiveOverlayAt`, `compactOverlay`, and `toolbar`. A resizable pane's
+  width is app state: render your signal as `settingsPanel.size` and pass it as
+  `wireCatalog`'s `settingsSize` (plus `settingsStorageKey` to remember it).
+- **`mainToolbar` / `footerToolbar`** take the entry toolbar's and the resource
+  footer toolbar's `ToolbarConfig` (`dividerSides`, `centerAlign`, `responsive`,
+  `responsiveAt`, `safeAreaEdges`). The defaults are a wrapping entry toolbar
+  and a footer toolbar that stacks at `narrow`, all without dividers of their
+  own: `wireCatalog` wires `wireScrollDividers`, so the shell's panes draw
+  their chrome dividers only while scrolled; an omitted or
+  `undefined` field keeps them. Configure these instead of styling the shell.
 - **`theme`** is a global preference — the app's signal; `wireCatalog` only reports
   the toggle, the app applies the theme (the shell reads `theme` to show the toggle's
   opposite-state label). Omit `theme` to hide the toggle entirely.
 
+## UX Review capture
+
+On a local Vite dev or preview server the catalog can offer a **Capture Region**
+header link that starts a UX Review region screenshot, preset with the project
+and the active entry. Static hosting has no local project, so the link never
+appears there. Three pieces wire it:
+
+```ts
+// vite.config.ts — Node only; never part of the browser bundle.
+import { uxReviewPlugin } from "@kerfjs/ui/vite-ux-review";
+
+export default defineConfig({ plugins: [uxReviewPlugin()] });
+```
+
+```tsx
+const uxReviewProject = signal<string | null>(null);
+
+mount(app, () => (
+  <Catalog
+    /* …the props above… */
+    uxReview={
+      uxReviewProject.value
+        ? { projectDirectory: uxReviewProject.value }
+        : undefined
+    }
+  />
+));
+
+wireCatalog(app, {
+  onSelect: (id) => (active.value = id),
+  onUxReviewProject: (directory) => (uxReviewProject.value = directory),
+});
+```
+
+- **`uxReviewPlugin(options?)`** answers `GET …/__ux-review/project.json` with
+  `{ projectDirectory }` on the dev and preview servers, at any base path. The
+  directory defaults to the repository holding Vite's `root` (the nearest
+  ancestor with `.git`, or `root` itself); pass `projectDirectory` (resolved
+  against `root`) to name another.
+- **`wireCatalog`'s `onUxReviewProject`** asks the page's server once and
+  reports the directory. It is never called on static hosting or a server
+  without the plugin. While wired, following the link stamps the current page
+  URL into the capture context.
+- **`Catalog`'s `uxReview`** (`{ projectDirectory, name? }`) renders the link
+  after `headerActions`. The capture is titled `<name>: <entry>`, and its
+  context names the catalog, the entry's section, and the entry; `name`
+  defaults to `brand.title`.
+
+The browser helpers behind it, `uxReviewCaptureUrl` and `loadUxReviewProject`,
+are exported from `@kerfjs/ui/catalog` for a capture link placed elsewhere.
+
+### Catalogs served without Vite
+
+A catalog served by the app's own backend (an esbuild bundle behind Hono,
+Express, or a plain Node server) mounts the same endpoint from the same
+Node-only subpath, on its development server only. The catalog requests
+`__ux-review/project.json` relative to its page, so a page at `/ux-demo` asks
+for `/__ux-review/project.json`; both helpers answer at any base path.
+
+```ts
+import {
+  resolveUxReviewProject,
+  uxReviewMiddleware,
+  uxReviewProjectResponse,
+} from "@kerfjs/ui/vite-ux-review";
+
+// Resolve once at startup: the repository holding the working directory, or
+// resolveUxReviewProject({ root, projectDirectory }) like the Vite plugin.
+const projectDirectory = resolveUxReviewProject();
+
+// Fetch API servers (Hono, Bun, Deno): null means "not this endpoint".
+if (isDev)
+  app.use("*", async (c, next) =>
+    uxReviewProjectResponse(c.req.raw, projectDirectory) ?? next(),
+  );
+
+// Node / connect servers (Express, node:http):
+if (isDev) expressApp.use(uxReviewMiddleware(projectDirectory));
+```
+
+- **`resolveUxReviewProject({ root?, projectDirectory? })`** returns the real
+  path the Vite plugin would serve: `projectDirectory` resolved against `root`,
+  or the repository holding `root` (default `process.cwd()`).
+- **`uxReviewProjectResponse(request, projectDirectory)`** answers a Fetch API
+  `Request`: the JSON for a GET, `405` for another method, or `null` for any
+  other path.
+- **`uxReviewMiddleware(projectDirectory)`** is the same endpoint as a
+  `(request, response, next)` handler; `uxReviewPlugin` mounts it on Vite.
+
+Never register the endpoint in production: it reveals a local path, and a
+deployed catalog has no local project to capture into.
+
 ## Custom action names
 
 The shell emits `data-action="catalog-select"` (sidebar items),
-`catalog-toggle-sidebar`, and `catalog-toggle-theme`. Override them with
-`selectAction` / `toggleSidebarAction` / `toggleThemeAction` on `Catalog` (and the
-matching options on `wireCatalog`) if they collide with your own action table.
+`catalog-toggle-sidebar`, `catalog-toggle-theme`, `catalog-toggle-contrast`,
+`catalog-toggle-motion`, and `catalog-select-background`. Override them with
+the matching `*Action` props on `Catalog` and options on `wireCatalog` if they
+collide with your own action table.
 
 ## CSS
 
-`Catalog` composes public primitives (`Toolbar`, `ListHeader`, `ListItem`, `Select`,
-…). Import `@kerfjs/ui/styles.css` for the whole layer, or `@kerfjs/ui/catalog.css`
-plus each composed primitive's CSS. The shell is theme-aware and responsive: it
-stacks the sidebar above the detail below ~832px and hides it when collapsed.
+`Catalog` composes public components (`Workbench`, `Pane`, `Toolbar`, `List`,
+`ListHeader`, `ListItem`, `ListInsetText`, `Text`, …) and owns only the preview stage
+(the checkerboard and left-aligned canvas), the example viewport
+options, and the brand mark's size. A bundler that honors the `browser` export
+condition loads the Catalog's stylesheets and those of every component it renders
+internally with the `@kerfjs/ui/catalog` import alone — no dependence on which other
+subpaths the app happens to import. Without that condition, import
+`@kerfjs/ui/styles.css` for the whole layer, or `@kerfjs/ui/catalog.css` plus
+`@kerfjs/ui/workbench.css` and each composed primitive's CSS. Like any Workbench it needs a definite containing height — the
+`@kerfjs/ui/document.css` baseline's `.kui-app-root`.