@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/docs/catalog.md

@@ -6,39 +6,88 @@ 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`
 ```
 
 - `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 and reveal the active sidebar row after a controlled render.
+  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?, tags?, resources?, related? }] }`. Each entry becomes a sidebar
-  `ListItem` under a `ListHeader` for its category. Short `tags` render as quiet
-  trailing pills for decision metadata such as `Discouraged`.
+  `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.
+- **`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` (the app owns it; wire it with `wireCatalog`'s `onToggleSecondary`).
 - 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 `TokenSearchField` 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
 
@@ -54,14 +103,25 @@ chosen component.
 
 Classify every entry before rendering it:
 
-| Entry kind            | Preview purpose                                                         | Geometry overlay                                                                    |
-| --------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| Focused component     | Show one public component, its meaningful variants, and adverse states. | `true`; the overlay inspects each selected specimen.                                |
-| Composition or recipe | Show several components cooperating as one product surface.             | `false`; child geometry remains unmarked so the composition can be read as a whole. |
-
-Keep `geometryOverlay` present and compute it from the active entry. Do not make
-it a permanent catalog-wide `true`, and do not give individual specimens their
-own overlay implementation.
+| 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
 
@@ -72,24 +132,92 @@ own overlay implementation.
   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.
+  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
+<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="none"`
-(the default) for a content item or composition that owns its geometry.
+for a control whose own inline padding contributes about 8px, and
+`align="text-trigger"` for a Web Awesome dropdown's text trigger whose visible
+label needs an 8px inset (such as a plain `PopupMenu` trigger). The dropdown host
+has no layout box, so this inset applies to its button child. Use
+`align="none"` (the default) for a content item or composition that owns its
+geometry.
 
 ```tsx
 import { CatalogExample, CatalogExampleStack } from "@kerfjs/ui/catalog";
 
 const buttonPreview = (
   <CatalogExampleStack
-    label="Button variants"
+    label="Button Variants"
     rootAttributes={{ "data-demo": "button" }}
   >
     <CatalogExample label="Icon" note="A bare glyph." align="glyph">
@@ -98,29 +226,17 @@ const buttonPreview = (
     <CatalogExample label="Control" align="inline-control">
       <SegmentedControl id="view" label="View" value="list" choices={choices} />
     </CatalogExample>
-    <CatalogExample
-      label="Authoring note"
-      note="Explanatory chrome is not a specimen."
-      rootAttributes={{ "data-catalog-geometry-overlay-skip": "" }}
-    >
+    <CatalogExample label="Authoring Note" note="Explain the specimen below.">
       <p>Use the public helper contract.</p>
     </CatalogExample>
   </CatalogExampleStack>
 );
 ```
 
-The overlay selects every immediate child of a `CatalogExample`; the helper
-marks its generated label and note so they are excluded automatically. It does
-not recursively promote a nested child to be the specimen. Outside an example
-row, it selects only top-level
-`[data-component]` roots in the canvas and ignores nested component descendants.
-These rules keep a row's label/group scaffolding out of the measurement and make
-the authored nesting determine exactly what is inspected.
-
 ### Metadata ownership
 
-Use `rootAttributes` on either helper for authoring metadata such as `data-demo`
-or `data-catalog-geometry-overlay-skip`; the metadata lands on that helper's
+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
@@ -128,54 +244,72 @@ 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`; do not infer or overwrite it from overlay
-pixels.
-
-### Geometry overlay and legend
-
-Pass the conditional `geometryOverlay` boolean to `Catalog`, then call
-`wireCatalogGeometryOverlay(root)` once after the first render and retain its
-disposer alongside `wireCatalog`'s.
+lives in `component-catalog.json`.
 
-| Overlay mark            | Meaning                                                                                              | It is not                                                                |
-| ----------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| Orange translucent band | A positive computed margin on the selected specimen, after subtracting the helper's alignment inset. | Padding, gap, or empty content. Zero and negative margins are not drawn. |
-| Accent solid edge       | The selected specimen's computed border widths and radius, except `none`/`hidden` styles.            | A focus ring, outline, child border, or metadata ownership claim.        |
-| Quiet dashed outline    | The border-box bound of a transparent selected specimen with no visible border.                      | A real CSS border, padding edge, or proof that the specimen owns size.   |
+### Component metadata
 
-The overlay recomputes from live rendered styles when specimens resize, preview
-markup changes, theme/root attributes change, or loaded/inline stylesheets
-change. Component CSS is therefore the source of truth; do not duplicate margin
-or border values in demo data. The overlay does not visualize padding, gaps,
-negative/zero margins, scroll overflow, hit targets, or nested descendants.
-Inspect computed styles and the machine-readable `geometry` metadata for those
-facts. Opaque borderless specimens do not receive the dashed bound.
+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.
 
-```tsx
-<Catalog
-  {...props}
-  geometryOverlay={activeEntry.kind === "component"}
-  content={renderers[active.value]()}
-/>
-```
-
-Put `rootAttributes={{ "data-catalog-geometry-overlay-skip": "" }}` on a
-`CatalogExample` or `CatalogExampleStack` only when that whole subtree is
-explanatory chrome rather than a specimen. The marker excludes the marked root
-and every descendant from selection; it does not merely hide one band. It is
-normally unnecessary in a composition because the active entry already sets the
-global overlay to `false`.
-
-Use the overlay together with machine-readable geometry ownership metadata; the
-overlay verifies what is rendered, while metadata tells people and AI tools
-whether the component, its parent, or its children are responsible for margin,
-border, and padding. Catalogs for downstream components should conform to the
+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
 
@@ -185,25 +319,30 @@ 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, example rows
-  are not empty, and composition routes do not add redundant skip markers;
+- 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`;
-- demo JSX does not copy private `kui-catalog-*` structural classes; and
-- the shell derives both geometry-overlay enablement and documented demo mode
-  from the active entry's source and kind.
+- focused demos have no relative stylesheet imports, inline style attributes,
+  or styling-only `demo-*`, `wa-demo-*`, and token-search 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 selection and geometry
-remain the browser suite's job.
+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, private markup, empty examples, composition overlay drift, and
-shell-mode drift always fail. The gate rejects duplicate, malformed, unused,
+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.
 
@@ -213,8 +352,8 @@ 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 is the Catalog desktop layout (`min-width: 52.01rem`), so compact
-layouts keep their existing scroll position.
+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
@@ -229,14 +368,15 @@ import {
   Catalog,
   CatalogExample,
   CatalogExampleStack,
+  type CatalogBackgroundStyle,
   type CatalogSection,
 } from "@kerfjs/ui/catalog";
 import {
   revealCatalogEntry,
   wireCatalog,
-  wireCatalogGeometryOverlay,
 } from "@kerfjs/ui/wire-catalog";
-import "@kerfjs/ui/styles.css"; // or import each primitive's CSS + @kerfjs/ui/catalog.css
+import "@kerfjs/ui/popup-menu/register"; // for the background chooser
+// A CSS-aware (browser-condition) bundler loads the Catalog's CSS with its import.
 
 type DemoKind = "component" | "composition";
 type DemoEntry = CatalogSection["entries"][number] & { kind: DemoKind };
@@ -262,7 +402,10 @@ const entries: DemoEntry[] = [
 const sections: CatalogSection[] = [
   {
     category: "Examples",
-    entries: entries.map(({ kind: _kind, ...entry }) => entry),
+    entries: entries.map(({ kind, ...entry }) => ({
+      ...entry,
+      tags: kind === "composition" ? ["Composition"] : undefined,
+    })),
   },
 ];
 
@@ -270,40 +413,38 @@ const sections: CatalogSection[] = [
 const renderers: Record<string, () => SafeHtml> = {
   button: () => (
     <CatalogExampleStack
-      label="Button states"
+      label="Button States"
       rootAttributes={{ "data-demo": "button" }}
     >
       <CatalogExample label="Default" align="inline-control">
         <Button label="Save" />
       </CatalogExample>
-      <CatalogExample
-        label="Authoring note"
-        note="This explanatory row is deliberately excluded from inspection."
-        rootAttributes={{ "data-catalog-geometry-overlay-skip": "" }}
-      >
+      <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"
+      label="Profile Form Composition"
       rootAttributes={{ "data-demo": "profile-form" }}
     >
-      <CatalogExample label="Complete composition">
+      <CatalogExample label="Complete Composition">
         <ProfileForm />
       </CatalogExample>
     </CatalogExampleStack>
   ),
 };
 
-// 3. App-owned state (domain: which entry; transient: collapsed; global: theme).
+// 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 activeEntry = () => entries.find(({ id }) => id === active.value) ?? entries[0];
+const increasedContrast = signal(false);
+const reducedMotion = signal(false);
+const backgroundStyle = signal<CatalogBackgroundStyle>("checkerboard");
 
 const app = document.getElementById("app")!;
 mount(app, () => (
@@ -314,7 +455,10 @@ mount(app, () => (
     content={renderers[active.value]?.() ?? <></>}
     collapsed={collapsed.value}
     theme={theme.value}
-    geometryOverlay={activeEntry().kind === "component"}
+    increasedContrast={increasedContrast.value}
+    reducedMotion={reducedMotion.value}
+    backgroundControl
+    backgroundStyle={backgroundStyle.value}
   />
 ));
 
@@ -329,10 +473,20 @@ wireCatalog(app, {
     theme.value = theme.value === "dark" ? "light" : "dark";
     document.documentElement.dataset.theme = theme.value; // apply your theme however you like
   },
+  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
 });
-wireCatalogGeometryOverlay(app);
 
 // Optional for an initial deep link whose row may start outside the viewport.
 revealCatalogEntry(app, initial, { block: "center" });
@@ -345,20 +499,159 @@ revealCatalogEntry(app, initial, { block: "center" });
 - **`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`.